# 批量任务

批量任务可以把一组 CAN、CAN FD 或 RS485 指令保存在开发板中，再由开发板按顺序执行。电脑断开后任务仍可运行，适合循环测试和固定动作流程。

批量任务功能较复杂，建议使用配套的线上工具 [SANPO Studio](https://www.sanporobot.com/sanpo-studio)，快速配置离线批量指令。

批量指令通过USB串口进行配置，接入开发板USB后，在Windows下显示2个管理串口 `SANPO Studio Management Port`，分别对应两个STM32 MCU，STM32(1) 控制CAN-1/2和RS485-1/2，STM32(2) 控制CAN-3/4和RS485-3/4。串口编号不保证与板上丝印顺序一致，首次使用时建议只连接一个设备确认对应关系。

## 基本规则

- 所有命令通过管理口发送，行尾使用 `CRLF`。
- 批次编号为 `1～99`，名称为 1～16 个字符，只能包含字母、数字、`_` 和 `-`。
- 条目编号必须从 `1` 开始连续增加，不能跳号或重复。
- 单条 payload 最多 80 字节；RS485 条目最多使用其中 68 字节。
- 固件内部允许较多条目，但为便于维护并减少存储压力，单个批次建议不超过 64 条。
- `Channel=0` 同时发送到当前 MCU 管理的两路同类接口；`1/3` 选择第一路，`2/4` 选择第二路。

## 创建并运行一个批次

下面的示例创建一个 CAN FD 扩展帧任务，并只执行一次：

```text
AT+BATBEGIN=1,fd_test
AT+BATADD=1,1,5,1,10,000001230A01020304050607081112131415161718
AT+BATCOMMIT=1
AT+BATRUN=1,1,0,1
```

每条命令成功时返回：

```text
OK
```

执行后可查询状态：

```text
AT+BATSTAT?
```

典型返回：

```text
BATSTAT:run=0,batch_id=1,mode=1,idx=2,count=1,repeat_cfg=1,repeat_done=0,last_err=0,tx_ok=1,tx_fail=0
```

重点检查 `last_err=0`、`tx_ok` 增加且 `tx_fail=0`。

## 条目格式

```text
AT+BATADD=<id>,<idx>,<proto>,<ch>,<delay_ms>,<hex_payload>
```

| 字段 | 说明 |
| --- | --- |
| `id` | 批次编号，`1～99` |
| `idx` | 条目编号，从 `1` 开始连续增加 |
| `proto` | 总线和帧类型，见下表 |
| `ch` | 目标通道；`0` 表示当前 MCU 的两路接口 |
| `delay_ms` | 本条发送成功后，到下一条开始前的等待时间，`0～9999 ms` |
| `hex_payload` | 不带空格的十六进制内容 |

`proto` 和 payload 的定义如下，CAN ID 使用高字节在前：

| `proto` | 类型 | `hex_payload` |
| ---: | --- | --- |
| `1` | 经典 CAN 标准帧 | `CANID(2B) + Len(1B) + Data(0～8B)` |
| `2` | 经典 CAN 扩展帧 | `CANID(4B) + Len(1B) + Data(0～8B)` |
| `3` | RS485 | 原始设备指令 `Data(1～68B)` |
| `4` | CAN FD 标准帧 | `CANID(2B) + 长度编码(1B) + Data(0～64B)` |
| `5` | CAN FD 扩展帧 | `CANID(4B) + 长度编码(1B) + Data(0～64B)` |

经典 CAN 的 `Len` 就是实际字节数。CAN FD 使用长度编码：

| 编码 | 字节数 | 编码 | 字节数 |
| ---: | ---: | ---: | ---: |
| `00` | 0 | `08` | 8 |
| `01` | 1 | `09` | 12 |
| `02` | 2 | `0A` | 16 |
| `03` | 3 | `0B` | 20 |
| `04` | 4 | `0C` | 24 |
| `05` | 5 | `0D` | 32 |
| `06` | 6 | `0E` | 48 |
| `07` | 7 | `0F` | 64 |

## 运行方式

```text
AT+BATRUN=<id>,<mode>,<period_ms>,<repeat>
```

| 字段 | 说明 |
| --- | --- |
| `mode=1` | 顺序执行一遍后停止 |
| `mode=2` | 周期执行 |
| `period_ms` | 周期模式下，两轮任务之间的等待时间，`0～65535 ms` |
| `repeat` | 周期模式的执行轮数；`0` 表示持续执行，直到收到 `AT+BATSTOP` |

例如，每 100 ms 执行一轮，共执行 10 轮：

```text
AT+BATRUN=1,2,100,10
```

停止当前任务：

```text
AT+BATSTOP
```

## 上电自动运行

确认批次已测试无误后，可设置上电自动运行：

```text
AT+BATAUTOSET=<id>,<mode>,<period_ms>,<repeat>
```

查询或清除：

```text
AT+BATAUTO?
AT+BATAUTOCLR
```

该设置会保存到 Flash。`mode=1` 时 `period_ms` 必须为 `0`。

## 查询和删除

| 命令 | 用途 |
| --- | --- |
| `AT+BATLIST?` | 列出已保存的批次 |
| `AT+BATREAD=<id>,<idx>` | 读取指定条目 |
| `AT+BATSTAT?` | 查看运行状态和收发统计 |
| `AT+BATDEL=<id>` | 删除指定批次 |
| `AT+BATERASE` | 清空全部批次 |

`AT+BATERASE` 不会清除设备身份和通信参数，但已保存的批次无法恢复。

## 较长命令分片上传

如果串口工具不能稳定发送较长的 AT 命令，可分片上传同一个 payload：

```text
AT+BATADDX=<id>,<idx>,<proto>,<ch>,<delay_ms>,<total_len>,<seq>,<off>,<hex_part>
AT+BATADDEND=<id>,<idx>,<crc16>
```

- 第一片从 `seq=1`、`off=0` 开始。
- 后续 `seq` 连续增加，`off` 等于之前已上传的总字节数。
- 所有分片完成后，对完整 payload 计算 CRC16-CCITT，初始值为 `0x0000`，再发送 `AT+BATADDEND`。
- 一个条目完成后才能继续上传下一个编号。

## 错误返回

失败时返回 `ERR,<code>`：

| code | 说明 | 常见处理 |
| ---: | --- | --- |
| `1` | 参数格式错误 | 检查字段数、十六进制内容和 payload 布局 |
| `2` | 当前状态不允许 | 检查是否已 `BATBEGIN`、编号是否连续、分片是否结束 |
| `3` | 参数超出范围 | 检查批次、通道、延时和长度 |
| `4` | CRC 不一致 | 重新计算完整 payload 的 CRC16 |
| `5` | 存储空间不足 | 删除无用批次；通信配置写满时使用 `AT+CFGERASE` |
| `6` | 批次不存在 | 先用 `AT+BATLIST?` 确认编号 |
| `7` | 发送队列忙 | 降低任务频率或增大条目间隔 |
| `8` | Flash 读写失败 | 重新上电后复测，仍失败则检查硬件 |

通信波特率、SPI 长度模式和 RS485 透传设置见[通信参数配置](baudrate_config)。