仙知网络协议API使用指南

  在操作移动机器人时，用户需要使用相关 API，

  有这方面需求的小伙伴，请认真看这篇文章哦！

一、API 简介

  整套 API 采用 TCP request/response 问答的方式, 机器人作为服务器接受客户端的请求并向客户端作出响应。

  API 请求由头部和数据区组成，头部为普通定长的字节, 用于标识数据包基本信息以及数据区的长度及类型等，数据区为序列化后的 JSON 数据，根据头部中的类型信息进行反序列化可以得到相应的 JSON 对象。

  API 的响应也由头部和数据区组成，头部为根据请求得到的定长字节(响应头部与对应请求头部的关系见下文), 数据区也为序列化后的 JSON 数据。

二、API 测试及例程

  我们将 API 测试工具开源在 Github,Source, 该工具使用 Qt 编写, 其源码可以作为例程参考。

  编译后的单 Windows 可执行文件也可在Release中下载。

三、API 类别

  API 分为六类, 分别为机器人状态 API、机器人控制 API、机器人导航 API、机器人配置 API、其他 API。

  1、机器人状态 API

  用于查询机器人各种状态量, 如位置、速度、报警信息等。

  2、机器人控制 API

  用于向机器人发送开环控制指令, 如前进速度、转向速度，重定位等。

  3、机器人导航 API

  用于向机器人发送导航指令, 如去路径返航、自由导航等。

  4、机器人配置 API 

  用于设置机器人的参数, 以及下载、上传地图等。

  5、其他 API

  杂项, 如喇叭控制等。

  每个类别使用不用的端口, 相互独立, 因此对不同的类别可以使用不同的传输协议。

四、API 简介

  备注

  1. 每个端口 API 请求的时间间隔为 200ms，请勿过快。

  2. 机器人将对每个建立的 TCP 连接进行 KeepAlive 保活, 对已死的连接会及时的清除。

  3. 机器人若收到任何不符合本协议报文头部的错误数据包, 将会主动关闭该 TCP 连接（不会回复任何信息）。

  4. 其他情况下, 机器人不会主动断开连接, API 使用者应自己控制连接何时中断。

  5. 对于仅允许建立一个连接的端口, 如果该端口已经有连接建立, 那么机器人将不响应其他任何建立连接的请求, 直到先建立的连接断开。

  6. 对于每个连接, 机器人都是以一问一答的形式处理的, 即未作出响应前是不会处理下一个请求的, 因此建议使用时等收到上一次请求的响应后再发送下一个请求。