Control Model Railroad Trains

Software for scheduling, dispatching, and driving trains on a model railroad.

Status: alpha. Interfaces, topics, and file formats change without notice, and nothing here runs on a layout other than the author's yet. Published to share the design, not to be installed. MIT licensed.

This repo (eventually) implements the features described in the docs:

• Goals — the end state: assets (tracks, blocks, connections, stock) and the three operations performed on them — scheduling, dispatching, driving.
• Milestone 1 — reached: what the first slice built, and what is deliberately still out of scope.
• Milestone 2 — not reached: trains on a physical layout, what is built for it, and what only a running railroad decides.
• System — the apps and the contracts between them: the event bus and its inventory, time, and the asset store.
• Architecture — how the repository is organized and how it is tested.
• Glossary — canonical terms; decisions in docs/adr.
• Deploy — the names, the certificate and the reverse proxy that puts the stack on the LAN, living in deploy/.

Each app's implementation details live beside it:

• Dispatcher — dispatch (finding, locking, and releasing routes), safety (why it is deadlock-free), and internals.
• Store — the drawing format and derivation, the only committed topology, and the derived layout, the roster and the harness's scenario file it feeds, and backing a store up with git; the drawn railroads and their rosters live in bench/layouts/ and the harness's scenarios in bench/scenarios/.
• Bench — the benchmark suite and the metrics derivations.
• Layout — the layout interface as a core app: the three rules a command meets, and the device vocabulary the hardware hangs under.
• Command station over USB — the command station mirror: one process owns the USB device and serves it on TCP 2560, so the dccex translator, JMRI and hand-held throttles share one command station.
• DCC-EX — the translator between the device vocabulary and the command station: the mapping a row at a time, the latched stop and the zeros that precede its release, and the only page here that writes the station's own syntax down.
• UI — one app with four views of the loaded railroad, the layout editor, the run view, the throttle a person drives a train from and the stock view they make cars and trains in, living in ui/.