Please press the following button to download the MattzoController firmware:

MattzoController Firmware V0.5.1

Code Structure

The firmware is contained in a zip file. Unzip the zip file into a folder of your choice, e.g. C:\Users\Mattze\Documents\MattzoController.

If you use the MTC4BT only, then proceed to the MTC4BT instructions.

If you use one or more of the Arduino based controllers (MTC4PF, MTC4PU, MLC), then you need to MOVE (NOT COPY!) the files in the “library” folder to the Arduino library folder. On Microsoft Windows, do something similar like:

  • Navigate to C:\Users\Mattze\Documents\MattzoController\libraries
  • Move the “MattzoBricks” folder to C:\Users\Mattze\Documents\Arduino\libraries

The exact directory names will vary on your computer system.

The following table contains a list of files and their purpose as of firmware version 0.5:

FilePurposeTo Dos
MattzoController_Library.hShared code library for all MattzoControllersMove to library folder.
MattzoController_Network_Configuration.hNetwork configuration shared by all MattzoControllersEdit and move to library folder.
MattzoPowerFunctions.cppLibrary required for IR supportMove to library folder.
MattzoPowerFunctions.hLibrary required for IR supportMove to library folder.
MTC4PF.inoFirmware for MTC4PF
MTC4PF_Configuration.hConfiguration for your MTC4PFs*Edit
MTC4PU.inoFirmware for MTC4PU
MTC4PU_Configuration.hConfiguration for your MTC4PUs*Edit
MattzoLayoutController.inoFirmware for MattzoLayoutController
MattzoLayoutController_Configuration.hConfiguration for your MattzoLayoutController*Edit
All files in folder MTC4BTSource code and configuration for MTC4BT. Requires Visual Studio Code and PlatformIO!See MTC4BT instructions.
Firmware files and their purpose

* If you have multiple Controllers of the same type, but with a different configuration, you may copy these files and change the #include directive in the corresponding firmware code file before compiling / uploading. This can faciliate the management and maintenance of your MattzoControllers significantly, because you can have the specific configuration and the firmware itself in different files.



Date: January 9th, 2022


MattzoTrainController for Power Functions (MTC4PF):

  • Function pins support now analog output values. This allows dimming of the connected LEDs. Required for bipolar LEDs in direction-dependent train lights.
  • Corrected bugs in some example configuration files.

MattzoLayoutController (MLC):

  • Improved servo power save mode for directly connected servos. Servos no longer swivel away when powered off.
  • Corrected minor bugs in some example configuration files.


Date: December 18th, 2021


MattzoTrainController for Bluetooth (MTC4BT)

  • Initial Release
  • ESP-32 based controller that supports LEGO Powered Up and SBrick
  • Enhances MTC4PU functionality
  • Based on PlatformIO instead of Arduino IDE
  • Might make MTC4PU obsolete on the long run

MattzoTrainController for Power Functions (MTC4PF)

  • Multi-train support (to control multiple Power Functions infrared receivers with one controller)
  • Minor changes in standard wiring configuration

MattzoTrainController for Powered Up (MTC4PU)

  • WiFi Bugfix

MattzoLayoutController (MLC)

  • Servo
    • Directly connected servo can now be powered off after a couple of seconds, which reduces power consumption, prevents servo burn offs if blocked and reduce servo flattering.
  • Switches
    • Improved configuration of multi-servo switches (e.g. Trixbrix double slip switches).
  • Signals
    • Support for semaphores (form signals)
    • New powerful and flexible signal configuration
    • LEDs can be used for multiple signal aspects, e.g. green/yellow for German Hp2 (“go slow”) aspect.
    • Multi-servo support for form signals for complex form signals
  • Level Crossings
    • Optimization of boom barriers movement
  • Bascule Bridges
    • Support for multi leaf bascule bridges
    • Support for continuous servosOptimized state machineOptimized configuration
  • SpeedController
    • Measure the speed of your LEGO trains and show it on a display!
  • Configuration
    • Improved configuration for servos, LEDs and sensors
    • Decoupled hardware components (servos, LEDs and sensors) from logical components (switches, signals, level crossings, bascule bridges etc.)
  • Removal of legacy Switch, Signal and Sensor Controller firmware packages.

Known Bugs in Firmware 0.5

  • In most of the MLC configuration files, the following lines MUST BE CHANGED from:


  • In most of the MTC4PF configuration files, the following line must be added:
bool STATUS_LED_REVERSE = false;


Date: April 3rd, 2021



  • Delayed primary boom barriers for enhanced realism.
  • Virtual sensors for switches, level crossing and bascule bridge to make sure that the controllers have received a command and to prevent trains to enter critical track sections before switches, boom barriers or bascule bridges are safely set or closed.


Date: March 20th, 2021



  • Unification of MattzoSwitchController, MattzoSignalController and MattzoSensorController into a single MattzoLayoutController.
  • Support for port extenders PCA9685 and MCF23017 to control hundreds of signals, switches and sensors with a single controller.
  • Support for level crossings with moving boom barriers and flashing lights.
  • Support for bascule bridges with opening and closing leafs.


  • Bug fix, improving stability of WiFi connection and controller operations.

Several other bug fixes and improvements.

Additional example configuration files for various MattzoControllers.


Date: January 3rd, 2021


MattzoTrainController for Powered Up (MTC4PU)

  • Initial release.

MattzoTrainController for Power Functions (MTC4PF):

  • Complete code refactoring.
  • Separation of configuration from firmware code.
  • Support for LEGO Infrared Receiver 8884.
  • Support for 4DBrix WiFi Train Receivers.
  • Multi-train-support.


  • Automatic train lights for all MattzoTrainControllers.

Boot problem fix for all ESP8266 based MattzoControllers.

Emergency stop for all trains if signal or sensor controller disconnect from MQTT.

Optional status LEDs for all MattzoControllers.

Network logging (syslog) and over-the-air (wireless) firmware updates.

MattzoController have now correct hostnames on the intranet.

Safety feature for MattzoSwitchController to prevent breaking switch servos on obvious misconfigurations.

A large variety of other new features and improvements.


Date: November 19th, 2020


MattzoTrainController for Power Functions (MTC4PF):

  • Bugfix.
  • Power range optimized.


Date: October 25th, 2020


MattzoTrainController for Power Functions (MTC4PF):

  • Initial Release

Central network configuration file to configure SSID, WiFi passphrase and MQTT broker IP address.

Various code improvements.


Date: June 6th, 2020


First public release of the firmware for MattzoSensorController, MattzoSignalController and MattzoSwitchController.


In the following, we continuously list our plans for upcoming versions.

Please note that the roadmap may change any time without prior notice.



  • Optimize servo power off for PCA9685


  • Migration of MLC and MTC4PF to
  • Web-interface to update firmware and configure the controllers
  • MattzoBlink (very flexible and powerful train and signal light system)
  • MattzoCentralController
  • MattzoDisplayController
  • MattzoRemoteController

27 thoughts on “Firmware

  1. Hi Mattzo,

    I’ve been using your firmware with great success sofar, so first: thank you for that! My first success was with the reed sensors. I have those working now and I’m very pleased with the results sofar. I have other parts and pieces on the way for the next steps I’m planning for my layout.

    I’m very excited about the path you’re taking and the content you’re sharing on the subject. As a 20+ year software developer and a Lego train enthusiast, I can’t wait to be able to contribute to the project.

    I have seen a couple of simple improvements sofar. Because I found a lot of the same code in all controllers, the first most obvious improvement for me would be to move some general setup logic (code and variables) to separate libraries for reuse. This could significantly simplify the actual code in each controller and make the hole project more maintainable in the process.

    I’m no expert on micro controllers, but it seems you have that part covered. I’d like to try and integrate the SBrick into Rocrail as an alternate train controller. I’m planning on doing that anyway and I’d love to donate the code to the project, if you’d like. This existing project seems like a good start:

    Please let me know if there is any way I can currently contribute to the project. I’d be more than happy to help!


  2. Hi Ray,
    substantial code unification is one of the key issues of Firmware 0.3 and leads us out of the prototype phase to a more mature approach of developing and maintaining the firmware. Regarding contribution: check your mail. 🙂


  3. Hello Mattze,

    Just downloaded V0.3 for my PU trains, and after some fiddling around, succes!
    It works perfectly, now to configure Rocrail and built some sensors and switches.
    (and the garden layout)
    Thank you for all your effort for making this, I’m a very happy man.

    Keep up the good work, can’t wait voor de levelcrossingcontoller….

    Greetings from the Netherlands,


    1. Hi Paul,
      thank you very much for your feedback! I am glad that it works on your end as well!

      We will publish some more very interesting stuff for you in the near future, so stay tuned!


    1. sorry i forgot to install this Legoino library.

      i use Amica V2 Nodemcu
      ESP8266MOD 12-F
      but now i got this:
      In file included from C:\Users\WORK\Documents\Arduino\MTC4PU\MTC4PU.ino:64:0:
      C:\Users\WORK\Documents\Arduino\libraries\MattzoBricks/MattzoController_Library.h:31:26: fatal error: PubSubClient.h: No such file or directory
      compilation terminated.
      exit status 1
      Error compiling for board NodeMCU 1.0 (ESP-12E Module).

      is there an other thing to install?

  4. Hi, ich habe gerade angefangen mit der Firmware herumzuspielen und versuche gerade die Software für die Sensoren auf meinen NodeMCU Lua Lolin V3 Modul, d.h. auf den ESP8266 12E zu spielen, nachdem ich mir nach herumsuchen im Web die Bibliothek für dieses Board heruntergeladen und installiert hatte, jedoch meckert nun Arduino IDE und behauptet “Fehler beim Kompilieren für das Board NodeMCU 1.0 (ESP-12E Module)”. Habe ich das falschle Board ausgewählt, oder die falsche Bibliothek heruntergeladen? Denn das V3 Board steht dort nicht zur Auswahl, obwohl auf diversen Seiten zu diesem Board diese eine Bibliothek angesprochen wurde.
    Würde mich über Hilfe sehr freuen!

      1. Ich habe den Fehler gefunden und PubSub ebenfalls installiert. Jetzt habe ich noch eine letzte Frage: Wo findet man die Syslog.h Datei? Denn diese ist das einzige Problem worüber Arduino IDE gerade meckert.

  5. Arduino: 1.8.13 (Windows 8.1), Board: “Arduino Uno”

    MTC4PU:31:10: fatal error: Lpf2Hub.h: No such file or directory

    #include “Lpf2Hub.h”


    compilation terminated.

    exit status 1

    Lpf2Hub.h: No such file or directory

    I’m struggling to find the problem with this.

  6. Hi I’m trying to upload the firmware for a switchcontroller to my NodeMCU V2 WiFi Amica ESP8266 ESP-12E. But when compiling i get this error:
    Meerdere bibliotheken gevonden voor “Servo.h”
    In file included from C:\Users\henk\Documents\Arduino\MattzoController_Switch\MattzoController_Switch.ino:13:0:
    Gebruikt: C:\Users\henk\AppData\Local\Arduino15\packages\esp8266\hardware\esp8266\2.7.4\libraries\Servo
    C:\Users\henk\Documents\Arduino\libraries\MattzoBricks/MattzoController_Library.h:44:22: fatal error: tinyxml2.h: No such file or directory
    Niet gebruikt: C:\Program Files (x86)\Arduino\libraries\Servo

    can anyone help with this one? I allready tried to install the TinyXML library without luck…

    1. Hello Henk,
      we have now set-up a support forum. You can find in the navigation bar under “My MattzoBricks”. Please post your question there, as it will be relevant for other people as well!

      I will close the commenting function on the documentation pages shortly.

      Thanks + good luck,

  7. Many Thanks Mattze! I started developing my own code for automating my LEGO trains, was a great experience, but your work has taking it to a whole different level. I started w/ the signal crossing and then moved to the switches. I was saving the train automation for last. Your code covers everything; Rocrail has been the hardest part to get going, but it’s awesome. I’ve connected MQTT into Node-Red for monitoring, and working on some control w/ it. That’s where I started with the automation, having found prior to your work.

    1. Hi Dan,
      happy to hear that. Love to hear further success reports. I am also collecting pictures and videos of people having built their layout with MattzoBricks train automation. The best ones are being published on, section “projects”.


  8. Hi Mattze,
    thanks for the great work. What are your thoughts on publishing this on github or any similar service so that people can contribute more easily?

    1. Hi Sebastian,
      we are planning to do that. Haven’t decided on the right point in time, though. If you are interested to contribute, send me an e-mail.


  9. Hi Matthias,
    Great work!
    I have looked through your code, but why haven’t you added OTA updates and a simple webpage for configuring the controller (Acces point and normal wifi mode)? All “soft” items can be stored in de nvs of an ESP32, basicly making it a compile once use many times firmware.
    I have done the STA and AP mode, nvs stuff and OTA stuff, so if you need a hand?

    1. > … why haven’t you added…

      There are many things we could do, and sometimes we have to focus on the things we actually do (in our sparetime). 🙂

      By the way, OTA is indeed already integrated. Check the file MattzoController_Library.h and search for “OTA”.

      We have thought about web configuration feature since quite a time, and maybe we are going to add this at a later point.

      1. Hi Matthias

        considered hosting on github? i just implemented sta+ap and mattzo_network_configuration with configmanager.


        1. Hi Georg,
          as you can see in the discussion thread above, we are planning to release the repository to the public one day, likely with version 1.0. At the moment it would be too much work for me and the other members of the core development team. We wouldn’t be able to check all the pull requests that we’d get, and therefore it would be too frustrating for people who would like to contribute. If we believe you are qualified to contribute, it’s better to get in touch with me directly and check if there are other ways of cooperation.

          Thanks for your patience.


  10. Hallo Herr Mattzo,
    ich würde gerne fragen ob es möglich wäre nur die Weiche und Lichtsignal oh Züge in Rocrail zu steuern und zu simulieren? wenn ja wie gebe ich die Adresse der Servo und Lichtsignal ?

Leave a Reply

Your email address will not be published. Required fields are marked *