This page will describe how to install the correct firmware on your LEGO Hubs and how to use motors and sensors with the hubs.

All Bluetooth hubs need to run Pybricks firmware to use them with brickrail. Only with this firmware, the hubs can run the programs necessary for communication with the PC and operating the layout.

Brickrail aims to be compatible with current Pybricks firmware releases. To make results consistent, Brickrail comes with the firmware that is used when developing Brickrail, in order to remove any variability when users have different versions of the Firmware. There is a specific .zip file for each type of LEGO Hub in the firmware/ folder in the Brickrail releases. It is recommended to install this firmware in order to eliminate any potential compatibility issues.

NOTE: Before installing the firmware, remove all connected devices from the hub! There is a bug in the LEGO bootloader which prevents the firmware to be installed correctly when a motor is plugged into the hub. If something went wrong, remove the batteries for a few seconds and then try the install process again.

To start installing the firmware, you can use Pybricks Code web-app. In the left menu, click on "Install Pybricks firmware". In the popup, select the type of hub you want to install the firmware on. Then, expand the "advanced" section in the lower part of the popup to reveal the custom firmware field. Drag and drop the custom firmware .zip file specific to this type of hub found in the brickrail release folder, then click next.

Next, you will be asked for a name for the hub. It is quite important that all your hubs have a unique name, as it is the only thing identifying the hubs. These names will later be assigned to the train and layout controller devices in the brickrail GUI.

For example, a naming convention could be <hub-type>-<color>. With this convention, a LEGO City hub could have the name "city-blue". Then put a blue LEGO piece on the hub so you will always know which one it is.

After selecting a name, follow the rest of the steps from the installation wizard. After a few minutes, the firmware should be correctly installed! You can play around using Pybricks Code and its documentation to make sure the installation has worked correctly.

Finally, repeat the installations for all hubs you plan to use on your layout.

Brickrail expects the driving motor to be plugged into Port "A" of your hub.

You will also need to attach a Color and Distance sensor. Make sure it is pointed downwards and close to the track, and plugged into Port "B".

Here is a example of how you might mount the sensor in a regular LEGO City Train:

This works flawlessly with the Passenger trains 60197, 60051. On the cargo train 60198, you'll need to reposition the PoweredUp hub into one of the cabs. Then the button can be operated by opening the cab roof.

For each of your motorized switches, you'll need one pybricks-compatible motor plugged into one port of a stationary hub. Currently, brickrail applies one 0.6 second long pulse to switch the switch. It applies a pulse in the other direction to switch to the other position.

Here is an example of a mechanism that I use together with switches from TrixBrix:

For official LEGO switches, you'll find a lot of examples of how to accomplish this. Just make sure that the mechanism involves a clutch of some kind, because right now, brickrail doesn't support angle-calibrated switch mechanisms yet.

Some inspiration for switch mechanisms can be found here.

Edit: Here's an updated much more compact version of the switch mechanism for trixbrix switches: trixbrix-switch-motorized-v6.pdf

Example mechanism of a LEGO Technic-based setup for Trixbrix-switches (Instructions.pdf (outdated, see above)):

As described in previous sections, blocks are essential concepts for train automation in brickrail. Each block reresents a section of your layout that can contain all your train fully (no train should be larger than your smallest block), and most blocks represent location where your train is able to stop.

To mark off your block, you have to place one color marker at each end.

If you plan to use prior sensors for trains that arrive backwards, add them before the blocks, consistent as with your virtual layout (prior sensors are explained in a previous section)

Each marker should have a color consistent with what you set in your virtual layout. If you set the color "None" the actual color doesn't matter, as long as the marker has a bright and saturated color (= high chroma value). Colors that work well are e.g. LEGO red and blue. Colors to avoid using as markers are black, white, gray and overall dark or desaturated colors.