Parts
- An ESP32 development board. (ESPHome's docs say the first install has to be over a USB cable, so you want a board with a USB port and a decent cable that carries data.)
- A BME280 breakout. The ESPHome page uses I2C with address 0x77 by default, and 0x76 if the breakout's address pin is set the other way. The docs also recommend pulling CSB to 3V in I2C mode to avoid communication errors.
- Four jumper wires: 3.3V, GND, SDA, SCL. Use 3.3V, not 5V, unless your breakout board says it handles it.
Most Home Assistant OS installs use the ESPHome Device Builder app. The command-line tool is the alternative, with identical YAML. In the Device Builder click Create device and follow the wizard (New Device Setup, board, Wi-Fi). It also generates an API encryption key for you.
Step 2: Wire it
I2C pins vary by board, so check your board's pinout. On many ESP32 dev boards the default I2C pins are GPIO21 (SDA) and GPIO22 (SCL), but confirm for yours. Keep the wires short and keep the sensor away from the ESP's heat. BME280 readings (especially humidity) are affected if it sits next to a warm board or regulator.
Step 3: Edit the YAML
Code: Select all
esphome:
name: lounge-climate
esp32:
board: esp32dev
framework:
type: esp-idf
logger:
api:
encryption:
key: !secret lounge_climate_api_key
ota:
- platform: esphome
password: !secret lounge_climate_ota_password
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
min_auth_mode: WPA2
ap:
ssid: "lounge-climate-fallback"
password: !secret lounge_climate_ap_password
i2c:
sda: GPIO21
scl: GPIO22
sensor:
- platform: bme280_i2c
address: 0x76
update_interval: 60s
temperature:
name: "Lounge temperature"
pressure:
name: "Lounge pressure"
humidity:
name: "Lounge humidity"
- Put the real values in secrets.yaml, never in a file you share. Use a unique key per device. The ESPHome security guide says the API key is a 32-byte base64 string, and a quick way to generate one on Linux or macOS is openssl rand -base64 32.
- Change address to 0x77 if your board uses the default. If the logs show "Communication with BME280 failed", re-check wiring, the address, and the CSB tip above.
- The security guide prefers OTA encryption over an OTA password where your version supports it. It says encryption reuses the API key, and describes the extra step needed on older firmware. I have used a password here because that is the documented fallback. Read the guide and pick the option for your version.
- The BME280 defaults to 16x oversampling and a 60 second update interval. The docs list options to change both.
- The fallback AP is optional. If you keep it, give it a password.
- First install: plug the board in over USB and use the Device Builder's Install option (browser serial or manual download, depending on your setup). The docs call this the fiddliest part. If it fails, check the cable and the troubleshooting guide.
- After that, updates are wireless (OTA).
- In Home Assistant, the new device appears under Settings > Devices & services as a Discovered ESPHome device. Enter the encryption key when asked.
- The three sensors appear as entities. Add them to a dashboard. If anything looks off, the Logs action on the device's card in the Device Builder shows the live device log.
- Reserve the device's IP in your router.
- If your IoT devices are on a VLAN, mDNS discovery will not cross it. ESPHome's guide suggests dual-homing the Home Assistant host, or using static IPs and adding the device by address.
- Do not enable the web server component unless you need it. If you do, set auth with a username and password, as the security guide says.
- Battery power: this config keeps Wi-Fi on all the time, which is not suitable for a battery without redesigning around deep sleep. Read the ESPHome deep sleep docs before attempting it.
Question for the group: what are you measuring with ESPHome (or other DIY Wi-Fi sensors) and which sensors have proven accurate? Anyone run battery nodes with deep sleep successfully?