立创开源：基于ESP8266与BME680的HA智能环境光立方DIY全攻略
立创开源：基于ESP8266与BME680的HA智能环境光立方DIY全攻略
最近在捣鼓智能家居，想做一个既能监测室内环境，又能当氛围灯的小玩意儿。在网上找了一圈，发现立创开源社区的这个项目正合我意——一个基于ESP8266的可充电式智能设备，集成了BME680环境传感器和WS2812 RGB灯带，还能无缝接入Home Assistant。我自己跟着做了一遍，过程挺有意思，也踩了一些坑。今天我就把这个项目的完整DIY过程，从硬件焊接、软件配置到接入智能家居平台，手把手地分享给大家，希望能帮你少走弯路。
这个项目最终成品是一个“智能环境光立方”。它能实时监测你房间的温度、湿度、气压和空气质量（VOC），并通过多彩的LED灯珠显示出来，或者根据你的心情变换灯光效果。所有数据和控制都能在Home Assistant里看到和操作，非常方便。无论你是刚接触ESP8266的创客，还是想给家里添置一个自制智能设备的玩家，这篇教程都能带你一步步完成。
1. 硬件准备与焊接要点
工欲善其事，必先利其器。在开始写代码之前，咱们得先把硬件搞定。这个项目的硬件主要分为三块：主控板、铝基板灯面板和BME680传感器板。我会重点讲主控板上几个容易出问题的地方。
1.1 核心主控板焊接与调试
主控板是整个设备的大脑，集成了ESP8266主控、IP5306电源管理芯片等核心部件。焊接和调试这一步至关重要，特别是电源部分，搞不好会烧芯片或者无法工作。
首先，重中之重：先焊电源部分！
我强烈建议你拿到PCB后，先别急着焊ESP8266和其他芯片。第一步，应该用热风枪或者加热台，单独把IP5306-I2C电源管理芯片及其周边电路（电感、电容等）焊接好。
注意：这是一个非常重要的安全操作。原文作者特别强调，错误的IP5306-I2C寄存器配置可能导致后级MCU（也就是ESP8266）断电甚至损坏。所以，我们必须先确保电源部分工作正常，再焊接MCU。
电源部分调试步骤：
- 焊接与初步测试：焊好IP5306周边电路后，先别接电池。用万用表测量IP5306的5V输出引脚，以及后级降压芯片TLV62569输出的3.3V是否正常。只有这两个电压都对了，才能进行下一步。
- I2C调试IP5306：为了安全地配置IP5306，原文提供了一个巧妙的办法。BME680传感器也是通过I2C通信的，我们可以先不焊ESP8266，而是在BME680的预留焊盘上，外接一个I2C调试器（比如USB转I2C模块、或者另一块单片机）来读写IP5306的寄存器。这样即使配置出错，也不会影响到还没焊接的ESP8266。
- 关于电池电压测量：板子上用了ADS1115这个ADC芯片来测量电池电压。这里有个细节：ADS1115需要5V供电才能正常工作。为了实现电源隔离，设计上使用了ISO1541 I2C隔离芯片。如果你不需要测量电池电压，可以去掉这部分电路，直接给ADS1115供3.3V也行。
- 关键元器件选择：
- 电感：IP5306旁边的功率电感是关键。如果你需要自己更换，务必确保电感的额定电流大于4.5A。否则，当WS2812灯珠全亮高亮度时，电流很大，电感可能会啸叫、产生过大压降，甚至导致ESP8266死机重启。
- 自恢复保险丝：充电时，板子上最热的部分往往是自恢复保险丝。为了减少发热，尽量选择阻值偏小的型号。正常充电10分钟后，温度应该会稳定下来。
- TYPE-C旁的开关：这个开关连接着IP5306的按键检测脚和ESP8266的唤醒引脚，用于控制开关机，别忘了焊上。
- 固定孔：板上的固定孔默认规格可能不太好配铜柱，你可以将其更换为更常见的M3规格的孔。
1.2 灯面板与传感器板
铝基板灯面板：灯板用的是WS2812 RGB灯珠，焊接在铝基板上是为了更好的散热。但铝基板有个特性：它是导电的！所以，千万不要用普通的排针来连接铝基板和主控板，因为排针穿过铝基板上的孔时会直接导致短路。
正确的做法是使用“pogopin”（弹簧探针）来接触。如果你实在想用排针，那么灯板就不能用铝基板，得换成普通的双层FR4 PCB。
不过说实话，根据我的实测，WS2812灯珠在一般亮度下发热并不大，不用铝基板，用普通PCB也完全没问题，还能省去处理导电问题的麻烦。
BME680传感器板：这个小板子就是用来焊接BME680传感器的。打样制作时需要注意：
- 板材厚度：选择0.8mm。
- 工艺备注：一定要在订单备注里写上“【不做半孔工艺】”。
- DRC检查：下单时可以不检查DRC（设计规则检查），以加快进度。
2. 软件环境搭建与固件烧录
硬件准备妥当后，咱们就来搞定软件。这个项目使用ESPHome来配置和编译固件，它极大地简化了ESP8266/ESP32的开发流程，让你能用YAML配置文件来定义设备功能，无需编写大量C++代码。
2.1 安装ESPHome
ESPHome推荐通过Python的pip包管理器安装，这是最方便的方法。
- 确保你的电脑已经安装了Python（建议Python 3.7或以上版本）。
- 打开命令行终端（Windows上是CMD或PowerShell，Mac/Linux上是Terminal）。
- 输入以下命令安装ESPHome：
pip install esphome - 安装完成后，你可以通过运行
esphome --help来验证是否安装成功。
2.2 准备并编译固件
项目作者已经提供了写好的配置文件test1.yaml。你需要下载项目附件，找到这个文件。
- 在命令行中，切换到
test1.yaml文件所在的目录。 - 运行以下命令来编译并将固件烧录到设备：
esphome run test1.yaml - 首次运行会提示你选择操作，选择
upload（烧录）。ESPHome会自动下载编译工具链和库文件，这可能需要一些时间。
2.3 进入下载模式与烧录
ESP8266需要通过串口烧录程序，需要手动让它进入下载模式。
- 连接设备：用USB转TTL串口模块，将电脑和主控板上的串口引脚（TX, RX, GND）连接好，并给主控板供电（可以接上电池）。
- 进入下载模式：这是一个经典操作：
- 先按住主控板上的
REST（复位）键不放。 - 接着再按住
BOOT（或FLASH）键不放。 - 然后，松开
REST键。 - 最后，松开
BOOT键。 此时，ESP8266就进入了等待烧录的状态。
- 先按住主控板上的
- 开始烧录：在命令行中确认串口号（如COM3或/dev/ttyUSB0），ESPHome会自动检测并开始烧录。看到进度条走完，并提示成功即可。
3. 配置文件详解与关键代码
烧录的固件行为完全由test1.yaml配置文件决定。理解这个文件，你就能自定义设备的功能。我们来拆解其中最核心的几个部分。
3.1 网络连接与MQTT配置
设备需要联网并将数据上报给Home Assistant。这里使用了MQTT协议，它比ESPHome原生API更适合跨网络或复杂网络环境（比如设备在校园网，HA在公网）。
mqtt: broker: 172.18.81.102 # 你的MQTT服务器IP地址 port: 1883 # MQTT端口，默认是1883 username: user # MQTT用户名（如果服务器需要认证） password: ...123456 # MQTT密码你需要修改的地方：
broker：改成你部署的MQTT服务器的实际IP地址。如果Home Assistant和ESP8266在同一个局域网，可以填Home Assistant的IP。username和password：根据你的MQTT服务器设置来修改。
提示：如果你还没有MQTT服务器，可以在安装Home Assistant时一并安装Mosquitto MQTT broker插件，这样
broker就可以填Home Assistant的IP。
3.2 I2C总线与设备扫描
BME680传感器和IP5306（I2C版本）都是通过I2C总线与ESP8266通信的。配置I2C是让传感器工作的第一步。
i2c: sda: GPIO4 # I2C数据线连接的ESP8266引脚 scl: GPIO5 # I2C时钟线连接的ESP8266引脚 id: my_i2c_bus scan: True # 启用I2C设备扫描，调试时非常有用！sda和scl：这两个引脚号必须根据你实际的PCB布线来填写。示例中是GPIO4和GPIO5，请务必核对原理图。scan: True：这个功能太实用了。设备启动时，它会在日志中打印出所有挂在I2C总线上的设备地址。如果你发现BME680没数据，首先就来这里看看日志，确认ESP8266是否找到了设备（BME680的I2C地址通常是0x76或0x77）。
3.3 理解IP5306-I2C的寄存器配置（进阶）
在提供的C++代码注释中，详细列出了IP5306-I2C芯片的各个寄存器功能。这部分属于进阶内容，但了解它能帮你更好地控制电源管理，比如设置充电截止电压、配置按键行为等。
寄存器分类简介：
- 系统控制寄存器 (0x00, 0x01, 0x02)：控制芯片的全局功能，如开启/关闭升压输出、使能充电、配置按键长按时间、轻载自动关机时间等。
- 充电控制寄存器 (0x03-0x06)：精细管理充电过程，包括设置电池充满的电压、充电截止电流、恒流恒压充电参数等。修改这些寄存器需要格外小心，错误的电压/电流设置可能损坏电池。
- 状态读取寄存器 (0x07-0x0A)：用于读取芯片当前状态，比如是否在充电、电池是否已满、当前负载轻重、以及按键被按下的类型（短按、长按、双击）。
重要提醒：正如在硬件部分强调的，配置这些寄存器有风险。建议先通过外接I2C调试器，在MCU未上电的情况下进行读写测试，找到最优配置后，再将配置代码集成到固件中。不要直接在已焊接MCU的板子上盲目修改寄存器。
4. 接入Home Assistant与使用
设备烧录好固件并上电后，它就会自动连接你配置的Wi-Fi和MQTT服务器。接下来就是在Home Assistant中把它添加进来。
4.1 安装Home Assistant
如果你还没有Home Assistant，推荐使用Docker安装，这是最灵活方便的方式。
- 在你的服务器（可以是树莓派、NAS、或者一台常开机的电脑）上安装Docker。
- 运行一条Docker命令即可启动Home Assistant容器。具体命令可以在Home Assistant官网找到，它会自动下载镜像并运行。
- 启动后，通过浏览器访问你服务器的IP地址加上端口号
8123（例如http://192.168.1.100:8123），就能进入Home Assistant的初始化界面。
4.2 发现与配置设备
- MQTT集成：在Home Assistant的“配置” -> “集成”中，点击“添加集成”，搜索并添加“MQTT”。
- 配置MQTT连接：填写你在
test1.yaml中设置的MQTT服务器地址、端口、用户名和密码。保存后，Home Assistant就会连接到MQTT服务器。 - 自动发现：如果一切配置正确，ESPHome设备通常支持MQTT自动发现。稍等片刻，Home Assistant的仪表盘上应该就会自动出现一个新的设备，里面包含了ESP8266的所有传感器实体（温度、湿度、气压、VOC）和灯光实体。
- 创建仪表盘：你可以将这些实体添加到Home Assistant的概览页面上，创建卡片来显示环境数据，并添加一个灯光卡片来控制WS2812灯带的颜色、亮度、效果模式。
至此，你的智能环境光立方就全部制作完成了！它现在是一个独立的、可充电的智能设备，既能为你提供实时的环境监测数据，又能营造丰富的灯光氛围，所有控制尽在Home Assistant的掌握之中。你可以把它放在书桌、床头或者客厅，成为你智能家居生态中一个兼具实用性和趣味性的自制节点。如果在制作过程中遇到问题，不妨回头检查一下电源焊接、I2C连线以及配置文件中的IP地址和引脚号，这些都是最容易出错的环节。祝你制作成功，玩得开心！