feat: add head control and joint data decoder

docs/天工3.0本地同构臂遥操迁移部署指南.md

@@ -926,12 +926,15 @@ systemctl --user enable --now tg3-omnisocket-sender.service
 11. 仅在 `[locomotion].enabled=true` 且相应链路断流保护已经验证后：先确认双摇杆回中，
     再把左摇杆小幅向前推出死区，确认下一个 50 Hz 周期立即响应；回中后确认立即零速停止；
 12. 在同一行走前提下，直接把右摇杆小幅横推，确认机器人原地转向；回中应立即清零角速度；
-13. 再次长按 Z+C 停止，观察双臂限速回到新机器人保存的 Home；
-14. 仅在 OmniSocket 模式、机器人已静止且急停可用时测试 Hub 断线：EAI sender 的 KCP
+13. 确认右摇杆纵轴回中后，按住左 Z 再小幅上推/下推，验证头部相机抬头/低头；
+    按 Z 期间右摇杆水平轴不应让机器人转向。检查角度始终位于 `-10°～+50°`，且
+    外部 `/head/cmd` 活跃时本项目会暂停头部输出；
+14. 再次长按 Z+C 停止，观察双臂限速回到新机器人保存的 Home；
+15. 仅在 OmniSocket 模式、机器人已静止且急停可用时测试 Hub 断线：EAI sender 的 KCP
     反馈超时约为 500 ms，触发后会作废 session；机器人若持续约 2 秒收不到活动帧，会另行
     重建我们的接收桥。不应期待断线后透明续控；恢复后先确认未武装，稳定松开 Z+C 后再重新长按
     启动。纯 ZMQ 模式在完成本地断流门控前禁止做运动中的断链测试；
-15. 记录 SSH 地址、Home、行走限速、手部端点和单食指姿态到设备档案；OmniSocket 模式
+16. 记录 SSH 地址、Home、行走限速、手部端点和单食指姿态到设备档案；OmniSocket 模式
     另记 Peer ID/Hub，纯 ZMQ 模式改记 EAI 固定局域网 IP、TCP 5003 防火墙范围和断流门控参数。
 
 迁移时确认目标机提供 `/hric/robot/cmd_vel`（`geometry_msgs/msg/TwistStamped`），并保持
@@ -1026,6 +1029,7 @@ ZMQ 专用断流门控前不得启用运动发布。
 
 ```text
 tg3_local_teleop.py
+head_control.py
 data_collection.py
 data_recorder_protocol.py
 data_recorder_node.py
@@ -1052,38 +1056,37 @@ systemctl --user restart tg3-local-teleop.service
 ```
 
 录制脚本必须依次加载 `/opt/ros/jazzy`、`/home/nvidia/xos` 和
-`/opt/robot_tele_server/install`，但**不能**再加载本项目 `ros2_py/install`。后者是桥接
-Python 进程专用的最小 `ArmStatus` 绑定，会遮蔽厂家完整 `ros2_bridge_msgs` C++ 库，导致
+`/opt/robot_tele_server/install`，但**不能**再加载本项目 `ros2_py/install`。后者只是遥操桥
+Python 进程专用的消息绑定（含 `ArmStatus`/`RobotState`/`HeadCtrl`），并不是
+厂家完整 `ros2_bridge_msgs` 包；它会遮蔽厂家 C++ 库，导致
 rosbag 加载 `RobotState/ArmCtrl` 时出现 undefined symbol。`run.sh` 仍需项目 overlay；
 `run_data_recorder.sh` 只用厂家完整消息 overlay。
 还需 Python 3 的 PyYAML（Ubuntu 包 `python3-yaml`）解析 rosbag metadata。
 迁移时在 `config.toml [data_collection]` 核对 `base_directory`、100 GiB 余量、30 分钟
 上限、明确 topic 白名单和 required topics。不要改成 `ros2 bag record -a`，点云需另行
-估算带宽和磁盘后再加入。当前白名单已经包含头/腰 Orbbec 的 JPEG RGB、无损 PNG 深度、
-CameraInfo、Metadata 和 `/tf_static`。头、腰相机都是 optional：服务已启动时 rosbag 自动
+估算带宽和磁盘后再加入。当前白名单只包含头部 Orbbec 的 JPEG RGB、无损 PNG 深度、
+CameraInfo、Metadata 和 `/tf_static`。头部相机是 optional：服务已启动时 rosbag 自动
 发现并采集；未启动时不影响核心 episode 开始或进入 READY。收尾后 manifest 会分别把
-两台相机标成 `absent`、`healthy`、`partial` 或 `low_rate`，后两种附带质量警告但不阻塞
+头部相机标成 `absent`、`healthy`、`partial` 或 `low_rate`，后两种附带质量警告但不阻塞
 核心数据保存。
 
-需要采集某台相机的完整 episode 时，先确认相机服务和发布者；不需要相机时可保持服务
+需要采集头部相机的完整 episode 时，先确认相机服务和发布者；不需要相机时可保持服务
 停止，L3 数采仍可正常启动：
 
 ```bash
-systemctl is-active orbbec_waist.service orbbec_head.service
-sudo systemctl enable --now orbbec_waist.service
-# 同时需要头部 RGB-D 时：
+systemctl is-active orbbec_head.service
 sudo systemctl enable --now orbbec_head.service
 
-ros2 topic info /ob_camera_waist/color/image_raw/compressed
-ros2 topic info /ob_camera_waist/depth/image_raw/compressedDepth
+ros2 topic info /ob_camera_head/color/image_raw/compressed
+ros2 topic info /ob_camera_head/depth/image_raw/compressedDepth
 ```
 
-希望采集腰部图像时，两条腰部话题应显示 `Publisher count: 1`；头部同理。原始
+希望釆头部图像时，两条话题都应显示 `Publisher count: 1`。原始
 1280x720 RGB+深度约
 `8.3 GB/min/相机`，所以默认不重复录 raw，而是录标准 image_transport 压缩流；现场
-单相机约 `1.3–1.5 GB/min`，实际随画面变化。头部和腰部都运行时应按约两倍预留空间与
-同步时间。`minimum_free_gib=100` 是停止下限，不是整条 episode 的容量预算；双相机
-长录制前至少预留“100 GiB + 预计数据量”，并在短录包中先确认实际带宽。
+单相机约 `1.3–1.5 GB/min`，实际随画面变化。`minimum_free_gib=100` 是停止下限，
+不是整条 episode 的容量预算；长录制前至少预留“100 GiB + 预计数据量”，并在短录包中
+先确认实际带宽。
 
 ### 11.2 PS 本机