前情提要
前几篇使用的是一块闲置的 NodeMCU,芯片为 ESP8266,配备 4MB Flash。到前一篇结束时,它已经能够完成以下功能:
- 自己开热点配网,并连接路由器
- 通过网页控制板载 LED 和 4 路继电器
- OTA 传输
.mpy 文件
- 开机通过 UDP 广播 IP
- 配套微信小程序
本来不打算继续折腾,但 AHT20 温湿度模块到货了,于是先在这块板子上接起来,给这个小项目补上环境数据采集功能。
AHT20 使用 I2C 接口,测量范围为温度 -40~85°C、湿度 0~100%RH,价格十元出头。常见的替代型号还有:
- SHT30:精度更好,价格也更高
- DHT11:单总线、价格低,但精度较差
选择 AHT20,主要是因为它支持 I2C,并且出厂已经完成校准,只需要连接四根线。
如果你正在系统学习单片机外设通信,I2C 是理解这类传感器驱动的基础。
先确认 NodeMCU 还剩哪些引脚
ESP8266 的 GPIO 不能凭印象选择。这块 NodeMCU 已经连接了串口、继电器、板载 LED 和 SPI Flash,需要先列出引脚占用情况。
| GPIO |
板上用途 |
能否用于 I2C |
| 0 |
空,D3,带内部上拉 |
可以 |
| 1 |
UART0 TX,COM10 日志口 |
不建议,会影响调试输出 |
| 2 |
板载 LED,低电平点亮 |
可以,但通信期间 LED 可能闪烁 |
| 3 |
UART0 RX |
不建议 |
| 4 |
继电器第 1 路,D2 |
不能 |
| 5 |
继电器第 2 路,D1 |
不能 |
| 6~11 |
SPI Flash |
不能,可能导致设备无法启动 |
| 12 |
继电器第 3 路 |
不能 |
| 13 |
空,丝印 MTCK |
可以 |
| 14 |
继电器第 4 路 |
不能 |
| 15 |
板载 10k 下拉电阻 |
不能作为 SCL,上升沿无法正常建立 |
| 16 |
RTC 域,没有内部上拉 |
有条件可用 |
容易踩坑的是,网上很多 NodeMCU I2C 教程默认使用:
SCL = D1 = GPIO5
SDA = D2 = GPIO4
但这块板子的 GPIO5 和 GPIO4 已经分别分配给继电器第 2 路和第 1 路。照抄教程接线,继电器会在接线后立即动作。
因此,第一版方案选择:
SCL = GPIO13
SDA = GPIO0
这两个引脚没有被继电器占用,其中 GPIO0 还带有内部上拉,GPIO13 也处于空闲状态。
不过,后续排查发现,SDA 实际插在了 GPIO16 上。这个问题先记下来,后面会看到如何定位。
ESP8266 没有硬件 I2C
这一点与 ESP32-C3 不同,并且会影响后面的所有调试过程。
ESP8266 芯片内部没有 I2C 外设,因此这块板子上不能使用 machine.I2C,只能使用:
machine.SoftI2C
它通过两个普通 GPIO,用软件模拟 I2C 时序。
这会带来三个直接影响。
1. 引脚选择更自由
由于没有固定的硬件 I2C 引脚,只要避开串口、SPI Flash 以及带特殊上下拉的引脚,普通 GPIO 都可以充当 SCL 或 SDA。
这也是为什么前面可以尝试将 I2C 改到 GPIO13 和 GPIO0。
2. 通信速率受 CPU 和中断影响
硬件 I2C 的时序由外设完成,软件 I2C 则依赖延时函数,例如 sleep_us。
当 WiFi 中断插入时,软件时序可能被拉长。因此,100kHz 不一定稳定,遇到通信失败时需要降低频率。
3. 上拉电阻必须真实存在
I2C 使用开漏结构,线路的高电平依赖上拉电阻。ESP8266 的内部上拉大约为 30~100kΩ,阻值偏大;在线路电容存在时,上升沿会变得很缓,使用 400kHz 时尤其容易读错。
AHT20 模块自带 4.7kΩ 上拉电阻,正好可以弥补这一缺陷。
这也解释了为什么同一份代码在 C3 上可以直接运行,移植到 ESP8266 后却需要重新调整参数:C3 具备硬件 I2C,而 ESP8266 只能使用软件模拟,两者的硬件结构不同。
驱动中的三个关键设计
sens.py 只有一百多行,但其中有三个决定是由实际硬件特性逼出来的。
读数缓存 3 秒
AHT20 每次测量都需要发送命令、等待约 80ms,再读取结果。网页每 5 秒请求一次 /api/status,如果每次请求都重新读取传感器,总响应时间会固定增加接近 100ms。
因此增加 3 秒缓存,让多个请求复用同一次测量结果:
CACHE_MS = 3000
if not force and _t is not None and time.ticks_diff(now, _last) < CACHE_MS:
return (_t, _h)
对于温湿度这类变化缓慢的物理量,3 秒内的变化通常小于传感器分辨率,缓存不会明显损失信息。
连续失败 5 次后停用传感器
传感器线松动或模块损坏时,readfrom 会抛出 OSError。如果每个请求都重新等待一次 80ms 超时,页面会出现明显卡顿,而且很难快速判断故障原因。
驱动连续失败 5 次后停用传感器:
except Exception as e:
_fail += 1
if _fail >= 5:
_ok = False
print("[SENS] lost after %d failures: %s" % (_fail, e))
停用后直接返回缓存值,网页保持响应,同时在串口留下故障日志。
传感器线松动、模块损坏时,故障处理通常还需要结合 传感器线 的供电、接触和上拉情况一起排查。
20 位数据的拆分
AHT20 返回 7 个字节,数据格式如下:
d[0] 状态字节,bit7 = busy
d[1] d[2] 湿度高 16 位
d[3] 的高 4 位 湿度低 4 位
d[3] 的低 4 位 温度高 4 位
d[4] d[5] 温度低 16 位
关键在于 d[3] 被湿度和温度共同使用:
- 高 4 位是湿度的最低 4 位
- 低 4 位是温度的最高 4 位
对应的拆分代码:
hr = ((d[1] << 16) | (d[2] << 8) | d[3]) >> 4
tr = ((d[3] & 0x0F) << 16) | (d[4] << 8) | d[5]
两个地方很容易写错:
- 湿度数据需要右移 4 位,否则结果会放大 16 倍
- 温度数据必须使用
d[3] & 0x0F,否则会把湿度的高 4 位误当成温度数据,最终得到几万摄氏度
换算公式如下:
t = tr * 200.0 / 1048576.0 - 50.0 # 200°C 量程,-50 偏移
h = hr * 100.0 / 1048576.0 # 0~100%RH
1048576 是 $2^{20}$。它作为除数时是正确的,但不能直接当成 20 位数据可以表示的最大值,后面的离线测试还会遇到这个边界问题。
第一次扫描:没有任何设备应答
固件烧录后第一次上电,串口输出:
[SENS] SCL=13 SDA=0 -> []
scan() 返回空列表,说明总线上没有设备应答。此时可能是引脚选错,也可能是接线问题,只能逐层排查。
第一轮:使用下拉检测是否接入模块
原本想给 SDA 配置内部下拉。如果模块已经接入,模块自带的上拉会把线路拉到高电平;如果没有接入,线路应该保持低电平。
但 ESP8266 不支持:
Pin.PULL_DOWN
ESP8266 只有内部上拉,没有内部下拉,这种检测方案无法使用。
第二轮:高阻输入检测外部上拉
接着改为输入模式读取电平。理论上,接入模块后,4.7kΩ 上拉会让线路读到 1;线路悬空时,电平应该不稳定。
实际结果是,除 GPIO15 读到 0 之外,其余引脚全部读到 1。原因在于 ESP8266 的 Pin.IN 默认带内部上拉,读到的高电平是芯片自己拉出来的,并不能证明外部接入了模块。
这个方法在 STM32 上可能有效,但在 ESP8266 上不适用。
第三轮:降低频率重新扫描
随后怀疑软件 I2C 时序过快,于是测试了 10kHz、50kHz 和 100kHz 三种速率,并组合四种引脚接法,一共 12 次扫描,结果仍然全部为空。
第四轮:手动 bit-bang
SoftI2C.scan() 只能告诉我们扫描成功或失败,却看不到中间的 ACK 电平。于是绕开它,使用最原始的手工时序逐位发送,每一步延时 100μs,约为 5kHz,并打印每个 ACK 位的实际电平。
[BB] 引脚 SCL=13 SDA=0 延时 100us
[BB] 1) 空转检查
[BB] SCL 输出低 -> SDA 读到 1 (两线没短路)
[BB] SDA 输出低 -> SCL 读到 1
[BB] 都释放后 SDA=1 SCL=1
[BB] 2) 逐个地址试 ACK
[BB] 0x38 -> ACK=1 无应答
[BB] 0x39 -> ACK=1 无应答
[BB] 0x44 -> ACK=1 无应答
[BB] 0x45 -> ACK=1 无应答
[BB] 0x3C -> ACK=1 无应答
[BB] 3) 对 0x38 发 AHT20 测量命令
[BB] ACK 链: 1 1 1 1
这三段输出分别说明:
- 引脚能够拉低和释放,两根线没有短路
- 在约 5kHz 下仍然没有地址应答,基本可以排除时序过快
- 对 0x38 发送完整命令时,四个字节都没有应答,因此不只是地址选择问题
此时,代码和时序基本可以排除,剩下最可能的原因就是:线没有接在以为的那两个引脚上。
不猜引脚:穷举 72 种组合
“可能接到了其他脚上”无法靠猜。排除串口 GPIO1、GPIO3 以及 SPI Flash GPIO6~11 后,可尝试的 GPIO 有 9 个:
(0, 2, 4, 5, 12, 13, 14, 15, 16)
SCL 和 SDA 各选一个不同的引脚,一共有 72 种组合。逐一扫描只需要十几秒。
PINS = (0, 2, 4, 5, 12, 13, 14, 15, 16)
for scl in PINS:
for sda in PINS:
if scl == sda:
continue
i2c = machine.SoftI2C(
scl=machine.Pin(scl),
sda=machine.Pin(sda),
freq=50000,
timeout=1000
)
found = i2c.scan()
扫描期间会把继电器占用的四个引脚也拉来拉去。如果接的是机械继电器,可能会听到轻微动作声,这是正常现象。
第一次扫描得到 9 个“命中”,但结果集中出现在 SDA=15 和 SDA=16 上。其中一条结果显示地址从 0x08 一直排列到 0x77,几乎一个不漏。
这并不是总线上挂了几十个设备,而是总线被拉低了。
I2C 主机每发送 8 位数据后,会释放 SDA,并在第 9 个时钟周期读取 ACK。如果 SDA 始终为 0,不管从设备是否存在,主机都会把它判断为“有设备应答”,于是每个地址都会被认为有效。
可以增加过滤条件:
if len(found) > 8:
# 一次扫出 8 个以上,是总线短地,不是设备
fake += 1
continue
重新运行后得到:
[ALL] pins = (0, 2, 4, 5, 12, 13, 14, 15, 16)
[ALL] HIT SCL=13 SDA=16 -> ['0x38'] (总 1 个地址)
[ALL] 试了 72 种组合,真命中 1 个,总线拉低的假象 8 个
[ALL] done
最终定位结果是:
SCL = GPIO13
SDA = GPIO16
设备地址 = 0x38
模块的 SDA 实际插在 GPIO16,也就是排针最后一格,而不是最初认为的 GPIO0。
为什么假象集中出现在 GPIO15 和 GPIO16 上,也可以解释:
- GPIO15 板上有 10kΩ 下拉,作为 SDA 时会被固定在低电平
- GPIO16 位于 RTC 域,没有内部上拉;如果没有外部上拉,也可能保持低电平
这两个引脚都会让总线表现出“似乎有设备应答”的假象。
同样的情况也会出现在 SDA 对地短路时。因此,“一次扫描返回超过 8 个地址”可以作为一个实用判据,快速判断总线被拉低,而不是逐个地址检查。
读到真实数据
换到实际引脚后,先单独读取几次:
AHT20 @ 0x38 calibration ok
26.86 °C 33.90 %RH
26.84 °C 33.86 %RH
26.86 °C 33.77 %RH
三次结果基本一致,湿度有小幅变化,说明传感器确实在完成测量转换,而不是返回固定值。
随后修改配置:
SENSOR_ENABLE = True
SENSOR_SCL = 13 # 丝印 GPIO13 MTCK
SENSOR_SDA = 16 # 丝印 GPIO16,排针最后一格
SENSOR_FREQ = 50000 # GPIO16 无内部上拉,50kHz 实测稳定
SENSOR_ADDR = 0 # 0 = 自动探测(0x38=AHT20,0x44=SHT3x)
重新部署后的串口输出:
[SENS] SCL=13 SDA=16 -> ['0x38']
[SENS] AHT20 at 0x38 ready
间隔 3.2 秒进行 8 次连续采样。由于间隔大于 3 秒缓存时间,每次都是真实读取:
| 次数 |
温度 |
湿度 |
响应时间 |
| 1 |
28.1°C |
31.3% |
151ms |
| 2 |
28.1°C |
31.2% |
239ms |
| 3 |
28.1°C |
31.1% |
165ms |
| 4 |
28.1°C |
31.0% |
204ms |
| 5 |
28.1°C |
30.9% |
150ms |
| 6 |
28.0°C |
31.0% |
135ms |
| 7 |
28.0°C |
30.9% |
161ms |
| 8 |
28.0°C |
30.9% |
145ms |
温度从 28.1°C 缓慢下降到 28.0°C,湿度从 31.3% 降到 30.9%,变化幅度处于传感器分辨率量级,符合室内环境的正常波动。
响应时间在 135~239ms 之间,其中约 80ms 是 AHT20 固有的转换时间,其余部分来自 HTTP 往返以及软件 I2C 逐位读取 7 个字节的开销。
这也是必须做缓存的原因:不缓存时,每次网页请求都要承担 130ms 以上的读取成本。
GPIO16 能用,但并不理想
GPIO16 在 ESP8266 上属于 RTC 域,有几个明确限制:
- 没有内部上拉
- 不支持中断
- 常见用途是 deep-sleep 唤醒,而不是普通 GPIO
当前配置能够工作,依靠的是 AHT20 模块自带的 4.7kΩ 上拉,同时将频率降低到了 50kHz。
因此,GPIO16 对布线比较敏感。线长超过 15cm,或者换成没有板载上拉电阻的传感器,通信可能再次失败。
更稳妥的方案是把 SDA 从排针最后一格挪到 GPIO0,也就是左侧第 12 格,然后在 config.py 中修改:
SENSOR_SDA = 0
其他配置不需要调整。现场已经可以稳定运行,因此这次没有更换,但 GPIO16 的上拉依赖属于已知隐患。
网页接口:没有传感器就返回 null
接口层将 sensor 字段设计为:
{
"led": 0,
"uptime": 600,
"mem": 8928,
"rssi": -57,
"ip": "192.168.151.67",
"ssid": "TEST",
"relay": [0, 0, 0, 0],
"sensor": null
}
接入传感器后:
{
"sensor": {
"kind": "AHT20",
"t": 27.9,
"h": 30.8
}
}
网页上的温湿度卡片初始隐藏,只有接口返回 sensor 对象后才显示。这样可以区分三种状态:
- 没有接入传感器:
null
- 已接入但读取失败:
null,同时保留串口日志
- 真实读数为 0:
0.0
如果统一使用 0,页面会显示“0°C、0%RH”,用户容易误以为设备发生故障,而实际情况可能只是没有接传感器。
内存:一个传感器功能占用约 3.5KB
ESP8266 的堆空间一直比较紧张,增加功能前必须先评估内存。
| 状态 |
free |
安装 sens 模块之前,开机后 |
15520 B |
| 安装之后,刚启动 |
12016 B |
| 同一块板子运行 10 分钟后 |
8928 B |
前两行相差约 3.5KB,主要来自 .mpy 代码、I2C 缓冲区和缓存变量。
第三行更值得注意:没有修改代码,只是运行了一段时间,free 就从 12016B 降到 8928B。ESP8266 的 WiFi 协议栈和 lwIP 会按需申请缓冲区,长时间运行还会产生堆碎片,因此 gc.mem_free() 返回的是瞬时值,不是固定容量。
编写代码时应该按运行过程中的最低值计算,而不是只看刚开机时的内存。
因为内存紧张,ESP8266 需要先将 .py 编译为 .mpy 再部署。.mpy 从 Flash 读取并执行,可以减少堆占用,但其格式版本必须与固件匹配。
本机原本没有安装 mpy-cross。安装时,清华镜像经系统代理访问一直返回 502,换成官方 PyPI 后下载成功:
pip install mpy-cross -i https://pypi.tuna.tsinghua.edu.cn/simple # 502
pip download mpy-cross # ok
最终使用的版本为:
1.29.0.post2
它与板上的 MicroPython 1.29.0 固件匹配。编译结果的头字节显示 ver=6,与板上原有 .mpy 文件一致。
部署时还遇到过以下日志:
could not enter raw repl
原因是开发板正在运行主循环,串口被占用,启动日志打断了上传。重新执行一次通常即可,不需要修改代码。
离线测试:不接硬件也能验证大部分逻辑
传感器只有一块,反复烧录和接线验证效率很低,因此先在 PC 上验证协议逻辑。
通过假的 I2C 对象注入 7 字节数据帧,然后运行:
tools/test_sens_pc.py
测试结果:
通过 24 项,失败 0 项
测试覆盖内容包括:
- 0°C/0%RH、-20°C、-40°C、45.5°C/99%RH、100%RH 等换算边界
- 校准命令
0xBE 0x08 0x00 的字节顺序
- 测量命令
0xAC 0x33 0x00 的字节顺序
- 3 秒内不重复访问 I2C 总线
- busy 位为 1 时不更新读数
- SHT30 分支的 CRC8 校验
- CRC 错误时丢弃脏数据
- 连续失败 5 次后自动停用
写测试桩时还遇到一个边界问题。
错误写法:
# 错误:把 2 的 20 次方当成满量程
hr = int(h / 100 * 1048576) & 0xFFFFF
100% 湿度按照这个公式计算会得到 1048576,但 20 位数据最大只能表示 1048575。经过 & 0xFFFFF 截断后,结果会变成 0,因此测试会报“100% 湿度读回 0”。
正确理解是:
- 驱动换算时使用
1048576 作为除数,这是 $2^{20}$,正确
- 生成测试数据时,最大可表示值应使用
1048575
- 不能把 $2^{20}$ 同时当作除数和 20 位数据最大值
改掉测试数据生成逻辑后,24 项测试全部通过。
项目结构
当前项目结构如下:
esp8266-nodemcu-demo/
├── src/
│ ├── config.py 引脚、传感器、OTA 白名单
│ ├── main.py GPIO → 传感器 → WiFi/AP → HTTP 主循环
│ ├── board.py 板载 LED
│ ├── gpio.py D0~D8 上电归低
│ ├── relay.py 四路继电器
│ ├── sens.py AHT20/SHT3x 自动探测、软 I2C、3 秒缓存
│ ├── pages.py 模板渲染与 form 解码
│ ├── web.py HTTP 服务、路由、OTA
│ └── sta.tpl / ap.tpl / ota.tpl / style.css
└── tools/
├── deploy.py 编译 .mpy 并上传
├── find_board.py 通过 UDP 查找开发板
├── probe_i2c_all.py 72 种引脚组合穷举
├── probe_i2c_bitbang.py 手工时序并打印每个 ACK
└── test_sens_pc.py 离线协议测试,24 项
新增接口:
| 用途 |
请求 |
| 获取设备状态和温湿度 |
GET /api/status,读取 sensor 字段 |
| 只读取温湿度 |
GET /api/sensor |
网页上的温湿度卡片位于 LED 卡片下方,使用两个 32px 数字显示:
27.9 °C
30.8 %RH
当前页面

页面中可以看到板载 LED、AHT20 温湿度、4 路继电器、运行时长、空闲内存、CPU 频率、WiFi 信息和固件版本。
这次遇到的 7 个坑
| # |
现象 |
真正原因 |
解法 |
| 1 |
按常见教程准备接 D1/D2 |
GPIO5/4 已分配给继电器第 1、2 路 |
接线前先确认引脚占用 |
| 2 |
Pin.PULL_DOWN 报错 |
ESP8266 只有内部上拉,没有内部下拉 |
依靠外部电路或其他方法判断 |
| 3 |
高阻输入判断外部上拉,全部读 1 |
Pin.IN 在 ESP8266 上默认带上拉 |
该测法在 ESP8266 上无效 |
| 4 |
扫描返回 0x08~0x77 全部地址 |
SDA 被拉在低电平,每个地址都被误判为 ACK |
一次扫出超过 8 个地址时判定为总线假象 |
| 5 |
SCL=13 SDA=0 一直扫不到 |
SDA 实际接在 GPIO16 |
穷举 72 种组合定位 |
| 6 |
100% 湿度测试读回 0 |
测试桩错误地使用 $2^{20}$ 作为 20 位最大值 |
数据生成使用 1048575,驱动除数仍使用 1048576 |
| 7 |
pip install mpy-cross 一直返回 502 |
镜像请求经过系统代理 |
更换下载源,最终使用 1.29.0.post2 |
前几篇中还讨论过复位时序、.mpy 版本号所在字节、frozen 模块覆盖、LED 极性以及请求没有到达开发板等问题,这里不再重复。
本文所有日志、读数和内存数据均来自以下实际环境:
Windows
CP210x @ COM10
MicroPython 1.29.0
NodeMCU ESP8266,4MB Flash
AHT20 @ I2C 0x38
SCL = GPIO13
SDA = GPIO16
I2C 频率 = 50kHz
相关阅读: