🛠️ PND Adam U 部署 SDK

PND 半身机器人开发套件 支持从源码构建、仿真与真机控制的完整流程。

🌍 环境要求

项目	要求
操作系统	Ubuntu 22.04 x86_64（暂不支持 Mac/Windows）
网络配置	真机运行时，确保开发机与机器人 NUC 处于同一局域网内
依赖配置	安装cyclonedds和cyclonedds-cxx 库

依赖配置安装教程

# 首先安装 cyclonedds
git clone https://github.com/eclipse-cyclonedds/cyclonedds.git
cd cyclonedds
git checkout 0.10.2
mkdir build
cd build
cmake ..
make -j8
sudo make install

# 其次安装 cyclonedds-cxx
git clone https://github.com/eclipse-cyclonedds/cyclonedds-cxx.git
cd cyclonedds-cxx
git checkout 0.10.2
mkdir build
cd build
cmake ..
make -j8
sudo make install

🤖 真机控制流程

1️⃣ 启动机器人控制服务

步骤 1：启动 `pndrobotdds`

ssh pnd-humanoid@192.168.41.xx
cd ~/Documents/adam_u_deploy_dds/pndrobotdds
sudo ./run.sh
# SDK 完成启动

控制启动成功

✅ 提示：当终端出现 [DDS] Starting publish loop (400 Hz)... 表示服务已成功启动。

步骤 2：启动 `pndadamudds`

ssh pnd-humanoid@192.168.41.xx
cd ~/Documents/adam_u_deploy_dds/pndadamudds
sudo ./run.sh
# 机器人启动后默认进入 Stop 模式

控制启动成功

✅ 提示：当终端出现 FSM start! 时，表示服务已成功启动。

2️⃣ 机器人操作说明

操作模式说明

Stop 模式（阻尼模式）

触发按键：LT + B
功能描述：初始化机器人状态。除腰部 Pitch 与 Roll 外，其余关节进入阻尼模式。

Zero 模式（回零模式）

触发按键：A
功能描述：机器人返回零位位置。

进入UserControl 模式（开发者模式）

触发按键：LT + Y（仅可在 Zero 模式下切换）
功能描述：接收用户发送的控制数据，实现精确控制。
注意事项：切换至该模式时，机器人应处于零位位置；发送数据时避免波动过大，以免引发异常动作。

退出 UserControl 模式

触发按键：LT + B
功能描述：紧急退出用户控制，切回 Stop 模式。

Func 模式（功能模式）

触发按键：X
子功能：
预定动作：按 RB 顺序触发预设动作
连续预定动作：按 RT + RB 连续执行多个预设动作
遥操数据接收：按十字按键“右”进入遥操接收模式，按十字键“左”退出遥操接收模式
数据记录：
- 触发按键：LT + LB（开始/结束记录）
- 路径：pndadamudds/logs/retarget_record.txt
- 内容：31 个数据（全部关节 + 手指位置）

动作重演方法 将 retarget_record.txt 复制到 pndadamudds/resource/motion 目录下即可循环播放。

电源管理

掉电：LB + RB
上电：Y + B

🧑‍💻 开发者模式

0️⃣ 环境准备

使用网线连接笔记本与机器人
设置笔记本 IP：

参数	值
IP 地址	10.10.20.111
子网掩码	255.255.255.0

修改IP地址

2️⃣ 安装并配置 `pnd_sdk_python`

安装依赖与源码

sudo apt install libyaml-cpp-dev libspdlog-dev libboost-all-dev libglfw3-dev
sudo apt install python3-pip

cd ~
git clone https://github.com/pndbotics/pnd_sdk_python.git
cd pnd_sdk_python

sudo pip3 install -e .

🔗 详情参考：pnd_sdk_python GitHub

3️⃣ 使用 `pnd_mujoco`

① 获取网卡名称

ifconfig

查找 IP 为 10.10.20.111 的网卡名。

② 安装 `pnd_mujoco`

pip3 install mujoco
pip3 install pygame

cd ~
git clone https://github.com/pndbotics/pnd_mujoco.git

③ mujoco启动示例

Mujoco 版本: 3.2.0

cd ~/pnd_mujoco
python3 simulate_python/pnd_mujoco.py

③ 真机启动示例

真机控制前提： 确认机器人端 ~/Documents/adam_u_deploy_dds 已运行成功（参考启动机器人控制服务）。

真机状态切换到 UserControl模式： 参考操作模式说明

cd ~/pnd_mujoco
python3 example/python/open_arm.py enp59s0
# enp59s0 为网卡名，请替换成实际值

🔗 详情参考：pnd_mujoco README

📦 系统模块图

软件架构图

🔗 DDS 消息定义

1️⃣ 下发消息：`rt/lowcmd`（身体期望位置）

字段	类型	维度	含义
`motor_cmd`	`MotorCmd_`	19	19 个执行器期望位置
`reserve`	`unsigned long`	1	保留字段

2️⃣ 订阅消息：`rt/lowstate`（身体实际状态）

字段	类型	维度	含义
`motor_cmd`	`MotorCmd_`	19	19 个执行器实际位置
`reserve`	`unsigned long`	1	保留字段

3️⃣ 下发消息：`rt/handcmd`（手指期望位置）

字段	类型	维度	含义
`position`	`unsigned long`	12	手部期望位置
`reserve`	`unsigned long`	1	保留字段

4️⃣ 订阅消息：`rt/handstate`（手指实际状态）

字段	类型	维度	含义
`position`	`unsigned long`	12	手部实际位置
`reserve`	`unsigned long`	1	保留字段

5️⃣ 单个关节数据类型：`MotorCmd_`

字段	类型	含义
`mode`	`octet`	模式（0）
`q`	`float`	位置
`dq`	`float`	速度
`tau`	`float`	力矩
`kp`	`float`	刚度（不可修改）
`kd`	`float`	阻尼（不可修改）
`reserve`	`unsigned long`	保留字段

6️⃣ 单个关节数据类型：`MotorState_`

字段	类型	含义
`mode`	`octet`	模式（0）
`q`	`float`	位置
`dq`	`float`	速度
`tau_est`	`float`	力矩估计
`motorstate`	`unsigned long`	当前状态
`reserve`	`unsigned long`	保留字段

🦾 维度映射说明

身体关节（19 维）

索引	关节名称	部位
0	`waistRoll`	躯干
1	`waistPitch`	躯干
2	`waistYaw`	躯干
3	`neckYaw`	颈部
4	`neckPitch`	颈部
5–11	左臂关节	左臂
12–18	右臂关节	右臂

手部数据（12 维）

索引范围	对应手
0–5	左手
6–11	右手

单手关节映射

索引	部位
1	小拇指（Pinky）
2	无名指（Ring）
3	中指（Middle）
4	食指（Index）
5	大拇指（Thumb）
6	大拇指侧向（Lateral）

🎮 手柄控制协作

按键功能映射

按键组合	功能说明
A	所有关节回零位
X	切换 Ready 状态
B	阻尼模式锁定
LB + RB	关节电源开关（禁用中）

数据结构定义

#define XBOX_TYPE_BUTTON 0x01
#define XBOX_TYPE_AXIS   0x02

// 按钮映射
#define XBOX_BUTTON_A     0x00
#define XBOX_BUTTON_B     0x01
#define XBOX_BUTTON_X     0x03
#define XBOX_BUTTON_Y     0x04
#define XBOX_BUTTON_LB    0x06
#define XBOX_BUTTON_RB    0x07
#define XBOX_BUTTON_START 0x02
#define XBOX_BUTTON_BACK  0x05
#define XBOX_BUTTON_HOME  0x08
#define XBOX_BUTTON_LO    0x09  /* 左摇杆按钮 */
#define XBOX_BUTTON_RO    0x0a  /* 右摇杆按钮 */

// 摇杆与方向键映射
#define XBOX_AXIS_LX 0x00
#define XBOX_AXIS_LY 0x01
#define XBOX_AXIS_RX 0x02
#define XBOX_AXIS_RY 0x03
#define XBOX_AXIS_LT 0x05
#define XBOX_AXIS_RT 0x04
#define XBOX_AXIS_XX 0x06
#define XBOX_AXIS_YY 0x07

// 值定义
#define XBOX_AXIS_VAL_UP    -32767
#define XBOX_AXIS_VAL_DOWN   32767
#define XBOX_AXIS_VAL_LEFT  -32767
#define XBOX_AXIS_VAL_RIGHT  32767
#define XBOX_AXIS_VAL_MIN   -32767
#define XBOX_AXIS_VAL_MAX    32767
#define XBOX_AXIS_VAL_MID    0x00

// 数据结构
typedef struct xbox_map {
  int time;
  int a, b, x, y;
  int lb, rb, start, back, home;
  int lo, ro;
  int lx, ly, rx, ry;
  int lt, rt, xx, yy;
} xbox_map_t;

🔣 控制参数说明：Kp / Kd

仿真环境（Isaac Gym）

PD 控制器：

\[\tau = K_p e_p + K_d e_v\]

参数	含义
(K_p)	刚度
(K_d)	阻尼
(e_p)	位置误差
(e_v)	速度误差

真实机器人执行器

PID 控制器公式：

\[I = P_p P_v e_p + P_v e_v$$ $$\tau' = g I K_t = g(P_p P_v K_t e_p + P_v K_t e_v)\]

参数	含义
(P_p)	位置环比例参数
(P_v)	速度环比例参数
(g)	齿轮比
(K_t)	扭矩常数

Sim-to-Real 参数关系

满足 $\tau = \tau'$ 时：

\[K_p = g P_p P_v K_t$$ $$K_d = g P_v K_t$$ $$P_v = \frac{K_d}{K_t g}$$ $$P_p = \frac{K_p}{K_d}\]