acquire_throttle
Gain control of a locomotive by its DCC address and receive its current speed and direction.
Instructions
Acquire control of a locomotive by its DCC address, and report its current state.
Args: address: The locomotive's DCC address. prefix: Optional command station prefix (e.g. "O", "Z", "R") to target when more than one DCC system is connected. Omit to auto-detect from the roster's DccSystem attribute (see list_roster's "dcc_system" field), else JMRI's default station. Pass explicitly only to override auto-detection.
You usually do NOT need to call this explicitly before set_speed/
stop/emergency_stop — those auto-acquire on first use (same
DccSystem auto-detection) for a smoother voice UX. Call this
directly when you want a loco's current speed/direction before
deciding what to do (the reply reports both), or to override the
detected station via an explicit prefix.
Safe to call again on an address already acquired this session — JMRI just re-confirms it, no error or loco reset. Release with release_throttle when done, though not required: JMRI releases every throttle this session holds if the MCP server disconnects.
In exhibition mode with an address allowlist configured, an address outside it is refused here (and by every other throttle tool, routed through this same check) — see enter_exhibition_mode.
Returns "system": full name of the command station actually used, only when non-default — mention it to the user when present.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| prefix | No | ||
| address | Yes |