# Examples

## 目录划分

- `examples/*.py`：Python 原生 PRO API 和 Python 官方兼容 facade 示例；
- `examples/cpp/*.cpp`：独立 C++ SDK 示例，只使用官方 C++ 公共接口。

`fast_lowcmd_cpp` 是 Python 可选加速扩展，不是另一套 C++ 示例入口。

## 高层 (HighLevel) — 通过 sportMode + MQTT, 不需停 Pi 进程

适合: 走/跳/姿态/表演动作. 跟 lowlevel 控制方式互不兼容, 同时只用一种.

### example_highlevel_walk.py — 走一圈

```bash
python examples/example_highlevel_walk.py
```

起立 → walk 模式 → 前进 2 秒 → 转向 2 秒 → 趴下.

### example_highlevel_pose.py — 姿态变化

```bash
python examples/example_highlevel_pose.py
```

stand 模式下做各种姿态: 倾斜/扭转/抬头/低头/蹲下/撑直.

### example_highlevel_dance.py — 跳舞 + 头灯

```bash
python examples/example_highlevel_dance.py
```

dance_1 + 头灯炫彩切换.

## 低层 (LowLevel) — 直接控制 12 电机, 必须停 sportMode

每个示例都假定:
- 你已经从狗上提取了 `blowfish_state.bin` (或用包内置的)
- 已经停掉 Pi 上的 keep_sport_alive + Legged_sport + appTransit
- 狗悬空 (脚架/吊带), 除非明确说不需要

## 只读类 (无风险)

### monitor_state.py — 实时监听状态

```bash
python examples/monitor_state.py --duration 30 --verbose
```

不触发任何电机, 持续发 damping LowCmd 维持 MCU 回包流, 解码后打印 12 关节角 + IMU + 电量.

### monitor_remote.py — 实时监听遥控器

```bash
python examples/monitor_remote.py --duration 60
```

按下按键/拨动摇杆都会实时输出. 包括 L2 模拟值.

## 控制类 (需要狗悬空!)

### example_sin_leg.py — 单腿小幅 sin

```bash
python examples/example_sin_leg.py --amplitude 0.3 --freq 0.5 --duration 10
```

**保守参数**, 适合首次电机控制. sin 中点 = 当前关节角, 不强行移动到指定位置.

### example_position.py — 复刻原版 example_position

```bash
python examples/example_position.py --max-steps 5000
```

跟 free-dog-sdk `example_position(lowlevel).py` **逻辑一模一样**:
- 0..10: 记录 qInit
- 10..400: 插值到 sin_mid_q = [0, 1.2, -2.0]
- 400+: 1Hz sin 摆动 (FR_1 ±0.6, FR_2 ±0.9)

Mac 上实测 480 Hz.

### example_remote_control.py — 摇杆控制 FR 腿

```bash
python examples/example_remote_control.py
```

- 左摇杆 X → 髋外摆
- 左摇杆 Y → 大腿前后
- L2 按下 → 退出

## 安全

所有控制类示例都内置 `apply_safety(cmd, state, power_factor=1)` (10% 力矩限制), 出问题会立即停机. 见 `docs/SAFETY.md`.

## C++ 官方兼容示例

[`cpp/example_official_compatible_position.cpp`](cpp/example_official_compatible_position.cpp)
使用与官方 `unitree_legged_sdk` 相同的头文件、命名空间、`UDP` 和 `Safety` API。构建：

```bash
cmake -S . -B build-cpp -DCMAKE_BUILD_TYPE=Release
cmake --build build-cpp --target example_official_compatible_position
```

该示例会先发送 stop sentinel，收到第一帧有效 `LowState` 后才启用位置目标。PRO 环境
链接本项目库；官方 Go1 环境使用相同源码重新链接官方库。