From 3008203f826be4cc991185bcb48bbf77843e32dd Mon Sep 17 00:00:00 2001 From: cyy_mac Date: Thu, 30 Jul 2026 15:29:30 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 57 ++++++++++++++++++++++++------ docs/ARCHITECTURE.md | 83 +++++++++++++++++++++++++++++++++++++------- examples/README.md | 20 +++++++++++ 3 files changed, 138 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index c739bea..a5de6b9 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,26 @@ Unitree Go1 **PRO** 机型的低层电机控制 Python/C++ SDK。完整逆向 PR ## 快速上手 +### 语言与入口 + +| 使用方式 | 源码位置 | 构建入口 | 用户入口 | +|---|---|---|---| +| Python 原生 PRO API | `go1_pro_sdk/` | `pyproject.toml` | `import go1_pro_sdk` | +| Python 官方兼容 API | `robot_interface.py`、`go1_pro_sdk/compat/` | `pyproject.toml` | `import robot_interface as sdk` | +| Python 可选原生加速 | `fast_lowcmd_cpp/` | `fast_lowcmd_cpp/setup.py` | `FastLowCmdBuilder` | +| C++ 官方兼容 SDK | `include/`、`src/` | `CMakeLists.txt` | `#include ` | + +`fast_lowcmd_cpp` 是供 Python 调用的 CPython 扩展，不是 C++ 用户的公共 SDK。C++ 用户 +只依赖根目录 CMake 生成的 `unitree_legged_sdk` 库以及 `include/unitree_legged_sdk/` +中的公共头文件。两套实现共享同一份 PRO 协议和 Blowfish state，但运行时不互相依赖。 + +Python 开发环境安装： + +```bash +conda activate free_dog_sdk +python -m pip install -e . +``` + ### 官方 Python SDK 兼容接口 需要复用官方 `unitree_legged_sdk` Python 示例时，可以继续使用原来的模块名和 @@ -172,19 +192,36 @@ bash tools/stop_sportmode.sh start ## 包结构 ``` -go1_pro_sdk/ -├── connection/ # MCUClient: 高层 UDP 客户端 -├── codec/ # Blowfish + LowCmd 序列化 + LowState 解析 -├── types/ # MotorCmd, LowState, IMU, BMS, RemoteState 等 -├── safety/ # PositionLimit / PowerProtect / PositionProtect -├── utils/ # CRC, 浮点编解码, 关节常量 -└── _data/ # blowfish_state.bin +go1_pro_sdk/ # Python 原生 PRO SDK +├── connection/ # MCUClient: UDP 客户端 +├── codec/ # Python Blowfish、LowCmd、LowState +├── compat/ # 官方 robot_interface Python facade +├── highlevel/ # sportMode MQTT API +├── safety/ # Python Safety 实现 +├── types/ # Python 数据结构 +├── utils/ # CRC、常量和字段编解码 +└── _data/ # Python wheel 内的 Blowfish state -include/unitree_legged_sdk/ # 官方 C++ 头文件兼容层 -src/ # PRO UDP/Blowfish/Safety 实现 -tests/cpp/ # C++ 契约、抓包和安装消费测试 +robot_interface.py # 官方 Python SDK 同名顶层入口 +pyproject.toml # Python 构建和安装入口 +fast_lowcmd_cpp/ # Python 可选 CPython 加速扩展 + +include/unitree_legged_sdk/ # C++ 公共头文件，路径与官方一致 +src/ # C++ 私有实现，不作为公共头文件安装 +cmake/ # C++ find_package 配置模板 +CMakeLists.txt # C++ 构建、测试和安装入口 + +examples/*.py # Python 示例 +examples/cpp/ # C++ 同源码兼容示例 +tests/*.py # Python、实机抓包和 facade 回归 +tests/cpp/ # C++ 契约与安装消费测试 +data/captures/ # 本机实机抓包，存在时自动参与回归 ``` +Python 和 C++ 的公共 API 不交叉包含：Python 安装由 `pyproject.toml` 管理，不会安装 +C++ 头文件；C++ 安装由 CMake 管理，不会安装 Python 包。两边唯一共享的运行数据是 +`blowfish_state.bin`，安装时分别进入 Python package data 和 C++ data directory。 + ## 文档 - `docs/PROTOCOL.md` — PRO LowCmd/LowState 字节级格式规格 diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 770988e..b131ff6 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,6 +1,23 @@ # 包结构与数据流 -## 模块依赖图 +## 仓库分层 + +本仓库同时提供 Python SDK 和独立 C++ SDK，两者按构建系统和公共入口区分： + +| 层 | Python | C++ | +|---|---|---| +| 公共 API | `go1_pro_sdk/`、`robot_interface.py` | `include/unitree_legged_sdk/` | +| 私有实现 | Python package 子模块 | `src/` | +| 构建入口 | `pyproject.toml` | `CMakeLists.txt` | +| 示例 | `examples/*.py` | `examples/cpp/*.cpp` | +| 测试 | `tests/*.py` | `tests/cpp/` | + +`fast_lowcmd_cpp/` 属于 Python 侧：它生成 CPython extension，用来加速 Python 的命令 +编解码和状态解析。它不提供 C++ 公共头文件，也不应被 C++ 应用直接链接。 + +## Python 架构 + +### 模块依赖图 ``` ┌──────────────────────┐ @@ -26,7 +43,7 @@ └─────────────┘ ``` -## 数据流: 收一帧 → 用户处理 → 发命令 +### 数据流: 收一帧 → 用户处理 → 发命令 ``` UDP 858B 密文 UDP 616B 密文 @@ -64,16 +81,16 @@ └─────────────────────────────────────────────────┘ ``` -## 各包职责 +### 各包职责 -### utils/ +#### utils/ 最底层。纯函数, 无副作用, 无依赖其他模块。 - `common.py`: CRC, float↔hex, tau↔2B, Kp↔2B, Kd↔2B, decode_sn/version - `constants.py`: MCU 地址, 关节命名, 限位, TAU_MAX, DAMPING_POSE -### types/ +#### types/ 数据结构 (dataclass)。依赖 utils, 不依赖 codec/safety/connection。 @@ -84,7 +101,7 @@ - `low_cmd.py`: LowCmd (12 motorCmd + 元数据) - `low_state.py`: LowState (12 motorState + IMU + BMS + remote 等) -### codec/ +#### codec/ 加解密和序列化。依赖 types + utils。 @@ -92,21 +109,21 @@ - `lowcmd_builder.py`: LowCmd → 616B 明文 → 加密后 616B - `lowstate_parser.py`: 解密后 807B → LowState 结构 -### safety/ +#### safety/ 控制保护层。依赖 types + utils。 - `safety.py`: PositionLimit/PowerProtect/PositionProtect 三个保护 + 统一入口 apply_safety -### connection/ +#### connection/ UDP 高层抽象。依赖前面所有。 - `mcu_client.py`: MCUClient (socket + Blowfish + 序列化 + safe_stop) -## 用户三种用法 +### 用户三种用法 -### Level 1: 高层 (推荐) +#### Level 1: 高层 (推荐) ```python from go1_pro_sdk import MCUClient, LowCmd, MotorCmd, MotorMode @@ -120,7 +137,7 @@ with MCUClient() as client: client.safe_stop() ``` -### Level 2: 中层 (自己管 socket, 用编解码) +#### Level 2: 中层 (自己管 socket, 用编解码) ```python from go1_pro_sdk import Blowfish, build_low_cmd_encrypted, parse_low_state, LowCmd @@ -136,7 +153,49 @@ data, _ = sock.recvfrom(2048) state = parse_low_state(bf.decrypt_ecb(data[:856])) ``` -### Level 3: 底层 (诊断/逆向) +#### Level 3: 底层 (诊断/逆向) 直接用 `Blowfish.encrypt_block(b8)` / `Blowfish.decrypt_block(b8)`, 自己处理 8B 块。 适合协议研究或字节级 diff。 + +## C++ 架构 + +```text +应用源码 + #include + │ + ▼ +include/unitree_legged_sdk/ 公共、官方兼容声明 + comm.h / udp.h / safety.h / loop.h / quadruped.h + │ + ▼ +src/ + udp.cpp POSIX UDP、线程安全收发、官方方法适配 + safety.cpp PositionLimit/PowerProtect/PositionProtect + loop.cpp Loop/LoopFunc 调度和 Linux CPU affinity + pro_codec.cpp 616B LowCmd、858B LowState、CRC、Blowfish + quadruped.cpp 版本、长度常量和 InitEnvironment +``` + +`src/pro_codec.h` 是库内部头文件，不安装给用户。C++ 应用只能包含 +`include/unitree_legged_sdk/` 下的头文件，这保证业务源码切换到官方 SDK 时不依赖 PRO +专有声明。PRO 的加密和私有线协议全部封装在 `UDP` 实现内部。 + +CMake 对外提供： + +- 构建树目标：`unitree_legged_sdk`； +- namespaced alias：`unitree_legged_sdk::unitree_legged_sdk`； +- 安装后的 `find_package(unitree_legged_sdk CONFIG REQUIRED)`； +- 安装目录中的公共头文件、静态库、CMake config 和 Blowfish state。 + +## 共享边界 + +Python 与 C++ 没有运行时语言绑定关系，也不会互相调用。它们共享的是协议规格、实机 +抓包回归基准和 Blowfish state。修改协议实现时必须同时运行： + +```bash +conda run -n free_dog_sdk python -m pytest -q tests fast_lowcmd_cpp/test_fast_lowcmd.py +cmake -S . -B build-cpp -DCMAKE_BUILD_TYPE=Release +cmake --build build-cpp +ctest --test-dir build-cpp --output-on-failure +``` diff --git a/examples/README.md b/examples/README.md index 3a699b0..9806b88 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,5 +1,12 @@ # Examples +## 目录划分 + +- `examples/*.py`：Python 原生 PRO API 和 Python 官方兼容 facade 示例； +- `examples/cpp/*.cpp`：独立 C++ SDK 示例，只使用官方 C++ 公共接口。 + +`fast_lowcmd_cpp` 是 Python 可选加速扩展，不是另一套 C++ 示例入口。 + ## 高层 (HighLevel) — 通过 sportMode + MQTT, 不需停 Pi 进程 适合: 走/跳/姿态/表演动作. 跟 lowlevel 控制方式互不兼容, 同时只用一种. @@ -89,3 +96,16 @@ python examples/example_remote_control.py ## 安全 所有控制类示例都内置 `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 环境使用相同源码重新链接官方库。