# ledog_ros2

**Repository Path**: openeuler/ledog_ros2

## Basic Information

- **Project Name**: ledog_ros2
- **Description**: The ROS control code repository for the alphadog dev + lerobot so101arm robotic arm defines a new robot kinematic model(alphadog dev + so101arm)
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2025-10-24
- **Last Updated**: 2025-12-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: sig-embedded

## README

# 蔚蓝 AlphaDog Dev + SO-101 机械臂 ROS 1 / ROS 2 通信桥接方案

## 1. 总览

本仓库针对蔚蓝智能科技（weilan）的 AlphaDog Dev开发者版本，并集成了 SO-101 机械臂。仓库旨在解决在外部计算单元（如外挂 PC 或香橙派 Orange Pi AI pro 等开发板）上，使用 ROS 2 Humble 环境进行统一开发的需求。

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

## 2. 仓库结构

本仓库采用“一体式”结构，将 ROS 1 和 ROS 2 的相关工作区都包含在一个统一的 Git 仓库中进行管理。`ros1_bridge` 及其所有 ROS 2 侧的依赖（包括修改后的消息包）均已集成到 `ros2_ws` 工作区中，简化了编译和管理。

```
alphadog_ros_ctl/  
├── doc/                             # 详细的教程与说明文档  
├── 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  
        └── so101_hw_interface/      # SO-101 机械臂硬件接口 (ros2_control)
```

* **`doc/`**: 包含在 Ubuntu 22.04 上从源码编译 ROS 1 Noetic 和配置 `ros1_bridge` 的详细指南。  
* **`ros1_ws/`**: 包含与机器狗通信所需的**原始** ROS 1 接口包。  
* **`ros2_ws/`**: 包含所有 ROS 2 相关代码。  
  * `dog_msg_ws/`: 存放了从 `ros1_ws` 迁移过来的接口包。这些包的接口定义文件 (`.msg`, `.srv`, `.action`) 已被修改，以符合 ROS 2 的严格规范（如字段名小写、`time` 类型替换等）。  
  * `ros1_bridge/`: 采用了一个社区维护的、功能更强大的分支，以支持 Action 桥接。  
  * `bridge_mapping/`: “增强版”网桥的“翻译词典”。由于 `ros_alphadog` 包名不符合 `_msgs` 后缀的自动映射规则，且 ROS 1 与 ROS 2 的接口定义因规范不同而存在差异，我们利用这个包中的 `.yaml` 文件来手动告诉网桥如何进行精确的包级别和字段级别映射。  
  * `lerobot_...` / `so101_...`: ROS 2 侧的机械臂控制、仿真和硬件接口相关包。  
  * `joystick_alphadog_with_so101_servo/`: 一个完整的 ROS 2 功能包，演示了如何使用手柄统一控制 ROS 1 的AlphaDog底盘和 ROS 2 的机械臂。

## 3. 核心挑战与解决方案

本仓库的配置解决了在非标准环境下桥接复杂闭源系统的几个核心挑战：

1. **在 Ubuntu 22.04 上运行 ROS 1 Noetic**: 通过源码编译并修复多个兼容性问题，实现了 ROS 1 在非官方支持的系统上的稳定运行。  
2. **桥接闭源 ROS 1 节点**: 方案是保持 ROS 1 接口原始，修改 ROS 2 接口，并利用手动映射规则来弥合差异。  
3. **克服 ros1_bridge 的限制**:  
   * **包名后缀问题**: `ros_alphadog` 包名不以 `_msgs` 结尾，通过 `bridge_mapping` 包中的包级别映射规则解决。  
   * Action 支持问题: 使用了社区的增强版 `ros1_bridge` 分支，并通过 `bridge_mapping` 中的动作级别（`action_fields_1_to_2`）和字段级别映射来解决。  
4. **修复 ros1_bridge 网络错误**:  
   * `ros1_bridge` 在启动时可能会因为无法解析机器狗的主机名（如 sport）而打印 `couldn't resolve publisher host [sport]` 错误，导致连接不稳定。  
   * 解决方案: 在运行网桥的 PC 上编辑 `/etc/hosts` 文件 (`sudo vim /etc/hosts`)，添加一行来手动指定 IP 映射，例如：`10.10.10.10 sport`。  
5. **DDS 启动竞态条件**:  
   * `ros1_bridge` 和多个 ROS 2 节点同时启动时，DDS 的服务发现机制可能失败，导致话题（如 `/alphadog_node/dog_ctrl_state`）虽然被 `ros2 topic info` 发现，但 `echo` 却收不到数据。  
   * 解决方案: 采用特定的启动顺序（见第5节），总是最后启动 `ros1_bridge`，确保 ROS 2 订阅者已处于稳定等待状态，从而实现可靠连接。

## 4. 快速上手指南

### 步骤 0: 先决条件

1. **操作系统**: Ubuntu 22.04 LTS。  
2. **ROS 2**: 已安装 ROS 2 Humble (Desktop)。
3. **ROS 1**: 已按照 `doc/` 目录下的教程，在你的系统上（例如 `/opt/ros/noetic`）成功从源码编译并安装了 ROS 1 Noetic。  
4. **Git**: 已安装 git。  
5. **PyMoveIt2**: x86 架构可参考 [jammy-humble-amd64 分支](https://github.com/AndrejOrsula/pymoveit2/tree/jammy-humble-amd64)，ARM 架构则需要从源码编译安装，参考 [main 分支](https://github.com/AndrejOrsula/pymoveit2/tree/main)。本仓库将在初始化步骤中自动克隆源码。  
6. **网络配置**: 在本地 `~/.zshrc` 或 `~/.bashrc` 中需要包括以下内容并 `source` 使其生效：  
   ```bash
   # AlphaDog 机器狗的 ROS 1 Master 地址
   export ROS_MASTER_URI=http://10.10.10.10:11311 ##机器狗IP，端口默认
   # 本机连接机器狗WiFi后分配的IP或者OPi控制板连接机器狗网络后分配的IP地址
   export ROS_IP=10.10.10.xxx     ##本机ip
   ```

#### **步骤 1: 克隆与初始化**

```shell
git clone https://gitee.com/chenxin852/alphadog_ros_ctl.git alphadog_ros_ctl
cd alphadog_ros_ctl
# 初始化并拉取 Git Submodule (ros1_bridge)
git submodule update --init --recursive
# 克隆 PyMoveIt2 到 ROS 2 工作区 (仅限 ARM 架构或需要从源码编译的情况)
# 注意：如果你的设备是 x86 架构，并且已经按照【步骤 0】中的第 5 点通过 apt 安装了 PyMoveIt2，请跳过此 git clone 步骤，否则可能会导致包冲突。
git clone https://github.com/AndrejOrsula/pymoveit2.git ros2_ws/src/pymoveit2

# 使用rosdep安装依赖
cd ros2_ws
rosdep install -y -r -i --rosdistro ${ROS_DISTRO} --from-paths src

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

#### **步骤 2: 编译 ROS 1 工作区**

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

```shell
# 在一个 source 了 ROS 1 Noetic 主环境的终端里操作
source /opt/ros/noetic/setup.zsh
cd ros1_ws/dog_msgs_ws
catkin_make
```
#### **步骤 3: 编译 ROS 2 工作区（不含 Bridge）**

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

```shell
# 打开一个全新的终端。
# 在一个 source 了 ROS 2 Humble 主环境的终端里操作
source /opt/ros/humble/setup.zsh
cd ros2_ws

# 安装所有依赖，包括 pymoveit2 的依赖
rosdep install -y -r -i --rosdistro ${ROS_DISTRO} --from-paths src

# 编译 ROS 2 节点
colcon build --symlink-install --packages-skip ros1_bridge
```

#### **步骤 4: 编译 `ros1_bridge`**

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

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

```shell
# 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. **运行编译**:  

```shell
cd <path-to-your-repo>/ros2_ws
colcon build --packages-select ros1_bridge --cmake-force-configure
```

## 5. 运行与验证

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

---

### 5.1 自动化启动 (推荐)

此方法使用 `tmux` 脚本一键启动所有必需的节点（ROS 2 节点和 ROS 1 网桥）。我们为仿真和实体机分别提供了脚本，它们会自动创建并管理所需的终端会话。

#### 5.1.1 仿真 (在 PC 上)

1.  **确保脚本有执行权限** (只需执行一次):
    ```shell
    # 假设脚本在你的仓库根目录
    cd <path-to-your-repo>
    chmod +x start_dog_sim.sh
    ```

2.  **一键启动所有服务**:
    ```shell
    # 在仓库根目录下
    ./start_dog_sim.sh
    ```
    脚本会创建一个名为 `so101_sim` 的 `tmux` 会话，并在后台启动所有仿真进程。

#### 5.1.2 实体机 (在 Orange Pi 上)

1.  **确保脚本有执行权限** (只需执行一次):
    ```shell
    cd <path-to-your-repo>
    chmod +x start_dog.sh
    ```

2.  **一键启动所有服务**:
    ```shell
    # 在 <path-to-your-repo> 目录下
    ./start_dog.sh
    ```
    脚本会创建一个名为 `so101_robot` 的 `tmux` 会话，并在后台启动所有进程。

#### 5.1.3 查看与关闭 Tmux 会话

`tmux` 会话会在后台持续运行。你可以使用以下命令来查看或关闭它：

* **查看节点日志**:
    你可以随时连接到会话来查看所有节点的实时日志（`<session_name>` 替换为 `so101_sim` 或 `so101_robot`）：
    ```shell
    tmux attach -t <session_name>
    ```
    * 会话中会显示左右分屏的布局：
        * **左侧窗格**: 运行所有 ROS 2 节点。
        * **右侧窗格**: 运行 `ros1_bridge`。
    * 要离开会话（让程序在后台继续运行），请按下 `Ctrl+B`，然后松开，再按下 `d`。

* **关闭所有节点**:
    ```shell
    # 关闭仿真会话
    tmux kill-session -t so101_sim

    # 或关闭实体机会话
    tmux kill-session -t so101_robot
    ```

---

### 5.2 手动启动 (用于调试)

如果你需要分别查看每个主要组件的启动过程，可以手动打开两个终端。此方法需要在两个终端中分别启动 ROS 2 主节点和 ROS 1 网桥。

#### 终端 A: 启动 ROS 2 主节点

`source` 你的 ROS 2 环境，然后根据你的目标（仿真或实体机）运行对应的主启动文件。

```shell
# source ROS 2 环境
source <path-to-your-repo>/ros2_ws/install/setup.bash
```

(仿真 - 在 PC 上):

```shell
# 启动所有 ROS 2 仿真节点 (Gazebo, MoveIt, RViz, 控制器)
ros2 launch joystick_alphadog_with_so101_servo start_real_dog_with_sim_arm.launch.py
```
--- 或 ---

(实体机 - 在 Orange Pi 上):

```shell
# 启动所有 ROS 2 节点 (硬件接口、MoveIt、控制器)
ros2 launch joystick_alphadog_with_so101_servo start_real_dog_with_arm.launch.py
```

#### 终端 B: 启动 ROS 1 网桥 (通用)
在终端 A 启动几秒钟后，打开第二个终端，source 混合环境并启动 `ros1_bridge`。此步骤对于仿真和实体机是相同的。

```Shell

# (可选但推荐) 确保 /etc/hosts 中已添加 '10.10.10.10 sport'

# 使用编译网桥时的那个“混合环境”
source <path-to-your-repo>/ros1_ws/dog_msgs_ws/devel/setup.bash
source <path-to-your-repo>/ros2_ws/install/setup.bash

# 启动网桥
ros2 run ros1_bridge dynamic_bridge --bridge-all-topics
```

### 5.3 启动结果
无论使用哪种方式：

在仿真环境中：你应该能看到 Gazebo 和 RViz 窗口。

在实体机上：move_group 和硬件接口节点应正常运行（无 RViz 界面）。

此时，你都可以通过手柄，经由 ROS 2 -> `ros1_bridge` -> ROS 1 的链路来控制机器狗底盘，并同时通过纯 ROS 2 来控制机械臂（仿真或实体）。

## **6. 详细文档**

关于如何在 Ubuntu 22.04 上从零开始编译 ROS 1 Noetic，以及本仓库中所有 `ros1_bridge` 编译问题的详细排查记录，请参考 `doc/` 目录下的教程文档。

## **7. 致谢**

本仓库中使用的 `ros1_bridge` 及其 bridge_mapping 方案，基于社区开发者 [**Doug Smith**](https://github.com/smith-doug) 的杰出工作。