Skip to content

官方示例使用说明 ​

返回首页 | SDK 开发与运行指南 | 控制指令接口

示例来源与选择 ​

本章介绍官方 genisom_L1_sdk 仓库中两个 HighLevel 示例的使用流程。

示例源码通信身份使用场景
Remote 示例remote_control.cpp默认 ROLE_REMOTE熟悉键盘遥控、姿态切换和状态读取
SDK 示例sdk_control.cppROLE_SDK验证 SDK 控制权申请、运动控制和交还流程

两个示例均为键盘交互程序,SDK 示例也需要人工按键,不会启动后自动执行任务。建议先完成 Remote 示例,再验证 SDK 示例。

运行准备 ​

在 Linux x86_64 或 ARM64(aarch64)设备上操作,使用支持 C++20 的编译器以及 CMake 3.10 或更高版本。编译要求详见第八章。

机器人开机后,将开发设备连接到机器人网络,并把机器人放在平整、开阔的测试区域。准备好现场接管和停止手段,只运行一个控制示例,避免多个程序争用控制权或本机接收端口。

下载与编译 ​

以下命令适用于使用 apt 的 Linux 环境:

bash
sudo apt update
sudo apt install -y git build-essential cmake

git clone https://github.com/zsibot/genisom_L1_sdk.git
cd genisom_L1_sdk
uname -m

cmake -S . -B build
cmake --build build --target remote_control sdk_control -j2

ls -l build/example/remote_control build/example/sdk_control

已有 SDK 文件夹时,可直接进入其根目录,从 uname -m 开始执行。根目录应包含 CMakeLists.txt、example/、include/ 和 lib/。上述命令使用根工程构建,后文运行路径均以 SDK 根目录为起点,无需先安装 SDK 到系统目录。

根工程会为 x86_64 或 aarch64 选择对应的 libzsibot.a。配置报错时,检查 lib/x86_64/ 或 lib/aarch64/ 中是否包含对应静态库。不要仅通过修改架构参数把另一平台的静态库用于本机。

构建路径依据仓库的根构建配置与示例构建配置。

确认网络 ​

两个示例默认连接机器人 192.168.234.1,发送到机器人 8081/UDP,本机使用 8080/UDP 接收状态。

bash
ip addr
ping -c 4 192.168.234.1

先确认网络可达,再运行示例。ping 成功只表示 IP 链路可达,仍需确认 UDP 状态持续更新;SSH 登录成功也不代表 SDK 已连接。若现场修改了 IP 或端口,需要按交付 SDK 的构造函数接口修改源码后重新编译,当前示例未提供命令行参数解析。

Remote 示例使用流程 ​

启动与读取状态 ​

在 SDK 根目录运行:

bash
./build/example/remote_control

保持终端焦点并使用英文输入法,按小写 i 读取状态,不需要按回车。启动后不一定自动输出操作菜单,终端输入字符也不会回显。

重点检查电量、温度、功能模式、控制模式和故障信息。多次按 i,结合机器人实际情况确认状态有效;出现全零、长期不变或异常值时,先排查连接,不要直接尝试运动。程序打印“向前移动”等文字只代表执行了对应发送分支,不代表机器人已经执行成功。

站立、移动与停止 ​

首次测试建议按下列顺序逐项操作,每一步确认反馈后再继续:

  1. 如当前不在遥控模式,按 r 请求遥控控制权,再按 i 核对功能模式。模式含义见控制指令接口。
  2. 按 2 请求站立,观察机器人是否站稳。
  3. 短按一次 w 测试前进,随即按 c 发送零运动量,确认机器人停止。
  4. 按需单独验证其他方向,每次操作后都按 c 停止。
  5. 按 1 请求趴下,确认姿态稳定后按 Ctrl+C 结束程序。

松开方向键不能作为停止操作。 示例只处理字符输入,没有按键释放后自动发送零运动量的逻辑。需要主动按 c 停止;遇到异常按 0 请求软急停,并根据现场情况使用独立接管手段。

SDK 示例使用流程 ​

先停止机器人并退出 Remote 示例,再从 SDK 根目录启动:

bash
./build/example/sdk_control

该示例使用 ROLE_SDK 身份创建执行器。设置身份与取得控制权是两个步骤,启动程序后应先申请控制权。

步骤操作确认内容
1按 i状态有效,电量、温度与故障信息允许继续测试
2按 k发送 SDK 控制权申请
3再按 i核对功能模式反馈已切换到 SDK 对应模式
4按 2机器人站稳
5短按一次方向键,随即按 c单方向运动和停止均有效
6按 1机器人趴下并稳定
7按 r,再按 i请求交还 Remote 控制权并核对模式反馈
8按 Ctrl+C结束程序

控制权未确认时不要继续发送运动命令;按 k 后的终端提示仅表示命令已发出。功能模式的枚举和值以交付 SDK 头文件和控制指令接口为准。

如果按 r 后模式没有恢复,先保持机器人停止,检查连接并通过现场遥控手段确认接管状态。

常用按键 ​

两个示例的主要控制按键一致,运动是否生效取决于当前控制权、机器人状态及机型支持。

按键作用
i打印设备状态
2请求站立
1请求趴下
w前进
s后退
a左移
d右移
q左转
e右转
c发送零运动量,停止移动
0请求软急停,进入失能趴下状态
k请求 SDK 控制权
r请求 Remote 控制权
Ctrl+C终止程序;退出前应先停止机器人

注意 q 是左转键,不是退出键;0 是软急停,也不会退出程序。

其他功能按键 ​

按键作用
g请求通用 SDK 模式
b平衡站立模式
p锁定模式
7进入实验室模式
8退出实验室模式
3跳跃
4前跳
5打招呼
6后空翻
9双腿站立,再按一次取消
u卸货下蹲

SDK 模式选择提示: SDK 模式(按 k 请求)与通用 SDK 模式(按 g 请求)对应不同步态。SDK 模式对应的步态可响应小速度,适合低速建图、回充;通用 SDK 模式对应的步态可响应大速度,适合高速奔跑和上楼梯。请根据任务场景选择模式,并确认模式反馈后再进行运动测试。

首次联调只验证基础姿态、单方向运动和停止。源码将跳跃、前跳、打招呼、后空翻、双腿站立及卸货下蹲列为需要先进入实验室模式的功能;其中轮足机型不支持前五项,卸货下蹲仍需确认机型与固件支持。上述动作应在完成机型确认和现场测试准备后单独验证。

Remote 示例另有 o 按键,但仅输出 Wi-Fi 功能演示提示,实际设置调用被注释,不会修改网络配置。

如何阅读和修改示例 ​

阅读源码时,可依次查看执行器构造、键盘循环、SetRemote()、SetCmd() 和状态读取分支。

代码位置关注内容
执行器构造Remote 使用默认身份;SDK 显式指定 ROLE_SDK
switch (ch)每个输入字符对应的操作
SetRemote()发送方向运动量;c 对应四个分量全零
SetCmd()请求姿态、功能模式和控制权切换
case 'i'读取电池、模式、速度、故障及关节状态等信息

修改源码后,在 SDK 根目录重新执行构建命令,再运行生成的程序。运动量字段顺序与范围请查阅控制指令接口,不要把源码中的 0.5 直接当作所有方向上的物理速度。

状态输出仅用于调试:当前示例的部分关节输出标签存在重复或错位,电机温度也只打印数组前四项。确认具体关节时,应以调用的 Getter、数组索引与传感器实时上报接口为准。

开发自动任务时,需要用业务控制逻辑替换键盘分支,并补充连接有效性检查、控制权反馈确认、运动超时归零和异常退出处理。示例未提供完整的自动任务与安全退出机制,不能假定 Ctrl+C 会自动执行停止或交还控制权。

退出与常见问题 ​

两个程序会修改终端输入模式,退出后如果输入内容不显示,可直接键入以下命令并回车:

bash
stty sane

必要时再执行 reset 恢复终端。

现象排查与处理
找不到可执行文件确认使用根工程构建,且当前处于 SDK 根目录;检查 build/example/
编译或链接失败检查 C++20 支持、架构及对应静态库;详见第八章
程序运行但不响应按键使用交互式终端、英文输入法和小写字母,确认终端焦点
终端打印动作但机器人不动检查 UDP 连接、当前控制权、模式、故障与机型支持
SDK 示例运动无效先按 k,再读取功能模式确认;仅设置 ROLE_SDK 不够
状态为零或长期不变检查 IP、UDP 端口、防火墙与机器人服务,暂停运动测试
松键后机器人仍移动主动按 c;示例没有按键释放自动归零处理
无法绑定接收端口退出其他 SDK 示例或占用本机 8080/UDP 的程序后重试
退出后终端不回显执行 stty sane,必要时执行 reset

返回首页 | 上一章:SDK 开发与运行指南