1. Walk through the code¶

The firmware is one ESPHome file: firmware/lux.yaml. You describe the hardware and behaviour in YAML; ESPHome turns that into firmware.

You don't need to memorise the file. The point is to know which block to open when you want to change something.

How the pieces connect¶

flowchart LR
  S["sensor<br/>VEML7700"] -->|lux| A[api] -->|entities| HA[Home Assistant]
  S -->|lux| D[display]
  M[Mode select] -->|Off Schedule Night| LED[LED]
  HA -->|set mode and thresholds| M
  HA -->|on or off| LED
  W[wifi] -->|page when unprovisioned| D
  W -.- N[(NVS)]
  M -.- N

The display defaults to readings. The QR setup page appears only when no home Wi‑Fi is saved yet (first boot or after factory reset). A short drop keeps the readings page and switches the header to the disconnected Wi‑Fi glyph. The dotted lines are where the chip stores home Wi‑Fi and Mode / schedule / night settings (NVS), never this file.

Schedule and Night run on the device from those saved values. Schedule also needs a valid clock (SNTP when online).

The blocks¶

ESP32

substitutions esphome esp32 logger time
Home Assistant

api ota dashboard_import
Wi‑Fi setup

wifi captive_portal (+ Improv in YAML, not walked through)
Lux and LED

i2c sensor output light
Modes

select number script interval
Display

spi output light switch font qr_code display
Factory reset

button binary_sensor

Where to change things¶

If you want to change…	Open
Setup hotspot name or password	ESP32 → `substitutions`
Timezone for Schedule	ESP32 → `timezone`
How often lux is read	Lux and LED → `update_interval`
Default schedule or night thresholds	Modes → `datetime` / `number`
Screen colours, layout or text	Display → `pages`
Which pins are used	Lux and LED / Display (same pins as Wire)
Reset hold time	Factory reset → `binary_sensor`

Next: ESP32