set_speed
Set a locomotive's speed as a percentage of its maximum using its DCC address. The tool acquires the throttle if needed and returns the actual speed JMRI reports.
Instructions
Set a locomotive's speed as a percentage of its maximum (0-100%).
Args: address: The locomotive's DCC address. speed_percent: 0-100. Values outside this range are clamped, not rejected. Acquires the throttle automatically if this session doesn't already hold it — no need to call acquire_throttle first for a simple "speed up the 3" style voice command.
Returns the actual speed JMRI reports back, as a percentage — this may differ slightly from what was requested (DCC uses a small number of discrete speed steps, so exact percentages get rounded).
Use stop for a controlled halt (speed 0%) or emergency_stop for a panic stop — don't call set_speed(speed_percent=0) for an emergency, it's a different command to JMRI, not just "speed 0".
A locomotive's speed can be changed by something other than this tool at any time — another JMRI panel, PanelPro, another MCP/voice session controlling the same loco. If the requested speed already matches the current one (whoever set it), JMRI does not send a confirmation and this call returns immediately without writing anything new to the layout — this is expected, not a failure; the reported speed_percent in the response is still accurate because it's read from a cache kept continuously up to date by JMRI's own state broadcasts, not from what this tool last sent.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | ||
| speed_percent | Yes |