Blocks, sensors, actuators

These three entities form the logical layer that sits on top of the track. Each one has a specific role.

Block

A block is an identified section of the layout, delimited by two track port references (a start and an end). Conceptually it’s a “station” or a “plain track section” that can be occupied by only one locomotive at a time.

The block is the basic unit for:

• Reservation (the supervisor reserves a block before letting a train enter it),
• Detection (knowing whether it’s occupied or free),
• The destination of a travel.

It has a human-readable name (“North Yard”, “Passing Loop 2”), a reserved / free state, an occupied / empty state, and a detection mode (continuous or point — see Detection modes (coming soon)).

Sensor

A sensor is a hardware point that detects the passage or presence of a train. In TrainPanel:

• It maps to a hardware address (such as a node + pin pair on a WIO box for instance).
• Its location is given by two network positions (a start and an end point) — a precise zone on the track.
• It is, most often, attached to a block (acting as start or end sensor, or to detect the block occupancy).

The sensor does not act on the block: it publishes an event when its state changes. The supervisor interprets those events to mark the block “occupied” or “freed”.

Actuator (turnouts and friends)

An actuator is a pilotable device attached to a rail: turnout motor, uncoupler, signal head, etc. It has:

• A DCC address (on the command-station side).
• A type: binary, discrete or mapped — see Configuring an actuator (coming soon).
• A current state as a string (e.g. straight / thrown for a binary turnout).

The actuator is what materialises the active path on a multi-path rail (turnout): changing the actuator state changes the rail’s active path.

The big picture

Locomotive  ───runs on───▶  Rails (paths)
                                │
                                │ grouped into
                                ▼
                            Blocks  ◀───triggered by────  Sensors
                                │
                                │ traversed by
                                ▼
                            Travels routed by the supervisor
                                │
                                │ which commands
                                ▼
                            Actuators (active-path change)

Wiring up all three entities is the prerequisite for automatic control. See Auto mode prerequisites (coming soon).