gaoro-xiao/TCP2UART
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

docs: rewrite mux/net/link protocol manuals

Browse Source
This commit is contained in:
😍
2026-04-03 16:47:15 +08:00
parent ac04bfc923
commit 6f4ba247a4
3 changed files with 512 additions and 790 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AT固件使用手册.md
+238 -496
View File
@@ -1,137 +1,158 @@
# TCP2UART AT 固件使用手册
## 1. 文档说明
## 1. 文档范围
本文档用于说明 `TCP2UART` 固件的 `AT` 配置功能使用方法。
本文档定义 `TCP2UART` 项目的最终 AT 外部协议。
本手册适用于当前工程中的 STM32 固件版本，配置口通过 `USART1` 提供，主要用于：
本文档只描述最终协议模型，不保留任何历史展开式实例字段，不包含测试记录，不讨论旧版兼容命令。
- 查询当前设备参数
- 修改网络参数
- 修改串口透传参数
- 保存参数到 Flash
- 恢复默认参数
- 软件复位设备
适用对象：
本文档内容基于以下信息整理：
- 上位机开发人员
- 联调与测试人员
- 固件接口实现人员
- 当前代码实现 `App/config.c`、`App/config.h`
- 当前默认配置定义
- 实板测试结果
- `uart-ch390-debug-handoff.md` 中已记录的 bench 经验
## 1.1 版本更新说明（2026-04-02）
为避免引入额外时序噪声与误判，当前固件已移除 CH390 的 bit-bang 诊断读路径。
当前版本仅保留 CH390 硬件 SPI 访问路径，启动探测与运行期寄存器访问均通过统一 SPI 接口执行。
## 2. 适用硬件
## 2. 设备与接口
- 主控：`STM32F103R8T6`
- 以太网芯片：`CH390D`
- 配置串口：`USART1`
- 透传串口：`USART2`、`USART3`
- 配置口：`USART1`
- 数据口：`USART2`、`USART3`
当前引脚用途如下：
职责划分：
- `PA9`：`USART1_TX`，配置口发送
- `PA10`：`USART1_RX`，配置口接收
- `PA2/PA3`：`USART2`，对应 TCP Server 透传串口
- `PB10/PB11`：`USART3`，对应 TCP Client 透传串口
- `USART1`：AT 配置口
- `USART2 / USART3`：业务数据口，可工作于普通透传或 MUX 透传模式
## 3. 配置口通信参数
## 3. 最终协议模型
连接配置口时，使用以下串口参数：
本项目最终控制协议由三部分组成：
- 波特率：`115200`
- 数据位：`8`
- 校验位：`None`
- 停止位：`1`
1. `MUX`：全局数据承载模式开关
2. `NET`：全局静态网络配置记录
3. `LINK[idx]`：按索引组织的链路配置记录
## 4. 最重要的使用规则
约束如下：
### 4.1 推荐使用 `\n` 作为命令结尾
- 设备只有一张网卡，因此本地网络参数只配置一次
- DHCP 不属于最终协议范围
- 所有 AT 文本命令必须以 `\r\n` 结尾
- 当 `DSTMASK=0x00` 时，MUX 数据口中的系统控制帧进入 AT 解析路径，其控制文本同样必须以 `\r\n` 结尾
这是当前固件 bench 联调中最重要的一条经验。
## 4. MUX 帧格式
在当前实板联调中，使用 `\n` 结尾是最稳妥的做法。例如：
当 `MUX=1` 时，数据口使用如下帧格式：
```text
AT\n
AT+?\n
AT+IP=192.168.1.123\n
SYNC | LEN_H | LEN_L | SRCID | DSTMASK | PAYLOAD | TAIL
```
代码中的帧接收逻辑会在收到 `\r` 或 `\n` 时结束当前命令，但当前 bench 记录表明，实际使用时优先采用 `\n` 结尾更可靠。如果上位机默认发送 `\r\n` 后看起来“设备没有响应”，优先改成只发送 `\n` 再测试。
字段定义：
### 4.2 修改参数后不会立刻写入 Flash
- `SYNC`：帧起始标记，建议固定为 `0x7E`
- `LEN_H / LEN_L`：`PAYLOAD` 长度，高字节在前
- `SRCID`：单字节源端点 ID
- `DSTMASK`：单字节目标端点位图
- `PAYLOAD`：负载数据
- `TAIL`：帧结束标记，建议固定为 `0x7F`
大多数设置命令只会先修改 RAM 中的当前配置，不会自动写入 Flash。
规则：
如果要让参数在复位或重新上电后继续保持，必须执行：
- `DSTMASK != 0x00`：业务数据帧
- `DSTMASK = 0x00`：系统控制帧
- 系统控制帧的 `PAYLOAD` 为 AT 文本，必须以 `\r\n` 结束
1. `AT+SAVE`
2. `AT+RESET`
## 5. 统一端点编码
### 4.3 `AT+DEFAULT` 只恢复当前默认值，不自动保存
`UART` 与 `TCP` 逻辑实例统一进入同一套编码空间：
执行 `AT+DEFAULT` 后，当前参数会恢复为默认值，但如果要让默认值持久生效，仍然需要：
1. `AT+SAVE`
2. `AT+RESET`
## 5. 默认参数
当前固件默认值如下：
| 参数 | 默认值 |
|------|--------|
| MAC | `02:00:00:00:00:01` |
| DHCP | `0` |
| IP | `192.168.1.100` |
| MASK | `255.255.255.0` |
| GW | `192.168.1.1` |
| PORT | `8080` |
| RIP | `192.168.1.200` |
| RPORT | `9000` |
| BAUD1 | `115200` |
| BAUD2 | `115200` |
| 端点 | 编码 |
|------|------|
| `C1` | `0x01` |
| `C2` | `0x02` |
| `UART2` | `0x04` |
| `UART3` | `0x08` |
| `S1` | `0x10` |
| `S2` | `0x20` |
说明：
- `BAUD1` 对应 `USART2`，即 TCP Server 对应的透传串口
- `BAUD2` 对应 `USART3`，即 TCP Client 对应的透传串口
- `SRCID` 必须为单一端点值
- `DSTMASK` 可以是一个或多个端点编码按位或的结果
- `DSTMASK=0x00` 保留给系统控制帧
## 6. AT 命令总览
## 6. AT 命令总则
当前固件支持以下命令：
### 6.1 命令结尾
- `AT`
- `AT+?`
- `AT+QUERY`
- `AT+IP=...`
- `AT+MASK=...`
- `AT+GW=...`
- `AT+RIP=...`
- `AT+MAC=...`
- `AT+PORT=...`
- `AT+RPORT=...`
- `AT+BAUD1=...`
- `AT+BAUD2=...`
- `AT+DHCP=0`
- `AT+SAVE`
- `AT+RESET`
- `AT+DEFAULT`
所有 AT 命令均必须以 `\r\n` 结尾。
## 7. 命令详细说明
例如：
### 7.1 测试设备在线
```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
LINK0 = 1,8080,0.0.0.0,0,U0
LINK1 = 0,8081,0.0.0.0,0,U1
LINK2 = 1,9001,192.168.1.200,9000,U1
LINK3 = 0,9002,192.168.1.201,9001,U0
```
固定索引映射：
- `0 = S1`
- `1 = S2`
- `2 = C1`
- `3 = C2`
UART 记号约定：
- `U0 = USART2`
- `U1 = USART3`
## 8. AT 命令定义
### 8.1 测试设备在线
命令：
```text
AT\n
AT\r\n
```
返回：
@@ -140,305 +161,147 @@ AT\n
OK
```
用途：
### 8.2 查询摘要
- 用于确认配置口通信正常
### 7.2 查询当前参数
命令 1：
命令：
```text
AT+?\n
AT+?\r\n
AT+QUERY\r\n
```
命令 2：
推荐返回格式：
```text
AT+QUERY\n
+NET:IP=192.168.1.100,MASK=255.255.255.0,GW=192.168.1.1,MAC=02:00:00:00:00:01
+LINK:0,EN=1,LPORT=8080,RIP=0.0.0.0,RPORT=0,UART=U0
+LINK:1,EN=0,LPORT=8081,RIP=0.0.0.0,RPORT=0,UART=U1
+LINK:2,EN=1,LPORT=9001,RIP=192.168.1.200,RPORT=9000,UART=U1
+LINK:3,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
MAC: 02:00:00:00:00:01
DHCP: 0
IP: 192.168.1.100
MASK: 255.255.255.0
GW: 192.168.1.1
PORT: 8080
RIP: 192.168.1.200
RPORT: 9000
BAUD1: 115200
BAUD2: 115200
```
用途：
- 查询当前运行配置
- 可用于保存前后、复位前后对比参数是否一致
### 7.3 设置设备 IP 地址
命令：
```text
AT+IP=192.168.1.123\n
```
成功返回：
```text
+MUX:1
OK
Note: Use AT+SAVE then AT+RESET to apply changes
```
失败返回：
### 8.4 NET 类命令
#### 设置 NET
```text
ERROR: Invalid IP format
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
```
### 8.5 LINK 类命令
#### 设置单条 LINK 记录
```text
AT+LINK=0,1,8080,0.0.0.0,0,U0\r\n
AT+LINK=2,1,9001,192.168.1.200,9000,U1\r\n
```
字段顺序：
```text
IDX,EN,LPORT,RIP,RPORT,UART
```
字段说明：
- `IDX`：实例索引，固定为 `0..3`
- `EN`：`0/1`
- `LPORT`：本地端口
- `RIP`：对端 IP
- `RPORT`：对端端口
- `UART`：`U0/U1`
说明：
- 推荐使用标准 IPv4 点分十进制格式
- 当前参数会立即更新到 RAM
- 需要 `AT+SAVE` 和 `AT+RESET` 后才会以持久配置重新启动
- `Server` 与 `Client` 共用同一条 `LINK` 记录模型
- `Server` 中 `RIP/RPORT` 可作为允许接入的对端约束或预设对端信息
- `Client` 中 `RIP/RPORT` 表示远端目标地址与端口
### 7.4 设置子网掩码
命令：
#### 查询单条 LINK
```text
AT+MASK=255.255.255.0\n
AT+LINK=0\r\n
```
成功返回：
返回示例：
```text
+LINK:0,EN=1,LPORT=8080,RIP=0.0.0.0,RPORT=0,UART=U0
OK
Note: Use AT+SAVE then AT+RESET to apply changes
```
失败返回：
#### 查询全部 LINK
```text
ERROR: Invalid mask format
AT+LINK?\r\n
```
### 7.5 设置网关
命令：
```text
AT+GW=192.168.1.1\n
```
成功返回：
返回示例：
```text
+LINK:0,EN=1,LPORT=8080,RIP=0.0.0.0,RPORT=0,UART=U0
+LINK:1,EN=0,LPORT=8081,RIP=0.0.0.0,RPORT=0,UART=U1
+LINK:2,EN=1,LPORT=9001,RIP=192.168.1.200,RPORT=9000,UART=U1
+LINK:3,EN=0,LPORT=9002,RIP=192.168.1.201,RPORT=9001,UART=U0
OK
Note: Use AT+SAVE then AT+RESET to apply changes
```
失败返回：
## 9. 保存与复位命令
### 9.1 保存配置
```text
ERROR: Invalid gateway format
```
### 7.6 设置远端服务器 IP
命令：
```text
AT+RIP=192.168.1.201\n
```
成功返回：
```text
OK
Note: Use AT+SAVE then AT+RESET to apply changes
```
失败返回：
```text
ERROR: Invalid remote IP format
```
说明：
- 该参数用于 TCP Client 主动连接的目标地址
### 7.7 设置 MAC 地址
命令：
```text
AT+MAC=02:12:34:56:78:9A\n
```
成功返回：
```text
OK
Note: Use AT+SAVE then AT+RESET to apply changes
```
失败返回：
```text
ERROR: Invalid MAC format
```
说明：
- 推荐使用 `:` 分隔的标准 MAC 字符串
- 当前实现也兼容 `-` 分隔格式
### 7.8 设置 TCP Server 监听端口
命令：
```text
AT+PORT=10001\n
```
成功返回：
```text
OK
Note: Use AT+SAVE then AT+RESET to apply changes
```
失败返回：
```text
ERROR: Invalid port
```
说明：
- 推荐使用 `1 ~ 65535` 范围内的十进制端口号
### 7.9 设置 TCP Client 远端端口
命令：
```text
AT+RPORT=10002\n
```
成功返回：
```text
OK
Note: Use AT+SAVE then AT+RESET to apply changes
```
失败返回：
```text
ERROR: Invalid port
```
说明：
- 推荐使用 `1 ~ 65535` 范围内的十进制端口号
### 7.10 设置 USART2 波特率
命令：
```text
AT+BAUD1=57600\n
```
成功返回：
```text
OK
Note: Use AT+SAVE then AT+RESET to apply changes
```
失败返回：
```text
ERROR: Invalid baudrate
```
说明：
- `BAUD1` 对应 `USART2`
- 推荐使用 `1200 ~ 921600` 范围内的标准波特率值
### 7.11 设置 USART3 波特率
命令：
```text
AT+BAUD2=38400\n
```
成功返回：
```text
OK
Note: Use AT+SAVE then AT+RESET to apply changes
```
失败返回：
```text
ERROR: Invalid baudrate
```
说明：
- `BAUD2` 对应 `USART3`
- 推荐使用 `1200 ~ 921600` 范围内的标准波特率值
### 7.12 设置 DHCP
命令：
```text
AT+DHCP=0\n
```
成功返回：
```text
OK
Note: Use AT+SAVE then AT+RESET to apply changes
```
失败返回 1：
```text
ERROR: Invalid value
```
失败返回 2：
```text
ERROR: DHCP disabled in this build
```
说明：
- 当前固件构建不支持 DHCP
- 因此 `AT+DHCP=1` 会明确返回失败
- 当前版本建议固定使用静态 IP
### 7.13 保存参数到 Flash
命令：
```text
AT+SAVE\n
AT+SAVE\r\n
```
成功返回：
@@ -447,23 +310,10 @@ AT+SAVE\n
OK: Configuration saved
```
失败返回：
### 9.2 软件复位
```text
ERROR: Save failed
```
用途：
- 将当前 RAM 中的配置写入 Flash
- 只有执行成功后，参数才会在复位后保留
### 7.14 软件复位设备
命令：
```text
AT+RESET\n
AT+RESET\r\n
```
返回：
@@ -472,17 +322,10 @@ AT+RESET\n
OK: Resetting...
```
用途：
- 请求设备执行软件复位
- 通常用于 `AT+SAVE` 之后让新配置重新生效
### 7.15 恢复默认参数
命令：
### 9.3 恢复默认值
```text
AT+DEFAULT\n
AT+DEFAULT\r\n
```
返回：
@@ -491,14 +334,7 @@ AT+DEFAULT\n
OK: Defaults restored
```
用途：
- 将当前配置恢复为固件默认值
- 如果要让默认值长期生效，仍然需要再执行 `AT+SAVE` 和 `AT+RESET`
## 8. 常见错误返回
当前固件已验证的错误返回如下：
## 10. 常见错误返回
| 场景 | 返回 |
|------|------|
@@ -510,133 +346,39 @@ OK: Defaults restored
| 非法网关 | `ERROR: Invalid gateway format` |
| 非法远端 IP | `ERROR: Invalid remote IP format` |
| 非法 MAC | `ERROR: Invalid MAC format` |
| 非法 DHCP 参数 | `ERROR: Invalid value` |
| DHCP 在当前构建中不可用 | `ERROR: DHCP disabled in this build` |
| 非法 `SRCID` / `DSTMASK` | `ERROR: Invalid route field` |
| Flash 保存失败 | `ERROR: Save failed` |
## 9. 推荐操作流程
### 9.1 查询当前参数
## 11. 推荐配置流程
```text
AT\n
AT+?\n
AT+NET=192.168.1.123,255.255.255.0,192.168.1.1,02:00:00:00:00:01\r\n
AT+LINK=0,1,10001,0.0.0.0,0,U1\r\n
AT+LINK=1,1,10003,0.0.0.0,0,U1\r\n
AT+LINK=2,1,20001,192.168.1.201,10002,U0\r\n
AT+MUX=1\r\n
AT+SAVE\r\n
AT+RESET\r\n
```
### 9.2 修改参数并永久保存
## 12. 故障排查建议
例如修改设备 IP、监听端口和远端地址：
### 12.1 发送 `AT` 没有返回
```text
AT+IP=192.168.1.123\n
AT+PORT=10001\n
AT+RIP=192.168.1.201\n
AT+RPORT=10002\n
AT+SAVE\n
AT+RESET\n
```
优先检查：
设备复位后，再执行：
```text
AT+?\n
```
确认参数是否与修改值一致。
### 9.3 恢复出厂默认参数
```text
AT+DEFAULT\n
AT+SAVE\n
AT+RESET\n
AT+?\n
```
## 10. Flash 持久化说明
当前固件已在实板上验证以下保存/复位路径：
- 设置参数后执行 `AT+SAVE`
- 再执行 `AT+RESET`
- 设备重启后再次查询参数
- 查询结果与保存前一致
- 原始 Flash 参数页 `0x0800FC00` 在 reset 前后读回一致
这说明在上述测试路径下：
- 配置确实被写入 Flash
- reset 后加载流程正常
- 参数在 `设置 -> 保存 -> 复位 -> 查询` 这条路径下可以保持一致
## 11. 故障排查建议
### 11.1 发送 `AT` 没有返回
优先检查以下几项：
1. 是否连接到了 `USART1`
1. 是否连接到 `USART1`
2. 串口参数是否为 `115200 8N1`
3. 是否优先使用 `\n` 作为命令结尾
4. USB 转串口模块接线是否正确
5. 设备是否已经正常上电运行
3. 是否严格使用 `\r\n` 作为命令结尾
4. 接线是否正确
5. 设备是否正常上电运行
### 11.2 设置成功但重启后参数丢失
### 12.2 设置成功但重启后参数丢失
检查是否漏掉了以下步骤：
检查是否漏掉以下步骤：
1. `AT+SAVE`
2. `AT+RESET`
如果只执行设置命令但没有保存，参数只会停留在当前 RAM 中。
### 11.3 `AT+DHCP=1` 失败
这是当前固件设计行为，不是故障。
当前构建不支持 DHCP，因此：
```text
AT+DHCP=1\n
```
返回：
```text
ERROR: DHCP disabled in this build
```
## 12. 已实测通过的命令行为
本手册中的以下命令行为已经在实板上验证通过：
- `AT`
- `AT+?`
- `AT+QUERY`
- `AT+IP=...`
- `AT+MASK=...`
- `AT+GW=...`
- `AT+RIP=...`
- `AT+MAC=...`
- `AT+PORT=...`
- `AT+RPORT=...`
- `AT+BAUD1=...`
- `AT+BAUD2=...`
- `AT+DHCP=0`
- `AT+SAVE`
- `AT+RESET`
- `AT+DEFAULT`
已实测通过的错误路径包括：
- `AT+UNKNOWN`
- `AT+PORT=0`
- `AT+PORT=65536`
- `AT+BAUD1=1199`
- `AT+BAUD1=921601`
- `AT+DHCP=1`
- `AT+IP=999.1.1.1`
- `AT+MAC=GG:11:22:33:44:55`
1. `AT+SAVE\r\n`
2. `AT+RESET\r\n`
## 13. 相关文件