https://github.com/claudiojara/esp32-esphome-lab
ESP32-C3 SuperMini + ESPHome + Home Assistant — OLED dashboards and HLK-LD2410C mmWave presence sensor
https://github.com/claudiojara/esp32-esphome-lab
esp32 esp32-c3 esphome home-assistant ld2410 mmwave-radar oled sh1106
Last synced: 24 days ago
JSON representation
ESP32-C3 SuperMini + ESPHome + Home Assistant — OLED dashboards and HLK-LD2410C mmWave presence sensor
- Host: GitHub
- URL: https://github.com/claudiojara/esp32-esphome-lab
- Owner: claudiojara
- License: mit
- Created: 2026-04-21T22:18:46.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-21T22:28:36.000Z (2 months ago)
- Last Synced: 2026-04-22T00:29:24.060Z (2 months ago)
- Topics: esp32, esp32-c3, esphome, home-assistant, ld2410, mmwave-radar, oled, sh1106
- Size: 925 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# esp32-esphome-lab
**ESP32-C3 SuperMini + ESPHome + Home Assistant** — OLED dashboards, mmWave presence, YAML-declarative firmware.
[](LICENSE)
[](https://esphome.io)
[](https://www.home-assistant.io)
[](https://www.espressif.com/en/products/socs/esp32-c3)
[](https://yaml.org)
---
## Stack Tecnológico
ESPHome
Firmware declarativo
Home Assistant
API nativa + mDNS
ESP32-C3
SuperMini RISC-V
Python + uv
ESPHome CLI toolchain
OLED SH1106
1.3" 128×64 I²C
HLK-LD2410C
24GHz mmWave UART
HAOS on Proxmox
VM sin acceso a USB
GitHub
Versioning + issues
---
## Features
- **LED control desde HA** como `light` entity
- **OLED dashboards**: cortina (`cover.curtain`), clima con ícono dinámico, info de sistema, avatar embebido
- **Multi-page rotation**: 5 páginas con auto-rotate (switch en HA) + botón físico (GPIO7) + botón virtual (HA)
- **mmWave presence detection**: LD2410C por UART a 256000 baud, con distancia móvil / quieta / de detección + energía
- **Reactive UI**: overlay de presencia en todas las páginas, avatar cambia de saludo cuando detecta a alguien
- **HA online images**: iconos de clima servidos desde `/config/www/weather/.png`
- **OTA nativo** post-primer-flash — ya no se vuelve a tocar el USB
---
## Quick Start
Prerequisites: Python 3.10+, [`uv`](https://github.com/astral-sh/uv).
```bash
# 1. Clonar
git clone https://github.com/claudiojara/esp32-esphome-lab.git
cd esp32-esphome-lab
# 2. Instalar ESPHome
uv tool install esphome
# 3. Copiar template de secretos y completar con tus credenciales
cp secrets.yaml.example secrets.yaml
$EDITOR secrets.yaml
# 4. Generar una API encryption key nueva por device
python3 -c "import secrets, base64; print(base64.b64encode(secrets.token_bytes(32)).decode())"
# Pégala en el api.encryption.key del YAML que vayas a flashear
# 5. Primer flash por USB (accede a la carpeta del proyecto que quieres flashear)
cd projects/esp32-test
ls /dev/cu.usbmodem*
esphome run esp32-test.yaml --device /dev/cu.usbmodem
# 6. Adoptar en HA: Settings -> Devices & Services -> ESPHome -> pegar la encryption key
# 7. A partir de ahora, OTA automático sin cable
esphome run esp32-test.yaml
```
> Cada subcarpeta de `projects/` tiene un symlink a `secrets.yaml` del root, así ESPHome encuentra los credenciales sin duplicarlos.
---
## Projects
Cada proyecto vive en su propia carpeta bajo [`projects/`](projects/) con su YAML, README y symlink a secrets. Detalle e índice completo en [`projects/README.md`](projects/README.md).
| Proyecto | Qué hace |
|----------|----------|
| [`projects/esp32-test`](projects/esp32-test/) | LED built-in como `light` HA vía GPIO8 active-low. Starting point minimal. |
| [`projects/esp32-test-interval`](projects/esp32-test-interval/) | Parpadeo standalone de 1s, sin `api`. Smoke test de hardware. |
| [`projects/esp32-test-oled-cover`](projects/esp32-test-oled-cover/) | OLED single-page mostrando `cover.curtain` position. |
| [`projects/esp32-test-oled-weather`](projects/esp32-test-oled-weather/) | OLED con reloj + ícono de clima dinámico fetchado de HA. |
| [`projects/esp32-test-oled-pages`](projects/esp32-test-oled-pages/) | **Proyecto principal.** Dashboard de 5 páginas con LD2410C integrado y UI reactiva. |
| [`projects/esp32-led-ring`](projects/esp32-led-ring/) | Anillo WS2812B 16 LEDs como `light.anillo` con 11 efectos para indicar eventos. |
| [`projects/mmwavetest`](projects/mmwavetest/) | LD2410C standalone sin display. |
| [`projects/mmwavetest-debug`](projects/mmwavetest-debug/) | Dump raw de bytes UART para diagnosticar cableado/baud. |
---
## Notas de hardware
### C3 SuperMini LED es active-low
`output.gpio.inverted: true` en GPIO8 o HA muestra el estado al revés.
### SH1106 1.3" clones necesitan `contrast: 100%` explícito
El default del driver ESPHome es 0 → pantalla completamente negra aunque I²C scan encuentre el device.
### 1.3" OLED es SH1106, NO SSD1306
Dos controladores distintos. Regla: **0.96" = SSD1306**, **1.3" = SH1106**. Driver equivocado = píxeles basura.
### LD2410C quiere 5V en VCC
Datasheet 5-12V. Con 3.3V puede bootear pero stream gibberish.
### First compile es lento
3-5 minutos la primera vez, <30s las siguientes (cache en `.esphome/`).
---
## Agent skill
La carpeta [`skill/`](skill/) contiene el espejo del agent skill global `esp32-homeassistant`. Cubre discovery → scaffolding → flashing, display integration patterns, mmWave debugging con firmas de bytes UART, y la tabla canónica de boards → LEDs → GPIOs. Ver [`skill/SKILL.md`](skill/SKILL.md).
---
## License
[MIT](LICENSE). Fork, break, learn.