feat: add head control and joint data decoder

docs/天工3.0同构臂遥操与数采跨设备迁移手册.md

@@ -488,8 +488,9 @@ joint_goal_rad = [<新机器人实测的14个弧度值>]
 - `[hands].closed_normalized` 和单食指姿态；
 - `[control]` 关节限位是否仍对应当前型号和 SDK；
 - `[locomotion]` 的 Topic、方向和厂家速度上限；
+- `[head]` 的 `/head/cmd`、`/robot_state`、俯仰方向、工作区、速度/加速度和外部命令租约；
 - `base_directory` 是否仍是 `/home/nvidia/tg3_data_collection`；
-- 相机 Topic 是否仍为 `/ob_camera_head/...` 和 `/ob_camera_waist/...`。
+- 头部相机 Topic 是否仍为 `/ob_camera_head/...`。
 
 ### 6.5 新机器人必须重新采集 Home
 
@@ -568,7 +569,8 @@ restart 本机同步服务。
 | 换 TS1P | EAI 原厂标定、EAI Peer、机器人 `expected_iarm_id`，必要时方向和按键复核 |
 | 换灵巧手型号 | 必须改代码和消息映射；不能只换 Topic 字符串 |
 | 相机未安装或未启动 | 不阻塞数采；manifest 标记 `absent` |
-| 头/腰相机启动 | 下一条数采自动包含对应压缩 RGB-D，并记录质量状态 |
+| 头部相机启动 | 下一条数采自动包含头部压缩 RGB-D，并记录质量状态 |
+| 腰部相机启动 | 不录制；当前白名单不含 `/ob_camera_waist/...` |
 
 ## 9. 统一启动顺序与现场验收
 
@@ -618,7 +620,7 @@ python3 -m json.tool Data_Get/sync_status.json
 - EAI 本地 5003/5001 数据持续更新；
 - 待机时 EAI 不发送业务帧；
 - PS 同步无错误且 pending 为 0；
-- 头/腰相机未启动不影响 recorder 服务 active。
+- 头部相机未启动不影响 recorder 服务 active；腰部相机不在数采白名单。
 
 ### 9.3 逐级运动验收
 
@@ -631,8 +633,10 @@ python3 -m json.tool Data_Get/sync_status.json
 5. 长按右 B 1 秒验证左右手同时单食指，再松开 0.5 秒、长按 1 秒退出；
 6. 确认双摇杆回中后，直接小幅推动左摇杆验证前后，回中应立即零速；
 7. 直接小幅横推右摇杆验证原地转向，回中应立即零速；
-8. L3 长按 1 秒开始短数采，再次长按 1 秒结束；
-9. 长按 Z+C 3 秒结束遥操，确认限速回新机器人的 Home。
+8. 右摇杆纵轴回中后，按住左 Z 再小幅上推/下推，确认头部相机视角
+   抬高/降低；同时小幅横向偏移不应让机器人转向，松开 Z 或回中后停止更新；
+9. L3 长按 1 秒开始短数采，再次长按 1 秒结束；
+10. 长按 Z+C 3 秒结束遥操，确认限速回新机器人的 Home。
 
 不要用本项目发布 `gotoHBWALK`，不要向厂家 `/proc_manager/config/notify` 发送伪进程启停
 JSON，也不要为了迁移删除厂家限位、电流、碰撞或急停保护。

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 本机