CN
EN
JP

D1 Edu\Ultra⼆次开发指南

发布时间：2026-03-31 11:08:15

文档修订记录

修订日期

修订内容

sdk版本

2025-07-16

• 初始版本sdk

v2.0.5

2025-07-19

• 新增高层sdk接口

v2.0.6

2025-09-15

• 修复“checkconnect”接口状态异常的问题

v0.2.6-patch1

2025-11-04

• 新增底层sdk接口

• 新增D1 Ultra-W高层sdk接口

v2.0.7



一、产品介绍

1.1 产品概述

意昂4仿生四足机器人 D1 Ultra\Edu，拥有 12 个自由度，具有多种运动步态和运动动作。同时，本产品开放了运动控制算法开发SDK和通信协议，允许用户根据需要进行二次开发。

注：本二次开发文档适用于D1 Edu和D1 Ultra，且固件版本在0.2.6及以上



1.2 产品清单

1.3 产品参数

分类

规格

说明

基础信息

材质信息

 

铝合金+高强度工程塑料(酚醛树脂)

Edu:   潘通色号PANTONE Warm Gray 5U

Ultra：潘通色号PANTONE Warm Gray 3U

站立尺寸(长*宽*高)

630mm*360mm*415mm

趴地尺寸(长*宽*高)

670mm*425mm*145mm

整机重量(含电池)

15kg

工作温度

0~40°C

防护等级

IP54

充电时长

1h

续航时间

1~2h

续航里程

6km

性能参数

基础算力

8核高性能CPU

工作最大功率

3500W

最大速度

3.7m/s

最大载荷

8kg(极限10kg)

连续攀爬楼梯高度

16cm

最大爬坡角度

标准环境30度，极限环境40度

跳跃起来离地高度

35cm

整机关机参数

执行器类型

高功率密度运动单元

最大关节扭矩

48N.M

关节运动空间(机身)

-28°~28°

关节运动空间(大腿)

-170°~66°

关节运动空间(小腿)

-35°~156°

传感器

相机FOV

DFO122°，HFO122°，VFO70°

IMU

标配

功能列表

标准动作

站立、卧倒、阻尼、俯仰身形、高低身形、水平转身

特技动作

向前跳、向后跳、双腿站立、后空翻、打招呼等

实时图像传输

支持

OTA升级

支持

二次开发

支持

功能拓展接口

以太网口、USB接口、电源接口、SBUS接口、UART接口

配件

适配器

标配

充电座

标配

手持遥控器

选配

带屏遥控器

选配

EPP拉杆箱

选配

其他

保修期

1年

 

充电时长数据在标准环境温度25°下测得

续航里程数据为在速度1m/s，无负载工况下测得

以上参数为实验室测试数据，实际表现可能因使用环境，操作方式等因素有所差异，请以实际为准


1.4 背部负载安装

 

注：背部负载安装孔位为M4，安装时需去除掉螺纹孔的防尘软塞。


1.5 电气拓展接口

序号

接口名称

数量

说明

备注

1

以太网口

1

RJ45接口，支持1000Mbps传输速率，用于高速数据传输，支持网络连接、远程监控、数据传输等应用


2

USB接口

2

Type_A接口，用于连接外部存储设备、摄像头、传感器等USB设备，提供高速数据传输和电力供应

3

电源接口

2

标准DC电源接口，提供稳定的电源供应，支持12V(3A)和24V(1.5A)电压输出，输出总功率不高于36W（后续版本会支持100W），对插接口型号是 XT30U-M

4

SBUS接口

1

标准SBUS接口，用于连接遥控器接收器或其他支持SBUS协议的通信设备，实现精确的遥控指令传输

5

UART接口

1

标准UART接口，用于连接嵌入式系统、通信设备或其他支持UART协议的设备，通过异步串行通信实现设备间的数据交换与控制


二、系统架构


2.1 AGIBot系统架构

 

注：实线框图为已实现功能，虚线框图可通过二次开发实现


2.2 SDK控制框图

2.3 SDK接口框图

当前已开放运动控制相关SDK接口，包括高层运动控制接口、底层电机控制接口、IMU惯导数据接口和电机状态数据接口


2.4 软件服务接口列表

序号

接口名称

功能

SDK版本

1

高层运动控制接口

App Function Service Interface

 

实现机器狗的高层运动控制，包括前后转向速度运动，趴下，旋转，四肢站立等

V0.2.6

2

底层电机控制接口

Motor Control Service Interface

 

控制电机底层接口，设置电机的目标运动状态，包括位置、速度、扭矩等。通过设置不同的参数，用户可以控制电机在不同的模式下执行特定的动作

V0.2.6

 

3

设备状态服务接口

Device State Service Interface

查询并获取当前设备状态和系统资源使用信息

V0.2.6

 

4

惯导状态数据接口

IMU Service Interface

获取IMU原始数据信息

 

V0.2.6

5

视频流推送数据接口

向客户端推送相机本体视频流

V0.2.6

6

控制权切换sdk接口

提供遥控器和sdk之间控制权切换的功能

v2.0.7


三、SDK开发指南


3.1 SDK介绍

• 本文档描述了 D1 Ultra\Edu 的软件开发工具包 (SDK)，提供其核心服务接口的详细信息，包括高层运动控制接口、底层电机控制接口、IMU 惯导数据接口、电机状态数据接口。

• 各章节分别介绍不同服务接口的调用方法、数据输入/输出的标准格式定义与一些功能开发示例。

• 接口定义会随量产开发状态产生变更，请以最新版本的接口定义文档为准。

• SDK程序与狗本体内程序通讯存在特定协议，故不同版本的SDK程序与狗本体内程序通讯存在差异，请根据设备版本选择对应版本SDK程序。若条件允许，建议更新狗内程序到最新版本，以获得更好的兼容性。

• SDK接口控制时，全部状态均由二次开发者设计指定，本体运控不做额外的干预与状态跳转。

• 运行SDK时, 请保证系统有足够的资源, 否则可能出现运动控制模块失效的情况。


3.2 环境依赖

• ubuntu22.04

• Cmake 3.8+

• GCC 11+

• Eigen3

• Boost 1.74

• python3+

3.3 网络连接

设备上配备无线网络与有线网络接口，其中无线网络信息位于设备右侧或腹部标签，标签内标注有设备SSID与密码信息，机器狗本体默认IP如下表：

网络接口

IP地址

DHCP

无线网络

192.168.234.1

有

有线网络

192.168.168.168

无

无线网络配备DHCP服务，连接上无线网络后，确保操作设备无线网络未配置固定IP，可以直接通过192.168.234.1与机器人建立通讯。

有线网络不配备DHCP服务，通过有线连接后，需要再操作设备有线网络配置固定IP，且IP为168网段，即可与机器人建立通讯。

3.4 设备登录

设备提供ssh登录，通过无线或有线与设备创建连接后，可通过ssh登录设备

 


• 无线连接方式

Plain Text
 
ssh firefly@192.168.234.1     #密码:firefly

• 有线连接方式

Plain Text
 
ssh firefly@192.168.168.168    #密码:firefly


3.5 固件版本号查询

 登录设备后，执行以下命令查看当前设备版本：

Bash
 
grep -oP 'motion-control_\K[^_]+' /etc/release/*[^rootfs]*.yaml

 

以上图为例：602002057TBD.yaml:0.2.7

固件版本号：第567位, 即固件为2.0.5

sdk版本号: 输出内容，即运控版本为0.2.7

若命令执行后版本号低于0.2.6，则说明设备版本过低，需要联系售后进行升级。

本文档适用于SDK版本0.2.6及以上版本，若低于此版本，请联系售后技术人员进行升级

 

0.3.4以下版本机器狗： sdk控制期间，遥控器无法使用

0.3.4及以上版本机器狗：sdk控制期间，可切换控制权，实现遥控器和sdk控制权的切换控制

如需需要控制权切换功能，请联系售后技术支持人员进行升级


3.6 SDK获取

way1:可联系售后支持人员获取

way2:通过如下github地址获取

Plain Text
 
git clone https://github.com/AgibotTech/agibot_D1_Edu-Ultra.git


3.7 sdk文件配置

3.7.1 无线连接模式

step1 修改sdk通信配置文件

通过vim命令修改机器狗本体/opt/export/config/sdk_config.yaml文件：

Plain Text
 
target_ip: "192.168.234.xx" #local_ip
target_port: 43988

• target_ip：机器狗控制端IP地址，切勿IP冲突(不能为192.168.234.1)

• target_port：默认43988，切勿修改

step2 配置参数修改后，需重启机器狗生效

 

3.7.2  有线连接模式

step1 修改sdk通信配置文件

通过vim命令修改机器狗本体/opt/export/config/sdk_config.yaml文件：

Plain Text
 
target_ip: "192.168.168.xxx"  #local_ip
target_port: 43988

• target_ip：机器狗控制端IP地址，切勿IP冲突(不能为192.168.168.168)

• target_port：默认43988，切勿修改

step2 配置SDK_CLIENT_IP

如需要使用网线或其他非192.168.234.X网段IP控制设备，需要通过vim命令修改

/opt/app_launch/start_motion_control.sh文件：

Bash
 
#!/bin/bash

echo "start motion control"

# 共享内存文件路径
SHM_FILE="/dev/shm/spline_shm"

# 循环检查设备是否存在
while true; do
    if [ -e "$SHM_FILE" ]; then
        echo "共享内存文件 $SHM_FILE 已存在。"
        break
    else
        echo "共享内存文件 $SHM_FILE 不存在，等待 1 秒后重试..."
        sleep 1
    fi
done

# 共享内存文件存在后执行的命令
echo "共享内存文件已准备好，可以执行后续操作。"

sudo ifconfig lo multicast
sudo route add -net 224.0.0.0 netmask 240.0.0.0 dev lo

export LD_LIBRARY_PATH=/opt/export/mc/bin
export ROBOT_TYPE=P2
export SDK_CLIENT_IP="机器人ip"

cd /opt/export/mc/bin && taskset -c 7 ./mc_ctrl r

• 在上面代码27行，增加对应配置:export SDK_CLIENT_IP="机器人ip"，并将机器人的IP地址填写在对应参数内

• 若使用有线网络，则将机器人IP修改为192.168.168.168,如果是其他IP则修改到对应IP即可

step3 修改网卡名称

修改机器狗本体内/etc/systemd/system/robot-launch.service文件

在Service里面添加一行Environment="ROBOT_NET_INTERFACES=wlan0"，其中wlan0为对应网卡名称，若使用有线网络可修改为eth0

完整配置文件如下：

JSON
 
[Unit]
Description=Run robot-launch at startup
After=network.target

[Service]
ExecStart=robot-launch server
ExecStop=/usr/local/bin/robot_launch_stop.sh
TimeoutStopSec=5s
Restart=always
User=root
Environment="ROBOT_HOME=/home/firefly"
Environment="ROBOT_LOG_DIR=/userdata/log"
Environment="ROBOT_NET_INTERFACES=wlan0"  #使用有线连接，wlan0 修改为 eth0

[Install]
WantedBy=multi-user.target

 

此参数配置后有概率导致机器狗无法使用遥控器！

配置SDK_CLIENT_IP后，若设备开机后网络未初始化完成，对应网卡未分配IP地址，导致运控程序绑定IP地址失败，会造成机狗无法使用遥控器。


3.8 修改SDK Demo配置

3.8.1 配置python IP和端口

在 {用户目录}/agibot_D1_Edu-Ultra-main/demo/zsl-1/python/examples/ 中，按需修改

Python
 
app.initRobot("127.0.0.1", 43988, "127.0.0.1")    #local_ip, local_port, dog_ip

 

3.8.2  配置C++ IP和端口

在 {用户目录}/agibot_D1_Edu-Ultra-main/demo/zsl-1/cpp/ 中，按需修改

C++
 
  constexpr int CLIENT_PORT = 43988;   // local port
  std::string CLIENT_IP = "127.0.0.1"; // local IP address
  std::string DOG_IP = "127.0.0.1";    // dog ip

 

配置参数中机器人IP和本地端口需与sdk_config中target_ip和target_port参数保持一致。

请确保机器人 IP 和端口号匹配，否则无法建立通信！

如果删除或注释掉sdk_config.yaml中ip会导致机器的运控服务无法自起！

当设备程序进行更新，或运控程序进行更新后，配置文件会被重置，相关配置需要重新配置！

 

如果是在四足机器人本体通过wifi连接的方式运行sdk demo程序，local ip和dog ip均设为192.168.234.1


3.9 示例Demo运行步骤

3.9.1  编译demo

在本地PC端，进入到sdk文件中

Bash
 
cd demo/zsl-1/cpp
mkdir build
cd build
cmake ..
make -j6

3.9.2 运行sdk demo

• 运行Python demo

Plain Text
 
cd demo/zsl-1/python/examples
python highlevel_demo.py
or
python lowlevel_demo.py

• 运行C++ demo

Plain Text
 
cd demo/zsl-1/cpp/build
./highlevel_demo
or
./lowlevel_demo

 

3.10  二开控制说明

指令下发需要按照以下状态跳转逻辑，否则可能会造成机器摔倒、故障、不响应等异常情况。

 

3.10.1 关节控制命令说明

�� 命令顺序

• FR（右前）

• FL（左前）

• RR（右后）

• RL（左后）

3.10.2 关节方向定义

A,H,K关节坐标系：前X， 左Y， 上Z

坐标方向符合右手坐标系，前向为X正方向，左为Y正方向，上为Z正方向

腿的顺序前右前左，后右后左

 

注：使用sdk控制时，需要加入低电量预警逻辑，当机器狗电量不足时，sdk连接会自动断开，在进行上层sdk控制时，需加入对应的处理逻辑

 


四、API函数介绍

详细接口说明，请查看对应版本的sdk说明文档：

https://github.com/AgibotTech/agibot_D1_Edu-Ultra/blob/main/docs/api_zsl-1.md


五、调试指南


5.1 视频流推送服务

机器狗广角相机的视频以Gstreamer方式推流到以下URL:

Plain Text
 rtsp://192.168.234.1:8554/test      #无线连接方式
 rtsp://192.168.168.168:8554/test    #有线连接方式

默认会在遥控器侧拉流显示实时画面，可通过VLC或者OpenCV进行预览和调用


5.2 指示灯说明

5.2.1 机器狗尾灯说明

灯光

灯语

备注

蓝色常亮

开机完成

正常状态

蓝色闪烁

开机中


白色常亮

实验室模式

此模式下可使用特技动作

绿灯常亮

追踪模式开启

sdk控制模式


黄灯常亮

电池电量低于20%

电池电量不足，无法开启狂暴模式，无法进行sdk控制

黄灯闪烁

电池电量低于5%

电池电量不足，需立即充电

红灯常亮

关节温度过高，需要冷却


红灯闪烁

系统异常

需要联系售后排查

5.2.2 电池指示灯说明


5.3 异常日志查询

log目录：/home/firefly/tmp/log

注意：机器狗内部设置了开机后日志清理服务，出现异常后，不要关机，先获取日志

 


5.4 控制权切换功能

适用于意昂4四足D1 Edu、D1 Ultra型号机器狗，用于说明遥控器和sdk控制之间切换控制权的使用方法

不支持同时采用sdk和遥控器进行控制

采用sdk控制时，如果电量较低，会自动将控制权切换至遥控器端

5.4.1 版本要求

机器狗固件版本：v0.2.5及以上

遥控器app软件版本：v2.4.5及以上

5.4.2 功能说明

控制端

如何切换

灯语说明

遥控器端

罗技手柄遥控器

长按LT+RT+A

遥控器模式：机器狗尾灯常蓝

 

SDK控制模式:机器狗尾灯常绿

 

带屏遥控器

长按L2+R2+A

SDK端

CPP

 

切换到SDK模式：zsibot_exec.SetCmd(CmdCode::CMD_SDK_CONTROL_RIGHT);

切换到遥控器模式：

zsibot_exec.SetCmd(CmdCode::CMD_REMOTE_CONTROL_RIGHT);

5.4.3 控制框图


六、FAQ


6.1：connect time out

运行SDK程序后存在连接超时，提示信息为：

Bash
 
client bind success
connect time out
error async receive from

1. 请按照文档修改SDK配置文件中target_ip参数。

2. 若与设备通讯采用非WiFi直连，还需按照文档修改SDK_CLIENT_IP参数。非WiFi直连时，设备会有概率出现运控绑定SDK失败，请按照文档有线连接绑定IP失败修改参数。


6.2：有线连接绑定IP失败

在配置SDK_CLIENT_IP后，若使用wlan0网络或者eth0网络进行SDK控制时，会存在设备开机后网络未初始化完成，对应网卡未分配IP地址，导致运控程序绑定IP地址失败。

具体表现为SDK程序运行后提示：connect time out，通过登录设备主控后，执行命令sudo lsof -i -P -n -c mc_ctrl | grep 43997查看输出内容,运控对应端口未被绑定。

通过修改设备主控内/etc/systemd/system/robot-launch.service文件配置可修复，在Service里面添加一行Environment="ROBOT_NET_INTERFACES=wlan0"其中wlan0为对应网卡名称，若使用有线网络可修改为eth0。

完整配置文件如下：

Bash
 
[Unit]
Description=Run robot-launch at startup
After=network.target

[Service]
ExecStart=robot-launch server
ExecStop=/usr/local/bin/robot_launch_stop.sh
TimeoutStopSec=5s
Restart=always
User=root
Environment="ROBOT_HOME=/home/firefly"
Environment="ROBOT_LOG_DIR=/userdata/log"
Environment="ROBOT_NET_INTERFACES=eth0"

[Install]
WantedBy=multi-user.target

 

参数配置后需进行重启设备生效！

 

此参数配置后有概率导致机器狗程序无法启动！

配置ROBOT_NET_INTERFACES后程序会检测所配置网卡是否被分配IP，若网卡始终没有IP，则会导致机器狗程序无法启动。

 


6.3：使用wlan0连接环境wifi，每次重启设备都不会自动连接

设备上AP与wlan网卡存在冲突，部分版本有清除自动连接功能，若需要关闭清除自动连接功能，可执行以下命令：

Bash
 
sudo systemctl stop networkmanager-cleanup.service      //关闭网络清除服务
sudo systemctl disable networkmanager-cleanup.service   //禁用网络清除服务


6.6: 运控中获取设备状态获取接口支持频率？

 lowlevel 的500hz, highlevel的50hz。


6.7: SDK中控制接口支持频率？

 控制数据最大可以支持500hz发送，一般来说20~50hz就可以保证设备稳定运行。


6.8: SDK程序是否为线程安全？

SDK程序为线程安全。


6.9: SDK是否存在通讯检测？

运控程序会检测是否持续收到SDK数据，若3秒内未收到数据，则认为SDK通讯中断，设备会自动切换阻尼模式趴下。


6.10: 在机器内通过service启动运控程序时，如何避免机器自身程序未启动？

service中After参数可以配置为robot-launch，robot-launch服务会启动机器自身程序。


6.11: 手柄遥控和sdk遥控可以同时切换吗？

 当前版本SDK优先级高于手柄遥控，无法同时切换。


6.12: 获取到的IMU数据是否是原始数据？

获取到的IMU数据是原始数据。


6.13: 获取到的IMU数据感觉存在误差？

 设备体内IMU数据受产品型号影响，精度存在误差，若对IMU精度有更高要求，需要单独采购高精度IMU在上身使用。


6.14: 使用过SDK控制后，再使用手柄遥控控制设备时，发送站立指令为什么设备会原地做‘俯卧撑’？

如果配置过SDK_CLIENT_IP参数，则运控启动时会绑定对应IP，若IP不存在，则会导致此现象。  


6.15: 四元数转换为欧拉角时，旋转顺序是什么？

欧拉角顺序为ZYX，即先Z轴旋转，再Y轴旋转，最后X轴旋转。


6.16: Highlevel与Lowlevel可以同时使用吗？

Highlevel与Lowlevel不可以同时使用，且在切换两种接口时，要预留一定时间等待设备端口释放。


6.17: 为什么运控程序升级后，SDK无法控制设备？

运控程序升级后，运控相关配置会被覆盖，需要重新配置SDK_CONFIG与SDK_CLIENT_IP参数。


6.18: 是否有ROS接口？

暂无ROS接口。


6.19: 使用SDK时，程序卡在initRobot函数不往下执行了？

SDK依赖boost 1.74.0版本，若使用版本过旧，可能存在结构体变化导致的兼容性问题。


6.20:是否支持在机器狗本体部署控制逻辑

不建议在机器狗本体部署控制逻辑，机器狗内部无多余算力