# Board Programmable Batch Feature (Offline Auto Execution)

> Store a batch of CAN/RS485 commands on the board and execute them automatically with configured period and repeat count.  
> For quick integration, use [SANPO Studio](https://sanporobot.com/sanpo-studio) to debug, store, and configure auto execution.

- All `AT+` commands must end with `\r\n`.
- This feature is available on firmware `V4.2` and later.
- Send `AT+VER`(end with \r\n) to check firmware version; if `V42` is not reported, update to the [latest firmware](https://gitcode.com/sanpo/robot/tree/v4/firmware/sanpo_spine).

## Command Overview

| Command | Description |
| --- | --- |
| `AT+BATBEGIN=<id>,<name>` | Create/overwrite a batch and begin upload |
| `AT+BATADD=<id>,<idx>,<proto>,<ch>,<delay_ms>,<hex_payload>` | Add one command item (short payload) |
| `AT+BATADDX=<id>,<idx>,<proto>,<ch>,<delay_ms>,<total_len>,<seq>,<off>,<hex_part>` | Add one chunk for long payload |
| `AT+BATADDEND=<id>,<idx>,<crc16>` | Finish chunk upload and verify |
| `AT+BATCOMMIT=<id>` | Commit and persist batch |
| `AT+BATRUN=<id>,<mode>,<period_ms>,<repeat>` | Run batch (`1=ONCE`, `2=PERIODIC`) |
| `AT+BATSTOP` | Stop current execution |
| `AT+BATLIST?` | Query batch list |
| `AT+BATREAD=<id>,<idx>` | Read batch entry; `idx=0` returns summary |
| `AT+BATDEL=<id>` | Delete a batch |
| `AT+BATSTAT?` | Query runtime status |
| `AT+BATAUTOSET=<id>,<mode>,<period_ms>,<repeat>` | Configure boot auto-run |
| `AT+BATAUTOCLR` | Clear boot auto-run configuration |
| `AT+BATAUTO?` | Query boot auto-run configuration |
| `AT+BATERASE` | Erase full BATCH storage area (do not use frequently) |

## Global Communication Parameters (Persistent)

For offline batch execution, set global CAN/RS485 parameters first:

- `AT+SETCAN=<baud>`: set global CAN baudrate (applies to CAN channels on current board).
- `AT+SETRS485=<baud>,<stop>,<parity>,<bits>`: set global RS485 parameters (applies to RS485 channels on current board).

Field definitions:

- `baud`: baudrate (examples: CAN `1000000/500000/250000/125000`, RS485 `4000000`)
- `stop`: stop bits, `1` or `2`
- `parity`: parity, `0=None`, `1=Odd`, `2=Even`
- `bits`: data bits, `8` or `9`

Persistence rule:

- After power cycle, the board reloads and applies the last saved parameters automatically.

Example:

```bash
AT+SETCAN=1000000
AT+SETRS485=4000000,1,0,8
```

## Field Definitions

- `id`: batch ID, range `1..99`
- `name`: batch name (letters/numbers/underscore/hyphen), max `16` chars
- `idx`: command index in batch, starts from `1`, must be strictly contiguous
- `proto`: `1=CAN_STD`, `2=CAN_EXT`, `3=RS485`
- `ch`: channel `1..4` (`0` means broadcast)
- `delay_ms`: relative delay between commands, range `0..9999` ms
- `hex_payload/hex_part`: hexadecimal text (`2 chars = 1 byte`)
- `mode`: `1=ONCE`, `2=PERIODIC`
- `repeat`: repeat count, `0` means infinite loop
- `seq`: chunk sequence, starts from `1`
- `off`: chunk byte offset, starts from `0`

## Payload Encoding

- `payload` uses hex text encoding (`2 chars = 1 byte`)
- `proto=1 (CAN_STD)`: `CANID(2B) + DLC(1B) + DATA(0~8B)`, total `3~11B`
- `proto=2 (CAN_EXT)`: `CANID(4B) + DLC(1B) + DATA(0~8B)`, total `5~13B`
- `proto=3 (RS485)`: use `AT+BATADD` for `<=17B`; use `AT+BATADDX` for longer data
- Example (CAN_EXT): `00000123081122334455667788`
- Example (RS485): `A55A010203040506`

## Length and Chunking Rules

- `AT+BATADD` is for short payload (`<=17` bytes).
- For longer payload, use `AT+BATADDX + AT+BATADDEND`.

## Usage Examples

1. Create a batch

```bash
AT+BATBEGIN=1,walk_cycle
```

2. Add one CAN_EXT item

```bash
AT+BATADD=1,1,2,1,20,00000123081122334455667788
```

3. Add one RS485 item

```bash
AT+BATADD=1,2,3,2,10,A55A010203040506
```

4. Commit and run (100 ms period, infinite loop)

```bash
AT+BATCOMMIT=1
AT+BATRUN=1,2,100,0
```

5. Stop

```bash
AT+BATSTOP
```

6. Chunked example (40-byte RS485)

```bash
AT+BATADDX=2,1,3,2,20,40,1,0,11223344556677889900AABBCCDDEEFF
AT+BATADDX=2,1,3,2,20,40,2,16,0102030405060708090A0B0C0D0E0F10
AT+BATADDX=2,1,3,2,20,40,3,32,1112131415161718
AT+BATADDEND=2,1,7A3C
AT+BATCOMMIT=2
```

7. Query stored batches

```bash
AT+BATLIST?
```

Response examples:

```text
BATLIST:1,walk_cycle;2,test_rs485
BATLIST:NONE
```

8. Read back stored entries

```bash
AT+BATREAD=1,0
AT+BATREAD=1,1
AT+BATREAD=1,2
```

Response format:

```text
BATREAD:id=<id>,name=<name>,count=<count>
BATREAD:id=<id>,idx=<idx>,proto=<proto>,ch=<ch>,delay_ms=<delay_ms>,payload=<hex_payload>
```

9. Query status

```bash
AT+BATSTAT?
```

10. Delete batch

```bash
AT+BATDEL=1
```

11. Configure boot auto-run

```bash
AT+BATAUTOSET=1,2,200,2
AT+BATAUTOSET=1,1,0,0
AT+BATAUTO?
AT+BATAUTOCLR
```

12. Erase full BATCH storage

```bash
AT+BATERASE
```

## Error Codes

Failure return format:

```text
ERR,<code>
```

Definitions:

- `0`: success (usually returns `OK`)
- `1`: `BAT_ERR_PARAM`, invalid format/missing args/illegal characters
- `2`: `BAT_ERR_STATE`, invalid state (`BATADD` before `BATBEGIN`, wrong chunk order, non-contiguous `idx`)
- `3`: `BAT_ERR_RANGE`, out-of-range params (`id`/`idx`/`seq`/`delay_ms`/length)
- `4`: `BAT_ERR_CRC`, `BATADDEND` CRC mismatch
- `5`: `BAT_ERR_NOSPACE`, insufficient flash space
- `6`: `BAT_ERR_NOTFOUND`, batch not found/deleted
- `7`: `BAT_ERR_QUEUE`, send queue busy (retry later)
- `8`: `BAT_ERR_FLASH`, flash read/write/erase failure