Trains
Interlock drives locomotives the way an LCC throttle does: it asks the command station for a train node with the Train Search protocol, takes the controller role, and sends Train Control commands for speed, direction and functions. The Throttle page is the cab; trains.yaml in the data directory is the roster; automations can drive trains with the train action; and the Programming page reads and writes CVs.
The roster
A roster entry gives a locomotive a name and remembers its function labels, what it is, and its decoders with their saved CV values; the Roster page covers those and importing a JMRI roster. The web interface writes the file; it can also be edited by hand (restart Interlock afterwards):
trains:
- id: big-boy
name: Big Boy
address: 4014
long: true
functions:
0: Headlight
1: Bell
2: Whistle
momentary:
- 2
road_name: Union Pacific
road_number: "4014"
decoders:
- id: tsunami2
file: SoundTraxx_Tsu2_Steam.xml
family: Tsunami2 Steam
model: TSU-2200 Steam
installed: tsunami2| Field | Meaning |
|---|---|
id | The entry's ID, made from its name when it is added. Entries from before 0.2 have their address as their ID ("1234", or "3l" for a long address of 127 or less) until their address changes. |
name | What the throttle shows. Defaults to the address. |
address | DCC address, 1 to 10239. Several entries may share one. |
long | Address kind. Addresses above 127 are always long; below that, short unless set. |
functions | Labels for the function keys, by number. |
momentary | Functions that act only while held, such as a horn. |
road_name, road_number, manufacturer, model, owner, comment | What the locomotive is. |
decoders | Its decoders: id (unique in the roster; it names the decoder's CV file), name, the definition's file, family and model, the identity it reported, and for one not fitted the address, long, functions and momentary it brings back when it is. |
installed | The ID of the decoder fitted now; the address and labels above are its own. |
A locomotive need not be in the roster to be driven: the throttle page accepts any address, and an automation names trains by address. Such a train shows up in the list marked as not in the roster, and can be added with its state kept.
Driving
The first command to a train does three things: it sends a Train Search event for the address with the allocate flag, so a command station that has no node for the locomotive yet creates one; it sends Controller Assign to the node that answered; and it reads the train's speed and functions back so the cab shows what the train is doing. After that each command is one Train Control message. Release gives the controller role up and keeps the last known state.
Speed runs from 0 to 126, which DCC command stations map to the 128 speed steps one for one. A train's emergency stop is its own command: it sets the speed to 0 at once, keeping the direction, and the train stays stopped until a speed is set. If another throttle takes the train, the train tells Interlock, which lets it go and shows who has it; the next command takes it back.
The Throttle page also carries the layout's emergency controls. "Stop all trains" produces the well-known Emergency Stop event and "Power off" the Emergency Off event. Command stations such as simple-dcc answer Emergency Stop by holding every locomotive stopped without changing its speed, and Emergency Off by cutting track power. Interlock watches for the same events from anyone else, so a stop pressed on a hardware throttle shows here too, and asks the command stations whether they hold their trains when they come onto the bus.
While the trains are held, each keeps the speed it was set to, and its cab shows that speed as held. A speed set meanwhile, here, from a throttle app or by an automation, is what the train goes back to; Stop sets it to 0, so the train stays put. Resume ends the hold, and every train goes back to its speed, slowly where its decoder has momentum. Before that, Interlock asks each train on the bus for its speed, since another throttle may have changed one during the hold, and lists those that will move, each with Set to 0. With none set to move it resumes at once.
Releasing a train that is held at a speed leaves it to start again on Resume with no throttle driving it, so its cab warns first and offers Stop and release. A drive ends when the hold begins and sets its train to 0, so that Resume doesn't start it with nothing to brake it (see Driving trains). Trains keep their speeds through Power off too, and carry on when power comes back.
Whether track power is on comes from the command stations: Interlock asks them when they come onto the bus, and simple-dcc also says so whenever it starts, with its power off. The page shows the power as unknown until a command station has said, or when two of them disagree; a command station that does not say leaves it unknown until power is switched from Interlock or another throttle.
Consists
A consist is two or more locomotives from the roster that run together, driven as one through the first of them, the lead. Add a consist on the Roster page starts one with a name, the lead, one more locomotive, and where the consist is kept; its page adds the rest. For each locomotive after the lead it says:
- which way it faces: forward like the lead, or backward, so it runs in reverse while the lead runs forward;
- whether it follows the lead's F0 (usually the lights) and the lead's other functions. Functions it does not follow stay its own, worked from its own cab on the Throttle page.
A consist is kept in one of two places, chosen when it is added and changed on its page while it is apart.
Kept in the decoders
Each decoder is given a consist address, 1 to 127, which it answers as well as its own: driving that address drives them all at once, with one packet on the track. This is DCC advanced consisting.
Make up writes each decoder's CVs on the main, with the locomotives stopped: CV 19 holds the consist address, with bit 7 set for a locomotive facing backward, and CVs 21 and 22 the functions it takes at the consist address. The lead takes them all; the others take F0 and the rest as the consist says. With a command station that reads on the main over RailCom, Interlock then reads CV 19 back from each decoder, and puts the consist apart again when one did not take it. The CVs are kept for each locomotive's fitted decoder, as programming on the main keeps them.
Drive the lead and the speed goes to the consist address, which every decoder answers; so do the lead's F0 to F12, which each decoder takes only if it follows them. Higher functions stay the lead's. A decoder in a consist ignores speeds at its own address, so the others' cabs refuse speed changes, and an emergency stop from any of their cabs stops the whole consist. Any throttle can drive the consist address too: it shows on the Throttle page under the consist's name once it has been driven, and throttle apps list it (see below).
The decoders keep the consist until it is broken up, through restarts of the command station and of Interlock. Break up, once the consist is stopped, writes 0 to each decoder's CV 19; a decoder that could not be reached, or still reads its consist address, leaves the consist made up, with the reason on its page, so it can be broken up again. A locomotive left in a consist answers its own address only for functions, so it seems not to run.
While a decoder is in a consist, RailCom detectors report it by the consist address. Tracking takes that address as the lead's train, so a consist runs as one train: put its locomotives in one train to give it its length. After the break up each decoder reports its own address again.
The command station has to send the decoders the standard's consist instruction for a write of CV 19 on the main; simple-dcc does.
Kept by the command station
Make up tells the lead's train node on the command station to pass its speed, and the functions each member follows, on to the members' train nodes. Nothing is written to the decoders, and each locomotive keeps its own address, so detectors still report each one. Drive the lead and the others follow; their cabs show the speed they were given and refuse speed changes of their own, though their functions and emergency stop still work. In a throttle app, drive the lead.
The command station forgets a consist when it restarts. Interlock keeps it made up, and puts it together again before the lead is next driven, after either of them restarts. Break up takes it apart again, once the lead is stopped: a member keeps the last speed the lead passed on, so breaking up a moving consist would leave it running.
A simple-dcc command station takes up to four locomotives besides the lead, and only locomotives on that command station; one that cannot be added leaves the consist apart, with the reason on its page.
Either kind
While a consist is made up its locomotives can be renamed but not given new addresses, removed from the roster or put in another consist.
Consists are kept in trains.yaml beside the locomotives:
consists:
- id: coal-drag
name: Coal Drag
kind: dcc # lcc for one the command station keeps
address: 10
members:
- train: csx-6641
- train: csx-9969
reverse: true
f0: true
made_up: trueThrottle apps
Throttle apps that speak WiThrottle can drive trains through Interlock: Engine Driver on Android, WiThrottle on iPhone and iPad, and handhelds such as WiTcontroller. Interlock announces itself on the local network, so the app lists it under Interlock's node name (Interlock unless it was renamed under node:); if an app does not find it, give it the computer's address and port 12090.
The app sees:
- the roster, with each locomotive's function labels. Functions marked momentary in the roster act only while held. A locomotive taken by its address, with nothing in the roster, keeps the app's own labels, and its F2 (the horn on most decoders) is momentary;
- the consists kept in the decoders while they are made up, by consist address; choosing one drives that address. Engine Driver lists each under its locomotives' addresses joined by "+", such as 150(L)+9969(L). A consist the command station keeps is driven through its lead;
- the turnouts, to throw and close, except hidden ones and guesses not confirmed on the Entities page;
- track power, which it switches with Emergency Off and Clear Emergency Off as the Throttle page does, and shows as the command stations report it;
- the fast clock;
- the web interface, in Engine Driver's Web tab.
Every app drives through Interlock's own node, so to the command station the apps and the Throttle page are one throttle. Several apps can hold the same locomotive, and each sees the others' changes. Interlock gives the train up when the last app releases it. Releasing a locomotive or closing the app leaves the train running at its speed, as other WiThrottle servers do; Engine Driver sets the speed to zero first unless told otherwise. While the layout's emergency stop holds the trains, Interlock sets a train an app lets go of, or loses when the phone drops off the network, to 0 first, so Resume doesn't start it with no throttle driving it.
An app that asks Interlock to watch it, as Engine Driver does once it holds a locomotive, and then sends nothing for 15 seconds has its trains brought to an emergency stop, for a phone that drops off the network with a train running. After 40 seconds its connection is closed. An app that connects again with the same device ID replaces its old connection without stopping anything.
The server is set in interlock.yaml. Like the web interface, it lets anyone on the network connect.
withrottle:
listen: ":12090" # "" turns it offIn automations
The train action drives a locomotive by address:
actions:
- type: train
address: 1234
command: speed
speed: 30
direction: forward
- type: train
address: 3
address_type: short
command: function
function: 0
state: on| Field | Meaning |
|---|---|
address, address_type | Which locomotive; address_type is long or short and only matters up to 127. |
command | speed, stop, estop or function. |
speed, direction | For speed: 0 to 126, and forward or reverse; leave the direction out to keep the current one. |
function, state | For function: F0 to F68 and on or off. |
Together with the locomotive trigger this is enough for "stop the train that just entered the yard" or "sound the horn at the crossing".
Programming
Service mode, on the programming track, reads and writes one CV at a time through memory space 0xF8 of the command station that produces the "is programming track" event; CV n is at address n-1. The command station acknowledges with reply pending and answers once the decoder has, which takes a few seconds for a read. The DCC error codes come back in plain words: no decoder answered, the decoder did not confirm, short circuit, no programming track.
Programming on the main reads and writes a CV through space 0xF8 of the train's node, which the command station turns into a POM packet for that address. A read waits for the decoder's answer over RailCom, so it needs a command station that hears RailCom and RailCom on in the decoder; one that cannot read on the main answers "not implemented", and Interlock says so.
Decoder settings covers changing settings by name from the decoder's definition rather than by CV number.
Without hardware
go run ./cmd/simnode -cdi cs -id 0A.00.00.00.00.43 simulates a command station: it creates train nodes when asked, drives them, and has a decoder with address 1234 on its programming track (-address changes it). Run it next to the simulated outpost to see a train trigger an automation.