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.
There is a video tutorial available here that covers these steps on a minimal layout.
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.
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.
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.
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.
Once all devices are assigned, you can save the layout to remember the specific hubs you connected with the layout.
Before operating the layout, you will need to make sure that each train position is consistent with the virtual layout. You can right click + drag each train in edit mode to a new logical block to teleport it to a new position.
When a train occupies a logical block, it is important that the orientation and the specific position of the Color sensor relative to the block markers is correct. Take e.g. the following brickrail train position:
The correct train position is this:
This train is oriented facing to the right. You can see the virtual trains orientation by the position of the black circle (not necessarily the arrow position). The black circle represents the location of the train sensor, which is always supposed to be in the front of the train.
For this logical block, the "in" marker is the right marker. For a train occupying this logical block, the sensor should be in front of the "in" marker.
This means that in your physical layout, the correct orientation of the train is looking to the right where the sensor of the train is at the right end of the train. The correct position of the train is such that the train sensor is located to the right of the "in" marker. The sensor should not be on top of the marker, but next to it on the right.
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" selector and select "All". 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.
When "control devices" is set to "Switches", only the switches will be controlled by the layout. Trains can then be controlled manually in the left panel. The virtual trains don't control your physical trains in this mode, but you can use right click on the virtual switches to operate your physical switches.
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. If you get the error message "missing motor or sensor", you should check whether all devices, are attached properly, as configured in the layout.
-
Each hub needs a unique name set in the pybricks firmware install process.
-
Brickrail is mostly tested with the specific version of the firmware provided in the Brickrail releases. If you have any problems with your hubs, try to install the firmware version that comes with Brickrail. 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.
-
If your train drives backwards when it is supposed to drive forwards, this means brickrail has the wrong assumption. You can flip the motor direction in the virtual train settings, if a hub is assigned. If your switches seem to always switch to the opposite position, you can set the "inverted" flag in the switch inspector.
-
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.
-
Make sure that the initial train positions are correct and consistent with the above instructions before starting any train.
-
Do not change any switch positions by hand while the layout is operated. This makes brickrail's understanding of the switch positions inconsistent with the actual switch positions.