SO101 ROS2 Bringup

SO101 机械臂 (6-DOF, STS3215 舵机) 的 ROS2 驱动包。

当前实现用自定义so101_hardware_bridge做串口桥接，未接入ros2_control。config/so101_controllers.yaml仅作后续升级参考。

架构

真机模式（默认）:

/dev/ttyACM* → so101_hardware_bridge → /joint_states → robot_state_publisher → /tf → RViz2 ↑ /joint_commands (用户节点 / so101_test_control)

调试模式（use_joint_state_gui:=true，不启硬件）:

joint_state_publisher_gui → /joint_states → robot_state_publisher → /tf → RViz2

与硬件桥接互斥：开 GUI 时不会启动so101_hardware_bridge。

前置条件

依赖包

sudoaptinstall-y\ros-humble-robot-state-publisher\ros-humble-joint-state-publisher\ros-humble-joint-state-publisher-gui\ros-humble-rviz2\python3-colcon-common-extensions pipinstallpyserial# 真机串口需要

WSL2 USB 转发（仅真机）

# Windows PowerShell (管理员)winget install usbipd usbipd list usbipd bind--busid <BUSID> usbipd attach--wsl--busid <BUSID>

sudochmod666/dev/ttyACM1# 或: sudo usermod -aG dialout $USER 后重新登录

编译

若 shell 里 conda/miniforge 的python3优先，请先保证系统 Python：

exportPATH="/usr/bin:$PATH"cd~/robot-urdfs/so101/so101_bringup colcon build --symlink-installsourceinstall/setup.bash

包内 URDF 使用package://so101_bringup/assets/...；仓库根目录so101/so101_new_calib.urdf仍是file://绝对路径，请优先用包内版本。

运行

重要 (WSL2):启动 RViz2 前必须使用软件 OpenGL，否则可能导致整机黑屏无法恢复。
launch 已自动设置LIBGL_ALWAYS_SOFTWARE=1。若手动启动rviz2，请先：

exportLIBGL_ALWAYS_SOFTWARE=1

调试（无真机，GUI 滑块 + RViz）

ros2 launch so101_bringup so101.launch.py use_joint_state_gui:=true

RViz 只负责显示；关节由弹出的Joint State Publisher滑块控制（不是在 RViz 视口里拖模型）。

真机（硬件桥接 + RViz）

ros2 launch so101_bringup so101.launch.py port:=/dev/ttyACM1

仅硬件桥接（不启 RViz）

ros2 launch so101_bringup so101.launch.py use_rviz:=false

控制机械臂（真机）

方式 1: 发布关节角度（弧度，顺序见下表）

ros2 topic pub /joint_commands std_msgs/msg/Float64MultiArray\"{data: [0, 0, 0, 0, 0, 0]}"-1

方式 2: 键盘测试节点

# 另开终端，先 source install/setup.bashros2 run so101_bringup so101_test_control

方式 3: Python

importrclpyfromstd_msgs.msgimportFloat64MultiArray rclpy.init()node=rclpy.create_node('so101_controller')pub=node.create_publisher(Float64MultiArray,'joint_commands',10)msg=Float64MultiArray()msg.data=[0.0,0.5,-0.8,0.0,0.0,0.0]pub.publish(msg)

查看状态

ros2 topicecho/joint_states# 当前实现主要发布 positionros2 run tf2_tools view_frames

话题

Launch 参数

硬件桥接节点内部参数（也可在 launch 中覆盖）：

关节顺序（与/joint_commandsdata 下标一致）

环境检查

更完整的安装与排错见 docs/ENV_SETUP.md。也可运行：

bashscripts/check_env.sh

效果

Reference

lerobot-so101-rviz2