LeDog: 基于openEuler Embedded 2403的蔚蓝AlphaDog Dev + So101arm融合控制

1. 总览

本仓库针对蔚蓝智能科技（weilan）的 AlphaDog Dev 开发者版本，并集成了 SO-101 机械臂。仓库旨在解决在 Orange Pi AI Pro(20T) 香橙派 运行 openEuler Embedded 24.03 系统上，使用 ROS 2 Humble 环境进行统一控制的需求。

核心解决方案是利用 ros1_bridge，将机器狗自带的、闭源的 ROS 1 环境与本地的 ROS 2 Humble 环境无缝打通。这使得开发者可以使用最新的 ROS 2 工具链（joystick）同时驱动 ROS 1 的机器狗底盘和 ROS 2 的 SO-101 机械臂（如 MoveIt 2），完成遥操作采集数据。

⚠️ 警告：本系统环境为 openEuler Embedded (BusyBox)，严禁执行 dnf update，否则可能导致系统核心损坏。

2. 仓库结构

本仓库采用“一体式”结构，将 ROS 1 和 ROS 2 的相关工作区都包含在一个统一的 Git 仓库中进行管理。

alphadog_ros_ctl/  
├── doc/ # 详细的教程与说明文档
│   └── openEuler_Embedded_ROS1_Bridge_Install_Guide.md # 核心安装指南
├── README.md                        # 当前文件
├── ros1_ws/                         # ROS 1 Catkin 工作区
│   └── dog_msgs_ws/                 # 存放与机器狗通信所需的【原始】ROS 1 消息/服务/动作包
│       └── src/
│           ├── agent_msgs
│           └── ros_alphadog
└── ros2_ws/                         # ROS 2 Colcon 工作区 (Humble)
    └── src/  
        ├── bridge_mapping/          # 为 bridge 提供手动映射规则
        ├── dog_msg_ws/              # 存放从 ROS 1 迁移并适配了 ROS 2 规范的【修改版】消息包
        │   ├── agent_msgs
        │   ├── ros_alphadog
        │   └── x_rosbridge_msgs
        ├── joystick_alphadog_with_so101_servo/   # 统一的机器狗+机械臂手柄控制节点
        ├── lerobot_controller/      # SO-101 机械臂ros2 control控制器
        ├── lerobot_description/     # SO-101 机械臂 URDF 和仿真模型
        ├── lerobot_moveit/          # SO-101 机械臂 MoveIt 2 配置
        ├── ros1_bridge/             # 支持 Action 桥接的增强版 ros1_bridge
        ├── pymoveit2/               # Python MoveIt2 接口 (Submodule)
        └── so101_hw_interface/      # SO-101 机械臂硬件接口 (ros2_control)

3. 核心挑战与解决方案

在 openEuler Embedded 24.03 上部署此混合环境解决了以下核心挑战：

1. ROS 1 & ROS 2 共存: 利用 openEuler 提供的 ROS SIG 测试源，通过 DNF 直接安装了 ARM 架构的 ROS 1 Noetic 和 ROS 2 Humble，无需在板端进行耗时的源码编译。

2. 嵌入式环境库缺失修复:

   • Boost 库软链接丢失: 修复了系统缺少无版本号 .so 链接导致编译器找不到 Boost 库的问题。

   • 开发包头文件缺失: 解决了 DNF 包管理中的“幽灵包”问题（如 yaml-cpp-devel），确保编译头文件完整。

3. 权限与路径问题: 修正了 /usr/local/lib64 的权限问题，使得非 Root 用户也能正常读取依赖库。

4. ros1_bridge 适配:

   • 包名映射: 通过 bridge_mapping 解决 ros_alphadog 非标准命名问题。

   • 网络解析: 需配置 /etc/hosts 解决机器狗主机名 sport 无法解析的问题。

4. 快速上手指南

步骤 0: 系统环境准备

在开始编译本仓库代码之前，必须先按照 doc/openEuler_Embedded_ROS1_Bridge_Install_Guide.md 完成基础环境的搭建。

该指南包含了以下关键操作，如果不做，后续编译必挂：

1. 配置 ROS 1 Noetic 和 ROS 2 Humble 的 DNF 源并安装基础包。

2. 执行 dnf reinstall 修复 tinyxml2, yaml-cpp, boost 等开发包。

3. 手动创建 Boost 库的软链接。

4. 修改 /usr/local/lib64 目录权限。

步骤 1: 克隆与初始化

git clone https://gitee.com/openeuler/ledog_ros2.git ledog_ros2
cd ledog_ros2

# 初始化并拉取 Git Submodules (包含 ros1_bridge, pymoveit2 和 topic_based_ros2_control)
git submodule update --init --recursive

# 安装 python pkg 依赖
pip install feetech-servo-sdk deepdiff tqdm

# 安装 ros2 相关依赖包
mv src/ros1_bridge ./
rosdepc install --from-paths src --ignore-src -y
mv ros1_bridge ./src/

步骤 2: 编译 ROS 1 工作区

这一步是为了确保你的 ROS 1 环境包含了与机器狗兼容的、原始的自定义消息。

# 1. Source 系统 ROS 1 环境
source /opt/ros/noetic/setup.bash

# 2. 编译
cd ros1_ws/dog_msgs_ws
catkin_make -DCMAKE_BUILD_TYPE=Release -DCMAKE_POLICY_VERSION_MINIMUM=3.5

步骤 3: 编译 ROS 2 工作区（不含 Bridge）

编译所有的 ROS 2 节点、机械臂相关包、消息以及 pymoveit2。

# 打开一个全新的终端
# 1. Source 系统 ROS 2 环境
source /opt/ros/humble/setup.bash

# 2. 编译 (跳过 bridge，ros1_bridge 需要在加载双环境后最后单独编译)
cd ros2_ws
colcon build --symlink-install --packages-skip ros1_bridge -DBUILD_TESTING=OFF

步骤 4: 编译 ros1_bridge

这是最关键的一步，编译网桥本身。必须在配置正确的“混合环境”中进行。

1. 打开一个全新的终端。
2. 严格按顺序 source 环境:

# 1. Source 你的 ROS 1 工作区
source <path-to-your-repo>/ros1_ws/dog_msgs_ws/devel/setup.zsh

# 2. Source 你的 ROS 2 工作区
source <path-to-your-repo>/ros2_ws/install/setup.zsh

3. 运行编译:

cd <path-to-your-repo>/ros2_ws
colcon build --packages-select ros1_bridge --cmake-force-configure --cmake-args -DBUILD_TESTING=OFF

5. 运行与验证

• 在机器狗上，驱动节点会自动运行。
• 你可以在 PC 或 OPi 上运行 roscore（如果需要），PC和OPi通过网络WiFi或网线连接机器狗。也可以通过 rostopic list 验证与机器狗的 ROS 1 网络已联通。

---

5.1 网络配置

在运行前，请确保板子与机器狗在同一网段，并配置了环境变量：

# 编辑 ~/.bashrc 或 ~/.zshrc
export ROS_MASTER_URI=http://10.10.10.10:11311  # 机器狗 IP
export ROS_IP=10.10.10.xxx                      # Orange Pi 的 IP

同时修改 /etc/hosts 添加机器狗主机名映射：

sudo echo "10.10.10.10 sport" >> /etc/hosts

5.2 自动化启动 (Tmux)

本仓库提供了 start_dog.sh 脚本，使用 tmux 一键启动。

注意：在 openEuler Embedded 上使用 tmux 前，需确保已按照安装指南修复了 libevent 缺失和 glibc-langpack-en 语言包问题，否则 tmux 无法启动。

1. 赋权:

chmod +x start_dog.sh

2. 启动:

./start_dog.sh
# or
./start_dog_split.sh

脚本会自动启动 ROS 2 驱动节点和 ros1_bridge。

3. 管理 Tmux:
   • 进入会话查看日志: tmux attach -t ledog
   • 后台挂起: 按下 Ctrl+B，松开后按 d。
   • 关闭会话: tmux kill-session -t ledog

5.3 手动启动 (调试用)

终端 A (ROS 2 驱动):

source /opt/ros/humble/setup.bash
source ros2_ws/install/setup.bash
ros2 launch joystick_alphadog_with_so101_servo start_real_dog_with_arm.launch.py

终端 B (Bridge):

source /opt/ros/noetic/setup.bash
source ros1_ws/dog_msgs_ws/devel/setup.bash
source /opt/ros/humble/setup.bash
source ros2_ws/install/setup.bash

ros2 run ros1_bridge dynamic_bridge --bridge-all-topics

5.4 机械臂校准 (调试)

使用统一的校准工具来校准 Leader 或 Follower 臂:

校准 Follower 臂 (默认):

ros2 run so101_hw_interface so101_calibrate_arm
# 或明确指定
ros2 run so101_hw_interface so101_calibrate_arm --arm follower

校准 Leader 臂:

ros2 run so101_hw_interface so101_calibrate_arm --arm leader

自定义串口:

ros2 run so101_hw_interface so101_calibrate_arm --arm leader --port /dev/ttyACM0

7. 致谢

本仓库中使用的 ros1_bridge 及其 bridge_mapping 方案，基于社区开发者 Doug Smith 的杰出工作。