外观
官方示例使用说明
返回首页 | SDK 开发与运行指南 | 控制指令接口
示例来源与选择
本章介绍官方 genisom_L1_sdk 仓库中两个 HighLevel 示例的使用流程。
| 示例 | 源码 | 通信身份 | 使用场景 |
|---|---|---|---|
| Remote 示例 | remote_control.cpp | 默认 ROLE_REMOTE | 熟悉键盘遥控、姿态切换和状态读取 |
| SDK 示例 | sdk_control.cpp | ROLE_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,结合机器人实际情况确认状态有效;出现全零、长期不变或异常值时,先排查连接,不要直接尝试运动。程序打印“向前移动”等文字只代表执行了对应发送分支,不代表机器人已经执行成功。
站立、移动与停止
首次测试建议按下列顺序逐项操作,每一步确认反馈后再继续:
- 如当前不在遥控模式,按
r请求遥控控制权,再按i核对功能模式。模式含义见控制指令接口。 - 按
2请求站立,观察机器人是否站稳。 - 短按一次
w测试前进,随即按c发送零运动量,确认机器人停止。 - 按需单独验证其他方向,每次操作后都按
c停止。 - 按
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 |

