单执行器实物接入

本节介绍真实设备的适配方法。先通过上一章的虚拟通信理解数据链路，再根据实际电机、驱动器和协议手册实现设备后端。

1.本节目标与适用范围

先接一个执行器，逐项完成身份、反馈、单位、方向、模式与停机验证，再复制到完整机器人。本章提供设备适配步骤与计算实例。接线、通信报文、使能和停机操作应依据实际设备手册实现，并在对应硬件上逐项确认。

2.示例 1：先填写设备契约

把实际设备手册中的信息整理为：

填写完成以前，可以解析反馈；不要凭通用例子猜测使能或力矩报文。

2.1.Ubuntu 中的串口设备路径与权限

USB 串口设备通常显示为 /dev/ttyUSB0 或 /dev/ttyACM0。连接设备后，先检查实际路径和所属用户组。例如：

ls -l /dev/ttyUSB0
id -nG

将第一条命令中的路径换成实际设备。若设备属于 dialout 组，而当前用户不在该组，可添加用户：

sudo usermod -aG dialout "$USER"

注销并重新登录后，再用 id -nG 检查组成员身份，然后以普通用户运行程序。存在 /dev/serial/by-id/ 时，也可以查看其中的稳定设备链接，减少重新插拔导致编号改变的问题。

上一章的 /tmp/ros2_ctrl_pc 和 /tmp/ros2_ctrl_mcu 是 socat 创建的虚拟终端别名。真实设备需要同时适配路径、协议与关节结构，不能只修改路径就直接沿用模拟下位机程序。

3.示例 2：编码器单位转换

假设设备已经给出的有效分辨率是每电机转 8192 count，减速比 10:1，零点 raw_zero，方向 sign 为 +1 或 -1：

输出轴角度 q = sign * (unwrapped_count - raw_zero) * 2π / (8192 * 10)
输出轴角速度 dq = sign * motor_rpm * 2π / (60 * 10)

这里 8192 指设备协议规定的有效 count/rev。如果手册给的是线数并要求四倍频，要先换算有效分辨率，不能再把已经四倍频的数值乘四。

下面程序只验证换算，不访问硬件，保存为 /tmp/encoder_units.cpp：

#include <cmath>
#include <iostream>
int main()
{
  const double pi = std::acos(-1.0);
  const double count_per_motor_rev = 8192.0;
  const double reduction = 10.0;
  const double sign = 1.0;
  const long long raw_zero = 0;
  const long long unwrapped_count = 40960;
  const double motor_rpm = 60.0;
  const double q = sign * (unwrapped_count - raw_zero) * 2.0 * pi /
    (count_per_motor_rev * reduction);
  const double dq = sign * motor_rpm * 2.0 * pi / (60.0 * reduction);
  std::cout << "q=" << q << " rad, dq=" << dq << " rad/s\n";
}

g++ -std=c++17 /tmp/encoder_units.cpp -o /tmp/encoder_units
/tmp/encoder_units

预期约为 q=3.14159 rad、dq=0.628319 rad/s。这些是假设参数的算术结果，不是对你的设备参数的测量。

3.1.单圈回绕要怎样处理

原始 count 从最大值回到 0 时，先根据回绕规则展开多圈计数，再换算角度。采样间隔必须足够短，或设备必须提供圈数，否则无法仅凭两个单圈读数唯一恢复跨越多圈的运动。

4.示例 3：先运行只读后端

最初的实物 SensorInterface 或只读工具只完成：打开设备、识别设备、解析反馈、检查帧序与时间、换算 SI 单位、上报故障。用手动允许的方式缓慢改变位置，确认符号、尺度和零点。

只读阶段不要启动需要命令接口的控制器。MiniSystem 示例固定两个关节，也不能只把串口路径改成真实设备，就当成单执行器驱动。

5.示例 4：逐项实现真实硬件插件

on_init：验证实际关节数量、接口和参数
on_configure：建立通信，核对设备，取得有效反馈
on_activate：确认模式、故障和使能条件，对齐初始目标
read：取最近有效反馈，转换单位，检测状态与超时
write：限幅与换算，再交给协议发送队列
on_deactivate：执行设备定义的停止/保持/禁能过程
on_cleanup/on_shutdown：确认退出结果并释放资源

真实设备需要异步确认时，应把握手作为显式状态过程处理，不能在实时 write 中无限等应答。使能、清错与停止等离散命令需要协议层可靠执行，不适合只保留“最新目标”的邮箱。

6.验收顺序

先证明反馈可信，再验证模式与初始目标一致，最后在设备允许条件下进行小范围运动。分别记录目标、反馈、时间戳、故障状态和停止结果；比较命令与实际运动，不以 Topic 发布成功作为验收。

本章覆盖设备适配方法与单位换算。完成设备专用实现后，应为实际硬件记录通信参数、协议版本、测试条件和每项验收结果。

---

返回 Humble 总览 · 上一篇：虚拟串口与模拟下位机 · 下一篇：完整机器人与进阶实例