# 天工 3.0 `joystick_bridge` 与 `/sbus_data` 证据记录

记录时间：2026-08-07

本文只区分三类结论：SDK 文档明确说明、机器人运行时直接观测、尚未证明。不能用 ROS
节点存在某个订阅或发布端，代替对其内部算法的证明。

## 1. 对此前说法的证据审计

|此前说法|目前证据|结论|
|---|---|---|
|`joystick_bridge` 处理按键|它订阅 `/sbus_data`；SDK 定义 A～H 语义；实机 `bridge_config.yaml` 给出 A～H 的规则|已证明|
|它处理“持续按住”条件|实机 YAML 配置 `a/b/c` 长按阈值分别为 `1.0/1.0/0.5 s`，并给出 `press_state` 规则|已证明厂商遥控器长按机制；与本地 xTELE 的 3 秒保护不是同一机制|
|它进行 `/robot_state` 状态检查|运行中的节点确实订阅 `/robot_state`|只证明订阅；如何检查、检查哪些字段尚未证明|
|它进行速度缩放和方向映射|已只读取得 `/home/ubuntu/data/param/bridge_config.yaml`，其中包含状态速度上限、偏置和速度处理流水线参数|已证明配置能力；核心算法在编译包中|
|它发布 `/fsm_state_cmd`、`/fsm_resume_cmd`、`/stand_cmd`|运行中的 `ros2 node info /joystick_bridge` 直接列出这三个发布端|已证明发布能力；触发条件和消息内容尚未证明|
|它有特定行走启停顺序|YAML 的 `fsm_command_bindings` 明确列出状态规则和持续速度动作|已证明配置规则；未做带运动的完整时序采样|

因此可以准确地说：`joystick_bridge` 是厂商 SBUS 遥控器适配器，包含按键规则、状态命令
和速度计算配置。但二次开放文档同时提供独立的 `/hric/robot/cmd_vel` topic 接口，本地
xTELE 桥不必伪装成 SBUS 遥控器。

## 2. SDK 文档证据

来源：`具身天工3.0+SDK+文档（26.04.x）+(1).md` 第 299～319 行。

文档明确规定：

- `/sbus_data` 类型为 `sensor_msgs/msg/Joy`；
- `axes` 包含 12 个 `float32`，取值范围 `[-1.0, 1.0]`；
- `buttons` 为空，不使用；
- `/sbus_data/event` 类型为 `bodyctrl_msgs/msg/SbusData`；
- 事件消息包含 A～H 的状态，以及 `x1/y1/x2/y2` 四个摇杆轴；
- 四个摇杆轴范围为 `[-1.0, 1.0]`，直接透传、不滤波。

文档没有给出 `/sbus_data.axes[0..11]` 与 `x1/y1/x2/y2/A..H` 的逐项下标映射，
因此不能只根据字段数量猜测 12 个下标。

## 3. 机器人运行时证据

在 Nvidia 侧加载机器人 ROS 环境后执行：

```bash
ros2 node info /joystick_bridge
ros2 param get /joystick_bridge config_file
ros2 param get /joystick_bridge joy_topic
ros2 topic info -v /sbus_data
```

观测结果：

```text
/joystick_bridge subscribers:
  /robot_state: ros2_bridge_msgs/msg/RobotState
  /sbus_data: sensor_msgs/msg/Joy

/joystick_bridge publishers:
  /hric/robot/cmd_vel: geometry_msgs/msg/TwistStamped
  /hric/robot/fsm_resume_cmd: std_msgs/msg/String
  /hric/robot/fsm_state_cmd: std_msgs/msg/String
  /hric/robot/stand_cmd: geometry_msgs/msg/TwistStamped
  （另有双臂、头、腰和双手控制话题）

config_file = /home/ubuntu/data/param/bridge_config.yaml
joy_topic = /sbus_data
```

`/sbus_data` 当前只有一个发布者 `/joystick`，QoS 为 `RELIABLE/VOLATILE`。空闲帧实测为：

```yaml
axes: [-0.0, -0.0, -0.0, -0.0, -1.0, -0.0, -1.0, -0.0,
       -1.0, -1.0, -1.0, -1.0]
buttons: []
```

对应时刻 `/sbus_data/event` 的语义状态为：

```yaml
button_a: -1
button_b: -1
button_c: -1
button_d: -1
button_e: -1
button_f: 0
button_g: 0
button_h: -1
x1: -0.0
y1: -0.0
x2: -0.0
y2: -0.0
```

这组同时采样可作为空闲状态基准，但不足以单独反推出所有按键下标和状态编码；需要读取
`bridge_config.yaml`，或对原遥控器逐键采样。

## 4. 同构臂侧是否具备生成 SBUS 输入的数据

EAI 上 xTELE 原始流 `tcp://127.0.0.1:5003` 的一帧实测包含：

```text
joystick = {'left': [-0.009, 0.012], 'right': [-0.059, 0.011]}
button   = {'left': [0, 0, 0, 0, 0], 'right': [0, 0, 0, 0, 0]}
```

同一帧还包含 `button_joystick`、`button_wheel`、`scroll`、`trigger` 等输入。因此：

- 如果“灵巧手”指同构臂手柄：可以取得左右摇杆和实体按键原始数据，数据源足够构造
  `sensor_msgs/msg/Joy`；
- 如果“灵巧手”指机器人 BrainCo 灵巧手：不可以。灵巧手只提供电机位置/状态和触觉等，
  不会产生遥控器摇杆与 A～H 开关数据；
- xTELE 按键是布尔输入，而 SBUS 中含二档、三档开关语义。需要通过明确映射或本地状态机
  转换，不能把布尔数组直接当成 12 个 SBUS 轴发布。

## 5. 本地桥不再发布 FSM 命令

已从 `tg3_local_teleop.py` 删除：

- `std_msgs/msg/String` FSM 发布器；
- `gotoHBWALK` 消息构造与重复发布；
- FSM burst、间隔和等待参数。

当前桥只在机器人已经报告 `HBWALK/running` 且安全门通过时发布
`/hric/robot/cmd_vel`，释放操作后仍发送限量零速度帧。

本地公网链路的唯一 3 秒门控现位于 EAI：左 Z + 右 C 产生 START/STOP 会话，待机不发送
xTELE 业务帧。会话启动后，右 C + 左摇杆在机器人端即时映射到 `/hric/robot/cmd_vel`；
松开立即零速，再次操作不重新计时。

部署后运行时检查 `/hric/robot/fsm_state_cmd` 只有厂商节点
`control_forward` 与 `joystick_bridge` 两个发布者，不再包含 `tg3_local_teleop`；状态文件同时显示：

```text
locomotion_fsm_publish_enabled = false
```

## 6. 最终采用 direct topic，而不是模拟 `/sbus_data`

`twice dev.pdf` 明确规定 `/hric/robot/cmd_vel` 为
`geometry_msgs/msg/TwistStamped`，其中 `linear.x/linear.y/angular.z` 分别控制前后、侧移和
转向。运行中的 `/hric_topic_bridge` 也直接订阅该话题。因此本项目继续使用 direct topic，
不增加第二个 `/sbus_data` 发布者，避免与原 `/joystick` 的约 43 Hz 数据交错。

实机 xmigcs `dex_config.yaml` 原先把 HBWALK 的四个速度上限全部设为零，这才是 HBWALK
topic 无法行走的关键配置。2026-08-07 已按文档把 HBWALK 上限改为当前 NAVIGATE 同值，
并保留原配置备份。`twice dev.pdf` 第 1 页规定半身行走 Topic 的 `linear.x` 范围为
`[-0.8, 1.0] m/s`、`angular.z` 范围为 `[-0.8, 0.8] rad/s`；本地桥现按这组官方 Topic
范围做前进/后退非对称限幅，不发布 `linear.y`。

## 7. xmigcs 配置的加载与重启边界

`dex_config.yaml` 只在 xmigcs 初始化时由 `robot_interface.init()` 读取，当前节点没有动态
reload 参数、service 或 action。现场固件的 `/proc_manager/config/notify` 也不是进程
启停接口：其回调只记录 String 内容并重新读取 proc_manager 自身的固定
`proc_manager.json`。曾尝试向该话题发送 `CMD_STOP_PROC/CMD_START_PROC` JSON，实测
xmigcs PID 始终为 `3269`，日志也没有任何启停记录；该用法已确认无效并从部署说明删除。

当前固件没有启用内部遗留 `OnRequest` 的 fd 通道，也没有单进程 ROS service、action、
监听端口或 CLI。因此加载新 YAML 应使用厂商真实生命周期：先退出遥操，按原流程切到
`48V Off`，由 proc_manager 停止 `rl` 与 `robot_control`，再恢复 48V 并完成原有物理启动
动作。只有 xmigcs 出现新的 PID/启动时间，才表示新配置已经进入运行态。不要直接 kill
xmigcs，也不要伪造 `/robotcontrol_state`。

2026-08-07 14:32 的实际重启结果为 PID `3125`。新日志明确打印 HBWALK 已加载
`max_x_plus=1.2`、`max_x_minus=0.6`、`max_y=0.6`、`max_yaw=1.0`，随后完成
Robot interface、SHM RPC 与 100 Hz 控制线程初始化，并进入 `HBWALK`。该进程会把
Linux `comm` 名称设为 `xmigcs`，因此 `ps -C python3` 可能无输出；应使用
`ps -C xmigcs -o pid,lstart,cmd` 或上述精确 `pgrep`。本机切断动力电源时 Ubuntu/网络也
可能同时离线，断电期间 SSH 失败属于正常现象，应在重新上电并完成启动后检查。