Controllers are required to power up and control components like locomotives, sensors, signals and switches. They are also handling the communication between those components and the central automation software.

Introducing the “MattzoController”

We have developed our own “MattzoControllers” for the LEGO train system.

The controller is not for sale, and it doesn’t have a nice housing yet. I am publishing information about it here, so that anybody who is interested and feels capable can build it himself.

The MattzoController is based on a micro controller that unifies digital processing, input/output from/to the railway component, and WIFI connectivity.

MattzoControllers communicate via WIFI with a communication hub called “MQTT Broker” via the “MQTT” protocol.

The present firmware of the MattzoController is built for interaction with “Rocrail”. Rocrail is a free, open-source software to control model railways. MattzoControllers natively understand the Rocrail protocol. That means, that no other translation layer is needed to enable the communication between Rocrail and the controllers.

Rocrail can be supported with a small donation. In return you receive a license key that enables some additional features in the software. I would encourage every user to support Rocrail in order to ensure the long-time viability of the Rocrail project. Check the Rocrail website for more information!

Current status

At the moment, the following controller types have been published by Mattzobricks:

  • The “MattzoSensorController” for reed sensors or other digital sensors.
  • The “MattzoSignalController” for light signals.
  • The “MattzeSwitchController” for switches.

The electrical wiring and the firmware of the different controller types are different, but they all have quite strong similarities.

The MattzoTrainController for locomotives is in development and has not been published yet. Thanks for your patience!

MattzoController in general

This section applies to all flavours of the MattzoController.

In this section, some common features of all flavours of the MattzoController are described. The different types of MattzoControllers are described in greater detail in the subsequent sections.

Connectivity

On first boot, the controller generates a random number called “MattzoControllerID”. This id is an integer value between 1 and ca. 65.000. The MattzoControllerID is stored in the long-term memory of the micro controller and used on any subsequent operations.

The MattzoController then tries to connect to WIFI. The SSID and WIFI passphrase must be changed in the code before you upload the firmware in order to enable the controller to establish the connection.

After establishing a WIFI connection, it connects to the MQTT broker. By default, the IP address MQTT broker is 192.168.1.19. This setting can be changed in the code.

After the controller has connected to the MQTT broker, the MattzoControllerID can be identified by checking the MQTT protocol. The MQTT broker should be running in “verbose” mode. If mosquitto is used as MQTT broker, the verbose mode can be entered by starting the broker with the command “mosquitto -v”.

The controller sends a ping to a specific MQTT topic. This ping is received by another important software component, that I will add soon to this page. Among other things, it acts as a watch dog that stops all trains if a sensor fails to confirm its full operability within a specific time interval.

Building the controller

Instructions how to build the different controllers can be found in the subsequent controller-specific sections.

Firmware

You need the Arduino IDE to upload the firmware to the micro controller. Required libraries can mainly be downloaded directly from the Arduino IDE. Exceptions: see code!

Press the button to download the firmware. The file contains different sketches, one for each type of the MattzeController.

Download
MattzoController Firmware V0.1

The firmware has been published under the MIT license. By downloading the software, you agree to the conditions of the license.

Version history

  • V0.1 of June 6th, 2020.
    • First publically released firmware for MattzoSensorController, MattzoSignalController and MattzoSwitchController.

How to contribute

The code is managed as a git repository Github. If you would like to contribute with code improvements or enhancements, send us an e-mail to info@mattzobricks.com.

Controller Setup

First you need to build the controller and upload the firmware with the correct SSID, WIFI passphrase and IP address of the MQTT broker. To complete this task successfully, it is helpful if you have played around with Arduino or something similar before. It is even more helpful if you have basic understanding of programming and micro controllers.

Beside the WIFI and MQTT settings in the code, a MattzoController needs no specific setup.

Then 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.

Rocrail Setup

Download and install Rocview on your computer.

Required settings:

  • Tab “Service”
    • Rocrail Properties (menu File / Rocrail Properties)
      • MQTT Service
        • Hostname: IP address of the MQTT broker (e.g. localhost)
  • Tab “Controller”
    • Add the “virtual” controller.
    • Rename it to “vcs-1” or similar.

Problem Fighting

  • 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.
  • 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 -h localhost -t # -v” and check if there are incoming messages from the controller at all.
  • 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.
    • 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.
  • 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!

Planned Improvements

  • Improve start-up behaviour.
  • WIFI connectivity via WPS.
  • Automatically search for MQTT brokers.
  • Store SSID and MQTT address in EEPROM upon successful connection.
  • Evaluate controllers voltage supply and report to monitoring software components.
  • Code improvements.
  • Translation of this page in German.
  • Production of some tutorials videos.

MattzoSensorController

Purpose

The MattzoSensorController is designed to receive input signals from digital sensors like reed switches and pass the information on to the Rocrail via the MQTT broker.

Functional Description

The controller connects to MQTT as described in the “General” section.

When a connected sensor has contact with a vehicle, the controller instantly sends a sensor event to the MQTT broker.

When a sensor looses contact, the controller waits one second after it sends the “sensor disconnected” event to the MQTT broker. If the sensor has reestablished contact during this period, the “sensor disconnected” event is omitted or postponed.

Up to four reed sensors (or other digital sensors) can be connected to the controller. For more information about reed sensors refer to the sensor section.

To facilitate error search and debugging, the controller has four LEDs. The LEDs light up when the controller is connected to the MQTT broker and a sensor has contact. The LEDs also light up in a certain sequence when searching for WIFI and the MQTT broker and act as a status indicator in this operation mode.

Wiring

The following diagram shows the wiring of the controller.

MattzoSensorController: Wiring Diagram

Required components:

  • I/O board with micro controller. We have used a NodeMCU Amica Modul V2 ESP8266 ESP-12F. Similar modules should work as well.
  • 4 reed sensors (details: see sensor page).
  • 4 resistors (10 or 100 kΩ).
  • 4 LEDs. Make sure that the LEDs cope with the power supply. Depending on the type of LED, they each might need one additional resistor wired in series.
  • Basic stuff like bread board, wires etc.

The LEDs are optional. They help to monitor the correct operation of the controller.

The controller can be powered up with a simple USB charger over USB or some other power supply of similar voltage that is connected to the VIN and GND pins of the controller.

Setup

For general setup instructions please refer to the “General” section.

To setup the sensor in Rocrail, navigate to the interface tab of the sensor definition. The MattzoControllerID must be used as “Bus” parameter, and the port of the sensor as “Address”.

The first port has the number “1” (not “0”).

ALL OTHER INFORMATION ON THIS PAGE CAN BE NEGLECTED AND HAS NO MEANING!

Sensor configuration in Rocrail

MattzoSignalController

Purpose

The MattzoSignalController is designed to receive signal commands from Rocrail via the MQTT broker and set light signals to a specific signal state.

Functional Description

When Rocrail wants a signal to change state, it communicates this as a command via the MQTT broker. The MattzoController receives this command and evaluates, if the command is relevant for the specific controller (i.e. if the signal is connected to this controller).

The signal state is communicated from Rocrail by switching specific LEDs on and off. Example: a signal has a red and a green light. If the new signal state is “green”, Rocrail sends two commands: 1. red off, 2. green on.

Up to eight LEDs can be connected to the controller. If standard signals with only red and green LEDs are used, this means, that four signals can be attached to one controller.

Wiring

The following diagram shows the wiring of the controller. As an example, four simple signals with one red and green LED each are connected to the controller.

MattzoSignalController: Wiring Diagram

Required components:

  • I/O board with micro controller. We have used a NodeMCU Amica Modul V2 ESP8266 ESP-12F. Similar modules should work as well.
  • LEDs in different colors (red, green, possibly green and white) if you build the signals yourself.
  • Possible some resistors to protect the LEDs. Resistors with 220 Ω are frequently used for this job. In doubt ask the vendor of your signals or LEDs.
  • Basic stuff like bread board, wires etc.

The controller can be powered up with a simple USB charger over USB or some other power supply of similar voltage that is connected to the VIN and GND pins of the controller.

We do not have reliable information about the LEDs used in signals that can be bought of the shelf from suppliers like Trixbrix, 4DBrix and others. In doubt, I recommend to wire a 220 Ω in series to protect the LED and/or ask the vendor.

In the wiring diagram, the signals are connected to the 3.3V terminal of the controller. The signals light up brighter of the plus terminal of the signals is connected to VIN (between 4.5 and 5V if supplied via USB) rather than to the 3.3V pin of the controller. We have no information if the LEDs are damaged if you supply them with higher voltage. Again, I recommend to protect the signals with additional resistors if in doubt.

From time to time we have experienced boot problems of the controller. Interrupting the power supply (plus terminal) of the lights during power up helps. As soon we have found a better solution or work-around, we will publish it here.

Setup

For general setup instructions please refer to the “General” section.

To setup the signal in Rocrail, navigate to the interface tab of the signal definition. The MattzoControllerID must be entered as “Address” parameter, and the port of the LED as “Port”. This must be done for all signal states (usually only red and green).

The first port of the controller has the number “1” (not “0”).

ALL OTHER INFORMATION ON THIS PAGE CAN BE NEGLECTED AND HAS NO MEANING!

Signal configuration in Rocrail

MattzoSwitchController

Purpose

The MattzoSwitchController is designed to receive switch commands from Rocrail via the MQTT broker and set switches to the requested direction.

Functional Description

When Rocrail wants a switch to change direction, it communicates this as a command via the MQTT broker. The MattzoController receives this command and evaluates, if the command is relevant for the specific controller (i.e. if the switch is connected to this controller).

The switch command contains the controller id and port to which the switch is connected to, and the requested direction of the switch.

The number of switches that can be attached to one MattzoController depends of the “logical type” of the switch.

  • A standard switch has one switch motor, and needs one port. Up to eight standard switches can be connected to one MattzoController.
  • A triple switch has two switch motors, and needs two ports. Up to four triple switches can be connected to one MattzoController.
  • A double slip switch has four switch motors, and needs four ports. Up to two doube slip switches can be connected to one MattzoController.

You can also connect any combination of different logical switches types to a MattzoController, e.g.:

  • 2 Standard, 3 Triple
  • 4 Standard, 2 Triple
  • 6 Standard, 1 Triple
  • 4 Standard, 1 Double Slip
  • 2 Standard, 1 Triple, 1 Double Slip
  • 2 Triple, 1 Double Slip

Attention: if a double slip switch is connected, some special ports need to be configured in Rocrail (see below).

Wiring

The following sketch shows the wiring of the controller for 4 switch motors:

MattzoSwitchController: Wiring Diagram (for 4 switches)

Building a controller for eight switch motors is similar. The main difference is that you need a logic level converter the handles eight ports instead of four:

MattzoSwitchController with eight switch motor ports

Required components:

  • I/O board with micro controller. We have used a NodeMCU Amica Modul V2 ESP8266 ESP-12F. Similar modules should work as well.
  • Logic level converter with 4 or 8 channels.
    • An 8 channel logic level converter is recommended. We used a converter type “TXS0108E”.
    • ATTENTION: The TXS0108E has different operation modes, which can be configured by pulling the OE pin of the converter up or down. The OE pin of the TXS0108E needs to be pulled-up with a 10 kΩ resistor to bring it in the correct operation mode. You can see the wiring of the resistor in the picture above.
  • Basic stuff like bread board, wires etc.

The logic level converter is required to convert the internal 3.3V of the micro controller to a higher voltage.

The controller can be powered up with a simple USB charger over USB or some other power supply of similar voltage that is connected to the VIN and GND pins of the controller. Voltage should be in the range of 4.5V and 5V. Sufficient power supply is crucial because the servo motors require some power to flip the switches. If the power supply is to weak, the voltage in the micro controller goes down, which can cause a crash of the controller.

From time to time we have experienced boot problems of the controller. Interrupting the power supply of the servos during power up helps. As soon we have found a better solution or work-around, we will publish it here.

Setup

For general setup instructions please refer to the “General” section.

Standard Switch

To setup a standard switch in Rocrail, navigate to the interface tab of the switch definition. The MattzoControllerID must be entered as “Address” parameter, and the port to which the switch is connected as “Port”.

Enter the minimum value of the switch servo motor into the “Parameter” field, and the maximum value into the “Value” field.

ALL OTHER INFORMATION ON THIS PAGE CAN BE NEGLECTED AND HAS NO MEANING!

Switch configuration in Rocrail: Standard Switch

Triple Switch

To setup a triple switch in Rocrail, navigate to the interface tab of the switch definition. As we are configuring two switch motors now, we need to configure everything twice compared to the standard switch.

The MattzoControllerID must be entered as “Address” parameter, and the ports to which the switch is connected as “Port”.

Enter the minimum value of the switch servo motors into the “Parameter” fields, and the maximum value into the “Value” fields.

ALL OTHER INFORMATION ON THIS PAGE CAN BE NEGLECTED AND HAS NO MEANING!

Switch configuration in Rocrail: Triple Switch

Double Slip Switch

To setup a double slip switch in Rocrail, navigate to the interface tab of the switch definition. What we are now doing is to configure four physical switch motors with just two logical ports in Rocrail.

The MattzoControllerID must be entered in both “Address” fields.

The first port must be configured as port “1001”, the second port as port “1002”. This setting assumes that the first two switch motors are attached to port 1 and 2 of the controller, and the other two switch motors are attached to port 3 and 4 of the controller.

If you are configuring two double slip switches on a single controller, the second switch has ports 1003 and 1004, which requires ports 5 to 8 on the controller for the switch motors.

Enter the minimum value of switch servo motors into the “Parameter” fields, and the maximum value into the “Value” fields. The values are valid for pair 1/2 and 3/4 of the switch motors and can not be modified individually.

ALL OTHER INFORMATION ON THIS PAGE CAN BE NEGLECTED AND HAS NO MEANING!

Switch configuration in Rocrail: Triple Switch

Additional Information

Please refer to the other pages on mattzobricks.com for more information and watch our videos on LEGO train automation on Youtube.