dotbot: document which app acts on wheel velocity and its stop timeout

AI-assisted: Claude Opus 5.5

Author: geonnave

doc/reference/rest.md

@@ -43,7 +43,7 @@ DotBot id; `{application}` is `0` (DotBot) or `1` (SailBot).
 | `GET` | `/controller/map_size` | Controller map size |
 | `GET` | `/controller/background_map` | Background map image (base64) |
 | `PUT` | `/controller/dotbots/{address}/{application}/move_raw` | Drive the motors |
-| `PUT` | `/controller/dotbots/{address}/{application}/wheel_velocity` | Set each wheel's speed: `left_mm_s` / `right_mm_s`, in mm/s, within ±800 |
+| `PUT` | `/controller/dotbots/{address}/{application}/wheel_velocity` | Set each wheel's speed: `left_mm_s` / `right_mm_s`, in mm/s, within ±700. Only the `dotbot-next` firmware app acts on it (other apps ignore it), and it stops the wheels about 500 ms after the last command, so resend faster than 2 Hz |
 | `PUT` | `/controller/dotbots/{address}/{application}/rgb_led` | Set the RGB LED |
 | `PUT` | `/controller/dotbots/{address}/{application}/waypoints` | Set navigation waypoints |
 | `DELETE` | `/controller/dotbots/{address}/positions` | Clear position history |

dotbot/server.py

@@ -159,7 +159,12 @@ def _dotbots_move_raw(address: str, command: DotBotMoveRawCommandModel):
 async def dotbots_wheel_velocity(
     address: str, application: int, command: DotBotWheelVelocityCommandModel
 ):
-    """Hand the DotBot's wheel speeds to its onboard wheel loop."""
+    """Hand the DotBot's wheel speeds to its onboard wheel loop.
+
+    Only the dotbot-next firmware app acts on this command; other apps accept
+    the frame and ignore it. dotbot-next stops the wheels about 500 ms after
+    the last command, so a caller must resend faster than 2 Hz.
+    """
     if address not in api.controller.dotbots:
         raise HTTPException(status_code=404, detail="No matching dotbot found")
     api.controller.send_payload(