> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 AMR 服务运行基本的 AMR 功能

> qrb_ros_amr_service 是一个 ROS2 包套件，旨在管理 Qualcomm 机器人平台上的 AMR 行为。

主要特性包括：

* P2P 导航请求。

* 路径跟随。

* 建图服务。

* 电量低时自动返回充电站。

## 软件结构

下图展示了自主移动机器人（AMR）服务的结构。

<Frame caption="AMR 服务的软件结构。">
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/SDKs/QIR-SDK-Ubuntu/images/image34.png" style={{width: "70%"}} alt="Layered software structure of the AMR service, showing the ROS packages, manager libraries, and controller modules." />
</Frame>

## AMR 服务中使用的 ROS 节点和模块

下表列出了 AMR 服务中使用的 ROS 节点和模块，以及每个的功能。

| 节点名                                       | 功能                                                                                                                                       |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `qrb_ros_amr`                             | ROS2 包，实现用于导航、建图和 AMR 状态反馈的动作/服务客户端和服务器、发布者和订阅者。                                                                                         |
| `qrb_amr_manager`                         | C++ 库，提供用于 AMR 状态管理和充电逻辑的 API。<br /><br />- Low Power Manager：电量 `< 2.2V` 时返回充电站。<br />- Manager：库接口。<br />- State Machine：管理 AMR 状态和动作。 |
| Follow Path Service & Follow Path Manager | 用于路径跟随导航的 ROS2 包                                                                                                                         |
| Robot Base & Robot Base Controller        | 用于 AMR 底座控制的 ROS2 包。                                                                                                                     |
| 2D lidar SLAM ROS 和 2D lidar SLAM         | 提供建图和定位。                                                                                                                                 |
| Nav2                                      | 提供 P2P 导航。                                                                                                                               |

## `qrb_ros_amr_service` API

下表列出了 `qrb_ros_amr_service` 公开的接口，包括每个接口的名称、类型和说明。

| 接口             | 名称                | 类型                                 | 说明         |
| -------------- | ----------------- | ---------------------------------- | ---------- |
| Publisher      | `amr_status`      | `qrb_ros_amr_msgs::msg::AMRStatus` | 发布 AMR 状态。 |
| Subscriber     | `test`            | `std_msgs::msg::Int16`             | 接收调试信息。    |
| Subscriber     | `debug_exception` | `std_msgs::msg::Int16`             | 接收模拟的异常信息。 |
| Service Server | `sub_cmd`         | `qrb_ros_amr_msgs::srv::SubCmd`    | 处理子命令请求。   |
| Service Server | `amr_mapping`     | `qrb_ros_amr_msgs::srv::Mapping`   | 处理建图请求。    |
| Service Server | `api`             | `qrb_ros_amr_msgs::srv::API`       | 处理 API 请求。 |
| Action Server  | `cmd`             | `qrb_ros_amr_msgs::action::Cmd`    | 处理导航命令。    |

## 前提条件

你已根据[安装 QIR SDK](./install-the-qir-sdk)完成设备设置，并在设备上安装了 ROS2 Jazzy 和 Qualcomm Intelligent Robotics (QIR) SDK。

## 开箱即用运行 AMR 服务

<Note>
  除非另有说明，否则在设备上运行以下命令。
</Note>

<Steps>
  <Step title="安装 AMR 服务包">
    ```bash Install the AMR service packages theme={null}
    sudo apt install ros-jazzy-nav2-msgs
    sudo apt install ros-jazzy-nav-2d-msgs
    sudo apt install ros-jazzy-qrb-ros-amr-msgs
    sudo apt install ros-jazzy-qrb-ros-navigation-msgs
    sudo apt install ros-jazzy-qrb-amr-manager
    sudo apt install ros-jazzy-qrb-ros-amr
    ```
  </Step>

  <Step title="设置 2D 激光雷达 SLAM">
    运行[开箱即用 2D 激光雷达 SLAM](./enable-2d-lidar-slam-with-cartographer_node-and-cartographer_occupancy_grid_node#run-out-of-the-box-2d-lidar-slam) 的步骤 1 到步骤 5 来启动 2D 激光雷达同步定位与建图 (SLAM)，跳过步骤 6。
  </Step>

  <Step title="设置 follow-path 服务">
    根据[开箱即用运行 qrb\_ros\_follow\_path 服务](./test-follow-path-with-the-qrb_ros_follow_path-service#run-out-of-the-box-qrb_ros_follow_path-service) 的步骤 1 到步骤 3 设置 follow-path 服务。
  </Step>

  <Step title="安装 nav2 包并设置 nav2">
    ```bash Install and launch nav2 theme={null}
    sudo apt install ros-jazzy-navigation2 ros-jazzy-nav2-bringup ros-jazzy-nav2-route
    ros2 launch nav2_bringup navigation_launch.py
    ```
  </Step>

  <Step title="在设备上设置示例环境">
    ```bash Launch the AMR service theme={null}
    source /opt/ros/jazzy/setup.bash
    source install/setup.bash
    ros2 launch qrb_ros_amr qrb_ros_amr_bringup.launch.py
    ```
  </Step>

  <Step title="测试 AMR 服务">
    * 你可以根据 `qrb_ros_amr_service` API 表实现一个 ROS 节点来完成建图、路径跟随和 P2P 导航。

    * 你也可以使用这些 ROS 命令来完成建图、路径跟随和 P2P 导航。

    a. 在主机（Ubuntu 24.04）上安装 `rqt-robot-steering`

    ```bash theme={null}
    sudo apt install ros-jazzy-rqt-robot-steering
    ```

    b. 在主机上运行 `rqt-robot-steering`。

    ```bash theme={null}
    ros2 run rqt_robot_steering rqt_robot_steering
    ```

    c. 初始化 AMR。

    ```bash theme={null}
    ros2 service call /api qrb_ros_amr_msgs/srv/API "{api_id: 1}"
    ```

    d. 开始建图。

    ```bash theme={null}
    ros2 service call /amr_mapping qrb_ros_amr_msgs/srv/Mapping "{cmd: 2}"
    ```

    e. 在主机上安装并设置 `rviz2`。

    ```bash theme={null}
    sudo apt install ros-jazzy-rviz2
    ros2 run rviz2 rviz2
    ```

    f. 使用 `rqt-robot-steering` 控制机器人底座的运动。

    g. 停止建图。

    ```bash theme={null}
    ros2 service call /amr_mapping qrb_ros_amr_msgs/srv/Mapping "{cmd: 3}"
    ```

    底座开始旋转，经过一段时间后停止旋转。地图在 `rviz` 上正常显示。

    h. 启动 P2P 导航。

    ```bash theme={null}
    ros2 action send_goal /cmd qrb_ros_amr_msgs/action/Cmd "{command: 3, goal: {header: {frame_id: 'map'}, pose: {position: {x: 0.0, y: 0.0, z: 0.0}, orientation: {x: 0.0, y: 0.0, z: 0.0, w: 2.0}}}}"
    ```

    该位姿可以用地图的真实值替换。

    i. 暂停当前 P2P 导航。

    ```bash theme={null}
    ros2 service call /sub_cmd qrb_ros_amr_msgs/srv/SubCmd "{ subcommand: 2}"
    ```

    j. 恢复当前 P2P 导航。

    ```bash theme={null}
    ros2 service call /sub_cmd qrb_ros_amr_msgs/srv/SubCmd "{ subcommand: 3}"
    ```

    k. P2P 导航完成后，根据 follow-path 开箱即用步骤的第 4 步（a 到 j）设置路径点和虚拟路径。

    l. 使用 `rqt-robot-steering` 将机器人底座移动到路径点（`id = 2`）。

    m. 启动从路径点（`id = 2`）到路径点（`id = 1`）的路径跟随操作。

    ```bash theme={null}
    ros2 action send_goal /cmd qrb_ros_amr_msgs/action/Cmd "{command: 6, goal_id: 1}"
    ```
  </Step>
</Steps>

## 从源码构建并运行 AMR 服务

当你需要修改服务代码时，可以从源码构建自主移动机器人（AMR）服务。设备端步骤包括安装依赖、克隆源码仓库、构建包并运行结果。

### 设备步骤

<Steps>
  <Step title="安装依赖">
    ```bash Install the dependencies theme={null}
    sudo apt install ros-jazzy-nav2-msgs
    sudo apt install ros-jazzy-nav-2d-msgs
    ```
  </Step>

  <Step title="下载并构建">
    ```bash Download and build theme={null}
    source /opt/ros/jazzy/setup.bash
    git clone https://github.com/qualcomm-qrb-ros/qrb_ros_amr_service.git
    git clone https://github.com/qualcomm-qrb-ros/qrb_ros_interfaces.git
    colcon build
    ```
  </Step>

  <Step title="运行并测试">
    根据[开箱即用运行 AMR 服务](./run-basic-amr-functionality-with-the-amr-service#run-the-out-of-the-box-amr-service)的步骤 2 到 6 运行并测试。
  </Step>
</Steps>