API 报文结构

顺序如下:

名称	内容	长度（byte）	描述
报文同步头	0x5A	1 (`uint8_t`)	报文同步头, 用于确定报文头部的开始
协议版本	1	1 (`uint8_t`)	协议的主版本号, 对于 v1.x.x 版本的协议均填 0x01
序号		2 (`uint16_t`)	请求及响应的序号, 0 ~ 65535, 请求包与响应包的这个字段是相同的, API 使用者自行填入序号。机器人对每个请求的响应都使用这个序号。这个序号是为了便于用户区分响应是对应于哪个请求的
数据区长度		4 (`uint32_t`)	数据区长度, 即 JSON 序列化数据的长度
报文类型 (编号)		2 (`uint16_t`)	标识报文的类型, 即 API 的编号, 具体见下文中各个 API 的章节
保留区域		6 (`uint8_t[6]`)	保留区, 用于未来可能的扩展
数据区		取决于头部中的数据区长度	JSON 序列化的数据内容

// C++ 的包头结构体如下
#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];
};

如上表所示, 报文头部的长度为 1 + 1 + 2 + 4 + 2 + 6 = 16 字节, 请求与响应的报文头部长度是相同的。如果某个报文类型没有数据区, 那么数据区长度的内容为 0x00000000。报文类型(编号)必须是下文API编号中的一种, 机器人若收到未定义的报文类型将会响应一个错误。若报文头部格式错误无法解析, 机器人将断开连接, 不做任何响应。若数据区解析错误, 机器人将认为这是一个错误的请求（参见对错误请求的响应）。

注 1: 每个报文头部正确的请求都会有一个响应, 编号用于将请求与响应对应起来, 一般情况下, 响应的编号为请求编号加 10000 (0x2710)

注 2: 机器人任何情况下都不会主动发送数据

注 3: 机器人若收到不属于某个端口的报文类型, 将会认为是错误的请求并响应 60000

注 4: 保留区域的 6 个字节必须填充不可省略, 一般用 0x000000000000 填充即可

请求数据区示例

以下文中的 2002 (0x07D2) 号请求为例:

2002(0x07D2) 号为重定位请求, 参数为 x 坐标, y 坐标, 标准 JSON 对象如下:

{
    "x": 10.0,
    "y": 3.0,
    "angle": 0
}

在报文中, 需要将上面的 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

响应数据区示例

以下文中的 11004 (0x2AFC) 号响应为例:

机器人当前的位置为 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
}

序列化后的数据为 {"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

API 报文结构