單執行器實物接入

本節介紹真實設備的適配方法。先通過上一章的虛擬通信理解數據鏈路，再根據實際電機、驅動器和協議手冊實現設備後端。

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 總覽 · 上一篇：虛擬串口與模擬下位機 · 下一篇：完整機械人與進階實例