文档修订记录
修订日期 | 修订内容 | 版本 |
2025.9 | ? 初始预测试版本 | V0.0.1 |
2025.10 | ? 提供基础机器人控制接口 ? 支持机器人状态数据回调 ? 支持故障信息回调 | v0.0.2 |
2025.11 | ? 添加登阶模式接口 ? 添加运动模式下爬高台接口 ? 添加模式状态获取接口 | v0.0.3 |
2025.12.27 | ? 添加获取系统版本号的接口 ? 新增 UDP 通信方式支持 ? 优化连接失败时的错误信息提示 ? 内部适配新版本通信协议 | v0.0.4 |
2026.1.17 | ? 新增2.10机体坐标系方向 ? 新增4.4本体传感器坐标 | v0.0.41 |
2026.01.15 | ? 新增步态姿态接口(Gait(...)) ? 新增瘦身姿态接口(Slim(...)) ? 新增断开后自动续连的配置接口 ? 新增获取当前连接状态接口 ? 添加一些自动续连/手动续连的示例 ? 异步接口中 添加获取发送结果的回调参数 | v0.0.5 |
2026.02.08 | ? 新增控制权切换功能 ? 新增 “4.5 RTK使用说明” ? 修复IMU acc/gyro 取反问题 | v0.0.6 |
2026.03.17 | ? 新增自主回充功能 ? 修改nx ssh登录用户名 ? 修改前后激光雷达IP地址及ros topic ? 新增 “1.6 D1 Max硬件架构图” | v0.0.8 |
一、产品介绍
1.1 产品概述
乐鱼体育仿生四足机器人 D1 Max是一款轮足式仿生四足机器人， 具备自重轻、负载大、续航长、防护强、运动灵活稳定等优势。机器狗每条腿配备3个关机电机和1个轮毂电机，配备光学相机、激光雷达、超声波雷达、IMU、RTK模块等传感设备，内部搭载高算力平台，用于实现运动控制、自主导航定位、环境侦测等功能，提供丰富的供电和通信接口，支持多品类的任务载荷拓展。
1.2 产品清单
1.3 产品参数
| 分类 | 规格 | 说明 |
| 基础信息 | 材质信息 | 铝合金+高强度工程塑料 |
| 站 立 尺 寸 ( 长 × 宽 × 高 ) | 930mm×480mm×585mm | |
| 趴 地 尺 寸 ( 长 × 宽 × 高 ) | 930mm×630mm×200mm | |
| 整机重量(含电池) | 41kg | |
| 自由度 | 12+4dof | |
| 工作温度 | -20℃~55℃ | |
| 防护等级 | IP67 | |
| 电池 | 54v,9.45Ah*2,双电池，支持快拆快换，支持热插拔 | |
| 充电时长 | <2h | |
| 续航时间 | 空载5h,满载3.5h | |
| 续航里程 | 空载29km,满载18km | |
| 整机算力 | 157 Tops/Nvidia Orin NX 16GB | |
| 性能参数 | 最大速度 | 8m/s |
| 额定负载 | 25kg | |
| 连续攀爬楼梯高度 | 25cm | |
| 最大爬坡角度 | 45° | |
| 跳跃离地高度 | 80cm | |
| 极限跨越障碍、沟壑高度 | 80cm | |
| 带载跨越高度 | 50cm | |
| 最窄通过宽度 | 50cm | |
| 最窄掉头宽度 | 支持原地调头、支持前后向切换 | |
| 匍匐行走高度 | 34cm | |
| 整机关节参数 | 最大关节扭矩 | 150N ·m |
| 关节运动空间(机身) | -30°40° | |
| 关节运动空间(大腿) | -160°~160° | |
| 关节运动空间(小腿) | -160°~160° | |
| 传感单元 | 激光雷达 | 前后各1个96线激光雷达、覆盖角度360°*90°、覆盖直径范围120m |
| 相机FOV | 前后各1个FPV相机，工业级800万像素，视场角： DFOV122°, HFOV111°,VFOV70° | |
| 补光灯 | 补光灯*4,FPV相机左右各1个。照射距离≥3m | |
| IMU | 车规级IMU*1 | |
| RTK模块 | GNSS RTK*1 | |
| 超声波传感器 | 左右各1个超声波，支持5m以内的障碍物识别 | |
| 功能列表 | 标准动作 | 踏步、滑行、匍匐等姿态，前后左右直线移动、原地旋转、转弯 等，支持膝关节姿态变换。 |
| 实时图像传输 | 支持 | |
| 二次开发 | 支持，提供SDK开发包，机器人模型提供3D数模和urdf文件用于仿真 | |
| 通讯功能 | 支持WIFI 5.0,蓝牙5.0 | |
| 供电接口 | 5V、12V、24V、48V,最大输出功率480W | |
| 功能拓展接口 | 千兆网口*2、USB3.0*2、RS232*1、RS485*1、SBUS*2、PPS*1 | |
| 配件 | 适配器 | 标配 |
| 充电座 | 标配 | |
| 遥控器 | 带屏遥控器，遥控距离700-1000m | |
| 自主充电桩 | 选配 |
注：以上参数为实验室测试数据，实际表现可能因使用环境、操作方式等因素有所差异，请以实际为准 |
注：以上参数为实验室测试数据，实际表现可能因使用环境、操作方式等因素有所差异，请以实际为准 |
? 关节参数
部位 | 参数 | 数值 |
髋部滚转关节(hip_roll) | 最大扭矩 | 150N.m |
最大转速 | 190RPM | |
重量 | 0.93kg | |
关节限位 | -39.9°~30° | |
髋部俯仰关节(hip_pitch) | 最大扭矩 | 150N.m |
最大转速 | 190RPM | |
重量 | 0.93kg | |
关节限位 | -140°~140° | |
膝部俯仰(knee_pitch) | 最大扭矩 | 150N.m |
最大转速 | 190RPM | |
重量 | 0.93kg | |
关节限位 | -160°~160° | |
足端(foot) | 最大扭矩 | 33N.m |
最大转速 | 1200RPM | |
重量 | 1.275kg | |
半径 | 9cm | |
关节限位 | -180°~180° |
1.4 载荷上装
1.4.1 负载安装孔位图
机器狗背部的空间平整，负载25-30kg，背部部署有双导轨，两条导轨上有14个M4孔位支持上装载荷便捷安装，双导轨具体尺寸如下
机器人加装负载后，仅支持基础运动模式，请勿在加装负载后使用高台模式 |
当在机器人背部加装载荷时，机器人的运动性能可能会受影响，请务必在加装前向售后人员咨询相关事宜 |
1.4.2 重心限制
为避免D1 Max机身上加装上装载荷之后，在各类地形运动过程中，腿部与上装载荷发生碰撞干涉，对D1 Max的上装空间给出如下推荐示意，具体尺寸为长40cm，宽22cm，高24cm，位置在机身背部居中位置，如下图所示：
1.5 电气拓展接口
序号 | 接口名称 |
1 | 48V(10A) |
2 | 24V(20A) |
3 | 24V(3A)+网口 |
4 | 12V(5A)+网口 |
5 | 串口（RS232 x1、RS485 x1、SBUS x2、PPS x1） |
6、7 | USB3.0（5V、1A） |
8 | RTK天线接口 |
9 | 拓展仓按键 |
? 所有供电接口的供电总功率在 480W 以内； ? 有航插头配备防护盖，以确保 IP67，不用的航插头务必盖好防护盖； ? 扩展仓按键用于控制扩展接口的供电，在进行上装接线时，务必先关闭扩展仓的电源。 |
航插扩展功能接口说明：
| V3机器设备路径 | V4机器设备路径 |
| ? RS232: /dev/ttyTHS3 | ? RS232:/dev/ttyCH9344USB4 |
| ? RS485: /dev/ttyTHS1 | ? RS485:/dev/ttyCH9344USB5 |
| ? SBUS1: /dev/ttyACM2 | ? SBUS1:/dev/ttyCH9344USB2 |
| ? SBUS2: /dev/ttyACM3 | ? SBUS2:/dev/ttyCH9344USB3 |
1.5.1 电源口48V(10A)
? 航插母图
航插名称 | 48V 10A | |
板端航插型号 | M12-S4S-GPFM16-135-CS24044 | |
线序定义
| 1 | GND |
2 | 48V | |
3 | 48V | |
4 | GND | |
? 对插线束
1.5.2 电源口24V(20A)
? 航插母头
航插名称 | 24V 20A | |
板端航插型号 | M12-S4S-GPFM16-135-CS24044 | |
线序定义
| 1 | GND |
2 | 24V | |
3 | 24V | |
4 | GND | |
? 对插线束
1.5.3 网口(24V)
? 航插母头
航插名称 | 网口+24V | |
板端航插型号 | M12- P12A-GPFM12 | |
线序定义
| 1 | GND |
2 | 24V | |
3 | 24V | |
4 | 网口A+ | |
5 | 网口A- | |
6 | 网口B+ | |
7 | 网口B- | |
8 | 网口C+ | |
9 | 网口C- | |
10 | GND | |
11 | 网口D+ | |
12 | 网口D- | |
? 对插线束
1.5.4 网口(12V)
? 航插母头
航插名称 | 网口+12V | |
板端航插型号 | M12- P12A-GPFM12 | |
线序定义
| 1 | GND |
2 | 12V | |
3 | 12V | |
4 | 网口A+ | |
5 | 网口A- | |
6 | 网口B+ | |
7 | 网口B- | |
8 | 网口C+ | |
9 | 网口C- | |
10 | GND | |
11 | 网口D+ | |
12 | 网口D- | |
? 对插线束
1.5.5 串口
? 航插母头
航插名称3 | 串口（RS232、RS845、SBUS*2、PPS） | |
板端航插型号 | M12- P8A-GPFM12 | |
线序定义
| 1 | PPS |
2 | SBUS1 | |
3 | SBUS2 | |
4 | RS485A | |
5 | RS485B | |
6 | RS232_TX | |
7 | RS232_RX | |
8 | GND | |
? 对插线束
1.5.6 USB口
? 航插母头
航插名称 | USB3.0+5V 两个 |
板端航插型号 | E10B- FT3-PPF |
线序定义 | 无 |
? 对插线束
二、SDK开发指南
2.1 SDK介绍
? 本文档描述了 D1 Max 的软件开发工具包 (SDK)，提供其核心服务接口的详细信息，包括高层运动控制接口、IMU 惯导数据接口、电机状态数据接口。
? 各章节分别介绍不同服务接口的调用方法、数据输入/输出的标准格式定义与一些功能开发示例。
? 接口定义会随量产开发状态产生变更，请以最新版本的接口定义文档为准。
? SDK程序与狗本体内程序通讯存在特定协议，故不同版本的SDK程序与狗本体内程序通讯存在差异，请根据设备版本选择对应版本SDK程序。若条件允许，建议更新狗内程序到最新版本，以获得更好的兼容性。
? SDK接口控制时，全部状态均由二次开发者设计指定，本体运控不做额外的干预与状态跳转。
? 运行SDK时, 请保证系统有足够的资源, 否则可能出现运动控制模块失效的情况。
2.2 sdk软件服务接口列表
序号 | 接口名称 | 功能 | SDK版本 |
1 | 高层运动控制接口
| 实现机器狗的高层运动控制，包括前后转向速度运动，趴下，旋转，四肢站立等 | V0.0.2
|
2 | 视频流推送数据接口 | 向客户端推送相机本体视频流 | V0.0.2 |
3 | 设备状态服务接口
| 查询并获取当前设备状态和系统资源使用信息 | V0.0.3
|
4 | 惯导状态数据接口 | 获取IMU原始数据信息 | V0.0.4 |
5 | 超声波雷达接口 | 实现自主避障功能 | v0.0.5 |
6 | 遥控器和sdk控制权切换功能及sdk接口 | 实现控制权切换功能 | v0.0.6 |
7 | RTK模块的sdk接口 | 实现自主定位功能 | v0.0.6 |
8 | 自主回充功能及sdk接口 | 实现自主充电功能 | v0.0.8 |
9 | slam建图导航功能及sdk接口 | 实现自主导航功能 | 暂未上线，目前可提供激光雷达ROS2接口 |
2.3 安全保护机制
2.3.1 硬急停
? 触发方式：按下机身急停按钮
? 效果：机器狗缓慢着地，红灯亮起
? 指示灯状态
? 按下时：红灯亮
? 松开后：绿灯亮
? 恢复：旋开急停按钮后，系统自动恢复(若无其他故障)
2.3.2 软急停
? 触发方式：通过遥控器触发或者通过sdk接口触发
? 效果：机器人立即停车，不再响应任何控制指令
? 恢复：接触软急停后可恢复正常操作
从V0.0.6版本sdk起，支持遥控器和sdk控制权切换功能，若要实现在sdk控制阶段通过遥控器触发设备软急停，必须得在sdk获取控制权后，点开app，然后便可以随时使用遥控器右上方红色急停按钮触发软急停，触发软急停后，机器狗显示红灯，保持当前姿态，不再响应任何控制指令 |
2.3.3 内部异常保护(自动触发)
以下情况将触发内部保护机制，机器人自动停车并缓慢着地
? 遥控信号断连(含网络阻塞)，重新连接APP即可恢复
? 电池在位但电量<10%
? 关节故障
? IMU(惯性测量单元)通信中断
2.4 环境依赖
- 操作系统: Ubuntu 22.04
- 构建工具: CMake 3.8+, GCC 11+
- 依赖库: Boost 1.74+
- 编程语言: C++
2.5 设备登录
网络连接
? Wifi 连接登录
? wifi名称：XG2WIFI_xxxxxx
? wifi密码：12345678
? 有线连接
? 使用网线连接机器狗拓展网口和控制端PC
? 设置控制端PC网口IP为192.168.168.x(不能设置为192.168.168.168和192.168.168.100)
ssh登录
Plain Text |
? RK3588算力板负责运动控制和系统监控等功能，勿在此板开发应用程序 ? Orin NX算力板负责建图、定位、导航等业务功能，用户可在此算力板开发轻量化的应用程序，需做好备份管理，刷机或OTA升级可能会被刷新 |
2.6 SDK获取
2.6.1 版本查询
通过ssh进入机器狗本体，查询对应的版本信息后，将查询到的机器狗固件版本号截图发送售后技术支持团队获取对应的SDK 安装包与示例代码，查询方式如下：
Bash |
2.6.2 获取对应固件版本的sdk
way1:请在查询到版本号后，截图发送给技术支持同事获取对应版本的sdk包
way2:通过如下github地址获取
Bash |
2.7 示例Demo运行步骤
在本地PC端，进入到sdk文件中
Bash |
在进行sdk控制前，遥控器端app务必先退出，否则sdk无法控制设备进行动作 在运行demo文件前，务必先阅读源文件 |
2.8 SDK控制说明
? sdk指令下发需要按照以下状态跳转逻辑，否则可能会造成机器摔倒、故障或不响应等异常情况。
注意： 1. 当下发站立命令时，完成站立后会根据当前的模式自动切换到通用状态或者原地状态 2. 锁定状态下切到任意其他状态下就算解锁 |
? SDK命令下发流程如下
2.9 关节命名规范
为便于识别与调试，本设备采用如下命名规则：
? 方向缩写
? f = front(前)
? b = back(后)
? l = left(左)
? r = right(右)
? 编号含义
? 1 = 髋部滚转(hip_roll)
? 2 = 髋部俯仰(hip_pitch)
? 3 = 膝部俯仰(knee_pitch)
? 4 = 足端(foot)
? 示例命名
? frl_hip_roll：右前腿1号关节(髋部滚转)
? bl3_knee_pitch：左后腿3号关节(膝部俯仰)
Plain Text |
2.10 机体坐标系方向
当各个关节均为零度时，各坐标系如下图。红色为 x 轴，绿色为 y 轴，蓝色为 z 轴。关节的旋转轴和旋转正方向请参考下图
三、SDK函数介绍
详细接口说明，请查看对应版本的sdk说明文档：
https://github.com/AgibotTech/Agibot_D1_Max/blob/main/docs/sdk_client_api.md
四、其他服务
前后广角相机的视频分别以Gstreamer方式推流到以下URL:
Plain Text |
默认会在遥控器侧拉流显示实时画面，可通过VLC或者OpenCV进行预览和调用
4.2 激光雷达信号接口
1. ROS2接口定义
topic | msg | 字段类型 | 字段 | 字段释义 | 初始值 | 数值范围 | 发送周期 |
前雷达点云数据：/front_lidar
| sensor_msgs::msg::PointCloud2（数据服务模型Qos::best_effort）
| std_msgs/Header | header | ROS2 标准MSG帧头 | 10hz | ||
uint32 | height | 点云的垂直高度（行数） | |||||
uint32 | width | 点云的水平方向宽度（列数） | |||||
PointField[] | fields | 点云中每个通道的字段描述 | |||||
bool | is_bigendian | 是否是大端字节序 | |||||
uint32 | point_step | 每个点所占字节数 | |||||
uint32 | row_step | 一行点数据占用的字节数 | |||||
uint8[] | data | 点云的原始二进制数据，是一维数组 | |||||
bool | is_dense | 是否为稠密点云（即没有无效点） |
前激光雷达IP: 192.168.1.102 后激光雷达IP: 192.168.2.102 |
2. 启动对应的驱动程序
Plain Text |
topic | msg | 字段类型 | 字段 | 字段释义 | 初始值 | 数值范围 | 发送周期 |
左侧超声波雷达： /uss_driver/uss_left/range 右侧超声波雷达：
| sensor_msgs::msg::Range
| std_msgs/Header | header | ROS2 标准MSG帧头 | 10hz | ||
uint8_t
| radiation_type | 传感器类型。枚举值：0 超声波 1 红外线 | 0 | 0-1 | |||
float | field_of_view | 传感器视场角（弧度），通常为测距锥形区域的角度 | 0 | 当前固定为0 | |||
float | min_range | 传感器可测量最小距离（米） | 0 | 当前固定为0 | |||
float | max_range | 传感器可测量的最大距离（米） | 0 | 当前固定为0 | |||
float | range | 当前实际测得距离（米） | 0 | 0-4米 |
| 传感器名称 | 传感器坐标（相对机身BASE原点)（单位mm） | 备注 | ||
| x | y | z | ||
| IMU_ICM42688（运控用） | 0 | 0 | 36.2 | |
| IMU_LUA300C （车规级） | 0 | 0 | 56.9 | 目前未开发固件 |
| 前激光雷达AIRY | 404.3 | 0 | -37.7 | 详见规格书 |
| 前摄像头IMX415 | 412.3 | 0 | 37.8 | 详见规格书 |
| 右前补光灯 | 420.3 | -30.9 | 28.3 | 照射范围 120° |
| 左前补光灯 | 420.3 | 30.9 | 28.3 | 照射范围 120° |
| 后激光雷达AIRY | -404.3 | 0 | -37.7 | 详见规格书 |
| 后摄像头IMX415 | -412.3 | 0 | 37.8 | 详见规格书 |
| 右后补光灯 | -420.3 | -30.9 | 28.3 | 照射范围 120° |
| 左后补光灯 | -420.3 | 30.9 | 28.3 | 照射范围 120° |
| 右前超声波雷达RADAR A22 | 179.2 | -100.2 | 50 | 详见规格书 |
| 左前超声波雷达RADAR A22 | 179.2 | 100.2 | 50 | 详见规格书 |
Click the image to view the sheet.
4.5 RTK使用说明
4.5.1 获取六分RTK服务
使用从注册的六分账户和密码登录到官网
网址：https://www.sixents.com/login
? 登录进控制台
? 获取AK和AS
准备好需要使用的AK和AS
4.5.2 配置
? 登录进入NX
首先需要连接机器狗的WIFI，密码默认是 12345678
Bash |
? 打开配置文件
配置文件路径：/ota/sixents_config.ini
Bash |
TOML |
? sdk_ak: 设置您购买服务实例的 AK
? sdk_as: 设置您购买服务实例的 AS
? sdk_dev_id: 设置您的设备 ID 或 SN（自定义）
? sdk_dev_type: 设置您的设备类型（自定义）
注意：sdk_dev_id 和 sdk_dev_type 是和 账户唯一绑定的，之后更改其他的需要去官网解绑
4.5.3 RTK Topic 说明
? rtk话题名称
rtk对应的话题为：/rtk_pvh
? 数据说明
类别 | 字段 | 说明 |
heading | utc_time_s | heading UTC时间 |
sol_status | 解的状态 ? 0：已解出 ? 1：观测量不足 ? 2：未收敛 ? 4：协方差矩阵的迹超过最大值（迹＞1000 米） | |
heading_type | 定位类型 ? 0：不进行解算 ? 16：单点定位 ? 17：伪距查分定位 ? 34：浮点解 ? 50：整数解 | |
base_line | 基线长度，单位米（0~3000） | |
heading_deg | 航向角，单位度（0~360） | |
pitch_deg | 俯仰角，单位度（±90） | |
heading_std | 航向角标准差，单位度 | |
pitch_std | 俯仰角标准差，单位度 | |
sys_num | 跟踪的卫星数 | |
soln_svs_num | 参与解算的卫星数 | |
bestnav | utc_time_s | bestpos UTC时间 |
p_sol_status | 解的状态 | |
pos_type | 定位类型 | |
latitude_deg | 纬度，单位度 | |
longitude_deg | 经度，单位度 | |
altitude_m | 海拔高，单位米 | |
undulation | 大地水准面差距，大地水准面与 WGS84 参考椭球面的差值，单位米 | |
lat_std | 纬度标准差，单位米 | |
lon_std | 经度标准差，单位米 | |
hgt_std | 高度标准差，单位米 | |
diff_age_s | 差分龄期，单位秒 | |
sol_age_s | 解的龄期，单位秒 | |
svs_num | 跟踪的卫星数 | |
soln_svs_num | 参与解算的卫星数 | |
v_sol_status | 解的状态 | |
vel_type | 定位类型 | |
hor_spd | 水平方向对地速度，单位米/秒 | |
trk_gnd | 相对于真北的实际对地运动方向，单位度 | |
ver_spd | 垂直方向速度，单位米/秒。正值表示方向向上，负值表示方向向下 | |
ver_spd_std | 垂直方向速度标准差（未填写） | |
hor_spd_std | 水平方向对地速度标准差（未填写 |
4.5.3 重启rtk服务
? 查看当前服务
TOML |
? 重启服务
TOML |
? 重启NX
TOML |
4.6 IMU数据
目前系统中有三个IMU（2雷达+1独立），通过topic发出数据，标准ROS2的数据类型 sensor_msgs::msg::Imu
前雷达IMU：/front_lidar/imu
后雷达IMU：/rear_lidar/imu
独立IMU：/imu_driver/imu_central
注：独立IMU涉及硬件改动的问题，若无法获取imu数据，请联系售后服务人员 |
4.7 相机数据
相机数据来源于RK3588, topic名称如下:
? 前: /front_camera/image_compressed
? 后: /rear_camera/image_compressed
五、调试说明
5.1 ROS2多机通信配置
NX系统中有统一配置的环境变量：/opt/runtime/env.bash , 这个变量在.bashrc中会默认导入
由上图可见，ROS_DOMAIN_ID=24 ，目前机器狗使用 ros2 的 zenoh 中间件对外提供 ros2 topic 服务，需要用户在自己的笔记本安装相关环境。
5.1.1 IP配置
配置用户笔记本 ip 为： 192.168.168.xxx （xxx不能为100或者168或者255）
5.1.2 用户笔记本环境配置
? Ubuntu22.04
? Ros2 humble
? Zenoh rmw
5.1.3 安装zenoh
Plain Text |
5.1.4 修改配置文件
使用编辑器打开下面文件
/opt/ros/humble/share/rmw_zenoh_cpp/config/DEFAULT_RMW_ZENOH_ROUTER_CONFIG.json5
找到 connecet/endpoints字段，将机器狗NX的IP写入并保存:
Plain Text |
在pc端新建终端1，设置中间件切换的环境变量以及 ROS2 的 Domain ID
Plain Text |
重置 ROS2 后台守护进程
Plain Text |
在上述的环境变量生效的前提下即可使用 rviz 可视化，录包，或者启动自己的 ros2 程序与狗中的驱动交互。
