# 程序控制文档
---
## 一、基本说明
- **版本号**：`v3.5.4`
- **适用算法**：OCR、色块、AprilTag
- **串口波特率**：115200
- **协议详情参见**：[附录：通信协议规范](#附录：通信协议规范)
---
## 二、支持算法列表
| 算法ID | 名称 | 简介说明 |
| ---- | -------- | ----------------------------- |
| `0` | 空 | 开机默认状态，无算法运行 |
| `1` | 色块检测 | 默认 LAB 参数为 0，需配合 `S` 指令设置颜色范围 |
| `2` | Apriltag | 检测 Apriltag 标签，返回 ID 与旋转角度 |
| `3` | OCR | 光学字符识别 |
| `4` | 交叉点 | 测试中功能，尚未稳定 |
---
## 三、串口发送格式
| 操作 | 指令字符 | 参数格式与说明 | 示例命令 |
| ------------ | ---- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| **开启指定算法** | `N` | `<算法ID>`
立即切换当前运行算法 | `N1`（启动色块检测） |
| **设置LAB参数** | `S` | `<参数ID>+LMin+LMax+AMin+AMax+BMin+BMax>`
用于色块检测的颜色范围（LAB色彩空间，0~255） | `S1+0+100+30+80+20+70` |
| **设置串口应答模式** | `A` | `<模式>`
• `-n`：定时上报，间隔 n 毫秒
• `0`：关闭上报
• `n>0`：仅上报第n个目标后自动切回 `A0` | `A-500`
`A0`
`A2` |
| **缩放画面比例** | `Z` | `<缩放倍数>`
以画面中心为基准缩放。`Z100`=原始尺寸，`Z150`=放大至150% | `Z100`
`Z150` |
| **设置分辨率** | `R` | `<分辨率>`
格式：`宽x高`，如 `552x368` | `R552x368` |
| **设置检测框显示项** | `D` | `+标识符+状态`
标识符: `i`, `x`, `y`, `w`, `h`, `v`, `r`, `cx`, `cy`
状态: `1`=显示, `0`=隐藏 | `D+i1+cx1+cy1`
`D+i1+x0+y0` |
| **设置色块算法参数** | `C` | `+合并开关+合并距离+最小X比例+最小Y比例`
合并开关：`1`=开启，`0`=关闭
合并距离：n>=0，小于n个像素的色块会被合并 | `C+1+30+0+0`(合并30像素间距色块)
`C+0+30+0+0`(不合并)
`C+0+30+30+50`（不合并，色块的面积、宽度、高度分别不低于面积阈值、最小Y尺寸，否则不返回) |
---
## 四、串口接收格式
返回数据以 `#` 开头，`!` 结尾
### 基础通用格式（适用于色块、OCR等）
```
#i{x}y{y}w{w}h{h}v{v}!
```
### 特殊格式 - Apriltag（含旋转角度）
```
#i{i}x{x}y{y}w{w}h{h}v{v}r{r}!
```
### 字段含义说明
| 字段 | 含义 | 说明 |
| --- | -------- | ----------------------------------------------------------- |
| `i` | 目标序号 | 第几个被检测到的目标（从 `1` 开始递增） |
| `x` | 中心点 X 坐标 | 目标在图像中的横向像素坐标 |
| `y` | 中心点 Y 坐标 | 目标在图像中的纵向像素坐标 |
| `w` | 宽度 | 目标包围框宽度（像素） |
| `h` | 高度 | 目标包围框高度（像素） |
| `v` | 结果值 | 根据算法不同：
• Apriltag → 标签 ID
• 色块 → LAB 参数组 ID（如 S1/S2） |
| `r` | 旋转角度 | 仅Apriltag |
### 示例输出（色块检测）
若检测到三个色块：
```
#i1x100y120w50h50v1!
#i2x200y160w60h60v1!
#i3x300y200w55h55v1!
```
### 输出排序规则
多个目标按以下优先级排序：
1. **X 坐标升序**
2. **Y 坐标升序**
---
# 附录：通信协议规范
## 一、数据帧结构
| 字段名 | 长度 | 描述 |
|----------------|----------|----------------------------------------------------------------------|
| `header` | 4B (LE) | 帧头标识，固定值 `0xAA 0xCA 0xAC 0xBB`，先发 `0xAA` |
| `data_len` | 4B (LE) | 数据总长度 = `flags + cmd + body + crc` 的字节数 |
| `flags` | 1B | 控制标志位，含响应类型、状态、版本等 |
| `cmd` | 1B | 命令类型，预定义命令从 255 递减，自定义命令范围 `0 ~ CMD_APP_MAX` |
| `body` | nB | 变长数据体，最大支持 `(2^32 - 1)` 字节 |
| `CRC16_IBM` | 2B (LE) | 校验码，覆盖 `header` 至 `body` 所有字段，低位在前 |
---
## 二、字段详解
### 1. Header（帧头）
- 固定 4 字节：`0xAA 0xCA 0xAC 0xBB`
- 发送顺序：`AA → CA → AC → BB`
### 2. Data Length（数据长度）
- 小端序编码，表示后续所有字段（flags + cmd + body + crc）的总字节数
- 示例：`0x00000009` → 实际发送：`09 00 00 00`
### 3. Flags（控制标志）
| 位位置（从高到低） | 名称 | 含义说明 |
|--------------------|-------------|--------------------------------------------------------------------------|
| Bit 7 | `is_resp` | 是否为响应帧：
`0`=请求；
`1`=响应或主动上报（此时 Bit 5 必须为 1） |
| Bit 6 | `resp_ok` | 响应结果：
请求时保留；
响应时 `1`=成功，`0`=失败 |
| Bit 5 | `is_report` | 是否为主动上报：
请求时保留；
响应时 `1`=上报，`0`=普通响应 |
| Bit 4~2 | Reserved | 保留位，未来扩展使用 |
| Bit 1~0 | `version` | 协议版本号，当前为 `1`（仅不兼容升级时修改） |
> 示例：`0x00` 表示：非响应、协议版本 1
### 4. Cmd（命令类型）
- 1 字节，预定义命令从 `255` 开始递减
- 自定义命令范围：`0` ~ `maix.protocol.CMD.CMD_APP_MAX`
### 5. Body（数据体）
- 变长字段，内容由 `cmd` 决定
- 字符串按 ASCII 顺序逐字节发送（如 `"hello"` → `68 65 6C 6C 6F`）
### 6. CRC16_IBM（校验码）
- 覆盖范围：从 `header` 到 `body` 所有字节
- 小端序存储，先发低位再发高位
---
## 三、完整示例
### 十进制示例：
| header | data_len | flags | cmd | body | crc |
|-------------|----------|-------|-----|---------|---------|
| 3148663466 | 9 | 0 | 1 | "hello" | 17451 |
### 十六进制示例：
| header | data_len | flags | cmd | body | crc |
|----------|--------------|-------|-----|----------------|---------|
| 0xBBACCAAA | 0x00000009 | 0x00 | 0x01 | 68 65 6c 6c 6F | 0x442B |
### 最终字节流（十六进制，按发送顺序）：
```
AA CA AC BB 09 00 00 00 00 01 68 65 6C 6C 6F 2B 44
```
> ✅ 注意：所有多字节字段均采用**小端序**，字符串按原顺序发送。
---
### 四、CRC16 实现
### 方法一：直接计算法（C语言）
```c
unsigned short crc16_IBM(unsigned char *ptr, int len) {
unsigned int i;
unsigned short crc = 0x0000;
while(len--) {
crc ^= *ptr++;
for (i = 0; i < 8; ++i) {
if (crc & 1)
crc = (crc >> 1) ^ 0xA001;
else
crc = (crc >> 1);
}
}
return crc;
}
```
### 方法二：查表法（推荐用于性能敏感场景）
```c
const unsigned int crc16_table[256] = {
0x0000, 0xc0c1, 0xc181, 0x0140, 0xc301, 0x03c0, 0x0280, 0xc241,
0xc601, 0x06c0, 0x0780, 0xc741, 0x0500, 0xc5c1, 0xc481, 0x0440,
0xcc01, 0x0cc0, 0x0d80, 0xcd41, 0x0f00, 0xcfc1, 0xce81, 0x0e40,
0x0a00, 0xcac1, 0xcb81, 0x0b40, 0xc901, 0x09c0, 0x0880, 0xc841,
0xd801, 0x18c0, 0x1980, 0xd941, 0x1b00, 0xdbc1, 0xda81, 0x1a40,
0x1e00, 0xdec1, 0xdf81, 0x1f40, 0xdd01, 0x1dc0, 0x1c80, 0xdc41,
0x1400, 0xd4c1, 0xd581, 0x1540, 0xd701, 0x17c0, 0x1680, 0xd641,
0xd201, 0x12c0, 0x1380, 0xd341, 0x1100, 0xd1c1, 0xd081, 0x1040,
0xf001, 0x30c0, 0x3180, 0xf141, 0x3300, 0xf3c1, 0xf281, 0x3240,
0x3600, 0xf6c1, 0xf781, 0x3740, 0xf501, 0x35c0, 0x3480, 0xf441,
0x3c00, 0xfcc1, 0xfd81, 0x3d40, 0xff01, 0x3fc0, 0x3e80, 0xfe41,
0xfa01, 0x3ac0, 0x3b80, 0xfb41, 0x3900, 0xf9c1, 0xf881, 0x3840,
0x2800, 0xe8c1, 0xe981, 0x2940, 0xeb01, 0x2bc0, 0x2a80, 0xea41,
0xee01, 0x2ec0, 0x2f80, 0xef41, 0x2d00, 0xedc1, 0xec81, 0x2c40,
0xe401, 0x24c0, 0x2580, 0xe541, 0x2700, 0xe7c1, 0xe681, 0x2640,
0x2200, 0xe2c1, 0xe381, 0x2340, 0xe101, 0x21c0, 0x2080, 0xe041,
0xa001, 0x60c0, 0x6180, 0xa141, 0x6300, 0xa3c1, 0xa281, 0x6240,
0x6600, 0xa6c1, 0xa781, 0x6740, 0xa501, 0x65c0, 0x6480, 0xa441,
0x6c00, 0xacc1, 0xad81, 0x6d40, 0xaf01, 0x6fc0, 0x6e80, 0xae41,
0xaa01, 0x6ac0, 0x6b80, 0xab41, 0x6900, 0xa9c1, 0xa881, 0x6840,
0x7800, 0xb8c1, 0xb981, 0x7940, 0xbb01, 0x7bc0, 0x7a80, 0xba41,
0xbe01, 0x7ec0, 0x7f80, 0xbf41, 0x7d00, 0xbdc1, 0xbc81, 0x7c40,
0xb401, 0x74c0, 0x7580, 0xb541, 0x7700, 0xb7c1, 0xb681, 0x7640,
0x7200, 0xb2c1, 0xb381, 0x7340, 0xb101, 0x71c0, 0x7080, 0xb041,
0x5000, 0x90c1, 0x9181, 0x5140, 0x9301, 0x53c0, 0x5280, 0x9241,
0x9601, 0x56c0, 0x5780, 0x9741, 0x5500, 0x95c1, 0x9481, 0x5440,
0x9c01, 0x5cc0, 0x5d80, 0x9d41, 0x5f00, 0x9fc1, 0x9e81, 0x5e40,
0x5a00, 0x9ac1, 0x9b81, 0x5b40, 0x9901, 0x59c0, 0x5880, 0x9841,
0x8801, 0x48c0, 0x4980, 0x8941, 0x4b00, 0x8bc1, 0x8a81, 0x4a40,
0x4e00, 0x8ec1, 0x8f81, 0x4f40, 0x8d01, 0x4dc0, 0x4c80, 0x8c41,
0x4400, 0x84c1, 0x8581, 0x4540, 0x8701, 0x47c0, 0x4680, 0x8641,
0x8201, 0x42c0, 0x4380, 0x8341, 0x4100, 0x81c1, 0x8081, 0x4040,
};
unsigned short crc16_IBM(const unsigned char *ptr,int len)
{
unsigned short crc = 0x0000;
while(len--)
{
crc = (crc >> 8) ^ crc16_table[(crc ^ *ptr++) & 0xff];
}
return (crc);
}
```
---