简介这是一套基于STM32 HAL库开发的4G模块通信程序工程面向物联网嵌入式开发者适用于设备接入4G网络、远程数据传输等应用场景。程序围绕AT指令交互与DTU联网配置展开覆盖4G信号强度获取、SIM卡ICCID与设备IMEI读取、登录包身份信息组建以及DTU的IP、端口、心跳包参数设置可直接部署在F1系列单片机物联网项目中。压缩包共159个文件容量约6.38MB除C源码与头文件外还包含工程配置文件、初始化图形配置、编译生成的固件及调试映射文件资源结构完整便于直接打开工程对照学习。目前已有2480人学习下载。借助该资源可快速理解单片机与4G模块的完整对接流程结合实际修改后可用于环境监测、设备定位、远程控制等场景有效缩短4G联网功能的开发周期。 四年前我第一次把4G模块接到STM32上时原本以为串口发个AT就能上网结果从PWRKEY时序到APN配置硬生生折腾了一周。后来陆续跑通了合宙Air724、移远EC801等多个模组又在量产设备上处理过网络注册不上、TCP断线不重连、SWD突然连不上这类问题才真正摸清楚STM32加HAL库驱动4G模块的完整链路。这篇文章就把我反复验证过的方案和踩过的坑一次性写出来内容围绕STM32、HAL库与4G模块开发覆盖从硬件选型、CubeMX配置、AT指令巡检到云平台接入和常见故障排查的全流程。先说清楚适合谁看。如果你急着做毕业设计或者老板丢给你一块STM32F103C8T6加一个4G模组让你几天内把数据送到云平台那照着本文操作可以少走很多弯路。如果你想系统理解“单片机怎么通过4G上网”本文也会把每个关键节点背后的原因讲明白。1. 4G模块选型与整体方案串口AT为什么最省心1.1 市面常见的4G模块分类我接触过的4G模块大概分三类。第一类是合宙Air724UG这类Cat.1模组价格低、资料多既可以OpenCPU方式二次开发也能用传统串口AT指令控制。第二类是移远EC801A、EC20这类工业级模组指令集规范、抗干扰能力强批量项目里出现频率最高。第三类是USB 4G上网模块比如高通方案的4G USB Dongle插到路由器或电脑上即插即用但这种大多走RNDIS或ECM虚拟网卡单片机没有完整网络协议栈的话很难直接用。如果用STM32 HAL库做项目我的建议是优先选串口AT指令的模块也就是第一和第二类。原因很直接HAL工程里只需要把UART当作数据管道AT指令可以边调边看出问题定位起来非常直观。你不需要在板子上再跑一个操作系统也不需要了解模块内部固件怎么写的只要按照指令集把收发逻辑做好模块就会把数据网络的部分全部处理掉。1.2 为什么不用PPP拨号或OpenCPU有朋友会问4G模块不是支持PPP拨号、内置TCP/IP协议栈吗为什么还要搞AT这背后是工程上的取舍。PPP拨号确实好用但它要求MCU侧移植完整PPP协议栈还涉及DNS、Socket、重传等机制。对裸机工程很不友好一旦断线重拨逻辑没写好整个通信链路就卡死了。OpenCPU方式则是把业务逻辑跑到模块内部省掉了外部MCU但这时你得在模块SDK里写代码调试工具链、内存管理都要重新熟悉产品迭代时反而更慢。串口AT加模块内置TCP/IP协议栈是现在绝大多数DTU、传感器网关的实际做法。外部单片机只负责按状态机发指令、收响应、透传业务数据。模块把TCP连接、DNS解析、网络重连全部管起来MCU负担降得很低稳定性主要靠模块保证。这种方式对HAL工程来说是最稳妥的因为HAL库本身擅长的是外设驱动你不需要在这个层面去实现一个完整的网络协议栈。1.3 硬件连接的基本原则选好模块后原理图上有几个位置要特别注意。模块的TXD/RXD一般要经过电平转换或直接接STM32的USART引脚很多3.3V供电的模块电平兼容3.3V可以直接连如果用了5V供电的老模块必须加电平转换否则时间长了容易烧引脚。电源部分同样不能省4G发射瞬间电流能到2A以上模块供电要单独走DCDC不能和单片机共用一颗AMS1117否则模块突然拉电流会把单片机电压拖垮。4G模组开关机检测电路一般围绕PWRKEY和STATUS/NETLIGHT两个引脚设计。PWRKEY负责开机脉冲STATUS或NETLIGHT用于读取模块状态。网上有现成的参考电路一般就是一颗三极管加两个电阻用STM32的GPIO控制三极管导通把PWRKEY拉低脉冲。STATUS引脚则直接接GPIO输入拉高表示模块已经正常启动。这一步看似简单但很多初学者在这里翻了车后面我会在开机流程里详细讲原因。2. 用CubeMX初始化HAL工程串口缓冲才是核心2.1 外设配置的推荐组合以最常见的STM32F103C8T6加移远EC801为例我在CubeMX里通常这样配RCC选择外部晶振HSE主频倍频到72MHzUSART1做调试串口USART3接4G模块波特率1152008位数据位、无校验、1位停止位再开一个USART的DMA接收通道和两个GPIO分别接模块的PWRKEY、STATUS。DMA接收不是必须项但如果要一边处理传感器数据一边解析4G模块返回DMA加中断配合环形缓冲区能大大降低串口数据丢失的概率。NVIC中断优先级的分配也有讲究。USART3接收中断设置为比定时器中断低、比主循环高的优先级确保长指令响应不会被传感器采集打断。调试串口和模块串口尽量分开不要共用一个printf输出口否则数据打印会干扰AT交互排查问题时你根本分不清哪条是模组回的、哪条是单片机自己的日志。2.2 串口中断只收一次的真相很多用HAL库的初学者都会撞上一个经典现象程序上电后能正常收到AT指令的第一条响应但之后串口就像死了一样模块再发数据都没反应。网上搜“hal库串口中断接收只收一次”答案五花八门其实根因就一句话HAL_UART_Receive_IT()一次只接收一个字节接收完成后回调里如果没有再次调用接收函数串口中断就不会再触发。正确的写法是在HAL_UART_RxCpltCallback回调里重新启动接收同时把收到的字节放入环形缓冲区。下面的代码是我在项目里实际用的模板// 全局环形缓冲区 uint8_t rx_byte; uint8_t uart3_rx_buf[512]; volatile uint16_t uart3_rx_head 0; volatile uint16_t uart3_rx_tail 0; void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart) { if (huart-Instance USART3) { uart3_rx_buf[uart3_rx_head] rx_byte; uart3_rx_head % sizeof(uart3_rx_buf); HAL_UART_Receive_IT(huart, rx_byte, 1); // 关键重新启动接收 } }主循环里只要检查tail ! head就说明有新数据到来把缓冲区按字节取出来再按行拆解成AT响应去解析。这套逻辑是所有串口通信代码的地基无论你后面接DHT11、MT6701磁编码器还是4G模块都是同一个套路。2.3 为什么必须有环形缓冲区有的教程会让你在回调里直接解析字符串不是不行但4G模块经常会把一长串网络状态、socket数据一次性发过来回调里做字符串比较很容易卡住接收流程稍不注意就丢数据。环形缓冲区相当于给硬件中断和业务解析之间加了一层缓冲中断只管快速把字节塞进队列业务代码在空闲时统一解析这样即使模块突发几十上百字节的数据一条也不会漏。从逻辑上看这就是生产者消费者模型。中断是生产者主循环是消费者。消费者处理速度再慢只要缓冲区足够大数据就不会丢。最初我把缓冲区设成64字节结果模块一次上报的注册信息超过100字节直接把还没解析的部分覆盖了后来把缓冲区扩到512字节才彻底解决。3. 从开机到网络附着时序、状态检测与指令巡检3.1 开机时序不能靠猜4G模块不是上电就工作的。Air724、EC801这类模块的典型要求是VBAT稳定供电后PWRKEY引脚被拉低至少500ms有些模块要求1秒模块才开始启动。我见过有人直接在主循环里延时100ms拉低PWRKEY结果模块永远开不了机因为模块的电源管理芯片还没完成初始化开机脉冲就已经过去了。所以开机流程应该是先确认电源脚电压稳定DCDC使能后延时至少200ms再把PWRKEY拉低800ms以上然后释放。PWRKEY这个引脚一般不能由STM32引脚直接驱动模块内部把它上拉到VBAT外部给低电平即可推荐用三极管或MOSFET做开关不要用开漏模式硬拉否则灌电流过大会影响模块稳定性。3.2 状态检测引脚的精髓模块开机是否成功光靠延时猜还不够准。EC801的STATUS引脚在模块正常运行后会输出高电平Air724的NETLIGHT引脚会随网络状态闪烁。把STATUS接到STM32的GPIO输入主循环先判断这个引脚确认模块已经正常启动再开始发AT指令比无脑等三秒可靠得多。为什么这个细节重要因为模块开机过程分为“系统起来”和“网络注册完成”两个阶段。STATUS只是告诉你系统起来了网络注册可能还要5到15秒甚至更久。有些模块在不插SIM卡时STATUS照样拉高所以光看状态引脚还不够最终要以ATCREG?的返回为准。3.3 AT指令巡检的正确顺序一个标准的启动巡检流程我按下面的顺序写每步都带超时和重试发送AT等待OK。如果等不到说明串口配置或开机时序有问题。发送ATE0关闭回显减少后面解析的干扰。发送ATCPIN?确认SIM卡识别正常返回READY才继续。发送ATCREG?或ATCGREG?检查4G网络注册状态。返回0,1表示已注册到本地网络0,5表示已漫游注册。一直返回0,2或0,0时优先检查天线和SIM卡。如果需要指定APN发送ATCGDCONT1,IP,你的APN然后ATCGACT1,1激活PDP上下文。发送ATCSQ查看信号强度返回的第一个数字在10以上基本可用小于5就要检查天线。很多项目卡在“发送ATCGACT1,1后模块主动返回一堆QIURC通知”这是模块在主动上报网络状态变化不是你发错了指令。解析代码里要能过滤这些主动上报消息否则会把正常应答识别成异常。3.4 巡检流程的工程化写法我强烈建议把巡检流程写成状态机而不是一个大while循环里按顺序发指令。原因很实际AT指令响应是异步的模块可能几毫秒就回也可能十几秒才回顺序等待的方式在遇到网络抖动时难以做超时重试。状态机的核心思想是每个状态负责发一条指令然后等待对应响应收到响应或超时后迁到下一个状态。比如状态0负责发AT状态1负责查卡状态2负责查注册每个状态都配一个5到10秒的看门狗超时。这种结构在调试时还能在串口实时打印状态编号哪一步卡住了一眼就能看到。而且移植到不同模组时只需要修改每个状态的指令内容状态机框架可以复用。4. 建立TCP通道并接入云平台心跳与粘包处理4.1 TCP连接移远模块的QIOPEN系列模块完成网络注册后就能建立TCP连接。以EC801为例流程是先用ATCGDCONT1,IP,CMNET设置上下文再ATCGACT1,1激活然后用ATQIOPEN1,0,TCP,服务器地址,端口建立socket。连接成功会返回CONNECT OK之后可以用透传模式收发数据。无论你接的是OneNET、阿里云还是自建TCP服务器本质上都是把数据塞进TCP流。云平台之间的差异主要在应用层协议底层连接方式是一样的。用花生壳做内网穿透时服务器地址就填花生壳给你的域名端口也用它映射出来的公网端口模块侧不需要任何特殊处理只看TCP目标地址和端口。4.2 接入OneNET这类云平台的思路OneNET支持多种接入协议最简单的是MQTT。EC801内置MQTT协议栈指令序列大概是先配置客户端参数然后打开连接再连接服务器建立成功后用发布指令发数据用订阅指令接收下行数据。如果自建平台那就更直接TCP加自定义协议就够了。单片机把传感器数据打包成JSON字符串按固定帧头、长度、数据体的格式发出去服务器解析入库即可。这种方案的好处是私密性高不受特定云平台约束以后想换云平台只需要改连接地址和协议解析不用改底层驱动逻辑。4.3 数据解析粘包和半包怎么处理4G模块收到网络数据后如果处于透传模式会直接在串口把数据吐出来如果是非透传模式会先上报一条通知消息比如QIURC: recv,0,32然后再用ATQIRD主动读取。无论哪种方式主控都面临两个经典问题粘包和半包。粘包指模块一次性把服务器发来多条消息合并发出半包指一条长消息被拆成两段。解决思路是在应用层定义报文边界。我用得最多的是“帧头加长度加数据体加结尾”的格式规定每帧报文以$开头后跟4位十六进制长度再跟JSON数据体。解析状态机只做三件事找帧头、收长度、收数据体完整收完一帧才交给业务层。这样无论网络层怎么切包应用层都能正确还原。4.4 心跳保活与断线重连TCP连接不会一直稳定。运营商的NAT超时时间从30秒到几分钟不等如果长时间没有数据服务器侧和运营商侧都可能把连接回收。需要在应用层加心跳包我通常设置30到60秒发一次数据格式就是{type:heartbeat,dev:dev001}。模块本身也有ATPING之类的指令但应用层心跳更可靠因为服务器能同时据此判断设备是否在线。断线重连逻辑同样要做进状态机里。当模块返回CONN LOST、QIURC: closed等通知时主控应当重新走一遍网络巡检流程先查注册状态再重连TCP。很多设备出现“一天后离线再也连不上”的问题就是因为没有处理这些异步断开通知。这个坑我踩过不止一次现在所有量产固件里都强制包含断开通知处理和自动重连机制。4.5 云服务器不在公网时的穿透方案调试阶段的服务器经常在公司内网没有固定公网IP。这时可以借助内网穿透工具比如花生壳把内网的一个TCP端口映射到公网域名和端口上模块直接连穿透服务商给的公网地址就能打通本地服务器。我做EC801和花生壳穿透联调时就是这么干的服务器端只需跑监听程序不需要公网IP。这种方案只适合开发和演示生产环境还是建议用云服务器毕竟第三方穿透服务的带宽和稳定性都不可控。5. HAL调试排错避坑实录SWD连不上与串口异常5.1 ST-Link报no target found的完整排查链路开发过程中最头疼的故障之一就是STM32突然被ST-Link认不出来提示Error: No STM32 target found! If your product embeds Debug Authentication, please perform a discovery using Debug Authentication.我遇到过好几次也帮别人排查过这类问题基本逃不出下面几个原因。第一是连接线质量或杜邦线过长。SWD信号频率较高飞线超过20cm就容易出现时序问题把线缩短到10cm以内再降低ST-Link的SWD频率通常能恢复。第二是目标板供电异常。ST-Link的3.3V输出能力有限如果板子上除了MCU还挂了4G模块、传感器整板电流已经超过ST-Link供电上限MCU会处于欠压状态自然连不上。把目标板改回外部电源供电就解决了。第三是读保护被意外开启。调试时如果把芯片的RDP等级设置成Level 1或Level 2外部调试器就无法正常连接。解决办法是BOOT0拉高复位进入系统Bootloader通过STM32CubeProgrammer整片擦除并复位RDP再重新烧录。具体操作是断电BOOT0接3.3V上电复位然后打开CubeProgrammer连接STM32内部Bootloader选择全片擦除并恢复RDP等级为AA完成后断电把BOOT0拉回低电平重新下载程序。第四是包含4G模块的电路异常复位。模块开机瞬间拉低电源轨导致MCU复位或看门狗反复触发调试器刚连上就被复位打断。此时给模块单独供电或暂时拆掉模块只留MCUSWD马上恢复正常。5.2 虚拟串口驱动的异常处理很多人用ST-Link的虚拟串口看日志明明硬件连接没问题设备管理器里却显示黄色感叹号。这种情况大概率是驱动版本不匹配或者USB枚举冲突。先去ST官网更新ST-Link驱动然后拔掉ST-Link重新插一次。如果还没解决检查设备管理器里是否同时连接了多个ST-Link把多余的拔掉只保留一个。另一个容易忽略的点是ST-Link VCP的TX/RX引脚如果没有接到MCU虚拟串口也会异常接好连接线再测试。5.3 用逻辑分析仪快速定位串口问题当模块不响应AT指令时不要急着改代码先接一个逻辑分析仪到模块TX引脚抓一段波形确认模块是不是真的把数据发出去了。很多坑查到最后是波特率不匹配或电平不对。逻辑分析仪能直观看到起始位、停止位和实际波特率比反复灌程序高效得多。还要提醒一点模块在上电初期会主动输出开机日志、网络状态通知这些不是AT指令的应答。调试时如果发现解析结果错乱先查看这些主动上报消息的格式在程序里做好过滤避免把网络层的QIURC通知当成业务指令响应处理。每次遇到4G模块通信异常我都按三层排查第一层查硬件电源、天线、电平、串口波形第二层查指令交互抓完整AT收发日志确认每一步都拿到预期响应第三层才查业务协议和服务器逻辑。很多看起来是“模块库没调好”的问题最后都出在最基础的连接和时序上。这也是我在串口缓冲区、开机时序、状态检测这些环节反复打磨的原因。如果你正在调试类似的工程建议先把这几个地基打牢后面的路会顺很多。本文还有配套的精品资源点击获取