找回密码
立即注册
搜索
发回帖 发新帖

6882

积分

0

好友

874

主题
发表于 9 小时前 | 查看: 5| 回复: 0
  • 从烧固件到手机配网,一个下午踩了 7 个坑
  • 全程没有打开 IDE,也没有查阅数据手册
  • 有些问题,只有接上真实硬件和网络才能发现

引子

抽屉里翻出一块 NodeMCU:ESP8266 芯片,MicroPython 时代的老朋友,大约是 10 年前买的。插上电脑,设备管理器里出现了 COM10,串口芯片是 CP210x。

NodeMCU ESP8266 开发板实物

ESP-12E NodeMCU 开发板引脚功能图

我打开 WorkBuddy,敲了一句话:

我这有一块 ESP8266 的小板子,NodeMcu 的板子,现在连接到电脑上了,串口号是 COM10,你能不能直接帮我写个脚本程序下载进去运行+调试?

后面的过程比预想中有意思。不是因为顺利,恰恰相反:从烧固件、写脚本,到网页控制和手机配网,一路都在排查问题。

这篇文章把过程和遇到的坑整理出来。如果你手边也有一块闲置的 ESP8266,可以参考这里的思路,少走一些弯路。

先让它能说话

选型:为什么是 MicroPython 而不是 Arduino

理由很简单:脚本修改后可以直接传到板子上,不用经过本地编译步骤。MicroPython 还提供 REPL,方便连接板子执行命令、查看变量和内存,或者临时修改引脚电平。

C 语言通常更省资源,但这次的目标是快速验证板子是否好用,MicroPython 更方便迭代。

烧固件:显式指定 Flash 参数

先探测芯片:

esptool --port COM10 --baud 115200 flash-id

输出:

Chip is ESP8266EX
Flash size: 4MB
MAC: ec:fa:bc:12:df:bd

确认芯片信息后,擦除 Flash 并烧写 MicroPython v1.29.0。镜像约 643 KB,首字节 0xE9 是有效的镜像标志。

这块板子的烧写命令显式指定了 Flash 模式、频率和容量:

esptool --port COM10 --baud 460800 write-flash \
    --flash-mode dout --flash-freq 40m --flash-size 4MB \
    0x0 fw/ESP8266_GENERIC-v1.29.0.bin

具体参数应与手头的芯片和 Flash 配置匹配,不能把这组值当成所有 ESP8266 开发板的通用配置。

烧完后 Hash 校验通过,看起来一切正常。然后就遇到了第一个问题。

坑 1:几秒内反复重启

打开串口后,看到的是乱码和不断重复的启动信息。抓取几秒日志,数出了 29 次启动,每次都类似:

ets Jan  8 2013,rst cause:2, boot mode:(3,7)
rf_cal[0] !=0x05,is 0x...

一开始我怀疑固件损坏、Flash 参数不匹配,甚至怀疑整片擦除影响了射频校准区。重刷两遍,症状依旧。

这次排查中,问题最终指向复位时序。NodeMCU 的 CP210x 串口芯片通过自动下载电路控制 GPIO0 和 EN 等引脚。最初的复位代码只保持了 0.15 秒:

s.setRTS(True)       # 拉低复位
time.sleep(0.15)
s.setRTS(False)      # 释放

rst cause:2 表示外部复位引脚触发,提示应该检查复位线路和控制时序。将保持时间改为 0.3 秒后,这块板子正常启动:

s.setRTS(True)
time.sleep(0.3)
s.setRTS(False)

串口终于输出:

MicroPython v1.29.0 on 2026-08-24; ESP module with ESP8266
>>>

经验:遇到反复重启和乱码时,可以先看启动日志中的复位原因,并检查 DTR、RTS 和供电,再结合现象排查固件与 Flash。复位时间应以具体板卡和工具的实际表现为准。

顺带一个坑:启动日志和应用输出的波特率不同

输出阶段 波特率 常见内容
上电或复位后的 ROM 启动阶段 74880 rst cause、boot mode、rf_cal
固件接管后的应用阶段 115200 MicroPython 启动信息和 print 输出

因此,用 115200 波特率打开串口时,复位开头出现一小段乱码是正常现象。我最初把它误认为烧写失败。

第一版脚本:让板子汇报状态

链路通了之后,先写一个自检脚本:

  • 扫描周边 WiFi,按信号强度排序,打印前 10 个。
  • 板载 LED,也就是 GPIO2,每轮闪烁 3 次。
  • 每 5 秒输出一行心跳,包含运行时长、空闲内存和 CPU 频率。

实测扫到了 24~26 个 AP,心跳日志如下:

[WIFI] found 24 AP(s)
[    0s] tick=1  mem_free=33312  freq=80MHz
[    5s] tick=2  mem_free=33312  freq=80MHz

一开始心跳周期实际上跑成了约 6 秒:循环中先花约 1 秒闪 LED,再休眠 5 秒,工作时间也被算进了周期。

改成按目标时间点对齐:

next_tick = time.ticks_add(time.ticks_ms(), 5000)

while True:
    # ...干活...
    now = time.ticks_ms()
    if time.ticks_diff(next_tick, now) > 0:
        time.sleep_ms(time.ticks_diff(next_tick, now))
    next_tick = time.ticks_add(next_tick, 5000)

修改后,心跳间隔稳定在 5 秒左右。如果工作耗时超过周期,还需要根据应用需求处理错过的时间点。

这一步验证了“写脚本、上传、运行、看日志、修改、再上传”的闭环,后续工作都建立在这个基础上。

第二版:把它变成网页

接下来要验证的是整条 TCP/IP 链路。能扫描到 WiFi,只能说明无线扫描功能正常,还不能证明应用层通信也正常。

目标是在浏览器里控制板载 LED,接口设计如下:

GET /                              控制页面
GET /api/led?state=on|off|toggle    控灯
GET /api/status                    JSON 状态

我用 socket 手写了一个极简 HTTP 服务端,没有引入框架:ESP8266 的可用内存有限,需要给业务代码留空间。

先在电脑上测试 HTTP 逻辑

每次在板子上调试,都要等待上传、重启和连接 WiFi,一轮约 30 秒。如果只是低级逻辑错误,这个等待会反复消耗时间。

于是我先写桩模块,在电脑上运行 HTTP 逻辑:用假的 machine、network、gc 顶替板上的模块,再把伪造的请求交给处理函数。

下面是测试思路的片段,省略了 FakeSock 初始化等已有代码:

class FakeSock:
    def recv(self, n):
        return self.rx[:n]  # 预置的请求字节

    def send(self, data):
        self.out += data

c = FakeSock(b"GET /api/led?state=on HTTP/1.1\r\nHost: x\r\n\r\n")
handle_sta(c, fake_sta, "1.2.3.4", "myssid")
assert c.out.startswith(b"HTTP/1.1 200 ")

测试中有 34 项断言,覆盖状态码、Content-Length 一致性、JSON 字段、LED 电平、404、204,以及空请求不导致崩溃等情况。

它还抓到了一个原本很难想到的问题。

坑 2:CSS 里的百分号导致首页报错

页面最初使用 Python 的 % 格式化。下面的写法已经将 CSS 百分号转义为 %%:

PAGE = """<style>.dot{border-radius:50%%}</style>...""" % {"host": HOSTNAME}

但真实代码里写的是 50%,后面紧跟 ;background。未转义的 % 被格式化操作当作占位符的开始,执行时报错:

not enough arguments for format string

结果是首页返回 500。排查时很容易盯着 socket、WiFi 或内存,却忽略 CSS 里的一个字符。

这次改用固定占位符替换,绕开了 % 格式化:

PAGE = PAGE.replace("{{HOST}}", config.HOSTNAME)

经验:在 Python 字符串中拼接 HTML、CSS 和 JavaScript 时,要留意模板语法与百分号、花括号的冲突。使用 % 或 .format() 时应正确转义;简单场景也可以用 str.replace() 替换约定好的占位符。

坑 3:MemoryError,ESP8266 上的内存瓶颈

功能加完后,代码增长到 19.3 KB。上传到板子,立刻报错:

MemoryError:

我先检查了 gc.mem_free(),怀疑存在内存泄漏,后来发现问题出在模块加载阶段。

这次运行环境中的堆约为 35 KB。导入 .py 模块时,MicroPython 需要在设备上解析并编译源码,这个过程会消耗额外内存。19.3 KB 的源码在加载和编译过程中耗尽了可用堆。

于是拆成 4 个模块:board.py 负责 LED,pages.py 放模板,web.py 负责 HTTP,main.py 作为入口。

重新上传,还是 MemoryError。单独的 pages.py 有 6.8 KB,导入时仍然失败。

这说明拆文件并不必然解决问题:单个模块的编译开销和当时剩余的可用内存同样重要。本次约 6~7 KB 的失败范围只是这套代码和运行状态下的观察值,不是 ESP8266 的通用文件大小上限。

预编译成 .mpy

MicroPython 的交叉编译器 mpy-cross 可以在电脑上将 .py 编译为 .mpy 字节码。板子加载字节码时不需要再进行源码编译,从而降低加载阶段的内存压力。

pip install mpy-cross
mpy-cross --version

本次使用的版本信息:

mpy-cross v1.29.0 / mpy v6.3

选择与固件兼容的 mpy-cross 和 .mpy 格式很重要;本次让编译器与固件都使用 v1.29.0。

部署脚本增加了 --all 流程:先编译全部 .mpy,再上传,同时删除板上同名的 .py 文件,避免加载时继续使用源码。

指标 修改前 修改后
源码体积 19.3 KB —
上传的 .mpy 体积 — 12.2 KB
启动情况 MemoryError 正常,空闲约 18.7 KB

三个需要结合真板验证的问题

CSS 格式化问题可以在电脑上通过测试发现。接下来几个问题则与 MicroPython 的实际 API、计时和真实网络行为有关,不能只依赖当前的 PC 桩测试。

坑 4:板上的 bytes 没有 partition()

解析 HTTP 请求时,需要按空行拆出头部和 body。在 CPython 中可以写:

head, _, body = data.partition(b"\r\n\r\n")

但这块板子的 MicroPython 固件报错:

AttributeError: 'bytes' object has no attribute 'partition'

改用 find() 和切片:

idx = data.find(b"\r\n\r\n")
head = data[:idx] if idx >= 0 else data
body = data[idx + 4:] if idx >= 0 else b""

这个问题是通过板上冒烟测试发现的:将测试脚本放到板子上,用伪 socket 给真实服务端代码提供请求。

mpremote connect COM10 run tools/onboard_smoke.py

这层测试运行的是真实 MicroPython 解释器和固件 API,只是不经过真实网络。PC 桩测试检查逻辑,板上冒烟测试检查固件 API 兼容性,两者各有作用。

坑 5:socket.send() 可能只发送一部分

板上冒烟测试和接口测试都通过了,浏览器打开页面时却只渲染了一半:

curl: (56) Recv failure: Connection reset by peer
# 只收到 947 字节,页面实际为 3779 字节

原因在于 socket 语义:send() 返回实际发送的字节数,不保证一次发送完所有数据。而代码发送后立刻调用 close(),剩余数据便没有发出去。

可以在固件支持时使用 sendall(),或者检查返回值并循环发送:

def send_all(cl, data):
    try:
        cl.sendall(data)
        return
    except AttributeError:
        pass

    n = 0
    total = len(data)
    while n < total:
        sent = cl.send(data[n:])
        if sent <= 0:
            raise OSError("socket connection closed during send")
        n += sent

具体还需要按 socket 的阻塞模式处理超时和异常。

当前桩测试中的 send() 每次都接收全部数据,因此没有模拟出短发送。真实网络测试暴露了这个问题,也提醒我们可以在桩测试中补充短发送场景。

坑 6:心跳漂移

前面已经修过心跳周期:循环里的工作时间叠加到固定休眠时间上,让 5 秒周期变成了约 6 秒。

这种“能跑但不准确”的小问题不一定会立刻造成故障,却可能在后续排查时误导判断。

第三版:让手机给它配网

前两版还有一个现实问题:WiFi 密码写死在代码里。换环境就要修改代码并重新上传。

于是改成 AP 配网:板子启动热点,手机连接后打开页面填写 WiFi 信息。

完整流程

  1. 板子启动后读取 wifi.json。
  2. 如果已有配置,尝试连接;连接不上时重试 2 次。
  3. 如果没有配置或连接失败,开启 nodemcu-setup 热点,地址为 192.168.4.1。
  4. 手机连接热点,在浏览器中打开 http://192.168.4.1。
  5. 页面扫描周边 WiFi,点击列表项自动填入 SSID,再填写密码并保存。
  6. 板子重启并连接路由器,配网热点关闭。
  7. 需要重新配网时,点击工作页面底部的“重新配网”,清除配置并返回热点配网流程。

密码中的特殊字符

密码可能包含 #、@、$ 或空格。表单使用 URL 编码提交时,服务端需要正确解码。这个固件环境没有直接使用 urllib.parse.unquote,因此实现了一个简单版本:

def unquote(s):
    """解码 x-www-form-urlencoded 中的百分号转义和加号。"""
    out = []
    i = 0
    n = len(s)

    while i < n:
        c = s[i]
        if c == "%" and i + 2 < n:
            try:
                out.append(chr(int(s[i + 1:i + 3], 16)))
                i += 3
                continue
            except ValueError:
                pass
        elif c == "+":
            out.append(" ")
            i += 1
            continue

        out.append(c)
        i += 1

    return "".join(out)

这个实现适合示例中的 ASCII 字符;如果 SSID 或密码包含非 ASCII 字符,还需要按表单编码处理字节并正确解码。

测试时应使用 test%40%23%24214,还原结果为 test@#$214。其中 $ 对应 %24。编码一旦处理错误,表面现象可能只是“密码错误、连不上”,很容易让人转而怀疑路由器、信道或天线。

那个“打不开网页”的乌龙

配网成功后,手机还在尝试访问板子的配网地址 192.168.4.1,浏览器显示:

无法访问此网站
192.168.4.1 拒绝了我们的连接请求。
ERR_CONNECTION_REFUSED

第一反应可能是 HTTP 服务挂了,但串口日志给出了另一条线索:

[MAIN] try 1/2  ssid=TEST
[WIFI] connected  ip=192.168.1.142  gw=192.168.1.1  rssi=-55 dBm  ch=1
[HTTP] ready ->  http://192.168.1.142/

板子已经连接路由器并进入工作模式。配网热点关闭后,服务地址也随之切换到路由器分配的新 IP,继续访问 192.168.4.1 自然不对。

看到 [HTTP] ready -> http://<IP>/ 后,应让手机或电脑连接到能够访问该 IP 的网络,再访问日志中显示的地址。日志表明服务已准备就绪,但实际访问是否成功仍要结合网络连通性验证。

最终从电脑使用 curl 验证:

首页        http=200  bytes=3779  耗时=0.15s
/api/status {"led":0,"uptime":75,"mem":19056,"rssi":-58,"ip":"192.168.1.142",...}
控灯        {"ok":true,"led":1}

顺带两个环境层面的坑

串口被占用。 抓日志时出现 PermissionError(13, '拒绝访问'),原因是串口调试助手还开着 COM10。关闭占用串口的程序后再连接。

电脑上的安全或 VPN 客户端。 排查时,任务列表中有 SangforPWEx.exe 和 SangforUDProtectEx.exe,对应 SSL VPN 和终端防护环境。此类软件的网络策略或路由配置可能影响内网设备访问。如果手机访问正常而电脑不行,可以检查电脑的路由、防火墙和客户端策略。

方法:三层测试各有分工

整个过程中最有价值的不只是代码,还有三层测试结构:

层级 工具 运行位置 主要检查内容 耗时
离线桩测试 tools/devtest_pc.py 电脑 业务逻辑、响应格式、边界条件 小于 1 秒
板上冒烟测试 tools/onboard_smoke.py 开发板 MicroPython API 差异、内存 约 5 秒
真实链路测试 curl / 浏览器 真实网络 socket 行为、大包传输、并发 手动

每一层发现的问题不同:

  • 离线桩测试发现 CSS 中的 % 与格式化冲突。
  • 板上冒烟测试发现 bytes.partition() 在当前固件中不可用。
  • 真实链路测试发现 send() 只发送了部分数据。

跳过板上冒烟测试,可能把 API 不兼容误当成网络故障;跳过真实链路测试,则可能直到演示时才发现页面传输不完整。

最终效果

最终,这块开发板运行 MicroPython v1.29.0,使用 5 个 Python 文件,编译后约 12.2 KB 字节码,在约 35 KB 的堆上运行一个手写 HTTP 服务端:

  • 手机连接热点配网,保存后自动重启入网。
  • 浏览器控制板载 LED,页面每 5 秒刷新状态。
  • /api/status 输出 JSON,可作为对接 Zabbix 或 Home Assistant 的数据接口,具体仍需按各自的接入方式配置。
  • WiFi 断开后,实测可在 5 秒内重连。
  • 页面提供重新配网入口。

NodeMCU 网页控制台:LED 控制与设备状态

本次测得的指标:

项目 数值
工作模式下的空闲内存 18.7 KB
首页传输 3779 字节,0.15 秒
连续 10 次 API 请求 全部返回 200
渲染配网页时的最低空闲内存 10.1 KB

最后一项值得留意:渲染配网页时只剩约 10.1 KB 空闲内存。如果继续增加多路继电器控制、数据图表或 OTA,就需要重新评估内存余量和页面体积。

附:7 个问题速查

问题 现象 本次排查结论 处理方式
复位异常 反复重启,出现 rst cause:2 复位控制时序存在问题 本次将脉冲保持时间由 0.15 秒改为 0.3 秒
启动乱码 串口开头出现一小段乱码 ROM 启动日志与应用输出的波特率不同 分别使用 74880 和 115200 查看
Flash 配置 烧写或启动异常 需要结合板卡检查 Flash 参数 本次显式指定 dout、40m、4MB
首页 500 串口出现格式化异常 CSS 的 % 与 Python % 格式化冲突 正确转义,或使用占位符和 replace()
MemoryError 导入模块时失败 源码编译阶段内存不足 使用兼容版本的 mpy-cross 预编译
bytes.partition() 不可用 板上出现 AttributeError 当前 MicroPython 固件未提供该方法 使用 find() 和切片
页面只返回一部分 curl 报错或页面渲染不完整 send() 发生短发送 使用 sendall() 或检查返回值后循环发送

本文数据、日志和报错来自一次硬件调试过程:硬件为 ESP8266EX、4 MB Flash 和 CP210x,固件为 MicroPython v1.29.0。




上一篇:AI+PyQt6开发串口上位机:嵌入式工程师实战指南
下一篇:ESP8266 MicroPython 实战:继电器、OTA 升级与 UDP 广播找 IP
您需要登录后才可以回帖 登录 | 立即注册

关闭

站长推荐上一条 /1 下一条

手机版|小黑屋|网站地图|云栈社区 ( 苏ICP备2022046150号-2 )

GMT+8, 2026-11-21 15:53 , Processed in 0.099944 second(s), 40 queries , Gzip On.

Powered by Discuz! X3.5

© 2025-2026 云栈社区.

快速回复 返回顶部 返回列表