故障排除

1. 先做环境一致性自检（建议先看）

按本文“安装与部署”里要求的顺序执行 source（先 ti5_control，后工作空间根 install）。
确认你运行时用到的 ti5_control 前缀是当前工作空间的那一份：

ros2 pkg prefix ti5_control

如果输出路径不是你当前期望的工作空间前缀，优先先修正 source，不要直接反复启动/重跑 demo。

2. 编译提示找不到 `ti5_control` / 运行提示找不到包

先按“先做环境一致性自检”里方式检查 source 与 ros2 pkg prefix ti5_control
若你尚未完成工作空间根目录 colcon build，先完成根目录构建再运行；否则可能会出现依赖解析失败

3. 服务发现不到 / 示例端超时

常见检查点：

joint_manager --type 必须与调用侧/配置侧一致
ti5/waist_* 仅在 joint_manager --type T170C 或 T170C_2_0 时注册
如果使用 ROS 命名空间（如 --ns /robot1），调用侧与服务端要保持相同命名空间；domain_id 也要一致

4. `jointstate_list` 停更 / 等待到位超时

现象：seq 长时间不增加、timestamp_ns 的 age 持续增大；或 motion_control_status.error_code=-1001。

常见原因与处理：

MoveJ/MoveL 期间 jointstate_list 停更：旧版服务回调阻塞默认回调组，定时器无法触发；请更新到当前版本（Reentrant 传感器定时器 + MultiThreadedExecutor + 规划/执行工作线程）
CAN/电机无反馈：检查对应关节 error_code、线缆与使能状态
客户端误判：等待到位须同时检查 seq 递增、timestamp_age < 1s、关节误差；反馈停更时应立即失败，不要仅依赖 BodyMove success=true

ros2 topic echo /ti5/jointstate_list --field seq --field timestamp_ns
ros2 topic echo /ti5/motion_control_status --field error_code --field error_msg --field jointstate_seq

5. `joint_manager` 启动报 `undefined symbol`（如 `WaistMoveL` typesupport）

多见于新增/修改 .srv 后未完整重编，或 Jetson 上直接 ros2 run 未加载 typesupport 动态库：

在工作空间根目录重新构建：colcon build --packages-select ti5_control --cmake-clean-cache（或至少 --packages-select ti5_control），再 source install/setup.bash
优先用包内脚本启动（已配置 LD_PRELOAD 与 typesupport 路径）：./script/run_joint_manager.sh --type T170C_2_0
确认 ros2 service list 能看到 ti5/waist_fk 等四项；日志中应有 binding_ok=1，以及 fold links a2=... a3=...

6. 动态库找不到 / `Ti5RobotControl.so: undefined symbol: Robot::fkPos`

多见于 /lib/aarch64-linux-gnu/Ti5RobotControl.so 为旧版，与当前 colcon build 的 joint_manager 不匹配；调用 ti5/arm_fk 时 joint_manager 会直接退出（symbol lookup error）。

根因：Robot::ik / Robot::fkPos 在 libti5Solver_arm.so 里，不在 Ti5RobotControl.so 里。若只把 Ti5RobotControl.so 拷到 /lib/aarch64-linux-gnu/，运行时会报 undefined symbol: Robot::ik 或 Robot::fkPos。

处理步骤（Jetson，按实际 install 路径调整）：

cd ~/Desktop/ros2
source install/setup.bash
LIB=install/ti5_control/lib/ti5_control
# 若在 src/ti5_control 下嵌套 install，则：
# LIB=src/ti5_control/install/ti5_control/lib/ti5_control

ls -l "$LIB/Ti5RobotControl.so" "$LIB/libti5Solver_arm.so"   # 两者都必须存在

sudo cp -f "$LIB/Ti5RobotControl.so" "$LIB/libti5Solver_arm.so" /lib/aarch64-linux-gnu/
sudo cp -f "$LIB/libti5_trajectory_planner.so" /lib/aarch64-linux-gnu/ 2>/dev/null || true
sudo ldconfig
nm -D /lib/aarch64-linux-gnu/libti5Solver_arm.so | grep -E 'Robot.*ik|fkPos'   # 应能看到符号

然后重新 ./script/run_ti5_services.sh --type T170C_2_0。脚本会成套同步 Ti5RobotControl.so + libti5_robot.so（不再只覆盖前者）。

若 libti5Solver_arm.so 不存在：从官方 SDK 拷贝到 src/ti5_control/.../humanoidarms_f_i_solutions/usrlib/TI5_TWO_ARM/arm/ 后重新 colcon build ti5_control。

其它「找不到 .so」：先 source install/setup.bash；必要时将 install/ti5_control/lib 写入 ld.so.conf.d 后 sudo ldconfig

7. CAN/串口权限

CAN/网卡类通常不建议普通权限下直接跑；若需要请按你们环境配置 capability
若你执行 ros2 launch ti5_bringup ti5_bringup.launch.py type:=T140A（或开启 enable_sri_can）时遇到 CAN 权限相关报错，建议先手动运行服务脚本打开所需能力：
- ./script/run_ti5_services.sh --type T140A
- 该脚本会对 joint_manager / sri_can_node 设置 setcap cap_net_admin,cap_net_raw+eip（以及必要时刷新动态库加载配置），用于非 sudo 访问 CAN。
灵巧手串口权限不足时，常见修复是把用户加入 dialout 组
说明：setcap 能力是写在二进制文件（可执行文件路径）上的。如果你把 ros 包移植到其它目录、或重新编译后生成了新的可执行文件，能力可能不会自动继承，此时需要再运行一次 ./script/run_ti5_services.sh --type <你的型号> 重新配置。

8. CSV 动作播放失败

CSV 文件与当前运行的 ti5_control 安装布局、型号目录需匹配
典型排查思路：确认对应 <型号>/...csv 是否存在于当前 ti5_control 安装前缀的 share/ 目录下

故障排除

1. 先做环境一致性自检（建议先看）

2. 编译提示找不到 ti5_control / 运行提示找不到包