docs: 添加 HTTP API 与 ROS 话题格式文档，底盘速度环合并左右电机为单一速度环

docs/API.md

@@ -0,0 +1,105 @@
+# HTTP API 数据格式
+
+Base URL: `http://192.168.0.11`
+
+所有 POST 请求 Content-Type 为 `application/json`。
+
+---
+
+## 1. 云台模式切换
+
+```
+POST /api/gimbal/mode/switch
+```
+
+**请求体:**
+
+```json
+{ "mode": "auto" }
+```
+
+`mode` 取值: `"auto"` | `"manual"` | `"debug"`
+
+---
+
+## 2. 底盘模式切换
+
+```
+POST /api/chassis/mode/switch
+```
+
+**请求体:**
+
+```json
+{ "mode": "auto" }
+```
+
+`mode` 取值: `"auto"` | `"manual"` | `"debug"`
+
+---
+
+## 3. 激光控制
+
+```
+POST /api/laser
+```
+
+**请求体:**
+
+```json
+{ "action": "on" }
+```
+
+`action` 取值: `"on"` | `"off"`
+
+---
+
+## 4. 云台 PID 配置
+
+```
+GET  /api/gimbal/pidconfig    (获取)
+POST /api/gimbal/pidconfig    (保存)
+```
+
+**GET 响应 / POST 请求体:**
+
+```json
+{
+  "visual_yaw":   { "kp": 0.0, "ki": 0.0, "kd": 0.0 },
+  "visual_pitch": { "kp": 0.0, "ki": 0.0, "kd": 0.0 },
+  "angle_yaw":    { "kp": 0.0, "ki": 0.0, "kd": 0.0 },
+  "angle_pitch":  { "kp": 0.0, "ki": 0.0, "kd": 0.0 }
+}
+```
+
+| 字段 | 对应 PID 环 |
+|------|------------|
+| `visual_yaw` | 视觉环 Yaw 电机 |
+| `visual_pitch` | 视觉环 Pitch 电机 |
+| `angle_yaw` | 角度环 Yaw 电机 |
+| `angle_pitch` | 角度环 Pitch 电机 |
+
+---
+
+## 5. 底盘 PID 配置
+
+```
+GET  /api/chassis/pidconfig   (获取)
+POST /api/chassis/pidconfig   (保存)
+```
+
+**GET 响应 / POST 请求体:**
+
+```json
+{
+  "speed":    { "kp": 0.0, "ki": 0.0, "kd": 0.0 },
+  "angle":    { "kp": 0.0, "ki": 0.0, "kd": 0.0 },
+  "position": { "kp": 0.0, "ki": 0.0, "kd": 0.0 }
+}
+```
+
+| 字段 | 对应 PID 环 |
+|------|------------|
+| `speed` | 速度环 |
+| `angle` | 角度环 |
+| `position` | 位置环 |

docs/ROS.md

@@ -0,0 +1,55 @@
+# ROS 话题格式
+
+通过 rosbridge WebSocket（`ws://192.168.0.11:9090`）发布，均为单向 `publish`（前端 → ROS），无订阅。
+
+---
+
+## 1. `/cmd_chassis` — 底盘控制
+
+**类型:** `std_msgs/Float32MultiArray`
+
+**格式:**
+
+```json
+{
+  "layout": { "dim": [], "data_offset": 0 },
+  "data": [0.5, 0.0]
+}
+```
+
+`data` 字段:
+
+| 索引 | 含义 | 单位 | 来源常量 |
+|------|------|------|---------|
+| `data[0]` | 线速度 | m/s | `BASE_SPEED` (0.5) |
+| `data[1]` | 角速度（偏航） | 度/秒 | `YAW_VELOCITY` (1.0) |
+
+---
+
+## 2. `/cmd_gimbal` — 云台控制
+
+**类型:** `geometry_msgs/Twist`
+
+**格式:**
+
+```json
+{
+  "linear":  { "x": 0, "y": 0, "z": 0 },
+  "angular": { "x": 0, "y": 10.0, "z": 0 }
+}
+```
+
+`angular` 字段:
+
+| 字段 | 含义 | 单位 | 来源常量 |
+|------|------|------|---------|
+| `angular.y` | 俯仰角速度 (pitch) | 度/秒 | `GIMBAL_PITCH_DEG_S` (10) |
+| `angular.z` | 偏航角速度 (yaw) | 度/秒 | `GIMBAL_YAW_DEG_S` (10) |
+
+`linear` 字段保留填零，云台无平移运动。
+
+---
+
+## 3. 发布频率
+
+发布频率常量 `PUBLISH_RATE = 30` Hz，但在 ManualMode 中实际采用 on-demand 模式：仅当键盘按住、且速度值有变化时才发布。