Please read this section carefully and completely before you start building your first MattzoController.
The electrical wiring and the firmware of the different MattzoController types are different, but all controllers also have strong similarities.
MattzoController in general
This section applies to all types of MattzoControllers.
In this section, some common features of all kinds of the MattzoController are described. The different types of MattzoControllers are described in greater detail in the subsequent sections.
First you need to build the controller, download the firmware, do some network and wiring configuration in the code, and then upload the firmware to the controller.
To complete these tasks successfully, it is helpful if you have played around with microcontrollers before. It is even more helpful if you have basic understanding of computer networks and computer programming.
Nevertheless, we know of many people who successfully managed to build and set-up MattzoControllers with very little specific knowledge about those things, and brought their LEGO train layout to a whole new level.
The Mattzobricks community is growing every day, and we are proud about each new layout that was automated with the Mattzobricks Train Automation System.
Building the different controller types
Instructions how to build the different controllers can be found in the controller-specific sections.
If you have a 3d printer, you may be interested in the stl files to print out some nice cases for the controllers.
Download the firmware
Firmware, firmware history and roadmap for planned features can be found here.
Unzip the zip file into a folder of your choice, e.g. C:\users\afol\documents\Mattzobricks
We plan to make the source code repository public in some point of the future. From this moment on, you will not be required to download the firmware package. You may than simply check out the git repository and keep it up to date easily. It is likely that we publish the source code repository once we have migrated the active MattzoControllers from Arduino to VS Code (see below).
Uploading the firmware
At present, we are in a transition of development platforms, which we also use to upload the firmware to the controller.
Two platforms are presently in use, which cover different types of MattzoControllers:
- Arduino IDE
- MattzoLayoutController (MLC)
- MattzoTrainController for Power Functions (MTC4PF)
- MattzoTrainController for Powered Up (MTC4PU; deprecated)
- Visual Studio Code with platform.io.
- MattzoTrainController for Bluetooth (MTC4BT)
We are going to migrate the MLC and MTC4PF from Arduino to VS Code.
Arduino based controllers
Download Arduino IDE
For the MLC and MTC4PF, you need the Arduino IDE to upload the firmware to the microcontroller.
Do NOT download the Arduino IDE via Microsoft Store. Download the installer directly from the download section of the Arduino website.
Install Arduino Board Managers
As we are using the ESP8266 platform for the MLC and MTC4PF, you need to add the following Board Manager URL to the Arduino IDE (Menu File / Preferences, Additional Board Manager URL):
- ESP 8266
- Supported version: 2.7.4 only.
- Attention: the firmware will presently not work correctly with board manager 3.0.0 and above.
In case you want to try the MTC4PU, your platform will be the ESP32. In this case, you need to add the following Board Manager URL:
- ESP 32
- Tested version: 1.0.4
- Newer versions should also work (not tested).
Install Arduino Libraries
The MattzoController firmware requires some code libraries. The required libraries depend on the MattzoController type. The libraries can mainly be downloaded easily from the Arduino IDE by using the built-in library manager (menu Tools / Manage Libraries). Details and exceptions are described in the main source code file (MTC4PF.ino or MLC.ino) for the specific MattzoController.
Configure the firmware
Firmware 0.3 – 0.5.x:
You need to copy the header file MattzoController_Network_Configuration.h to the library directory of the Ardunio IDE and enter your network settings.
You need to move the folder “libraries/MattzoBricks” including its contents to the Arduino libraries folder. The files are required by the firmware for the various controller types and included in the compilation process before uploading the firmware.
The type specific firmware sketches have their own additional configuration files. The configuration files may be copied in order to maintain different configurations for e.g. two different MTC4PU controllers controlling different trains.
The file and folder structure has changed with firmware 0.6 significantly, to make installation and management of the firmware easier and more transparent.
After you have unzipped the firmware, you need to change the name of two folders:
- MattzoController\MLC\conf\default -> MattzoController\MLC\conf\my
- MattzoController\MTC4PF\conf\default -> MattzoController\MTC4PF\conf\my
For advanced users: the “my” folders are under an gitignore policy, which is important you users that use the firmware via a git checkout. If you have no idea what that means: don’t arrow, it’s not important for you.
Now you need to edi the files in the “my” folders, which are:
The network_conf.h file contains important network settings like WiFi access data etc. Understanding and editing the parameters in this file is relatively easy.
The controller_config.h file is more complicated. To give you a quick start, we have compile various example file in the MattzoController\MLC\conf\examples folder. If you have identified the example file or your choice, you may copy it over the controller_config.h file and use it instead.
Compile and Upload the Firmware
To compile the firmware, you need to start the Arduino IDE and load the MTC4PF.ino or MLC.ino file.
To upload the firmware, you would normally connect the controller via USB to your computer. Please note that you might need a USB driver specific to your microcontroller in order to establish the connection via USB. After the controller is connected via USB, select the correct board from the Board manager, choose the USB port and hit Ctrl+U (Upload). This will compile the firmware and upload it to the controller.
MattzoControllers also features OTA (over the air) firmware updates. This way, you can update the firmware via WiFi without USB connection after it has been successfully installed for the first time. To do OTA uploads, choose the OTA name (usually the hostname) of the controller instead of the USB port. If you wonder why OTA is important, imagine a layout with 25 MattzoLayoutControllers and 30 MattzoTrainControllers, and all controllers carefully inserted into your LEGO layout or trains. Updating all of these controllers via USB would be a nightmare.
Visual Studio Code / platform.io based controllers
Follow the instructions on the MTC4BT page.
We invite you to get used to VS Code and platform.io, as we are going to migrate the Arduino based controllers to this platform in the future.
The MattzoController tries to connect to WIFI on start-up. The SSID and WIFI passphrase must be set in the network configuration file before you upload the firmware in order to enable the controller to establish the connection.
If you have installed the optional status LED, the LED flashes during the WiFi connection process (0.1 seconds on, 0.9 seconds off). After a successful connect, the LED turns blinking (0.5 seconds on, 0.5 seconds off) to indicate it tries to connect to the MQTT broker.
Setting up MQTT
After establishing a WIFI connection, the controler connects to the MQTT broker.
Download and install a MQTT broker and start it somewhere in your local network, e.g. on the computer on which Rocrail is running. The most common MQTT broker is the free “mosquitto” software, which can be downloaded from https://mosquitto.org.
The IP address of the MQTT broker must also be set in your network configuration file.
Mosquitto needs no special configuration in version 1.x. Just start it by running mosquitto.exe.
Please be aware that your computer may have multiple network adapters, e.g. one for Ethernet (LAN) and another one for WiFi. It is important that mosquitto is listening on the WiFi network adapter. If you want to keep things simple, deactivate all network adapters that you do not need or – even simpler – pull out the network cable before starting mosquitto.
Important: From mosquitto version 2.0 and above, mosquitto needs a configuration file in order to allow connections from clients that do run on the same machine as mosquitto itself – like the MattzoControllers. The configuration file should be named mosquitto.conf and should be in the mosquitto installation directory. The file needs to contain the following lines:
You can now start mosquitto with the following command:
mosquitto -c mosquitto.conf
If you use Microsoft Windows 10, another option is to use the mosquitto service, which is automatically installed on your machine if you have installed mosquitto 2.0 with the mosquitto installation program. Navigate to the Windows Services, start the service and set the start-up type to “automatic”. Remember to set-up the mosquitto.conf file exactly as described above!
If you have installed the optional status LED, the LED blinks (0.5 seconds on, 0.5 seconds off) to indicate it tries to connect to the MQTT broker. After a successful connection, the LED is turned off.
Fetching the MattzoControllerID via MQTT
When a MattzoController starts for the first time, it automatically creates a MattzoControllerID.
The MattzoControllerID is required for the MLC, as it must be used as the Rocrail base address of all components that you connect to the controller.
After the controller has connected to the MQTT broker, the MattzoControllerID can be identified by monitoring the MQTT messages on the MQTT broker. To inspect the MQTT message, you must run the MQTT broker in a mode in which it logs out the MQTT messages. This is often called the “verbose” mode. If mosquitto is used as MQTT broker, the verbose mode can be started in MS Windows. Stop the service, open a command line window, navigate to the mosquitto installation directory and type:
If you use mosquitto 2.0+, the command would be:
mosquitto -c mosquitto.conf -v
Important: The verbose mode is good for detecting the MattzoControllerID, and for testing and debugging. Do not use verbose mode when you operate large and complex layouts with a large number of switches, sensors, lights, trains and MattzoControllers, because the option may significantly slow down the communication between the components. This may lead to overshooting of trains after they pass sensors or other undesired behaviour of the your rolling and fixed stock.
MattzoControllers send last will messages to the MQTT broker upon disconnection, if they are critical to your railway operation. A controller must be considered “critical” if it controls one or more of the following components:
- bascule bridges,
- turn tables,
The following components are usually not critically, as they simply beautify your layout, but do not lead to consecutive problems in case of their failure:
- level crossings,
- speed controllers.
Last will messages trigger the emergency brake for all MattzoTrainControllers, i.e. all trains stop if a critical MattzoController disconnects from the MQTT broker. This helps to prevent larger crashes on the layout.
You can also trigger the emergency brake directly from Rocrail: Either press the “Power off” button (the light bulb), or the “Emergency Brake” (the red dot). This way, a ghost train can trigger an emergency brake situation, which is quite handy to prevent larger crashes. To set this up, you need to enable the feature “Power off at ghost train” in the Rocrail settings.
Shutting down Rocrail will also trigger the emergency brake.
An emergency brake situation can be noted by two things:
- No trains are moving any more
- All train lights are blinking.
The emergency brake situation remains until you have reset it. To reset, you need to virtually switch the “power” in Rocrail off and on again:
The Serial Monitor
On first boot, the controller generates a random number called “MattzoControllerID”. This id is an integer value between 1 and 65000. The MattzoControllerID is stored in the long-term memory of the micro controller and reloaded on subsequent boots.
The controller prints the MattzoControllerId to serial on boot. You can inspect the information when you connect the controller via USB to your PC, start the serial monitor of the Arduino IDE (Ctrl + Shift + M) and reset the controller.
Tip: it’s also a good idea to have the controller connected to the serial monitor when trying to solve problems. Even better it to use the built-in syslog capability of the MattzoControllers. To use this feature, you need to enable and set it up in MattzoController_Network_Configuration.h.
If you use the MTC4BT: there is also a very good serial monitor in Visual Studio Code / Platform.io.
Download and install Rocview on your computer.
- Tab “Service”
- Rocrail Properties (menu File / Rocrail Properties)
- MQTT Service
- Hostname: IP address of the MQTT broker (e.g. localhost)
- MQTT Service
- Rocrail Properties (menu File / Rocrail Properties)
- Tab “Controller”
- Add the “virtual” controller.
- Rename it to “vcs-1” or similar.
- If Rocrail does not receive sensor events from the MattzoController, you should first check if the controller has booted correctly. If this is not the case, it may help to disconnect LEDs or sensors from the micro controller and try again.
- Then you should check if the controller has successfully connected to WIFI. Make sure that you have sufficient WIFI coverage at the desired location of the controller. Rebooting the controller (something multiple times) may also help, especially on ESP-32 boards.
- Check if the controller has successfully connected to MQTT. If you use mosquitto, it may help to subscribe to the MQTT broker with the command line “mosquitto_sub -t # -v” and check if there are incoming messages from the controller at all. Make sure you enable anonymous inbound connections if using mosquitto 2.0 or above as described in the MQTT section!
- Check if Rocrail is configured correctly.
Tips and Tricks
- Make sure that all network nodes have permanent and sufficient WIFI reception!
- Make sure that the controllers have sufficient power supply. This applies especially to the MattzoSwitchController, but in general also to the other controller types!
- Reduce anything that could cause lags and delays on your computer, e.g.:
- Switch off “Trace” in Rocrail settings.
- Do not run mosquitto in verbose mode when actually operating real trains.
- Switch off desktop background slide shows that load complex pictures.
- Switch off complex screen savers.
- Stop clients like Dropbox, OneDrive, iCloud or other cloud upload/download software. They demand significant processing and network ressources on your computer and may come to live arbitrarily.
- Switch off syslog and too verbose logging in the MattzoController network configuration. The maximum log level in MLC, MTC4PF and MTC4PU should be LOG_INFO.
- If you not attending your layout, power down all MattzoSwitchControllers for security reasons. If a switch motor is trying to turn to a position that it can not achieve, it will block, overheat and eventually break. MattzoSwitchControllers are trying to turn the servo motor as they are told from Rocrail. It is important to note that a simple configuration error can cause the switch motor to overheat! PLEASE TAKE THIS WARNING SERIOUS. I have reports of a user who literally BURNED off an ESP-8266 micro controller. With “burn” I mean: it went on flames! Okay okay, the guy connection the controller to a car battery, but be careful anyway!
How to contribute
The code is managed as a git repository on Github. Maintenance and enhanvements are mainly done by Mattze and other members of the MattzoBricks core development team.
If you would like to join the MattzoBricks core development team, send an e-mail to firstname.lastname@example.org.
We think about setting the git repository to public, maybe from firmware version 1.0.