6 Operate your physical layout

This page describes how to setup and run your LEGO devices with a virtual layout that you have created before.

Add your hubs

With your virtual layout open in brickrail, you'll notice in the right panel the tabs "trains" and "controllers".

With the "trains" tab open, click "add train". A panel with the name "train0" should appear below.

Now we want to associate this train with one of your hubs. Make sure you have installed pybricks firmware on this hub (see previous section), then turn the hub on by pressing the button. It should not flash with a blue light, which means that the device is discoverable via Bluetooth Low Energy (BLE).

While the hub is discoverable, hit the "scan" button to the right of the new "train0" panel in the "trains" tab. The name "hub0" should get replaced with the name of your hub within a fraction of a second. If not, make sure you've installed pybricks firmware properly.

That's it for assigning your hub to this brickrail layout. You can try hitting the "connect" button on the train. If it worked correctly, the associated hub should stop flashing and instead display a continuous blue light.

You can now do the same process for all your train hubs. Make sure that your other hubs are either turned off (press the button for a few seconds) or connected in brickrail, otherwise you might accidentally discover the wrong hub with your new train. Double-check that all your trains have unique names associated with them.

If you also have layout controller hubs, head to the "controllers" tab and repeat the same process for all your stationary hubs.

Assign devices

After you have added a hub to your layout, we now want to assign these physical devices with their virtual representations in the brickrail layout.

To do this, make sure you are in the "edit" layout mode.

Assign trains

To assign one of your physical trains with a brickrail train, select the virtual train in brickrail. In the Inspector to the right, you should see a "ble train" field. Select the name of the hub you added previously to assign this hub to the virtual train.

Assign switch motors

Switch motors are assigned to specific ports of a given layout controller hub. To do that, select the switch in the layout, then assign the "controller" and "port" fields to the correct hub name and port.

Save the layout

Once all devices are assigned, you can save the layout to remember the specific hubs you connected with the layout.

Operate the layout

Now we are ready to operate the layout. Go to the "run" layout mode. In the top panel above the viewport, find the "control devices" switch and turn it on. If you have hubs in the project, brickrail will now try to connect to all of them and start the correct programs on each hub. After a few seconds, the "control devices" switch should be on, and you can start to control your devices. All your hubs should now show a "breathing" blue hub light (Not blinking, not turned off).

Right click on a switch to switch it. If that switch is connected to one of your physical switch motors, this switch should now operate physically as well. If not, disable "control devices" and double check your controller and port settings in "edit" mode.

To start a train, operate them just as you learned in the previous sections. Right click and hold a train, hover over a logical block and release to make the train go to this logical block. Turn on "random" targets to operate the layout fully autonomously.

Troubleshooting

If things aren't working as expected, these can be some common sources of errors:

• Trains need to have a pybricks-compatible Motor plugged into Port A, and a Color & Distance Sensor plugged into Port B. Currently, there is no good error message appearing if that isn't the case, and the hub program will just crash.

• Each hub needs a unique name set in the pybricks firmware install process.

• Each hub needs the special firmware provided with brickrail, not the default pybricks firmware. Make sure you selected the special firmware in the install dialog in pybricks code. Check the previous section again for detailed instructions.

• All virtual devices in brickrail need to be correctly associated, make sure each switch motor has the correct controller hub and Port assigned, and all trains have a different train hub assigned.

• Currently there is no way to change default motor directions, so brickrail assumes the motor direction. If your train drives backwards when it is supposed to drive forwards, this means brickrail has the wrong assumption. Similarly, if your switches seem to always switch to the opposite position, the switching mechanism is built with misaligned motor direction assumption. In the future, you will be able to configure this but for now, make sure your models are built with this assumtion in mind, or head to the source code micropython programs "smart_train.py" and "layout_controller.py" to try to change it.

• Make sure the color of your physical layout markers is consistent with the sensors set in the brickrail layout. Also avoid using any high-chroma colors in the rest of your layout. Low-saturation colors like dark bluish gray, black and white should be fine.

• Make sure the Color Sensor is mounted correctly, it should be within 1cm of the color markers on the tracks, pointing straight down.