外观
心跳检测接口
接口说明
心跳检测接口对应红框中的“心跳检测端口”,用于判断 SDK 与机器人之间的通信是否仍然有效。当前 SDK 的心跳由内部线程自动维护,不是应用程序单独绑定的网络端口。
SDK 使用 UDP 发送端口 8081 发送心跳,并通过接收端口 8080 接收机器人状态。应用程序主要通过 IsConnected() 读取连接状态。
通信参数
| 参数 | 默认值 |
|---|---|
| 机器人 IP | 192.168.234.1 |
| SDK 发送端口 | 8081 |
| SDK 接收端口 | 8080 |
| 心跳周期 | 50 ms |
| 连接超时判断 | SDK 内部心跳计时超过 5 s,或尚未收到机器人数据时视为未连接 |
| 传输协议 | UDP |
工作方式
创建 ZsibotExecutor 后,SDK 会启动发送、接收和心跳通信线程:
- 心跳线程按默认周期向机器人发送心跳消息。
- 接收线程接收机器人状态和反馈消息。
- SDK 根据内部心跳计时和机器人状态接收情况维护连接状态。
- 应用程序通过
IsConnected()查询当前连接状态。
应用程序不需要自己调用心跳发送函数,也不应在外部重复创建同一端口的心跳线程。
检查连接状态
| 字段 | 内容 |
|---|---|
| 函数名 | IsConnected |
| 函数原型 | bool IsConnected() const |
| 功能概述 | 判断 SDK 是否已经收到机器人数据,并且连接仍在有效时间内 |
| 参数 | 无 |
| 返回值 | true:已经收到机器人数据且 SDK 内部心跳计时未超过 5 s;false:未建立连接或连接超时 |
| 备注 | true 只表示通信链路有效,不表示当前程序已经获得运动控制权 |
连接判定
| 条件 | 说明 |
|---|---|
| 已收到数据 | SDK 至少收到过一条机器人数据 |
| 心跳未超时 | SDK 内部心跳计时在 5 s 内 |
IsConnected() 返回 true | 上述条件同时满足 |
示例:
cpp
ZsibotExecutor robot(Role::ROLE_SDK);
while (!robot.IsConnected()) {
std::this_thread::sleep_for(std::chrono::milliseconds(100));
}断开后的处理
连接断开或 IsConnected() 返回 false 后,应用程序应:
- 停止发送运动指令和连续运动输入。
- 记录断开时间和当前运动状态。
- 等待连接恢复,或进入程序定义的安全处理流程。
- 连接恢复后重新确认机型、控制模式、故障状态和控制权。
与控制权的区别
网络连接、心跳状态和运动控制权分别表示不同的状态:
| 状态 | 含义 |
|---|---|
IsConnected() == true | SDK 能够收到机器人数据,通信链路有效 |
GetFunctionMode() | 当前功能控制来源,例如遥控、SDK 或通用 SDK |
GetControlMode() | 当前运动控制模式,例如站立、移动或锁定 |
CMD_SDK_CONTROL_RIGHT | 请求 SDK 运动控制权 |
不能因为心跳正常就直接发送高风险运动指令。现场测试应保留遥控器的软件急停或阻尼切换方式。
开发注意事项
- 不要在应用层重复绑定 SDK 已使用的 UDP 端口。
ping成功只能证明 IP 网络可达,不能证明 SDK 已收到有效状态数据。- 修改 WiFi 或机器人 IP 后,连接状态可能暂时变为
false,应用应做好重连处理。 - 断网、心跳超时、故障等级升高或程序异常时,应停止发送运动指令。

