feat: add head control and joint data decoder

tg3_local_teleop/README.md

@@ -15,6 +15,8 @@ TS1P 同构臂
   -> 天工 3.0 BrainCo Revo2 双灵巧手
   -> /hric/robot/cmd_vel（左摇杆前后 / 右摇杆转向；50 Hz TwistStamped）
   -> 天工 3.0 HBWALK 行走
+  -> /head/cmd（左 Z + 右摇杆上下；Head Pitch 位置模式）
+  -> 天工 3.0 头部相机上下视角
 ```
 
 ## 自动运行与操作
@@ -38,6 +40,13 @@ TS1P 同构臂
   `0.8 rad/s`；死区 `0.2`，输出频率 `50 Hz`。
 - xTELE 0.1.2 的摇杆数组顺序是“纵轴、横轴”；左纵轴映射到 `linear.x`，右横轴
   映射到 `angular.z`。`TwistStamped.header.frame_id` 按二次开放文档设置为 `pelvis`。
+- 头部视角：遥操已启动且右摇杆纵轴先回中过一次后，按住左 Z，右摇杆上推使
+  Head Pitch 向负值移动（抬头），下推使其向正值移动（低头）；不需要 R3。按 Z
+  期间右摇杆水平转向会被屏蔽，避免调整视角时误转。控制只使用 `mode=0` 绝对
+  位置、`cur=1.0 A`，从 `/robot_state` 的真实 `name=2` 反馈起步，限制在 `-10°～+50°`、
+  最大 `0.2 rad/s`、加速度 `0.5 rad/s²`。摇杆回中、输入/反馈失联或头电机报错时停止
+  更新目标。检测到 `control_forward`、`patrol_agent`、`joystick_bridge` 等外部
+  `/head/cmd` 实际消息后，本项目暂停头部输出，静默 1 秒并再次观察摇杆回中后才恢复。
 - 当前安装的 xTELE 0.1.2 没有注册同侧右 `C+A` 组合，因此 `C+A` 不执行动作；不能
   在不清楚厂商语义的情况下把它擅自绑定为状态切换。
 - 同构臂当前的一维手部开合量以机器人实测默认打开姿态为 0 端点，并按厂家 xTELE 的
@@ -73,6 +82,10 @@ HBWALK 状态等运行时保护仍持续检查。厂家 `freq_change_tg3_node`
 或右摇杆横向越过死区时发布。摇杆回中后立即发布零速，并补发 10 帧零速。公网断线、退出遥操、
 回 Home 或机器人退出 HBWALK 也走同一停止逻辑。
 
+头部控制只在同一次遥操武装期间启用，不改变 Head Yaw，也不改变厂家头部机械限位、
+电流、高温或碰撞保护。服务重启或新会话不会把软件累计角度当真实位置，必须重新读取
+`/robot_state` 的 Head Pitch 反馈。
+
 灵巧手仅在同一次长按武装后发布；以机器人真实手指位置为起点，并按每秒最多 400 个
 位置单位平滑跟随。BrainCo 状态 `0`（空闲）、`1`（运动）、`2`（接触/堵转或到限位）
 和 `3`（持续力）均为厂家定义的正常运行状态；仅状态失联、未知/非法状态
@@ -166,13 +179,12 @@ OmniSocket 进程；在此之前桥会保持最后一帧目标。未 START 或
 项目自有 `tg3-data-recorder.service` 在 Nvidia 上运行独立 `ros2 bag record`，不停止、
 重配或接管 Ubuntu 厂家 `/record_bag_node`。仅录 `config.toml` 中的明确白名单，包含
 `/robot_state`、双臂/BrainCo 双手命令与反馈、HBWALK、IMU、电源状态、完整 xTELE
-应用帧，以及头/腰 Orbbec 的 RGB、深度、内参和元数据；仍禁止改成 `-a` 或录点云。
+应用帧，以及头部 Orbbec 的 RGB、深度、内参和元数据；仍禁止改成 `-a` 或录点云。
 
 为避免 1280x720 原始 RGB+深度每台相机约 `8.3 GB/min` 的持续写盘负载，默认录制
 `color/image_raw/compressed`（JPEG）和 `depth/image_raw/compressedDepth`（16UC1
-无损 PNG）。现场单台腰部相机实测合计约 `22–25 MB/s`（约 `1.3–1.5 GB/min`，随
-场景变化）。头、腰两组相机都不是 required topics：服务在运行就由 rosbag 自动发现并
-采集，未运行不阻塞 L3 或核心 READY。manifest 对每组记录 `absent`、`healthy`、
+无损 PNG）。头部相机不是 required topic：服务在运行就由 rosbag 自动发现并
+采集，未运行不阻塞 L3 或核心 READY。manifest 记录 `absent`、`healthy`、
 `partial` 或 `low_rate`，并保存各话题消息数和图像平均频率；相机异常会产生明确质量
 警告，但不会丢弃其余机器人控制数据。静态 TF 也尽力采集，不作为启动门槛。
 
@@ -187,7 +199,7 @@ OmniSocket 进程；在此之前桥会保持最后一帧目标。未 START 或
 ```
 
 MCAP 使用 `zstd_fast`、64 MiB cache、每 300 秒分片；每条 episode 最长 30 分钟，
-加入双 RGB-D 后启动/运行最低保留 100 GiB。正常停止以 SIGINT 让 rosbag 写完
+启动/运行最低保留 100 GiB。正常停止以 SIGINT 让 rosbag 写完
 `metadata.yaml`，随后执行
 `ros2 bag info`，并确认所有 required topics 都有非零消息数；然后计算 SHA-256、写
 `manifest.json` 和 `READY`，最后才原子进入 `ready/`。Nvidia 需已安装 `python3-yaml`
@@ -209,7 +221,8 @@ sudo systemctl enable --now orbbec_head.service
 ```
 
 录制服务只加载厂家完整 `/opt/robot_tele_server/install` 消息 overlay，不加载本项目
-`ros2_py/install`；项目 overlay 仅供桥的 Python `ArmStatus` 绑定使用。两者混在同一个
+`ros2_py/install`；项目 overlay 仅供遥操桥的 Python 消息绑定使用
+（包括 `ArmStatus`/`RobotState`/`HeadCtrl`，但不是厂家完整包）。两者混在同一个
 rosbag 环境会让部分 `ros2_bridge_msgs` C++ 类型支持出现动态库符号冲突。
 
 部署两个机器人侧服务：