一、项目概述
本项目用 M5AtomS3R 通过 I2C 读取 BH1750 数字光照传感器的照度值,做 5 点滑动平均滤波后,一路从串口输出,一路通过板载 WebServer 以网页形式展示,页面每秒刷新一次,数据逐条成行显示在页面右侧,支持清除与导出 Excel(CSV)。硬件连接:BH1750 模块的 VCC 接 3.3V,GND 与主控共地,SDA 接 GPIO2,SCL 接 GPIO1,ADDR 引脚悬空或接地。
二、BH1750 资料
2.1 器件特性
16 位数字环境光传感器,内置 ADC,输出为数字量,无需外部运放与标定电路。
光谱响应接近人眼,红外干扰较小,适合室内照度测量。
测量范围 1 ~ 65535 lx,高分辨率模式下最小分辨 0.5 lx(换算系数 1.2)。
供电 2.4 ~ 3.6 V,典型工作电流约 0.12 mA,支持掉电模式。
标准 I2C 接口,最高 400 kHz,7 位地址由 ADDR 引脚决定。
2.2 I2C 地址
ADDR 引脚接低电平或悬空时,器件 7 位地址为 0x23,这是模块的默认地址;ADDR 接高电平(VCC)时地址变为 0x5C,可在同一条 I2C 总线上挂多个器件时避免地址冲突。
本工程使用 0x23,若模块 ADDR 接高电平需改为 0x5C。
2.3 常用指令
常用的指令有以下几条:0x01 为上电(Power On);0x00 为掉电(Power Down);0x07 为复位数据寄存器;0x10 为连续测量高分辨率模式,约 120 ms 输出一次;0x11 为连续测量高分辨率模式 2,同样约 120 ms;0x13 为连续测量低分辨率模式,约 16 ms;0x20 为单次测量高分辨率模式,测量完成后自动掉电。
2.4 数据换算
高分辨率模式下,器件返回 16 位原始值(高字节在前),照度按经验系数换算:
lux = raw / 1.2
若原始值为 0xFFFF(65535),说明光照严重过曝,实际照度超过量程上限。
2.5 通信时序要点
主机写指令:START → 地址+W → 指令字节 → STOP。
主机读结果:发送测量指令后等待一次测量周期(高分辨率约 120 ms),再 START → 地址+R → 读 2 字节(ACK/NAK)→ STOP。
连续测量模式下指令只需发一次,之后按周期重复读取即可,本工程采用这种方式。
三、实现思路
整体分为四层,职责单一、互相解耦:
BH1750 硬件 │ I2C(GPIO2/GPIO1) 采集层 bh1750Init() / bh1750Read() // 只负责上电、读原始值并换算 │ 处理层 pushSample() / averageLux() // 5 点滑动窗口求平均,抑制抖动 │ 服务层 WebServer:GET / GET /data GET /reset + 串口打印 │ HTTP 展示层 webpage.h(HTML/CSS/JS):每秒 fetch 一次,逐行渲染
关键设计取向:
非阻塞轮询:不用 delay(1000) 读传感器,而是用 millis() 计时,主循环始终保持对 Web 请求和 OTA 的响应能力。
滤波放在设备端:先滤波再对外发布,网页、串口、导出数据口径一致,避免同一时刻三处数值不同。
前后端分离到文件:网页代码放在独立头文件,.ino 只保留设备逻辑,便于单独修改页面样式。
单页自适应:桌面端左右分栏(左侧信息、右侧数据),窄屏自动变为上下排列。
四、软件代码实现流程
4.1 文件结构
工程只有两个源文件:08webserverBH1750.ino 负责设备端逻辑,包括 WiFi 连接、I2C 采集、滑动滤波、HTTP 路由与串口输出;webpage.h 存放网页端代码,即 HTML、CSS 与 JavaScript,统一以 PROGMEM 常量 MAIN_page 保存。webpage.h 通过 #include "webpage.h" 引入,用 server.send_P() 直接从 Flash 发送,不占 RAM。
4.2 启动流程(setup)
Serial.begin(115200),初始化调试串口。
Wire.begin(I2C_SDA, I2C_SCL),即 GPIO2= SDA、GPIO1 = SCL。
bh1750Init():写 0x01 上电、写 0x10 进入连续高分辨率模式;返回非 0 表示无应答,串口提示“未检测到”。
WiFi.begin(ssid, password),连接失败 1 秒后 ESP.restart() 重试;成功后打印 SSID、RSSI、IP、掩码、网关,便于排查网段问题。
MDNS.begin("bh1750") + ArduinoOTA.setHostname("bh1750") + ArduinoOTA.begin(),支持 bh1750.local 和网络 OTA。
注册三条路由:/(页面、禁止缓存)、/data(JSON 数据)、/reset(清除滤波窗口)。
server.begin(),串口打印可访问地址。4.3 运行流程(loop)
ArduinoOTA.handle() 处理 OTA 请求。
server.handleClient() 处理 HTTP 请求。
传感器离线时每 5 秒尝试一次 bh1750Init() 重连。
每满 1000 ms:bh1750Read() → 成功则 pushSample() 入窗、averageLux() 求平均 → 串口打印“原始值 + 5 次平均”。
delay(2) 让出 CPU,避免看门狗和 WiFi 任务饥饿。4.4 核心代码逻辑
滑动滤波(环形缓冲,窗口长度 5):
// ---------------- 滑动滤波(最近 5 次采样取平均) ----------------
const uint8_t AVG_COUNT = 5;
float samples[AVG_COUNT];
uint8_t sampleNum = 0; // 当前窗口内有效样本数
uint8_t sampleIdx = 0;
// ---------------- BH1750 操作 ----------------
bool bh1750Init() {
Wire.beginTransmission(BH1750_ADDR);
Wire.write(BH1750_POWER_ON);
if (Wire.endTransmission() != 0) return false;
Wire.beginTransmission(BH1750_ADDR);
Wire.write(BH1750_CONT_H_RES);
return Wire.endTransmission() == 0;
}
float bh1750Read() {
if (Wire.requestFrom((uint8_t)BH1750_ADDR, (uint8_t)2) != 2) return -1.0f;
uint16_t raw = ((uint16_t)Wire.read() << 8) | Wire.read();
return raw / 1.2f; // 高分辨率模式下 1.2 lx / count
}
// 把新样本推入滑动窗口
void pushSample(float v) {
samples[sampleIdx] = v;
sampleIdx = (sampleIdx + 1) % AVG_COUNT;
if (sampleNum < AVG_COUNT) sampleNum++;
}
// 窗口内平均值
float averageLux() {
if (sampleNum == 0) return 0.0f;
float sum = 0;
for (uint8_t i = 0; i < sampleNum; i++) sum += samples[i];
return sum / sampleNum;
}
// 清除:重置滑动窗口与显示值
void resetFilter() {
sampleNum = 0;
sampleIdx = 0;
lux = 0.0f;
}设备刚上电或刚清除时 sampleNum < 5,此时按已有样本求平均,避免前几秒出现被 0 拉低的假值。
数据接口 /data 返回:
{"ok":true,"lux":53.2,"n":5,"time":"00:03:12"}ok:传感器是否正常读回数据(false 表示 I2C 无应答)
lux:5 点滑动平均后的照度
n:当前窗口内的样本数,页面据此判断是否可以出数
time:设备运行时间(时:分:秒)
/reset 将 sampleNum、sampleIdx、lux 归零,实现“清除后重新累计”。
4.5 网页端流程
页面加载后立即 poll(),随后 setInterval(poll, 1000) 每秒执行一次。
fetch('/data') 取 JSON:ok=true 且 n>0 时,生成一行 #序号 时间 xx.x lx 插到列表最上面,并更新计数与更新时间。
超过 300 行时移除最旧一行,防止长时间运行导致 DOM 膨胀卡顿。
“清除”按钮:清空本地记录与列表,同时请求 /reset 重置设备端滤波窗口。
“导出 Excel”按钮:把内存记录拼成带 UTF-8 BOM 的 CSV,通过 Blob + <a download> 保存到本地,Excel 双击即可按列打开。
五、项目功能
I2C 采光:通过 GPIO2/GPIO1 读取 BH1750,1 秒一次,使用 0x10 连续高分辨率模式。
滑动滤波:对最近 5 次采样取平均,明显抑制读数抖动。
串口输出:115200 波特率,每秒打印原始值与平均值,便于对照滤波效果。
网页实时显示:右侧逐行显示采集记录,最新一行在最上面并高亮,1 秒刷新一次。
清除:一键清空页面列表,并重置设备端的滤波窗口。
导出 Excel:前端把记录生成 CSV,Excel 可直接打开,文件名带时间戳。
状态指示:用三态圆点区分“正常”“未连接”“连接断开”,便于分辨传感器故障与网络故障。
掉线自恢复:传感器异常时每 5 秒重试;WiFi 连接失败则自动重启重连。
mDNS 与 OTA:支持 bh1750.local 访问与网络升级,无需反复插 USB。
资源占用(当前版本):Flash 约 30%,RAM 约 15%,页面 HTML 约 7.7 KB。


六、出现问题及解决办法
6.1 本机打不开 192.168.10.230,其他电脑却正常
现象:浏览器无法访问,但串口显示设备已联网。
排查:ipconfig 显示本机 IP 为 192.168.17.22/23,网关 192.168.16.1;route print 中没有 192.168.10.0/24 路由;ping 超时。
原因:电脑连的是 HTKY(192.168.16/17 网段),开发板连的是“航天科宇”(192.168.10 网段),两个网段互相隔离。
解决:电脑 WiFi 切换到与开发板相同的 SSID,IP 变为 192.168.10.194 后立即可以访问。
经验:先用 ping 验证连通性,再用 curl 验证 HTTP,最后才怀疑浏览器;排查顺序从物理层往上走最快。
6.2 bh1750.local 无法解析
原因:Windows 需要 mDNS/Bonjour 支持,本机未启用解析。
解决:直接用串口打印的 IP 访问;mDNS 作为可选入口保留。
6.3 烧录报 “Could not open COM15, the port is busy”
原因:Arduino IDE 的串口监视器进程 serial-monitor 独占串口。
解决:关闭 IDE 的串口监视器(或结束该进程)后重新烧录;烧录完成后按需重新打开监视器。
6.4 编译报 build.options.json: Access is denied
原因:Arduino IDE 与 arduino-cli 共用同一构建目录,IDE 持有该文件锁。
解决:命令行编译时指定独立构建目录:
arduino-cli compile --fqbn m5stack:esp32:m5stack_atoms3r --build-path "%TEMP%\bh1750_build" .
6.5 网页能打开但数据为空 / 显示旧界面
现象:设备 /data 有正常数值,页面却不刷新。
原因:浏览器缓存了旧版本页面,或被打开时正赶上烧录重启。
解决:服务端对 / 与 /data 增加响应头
Cache-Control: no-store, no-cache, must-revalidate, max-age=0
并配合 Ctrl+F5 强刷、关闭旧标签后重新打开新标签。
6.6 传感器读数异常 / 读不到
排查与解决:
先确认地址:ADDR 悬空为 0x23,接高电平为 0x5C。
确认 SDA/SCL 顺序:本板为 SDA=GPIO2、SCL=GPIO1,接反会一直无应答。
供电与共地:BH1750 模块与主控必须共地。
代码层面增加容错:bh1750Read() 返回负值即判定掉线,标记 sensorOK=false,每 5 秒重新初始化,恢复后自动继续采集。
6.7 串口中文乱码
现象:监视器中出现 ????。
原因:终端按 GBK 解码,而设备输出的是 UTF-8。
解决:把串口监视器编码设置为 UTF-8;数值本身不受影响。
七、调试感想
分层验证比反复重启有效。 打不开网页时,先 ping(三层通不通)、再 curl(四层/七层通不通)、最后才看浏览器。三步定位出问题在网段而不是代码,避免在 ESP32 上白折腾。
“能访问”和“能正确显示”是两件事。 页面打不开是网络问题,页面打开但没数据是缓存/接口/传感器问题,必须用状态文案把两类故障区分开,否则用户和开发者都会误判。
缓存是最容易被忽略的坑。 前端代码内嵌在固件里时,浏览器很容易继续用旧副本,服务端主动声明 no-store 比让用户手动清缓存可靠。
滤波参数要按场景取舍。 5 点滑动平均对室内慢变化足够,响应延迟约 2~3 秒;如果要做“开灯瞬间响应”的演示,可以缩短窗口或改用中值+均值组合。
非阻塞设计带来稳定性。 采样、HTTP、OTA 全部在同一个 loop() 里协作,用 millis() 计时而不是 delay(),页面连续轮询时也不会卡死(实测 20 次连续请求、6 个并发请求全部成功)。
工具链冲突要提前规避。 IDE 与命令行共用构建目录、串口被监视器占用,这两类问题与代码无关却最耗时,固定使用独立构建目录和“烧录前关监视器”的习惯能省很多时间。
八、后续可扩展方向
历史趋势曲线(前端 Canvas 绘制最近 N 次采样)。
数据断电保存(内部 Flash / LittleFS / SD 卡),配合 CSV 或真 .xlsx 导出。
增加光照阈值告警与继电器/灯光联动。
多传感器并挂同一 I2C 总线(利用 ADDR 切换地址)。
接入 MQTT 或 Home Assistant,实现远程监控。
我要赚赏金
