Skip to content

关于M7 ​

产品介绍 ​

M7是 Robotera 开发的最新半身通用人形机器人,具有业界顶尖的 42个自由度,最大 95Nm 峰值扭矩和 4.20 rad/s 峰值转速的电机,搭配有一双 12 个主动自由度的灵巧手,配合上强大的 275TOPS 平台算力,可实现遥操作,模仿学习,机器人大模型等多种算法,在科研,工厂,商业,家庭等场景落地 AGI。

概览 ​

机器人整体形态如下

图片

整机参数 ​

规格参数 ​

M7 规格参数
尺寸直立尺寸:底座尺寸632*632mm,高度1713-1760mm可调
手臂总长度717mm x 2
单臂负载:10Kg
自由度42个(手臂7自由度 x 2,腰部2自由度,脖子2自由度,灵巧手12自由度 x 2)
整机重量约70kg
手臂末端****速度3m/s
手臂末端精度0.02mm
控制和感知能力80 TOPS(x86)+275 TOPS(Orin AGX)
感知传感器配置深度相机 语音模块
灵巧手具备类人手外形,单手主动12个自由度
通信接口Ethernet、USB 4.0、Wi-Fi 6、USB-C

关节与电机 ​

图片

各个关节峰值扭矩和速度如下:

positionPeak torque (Nm)speed (rad/s)
shoulder pitch954
shoulder roll
arm yaw
elbow pitch
elbow yaw354
wrist roll
wrist pitch
neck pitch354
neck yaw
waist pitch1844
waist yaw

各关节角度范围:

机器人部位对应关节角度范围
手臂肩pitch:±160° 肩roll:-32°~145° 肩yaw:-250~70° 肘:-135°~40° 腕yaw:±160° 腕ptich:±45° 腕roll:±90°
颈部颈pitch:-10°~31° 颈yaw:-60°~60°
腰部腰pitch:-10°~90° 腰yaw:-90°~90°

机载计算资源连接图 ​

白板/架构图

机载计算资源的硬件和系统参数表:

计算单元名称:AMD 锐龙 AI 9 HX 370
CPU12核
内存32GB
硬盘1TB SSD

(选配ORIN)

计算单元名称:Jetson Orin AGX 64GB
AI 性能275 TOPS
GPU搭载 64 个 Tensor Core 的 2048 核 NVIDIA Ampere 架构 GPU
GPU 最大频率1.3 GHz
CPU12 核 Arm® Cortex®-A78AE v8.2 64 位 CPU 3MB L2 + 6MB L3
CPU 最大频率2.2 GHz
显存64GB 256 位 LPDDR5 204.8GB/s

​

操作指南 ​

开箱和启动 ​

开箱

机器人的开箱指南通常包括以下几个步骤:

  • 检查包装:在开箱前,首先要检查包装盒是否有损坏,以确保产品在运输过程中没有遭到损害 。
  • 取出物品:打开包装盒,按照说明书的指导,逐一取出产品及其配件,如电源、工装等 。

连接到机器人 ​

在机器人的hip roll关节下查找产品的WiFi名:L_v3_BOTXX

在网络中搜索“L_v3_BOTXX”并连接到机身内路由器上。

注意:5G WiFI 出来的时间会更晚。

wifi的默认密码为xbot123456

内部固定地址修改限制:192.168.8.100 为机器人内部固定通信地址,其中 “8.100” 段为预设固定配置,禁止修改;修改将导致机器人通信异常、功能无法正常运行。

查看机器人管理后台 ​

打开浏览器,输入地址:http://192.168.8.100:1888 ,打开机器人控制后台,可在控制后台中查看机器人的各项信息内容。

创建访问密码 ​

创建密码 ​

图片

XOS 的初始安全设置界面,用于为一站式机器人控制中心配置访问密码,保障系统与设备的权限安全。

双重认证 ​

图片

XOS 的双重认证设置界面,进一步加固机器人控制中心的访问安全,为系统提供密码之外的第二层防护。

主页 ​

图片

1、通过产品主页展示机器人整机状态信息,实时了解机器人当前状况。

2、展示机器人整机信息:

机器人状态:

INIT:开机启动后的状态

IDLE:机器人硬件连接的状态

READY:机器人初始化的状态

ACTIVE:机器人进入任务接受的状态

ERROR:机器人发生错误的状态

机器人型号:当前机器人的型号

灵巧手型号:当前机器人灵巧手型号

机器人SN:当前机器人的SN

NUC的IP:当前机器人NUC的IP地址

XOS的版本号:当前机器人XOS的版本

CPU使用率: 当前CPU的总体使用率曲线

机器人模型:当前型号的机器人仿真模型

3、实时错误信息:如果有告警或错误发生,机器人仿真对应告警或错误关节会变成红色。

机器人概览 ​

日志管理 ​

图片

1、日志管理模块具备系统化的日志采集、存储与可视化展示能力。

2、可按系统架构层级对各功能模块的运行日志进行分类归集。

3、通过交互式界面提供展示及结构化解析功能。

4、支持用户根据业务需求手动下载指定模块的日志文件,满足系统调试、问题追溯等日志管理需求。

CPU 频率看板 ​

图片

1、该功能支持实时查看 CPU 总体频率曲线,通过可视化图形界面动态展示cpu所有内核综合频率随时间的变化趋势,横轴为时间,纵轴精确显示频率值(GHz)。支持实时动态刷新,用户直观监控 CPU 性能波动、分析频率调度策略并排查异常状态。

2、CPU:支持cpu、cpu_max、cpu_min、cpu_avg 以及各个cpu内核的选择,可单选、多选,多选支持全选

3、时间区间,支持24小时区间查看。

4、重置功能:重置页面的查询条件,包括已选择的 CPU、时间,点击重置后,清空查询条件。

5、关闭、开启刷新功能:曲线页面,默认会实时动态刷新,关闭后不刷新,开启后,实时获取最新的数据和绘制曲线。

异常状态 ​

图片

1、支持实时监控机器人各模块的运行异常状态,支持弹窗通知与语音播报,可以快速定位并处理故障。

核心功能:

  • 异常通知:支持弹窗通知和语音播报两种提醒方式,默认开启。
  • 异常列表:清晰展示异常模块、名称、编码、部位、描述及等级,便于快速识别问题。
  • 快速处理:每条异常提供 “查看解决方案” 入口,直接跳转至对应处理指引。

操作说明:

2、开启 / 关闭通知

  • 点击 “弹窗通知” 或 “语音播报” 右侧的开关,即可切换开启 / 关闭状态。

3、查看异常详情

  • 在列表中查看异常的模块、部位、等级等关键信息。
  • 异常等级分为:致命错误,严重错误,错误,警告,提示,信息。

4、处理异常

  • 点击异常行右侧操作栏的 “查看解决方案”,获取官方处理步骤。

机器人管理 ​

音色和音量 ​

图片

1、支持0-100% 的音量调节区间,用户可通过滑动调节条或加减按键精准控制机器人的发声音量,系统默认记忆上次设置参数,重启后自动恢复用户偏好设置。

2、支持用户自主选择机器人的音频输出设备,系统将自动扫描并列出当前可用的声卡列表(包括内置声卡、外接 USB 声卡等),可通过下拉菜单快速切换输出设备。

机器人数控台 ​

详细使用方式参考xviz 使用说明文档

综合数据中心 ​

图片

XOS 的机器人控制台 - 综合数据中心,是为机器人运维人员打造的一站式数据可视化与仿真调试平台,可实现机器人关节状态等运行数据的实时监控、故障诊断、数据录制与仿真验证,为机器人调试、运行分析和问题定位提供全流程支撑。

数据监控中心 ​

图片

XOS 的数据监控中心,是机器人运行数据的实时可视化看板,支持以折线图等形式对关节状态(如手臂、肘部关节位置)等关键话题数据进行实时采集与展示,帮助直观掌握机器人运行状态、快速识别数据异常与波动。

录制中心 ​

图片

  • 实现 ROS 话题(含 Xos 专属话题)灵活订阅、自定义时段录制 / 导出,支持一键快速导出与精准时段导出,适配 Xos 数据格式与便携设备小屏布局,简化数据采集与导出操作。

仿真中心 ​

图片

XOS 仿真中心-孪生模式,通过将机器人真实运行数据与虚拟模型实时联动,实现 “虚实同态” 的可视化调试与验证,支持关节状态实时映射、运动轨迹复现与物理仿真校验,帮助开发者直观验证控制逻辑、提前排查风险,大幅提升调试效率与安全性。

应用管理 ​

图片

1、该页面提供对系统的拓展应用的上传、安装、以及启动的操作。

2.上传应用的压缩包,支持文件包拖拽到页面,支持系统文件选择,上传成功后,点击"上传并安装"按钮,安装应用。

3、安装成功后应用列表新增一个应用,点击应用后打开应用。

系统升级 ​

  1. 本功能用于管理机器人系统及手控器的软件版本,支持云端检测更新与手动升级两种方式。

版本信息展示: ​

1.版本号:查看当前系统版本(RobotOS)。

2.版本详情:点击 【版本详情】可查看每个模块版本号。

图片

升级包获取方式: ​

  • 云端检测:

1.一键从云端服务器检测并获取最新版本。

2.点击 “检查更新” 按钮,系统将重新从云端检测最新版本。

图片

3.下载

点击“下载升级包vX.X.X.X” 按钮开始下载,下载过程中支持删除。

图片

图片

  • 手动上传升级包

支持本地升级包上传,用于离线或指定版本升级。

图片

升级 ​

升级前确认事项

  1. 机器人需处于安全静止状态。
  2. 升级过程中机器人将自动重启,期间请勿操作设备。

确认满足以上条件后,点击 “升级到 vX.X.X” 按钮启动升级。升级进行中请勿断电或操作机器人,防止升级异常。

图片

升级完成判断

  1. 升级启动后系统将自动执行升级,待界面显示 “升级完成” 字样,即表示本次升级成功。全程请勿关闭电源。

图片

安全中心 ​

设置密码 ​

图片

XOS 安全中心的设置密码功能,支持用户更新登录密码(6-8 位字母或数字),也可关闭密码保护,实现机器人控制中心访问权限的灵活管理。

身份验证器管理 ​

图片

XOS 安全中心的身份验证器管理功能,支持用户添加、重命名、删除 TOTP 验证设备,最多可绑定 5 个,方便用户灵活管理双重认证的备用设备,保障系统访问安全。

登录历史 ​

图片

XOS 安全中心的登录历史功能,可展示最近 50 条登录记录,包含登录 IP、时间、结果与客户端信息,帮助用户追溯访问行为、及时发现异常登录风险。

ROS-IP管理 ​

图片

XOS安全中心的ROS-IP白名单管理功能,用于配置CycloneDDS通信的可信IP地址,支持添加、删除IP,仅允许白名单内设备与机器人系统通信,提升ROS通信的安全性与可控性。

防火墙管理 ​

图片

XOS 安全中心的防火墙管理功能,用于管理 nftables INPUT 链的端口允许规则,支持查看系统内置规则与自定义添加新规则,管控机器人系统的网络端口访问,强化网络安全防护。

机器人内网遥操作 ​

图片

上传遥操作授权文件 ​

1、上传遥操作授权文件,上传并校验成功可以使用遥操作功能。

2、支持手动配置摄像头参数。

图片

打开遥操作 app ​

1、打开遥操作 app ,进入主页面,机器人开始启动,启动完成抬起双臂,进入等待连接VR 设备状态。

2、VR 设备连接成功后通过星遥App开始遥操作。

3、点击退出遥操作,页面返回到 xos ,机器人退出遥操作状态。

图片

连接 MetaQuest ​

1、开启 Meta Quest 设备,进入系统设置。

2、选择网络连接方式:

有线连接:通过数据线将 Meta Quest 与机器人直接连接。

WiFi 连接:找到机器人对应的 WiFi,输入密码完成连接。

3、在 Meta Quest 应用列表中找到「星遥 App」图标,点击即可启动。

详细使用方式参考:星遥App软件使用说明

机器人数据采集 ​

星动数据管理平台使用说明

紧急停止 ​

M7 提供紧急停止遥控器,以便在出现意外状况的时候及时切断电源,确保安全。

下图是急停遥控器:

图片

按一次A键会关闭机载电脑的电源,再按一次A键恢复

按一次D键会关闭关节电机电源,再按一次D键恢复

exclamation 重要,请确保在调试时准备好急停遥控器,如果遇到紧急情况请按D,避免异常发生时无法关闭电源

开发指南 ​

整机软件架构 ​

图片

关节坐标轴 ​

SDK调用说明 ​

M7使用Ros2 Humble 和整机进行交互,开发者可以通过有线/无线网络连接到机器人,或者通过登录到开发者容器中编写程序运行和主机系统进行通信。

Ros2 domain: 211

如果希望通过另外一台主机连接机器人,进行控制:

  1. 通过有线连接机器人,或者直接连接机器人WIFI
  2. 前提条件:主机有 ros-humble + cyclonedds 环境
  3. 需要在自己主机部署机器人所使用的消息
shell
git clone https://github.com/roboterax/teleop_client.git
cd teleop_client
colcon build
source install/setup.bash
  1. 设置环境变量
shell
export ROS_DOMAIN_ID=211
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
  1. 配置单播,在主机直接执行下面的命令:
shell
sudo mkdir /etc/xbot/
sudo tee /etc/xbot/cyclonedds.xml > /dev/null << 'EOF'
<?xml version="1.0"?>
<CycloneDDS xmlns="https://cdds.io/config">
  <Domain id="211">
    <General>
      <AllowMulticast>false</AllowMulticast>
    </General>
    <Discovery>
      <Peers>
        <Peer address="127.0.0.1"/>
        <Peer address="192.168.8.100"/>
      </Peers>
      <ParticipantIndex>auto</ParticipantIndex>
      <MaxAutoParticipantIndex>300</MaxAutoParticipantIndex>
    </Discovery>
  </Domain>
</CycloneDDS>
EOF

export CYCLONEDDS_URI=file:///etc/xbot/cyclonedds.xml
ros2 daemon stop
ros2 daemon start
  1. 在机器人-XOS上设置ROSIP白名单ROSIP设置说明文档
    1. 将主机 ip 添加进 xos ros 白名单即可
  2. 直接跳到 **底层关节控制SDK** 章节即可

机器人端口使用规范 ​

禁止使用端口 ​

系统预留端口常用内置端口:

tcp dport { 22, 80, 443, 2222 } accept

tcp dport { 5555, 8888, 1688, 1788, 1888, 1988 } accept
tcp dport { 8765, 8080, 8090 } accept
tcp dport 1788-1888 accept

开发者可用端口 ​

仅限:1024 ~ 65535

进入开发者容器 ​

用户名: developer 初始密码:developer 端口号:2222

plaintext
ssh developer@192.168.8.100 -p 2222      #ssh连接机器人后端, 进入工作空间

底层关节控制SDK ​

关节控制流程 ​

plaintext

flowchart TD
    A[检查机器人硬件状态<br>(确认Ethercat连接、关节上电<br>绿色电源灯亮起)] --> B{选择模式}
    B -->|全身形态(带XHAND)| C[启动底层关节控制服务<br>/dynamic_launch<br>launch_mode: 'pos']
    B -->|全身形态(无XHAND)| C2[启动底层关节控制服务<br>/dynamic_launch<br>launch_mode: 'no_hand_pos']
    C & C2 --> D[初始化关节控制服务<br>/ready_service<br>(等待约20秒,接口返回成功)]
    D --> E[关节到标准起始位置<br>/simple_trajectory]
    E -->|使能算法控制| G1[使能算法控制<br>/activate_service]
    G1 --> H[发送关节控制命令<br>]
    H --> I[停止底层关节控制服务<br>/stop_launch]

图片

整机关节名称 ​

关节列表如下,整机结构参考产品结构图

bash
| Joint Name                 |
|----------------------------|
| left_shoulder_pitch_joint  |
| left_shoulder_roll_joint   |
| left_arm_yaw_joint         |
| left_elbow_pitch_joint     |
| left_elbow_yaw_joint       |
| left_wrist_pitch_joint     |
| left_wrist_roll_joint      |
| neck_yaw_joint             |
| neck_pitch_joint           |
| right_shoulder_pitch_joint |
| right_shoulder_roll_joint  |
| right_arm_yaw_joint        |
| right_elbow_pitch_joint    |
| right_elbow_yaw_joint      |
| right_wrist_pitch_joint    |
| right_wrist_roll_joint     |
| waist_pitch_joint          |
| waist_yaw_joint            |

| XHAND Joint Name             |
|------------------------------|
| left_hand_thumb_bend_joint   |
| left_hand_thumb_rota_joint1  |
| left_hand_thumb_rota_joint2  |
| left_hand_index_bend_joint   |
| left_hand_index_joint1       |
| left_hand_index_joint2       |
| left_hand_mid_joint1         |
| left_hand_mid_joint2         |
| left_hand_ring_joint1        |
| left_hand_ring_joint2        |
| left_hand_pinky_joint1       |
| left_hand_pinky_joint2       |
| right_hand_thumb_bend_joint  |
| right_hand_thumb_rota_joint1 |
| right_hand_thumb_rota_joint2 |
| right_hand_index_bend_joint  |
| right_hand_index_joint1      |
| right_hand_index_joint2      |
| right_hand_mid_joint1        |
| right_hand_mid_joint2        |
| right_hand_ring_joint1       |
| right_hand_ring_joint2       |
| right_hand_pinky_joint1      |
| right_hand_pinky_joint2      |

关节控制说明 ​

控制模式 ​

M7 系统没有下肢,腰部在内的上肢支持力矩控制模式和位置控制模式。通过不同的启动方式来进行区分

在不同的启动模式下

  1. 对于力矩控制的关节仅可设置参数如下:
  • velocity:关节目标速度
  • position:关节目标位置
  • feedforward:前馈力
  • kp:比例增益
  • kd:微分增益
  1. 对于位置控制的关节仅需设置 position(每个关节的目标位置)参数。其余参数包括:
  • velocity:关节目标速度
  • feedforward:前馈力或力矩
  • kp:比例增益
  • kd:微分增益

上述参数在位置控制模式下不生效,无需配置。请确保仅填写 position 字段,以避免冗余数据或接口误用。

控制频率 ​

L3的关节控制频率可以达到500Hz,灵巧手的控制频率是83Hz(串行数据)

抱闸 ​

机器人在腰部的 Pitch和 yaw 方向关节配备有抱闸机构。

  • 在进入位置控制模式时,这些关节的抱闸将自动解除,允许关节自由运动;当控制结束或系统断电时,抱闸将自动闭合,以确保机器人在非控制状态下的姿态安全和机械稳定。
  • 在进入 PD 模式前,需要手动解除抱闸,解除抱闸的命令如下:
shell
# 开抱闸
ros2 service call /control_brake xbot_common_interfaces/srv/SetJointIntegerParam "joint_name: ['waist_pitch_joint']
param_value: [1]"

ros2 service call /control_brake xbot_common_interfaces/srv/SetJointIntegerParam "joint_name: ['waist_yaw_joint']
param_value: [1]"

# 关抱闸
ros2 service call /control_brake xbot_common_interfaces/srv/SetJointIntegerParam "joint_name: ['waist_pitch_joint']
param_value: [0]"

ros2 service call /control_brake xbot_common_interfaces/srv/SetJointIntegerParam "joint_name: ['waist_yaw_joint']
param_value: [0]"

此机制无需用户手动干预,由系统自动管理,适用于正常启停及异常断电场景。

底层关节控制接口 ​

1. 关节控制命令接口 ​

接口名称类型功能说明消息类型
/hybrid_body_controller/commandsROS2 Topic发布关节控制命令xbot_common_interfaces/msg/HybridJointCommand
  • xbot_common_interfaces/msg/HybridJointCommand 参数说明:
    • header:标准消息头(含时间戳和 frame_id)
    • joint_name:string[],关节名称列表,对应每个控制关节
    • position:float64[],每个关节的目标位置(rad)
    • velocity:float64[],每个关节的目标速度(rad/s)
    • feedforward:float64[],前馈力或力矩(N·m)
    • kp:float64[],每个关节的比例增益
    • kd:float64[],每个关节的微分增益当前力/力矩

2. 手关节控制命令接口 ​

接口名称类型功能说明消息类型
/hand_controller/commandsROS2 Topic发布关节控制命令xbot_common_interfaces/msg/HybridJointCommand
  • xbot_common_interfaces/msg/HybridJointCommand 参数说明:
    • header:标准消息头(含时间戳和 frame_id)
    • joint_name:string[],关节名称列表,对应每个控制关节
    • position:float64[],每个关节的目标位置(rad)
    • velocity:float64[],每个关节的目标速度(rad/s)
    • feedforward:float64[],前馈力或力矩(N·m)
    • kp:float64[],每个关节的比例增益
    • kd:float64[],每个关节的微分增益当前力/力矩

3. 关节状态接口 ​

接口名称类型功能说明消息类型
/joint_statesROS2 Topic发布关节状态命令sensor_msgs/msg/JointState
  • sensor_msgs/msg/JointState 参数说明:
    • header:标准消息头(含时间戳和 frame_id)
    • name:string[],所有关节名称
    • position:float64[],每个关节的目标位置(rad)
    • velocity:float64[],每个关节的目标速度(rad/s)
    • effort:float64[],关节力矩(N·m)

4. Hand Sensor状态接口 ​

XHAND

接口名称类型功能说明消息类型
/hand_sensorROS2 Topic发布关节状态命令xbot_common_interfaces::msg::XhandHandSensor
  • xbot_common_interfaces::msg::XhandHandSensor 参数说明:

    • header:标准消息头(含时间戳和 frame_id)
    • hand_type:string[],手类型
    • fx:int8[],手指在x方向的力,单位 0.1N
    • fy:int8[],手指在y方向的力,单位 0.1N
    • fz:int8[],手指在z方向的力,单位 0.1N
    • temperature:uint8[],手指温度,摄氏度
    • calc_temperature:uint8,计算得到的温度,摄氏度
  • 每个 Sensor 包含 121 组 fx、fy、fz 数据:第一组是合力,剩余 120 组是分力,按 10 * 12 排列。

  • 总共 5 个 Sensor,ID 为 0x11、0x12、0x13、0x14、0x15。

​

底层关节控制示例 ​

通过命令行进行控制 ​

M7整机关节使用Ethercat进行通信,因此在启动前,请先确认机器人硬件状态。当前M7支持如下模式:

bash
# 带有左右两只XHAND的全身形态 位置模式
launch_mode: 'pos'

# 未安装XHAND的全身形态 位置模式
launch_mode: 'no_hand_pos'

# 带有左右两只XHAND的全身形态 力矩模式
launch_mode: 'pd'

# 未安装XHAND的全身形态 力矩模式
launch_mode: 'no_hand_pd'

以启动带有左右两只XHAND的全身形态为例,启动脚本如下:

bash
#ssh连接机器人后端, 进入工作空间
ssh developer@192.168.8.100 -p 2222      

# source 消息定义
git clone https://github.com/roboterax/teleop_client.git
cd teleop_client
colcon build
source install/setup.bash

# 启动关节服务
ros2  service call /dynamic_launch xbot_common_interfaces/srv/DynamicLaunch "app_name: ''
sync_control: false
launch_mode: 'pos'"

# 初始化关节模组,此过程需要大概20秒M7整机关节使用Et
ros2  service call /ready_service std_srvs/srv/Trigger {}

# 将关节设置到标准起始位置,此过程需要大概4秒
ros2 action send_goal /simple_actions xbot_common_interfaces/action/SimpleActions "{action_name: 'initpose_handsdown', time_cost: 4.0}"

# 小臂抬起
ros2 action send_goal /simple_actions xbot_common_interfaces/action/SimpleActions "{action_name: 'lift_up', time_cost: 4.0}"

# Xhand 双手微微握住(注意执行前需执行上一步骤,以抬起手臂)
ros2 topic pub /hand_controller/commands xbot_common_interfaces/msg/HybridJointCommand "header:
  stamp:
    sec: 0
    nanosec: 0
  frame_id: ''
joint_name: ['left_hand_thumb_bend_joint', 'left_hand_thumb_rota_joint1', 'left_hand_thumb_rota_joint2', 'left_hand_index_bend_joint', 'left_hand_index_joint1', 'left_hand_index_joint2', 
             'left_hand_mid_joint1', 'left_hand_mid_joint2', 'left_hand_ring_joint1', 'left_hand_ring_joint2', 'left_hand_pinky_joint1', 'left_hand_pinky_joint2',
             'right_hand_thumb_bend_joint', 'right_hand_thumb_rota_joint1', 'right_hand_thumb_rota_joint2', 'right_hand_index_bend_joint', 'right_hand_index_joint1', 'right_hand_index_joint2',
             'right_hand_mid_joint1', 'right_hand_mid_joint2', 'right_hand_ring_joint1', 'right_hand_ring_joint2', 'right_hand_pinky_joint1', 'right_hand_pinky_joint2']
position: [0.5, 0.5, 1.0, 0.3, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
           0.5, 0.5, 1.0, 0.3, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0]
velocity: [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
           0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]
feedforward: [350.0, 350.0, 350.0, 350.0, 350.0, 350.0, 350.0, 350.0, 350.0, 350.0, 350.0, 350.0,
              350.0, 350.0, 350.0, 350.0, 350.0, 350.0, 350.0, 350.0, 350.0, 350.0, 350.0, 350.0]
kp: [100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0,
      100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0, 100.0]
kd: [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
      0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]"

#开启算法控制权限
ros2 service call /activate_service std_srvs/srv/Trigger {}
# 读取关节信息
ros2 topic echo /joint_states --once

# 停止底层关节控制服务
ros2 service call /stop_launch std_srvs/srv/Trigger {}

python示例代码: ​

python
import rclpy
from rclpy.node import Node
from xbot_common_interfaces.srv import DynamicLaunch, SwitchController
from std_srvs.srv import Trigger
from xbot_common_interfaces.action import SimpleActions
from rclpy.action import ActionClient
from sensor_msgs.msg import JointState
from xbot_common_interfaces.msg import Imu

import time

class RobotStartupDemo(Node):
    def __init__(self):
        super().__init__('robot_startup_demo')

        # Service clients
        self.dynamic_launch_cli = self.create_client(DynamicLaunch, '/dynamic_launch')
        self.ready_service_cli = self.create_client(Trigger, '/ready_service')
        self.activate_cli = self.create_client(Trigger, '/activate_service')
        self.stop_launch_cli = self.create_client(Trigger, '/stop_launch')

        # Action client
        self.simple_actions_client = ActionClient(self, SimpleActions, '/simple_actions')

        # 状态读取相关
        self.joint_state_sub = None
        self.imu_sub = None
        self.joint_state_msg = None
        self.imu_msg = None

    def call_service(self, client, request):
        future = client.call_async(request)
        rclpy.spin_until_future_complete(self, future)
        return future.result()

    def wait_for_services(self):
        self.get_logger().info('等待服务...')
        self.dynamic_launch_cli.wait_for_service()
        self.ready_service_cli.wait_for_service()
        self.activate_cli.wait_for_service()
        self.stop_launch_cli.wait_for_service()

    def send_simple_action_goal(self, action_name: str, time_cost: float) -> bool:
        goal_msg = SimpleActions.Goal()
        goal_msg.action_name = action_name
        goal_msg.time_cost = time_cost

        self.simple_actions_client.wait_for_server()
        send_goal_future = self.simple_actions_client.send_goal_async(goal_msg)
        rclpy.spin_until_future_complete(self, send_goal_future)
        goal_handle = send_goal_future.result()
        if not goal_handle or not goal_handle.accepted:
            self.get_logger().error(f'SimpleActions Goal未被接受: {action_name}')
            return False

        get_result_future = goal_handle.get_result_async()
        rclpy.spin_until_future_complete(self, get_result_future)
        return True

    def run_startup_sequence(self):
        self.wait_for_services()

        # 1. 启动关节服务
        self.get_logger().info('启动关节服务...')
        dyn_launch_req = DynamicLaunch.Request()
        dyn_launch_req.app_name = ''
        dyn_launch_req.sync_control = False
        dyn_launch_req.launch_mode = 'pos'
        self.call_service(self.dynamic_launch_cli, dyn_launch_req)

        # 2. 初始化关节模组
        self.get_logger().info('初始化关节模组...')
        self.call_service(self.ready_service_cli, Trigger.Request())
        time.sleep(20)  # 按文档建议,实际部署时可优化等待逻辑

        # 3. 将关节设置到标准起始位置,此过程需要大概4秒
        self.get_logger().info('发送SimpleActions: initpose_handsdown')
        if not self.send_simple_action_goal('initpose_handsdown', 4.0):
            return

        # 4. 开启算法控制权限

        self.call_service(self.activate_cli,  Trigger.Request())

        # 5. 读取关节信息
        self.get_logger().info('读取一条关节状态...')
        self.joint_state_msg = None
        self.joint_state_sub = self.create_subscription(
            JointState, '/joint_states', self.joint_state_callback, 10
        )
        self.wait_for_msg('joint_state_msg')

        # 6. 读取IMU信息
        self.get_logger().info('读取一条IMU状态...')
        self.imu_msg = None
        self.imu_sub = self.create_subscription(
            Imu, '/imu_feedback', self.imu_callback, 10
        )
        self.wait_for_msg('imu_msg')

        # 7. 停止底层关节控制服务
        self.get_logger().info('停止底层关节控制服务...')
        self.call_service(self.stop_launch_cli, Trigger.Request())
        self.get_logger().info('流程结束。')

    def joint_state_callback(self, msg):
        if self.joint_state_msg is None:
            self.joint_state_msg = msg
            self.get_logger().info(f'收到关节状态: {msg}')
            self.joint_state_sub.destroy()

    def imu_callback(self, msg):
        if self.imu_msg is None:
            self.imu_msg = msg
            self.get_logger().info(f'收到IMU状态: {msg}')
            self.imu_sub.destroy()

    def wait_for_msg(self, attr_name, timeout=5.0):
        start = time.time()
        while getattr(self, attr_name) is None and rclpy.ok():
            if time.time() - start > timeout:
                self.get_logger().warning(f'{attr_name} 获取超时')
                break
            rclpy.spin_once(self, timeout_sec=0.1)

def main(args=None):
    rclpy.init(args=args)
    node = RobotStartupDemo()
    node.run_startup_sequence()
    node.destroy_node()
    rclpy.shutdown()

if __name__ == '__main__':
    main()

整机标零 ​

  • 取出标定工装,按标定工装规范将机器固定在标定工装加上
  • 确认完成机器人在标定工装上的安装后,启动启动机器e
bash
#ssh连接机器人后端, 进入工作空间
ssh developer@192.168.8.100 -p 2222      

# 以PD模式启动关节服务
ros2  service call /dynamic_launch xbot_common_interfaces/srv/DynamicLaunch "app_name: ''
sync_control: false
launch_mode: 'pd'"

# 初始化关节模组,此过程需要大概20秒
ros2  service call /ready_service std_srvs/srv/Trigger {}

# 调用标零服务
ros2 service call /set_zero_pos std_srvs/srv/Trigger {}

# 返回 True 后,停止底层关节控制服务
ros2 service call /stop_launch std_srvs/srv/Trigger {} 

# 使用急停遥控器,按“D”键两次,将关节重新上下电

# 再次启动关节服务
ros2  service call /dynamic_launch xbot_common_interfaces/srv/DynamicLaunch "app_name: ''
sync_control: false
launch_mode: 'pd'"

# 初始化关节模组,此过程需要大概20秒
ros2  service call /ready_service std_srvs/srv/Trigger {}

# 标定结果验证
ros2 topic echo /joint_states

# 查看 position 数值,若须知绝对值低于 0.02 ,即表示标定成功;
# 否则,查看关节位置是否到位,确定到位后,再重新执行以上步骤

上层控制SDK ​

注意:上层控制SDK的运行依赖于下层控制,请先完成底层关节控制服务再调用上层控制。


MPC接口说明 ​

exclamation 使用此接口时,请遵循以下步骤和注意事项以确保操作的稳定性和安全性:

  • 读取当前位姿:在发送控制指令前,应先读取当前的机械臂位姿,以作为轨迹控制的起点。
  • 逐步接近目标:推荐以较小的增量连续发送目标位姿,逐步引导机械臂到达目标位置。
  • 避免剧烈动作:请避免一次性发送跨度过大的位姿变换。快速或大范围移动可能导致机械臂运动不稳定或引发安全风险。
  • 建议结合轨迹规划:此接口适用于连续控制,建议结合外部轨迹生成器或平滑算法,以提高控制精度与安全性。

1. servoPose 接口 ​

接口名称类型功能说明消息类型
/servo_posesROS2 Topic控制左右手目标位姿xbot_common_interfaces/msg/ServoPose
  • ServoPose.msg 包括三个字段:

    • geometry_msgs/PoseStamped left_pose
    • geometry_msgs/PoseStamped right_pose
    • geometry_msgs/PoseStamped head_pose
  • geometry_msgs/PoseStamped 结构:

    • std_msgs/Header header
    • geometry_msgs/Pose pose

2. getPose 接口 ​

接口名称类型功能说明消息类型
/get_poseROS2 Topic获取左右手当前位姿xbot_common_interfaces/msg/ServoPose
  • ServoPose.msg 包括两个字段:

    • geometry_msgs/PoseStamped left_pose
    • geometry_msgs/PoseStamped right_pose
    • geometry_msgs/PoseStamped head_pose
  • geometry_msgs/PoseStamped 结构:

    • std_msgs/Header header
    • geometry_msgs/Pose pose

使用MPC ​

exclamation 上肢控制是针对腰部,头部和双臂操作的控制程序,通过dynamic精确控制手臂末端到设定位置。如需使用,请先启动机器人到“初始化关节模组”这一步再继续。

通过命令行使用 ​

bash
#ssh连接机器人后端, 进入工作空间
ssh developer@192.168.8.100 -p 2222      

# 通过下层SDK启动机器人关节电机
# 让机器人进入零位
# 此处省略,请参考底层关节控制部分

# 开启算法控制权限
ros2 service call /activate_service std_srvs/srv/Trigger {}

# 下载 l3_pub_client.py,用于启动 mpc
git clone https://github.com/roboterax/teleop_client.git
cd teleop_client
colcon build
cp ~/teleop_client/l3_pub_client.py ~/
cd ~/

# 启动MPC算法
python l3_pub_client.py --type mpc --cmd start

# 查看 MPC 状态,status返回值为1表示已启动,0为未启动
python l3_pub_client.py --type mpc --cmd query

# reset mpc 0抬手 
# --mode 0 也是开启 mpc 后机器人的初始位置
python l3_pub_client.py --type mpc --cmd reset --mode 0 

# 单独 ros 命令控制抬手。-r 后面表示消息发送频率,-r 100 就表示 100hz,这个参数可以控制速度
ros2 topic pub -r 20 /servo_poses xbot_common_interfaces/msg/ServoPose "{
  left_pose: {
    header: {frame_id: 'base_link'},
    pose: {position: {x: 0.425, y: 0.3, z: 0.292}, orientation: {x: 0.612, y: -0.016, z: 0.79, w: -0.006}}
  },
  right_pose: {
    header: {frame_id: 'base_link'},
    pose: {position: {x: 0.417, y: -0.146, z: 0.382}, orientation: {x: 0.521, y: 0.1, z: 0.842, w: -0.096}}
  },
  head_pose: {
    header: {frame_id: 'base_link'},
    pose: {position: {x: 0.0, y: 0.0, z: 0.0}, orientation: {x: 0.0, y: 0.0, z: 0.0, w: 1.0}}
  }
}"

# 停止MPC算法
python l3_pub_client.py --type mpc --cmd stop

# 关闭算法控制权限
ros2 service call /deactivate_service std_srvs/srv/Trigger {}

python代码示例 ​

python
import rclpy
from rclpy.node import Node
from std_srvs.srv import Trigger
import subprocess
import time
import textwrap

class MPCStartupDemo(Node):
    def __init__(self):
        super().__init__('mpc_startup_demo')
        self.cli_activate = self.create_client(Trigger, '/activate_service')
        self.cli_activate.wait_for_service()

    def call_activate_service(self):
        self.get_logger().info('开启算法控制权限...')
        req = Trigger.Request()
        future = self.cli_activate.call_async(req)
        rclpy.spin_until_future_complete(self, future)
        resp = future.result()
        if resp.success:
            self.get_logger().info('算法控制权限开启成功')
        else:
            self.get_logger().error(f'开启失败: {resp.message}')

    def launch_mpc(self):
        self.get_logger().info('启动MPC算法...')
        # 启动ros2 launch进程(注意:如需交互终端请用shell=True,或使用subprocess.Popen异步模式)
        # 这里用Popen,可Ctrl+C终止
        subprocess.run(["python", "l3_pub_client.py", "--type", "mpc", "--cmd", "start"])
        self.get_logger().info('MPC算法已启动(如需停止请手动Ctrl+C终止此脚本)')

    def publish_servo_pose_rate(self, rate_hz: int = 10):
        """以指定频率连续发布抬手位姿到 /servo_poses(默认 10Hz)"""
        message = textwrap.dedent(
            """
            {
              left_pose: {
                header: {frame_id: 'base_link'},
                pose: {position: {x: 0.425, y: 0.3, z: 0.292}, orientation: {x: 0.612, y: -0.016, z: 0.79, w: -0.006}}
              },
              right_pose: {
                header: {frame_id: 'base_link'},
                pose: {position: {x: 0.417, y: -0.146, z: 0.382}, orientation: {x: 0.521, y: 0.1, z: 0.842, w: -0.096}}
              },
              head_pose: {
                header: {frame_id: 'base_link'},
                pose: {position: {x: 0.0, y: 0.0, z: 0.0}, orientation: {x: 0.0, y: 0.0, z: 0.0, w: 1.0}}
              }
            }
            """
        ).strip()
        self.get_logger().info(f'以 {rate_hz}Hz 频率发布 /servo_poses 抬手指令...')
        subprocess.run([
            'ros2', 'topic', 'pub', '-r', str(rate_hz),
            '/servo_poses', 'xbot_common_interfaces/msg/ServoPose',
            message
        ], check=True)

def main(args=None):
    rclpy.init(args=args)
    node = MPCStartupDemo()
    node.call_activate_service()
    # 暂停1秒确保服务完全生效
    time.sleep(1)
    node.launch_mpc()
    node.publish_servo_pose_rate()
    node.destroy_node()
    rclpy.spin(node)
    rclpy.shutdown()
    subprocess.run(["python", "l3_pub_client.py", "--type", "mpc", "--cmd", "stop"])

if __name__ == '__main__':
    main()

在开发者环境下直接使用音频设备 ​

机器人集成了麦克风和扬声器,可在系统中直接使用

使用方法 ​

通过命令行测试设备是否正常 ​

bash
# 登录到开发者环境 密码为developer
ssh developer@192.168.8.100 -p 2222      #ssh连接机器人后端, 进入工作空间

# 安装音频库
sudo apt update
sudo apt install libportaudio2 python3-pyaudio portaudio19-dev

# 安装虚拟环境
curl -L -A "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36" \
  -o python3-pip-whl_22.0.2+dfsg-1_all.deb \
  "https://mirrors.ustc.edu.cn/ubuntu/pool/universe/p/python-pip/python3-pip-whl_22.0.2+dfsg-1_all.deb"
sudo dpkg -i python3-pip-whl_22.0.2+dfsg-1_all.deb
sudo apt-get install --fix-broken python3.10-venv

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate

# 安装依赖 (如果无法安装,可以指定源)
# 阿里源示例: pip install sounddevice scipy -i https://mirrors.aliyun.com/pypi/simple/
# 清华源示例: pip install sounddevice scipy -i https://pypi.tuna.tsinghua.edu.cn/simple/ --trusted-host pypi.tuna.tsinghua.edu.cn
pip install sounddevice scipy --timeout=1000

# 给snd设备附加权限避免问题
sudo chmod 777 /dev/snd/*

# 读取声卡信息:
    python3 -c "import sounddevice as sd; print(sd.query_devices())"

#如果正常可以看到类似如下内容:
developer@xbot-NUC:~$ python3 -c "import sounddevice as sd; print(sd.query_devices())"
< 0 HD-Audio Generic: HDMI 0 (hw:0,3), ALSA (0 in, 8 out)
  1 HD-Audio Generic: HDMI 1 (hw:0,7), ALSA (0 in, 8 out)
  2 HD-Audio Generic: HDMI 2 (hw:0,8), ALSA (0 in, 8 out)
  3 HD-Audio Generic: HDMI 3 (hw:0,9), ALSA (0 in, 8 out)
> 4 POROSVOC: USB Audio (hw:1,0), ALSA (1 in, 0 out)
  5 HD-Audio Generic: ALC897 Analog (hw:2,0), ALSA (2 in, 2 out)
  6 USB Audio Device: - (hw:3,0), ALSA (1 in, 2 out)
  7 hdmi, ALSA (0 in, 8 out)

# 退出虚拟环境命令
deactivate

python代码示例 ​

python
import sounddevice as sd
import numpy as np
from scipy.signal import resample

duration = 2.0  # 秒

# 根据需求调整输入和输出设备
sd.default.device = (6, 6)  # M7默认的音频设备是6号

# 获取默认设备索引
input_device, output_device = sd.default.device

# 获取设备参数
input_info = sd.query_devices(input_device)
output_info = sd.query_devices(output_device)

input_samplerate = int(input_info['default_samplerate'])
output_samplerate = int(output_info['default_samplerate'])
channels = input_info['max_input_channels']

print(f"🎤 正在从默认输入设备(设备 {input_device})录音 {duration} 秒 @ {input_samplerate} Hz, 通道数: {channels}")

sd.default.device = (input_device, output_device)

# 录音
recording = sd.rec(int(input_samplerate * duration), samplerate=input_samplerate, channels=channels, dtype='int16')
sd.wait()

# 音量放大,请根据实际情况调整
amplified = recording * 1
amplified = np.clip(amplified, -32768, 32767).astype(np.int16)

# 如果播放采样率和录音不同,则升/降采样
if input_samplerate != output_samplerate:
    print(f"🔁 正在将录音采样率从 {input_samplerate} Hz 转为 {output_samplerate} Hz 以便播放")
    num_samples = int(output_samplerate * duration)
    amplified = resample(amplified, num_samples).astype(np.int16)

print(f"🔊 正在从默认输出设备(设备 {output_device})播放...")
sd.play(amplified, samplerate=output_samplerate)
sd.wait()

print("✅ 播放完成")

在开发者环境下使用相机 ​

M7 机器人集成了相机(双目或者 realsense),可在开发者环境中直接使用

使用方法 ​

双目相机 ​

bash
# 登录到开发者环境 密码为developer
ssh developer@192.168.8.100 -p 2222      #ssh连接机器人后端, 进入工作空间

# 软连接
sudo bash /usr/local/bin/map_video.sh

# 安装v4l设备工具
sudo apt install v4l-utils

# 查看视频设备
sudo v4l2-ctl --list-devices

#如果正常可以看到类似如下内容:
developer@xbot-NUC:~$ v4l2-ctl --list-devices
PayCam: PayCam (usb-0000:66:00.4-1):
        /dev/video0
        /dev/video1
        
# 录制一帧图像
# 保存 yuv 图
sudo v4l2-ctl --device=/dev/video4 \
  --set-fmt-video=width=1280,height=720,pixelformat=YUYV \
  --stream-mmap --stream-count=1 \
  --stream-to=frame.raw

# 将 yuv 转换位 jpeg
sudo apt install ffmpeg
ffmpeg -f rawvideo -pixel_format yuyv422 -video_size 1280x720 -i frame.raw frame.jpg

realsense 相机 ​

  1. Windows 环境下载mobaxterm访问:https://mobaxterm.mobatek.net/
python
ssh -X developer@192.168.8.100 -p 2222
  1. Linux 环境重新进入环境:
python
ssh -X developer@192.168.8.100 -p 2222
  1. 终端下启动 realsense-viewer 可以打开GUI操作
shell
realsense-viewer
  1. 启动 realsense2_camera,可以通过 ros 实时外发图像相关数据
python
ros2 launch realsense2_camera rs_launch.py

# 如果想设置分辨率 
ros2 launch realsense2_camera rs_align_depth_launch.py depth_module.depth_profile:=848x480x60 rgb_camera.color_profile:=848x480x60
  1. 使用 ros2 topic list,查看图像消息
bash
/camera/camera/color/camera_info
/camera/camera/color/image_raw
/camera/camera/color/metadata
/camera/camera/depth/camera_info
/camera/camera/depth/image_rect_raw
/camera/camera/depth/metadata
/camera/camera/extrinsics/depth_to_color
/tf_static
topic 名称数据类型含义
/camera/camera/color/camera_infosensor_msgs/msg/CameraInfo彩色相机的内参(K矩阵、畸变参数等)
/camera/camera/color/image_rawsensor_msgs/msg/ImageRGB 彩色图像原始数据
/camera/camera/color/metadatarealsense2_camera_msgs/msg/Metadata帧元数据(时间戳、曝光、增益等)
/camera/camera/depth/camera_infosensor_msgs/msg/CameraInfo深度相机的内参
/camera/camera/depth/image_rect_rawsensor_msgs/msg/Image对齐或矫正后的深度图
/camera/camera/depth/metadatarealsense2_camera_msgs/msg/Metadata帧元数据(时间戳、曝光、增益等)
/camera/camera/extrinsics/depth_to_colorrealsense2_camera_msgs/msg/Extrinsics深度→彩色相机的外参矩阵
/tf_statictf2_msgs/msg/TFMessage静态坐标变换(相机坐标系等)

在开发者环境下机器人动作的录制和播放 ​

启动遥操作 ​

exclamation 遥操作需两个人同时配合,在停止mpc之前,头显操作人员切勿乱动

参考:操作指南:机器人遥操作 和 开发指南:在开发者环境下使用遥操作

录制机器人动作 ​

exclamation 注意:人的动作必须和机器人的动作保持一致后开启遥操作。

bash
#进入develeoper
ssh developer@192.168.8.100 -p 2222 #密码:developer

#如果已经拉取teleop_client
cd teleop_client
colcon build
source install/setup.bash
#如果没有teleop_client目录请执行{遥操作服务启动说明中第一步}

#录制
ros2 bag record /hand_controller/commands /servo_poses -o [bag package name]
#-o 后面定义保存的包名

#保存录制内容:在录制机器人动作的终端下使用ctrl-c停止录制

播放机器人动作 ​

developer容器中播放

bash
#启动sdk 如果sdk已经启动,请不要重复启动
python l3_pub_client.py --cmd start_sdk

# 启动MPC算法
python l3_pub_client.py --type mpc --cmd start

#play
ros2 bag play [bag package name]
#[bag package name] 保存的机器人动作

# 停止MPC算法
python l3_pub_client.py --type mpc --cmd stop
# 停止
Ctrl-C mpc终端
python l3_pub_client.py --cmd stop_sdk

在开发者环境下配置程序自启动 ​

在开发者环境中,可以通过修改 /ros_entrypoint.sh 配置容器启动时自动运行的程序。该脚本会在开发者环境启动时执行,适合用于添加需要随环境启动的后台服务或用户程序。

  1. 打开并编辑 /ros_entrypoint.sh 文件。

  2. 在最后一行 exec "$@" 前添加需要自启动的程序命令。例如:

bash
#!/bin/bash
set -e

# setup ros2 environment
source "/opt/ros/$ROS_DISTRO/setup.bash"

sudo /usr/sbin/sshd -D &
sudo bash /usr/local/bin/maps/video.sh &

exec "$@"

注意:添加的进程命令末尾需要带上 & 符号,表示后台运行。