Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 18 additions & 6 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,18 @@ on:
description: Include all supported Python versions
type: boolean
default: false
transport_ref:
description: linkerbot-transport branch, tag or commit (empty uses dependency_ref/main)
type: string
default: ""
arm_ref:
description: linkerbot-arm-python-sdk branch, tag or commit (empty uses dependency_ref/main)
type: string
default: ""
ros_ref:
description: linkerbot-hand-ros-sdk branch, tag or commit (empty uses dependency_ref/main)
type: string
default: ""
schedule:
- cron: "17 3 * * 1"

Expand Down Expand Up @@ -90,7 +102,7 @@ jobs:
persist-credentials: false
repository: ${{ env.CI_DEPENDENCY_OWNER }}/linkerbot-transport
path: .ci/transport
ref: ${{ env.CI_DEPENDENCY_REF }}
ref: ${{ inputs.transport_ref || env.CI_DEPENDENCY_REF }}
- uses: actions/setup-python@v7
with:
python-version: ${{ matrix.python }}
Expand Down Expand Up @@ -138,7 +150,7 @@ jobs:
persist-credentials: false
repository: ${{ env.CI_DEPENDENCY_OWNER }}/linkerbot-transport
path: .ci/transport
ref: ${{ env.CI_DEPENDENCY_REF }}
ref: ${{ inputs.transport_ref || env.CI_DEPENDENCY_REF }}
- uses: actions/setup-python@v7
with:
python-version: "3.10"
Expand Down Expand Up @@ -183,13 +195,13 @@ jobs:
persist-credentials: false
repository: ${{ env.CI_DEPENDENCY_OWNER }}/linkerbot-transport
path: .ci/transport
ref: ${{ env.CI_DEPENDENCY_REF }}
ref: ${{ inputs.transport_ref || env.CI_DEPENDENCY_REF }}
- uses: actions/checkout@v7
with:
persist-credentials: false
repository: ${{ env.CI_DEPENDENCY_OWNER }}/linkerbot-arm-python-sdk
path: .ci/arm
ref: ${{ env.CI_DEPENDENCY_REF }}
ref: ${{ inputs.arm_ref || env.CI_DEPENDENCY_REF }}
- name: Pin dependency revisions for all integration jobs
id: revisions
run: |
Expand Down Expand Up @@ -251,13 +263,13 @@ jobs:
persist-credentials: false
repository: ${{ env.CI_DEPENDENCY_OWNER }}/linkerbot-transport
path: .ci/transport
ref: ${{ env.CI_DEPENDENCY_REF }}
ref: ${{ inputs.transport_ref || env.CI_DEPENDENCY_REF }}
- uses: actions/checkout@v7
with:
persist-credentials: false
repository: ${{ env.CI_DEPENDENCY_OWNER }}/linkerbot-hand-ros-sdk
path: .ci/ros
ref: ${{ env.CI_DEPENDENCY_REF }}
ref: ${{ inputs.ros_ref || env.CI_DEPENDENCY_REF }}
- name: Build and test this SDK with latest ROS wrapper
run: bash ".ci/ros/tests/docker/run.sh" "${{ matrix.ros }}" "$PWD/.ci/transport" "$PWD" "$PWD/reports/${{ matrix.ros }}"
- uses: actions/upload-artifact@v7
Expand Down
56 changes: 55 additions & 1 deletion docs/en/src/reference/tutorials/o30.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,11 @@
# O30 Feature Guide

O30 uses CAN FD and has 20 joints. In the examples below, `hand` is an already connected device object.
O30 uses HOP over classic CAN or CAN FD and has 20 joints. CAN FD remains the default. Both wire modes share the same feature API.

## Contents

- [Classic CAN Connection and Test](#classic-can)

- [Joint Order](#joint-order)
- [Device Identity](#identity)
- [Device Capabilities](#capabilities)
Expand All @@ -14,6 +16,58 @@ O30 uses CAN FD and has 20 joints. In the examples below, `hand` is an already c
- [Torque Limits](#torque-limits)
- [Setting Motion Times](#motion-time)

<a id="classic-can"></a>

## Classic CAN Connection and Test

The hand and adapter must already use classic CAN at matching nominal bitrates. This complete read-only example uses a right hand, default request ID `0x001`, and 1 Mbit/s:

```python
from linkerbot_hand import DeviceConfig, HandDevice, TransportKind
from linkerbot_transport.can import CANTransport

hand = HandDevice(
model="O30",
side="right",
transport=CANTransport("can0"),
config=DeviceConfig(hop_transport=TransportKind.CAN, hop_request_id=0x001),
)
try:
hand.open()
print(hand.get_device_info(timeout=2.0))
print(hand.get_angles(timeout=2.0).raw)
finally:
hand.close()
```

`hop_transport` selects SDK framing; it does not reconfigure the device or adapter. Classic CAN requires BRS off. For CAN FD, keep the existing FD transport and omit `hop_transport` or select `TransportKind.CAN_FD`. The default left-hand request ID is `0x002`; use the actual ID for configured devices. The response ID is the request ID `| 0x400`. Firmware without side information remains `PARTIAL` during discovery and requires an explicit side for construction.

Run from the repository root using a Python environment with this SDK source installed:

```bash
# Read identity, 15 state/configuration objects, tactile data, poll, reopen, recover
python examples/o30_classic_can.py --channel can0 --side right

# Write existing settings back, verify configuration readback, move one joint,
# then restore the original target registers
python examples/o30_classic_can.py --channel can0 --side right --write-back --motion-joint 6 --delta 2

# Request 50 Hz angle polling and save measurements and raw frames
python examples/o30_classic_can.py --channel can0 --side right --angles-hz 50 --duration 5 --report o30_can_report.json
```

`--motion-joint` is a zero-based joint index; `--delta` is a nonzero raw angle change from -5 to 5. Motion commands are disabled by default. `--write-back` writes existing configuration values only; it sends no angle command. The motion exercise reads the actual target registers, preserves the other joints' targets, and restores and verifies the original targets on completion or error. The script does not change CAN ID, bitrate, mode, or flash settings, and does not switch back to FD. The default request ID follows `--side`; override it with `--request-id 0x123` when needed.

Classic CAN carries at most five object payload bytes per frame. The SDK splits long reads and 25-slot whole-hand writes into requests of at most five bytes, waiting for each reply before sending the next request. Read results update the complete state only after all ranges arrive. A failure stops subsequent stages; already applied writes cannot be rolled back. CAN FD retains its existing read behavior. Whole-hand writes and returned states are not simultaneous, and acknowledgement does not prove mechanical arrival. Polling rates are requested targets; the report counts observed new samples. `snapshot` holds the latest complete state, rather than a queue.

`--motion-timeout 2` queries current angles for about two seconds after writing the test targets and again after restoring the original targets. The script strictly verifies target registers and records actual angles, deviations, and changes in other joints. Physical behavior may produce a target offset or no observable movement; these observations do not fail SDK validation. `PASS` means communication and target readback passed, without guaranteeing mechanical arrival or accuracy. `--delta` is relative to the original target and does not bound actual displacement. Protocol, communication, or target-readback errors produce `FAIL` and exit code 1. Do not run another query or command producer on the same endpoint during this script.

`NO_SENSOR` is reported as `SKIP`; zero values remain unchanged and do not imply a fault. Some firmware reports the previous interface type after switching, so verify the actual CAN frame flags too. Mode changes that are not saved to flash may revert after a power cycle.

O30 and P7 have been tested sharing a classic CAN bus, with both SDKs in one process and device close/reconnect exercises. Joint polling at 50 Hz still showed occasional query timeouts and stale data. Automatic retries have not been added, and the cause remains undetermined. This establishes basic communication compatibility, without guaranteeing continuous 50 Hz updates without loss.

The remaining examples use an already connected `hand`; call `hand.close()` when finished.

## Joint Order

The SDK reads and sets joint data in the following order.
Expand Down
55 changes: 54 additions & 1 deletion docs/zh/src/reference/tutorials/o30.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,11 @@
# O30 功能文档

O30 使用 CAN FD,包含 20 个关节。以下示例中的 `hand` 为已连接的设备对象。
O30 使用 HOP,支持经典 CAN 和 CAN FD,包含 20 个关节。默认仍为 CAN FD。以下功能在两种传输方式下使用相同的 API。

## 目录

- [经典 CAN 连接与测试](#classic-can)

- [关节顺序](#关节顺序)
- [身份识别](#identity)
- [能力查询](#capabilities)
Expand All @@ -14,6 +16,57 @@ O30 使用 CAN FD,包含 20 个关节。以下示例中的 `hand` 为已连接
- [力矩限幅](#torque-limits)
- [运动时间设置](#motion-time)

<a id="classic-can"></a>

## 经典 CAN 连接与测试

设备和适配器须已配置为经典 CAN,且波特率一致。以下为右手、默认请求 ID `0x001`、1 Mbit/s 的完整只读示例:

```python
from linkerbot_hand import DeviceConfig, HandDevice, TransportKind
from linkerbot_transport.can import CANTransport

hand = HandDevice(
model="O30",
side="right",
transport=CANTransport("can0"),
config=DeviceConfig(hop_transport=TransportKind.CAN, hop_request_id=0x001),
)
try:
hand.open()
print(hand.get_device_info(timeout=2.0))
print(hand.get_angles(timeout=2.0).raw)
finally:
hand.close()
```

`hop_transport` 只选择 SDK 的帧格式,不修改设备模式或主机接口。经典 CAN 禁用 BRS;CAN FD 继续使用原来的 FD transport,并省略 `hop_transport` 或设为 `TransportKind.CAN_FD`。左手默认请求 ID 为 `0x002`,自定义 ID 使用实际值;回复 ID 为请求 ID `| 0x400`。无侧别信息的固件,发现结果保留 `PARTIAL`,需显式指定侧别后构造。

在仓库根目录运行测试脚本(使用已安装本次源码的 Python 环境):

```bash
# 默认只读:身份、15 项状态/配置、触觉、轮询、重新打开和恢复
python examples/o30_classic_can.py --channel can0 --side right

# 回写原有配置并回读;只修改一个关节的原目标,随后恢复原目标
python examples/o30_classic_can.py --channel can0 --side right --write-back --motion-joint 6 --delta 2

# 仅查询,以 50 Hz 请求角度轮询,保存结果及原始帧
python examples/o30_classic_can.py --channel can0 --side right --angles-hz 50 --duration 5 --report o30_can_report.json
```

`--motion-joint` 是从 0 开始的关节索引,`--delta` 是原始角度变化量(非零,-5~5)。默认不发送运动指令;`--write-back` 只回写原有配置,不发送角度指令。运动测试读取真实目标寄存器,保留其他关节原目标,结束或异常时恢复原目标并回读核对。脚本不修改 CAN ID、波特率或模式,不保存 Flash,也不切回 CAN FD。默认请求 ID 随 `--side` 选择;非默认设备用 `--request-id 0x123` 指定。

经典 CAN 每帧最多承载 5 字节对象数据。SDK 将长范围读取和整手 25 槽写入拆成每段最多 5 字节的请求,收到当前段回复后再查询或写入下一段;读取收齐后才更新完整状态。任一段失败就停止,已执行的写入段无法回滚。CAN FD 保持原来的读取方式。整手控制和返回状态不是同一时刻的采样;命令确认也不代表机械到位。轮询频率是请求目标,实际新样本数量以报告为准。`snapshot` 保存最新完整状态,不是数据队列。

`--motion-timeout 2` 在写入测试目标和恢复原目标后分别持续查询当前角度约 2 秒。脚本严格核对目标寄存器,并记录实际角度、偏差和其他关节的变化;物理原因可能导致实际角度与目标不一致,甚至没有可观测变化,这些观测不作为 SDK 失败条件。`PASS` 表示通信及目标回读通过,不保证机械到位或精度。`--delta` 相对于原目标计算,不能用它保证实际位移大小。协议、通信或目标回读错误返回 `FAIL`、退出码 1。运行测试期间不要让其他程序同时对该端点查询或写入。

`NO_SENSOR` 在报告中标记 `SKIP`;零值保留原值,不判为故障。已遇到固件切换后仍回报旧接口类型的情况,应结合实际 CAN 帧标志确认模式。未保存 Flash 的模式切换可能在断电后恢复原设置。

已验证 O30 与 P7 共用经典 CAN 总线并由两个 SDK 同进程通信、关闭重连;50 Hz 联合轮询仍观察到偶发查询超时和数据过期,暂未增加自动重试,也未确定根因。该结果说明基本通信兼容,不保证持续 50 Hz 无丢失。

其余示例使用已连接的 `hand`,结束后调用 `hand.close()`。

## 关节顺序

SDK 按以下顺序读取和设置关节数据。
Expand Down
Loading