ESPHome architecture A: presets, CI, HA-first README - #3
Merged
Conversation
- Add MIT LICENSE (Copyright 2026 PixelTheater) - Add CHANGELOG.md with [Unreleased] and [0.1.0] sections - README: add YAML frontmatter, Release History section, MIT license link - README: replace fragile issues/new URL with stable wording - README: trim trailing whitespace - docs: rename media/Candle LEDs and Features.jpg to media/candle-leds-and-features.jpg - esphome: refresh secrets-example.yaml with rotation guidance - chore: ignore .pi/ audit scratch directory No source or firmware files were changed.
…pping Plan: start the housekeeping action plan with H3, H4, and H5. - Remove orphan esphome/espcandle.yaml (leftover from base/example refactor) - esphome/Makefile: pin default to esphome@2025.7.3 (real, tested release) - esphome/requirements.txt: tighten range to >=2025.7.0,<2026.0.0 - src/main.cpp: seed RNG in setup() with chip-unique entropy - src/main.cpp: gate [CANDLE] diagnostic log behind CANDLE_DEBUG_LOG macro - src/main.cpp: bounds-check setPWMBrightness() before indexing LED_PINS[] - src/cli.cpp: add dutyToFastLEDBrightness() helper to scale 0-4095 to 0-255 so FastLED.setBrightness() no longer wraps modulo 256 in CLI test paths - src/config.h: declare CANDLE_DEBUG_LOG (default 0) - CHANGELOG.md: log the new Unreleased changes - README.md: add version: 0.2.0-dev to frontmatter
Collapse the ESPHome build into one no-secret factory firmware where the per-device API encryption key is negotiated at runtime by Home Assistant (Noise PSK adoption, ESPHome >= 2025.10.0). - espcandle.base.yaml: api: ships with no baked-in key by default; min_version 2025.10.0; project_version 1.5.0 (single source). - espcandle.example.yaml: rewritten as a per-device named overlay, runtime PSK, no secrets, name_add_mac_suffix: false. - espcandle.factory.yaml (new): Device Builder import target; packages the base; holds dashboard_import (so dev builds do not advertise a key-stripping re-import). - espcandle.factory.factory.yaml (new): bench-flash binary; packages .factory.yaml + http_request OTA self-update. - manifest.json (new): skeleton, populated at release time. - secrets-example.yaml: repurposed for the dev-only static-key path. - Makefile + requirements.txt: pin esphome@2025.10.5, range >=2025.10.0,<2026.0.0; add factory/factory-run/factory-config targets. - .gitignore: allowlist the two factory YAMLs. No source/firmware C++ changes. See docs/adoption-strategy.md (next commit) for the full strategy and security model.
- docs/adoption-strategy.md (new): self-contained reference for the single-firmware runtime-PSK adoption path. Covers the four discovery paths (BLE Improv, USB-CDC improv_serial, mDNS, Device Builder Adopt), how runtime Noise PSK adoption works (cites upstream PRs by URL), the dev static-key path, the security model (open OTA, open AP, open web_server as recorded open questions), versioning, and open questions. - README.md: replace "Option 2: ESPHome Integration" body with "Onboarding (ESPHome)" covering end-user (BLE), end-user (web flasher), developer (build from repo), and how discovery works. Drop the stale "Web flasher (planned)" callout. Link the strategy doc. Option 1 (PlatformIO demo) and all other sections untouched. - CHANGELOG.md: new [Unreleased] entry for the adoption path; remove the three now-superseded standalone lines (Makefile pin, requirements range, secrets-example refresh) since the adoption entry covers them.
…ls, effect-cycling button Reduce the factory ESPHome config to a clean product surface while keeping modder features available as commented examples + docs. User-facing changes: - One visible HA light: "ESP Candle", a partition light joining the 20-LED RGB strip and the four PWM channels (warm white 1/2, UV, deep red) into a single logical light with curated effects Candle / Color / Magic (mirroring the standalone firmware mode names). - The five underlying channel lights are now internal: true (drive the hardware but not exposed to HA). - Boot button: short press cycles effects (globals counter + light.turn_on lambda, since light.effect.next needs ESPHome >= 2026.6.0 and this firmware pins 2025.10/2025.12); long press toggles the candle on/off. - Diagnostics report but are disabled_by_default to cut HA UI noise (internal temp, uptime, WiFi signal, IP/SSID/MAC, ESPHome version). Lean-down (commented as modder examples, see docs/modders.md): - web_server, i2c, extra GPIO 10/11/12 switches, SNTP + Last Restart template, WiFi Signal % copy sensor. Validated: esphome config passes on all four YAMLs; esphome compile succeeds for espcandle.factory.yaml (partition + single_light_id + globals lambda all build). Adds docs/modders.md (I2C, extra GPIO pin-safety, web server, direct per-channel control, static-key dev path).
…+ runbook
Three parts:
1. ESPHome bump to 2026.6.5 (requirements, Makefile, base min_version).
- Unblocks light.effect.next; simplify the boot button from a
globals-counter + light.turn_on lambda to a one-line
light.effect.next call.
- All four configs re-validated; factory binary compiles clean.
2. Custom effect engine (esphome/includes/candle_effects.h):
- Port the standalone firmware Candle/Color/Magic algorithms into
ESPHome addressable_lambda effects on the ESP Candle partition light.
- Candle: Perlin-noise flame (CALM/FLICKER/WIND submodes, W1/W2 drift,
snuff events, red ember inverse curve) driving the warm whites + red
via ledc set_level; RGB off.
- Color: HSV drift with speed random-walk + spatial history buffer +
blur on the RGB strip.
- Magic: drift/spark phases in purple/blue, UV on, red slow drift.
- Self-contained value-noise (no FastLED — esp32_rmt_led_strip is not
FastLED-backed). Tunables grouped per effect, mirroring src/config.h.
- Replaces the previous generic flicker/rainbow/twinkle stand-ins.
3. Testing:
- make smoke-test: validates all four YAMLs + compiles the factory
binary (no hardware). PR gate, ~90s warm.
- docs/testing.md: on-device runbook (first flash, provision/adopt,
effect checks, OTA, known 2026.6.x + esp32_rmt_led_strip boot-loop
risk #17060, future CI hook).
Auto mode is intentionally not ported: light.effect.next + the button
already give the user the same effect-cycling UX.
- Replaced partition light with RGB light + Preset select + White/Red/UV numbers - Boot short-press cycles presets; light toggle is master off; softer on without white flash - Tuned Warm Glow/Ember/Candle/Color/Magic; added Ember effect; safer on_turn_on StringRef handling - Project-local boards/espcandle.json and root Makefile smoke-test/factory-run wrappers - Docs and changelog updated for the new HA surface and power caps Co-authored-by: Cursor <cursoragent@cursor.com>
- New workflow runs make smoke-test and pio run -e esp32s3 on push/PR - Makefile prefers .venv esphome locally and falls back to PATH for CI - Docs/changelog note the CI gate Co-authored-by: Cursor <cursoragent@cursor.com>
…ness. - Added HA controls screenshot and made Home Assistant + ESPHome the primary section - Documented Made for ESPHome checklist (logos only after approval) - Added missing component ids so Take Control / extend works cleanly Co-authored-by: Cursor <cursoragent@cursor.com>
- Comment out http_request update on the factory flash image to stop boot 404s - Docs/README note that HA ESPHome OTA still works Co-authored-by: Cursor <cursoragent@cursor.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
make smoke-test+ PlatformIO demo build)boards/espcandle.json; HTTP self-update disabled until a real manifest/release existslight_restore_mode)Test plan
make smoke-testlocallypio run -e esp32s3locallyMade with Cursor