---
name: robot-motion
description: Drive, stop, or read sensors on the physical robot over MQTT. Use for any request to move, turn, or check robot status/battery.
metadata:
  openclaw:
    requires:
      bins: [python3]
---

# Robot Motion

Use the `exec` tool to run `python3 ~/robot/pi/mqtt_bridge.py <command>`. All bounds-checking
(valid directions, speed 0-255, duration cap 5s) happens inside that script — pass through
whatever the user asked for, the script clamps/rejects invalid values itself.

## Drive
python3 ~/robot/pi/mqtt_bridge.py drive <direction> [speed] [duration_ms]

- direction: forward, backward, left, or right — nothing else
- speed: 0-255, default 150. Only go above 200 if explicitly asked for full/max speed
- duration_ms: default 1000, capped at 5000. For longer moves, issue repeated drive calls
  rather than one long duration, so you can react to new sensor readings between them
- This call blocks until the move finishes, so don't queue multiple drives expecting them
  to run concurrently

## Stop
python3 ~/robot/pi/mqtt_bridge.py stop

Call this immediately if asked to stop, or if a sensor reading looks unsafe (e.g. very low
battery) before continuing any plan.

## Read sensors
python3 ~/robot/pi/mqtt_bridge.py sensors

Returns JSON: {"battery_v": <float>, "uptime_ms": <int>}. Check this before starting any
multi-step movement (patrol, "explore", multi-turn plans). If battery_v < 6.5, stop and
report low battery instead of continuing.