set_speed_ramped
Ramp a DCC locomotive's speed up or down to a target percentage, with optional direction flip and automatic stop after a hold time.
Instructions
Change a locomotive's speed gradually — a smooth ramp up and/or down.
Args: address: DCC address. Auto-acquires the throttle if needed. speed_percent: Target speed, 0-100%. Legacy shorthand: NEGATIVE toggles direction relative to current facing, ramps to |value|%. Prefer explicit direction for new calls — ignored as a sign once direction is given (only its clamped 0-100 magnitude used then). direction: Optional "forward"/"reverse" (case-insensitive), set atomically with speed_percent, e.g. "avance progressivement à 40%" (loco in reverse) -> speed_percent=40, direction="forward", rampup_seconds=3. Wins over the negative-sign shorthand if both given. rampup_seconds: Seconds to climb to the target if higher (or on a direction flip while moving). 0 = instant. rampdown_seconds: Seconds to descend when lower, on a direction-flip stop-first, and for hold_seconds' auto-stop. 0 = instant. hold_seconds: Hold the target this long, then auto-ramp to a stop before returning — "run forward at 30% for 10s" -> hold_seconds=10. Omit to reach the target and keep going.
Use instead of plain set_speed for "en douceur"/"progressivement" or a duration before stopping. Use emergency_stop for a panic stop — never sent here, even at rampdown_seconds=0.
A SHORT total duration blocks and returns final speed/direction. A LONGER one returns immediately with "status": "started" and keeps running server-side — the loco stops itself automatically, no follow-up call needed. "started" is success, not "finished".
A direction flip while moving ramps to 0 first, flips, then ramps back up.
speed_percent is relative to THIS loco's configured maximum (roster "Throttle Speed Limit") like set_speed.
Returns final speed/direction, or for the background path: {"address", "status": "started", "speed_percent", "direction", "seconds_total"}. Either shape includes "system" (full command-station name) only when non-default.
In exhibition mode, speed_percent/direction are IGNORED and replaced with a fixed, moderate, forward-only speed.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | ||
| direction | No | ||
| hold_seconds | No | ||
| speed_percent | Yes | ||
| rampup_seconds | No | ||
| rampdown_seconds | No |