The MattzoTrainController for Bluetooth (MTC4BT) has two main use cases:

Act as MattzoTrainController, i.e. making locomotives on the layout go and stop.
Act as MattzoRemoteController, i.e. integrate LEGO Powered Up remote controls into the MattzoBricks Train Automation System 2.0.

On this page, the MattzoTrainController functionality of the controler is described.

Supported devices

MTC4BT supports the following BLE devices to control trains:

LEGO Powered Up (PU) hub
SBrick by Sengit
Buwizz 2.0 (from firmware 1.2)

Up to nine BLE devices can be connected to the MTC4BT at the same time. BLE devices can be combined. This means that you can control a mix of up to nine BLE devices using just one single ESP-32 controller. You can even combine different types of BLE devices in one locomotive if needed.

Please note that the different BLE hubs have different number of ports, to which train motors or lights can be connected:

LEGO Powered Up hubs have two channels.
SBricks and BuWizz2 units have 4 channels.

But wait, there is more! We use the ESP-32 controller and it already has all those pins at our disposal. MTC4BT enables you to use those pins to attach stuff to them. For now it’s limited to lights (LED’s), but support for other peripherals can be added in the future. Think of all the possibilities this could give you, if you’d put an ESP-32 inside your train.

These extras of MTC4BT open up many new possibilities for your locomotives and trains in general. We can’t wait to see what you’ll do with it!

Functional Description

When Rocrail wants to make a train go into a certain direction, it communicates this as a “loco” command via the MQTT broker.

MTC4BT receives this command and evaluates it, to see if the command is relevant for one of the BLE hubs that is connected to the controller. It checks if its own MattzoControllerID corresponds with the “address” attribute that is configured for the train in Rocrail (see below). If this is the case, MTC4BT converts the desired speed and direction into a command for one or more connected BLE hubs, which then regulate the power supply for the attached motors and lights.

All BLE hubs and attached motors / lights must be configured. You can also configure the sense of rotation for all motors individually. This flexibility enables an enourmous variety of deployment scenarios for your trains, e.g.:

A single loco with one BLE hub and just one motor.
A powerful loco with one BLE hub and two motors.
A commuter train (ICE, Eurostar, TGV, Regio Express etc.) with two locos, one in the front, and one in the back. Each loco has one BLE hub and one motor.
Multiple locos pulling a giant freight train.
A long train with additional motors hidden in some cars in the middle of the train.

Many other scenarios are possible.

The implementation of the MTCBT adds full support of Rocrail’s capability of up to 32 functions. Each function can be connected to either a hub channel or a pin on the ESP-32. It is possible to connect cheap standard LEDs to the MTC4BT, which will enable various independent lighting options for the train, which you can control from Rocrail.

In the future we hope to include things like direction-dependend automatic white/red head and tail lights, a flashing disco light for a special wagon using multi-color LEDs, flashing lights in any color for special trains, etcetera. We also plan to adapt the motor power to the decreasing voltage of the battery in future versions of the firmware.

Controller Configuration

Make sure you know the MAC address(es) of your hub(s). The MAC address of your hub is required to start configuring your first locomotive.

Configuring your first locomotive

Let’s assume you have a locomotive you want to control using Rocrail. It has a PU Hub in it, with a motor attached to channel A and lights to channel B. In that case your controller_config.json could look like this:

{
  "locos": [
    {
      "address": 1,
      "name": "Your first loco",
      "bleHubs": [
        {
          "type": "PU",
          "address": "00:07:80:d0:47:43",
          "channels": [
            {
              "channel": "A",
              "attachedDevice": "motor"
            },
            {
              "channel": "B",
              "attachedDevice": "light"
            }
          ]
        }
      ]
    }
  ]
}

If you’re familiar with JSON files you can probably understand this structure. The root of this config file has a subnode locos, which contains an array of locomotives. For each locomotive you need to specify a few basic properties:

address: The Rocrail address of the locomotive
name: A name for your locomotive
enabled: Indicates if the loco is enabled (“true”, default) or not (“false”). Can be used to temporarily remove a loco from the controller without removing the configuration itself.
bleHubs: This contains an array of BLE Hubs within this locomotive

For each BLE Hub that’s in your locomotive you also need to configure some properties:

type: The type of BLE Hub (either PU or SBrick)
address: The MAC address of the BLE Hub (see above on how to discover this)
powerlevel: For BuWizz2 hubs, you can specify a powerlevel. Allowed values are: “slow”, “normal” (default), “fast” and “ldcrs”. Please be careful with any powerlevel beyond “normal”, as your appliances may be damaged due to overvoltage.
channels: This contains an array of BLE Hub channels

For each channel of the BLE Hub you need to configure a few parameters as well:

channel:
- for LEGO PU Hub:
  - A, B or LED
- for SBrick:
  - A, B, C or D
- for BuWizz2:
  - 1, 2, 3 or 4
attachedDevice: The type of device connected to the channel (either motor or light)

Assuming you have Rocrail setup correctly and made no errors in your configuration files, this should allow you to run your first train using Rocrail, controlled by the MTC4BT.

Please note these are only the basics and there are many other properties on all levels that you can use to tweak your locomotives. We’ll go into more detail in the next sections.

Advanced configurations

Even though a controller can run with an empty controller_config.json file, for fun you need to at least add one locomotive configuration to it. But there’s a lot more you can configure related to the controller itself. Please find a complete list of settings below.

{
  "name": "MTC4BT1",
  "pwrIncStep": 10,
  "pwrDecStep": 10,
  "espPins": [
    {
      "pin": 17,
      "attachedDevice": "light"
    },
    {
      "pin": 18,
      "attachedDevice": "status"
    }
  ],
  "locos": [
    {
      "address": 1,
      "name": "Your first loco",
      "bleHubs": [
        {
          "type": "PU",
          "address": "00:07:80:d0:47:43",
          "channels": [
            {
              "channel": "A",
              "attachedDevice": "motor"
            },
            {
              "channel": "B",
              "attachedDevice": "light"
            }
          ]
        }
      ]
    }
  ],
  "locoConfigs": [
    "/loco_BC60052.json",
    "/loco_CR10277.json"
  ]
}

name: Name for your controller (default: MTC4BT)
pwrIncStep: The default power increment step to be used for all locomotives (default: 10)
pwrDecStep: The default power decrement step to be used for all locomotives (default: 10)
espPins: This contains an array of pins of the ESP-32 microcontroller to use
- pin: pin number
- attachedDevice: light (use as a regular LED) or status (use as a status LED)
locos: This contains an array of locomotive configurations
locoConfigs: This contains an array of separate locomotive configuration files to load during startup (to be placed in the same directory as the network_config.json and controller_config.json files)

Both nodes “locos” and “locoConfigs” can be used in the same controller_config.json file. Read more on all settings of a locomotive in the next paragraph.

A locomotive with events, triggers and actions

Locomotives are what makes our world go round, so there are loads of settings to configure them just like you want them to behave on your layout. Below you find a complete set of all options for locomotives. The same structure can be used in the “nodes” section of the controller_config.json file as well as the content of separate locomotive configuration files.

{
  "address": 6,
  "name": "CR10277",
  "pwrIncStep": 10,
  "pwrDecStep": 10,
  "bleHubs": [
    {
      "type": "PU",
      "address": "90:84:2b:0a:e3:73",
      "channels": [
        {
          "channel": "LED"
        },
        {
          "channel": "A",
          "attachedDevice": "motor",
          "direction": "backward"
        },
        {
          "channel": "B",
          "attachedDevice": "light"
        }
      ]
    }
  ],
  "events": [
    {
      "triggers": [
        {
          "source": "rr",
          "eventType": "fnchanged",
          "identifier": "f1",
          "value": "on"
        },
        {
          "source": "loco",
          "eventType": "dirchanged",
          "value": "forward"
        },
        {
          "source": "loco",
          "eventType": "dirchanged",
          "value": "backward"
        }
      ],
      "actions": [
        {
          "channel": "LED",
          "color": "white"
        },
        {
          "channel": "B",
          "pwrPerc": 80
        }
      ]
    },
    {
      "triggers": [
        {
          "source": "rr",
          "eventType": "fnchanged",
          "identifier": "f1",
          "value": "off"
        },
        {
          "source": "loco",
          "eventType": "dirchanged",
          "value": "stopped"
        }
      ],
      "actions": [
        {
          "channel": "LED",
          "color": "off"
        },
        {
          "channel": "B",
          "pwrPerc": 0
        }
      ]
    }
  ]
}

We already established most of these basic settings for a locomotive:

address: The Rocrail address of the locomotive
name: A name for your locomotive
pwrIncStep: Can be used to override the “pwrIncStep” configured at controller level
pwrDecStep: Can be used to override the “pwrDecStep” configured at controller level
bleHubs: This contains an array of BLE Hubs within this locomotive

For each BLE Hub that’s in your locomotive you also need to configure some properties:

type: The type of BLE Hub (“PU”, “SBrick” or “BuWizz2”; all case sensitive)
address: The MAC address of the BLE Hub, e.g. “84:2e:14:51:7f:c5” (see above on how to discover this)
channels: This contains an array of BLE Hub channels

For each channel of the BLE Hub you need to configure a few parameters as well:

channel:
- for PU Hub:
  - A, B or LED
- for SBrick:
  - A, B, C or D
- for BuWizz2:
  - 1, 2, 3 or 4
attachedDevice: The type of device connected to the channel, either motor, light or nothing (default: nothing)
direction: forward or backward, can be used to reverse a motor (default: forward).
- Attention: up to firmware version V1.0.2, please use the keyword reverse instead of backward. In more recent versions of the firmware, the keyword reverse also still works.

A PU Hub has an onboard LED. By default it flashes after you turn it on or the hub looses its connection. It turns white after establishing a connection with the controller. By explicitly specifying the “LED” channel in a PU Hub’s configuration, you basically get full control over it. It can now be references by event actions, which we get more into later. Did you know the onboard LED can display colors? B.t.w. there is no need to explicitly configure the “attachedDevice” for an “LED” channel. We enforce “light” as the attached device, no matter what you might configure here.

events: This contains an array of events
- triggers: This contains an array of triggers
- actions: This contains an array of actions

Events can be used to automate behavior. They can be triggered by Rocrail functions, by the locomotive or both. Each event can have multiple possible triggers and can execute multiple actions. Any trigger defined in an event executes all actions defined for that event.

You can configure a Rocrail trigger like this:

{
  "source": "rr",
  "eventType": "fnchanged",
  "identifier": "f1",
  "value": "on"
}

source: rr = rocrail (default: loco)
eventType: fnchanged
identifier: Name of the Rocrail function that triggers the event (f0-f32)
value: The value that triggers the event: on or off

A locomotive trigger is configured like this:

{
  "source": "loco",
  "eventType": "dirchanged",
  "value": "forward"
}

source: loco (default: loco)
eventType: dirchanged (raised when the locomotive changes direction or stops)
value: The value that triggers the event: forward, backward or stopped

With actions you can configure what should happen if a trigger for an event is fired. Actions reference a channel of a specific device.

An action turning on an LED attached to a pin of the microcontroller can be configured like so:

{
  "device": "espPin",
  "pin": 17,
  "pwrPerc": 50
}

device: espPin or bleHub (default: bleHub)
pin: ESP-32 pin number (note the pin must be configured at controller level!)
pwrPerc: Percentage of power to apply to the channel (can be negative for backward direction)

An action turning on an LED attached to a channel of a BLE Hub can be configured like so:

{
  "device": "bleHub",
  "address": "90:84:2b:0a:e3:73",
  "channel": "B",
  "pwrPerc": 50
}

device: espPin or bleHub (default: bleHub)
address: BLE Hub address (not required if only one hub configured, else it must match the address of a configured BLE Hub)
channel: BLE Hub channel (must match a configured BLE Hub channel)
pwrPerc: Percentage of power to apply to the channel (can be negative for backward direction)

An action changing the state of the onboard LED of a PU Hub can be configured like so:

{
  "device": "bleHub",
  "address": "90:84:2b:0a:e3:73",
  "channel": "led",
  "color": "red"
}

device: espPin or bleHub (default: bleHub)
address: PU Hub address (not required if only one BLE Hub configured, else it must match the address of a configured PU Hub)
channel: led
color: none, off/black, pink, purple, blue, lightblue, cyan, green, yellow, orange, red or white

More configuratione examples

You’ll find a lot more example loco files in the directory ‘data_example/loco_examples’.