# 山猫 S10 遥控示例

基于《山猫S10 软件开发指南》和 DeepRoboticsLab 2.5.4 的连接实测，提供协议实现与演示：

| 文件 | 说明 |
|---|---|
| `s10_robot.py` | 遥控通信模块（标准库，无第三方依赖） |
| `demo_stand_rotate_lie.py` | 演示：起立 → 原地旋转 → 停止 → 趴下恢复 |
| `status_probe.py` | **只读**状态订阅：只发心跳，不下发任何控制指令 |
| `tests/test_protocol.py` | 协议层单元测试 |
| `tests/fake_robot.py` | 本地假机器人（TLS + 协议仿真），用于无真机联调 |
| `山猫S10-遥控指令.md` | 指令整理文档 |

## 环境

```bash
uv venv .venv
uv run python -m unittest discover -s tests -v   # 17 项测试
```

证书默认按顺序查找：`--certs` → `$S10_CERTS` → `./certs` →
`~/.zcode/workspace/draft-183385f3-.../backup/certs`。目录内需要
`client_chain.crt`、`client.key`、`root_ca.crt`。

## 只读观察真机

```bash
uv run python status_probe.py --host 10.21.33.103 --seconds 10
```

只发送心跳（≥1Hz）以开启状态上报，不会切换模式、站立或发轴指令。

## 跑动作演示

```bash
uv run python demo_stand_rotate_lie.py --seconds 5 --yaw 0.3
```

参数：`--yaw` 偏航比例 [-1,1]（正值逆时针）、`--seconds` 旋转时长、
`--rate` 轴指令频率（默认 10Hz）。任何异常、Ctrl-C 或超时都会先发全 0
停止，若仍在站立/RL 状态则自动趴下，最后关闭连接。

## 无真机联调

```bash
uv run python tests/fake_robot.py --port 30003 --once
# 另一个终端
uv run python demo_stand_rotate_lie.py --host 127.0.0.1 --seconds 3
```

假机器人会模拟：心跳后 5Hz 上报、站立后自动进入 RL 控制（17）、
趴下（4）、步态/模式更新，轴指令只记录不回包。

## 模块用法

```python
from s10_robot import S10Client, MotionState, Gait, Mode

with S10Client(host="10.21.33.103") as robot:   # 证书用默认路径
    robot.set_mode(Mode.NORMAL)
    robot.stand()
    robot.wait_motion_state({MotionState.RL}, timeout=20)
    robot.set_gait(Gait.BASIC)

    for _ in range(50):        # 10Hz 持续 5 秒
        robot.move(yaw=0.3)
        time.sleep(0.1)
    robot.stop()

    robot.lie_down()
    robot.wait_motion_state({MotionState.LYING, MotionState.DEFAULT}, timeout=20)
```

主要方法：`heartbeat` / `set_mode` / `set_motion_state`(`stand`/`lie_down`/`damp`) /
`set_gait` / `move`（轴指令）/ `drive_velocity`（速度指令）/ `stop` /
`set_led` / `charge` / `sdk_mode` / `sleep_mode`；状态读取 `basic_status`、
`motion_status`、`motor_status`、`active_errors` 和 `wait_basic` /
`wait_motion_state`。

## 注意

- 轴指令、速度指令**不返回响应帧**，只能通过状态上报确认；轴指令要求 2 秒内来自同一客户端，所以要在同一连接里循环下发。
- 心跳中断 2 秒机器人就停止上报，需要重连。
- 证书客户端有效期到 2027-04-03，过期需重新获取。
- 脚本默认不严格校验服务端证书链（根 CA 缺 keyUsage，Python 3.13+ 严格模式会拒绝），需要时加 `--verify`。
- 标准库不支持 DTLS，30004/UDP 需要额外依赖（如 python-mbedtls）；30003/TCP 与之等价。