> ## Documentation Index
> Fetch the complete documentation index at: https://motorbridge.seeedstudio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Python Binding 总览

## 通道兼容说明（PCAN + slcan + CAN-FD + Damiao 串口桥）

* Linux SocketCAN 直接使用网卡名：`can0`、`can1`、`slcan0`。
* 串口类 USB-CAN 需先创建并拉起 `slcan0`：`sudo slcand -o -c -s8 /dev/ttyUSB0 slcan0 && sudo ip link set slcan0 up`。
* CAN-FD 链路可通过 CLI（`--transport socketcanfd`）和 Python SDK（`Controller.from_socketcanfd(...)`）使用，Hexfellow 必须走该链路。
* 仅 Damiao 可选串口桥链路：`--transport dm-serial --serial-port /dev/ttyACM0 --serial-baud 921600`。
* Damiao 串口桥完整接口与命令模板见 `motor_cli/README.zh-CN.md` 第 `3.6` 节（英文见 `motor_cli/README.md`）。
* Linux SocketCAN 下 `--channel` 不要带 `@bitrate`（例如 `can0@1000000` 无效）。
* Windows（PCAN 后端）中，`can0/can1` 映射 `PCAN_USBBUS1/2`，可选 `@bitrate` 后缀。

这是基于 `motor_abi` 的 Python 绑定层。

> English version: [README.md](/source/python/overview)

## README 导航（先看哪个）

如果你是第一次接触这个目录，建议按下面顺序阅读：

1. 本文档 [README.zh-CN.md](/zh/source/python/overview)
   作用：Python binding 总览（安装、API 范围、常用命令）。
2. [examples/READMEzh\_cn.md](/zh/source/python/examples/overview)（中文） / [examples/README.md](/source/python/examples/overview)（英文）
   作用：所有 Python 示例的入口说明（从最简单到高级示例）。
   2.5. [`../motorbridge-docs`](https://github.com/tianrking/motorbridge/tree/main/../motorbridge-docs)
   作用：正式 Mintlify 文档站入口（教程 + API 手册风格）。
3. [get\_started/README.zh-CN.md](/zh/source/python/get-started/overview) / [get\_started/README.md](/source/python/get-started/overview)
   作用：pip 安装用户的快速上手路径（安装 -> 扫描 -> 运行）。
4. [DAMIAO\_PYTHON\_REFERENCE.zh-CN.md](/zh/source/python/damiao-python-reference)
   作用：Damiao Python 接口参考，偏“按接口查参数”。
5. [DAMIAO\_binding.md](/source/python/damiao-binding)
   作用：Damiao 绑定实现说明，偏“原理/实现细节”。
6. [README.md](/source/python/overview)
   作用：英文版总览（给英文协作成员）。

补充：

* 如果你主要想“马上跑起来”，优先看 `examples/READMEzh_cn.md` 的“新手优先（最简单的 2 个示例）”。
* 如果你主要想查 CLI 参数，去 `../../motor_cli/README.zh-CN.md`。

## 范围

* 当前目标包版本：`0.4.1`。
* 版本可通过 `motorbridge.__version__`、`motorbridge.get_version()` 和 `motorbridge-cli -v` 获取。
* ABI 元数据 helper：
  * `motorbridge.abi_version()` 返回当前加载的 ABI 库版本。
  * `motorbridge.abi_capabilities()` 返回当前加载 ABI 的能力 JSON，并转换为 Python `dict`。
* `0.4.1` 新增 ABI 版本/能力发现，并通过 `bindings/api_surface.json` 跟踪 Python/C++ binding parity。
* 高层 API: `Controller`、`Motor`、`Mode`
* CLI: `motorbridge-cli`
* 网关启动命令（pip 安装后进入 PATH）：
  * `motorbridge-gateway -- --bind 127.0.0.1:9002 ...`
* 安全说明：
  * 本地使用建议保持回环地址 `127.0.0.1`。
  * 若绑定到非回环地址（`0.0.0.0` 或网卡 IP），启动前必须设置 `MOTORBRIDGE_WS_TOKEN`。
  * 客户端需在握手中携带 token：`x-motorbridge-token` 或 `Authorization: Bearer ...`。
* macOS 运行说明（仅当出现动态库加载错误时需要）：
  * 通用方式获取网关路径（不写死本机路径）：
    `GW="$(python3 -c "import motorbridge, pathlib; print(pathlib.Path(motorbridge.__file__).resolve().parent/'bin'/'ws_gateway')")"`
  * 使用包内 `lib` 目录设置动态库路径：
    `PKG_DIR="$(python3 -c "import motorbridge, pathlib; print(pathlib.Path(motorbridge.__file__).resolve().parent)")"`
    `DYLD_LIBRARY_PATH="$PKG_DIR/lib:${DYLD_LIBRARY_PATH:-}" "$GW" --bind 127.0.0.1:9002 --vendor damiao --channel can0 --model auto --motor-id 0x01 --feedback-id 0x11 --dt-ms 20`
* Controller 构造入口：
  * `Controller(channel=\"can0\")`（SocketCAN/PCAN 路径）
  * `Controller.from_socketcanfd(channel=\"can0\")`（CAN-FD 路径，Hexfellow 必须使用）
  * `Controller.from_dm_serial(serial_port=\"/dev/ttyACM0\", baud=921600)`（仅 Damiao 串口桥）
* 厂商入口:
  * Damiao: `add_damiao_motor(...)`
  * Hexfellow: `add_hexfellow_motor(...)`
  * MyActuator: `add_myactuator_motor(...)`
  * RobStride: `add_robstride_motor(...)`
  * HighTorque: `add_hightorque_motor(...)`
* 状态查询统一范式：
  * 推荐统一使用 `request_feedback() -> poll_feedback_once() -> get_state()`。
  * RobStride 路径在 ABI 内部已做兼容处理，可按同一范式调用（`robstride_ping()` 仍保留可用）。

## 统一模式映射摘要（顶层协议 -> 厂商原生）

| 顶层统一模式           | Damiao        | RobStride                                                              | Hexfellow         | MyActuator       | HighTorque        |
| ---------------- | ------------- | ---------------------------------------------------------------------- | ----------------- | ---------------- | ----------------- |
| `Mode.MIT`       | 原生 MIT        | 原生 MIT                                                                 | 原生 MIT（模式 5）      | 不支持              | 映射到原生 pos+vel+tqe |
| `Mode.POS_VEL`   | 原生 POS\_VEL   | 映射到原生 Position（`run_mode=1` + `limit_spd(0x7017)` + `loc_ref(0x7016)`） | 原生 POS\_VEL（模式 1） | Position 设定流程    | 映射到原生 pos+vel+tqe |
| `Mode.VEL`       | 原生 VEL        | 原生 Velocity                                                            | 不支持               | 原生 Velocity 设定流程 | 原生速度命令            |
| `Mode.FORCE_POS` | 原生 FORCE\_POS | 不支持                                                                    | 不支持               | 不支持              | 映射到原生 pos+vel+tqe |

说明：

* RobStride 统一高层当前覆盖 `MIT` / `POS_VEL` / `VEL`。
* `TORQUE/CURRENT` 对 RobStride 仍为参数级能力（`robstride_write_param_*`），尚未提供独立统一模式。
* RobStride 支持 `rs-00` 到 `rs-06`；调用 `add_robstride_motor(...)` 时请传真实型号，因为参数读写使用第 4 章通用运行参数表。
* RobStride 建议默认使用 `feedback-id=0xFD`；扫描默认尝试 `0xFD,0xFF,0xFE,0x00,0xAA`。
* RobStride 的 `feedback_id` / `host_id` 不是电机 `device_id`；扫描命中的电机 ID 看 `probe` / `device_id`。

## 快速开始

```python theme={null}
from motorbridge import Controller, Mode

with Controller("can0") as ctrl:
    motor = ctrl.add_damiao_motor(0x01, 0x11, "4340P")
    ctrl.enable_all()
    motor.ensure_mode(Mode.MIT, 1000)
    motor.send_mit(0.0, 0.0, 20.0, 1.0, 0.0)
    motor.request_feedback()
    ctrl.poll_feedback_once()
    print(motor.get_state())
    motor.close()
```

最简单控制示例（统一接口，转到目标角度）：

```python theme={null}
from motorbridge import Controller, Mode

TARGET_POS = 1.0  # 目标角度(rad)

with Controller("can0") as ctrl:
    motor = ctrl.add_damiao_motor(0x01, 0x11, "4340P")  # 可替换为你的 id / model
    ctrl.enable_all()
    motor.ensure_mode(Mode.MIT, 1000)
    motor.send_mit(TARGET_POS, 0.0, 20.0, 1.0, 0.0)
    motor.request_feedback()
    ctrl.poll_feedback_once()
    print("state=", motor.get_state())
    motor.close()
```

```python theme={null}
from motorbridge import Controller, Mode

TARGET_POS = 1.0  # 目标角度(rad)

with Controller("can0") as ctrl:
    motor = ctrl.add_robstride_motor(127, 0xFD, "rs-06")  # 请替换为你的 id / 用于限值/日志的 RS 型号
    ctrl.enable_all()
    motor.ensure_mode(Mode.MIT, 1000)
    motor.send_mit(TARGET_POS, 0.0, 8.0, 0.2, 0.0)
    motor.request_feedback()
    ctrl.poll_feedback_once()
    print("state=", motor.get_state())
    motor.close()
```

Damiao 串口桥示例：

```python theme={null}
from motorbridge import Controller, Mode

TARGET_POS = 0.5  # 目标角度(rad)

with Controller.from_dm_serial("/dev/ttyACM1", 921600) as ctrl:
    motor = ctrl.add_damiao_motor(0x04, 0x14, "4310")
    ctrl.enable_all()
    motor.ensure_mode(Mode.MIT, 1000)
    motor.send_mit(TARGET_POS, 0.0, 20.0, 1.0, 0.0)  # 控制到目标角度
    motor.request_feedback()
    ctrl.poll_feedback_once()
    print(motor.get_state())
    motor.close()
```

RobStride 快速示例:

```python theme={null}
from motorbridge import Controller, Mode

TARGET_POS = 1.0  # 目标角度(rad)

with Controller("can0") as ctrl:
motor = ctrl.add_robstride_motor(127, 0xFD, "rs-06")
    ctrl.enable_all()
    motor.ensure_mode(Mode.MIT, 1000)
    motor.send_mit(TARGET_POS, 0.0, 8.0, 0.2, 0.0)  # 控制到目标角度
    motor.request_feedback()
    ctrl.poll_feedback_once()
    print(motor.get_state())
    motor.close()
```

MyActuator 快速示例:

```python theme={null}
from motorbridge import Controller, Mode

with Controller("can0") as ctrl:
    motor = ctrl.add_myactuator_motor(1, 0x241, "X8")
    ctrl.enable_all()
    motor.ensure_mode(Mode.POS_VEL, 1000)
    motor.send_pos_vel(3.1416, 2.0)  # rad / rad/s
    print(motor.get_state())
    motor.close()
```

Hexfellow 快速示例（仅 CAN-FD）:

```python theme={null}
from motorbridge import Controller, Mode

with Controller.from_socketcanfd("can0") as ctrl:
    motor = ctrl.add_hexfellow_motor(1, 0x00, "hexfellow")
    ctrl.enable_all()
    motor.ensure_mode(Mode.MIT, 1000)      # Hexfellow 仅支持 MIT / POS_VEL
    motor.send_mit(0.8, 1.0, 30.0, 1.0, 0.1)
    print(motor.get_state())
    motor.close()
```

## CLI 示例

Damiao:

```bash theme={null}
motorbridge-cli run \
  --vendor damiao --channel can0 --model 4340P --motor-id 0x01 --feedback-id 0x11 \
  --mode mit --pos 0 --vel 0 --kp 20 --kd 1 --tau 0 --loop 50 --dt-ms 20

motorbridge-cli run \
  --vendor damiao --channel can0 --model 4340P --motor-id 0x01 --feedback-id 0x11 \
  --set-motor-id 0x02 --set-feedback-id 0x12 --store 1 --verify-id 1
```

RobStride:

```bash theme={null}
motorbridge-cli run \
  --vendor robstride --channel can0 --model rs-06 --motor-id 127 \
  --mode ping
```

Python CLI 和 SDK 调用都请使用真实 RobStride 型号（`rs-00` 到 `rs-06`）。系列内控制方法一致；v0.4.1 参数读写继续使用第 4 章通用运行表。

RobStride MIT 与 POS\_VEL 快速验证：

```bash theme={null}
motorbridge-cli run \
  --vendor robstride --channel can0 --model rs-00 \
  --motor-id 2 --feedback-id 0xFD \
  --mode mit --ensure-strict 1 \
  --pos 0.5 --vel 0 --kp 20.0 --kd 0.5 --tau 0 \
  --loop 100 --dt-ms 20

motorbridge-cli run \
  --vendor robstride --channel can0 --model rs-00 \
  --motor-id 2 --feedback-id 0xFD \
  --mode pos-vel \
  --pos 1.5 --vlim 1.0 --loc-kp 5.0 \
  --loop 1 --dt-ms 20
```

RobStride 读参数:

```bash theme={null}
motorbridge-cli robstride-read-param \
  --channel can0 --model rs-06 --motor-id 127 --param-id 0x7019 --type f32

motorbridge-cli run \
  --vendor robstride --channel can0 --model rs-06 --motor-id 127 --feedback-id 0xFD \
  --mode read-param --param-id 0x7019 --param-type f32
```

Damiao 参数读写:

```bash theme={null}
motorbridge-cli damiao-read-param \
  --channel can0 --model 4340P --motor-id 0x01 --feedback-id 0x11 \
  --param-id 21 --type f32

motorbridge-cli damiao-write-param \
  --channel can0 --model 4340P --motor-id 0x01 --feedback-id 0x11 \
  --param-id 8 --type u32 --value 0x01 --verify 1 --store 1
```

统一扫描（所有 vendor）:

```bash theme={null}
motorbridge-cli scan --vendor all --channel can0 --start-id 0x01 --end-id 0xFF
```

RobStride 单独扫描和改 ID：

```bash theme={null}
motorbridge-cli scan \
  --vendor robstride --channel can0 --start-id 1 --end-id 127 \
  --feedback-ids 0xFD,0xFF,0xFE,0x00,0xAA

motorbridge-cli id-set \
  --vendor robstride --channel can0 \
  --motor-id 127 --feedback-id 0xFD \
  --new-motor-id 126 --store 1 --verify 1
```

通过绑定使用 HighTorque：

```python theme={null}
from motorbridge import Controller

with Controller("can0") as ctrl:
    motor = ctrl.add_hightorque_motor(1, 0x01, "hightorque")
    motor.send_mit(3.1416, 0.8, 0.0, 0.0, 0.8)  # kp/kd 参数保留，但协议本身不使用
    motor.request_feedback()
    print(motor.get_state())
    motor.close()
```

通过 Rust CLI 使用 HighTorque：

```bash theme={null}
cargo run -p motor_cli --release -- \
  --vendor hightorque --channel can0 --motor-id 1 --mode read
```

## Windows 实验支持（PCAN-USB）

项目主线仍以 Linux 为主。Windows 支持为实验性能力，当前通过 PEAK PCAN 后端实现。

* 安装 PEAK 驱动与 PCAN-Basic 运行时（`PCANBasic.dll`）。
* Windows 下建议使用 `can0@1000000`（映射到 `PCAN_USBBUS1`，1Mbps）。

建议先用 Rust CLI 做快速验证：

```bash theme={null}
cargo run -p motor_cli --release -- --vendor damiao --channel can0@1000000 --model 4340P --motor-id 0x01 --feedback-id 0x11 --mode scan --start-id 1 --end-id 16
cargo run -p motor_cli --release -- --vendor damiao --channel can0@1000000 --model 4340P --motor-id 0x01 --feedback-id 0x11 --mode pos-vel --pos 3.1416 --vlim 2.0 --loop 1 --dt-ms 20
cargo run -p motor_cli --release -- --vendor damiao --channel can0@1000000 --model 4310 --motor-id 0x07 --feedback-id 0x17 --mode pos-vel --pos 3.1416 --vlim 2.0 --loop 1 --dt-ms 20
```

Windows 本地 wheel 构建：

```bash theme={null}
python -m pip install --user wheel
set MOTORBRIDGE_LIB=%CD%\\target\\release\\motor_abi.dll
set MOTORBRIDGE_WS_GATEWAY_BIN=%CD%\\target\\release\\ws_gateway.exe
python -m pip wheel --no-build-isolation bindings/python -w bindings/python/dist
python -m pip install bindings/python/dist/motorbridge-*.whl
```

## 示例程序

* Damiao wrapper 示例: `examples/python_wrapper_demo.py`
* Hexfellow CAN-FD 示例: `examples/hexfellow_canfd_demo.py`（仅 MIT / POS\_VEL）
* Damiao 维护接口示例: `examples/damiao_maintenance_demo.py`
* Damiao 寄存器读写示例: `examples/damiao_register_rw_demo.py`
* Damiao 串口桥链路示例: `examples/damiao_dm_serial_demo.py`
* RobStride wrapper 示例: `examples/robstride_wrapper_demo.py`
* Damiao 全模式示例: `examples/full_modes_demo.py`
* Damiao 扫描 / 调参 / 位置辅助:
  * `examples/scan_ids_demo.py`
  * `examples/pid_register_tune_demo.py`
  * `examples/pos_ctrl_demo.py`
  * `examples/pos_repl_demo.py`

详细见 [examples/READMEzh\_cn.md](/zh/source/python/examples/overview)（中文）或 [examples/README.md](/source/python/examples/overview)（英文）。

## Damiao 全覆盖状态

Python 示例中 Damiao 用法已覆盖到位：

* 控制模式：`mit` / `pos-vel` / `vel` / `force-pos`
* 传输链路：`Controller(channel)` 与 `Controller.from_dm_serial(...)`
* 维护接口：`clear_error`、`set_zero_position`、`set_can_timeout_ms`、`request_feedback`
  * Damiao 置零规范：先 `disable()`，再 `set_zero_position()`
  * Python 不暴露置零等待参数；核心层内置固定 `20ms` 稳定等待
* 寄存器接口：`get/write f32`、`get/write u32`、`store_parameters`

## 端到端示例命令

```bash theme={null}
# 先构建 ABI
cargo build -p motor_abi --release
export PYTHONPATH=bindings/python/src
export LD_LIBRARY_PATH=$PWD/target/release:${LD_LIBRARY_PATH}

# Damiao wrapper 示例
python3 bindings/python/examples/python_wrapper_demo.py \
  --channel can0 --model 4340P --motor-id 0x01 --feedback-id 0x11 \
  --pos 0 --vel 0 --kp 20 --kd 1 --tau 0 --loop 20 --dt-ms 20

# RobStride wrapper 示例：ping
python3 bindings/python/examples/robstride_wrapper_demo.py \
--channel can0 --model rs-06 --motor-id 127 --feedback-id 0xFD --mode ping

# RobStride wrapper 示例：速度
python3 bindings/python/examples/robstride_wrapper_demo.py \
--channel can0 --model rs-06 --motor-id 127 --feedback-id 0xFD \
  --mode vel --vel 0.3 --loop 40 --dt-ms 50
```

## 说明

* `id-dump` 仍是 Damiao 工作流；`id-set` 支持 Damiao 和 RobStride；`scan` 支持 `damiao|hexfellow|myactuator|robstride|hightorque|all`。
* RobStride `id-set` 中，`--new-motor-id` 修改 `device_id`；`--feedback-id` 仍是上位机侧 host\_id。
* RobStride `motor_id` / `device_id` 会校验为 `1..255`；`feedback_id` / `host_id` 会校验为 `0..255`，避免 `ctypes` 静默截断。
* RobStride 扫描会通过指定 host\_id 的 ABI helper 精确探测每个 `--feedback-ids`；非法 host\_id 会直接报错，不会静默回退。
* MyActuator 在 ABI wrapper 中不支持 `Mode.MIT` 与 `send_force_pos`。
* Hexfellow 在 ABI wrapper 中支持 `MIT` 与 `POS_VEL`，`VEL` / `FORCE_POS` 会返回不支持。
* Damiao 的完整调参参考仍保留在:
  * [DAMIAO\_API.md](/source/python/damiao-api)
  * [DAMIAO\_API.zh-CN.md](/zh/source/python/damiao-api)

## PyPI 自动发布（GitHub Actions）

仓库已新增 `.github/workflows/pypi-publish.yml`。

* Tag 自动发布策略：
  * 推送 `vX.Y.Z` -> 同一套产物同时发布到 TestPyPI 和 PyPI
* 手动发布：在 GitHub Actions 运行 `Python Publish`，可选：
  * `testpypi`（仅发布 TestPyPI）
  * `pypi`（仅发布 PyPI）

### 一次性配置（token 模式）

1. 在 PyPI 创建 API token，并配置仓库 secret：`PYPI_API_TOKEN`。
2. 在 TestPyPI 创建 API token，并配置仓库 secret：`TEST_PYPI_API_TOKEN`。
3. 每次上传必须使用全新版本号（例如 `0.1.6`、`0.1.7`）。