diff --git a/all_automations.json b/all_automations.json index eacff62c3d..26dc2b3ab6 100644 --- a/all_automations.json +++ b/all_automations.json @@ -136,6 +136,7 @@ "grove_tb6612fng.run", "grove_tb6612fng.standby", "grove_tb6612fng.stop", + "hc8.calibrate", "homeassistant.action", "homeassistant.event", "homeassistant.service", diff --git a/content/automations/all_actions.md b/content/automations/all_actions.md index 523d2fc5cc..bc9afd843e 100644 --- a/content/automations/all_actions.md +++ b/content/automations/all_actions.md @@ -31,6 +31,7 @@ title: "" - **fingerprint_grow:** `aura_led_control`, `cancel_enroll`, `delete`, `delete_all`, `enroll`, `led_control` - **globals:** `set` - **grove_tb6612fng:** `break`, `change_address`, `no_standby`, `run`, `standby`, `stop` +- **hc8:** `calibrate` - **homeassistant:** `event`, `service`, `tag_scanned` - **http_request:** `get`, `post`, `send` - **htu21d:** `set_heater`, `set_heater_level` diff --git a/content/changelog/2025.12.0.md b/content/changelog/2025.12.0.md new file mode 100644 index 0000000000..89e2c48391 --- /dev/null +++ b/content/changelog/2025.12.0.md @@ -0,0 +1,358 @@ +--- +description: "Changelog for ESPHome 2025.12.0." +title: "ESPHome 2025.12.0 - December 2025" +params: + seo: + description: Changelog for ESPHome 2025.12.0. + image: /changelog/images/changelog-2025.12.0.png +--- + +{{< imgtable >}} +"BM8563 RTC","components/time/bm8563","bm8563.svg","" +"CC1101","components/cc1101","cc1101.webp","" +"HC8","components/sensor/hc8","hc8.png","" +"HLW8032","components/sensor/hlw8032","hlw8032.png","" +"HUB75","components/display/hub75","hub75.svg","" +"STTS22H","components/sensor/stts22h","stts22h.jpg","" +"ThermoPro BLE","components/sensor/thermopro_ble","thermopro_tp357.jpg","" +"USB CDC-ACM","components/usb_cdc_acm","usb.svg","dark-invert" +{{< /imgtable >}} + +## Release Overview + + + +## Full list of changes + +### New Features + +- [nrf52] add settings for dcdc converter [esphome#11841](https://github.com/esphome/esphome/pull/11841) by [@tomaszduda23](https://github.com/tomaszduda23) (new-feature) +- [config] !extend / !remove support for LVGL-style configs [esphome#11534](https://github.com/esphome/esphome/pull/11534) by [@jpeletier](https://github.com/jpeletier) (new-feature) +- [stts22h] Add support for STTS22H temperature sensor [esphome#11778](https://github.com/esphome/esphome/pull/11778) by [@B48D81EFCC](https://github.com/B48D81EFCC) (new-component) (new-feature) (new-platform) +- [hc8] Add support for HC8 CO2 sensor [esphome#11872](https://github.com/esphome/esphome/pull/11872) by [@omartijn](https://github.com/omartijn) (new-component) (new-feature) (new-platform) +- [climate_ir] Add optional humidity sensor [esphome#9805](https://github.com/esphome/esphome/pull/9805) by [@damib](https://github.com/damib) (new-feature) +- [mcp3204] differential mode support [esphome#7436](https://github.com/esphome/esphome/pull/7436) by [@markodraca](https://github.com/markodraca) (new-feature) +- [bm8563] Add bm8563 component [esphome#11616](https://github.com/esphome/esphome/pull/11616) by [@abmantis](https://github.com/abmantis) (new-component) (new-feature) (new-platform) +- [mipi_dsi] add guition JC4880P443 display [esphome#12068](https://github.com/esphome/esphome/pull/12068) by [@23900](https://github.com/23900) (new-feature) +- [wifi] ap_active condition [esphome#11852](https://github.com/esphome/esphome/pull/11852) by [@AzonInc](https://github.com/AzonInc) (new-feature) +- [thermopro_ble] Add thermopro ble support [esphome#11835](https://github.com/esphome/esphome/pull/11835) by [@sittner](https://github.com/sittner) (new-component) (new-feature) (new-platform) +- [prometheus] Add event and text base components metrics [esphome#10240](https://github.com/esphome/esphome/pull/10240) by [@jzucker2](https://github.com/jzucker2) (new-feature) +- [api] Connected Condition - state_subscription_only flag [esphome#11906](https://github.com/esphome/esphome/pull/11906) by [@AzonInc](https://github.com/AzonInc) (new-feature) +- Add more lvgl arc update parameters [esphome#12066](https://github.com/esphome/esphome/pull/12066) by [@bdm310](https://github.com/bdm310) (new-feature) +- [lvgl] Add missing obj scroll properties [esphome#11901](https://github.com/esphome/esphome/pull/11901) by [@clydebarrow](https://github.com/clydebarrow) (new-feature) +- [lvgl] Automatically pad rows and columns [esphome#11879](https://github.com/esphome/esphome/pull/11879) by [@clydebarrow](https://github.com/clydebarrow) (new-feature) +- [lvgl] Add option to sync updates with display [esphome#11896](https://github.com/esphome/esphome/pull/11896) by [@clydebarrow](https://github.com/clydebarrow) (new-feature) +- [lvgl] Allow setting text directly on a button [esphome#11964](https://github.com/esphome/esphome/pull/11964) by [@clydebarrow](https://github.com/clydebarrow) (new-feature) +- [epaper_spi] Add SSD1677 and Waveshare 4.26 [esphome#11887](https://github.com/esphome/esphome/pull/11887) by [@clydebarrow](https://github.com/clydebarrow) (new-feature) +- [esp32] Improve IDF component support [esphome#12127](https://github.com/esphome/esphome/pull/12127) by [@swoboda1337](https://github.com/swoboda1337) (new-feature) +- [mipi_spi] add guition JC4827W543 C/R [esphome#12034](https://github.com/esphome/esphome/pull/12034) by [@jpeletier](https://github.com/jpeletier) (new-feature) +- Add MEASUREMENT_ANGLE to SensorStateClass [esphome#12085](https://github.com/esphome/esphome/pull/12085) by [@jakubcermak](https://github.com/jakubcermak) (new-feature) +- [psram] Add C5 support [esphome#12215](https://github.com/esphome/esphome/pull/12215) by [@swoboda1337](https://github.com/swoboda1337) (new-feature) +- [remote_transmitter, remote_receiver] Add RP2040 support [esphome#12048](https://github.com/esphome/esphome/pull/12048) by [@j-be](https://github.com/j-be) (new-feature) +- [esp32] Place FreeRTOS functions in flash by default (prep for IDF 6.0) [esphome#12182](https://github.com/esphome/esphome/pull/12182) by [@bdraco](https://github.com/bdraco) (new-feature) +- [esp32] Place ring buffer functions in flash by default (prep for IDF 6.0) [esphome#12184](https://github.com/esphome/esphome/pull/12184) by [@bdraco](https://github.com/bdraco) (new-feature) +- [gree] `turbo`, `light`, `health`, `xfan` switches for supported models [esphome#12160](https://github.com/esphome/esphome/pull/12160) by [@nagyrobi](https://github.com/nagyrobi) (new-feature) (new-platform) +- [cc1101] Add new cc1101 component [esphome#11849](https://github.com/esphome/esphome/pull/11849) by [@lygris](https://github.com/lygris) (new-component) (new-feature) +- [wifi, wifi_info] Add a WiFi power mode text sensor [esphome#11480](https://github.com/esphome/esphome/pull/11480) by [@kahrendt](https://github.com/kahrendt) (new-feature) +- [sps30] Add idle mode functionality [esphome#12255](https://github.com/esphome/esphome/pull/12255) by [@c0mputerguru](https://github.com/c0mputerguru) (new-feature) +- [hub75] HUB75 display component [esphome#11153](https://github.com/esphome/esphome/pull/11153) by [@stuartparmenter](https://github.com/stuartparmenter) (new-component) (new-feature) (new-platform) +- [mipi_spi] Add M5CORE2 model that extends the ILI9341 driver chip [esphome#12301](https://github.com/esphome/esphome/pull/12301) by [@lboue](https://github.com/lboue) (new-feature) +- [api] Device defined action responses [esphome#12136](https://github.com/esphome/esphome/pull/12136) by [@jesserockz](https://github.com/jesserockz) (new-feature) +- Add seeed_xiao_esp32c6 board definition [esphome#12307](https://github.com/esphome/esphome/pull/12307) by [@berikv](https://github.com/berikv) (new-feature) +- [hlw8032] Single-phase metering IC [esphome#7241](https://github.com/esphome/esphome/pull/7241) by [@rici4kubicek](https://github.com/rici4kubicek) (new-component) (new-feature) (new-platform) +- [usb_cdc_acm] New component [esphome#11687](https://github.com/esphome/esphome/pull/11687) by [@kbx81](https://github.com/kbx81) (new-component) (new-feature) +- [pca9685] Allow to disable the phase balancer for PCA9685 [esphome#9792](https://github.com/esphome/esphome/pull/9792) by [@jonau](https://github.com/jonau) (new-feature) +- [mipi_rgb] Add Waveshare 3.16 [esphome#12309](https://github.com/esphome/esphome/pull/12309) by [@clydebarrow](https://github.com/clydebarrow) (new-feature) +- [core] Packages refactor and conditional package inclusion (package refactor part 1) [esphome#11605](https://github.com/esphome/esphome/pull/11605) by [@jpeletier](https://github.com/jpeletier) (new-feature) + +### New Components + +- [stts22h] Add support for STTS22H temperature sensor [esphome#11778](https://github.com/esphome/esphome/pull/11778) by [@B48D81EFCC](https://github.com/B48D81EFCC) (new-component) (new-feature) (new-platform) +- [hc8] Add support for HC8 CO2 sensor [esphome#11872](https://github.com/esphome/esphome/pull/11872) by [@omartijn](https://github.com/omartijn) (new-component) (new-feature) (new-platform) +- [bm8563] Add bm8563 component [esphome#11616](https://github.com/esphome/esphome/pull/11616) by [@abmantis](https://github.com/abmantis) (new-component) (new-feature) (new-platform) +- [thermopro_ble] Add thermopro ble support [esphome#11835](https://github.com/esphome/esphome/pull/11835) by [@sittner](https://github.com/sittner) (new-component) (new-feature) (new-platform) +- [cc1101] Add new cc1101 component [esphome#11849](https://github.com/esphome/esphome/pull/11849) by [@lygris](https://github.com/lygris) (new-component) (new-feature) +- [hub75] HUB75 display component [esphome#11153](https://github.com/esphome/esphome/pull/11153) by [@stuartparmenter](https://github.com/stuartparmenter) (new-component) (new-feature) (new-platform) +- [hlw8032] Single-phase metering IC [esphome#7241](https://github.com/esphome/esphome/pull/7241) by [@rici4kubicek](https://github.com/rici4kubicek) (new-component) (new-feature) (new-platform) +- [usb_cdc_acm] New component [esphome#11687](https://github.com/esphome/esphome/pull/11687) by [@kbx81](https://github.com/kbx81) (new-component) (new-feature) + +### New Platforms + +- [stts22h] Add support for STTS22H temperature sensor [esphome#11778](https://github.com/esphome/esphome/pull/11778) by [@B48D81EFCC](https://github.com/B48D81EFCC) (new-component) (new-feature) (new-platform) +- [hc8] Add support for HC8 CO2 sensor [esphome#11872](https://github.com/esphome/esphome/pull/11872) by [@omartijn](https://github.com/omartijn) (new-component) (new-feature) (new-platform) +- [bm8563] Add bm8563 component [esphome#11616](https://github.com/esphome/esphome/pull/11616) by [@abmantis](https://github.com/abmantis) (new-component) (new-feature) (new-platform) +- [thermopro_ble] Add thermopro ble support [esphome#11835](https://github.com/esphome/esphome/pull/11835) by [@sittner](https://github.com/sittner) (new-component) (new-feature) (new-platform) +- [gree] `turbo`, `light`, `health`, `xfan` switches for supported models [esphome#12160](https://github.com/esphome/esphome/pull/12160) by [@nagyrobi](https://github.com/nagyrobi) (new-feature) (new-platform) +- [hub75] HUB75 display component [esphome#11153](https://github.com/esphome/esphome/pull/11153) by [@stuartparmenter](https://github.com/stuartparmenter) (new-component) (new-feature) (new-platform) +- [hlw8032] Single-phase metering IC [esphome#7241](https://github.com/esphome/esphome/pull/7241) by [@rici4kubicek](https://github.com/rici4kubicek) (new-component) (new-feature) (new-platform) + +### Breaking Changes + +- [core] Deprecate unsafe const char`*` APIs in mark_failed() and status_set_error(), add LogString`*` overloads [esphome#12021](https://github.com/esphome/esphome/pull/12021) by [@bdraco](https://github.com/bdraco) (breaking-change) +- [wifi_info] Use callbacks instead of polling [esphome#10748](https://github.com/esphome/esphome/pull/10748) by [@kbx81](https://github.com/kbx81) (breaking-change) +- [esp32_ble_client] Replace std::string with char[18] for BLE address storage [esphome#12070](https://github.com/esphome/esphome/pull/12070) by [@bdraco](https://github.com/bdraco) (breaking-change) +- [prometheus] Avoid generating unused light color metrics to reduce memory usage on ESP8266 [esphome#9530](https://github.com/esphome/esphome/pull/9530) by [@pgolawsk](https://github.com/pgolawsk) (breaking-change) +- [text_sensor] Avoid duplicate string storage when no filters configured [esphome#12205](https://github.com/esphome/esphome/pull/12205) by [@bdraco](https://github.com/bdraco) (breaking-change) +- [micronova] Set update_interval on entities instead on hub [esphome#12226](https://github.com/esphome/esphome/pull/12226) by [@edenhaus](https://github.com/edenhaus) (breaking-change) +- [micronova] Set the write bit automatically [esphome#12318](https://github.com/esphome/esphome/pull/12318) by [@edenhaus](https://github.com/edenhaus) (breaking-change) +- [i2c] Fix port logic with ESP-IDF [esphome#12063](https://github.com/esphome/esphome/pull/12063) by [@arno1801](https://github.com/arno1801) (breaking-change) +- [micronova] Remove MicroNovaFunctions [esphome#12363](https://github.com/esphome/esphome/pull/12363) by [@edenhaus](https://github.com/edenhaus) (breaking-change) +- [micronova] Require memory location and address for custom entities [esphome#12371](https://github.com/esphome/esphome/pull/12371) by [@edenhaus](https://github.com/edenhaus) (breaking-change) + +### All changes + +
+ + +- [wifi] Pass ManualIP by const reference to reduce stack usage [esphome#11858](https://github.com/esphome/esphome/pull/11858) by [@bdraco](https://github.com/bdraco) +- [esp32_ble] Use stack allocation for MAC formatting in dump_config [esphome#11860](https://github.com/esphome/esphome/pull/11860) by [@bdraco](https://github.com/bdraco) +- [wifi] Use stack allocation for BSSID formatting in logging [esphome#11859](https://github.com/esphome/esphome/pull/11859) by [@bdraco](https://github.com/bdraco) +- [nrf52] add settings for dcdc converter [esphome#11841](https://github.com/esphome/esphome/pull/11841) by [@tomaszduda23](https://github.com/tomaszduda23) (new-feature) +- [font] Store data in flash only [esphome#11926](https://github.com/esphome/esphome/pull/11926) by [@clydebarrow](https://github.com/clydebarrow) +- [binary_sensor] Modernize to C++17 nested namespaces and remove redundant qualifications [esphome#11929](https://github.com/esphome/esphome/pull/11929) by [@bdraco](https://github.com/bdraco) +- Add tests for sensor timeout filters [esphome#11923](https://github.com/esphome/esphome/pull/11923) by [@bdraco](https://github.com/bdraco) +- [lvgl] Migrate lv_font creation into Font class and optimize [esphome#11915](https://github.com/esphome/esphome/pull/11915) by [@clydebarrow](https://github.com/clydebarrow) +- [cover] Modernize to C++17 nested namespaces [esphome#11935](https://github.com/esphome/esphome/pull/11935) by [@bdraco](https://github.com/bdraco) +- [config] !extend / !remove support for LVGL-style configs [esphome#11534](https://github.com/esphome/esphome/pull/11534) by [@jpeletier](https://github.com/jpeletier) (new-feature) +- [number] Modernize to C++17 nested namespaces [esphome#11945](https://github.com/esphome/esphome/pull/11945) by [@bdraco](https://github.com/bdraco) +- [wifi] Skip redundant setter calls for default values [esphome#11943](https://github.com/esphome/esphome/pull/11943) by [@bdraco](https://github.com/bdraco) +- [dashboard_import] Store package import URL in .rodata instead of RAM [esphome#11951](https://github.com/esphome/esphome/pull/11951) by [@bdraco](https://github.com/bdraco) +- [ld24xx] Use stack allocation for MAC and version formatting [esphome#11961](https://github.com/esphome/esphome/pull/11961) by [@bdraco](https://github.com/bdraco) +- [bme68x] Print error when no sensors are configured [esphome#11976](https://github.com/esphome/esphome/pull/11976) by [@swoboda1337](https://github.com/swoboda1337) +- [wifi, captive_portal, web_server, wifi_info] Use stack allocation for MAC address formatting [esphome#11963](https://github.com/esphome/esphome/pull/11963) by [@bdraco](https://github.com/bdraco) +- [light] Modernize namespace declarations to C++17 syntax [esphome#11986](https://github.com/esphome/esphome/pull/11986) by [@bdraco](https://github.com/bdraco) +- [ld24xx] Modernize namespace declarations to C++17 syntax [esphome#11988](https://github.com/esphome/esphome/pull/11988) by [@bdraco](https://github.com/bdraco) +- [api] Fix format warnings in dump [esphome#11999](https://github.com/esphome/esphome/pull/11999) by [@swoboda1337](https://github.com/swoboda1337) +- [socket] Fix IPv6 address parsing for BSD sockets [esphome#11996](https://github.com/esphome/esphome/pull/11996) by [@dwmw2](https://github.com/dwmw2) +- [stts22h] Add support for STTS22H temperature sensor [esphome#11778](https://github.com/esphome/esphome/pull/11778) by [@B48D81EFCC](https://github.com/B48D81EFCC) (new-component) (new-feature) (new-platform) +- Document XFLIP handling in ST7701S [esphome#12014](https://github.com/esphome/esphome/pull/12014) by [@jpeletier](https://github.com/jpeletier) +- [select] Modernize namespace declarations to C++17 syntax [esphome#12007](https://github.com/esphome/esphome/pull/12007) by [@bdraco](https://github.com/bdraco) +- [mdns] Modernize to C++17 nested namespace syntax [esphome#11983](https://github.com/esphome/esphome/pull/11983) by [@bdraco](https://github.com/bdraco) +- [lock] Modernize to C++17 nested namespaces [esphome#11982](https://github.com/esphome/esphome/pull/11982) by [@bdraco](https://github.com/bdraco) +- [core] Document threading model rationale in ThreadModel enum [esphome#11979](https://github.com/esphome/esphome/pull/11979) by [@bdraco](https://github.com/bdraco) +- [nrf52,i2c] fix review comment [esphome#11931](https://github.com/esphome/esphome/pull/11931) by [@tomaszduda23](https://github.com/tomaszduda23) +- [core] Optimize DelayAction for no-argument case using if constexpr [esphome#11913](https://github.com/esphome/esphome/pull/11913) by [@bdraco](https://github.com/bdraco) +- [hc8] Add support for HC8 CO2 sensor [esphome#11872](https://github.com/esphome/esphome/pull/11872) by [@omartijn](https://github.com/omartijn) (new-component) (new-feature) (new-platform) +- [climate_ir] Add optional humidity sensor [esphome#9805](https://github.com/esphome/esphome/pull/9805) by [@damib](https://github.com/damib) (new-feature) +- [tests] Fix mipi_spi test board [esphome#12031](https://github.com/esphome/esphome/pull/12031) by [@ximex](https://github.com/ximex) +- [mcp3204] differential mode support [esphome#7436](https://github.com/esphome/esphome/pull/7436) by [@markodraca](https://github.com/markodraca) (new-feature) +- [bm8563] Add bm8563 component [esphome#11616](https://github.com/esphome/esphome/pull/11616) by [@abmantis](https://github.com/abmantis) (new-component) (new-feature) (new-platform) +- [api] Rename `USE_API_SERVICES` to `USE_API_USER_DEFINED_ACTIONS` [esphome#12029](https://github.com/esphome/esphome/pull/12029) by [@jesserockz](https://github.com/jesserockz) +- [core] Fix error on invalid id extend/remove [esphome#12064](https://github.com/esphome/esphome/pull/12064) by [@jpeletier](https://github.com/jpeletier) +- [ci] Fix filename [esphome#12065](https://github.com/esphome/esphome/pull/12065) by [@swoboda1337](https://github.com/swoboda1337) +- [ci] Fix test grouping [esphome#12067](https://github.com/esphome/esphome/pull/12067) by [@swoboda1337](https://github.com/swoboda1337) +- [mipi_dsi] add guition JC4880P443 display [esphome#12068](https://github.com/esphome/esphome/pull/12068) by [@23900](https://github.com/23900) (new-feature) +- [logger] Reduce UART overhead on ESP32/ESP8266 and fix buffer truncation [esphome#11927](https://github.com/esphome/esphome/pull/11927) by [@bdraco](https://github.com/bdraco) +- [api] Reduce heap allocations in DeviceInfoResponse [esphome#11952](https://github.com/esphome/esphome/pull/11952) by [@bdraco](https://github.com/bdraco) +- [web_server_base] Replace shared_ptr with unique_ptr for AsyncWebServer [esphome#11984](https://github.com/esphome/esphome/pull/11984) by [@bdraco](https://github.com/bdraco) +- [ethernet] Conditionally compile manual_ip to save 24 bytes RAM [esphome#11832](https://github.com/esphome/esphome/pull/11832) by [@bdraco](https://github.com/bdraco) +- [light] Dynamically disable loop when idle to reduce CPU overhead [esphome#11881](https://github.com/esphome/esphome/pull/11881) by [@bdraco](https://github.com/bdraco) +- [api] Use stack buffer for MAC address in Noise handshake [esphome#12072](https://github.com/esphome/esphome/pull/12072) by [@bdraco](https://github.com/bdraco) +- [wifi] ap_active condition [esphome#11852](https://github.com/esphome/esphome/pull/11852) by [@AzonInc](https://github.com/AzonInc) (new-feature) +- [esp32] Use the IDF I2C implementation on Arduino [esphome#12076](https://github.com/esphome/esphome/pull/12076) by [@swoboda1337](https://github.com/swoboda1337) +- [thermopro_ble] Add thermopro ble support [esphome#11835](https://github.com/esphome/esphome/pull/11835) by [@sittner](https://github.com/sittner) (new-component) (new-feature) (new-platform) +- [prometheus] Add event and text base components metrics [esphome#10240](https://github.com/esphome/esphome/pull/10240) by [@jzucker2](https://github.com/jzucker2) (new-feature) +- [api] Connected Condition - state_subscription_only flag [esphome#11906](https://github.com/esphome/esphome/pull/11906) by [@AzonInc](https://github.com/AzonInc) (new-feature) +- [api] Optimize APINoiseContext memory usage by removing shared_ptr overhead [esphome#11981](https://github.com/esphome/esphome/pull/11981) by [@bdraco](https://github.com/bdraco) +- [api] Remove redundant socket pointer from APIFrameHelper [esphome#11985](https://github.com/esphome/esphome/pull/11985) by [@bdraco](https://github.com/bdraco) +- [wifi] Add runtime power saving mode control [esphome#11478](https://github.com/esphome/esphome/pull/11478) by [@kahrendt](https://github.com/kahrendt) +- [logger] Eliminate strlen overhead on LibreTiny [esphome#11938](https://github.com/esphome/esphome/pull/11938) by [@bdraco](https://github.com/bdraco) +- [wifi] Use ESP-IDF IP formatting macros directly to eliminate heap allocations [esphome#12078](https://github.com/esphome/esphome/pull/12078) by [@bdraco](https://github.com/bdraco) +- [prometheus] Use current_option() instead of deprecated .state for select entities [esphome#12079](https://github.com/esphome/esphome/pull/12079) by [@bdraco](https://github.com/bdraco) +- [core] Deprecate unsafe const char`*` APIs in mark_failed() and status_set_error(), add LogString`*` overloads [esphome#12021](https://github.com/esphome/esphome/pull/12021) by [@bdraco](https://github.com/bdraco) (breaking-change) +- [bluetooth_proxy] Fix crash due to null pointer [esphome#12084](https://github.com/esphome/esphome/pull/12084) by [@kbx81](https://github.com/kbx81) +- [wifi_info] Use callbacks instead of polling [esphome#10748](https://github.com/esphome/esphome/pull/10748) by [@kbx81](https://github.com/kbx81) (breaking-change) +- [ble_client] Write static BLE data directly from flash without allocation [esphome#11826](https://github.com/esphome/esphome/pull/11826) by [@bdraco](https://github.com/bdraco) +- [template.alarm_control_panel] Replace std::map with FixedVector for heap and flash savings [esphome#11893](https://github.com/esphome/esphome/pull/11893) by [@bdraco](https://github.com/bdraco) +- Add more lvgl arc update parameters [esphome#12066](https://github.com/esphome/esphome/pull/12066) by [@bdm310](https://github.com/bdm310) (new-feature) +- [esp8266] Use C++17 nested namespaces and constexpr [esphome#12096](https://github.com/esphome/esphome/pull/12096) by [@bdraco](https://github.com/bdraco) +- [api] Use const char`*` pointers for light effects to eliminate heap allocations [esphome#12090](https://github.com/esphome/esphome/pull/12090) by [@bdraco](https://github.com/bdraco) +- [core] Reduce flash size by combining set_name() and set_object_id() calls [esphome#11941](https://github.com/esphome/esphome/pull/11941) by [@bdraco](https://github.com/bdraco) +- [web_server] Consolidate turn_on/turn_off handlers to eliminate duplicate lambdas [esphome#12094](https://github.com/esphome/esphome/pull/12094) by [@bdraco](https://github.com/bdraco) +- [esp32_ble] Optimize name storage to reduce RAM and eliminate heap allocations [esphome#12071](https://github.com/esphome/esphome/pull/12071) by [@bdraco](https://github.com/bdraco) +- [ltr390] Simplify mode tracking with bitmask instead of vector/function [esphome#12093](https://github.com/esphome/esphome/pull/12093) by [@bdraco](https://github.com/bdraco) +- [sht4x] Read and store a serial number of SHT4x sensors [esphome#12089](https://github.com/esphome/esphome/pull/12089) by [@namezys](https://github.com/namezys) +- Add developer-breaking-change labelling [esphome#12095](https://github.com/esphome/esphome/pull/12095) by [@jesserockz](https://github.com/jesserockz) +- [core] Replace seq<>/gens<> with std::index_sequence for code clarity [esphome#11921](https://github.com/esphome/esphome/pull/11921) by [@bdraco](https://github.com/bdraco) +- [core] Deduplicate identical stateless lambdas to reduce flash usage [esphome#11918](https://github.com/esphome/esphome/pull/11918) by [@bdraco](https://github.com/bdraco) +- [esp32_ble_client] Replace std::string with char[18] for BLE address storage [esphome#12070](https://github.com/esphome/esphome/pull/12070) by [@bdraco](https://github.com/bdraco) (breaking-change) +- [lvgl] Fix lambda return types for coord and font validators [esphome#12113](https://github.com/esphome/esphome/pull/12113) by [@bdraco](https://github.com/bdraco) +- [lvgl] Add missing obj scroll properties [esphome#11901](https://github.com/esphome/esphome/pull/11901) by [@clydebarrow](https://github.com/clydebarrow) (new-feature) +- [lvgl] Automatically pad rows and columns [esphome#11879](https://github.com/esphome/esphome/pull/11879) by [@clydebarrow](https://github.com/clydebarrow) (new-feature) +- Revert "[core] Deduplicate identical stateless lambdas to reduce flash usage" [esphome#12117](https://github.com/esphome/esphome/pull/12117) by [@bdraco](https://github.com/bdraco) +- [packages] Fix package schema validation [esphome#12116](https://github.com/esphome/esphome/pull/12116) by [@jpeletier](https://github.com/jpeletier) +- [prometheus] Avoid generating unused light color metrics to reduce memory usage on ESP8266 [esphome#9530](https://github.com/esphome/esphome/pull/9530) by [@pgolawsk](https://github.com/pgolawsk) (breaking-change) +- make thermostat humidification_action public [esphome#12132](https://github.com/esphome/esphome/pull/12132) by [@jonoberheide](https://github.com/jonoberheide) +- [core] Fix for missing arguments to shared_lambda [esphome#12115](https://github.com/esphome/esphome/pull/12115) by [@clydebarrow](https://github.com/clydebarrow) +- [lvgl] Add option to sync updates with display [esphome#11896](https://github.com/esphome/esphome/pull/11896) by [@clydebarrow](https://github.com/clydebarrow) (new-feature) +- [lvgl] Allow setting text directly on a button [esphome#11964](https://github.com/esphome/esphome/pull/11964) by [@clydebarrow](https://github.com/clydebarrow) (new-feature) +- [epaper_spi] Add SSD1677 and Waveshare 4.26 [esphome#11887](https://github.com/esphome/esphome/pull/11887) by [@clydebarrow](https://github.com/clydebarrow) (new-feature) +- [inkplate] Ignore strapping pin warnings on default pins [esphome#12110](https://github.com/esphome/esphome/pull/12110) by [@jesserockz](https://github.com/jesserockz) +- [esp32] Improve IDF component support [esphome#12127](https://github.com/esphome/esphome/pull/12127) by [@swoboda1337](https://github.com/swoboda1337) (new-feature) +- [logger] Replace std::function callbacks with LogListener interface [esphome#12153](https://github.com/esphome/esphome/pull/12153) by [@bdraco](https://github.com/bdraco) +- [light] Replace sparse enum switch with linear search to save 156 bytes RAM [esphome#12140](https://github.com/esphome/esphome/pull/12140) by [@bdraco](https://github.com/bdraco) +- [wifi] Save 112 bytes BSS on ESP8266 by calling SDK directly for BSSID [esphome#12137](https://github.com/esphome/esphome/pull/12137) by [@bdraco](https://github.com/bdraco) +- [esp32_ble_tracker] Replace scanner state callback with listener interface [esphome#12156](https://github.com/esphome/esphome/pull/12156) by [@bdraco](https://github.com/bdraco) +- [wifi] Replace std::function callbacks with listener interfaces [esphome#12155](https://github.com/esphome/esphome/pull/12155) by [@bdraco](https://github.com/bdraco) +- [api] Eliminate rx_buf heap churn and release buffers after initial sync [esphome#12133](https://github.com/esphome/esphome/pull/12133) by [@bdraco](https://github.com/bdraco) +- [tests] Remote packages with substitutions [esphome#12145](https://github.com/esphome/esphome/pull/12145) by [@jpeletier](https://github.com/jpeletier) +- [packages] Restore remote shorthand vars and !remove in early package contents validation [esphome#12158](https://github.com/esphome/esphome/pull/12158) by [@jpeletier](https://github.com/jpeletier) +- [sensor] Replace timeout filter scheduler with loop-based implementation [esphome#11922](https://github.com/esphome/esphome/pull/11922) by [@bdraco](https://github.com/bdraco) +- [logger] Conditionally compile log level change listener [esphome#12168](https://github.com/esphome/esphome/pull/12168) by [@bdraco](https://github.com/bdraco) +- [ble_client] Convert to C++17 namespace style [esphome#12176](https://github.com/esphome/esphome/pull/12176) by [@bdraco](https://github.com/bdraco) +- [number] Reduce NumberCall size by 4 bytes on 32-bit platforms [esphome#12178](https://github.com/esphome/esphome/pull/12178) by [@bdraco](https://github.com/bdraco) +- [light] Store log_percent parameter strings in flash on ESP8266 [esphome#12174](https://github.com/esphome/esphome/pull/12174) by [@bdraco](https://github.com/bdraco) +- [mipi_spi] add guition JC4827W543 C/R [esphome#12034](https://github.com/esphome/esphome/pull/12034) by [@jpeletier](https://github.com/jpeletier) (new-feature) +- Add MEASUREMENT_ANGLE to SensorStateClass [esphome#12085](https://github.com/esphome/esphome/pull/12085) by [@jakubcermak](https://github.com/jakubcermak) (new-feature) +- [ade7953_base] Add missing CODEOWNERS [esphome#12181](https://github.com/esphome/esphome/pull/12181) by [@dlitz](https://github.com/dlitz) +- [climate] Use C++17 nested namespace syntax [esphome#12194](https://github.com/esphome/esphome/pull/12194) by [@bdraco](https://github.com/bdraco) +- [esp32_can] Add P4 support [esphome#12201](https://github.com/esphome/esphome/pull/12201) by [@swoboda1337](https://github.com/swoboda1337) +- [openthread] Add C5 support [esphome#12200](https://github.com/esphome/esphome/pull/12200) by [@swoboda1337](https://github.com/swoboda1337) +- [mdns] Bump mDNS component to 1.9.1 [esphome#12207](https://github.com/esphome/esphome/pull/12207) by [@HeMan](https://github.com/HeMan) +- [lock] Refactor trigger classes to template and add integration tests [esphome#12193](https://github.com/esphome/esphome/pull/12193) by [@bdraco](https://github.com/bdraco) +- [web_server] Replace routing table with if-else chain to save 116 bytes RAM [esphome#12139](https://github.com/esphome/esphome/pull/12139) by [@bdraco](https://github.com/bdraco) +- [psram] Add C5 support [esphome#12215](https://github.com/esphome/esphome/pull/12215) by [@swoboda1337](https://github.com/swoboda1337) (new-feature) +- [uart] Add `wake_loop_on_rx` flag for low latency processing [esphome#12172](https://github.com/esphome/esphome/pull/12172) by [@kbx81](https://github.com/kbx81) +- [wifi_info] Fix compilation error when using only mac_address sensor, add tests [esphome#12222](https://github.com/esphome/esphome/pull/12222) by [@kbx81](https://github.com/kbx81) +- [uart] Convert to C++17 namespace style [esphome#12220](https://github.com/esphome/esphome/pull/12220) by [@kbx81](https://github.com/kbx81) +- [core] Fix status_momentary API misuse and optimize parameter type [esphome#12216](https://github.com/esphome/esphome/pull/12216) by [@bdraco](https://github.com/bdraco) +- [micronova] Convert to C++17 namespace style [esphome#12229](https://github.com/esphome/esphome/pull/12229) by [@edenhaus](https://github.com/edenhaus) +- [remote_transmitter, remote_receiver] Add RP2040 support [esphome#12048](https://github.com/esphome/esphome/pull/12048) by [@j-be](https://github.com/j-be) (new-feature) +- [uart] Automatically enable the socket wake infrastructure when RX wake requested [esphome#12221](https://github.com/esphome/esphome/pull/12221) by [@kbx81](https://github.com/kbx81) +- [zwave_proxy] Use new socket wake infrastructure to reduce latency, convert to C++17 namespace style [esphome#12135](https://github.com/esphome/esphome/pull/12135) by [@kbx81](https://github.com/kbx81) +- [helpers] Fix unit tests following #12135 [esphome#12237](https://github.com/esphome/esphome/pull/12237) by [@kbx81](https://github.com/kbx81) +- [datetime] Convert to C++17 nested namespace style [esphome#12235](https://github.com/esphome/esphome/pull/12235) by [@bdraco](https://github.com/bdraco) +- [button] Convert to C++17 nested namespace style [esphome#12233](https://github.com/esphome/esphome/pull/12233) by [@bdraco](https://github.com/bdraco) +- [mqtt] Enable support for the RTL87XX platform [esphome#7697](https://github.com/esphome/esphome/pull/7697) by [@popovec](https://github.com/popovec) +- [esp8266] Allow IN&OUT pin config for ESP8266 [esphome#12238](https://github.com/esphome/esphome/pull/12238) by [@DjordjeMandic](https://github.com/DjordjeMandic) +- [esp32] Place FreeRTOS functions in flash by default (prep for IDF 6.0) [esphome#12182](https://github.com/esphome/esphome/pull/12182) by [@bdraco](https://github.com/bdraco) (new-feature) +- [cover] Store cover state strings in flash on ESP8266 [esphome#12196](https://github.com/esphome/esphome/pull/12196) by [@bdraco](https://github.com/bdraco) +- [ota] Use ESP-IDF OTA backend for all ESP32 builds [esphome#12244](https://github.com/esphome/esphome/pull/12244) by [@swoboda1337](https://github.com/swoboda1337) +- [esp32] Place ring buffer functions in flash by default (prep for IDF 6.0) [esphome#12184](https://github.com/esphome/esphome/pull/12184) by [@bdraco](https://github.com/bdraco) (new-feature) +- [text_sensor] Avoid duplicate string storage when no filters configured [esphome#12205](https://github.com/esphome/esphome/pull/12205) by [@bdraco](https://github.com/bdraco) (breaking-change) +- [core] Filter noisy platformio log messages [esphome#12218](https://github.com/esphome/esphome/pull/12218) by [@swoboda1337](https://github.com/swoboda1337) +- [lock] Store lock state strings in flash on ESP8266 [esphome#12163](https://github.com/esphome/esphome/pull/12163) by [@bdraco](https://github.com/bdraco) +- [esp32_camera] Replace std::function callbacks with CameraListener interface [esphome#12165](https://github.com/esphome/esphome/pull/12165) by [@bdraco](https://github.com/bdraco) +- [light] Use listener pattern for state callbacks with lazy allocation [esphome#12166](https://github.com/esphome/esphome/pull/12166) by [@bdraco](https://github.com/bdraco) +- [core] Add RAM strings and symbols analysis to analyze-memory command [esphome#12161](https://github.com/esphome/esphome/pull/12161) by [@bdraco](https://github.com/bdraco) +- [web_server] Store update state strings in flash on ESP8266 [esphome#12204](https://github.com/esphome/esphome/pull/12204) by [@bdraco](https://github.com/bdraco) +- [valve] Store valve state strings in flash on ESP8266 [esphome#12202](https://github.com/esphome/esphome/pull/12202) by [@bdraco](https://github.com/bdraco) +- [web_server_idf] Fix SSE multi-line message formatting [esphome#12247](https://github.com/esphome/esphome/pull/12247) by [@bdraco](https://github.com/bdraco) +- [text_sensor] Add deprecation warning for raw_state member access [esphome#12246](https://github.com/esphome/esphome/pull/12246) by [@bdraco](https://github.com/bdraco) +- [wifi] Fix ap_active condition [esphome#12227](https://github.com/esphome/esphome/pull/12227) by [@AzonInc](https://github.com/AzonInc) +- [core] Add PROGMEM macros and move web_server JSON keys to flash [esphome#12214](https://github.com/esphome/esphome/pull/12214) by [@bdraco](https://github.com/bdraco) +- [tests] Allow substitution tests to run independently for debugging [esphome#12224](https://github.com/esphome/esphome/pull/12224) by [@jpeletier](https://github.com/jpeletier) +- [gree] `turbo`, `light`, `health`, `xfan` switches for supported models [esphome#12160](https://github.com/esphome/esphome/pull/12160) by [@nagyrobi](https://github.com/nagyrobi) (new-feature) (new-platform) +- [cc1101] Add new cc1101 component [esphome#11849](https://github.com/esphome/esphome/pull/11849) by [@lygris](https://github.com/lygris) (new-component) (new-feature) +- [text_sensor] Fix spurious raw_state deprecation warnings [esphome#12262](https://github.com/esphome/esphome/pull/12262) by [@bdraco](https://github.com/bdraco) +- [tests] Add testing of command line substitutions [esphome#12210](https://github.com/esphome/esphome/pull/12210) by [@jpeletier](https://github.com/jpeletier) +- [core] Improve CORE.data documentation with dataclass pattern [esphome#12170](https://github.com/esphome/esphome/pull/12170) by [@bdraco](https://github.com/bdraco) +- [cst816] Fix CST826 & CST836 [esphome#12260](https://github.com/esphome/esphome/pull/12260) by [@jsmarion](https://github.com/jsmarion) +- [wifi, wifi_info] Add a WiFi power mode text sensor [esphome#11480](https://github.com/esphome/esphome/pull/11480) by [@kahrendt](https://github.com/kahrendt) (new-feature) +- [esp32] Sort variants in situ [esphome#10410](https://github.com/esphome/esphome/pull/10410) by [@ximex](https://github.com/ximex) +- [lvgl] fix hello_world passing invalid parameter to parse_yaml [esphome#12274](https://github.com/esphome/esphome/pull/12274) by [@jpeletier](https://github.com/jpeletier) +- [tests] Bump esp32_hosted in the test code [esphome#12289](https://github.com/esphome/esphome/pull/12289) by [@swoboda1337](https://github.com/swoboda1337) +- [CI] Update renamed action repo [esphome#12290](https://github.com/esphome/esphome/pull/12290) by [@jesserockz](https://github.com/jesserockz) +- [api] Use loop-based reboot timeout check to avoid scheduler heap churn [esphome#12291](https://github.com/esphome/esphome/pull/12291) by [@bdraco](https://github.com/bdraco) +- [remote_receiver] buffer usage fix and idle optimizations [esphome#9999](https://github.com/esphome/esphome/pull/9999) by [@Citizen07](https://github.com/Citizen07) +- Update readme logo [esphome#12294](https://github.com/esphome/esphome/pull/12294) by [@jesserockz](https://github.com/jesserockz) +- [esp32] Change imports to use esp32 only, not .const [esphome#12243](https://github.com/esphome/esphome/pull/12243) by [@jesserockz](https://github.com/jesserockz) +- [remote_receiver] Fix Zephyr clang tidy [esphome#12299](https://github.com/esphome/esphome/pull/12299) by [@swoboda1337](https://github.com/swoboda1337) +- [api] Simplify MessageCreator to trivially copyable type [esphome#12295](https://github.com/esphome/esphome/pull/12295) by [@bdraco](https://github.com/bdraco) +- [esp32] Add support for ESP32-C61 variant [esphome#12285](https://github.com/esphome/esphome/pull/12285) by [@swoboda1337](https://github.com/swoboda1337) +- [light] Fix schedule_show not enabling loop for idle addressable lights [esphome#12302](https://github.com/esphome/esphome/pull/12302) by [@bdraco](https://github.com/bdraco) +- [sps30] Add idle mode functionality [esphome#12255](https://github.com/esphome/esphome/pull/12255) by [@c0mputerguru](https://github.com/c0mputerguru) (new-feature) +- [hub75] HUB75 display component [esphome#11153](https://github.com/esphome/esphome/pull/11153) by [@stuartparmenter](https://github.com/stuartparmenter) (new-component) (new-feature) (new-platform) +- [mipi_spi] Add M5CORE2 model that extends the ILI9341 driver chip [esphome#12301](https://github.com/esphome/esphome/pull/12301) by [@lboue](https://github.com/lboue) (new-feature) +- [esp32] Add missing variant support [esphome#12305](https://github.com/esphome/esphome/pull/12305) by [@swoboda1337](https://github.com/swoboda1337) +- [cc1101] Use Hz and cv.frequency instead of kHz [esphome#12313](https://github.com/esphome/esphome/pull/12313) by [@swoboda1337](https://github.com/swoboda1337) +- [image] Add USE_IMAGE in defines.h [esphome#12317](https://github.com/esphome/esphome/pull/12317) by [@clydebarrow](https://github.com/clydebarrow) +- [ci-custom] Fix after switch from string to path [esphome#12314](https://github.com/esphome/esphome/pull/12314) by [@clydebarrow](https://github.com/clydebarrow) +- [api] Device defined action responses [esphome#12136](https://github.com/esphome/esphome/pull/12136) by [@jesserockz](https://github.com/jesserockz) (new-feature) +- [text_sensor] Reduce filter memory usage using const char`*` [esphome#12334](https://github.com/esphome/esphome/pull/12334) by [@bdraco](https://github.com/bdraco) +- [nextion] Use 16-bit id for pics [esphome#12330](https://github.com/esphome/esphome/pull/12330) by [@edwardtfn](https://github.com/edwardtfn) +- [text] Add component tests with pattern coverage [esphome#12345](https://github.com/esphome/esphome/pull/12345) by [@bdraco](https://github.com/bdraco) +- [esp8266] Allow use of recvfrom for esphome sockets [esphome#12342](https://github.com/esphome/esphome/pull/12342) by [@elupus](https://github.com/elupus) +- [template] Use C++17 nested namespace syntax [esphome#12346](https://github.com/esphome/esphome/pull/12346) by [@bdraco](https://github.com/bdraco) +- [text] Store pattern as const char`*` to reduce memory usage [esphome#12335](https://github.com/esphome/esphome/pull/12335) by [@bdraco](https://github.com/bdraco) +- [micronova] Set update_interval on entities instead on hub [esphome#12226](https://github.com/esphome/esphome/pull/12226) by [@edenhaus](https://github.com/edenhaus) (breaking-change) +- [micronova] Move STOVE_STATES to text sensor file as it's used only there [esphome#12349](https://github.com/esphome/esphome/pull/12349) by [@edenhaus](https://github.com/edenhaus) +- [micronova] Add FINAL_VALIDATE_SCHEMA to validate uart [esphome#12350](https://github.com/esphome/esphome/pull/12350) by [@edenhaus](https://github.com/edenhaus) +- [core] Move Color::gradient to cpp to avoid duplicate code [esphome#12348](https://github.com/esphome/esphome/pull/12348) by [@bdraco](https://github.com/bdraco) +- [wifi_signal] Update signal strength immediately on WiFi connect/disconnect [esphome#12347](https://github.com/esphome/esphome/pull/12347) by [@bdraco](https://github.com/bdraco) +- [wifi_signal] Add ifdef guards for clang-tidy compatibility [esphome#12362](https://github.com/esphome/esphome/pull/12362) by [@bdraco](https://github.com/bdraco) +- Add seeed_xiao_esp32c6 board definition [esphome#12307](https://github.com/esphome/esphome/pull/12307) by [@berikv](https://github.com/berikv) (new-feature) +- [micronova] Set the write bit automatically [esphome#12318](https://github.com/esphome/esphome/pull/12318) by [@edenhaus](https://github.com/edenhaus) (breaking-change) +- [hlw8032] Single-phase metering IC [esphome#7241](https://github.com/esphome/esphome/pull/7241) by [@rici4kubicek](https://github.com/rici4kubicek) (new-component) (new-feature) (new-platform) +- [hub75] fix id conflict [esphome#12365](https://github.com/esphome/esphome/pull/12365) by [@arno1801](https://github.com/arno1801) +- [usb_cdc_acm] New component [esphome#11687](https://github.com/esphome/esphome/pull/11687) by [@kbx81](https://github.com/kbx81) (new-component) (new-feature) +- [pca9685] Allow to disable the phase balancer for PCA9685 [esphome#9792](https://github.com/esphome/esphome/pull/9792) by [@jonau](https://github.com/jonau) (new-feature) +- [core] Use StringRef for get_comment and get_compilation_time to avoid allocations [esphome#12219](https://github.com/esphome/esphome/pull/12219) by [@bdraco](https://github.com/bdraco) +- [select] Add zero-copy support for API select commands [esphome#12329](https://github.com/esphome/esphome/pull/12329) by [@bdraco](https://github.com/bdraco) +- [micronova] Make stove switch entity independent [esphome#12355](https://github.com/esphome/esphome/pull/12355) by [@edenhaus](https://github.com/edenhaus) +- [i2c] Fix port logic with ESP-IDF [esphome#12063](https://github.com/esphome/esphome/pull/12063) by [@arno1801](https://github.com/arno1801) (breaking-change) +- Update URLs [esphome#12369](https://github.com/esphome/esphome/pull/12369) by [@smarthome-10](https://github.com/smarthome-10) +- [micronova] Remove MicroNovaFunctions [esphome#12363](https://github.com/esphome/esphome/pull/12363) by [@edenhaus](https://github.com/edenhaus) (breaking-change) +- [sx1509] Change setup priority from HARDWARE to IO [esphome#12373](https://github.com/esphome/esphome/pull/12373) by [@mirko](https://github.com/mirko) +- [psram] Fix boot failure with 120MHz Octal flash [esphome#12377](https://github.com/esphome/esphome/pull/12377) by [@clydebarrow](https://github.com/clydebarrow) +- [pio] Rationalise library definitions in platformio.ini [esphome#12374](https://github.com/esphome/esphome/pull/12374) by [@clydebarrow](https://github.com/clydebarrow) +- [scheduler] Avoid std::string allocation in RetryArgs [esphome#12311](https://github.com/esphome/esphome/pull/12311) by [@bdraco](https://github.com/bdraco) +- [mdns] Reduce RAM usage by eliminating MAC address heap allocation [esphome#12073](https://github.com/esphome/esphome/pull/12073) by [@bdraco](https://github.com/bdraco) +- [core] Add PR template instruction to AI instructions [esphome#12375](https://github.com/esphome/esphome/pull/12375) by [@swoboda1337](https://github.com/swoboda1337) +- [api] Store device info strings in flash on ESP8266 [esphome#12173](https://github.com/esphome/esphome/pull/12173) by [@bdraco](https://github.com/bdraco) +- [packages] Add more information and deprecation deadline for "single package" includes [esphome#12280](https://github.com/esphome/esphome/pull/12280) by [@jpeletier](https://github.com/jpeletier) +- [api] Use StringRef for ActionResponse error message to avoid copy [esphome#12240](https://github.com/esphome/esphome/pull/12240) by [@bdraco](https://github.com/bdraco) +- [api] Store Home Assistant state subscriptions in flash instead of heap [esphome#12008](https://github.com/esphome/esphome/pull/12008) by [@bdraco](https://github.com/bdraco) +- [wifi] Fix LibreTiny spurious disconnect events aborting connections [esphome#12357](https://github.com/esphome/esphome/pull/12357) by [@bdraco](https://github.com/bdraco) +- [api] Reduce heap usage for Home Assistant service call string storage [esphome#12151](https://github.com/esphome/esphome/pull/12151) by [@bdraco](https://github.com/bdraco) +- [micronova] Require memory location and address for custom entities [esphome#12371](https://github.com/esphome/esphome/pull/12371) by [@edenhaus](https://github.com/edenhaus) (breaking-change) +- [epaper_spi] Set reasonable default update interval [esphome#12331](https://github.com/esphome/esphome/pull/12331) by [@clydebarrow](https://github.com/clydebarrow) +- [mipi_rgb] Add Waveshare 3.16 [esphome#12309](https://github.com/esphome/esphome/pull/12309) by [@clydebarrow](https://github.com/clydebarrow) (new-feature) +- [ci] Allow memory impact target branch build to fail without blocking CI [esphome#12381](https://github.com/esphome/esphome/pull/12381) by [@bdraco](https://github.com/bdraco) +- [ci] Isolate usb_cdc_acm in component tests due to tinyusb/usb_host conflict [esphome#12392](https://github.com/esphome/esphome/pull/12392) by [@bdraco](https://github.com/bdraco) +- [micronova] Fix test UART package key to match directory name [esphome#12391](https://github.com/esphome/esphome/pull/12391) by [@bdraco](https://github.com/bdraco) +- [tests] Fix clang-tidy warnings in custom_api_device_component fixture [esphome#12390](https://github.com/esphome/esphome/pull/12390) by [@bdraco](https://github.com/bdraco) +- [core] Packages refactor and conditional package inclusion (package refactor part 1) [esphome#11605](https://github.com/esphome/esphome/pull/11605) by [@jpeletier](https://github.com/jpeletier) (new-feature) + +
+ +
+ + +- Bump pytest from 9.0.0 to 9.0.1 [esphome#11874](https://github.com/esphome/esphome/pull/11874) by [@dependabot[bot]](https://github.com/apps/dependabot) +- Bump pylint from 4.0.2 to 4.0.3 [esphome#11894](https://github.com/esphome/esphome/pull/11894) by [@dependabot[bot]](https://github.com/apps/dependabot) +- Bump github/codeql-action from 4.31.2 to 4.31.3 [esphome#11911](https://github.com/esphome/esphome/pull/11911) by [@dependabot[bot]](https://github.com/apps/dependabot) +- Bump ruff from 0.14.4 to 0.14.5 [esphome#11910](https://github.com/esphome/esphome/pull/11910) by [@dependabot[bot]](https://github.com/apps/dependabot) +- Bump ruamel-yaml-clib from 0.2.14 to 0.2.15 [esphome#11956](https://github.com/esphome/esphome/pull/11956) by [@dependabot[bot]](https://github.com/apps/dependabot) +- Bump actions/checkout from 5.0.0 to 5.0.1 [esphome#11957](https://github.com/esphome/esphome/pull/11957) by [@dependabot[bot]](https://github.com/apps/dependabot) +- Bump github/codeql-action from 4.31.3 to 4.31.4 [esphome#11977](https://github.com/esphome/esphome/pull/11977) by [@dependabot[bot]](https://github.com/apps/dependabot) +- Bump pyupgrade from 3.21.1 to 3.21.2 [esphome#12002](https://github.com/esphome/esphome/pull/12002) by [@dependabot[bot]](https://github.com/apps/dependabot) +- Bump actions/checkout from 5.0.1 to 6.0.0 [esphome#12022](https://github.com/esphome/esphome/pull/12022) by [@dependabot[bot]](https://github.com/apps/dependabot) +- Bump github/codeql-action from 4.31.4 to 4.31.5 [esphome#12080](https://github.com/esphome/esphome/pull/12080) by [@dependabot[bot]](https://github.com/apps/dependabot) +- Bump peter-evans/create-pull-request from 7.0.8 to 7.0.9 [esphome#12082](https://github.com/esphome/esphome/pull/12082) by [@dependabot[bot]](https://github.com/apps/dependabot) +- Bump actions/create-github-app-token from 2.1.4 to 2.2.0 [esphome#12081](https://github.com/esphome/esphome/pull/12081) by [@dependabot[bot]](https://github.com/apps/dependabot) +- Bump bleak from 1.1.1 to 2.0.0 [esphome#12083](https://github.com/esphome/esphome/pull/12083) by [@dependabot[bot]](https://github.com/apps/dependabot) +- Bump aioesphomeapi from 42.7.0 to 42.8.0 [esphome#12092](https://github.com/esphome/esphome/pull/12092) by [@dependabot[bot]](https://github.com/apps/dependabot) +- Bump actions/setup-python from 6.0.0 to 6.1.0 [esphome#12106](https://github.com/esphome/esphome/pull/12106) by [@dependabot[bot]](https://github.com/apps/dependabot) +- Bump actions/setup-python from 6.0.0 to 6.1.0 in /.github/actions/restore-python [esphome#12108](https://github.com/esphome/esphome/pull/12108) by [@dependabot[bot]](https://github.com/apps/dependabot) +- Bump aioesphomeapi from 42.8.0 to 42.9.0 [esphome#12189](https://github.com/esphome/esphome/pull/12189) by [@dependabot[bot]](https://github.com/apps/dependabot) +- Bump ruff from 0.14.5 to 0.14.7 [esphome#12190](https://github.com/esphome/esphome/pull/12190) by [@dependabot[bot]](https://github.com/apps/dependabot) +- Bump github/codeql-action from 4.31.5 to 4.31.6 [esphome#12234](https://github.com/esphome/esphome/pull/12234) by [@dependabot[bot]](https://github.com/apps/dependabot) +- Bump aioesphomeapi from 42.9.0 to 42.10.0 [esphome#12245](https://github.com/esphome/esphome/pull/12245) by [@dependabot[bot]](https://github.com/apps/dependabot) +- Bump pylint from 4.0.3 to 4.0.4 [esphome#12239](https://github.com/esphome/esphome/pull/12239) by [@dependabot[bot]](https://github.com/apps/dependabot) +- Bump actions/checkout from 6.0.0 to 6.0.1 [esphome#12259](https://github.com/esphome/esphome/pull/12259) by [@dependabot[bot]](https://github.com/apps/dependabot) +- Bump actions/stale from 10.1.0 to 10.1.1 [esphome#12270](https://github.com/esphome/esphome/pull/12270) by [@dependabot[bot]](https://github.com/apps/dependabot) +- Bump ruff from 0.14.7 to 0.14.8 [esphome#12286](https://github.com/esphome/esphome/pull/12286) by [@dependabot[bot]](https://github.com/apps/dependabot) +- Bump peter-evans/create-pull-request from 7.0.9 to 7.0.11 [esphome#12303](https://github.com/esphome/esphome/pull/12303) by [@dependabot[bot]](https://github.com/apps/dependabot) +- Bump github/codeql-action from 4.31.6 to 4.31.7 [esphome#12304](https://github.com/esphome/esphome/pull/12304) by [@dependabot[bot]](https://github.com/apps/dependabot) +- Bump aioesphomeapi from 43.0.0 to 43.1.0 [esphome#12333](https://github.com/esphome/esphome/pull/12333) by [@dependabot[bot]](https://github.com/apps/dependabot) +- Bump pytest from 9.0.1 to 9.0.2 [esphome#12332](https://github.com/esphome/esphome/pull/12332) by [@dependabot[bot]](https://github.com/apps/dependabot) +- Bump aioesphomeapi from 43.1.0 to 43.2.1 [esphome#12385](https://github.com/esphome/esphome/pull/12385) by [@dependabot[bot]](https://github.com/apps/dependabot) + +
+ + + +## All Changelogs + +{{< changelogs >}} diff --git a/content/changelog/_index.md b/content/changelog/_index.md index 9c805b76c4..771d6f66ce 100644 --- a/content/changelog/_index.md +++ b/content/changelog/_index.md @@ -3,4 +3,4 @@ description: "Changelog" title: "Changelog" --- -{{< redirect url="/changelog/2025.11.0.html" >}} +{{< redirect url="/changelog/2025.12.0.html" >}} diff --git a/content/components/_index.md b/content/components/_index.md index 4c3e080d2d..dfb24cfbd0 100644 --- a/content/components/_index.md +++ b/content/components/_index.md @@ -169,6 +169,7 @@ Create update entities simplifying management of OTA updates. "SPI Bus","components/spi","spi.svg","" "TinyUSB","components/tinyusb","usb.svg","dark-invert" "UART","components/uart","uart.svg","" +"USB CDC-ACM","components/usb_cdc_acm","usb.svg","dark-invert" "USB Host","components/usb_host","usb.svg","dark-invert" "USB UART","components/usb_uart","usb.svg","dark-invert" {{< /imgtable >}} @@ -240,6 +241,7 @@ Sensors are organized into categories; if a given sensor fits into more than one "GCJA5","components/sensor/gcja5","gcja5.svg","Particulate","","" "GP2Y1010AU0F","components/sensor/gp2y1010au0f","gp2y1010au0f.png","Particulate","","" "Grove Multichannel Gas V2","components/sensor/grove_gas_mc_v2","grove-gas-mc-v2.png","NO₂ & CO & Ethanol & Volatile organics","","" +"HC8","components/sensor/hc8","hc8.png","CO₂","","" "HM3301","components/sensor/hm3301","hm3301.jpg","Particulate","","" "iAQ-Core","components/sensor/iaqcore","iaqcore.jpg","eCO₂ & Volatile organics","","" "MH-Z19","components/sensor/mhz19","mhz19.jpg","CO₂ & Temperature","","" @@ -291,6 +293,7 @@ Sensors are organized into categories; if a given sensor fits into more than one "Mopeka Pro Check LP","components/sensor/mopeka_pro_check","mopeka_pro_check.jpg","Tank level" "Mopeka Standard Check LP","components/sensor/mopeka_std_check","mopeka_std_check.jpg","Tank level" "RuuviTag","components/sensor/ruuvitag","ruuvitag.jpg","Temperature & Humidity & Accelerometer" +"ThermoPro BLE","components/sensor/thermopro_ble","thermopro_tp357.jpg","Temperature & Humidity" "Xiaomi BLE","components/sensor/xiaomi_ble","xiaomi_mijia_logo.jpg","Various" {{< /imgtable >}} @@ -335,6 +338,7 @@ Sensors are organized into categories; if a given sensor fits into more than one "Daly BMS","components/sensor/daly_bms","daly_bms.jpg","Voltage & Current & Power" "DSMR","components/sensor/dsmr","dsmr.svg","Electrical counter" "HLW8012","components/sensor/hlw8012","hlw8012.svg","Voltage & Current & Power" +"HLW8032","components/sensor/hlw8032","hlw8032.png","Voltage & Current & Power" "INA219","components/sensor/ina219","ina219.jpg","DC Current" "INA226","components/sensor/ina226","ina226.jpg","DC Current & Power" "INA228","components/sensor/ina2xx","ina228.jpg","DC Voltage & Current & Power & Charge" @@ -380,6 +384,7 @@ Sensors are organized into categories; if a given sensor fits into more than one "EMC2101","components/emc2101","emc2101.jpg","Temperature","" "ENS160","components/sensor/ens160","ens160.jpg","eCO₂ & Air Quality","" "ENS210","components/sensor/ens210","ens210.jpg","Temperature & Humidity","" +"HC8","components/sensor/hc8","hc8.png","CO₂","" "HDC1080","components/sensor/hdc1080","hdc1080.jpg","Temperature & Humidity","" "HDC2010","components/sensor/hdc2010","hdc2010.png","Temperature & Humidity","" "HHCCJCY10 (MiFlora Pink)","components/sensor/xiaomi_hhccjcy10","xiaomi_hhccjcy10.jpg","Soil moisture & Temperature & Light","" @@ -416,6 +421,7 @@ Sensors are organized into categories; if a given sensor fits into more than one "SHTCx","components/sensor/shtcx","shtc3.jpg","Temperature & Humidity","" "SMT100","components/sensor/smt100","smt100.jpg","Moisture & Temperature","" "STS3X","components/sensor/sts3x","sts3x.jpg","Temperature","" +"STTS22H","components/sensor/stts22h","stts22h.jpg","Temperature","" "TC74","components/sensor/tc74","tc74.jpg","Temperature","" "TEE501","components/sensor/tee501","TEE501.png","Temperature","" "TE-M3200","components/sensor/tem3200","tem3200.jpg","Temperature & Pressure","" @@ -999,6 +1005,7 @@ at the {{< docref "light/fastled" "FastLED Light" >}}. {{< imgtable >}} "Time Core","components/time/index","clock-outline.svg","dark-invert" +"BM8563 RTC","components/time/bm8563","bm8563.svg","" "DS1307 RTC","components/time/ds1307","clock-outline.svg","dark-invert" "RX8130 RTC","components/time/rx8130","clock-outline.svg","dark-invert" "GPS Time","components/time/gps","crosshairs-gps.svg","dark-invert" @@ -1037,6 +1044,7 @@ Used for creating infrared (IR) or radio frequency (RF) remote control transmitt ESPHome to cellular networks. **Does not encompass Wi-Fi.** {{< imgtable >}} +"CC1101","components/cc1101","cc1101.webp","" "IR Remote Climate","components/climate/climate_ir","air-conditioner-ir.svg","dark-invert" "Remote Receiver","components/remote_receiver","remote.svg","dark-invert" "Remote Transmitter","components/remote_transmitter","remote.svg","dark-invert" diff --git a/content/components/api.md b/content/components/api.md index 214679f5a5..09825c4f8b 100644 --- a/content/components/api.md +++ b/content/components/api.md @@ -58,7 +58,12 @@ api: > The defaults are set to balance memory usage with allowing multiple simultaneous connections. - **max_send_queue** (*Optional*, int): The maximum number of messages that can be queued for sending per connection before the connection is dropped. Must be between 1 and 64. - Defaults to `5` for ESP8266/RP2040, `8` for ESP32/BK72xx/RTL87xx/LN882x, `16` for host platform. This prevents memory exhaustion when a client is slow or network-stalled. + Defaults to: + - `5` for ESP8266/RP2040, + - `8` for ESP32/BK72xx/LN882x/nRF52/RTL87xx, + - `16` for host platform. + + This prevents memory exhaustion when a client is slow or network-stalled. Each queued message uses approximately 8-12 bytes of overhead plus the message size. > [!NOTE] @@ -385,13 +390,19 @@ api: - logger.log: "API client disconnected!" ``` +## Conditions + {{< anchor "api-connected_condition" >}} -## `api.connected` Condition +### `api.connected` Condition + +This [Condition](/automations/actions#all-conditions) checks if at least one client is connected to the ESPHome native API. + +#### Configuration variables + +- **state_subscription_only** (*Optional*, boolean): If enabled, only counts clients that have subscribed to entity state updates. This filters out logger-only connections (such as `esphome logs` command), which can cause false positives when waiting for Home Assistant. Defaults to `false`. -This [Condition](/automations/actions#all-conditions) checks if at least one client is connected to the ESPHome -native API. Please note client not only includes Home Assistant, but also ESPHome's OTA log output -if logs are shown remotely. +**Check if any client is connected:** ```yaml on_...: @@ -399,11 +410,31 @@ on_...: condition: api.connected: then: - - logger.log: API is connected! + - logger.log: Client is connected to API! ``` The lambda equivalent for this is `id(api_id).is_connected()`. +**Check if a client subscribed to entity states is connected (typically Home Assistant):** + +```yaml +on_boot: + - wait_until: + condition: + api.connected: + state_subscription_only: true + - logger.log: Home Assistant is connected! + - homeassistant.event: + event: esphome.device_booted +``` + +The lambda equivalent for this is `id(api_id).is_connected(true)`. + +**Use Cases:** + +- Use `state_subscription_only: false` (default) to detect any API connection +- Use `state_subscription_only: true` when you need to ensure Home Assistant (or other connections that subscribe to states) is connected before sending events or calling services, preventing errors from logger-only connections + {{< anchor "api-device-actions" >}} ## User-defined Actions @@ -412,6 +443,10 @@ It is also possible to get data from Home Assistant to ESPHome with user-defined When you declare actions in your ESPHome YAML file, they will automatically show up in Home Assistant and you can call them directly. +> [!NOTE] +> User-defined actions can also send responses back to the calling client using the `api.respond` action. +> See [Action Responses](#action-responses) for details. + ```yaml # Example configuration entry api: @@ -471,6 +506,144 @@ Each of these also exist in array form: - bool[]: An array of boolean values. C++ type: `std::vector` - ... - Same for other types. +### Action Responses + +User-defined actions can send responses back to the calling client (such as Home Assistant). This enables +bidirectional communication where actions can report success/error status or return structured JSON data. + +#### Response Modes + +The response behavior is controlled by the `supports_response` option, which can be set explicitly or +auto-detected based on your action configuration: + +- **none** (default): No response is sent. The action is "fire and forget". +- **status**: Reports success/error status without data. Auto-detected when `api.respond` is used without `data:`. +- **optional**: Returns JSON data when the client requests it. Auto-detected when `api.respond` is used with `data:`. +- **only**: Always returns JSON data. Must be set explicitly. Use this for query-type actions. + +#### Configuration variables + +- **supports_response** (*Optional*, string): The response mode for this action. One of `none`, `status`, + `optional`, or `only`. If not specified, the mode is auto-detected based on `api.respond` usage in the action. + +#### Trigger variables + +When `supports_response` is not `none`, the following variables are available in the action: + +- **call_id** (`uint32_t`): A unique identifier for this action call. Used internally by `api.respond`. +- **return_response** (`bool`): Only available in `optional` mode. Indicates whether the client requested + a response. You don't typically need to check this - `api.respond` handles it automatically. + +### `api.respond` Action + +This action sends a response back to the client that called the user-defined action. It can report +success/error status and optionally include JSON data. + +#### Configuration variables + +- **success** (*Optional*, boolean, [templatable](/automations/templates)): Whether the action succeeded. + Defaults to `true`. +- **error_message** (*Optional*, string, [templatable](/automations/templates)): An error message to include + when `success` is `false`. Defaults to an empty string. +- **data** (*Optional*, [lambda](/automations/templates#config-lambda)): A lambda that populates a JSON object + with response data. The lambda receives a `root` variable of type [`JsonObject`](https://arduinojson.org/v7/api/jsonobject/) + that you can populate with key-value pairs. + +#### Status Response Example + +Report success or error without returning data: + +```yaml +api: + actions: + - action: validate_input + variables: + value: int + then: + - if: + condition: + lambda: 'return value < 0;' + then: + - api.respond: + success: false + error_message: "Value must be positive" + else: + - api.respond: + success: true +``` + +#### Data Response Example + +Return structured JSON data to the caller: + +```yaml +api: + actions: + - action: get_sensor_data + variables: + sensor_name: string + then: + - api.respond: + data: !lambda |- + root["sensor"] = sensor_name; + root["value"] = id(my_sensor).state; + root["unit"] = "°C"; + root["timestamp"] = id(homeassistant_time).now().timestamp; +``` + +This action will be auto-detected as `optional` mode because it uses `api.respond` with `data:`. + +#### Query Action Example + +For actions that always return data (like queries), explicitly set `supports_response: only`: + +```yaml +api: + actions: + - action: get_device_info + supports_response: only + then: + - api.respond: + data: !lambda |- + root["hostname"] = App.get_name(); + root["version"] = ESPHOME_VERSION; + root["uptime"] = millis() / 1000; +``` + +#### Nested JSON Data + +You can create complex nested JSON structures: + +```yaml +api: + actions: + - action: get_full_status + supports_response: only + then: + - api.respond: + data: !lambda |- + root["device"]["name"] = "living_room"; + root["device"]["version"] = 1; + root["sensors"]["temperature"] = id(temp_sensor).state; + root["sensors"]["humidity"] = id(humidity_sensor).state; +``` + +#### Calling from Home Assistant + +Actions with response support appear in Home Assistant with their response mode indicated. You can call +them and receive the response data: + +```yaml +# Home Assistant automation example +action: esphome.device_get_sensor_data +data: + sensor_name: "living_room" +response_variable: sensor_response +``` + +The response will be available in the `sensor_response` variable with the structure you defined in the +`data:` lambda. + ## Advantages over MQTT The ESPHome native API has many advantages over using MQTT for communication with Home diff --git a/content/components/canbus/esp32_can.md b/content/components/canbus/esp32_can.md index 114d7df1fb..8cfb45bd03 100644 --- a/content/components/canbus/esp32_can.md +++ b/content/components/canbus/esp32_can.md @@ -10,6 +10,7 @@ params: {{< anchor "esp32-can" >}} The ESP32 has an integrated CAN controller and therefore doesn't necessarily need an external controller. +Some variants (ESP32-C5, ESP32-C6, ESP32-P4) have multiple CAN controllers - see [Multiple CAN Controllers](#multiple-can-controllers) below. You only need to specify the RX and TX pins. Any GPIO will work. ```yaml @@ -39,28 +40,43 @@ canbus: The following table lists the bit rates supported by the component for ESP32 variants: -| bit_rate | ESP32 | ESP32-C3 | ESP32-C6 | ESP32-H2 | ESP32-S2 | ESP32-S3 | -| ----------------- | ----- | -------- | -------- | -------- | -------- | -------- | -| 1KBPS | | x | x | x | x | x | -| 5KBPS | | x | x | x | x | x | -| 10KBPS | | x | x | x | x | x | -| 12K5BPS | | x | x | x | x | x | -| 16KBPS | | x | x | x | x | x | -| 20KBPS | | x | x | x | x | x | -| 25KBPS | x | x | x | x | x | x | -| 31K25BPS | | | | | | | -| 33KBPS | | | | | | | -| 40KBPS | | | | | | | -| 50KBPS | x | x | x | x | x | x | -| 80KBPS | | | | | | | -| 83K38BPS | | | | | | | -| 95KBPS | | | | | | | -| 100KBPS | x | x | x | x | x | x | -| 125KBPS (Default) | x | x | x | x | x | x | -| 250KBPS | x | x | x | x | x | x | -| 500KBPS | x | x | x | x | x | x | -| 800KBPS | x | x | x | x | x | x | -| 1000KBPS | x | x | x | x | x | x | +| bit_rate | ESP32 | Other variants* | +| ----------------- | ----- | --------------- | +| 1KBPS | | x | +| 5KBPS | | x | +| 10KBPS | | x | +| 12K5BPS | | x | +| 16KBPS | | x | +| 20KBPS | | x | +| 25KBPS | x | x | +| 31K25BPS | | | +| 33KBPS | | | +| 40KBPS | | | +| 50KBPS | x | x | +| 80KBPS | | | +| 83K3BPS | | | +| 95KBPS | | | +| 100KBPS | x | x | +| 125KBPS (Default) | x | x | +| 250KBPS | x | x | +| 500KBPS | x | x | +| 800KBPS | x | x | +| 1000KBPS | x | x | + +Other variants: ESP32-C3, ESP32-C5, ESP32-C6, ESP32-H2, ESP32-P4, ESP32-S2, ESP32-S3 + +> [!NOTE] +> ESP32-C2 and ESP32-C61 do not have TWAI/CAN hardware and are not supported. + +## Multiple CAN Controllers + +Some ESP32 variants have multiple CAN (TWAI) controllers: + +- **ESP32-C5**: 2 controllers +- **ESP32-C6**: 2 controllers +- **ESP32-P4**: 3 controllers + +All other supported variants have a single controller. ESP32-C2 and ESP32-C61 do not have CAN hardware. ## Wiring options diff --git a/content/components/cc1101.md b/content/components/cc1101.md new file mode 100644 index 0000000000..92f608419a --- /dev/null +++ b/content/components/cc1101.md @@ -0,0 +1,252 @@ +--- +title: CC1101 Low-Power Sub-1 GHz RF Transceiver +description: Instructions for setting up CC1101 RF Transceiver in ESPHome. +image: /components/images/cc1101-full.webp +keywords: [cc1101] +--- + +The **CC1101** component provides a driver for the **Texas Instruments CC1101** Sub-1 GHz RF Transceiver +([datasheet](https://www.ti.com/lit/ds/symlink/cc1101.pdf)). The CC1101 is a low-cost, low-power radio +chip commonly used for wireless communication in the 300-928 MHz frequency bands, including the popular +315 MHz, 433 MHz, 868 MHz, and 915 MHz ISM bands. + +The **CC1101** supports multiple modulation schemes (ASK/OOK, 2-FSK, 4-FSK, GFSK, MSK), configurable data +rates from 600 to 500,000 baud, and adjustable output power from -30 dBm to +11 dBm. It connects to +ESPHome via the [SPI Bus](/components/spi) and integrates with the +[Remote Transmitter](/components/remote_transmitter) and +[Remote Receiver](/components/remote_receiver) components for encoding and decoding RF protocols. + +{{< img src="cc1101-full.webp" alt="CC1101 Module" width="50.0%" class="align-center" >}} + +## Component Configuration + +```yaml +# Minimal Example +cc1101: + cs_pin: GPIOXX + frequency: 433.92MHz +``` + +## Configuration Variables + +### Hardware Settings + +- **cs_pin** (**Required**, [Pin](/guides/configuration-types/#pin)): + The SPI Chip Select (CSN) pin connected to the module. + +### General Settings + +- **frequency** (*Optional*, frequency): The operating frequency. + Range: `300MHz` to `928MHz`. Defaults to `433.92MHz`. +- **output_power** (*Optional*, float): The transmission power in dBm. + Range: `-30` to `11`. Defaults to `10`. +- **modulation_type** (*Optional*, enum): The modulation format. + Options: `ASK/OOK` (default), `2-FSK`, `4-FSK`, `GFSK`, `MSK`. +- **symbol_rate** (*Optional*, int): The symbol rate in Baud. + Range: `600` to `500000`. Defaults to `5000`. +- **rx_attenuation** (*Optional*, enum): Internal RX attenuation. + Options: `0dB`, `6dB`, `12dB`, `18dB`. Defaults to `0dB`. +- **dc_blocking_filter** (*Optional*, boolean): Enable the digital DC blocking filter. Defaults to `true`. + +### Tuner Settings + +- **filter_bandwidth** (*Optional*, frequency): The receive filter bandwidth. + Range: `58kHz` to `812kHz`. Defaults to `203kHz`. +- **fsk_deviation** (*Optional*, frequency): Frequency deviation for FSK/GFSK modulation. + Range: `1.5kHz` to `381kHz`. +- **msk_deviation** (*Optional*, int): Deviation index for MSK modulation. Range: `1` to `8`. +- **channel** (*Optional*, int): Channel number (added to base frequency). Defaults to `0`. +- **channel_spacing** (*Optional*, frequency): Spacing between channels. + Range: `25kHz` to `405kHz`. Defaults to `200kHz`. +- **if_frequency** (*Optional*, frequency): Intermediate Frequency. + Range: `25kHz` to `788kHz`. Defaults to `153kHz`. +- **pktlen** (*Optional*, int): Packet length configuration. Sets the expected packet size for + fixed-length packet mode. Range: `1` to `255`. Not typically needed for OOK/ASK modulation. + +### AGC (Automatic Gain Control) Settings + +Advanced users can fine-tune the AGC dynamics. The AGC automatically adjusts receiver gain to handle +signals of varying strength. These settings control how aggressively and quickly the gain adapts. +See the [CC1101 Datasheet](https://www.ti.com/lit/ds/symlink/cc1101.pdf) for detailed information. + +- **magn_target** (*Optional*, dB): Target signal amplitude for the AGC loop. Higher values increase + sensitivity but may cause clipping on strong signals. + Range: `24dB` to `42dB` in increments of 3 (e.g., `33dB`). Defaults to `42dB`. +- **max_lna_gain** (*Optional*, dB): Limits the maximum LNA (Low Noise Amplifier) gain. Use to prevent + saturation in high-signal environments. Defaults to `Default`. + Options: `Default`, `2.6dB`, `6.1dB`, `7.4dB`, `9.2dB`, `11.5dB`, `14.6dB`, `17.1dB`. +- **max_dvga_gain** (*Optional*, enum): Limits the maximum DVGA (Digital Variable Gain Amplifier) gain. + Options: `Default`, `-1`, `-2`, `-3`. Defaults to `-3`. +- **lna_priority** (*Optional*, boolean): If true, reduce LNA gain before DVGA gain when decreasing + overall gain. Useful for optimizing noise figure. Defaults to `false`. +- **carrier_sense_abs_thr** (*Optional*, int): Absolute RSSI threshold for carrier sense. The radio + considers a carrier present when RSSI exceeds this level. +- **carrier_sense_rel_thr** (*Optional*, enum): Relative RSSI threshold for carrier sense, compared + to the current noise floor. Options: `Default`, `+6dB`, `+10dB`, `+14dB`. +- **filter_length_fsk_msk** (*Optional*, enum): Averaging length for AGC in FSK/MSK modes. + Longer values provide more stable gain but slower response. Options: `8`, `16`, `32`, `64`. +- **filter_length_ask_ook** (*Optional*, enum): Averaging length for AGC in ASK/OOK modes. + Longer values provide more stable gain but slower response. Options: `4dB`, `8dB`, `12dB`, `16dB`. +- **freeze** (*Optional*, enum): Controls when AGC gain is frozen (held constant). + Options: `Default`, `On Sync`, `Analog Only`, `Analog And Digital`. +- **wait_time** (*Optional*, enum): Time to wait after a gain change before allowing another adjustment. + Options: `8`, `16`, `24`, `32`. Defaults to `32`. +- **hyst_level** (*Optional*, enum): Hysteresis level to prevent gain oscillation on borderline signals. + Options: `None`, `Low`, `Medium`, `High`. + +## Actions + +This component provides actions to control the radio state, primarily used for coordinating transmission. + +- **cc1101.begin_tx**: Puts the radio into TX mode. Must be called before transmitting. +- **cc1101.begin_rx**: Puts the radio into RX mode. Call after transmitting to resume receiving. +- **cc1101.set_idle**: Puts the radio into an idle state. In single-pin configurations, this should be + called before switching between TX and RX modes to ensure clean state transitions. +- **cc1101.reset**: Resets the CC1101 chip and re-applies configuration. + +## Integration with Remote Receiver/Transmitter + +The component automatically configures the GDO pins to support both dual and single pin wiring schemes +without any extra configuration. + +### 1. Dual Pin Wiring (Recommended) + +This is the simplest and recommended wiring scheme. It uses separate pins for transmitting and receiving data. + +- **GDO0 (Module Pin 3)**: Connect to the MCU pin used by `remote_transmitter`. +- **GDO2 (Module Pin 8)**: Connect to the MCU pin used by `remote_receiver`. + +```yaml +cc1101: + cs_pin: GPIOXX + +remote_transmitter: + pin: GPIOXX # Must match GDO0 + carrier_duty_percent: 100% + on_transmit: + then: + - cc1101.begin_tx + on_complete: + then: + - cc1101.begin_rx + +remote_receiver: + pin: GPIOXX # CC1101 GDO2 + dump: all +``` + +### 2. Single Pin Wiring + +This wiring scheme uses a single MCU pin for both transmitting and receiving data, connected to GDO0. +This requires careful configuration of the `remote_transmitter` and `remote_receiver` to avoid conflicts. +Using an open-drain pin mode is recommended to simplify the setup. + +- **GDO0 (Module Pin 3)**: Connect to a single MCU GPIO pin. +- **GDO2 (Module Pin 8)**: Leave disconnected. + +#### Single Pin with Open-Drain + +ESP32 must use this method when using single-pin wiring. The shared pin should be set to open-drain with a +pullup. The `eot_level` option (from `remote_transmitter`) controls the pin state after transmission +completes - setting it to `false` keeps the pin low until explicitly released. In addition to setting the +CC1101 mode in `on_transmit`/`on_complete`, the pin should be driven low before `begin_tx` and released +before `begin_rx`. + +```yaml +cc1101: + cs_pin: GPIOXX + +remote_receiver: + pin: + number: GPIOXX # Must match GDO0 + mode: + input: true + output: true + pullup: true + open_drain: true + allow_other_uses: true + dump: all + +remote_transmitter: + pin: + number: GPIOXX # Must match GDO0 + mode: + input: true + output: true + pullup: true + open_drain: true + allow_other_uses: true + eot_level: false + carrier_duty_percent: 100% + on_transmit: + then: + - cc1101.set_idle + - remote_transmitter.digital_write: false + - cc1101.begin_tx + on_complete: + then: + - cc1101.set_idle + - remote_transmitter.digital_write: true + - cc1101.begin_rx +``` + +#### Single Pin with Mode Switching + +This method requires lambdas to manually switch the pin mode between input and output around transmissions. +On boot, the pin must be set to input mode so the receiver can operate. + +```yaml +esphome: + on_boot: + - priority: 0 + then: + - lambda: id(rx_pin)->pin_mode(gpio::FLAG_INPUT); + +cc1101: + cs_pin: GPIOXX + +remote_receiver: + pin: + id: rx_pin + number: GPIOXX # Must match GDO0 + allow_other_uses: true + dump: all + +remote_transmitter: + pin: + id: tx_pin + number: GPIOXX # Must match GDO0 + allow_other_uses: true + carrier_duty_percent: 100% + on_transmit: + then: + - cc1101.set_idle + - lambda: id(tx_pin)->pin_mode(gpio::FLAG_OUTPUT); + - cc1101.begin_tx + on_complete: + then: + - cc1101.set_idle + - lambda: id(rx_pin)->pin_mode(gpio::FLAG_INPUT); + - cc1101.begin_rx +``` + +## Troubleshooting + +### "FF0F was found" Error + +If you see a log entry stating `FF0F`, `0000`, or `FFFF` during setup, this indicates an SPI +communication failure. Check your wiring (MISO/MOSI/CS). + +### No Signal during Transmit + +- **Check Pinout**: For all modes, the data line must be connected to GDO0 (Module Pin 3), + as the CC1101 chip only supports transmission input via the GDO0 pin. +- **Check Pin Mode**: If using the Single Pin with Mode Switching method, + ensure your `on_transmit`/`on_complete` logic correctly flips the pin mode. + +## See Also + +- [Remote Receiver](/components/remote_receiver) +- [Remote Transmitter](/components/remote_transmitter) +- [SPI Component](/components/spi) +- [CC1101 Datasheet](https://www.ti.com/lit/ds/symlink/cc1101.pdf) diff --git a/content/components/climate/climate_ir.md b/content/components/climate/climate_ir.md index 83caa0002a..64aa607efd 100644 --- a/content/components/climate/climate_ir.md +++ b/content/components/climate/climate_ir.md @@ -64,6 +64,8 @@ climate: - **sensor** (*Optional*, [ID](/guides/configuration-types#id)): The sensor that is used to measure the ambient temperature. This is only for reporting the current temperature in the frontend. +- **humidity_sensor** (*Optional*, [ID](/guides/configuration-types#id)): The sensor that is used to measure the ambient + humidity. This is only for reporting the current humidity in the frontend. - **supports_cool** (*Optional*, boolean): Enables setting cooling mode for this climate device. Defaults to `true`. - **supports_heat** (*Optional*, boolean): Enables setting heating mode for this climate device. Defaults to `true`. @@ -129,7 +131,7 @@ The Daikin ARC remotes (`daikin_arc` climate, `daikin_arc417`, `daikin_arc480` p ### `gree` -- **model** (**Required**, string): GREE has a few different protocols depending on model. One of these will work for you. +- **model** (**Required**, string): GREE has a few different protocols depending on model. One of these will likely work for you: - `generic` - `yan` @@ -140,14 +142,38 @@ The Daikin ARC remotes (`daikin_arc` climate, `daikin_arc417`, `daikin_arc480` p - `yag` ```yaml -# Example configuration entry +# Example configuration entry for climate only climate: - platform: gree name: "AC" + id: my_gree_ac sensor: room_temperature model: yan ``` +Models `yan`, `yaa`, `yac` and `yac1fb9` support a couple of additional features which can be controlled with switches: + +- **gree_id** (**Required**, [ID](/guides/configuration-types#id)): Specify the ID of the `gree` climate to which these swicthes should belong. +- **light** (*Optional*, [Switch](/components/switch#config-switch)): To turn off indoor unit display/LED at night for complete room darkness. +- **turbo** (*Optional*, [Switch](/components/switch#config-switch)): For maximum fan speed and fastest results. +- **health** (*Optional*, [Switch](/components/switch#config-switch)): Removal of dust and germs from the environment by ionizing the air flowing through the blades. +- **xfan** (*Optional*, [Switch](/components/switch#config-switch)): Prevention of excess moisture in the machine that cause mold, mildew, and unpleasant odors. Indoor fan will keep running for short period after turning turn off the AC, to dry the blades. + +```yaml +# Example configuration entry for switches of the climate +switch: + - platform: gree + gree_id: my_gree_ac + light: + name: "AC Lights" + turbo: + name: "AC Turbo" + health: + name: "AC Health" + xfan: + name: "AC X-Fan" +``` + {{< anchor "midea_ir" >}} ### `midea_ir` diff --git a/content/components/deep_sleep.md b/content/components/deep_sleep.md index 2d671daec9..f06cbc951a 100644 --- a/content/components/deep_sleep.md +++ b/content/components/deep_sleep.md @@ -67,7 +67,7 @@ Advanced features: - **pins** (**Required**, list of pin numbers): The pins to wake up on. - **mode** (**Required**): The mode to use for the wakeup source. Must be one of: - - `ANY_LOW`: wake up when any selected pin is LOW (ESP32‑S2/S3/C6/H2 only) + - `ANY_LOW`: wake up when any selected pin is LOW (ESP32‑C5/C6/C61/H2/P4/S2/S3 only) - `ALL_LOW`: wake up when all selected pins are LOW (ESP32 only) - `ANY_HIGH`: wake up when any selected pin is HIGH diff --git a/content/components/display/epaper_spi.md b/content/components/display/epaper_spi.md index c72cf57054..726b6089f6 100644 --- a/content/components/display/epaper_spi.md +++ b/content/components/display/epaper_spi.md @@ -12,7 +12,7 @@ with improved state management and non-blocking operation. This component implem queue-based state machine that eliminates blocking waits for the busy pin and provides better integration with ESPHome's async architecture. -The communication method uses 4-wire [SPI](/components/spi), so you need to have an `spi:` section in your +The communication method uses [SPI](/components/spi), so you need to have an `spi:` section in your configuration. The driver supports a number of displays and there are also specific configurations for ESP32 boards with integrated displays. @@ -26,43 +26,85 @@ display: it.filled_circle(it.get_width() / 2, it.get_height() / 2, 50, Color::BLACK); ``` -## Supported displays +## Supported display controllers -| Model name | Manufacturer | Product Description | -| ---------------------- | ------------ | ---------------------------------------------------------- | -| Spectra-E6 | Eink | | -| 7.3in Spectra-E6 | Eink | | -| Seeed-reTerminal-E1002 | Seeed Studio | | +These are the supported controller chips. Using just the chip name as the model will require full configuration with +pins and dimensions specified. + +| Chip name | Manufacturer | Product Description | +|------------------------|--------------|------------------------------------------------------------------------------------------------------------------------------| +| Spectra-E6 | Eink | | +| SSD1677 | Solomon | | + +## Supported integrated display boards + +These models correspond to displays integrated with a microcontroller, and have a full configuration predefined, so at +a minimum only the model name need be configured. Other options can be overridden in the configuration if needed. + +| Model name | Manufacturer | Product Description | +| ---------------------- |--------------| ---------------------------------------------------------------------------------------------------------------------------- | +| Seeed-reTerminal-E1002 | Seeed Studio | | +| Seeed-ee04-mono-4.26 | Seeed Studio | Seeed EE04 board with Waveshare 4.26" mono epaper. | ## Configuration variables -When using a model defining an integrated ESP32 display board most of the configuration such as the pins and dimensions will be set by default, +When using a model defining an integrated display board most of the configuration such as the pins and dimensions will be set by default, but can be overridden if needed. -- **model** (**Required**): The model of the ePaper display. See the table above for options. +- **model** (**Required**): The model of the ePaper display. See the table above for options (case is not significant). - **cs_pin** (**Required**, [Pin Schema](/guides/configuration-types#pin-schema)): The CS pin. Predefined for integrated boards. - **dc_pin** (**Required**, [Pin Schema](/guides/configuration-types#pin-schema)): The DC pin. Predefined for integrated boards. - **busy_pin** (*Optional*, [Pin Schema](/guides/configuration-types#pin-schema)): The BUSY pin, if used. - **reset_pin** (*Optional*, [Pin Schema](/guides/configuration-types#pin-schema)): The RESET pin, if used. Make sure you pull this pin high (by connecting it to 3.3V with a resistor) if not connected to a GPIO pin. +- **dimensions** (**Required**, dict): Dimensions of the screen, specified either as *width* **x** *height* (e.g `320x240` ) + or with separate config keys. For integrated boards with full pre-defined configuration this is optional and will be preset by + the model selected. The dimensions are specified in pixels, and the width and height must be greater than 0. -- **rotation** (*Optional*): Set the rotation of the display. Everything you draw in `lambda:` will be rotated + - **height** (**Required**, int): Specifies height of display. + - **width** (**Required**, int): Specifies width of display. + +- **rotation** (*Optional*, int): Set the rotation of the display. Everything you draw in `lambda:` will be rotated by this option. One of `0°` (default), `90°`, `180°`, `270°`. +- **transform** (*Optional*, dict): If `rotation` is not sufficient, use this to transform the display. Options are: + - **mirror_x** (**Required**, boolean): If true, mirror the x axis. + - **mirror_y** (**Required**, boolean): If true, mirror the y axis. - **reset_duration** (*Optional*, [Time](/guides/configuration-types#time)): Duration for the display reset operation. Defaults to `200ms`. - - **lambda** (*Optional*, [lambda](/automations/templates#config-lambda)): The lambda to use for rendering the content on the display. See [Display Rendering Engine](/components/display#display-engine) for more information. - **pages** (*Optional*, list): Show pages instead of a single lambda. See [Display Pages](/components/display#display-pages). - - **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval to re-draw the screen. Defaults to `60s`, use `never` to only manually update the screen via `component.update`. -- **spi_id** (*Optional*, [ID](/guides/configuration-types#id)): Manually specify the ID of the [SPI Component](/components/spi) if you want - to use multiple SPI buses. +- **full_update_every** (*Optional*, int): On screens that support partial updates, this sets the number of updates + before a full update is forced. Defaults to `1` which will make every update a full update. +- **spi_id** (*Optional*, [ID](/guides/configuration-types#id)): Required to specify the ID of the [SPI Component](/components/spi) if your + configuration defines multiple SPI buses. If only a single SPI bus is configured, this is optional. - **id** (*Optional*, [ID](/guides/configuration-types#id)): Manually specify the ID used for code generation. +### Full configuration example + +```yaml +display: + - platform: epaper_spi + model: SSD1677 + full_update_every: 10 + update_interval: 5s + dimensions: + width: 800 + height: 480 + transform: + mirror_x: true + mirror_y: false + rotation: 90 # Rotate to portrait + cs_pin: GPIOXX + dc_pin: GPIOXX + reset_pin: GPIOXX + busy_pin: { number: GPIOXX, inverted: False, mode: { input: True, pulldown: True } } +``` + ## See Also -- {{< docref "index/" >}} - {{< apiref "epaper_spi/epaper_spi.h" "epaper_spi/epaper_spi.h" >}} - [ESPHome Display Rendering Engine](/components/display#display-engine) +- {{< docref "components/lvgl" >}} diff --git a/content/components/display/hub75.md b/content/components/display/hub75.md new file mode 100644 index 0000000000..7202b937b2 --- /dev/null +++ b/content/components/display/hub75.md @@ -0,0 +1,416 @@ +--- +description: "Instructions for setting up HUB75 RGB LED matrix displays." +title: "HUB75 RGB LED Matrix Display" +params: + seo: + description: Instructions for setting up HUB75 RGB LED matrix displays. + image: hub75.svg +--- + +The `hub75` display platform allows you to use HUB75 RGB LED matrix panels with ESPHome. This component uses a high-performance DMA-based driver that provides efficient, low-CPU-overhead driving of LED matrix panels. + +HUB75 displays are RGB LED matrix panels that use parallel row updating to create dynamic, colorful displays. They are commonly available in sizes like 64×32, 64×64, and can be chained together to create larger displays. + +## Hardware Requirements + +**Supported ESP32 Variants:** + +- ESP32 (original) +- ESP32-S2 +- ESP32-S3 +- ESP32-C6 +- ESP32-P4 + +> [!WARNING] +> This component does **NOT** work with ESP32-C3, ESP32-C2, or ESP32-H2. + +**Memory Considerations:** + +- Uses significant internal SRAM for DMA buffering +- Larger displays or longer chains require more memory +- ESP32-S3 with PSRAM can help with memory constraints +- Memory usage increases with panel resolution and chain length + +**Power Supply:** + +- Requires dedicated power supply for the LED panels +- Proper grounding between ESP32 and panel is essential +- Add capacitors to power lines to prevent flickering + +**Supported Panel Types:** + +- "Two scan" panels (1/16 and 1/32 scan rates) +- Panels with various driver chips (FM6124, FM6126A, ICN2038S, MBI5124, DP3246, etc.) + +## Pin Connections + +HUB75 panels use a standard connector with the following pins: + +| HUB75 Pin | Description | ESPHome Config | +|-----------|----------------------|----------------| +| R1 | Red data (top half) | `r1_pin` | +| G1 | Green data (top) | `g1_pin` | +| B1 | Blue data (top) | `b1_pin` | +| R2 | Red data (bottom) | `r2_pin` | +| G2 | Green data (bottom) | `g2_pin` | +| B2 | Blue data (bottom) | `b2_pin` | +| A | Row address bit 0 | `a_pin` | +| B | Row address bit 1 | `b_pin` | +| C | Row address bit 2 | `c_pin` | +| D | Row address bit 3 | `d_pin` | +| E | Row address bit 4 | `e_pin` | +| LAT | Latch/Strobe | `lat_pin` | +| OE | Output Enable | `oe_pin` | +| CLK | Clock | `clk_pin` | +| GND | Ground | N/A | + +> [!NOTE] +> The E pin is only required for 1/32 scan panels (panels with 32 or 64 rows). It can be omitted for 1/16 scan panels. + +> [!TIP] +> Use a [board preset](#board-presets) to automatically configure pins for common hardware, or specify all pins manually if using custom wiring. + +## Usage + +```yaml +# Example using a board preset (recommended) +display: + - platform: hub75 + id: matrix_display + board: adafruit-matrix-portal-s3 + panel_width: 64 + panel_height: 32 + lambda: |- + it.print(0, 0, id(font), "Hello World!"); +``` + +> [!NOTE] +> Unlike some other display components, HUB75 does **NOT** require an SPI bus configuration. It uses DMA internally for efficient display updates. + +## Board Presets + +Board presets automatically configure all pin mappings for popular HUB75 controller boards. This is the recommended approach for supported hardware. + +**Available Board Presets:** + +- **`adafruit-matrix-portal-s3`** - Adafruit Matrix Portal S3 +- **`apollo-automation-m1-rev4`** - Apollo Automation M1 Rev 4 +- **`apollo-automation-m1-rev6`** - Apollo Automation M1 Rev 6 +- **`huidu-hd-wf2`** - Huidu HD-WF2 + +### Using a Board Preset + +```yaml +display: + - platform: hub75 + id: matrix_display + board: adafruit-matrix-portal-s3 + panel_width: 64 + panel_height: 32 +``` + +### Overriding Specific Pins + +You can override individual pins while still using a board preset: + +```yaml +display: + - platform: hub75 + id: matrix_display + board: apollo-automation-m1-rev4 + panel_width: 64 + panel_height: 32 + r2_pin: GPIO21 # Override just one pin + g2_pin: GPIO22 +``` + +### Manual Pin Configuration + +If you're not using a supported board, specify all pins manually: + +```yaml +display: + - platform: hub75 + id: matrix_display + panel_width: 64 + panel_height: 32 + r1_pin: GPIO25 + g1_pin: GPIO26 + b1_pin: GPIO27 + r2_pin: GPIO21 + g2_pin: GPIO22 + b2_pin: GPIO32 + a_pin: GPIO23 + b_pin: GPIO19 + c_pin: GPIO5 + d_pin: GPIO17 + e_pin: GPIO18 # Optional, omit for 1/16 scan panels + lat_pin: GPIO4 + oe_pin: GPIO15 + clk_pin: GPIO16 +``` + +## Configuration Variables + +### Board Configuration (Recommended) + +- **board** (*Optional*, string): Board preset name. One of: `adafruit-matrix-portal-s3`, `apollo-automation-m1-rev4`, `apollo-automation-m1-rev6`, `huidu-hd-wf2`. When specified, automatically configures all pin mappings. + +### Panel Dimensions (Required) + +- **panel_width** (**Required**, int): Width of a single panel in pixels (e.g., `64`). +- **panel_height** (**Required**, int): Height of a single panel in pixels (e.g., `32`). + +### Multi-Panel Layout (Optional) + +For creating larger displays by chaining multiple panels: + +- **layout_rows** (*Optional*, int): Number of panels arranged vertically. Defaults to `1`. +- **layout_cols** (*Optional*, int): Number of panels arranged horizontally. Defaults to `1`. +- **layout** (*Optional*, enum): Physical panel chaining pattern. Defaults to `HORIZONTAL`. One of: + - `HORIZONTAL` - Simple left-to-right horizontal chain (single row) + - `TOP_LEFT_DOWN` - Serpentine: start top-left, rows top→bottom + - `TOP_RIGHT_DOWN` - Serpentine: start top-right, rows top→bottom + - `BOTTOM_LEFT_UP` - Serpentine: start bottom-left, rows bottom→top + - `BOTTOM_RIGHT_UP` - Serpentine: start bottom-right, rows bottom→top + - `TOP_LEFT_DOWN_ZIGZAG` - Zigzag: start top-left (all panels upright) + - `TOP_RIGHT_DOWN_ZIGZAG` - Zigzag: start top-right (all panels upright) + - `BOTTOM_LEFT_UP_ZIGZAG` - Zigzag: start bottom-left (all panels upright) + - `BOTTOM_RIGHT_UP_ZIGZAG` - Zigzag: start bottom-right (all panels upright) + +> [!NOTE] +> The total display size will be `panel_width × layout_cols` by `panel_height × layout_rows` pixels. + +### Panel Hardware (Optional) + +- **scan_wiring** (*Optional*, enum): Panel scan wiring pattern. Defaults to `STANDARD_TWO_SCAN`. One of: + - `STANDARD_TWO_SCAN` - Standard 1/16 or 1/32 scan (most common) + - `FOUR_SCAN_16PX_HIGH` - Four-scan for 16px high panels + - `FOUR_SCAN_32PX_HIGH` - Four-scan for 32px high panels + - `FOUR_SCAN_64PX_HIGH` - Four-scan for 64px high panels + +- **shift_driver** (*Optional*, enum): LED shift register driver chip type. Defaults to `GENERIC`. One of: + - `GENERIC` - Standard shift register (default) + - `FM6124` - FM6124 driver + - `FM6126A` - FM6126A / ICN2038S driver (very common) + - `ICN2038S` - Alias for FM6126A + - `MBI5124` - MBI5124 driver (requires `clock_phase: true`) + - `DP3246` - DP3246 driver + +### Display Configuration (Optional) + +- **brightness** (*Optional*, int): Initial brightness level (0-255). Defaults to `128`. +- **bit_depth** (*Optional*, int): Color bit depth (6-12). Higher values = better color accuracy but slower refresh. Defaults to `8`. +- **gamma_correct** (*Optional*, enum): Gamma correction mode. One of: + - `LINEAR` - No gamma correction (raw values) + - `CIE1931` - CIE 1931 perceptual curve (recommended for most displays) + - `GAMMA_2_2` - Standard 2.2 gamma curve +- **double_buffer** (*Optional*, boolean): Enable double buffering to prevent tearing. Defaults to `false`. Set to `false` when using LVGL. +- **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): Display update frequency. Defaults to `16ms` (~60 FPS). Set to `never` when using LVGL. +- **min_refresh_rate** (*Optional*, int): Minimum panel refresh rate in Hz (40-200). The panel may refresh faster than this, but won't go slower. Auto-calculated from `update_interval` (defaults to 60 Hz when `update_interval: never`). Rarely needs to be set manually. + +### Pin Configuration + +**Required when `board` is not specified:** + +- **r1_pin** ([Pin Schema](/guides/configuration-types#pin-schema)): Red data pin for top half. +- **g1_pin** ([Pin Schema](/guides/configuration-types#pin-schema)): Green data pin for top half. +- **b1_pin** ([Pin Schema](/guides/configuration-types#pin-schema)): Blue data pin for top half. +- **r2_pin** ([Pin Schema](/guides/configuration-types#pin-schema)): Red data pin for bottom half. +- **g2_pin** ([Pin Schema](/guides/configuration-types#pin-schema)): Green data pin for bottom half. +- **b2_pin** ([Pin Schema](/guides/configuration-types#pin-schema)): Blue data pin for bottom half. +- **a_pin** ([Pin Schema](/guides/configuration-types#pin-schema)): Row address bit 0. +- **b_pin** ([Pin Schema](/guides/configuration-types#pin-schema)): Row address bit 1. +- **c_pin** ([Pin Schema](/guides/configuration-types#pin-schema)): Row address bit 2. +- **d_pin** ([Pin Schema](/guides/configuration-types#pin-schema)): Row address bit 3. +- **e_pin** (*Optional*, [Pin Schema](/guides/configuration-types#pin-schema)): Row address bit 4. Required for 1/32 scan panels (32+ rows), omit for 1/16 scan panels. +- **lat_pin** ([Pin Schema](/guides/configuration-types#pin-schema)): Latch/strobe pin. +- **oe_pin** ([Pin Schema](/guides/configuration-types#pin-schema)): Output enable pin. +- **clk_pin** ([Pin Schema](/guides/configuration-types#pin-schema)): Clock pin. + +### Advanced Timing (Optional) + +- **clock_speed** (*Optional*, enum): Output clock speed. Defaults to `20MHZ`. One of: + - `8MHZ` - 8 MHz + - `10MHZ` - 10 MHz + - `16MHZ` - 16 MHz + - `20MHZ` - 20 MHz (default) + +- **latch_blanking** (*Optional*, int): Number of clock cycles OE is blanked during LAT pulse. Defaults to `1`. +- **clock_phase** (*Optional*, boolean): Invert clock phase. Defaults to `false`. Required to be `true` for MBI5124 driver. + +### Standard Display Options + +All standard [graphical display configuration](/components/display#display-configuration) options are also available, including **lambda**, **pages**, **rotation**, and **auto_clear_enabled**. + +## Multi-Panel Layouts + +You can chain multiple panels together to create larger displays. The component supports both simple horizontal chains and complex 2D grid arrangements. + +### Horizontal Chain + +For a simple left-to-right horizontal chain, use `layout_cols`: + +```yaml +# Three 64x32 panels chained horizontally = 192x32 total +display: + - platform: hub75 + id: matrix_display + board: adafruit-matrix-portal-s3 + panel_width: 64 + panel_height: 32 + layout_cols: 3 + layout: HORIZONTAL +``` + +### 2D Grid Layouts + +For panels arranged in rows and columns, specify both `layout_rows` and `layout_cols`, along with the appropriate `layout` pattern: + +```yaml +# Four 64x32 panels in 2x2 grid = 128x64 total +display: + - platform: hub75 + id: matrix_display + board: adafruit-matrix-portal-s3 + panel_width: 64 + panel_height: 32 + layout_rows: 2 + layout_cols: 2 + layout: TOP_LEFT_DOWN_ZIGZAG +``` + +> [!TIP] +> **Serpentine layouts** (e.g., `TOP_LEFT_DOWN`) physically rotate alternate rows upside down to minimize cable length. **Zigzag layouts** (e.g., `TOP_LEFT_DOWN_ZIGZAG`) keep all panels upright but require longer cables between rows. + +## Using with LVGL + +When using this display with {{< docref "/components/lvgl/index" "LVGL" >}}, you must configure the display as follows: + +```yaml +display: + - platform: hub75 + id: matrix_display + board: adafruit-matrix-portal-s3 + panel_width: 64 + panel_height: 32 + update_interval: never + auto_clear_enabled: false + double_buffer: false + # LVGL configuration goes separately +``` + +The three key settings for LVGL are: + +- `update_interval: never` - LVGL controls when to update (minimum refresh rate auto-defaults to 60 Hz) +- `auto_clear_enabled: false` - LVGL handles clearing +- `double_buffer: false` - LVGL manages its own buffering + +## Configuration Examples + +### Basic Single Panel (with Board Preset) + +```yaml +display: + - platform: hub75 + id: matrix_display + board: adafruit-matrix-portal-s3 + panel_width: 64 + panel_height: 32 + lambda: |- + it.print(0, 0, id(font), "Hello!"); +``` + +### Horizontally Chained Panels + +```yaml +# Three 64x32 panels chained horizontally = 192x32 total +display: + - platform: hub75 + id: matrix_display + board: apollo-automation-m1-rev4 + panel_width: 64 + panel_height: 32 + layout_cols: 3 + layout: HORIZONTAL + lambda: |- + it.printf(0, 0, id(font), "Width: %d", it.get_width()); +``` + +### Manual Pin Configuration + +```yaml +# Using custom pins without a board preset +display: + - platform: hub75 + id: matrix_display + panel_width: 64 + panel_height: 32 + r1_pin: GPIO25 + g1_pin: GPIO26 + b1_pin: GPIO27 + r2_pin: GPIO21 + g2_pin: GPIO22 + b2_pin: GPIO32 + a_pin: GPIO23 + b_pin: GPIO19 + c_pin: GPIO5 + d_pin: GPIO17 + e_pin: GPIO18 # Required for 1/32 scan panels + lat_pin: GPIO4 + oe_pin: GPIO15 + clk_pin: GPIO16 +``` + +### Advanced Configuration with Shift Driver + +```yaml +display: + - platform: hub75 + id: matrix_display + board: adafruit-matrix-portal-s3 + panel_width: 64 + panel_height: 32 + shift_driver: FM6126A + clock_speed: 20MHZ + brightness: 200 + bit_depth: 10 + latch_blanking: 2 + lambda: |- + it.fill(Color(255, 0, 0)); # Red background +``` + +### 2×2 Grid Layout + +```yaml +# Four 64x32 panels in a 2x2 grid = 128x64 total +display: + - platform: hub75 + id: matrix_display + board: adafruit-matrix-portal-s3 + panel_width: 64 + panel_height: 32 + layout_rows: 2 + layout_cols: 2 + layout: TOP_LEFT_DOWN_ZIGZAG + lambda: |- + it.printf(32, 28, id(font), "128x64"); +``` + +## Important Notes + +- **ESP32 support**: This component works with ESP32, ESP32-S2, ESP32-S3, ESP32-C6, and ESP32-P4. It does NOT work with ESP32-C3, ESP32-C2, or ESP32-H2. +- **Memory limitations**: The DMA buffer can consume significant RAM. Larger displays or longer panel chains may not fit in available memory. ESP32-S3 with PSRAM is recommended for large installations. +- **Board presets**: Using a board preset is the easiest way to get started. It automatically configures all pins correctly for popular hardware. +- **Pin configuration**: If not using a board preset, all pins (except `e_pin`) must be specified manually. There are no default pin values. +- **Driver compatibility**: Different panels use different shift register chips. If colors appear wrong or the display doesn't work, try different `shift_driver` settings. FM6126A/ICN2038S is very common in modern panels. +- **Power supply**: Always use a dedicated power supply for the panels. LED matrices can draw significant current (multiple amps for larger displays). +- **E pin requirement**: The E pin is required for 1/32 scan panels (32 or 64 rows). It can be omitted for 1/16 scan panels (16 rows). +- **Clock phase**: MBI5124 driver requires `clock_phase: true` to function correctly. + +## See Also + +- {{< docref "index/" >}} +- {{< docref "/components/lvgl/index" "LVGL Component" >}} +- {{< apiref "hub75/hub75_component.h" "hub75/hub75_component.h" >}} +- [HUB75 ESP32 Driver Library](https://github.com/stuartparmenter/hub75-esp32) diff --git a/content/components/display/images/hub75.svg b/content/components/display/images/hub75.svg new file mode 100644 index 0000000000..b801755bb2 --- /dev/null +++ b/content/components/display/images/hub75.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/content/components/display/mipi_dsi.md b/content/components/display/mipi_dsi.md index 0093e7f11f..89a76af8f6 100644 --- a/content/components/display/mipi_dsi.md +++ b/content/components/display/mipi_dsi.md @@ -43,6 +43,7 @@ specified, or a custom init sequence can be provided. | Model | Manufacturer | Product Description | | ---------------------- | ------------ | ----------------------------------------------------------------------------- | | JC1060P470 | Guition | | +| JC4880P443 | Guition | | | M5STACK-TAB5 | M5Stack | | | WAVESHARE-P4-NANO-10.1 | Waveshare | | | WAVESHARE-P4-86-PANEL | Waveshare | | diff --git a/content/components/display/mipi_rgb.md b/content/components/display/mipi_rgb.md index bd069c8564..dbdf76e6cf 100644 --- a/content/components/display/mipi_rgb.md +++ b/content/components/display/mipi_rgb.md @@ -40,7 +40,7 @@ These boards have completely pre-filled configurations for the display driver, s option is `model`. | Board | Driver Chip | Manufacturer | Product link | -|------------------------------| ----------- | ------------ | ---------------------------------------------------------------- | +|------------------------------|-------------| ------------ |------------------------------------------------------------------| | GUITION-4848S040 | ST7701s | Guition | | | T-PANEL-S3 | ST7701s | Lilygo | | | T-RGB-2.1 | ST7701s | Lilygo | | @@ -48,6 +48,7 @@ option is `model`. | SEEED-INDICATOR-D1 | ST7701s | Seeed Studio | | | ESP32-S3-TOUCH-LCD-4.3 | RPI | Waveshare | | | ESP32-S3-TOUCH-LCD-7-800X480 | RPI | Waveshare | | +| WAVESHARE-3.16-320X820 | ST7701s | Waveshare | | | WAVESHARE-4-480X480 | RPI | Waveshare | | | WAVESHARE-5-1024X600 | RPI | Waveshare | | diff --git a/content/components/display/mipi_spi.md b/content/components/display/mipi_spi.md index 00a482acbe..37dd3130b8 100644 --- a/content/components/display/mipi_spi.md +++ b/content/components/display/mipi_spi.md @@ -61,7 +61,8 @@ using an octal SPI bus, so references here to parallel and octal SPI are equival | ------------------------------------ | ------------ | ----------------------------------------------------------------- | | ADAFRUIT-S2-TFT-FEATHER | Adafruit | | | ADAFRUIT-FUNHOUSE | Adafruit | | -| M5CORE | M5Stack | | +| M5CORE | M5Stack | | +| M5CORE2 | M5Stack | | | S3BOX | Espressif | | | S3BOXLITE | Espressif | | | WAVESHARE-4-TFT | Waveshare | | @@ -73,6 +74,7 @@ using an octal SPI bus, so references here to parallel and octal SPI are equival | JC3248W535 | Guition | | | JC3636W518 | Guition | | | JC3636W518V2 | Guition | | +| JC4827W543 | Guition | | | LANBON-L8 | Lanbon | | | T4-S3 | Lilygo | | | T-EMBED | Lilygo | | diff --git a/content/components/esp32.md b/content/components/esp32.md index d1dbce9bc4..c990d89e90 100644 --- a/content/components/esp32.md +++ b/content/components/esp32.md @@ -18,7 +18,7 @@ esp32: ## Configuration variables - **variant** (*Optional*, string): The ESP32 mcu/chip to use for this device configuration. One of `esp32`, - `esp32s2`, `esp32s3`, `esp32c2`, `esp32c3`, `esp32c5`, `esp32c6`, `esp32h2` or `esp32p4`. + `esp32s2`, `esp32s3`, `esp32c2`, `esp32c3`, `esp32c5`, `esp32c6`, `esp32c61`, `esp32h2` or `esp32p4`. This must match the hardware in use, or it will fail to flash. - **board** (*Optional*, string): The PlatformIO board ID that should be used. Choose the appropriate board from @@ -64,7 +64,7 @@ esp32: ### ESP-IDF Framework -ESP-IDF is Espressif's native development framework. It is required for ESP32-C2, ESP32-C5, ESP32-C6, +ESP-IDF is Espressif's native development framework. It is required for ESP32-C2, ESP32-C5, ESP32-C6, ESP32-C61, ESP32-H2, and ESP32-P4 variants, as these are not supported by the Arduino framework. It is recommended for all ESP32 chips when possible. See the {{< docref "/guides/esp32_arduino_to_idf" "migration guide" >}} for help transitioning from Arduino. @@ -78,7 +78,7 @@ esp32: ### Configuration variables -- **type** (*Optional*, string): The framework type, either `esp-idf` or `arduino`. Defaults to `arduino` for ESP32 (classic), ESP32-C3, ESP32-S2, and ESP32-S3. Defaults to `esp-idf` for ESP32-C2, ESP32-C5, ESP32-C6, ESP32-H2, and ESP32-P4 (Arduino is not supported on these variants) +- **type** (*Optional*, string): The framework type, either `esp-idf` or `arduino`. Defaults to `arduino` for ESP32 (classic), ESP32-C3, ESP32-S2, and ESP32-S3. Defaults to `esp-idf` for ESP32-C2, ESP32-C5, ESP32-C6, ESP32-C61, ESP32-H2, and ESP32-P4 (Arduino is not supported on these variants) - **version** (*Optional*, string): The base framework version number to use, from [ESP32 ESP-IDF releases](https://github.com/espressif/esp-idf/releases) or @@ -198,6 +198,25 @@ The following options disable unused VFS features to save flash memory: future storage components) automatically enable it regardless of this setting. Disabling this saves approximately 0.5 KB+ of flash. Defaults to `true` (VFS directory support disabled to save flash). +**FreeRTOS Memory Options:** + +- **freertos_in_iram** (*Optional*, boolean): Keep FreeRTOS functions in IRAM instead of moving them to flash. By default, + non-ISR FreeRTOS functions are placed in flash to save up to 8 KB of IRAM. ISR-safe functions (`FromISR` variants) always + remain in IRAM. Testing on ESP-IDF 5.5 with Bluetooth proxies shows no performance difference thanks to fast XIP (execute + in place) from flash. Bluetooth proxies are one of the most IRAM-intensive and timing-sensitive use cases, which is likely + why Espressif made this the default in IDF 6.0. This matches + the default behavior in ESP-IDF 6.0 where `CONFIG_FREERTOS_PLACE_FUNCTIONS_INTO_FLASH` is removed and replaced by + `CONFIG_FREERTOS_IN_IRAM` to restore the old behavior (see [ESP-IDF 6.0 breaking changes](https://github.com/espressif/esp-idf/issues/17052) + and [migration guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/migration-guides/release-6.x/6.0/system.html#memory-placement)). + Set to `true` only if you encounter issues with code that incorrectly calls FreeRTOS functions from ISRs with flash cache + disabled. Defaults to `false` (FreeRTOS functions in flash to save IRAM). + +- **ringbuf_in_iram** (*Optional*, boolean): Keep ring buffer functions in IRAM instead of moving them to flash. By default, + ring buffer functions are placed in flash to save ~1.5 KB of IRAM. Ring buffer functions are typically only called every + ~10ms for audio components, so the overhead of loading from flash vs IRAM is negligible compared to actual data processing. + This matches the default behavior in ESP-IDF 6.0 (see [migration guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/migration-guides/release-6.x/6.0/system.html#id1)). + Set to `true` only if you encounter issues. Defaults to `false` (ring buffer functions in flash to save IRAM). + Some options can be disabled to save flash memory without affecting typical ESPHome functionality. The performance options (defaulting to `true` ) improve socket operation performance but can be disabled if you need better multi-threaded scalability (which is uncommon since ESPHome uses an event loop). @@ -231,15 +250,39 @@ esp32: The `components` option allows you to include IDF components. These components will then be compiled into the resulting firmware and may be used by [lambdas](/automations/templates#config-lambda). The most common usage of this option is to include third-party -components that are available in the [ESP Component Registry](https://components.espressif.com/). They can be added by -listing their name under this option. It is also possible to use specific versions, or to fetch components from a file or -git repository. +components that are available in the [ESP Component Registry](https://components.espressif.com/). + +### Simple + +For components from the ESP Component Registry, you can use the shorthand syntax `owner/component^version`: + +```yaml +esp32: + framework: + components: + - espressif/esp_hosted^2.6.1 +``` + +### Advanced + +For more complex configurations (custom git repositories, local paths, etc.), use the advanced syntax: + +```yaml +esp32: + framework: + components: + - name: my_custom_component + source: https://github.com/user/component.git + ref: main + path: components/custom +``` + +#### Configuration Variables - **name** (*Required*, string): Name of the component e.g. `espressif/esp_hosted`. - **ref** (*Optional*, string): Component registry version or a git ref. - **source** (*Optional*, string): The git repository to use for the component. This can be used for a custom or patched version of the component. - - **path** (*Optional*, string): The path of the component in the git repository or a local path to the component if `source` is not set. diff --git a/content/components/ethernet.md b/content/components/ethernet.md index ceaab53aba..b451e9df90 100644 --- a/content/components/ethernet.md +++ b/content/components/ethernet.md @@ -59,6 +59,7 @@ ethernet: - `W5500` (SPI) - `OPENETH` (QEMU, ESP-IDF only) - `DM9051` (SPI, ESP-IDF only) + - `LAN8670` (RMII) ### RMII configuration variables @@ -268,7 +269,7 @@ ethernet: power_pin: GPIO5 ``` -**wESP32**: +**Silicognition wESP32**: ```yaml # for board up to rev.5 @@ -299,6 +300,30 @@ ethernet: > [!NOTE] > Revision 5 and below of the wESP32 board use the LAN8720 Ethernet PHY. Revision 7 and newer of it use the RTL8201 Ethernet PHY. +**Silicognition ManT1S**: + +```yaml +ethernet: + type: LAN8670 + mdc_pin: + number: GPIO8 + ignore_pin_validation_error: true + mdio_pin: + number: GPIO7 + ignore_pin_validation_error: true + clk: + pin: + number: GPIO0 + ignore_strapping_warning: true + mode: CLK_EXT_IN + phy_addr: 0 +``` + +> [!NOTE] +> The `ignore_pin_validation_error` options are required for the MDC and MDIO pins, since the pin +> validator assumes these pins are used for flash. However, this board uses the ESP32-PICO-V3-02 +> module, which has these pins available for other uses, so this check needs to be disabled. + **OpenHacks LAN8720**: ```yaml diff --git a/content/components/i2c.md b/content/components/i2c.md index 3e6c80827f..d8b93e01de 100644 --- a/content/components/i2c.md +++ b/content/components/i2c.md @@ -10,9 +10,10 @@ params: {{< anchor "i2c" >}} This component sets up the I²C bus for your ESP32, ESP8266, RP2040 or NRF52. In order for these components -to work correctly, you need to define the I²C bus in your configuration. Please note the ESP -will enable its internal 10kΩ pullup resistors for these pins, so you usually don't need to -put on external ones. You can use multiple devices on one I²C bus as each device is given a +to work correctly, you need to define the I²C bus in your configuration. On ESP32 (both Arduino and ESP-IDF +frameworks), internal pullup resistors are enabled by default. On ESP8266, the internal 10kΩ pullup resistors +are always enabled. External pullups are still recommended for longer wire runs or multiple devices. +You can use multiple devices on one I²C bus as each device is given a unique address for communicating between it and the ESP. You can do this by hopping wires from the two lines (SDA and SCL) from each device board to the next device board or by connecting the wires from each device back to the two I²C pins on the ESP. @@ -43,8 +44,17 @@ i2c: NRF52 supports only `100kHz` and `400kHz`. - **timeout** (*Optional*, [Time](/guides/configuration-types#time)): Set the I²C bus timeout. - Defaults to the framework defaults (`100us` on `esp32` with `esp-idf`, `50ms` on `esp32` with `Arduino`, - `1s` on `esp8266` and `1s` on `rp2040` ). Maximum on `esp-idf` is 13ms. + Defaults to the framework defaults (`100us` on `esp32`, `1s` on `esp8266` and `1s` on `rp2040`). + Maximum on `esp32` is 13ms. + +- **sda_pullup_enabled** (*Optional*, boolean): Enable the internal pullup resistor for the SDA pin. + Defaults to `true`. Only available on ESP32. + +- **scl_pullup_enabled** (*Optional*, boolean): Enable the internal pullup resistor for the SCL pin. + Defaults to `true`. Only available on ESP32. + +- **low_power_mode** (*Optional*, boolean): Enable the low-power (master only) I²C bus. + Only availible on ESP32C5, ESP32C6 and ESP32P4. Defaults to `false` unless required. - **id** (*Optional*, [ID](/guides/configuration-types#id)): Manually specify the ID for this I²C bus if you need multiple I²C buses. diff --git a/content/components/images/cc1101-full.webp b/content/components/images/cc1101-full.webp new file mode 100644 index 0000000000..f99bf15e97 Binary files /dev/null and b/content/components/images/cc1101-full.webp differ diff --git a/content/components/light/esp32_rmt_led_strip.md b/content/components/light/esp32_rmt_led_strip.md index cec865d8f8..f540d5fc52 100644 --- a/content/components/light/esp32_rmt_led_strip.md +++ b/content/components/light/esp32_rmt_led_strip.md @@ -61,6 +61,7 @@ light: | ESP32-C3 | 96 symbols | 48 symbols | | ESP32-C5 | 96 symbols | 48 symbols | | ESP32-C6 | 96 symbols | 48 symbols | +| ESP32-C61 | 96 symbols | 48 symbols | | ESP32-H2 | 96 symbols | 48 symbols | | ESP32-P4 | 192 symbols | 48 symbols | | ESP32-S2 | 256 symbols | 64 symbols | diff --git a/content/components/logger.md b/content/components/logger.md index c76b79e6bb..8c3c36b3f6 100644 --- a/content/components/logger.md +++ b/content/components/logger.md @@ -91,6 +91,7 @@ so if you use any other configuration you will not get log messages over the on- | ESP32-C3 | TX: 21, RX: 20 | N/A | Undefined | N/A | N/A | 18/19 | | ESP32-C5 | TX: 10, RX: 11 | N/A | Undefined | N/A | N/A | 13/14 | | ESP32-C6 | TX: 16, RX: 17 | N/A | Undefined | N/A | N/A | 12/13 | +| ESP32-C61 | TX: 5, RX: 4 | N/A | Undefined | N/A | N/A | 12/13 | | ESP32-P4 | TX: 37, RX: 38 | N/A | TX: 10, RX: 11 | N/A | N/A | 24/25 | | ESP32-S2 | TX: 43, RX: 44 | N/A | TX: 17, RX: 18 | N/A | 19/20 | N/A | | ESP32-S3 | TX: 43, RX: 44 | N/A | TX: 17, RX: 18 | Undefined | 19/20 | 19/20 | @@ -114,6 +115,7 @@ the original ESP32 or ESP8266) continue to use USB-to-serial bridge ICs for comm | ESP32-C3 | `USB_SERIAL_JTAG` | | ESP32-C5 | `USB_SERIAL_JTAG` | | ESP32-C6 | `USB_SERIAL_JTAG` | +| ESP32-C61 | `USB_SERIAL_JTAG` | | ESP32-P4 | `USB_SERIAL_JTAG` | | ESP32-S2 | `USB_CDC` | | ESP32-S3 | `USB_SERIAL_JTAG` | diff --git a/content/components/lvgl/_index.md b/content/components/lvgl/_index.md index 830bd72096..8777d7f747 100644 --- a/content/components/lvgl/_index.md +++ b/content/components/lvgl/_index.md @@ -131,6 +131,11 @@ The following configuration variables apply to the main `lvgl` component, in ord > - If you press the encoder on a complex object (like a list, message box, etc.) the object will go to edit mode whereby you can adjust the value of the object by turning the encoder. > - To leave edit mode, long press the button. +- **update_when_display_idle** (*Optional*, boolean): When using the {{< docref "/components/display/epaper_spi" >}} + or other displays with long update times, setting this option + to `true` will cause the display to only be updated if the display is idle. During the update LVGL will pause. + The display `update_interval` should be set to `never` when this is used, as the display will be updated automatically + by LVGL. - **resume_on_input** (*Optional*, boolean): If LVGL is paused and the user interacts with the screen, resume the activity of LVGL. Defaults to `true`. "Interacts" means to release a touch or button, or rotate an encoder. - **color_depth** (*Optional*, string): The color depth at which the contents are generated. Currently only `16` is supported (RGB565, 2 bytes/pixel), which is the default value. - **buffer_size** (*Optional*, percentage): The percentage of screen size to allocate buffer memory. If unconfigured, the default is `100%` with runtime fallback to `12%` if a full size buffer allocation fails. For devices without PSRAM, the recommended value is `25%`. diff --git a/content/components/lvgl/layouts.md b/content/components/lvgl/layouts.md index 85f474b5fa..bbfda33bde 100644 --- a/content/components/lvgl/layouts.md +++ b/content/components/lvgl/layouts.md @@ -41,6 +41,9 @@ The configuration `layout: horizontal` is a shorthand for a flex layout: flex_align_cross: stretch ``` +In addition, if the option `pad_all` is set on the container (thus applying padding to the outside) the same +padding will be applied between the columns, i.e. `pad_column` will be set. + ### Vertical Layout The configuration `layout: vertical` is a shorthand for a flex layout: @@ -54,6 +57,8 @@ The configuration `layout: vertical` is a shorthand for a flex layout: flex_align_cross: stretch ``` +Similarly to the `horizontal` layout, using `pad_all` on the container will also apply that padding between rows. + ### Flex The Flex layout in LVGL is a subset implementation @@ -156,11 +161,15 @@ distribute the free space proportionally. them. If one of the items has a value of 2, that one would take up twice as much of the space as either one of the others. +**Cell positioning:** + Child widgets can be placed on the grid using the `grid_cell_row_pos` and `grid_cell_column_pos` configuration variables. If either is specified both must be specified. If neither is specified the widget will be placed in the first available position, in a row-major order. Row and column spans will be taken into account when reserving space. +Two or more widgets may not be explicitly assigned the same row and column positions unless the option +`multiple_widgets_per_cell` is set to `true`. #### Shorthand @@ -181,9 +190,9 @@ columns, with all rows and columns of equal size. For example `layout: 2x3` is a pixels. Possible options below. - **pad_row** (*Optional*, int16): Set the padding between the rows, in pixels. - **pad_column** (*Optional*, int16): Set the padding between the columns, in pixels. +- **multiple_widgets_per_cell** (*Optional*, bool): If true, multiple widgets can be placed in the same cell. Defaults to `false`. -In a grid layout, *all the widgets placed on the grid* can have some additional configuration variables to help with -placement: +In a grid layout, all child widgets placed on the grid have additional configuration options available: - **grid_cell_row_pos** (*Optional*, int16): Position of the widget, in which row to appear (0 based count). - **grid_cell_column_pos** (*Optional*, int16): Position of the widget, in which column to appear (0 based count). diff --git a/content/components/lvgl/widgets.md b/content/components/lvgl/widgets.md index 6b2df21aa8..f74f7900ac 100644 --- a/content/components/lvgl/widgets.md +++ b/content/components/lvgl/widgets.md @@ -38,7 +38,12 @@ The properties below are common to all widgets. - `"ON"` : Always show the scroll bars (use the double quotes!). - `"ACTIVE"` : Show scroll bars while a widget is being scrolled. - `"AUTO"` : Show scroll bars when the content is large enough to be scrolled (default). - +- **scroll_dir** (*Optional*, string): Sets the permissible scroll directions for an object - one of `LEFT`, `RIGHT`, + `BOTTOM`, `TOP`, `HOR`, `VER`, `ALL` (default). +- **scroll_snap_x** (*Optional*, string): For a child of a scrollable object, this property defines the snap position + of the child in the X direction. One of `NONE` (default), `START`, `END`, `CENTER`. +- **scroll_snap_y** (*Optional*, string): For a child of a scrollable object, this property defines the snap position + of the child in the Y direction. One of `NONE` (default), `START`, `END`, `CENTER`. - **align** (*Optional*, enum): Alignment of the widget relative to the parent. A child widget is clipped to its parent boundaries. One of the values *not* starting with `OUT_` (see picture below). - **align_to** (*Optional*, list): Alignment of the widget relative to another widget on the same level: - **id** (**Required**): The ID of a widget *to* which you want to align. @@ -282,16 +287,16 @@ The arc consists of a background and a foreground arc. The indicator foreground - **arc_opa** (*Optional*, [opacity](/components/lvgl#lvgl-opacity)): Opacity of the arc. - **arc_rounded** (*Optional*, boolean): Make the end points of the arcs rounded. `true` rounded, `false` perpendicular line ending. - **arc_width** (*Optional*, int16): Set the width of the arcs in pixels. -- **change_rate** (*Optional*, int8): If the arc is pressed the current value will set with a limited speed according to the set change rate. The change rate is defined in degree/second. Defaults to `720`. +- **change_rate** (*Optional*, uint16): Limits the speed at which the arc value changes when touched or dragged. The change rate is defined in degree/second. Defaults to `720`. - **end_angle** (*Optional*, 0-360): end angle of the arc background (see note). Defaults to `45`. - **indicator** (*Optional*, list): Settings for the indicator *part* to show the value. Supports a list of [styles](/components/lvgl#lvgl-styling) and state-based styles to customize. Draws *another arc using the arc style* properties. Its padding values are interpreted relative to the background arc. - **knob** (*Optional*, list): Settings for the knob *part* to control the value. Supports a list of [styles](/components/lvgl#lvgl-styling) and state-based styles to customize. Draws a handle on the end of the indicator using all background properties and padding values. With zero padding the knob size is the same as the indicator's width. Larger padding makes it larger, smaller padding makes it smaller. -- **max_value** (*Optional*, int8): Maximum value of the indicator. Defaults to `100`. -- **min_value** (*Optional*, int8): Minimum value of the indicator. Defaults to `0`. +- **max_value** (*Optional*, int16): Maximum value of the indicator. Defaults to `100`. +- **min_value** (*Optional*, int16): Minimum value of the indicator. Defaults to `0`. - **mode** (*Optional*, string): `NORMAL` : the indicator is drawn from the minimum value to the current. `REVERSE` : the indicator is drawn counter-clockwise from the maximum value to the current. `SYMMETRICAL` : the indicator is drawn from the middle point to the current value. Defaults to `NORMAL`. - **rotation** (*Optional*, 0-360): Offset to the 0 degree position. Defaults to `0.0`. - **start_angle** (*Optional*, 0-360): start angle of the arc background (see note). Defaults to `135`. -- **value** (*Optional*, int8): Actual value of the indicator at start, in `0` -`100` range. Defaults to `0`. +- **value** (*Optional*, int16): Actual value of the indicator at start, in `0` -`100` range. Defaults to `0`. - Any [Styling](/components/lvgl#lvgl-styling) and state-based option to override styles inherited from parent. The arc's size and position will respect the padding style properties. If the `adv_hittest` [flag](#lvgl-widget-flags) is enabled the arc can be clicked through in the middle. Clicks are recognized only on the ring of the background arc. @@ -303,7 +308,14 @@ If the `adv_hittest` [flag](#lvgl-widget-flags) is enabled the arc can be clicke - `lvgl.arc.update` [action](/automations/actions#actions-action) updates the widget styles and properties from the specific options above, just like the [lvgl.widget.update](#lvgl-automation-actions) action is used for the common styles, states or flags. - **id** (**Required**): The ID or a list of IDs of arc widgets to be updated. - - **value** (*Optional*, int8): New value of the indicator. + - **change_rate** (*Optional*, uint16): New change rate in degree/second. + - **end_angle** (*Optional*, 0-360): New end angle of the arc background. + - **max_value** (*Optional*, int16): New maximum value of the indicator. + - **min_value** (*Optional*, int16): New minimum value of the indicator. + - **mode** (*Optional*, string): New indicator mode. + - **rotation** (*Optional*, 0-360): New offset to the 0 degree position. + - **start_angle** (*Optional*, 0-360): New start angle of the arc background. + - **value** (*Optional*, int16): New value of the indicator. - Any [Styling](/components/lvgl#lvgl-styling) and state-based option to override styles inherited from parent. The arc's size and position will respect the padding style properties. **Triggers:** @@ -417,9 +429,17 @@ Simple push (momentary) or toggle (two-states) button. {{< img src="lvgl_button.png" alt="Image" class="align-center" >}} +A button has no inherent content so requires child widgets to be added. As a shorthand for a button with a single text label, +the `text:` option may be used to add a single `label` child, otherwise the `widgets:` key must be used to add other +widgets inside the button. + +A button is momentary by default, which has a `pressed` state. If the `checkable` flag is set, it becomes a toggle button, which also has a `checked` state. + **Configuration variables:** -- **checkable** (*Optional*, boolean): A significant [flag](#lvgl-widget-flags) to make a toggle button (which remains pressed in `checked` state). Defaults to `false`. +- **checkable** (*Optional*, boolean): A significant [flag](#lvgl-widget-flags) to make a toggle button (which reports its `checked` state). Defaults to `false`. +- **text** (*Optional*, string): Text to be displayed on the button. This will create and add a single label widget to the button. May not be used + with the `widgets:` key. - Style options from [Style properties](/components/lvgl#lvgl-styling) for the background of the button. Uses the typical background style properties. A notable state is `checked` (boolean) which can have different styles applied. @@ -433,30 +453,22 @@ A notable state is `checked` (boolean) which can have different styles applied. **Example:** ```yaml -# Example widget: +# Example widget with text: - button: - x: 10 - y: 10 - width: 50 - height: 30 id: btn_id + text: "Click me!" ``` -To have a button with a text label on it, add a child [`label`](#lvgl-widget-label) widget to it: +To create an image button, add a child [`image`](#lvgl-widget-image) widget to it: ```yaml -# Example toggle button with text: +# Example toggle button with image: - button: - x: 10 - y: 10 - width: 70 - height: 30 id: btn_id checkable: true widgets: - - label: - align: center - text: "Light" + - image: + src: my_image_id # Example trigger: - button: @@ -466,12 +478,37 @@ To have a button with a text label on it, add a child [`label`](#lvgl-widget-lab - logger.log: format: "Button checked state: %d" args: [ x ] + ``` The `button` can be also integrated as a {{< docref "/components/binary_sensor/lvgl" "Binary Sensor" >}} or as a {{< docref "/components/switch/lvgl" "Switch" >}} component. +> [!NOTE] +> A binary sensor linked to a button reports its `pressed` state, while a switch linked to a button reports its `checked` state. See [Remote light button](/cookbook/lvgl#lvgl-cookbook-binent) for an example which demonstrates how to use a checkable button to act on a Home Assistant service. +**Actions:** + +- `lvgl.button.update` [action](/automations/actions#actions-action) may be used to update the button styles at runtime. If + the button has a `text:` option then it may also be updated with this action. + - **id** (**Required**): The ID or a list of IDs of button widgets to be updated. + - **text** (*Optional*, string): Update the button's text (only if the button was configured with the `text:` option). + - Style options from [Style properties](/components/lvgl#lvgl-styling) for the background of the button. + + > [!NOTE] + > Where other widgets are added as children, they must be updated directly. + +```yaml +# Text update example +- button: + id: btn_id + text: "Click me!" + on_click: + lvgl.button.update: + id: btn_id + text: "Clicked" +``` + {{< anchor "lvgl-widget-buttonmatrix" >}} ## `buttonmatrix` diff --git a/content/components/micronova.md b/content/components/micronova.md index 45915537f5..b49a5fbea1 100644 --- a/content/components/micronova.md +++ b/content/components/micronova.md @@ -49,16 +49,14 @@ micronova: ### Configuration variables - **enable_rx_pin** (**Required**, [Pin](/guides/configuration-types#pin)): Output pin to be used to switch the line between RX and TX. -- **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval that the sensors should be checked. - Defaults to 60 seconds. > [!NOTE] > For all text sensors, sensors, numbers, buttons and switches hereafter most of the the default **memory_location** and **memory_address** parameters will work so you should > not specify them. However your Micronova boad may require you to specify alternate values. So every text sensor, button, > switch or number accepts these parameters: > -> - **memory_location** (*Optional*): The memory location where the parameter must be read. For most stoves this is 0x00 for RAM -> or 0x20 for EPROM. +> - **memory_location** (*Optional*): The memory location for the parameter (0x00 for RAM, 0x20 for EPROM on most stoves). +> The write bit is set automatically when writing. > > - **memory_address** (*Optional*): The address where the parameter is stored. @@ -74,7 +72,8 @@ text_sensor: ### Configuration variables - **stove_state** (*Optional*): The current stove state. - All options from [Text Sensor](/components/text_sensor#config-text_sensor). + - **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval that the sensors should be checked. Defaults to 60 seconds. + - All options from [Text Sensor](/components/text_sensor#config-text_sensor). ## Sensors @@ -103,27 +102,36 @@ sensor: ### Configuration variables - **room_temperature** (*Optional*): Sensor that reads the stoves ambient room temperature. - All options from [Sensor](/components/sensor). + - **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval that the sensors should be checked. Defaults to 60 seconds. + - All options from [Sensor](/components/sensor). - **fumes_temperature** (*Optional*): Fumes temperature. - All options from [Sensor](/components/sensor). + - **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval that the sensors should be checked. Defaults to 60 seconds. + - All options from [Sensor](/components/sensor). - **stove_power** (*Optional*): Current stove power. - All options from [Sensor](/components/sensor). + - **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval that the sensors should be checked. Defaults to 60 seconds. + - All options from [Sensor](/components/sensor). - **fan_speed** (*Optional*): Current fan speed. The raw value from the stove is multiplied by 10 + `fan_rpm_offset`. - - **fan_rpm_offset** (*Optional*, integer): Offset the reported RPM value. Must be between 0 and 255. Defaults to 0. + - **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval that the sensors should be checked. Defaults to 60 seconds. - All other options from [Sensor](/components/sensor). -- **water_temperature** (*Optional*): Internal boiler water termperature. - All options from [Sensor](/components/sensor). + +- **water_temperature** (*Optional*): Internal boiler water temperature. + - **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval that the sensors should be checked. Defaults to 60 seconds. + - All options from [Sensor](/components/sensor). - **water_pressure** (*Optional*): Internal boiler water pressure. - All options from [Sensor](/components/sensor). + - **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval that the sensors should be checked. Defaults to 60 seconds. + - All options from [Sensor](/components/sensor). -- **memory_address_sensor** (*Optional*): Can be any **memory_location** / **memory_address** you want to track. Usefull - when you don't know where the parameter is for your stove is. - All options from [Sensor](/components/sensor). +- **memory_address_sensor** (*Optional*): Can be any **memory_location** / **memory_address** you want to track. Useful + when you don't know where the parameter for your stove is. + - **memory_location** (**Required**): The memory location for the parameter (0x00 for RAM, 0x20 for EPROM on most stoves). + - **memory_address** (**Required**): The address where the parameter is stored. + - **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval that the sensors should be checked. Defaults to 60 seconds. + - All options from [Sensor](/components/sensor). ## Numbers @@ -141,15 +149,11 @@ number: - **thermostat_temperature** (*Optional*): Number that holds the current stove thermostat value. - **step** (*Optional*): Temperature step. This value is used to multiply/devide the raw value when setting/reading the **thermostat_temperature** + - **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval that the sensors should be checked. Defaults to 60 seconds. - All other options from [Number](/components/number#config-number). - **power_level** (*Optional*): Number that sets/reads the requested stove power. - All options from [Number](/components/number#config-number). - -> [!NOTE] -> Besides **memory_location** and **memory_address** you can specify a specific **memory_write_location** parameter. -> This parameter is a hex value for the **memory_location** where the new thermostat value must be written. -> -> - **memory_write_location** (*Optional*): The **memory_location** where to write the new thermostat value. + - **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval that the sensors should be checked. Defaults to 60 seconds. + - All options from [Number](/components/number#config-number). ## Buttons @@ -167,11 +171,9 @@ button: - **custom_button** (*Optional*): Write the hex value **memory_data** to a **memory_location** and **memory_address** All options from [Button](/components/button#config-button). - -> [!NOTE] -> Besides **memory_location** and **memory_address** you must specify a specific **memory_data** parameter. -> -> - **memory_data** (**Required**): The hex value to be written to the **memory_location** and **memory_address**. + - **memory_location** (**Required**): The memory location for the parameter (0x00 for RAM, 0x20 for EPROM on most stoves). The write bit is set automatically. + - **memory_address** (**Required**): The address where the parameter is stored. + - **memory_data** (**Required**): The hex value to be written to the **memory_location** and **memory_address**. ## Switches @@ -185,8 +187,10 @@ switch: ### Configuration variables - **stove** (*Optional*): Turn the stove on or off. This switch will also reflect the current stove state. - If the **stove_state** is "Off" the switch will be off, in all other states, the switch wil be on. - All options from [Switch](/components/switch#config-switch). + If the **stove_state** is "Off" the switch will be off, in all other states, the switch will be on. + - **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval at which the state should + be checked. Defaults to 60 seconds. + - All options from [Switch](/components/switch#config-switch). > [!NOTE] > Besides **memory_location** and **memory_address** you can specify specific **memory_data_on** and **memory_data_off** parameters. diff --git a/content/components/nrf52.md b/content/components/nrf52.md index 2778ae164d..75e347aa3c 100644 --- a/content/components/nrf52.md +++ b/content/components/nrf52.md @@ -22,6 +22,11 @@ nrf52: - **board** (*Required*, string): The board type. Valid options are `adafruit_feather_nrf52840`, `adafruit_itsybitsy_nrf52840`, `xiao_ble`. Other boards should work with those configuration as well. - **bootloader** (*Optional*, string): Bootloader type. Valid options are `mcuboot`, `adafruit`, `adafruit_nrf52_sd132`, `adafruit_nrf52_sd140_v6`, `adafruit_nrf52_sd140_v7`. Default value depends on board type. +- **dcdc** (*Optional*, boolean): Enable DC/DC converter for REG1 stage. Defaults to `true`. +External LC filters must be connected to the DC/DC regulator pins if it is being used. +The advantage of using a DC/DC regulator is that the overall power consumption is normally reduced +as the efficiency of such a regulator is higher than that of a LDO. +⚠️ Warning: Enabling DC/DC may cause the board to fail to boot if external LC filter is misconfigured or is poor quality. ## Getting Started diff --git a/content/components/openthread.md b/content/components/openthread.md index 5a1ff11f1c..5f63cc87c9 100644 --- a/content/components/openthread.md +++ b/content/components/openthread.md @@ -18,7 +18,7 @@ This component allows ESPHome nodes to communicate with Home Assistant over a Th ## Usage -This component requires an ESP32 (ESP32-C6 or ESP32-H2 because they have Thread radio chip) and the use of +This component requires an ESP32 (ESP32-C5, ESP32-C6, or ESP32-H2 because they have Thread radio chip) and the use of ESP-IDF. ```yaml diff --git a/content/components/output/pca9685.md b/content/components/output/pca9685.md index ac5bea4a24..c3704033cd 100644 --- a/content/components/output/pca9685.md +++ b/content/components/output/pca9685.md @@ -53,6 +53,22 @@ output: channel: 0 ``` +```yaml +# Example configuration entry with disabled phase_balancer +pca9685: + - id: pca9685_hub1 + phase_balancer: none + +# Individual outputs +output: + - platform: pca9685 + pca9685_id: 'pca9685_hub1' + channel: 0 + - platform: pca9685 + pca9685_id: 'pca9685_hub1' + channel: 1 +``` + ### Configuration variables - **frequency** (*Optional*, float): The frequency to let the @@ -66,6 +82,20 @@ output: - **id** (*Optional*, [ID](/guides/configuration-types#id)): The id to use for this pca9685 component. Use this if you have multiple PCA9685s connected at the same time +- **phase_balancer** (*Optional*, string): The phase balancer algorithm to use. + See [Phase Balancer](#phase-balancer) below. + +### Phase Balancer + +The PCA9685 allows setting different phase angles on each output. The following algorithms can be used +to set the phase angle of each output: + +- `linear` (default): The phase angle is set by distributing all defined outputs equally among 360°. + So with 3 outputs the first would have 0°, the second 120° and the last 240°. This algorithm can + cause flickering when animating the light, because the PCA9685 chip will need an additional frame + where no PWM is generated if the start angle is higher than the stop angle. +- `none`: The phase angle is always 0°. This is the safer option if you control LED lights. + {{< anchor "pca9685-output" >}} ## PCA9685 Output diff --git a/content/components/packages.md b/content/components/packages.md index 29d223287f..7783df4920 100644 --- a/content/components/packages.md +++ b/content/components/packages.md @@ -23,9 +23,11 @@ merged by concatenation. All other configuration values are replaced with the la ESPHome uses `!include` to "bring in" packages from other files; this feature is described in [!include](/guides/yaml#yaml-include). -The `packages:` key may have a value that is a list of valid package references, or a mapping of keys to package references. -When a mapping is used, the keys are for reference only and have no significance in themselves. -Where only a single package reference is required, it may be used directly rather than in a list. +The `packages:` key may have a value that is: + +- A list of valid package references +- A mapping of keys to package references. When a mapping is used, the keys are for reference only and have no significance in themselves. + Examples of all formats are shown below. ## Local Packages @@ -186,14 +188,40 @@ sensor: ``` ```yaml -# only one package is included here, no need for a list -packages: !include common.yaml +packages: + - !include common.yaml sensor: - id: !extend uptime_sensor update_interval: 10s ``` +LVGL-style configuration hierarchies are also supported: + +```yaml +# In interface.yaml +lvgl: + pages: + - id: main_page + widgets: + - label: + id: title_label + text: "Main Page" +``` + +```yaml +packages: + - !include interface.yaml +lvgl: + pages: + - id: !extend main_page + widgets: + - label: + id: !extend title_label + text: "New Title" + text_color: red +``` + `!extend` also works with substitutions and jinja: ```yaml @@ -229,16 +257,31 @@ the ID of the entry to modify. For example, to remove a common uptime sensor that is shared between configurations: ```yaml -packages: !include common.yaml # see above +packages: + - !include common.yaml # see above sensor: - id: !remove uptime_sensor ``` +Remove an item in a LVGL-style configuration: + +```yaml +packages: + - !include interface.yaml # see above +lvgl: + pages: + - id: !extend main_page + widgets: + - label: + id: !remove title_label +``` + To remove captive portal for a specific device: ```yaml -packages: !include common.yaml # see above +packages: + - !include common.yaml # see above captive_portal: !remove ``` diff --git a/content/components/prometheus.md b/content/components/prometheus.md index b6ad3bdcdb..60ef05e582 100644 --- a/content/components/prometheus.md +++ b/content/components/prometheus.md @@ -52,6 +52,8 @@ prometheus: - Switch - Lock - Text Sensor +- Text +- Event - Number - Select - Media Player @@ -92,6 +94,92 @@ prometheus: name: "Angry Pixies" ``` +## Example Metrics + +Here's an example of *some* of the many prometheus metrics available: + +```text +#TYPE esphome_sensor_value gauge +#TYPE esphome_sensor_failed gauge +esphome_sensor_failed{id="dev_idf_prometheus_goober_wifi_signal_db",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober WiFi Signal dB"} 0 +esphome_sensor_value{id="dev_idf_prometheus_goober_wifi_signal_db",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober WiFi Signal dB",unit="dBm"} -35 +esphome_sensor_failed{id="dev_idf_prometheus_goober_wifi_signal_percent",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober WiFi Signal Percent"} 0 +esphome_sensor_value{id="dev_idf_prometheus_goober_wifi_signal_percent",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober WiFi Signal Percent",unit="Signal %"} 100 +esphome_sensor_failed{id="dev_idf_prometheus_goober_uptime_sensor",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober Uptime Sensor"} 0 +esphome_sensor_value{id="dev_idf_prometheus_goober_uptime_sensor",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober Uptime Sensor",unit="s"} 4 +esphome_sensor_failed{id="dev_idf_prometheus_goober_uptime_timestamp",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober Uptime Timestamp"} 1 +esphome_sensor_failed{id="dev_idf_prometheus_goober_esphome_internal_temperature",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober ESPHome Internal Temperature"} 0 +esphome_sensor_value{id="dev_idf_prometheus_goober_esphome_internal_temperature",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober ESPHome Internal Temperature",unit="°C"} 33.1 +esphome_sensor_failed{id="heap_free",area="Dev",node="devidfprometheus",name="Heap Free"} 0 +esphome_sensor_value{id="heap_free",area="Dev",node="devidfprometheus",name="Heap Free",unit="B"} 224724 +esphome_sensor_failed{id="heap_max_block",area="Dev",node="devidfprometheus",name="Heap Max Block"} 0 +esphome_sensor_value{id="heap_max_block",area="Dev",node="devidfprometheus",name="Heap Max Block",unit="B"} 147456 +esphome_sensor_failed{id="loop_time",area="Dev",node="devidfprometheus",name="Loop Time"} 0 +esphome_sensor_value{id="loop_time",area="Dev",node="devidfprometheus",name="Loop Time",unit="ms"} 17 +esphome_sensor_failed{id="cpu_frequency",area="Dev",node="devidfprometheus",name="CPU Frequency"} 0 +esphome_sensor_value{id="cpu_frequency",area="Dev",node="devidfprometheus",name="CPU Frequency",unit="Hz"} 160000000 +#TYPE esphome_binary_sensor_value gauge +#TYPE esphome_binary_sensor_failed gauge +esphome_binary_sensor_failed{id="dev_idf_prometheus_goober_button",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober Button"} 0 +esphome_binary_sensor_value{id="dev_idf_prometheus_goober_button",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober Button"} 0.000000 +esphome_binary_sensor_failed{id="dev_idf_prometheus_goober_connected_status",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober Connected Status"} 0 +esphome_binary_sensor_value{id="dev_idf_prometheus_goober_connected_status",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober Connected Status"} 0.000000 +#TYPE esphome_light_state gauge +#TYPE esphome_light_color gauge +#TYPE esphome_light_effect_active gauge +esphome_light_state{id="dev_idf_prometheus_goober_light",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober Light"} 0.000000 +esphome_light_color{id="dev_idf_prometheus_goober_light",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober Light",channel="brightness"} 0.000000 +esphome_light_color{id="dev_idf_prometheus_goober_light",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober Light",channel="r"} 0.000000 +esphome_light_color{id="dev_idf_prometheus_goober_light",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober Light",channel="g"} 0.000000 +esphome_light_color{id="dev_idf_prometheus_goober_light",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober Light",channel="b"} 0.000000 +esphome_light_color{id="dev_idf_prometheus_goober_light",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober Light",channel="w"} 0.000000 +esphome_light_effect_active{id="dev_idf_prometheus_goober_light",area="Dev",node="devidfprometheus",name="Dev IDF Prometheus Goober Light",effect="None"} 0 +#TYPE esphome_switch_value gauge +#TYPE esphome_switch_failed gauge +esphome_switch_failed{id="beta_firmware",area="Dev",node="devidfprometheus",name="Beta firmware"} 0 +esphome_switch_value{id="beta_firmware",area="Dev",node="devidfprometheus",name="Beta firmware"} 0.000000 +#TYPE esphome_text_sensor_value gauge +#TYPE esphome_text_sensor_failed gauge +esphome_text_sensor_failed{id="esphome_version_detailed",area="Dev",node="devidfprometheus",name="ESPHome Version Detailed"} 0 +esphome_text_sensor_value{id="esphome_version_detailed",area="Dev",node="devidfprometheus",name="ESPHome Version Detailed",value="2025.8.0b1 Aug 16 2025, 13:48:52"} 1.0 +esphome_text_sensor_failed{id="esphome_version",area="Dev",node="devidfprometheus",name="ESPHome Version"} 0 +esphome_text_sensor_value{id="esphome_version",area="Dev",node="devidfprometheus",name="ESPHome Version",value="2025.8.0b1"} 1.0 +esphome_text_sensor_failed{id="esphome_project_version",area="Dev",node="devidfprometheus",name="ESPHome Project Version"} 0 +esphome_text_sensor_value{id="esphome_project_version",area="Dev",node="devidfprometheus",name="ESPHome Project Version",value="4.13.8"} 1.0 +esphome_text_sensor_failed{id="esphome_project_version_detailed",area="Dev",node="devidfprometheus",name="ESPHome Project Version Detailed"} 0 +esphome_text_sensor_value{id="esphome_project_version_detailed",area="Dev",node="devidfprometheus",name="ESPHome Project Version Detailed",value="4.13.8 Aug 16 2025, 13:48:52"} 1.0 +esphome_text_sensor_failed{id="esphome_board",area="Dev",node="devidfprometheus",name="ESPHome Board"} 0 +esphome_text_sensor_value{id="esphome_board",area="Dev",node="devidfprometheus",name="ESPHome Board",value="esp32-s3-devkitc-1"} 1.0 +esphome_text_sensor_failed{id="esphome_board_variant",area="Dev",node="devidfprometheus",name="ESPHome Board Variant"} 0 +esphome_text_sensor_value{id="esphome_board_variant",area="Dev",node="devidfprometheus",name="ESPHome Board Variant",value="ESP32-S3"} 1.0 +esphome_text_sensor_failed{id="esphome_framework_type",area="Dev",node="devidfprometheus",name="ESPHome Framework Type"} 0 +esphome_text_sensor_value{id="esphome_framework_type",area="Dev",node="devidfprometheus",name="ESPHome Framework Type",value="ESP-IDF"} 1.0 +esphome_text_sensor_failed{id="esphome_idf_version",area="Dev",node="devidfprometheus",name="ESPHome IDF Version"} 0 +esphome_text_sensor_value{id="esphome_idf_version",area="Dev",node="devidfprometheus",name="ESPHome IDF Version",value="5.4.2"} 1.0 +esphome_text_sensor_failed{id="reset_reason",area="Dev",node="devidfprometheus",name="Reset Reason"} 0 +esphome_text_sensor_value{id="reset_reason",area="Dev",node="devidfprometheus",name="Reset Reason",value="USB peripheral"} 1.0 +#TYPE esphome_number_value gauge +#TYPE esphome_number_failed gauge +esphome_number_failed{id="template_number",area="Dev",node="devidfprometheus",name="Template number"} 0 +esphome_number_value{id="template_number",area="Dev",node="devidfprometheus",name="Template number"} 0.000000 +#TYPE esphome_select_value gauge +#TYPE esphome_select_failed gauge +esphome_select_failed{id="template_select",area="Dev",node="devidfprometheus",name="Template select"} 0 +esphome_select_value{id="template_select",area="Dev",node="devidfprometheus",name="Template select",value="two"} 1.0 +#TYPE esphome_update_entity_state gauge +#TYPE esphome_update_entity_info gauge +#TYPE esphome_update_entity_failed gauge +esphome_update_entity_failed{id="firmware_update",area="Dev",node="devidfprometheus",name="Firmware Update"} 1 +#TYPE esphome_text_value gauge +#TYPE esphome_text_failed gauge +esphome_text_failed{id="template_text",area="Dev",node="devidfprometheus",name="Template text"} 0 +esphome_text_value{id="template_text",area="Dev",node="devidfprometheus",name="Template text",value="Hello World"} 1.0 +#TYPE esphome_event_value gauge +#TYPE esphome_event_failed gauge +esphome_event_failed{id="template_event",area="Dev",node="devidfprometheus",name="Template Event"} 0 +esphome_event_value{id="template_event",area="Dev",node="devidfprometheus",name="Template Event",last_event_type="custom_event_1"} 1.0 +``` + ## See Also - {{< docref "/components/web_server" >}} diff --git a/content/components/psram.md b/content/components/psram.md index afc496d82a..d3ce9aba88 100644 --- a/content/components/psram.md +++ b/content/components/psram.md @@ -23,7 +23,7 @@ psram: ## Configuration variables - **mode** (*Optional*): Defines the operating mode the PSRAM should utilize. One of `quad`, `octal` or `hex`. - Defaults to `quad` for ESP32 and `hex` for ESP32-P4. ESP32-S3 has no default and *requires* this option to be set. + Defaults to `quad` for ESP32, ESP32-C5, ESP32-S2 and `hex` for ESP32-P4. ESP32-S3 has no default and *requires* this option to be set. See notes below. - **speed** (*Optional*, int): The speed at which the PSRAM should operate. One of `40MHz` (default), `80MHz` or `120MHz`. - **enable_ecc** (*Optional*, bool): For octal mode, enable ECC (Error Correction Code) for the PSRAM (default is off.) @@ -39,7 +39,7 @@ psram: ## Modes -The ESP32 PSRAM is only available in `quad` mode, and ESP32-P4 only supports `hex` mode. These are the defaults +The ESP32, ESP32-C5 and ESP32-S2 PSRAM is only available in `quad` mode, and ESP32-P4 only supports `hex` mode. These are the defaults when using those variants. For ESP32-S3, the `mode` option is required and must be set to `quad` or `octal`. Typically on ESP32-S3 modules, a 2MB PSRAM will use quad mode, while 8 or 16MB will use octal mode, but check the datasheet for the module you are using to be sure. diff --git a/content/components/remote_receiver.md b/content/components/remote_receiver.md index 9e69d7809a..0f5eb58a3d 100644 --- a/content/components/remote_receiver.md +++ b/content/components/remote_receiver.md @@ -110,6 +110,7 @@ Multiple remote receivers can be configured as a list of dict definitions within | ESP32-C3 | 96 symbols | 48 symbols | | ESP32-C5 | 96 symbols | 48 symbols | | ESP32-C6 | 96 symbols | 48 symbols | +| ESP32-C61 | 96 symbols | 48 symbols | | ESP32-H2 | 96 symbols | 48 symbols | | ESP32-P4 | 192 symbols | 48 symbols | | ESP32-S2 | 256 symbols | 64 symbols | diff --git a/content/components/remote_transmitter.md b/content/components/remote_transmitter.md index 37ed63f367..85071e9cb2 100644 --- a/content/components/remote_transmitter.md +++ b/content/components/remote_transmitter.md @@ -51,6 +51,7 @@ remote_transmitter: | ESP32-C3 | 96 symbols | 48 symbols | | ESP32-C5 | 96 symbols | 48 symbols | | ESP32-C6 | 96 symbols | 48 symbols | +| ESP32-C61 | 96 symbols | 48 symbols | | ESP32-H2 | 96 symbols | 48 symbols | | ESP32-P4 | 192 symbols | 48 symbols | | ESP32-S2 | 256 symbols | 64 symbols | diff --git a/content/components/sensor/adc.md b/content/components/sensor/adc.md index e048b732cf..b6c7b4b6c7 100644 --- a/content/components/sensor/adc.md +++ b/content/components/sensor/adc.md @@ -86,6 +86,7 @@ To simplify this, we provide the setting `attenuation: auto` for an automatic/se | ESP32-C3 | GPIO0 - GPIO4 | GPIO5 | | ESP32-C5 | GPIO1 - GPIO6 | no `ADC2` | | ESP32-C6 | GPIO0 - GPIO6 | no `ADC2` | +| ESP32-C61 | GPIO1, GPIO3 - GPIO5 | no `ADC2` | | ESP32-H2 | GPIO1 - GPIO5 | no `ADC2` | | ESP32-S2 | GPIO1 - GPIO10 | GPIO11 - GPIO20 | | ESP32-S3 | GPIO1 - GPIO10 | GPIO11 - GPIO20 | @@ -94,7 +95,7 @@ To simplify this, we provide the setting `attenuation: auto` for an automatic/se Different ESP32 variants use different ADC calibration methods: - Original ESP32 (non-variant) & ESP32-S2: Use line-fitting calibration -- ESP32-C3, ESP32-C5, ESP32-C6, ESP32-H2, ESP32-S3 & ESP32-P4: Use curve-fitting calibration +- ESP32-C3, ESP32-C5, ESP32-C6, ESP32-C61, ESP32-H2, ESP32-S3 & ESP32-P4: Use curve-fitting calibration This is handled automatically by the code, but it's worth noting if you're debugging ADC readings or need to understand the calibration process. diff --git a/content/components/sensor/hc8.md b/content/components/sensor/hc8.md new file mode 100644 index 0000000000..140533a43e --- /dev/null +++ b/content/components/sensor/hc8.md @@ -0,0 +1,79 @@ +--- +description: "Instructions for setting up HC8 CO2 sensors" +title: "HC8 CO₂ Sensor" +params: + seo: + description: Instructions for setting up HC8 CO2 sensors + image: hc8.png +--- + +The `hc8` sensor platform allows you to use HC8 CO₂ sensors. + +{{< img src="hc8-full.png" alt="HC8 CO₂ Sensor" caption="HC8 CO₂ Sensor." width="50.0%" class="align-center" >}} + +As the communication with the HC8 sensor is done using UART, you need +to have an [UART bus](/components/uart) in your configuration with the `rx_pin` connected to the TX pin of the +HC8 and the `tx_pin` connected to the RX Pin of the HC8 (it's switched because the +TX/RX labels are from the perspective of the HC8). Additionally, you need to set the baud rate to 9600. + +```yaml +# Example configuration entry +sensor: + - platform: hc8 + co2: + name: HC8 CO2 Value +``` + +## Configuration Variables + +- **co2** (*Optional*): The CO₂ data from the sensor in parts per million (ppm). + All options from [Sensor](/components/sensor). + +- **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval to check the + sensor. Defaults to `60s`. + +- **uart_id** (*Optional*, [ID](/guides/configuration-types#id)): Manually specify the ID of the [UART Component](/components/uart) if you want + to use multiple UART buses. + +- **id** (*Optional*, [ID](/guides/configuration-types#id)): Manually specify the ID used for actions. + +- **warmup_time** (*Optional*, [Time](/guides/configuration-types#time)): The sensor has a warmup period during which it returns inaccurate readings (e.g., 500ppm, 505ppm). This setting discards readings until the warmup time has elapsed (returning `NaN` during warmup). The datasheet specifies a 10-minute preheating time for full accuracy, with 90% accuracy achieved after 3 minutes. Empirical evidence shows that reasonable values are usually returned after about 1 minute. Defaults to `75s`. + +{{< anchor "hc8-calibrate_action" >}} + +## `hc8.calibrate` Action + +This [action](/automations/actions#all-actions) executes baseline calibration command on the sensor with the given ID. + +Before executing baseline calibration, ensure the HC8 sensor has been operating in a stable gas environment +(with known CO₂ concentration) for at least 2 minutes. + +**Warning:** Only calibrate the sensor in a known stable environment (e.g., outdoors or in a well-ventilated room). +Incorrect calibration will result in inaccurate readings. + +```yaml +on_...: + then: + - hc8.calibrate: + id: my_hc8_id + baseline: 420 # Current outdoor CO₂ level +``` + +You can provide an [action](/components/api#api-device-actions) to perform from Home Assistant + +```yaml +api: + actions: + - action: hc8_calibrate + variables: + my_baseline: int + then: + - hc8.calibrate: + id: my_hc8_id + baseline: !lambda 'return my_baseline;' +``` + +## See Also + +- [Sensor Filters](/components/sensor#sensor-filters) +- {{< apiref "hc8/hc8.h" "hc8/hc8.h" >}} diff --git a/content/components/sensor/hlw8032.md b/content/components/sensor/hlw8032.md new file mode 100644 index 0000000000..a06c283591 --- /dev/null +++ b/content/components/sensor/hlw8032.md @@ -0,0 +1,100 @@ +--- +description: "Instructions for setting up HLW8032 power sensors" +title: "HLW8032 Power Sensor" +params: + seo: + description: Instructions for setting up HLW8032 power sensors + image: hlw8032.png +--- + +The `hlw8032` sensor platform allows you to use your HLW8032 voltage/current and power sensors +([datasheet](https://datasheet.lcsc.com/lcsc/2307271600_Hiliwei-Tech-HLW8032_C128023.pdf)) with +ESPHome. This sensor is commonly found in M5Stack modules. + +{{< img src="images/hlw8032.png" alt="HLW8032 board" width="50.0%" class="align-center" >}} + +> [!WARNING] +> SAFETY HAZARD: Some devices have the digital GND connected directly to mains +> voltage so **the GPIOs become LIVE during normal operation**. Our advice is to mark these boards to prevent +> any use of the dangerous digital pins. UART TX pin is usually connected to the MCU via optocoupler. + +The HLW8032 IC measures a single phase's voltage (using a voltage divider) and current (using a shunt) +and additionally provides active and apparent power and power factor measurements. + +As the communication with the HLW8032 is done using UART, you need +to have a [UART bus](/components/uart) in your configuration with the `rx_pin` connected to the HLW8032. +Additionally, you need to set the baud rate to `4800` and the `EVEN` parity. The device sends multiple +updates per second, so you will probably want some sort of averaging or throttle filter on the sensors. + +```yaml +# Example configuration entry +uart: + rx_pin: GPIOXX + baud_rate: 4800 + parity: EVEN + +sensor: + - platform: hlw8032 + voltage: + name: HLW8032 Voltage + id: hlw8032_voltage + current: + name: HLW8032 Current + id: hlw8032_current + power: + name: HLW8032 Power + id: hlw8032_power + apparent_power: + name: HLW8032 Apparent Power + id: hlw8032_apparent_power + power_factor: + name: HLW8032 Power Factor + id: hlw8032_power_factor +``` + +## Configuration variables + +- **current** (*Optional*): Use the current value of the sensor in amperes. + All options from [Sensor](/components/sensor). +- **power** (*Optional*): Use the (active) power value of the sensor in watts. + All options from [Sensor](/components/sensor). +- **voltage** (*Optional*): Use the voltage value of the sensor in V (RMS). + All options from [Sensor](/components/sensor). +- **apparent_power** (*Optional*): Use the apparent power value of the sensor in volt amps. + All options from [Sensor](/components/sensor). +- **power_factor** (*Optional*): Use the power factor value of the sensor. + All options from [Sensor](/components/sensor). +- **uart_id** (*Optional*, [ID](/guides/configuration-types#id)): Manually specify the ID of the [UART Component](/components/uart) if you want + to use multiple UART buses. + +### Advanced Options + +- **current_resistor** (*Optional*, float): The value of the shunt resistor for current measurement. + Default value is `0.001 ohm`. +- **voltage_divider** (*Optional*, float): The value of the voltage divider + on the board as `R_upstream / (R_downstream * 1000)`. Default value is `1.72`. + +## Energy Measurement + +The HLW8032 has a PF (Pulse Frequency) output pin that generates pulses proportional to active energy consumption. +This could be used with the [Pulse Meter](/components/sensor/pulse_meter) component for energy tracking. + +Alternatively, you can use software integration with the power sensor: + +```yaml +sensor: + - platform: hlw8032 + power: + name: HLW8032 Power + id: hlw8032_power + - platform: total_daily_energy + name: "Daily Energy" + power_id: hlw8032_power +``` + +## See Also + +- [Sensor Filters](/components/sensor#sensor-filters) +- [Pulse Meter](/components/sensor/pulse_meter) +- [Total Daily Energy](/components/sensor/total_daily_energy) +- {{< apiref "hlw8032/hlw8032.h" "hlw8032/hlw8032.h" >}} diff --git a/content/components/sensor/images/hc8-full.png b/content/components/sensor/images/hc8-full.png new file mode 100644 index 0000000000..55c3ca9a21 Binary files /dev/null and b/content/components/sensor/images/hc8-full.png differ diff --git a/content/components/sensor/images/hlw8032.png b/content/components/sensor/images/hlw8032.png new file mode 100644 index 0000000000..5357ea2136 Binary files /dev/null and b/content/components/sensor/images/hlw8032.png differ diff --git a/content/components/sensor/images/stts22h.png b/content/components/sensor/images/stts22h.png new file mode 100644 index 0000000000..0dc7aab4b7 Binary files /dev/null and b/content/components/sensor/images/stts22h.png differ diff --git a/content/components/sensor/images/thermopro_tp357-full.jpg b/content/components/sensor/images/thermopro_tp357-full.jpg new file mode 100644 index 0000000000..09413dea3f Binary files /dev/null and b/content/components/sensor/images/thermopro_tp357-full.jpg differ diff --git a/content/components/sensor/mcp3204.md b/content/components/sensor/mcp3204.md index b4fd95a7a1..81838e6f1f 100644 --- a/content/components/sensor/mcp3204.md +++ b/content/components/sensor/mcp3204.md @@ -58,19 +58,48 @@ sensor: id: solar_voltage number: 0 # MCP3204 pin number -# In case MCP3208 is used. you can specify pin number > 4 + # In case MCP3208 is used, you can specify pin number > 4 - platform: mcp3204 # Attached to pin 7 of the MCP3208. id: supply_voltage number: 7 # MCP3208 pin number + + # Measures difference between CH0 (IN+) and CH1 (IN-) + - platform: mcp3204 # Differential pair on pins 0-1. + id: thermocouple_voltage + number: 0 + diff_mode: true ``` ### Configuration variables - **mcp3204_id** (**Required**, [ID](/guides/configuration-types#id)): The id of the parent MCP3204 component. -- **number** (**Required**, int): The pin number of the MCP3204 -- **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval to check the sensor. Defaults to `60s`. +- **number** (**Required**, int): The pin to measure on the MCP3204/MCP3208 +- **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval to check the sensor. + Defaults to `60s`. +- **diff_mode** (*Optional*, boolean): Enable differential mode measurement. Defaults to `false`. - All other options from [Sensor](/components/sensor). +## Operating Modes + +The MCP3204/3208 supports two input configurations: + +### Single-Ended Mode (default) + +Each channel measures voltage independently relative to ground. The MCP3204 provides 4 channels, +and MCP3208 provides 8 channels. This is the default operating mode when `diff_mode` is not +specified or set to `false`. + +### Differential Mode + +When `diff_mode: true`, channel pairs measure the voltage difference between two inputs (IN+ and +IN-). Specify the positive input channel number with the `number` parameter. The next sequential +channel automatically becomes the negative input (IN-). + +Available differential pairs: + +- MCP3204: 2 pairs (CH0/CH1, CH2/CH3) +- MCP3208: 4 pairs (CH0/CH1, CH2/CH3, CH4/CH5, CH6/CH7) + ## See Also - [SPI Bus](/components/spi) diff --git a/content/components/sensor/sps30.md b/content/components/sensor/sps30.md index aa7aa13dea..0331802eeb 100644 --- a/content/components/sensor/sps30.md +++ b/content/components/sensor/sps30.md @@ -50,6 +50,7 @@ sensor: id: "pm_size" address: 0x69 update_interval: 10s + idle_interval: 5min ``` ## Configuration variables @@ -102,6 +103,9 @@ sensor: - **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval to check the sensor. Defaults to `60s`. +- **idle_interval** (*Optional*, [Time](/guides/configuration-types#time)): If specified, puts the sensor + into idle mode between readings for the specified amount of time. + ## Wiring The sensor has a 5 pin JST ZHR type connector, with a 1.5mm pitch. ([Matching connector housing](https://octopart.com/zhr-5-jst-279203), [datasheet](http://www.farnell.com/datasheets/1393424.pdf)) @@ -147,6 +151,42 @@ sensor: Sensirion recommends cleaning at least once per week. +## Idle Operation Mode + +The SPS30 sensor can go into an idle operation mode where most internal electronics are switched off, +including the fan and laser. This greatly reduces power consumption and can prolong the life of the sensor. + +Specifying an `idle_interval` configuration parameter will automatically stop the sensor for that interval, +wake it when it is time, allow the sensor to warm up for 30 seconds, and take a reading before putting it back +into idle state. + +The start and stop actions below allow users to manually take the sensor in and out of idle mode. +Note that after the sensor is started, it does have a warm-up period of 30 seconds prior to outputting +measurements. + +See [low power documentation](https://sensirion.com/media/documents/188A2C3C/6166F165/Sensirion_Particulate_Matter_AppNotes_SPS30_Low_Power_Operation_D1.pdf) +for more information. + +### Start Measurement Action + +This [action](/automations/actions#all-actions) manually puts the sensor into measurement mode. + +```yaml +on_...: + then: + - sps30.start_measurement: my_sps30 +``` + +### Stop Measurement Action + +This [action](/automations/actions#all-actions) manually puts the sensor into idle mode. + +```yaml +on_...: + then: + - sps30.stop_measurement: my_sps30 +``` + ## See Also - [Sensor Filters](/components/sensor#sensor-filters) diff --git a/content/components/sensor/stts22h.md b/content/components/sensor/stts22h.md new file mode 100644 index 0000000000..6c8a591b6b --- /dev/null +++ b/content/components/sensor/stts22h.md @@ -0,0 +1,49 @@ +--- +description: "Instructions for setting up STTS22H temperature sensor from STMicroelectronics" +title: "STTS22H Temperature Sensor" +params: + seo: + description: Instructions for setting up STTS22H temperature sensor from STMicroelectronics with ESPHome + image: stts22h.png +--- + +The `stts22h` sensor platform allows you to use a STTS22H temperature sensor +([datasheet](https://www.st.com/resource/en/datasheet/stts22h.pdf)) with ESPHome. This is a low-power, +high-accuracy digital temperature sensor with ±0.5°C accuracy (typical at 25°C) and a temperature range +from -40°C to +125°C. + +The [I²C Bus](/components/i2c) is required to be set up in your configuration for this sensor to work. + +{{< img src="stts22h.png" alt="STTS22H Temperature Sensor" +caption="SparkFun STTS22H Temperature Sensor Breakout Boards" class="align-center" >}} + +```yaml +# Example configuration entry +sensor: + - platform: stts22h + name: "STTS22H Temperature" + address: 0x3C + update_interval: 60s +``` + +## Configuration variables + +- **i2c_id** (*Optional*, [ID](/guides/configuration-types#id)): Manually specify the ID of the + [I²C Bus](/components/i2c) if you want to use multiple I²C buses. + +- **address** (*Optional*, int): The I²C address of the sensor. Defaults to + `0x3C`. + The address is determined by the ADDR pin configuration on the sensor. + Possible addresses: `0x38`, `0x3C`, `0x3E`, `0x3F`. + +- **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval to check + the sensor. Defaults to `60s`. + +- All other options from [Sensor](/components/sensor). + +## See Also + +- [Sensor Filters](/components/sensor#sensor-filters) +- [I²C Bus](/components/i2c) +- [STTS22H Datasheet (PDF)](https://www.st.com/resource/en/datasheet/stts22h.pdf) +- [STTS22H Product Overview - STMicroelectronics](https://www.st.com/en/mems-and-sensors/stts22h.html) diff --git a/content/components/sensor/thermopro_ble.md b/content/components/sensor/thermopro_ble.md new file mode 100644 index 0000000000..60c94b2544 --- /dev/null +++ b/content/components/sensor/thermopro_ble.md @@ -0,0 +1,116 @@ +--- +description: "Instructions for setting up ThermoPro Bluetooth-based temperature and humidity sensors in ESPHome." +title: "ThermoPro BLE Sensors" +params: + seo: + description: Instructions for setting up ThermoPro Bluetooth-based temperature and humidity sensors in ESPHome. + image: thermopro_tp357.jpg +--- + +The `thermopro_ble` sensor platform lets you track the output of ThermoPro Bluetooth +Low Energy devices using the {{< docref "/components/esp32_ble_tracker" >}}. This component will track the +temperature, humidity, battery level and signal strength of the ThermoPro device every time the +sensor sends out a BLE broadcast. + +## Supported Devices + +This component supports multiple ThermoPro BLE sensor models: + +- **TP3xx series** (e.g., TP357S): Temperature, humidity, and battery level sensors. Testing has been primarily done with TP357S devices. +- **TP96x series**: Internal and external temperature sensors with battery level monitoring. +- **TP970**: Internal and external temperature sensors with battery level monitoring. +- **TP972**: Internal and external temperature sensors with battery level monitoring. + +All models support signal strength (RSSI) monitoring. + +{{< img src="thermopro_tp357-full.jpg" alt="Image" caption="ThermoPro TP357 Temperature and Humidity Sensor over BLE." width="80.0%" class="align-center" >}} + +```yaml +# Example configuration entry +esp32_ble_tracker: + +sensor: + # TP3xx series example (TP357S with humidity) + - platform: thermopro_ble + mac_address: XX:XX:XX:XX:XX:XX + temperature: + name: "ThermoPro Temperature" + humidity: + name: "ThermoPro Humidity" + battery_level: + name: "ThermoPro Battery Level" + signal_strength: + name: "ThermoPro Signal Strength" + + # TP96x/TP970/TP972 example (with external temperature probe) + # - platform: thermopro_ble + # mac_address: YY:YY:YY:YY:YY:YY + # temperature: + # name: "ThermoPro Internal Temperature" + # external_temperature: + # name: "ThermoPro External Temperature" + # battery_level: + # name: "ThermoPro Battery Level" + # signal_strength: + # name: "ThermoPro Signal Strength" +``` + +## Configuration variables + +- **mac_address** (**Required**, MAC Address): The MAC address of the ThermoPro device. + +- **temperature** (*Optional*): The information for the temperature sensor. + + - All options from [Sensor](/components/sensor#config-sensor). + +- **external_temperature** (*Optional*): The information for the external/probe temperature sensor. + Some models (TP972, TP970, TP96x) support dual temperature readings - one internal and one from an external probe. + + - All options from [Sensor](/components/sensor#config-sensor). + +- **humidity** (*Optional*): The information for the humidity sensor. Only available on TP3xx devices. + + - All options from [Sensor](/components/sensor#config-sensor). + +- **battery_level** (*Optional*): The information for the battery level sensor. + + - All options from [Sensor](/components/sensor#config-sensor). + +- **signal_strength** (*Optional*): The information for the signal strength (RSSI) sensor. + + - All options from [Sensor](/components/sensor#config-sensor). + +## Setting Up Devices + +To set up ThermoPro devices you first need to find their MAC Address so that ESPHome can +identify them. So first, create a simple configuration without any `thermopro_ble` entries +like so: + +```yaml +esp32_ble_tracker: + on_ble_advertise: + - then: + - lambda: 'ESP_LOGD("ble_adv", "BLE device address: %s name: %s", x.address_str().c_str(), x.get_name().c_str());' +``` + +After uploading the ESP32 will immediately try to scan for BLE devices such as the ThermoPro, so +you will see messages like this (please note the TPxxxx model name): + +```log +[13:36:43][D][ble_adv:042]: BLE device address: XX:XX:XX:XX:XX:XX name: TP357S (XXXX) +``` + +Note that it can sometimes take some time for the first BLE broadcast to be received. + +Then just copy the address (`XX:XX:XX:XX:XX:XX`) into a new `sensor.thermopro_ble` platform +entry like in the configuration example at the top. + +> [!NOTE] +> The ThermoPro BLE component listens passively to packets the device sends by itself. +> ESPHome therefore has no impact on the battery life of the device. + +## See Also + +- {{< docref "/components/esp32_ble_tracker" >}} +- {{< docref "/components/sensor" >}} +- {{< apiref "thermopro_ble/thermopro_ble.h" "thermopro_ble/thermopro_ble.h" >}} diff --git a/content/components/sensor/total_daily_energy.md b/content/components/sensor/total_daily_energy.md index 879fe23dce..121efc59d3 100644 --- a/content/components/sensor/total_daily_energy.md +++ b/content/components/sensor/total_daily_energy.md @@ -8,7 +8,7 @@ params: --- The `total_daily_energy` sensor is a helper sensor that can use the power value of -other sensors like the {{< docref "hlw8012" "HLW8012" >}}, {{< docref "cse7766" "CSE7766" >}}, {{< docref "atm90e32" "ATM90E32" >}}, etc and integrate +other sensors like the {{< docref "hlw8012" "HLW8012" >}}, {{< docref "hlw8032" "HLW8032" >}}, {{< docref "cse7766" "CSE7766" >}}, {{< docref "atm90e32" "ATM90E32" >}}, etc and integrate it over time. So this component allows you to convert readings in `W` or `kW` to readings of the total diff --git a/content/components/text_sensor/wifi_info.md b/content/components/text_sensor/wifi_info.md index 078518d765..95d3fd0ca2 100644 --- a/content/components/text_sensor/wifi_info.md +++ b/content/components/text_sensor/wifi_info.md @@ -15,32 +15,34 @@ via text sensors. text_sensor: - platform: wifi_info ip_address: - name: ESP IP Address + name: Device IP Address address_0: - name: ESP IP Address 0 + name: Device IP Address 0 address_1: - name: ESP IP Address 1 + name: Device IP Address 1 address_2: - name: ESP IP Address 2 + name: Device IP Address 2 address_3: - name: ESP IP Address 3 + name: Device IP Address 3 address_4: - name: ESP IP Address 4 + name: Device IP Address 4 ssid: - name: ESP Connected SSID + name: Device Connected SSID bssid: - name: ESP Connected BSSID + name: Device Connected BSSID mac_address: - name: ESP Mac Wifi Address + name: Device Mac Wifi Address scan_results: - name: ESP Latest Scan Results + name: Device Latest Scan Results dns_address: - name: ESP DNS Address + name: Device DNS Address + power_save_mode: + name: Device Wifi Power Save Mode ``` ## Configuration variables -- **ip_address** (*Optional*): Expose the IP Address of the ESP as a text sensor. +- **ip_address** (*Optional*): Expose the IP Address of the device as a text sensor. All options from [Text Sensor](/components/text_sensor#config-text_sensor). - **address_0** (*Optional*): With dual stack (IPv4 and IPv6) the device will have at least two IP addresses, often more. @@ -59,9 +61,11 @@ text_sensor: - **scan_results** (*Optional*): Expose the latest networks found during the latest scan. All options from [Text Sensor](/components/text_sensor#config-text_sensor). -- **dns_address** (*Optional*): Expose the DNS Address of the ESP as text sensor. +- **dns_address** (*Optional*): Expose the DNS Address of the device as text sensor. [Text Sensor](/components/text_sensor#config-text_sensor). +- **power_save_mode** (*Optional*) Expose the WiFi Power save mode of the device as a text sensor. + ## See Also - {{< docref "/components/wifi" >}} diff --git a/content/components/time/bm8563.md b/content/components/time/bm8563.md new file mode 100644 index 0000000000..0ed84e9769 --- /dev/null +++ b/content/components/time/bm8563.md @@ -0,0 +1,114 @@ +--- +description: "BM8563 Time Source" +title: "BM8563 Time Source" +--- + +You first need to set up the {{< docref "/components/i2c" "I2C" >}} component. + +```yaml +# Example configuration entry +time: + - platform: bm8563 + id: bm8563_time +``` + +## Configuration variables + +- **address** (*Optional*, int): Manually specify the I²C address of the RTC. Defaults to `0x51`. +- All other options from [Base Time Configuration](/components/time#base_time_config). + +{{< anchor "bm8563-write_time_action" >}} + +## `bm8563.write_time` Action + +This [Action](/automations/actions#config-action) triggers a synchronization of the current system time to the RTC hardware. + +> [!NOTE] +> The BM8563 component will *not* write the RTC clock if not triggered *explicitly* by this action. + +```yaml +on_...: + - bm8563.write_time + + # in case you need to specify the BM8563 id + - bm8563.write_time: + id: bm8563_time +``` + +{{< anchor "bm8563-read_time_action" >}} + +## `bm8563.read_time` Action + +This [Action](/automations/actions#config-action) triggers a synchronization of the current system time from the RTC hardware. + +> [!NOTE] +> The BM8563 component will automatically read the RTC clock every 15 minutes by default and synchronize the +> system clock when a valid timestamp was read from the RTC. (The `update_interval` can be changed.) +> This action can be used to trigger *additional* synchronizations. + +```yaml +on_...: + - bm8563.read_time + + # in case you need to specify the BM8563 id + - bm8563.read_time: + id: bm8563_time +``` + +{{< anchor "bm8563-start_timer_action" >}} + +## `bm8563.start_timer` Action + +This [Action](/automations/actions#config-action) starts the RTC timer. + +```yaml +on_...: + - bm8563.start_timer: + duration: 60s + + # in case you need to specify the BM8563 id + - bm8563.start_timer: + id: bm8563_time + duration: 60s +``` + +Configuration options: + +- **duration** (**Required**, [Time](/guides/configuration-types#config-time)): The time duration for the timer. +- **id** (*Optional*, [ID](/guides/configuration-types#config-id)): Manually specify the ID of the BM8563 component if you have multiple components. + +{{< anchor "bm8563-config_example" >}} + +## Full Configuration Example + +In a typical setup, you will have at least one additional time source to synchronize the RTC with. Such an +external time source might not always be available e.g. due to a limited network connection. +In order to have a valid, reliable system time, the system should read the RTC once at start and then try to +synchronize with an external reliable time source. +When a synchronization to another time source was successful, the RTC can be resynchronized. + +```yaml +esphome: + on_boot: + then: + # read the RTC time once when the system boots + bm8563.read_time: + +time: + - platform: bm8563 + # repeated synchronization is not necessary unless the external RTC + # is much more accurate than the internal clock + update_interval: never + - platform: homeassistant + # instead try to synchronize via network repeatedly ... + on_time_sync: + then: + # ... and update the RTC when the synchronization was successful + bm8563.write_time: +``` + +## See Also + +- {{< docref "/components/i2c" "I2C Bus" >}} +- {{< docref "/components/time" "Time Component" >}} +- {{< docref "/components/deep_sleep" "Deep Sleep Component" >}} diff --git a/content/components/usb_cdc_acm.md b/content/components/usb_cdc_acm.md new file mode 100644 index 0000000000..3baa1569a7 --- /dev/null +++ b/content/components/usb_cdc_acm.md @@ -0,0 +1,69 @@ +--- +description: "Instructions for setting up USB CDC-ACM virtual serial ports on ESP32 variants in ESPHome" +title: "USB CDC-ACM Interface" +params: + seo: + description: Instructions for setting up USB CDC-ACM virtual serial ports on ESP32 variants in ESPHome + image: usb.svg +--- + +The USB CDC-ACM (Communications Device Class - Abstract Control Model) component enables supported devices to function +as USB virtual serial ports. When connected to a host computer, the microcontroller will appear as one or +more serial/COM ports, allowing serial communication with the application running on the microcontroller. + +You must have {{< docref "/components/tinyusb" >}} in your device's configuration to use this component. + +The following ESP32 microcontroller variants are currently supported: + +- ESP32-P4 +- ESP32-S2 +- ESP32-S3 + +```yaml +# Example minimal configuration entry +usb_cdc_acm: +``` + +## Configuration variables + +- **rx_buffer_size** (*Optional*, int): Size of the USB receive buffer in bytes. Range: 1-65535. Defaults to `256`. +- **tx_buffer_size** (*Optional*, int): Size of the USB transmit buffer in bytes. Range: 1-65535. Defaults to `256`. +- **interfaces** (*Optional*, list): List of CDC-ACM interface instances. Up to two are supported; at least one is + required. Defaults to a single-item list which defines a single interface only. + +## Interface configuration variables + +Each interface in the `interfaces` list consists of the following: + +- **id** (*Optional*, [ID](/guides/configuration-types#config-id)): The ID to use for this interface instance. This is + used to refer to the interface in other components, platforms or lambdas. + +## Multiple Interface Example + +The USB CDC-ACM component supports up to two simultaneous virtual serial port interfaces on a single device. This +allows you to create multiple independent communication channels over a single physical USB connection. + +```yaml +# Example configuration with two interfaces +usb_cdc_acm: + interfaces: + - id: cdc_acm_1 + - id: cdc_acm_2 +``` + +In this configuration, the device will appear as two separate serial/COM ports to the host computer. Each interface +operates independently with its own data buffers. + +## Buffer Size Considerations + +The buffer sizes determine how much data can be temporarily stored during USB transfers: + +- **Small buffers (256 bytes, default)**: Suitable for low-bandwidth applications and conserves RAM +- **Large buffers (512-1024 bytes)**: Recommended for high-throughput applications or when handling bursts of data + +Increase buffer sizes if you experience data loss or need to handle larger data packets without frequent polling. + +## See Also + +- {{< docref "/components/tinyusb" >}} +- {{< apiref "usb_cdc_acm/usb_cdc_acm.h" "usb_cdc_acm/usb_cdc_acm.h" >}} diff --git a/content/components/wifi.md b/content/components/wifi.md index e33ca495a9..d5795f010e 100644 --- a/content/components/wifi.md +++ b/content/components/wifi.md @@ -494,6 +494,22 @@ on_...: The lambda equivalent for this is `!id(wifi_id).is_disabled()`. +{{< anchor "wifi-ap-active_condition" >}} + +### `wifi.ap_active` Condition + +This [Condition](/automations/actions#all-conditions) checks if WiFi AP is currently active or not. + +```yaml +on_...: + - if: + condition: wifi.ap_active + then: + - logger.log: WiFi AP is active! +``` + +The lambda equivalent for this is `id(wifi_id).is_ap_active()`. + ## See Also - {{< docref "captive_portal/" >}} diff --git a/content/guides/getting_started_hassio.md b/content/guides/getting_started_hassio.md index 6788ef32d5..af9233c11a 100644 --- a/content/guides/getting_started_hassio.md +++ b/content/guides/getting_started_hassio.md @@ -55,6 +55,16 @@ The web UI will present a wizard which will walk you through creating your first {{< img src="dashboard_empty.png" alt="Image" width="95.0%" class="align-center" >}} +The wizard begins by asking you how you'd like to create your configuration. You have three options: + +- **New Device Setup**: The wizard guides you through platform selection, board configuration, and Wi-Fi + setup to create a basic working configuration. +- **Import from File**: Upload an existing ESPHome configuration file (.yaml or .yml). This is useful for + restoring backups and migrating configurations. You can browse for files or drag and drop them directly + onto the dialog. +- **Empty Configuration**: Creates a minimal configuration file for advanced users who prefer to write + their own configuration from scratch or paste from [devices.esphome.io](https://devices.esphome.io/). + After creating your first configuration, you'll need to install it on your device. > [!NOTE] diff --git a/data/version.yaml b/data/version.yaml index 11590aec6b..2cc1ee960f 100644 --- a/data/version.yaml +++ b/data/version.yaml @@ -1,2 +1,2 @@ -release: 2025.11.5 -version: '2025.11' +release: 2025.12.0b1 +version: '2025.12' diff --git a/static/images/bm8563.svg b/static/images/bm8563.svg new file mode 100644 index 0000000000..f1a11651f8 --- /dev/null +++ b/static/images/bm8563.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/static/images/cc1101.webp b/static/images/cc1101.webp new file mode 100644 index 0000000000..f99bf15e97 Binary files /dev/null and b/static/images/cc1101.webp differ diff --git a/static/images/hc8.png b/static/images/hc8.png new file mode 100644 index 0000000000..0c1c7ab3c7 Binary files /dev/null and b/static/images/hc8.png differ diff --git a/static/images/hlw8032.png b/static/images/hlw8032.png new file mode 100644 index 0000000000..144e304dcf Binary files /dev/null and b/static/images/hlw8032.png differ diff --git a/static/images/hub75.svg b/static/images/hub75.svg new file mode 100644 index 0000000000..b801755bb2 --- /dev/null +++ b/static/images/hub75.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/static/images/stts22h.jpg b/static/images/stts22h.jpg new file mode 100644 index 0000000000..09cf294fe7 Binary files /dev/null and b/static/images/stts22h.jpg differ diff --git a/static/images/thermopro_tp357.jpg b/static/images/thermopro_tp357.jpg new file mode 100644 index 0000000000..2d57b7faaf Binary files /dev/null and b/static/images/thermopro_tp357.jpg differ