The routing supervisor

The supervisor is the module that turns a travel request into concrete commands (speeds, turnouts). Serving as a dedicated model train collision prevention system, it’s the “brain” of Auto mode.

What it does

The supervisor runs continuously (several times per second):

  1. For each queued request, it tries to find a free route.
  2. For each active travel, it checks where the loco is and adjusts commands.
  3. It reserves the upcoming blocks ahead of time and throws turnouts before the train passes.
  4. It releases blocks as the train clears them (exit-sensor trigger or physics-engine estimate).

Route computation

At a high level, the supervisor:

  • starts from the block containing the loco (with its current orientation),
  • explores neighbouring blocks via the port connections,
  • prefers shortest routes by number of paths traversed,
  • excludes any route through a block reserved by another loco.

When several routes are possible, the shortest wins. You can steer the choice by specifying the entry/exit sides of the blocks (see Create a travel).

Reservations

Before letting a train into a block, the supervisor reserves it: the block is reserved for that locomotive. No other train can enter as long as the reservation is alive.

The reservation is released as soon as the locomotive has left (exit-sensor trigger or physics-engine estimate). That’s what lets a following train take the same path without collision.

See Reservation, occupation, force-release (coming soon).

Speed servoing

The supervisor doesn’t send a constant speed: it ramps the target speed based on the distance to the next braking point (entry of a reserved block, end of route). Concretely:

  • approaching a still-reserved block, it slows down progressively and stops before the limit if needed,
  • at the final destination, it brakes to stop precisely where requested.

The acceleration used respects the loco’s acceleration parameter.

Failure and recovery

If a travel fails (faulty sensor, unexpected conflict, Derailed status), the supervisor:

  • stops the affected loco,
  • marks the travel as error (visible in the list),
  • releases its reservations.

It’s up to you to fix (re-place the locomotive, release a block by hand) and then re-issue a new travel request.

Take back control

At any time, switch to Manual mode: the supervisor halts its calculations and lets you drive directly. Switch back to Auto and it resumes queued travels.