API结构
| 名称 | 内容 | 长度（byte） | 描述 |
|---|---|---|---|
| 报文同步头 | 0x5A | 1 (uint8) | 报文同步头, 用于确定报文头部的开始 |
| 协议版本 | 1 | 1 (uint8) | 协议的主版本号, 目前均填 0x01 |
| 序号 | 2 (uint16) | 请求及响应的序号（0 ~ 65535），请求包与响应包的这个字段是相同的，API 使用者自行填入序号。机器人对每个请求的响应都使用这个序号。 | |
| 数据区长度 | 4(uint32) | 数据区长度, 即 JSON 序列化数据的长度 | |
| 报文类型 (编号) | 2(uint16) | 标识报文的类型, 即 API 的编号, 具体见 下文 中各个 API 的章节 | |
| 内部使用区域 | 6(uint8[6]) | 程序内部使用（不必关注该区域的内容，其内容可能不为 0 且可能会发生变化） | |
| 数据区 | 取决于头部中的数据区长度 | JSON 序列化的数据内容 |
#include <stdint.h>
struct ProtocolHeader {
uint8_t m_sync;
uint8_t m_version;
uint16_t m_number;
uint32_t m_length;
uint16_t m_type;
uint8_t m_reserved[6];
};
2
3
4
5
6
7
8
9
如上表所示, 报文头部的长度为 1 + 1 + 2 + 4 + 2 + 6 = 16 字节, 请求与响应的报文头部长度是相同的。
- 如果某个报文类型没有数据区, 那么数据区长度的内容为 0x00000000。
- 报文类型(编号)必须是下文 API 编号中的一种, 机器人若收到未定义的报文类型将会响应一个错误。
- 若 报文头部 格式错误无法解析, 机器人将 断开连接 , 不做任何响应。
- 若数据区解析错误也将会响应一个错误。
注意：
- 每个报文头部正确的请求都会有一个响应, 编号用于将请求与响应对应起来, 一般情况下, 响应的编号为请求编号加 10000 (0x2710)
- 机器人任何情况下都不会主动发送数据
- 机器人若收到不属于某个端口的报文类型, 将会响应错误
- 保留区域的 6 个字节必须填充不可省略, 用 0x000000000000 填充即可
请求示例
以下文中的 2002 (0x07D2) 号请求为例
请求数据区结构如下：
| 字段名 | 类型 | 描述 | 可缺省 |
|---|---|---|---|
| x | number | 世界坐标系中的 x 坐标, 单位 m | 是 |
| y | number | 世界坐标系中的 y 坐标, 单位 m | 是 |
| angle | number | 世界坐标系中的角度, 单位 rad | 是 |
2002(0x07D2) 号为重定位请求, 参数为 x 坐标, y 坐标, 标准 JSON 对象如下:
{
"x": 10.0,
"y": 3.0,
"angle": 0
}
2
3
4
5
在报文中, 需要将上面的 JSON 对象序列化并塞入报文的数据区, 并将序列化后的长度填入报文头部的数据区长度中。
序列化后的数据为 {"x":10.0,"y":3.0,"angle":0}，转化为十六进制为 7B 22 78 22 3A 31 30 2E 30 2C 22 79 22 3A 33 2E 30 2C 22 61 6E 67 6C 65 22 3A 30 7D，长度为 28(0x1c) 个字节，因此头部为 5A 01 00 01 00 00 00 1C 07 D2 00 00 00 00 00 00，将头部与数据区拼接在一起得到一个请求如下(共 44 字节):
5A 01 00 01 00 00 00 1C 07 D2 00 00 00 00 00 00
7B 22 78 22 3A 31 30 2E 30 2C 22 79 22 3A 33 2E 30 2C 22 61 6E 67 6C 65 22 3A 30 7D
2
响应示例
以下文中的 11004 (0x2AFC) 号响应为例
响应数据区结构如下：
| 字段名 | 类型 | 描述 | 可缺省 |
|---|---|---|---|
| x | number | 机器人的 x 坐标, 单位 m | 是 |
| y | number | 机器人的 y 坐标, 单位 m | 是 |
| angle | number | 机器人的 angle 坐标, 单位 rad | 是 |
| confidence | number | 机器人的定位置信度, 范围 [0, 1] | 是 |
| ret_code | number | API 错误码 | 是 |
每一次返回的数据区 JSON Object 中 Key 的顺序是不保证的，因为 JSON 并没有规定这一点。
机器人当前的位置为 x = 6.0, y = 2.0, angle = 1.57, confidence = 0.9, 表示成 JSON 对象如下:
{
"ret_code": 0,
"x": 6.0,
"y": 2.0,
"angle": 1.57,
"confidence": 0.9
}
2
3
4
5
6
7
序列化后的数据为 {"ret_code":0,"x":6.0,"y":2.0,"angle":1.57,"confidence":0.9}，转化为十六进制为
7B 22 72 65 74 5F 63 6F 64 65 22 3A 30 2C 22 78 22 3A 36 2E 30 2C 22 79 22 3A 32 2E 30 2C 22 61 6E 67 6C 65 22 3A 31 2E 35 37 2C 22 63 6F 6E 66 69 64 65 6E 63 65 22 3A 30 2E 39 7D
长度为 60(0x3C) 字节，因此响应的头部为 5A 01 00 01 00 00 00 3C 2A FC 00 00 00 00 00 00 拼接后数据如下(共 76 字节):
5A 01 00 01 00 00 00 3C 2A FC 00 00 00 00 00 00
7B 22 72 65 74 5F 63 6F 64 65 22 3A 30 2C 22 78 22 3A 36 2E 30 2C 22 79 22 3A 32 2E 30 2C 22 61 6E 67 6C 65 22 3A 31 2E 35 37 2C 22 63 6F 6E 66 69 64 65 6E 63 65 22 3A 30 2E 39 7D
2
响应结构
API 响应数据区通常包含如下字段：
| 字段名 | 类型 | 描述 | 可缺省 |
|---|---|---|---|
| ret_code | number | API 错误码 | 是 |
| create_on | string | API 上传时间戳 （3.3.3.59及以上版本加入） | 是 |
| err_msg | string | 错误信息 | 是 |
- API 错误码为响应数据区 JSON 对象包含的错误码（
ret_code），用于指示对请求执行不成功或请求出错等错误。若 ret_code 为 0 或缺省，说明没有错误，若不为 0，说明发生了错误，错误码见 附录A: API 错误码。 - 没有错误时，err_msg 也会缺省，即会出现数据区为空的情况。
- create_on为API返回时的时间戳，于
3.3.3.59版本加入。
感谢反馈
感谢反馈
