ROS2 教程
前置知识
什么是 ROS2？
ROS2 是用于机器人开发的通信框架和工具集合。机械臂的关节、传感器、摄像头和上位机可以通过 ROS2 互相收发消息并协同工作。
为什么需要 ROS2？
直接给机械臂发送 JSON 指令时，需要手动构造、发送并解析返回数据。ROS2 封装底层通信后，可以实现：
- 用标准接口发布“目标位置”，订阅“当前姿态”。
- 调用现成的运动规划、逆解算法。
- 把机械臂、摄像头、手柄等不同设备连接到同一套消息系统中。
常见概念
| 概念 | 说明 |
|---|---|
| 节点（Node） | 一个独立运行的程序，例如“机械臂控制节点”“摄像头节点”“手柄节点”。 |
| 话题（Topic） | 节点之间传递消息的通道。例如“关节状态”话题上，机械臂节点持续发布当前角度，控制节点订阅后即可获取。 |
| 消息（Message） | 结构化的数据，例如 JointState（关节弧度）、Pose（位置和姿态）。 |
| 服务（Service） | 一问一答的通信方式，例如发送“执行轨迹规划指令”，机械臂回复“成功/失败”。 |
| 启动文件（Launch） | 一次性启动多个节点和配置的脚本，不需要逐个节点打开终端。 |
WSL2 与 ROS2 环境安装配置
WSL2 是 Windows 上运行 Linux 发行版的环境。本教程使用 WSL2 Ubuntu 22.04 + ROS2 Humble 连接实体 RoArm-M3。
本教程不是仿真教程。后续 roarm_driver、RViz2、MoveIt2、键盘控制、指令控制和 MTC 演示都会连接实体 RoArm-M3，执行控制命令会让机械臂真实运动。
安装前确认
右键点击 Windows 开始菜单，选择 Windows PowerShell（管理员）。
先执行：
wsl --list --online
如果输出中出现 Wsl/WSL_E_WSL_OPTIONAL_COMPONENT_REQUIRED，表示 WSL 相关 Windows 可选组件尚未启用。
在管理员 PowerShell 中启用“适用于 Linux 的 Windows 子系统”：
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
启用“虚拟机平台”：
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
执行完成后，重启 Windows。
也可以通过 Windows 图形界面启用功能：打开“控制面板” > “程序” > “启用或关闭 Windows 功能”，勾选“适用于 Linux 的 Windows 子系统”和“虚拟机平台”，确认后重启 Windows。PowerShell 命令和图形界面二选一即可。
安装 WSL2 Ubuntu 22.04
重启后，再次以管理员身份打开 Windows PowerShell。可先尝试更新 WSL：
wsl --update
如果出现 Wsl/UpdatePackage/0x80190193 等更新错误，改用在线源下载更新包：
wsl --update --web-download
wsl --update 用于更新 WSL 程序包。若普通更新失败，优先使用 wsl --update --web-download。如果两条命令都失败，先继续执行后续 wsl --status 和 wsl --list --online 检查；若仍无法列出发行版，再检查网络、代理、防火墙或 Windows 更新策略。
查看 WSL 状态：
wsl --status
如果输出中包含：
Default Version: 2
表示默认版本已是 WSL2。
查看可安装发行版：
wsl --list --online
安装 Ubuntu 22.04：
wsl --install -d Ubuntu-22.04
如果下载异常，使用在线源安装：
wsl --install --web-download -d Ubuntu-22.04
在线源安装成功后，会自动启动 Ubuntu 22.04，并进入初始化界面。根据提示创建默认 Linux 账户，并输入两次密码。密码输入时终端不会显示字符。
示例输出：
Provisioning the new WSL instance Ubuntu-22.04
This might take a while...
Create a default Unix user account: ag
New password:
Retype new password:
passwd: password updated successfully
ag@DESKTOP-911KDB6:/mnt/c/Windows/system32$
上方 ag 只是账户名示例，根据实际需要设置。
看到 ag@DESKTOP-911KDB6:/mnt/c/Windows/system32$ 这类提示符，表示已经进入 Ubuntu 22.04 终端。后续 wsl 检查命令需要回到 Windows PowerShell 执行，先输入：
exit
返回 Windows PowerShell 后，若当前窗口不是管理员 PowerShell，重新以管理员身份打开 Windows PowerShell。将默认 WSL 版本设置为 WSL2：
wsl --set-default-version 2
在管理员 PowerShell 中查看已安装发行版，并确认目标发行版的 VERSION 为 2：
wsl --list --verbose
如果目标发行版的 VERSION 不是 2，在管理员 PowerShell 中执行：
wsl --set-version Ubuntu-22.04 2
进入 Ubuntu 22.04：
wsl -d Ubuntu-22.04
也可以通过 WSL2 图形化终端进入 Ubuntu 22.04：打开 Windows 开始菜单，搜索 Ubuntu 22.04，点击进入。
在WSL2的图形化终端中，在光标处点击鼠标右键，可以实现粘贴Windows中复制的代码。
ROS2 镜像下载
下载 RoArm-M3 ROS2 Humble WSL2 镜像文件：
- 文件名：
RoArm_M3_Final_WSL2_ROS2_Humble.tar - 下载链接：https://pan.baidu.com/s/1LdQwwGZKYS0oiLX4kg8FbA?pwd=WXDZ
- 提取码：
WXDZ
下载完成后，记录镜像文件所在路径。下文使用 E:\WSL_Export\RoArm_M3_Final_WSL2_ROS2_Humble.tar 作为示例路径，按实际保存位置替换。
导入 ROS2 镜像
以管理员身份打开 Windows PowerShell，创建 WSL 镜像存放目录：
mkdir D:\WSL\RoArm_M3
在管理员 PowerShell 中导入下载的 ROS2 镜像：
wsl --import RoArm_M3 D:\WSL\RoArm_M3 E:\WSL_Export\RoArm_M3_Final_WSL2_ROS2_Humble.tar
导入完成后，Windows 开始菜单中会出现 RoArm_M3 终端入口。点击该入口进入镜像终端。
RoArm_M3、D:\WSL\RoArm_M3 和 E:\WSL_Export\RoArm_M3_Final_WSL2_ROS2_Humble.tar 均为示例值，按实际发行版名称、安装目录和镜像文件路径替换。
导入后，在管理员 PowerShell 中确认发行版 VERSION 为 2：
wsl --list --verbose
如果 RoArm_M3 的 VERSION 不是 2，执行：
wsl --set-version RoArm_M3 2
检查 ROS2 与工作区
打开 RoArm_M3 终端，检查 ROS2 Humble 环境：
source /opt/ros/humble/setup.bash
ros2 --help
如果终端输出中包含以下内容，说明 ROS2 命令行工具可正常调用：
ros2 is an extensible command-line tool for ROS 2.
继续检查输出中的 Commands 列表。能看到 launch、node、pkg、run、service、topic 等命令，即可继续后续步骤。
ROS2 Humble 的 ros2 命令不支持 ros2 --version。如果执行后出现 ros2: error: unrecognized arguments: --version，表示 ros2 命令已被识别，但该参数不适用。环境检查以 ros2 --help 和 ros2 pkg list 为准。
继续执行：
ros2 pkg list
如果命令能输出功能包名称列表，说明 ROS2 环境已加载。
若提示 ros2: command not found，重新执行：
source /opt/ros/humble/setup.bash
检查工作区路径：
cd ~/roarm_ws/roarm_ws-ros2-humble
ls
如果工作区中已有 install/ 目录，直接加载工作区环境：
source install/setup.bash
如果缺少 install/ 目录，在工作区内执行构建：
colcon build
source install/setup.bash
终端约定
后续每个新的 RoArm_M3 终端都先执行以下统一初始化命令：
cd ~/roarm_ws/roarm_ws-ros2-humble
source /opt/ros/humble/setup.bash
source install/setup.bash
export ROARM_MODEL=roarm_m3
同一个 RoArm_M3 终端执行一次统一初始化命令即可。若该终端没有关闭，并且已经执行过上述命令，可直接继续运行后续 ROS2 命令。新打开的 RoArm_M3 终端必须重新执行一次。
后续终端分工如下：
- Windows PowerShell：在 Windows 中执行，用于查看
RoArm_M3发行版和挂载 USB 设备。 - RoArm_M3 终端 1：运行
roarm_driver，作为机械臂驱动节点终端。 - RoArm_M3 终端 2：运行 RViz2、MoveIt2、Servo、MTC 等控制例程。
- RoArm_M3 终端 3：运行键盘控制程序、服务调用命令或 MTC 子演示。
后续步骤均在 WSL2 Ubuntu 22.04 发行版中执行，并直接加载 ROS2 Humble 和 RoArm-M3 工作区环境。一次只运行一个控制例程，避免多个节点同时控制实体机械臂。
连接 WSL2 与机械臂 USB 串口
安装 usbipd-win
前置知识
为什么需要 usbipd-win？
RoArm-M3 通过 USB 串口与 ROS2 驱动节点通信。WSL2 中的 Ubuntu 运行在 Windows 的 Linux 子系统环境中，USB 设备会先被 Windows 识别，不能像普通 Linux 主机一样直接出现在 WSL2 中。
usbipd-win 用于把 Windows 主机上的 USB 设备共享并挂载到 RoArm_M3 发行版。挂载成功后，机械臂串口才会在 RoArm_M3 终端中显示为 /dev/ttyUSB0、/dev/ttyACM0 或其它 tty 设备，后续 roarm_driver 才能连接实体机械臂。
前往 usbipd-win 项目发布页，下载最新版 .msi 安装包。下载完成后，双击 .msi 文件，按安装向导完成安装。
安装完成后，以管理员身份打开 Windows PowerShell。执行以下命令：
usbipd --version
如有版本号返回，则确认 usbipd-win 已安装
usbipd-win 安装在 Windows 侧。后续 usbipd list、usbipd bind、usbipd attach 均在 Windows PowerShell 中执行，不在 RoArm_M3 终端中执行。
使用 usbipd-win 挂载 USB 设备
先给机械臂接通电源，打开机械臂驱动板电源开关，再用 USB 线连接机械臂驱动板中间的 Type-C 接口。边缘 Type-C 接口用于雷达通信，不用于 ESP32 通信。
机械臂启动时会回到初始化状态，注意保持周边环境空旷。
先打开 RoArm_M3 发行版，并保持该窗口处于打开状态。可打开 Windows 开始菜单，搜索 RoArm_M3，点击进入 WSL2 图形化终端。也可以在 Windows PowerShell 中执行：
wsl -d RoArm_M3
另开管理员 PowerShell，查看 Windows 识别到的 USB 设备：
usbipd list
在输出中找到机械臂串口设备。实测中设备显示为 Silicon Labs CP210x USB to UART Bridge (COM10)，对应 BUSID 为 4-1。
在管理员 PowerShell 中绑定机械臂 USB 设备：
usbipd bind --busid 4-1
如果输出 Device with busid '4-1' was already shared，表示该 USB 设备已经共享过，可继续执行挂载步骤。
在管理员 PowerShell 中挂载到 RoArm_M3 发行版。usbipd-win 5.x 可使用 --wsl RoArm_M3 指定发行版：
usbipd attach --wsl RoArm_M3 --busid 4-1
如果输出中出现以下信息，表示挂载成功：
usbipd: info: Using WSL distribution 'RoArm_M3' to attach; the device will be available in all WSL 2 distributions.
usbipd: info: Detected networking mode 'nat'.
usbipd: info: Using IP address ... to reach the host.
4-1只是 BUSID 示例，以usbipd list输出为准。- 重新插拔 USB、重启电脑或执行
wsl --shutdown后，通常需要重新执行attach。
- 若执行
usbipd attach --wsl --busid 4-1后提示There is no WSL 2 distribution running，先打开RoArm_M3终端，再执行usbipd attach --wsl RoArm_M3 --busid 4-1。 - 若提示
A specific distribution is no longer required，可继续按输出信息判断是否挂载成功。
在 RoArm_M3 终端中确认串口
在 RoArm_M3 终端中执行：
lsusb
ls /dev/ttyUSB* 2>/dev/null
ls /dev/ttyACM* 2>/dev/null
如果输出中出现 /dev/ttyUSB0，后续命令按 /dev/ttyUSB0 执行。roarm_driver 默认串口也是 /dev/ttyUSB0。若实际设备为 /dev/ttyACM0 或其它 tty 设备，后续权限命令和驱动启动命令都要改为检测到的设备名。若没有输出任何 tty 设备，说明机械臂 USB 串口尚未出现在 RoArm_M3 终端中，返回上一节重新执行 usbipd list、usbipd bind 和 usbipd attach。
给串口设备读写权限：
sudo chmod 666 /dev/ttyUSB0
如果实际设备为 /dev/ttyACM0：
sudo chmod 666 /dev/ttyACM0
密码为之前设置好的 Linux 账户密码，输入时不会显示明文。
如果权限命令报错，重新确认 usbipd-win 是否已 attach 到 RoArm_M3 发行版，并确认 RoArm_M3 终端中实际出现的 tty 设备名。
驱动节点控制现实中的机械臂
roarm_driver 是实体机械臂驱动节点。后续 display、MoveIt2、键盘控制、指令控制和 MTC 测试都依赖该节点。运行成功后，该终端可能没有明显输出，这是正常现象。
启动 roarm_driver 驱动节点
执行后会连接实体机械臂。清空机械臂周围易碎品，远离儿童，确认供电稳定，避免机械臂撞到障碍物或触碰人体。
如果是顺着上一节完成串口确认，当前打开的 RoArm_M3 终端可直接作为 RoArm_M3 终端 1。若该终端尚未执行过统一初始化命令，先执行：
cd ~/roarm_ws/roarm_ws-ros2-humble
source /opt/ros/humble/setup.bash
source install/setup.bash
export ROARM_MODEL=roarm_m3
启动 roarm_driver 驱动节点：
ros2 run roarm_driver roarm_driver
如果实际串口不是 /dev/ttyUSB0，启动时通过 serial_port 参数指定。例如实际设备为 /dev/ttyACM0 时执行：
ros2 run roarm_driver roarm_driver --ros-args -p serial_port:=/dev/ttyACM0
若启动时报错 could not open port /dev/ttyUSB0 或 No such file or directory: '/dev/ttyUSB0'，表示 roarm_driver 没有找到默认串口。先回到在 RoArm_M3 终端中确认串口，确认 /dev/ttyUSB0 已出现并完成权限设置，再重新执行本节命令。
若出现 ROARM_MODEL 相关报错，重新执行统一初始化命令，并确认其中包含：
export ROARM_MODEL=roarm_m3
RoArm_M3 终端 1 是驱动节点终端。后续测试都要保持该终端运行，不要关闭。若不小心关闭了 RoArm_M3 终端 1，重新打开 RoArm_M3 终端 1，并按本节上方命令重新运行。
ROS2 RViz2 显示并控制实体机械臂
前置知识
什么是 RViz2？
RViz2 是 ROS2 的可视化工具，可显示机械臂模型、关节状态、规划路径等信息。本节中的 display.launch.py 不只是显示模型，它会让实体机械臂跟随关节界面运动。
启动 RViz2 模型关节界面
执行 display.launch.py 后，实体机械臂会真实运动。清空机械臂周围易碎品，远离儿童，确认供电稳定，避免机械臂撞到障碍物或触碰人体。
保持 RoArm_M3 终端 1 的 roarm_driver 运行。若 RoArm_M3 终端 1 已关闭或 roarm_driver 已结束，先按启动 roarm_driver 驱动节点重新启动，再继续本节。打开 RoArm_M3 终端 2，执行统一初始化命令：
cd ~/roarm_ws/roarm_ws-ros2-humble
source /opt/ros/humble/setup.bash
source install/setup.bash
export ROARM_MODEL=roarm_m3
启动 RViz2 模型关节界面：
ros2 launch roarm_description display.launch.py
display.launch.py 启动后，RViz2 会打开模型显示界面和 Joint State Publisher 关节控制窗口。
界面主要看三处：
- 左侧 Displays：
Global Status: Ok、Fixed Frame: OK、RobotModel Status: Ok表示模型加载正常。 - 中间 3D 视图区：显示 RoArm-M3 模型，模型姿态会跟随关节滑块变化。
- Joint State Publisher 窗口：拖动
base_link_to_link1、link1_to_link2、link2_to_link3、link3_to_link4、link4_to_link5、link5_to_gripper_link等滑块控制对应关节。 - 视角操作：在 3D 视图区中，左键拖动旋转视角，右键拖动平移视角，滚轮缩放视图，中键拖动垂直平移。
关节滑块对应关系：
| 滑块名称 | 对应部位 |
|---|---|
base_link_to_link1 | 底座旋转 |
link1_to_link2 | 肩部关节 |
link2_to_link3 | 肘部关节 |
link3_to_link4 | 腕部俯仰 |
link4_to_link5 | 腕部旋转 |
link5_to_gripper_link | 夹爪关节 |
拖动滑块或点击 Randomize 后，Joint State Publisher 会发布 /joint_states，roarm_driver 订阅关节状态后，再把关节角转换为 JSON 控制指令发送给实体机械臂。因此，实体机械臂会跟随 RViz2 模型同步运动。
Randomize 会让实体机械臂随机运动到一个位置，有碰撞桌面或周围物体的风险，建议断开实体机械臂连接再测试。
MoveIt2 拖拽交互
前置知识
什么是 MoveIt2？
MoveIt2 是 ROS2 下的机械臂运动规划框架，可在 RViz2 中拖拽末端位姿、规划路径，并通过 roarm_driver 将轨迹发送给实体机械臂。
启动 MoveIt2 启动文件
启动 MoveIt2 前，先在 RoArm_M3 终端 2 按 Ctrl+C 结束 display.launch.py。保持 RoArm_M3 终端 1 的 roarm_driver 运行。若 RoArm_M3 终端 1 已关闭或 roarm_driver 已结束，先按启动 roarm_driver 驱动节点重新启动，再继续本节。
执行 MoveIt2 启动命令后，实体机械臂会运动到 MoveIt2 初始姿态。清空机械臂周围易碎品，远离儿童，确认供电稳定，避免机械臂撞到障碍物或触碰人体。
如果 RoArm_M3 终端 2 未关闭，并且刚才只是按 Ctrl+C 结束了 display.launch.py，ROS2 环境仍然有效，可直接执行下一条 MoveIt2 启动命令。若 RoArm_M3 终端 2 是新打开的，或不确定当前环境是否已加载，先执行统一初始化命令：
cd ~/roarm_ws/roarm_ws-ros2-humble
source /opt/ros/humble/setup.bash
source install/setup.bash
export ROARM_MODEL=roarm_m3
启动 MoveIt2 启动文件：
ros2 launch roarm_moveit roarm_moveit.launch.py
MoveIt2 启动后，RViz2 会显示 MotionPlanning 面板和机械臂模型。
界面主要看三处：
- 左侧 Displays：
Fixed Frame为base_link，Global Status: Ok表示显示状态正常。 - 左下 MotionPlanning 面板：
Planning Group选择规划组，Plan只规划轨迹，Plan & Execute会规划并执行轨迹。hand用于机械臂末端位姿规划，gripper用于夹爪open/close。 - 中间 3D 视图区：橙色模型为当前机械臂状态，末端彩色控制球用于拖拽目标位姿。
基本操作：
- 在 MotionPlanning 面板中将
Planning Group设为hand。 - 在 3D 视图区拖动末端彩色控制球，改变目标位置或姿态。
- 点击
Plan查看规划轨迹。 - 确认轨迹安全后，点击
Plan & Execute执行。 - 需要复位时，将
Goal State设为home，再点击Plan & Execute。
点击 Plan & Execute 会让实体机械臂执行规划轨迹。确认机械臂运动范围内没有障碍物或人体。
夹爪测试时，将 Planning Group 改为 gripper，在 Goal State 中选择 open 或 close，再点击 Plan & Execute。执行前确认夹爪附近没有手指、线材或易碎品。
键盘控制机械臂
键盘控制前，先结束上一项 MoveIt2 拖拽交互例程。保持 RoArm_M3 终端 1 的 roarm_driver 运行。若 RoArm_M3 终端 1 已关闭或 roarm_driver 已结束，先按启动 roarm_driver 驱动节点重新启动，再继续本节。
启动 MoveIt2 Servo 启动文件
启动 MoveIt2 Servo 启动文件后，实体机械臂可能进入控制初始状态。清空机械臂周围易碎品，远离儿童，确认供电稳定，避免机械臂撞到障碍物或触碰人体。
在 RoArm_M3 终端 2 执行统一初始化命令：
cd ~/roarm_ws/roarm_ws-ros2-humble
source /opt/ros/humble/setup.bash
source install/setup.bash
export ROARM_MODEL=roarm_m3
启动 MoveIt2 Servo 启动文件：
ros2 launch roarm_moveit_servo servo_control.launch.py
启动键盘控制程序
按键会直接控制实体机械臂运动。确认机械臂运动范围内没有障碍物、儿童或人体。
打开 RoArm_M3 终端 3，执行统一初始化命令：
cd ~/roarm_ws/roarm_ws-ros2-humble
source /opt/ros/humble/setup.bash
source install/setup.bash
export ROARM_MODEL=roarm_m3
启动键盘控制程序：
ros2 run roarm_moveit_servo keyboardcontrol
启动成功后，RoArm_M3 终端 3 会显示键盘控制说明。RoArm_M3 终端 2 中的 MoveIt2 Servo 启动文件需要保持运行，RoArm_M3 终端 3 中的键盘控制程序负责接收按键输入。
键盘控制程序分为关节点动和笛卡尔点动两类。先确认 RoArm_M3 终端 3 为当前输入焦点，再按键控制。不同版本的终端提示可能略有差异，实际操作以启动后终端打印的按键说明为准。
通用按键：
| 按键 | 动作 |
|---|---|
| J | 选择关节点动模式 |
| T | 选择笛卡尔点动模式 |
| R | 反转点动方向 |
| W / E | 在规划坐标系和末端执行器坐标系之间切换 |
| Q | 退出键盘控制 |
关节控制按键：
| 按键 | 动作 |
|---|---|
| 1 | 底座旋转关节点动 |
| 2 | 肩部关节点动 |
| 3 | 肘部关节点动 |
| 4 | 腕部俯仰关节点动 |
| 5 | 腕部旋转关节点动 |
| G | 控制夹爪 |
笛卡尔控制按键：
| 按键 | 动作 |
|---|---|
| ← / → | 笛卡尔方向点动 |
| ↑ / ↓ | 笛卡尔方向点动 |
| , / . | 笛卡尔方向点动 |
保持 RoArm_M3 终端 3 为当前输入焦点，按键才会被键盘控制程序接收。
指令控制机械臂
指令控制前，先结束上一项控制例程。保持 RoArm_M3 终端 1 的 roarm_driver 运行。若 RoArm_M3 终端 1 已关闭或 roarm_driver 已结束，先按启动 roarm_driver 驱动节点重新启动，再继续本节。
启动指令控制启动文件
启动指令控制启动文件和执行后续服务调用会控制实体机械臂运动。清空机械臂周围易碎品，远离儿童，确认供电稳定，避免机械臂撞到障碍物或触碰人体。
在 RoArm_M3 终端 2 执行统一初始化命令：
cd ~/roarm_ws/roarm_ws-ros2-humble
source /opt/ros/humble/setup.bash
source install/setup.bash
export ROARM_MODEL=roarm_m3
启动指令控制启动文件：
ros2 launch roarm_moveit_cmd command_control.launch.py
打开 RoArm_M3 终端 3，执行统一初始化命令：
cd ~/roarm_ws/roarm_ws-ros2-humble
source /opt/ros/humble/setup.bash
source install/setup.bash
export ROARM_MODEL=roarm_m3
执行服务调用前，可先查看接口字段。后续示例以接口输出字段为准：
ros2 interface show roarm_msgs/srv/GetPoseCmd
ros2 interface show roarm_msgs/srv/MoveJointCmd
ros2 interface show roarm_msgs/srv/MoveLineCmd
ros2 interface show roarm_msgs/srv/MoveCircleCmd
获取当前位置
该命令只读取当前位姿：
ros2 service call /get_pose_cmd roarm_msgs/srv/GetPoseCmd
控制机械臂末端运动到指定位置
执行 /move_joint_cmd 会让实体机械臂运动。确认机械臂运动路径内没有障碍物或人体。
ros2 service call /move_joint_cmd roarm_msgs/srv/MoveJointCmd "{x: 0.3, y: 0, z: 0.1, roll: 0.2, pitch: 0.2, yaw: 0}"
x、y、z 为目标位置坐标，单位为 m。roll、pitch、yaw 为末端执行器旋转角度，单位为 rad。
控制机械臂末端沿直线运动
执行 /move_line_cmd 会让实体机械臂沿直线轨迹运动。确认机械臂运动路径内没有障碍物或人体。
ros2 service call /move_line_cmd roarm_msgs/srv/MoveLineCmd "{x: 0.2, y: 0.2, z: 0.1}"
x、y、z 为目标位置坐标，单位为 m。
控制夹爪到指定弧度位置
执行 /gripper_cmd 会让实体夹爪运动。确认夹爪附近没有手指、线材或易碎品。
ros2 topic pub /gripper_cmd std_msgs/msg/Float32 "{data: 0.5}" -1
data 为夹爪目标弧度，单位为 rad，范围按原例程为 0.0~1.5。
控制 LED
该命令用于控制夹爪上的 LED，data 为亮度数值，范围为 0~255：
ros2 topic pub /led_ctrl std_msgs/msg/Float32 "{data: 0}" -1
在固定高度上画圆
如需在 RViz2 中查看末端轨迹，可在 RViz2 中点击 Add，添加 RobotModel。
在 RobotModel 选项卡内，将 Description Topic 设为 /robot_description。
在 Links 选项中找到 hand_tcp，展开后勾选 Show Trail，用于查看末端关节运动轨迹。
执行 /move_circle_cmd 会让实体机械臂沿圆弧轨迹运动。确认机械臂运动路径内没有障碍物或人体。
ros2 service call /move_circle_cmd roarm_msgs/srv/MoveCircleCmd "{x0: 0.2, y0: 0.1, z0: 0.2, x1: 0.2, y1: 0.2, z1: 0.2}"
x0、y0、z0 为中心点坐标，x1、y1、z1 为目标点坐标，单位为 m。
MoveIt MTC 规划轨迹
前置知识
MoveIt MTC 演示的三种模式
MTC（Task Constructor，任务构造器）会把动作拆分为多个阶段执行。本节测试 cartesian、cartesian_modular 和 pick_place 三个演示。
MTC 演示前，先结束上一项控制例程。保持 RoArm_M3 终端 1 的 roarm_driver 运行。若 RoArm_M3 终端 1 已关闭或 roarm_driver 已结束，先按启动 roarm_driver 驱动节点重新启动，再继续本节。MTC 同样会驱动实体机械臂，一次只运行一个 run.launch.py。
启动 MTC 演示界面
启动 MTC 演示界面后，实体机械臂可能进入演示初始状态。清空机械臂周围易碎品，远离儿童，确认供电稳定，避免机械臂撞到障碍物或触碰人体。
在 RoArm_M3 终端 2 执行统一初始化命令：
cd ~/roarm_ws/roarm_ws-ros2-humble
source /opt/ros/humble/setup.bash
source install/setup.bash
export ROARM_MODEL=roarm_m3
启动 MTC 演示界面：
ros2 launch roarm_moveit_mtc_demo demo.launch.py
打开 RoArm_M3 终端 3，执行统一初始化命令：
cd ~/roarm_ws/roarm_ws-ros2-humble
source /opt/ros/humble/setup.bash
source install/setup.bash
export ROARM_MODEL=roarm_m3
笛卡尔演示
执行 cartesian 演示会让实体机械臂运动。确认机械臂运动路径内没有障碍物或人体。
ros2 launch roarm_moveit_mtc_demo run.launch.py exe:=cartesian
在界面中选择对应的完整路径后，点击 Exec 执行 Demo。
笛卡尔模块演示
切换演示前，在 RoArm_M3 终端 3 按 Ctrl+C 结束上一个 run.launch.py。
执行 cartesian_modular 演示会让实体机械臂运动。确认机械臂运动路径内没有障碍物或人体。
ros2 launch roarm_moveit_mtc_demo run.launch.py exe:=cartesian_modular
在界面中选择对应的完整路径后，点击 Exec 执行 Demo。
Pick Place 演示
切换演示前，在 RoArm_M3 终端 3 按 Ctrl+C 结束上一个 run.launch.py。
执行 pick_place 演示会让实体机械臂运动。确认机械臂运动路径内没有障碍物或人体。
ros2 launch roarm_moveit_mtc_demo run.launch.py exe:=pick_place
在界面中选择对应的完整路径后，点击 Exec 执行 Demo。
