简介：嵌入式系统开发中，实时操作系统与轻量级网络协议栈的配合是构建物联网设备的关键技术。FreeRTOS作为市场占有率极高的开源RTOS，提供基于优先级的抢占式调度与任务管理能力，帮助开发者将复杂业务拆分为独立任务，确保实时性；而lwIP则是专为资源受限设备设计的TCP/IP协议栈，支持在带OS环境下通过信号量与邮箱机制高效运行。两者结合国产高性价比MCU GD32（基于ARM Cortex-M内核），能够构建出稳定可靠的嵌入式网络终端。该组合广泛应用于工业数据采集网关、智能楼宇控制器、IoT边缘节点等场景。但在实际工程中，任务栈配置、中断优先级、PHY芯片调试、lwIP内存管理等问题常常成为落地障碍。从任务划分、lwIP移植到网络调试，系统化掌握该方案的核心要点，能够显著提升项目开发效率与稳定性。 做嵌入式这几年，像 freertos_gd32_lwip 这种压缩包我见过太多，很多朋友拿到一个项目压缩包，解压之后面对一堆代码却不知道从哪下手。这篇文章就从一个实际项目的视角，把 GD32 + FreeRTOS + lwIP 这三件套的组合逻辑、移植要点、任务划分和常见坑位一次讲透。

这套组合到底解决什么问题？简单说，就是让一颗 GD32 芯片既能跑实时任务调度，又能上网。GD32 是国产 ARM Cortex-M 内核 MCU 里出货量很大的一个系列，性价比高、外设全，但官方库和例程的风格偏传统；FreeRTOS 是市场占有率最高的开源 RTOS，生态成熟、资料多；lwIP 是嵌入式领域最流行的轻量级 TCP/IP 协议栈，专为资源受限设备设计。把三者拼在一起，就能做出一个带网络能力的实时嵌入式系统，典型的应用场景包括：工业数据采集网关、智能楼宇控制器、IoT 边缘节点、设备远程监控终端。

这篇内容适合正在折腾 GD32 网络项目、准备把工程从裸机迁到 RTOS、或者搞不清 lwIP 怎么跟 RTOS 配合的朋友。你不需要是网络协议专家，但最好对 Cortex-M 内核和中断有一定基础。

1. 项目全貌：这套组合到底在干什么

1.1 需求拆解与架构定位

一个典型的 GD32 网络项目，硬件上通常包括：GD32 主控芯片（带以太网 MAC）、一颗外接 PHY 芯片（比如 LAN8720A）、网络变压器和 RJ45 接口，再加上传感器或执行器电路。软件上需要三部分协作：RTOS 负责任务调度和资源管理，lwIP 负责网络协议处理，应用代码负责业务逻辑。

你可能会问，为什么不用裸机加一个网络协议库？因为一旦业务复杂起来，裸机的主循环很快就会变成一锅粥。比如你要同时处理网口数据、串口数据、按键输入、LED 闪烁、传感器采集，每个事件都要轮询，优先级不好控制，响应时间也没法保证。引入 FreeRTOS 之后，每个功能模块独立成任务，各自有优先级和栈空间，代码结构会清晰得多。

lwIP 和 FreeRTOS 的关系也需要提前想明白。lwIP 有两种运行模式： NO_SYS=1 是裸机模式，协议栈在主循环里被轮询调用； NO_SYS=0 是带 OS 模式，lwIP 内部会创建自己的线程（在 FreeRTOS 里叫任务），通过信号量和邮箱机制跟其他任务通信。既然项目名字叫 freertos_gd32_lwip ，那目标一定是 NO_SYS=0 的移植方式。

1.2 方案选型：为什么是这三件套

先说 GD32。我在项目里用的是 GD32F450 系列，主频最高 200MHz，自带 10/100M 以太网 MAC，集成度高，不需要外接 MAC 芯片，只要搭配一颗 PHY 就行。跟同级别的 STM32F4 相比，GD32F450 的价格通常更有优势，而且直接兼容大部分 STM32 的引脚定义，迁移成本低。

FreeRTOS 选型就更容易了，它现在由 Amazon 维护，文档齐全，内核极小，RAM 占用可以压到 1KB 以内，对 GD32 这种资源相对充裕的芯片来说毫无压力。关键在于，FreeRTOS 的调度机制成熟稳定：基于优先级的抢占式调度 + 时间片轮转，这在嵌入式多任务场景下是最实用的组合。

lwIP 选 2.1.x 版本比较稳，API 稳定、社区活跃、资料多。这里要注意一个坑：lwIP 有一个叫 netconn 的 API 层，是专门为 RTOS 环境设计的封装，比裸的 raw/callback API 好用得多。如果你看到网上有些教程直接操作 pbuf 和 tcp_pcb 回调，那是老古董写法，在 OS 环境下用 netconn 或 socket API 才是正道。

提示：版本选择上，FreeRTOS 建议用 V10.4.3 以后的内核，lwIP 用 2.1.2 或 2.1.3，这两个版本匹配度好，社区验证充分，不要一味追新。

2. 环境搭建与工程移植：从零拼起一个能跑的项目

2.1 GD32 开发环境的选择

GD32 的开发环境有几种选择：官方出的 GD32 Embedded Builder（基于 Eclipse 魔改，免费）、Keil MDK、IAR，或者纯命令行 GCC。我个人的建议是，新项目直接用 GD32 Embedded Builder 或者 Keil + GCC 工具链，原因很简单：官方例程的工程文件大多是这两种格式，直接导入最快。

如果你是 Linux 用户，用 Ubuntu + Eclipse + GCC 编译 GD32 也是完全可行的。GD32 官方提供了 GCC 启动文件和链接脚本，稍微配置一下就能编译通过。关键是启动文件（ startup_gd32f450.S ）和链接脚本（ .ld 文件）要选对，这两个文件决定了芯片上电后的初始化顺序和内存布局，出错的话程序根本跑不起来。

工程骨架建议这样组织： 

project/
├── app/
│   ├── main.c
│   ├── ethernet_if.c
│   ├── tcp_server.c
│   └── cjson_handler.c
├── bsp/
│   ├── gd32f4xx_adc.c
│   ├── gd32f4xx_gpio.c
│   └── gd32f4xx_enet.c
├── rtos/
│   ├── FreeRTOS/
│   ├── portable/
│   └── include/
├── lwip/
│   ├── src/
│   ├── include/
│   └── port/
└── md/
    ├── startup_gd32f4xx.s
    └── gd32f4xx_flash.ld

2.2 FreeRTOS 移植的核心步骤

FreeRTOS 移植到 GD32 其实很机械，因为 Cortex-M4 内核的移植代码是通用的。核心文件只有三个： port.c 、 portmacro.h 、 portASM.S ，在官方包里 portable/GCC/ARM_CM4F/ 目录下找。需要注意的适配点：

  • 配置 configCPU_CLOCK_HZ 为实际主频，比如 200MHz。
  • 配置 configTICK_RATE_HZ ，一般用 1000，代表系统时钟节拍 1ms。
  • 配置 configTOTAL_HEAP_SIZE ，总量取决于你的任务数和 lwIP 需求。
  • 配置 configSUPPORT_DYNAMIC_ALLOCATION 为 1，用动态内存分配创建任务。
  • 把 PendSV_Handler 和 SysTick_Handler 中断改成 FreeRTOS 的版本。这是移植中最容易出问题的地方，GD32 官方固件库的 gd32f4xx_it.c 里可能默认实现了这两个中断，一定要屏蔽掉，否则链接时冲突。

SysTick 在 FreeRTOS 里默认是用于系统节拍的，如果你还用 SysTick 做毫秒延时，那就冲突了。我的做法是提供独立函数 delay_ms() ，在任务里调用 vTaskDelay() ，在初始化阶段用 vTaskDelay 之外的逻辑替代。

2.3 lwIP 与 GD32 以太网 MAC 的对接

lwIP 移植的核心是提供三样东西：给 lwIP 提供时间的 sys_now 函数、底层网卡收发函数 low_level_output 和 low_level_input ，以及信号量/邮箱的适配。

GD32F450 的以太网 MAC 使用 DMA 收发描述符，初始化流程大致是：

  1. 配置 PHY 的 RMII 或 MII 模式，启用 GPIO 复用功能。
  2. 配置 MAC 地址、速率、双工模式。
  3. 设置 DMA 描述符链，分配收发缓冲区。
  4. 使能 MAC 和 DMA 中断。

底层收发函数的核心逻辑是： low_level_input 从 DMA 描述符里取一帧数据，拷贝到 lwIP 的 pbuf 里，返回给协议栈； low_level_output 把 lwIP 的 pbuf 数据链，通过 DMA 描述符发出去。数据拷贝在这个环节是不可避免的，但可以优化：在设计 PHY 芯片和缓冲区时，用 RB 描述符（Receive Buffer Descriptor）做双缓冲，减少丢帧概率。

中断处理上，以太网 RX 中断里不要直接调用 lwIP 的函数，而是用信号量通知 tcpip_thread 来处理。这也是 lwIP 在 OS 模式下的推荐做法。

3. 核心代码实现：任务划分与业务逻辑

3.1 FreeRTOS 任务设计与优先级分配

任务设计是这个项目最体现功力的一步。优先级分配的原则是：实时性要求高的任务优先，但不要优先级反转或饿死低优先级任务。下面是我在实际项目里用过的任务表：

任务名 优先级 栈大小（字） 职责
tcpip_thread 5（最高） 1024 lwIP 协议栈处理，自带
netif_link 4 512 检测网线插拔，更新链路状态
app_tcp_server 3 1024 TCP 业务逻辑，接收命令
app_data_report 2 768 定时上报传感器数据
app_led_blink 1（最低） 256 LED 指示，心跳灯
idle_task 0 128 FreeRTOS 自带空闲任务

注意 tcpip_thread 是 lwIP 在 tcpip_init() 时自动创建的，它的栈大小可以在 lwipopts.h 里配置 TCPIP_THREAD_STACKSIZE 。如果栈开小了，抓包看起来一切正常，但运行一段时间后协议栈会随机死掉，这是隐蔽的坑。

每个任务里都要用 vTaskDelay 或信号量等待替代空转轮询。有人觉得加个 vTaskDelay(1) 无所谓，但这对低功耗和 CPU 占用率影响巨大。在电池供电的设备里，尽量减少任务空转，能显著降低功耗。GD32 的待机模式 + 按键唤醒功能在这个场景下也非常实用，任务全部挂起后可以进入待机状态，按一下唤醒按键重新初始化。

3.2 TCP 服务端的实现：从裸 API 到 netconn API

这里上一个实际可用的 TCP 服务端代码框架，用 netconn API，在 FreeRTOS 任务里跑： 

#include "lwip/netconnapi.h"
#include "lwip/api.h"
#include "cmsis_os.h"

static void tcp_server_thread(void *arg)
{
    struct netconn *conn, *newconn;
    struct netbuf *buf;
    err_t err;

    conn = netconn_new(NETCONN_TCP);
    netconn_bind(conn, IP_ADDR_ANY, 8080);
    netconn_listen(conn);

    while (1) {
        err = netconn_accept(conn, &newconn);
        if (err == ERR_OK) {
            while (1) {
                err = netconn_recv(newconn, &buf);
                if (err == ERR_OK) {
                    /* 处理收到的数据，这里交给 cJSON 解析 */
                    handle_json_packet(newconn, buf);
                    netbuf_delete(buf);
                } else {
                    break;
                }
            }
            netconn_close(newconn);
            netconn_delete(newconn);
        }
    }
}

这段代码的逻辑是：创建监听 socket，接受连接后循环收数据，收到数据交给 JSON 解析函数处理。注意 handle_json_packet 里千万别做耗时太长的操作，比如往 flash 里写日志，否则会阻塞这个连接的接收，并发性能会受影响。如果业务复杂，应该在解析后把数据放到队列里，由专门的任务去处理。

3.3 cJSON 集成与数据包装

跟 lwIP 配合最常做的就是 JSON 数据交互。cJSON 是一个轻量级的 JSON 解析/生成库，单文件，移植非常方便。在嵌入式里使用要注意：默认的 cJSON 使用 malloc 动态内存，而 FreeRTOS 环境下最好重定义内存函数，统一使用 FreeRTOS 的堆： 

#define cJSON_malloc  pvPortMalloc
#define cJSON_free    vPortFree

这样 cJSON 分配的内存就来自 FreeRTOS 的堆管理，避免碎片化。实测下来，当 JSON 数据包比较大，几十 KB 级别时，FreeRTOS 的 heap_4 能有效避免内存碎片，比裸机的标准库 malloc 稳得多。

数据包的构造也别大意，推荐的做法是，用 cJSON 构造好 JSON 对象之后，一次性调用 cJSON_PrintUnformatted 输出，然后用 netconn_write 发送。注意 netconn_write 支持 NETCONN_COPY 标志，如果你不确定缓冲区生命周期，就加上这个标志，它会帮你拷贝数据，安全第一。

4. 常见问题与调试实录：这些坑我替你踩过了

4.1 任务栈溢出与内存不足

栈溢出是最常遇到却又最隐蔽的问题。症状是系统跑一会儿就随机死机，或者某个任务突然消失。排查方法有两个：

  1. 打开 FreeRTOS 的栈溢出检测：在 FreeRTOSConfig.h 中设置 configCHECK_FOR_STACK_OVERFLOW 为 2，并实现 vApplicationStackOverflowHook() ，在里面点亮一个错误 LED 或打印信息。
  2. 用 uxTaskGetStackHighWaterMark() 查询每个任务的栈剩余空间，在任务启动后跑一段时间再查看数据，确认有没有逼近危险水位。

内存方面， configTOTAL_HEAP_SIZE 要综合考虑所有任务的栈、队列、信号量、lwIP 的 pbuf 池和 TCP 窗口内存。我的经验值是：一个 4 任务的简单系统，总堆 32KB 起；如果跑 TCP 大包收发，建议 48KB 以上。GD32F450 的 SRAM 通常是 256KB 或更多，空间是够的。

4.2 网卡 Ping 不通的排查路径

网口 ping 不通，90% 是以下原因：

  • PHY 复位时序不对。PHY 芯片需要上电后等待一段复位时间，常见的是 1ms 到 10ms，如果初始化太快，PHY 还没就绪，读 PHY_REG_BSR 时一直超时。解决：初始化前延时 100ms。
  • RMII 引脚复用配置漏了。GD32 的 ETH 引脚需要配置为 AF_PP（复用推挽）模式，且时钟要打开。这个很容易因为 GPIO 配置不完整，导致 RX 端收不到数据。
  • MAC 地址全零。 netif->hwaddr 如果全为 0，部分交换机厂商的设备会拒绝转发。随便设一个比如 00:80:E1:00:00:01 就行。
  • MDC 时钟频率超标。MDC 最大频率是 2.5MHz，如果系统时钟分频不对，MDIO 读取会出错，PHY 状态始终不对。

调试时先用示波器或逻辑分析仪抓 RMII 的 MDC/MDIO 信号，确认链路层通不通；再在 status_callback 里打印 netif_is_link_up() 的状态，确认 PHY 协商结果；最后再看收发中断有没有触发。一层层下来，问题很快能定位。

4.3 中断优先级与临界区的冲突

GD32 和 STM32 一样，Cortex-M 内核支持中断优先级嵌套。FreeRTOS 在 portmacro.h 里用 configMAX_SYSCALL_INTERRUPT_PRIORITY 限制哪些中断里可以调用 FreeRTOS API。如果以太网 DMA 中断的优先级数值高于这个宏配置（数值更大，优先级更低），那么在这个中断里调用 tx_sem 等同步原语会直接触发断言。

这个问题的典型表现是：调试器里看到 configASSERT 触发，或者在中断使能瞬间系统崩溃。解决方法很简单：把 configMAX_SYSCALL_INTERRUPT_PRIORITY 调整到比所有使用 FreeRTOS API 的中断优先级数值大，比如设为 5，以太网中断设为 7（数值大代表优先级低，可以安全调用）。

注意：Cortex-M 的优先级数值越小，优先级越高，这一点和 FreeRTOS 任务优先级正好相反，初学容易搞混。

4.4 调试总结：一份速查表

症状 可能原因 排查/解决
系统随机死机 任务栈溢出或堆不足 开启栈溢出检测，查询高水位
网口持续 ping 不通 PHY 复位/GPIO/MDC 检查复位时序、引脚复用、MDC 分频
数据收发一帧就卡住 DMA 描述符不足 加大 ETH_RXBUFNB 和 ETH_TXBUFNB
接收数据乱码 DHCP 冲突或 IP 重叠 静态 IP 实验排除协议问题
不定时进 configASSERT 临界区中断优先级配置错误 调整 configMAX_SYSCALL_INTERRUPT_PRIORITY
lwIP 跑一段时间内存耗尽 pbuf 池过小或数据泄漏 调用 tcpip_thread 栈统计，检查 netbuf_delete

5. 项目继续深挖的方向

如果这个项目要走到量产或者后续版本迭代，有几个方向可以考虑：

第一，把 lwIP 的内存配置做成可调节的。在 lwipopts.h 里， MEM_SIZE 决定堆大小， PBUF_POOL_SIZE 决定 pbuf 池深度， TCP_SND_BUF 和 TCP_WND 决定 TCP 吞吐和接收窗口。这几个参数互相影响，建议通过测试不同配置下的吞吐率来调节。

第二，从 TCP 服务端扩展到 MQTT 客户端。lwIP 配合 MQTT 库可以很方便地接入云端平台，做远程设备监控。再把 cJSON 升级成更紧凑的 BSON 或者 Protobuf，能进一步减少网络流量。

第三，把串口、网络、任务日志整合成一个统一的调试通道。我在实际项目中习惯加一个 shell 任务，网络口和串口都能调出命令，这样在产品现场不用接调试器也能查看系统状态和修改参数。

这套 GD32 + FreeRTOS + lwIP 的组合，说白了就是嵌入式联网设备的“黄金搭档”。花时间把这套底子打好，以后不管换芯片还是换业务，都能快速复用，边际成本很低。

本文还有配套的精品资源，点击获取 menu-r.4af5f7ec.gif

Logo
乐奇 Rokid 开放社区

更多推荐

在 Rokid AI Glasses 上做背单词应用：AIUI拍照听写的实现

分享在 Rokid AI Glasses 上用 AIUI 开发背单词应用的实践：从镜腿单击拍照、图片编码和多模态识别，到切题时的异步任务处理、语音调度与学习进度保存，结合关键代码和界面动图说明实现过程。

avatar 乐奇 Rokid 开放社区
cover

极刻觅镜 | AI眼镜周报｜智能眼镜周报：销售高增长、标准落地与新品密集发布

avatar 乐奇 Rokid 开放社区
cover

极刻觅镜 | AI眼镜日报｜Rokid无人店落地香港，中科创达发布Veda平台

avatar 乐奇 Rokid 开放社区