概述
RoboKit 向用户开放机器人操作的相关 API。整套 API 采用 TCP request/response 问答的方式, 机器人作为服务器接受客户端的请求并向客户端作出响应。API 请求由头部和数据区组成，头部为普通定长的字节, 用于标识数据包基本信息以及数据区的长度及类型等，数据区为序列化后的 JSON 数据，根据头部中的类型信息进行反序列化可以得到相应的 JSON 对象。API 的响应也由头部和数据区组成，头部为根据请求得到的定长字节(响应头部与对应请求头部的关系见下文), 数据区也为序列化后的 JSON 数据。
API 测试及例程
我们将 API 测试工具开源在 Github, Source, 该工具使用 Qt 编写, 其源码可以作为例程参考。编译后的单 Windows 可执行文件也可在 Release 中下载。
API 类别
API 分为六类, 分别为机器人状态 API、机器人控制 API、机器人任务 API、机器人配置 API、机器人核心 API、其他 API。
- 机器人状态 API : 用于查询机器人各种状态量, 如位置、速度、报警信息等。
- 机器人控制 API : 用于向机器人发送开环控制指令, 如前进速度、转向速度，重定位等。
- 机器人任务 API : 用于向机器人发送任务级别的控制指令, 如去目标点、返航等。
- 机器人配置 API : 用于设置机器人的参数, 以及下载、上传地图等。
- 机器人核心 API : 用于启停机器人、更换运行脚本等。
- 其他 API : 杂项, 如喇叭控制等。
每个类别使用不用的端口, 相互独立, 因此对不同的类别可以使用不同的传输协议。
端口
| 类别 | 端口 | 允许连接数 |
|---|---|---|
| 机器人状态 API | 19204 | 10 |
| 机器人控制 API | 19205 | 1 |
| 机器人任务 API | 19206 | 1 |
| 机器人配置 API | 19207 | 1 |
| 机器人核心 API | 19208 | 1 |
| 其他API | 19210 | 1 |
机器人将对每个建立的 TCP 连接进行 KeepAlive 保活, 对已死的连接会及时的清除。
机器人若收到任何不符合本协议报文头部的错误数据包, 将会主动关闭该 TCP 连接（不会回复任何信息）。
其他情况下, 机器人不会主动断开连接, API 使用者应自己控制连接何时中断。
对于仅允许建立一个连接的端口, 如果该端口已经有连接建立, 那么机器人将不响应其他任何建立连接的请求, 直到先建立的连接断开。
对于每个连接, 机器人都是以一问一答的形式处理的, 即未作出响应前是不会处理下一个请求的, 因此建议使用时等收到上一次请求的响应后再发送下一个请求。