★ FEATURED ARTICLE 1. 项目缘起与整体设计思路嵌入式开发做久了你会发现一个规律越是看起来简单的需求越容易在细节上翻车。这次要聊的这个项目需求本身并不复杂——用MicroPython从文件里读取配置信息然后通过AT指令配置一个汉枫WIFI模块让它进入TCP透传模式。但真正动手做的时候从配置文件格式设计、串口通信稳定性、AT指令时序控制到透传模式的状态确认每一步都有坑。先说清楚这个项目解决的是什么问题。在很多物联网终端设备里主控芯片负责业务逻辑WIFI通信则交给独立的WIFI模块来处理。主控和WIFI模块之间通过串口连接用AT指令交互。这种架构的好处是主控不需要跑复杂的网络协议栈WIFI模块厂商已经把TCP/IP协议栈封装好了你只需要发几条AT指令就能建立TCP连接。汉枫的WIFI模块在国内工控和物联网领域用得比较多它的AT指令集相对规范透传模式下数据双向透明传输对主控来说就像操作一个串口一样简单。那为什么要用MicroPython从文件读取配置信息因为在实际部署中WIFI的SSID、密码、目标服务器IP和端口这些参数经常需要修改。如果把这些参数硬编码在代码里每次改配置都要重新烧录固件这在现场部署时非常麻烦。把配置信息放在一个独立的文件里修改配置只需要改文件内容不用动代码维护效率高很多。MicroPython本身支持文件系统操作读取JSON或者键值对格式的配置文件都很方便。这个项目的适合人群是有一定MicroPython基础、了解串口通信原理、需要在嵌入式设备上集成WIFI通信功能的开发者。如果你之前没接触过AT指令也不用担心我会把每条指令的作用和参数含义都讲清楚。整个方案的思路是这样的设备上电后MicroPython先读取配置文件解析出WIFI连接参数和服务器信息然后通过UART向汉枫模块发送AT指令依次完成模块自检、WIFI连接、TCP连接建立、进入透传模式这几个步骤。每个步骤都需要等待模块返回预期结果确认成功后再进行下一步任何一步失败都要有重试和错误处理机制。我选择用JSON格式来存配置信息原因是JSON结构清晰、可读性好、MicroPython内置了json模块可以直接解析不需要额外安装库。配置文件放在文件系统的根目录下命名为config.jsonMicroPython启动后首先读取这个文件。如果你用的是ESP32或者ESP8266跑MicroPython文件系统就是内置的Flash分区如果用其他主控可能需要外挂SD卡或者SPI Flash但文件操作的API是一样的。整个方案的硬件连接也不复杂主控的一个UART接口连接到汉枫模块的串口引脚注意TX和RX要交叉连接波特率通常默认是115200但具体要看模块型号和出厂设置。供电方面汉枫模块在建立TCP连接和传输数据时电流会有波动建议单独给它一路稳定的3.3V供电不要和主控共用LDO输出否则可能出现连接不稳定甚至模块重启的问题。这个坑我在实际项目中踩过后面会详细说。2. 核心细节解析与实操要点2.1 配置文件格式设计与解析逻辑配置文件的设计看似简单但有几个关键决策需要想清楚。首先是格式选择我对比过三种方案纯文本键值对、JSON、以及Python字典直接写在.py文件里。纯文本键值对解析起来要自己写字符串处理逻辑容易出错Python字典虽然直接import就能用但修改配置需要保证语法正确现场人员容易改错JSON是折中方案结构清晰解析可靠而且用任何文本编辑器都能改。配置文件的内容大概长这样{ wifi: { ssid: YourSSID, password: YourPassword }, server: { host: 192.168.1.100, port: 8080 }, uart: { baudrate: 115200, tx_pin: 17, rx_pin: 16 } }这里我把配置分成了三组wifi组存SSID和密码server组存目标服务器的IP和端口uart组存串口参数。为什么要分组因为不同组的配置修改频率不一样。WIFI信息可能在部署时改一次就不动了服务器信息可能根据项目不同而变化串口参数一般固定但偶尔需要调整。分组之后现场人员改配置时目标更明确不容易改错地方。解析逻辑用MicroPython的json模块import json def load_config(path/config.json): try: with open(path, r) as f: config json.load(f) return config except OSError: print(Config file not found) return None except ValueError: print(Config file format error) return None这里有个细节要注意json.load()在文件内容不是合法JSON时会抛出ValueError文件不存在时抛出OSError。两种异常要分开处理因为排查方向完全不同——前者是配置内容写错了后者是文件根本没放进去。我在实际项目中遇到过现场人员用Windows记事本编辑JSON文件保存时带了BOM头导致解析失败。解决办法是在读取时用utf-8-sig编码或者提醒现场人员用支持UTF-8无BOM的编辑器。注意MicroPython的文件系统空间有限配置文件不要写太多注释和多余空格否则会占用宝贵的Flash空间。另外配置文件读取后建议在内存中保留一份副本避免每次需要参数时都去读文件。2.2 汉枫模块AT指令集关键指令解析汉枫WIFI模块的AT指令集比较丰富但配置进入TCP透传只需要用到其中几条核心指令。我把关键指令和它们的返回值整理成了一张表方便你对照查阅指令作用预期返回注意事项AT模块自检OK确认串口通信正常ATWMODE1设置为STA模式OK1表示STA2表示APATWJAPssid,pwd连接WIFIOK连接成功返回OK失败返回ERRORATWJAP?查询WIFI连接状态WJAP:...可用于确认是否真正连上ATWIPSTARTTCP,host,port建立TCP连接OK参数顺序不能错ATWIPMODE1进入透传模式OK进入后AT指令不再生效ATWIPMODE0退出透传模式OK需要先发送退出这里重点说几个容易出问题的地方。ATWJAP这条指令模块连接WIFI需要时间从发送指令到返回OK可能有几秒钟的延迟。如果你用固定的短超时去等很可能还没连上就超时了。我的做法是给这条指令单独设置10秒超时其他指令用3秒超时就够了。ATWIPSTART建立TCP连接时如果目标服务器不可达模块会返回ERROR或者一直不返回。这时候要有超时重试机制不能死等。我一般设置连接超时为15秒失败后重试2次还不行就报错重启WIFI模块。进入透传模式的ATWIPMODE1这条指令有个坑发送之后模块返回OK但这个OK是在进入透传模式之前返回的。也就是说你收到OK的时候模块可能还没完全切换到透传状态。我的经验是收到OK后再等200毫秒然后再开始发送业务数据这样比较稳妥。提示不同型号的汉枫模块AT指令集可能有细微差异比如有些型号用ATCWJAP而不是ATWJAP。动手之前一定要找到对应型号的AT指令手册不要凭经验套用。2.3 串口通信的稳定性设计MicroPython操作UART的API很简洁但要用稳需要额外做几件事。首先是串口初始化from machine import UART, Pin uart UART(2, baudrate115200, txPin(17), rxPin(16), timeout1000)timeout参数很关键它决定了uart.read()等待数据的最长时间。设得太短模块还没返回你就读完了拿到空数据设得太长程序会阻塞在这里影响其他任务。我一般设1000毫秒配合下面的读取函数使用def uart_read_until(uart, expected, timeout3000): import time start time.ticks_ms() buf b while time.ticks_diff(time.ticks_ms(), start) timeout: if uart.any(): data uart.read() if data: buf data if expected in buf: return buf time.sleep_ms(50) return buf这个函数的作用是在指定超时时间内不断读取串口数据直到收到预期的字符串或者超时。为什么要循环读取而不是读一次因为模块返回的数据可能分多次到达串口缓冲区一次read()不一定能拿到完整响应。循环读取配合time.sleep_ms(50)的小延时既能保证数据完整性又不会过度占用CPU。还有一个细节发送AT指令时要在末尾加上\r\n这是AT指令的标准结束符。有些模块对\r\n和\n都兼容但加上\r\n是最保险的做法。发送函数这样写def send_at(uart, cmd, waitOK, timeout3000): uart.write(cmd \r\n) return uart_read_until(uart, wait, timeout)每次发送指令后我都会把模块的返回内容打印出来方便调试。正式部署时可以关掉打印但在开发阶段这些日志能帮你快速定位问题。3. 实操过程与核心环节实现3.1 完整配置流程的代码实现把前面讲的各个模块串起来整个配置流程分成五个阶段读取配置、初始化串口、模块自检与WIFI连接、TCP连接建立、进入透传模式。下面按顺序展开。第一阶段读取配置文件并解析config load_config() if config is None: print(Failed to load config, using defaults) config { wifi: {ssid: default_ssid, password: default_pwd}, server: {host: 192.168.1.100, port: 8080}, uart: {baudrate: 115200, tx_pin: 17, rx_pin: 16} }这里做了一个降级处理如果配置文件读取失败使用一套默认配置继续运行。这样做的好处是设备不会因为配置文件丢失就完全不能用至少还能尝试连接默认网络。当然默认配置里的参数要根据你的实际环境来设。第二阶段初始化串口uart UART(2, baudrateconfig[uart][baudrate], txPin(config[uart][tx_pin]), rxPin(config[uart][rx_pin]), timeout1000)第三阶段模块自检和WIFI连接import time def init_wifi_module(uart, wifi_config): # 模块自检 resp send_at(uart, AT, OK, 3000) if bOK not in resp: print(Module not responding) return False # 设置为STA模式 resp send_at(uart, ATWMODE1, OK, 3000) if bOK not in resp: print(Failed to set STA mode) return False # 连接WIFI cmd ATWJAP{},{}.format( wifi_config[ssid], wifi_config[password]) resp send_at(uart, cmd, OK, 10000) if bOK not in resp: print(Failed to connect WiFi) return False # 确认连接状态 time.sleep(1) resp send_at(uart, ATWJAP?, WJAP, 3000) print(WiFi status:, resp) return True这段代码里WIFI连接指令的超时设成了10秒因为实际测试下来从发送指令到模块连上路由器快的时候2秒慢的时候7-8秒都有可能。如果路由器信号弱或者密码错误模块可能一直不返回10秒超时后就会走失败分支。第四阶段建立TCP连接def connect_tcp(uart, server_config, retry2): for i in range(retry 1): cmd ATWIPSTARTTCP,{},{}.format( server_config[host], server_config[port]) resp send_at(uart, cmd, OK, 15000) if bOK in resp: print(TCP connected) return True print(TCP connect attempt {} failed.format(i 1)) time.sleep(2) return False重试机制很重要。TCP连接失败的原因很多服务器没开、网络不通、模块状态异常。重试之前加2秒延时给模块一点恢复时间。如果重试2次还不行就应该考虑重启WIFI模块或者上报错误了。第五阶段进入透传模式def enter_transparent_mode(uart): resp send_at(uart, ATWIPMODE1, OK, 5000) if bOK not in resp: print(Failed to enter transparent mode) return False time.sleep_ms(200) print(Transparent mode active) return True进入透传模式后串口上发送的任何数据都会被模块直接转发到TCP连接的对端模块返回的数据也会直接出现在串口上。这时候就不能再用AT指令了要退出透传需要发送注意前后要有至少1秒的静默时间模块会返回确认信息并退出透传。3.2 主流程串联与异常处理把上面五个阶段串起来主流程大概是这样def main(): config load_config() if config is None: print(Config load failed) return uart UART(2, baudrateconfig[uart][baudrate], txPin(config[uart][tx_pin]), rxPin(config[uart][rx_pin]), timeout1000) if not init_wifi_module(uart, config[wifi]): print(WiFi init failed, restarting...) return if not connect_tcp(uart, config[server]): print(TCP connect failed, restarting...) return if not enter_transparent_mode(uart): print(Transparent mode failed, restarting...) return # 透传模式下的业务逻辑 transparent_loop(uart) def transparent_loop(uart): while True: if uart.any(): data uart.read() if data: # 处理从服务器收到的数据 process_server_data(data) # 这里可以加入定时发送或其他业务逻辑 time.sleep_ms(10)异常处理的核心思路是任何一步失败都打印明确的错误信息然后重启整个流程。在实际部署中我会加一个看门狗定时器如果主流程卡死超过一定时间就自动复位设备。MicroPython的machine.WDT可以派上用场。注意透传模式下如果TCP连接断开模块通常会通过串口输出断开提示信息。你的业务代码需要能识别这类信息并触发重连流程。不同模块的断开提示格式不一样建议在调试阶段故意断开服务器观察模块输出什么内容。3.3 参数计算与选型依据串口波特率的选择115200是汉枫模块的常见默认值也是大多数主控能稳定支持的最高常用波特率。如果你需要传输大量数据可以考虑提高到921600但前提是主控和模块都支持而且接线质量要好。我在实际项目中用115200跑透传传输小批量传感器数据完全够用。超时时间的设定前面提到的各个超时值不是拍脑袋定的而是根据实际测试结果加上一定余量。比如WIFI连接实测最快2秒最慢8秒设10秒超时留了2秒余量。TCP连接实测最快1秒最慢12秒服务器响应慢的时候设15秒超时。这些数值你可以根据自己的网络环境调整但原则是宁可多等一会儿不要过早判定失败。重试次数的选择TCP连接重试2次WIFI连接不重试因为WIFI连接失败通常是密码错误或信号问题重试也没用。这个策略是在多个现场部署后总结出来的能覆盖大部分临时性故障又不会让启动时间过长。4. 常见问题与排查技巧实录4.1 串口通信类问题排查问题一发送AT指令后没有任何返回。这是最常见的问题排查顺序如下先确认TX和RX有没有接反这是新手最容易犯的错误然后用万用表量一下模块的供电电压是不是稳定的3.3V接着确认波特率是否匹配有些模块出厂波特率是9600而不是115200最后检查串口引脚号是否配置正确不同主控的UART引脚编号不一样。问题二返回的数据不完整或者乱码。乱码通常是波特率不匹配导致的微调波特率试试。数据不完整一般是读取逻辑的问题确保你用了循环读取而不是单次读取。另外如果主控和模块之间连线较长超过20厘米建议在TX和RX线上加100欧姆的串联电阻减少信号反射。问题三AT指令返回OK但后续操作失败。这种情况说明串口通信本身没问题但模块状态不对。可能是模块之前进入了透传模式没有退出这时候发送退出透传然后重新走配置流程。也有可能是模块固件版本和指令集不匹配用ATVER?查询固件版本对照手册确认指令用法。4.2 WIFI连接类问题排查问题四WIFI连接一直返回ERROR。先确认SSID和密码是否正确注意大小写和特殊字符。如果SSID是中文或者包含空格需要确认模块是否支持。另外有些路由器开启了MAC地址过滤或者AP隔离也会导致连接失败。用手机热点测试一下如果热点能连上而路由器连不上问题就出在路由器配置上。问题五WIFI连接成功但TCP连接失败。WIFI连上只说明模块和路由器之间通了TCP连接失败可能是服务器地址不对、端口没开、或者服务器和模块不在同一个网段。先用电脑ping一下服务器IP确认网络可达。如果服务器在公网还要确认防火墙有没有放行对应端口。问题六透传模式下数据丢失。透传模式下数据丢失通常有两个原因一是串口缓冲区溢出主控发送数据太快模块来不及处理。解决办法是在发送大量数据时加流控或者降低发送速率。二是TCP连接实际上已经断开但模块没有及时通知主控数据发出去就丢了。建议在应用层加心跳机制定期发送心跳包检测连接状态。4.3 配置文件类问题排查问题七配置文件读取失败。先确认文件确实存在于文件系统中用os.listdir()查看根目录下的文件列表。然后确认文件名和路径大小写是否匹配MicroPython的文件系统区分大小写。最后检查JSON格式是否合法可以用在线的JSON校验工具先验证一下。问题八配置修改后不生效。MicroPython在读取文件后可能会缓存修改文件后需要重新读取。另外如果你是通过串口REPL修改的文件确保写入操作已经完成文件对象要close。最保险的做法是修改配置后重启设备。4.4 独家避坑经验第一个坑汉枫模块在进入透传模式后如果TCP连接断开模块会输出类似CLOSED的提示信息。这个信息会混在正常的业务数据里如果你的业务数据处理逻辑没有过滤掉它可能会把断开提示当成有效数据来处理。我的做法是在透传循环里先检查数据中是否包含断开关键词如果有就触发重连。第二个坑模块供电不足会导致各种奇怪的问题比如AT指令偶尔不返回、WIFI连接随机失败、透传数据丢包。我遇到过一块板子用主控的3.3V LDO同时给主控和WIFI模块供电WIFI发射时电流突增导致电压跌落主控直接复位。后来给WIFI模块单独加了一路LDO和100uF的滤波电容问题彻底解决。第三个坑MicroPython的UART在接收大量数据时如果不用中断或者DMA可能会丢数据。透传模式下如果服务器发送的数据比较密集建议把UART接收缓冲区设大一些或者用uart.irq()注册中断处理函数。不过中断处理函数里不能做太耗时的操作收到数据后尽快存入缓冲区在主循环里再处理。第四个坑配置文件里的端口号要写成数字而不是字符串。JSON里port: 8080和port: 8080看起来差不多但拼接AT指令时字符串会多出引号导致指令格式错误。这个坑很隐蔽因为JSON解析不会报错但AT指令就是失败。建议在解析后加一个类型检查。问题现象可能原因排查方法解决方案AT无返回接线错误/波特率不匹配检查TX/RX交叉、测量电压重新接线、调整波特率WIFI连接ERROR密码错误/信号弱用手机验证密码、查看信号强度修正密码、靠近路由器TCP连接超时服务器不可达/端口未开ping服务器、telnet端口检查服务器状态和防火墙透传数据丢失缓冲区溢出/连接已断降低发送速率、加心跳加流控、实现重连机制配置读取失败文件不存在/格式错误列出文件、校验JSON重新放置文件、修正格式这张表可以打印出来贴在工位上遇到问题按表排查能省不少时间。我自己的经验是80%的问题集中在接线、供电和配置格式这三类上真正涉及代码逻辑的bug反而比较少。所以每次调试新板子先花五分钟检查硬件连接和供电比上来就改代码效率高得多。透传模式下的数据收发测试我一般用网络调试助手在服务器端配合。先发几个短字符串确认双向通信正常再发长数据测试稳定性。如果长数据有问题多半是缓冲区或者流控的问题。另外透传模式下模块的串口波特率和TCP数据速率要匹配如果串口是115200而服务器发送速率远高于此数据必然丢失。这时候要么提高串口波特率要么在服务器端限制发送速率。最后分享一个调试技巧在开发阶段把每一步AT指令的发送内容和模块返回内容都打印出来包括时间戳。这样当出现问题时你能清楚地看到是哪条指令超时了、模块实际返回了什么。正式部署时再把这些调试输出关掉。我习惯用print([{:.3f}] TX: {}.format(time.time(), cmd))这样的格式时间戳精确到毫秒排查时序问题特别有用。
阅读完成 · 觉得有帮助？
