OpenRig 这个项目，是我在专注具身智能数据采集时折腾出来的一个开源工具链。说白了，它是一套用低成本传感器和 3D 打印件搭起来的机械臂遥操作与操作数据采集台。最近这一两年大家都在喂机器人学“模仿学习”，但真正卡住进度的往往不是网络结构，也不是显卡，而是没有稳定、可控、低成本的采集方案。现成的遥操作设备要么是六位数起步的商业力反馈台，要么是实验室里维护成本极高的定制系统，个人开发者根本没法抄作业。OpenRig 的初衷就是把这套流程打通：主端是一套轻量穿戴式感应骨架，从端是你手头已有的六轴机械臂，人负责做动作，机械臂负责复现，同时把每一帧关节角、姿态、力信息和对应视频全部记录下来，直接喂给 ACT、Diffusion Policy 这类算法。适合两种人：手里已经有一台机械臂、但不想花大钱做数据采集的工程师，以及想把遥操作从“看视频意会”变成“真机数据驱动”的学生和极客。这篇文章我把方案选型、传感器原理、硬件装配、通信协议、上位机处理到踩坑排查的完整过程都写出来，基本是拿钱和时间换来的经验。
1. 项目定位与方案思路拆解
1.1 为什么非要做主从遥操作，而不是直接用视觉捕捉
做机器人操作数据采集，最直接的想法是买一套光学动捕。Vicon 这类设备精度确实高，但价格劝退，而且使用环境要求苛刻，标记点一旦被手臂遮挡，数据就断。普通 RGB 相机做 3D 姿态估计倒是便宜，可用在精细操作场景里，手腕旋转零点几度就是抓取成败的差别，视觉误差很难压下去。更麻烦的是，我们需要的数据是“机械臂关节角”，不是“人类骨骼关键点”。相机给出的坐标还得再过一层逆向运动学，误差越传越大。
OpenRig 换了一条思路：直接让人承担主端结构。把编码器、惯性测量单元放在人的手臂外侧，关节转多大角度、手臂什么姿态，传感器直接读数。这个“穿戴式主端”本质上是一台人体关节角度测量仪，输出的是与机械臂关节一一对应的角度序列。从端机械臂把这些角度当成目标位置去执行，人和机器人之间就形成了主从关系。这样做的好处很直接：数据里没有反向运动学求解误差，关节角就是机器人控制指令，拿来即用。
当然，主从方案也有代价，比如人胳膊的关节轴和机械臂的关节轴不一定完全对应，需要做坐标映射和行程标定。这部分后面详细说。
1.2 方案选型：为什么是“便宜传感器 + 3D 打印 + 自研协议”
OpenRig 在设计时给自己定了三个硬约束。第一个是单套硬件成本压进 2000 元人民币以内，这就要求传感器尽量用几十块钱的工业级芯片，能用磁编码器就不用谐波减速器上的昂贵角度编码器，能用 IMU 就不用旋转激光雷达。第二个是必须跨机械臂平台，主端采集到的是标准关节角，不绑定某一家的 SDK，只要从端机械臂能接收位置指令，就能跑起来。第三个是代码要足够透明，通信帧格式、滤波算法、映射表全部开源，开发者拿到源码后可以改成适合自己的结构。
最后确定的硬件方案是：关节处使用 AS5600 这类 12-bit 磁编码器，测量绝对角度，零位不丢；肢体段使用九轴 IMU 做姿态融合，采集手的倾斜、俯仰和横滚；手指部分用线性电位器或者弯曲传感器，测握持开合程度。主控平台用 ESP32 或者 STM32，数据通过串口或者 USB 虚拟串口发到宿主机。结构件全部用 PLA 或者 PETG 3D 打印，成本低，坏了重打一个就行。
这个组合方案最妙的一点是它同时利用了磁编码器的“重复性好、抗干扰”和 IMU 的“无基准安装自由”。肩部和肘部需要精确的相对角度，用编码器；手腕到指尖需要感知空间姿态变化，用 IMU；两者互补，数据质量接近工业动捕，成本却差了两个数量级。
1.3 系统整体架构分层
OpenRig 从底到顶一共四层，每层之间用简单明确的接口隔开，这样几个人协作开发也不会打架。
硬件层包括主端穿戴骨架、传感器模块、主控板、电池和从端机械臂。主端骨架我做成模块化的：上臂、前臂、手背板三段，每段有独立的支架和传感器座，中间用万向节连接，方便不同臂长的人群调整。
数据采集层跑在单片机上，任务包括按固定频率扫描所有传感器、对原始信号做简单滤波、拼接数据帧并加上时间戳，然后通过串口或者蓝牙把帧推出去。这个层最关键的是稳定性，我把它做成固定 100Hz 采样，每帧 40 字节左右，预留扩展位。
上位机驱动层负责收帧、校验、把字节流还原成关节角度，然后做坐标变换和限位保护，最后发布成标准 ROS 2 topic 或者直接写入自定义的数据文件。因为很多训练框架不接 ROS，所以 OpenRig 也提供了一份纯 Python 的数据采集接口，只依赖 numpy 和 pyserial，尽量降低使用门槛。
应用层才是最吸引人的部分：用户随便用一套熟悉的模仿学习算法，加载 OpenRig 采集的 HDF5 文件，不用改格式直接训练。为了演示，我额外写了一个重放工具，可以把已经录制的动作序列重新发给机械臂，检查动作轨迹是否顺滑。
2. 硬件与核心细节：传感器、映射与数据流
2.1 关节角度的获取原理：编码器、IMU 和互补滤波
先说磁编码器。AS5600 内部是一个磁旋转角度传感器，它上面贴一个直径 6 毫米的径向充磁磁铁，当关节轴旋转时，磁场角度变化，芯片直接输出 0 到 360 度的绝对角度。分辨率 12-bit，也就是一整圈有 4096 个细分，对于大多数遥操作场景已经足够。它的优势是可以做成非接触式，不用担心机械磨损，装配时只要保证磁铁中心和芯片中心对齐就行，大约两三毫米误差也能接受。
IMU 部分我选的是带三轴加速度计、三轴陀螺仪、三轴磁力计的模块，比如 MPU9250 或者 BMI270。加速度计能测到重力方向，所以可以推算静置时的绝对角度；陀螺仪能测到角速度，积分后也能得到角度，但会有漂移。单独用任何一路都不可靠，必须做融合。我的做法是最简单的互补滤波。
假设 pitch 轴上一次的角度是 angle_prev，陀螺仪测到的角速度是 gyro，加速度计计算出的角度是 acc_angle，采样时间为 dt，滤波系数为 alpha，那融合后的角度就是：
angle = alpha * (angle_prev + gyro * dt) + (1 - alpha) * acc_angle
alpha 的计算方式通常取 alpha = tau / (tau + dt)，tau 是滤波器的时间常数，我一般取 0.1 到 0.5 秒。dt 是 0.01 秒时，tau 取 0.1 秒，alpha 大约为 0.909。这个值意味着信任陀螺仪的短期积分多一点，信任加速度计的长周期稳定性多一点。反应速度会稍微慢一点点，但角度曲线很干净。实现的时候要注意，角度差要转成 -180 到 180 之间，否则会造成跳变。
2.2 主端到从端的映射方式：直接角度映射与限位保护
OpenRig 主端输出的是一组人体关节绝对角度。从端机械臂需要的是它自己的关节目标角度。如果主端机械结构和从端机械臂拥有完全一致的关节轴顺序，那可以做一个最简单的 1:1 映射。比如肘关节弯曲 60 度，从端机械臂肘关节也转到 60 度。这种方案最直观、最容易调试。
不过实际搭建时，很难保证人的肩关节轴和机械臂的肩关节轴完全重合。人的肩部是球窝关节，有三自由度，机械臂肩部通常是一个横滚加一个俯仰，另有肘部俯仰、腕部横滚等。我的处理方式是做一个“关节角色表”：在装配时把主端每个传感器通道对应到从端的哪个关节，逐个确认旋转正方向，并记录零位偏移。
有了角色表之后，数据在进控制器之前还要做两件事。第一是行程映射。人的关节活动范围通常比机械臂大，例如人肘部可以弯曲到 145 度，有些机械臂只有 120 度，如果直接发目标值，机械臂会撞限位报错。所以我在驱动层加了一个 clmap 函数，把目标角度限制在机械臂官方软件限位内，同时留出 2 到 3 度安全余量。第二是平滑处理。人手快停时角度会有轻微抖动，直接发给伺服电动机会造成末端震颤，我给每个通道加了一阶低通滤波器，时间常数大概 50 毫秒，效果立竿见影。
2.3 数据采集链路：同步时间戳、视频和关节数据
做模仿学习的都知道，只有关节角数据不够，视觉信息不能少。OpenRig 的数据采集链路需要同时记录三路信息：主端关节角、从端执行后的实际关节角、以及一到两台相机的画面。
最理想的采集频率是 50 到 100 赫兹，视频一般 30 帧。高频数据与低频视频之间必须对齐，否则算法训练时状态和动作会错位。我的做法是在宿主机上维护一个统一单调时钟。串口数据到达后，立刻用主机当前时间打一个时间戳，这条时间戳不从单片机走，因为单片机的晶振和主机时钟会漂移。摄像头帧回调同样打上主机时间。保存数据时，我把关节数据和图像帧通过时间戳排序，离线再做一次插值对齐。
存储格式我用 HDF5，一个 episode 一个 group。里面存了 qpos_main、qpos_from、actions、timestamp 和 image 数据集。dataset 的组织方式决定了后面调算法时的读取效率，我建议提前留好扩展字段，比如力传感器数据，否则后面重新录一批数据会很痛苦。
2.4 零位标定与机械装配细节
第一个坑就是零位标定。传感器安装位置不可能和关节轴线完美重合，人穿上装置后也不可能完全直立。所以每次开始工作前，必须做一次“归零”：让用户自然站立，手臂垂在身侧，然后让程序记录当前所有通道的角度，作为零位偏移。后续所有数据都先减掉这个偏移，形成相对角度。
机械装配上，有两点直接决定数据质量。第一是关节支架刚性。如果上臂支架是软塑料，人在挥臂时支架自身会弯折，传感器读到的是“架子变形的角度”而不是关节角度。我会在受力方向加碳纤维管支撑，或者把打印件壁厚加到百分之四十以上。第二是线缆管理。主端上每个关节都有传感器线，手臂旋转时线缆会跟着扭，一旦反复拉扯，容易造成信号瞬断。解决办法是在每个关节旁边留一个过线环，让线从旋转中心附近穿过，减少线缆弯折半径，有条件的话可以用微型滑环。
3. 从固件到上位机：实操搭建与端到端采集
3.1 硬件清单和成本控表
我给出自己在用的配置，不代表最优，但代表一个完全可以复现的平衡点。主端一共用了五个磁编码器、两个九轴 IMU、一个线性电位器、一块 ESP32 开发板、一块定制转接 PCB 和若干 3D 打印结构件。磁编码器模块大概每个 20 到 40 元，IMU 模块 35 到 70 元，ESP32 开发板 40 元左右，加上打印材料和线材，整套主端成本不到 700 元。从端是用户自己的机械臂，OpenRig 不负责机械臂本体。
每个关节的传感器接线我先汇总到一个传感器汇流排上，再连到主控板。电源用 5V USB 充电宝供电，但要注意不同传感器模块的供电电压范围。AS5600 支持 3.3 到 5V，IMU 最好统一用 3.3V，我的 PCB 上加了电平转换和稳压，避免烧芯片。
从端机械臂的指令接口各家不同，但 OpenRig 上位机只负责输出“目标关节角数组”，对接时写一个几十行的 adapter 函数即可。如果你的机械臂支持 Modbus、TCP 或者 ROS 2，都可以直接接。
3.2 通信协议设计：一帧 40 字节怎么定义
主端和上位机之间的通信是最容易出问题的地方。我一开始用 JSON 文本，调试方便，但数据量一大就出现粘包、解析错误，后来干脆换成二进制帧格式。每帧结构如下：帧头 0xAA 0x55，1 字节数据长度，1 字节命令字，随后是数据负载，最后 1 字节 CRC 校验。负载里面依次放入每个通道的 16 位角度值，单位是 0.01 度。比如五个编码器和两个 IMU 换算出来的姿态角共需要 7 个通道，也就是 14 字节，再加一个手指电位器 2 字节，负载长度 16 字节。
单片机上发送代码的核心就是维护一个发送周期。可以用定时器中断，保证 10 毫秒发一次。用 ESP32 的话，我建议用双核中的一个核专门跑通信任务，另一个核跑传感器扫描。实际测试时，在 115200 波特率下，40 字节一帧大约需要 3.5 毫秒，足够满足 100Hz 发送要求。如果波特率提到 921600，时间能压到 0.5 毫秒以下，支持更高频率。
下面给一个简单的数据帧打包伪代码：
void packFrame(uint16_t *channels, uint8_t len, uint8_t *buf) { buf[0] = 0xAA; buf[1] = 0x55; buf[2] = 2 + len * 2; // len includes command + payload buf[3] = 0x01; // cmd: angle publish for (int i = 0; i < len; i++) { buf[4 + i * 2] = channels[i] >> 8; buf[5 + i * 2] = channels[i] & 0xFF; } uint8_t crc = 0; for (int i = 0; i < 4 + len * 2; i++) { crc ^= buf[i]; } buf[4 + len * 2] = crc; }注意代码里我故意把 length 字段定义成了包括命令字和负载的长度，上位机解析时严格依据这个值。CRC 用最简单的异或校验，够用，但不抗多字节连续错误，如果你需要更稳，可以换 CRC16。
3.3 上位机解析与滤波：从字节流到平滑关节角
上位机我写了一个名为 OpenRigReceiver 的 Python 类。它启动后不断从串口读字节，放入环形缓冲区，然后查找帧头，解析帧长，校验 CRC，再取数据。一旦拿到一组完整关节角，就做零位修正、低通滤波、限位保护，最后对外提供 get_latest_pose() 接口。
这里有一个很关键的点：不要在串口回调里直接做滤波，因为回调频率不稳定，滤波系数依赖 dt，用不准的 dt 会让曲线失真。我的做法是回调里只负责把帧放入队列，主线程以固定 500Hz 的循环时间取数据并计算滤波间隔，这样时间步长是可控的。
import serial, struct, time, threading class OpenRigReceiver: def __init__(self, port="/dev/ttyUSB0", baud=115200): self.ser = serial.Serial(port, baud, timeout=0.05) self.raw = bytearray() self.lock = threading.Lock() self.latest_pose = None def read_loop(self): while True: data = self.ser.read(128) self.raw.extend(data) self._parse_frames() def _parse_frames(self): while len(self.raw) >= 4: if self.raw[0] != 0xAA or self.raw[1] != 0x55: self.raw.pop(0) continue length = self.raw[2] if len(self.raw) < 3 + length: return frame = self.raw[:3 + length] self.raw = self.raw[3 + length:] self._handle_frame(frame) def _handle_frame(self, frame): raw_channels = [] for i in range(0, len(frame[4:-1]), 2): val = struct.unpack(">H", frame[4+i:6+i])[0] raw_channels.append(val / 100.0 - 180.0) with self.lock: self.latest_pose = raw_channels这是精简版本，实际项目里还要加上断帧超时、线程退出和日志。关键是让“解析串口”和“上层业务”解耦，否则后面接相机、接机械臂时会手忙脚乱。
3.4 端到端采集流程：从穿设备到保存 episode
第一步，固定从端机械臂和相机。相机角度要能同时看到操作台和机械臂末端，我一般用一个 70 度视角的广角相机，放在主操作区上方 60 厘米处。
第二步，给主端上电，运行 OpenRigReceiver，执行零位标定。此时人穿戴上主端并保持自然直立，程序把当前角度存入配置文件。这个动作每次采集前都要做，可以写成脚本一键完成。
第三步，控制从端机械臂回到复位姿态。复位姿态最好和主端标定姿态尽量相似，这样从端启动的时候不会因为角度差过大产生猛冲。
第四步，开始录制。程序同时启动三个线程：串口采集线程、相机采集线程、安全监控线程。安全监控线程每秒检查一次所有关节目标值是否越界，如果越界就强制把目标值拉回限位并发出告警。
第五步，用户做出演示动作。主端的角度实时映射到从端，机械臂跟随运动。这一步骤要特别注意速度，主端动多快，从端跟随就有多快。如果机械臂最大速度跟不上，它会一直在追赶误差，数据里就会记录到“实际关节角”和“目标关节角”的偏差，这个偏差对模仿学习来说反而是额外的有用信息，但你必须作为独立字段记录下来。
第六步，动作结束后停止录制，把 HDF5 文件和相机视频打包。然后运行一段重放脚本，让机械臂自动复现刚才的动作。如果复现轨迹和录制时的轨迹高度一致，说明整个链路的数据是干净的，可以开工训练了。
4. 高频坑点与排查技巧实录
4.1 从端机械臂一直高频抖动
最让人恼火的问题就是机械臂接收到角度后，即使在静止状态也抖个不停。我遇到的情况分三种。第一种是主端电位器或者 IMU 输出的原始噪声太大。用手转到一个角度不动，串口监视器里数据上下跳了正负 0.5 度，机械臂当然会抖。解决方法是先在上位机做 5 点平均或者一阶低通。第二种是主端和上位机通信频率不稳定，导致时间戳间隔忽大忽小，滤波器输出的角度出现毛刺。这种情况需要把解析和业务线程分开，确保滤波循环是定频的。第三种是从端控制器的速度环和位置环增益太高，机械臂自身对微小误差过度响应。这种只能在机械臂控制器里调参数，不是 OpenRig 的问题。
我在 OpenRig 里默认加了一阶低通滤波，截止频率大约 10 赫兹。这样人手正常的动作速度完全不受影响，而 200 赫兹以上的电气噪声会被压掉。如果你的动作需要很快，可以把截止频率调到 20 赫兹，但副作用是快速停止时会有一点点过冲。
4.2 角度出现瞬间跳变，从端猛甩一下
这个问题的根源大多数是角度表示方式出了问题。IMU 输出的欧拉角，在接近 90 度俯仰角附近会发生万向锁，两个轴的角度出现奇异，数值会从接近 180 度直接跳到负 180 度。虽然角度数值对，但在传输时没有做连续性处理，上位机把这些跳变当成真实角度发给机械臂，机械臂就会猛甩。
处理方式有两个。最简单的办法是避免使用欧拉角。IMU 的输出改为四元数，上位机再通过方向向量计算相对角度差，这样不存在 180 度跳变问题。第二种方法是在发送端使用 unwrap 函数，让角度连续累加，不取模到 360 度。我比较推荐四元数路线，不仅解决跳变，还方便后面做姿态插值。
4.3 主端动了，从端方向反了或者轴对不上
这个问题在第一次装配时几乎必现。人的手臂内旋，机械臂却外翻，感觉像是穿越了一样。原因就是坐标系定义不一致。我在设计时确定了主端每个传感器的 Z 轴必须指向关节旋转轴，并规定逆时针为正。从端机械臂通常使用笛卡尔坐标系，关节正方向在各家说明书里可能不一致。
排查的时候不要直接试动作，写一个小脚本，让主端每次只驱动一个轴，例如只抬肘关节 10 度，观察从端哪个关节动了、方向是正是反。把这个测试结果记成一张映射表，在代码里修正。我在 OpenRig 里内置了一个“方向配置文件”，每个通道都能单独设置正负和轴偏移，这个配置文件比硬编码可靠得多。
4.4 相机数据和关节数据对不上，训练效果很差
出现这种问题后，最典型的现象是训练出来的策略看画面觉得手已经碰到物体了，但关节角数据还是几帧之前的状态。主要原因是视频帧时间戳和关节角度时间戳来自不同的时钟源，在长时间采集后，累计走时误差会越来越大。
我的解决方案是：所有时间戳统一使用宿主机单调时钟。视频回调里，OpenCV 的 cap.read() 返回后立刻用 time.time_ns() 打戳。串口帧到达后也在收到帧头时立刻打上宿主机时间戳。离线保存时，再根据时间戳做最近邻插值。另外，为了验证同步效果，我会录一段“拿着主端快速上下晃 10 次”的标定视频，离线检查视频中最下方位置对应的时间戳和关节角最低点是否一致。误差在 30 毫秒以内就可以接受。
4.5 从端机械臂过流报警或者失控
这个场景通常是碰上了主从结构行程不匹配。人感觉手臂只转了一点点，但从端关节已经达到物理限位，机械臂还在拼命运转。OpenRig 的限位保护只在软件层做，如果上位机卡顿，软件限位会失效，机械臂本体就成了最后防线。
我习惯在三个层面同时设防。第一层是上位机 clamp 目标角度。第二层是在机械臂 SDK 里设置速度上限和加速度上限，让机器不会突然暴力动作。第三层是接一个硬件急停开关，一组常闭触点串联到机械臂的使能信号和主端电源，手拍下去，全系统立刻失能。这个不是可选配件，是必配。
5. 后续可以怎么玩：扩展方向与个人经验
5.1 不只是数据采集：低成本遥操作演示
OpenRig 做出来之后，我发现它的价值不只是训练数据。前几天我把它接到一台远程机械臂上，主端放在办公室，从端放在另一个房间，通过局域网传输角度帧，延迟大约 70 毫秒。隔着墙操作机械臂抓取、码放小方块，体验已经很接近商用遥操作台。如果再叠加一个简单的末端摄像头，就能实现“第一视角远程操控”，在危险环境演示、教育展示里都能用得上。
不过延迟问题要理性看待。局域网 70 毫秒里大约有 30 毫秒是主端采样周期带来的，20 毫秒是网络传输，剩下是机械臂自身响应。跨公网的话延迟会飙到 200 毫秒以上，操作手感会变肉，建议只做数据采集，不做实时遥操作。
5.2 扩展双手和手指自由度
当前版本主端只覆盖单臂和简单的手掌开合，但实际操作任务，比如炒菜、拆快递，需要双手协同和精细手指动作。OpenRig 的通信协议里预留了扩展字节，我可以再加一块从端主控采集另一只手的数据，用同一个上位机合并成多臂数据流。手指部分如果想做得更好，可以用力传感器代替电位器，记录抓握力，这对于模仿学习中的力控策略很有价值。
不过要提醒一点，不要一开始就追求复杂。先把单臂数据流做稳定、格式做统一，再扩展多手，否则调试问题会成倍增加。我从 7 个通道扩到 15 个通道时，光是传感器校准和线缆整理就花了一个星期。
5.3 以自述方式把坑都写在文档里
开源项目最怕的不是代码烂，而是文档里全是空白。我在整理 OpenRig 时，会把每次踩坑都记录成“问题现象、排查步骤、最终原因、解决方案”四段式。这个习惯源于一次调试：从端机械臂夜里突然自动转动，查了一晚都不是程序问题，最后才发现是有人碰到了桌面上的鼠标，把串口调试窗口的输入焦点切走了，导致上位机线程卡住。这种奇葩问题如果没有文档记录，第二次遇到还是会想很久。
所以我的经验是，项目的文档目录下建一个 troubleshooting.md，按问题类别整理。发布的时候别人照着文档，能在十分钟内定位到自己的问题在第几类。这不复杂，但真的会让项目从“自己用”变成“大家能用的开源项目”。
回到 OpenRig 本身，我最大的体会是：廉价硬件不是做不出好数据的关键，错误的时间同步、不明确的坐标系、没有限位保护的软件层，才是导致项目翻车的三座大山。只要这三样处理干净，几百块钱的设备一样能采出训练级的数据。最后分享一个小技巧：每次录制前，在主端手腕处贴一个反光标记点，旁边放一个普通摄像头做 2D 视觉轨迹记录。这样即使 IMU 漂移或编码器丢失，你也有一路视觉数据可以回头校验和补帧。这个低成本的“冗余轨道”，在关键时刻救过我很多次。
