# TCP2UART AT 固件使用手册

## 1. 文档范围

本文档定义 `TCP2UART` 项目的最终 AT 外部协议。

本文档只描述最终协议模型，不保留任何历史展开式实例字段，不包含测试记录，不讨论旧版兼容命令。

适用对象：

- 上位机开发人员
- 联调与测试人员
- 固件接口实现人员

## 2. 设备与接口

- 主控：`STM32F103RCT6`（256KB Flash / 48KB SRAM）
- 以太网芯片：`CH390D`
- 配置口：`USART1`
- 数据口：`USART2`、`USART3`

职责划分：

- `USART1`：AT 配置口
- `USART2 / USART3`：业务数据口，可工作于普通透传或 MUX 透传模式

## 3. 最终协议模型

本项目最终控制协议由三部分组成：

1. `MUX`：全局数据承载模式开关
2. `NET`：全局静态网络配置记录
3. `LINK[ROLE]`：按角色名组织的链路配置记录（`S1/S2/C1/C2`）

约束如下：

- 设备只有一张网卡，因此本地网络参数只配置一次
- DHCP 不属于最终协议范围
- 所有 AT 文本命令必须以 `\r\n` 结尾
- 当 `DSTMASK=0x00` 时，MUX 数据口中的系统控制帧进入 AT 解析路径，其控制文本同样必须以 `\r\n` 结尾

## 4. MUX 帧格式

当 `MUX=1` 时，数据口使用如下帧格式：

```text
SYNC | LEN_H | LEN_L | SRCID | DSTMASK | PAYLOAD | TAIL
```

字段定义：

- `SYNC`：帧起始标记，建议固定为 `0x7E`
- `LEN_H / LEN_L`：`PAYLOAD` 长度，高字节在前
- `SRCID`：单字节源端点 ID
- `DSTMASK`：单字节目标端点位图
- `PAYLOAD`：负载数据
- `TAIL`：帧结束标记，建议固定为 `0x7F`

规则：

- `DSTMASK != 0x00`：业务数据帧
- `DSTMASK = 0x00`：系统控制帧
- 系统控制帧的 `PAYLOAD` 为 AT 文本，必须以 `\r\n` 结束

## 5. 统一端点编码

`UART` 与 `TCP` 逻辑实例统一进入同一套编码空间：

| 端点 | 编码 |
|------|------|
| `C1` | `0x01` |
| `C2` | `0x02` |
| `U0` | `0x04` |
| `U1` | `0x08` |
| `S1` | `0x10` |
| `S2` | `0x20` |

说明：

- `SRCID` 必须为单一端点值
- `DSTMASK` 可以是一个或多个端点编码按位或的结果
- `DSTMASK=0x00` 保留给系统控制帧

## 6. AT 命令总则

### 6.1 命令结尾

所有 AT 命令均必须以 `\r\n` 结尾。

例如：

```text
AT\r\n
AT+MUX?\r\n
AT+NET=192.168.1.100,255.255.255.0,192.168.1.1,02:00:00:00:00:01\r\n
```

### 6.2 持久化规则

参数设置成功后只写入当前运行配置，不会自动写入 Flash。

若要掉电保持，必须执行：

1. `AT+SAVE\r\n`
2. `AT+RESET\r\n`

### 6.3 响应风格

- 成功：`OK`
- 需要保存后生效时，允许追加提示文本
- 失败：`ERROR: <reason>`

## 7. 默认配置

### 7.1 MUX 默认值

```text
MUX = 0
```

### 7.2 NET 默认值

```text
NET = 192.168.1.100,255.255.255.0,192.168.1.1,02:00:00:00:00:01
```

### 7.3 LINK 默认值

```text
LINK:S1 = 1,8080,0.0.0.0,0,U0
LINK:S2 = 0,8081,0.0.0.0,0,U1
LINK:C1 = 1,9001,192.168.1.200,9000,U1
LINK:C2 = 0,9002,192.168.1.201,9001,U0
```

说明：

- `S1/S2/C1/C2` 为对外可见角色名
- 内部索引映射由固件管理，不对外暴露

UART 记号约定：

- `U0 = USART2`
- `U1 = USART3`

## 8. AT 命令定义

### 8.1 测试设备在线

命令：

```text
AT\r\n
```

返回：

```text
OK
```

### 8.2 查询摘要

命令：

```text
AT+?\r\n
AT+QUERY\r\n
```

推荐返回格式：

```text
+NET:IP=192.168.1.100,MASK=255.255.255.0,GW=192.168.1.1,MAC=02:00:00:00:00:01
+LINK:S1,EN=1,LPORT=8080,RIP=0.0.0.0,RPORT=0,UART=U0
+LINK:S2,EN=0,LPORT=8081,RIP=0.0.0.0,RPORT=0,UART=U1
+LINK:C1,EN=1,LPORT=9001,RIP=192.168.1.200,RPORT=9000,UART=U1
+LINK:C2,EN=0,LPORT=9002,RIP=192.168.1.201,RPORT=9001,UART=U0
+MUX:0
+MAP:UART2=0x04,UART3=0x08,C1=0x01,C2=0x02,S1=0x10,S2=0x20
+BAUD:U0=115200,U1=115200
OK
```

### 8.3 MUX 类命令

#### 设置 MUX

```text
AT+MUX=1\r\n
```

参数：

- `0`：普通透传模式
- `1`：MUX 透传模式

查询：

```text
AT+MUX?\r\n
```

返回示例：

```text
+MUX:1
OK
```

### 8.4 NET 类命令

#### 设置 NET

```text
AT+NET=192.168.1.100,255.255.255.0,192.168.1.1,02:00:00:00:00:01\r\n
```

字段顺序：

```text
IP,MASK,GW,MAC
```

查询：

```text
AT+NET?\r\n
```

返回示例：

```text
+NET:IP=192.168.1.100,MASK=255.255.255.0,GW=192.168.1.1,MAC=02:00:00:00:00:01
OK
```

**MAC 设置说明：**

当MAC设置为全0时，固件将使用硬件MAC地址，此时通过AT+?查询到的MAC地址即为当前生效的硬件MAC地址。

### 8.5 LINK 类命令

#### 设置单条 LINK 记录

```text
AT+LINK=S1,1,8080,0.0.0.0,0,U0\r\n
AT+LINK=C1,1,9001,192.168.1.200,9000,U1\r\n
```

字段顺序：

```text
ROLE,EN,LPORT,RIP,RPORT,UART
```

字段说明：

- `ROLE`：链路角色名，固定为 `S1/S2/C1/C2`
- `EN`：`0/1`
- `LPORT`：本地端口
- `RIP`：对端 IP
- `RPORT`：对端端口
- `UART`：`U0/U1`

说明：

- `Server` 与 `Client` 共用同一条 `LINK` 记录模型
- `Server` 中 `RIP/RPORT` 可作为允许接入的对端约束或预设对端信息
- `Client` 中 `RIP/RPORT` 表示远端目标地址与端口
- `Client` 侧当前保留固定 `LPORT` 语义，用于满足部分上位机或现场网络策略对固定源端口的依赖
- 为避免固定 `LPORT` 下频繁重连被 lwIP `TIME_WAIT` 长时间占用阻塞，当前固件对 `Client` 主动断开后的释放路径采用 abortive close（RST）而非优雅 `FIN/ACK` 关闭
- 因此 `Client` 重连场景下，对端可能观察到 `RST` 或“连接被重置”，这属于当前产品约束下的有意设计取舍，不影响 `AT+LINK` 对 `LPORT` 的配置语义

#### 查询单条 LINK

```text
AT+LINK=S1\r\n
```

返回示例：

```text
+LINK:S1,EN=1,LPORT=8080,RIP=0.0.0.0,RPORT=0,UART=U0
OK
```

#### 查询全部 LINK

```text
AT+LINK?\r\n
```

返回示例：

```text
+LINK:S1,EN=1,LPORT=8080,RIP=0.0.0.0,RPORT=0,UART=U0
+LINK:S2,EN=0,LPORT=8081,RIP=0.0.0.0,RPORT=0,UART=U1
+LINK:C1,EN=1,LPORT=9001,RIP=192.168.1.200,RPORT=9000,UART=U1
+LINK:C2,EN=0,LPORT=9002,RIP=192.168.1.201,RPORT=9001,UART=U0
OK
```

## 9. 保存与复位命令

### 9.1 保存配置

```text
AT+SAVE\r\n
```

成功返回：

```text
OK: Configuration saved
```

### 9.2 软件复位

```text
AT+RESET\r\n
```

返回：

```text
OK: Resetting...
```

### 9.3 恢复默认值

```text
AT+DEFAULT\r\n
```

返回：

```text
OK: Defaults restored
```

## 10. 常见错误返回

| 场景 | 返回 |
|------|------|
| 未知命令 | `ERROR: Unknown command` |
| 非法端口 | `ERROR: Invalid port` |
| 非法波特率 | `ERROR: Invalid baudrate` |
| 非法 IP 地址 | `ERROR: Invalid IP format` |
| 非法掩码 | `ERROR: Invalid mask format` |
| 非法网关 | `ERROR: Invalid gateway format` |
| 非法远端 IP | `ERROR: Invalid remote IP format` |
| 非法 MAC | `ERROR: Invalid MAC format` |
| 非法 `SRCID` / `DSTMASK` | `ERROR: Invalid route field` |
| Flash 保存失败 | `ERROR: Save failed` |

## 11. 推荐配置流程

```text
AT+NET=192.168.1.123,255.255.255.0,192.168.1.1,02:00:00:00:00:01\r\n
AT+LINK=S1,1,10001,0.0.0.0,0,U1\r\n
AT+LINK=S2,1,10003,0.0.0.0,0,U1\r\n
AT+LINK=C1,1,20001,192.168.1.201,10002,U0\r\n
AT+MUX=1\r\n
AT+SAVE\r\n
AT+RESET\r\n
```

## 12. 故障排查建议

### 12.1 发送 `AT` 没有返回

优先检查：

1. 是否连接到 `USART1`
2. 串口参数是否为 `115200 8N1`
3. 是否严格使用 `\r\n` 作为命令结尾
4. 接线是否正确
5. 设备是否正常上电运行

### 12.2 设置成功但重启后参数丢失

检查是否漏掉以下步骤：

1. `AT+SAVE\r\n`
2. `AT+RESET\r\n`

## 13. 相关文件

- AT 命令实现：`App/config.c`
- 配置结构与默认值：`App/config.h`
- FreeRTOS 任务定义：`Core/Src/freertos.c`
- 调试指导：`工程调试指南.md`