Crossing-gate Example

This is an example of how a model railroader might first encounter OpenLCB by using it to automate a crossing gate.

Basic Setup

A user wants to operate a crossing gate from two block detectors (left and right). Specifically, the crossing gate assembly is made by Manufacturer A, and has a bus interface. The block detectors come with a single block interface card.

This is his first use of the bus. He has neither parts nor knowledge to reuse.

His criteria are:


He needs to buy the crossing gate (with interface) and the block detectors (with interface), plus

Assembly & Configuration (Option A)

This option uses on-board capabilities only. See option B for use of a separate configuration tool.

  1. The user mechanically installs the boards on the layout or test bench, wires them to power and other connections as needed.

  2. The user connects the cable between the two cards

  3. The user puts a terminator in the empty second socket on each card

  4. Layout power (power to one board, the other obtains power though its CAN cable) is turned on

  5. Each of the two boards initializes itself using its on-board resources.

  6. [The "new board gets new IDs" process is performed twice to configure the boards with unique & valid, but otherwise unknown, CAN IDs, node IDs and one or two device IDs. These are then remembered and used by the board from now until changed. More detail on this is needed. It's assumed to take less than people-time, e.g. no explicit wait for it is required].

  7. The block occupancy board comes with Events pre-configured to be unique from each other. The user can test them by adding and removing loads to the monitor track sections; the LEDs on each of the boards should react (see the "Diagnostics" section). Because this is an initial configuration, the block occupancy board needs nothing else.

  8. The crossing gate board needs to learn four events: "Left track occupied", "left track empty", "right track occupied", "right track empty". To do this, the user ensures that the two tracks are unoccupied, then:

The user can then test the operation by adding and removing loads from the track. It's up to the crossing gate as to how it responds, e.g. lights, motion, etc.

Assembly & Configuration (Option B)

This option uses a separate configuration tool. See option A for use of only on-board capabilities.

  1. The user mechanically installs the boards on the layout, wires them to power and other connections as needed.

  2. The user installs the configuration node where wanted; if that involves connection to a computer and installation of software, the user does that

  3. The user connects the three nodes with two cables

  4. The user puts a terminator in the two empty sockets

  5. On power-up, the boards will self-configure and announce ther presence to the configuration program. The program will then request more information from the boards as to their identities and capabilities. The program will then let the user link the two boards together easily.

  6. The software will also know the capabilities of the boards and the node variables (NVs) that each contains. It will allow the user to review and change these NVs to change the behaviour of the boards. In the present example, NVs might include the speed of raising and lower the pole, flashing patterns, hold-over time, and sound effect volume.


  1. Layout power comes on .

  2. Each of the two boards initializes itself using its on-board resources.

  3. Soon after power is up and stable, each board transmits an "I am here" message which starts the assignment of a local ID process.

  4. After the local IDs are assigned, the occupancy detector checks the status of the monitored tracks. The default track status is by default unoccupied; if the track status at this point is the same as the default status, no event needs to be reported. If the tracks status at this point is different from the default status, the appropriate event is generated. (Optionally, the board can have the default status configurable, and whether the current state is always reported).

  5. When a change to track occupancy is detected, the occupancy-detector board sends the relevant tie-ID as a message. This occurs on either type of change, for either section. (Optionally, the occupancy board can have debouncing and/or delay built in, which might or might not be configurable. In any case, once an event is reported, the device is considered to be in the reported state, and any change in the state requires another event to be reported).

  6. When it receives an event message from the occupancy detector, the crossing gate module uses its own internal logic and configuration information to act. This might be as simple as "gate down when either track occupied, stays down until both tracks cleared. But it might be more complicated, such as "gate down when one track goes occupied, gate goes up when that track clears, even if other track is occupied' (directional logic). Etc.

  7. Neither module retains state on power down warning.

Diagnosis of Faults

[This section describes some basic diagnostic capabilities. As such, it's not clear that it fits a "normal operation" scenario, but we've got so much invested in the context of this scenario, and diagnostics are so necessary in practice, that I've included it. Some of the stuff mentioned here is not replicated above in the interest of brevity, but it could be)].

Each board carries an LED (the "bus activity LED") that flashes when the node sees a good frame from _another_ node on the bus. Note that this LED does not flash when this node sends a message. The flashing does not depend on whether this node acts on the message, or even is interested in it.

Each board also carries an LED (the "addressed LED") that flashes when the node emits a message or receives a message that it will act on.

Shortly after layout power-up, each node will therefore flash its bus activity once. At about the same time, each node will also flash its bus activity LED, at least once, to indicate that the connection to the other node(s) is operational.

When one of the occupancy detectors is triggered, e.g. by a load going on or off the track in that section, the activity LED should blink on all cards, and the addressed LED should blink on the occupancy detector card. If that doesn’t happen, the bus wiring should be tested. Once the bus is working properly and the cards are configured, the crossing-gate card’s activity light should also flash when an occupancy detector goes active, signaling that the crossing gate card is configured to listen for that event.

Site hosted by

This is SVN $Revision: 721 $