Repti-Sense

A multi-point environment monitor for a lizard enclosure, built around an ESP32 running ESPHome.

The board reads from up to 5 I2C sensors/attachments, each connected through an I2C multiplexer so multiple points in the enclosure (e.g. basking spot, cool side, substrate, ambient) can be monitored from a single controller without I2C address collisions. Each attachment point is exposed via a JST-PH socket wired [G, V, SD, SC] — GND, VCC, SDA, SCL.

The schematic and board were designed in LibrePCB, and the first prototype has been assembled. The ESPHome configuration is written and compiles clean; next up is the first USB flash and hardware bring-up.

Hardware

The LibrePCB project lives in hardware/. Design summary (see hardware/ITERATION-NOTES.md for the full review and open questions):

• MCU: ESP32-C3-Zero (TENSTAR), reflow-mounted flat on the board. (The LibrePCB library/docs still mislabel it "ESP32-S3-Zero" — known doc bug, tracked in hardware/ITERATION-NOTES.md, not yet fixed.)
• I2C mux: Adafruit TCA9548A breakout at address 0x70 — fans the ESP32's I2C bus out to 5 independent channels, one per JST-PH port.
• Sensor ports: 5x JST-PH 4-pin (S4B-PH-K-S), wired [G, V, SD, SC], labeled TH0–TH4 in the schematic, one per mux channel. Sensors are Sensirion SHT40-family (I2C address 0x44).

Firmware

The ESPHome config lives in esphome/repti-sense.yaml; design rationale is in docs/superpowers/specs/2026-08-13-esphome-config-design.md. Copy esphome/secrets.yaml.example to esphome/secrets.yaml (gitignored) and fill in real values before flashing — in particular, the wifi_ssid/wifi_password placeholders must be replaced with your real network credentials.

All 5 sensor ports (TH0–TH4) are declared in the config even though only TH0/TH1 are physically populated — TH2/TH3/TH4 will report unavailable until sensors are soldered on. ESPHome doesn't hot-detect I2C devices — after adding a sensor to a previously-empty port (or reseating a connector), power-cycle or re-flash the board before expecting readings.

Status LED

The board's onboard WS2812 RGB LED (GPIO10) runs a repeating scanner: it flashes each sensor port's health (TH0→TH4, green=reporting/red=not) then the network state (blue=connected, amber=connecting, magenta=AP fallback), then pauses before repeating. Design rationale in docs/superpowers/specs/2026-08-16-status-led-design.md. Brightness is adjustable from Home Assistant via the "Status LED Brightness" number entity (defaults to 15%, dim by design since the board sits on a live enclosure).

Status

• Schematic + board designed (LibrePCB)
• First prototype board built — only TH0 (sensor 0) and TH1 (sensor 1) are populated; TH2–TH4 are unpopulated for now
• ESPHome configuration written
• First firmware upload
• Sensors verified on hardware (scoped to sensor 0 & 1 first)
• Onboard status LED scanner verified on hardware (colors correct, network states confirmed including AP fallback, brightness control confirmed) — a populated-port green flash is still unconfirmed since no TH sensor is physically wired up yet
• Enclosure bring-up / soak test

Steps to a working prototype

1. Capture the hardware contract — done: GPIO4/GPIO5 (SDA/SCL) confirmed against the physical board, TCA9548A at 0x70, ports TH0–TH4 mapped to mux channels 0–4.
2. Confirm ESPHome's TCA9548A support — done: native tca9548a: component, each channel becomes its own I2C bus.
3. Identify the sensors on TH0 and TH1 — done: Sensirion SHT40-family, sht4x ESPHome platform, address 0x44.
4. Scaffold the ESPHome project — done, see "Firmware" above.
5. Write the config — done: platform/network/I2C/mux/all 5 sensors, see esphome/repti-sense.yaml. Validated (esphome config) and compiled clean against ESPHome 2026.7.4.
6. Fill in real secrets and first-flash over USB. Copy esphome/secrets.yaml.example → esphome/secrets.yaml, fill in your real WiFi credentials, then esphome run esphome/repti-sense.yaml with the board connected via USB (OTA isn't available until it's proven it can join WiFi). Confirm clean boot and logs.
7. Confirm the I2C scan. Logs should show 0x70 (mux) and 0x44 on channels 0 & 1 (TH0/TH1). Expect sht4x setup failures logged for channels 2–4 — that's the unpopulated ports, not a bug.
8. Confirm sensor 0 (TH0) and sensor 1 (TH1) readings show up and look sane in Home Assistant (via the ESPHome integration).
9. Populate and bring up TH2–TH4 as they get sensors soldered on — power-cycle/re-flash after each addition (see "Firmware" above), then repeat the same per-port verification.
10. Enclosure bring-up test. Mount the board and sensors in the actual enclosure and soak-test for a period, watching for sane readings across the temperature/humidity gradient and basking area.
11. Iterate: alerting thresholds, dashboards/Home Assistant integration, and any firmware polish once the hardware path is proven.

Open questions

• None blocking firmware work — see hardware/ITERATION-NOTES.md for hardware-side open items (ESP32-S3/C3 doc mislabel, ERC/DRC not yet run).