set_direction
Sets a locomotive's direction (forward/reverse) via its DCC address. For smooth operation, stop the loco before changing direction.
Instructions
Set a locomotive's direction of travel: "forward" or "reverse".
Args: address: The locomotive's DCC address. Acquires the throttle automatically if this session doesn't already hold it. direction: Must be exactly "forward" or "reverse" (case- insensitive). "forward"/"reverse" here mean the loco's own notion of front/back as wired in its decoder — not compass direction or "toward/away from the operator" — so if a user says "turn it around" or "go the other way", flip whatever the current reported direction is rather than guessing.
Best practice: for a moving loco, bring it to a stop first — DCC decoders generally accept a direction change at speed, but it can cause a rough jolt or be ignored/delayed by the decoder depending on its configuration; this tool does not enforce that, it just forwards the request.
Returns the direction JMRI actually reports back as "forward" or "reverse" (translated from JMRI's own true/false), not "stopped" — direction and speed are independent fields on the same throttle, so set_direction never changes speed and doesn't report one.
Like set_speed/stop/emergency_stop, this is safe to call repeatedly with the same direction: JMRI silently no-ops a redundant "already going this way" request instead of replying, and this tool checks a local direction cache — kept fresh by JMRI's own broadcasts of state changes from ANY client, not just this one — before deciding whether to send anything, so a repeat call (or a direction that was actually last changed by a JMRI panel/PanelPro, not this session) still reports the correct current direction instead of hanging.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | ||
| direction | Yes |