單執行器實物接入

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

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 總覽 · 上一篇：虛擬序列埠與模擬下位機 · 下一篇：完整機器人與進階例項