169 lines
7.9 KiB
Markdown
169 lines
7.9 KiB
Markdown
# 天工 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 失败属于正常现象，应在重新上电并完成启动后检查。
|