CN
EN
JP

D1 Ultra-W⼆次开发指南

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

修订日期

修订内容

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-W，拥有 12 个自由度，具有多种运动步态和运动动作。同时，本产品开放了运动控制算法开发 SDK和通信协议，允许用户根据需要进行二次开发。


1.2 产品清单

1.3 产品参数

分类

规格

说明

基础信息

材质信息

铝合金+高强度工程塑料


站立尺寸(长*宽*高)

630mm*440mm*455mm


趴地尺寸(长*宽*高)

690mm*580mm*145mm


整机重量(含电池)

20kg


工作温度

0~40°C


防护等级

IP54


充电时长

1h


续航时间

1~2h


续航里程

9km

性能参数

基础算力

8核高性能CPU


最大速度

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年


1.4 背部负载安装


1.5 电气拓展接口

序号

接口名称

数量

说明

备注

1

以太网口

1

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

 

 

2

USB接口

2

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

3

电源接口

2

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

4

SBUS接口

1

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

5

UART接口

1

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



二、系统架构


2.1 AGIBot系统架构

 

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


2.2 SDK软件框图

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

 

 


2.3 软件服务接口列表

序号

接口名称

功能

SDK版本

1

高层运动控制接口

App Function Service Interface

 

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

V0.2.7

2

设备状态服务接口

Device Status Service Interface

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

V0.2.7

 

3

惯导状态数据接口

IMU Service Interface

获取IMU原始数据信息

 

V0.2.7

4

视频流推送数据接口

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

V0.2.7

 


三、SDK开发指南


3.1 SDK介绍

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

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

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

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

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

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

 


3.2 环境依赖

• ubuntu22.04

• Cmake 3.8+

• GCC 11+

• Eligen3

• Boost

• 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-1w/python/examples/highlevel_demo.py 中，修改initRobot()函数中IP地址

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-1w/cpp/highlevel_demo.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-1w/cpp
mkdir build
cd build
cmake ..
make -j6

3.9.2 运行sdk demo

• 运行Python demo

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

• 运行C++ demo

Plain Text
 
cd demo/zsl-1w/cpp/build
./highlevel_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-1w.md