diff --git a/content/changelog/2026.1.0.md b/content/changelog/2026.1.0.md index 193f8bbeb9..be8ca917b3 100644 --- a/content/changelog/2026.1.0.md +++ b/content/changelog/2026.1.0.md @@ -522,6 +522,8 @@ For detailed migration guides and API documentation, see the [ESPHome Developers ## Full list of changes +The lists below are grouped by tag and may contain duplicates across sections. + ### New Features - [esp32] Add OTA rollback support [esphome#12460](https://github.com/esphome/esphome/pull/12460) by [@swoboda1337](https://github.com/swoboda1337) (new-feature) @@ -533,7 +535,7 @@ For detailed migration guides and API documentation, see the [ESPHome Developers - [water_heater] (1/4) Implement API/Core/component for new water_heater component [esphome#12498](https://github.com/esphome/esphome/pull/12498) by [@dhoeben](https://github.com/dhoeben) (new-component) (new-feature) - Add Event Component to UART [esphome#11765](https://github.com/esphome/esphome/pull/11765) by [@eoasmxd](https://github.com/eoasmxd) (new-feature) (new-platform) - [bme68x_bsec2] add `id:` to allow extending [esphome#12649](https://github.com/esphome/esphome/pull/12649) by [@ssieb](https://github.com/ssieb) (new-feature) -- Add BTHome advertisments parsing to Xiaomi Mijia BLE Sensors [esphome#12635](https://github.com/esphome/esphome/pull/12635) by [@nagyrobi](https://github.com/nagyrobi) (new-component) (new-feature) (new-platform) +- Add BTHome advertisements parsing to Xiaomi Mijia BLE Sensors [esphome#12635](https://github.com/esphome/esphome/pull/12635) by [@nagyrobi](https://github.com/nagyrobi) (new-component) (new-feature) (new-platform) - [spi] Allow any achievable data rate [esphome#12753](https://github.com/esphome/esphome/pull/12753) by [@tuct](https://github.com/tuct) (new-feature) - [mhz19] Make detection range configurable [esphome#12677](https://github.com/esphome/esphome/pull/12677) by [@jvanderneutstulen](https://github.com/jvanderneutstulen) (new-feature) - [water_heater] (2/4) Implement template for new water_heater component [esphome#12516](https://github.com/esphome/esphome/pull/12516) by [@dhoeben](https://github.com/dhoeben) (new-feature) @@ -567,7 +569,7 @@ For detailed migration guides and API documentation, see the [ESPHome Developers - Add hmac-sha256 support [esphome#12437](https://github.com/esphome/esphome/pull/12437) by [@dwmw2](https://github.com/dwmw2) (new-component) - [aqi, hm3301, pmsx003] Air Quality Index improvements [esphome#12203](https://github.com/esphome/esphome/pull/12203) by [@jasstrong](https://github.com/jasstrong) (new-component) (new-feature) (breaking-change) - [water_heater] (1/4) Implement API/Core/component for new water_heater component [esphome#12498](https://github.com/esphome/esphome/pull/12498) by [@dhoeben](https://github.com/dhoeben) (new-component) (new-feature) -- Add BTHome advertisments parsing to Xiaomi Mijia BLE Sensors [esphome#12635](https://github.com/esphome/esphome/pull/12635) by [@nagyrobi](https://github.com/nagyrobi) (new-component) (new-feature) (new-platform) +- Add BTHome advertisements parsing to Xiaomi Mijia BLE Sensors [esphome#12635](https://github.com/esphome/esphome/pull/12635) by [@nagyrobi](https://github.com/nagyrobi) (new-component) (new-feature) (new-platform) - [nrf52,zigbee] add support for binary_input [esphome#11535](https://github.com/esphome/esphome/pull/11535) by [@tomaszduda23](https://github.com/tomaszduda23) (new-component) (new-feature) - [rd03d] Add Ai-Thinker RD-03D mmWave radar component [esphome#12764](https://github.com/esphome/esphome/pull/12764) by [@jasstrong](https://github.com/jasstrong) (new-component) (new-feature) (new-platform) - [infrared] Implement experimental API/Core/component for new component/entity type [esphome#13129](https://github.com/esphome/esphome/pull/13129) by [@kbx81](https://github.com/kbx81) (new-component) @@ -576,7 +578,7 @@ For detailed migration guides and API documentation, see the [ESPHome Developers ### New Platforms - Add Event Component to UART [esphome#11765](https://github.com/esphome/esphome/pull/11765) by [@eoasmxd](https://github.com/eoasmxd) (new-feature) (new-platform) -- Add BTHome advertisments parsing to Xiaomi Mijia BLE Sensors [esphome#12635](https://github.com/esphome/esphome/pull/12635) by [@nagyrobi](https://github.com/nagyrobi) (new-component) (new-feature) (new-platform) +- Add BTHome advertisements parsing to Xiaomi Mijia BLE Sensors [esphome#12635](https://github.com/esphome/esphome/pull/12635) by [@nagyrobi](https://github.com/nagyrobi) (new-component) (new-feature) (new-platform) - [rd03d] Add Ai-Thinker RD-03D mmWave radar component [esphome#12764](https://github.com/esphome/esphome/pull/12764) by [@jasstrong](https://github.com/jasstrong) (new-component) (new-feature) (new-platform) - [aqi] Implement a sensor that computes AQI [esphome#12958](https://github.com/esphome/esphome/pull/12958) by [@jasstrong](https://github.com/jasstrong) (new-feature) (new-platform) @@ -720,7 +722,7 @@ For detailed migration guides and API documentation, see the [ESPHome Developers - [ethernet_info] Eliminate heap allocations in DNS text sensor [esphome#12756](https://github.com/esphome/esphome/pull/12756) by [@bdraco](https://github.com/bdraco) - [core] Add format_hex_pretty_to buffer helper and reduce code duplication [esphome#12687](https://github.com/esphome/esphome/pull/12687) by [@bdraco](https://github.com/bdraco) - [core] Make LockFreeQueue more widely available [esphome#12766](https://github.com/esphome/esphome/pull/12766) by [@clydebarrow](https://github.com/clydebarrow) -- Add BTHome advertisments parsing to Xiaomi Mijia BLE Sensors [esphome#12635](https://github.com/esphome/esphome/pull/12635) by [@nagyrobi](https://github.com/nagyrobi) (new-component) (new-feature) (new-platform) +- Add BTHome advertisements parsing to Xiaomi Mijia BLE Sensors [esphome#12635](https://github.com/esphome/esphome/pull/12635) by [@nagyrobi](https://github.com/nagyrobi) (new-component) (new-feature) (new-platform) - [mipi_spi] Use stack buffer for hex formatting in verbose logging [esphome#12778](https://github.com/esphome/esphome/pull/12778) by [@bdraco](https://github.com/bdraco) - Fix display driver fill implementations to honor clipping correctly [esphome#12808](https://github.com/esphome/esphome/pull/12808) by [@stuartparmenter](https://github.com/stuartparmenter) (breaking-change) - [mipi_dsi] Use stack buffer for hex formatting in very verbose logging [esphome#12776](https://github.com/esphome/esphome/pull/12776) by [@bdraco](https://github.com/bdraco) @@ -1117,19 +1119,6 @@ For detailed migration guides and API documentation, see the [ESPHome Developers - [safe_mode] Detect bootloader rollback support at runtime [esphome#13230](https://github.com/esphome/esphome/pull/13230) by [@swoboda1337](https://github.com/swoboda1337) - [qr_code] Allocate and free memory for QR code buffer [esphome#13161](https://github.com/esphome/esphome/pull/13161) by [@rootnegativ1](https://github.com/rootnegativ1) - [web_server][captive_portal] Change default compression from Brotli to gzip [esphome#13246](https://github.com/esphome/esphome/pull/13246) by [@bdraco](https://github.com/bdraco) -- [sprinkler] Fix scheduler deprecation warnings and heap churn with FixedVector [esphome#13251](https://github.com/esphome/esphome/pull/13251) by [@bdraco](https://github.com/bdraco) -- [dallas_temp] Use const char* for set_timeout to fix deprecation warning and heap churn [esphome#13250](https://github.com/esphome/esphome/pull/13250) by [@bdraco](https://github.com/bdraco) -- [api] Fix clock conflicts when multiple clients connected to homeassistant time [esphome#13253](https://github.com/esphome/esphome/pull/13253) by [@bdraco](https://github.com/bdraco) -- [esp32_ble_client] Reduce GATT data event logging to prevent firmware update failures [esphome#13252](https://github.com/esphome/esphome/pull/13252) by [@bdraco](https://github.com/bdraco) -- [ntc, resistance] change log level to verbose [esphome#13268](https://github.com/esphome/esphome/pull/13268) by [@mrtoy-me](https://github.com/mrtoy-me) -- [hmac_sha256] Replace unsafe sprintf with format_hex_to [esphome#13290](https://github.com/esphome/esphome/pull/13290) by [@bdraco](https://github.com/bdraco) -- [hub75] Bump esp-hub75 version to 0.3.0 [esphome#13243](https://github.com/esphome/esphome/pull/13243) by [@stuartparmenter](https://github.com/stuartparmenter) (breaking-change) -- [http_request] Unable to handle chunked responses [esphome#7884](https://github.com/esphome/esphome/pull/7884) by [@HLFCode](https://github.com/HLFCode) -- [network] Fix IPAddress::str_to() to lowercase IPv6 hex digits [esphome#13325](https://github.com/esphome/esphome/pull/13325) by [@bdraco](https://github.com/bdraco) -- [api] Fix truncation of Home Assistant attributes longer than 255 characters [esphome#13348](https://github.com/esphome/esphome/pull/13348) by [@bdraco](https://github.com/bdraco) -- [core] Fix state leakage and module caching when processing multiple configurations [esphome#13368](https://github.com/esphome/esphome/pull/13368) by [@swoboda1337](https://github.com/swoboda1337) -- [x9c] Fix potentiometer unable to decrement [esphome#13382](https://github.com/esphome/esphome/pull/13382) by [@swoboda1337](https://github.com/swoboda1337) -- [wifi_info] Fix missing state when both IP+DNS or SSID+BSSID configure [esphome#13385](https://github.com/esphome/esphome/pull/13385) by [@bdraco](https://github.com/bdraco) diff --git a/content/components/_index.md b/content/components/_index.md index d33088c70e..e6654fd88c 100644 --- a/content/components/_index.md +++ b/content/components/_index.md @@ -506,6 +506,7 @@ Sensors are organized into categories; if a given sensor fits into more than one "Resol VBus","components/vbus","resol_deltasol_bs_plus.jpg","" "Rotary Encoder","components/sensor/rotary_encoder","rotary_encoder.jpg","" "SMT100","components/sensor/smt100","smt100.jpg","Moisture & Temperature" +"SY6970","components/sensor/sy6970","sy6970.jpg","Battery charge IC" "Sound Level","components/sensor/sound_level","waveform.svg","dark-invert" "Tuya Sensor","components/sensor/tuya","tuya.png","" "TX20","components/sensor/tx20","tx20.jpg","Wind speed & Wind direction" diff --git a/content/components/binary_sensor/status.md b/content/components/binary_sensor/status.md index 0c3a366e21..8d545918a8 100644 --- a/content/components/binary_sensor/status.md +++ b/content/components/binary_sensor/status.md @@ -1,9 +1,9 @@ --- -description: "Instructions for setting up MQTT status binary sensors." +description: "Instructions for setting up status binary sensors." title: "Status Binary Sensor" params: seo: - description: Instructions for setting up MQTT status binary sensors. + description: Instructions for setting up status binary sensors. image: server-network.svg --- @@ -21,7 +21,9 @@ binary_sensor: ## Configuration variables -- All options from [Binary Sensor](/components/binary_sensor#config-binary_sensor). (Inverted mode is not supported) +- **update_interval** (*Optional*, {{< docref "/guides/configuration-types#time" "Time" >}}): The interval + to check the connection status. Defaults to `1s`. +- All other options from [Binary Sensor](/components/binary_sensor#config-binary_sensor). (Inverted mode is not supported) ## See Also diff --git a/content/components/captive_portal.md b/content/components/captive_portal.md index 15df881a80..13048245f8 100644 --- a/content/components/captive_portal.md +++ b/content/components/captive_portal.md @@ -38,8 +38,9 @@ captive_portal: ## Configuration variables - **compression** (*Optional*, string): The compression algorithm used for the embedded web assets. - Options are `br` (Brotli) or `gzip`. Brotli provides ~24% smaller size than gzip. - Defaults to `br`. + Options are `gzip` or `br` (Brotli). Brotli provides ~24% smaller size than gzip, but some browsers + only support Brotli over HTTPS connections. Since the captive portal is served over HTTP, gzip is recommended + for maximum compatibility. Defaults to `gzip`. ## See Also diff --git a/content/components/climate/climate_ir.md b/content/components/climate/climate_ir.md index 64aa607efd..2bc4bc3fc3 100644 --- a/content/components/climate/climate_ir.md +++ b/content/components/climate/climate_ir.md @@ -350,7 +350,7 @@ climate: The `heatpumpir` platform supports dozens of manufacturers and hundreds of AC units by utilising the [Arduino-HeatpumpIR library](https://github.com/ToniA/arduino-heatpumpir). -This platform compiles only under `arduino` framework or LibreTiny, and should only be used if your AC unit is not supported by any of the other (native) platforms from above. No support can be provided for Arduino-HeatpumpIR, because it is a third party library. +This platform works with the `arduino` framework and ESP-IDF (on ESP32), and should only be used if your AC unit is not supported by any of the other (native) platforms from above. No support can be provided for Arduino-HeatpumpIR, because it is a third party library. This platform utilises the library's generic one-size-fits-all API, which might not line up perfectly with all of the supported AC units. For example, some AC units have more fan speed options than what the generic API supports. diff --git a/content/components/debug.md b/content/components/debug.md index fe65486b16..e1836d947e 100644 --- a/content/components/debug.md +++ b/content/components/debug.md @@ -30,10 +30,12 @@ sensor: - platform: debug free: name: "Heap Free" - fragmentation: - name: "Heap Fragmentation" block: name: "Heap Max Block" + min_free: + name: "Heap Min Free" + fragmentation: + name: "Heap Fragmentation" loop_time: name: "Loop Time" psram: @@ -76,12 +78,14 @@ sensor: - **free** (*Optional*): Reports the free heap size in bytes. All options from [Sensor](/components/sensor). +- **block** (*Optional*): Reports the largest contiguous free RAM block on the heap in bytes. All options from [Sensor](/components/sensor). + +- **min_free** (*Optional*): Reports the minimum free heap size since boot in bytes. This is useful for detecting memory leaks or high-water-mark usage. Only available on ESP32 and LibreTiny. All options from [Sensor](/components/sensor). + - **fragmentation** (*Optional*): Reports the fragmentation metric of the heap - (0% is clean, more than ~50% is not harmless). Only available on ESP8266 with Arduino 2.5.2+. + (0% is clean, more than ~50% may cause allocation failures). Available on ESP8266 with Arduino 2.5.2+ and ESP32. All options from [Sensor](/components/sensor). -- **block** (*Optional*): Reports the largest contiguous free RAM block on the heap in bytes. All options from [Sensor](/components/sensor). - - **loop_time** (*Optional*): Reports the longest time between successive iterations of the main loop. All options from [Sensor](/components/sensor). - **psram** (*Optional*): Reports the free PSRAM in bytes. Only available on ESP32. All options from [Sensor](/components/sensor). diff --git a/content/components/display/epaper_spi.md b/content/components/display/epaper_spi.md index 96d587702a..416bb143df 100644 --- a/content/components/display/epaper_spi.md +++ b/content/components/display/epaper_spi.md @@ -45,6 +45,8 @@ the pins used to interface to the display to be specified. |---------------------|--------------|----------------------------------------------------| | Waveshare-2.13in-v3 | Waveshare | | | Waveshare-4.26in | Waveshare | | +| WeAct-2.9in-3c | WeAct | 2.9" 3-color e-paper (128x296, SSD1683) | +| WeAct-4.2in-3c | WeAct | 4.2" 3-color e-paper (400x300, SSD1683) | ## Supported integrated display boards diff --git a/content/components/display/images/tab5-version-label.jpg b/content/components/display/images/tab5-version-label.jpg new file mode 100644 index 0000000000..838217e973 Binary files /dev/null and b/content/components/display/images/tab5-version-label.jpg differ diff --git a/content/components/display/mipi_dsi.md b/content/components/display/mipi_dsi.md index 89a76af8f6..c3f0323dad 100644 --- a/content/components/display/mipi_dsi.md +++ b/content/components/display/mipi_dsi.md @@ -44,10 +44,27 @@ specified, or a custom init sequence can be provided. | ---------------------- | ------------ | ----------------------------------------------------------------------------- | | JC1060P470 | Guition | | | JC4880P443 | Guition | | +| JC8012P4A1 | Guition | | | M5STACK-TAB5 | M5Stack | | +| M5STACK-TAB5-V2 | M5Stack | | | WAVESHARE-P4-NANO-10.1 | Waveshare | | | WAVESHARE-P4-86-PANEL | Waveshare | | +> [!NOTE] +The M5Stack Tab5 has two hardware revisions with different display chips requiring different model selections. + +Units manufactured before October 14, 2025 use the ILI9881C display driver with separate GT911 touch driver (use `M5STACK-TAB5`). +Units manufactured on or after that date use the integrated ST7123 display-touch driver (use `M5STACK-TAB5-V2`). + +If unsure which model you have, check the sticker on the back of the device for the display driver chip name. +The label is just above the ESPressif icon. See image below for example of V2 hardware. + +Selection of the wrong display driver model will cause the display to simply fail to work with no relevant logging. +Selection of the wrong touchscreen driver however will display an error message in the log output, so if in doubt, +verify the correct touchscreen driver first to accurately identify the board before configuring the display driver. + +{{< img src="tab5-version-label.jpg" alt="Tab5 version label showing model identification" width="50%" class="align-center" >}} + ## Configuration ```yaml diff --git a/content/components/display/mipi_spi.md b/content/components/display/mipi_spi.md index 1cc05b9cab..9ee4ebc1fa 100644 --- a/content/components/display/mipi_spi.md +++ b/content/components/display/mipi_spi.md @@ -39,9 +39,10 @@ using an octal SPI bus, so references here to parallel and octal SPI are equival ### Driver chips | Driver Chip | Typical Dimensions | -| ----------- | ------------------ | +| ----------- |--------------------| | RM690B0 | 320x240 | | ILI9341 | 320x240 | +| ILI9342 | 240x320 | | ILI9481 | 320x480 | | ILI9486 | 320x480 | | ILI9488 | 320x480 | @@ -58,31 +59,33 @@ using an octal SPI bus, so references here to parallel and octal SPI are equival ### Boards with integrated displays | Model | Manufacturer | Product Description | -| ------------------------------------ | ------------ | ----------------------------------------------------------------- | +|--------------------------------------|--------------|-------------------------------------------------------------------| | ADAFRUIT-S2-TFT-FEATHER | Adafruit | | | ADAFRUIT-FUNHOUSE | Adafruit | | -| M5CORE | M5Stack | | -| M5CORE2 | M5Stack | | -| S3BOX | Espressif | | -| S3BOXLITE | Espressif | | -| WAVESHARE-4-TFT | Waveshare | | -| PICO-RESTOUCH-LCD-3.5 | Waveshare | | -| WAVESHARE-ESP32-S3-TOUCH-AMOLED-1.75 | Waveshare | | -| WAVESHARE-ESP32-S3-TOUCH-LCD-3.49 | Waveshare | | -| WT32-SC01-PLUS | Wireless-Tag | | -| ESP32-2432S028 | Sunton | | -| JC3248W535 | Guition | | -| JC3636W518 | Guition | | -| JC3636W518V2 | Guition | | -| JC4827W543 | Guition | | -| LANBON-L8 | Lanbon | | -| T4-S3 | Lilygo | | -| T-EMBED | Lilygo | | -| T-DISPLAY | Lilygo | | -| T-DISPLAY-S3 | Lilygo | | -| T-DISPLAY-S3-PRO | Lilygo | | -| T-DISPLAY-S3-AMOLED | Lilygo | | -| T-DISPLAY-S3-AMOLED-PLUS | Lilygo | | +| M5CORE | M5Stack | | +| M5CORE2 | M5Stack | | +| S3BOX | Espressif | | +| S3BOXLITE | Espressif | | +| WAVESHARE-4-TFT | Waveshare | | +| PICO-RESTOUCH-LCD-3.5 | Waveshare | | +| WAVESHARE-ESP32-S3-TOUCH-AMOLED-1.75 | Waveshare | | +| WAVESHARE-ESP32-S3-TOUCH-LCD-3.49 | Waveshare | | +| WT32-SC01-PLUS | Wireless-Tag | | +| ESP32-2432S028 | Sunton | 2.8" CYD. Original micro-USB version with ILI9341 controller. | +| ESP32-2432S028-7789 | Sunton | Dual-USB version with ST7789V. | +| ESP32-2432S028-9342 | Sunton | Dual-USB version with ILI9342. | +| JC3248W535 | Guition | | +| JC3636W518 | Guition | | +| JC3636W518V2 | Guition | | +| JC4827W543 | Guition | | +| LANBON-L8 | Lanbon | | +| T4-S3 | Lilygo | | +| T-EMBED | Lilygo | | +| T-DISPLAY | Lilygo | | +| T-DISPLAY-S3 | Lilygo | | +| T-DISPLAY-S3-PRO | Lilygo | | +| T-DISPLAY-S3-AMOLED | Lilygo | | +| T-DISPLAY-S3-AMOLED-PLUS | Lilygo | | ## SPI Bus @@ -128,9 +131,10 @@ most of the configuration will be set by default, but can be overridden if neede - **invert_colors** (*Optional*, boolean): Specifies whether the display colors should be inverted. Options are `true` or `false`. Defaults to `false`. - **rotation** (*Optional*): Rotate the display presentation in software. Choose one of `0°`, `90°`, `180°`, or `270°`. If the driver chip supports hardware rotation for the given orientation this will be translated to the appropriate hardware command. If hardware rotation is not supported, the display will be rotated in software. -- **transform** (*Optional*): If `rotation` is not sufficient, use this to transform the display. If this option is specified, then the `dimensions` option must also be provided. The value can either be the string `disabled` to disable hardware transform, or a dictionary. Options are: - This option should not be used with `rotation`. For the `CUSTOM` model, use `transform: disabled` - if the display does not support it, which will prevent a `rotation` being translated to a hardware transform. +- **transform** (*Optional*): If `rotation` is not sufficient, use this to transform the display. If this option is + specified, then the `dimensions` option must also be provided. The value can either be the string `disabled` to disable hardware transform, or a dictionary. + For the `CUSTOM` model, use `transform: disabled` if the display does not support it, which will prevent a `rotation` + being translated to a hardware transform, otherwise the options below: - **swap_xy** (**Required**, boolean): If true, exchange the x and y axes. - **mirror_x** (**Required**, boolean): If true, mirror the x axis. diff --git a/content/components/display/nextion.md b/content/components/display/nextion.md index 8a0922a145..901309fa6f 100644 --- a/content/components/display/nextion.md +++ b/content/components/display/nextion.md @@ -80,6 +80,17 @@ display: - **auto_wake_on_touch** (*Optional*, boolean): If set to `true`, the Nextion will be configured to wake from sleep when touched. +- **max_queue_age** (*Optional*, [Time](/guides/configuration-types#time)): Maximum age in milliseconds for queued commands before they are automatically + removed. This helps prevent stale commands from being executed after delays. Set to ``0`` to disable age-based + removal (commands are only limited by queue size). **Note:** Very low values (e.g., <50ms) may cause commands + to be dropped before transmission due to ESPHome's loop timing (~16ms). Recommended minimum is 100ms when enabled. + Range: 0-65535. Defaults to ``8000`` (8 seconds). + +- **startup_override_ms** (*Optional*, [Time](/guides/configuration-types#time)): Time in milliseconds to wait before forcing the display to be marked as ready + if it hasn't responded to the connection handshake. Set to ``0`` to disable the override and wait indefinitely + for the handshake. This is useful for displays with slower startup sequences or to enforce strict handshake requirements. + Range: 0-65535. Defaults to ``8000`` (8 seconds). + - **skip_connection_handshake** (*Optional*, boolean): Sets whether the initial display connection handshake process is skipped. When set to `true`, the connection will be established without performing the handshake. This can be useful when using Nextion Simulator. Defaults to `false`. diff --git a/content/components/display/waveshare_epaper.md b/content/components/display/waveshare_epaper.md index c52e2c76d2..d17b311489 100644 --- a/content/components/display/waveshare_epaper.md +++ b/content/components/display/waveshare_epaper.md @@ -31,12 +31,12 @@ configuration. | ------------------ | ----------- | ------------------ | | `VCC` | `3.3V` | N/A | | `GND` | `GND` | N/A | -| `CLK` | Any GPIO | `spi.clk_pin` | -| `DIN` | Any GPIO | `spi.mosi_pin` | -| `CS` | Any GPIO | `cs_pin` | -| `DC` | Any GPIO | `dc_pin` | -| `BUSY` (Optional) | Any GPIO | `busy_pin` | -| `RESET` (Optional) | Any GPIO | `reset_pin` | +| `CLK` | Any GPIO | `spi.clk_pin` | +| `DIN` | Any GPIO | `spi.mosi_pin` | +| `CS` | Any GPIO | `cs_pin` | +| `DC` | Any GPIO | `dc_pin` | +| `BUSY` (Optional) | Any GPIO | `busy_pin` | +| `RESET` (Optional) | Any GPIO | `reset_pin` | {{< img src="waveshare_epaper-pins.jpg" alt="Image" width="60.0%" class="align-center" >}} @@ -96,6 +96,7 @@ lambda: |- - `2.13in-ttgo-dke` - T5_V2.3 with DKE group display (DEPG0213BN) tested - `2.13inv2` - 2.13in V2 display (Pico e-Paper 2.13v2 and Cloud Module) - `2.13inv3` - 2.13in V3 display (Pico e-Paper 2.13v3) + - `2.13in3c-weact` - WeAct Studio 2.13in 3-color (Black/White/Red) e-paper display (122x250) - not tested - `2.70in` - currently not working with the HAT Rev 2.1 version - `2.70inv2` - `2.70in-b` - Black/White/Red @@ -106,10 +107,12 @@ lambda: |- - `2.90inv2-r2` - 2.9in V2 display, but with different initialization and full/partial display refresh management than `2.90inv2` - `2.90in-b` - B/W rendering only - `2.90in-bV3` - B/W rendering only + - `2.90in3c-weact` - WeAct Studio 2.90in 3-color (Black/White/Red) e-paper display (128x296) - tested - `4.20in` - `4.20in-bV2` - B/W rendering only - `gdey042t81` - GoodDisplay GDEY042T81 4.2" B/W - `4.20in-bV2-bwr` - BWR rendering enabled (uses double the amount of RAM for the display buffer as B/W rendering) + - `4.20in3c-weact` - WeAct Studio 4.20in 3-color (Black/White/Red) e-paper display (400x300) - not tested - `5.83in` - `5.83inv2` - `gdey0583t81` - GoodDisplay GDEY0583T81 5.83" B/W @@ -142,10 +145,13 @@ lambda: |- - **full_update_every** (*Optional*, int): E-Paper displays have two modes of switching to the next image: A partial update that only changes the pixels that have changed and a full update mode that first clears the entire display and then re-draws the image. The former is much quicker and nicer, but every so often a full update needs to happen - because artifacts accumulate. On the `1.54in`, `1.54inv2`, `2.13in`, `2.13inv2`, `2.90in`, `2.90inv2`, `7.50inV2p` and `gdew029t5` models, you have the option to only + because artifacts accumulate. On the `1.54in`, `1.54inv2`, `2.13in`, `2.13inv2`, `2.90in`, `2.90inv2`, `7.50inV2p`, `gdew029t5` you have the option to only do a full-redraw every x-th time using this option. Defaults to `30` on the described models and a full update for all other models. +> [!NOTE] +> For WeAct 3-color models, `full_update_every` is not configurable as they typically perform a full refresh with every display update to ensure optimal color rendering and prevent ghosting. + - **reset_duration** (*Optional*, [Time](/guides/configuration-types#time)): Duration for the display reset operation. Defaults to `200ms`. Setting this value to `2ms` may resolve issues with newer e-Paper Driver modules (e.g. Rev 2.1). diff --git a/content/components/select/_index.md b/content/components/select/_index.md index 40a21ca2c6..4be07f327d 100644 --- a/content/components/select/_index.md +++ b/content/components/select/_index.md @@ -53,8 +53,6 @@ Configuration variables: - If Webserver enabled and version 3 is selected, All other options from Webserver Component.. See [Webserver Version 3](/components/web_server#config-webserver-version-3-options). -Automations: - - **on_value** (*Optional*, [Automation](/automations)): An automation to perform when a new value is published. See [`on_value`](#select-on_value). @@ -62,12 +60,14 @@ MQTT Options: - All other options from [MQTT Component](/components/mqtt#config-mqtt-component). -## Select Automation +### Accessing the current option You can access the most recent state of the select in [lambdas](/automations/templates#config-lambda) using `id(select_id).current_option()`. For more information on using lambdas with select, see [lambda calls](#select-lambda_calls). +## Triggers + {{< anchor "select-on_value" >}} ### `on_value` @@ -88,6 +88,48 @@ select: Configuration variables: See [Automation](/automations). +## Conditions + +### `select.is` Condition + +This [Condition](/automations/actions#all-conditions) checks if the select is set to any one of a list of options. A lambda may also be used for more complex computations. + +Configuration variables: + +- **id** (**Required**, [ID](/guides/configuration-types#id)): The ID of the select to test. +- **options** (*Optional*, list): A string, or list of strings to compare with the current selection. The condition is true if any match. +- **lambda** (*Optional*, [templatable](/automations/templates)): A lambda returning a boolean value. The current selection is passed in a `StringRef` argument called `current`. + +Only one of `options` and `lambda` must be provided. + +```yaml +# In some trigger: +on_...: + - if: + condition: + select.is: + id: my_select + options: [Happy, Ecstatic] + then: + - logger.log: "Select is Happy or Ecstatic" + - if: + condition: + select.is: + id: my_select + options: "Happy" # Single option + then: + - logger.log: "Select is exactly Happy" + - if: + condition: + select.is: + id: my_select + lambda: return id(text_sensor).state == current || "Happy" == current; + then: + - logger.log: "Select is Happy, or matches some variable state" +``` + +## Actions + {{< anchor "select-set_action" >}} ### `select.set` Action @@ -249,10 +291,9 @@ Configuration variables: {{< anchor "select-lambda_calls" >}} -### lambda calls +## Using Selects in Lambdas -From [lambdas](/automations/templates#config-lambda), you can call several methods on all selects to do some -advanced stuff (see the full API Reference for more info). +From [lambdas](/automations/templates#config-lambda), you can call several methods on selects (see the full API Reference for more info). - `.make_call()` : Create a call for changing the select state. diff --git a/content/components/sensor/_index.md b/content/components/sensor/_index.md index 24933d77dd..b72cd371b4 100644 --- a/content/components/sensor/_index.md +++ b/content/components/sensor/_index.md @@ -173,7 +173,9 @@ filters: - heartbeat: 5s - debounce: 0.1s - timeout: 1min - - delta: 5.0 + - delta: + min_value: 5.0 + max_value: 2% - or: - throttle: 1s - delta: 5.0 diff --git a/content/components/sensor/bmp581.md b/content/components/sensor/bmp581.md index 72adfa6e75..1a6a563956 100644 --- a/content/components/sensor/bmp581.md +++ b/content/components/sensor/bmp581.md @@ -8,15 +8,17 @@ params: --- The `bmp581` sensor platform allows you to use your BMP581 -([datasheet](https://www.bosch-sensortec.com/media/boschsensortec/downloads/datasheets/bst-bmp581-ds004.pdf), [SparkFun](https://www.sparkfun.com/products/20170)) temperature and pressure sensors with ESPHome. The [I²C](/components/i2c) bus is -required to be set up in your configuration for this sensor to work. +([datasheet](https://www.bosch-sensortec.com/media/boschsensortec/downloads/datasheets/bst-bmp581-ds004.pdf), [SparkFun](https://www.sparkfun.com/products/20170) or [Adafruit](https://www.adafruit.com/product/6407)) temperature and pressure sensors with ESPHome. The [I²C](/components/i2c) bus is +required to be set up in your configuration for this sensor to work. While technically possible, ESPHome does not yet support communication with this sensor via the SPI bus. {{< img src="bmp581.jpg" alt="Image" caption="BMP581 Temperature and Pressure Sensor. (Credit: [SparkFun](https://www.sparkfun.com/products/20170), image cropped and compressed)" width="50.0%" class="align-center" >}} +## Over I²C + ```yaml -# Example configuration entry +# Example configuration entry for I2C connection sensor: - - platform: bmp581 + - platform: bmp581_i2c temperature: name: "Indoor Temperature" pressure: diff --git a/content/components/sensor/filter/clamp.md b/content/components/sensor/filter/clamp.md index ebfe96d0a6..2052abde3b 100644 --- a/content/components/sensor/filter/clamp.md +++ b/content/components/sensor/filter/clamp.md @@ -3,7 +3,7 @@ description: "" headless: true --- -Limits the value to the range between `min_value` and `max_value`. By default, sensor values outside these bounds will be set to `min_value` or `max_value`, respectively. If `ignore_out_of_range` is true, then sensor values outside those bounds will be ignored. If `min_value` is not set, there is no lower bound; if `max_value` is not set there is no upper bound. +Limits the value to the inclusive range between `min_value` and `max_value`. Configuration variables: @@ -11,6 +11,18 @@ Configuration variables: - **max_value** (*Optional*, float): The upper bound of the range. - **ignore_out_of_range** (*Optional*, bool): If true, ignores all sensor values out of the range. Defaults to `false`. +At least one of `min_value` or `max_value` must be specified. + +When a sensor value is passed through this filter, if it is less than `min_value`, it will be set to `min_value`. If it +is greater than `max_value`, it will be set to `max_value`. +An unspecified bound is considered unbounded (i.e., if `min_value` is not set, there is no lower limit). + +A value of NaN (not a number) will be clamped to the lower bound if `min_value` is set, otherwise to the upper bound. +A value of positive or negative infinity will be clamped to the upper or lower bound, respectively, if those bounds are +set. + +If `ignore_out_of_range` is true, any values not within the specified range will be ignored instead of clamped. + ```yaml # Example configuration entry filters: diff --git a/content/components/sensor/filter/delta.md b/content/components/sensor/filter/delta.md index c0646c9acc..241364a723 100644 --- a/content/components/sensor/filter/delta.md +++ b/content/components/sensor/filter/delta.md @@ -5,16 +5,44 @@ headless: true This filter stores the last value passed through this filter and only passes incoming values through if incoming value is sufficiently different from the previously passed one. -This difference can be calculated in two ways an absolute difference or a percentage difference. +This difference can be calculated in two ways an absolute difference or a percentage difference, and +with respect to a minimum, `min_value` and maximum value, `max_value`. -If a number is specified, it will be used as the absolute difference required. -For example if the filter were configured with a value of 2 and the last value passed through was 10, -only values greater than or equal to 12 or less than or equal to 8 would be passed through. +## Configuration variables + +- **min_value** (*Optional*, float, percent): The minimum absolute or percentage difference required (default is `0.0`) +- **max_value** (*Optional*, float, percent): The maximum absolute or percentage difference allowed (default is infinity) +- **baseline** (*Optional*, float, [lambda](/automations/templates#config-lambda)): A baseline to use + when calculating the difference. By default the last passed value is used. + +At least one of `min_value` or `max_value` must be specified. Alternatively to specifying `min_value` +and/or `max_value` as keys, you can also just provide a single float or percentage value. In this case the value +is interpreted as `min_value`. + +The filter will reject values that do not differ from the baseline by more than `min_value`, or that +differ from the baseline by more than the `max_value`. +For example, if the filter were configured with a value of `2.0` only values that differ from the last +passed value by more than `2.0` will be passed through. + +> [!NOTE] +> A `min_value` of `0.0` means that +> values equal to the last value will not be passed through, only values that differ, making it useful for +> eliminating duplicate values. ```yaml # Example configuration entry filters: + - delta: + min_value: 2.0 + # Same as above, min_value is implied here. - delta: 2.0 + + - delta: + max_value: 10% + # Specifying both min_value and max_value is permitted. + - delta: + min_value: 2.0 + max_value: 10% ``` If a percentage is specified a percentage of the last value will be used as the required difference. @@ -28,3 +56,32 @@ equal to 80 would be passed through. filters: - delta: 20% ``` + +When setting a maximum delta filter, it may be possible for the sensor values to escape the +bandwidth permitted by the filter without returning. In this case, it can be helpful to override the +value being compared from the default of the last value to an arbitrary other sensor that determines +a baseline: + +```yaml +# Example configuration entry +sensors: + # This sensor just calculates the baseline. + - platform: copy + source_id: my_sensor_to_be_filtered + id: baseline + filters: + - median: + window_size: 6 + send_every: 1 + send_first_at: 1 + + # This sensor will publish the values from your sensor with the max delta filter applied. + - platform: copy + source_id: my_sensor_to_be_filtered + name: "Filter Max With Baseline" + id: filter_baseline_max + filters: + - delta: + max_value: 10 + baseline: !lambda return id(baseline).state; +``` diff --git a/content/components/sensor/scd4x.md b/content/components/sensor/scd4x.md index 85ec8de623..192754db0c 100644 --- a/content/components/sensor/scd4x.md +++ b/content/components/sensor/scd4x.md @@ -107,9 +107,9 @@ api: variables: co2_ppm: int then: - - scd4x.perform_forced_calibration: - value: !lambda 'return co2_ppm;' - id: my_scd41 + - scd4x.perform_forced_calibration: + value: !lambda 'return co2_ppm;' + id: my_scd41 ``` {{< anchor "factory_reset_action" >}} diff --git a/content/components/sensor/sy6970.md b/content/components/sensor/sy6970.md new file mode 100644 index 0000000000..1a87fe0dd8 --- /dev/null +++ b/content/components/sensor/sy6970.md @@ -0,0 +1,289 @@ +--- +description: "Instructions for setting up SY6970 Battery Management IC" +title: "SY6970 Battery Management IC" +params: + seo: + description: Instructions for setting up SY6970 battery management and charging IC with ESPHome + image: sy6970.jpg +--- + +The `sy6970` component allows you to use the SY6970 battery management and charging ICs [SY6970 Datasheet](https://github.com/Xinyuan-LilyGO/LilyGo-AMOLED-Series/blob/master/datasheet/SY6970%20Datasheet.pdf) with ESPHome. + +The SY6970 is a highly integrated battery charger and system power path management device for single-cell +lithium-ion and lithium-polymer batteries. It features a wide input voltage range, programmable charge +current and voltage, and comprehensive safety features. + +This component is found in the LilyGo T-Display S3 Pro. + +The [I²C Bus](/components/i2c) is required in your configuration for this sensor to work. + +This implementation was inspired by [lewisxhe/XPowersLib Arduino Library](https://github.com/lewisxhe/XPowersLib/). + +## Component/Hub + +The SY6970 component must be defined in your configuration to set up the device. All other platforms below refer to this component. + +```yaml +# Example configuration entry +i2c: + - id: bus_a + sda: GPIO5 + scl: GPIO6 + +sy6970: + id: pmu + address: 0x6A + enable_status_led: true + input_current_limit: 1000 + charge_voltage: 4200 + charge_current: 500 + precharge_current: 128 + charge_enabled: true + enable_adc: true + update_interval: 1s +``` + +## Configuration variables + +- **id** (*Optional*, [ID](/guides/configuration-types#config-id)): Manually specify the ID used for code generation. +- **address** (*Optional*, int): The I²C address of the device. Defaults to `0x6A`. +- **enable_status_led** (*Optional*, boolean): Enable or disable the status LED on the IC. Defaults to `true`. +- **input_current_limit** (*Optional*, int): Input current in milliamps. Accepts values between 100 and 3200. Defaults to `500`. +- **charge_voltage** (*Optional*, int): Charge voltage in millivolts. Accepts values between 3840 and 4608. Defaults to `4208`. +- **charge_current** (*Optional*, int): Charge current in milliamps. Accepts values between 0 and 5056. Defaults to `2048`. +- **precharge_current** (*Optional*, int): Pre-charge current in milliamps. Accepts values between 64 and 1024. Defaults to `128`. +- **charge_enabled** (*Optional*, boolean): Enable or disable charging. Defaults to `true`. +- **enable_adc** (*Optional*, boolean): Enable or disable the ADC. Defaults to `true`. +- All other options from [I²C Device](/components/i2c). +- **update_interval** (*Optional*, [Time](/guides/configuration-types#config-time)): The interval to check the sensor. Defaults to `5s`. + +## Sensor + +The `sy6970` sensor platform exposes voltage and current measurements from the SY6970 IC. + +```yaml +# Example configuration entry +sensor: + - platform: sy6970 + sy6970_id: pmu + vbus_voltage: + name: "VBUS Voltage" + battery_voltage: + name: "Battery Voltage" + system_voltage: + name: "System Voltage" + charge_current: + name: "Charge Current" + precharge_current: + name: "Precharge Current" +``` + +## Sensor Configuration variables + +- **sy6970_id** (*Optional*, [ID](/guides/configuration-types#config-id)): The ID of the SY6970 component. Defaults to the only SY6970 component in your configuration. +- **vbus_voltage** (*Optional*): The voltage on the VBUS (USB) input in volts. + - All options from [Sensor](/components/sensor). +- **battery_voltage** (*Optional*): The battery voltage in volts. + - All options from [Sensor](/components/sensor). +- **system_voltage** (*Optional*): The system voltage in volts. + - All options from [Sensor](/components/sensor). +- **charge_current** (*Optional*): The charging current in milliamps. + - All options from [Sensor](/components/sensor). +- **precharge_current** (*Optional*): The precharge current in milliamps. + - All options from [Sensor](/components/sensor). +- All other options from [Sensor](/components/sensor). + +## Binary Sensor + +The `sy6970` binary sensor platform exposes charging state information from the SY6970 IC. + +```yaml +# Example configuration entry +binary_sensor: + - platform: sy6970 + sy6970_id: pmu + vbus_connected: + name: "VBUS Connected" + charging: + name: "Battery Charging" + charge_done: + name: "Charge Done" +``` + +## Binary Sensor Configuration variables + +- **sy6970_id** (*Optional*, [ID](/guides/configuration-types#config-id)): The ID of the SY6970 component. Defaults to the only SY6970 component in your configuration. +- **vbus_connected** (*Optional*): Indicates whether VBUS (USB power) is connected. + - All options from [Binary Sensor](/components/binary_sensor). +- **charging** (*Optional*): Indicates whether the battery is currently charging. + - All options from [Binary Sensor](/components/binary_sensor). +- **charge_done** (*Optional*): Indicates whether charging is complete. + - All options from [Binary Sensor](/components/binary_sensor). +- All other options from [Binary Sensor](/components/binary_sensor). + +## Text Sensor + +The `sy6970` text sensor platform exposes status information from the SY6970 IC as text. + +```yaml +# Example configuration entry +text_sensor: + - platform: sy6970 + sy6970_id: pmu + bus_status: + name: "Power Source Type" + charge_status: + name: "Charging Status" + ntc_status: + name: "Battery Temperature" +``` + +## Text Sensor Configuration variables + +- **sy6970_id** (*Optional*, [ID](/guides/configuration-types#config-id)): The ID of the SY6970 component. Defaults to the only SY6970 component in your configuration. +- **bus_status** (*Optional*): The type of power source connected. Possible values are: + - `No Input` - No power source connected + - `USB SDP` - USB Standard Downstream Port + - `USB CDP` - USB Charging Downstream Port + - `USB DCP` - USB Dedicated Charging Port + - `HVDCP` - High Voltage Dedicated Charging Port + - `Adapter` - Dedicated adapter + - `Non-Standard Adapter` - Non-standard adapter + - `OTG` - OTG mode + - All options from [Text Sensor](/components/text_sensor). +- **charge_status** (*Optional*): The current charging status. Possible values are: + - `Not Charging` - Battery is not charging + - `Pre-charge` - Battery is in pre-charge phase + - `Fast Charge` - Battery is in fast charge phase + - `Charge Done` - Charging is complete + - All options from [Text Sensor](/components/text_sensor). +- **ntc_status** (*Optional*): The battery temperature status based on NTC thermistor. Possible values are: + - `Normal` - Temperature is in normal range + - `Warm` - Battery is warm + - `Cool` - Battery is cool + - `Cold` - Battery is cold + - `Hot` - Battery is hot + - All options from [Text Sensor](/components/text_sensor). +- All other options from [Text Sensor](/components/text_sensor). + +## Complete Example + +Below is a complete example configuration for the LilyGo T-Display S3 Pro v1: + +```yaml +# Complete configuration example for LilyGo T-Display S3 Pro +i2c: + - id: bus_a + scan: true + sda: GPIO5 + scl: GPIO6 + +sy6970: + id: pmu + address: 0x6A + update_interval: 1s + enable_status_led: true + input_current_limit: 1000 + charge_voltage: 4200 + charge_current: 500 + precharge_current: 128 + charge_enabled: true + enable_adc: true + +sensor: + - platform: sy6970 + sy6970_id: pmu + vbus_voltage: + name: "VBUS Voltage" + battery_voltage: + name: "Battery Voltage" + system_voltage: + name: "System Voltage" + charge_current: + name: "Charge Current" + precharge_current: + name: "Precharge Current" + +text_sensor: + - platform: sy6970 + sy6970_id: pmu + bus_status: + name: "Power Source Type" + charge_status: + name: "Charging Status" + ntc_status: + name: "Battery Temperature" + +binary_sensor: + - platform: sy6970 + sy6970_id: pmu + charging: + name: "Battery Charging" + vbus_connected: + name: "VBUS Connected" + charge_done: + name: "Charge Done" +``` + +## Advanced Configuration + +The SY6970 provides several configuration methods that can be called from automations or scripts: + +```yaml +# Example automation to adjust charging parameters +automation: + - trigger: + - platform: homeassistant + event: start + then: + - lambda: |- + // Set input current limit to 1500mA + id(pmu).set_input_current_limit(1500); + // Set charge target voltage to 4200mV + id(pmu).set_charge_target_voltage(4200); + // Set charge current to 1000mA + id(pmu).set_charge_current(1000); + // Enable charging + id(pmu).set_charge_enabled(true); +``` + +## Available Methods + +- `set_input_current_limit(uint16_t milliamps)` - Set the input current limit (100-3200mA in 50mA steps) +- `set_charge_target_voltage(uint16_t millivolts)` - Set the target charging voltage (3840-4608mV in 16mV steps) +- `set_charge_current(uint16_t milliamps)` - Set the fast charge current (0-5056mA in 64mA steps) +- `set_precharge_current(uint16_t milliamps)` - Set the precharge current (64-1024mA in 64mA steps) +- `set_charge_enabled(bool enabled)` - Set battery charging enabled/disabled +- `set_led_enabled(bool enabled)` - Set status LED to enabled/disabled +- `set_enable_adc_measure(bool enabled)` - Enable ADC measurements + +## Technical Details + +The SY6970 is an I²C controlled battery management IC with the following features: + +- Single-cell Li-Ion/Li-Polymer battery charger +- Wide input voltage range: 4.5V to 14V +- Programmable charge current up to 5A +- Programmable charge voltage up to 4.608V +- Battery over-temperature protection via NTC thermistor +- Automatic power path management +- Built-in ADC for voltage and current monitoring +- Status LED output + +## Register Implementation + +The component directly implements the SY6970 register protocol: + +- **REG_0B**: Bus and charge status (bits 7:5 for bus type, bits 4:3 for charge state) +- **REG_0E**: Battery voltage (base 2304mV, 20mV steps) +- **REG_11**: VBUS voltage (base 2600mV, 100mV steps) +- **REG_12**: Charge current (50mA steps) +- **REG_00-07**: Configuration registers for current limits, charge parameters, and safety timers + +### See Also + +- [SY6970 Datasheet](https://github.com/Xinyuan-LilyGO/LilyGo-AMOLED-Series/blob/master/datasheet/SY6970%20Datasheet.pdf) +- [Sensor](/components/sensor) +- [Binary Sensor](/components/binary_sensor) +- [Text Sensor](/components/text_sensor) +- [I²C Bus](/components/i2c) diff --git a/content/components/sensor/xiaomi_ble.md b/content/components/sensor/xiaomi_ble.md index 36c7d3b702..44af8fe1e3 100644 --- a/content/components/sensor/xiaomi_ble.md +++ b/content/components/sensor/xiaomi_ble.md @@ -25,7 +25,7 @@ Configuration example: ```yaml sensor: - platform: xiaomi_hhccjcy01 - mac_address: XX:XX:XX:XX:XX:XX + mac_address: "XX:XX:XX:XX:XX:XX" temperature: name: "Xiaomi HHCCJCY01 Temperature" moisture: @@ -53,7 +53,7 @@ Configuration example: ```yaml sensor: - platform: xiaomi_gcls002 - mac_address: XX:XX:XX:XX:XX:XX + mac_address: "XX:XX:XX:XX:XX:XX" temperature: name: "GCLS02 Temperature" moisture: @@ -75,7 +75,7 @@ Configuration example: ```yaml sensor: - platform: xiaomi_hhccpot002 - mac_address: XX:XX:XX:XX:XX:XX + mac_address: "XX:XX:XX:XX:XX:XX" moisture: name: "HHCCPOT002 Moisture" conductivity: @@ -93,7 +93,7 @@ Configuration example: ```yaml sensor: - platform: xiaomi_lywsdcgq - mac_address: XX:XX:XX:XX:XX:XX + mac_address: "XX:XX:XX:XX:XX:XX" temperature: name: "LYWSDCGQ Temperature" humidity: @@ -115,7 +115,7 @@ Configuration example: ```yaml sensor: - platform: xiaomi_lywsd02 - mac_address: XX:XX:XX:XX:XX:XX + mac_address: "XX:XX:XX:XX:XX:XX" temperature: name: "LYWSD02 Temperature" humidity: @@ -133,7 +133,7 @@ Configuration example: ```yaml sensor: - platform: xiaomi_lywsd02mmc - mac_address: "A4:C1:38:54:5E:18" + mac_address: "XX:XX:XX:XX:XX:XX" bindkey: "2529d8e0d23150a588675cc54ad48400" temperature: name: "LYWSD02MMC Temperature" @@ -156,7 +156,7 @@ Configuration example: ```yaml sensor: - platform: xiaomi_cgg1 - mac_address: XX:XX:XX:XX:XX:XX + mac_address: "XX:XX:XX:XX:XX:XX" temperature: name: "CGG1 Temperature" humidity: @@ -164,7 +164,7 @@ sensor: battery_level: name: "CGG1 Battery Level" - platform: xiaomi_cgg1 - mac_address: XX:XX:XX:XX:XX:XX + mac_address: "XX:XX:XX:XX:XX:XX" bindkey: "00112233445566778899aabbccddeeff" temperature: name: "CGG1 (New) Temperature" @@ -178,24 +178,25 @@ Hygro thermometer, small square body, segment LCD, encrypted, broadcasts tempera {{< img src="xiaomi_lywsd03mmc.jpg" alt="Image" width="30.0%" class="align-center" >}} -There are the following possibilities to operate this sensor: +There are several ways to operate this sensor: -1. Xiaomi stock firmware (requires a bindkey in order to decrypt the received data, see [Obtaining the Bindkey](#obtaining_the_bindkey)) -1. Device flashed with [PVVX MiThermometer](https://github.com/pvvx/ATC_MiThermometer) custom firmware -1. Device flashed with [ATC MiThermometer](https://github.com/atc1441/ATC_MiThermometer) custom firmware +1. Xiaomi stock firmware (requires a bindkey) +1. Device flashed with [PVVX MiThermometer](https://github.com/pvvx/ATC_MiThermometer) custom firmware, supporting "BTHome v2", "ATC1441", "PVVX (Custom)", "MIJIA (MiHome)" advertisements +1. Device flashed with [ATC MiThermometer](https://github.com/atc1441/ATC_MiThermometer) custom firmware, supporting "Mi Like", "Custom" advertisements -- "Mi Like" advertisement (dummy bindkey required) -- "Custom" advertisement (no bindkey required) -- "pvvx" advertisement (no bindkey required, only PVVX firmware) -- "BTHome" advertisement (no bindkey required, PVVX firmware default) +With PVVX firmware and "BTHome v2" advertisement, encryption with bindkey is supported, just like with Xiaomi stock firmware +(see [Obtaining the Bindkey](#obtaining_the_bindkey)). Unencrypted communication is supported only in custom firmware, but it's not recommended for obvious security reasons. + +> [!NOTE] +> PVVX firmare deprecated any other advertisment format other than "BTHome v2" starting with version 6.0. Configuration example for Xiaomi stock firmware or ATC MiThermometer firmware set to "Mi Like" advertisement: ```yaml sensor: - platform: xiaomi_lywsd03mmc - mac_address: XX:XX:XX:XX:XX:XX - bindkey: "eef418daf699a0c188f3bfd17e4565d9" + mac_address: "XX:XX:XX:XX:XX:XX" + bindkey: "00112233445566778899aabbccddeeff" temperature: name: "LYWSD03MMC Temperature" humidity: @@ -204,12 +205,13 @@ sensor: name: "LYWSD03MMC Battery Level" ``` -Configuration example for PVVX MiThermometer firmware set to "BTHome" advertisement: +Configuration example for PVVX MiThermometer firmware set to "BTHome v2" advertisement: ```yaml sensor: - platform: bthome_mithermometer - mac_address: AA:BB:CC:DD:EE:FF + mac_address: "XX:XX:XX:XX:XX:XX" + bindkey: "00112233445566778899aabbccddeeff" temperature: name: "BTHome Temperature" humidity: @@ -222,12 +224,17 @@ sensor: name: "BTHome Signal" ``` -Configuration example for PVVX MiThermometer firmware set to "pvvx" advertisement: +If you enable "Encrypted beacon" in the PVVX firmware, specify the `bindkey` with the value you see when you press the "Get BindKey" button in Telink Flasher (see [Obtaining the Bindkey](#obtaining_the_bindkey)). + +> [!NOTE] +> Once you've set a `bindkey`, the component will not accept unencrypted beacons from that `mac_address`. The mismatch will be printed in the log. + +Configuration example for PVVX MiThermometer firmware set to "pvvx" advertisement (deprecated): ```yaml sensor: - platform: pvvx_mithermometer - mac_address: XX:XX:XX:XX:XX:XX + mac_address: "XX:XX:XX:XX:XX:XX" temperature: name: "PVVX Temperature" humidity: @@ -240,12 +247,12 @@ sensor: name: "PVVX Signal" ``` -Configuration example for ATC MiThermometer firmware set to "Custom" advertisement: +Configuration example for ATC MiThermometer firmware set to "Custom" advertisement (deprecated): ```yaml sensor: - platform: atc_mithermometer - mac_address: XX:XX:XX:XX:XX:XX + mac_address: "XX:XX:XX:XX:XX:XX" temperature: name: "ATC Temperature" humidity: @@ -258,9 +265,6 @@ sensor: name: "ATC Signal" ``` -> [!NOTE] -> PVVX firmare deprecated any other advertisment format other than "BTHome" starting with version 6.0. - ### XMWSDJ04MMC Hygro thermometer, small square body, e-ink display, encrypted, broadcasts temperature, humidity and battery status. Requires a bindkey in order to decrypt the received data (see [Obtaining the Bindkey](#obtaining_the_bindkey)). @@ -272,8 +276,8 @@ Configuration example: ```yaml sensor: - platform: xiaomi_xmwsdj04mmc - mac_address: XX:XX:XX:XX:XX:XX - bindkey: "eef418daf699a0c188f3bfd17e4565d9" + mac_address: "XX:XX:XX:XX:XX:XX" + bindkey: "00112233445566778899aabbccddeeff" temperature: name: "XMWSDJ04MMC Temperature" humidity: @@ -295,7 +299,7 @@ Configuration example: ```yaml sensor: - platform: xiaomi_mhoc303 - mac_address: XX:XX:XX:XX:XX:XX + mac_address: "XX:XX:XX:XX:XX:XX" temperature: name: "MHO-C303 Climate Temperature" humidity: @@ -325,8 +329,8 @@ Configuration example for Xiaomi stock firmware: ```yaml sensor: - platform: xiaomi_mhoc401 - mac_address: XX:XX:XX:XX:XX:XX - bindkey: "eef418daf699a0c188f3bfd17e4565d9" + mac_address: "XX:XX:XX:XX:XX:XX" + bindkey: "00112233445566778899aabbccddeeff" temperature: name: "MHOC401 Temperature" humidity: @@ -340,7 +344,7 @@ Configuration example for PVVX MiThermometer firmware set to "Custom" advertisem ```yaml sensor: - platform: pvvx_mithermometer - mac_address: XX:XX:XX:XX:XX:XX + mac_address: "XX:XX:XX:XX:XX:XX" temperature: name: "PVVX Temperature" humidity: @@ -362,8 +366,8 @@ Configuration example: ```yaml sensor: - platform: xiaomi_cgd1 - mac_address: XX:XX:XX:XX:XX:XX - bindkey: "fe39106baeedb7c801e3d63c4396f97e" + mac_address: "XX:XX:XX:XX:XX:XX" + bindkey: "00112233445566778899aabbccddeeff" temperature: name: "CGD1 Temperature" humidity: @@ -384,8 +388,8 @@ Configuration example: ```yaml sensor: - platform: xiaomi_cgdk2 - mac_address: XX:XX:XX:XX:XX:XX - bindkey: "fe39106baeedb7c801e3d63c4396f97e" + mac_address: "XX:XX:XX:XX:XX:XX" + bindkey: "00112233445566778899aabbccddeeff" temperature: name: "CGDK2 Temperature" humidity: @@ -405,7 +409,7 @@ Configuration example: ```yaml sensor: - platform: xiaomi_jqjcy01ym - mac_address: XX:XX:XX:XX:XX:XX + mac_address: "XX:XX:XX:XX:XX:XX" temperature: name: "JQJCY01YM Temperature" humidity: @@ -429,7 +433,7 @@ sensor: binary_sensor: - platform: xiaomi_wx08zm - mac_address: XX:XX:XX:XX:XX:XX + mac_address: "XX:XX:XX:XX:XX:XX" tablet: name: "WX08ZM Mosquito Tablet" battery_level: @@ -450,7 +454,7 @@ sensor: binary_sensor: - platform: xiaomi_mue4094rt name: "MUE4094RT Night Light" - mac_address: XX:XX:XX:XX:XX:XX + mac_address: "XX:XX:XX:XX:XX:XX" timeout: "5s" ``` @@ -468,8 +472,8 @@ sensor: binary_sensor: - platform: xiaomi_mjyd02yla name: "MJYD02YL-A Night Light" - mac_address: XX:XX:XX:XX:XX:XX - bindkey: "48403ebe2d385db8d0c187f81e62cb64" + mac_address: "XX:XX:XX:XX:XX:XX" + bindkey: "00112233445566778899aabbccddeeff" idle_time: name: "MJYD02YL-A Idle Time" light: @@ -492,8 +496,8 @@ Configuration example: binary_sensor: - platform: xiaomi_cgpr1 name: "CGPR1 Motion detector" - mac_address: XX:XX:XX:XX:XX:XX - bindkey: "ff1ae526b23b4aebeadcaaad86f59055" + mac_address: "XX:XX:XX:XX:XX:XX" + bindkey: "00112233445566778899aabbccddeeff" idle_time: name: "CGPR1 Idle Time" battery_level: @@ -514,8 +518,8 @@ Configuration example: ```yaml xiaomi_rtcgq02lm: - id: motion_one - mac_address: XX:XX:XX:XX:XX:XX - bindkey: fe39106baeedb7c801e3d63c4396f97e + mac_address: "XX:XX:XX:XX:XX:XX" + bindkey: 00112233445566778899aabbccddeeff binary_sensor: - platform: xiaomi_rtcgq02lm @@ -578,35 +582,25 @@ It can sometimes take some time for the first BLE broadcast to be received. Once ## Obtaining the Bindkey -To set up an encrypted device such as the LYWSD03MMC (with Xiaomi stock firmware) and CGD1, you first need to obtain the bind key. The `xiaomi_ble` sensor component is not able to automatically generate a bindkey so other workarounds are necessary. - -### LYWSD03MMC/MHO-C401 - -If the LYWSD03MMC or MHO-C401 sensor is operated with the Xiaomi stock firmware, you can use the [TeLink flasher application](https://atc1441.github.io/TelinkFlasher.html) to easily generate a new bind key and upload the key to the device without the need to flash a new firmware (see figure). For this, you load the flasher [webpage](https://atc1441.github.io/TelinkFlasher.html) with a [supported browser](https://github.com/WebBluetoothCG/web-bluetooth/blob/master/implementation-status.md) and connect the device by pressing "Connect". After the connection is established, you press the "Do Activation" button and the new key will be shown in the "Mi Bind Key" field. The key can be copied directly into the sensor YAML configuration. - -{{< img src="telink_flasher.jpg" alt="Image" caption="Telink flasher application." width="100.0%" class="align-center" >}} +To set up an encrypted device you need to obtain the `bindkey`. The `xiaomi_ble` sensor component is not able to automatically generate a bindkey so other workarounds are necessary. > [!WARNING] -> The new bind key will work with ESPHome, but the Mi Home app will not recognise the sensor anymore once the device has been activated by the TeLink flasher application. To use the sensor again with the Xiaomi Mi Home app, the device needs to be removed and then re-added inside the Mi Home app. - -### CGDK2 - -The method to obtain a new bind key for the CGDK2 sensor is similar to the method for the LYWSD03MMC sensor, except a modified version of the flasher application is used. - -For this, you load the [application](https://zaluthar.github.io/TelinkFlasher.html) with a [supported browser](https://github.com/WebBluetoothCG/web-bluetooth/blob/master/implementation-status.md) and connect the device by pressing "Connect". After the connection is established, you press the "Do Activation" button and the new key will be shown in the "Mi Bind Key" field. The key can be copied directly into the sensor YAML configuration. +> If you keep the stock firmware, the new bind key will work with ESPHome, but the Mi Home app will not recognise the sensor anymore once the device has been activated by the TeLink flasher application. +> To use the sensor again with the Xiaomi Mi Home app, the device needs to be removed and then re-added inside the Mi Home app. -### Other encrypted devices +### LYWSD03MMC, CGD1 and most other encrypted devices -- The easiest method (confirmed to work for LYWSD03MMC) is to use the [Telink flasher method](https://github.com/pvvx/ATC_MiThermometer). The accompanying [video](https://www.youtube.com/watch?v=NXKzFG61lNs) shows how to wirelessly flash a LYWSD03MMC, or how to obtain the bind key of the stock firmware +- The easiest method is to use [PVVX](https://github.com/pvvx/ATC_MiThermometer)'s [Telink flasher method](https://github.com/pvvx/ATC_MiThermometer). The accompanying + [video](https://www.youtube.com/watch?v=NXKzFG61lNs) shows how to wirelessly flash a LYWSD03MMC, or how to obtain the bind key of the stock firmware (watch till around 13:10). The custom firmware allows you to change several settings of the device, including the smiley and the advertising interval. - Follow the instructions on the site using Telink Flasher - best results with a Bluetooth-enabled Android phone. Note that with `pvvx` default settings - advertisment is set to `Custom` with no encryption. No need for `bind_key` in this case, you can just add the sensors to your ESPHome config as described above. + Follow the instructions on the site using Telink Flasher - best results with a Bluetooth-enabled Android phone. Note that by default there's no encryption set, + thus no need for `bind_key` in this case, you can just add the sensors to your ESPHome config as described above. However, if you do enable the "Encrypted beacon" + checkbox, scroll down to the bottom of the page press the “Get BindKey” button to see the key. - The other option is to use the original Mi Home app to add the sensor once. While adding the device, a new key is generated and uploaded into the Xiaomi cloud - and to the device itself. Currently a chinese server needs to be selected as the rest of the world doesn't support most of these devices yet. Once generated, - the key will not change again until the device is removed and re-added in the Xiaomi app. + and to the device itself. Once generated, the key will not change again until the device is removed and re-added in the Xiaomi app. - - The easiest method to retrieve the bindkey from the cloud is to use the + - To retrieve the bindkey from the cloud you can use the [Cloud Tokens Extractor](https://github.com/PiotrMachowski/Xiaomi-cloud-tokens-extractor), written by one of Home Assistant users. If you prefer to not use the executable, read [the Home Assistant Documentation](https://www.home-assistant.io/integrations/xiaomi_miio/#xiaomi-cloud-tokens-extractor). @@ -624,24 +618,27 @@ For this, you load the [application](https://zaluthar.github.io/TelinkFlasher.ht The `bind_key` is the 32 digits "value" item in the above output which needs to be inserted into the config file. +- If the LYWSD03MMC or MHO-C401 sensor is operated with the Xiaomi stock firmware, you can also use ATC's [TeLink flasher application](https://atc1441.github.io/TelinkFlasher.html) + to easily generate a new bind key and upload the key to the device without the need to flash a new firmware (see figure). For this, you load the flasher + [webpage](https://atc1441.github.io/TelinkFlasher.html) with a [supported browser](https://github.com/WebBluetoothCG/web-bluetooth/blob/master/implementation-status.md) + and connect the device by pressing "Connect". After the connection is established, you press the "Do Activation" button and the new key will be shown in the "Mi Bind Key" + field. The key can be copied directly into the sensor YAML configuration. + +{{< img src="telink_flasher.jpg" alt="Image" caption="Telink flasher application." width="100.0%" class="align-center" >}} + +- For CGDK2 can also load Zaluthar's [application](https://zaluthar.github.io/TelinkFlasher.html) with a [supported browser](https://github.com/WebBluetoothCG/web-bluetooth/blob/master/implementation-status.md) + and connect the device by pressing "Connect". After the connection is established, you press the "Do Activation" button and the new key will be shown in the "Mi Bind Key" + field. The key can be copied directly into the sensor YAML configuration. + ## Improving reception performance Use a board with an Ethernet connection to the network, to offload ESP32's radio module from WiFi traffic, this gains performance on Bluetooth side. -To maximize the chances of catching advertisements of the sensors, you can set `interval` equal to `window` in {{< docref "/components/esp32_ble_tracker" >}} scan parameter settings: - -```yaml -esp32_ble_tracker: - scan_parameters: - interval: 5s # try with 300ms if you don't have LAN module - window: 5s # try with 300ms if you don't have LAN module - active: false -``` Avoid placing the ESP node in racks, close to routers/switches or other network equipment as EMI interference will degrade Bluetooth signal reception. For best results put as far away as possible, at least 3 meters distance from any other such equipment. ## Security considerations -You should at least protect your sensors with a custom pairing PIN code. Choose a method employing bindkey in order to use encrypted communication over the air. +You should at least protect your sensors with a custom pairing PIN code. Choose a method employing `bindkey` in order to use encrypted communication over the air, and prevent accepting spoofed messages. ## See Also diff --git a/content/components/web_server.md b/content/components/web_server.md index fa7cc1a51c..d45e0fa7d1 100644 --- a/content/components/web_server.md +++ b/content/components/web_server.md @@ -68,8 +68,9 @@ web_server: Defaults to `false`. - **compression** (*Optional*, string): The compression algorithm used for embedded web assets when `local` is enabled. - Options are `br` (Brotli) or `gzip`. Brotli typically results in smaller embedded web assets than gzip, especially for - text-based resources, but the exact size difference depends on the assets being compressed. Defaults to `br`. + Options are `gzip` or `br` (Brotli). Brotli provides smaller embedded web assets (~10% smaller than gzip), but some + browsers only support Brotli over HTTPS connections. Since ESPHome devices typically serve over HTTP, gzip + is recommended for maximum compatibility. Defaults to `gzip`. - **version** (*Optional*, string): `1`, `2` or `3`. Version 1 displays as a table. Version 2 uses web components and has more functionality. Version 3 uses HA-Styling. Defaults to `2`. diff --git a/content/guides/diy.md b/content/guides/diy.md index 86a4bd7434..bd153ff24a 100644 --- a/content/guides/diy.md +++ b/content/guides/diy.md @@ -105,6 +105,7 @@ unless it's truly exceptional, etc. - [Digoo DG-R8H and similar nexus433 sensors to MQTT component](https://github.com/FreeBear-nc/esphome-nexus433) by {{< ghuser name="FreeBear-nc" >}} - [Adaptive Lighting for white/warm lights](https://github.com/mdvorak/esphome-adaptive-lighting) by {{< ghuser name="mdvorak" >}} - [Connecting the PAJ7620 gesture sensor](https://github.com/apaex/PAJ7620-ESPHome) by {{< ghuser name="apaex" >}} +- [Dew Point Sensor using Magnus formula](https://github.com/iret33/esphome-dew-point) by {{< ghuser name="iret33" >}} ## Sample Configurations diff --git a/data/version.yaml b/data/version.yaml index 3dbb979e58..05c0a85549 100644 --- a/data/version.yaml +++ b/data/version.yaml @@ -1,2 +1,2 @@ -release: 2026.1.1 +release: 2026.1.0b2 version: '2026.1' diff --git a/static/images/sy6970.jpg b/static/images/sy6970.jpg new file mode 100644 index 0000000000..3427aa216a Binary files /dev/null and b/static/images/sy6970.jpg differ