# TCP2UART 项目说明

`TCP2UART` 是一个基于 `STM32F103RCT6 + CH390D` 的 TCP 与双串口透传固件。系统运行在 `FreeRTOS` 上，网络协议栈使用 `lwIP NO_SYS=0 + netconn API`，通过 `SEGGER RTT` 输出调试日志，工程入口为 Keil MDK 项目 `MDK-ARM/TCP2UART.uvprojx`。

本仓库当前文档已经收敛为两类：

1. 面向开发者的代码阅读与系统理解文档。
2. 面向上位机、测试和联调人员的 AT 命令接口文档。

## 硬件与软件基线

| 项目 | 内容 |
|------|------|
| 主控 | `STM32F103RCT6` |
| 以太网芯片 | `CH390D` |
| 配置串口 | `USART1` |
| 数据串口 | `USART2`、`USART3` |
| RTOS | `FreeRTOS` |
| TCP/IP | `lwIP`，`NO_SYS=0`，启用 `netconn` API |
| 调试输出 | `SEGGER RTT` |
| 构建工程 | `MDK-ARM/TCP2UART.uvprojx` |

`USART1` 只承担 AT 配置面。`USART2/USART3` 是业务数据口，可工作在普通透传模式或 MUX 帧模式。网络侧提供 2 路 TCP Server 实例和 2 路 TCP Client 实例，统一使用 `LINK` 配置模型管理。

## 当前文档地图

| 文档 | 读者 | 内容 |
|------|------|------|
| `README.md` | 所有人 | 项目总览、文档入口、快速理解路径 |
| `项目代码阅读指南.md` | 固件开发、调试、交接人员 | 代码目录、启动流程、任务模型、数据流、阅读顺序、调试线索 |
| `AT固件使用手册.md` | 上位机、测试、联调人员 | AT 命令、参数模型、默认值、配置流程、常见错误 |

旧的需求说明、技术实现、调试交接、Prompt 和单点问题复盘文档已经合并到上述文档中。临时调试结论不再作为根目录入口，避免把某一轮现场状态误认为长期项目事实。

## 一句话架构

```text
远端 TCP 连接
    |
    v
TcpSrvTask_S1/S2 或 TcpCliTask_C1/C2
    |
    v
route_msg_t + FreeRTOS Queue
    |
    v
UartRxTask / uart_trans
    |
    v
USART2 / USART3
```

反向数据流也走同一套路由对象：数据口收到字节后由 `UartRxTask` 判断普通透传或 MUX 帧，再投递到对应 `xLinkTxQueues[]`，最终由 TCP 任务调用 `netconn_write()` 发回网络。

## 快速阅读顺序

首次接手建议按下面顺序阅读：

1. `README.md`：确认硬件、软件、文档入口。
2. `项目代码阅读指南.md` 的“总体架构”和“业务数据流示例”：先建立整体图。
3. `Core/Src/main.c`：理解上电初始化顺序。
4. `Core/Src/freertos.c`：理解队列、信号量和任务创建。
5. `App/config.c`、`AT固件使用手册.md`：理解配置模型和 AT 命令。
6. `App/tcp_server.c`、`App/tcp_client.c`、`App/uart_trans.c`、`App/route_msg.c`：理解 TCP 与 UART 如何互相转发。
7. `App/task_net_poll.c`、`Drivers/CH390/*`、`Drivers/LwIP/src/netif/ethernetif.c`：需要定位网络底层问题时再深入。

## 核心配置模型

固件内部把所有链路抽象为 4 条 `LINK`：

| 角色 | 内部索引 | 端点编码 | 含义 |
|------|----------|----------|------|
| `S1` | `CONFIG_LINK_S1` | `0x10` | TCP Server 1 |
| `S2` | `CONFIG_LINK_S2` | `0x20` | TCP Server 2 |
| `C1` | `CONFIG_LINK_C1` | `0x01` | TCP Client 1 |
| `C2` | `CONFIG_LINK_C2` | `0x02` | TCP Client 2 |
| `UART2` / `U0` | `LINK_UART_U0` | `0x04` | 数据串口 0 |
| `UART3` / `U1` | `LINK_UART_U1` | `0x08` | 数据串口 1 |

每条 `LINK` 记录包含：启用状态、本地端口、远端 IP、远端端口、绑定的数据串口。外部配置命令见 `AT固件使用手册.md`。

## 常用开发入口

| 目的 | 文件 |
|------|------|
| 上电初始化 | `Core/Src/main.c` |
| 任务和队列创建 | `Core/Src/freertos.c` |
| AT 命令与 Flash 参数 | `App/config.c`、`App/flash_param.c` |
| 路由消息池 | `App/route_msg.c` |
| UART DMA/IDLE、普通透传、MUX 帧 | `App/uart_trans.c` |
| TCP Server | `App/tcp_server.c` |
| TCP Client | `App/tcp_client.c` |
| 网络初始化和轮询 | `App/task_net_poll.c` |
| CH390 与 lwIP netif | `Drivers/CH390/*`、`Drivers/LwIP/src/netif/ethernetif.c` |
| RTT 日志封装 | `Core/Src/debug_log.c` |

## 调试提示

1. 启动阶段先看 RTT 中的 `debug_log_boot()` 里程碑，例如 `hal-init`、`clock-config`、`peripherals-ready`、`tasks-created`、`scheduler-start`。
2. 网络阶段重点看 `NetPollTask` 的 `tcpip-init`、`netif-init`、`netif-ready`、`post-ready free/min heap` 日志。
3. TCP 或 UART 透传异常时，优先检查 `route_send()` 返回的 `pool`、`queue`、`invalid`，它们能区分消息池耗尽、队列满和参数错误。
4. HardFault、MemManage、BusFault、UsageFault 会进入 `Debug_TrapWithRttHint()`，应先保留 RTT 现场再修改代码。
5. `STM32F103RCT6` RAM 余量有限；如果 full-task 模式下问题呈现强资源相关特征，应优先核对堆、栈、水位和 lwIP 池配置，不要只看业务逻辑。

更详细的阅读和调试路线见 `项目代码阅读指南.md`。