Upstream/esphome-docs
1
0
Fork 0
mirror of https://github.com/esphome/esphome-docs.git synced 2025-11-18 06:34:33 +01:00
Code Issues Projects Releases Wiki Activity

Migrate shortcode admonitions to markdown (#5433)

Browse Source
This commit is contained in:
Jesse Hills 2025-10-01 14:00:40 +13:00 committed by GitHub
parent 5c00d9cb72
commit beca60fa06
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
306 changed files with 3375 additions and 4420 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.markdownlintrc
View File

@ -7,6 +7,7 @@
"MD024": {
"siblings_only": true
},
"MD028": false,
"MD029": {
"style": "one"
},

7
content/automations/actions.md
View File

@ -178,11 +178,10 @@ on_...:
- delay: !lambda "if (id(reed_switch).state) return 1000; else return 0;"
```
{{< note >}}
This is a "smart" asynchronous delay - other code will still run in the background while
the delay is happening. When using a lambda call, you should return the delay value in milliseconds.
> [!NOTE]
> This is a "smart" asynchronous delay - other code will still run in the background while
> the delay is happening. When using a lambda call, you should return the delay value in milliseconds.
{{< /note >}}
{{< anchor "if_action" >}}
### `if` Action

32
content/automations/templates.md
View File

@ -55,25 +55,23 @@ Finally, `id(...)` is a helper function that makes ESPHome fetch an object with
somewhere else, like `top_end_stop` ) and lets you call any of ESPHome's many APIs directly. For example, here we're
retrieving the current state of the end stop using `.state` and using it to construct our cover state.
{{< note >}}
ESPHome does not check the validity of lambda expressions you enter and will blindly copy them into the generated
C++ code. If compilation fails or something else is not working as expected with lambdas, it's always best to look
at the generated C++ source file under `<NODE_NAME>/src/main.cpp`.
> [!NOTE]
> ESPHome does not check the validity of lambda expressions you enter and will blindly copy them into the generated
> C++ code. If compilation fails or something else is not working as expected with lambdas, it's always best to look
> at the generated C++ source file under `<NODE_NAME>/src/main.cpp`.
{{< /note >}}
{{< tip >}}
To store local variables inside lambdas that retain their value across executions, you can create `static`
variables as shown in the example below. Here, the variable `num_executions` is incremented by one each time the
lambda is executed and the current value is logged.
> [!TIP]
> To store local variables inside lambdas that retain their value across executions, you can create `static`
> variables as shown in the example below. Here, the variable `num_executions` is incremented by one each time the
> lambda is executed and the current value is logged.
>
> ```yaml
> lambda: |-
> static int num_executions = 0;
> ESP_LOGD("main", "I am at execution number %d", num_executions);
> num_executions += 1;
> ```
```yaml
lambda: |-
static int num_executions = 0;
ESP_LOGD("main", "I am at execution number %d", num_executions);
num_executions += 1;
```
{{< /tip >}}
{{< anchor "config-templatable" >}}
## Templating Actions

7
content/changelog/2022.12.0.md
View File

@ -32,11 +32,10 @@ of the performance increases for bluetooth, it is best to at least one serial fl
## Container images
{{< note >}}
This breaking change only affects you if you use docker containers directly and specify the suffix
in your image.
> [!NOTE]
> This breaking change only affects you if you use docker containers directly and specify the suffix
> in your image.
{{< /note >}}
2022.12.6 changes the way the container images are built and published. This is due to something
breaking somewhere that we could not explain. It has to do with the `docker manifest` command
which has been around for a while but always been marked as `experimental` so we cannot really

8
content/changelog/2023.2.0.md
View File

@ -31,11 +31,9 @@ params:
ESPHome now supports setting a `friendly_name` which is sent to Home Assistant. This name will be used for the config entry,
the device name, and will be automatically prefixed to all of the entities where needed by Home Assistant.
{{< note >}}
If you opt to use this new friendly name, take note that you should remove any friendly name (substitition) that
you currently prepend onto entity `name` in YAML.
{{< /note >}}
> [!NOTE]
> If you opt to use this new friendly name, take note that you should remove any friendly name (substitition) that
> you currently prepend onto entity `name` in YAML.
```yaml
esphome:

10
content/changelog/2023.9.0.md
View File

@ -69,12 +69,10 @@ This was done because it is exactly what the add-on `/data` folder was made for
that were making the Home Assistant Backup larger for no reason at all. All files in there are generated or sourced from online based
on your configurations files which have not been touched.
{{< note >}}
2023.9.1 makes a further small change that moves the `json` files used by the dashboard into the new `/data` folder.
If you had already updated to 2023.9.0 though, the files would have already been removed and they will be re-generated
next time you install each device.
{{< /note >}}
> [!NOTE]
> 2023.9.1 makes a further small change that moves the `json` files used by the dashboard into the new `/data` folder.
> If you had already updated to 2023.9.0 though, the files would have already been removed and they will be re-generated
> next time you install each device.
### Enum device class

6
content/changelog/2024.6.0.md
View File

@ -69,10 +69,8 @@ update available for this device. You do not need to adopt the device into the E
you don't actually need the ESPHome dashboard installed. Using the new `http_request` OTA platform,
the device will be able to download the firmware and update itself.
{{< note >}}
Update Entities require at least Home Assistant 2024.7 to show up and be controlled in the Home Assistant UI.
{{< /note >}}
> [!NOTE]
> Update Entities require at least Home Assistant 2024.7 to show up and be controlled in the Home Assistant UI.
### Voice Assistant Timers

48
content/changelog/2025.6.0.md
View File

@ -34,17 +34,15 @@ This version bump brings expanded microcontroller support. ESPHome now officiall
- **ESP32-S3** - Dual-core Xtensa LX7 with Wi-Fi and Bluetooth 5 (LE)
- **ESP32-P4** - Dual-core RISC-V high-performance variant *(new)*
{{< note >}}
The newly supported variants (ESP32-C6, ESP32-H2, ESP32-P4) are still being refined. Some components may not yet
be fully compatible with these chips. Additional component updates are planned for ESPHome 2025.7.0.
They also currently only support using the ESP-IDF framework, and do not work with the Arduino framework in this
release.
Please check our [Pull Requests](https://github.com/esphome/esphome/pulls) for the latest compatibility status
before reporting issues with these new variants.
{{< /note >}}
> [!NOTE]
> The newly supported variants (ESP32-C6, ESP32-H2, ESP32-P4) are still being refined. Some components may not yet
> be fully compatible with these chips. Additional component updates are planned for ESPHome 2025.7.0.
>
> They also currently only support using the ESP-IDF framework, and do not work with the Arduino framework in this
> release.
>
> Please check our [Pull Requests](https://github.com/esphome/esphome/pulls) for the latest compatibility status
> before reporting issues with these new variants.
### ESP-IDF 4.x Support
@ -53,13 +51,11 @@ the default Arduino version to 3.1.3, which is now built on IDF 5.x and, as such
ESP-IDF 4.x support to maintain compatibility with Arduino. Please see
[our developer blog](https://developers.esphome.io/blog/2025/06/18/sunsetting-support-for-idf-4x/) for more details.
{{< warning >}}
Device configurations held back on ESP-IDF 4.x are unlikely to compile with the next ESPHome release (2025.7.0).
You can continue to use older versions of ESPHome, but you'll need to ensure your device configurations are using
IDF 5.x if you wish to upgrade to 2025.7.0 or later releases of ESPHome.
{{< /warning >}}
> [!WARNING]
> Device configurations held back on ESP-IDF 4.x are unlikely to compile with the next ESPHome release (2025.7.0).
>
> You can continue to use older versions of ESPHome, but you'll need to ensure your device configurations are using
> IDF 5.x if you wish to upgrade to 2025.7.0 or later releases of ESPHome.
## OpenThread
@ -113,11 +109,9 @@ upgrade both timely and necessary for long-term security and maintainability.
| Container Images (Docker) | **No action needed** - Already uses Python 3.12 |
| Direct Installation (pip) | Ensure Python 3.10+ is installed before running `pip install -U esphome` |
{{< warning >}}
If you're running ESPHome directly on your machine with Python 3.9 or older, running `pip install -U esphome`
will not upgrade beyond version 2025.5.2. You must upgrade your Python installation first.
{{< /warning >}}
> [!WARNING]
> If you're running ESPHome directly on your machine with Python 3.9 or older, running `pip install -U esphome`
> will not upgrade beyond version 2025.5.2. You must upgrade your Python installation first.
## Performance Optimizations
@ -151,11 +145,9 @@ that removes the Arduino framework dependency. This improvement means:
This change makes the BME68x environmental sensors more versatile and easier to integrate into ESP-IDF projects,
continuing ESPHome's move toward framework flexibility.
{{< note >}}
This change applies *only* to the {{< docref "/components/sensor/bme68x_bsec2" "BME68x BSEC2 sensor component" >}}.
It does not apply to the older, now-outdated {{< docref "/components/sensor/bme680_bsec" "BME680 BSEC sensor component" >}}.
{{< /note >}}
> [!NOTE]
> This change applies *only* to the {{< docref "/components/sensor/bme68x_bsec2" "BME68x BSEC2 sensor component" >}}.
> It does not apply to the older, now-outdated {{< docref "/components/sensor/bme680_bsec" "BME680 BSEC sensor component" >}}.
<!-- markdownlint-disable MD013 -->

59
content/changelog/2025.7.0.md
View File

@ -47,12 +47,11 @@ and introducing powerful new features for advanced users.
## Web Server OTA Platform
{{< warning >}}
**Breaking Change:** Read this carefully! If your only OTA method is `web_server` and you don't have it explicitly
enabled, you will lose the ability to update devices OTA after updating to 2025.7.0. You must add the `web_server`
OTA platform to your configuration to maintain OTA functionality.
> [!WARNING]
> **Breaking Change:** Read this carefully! If your only OTA method is `web_server` and you don't have it explicitly
> enabled, you will lose the ability to update devices OTA after updating to 2025.7.0. You must add the `web_server`
> OTA platform to your configuration to maintain OTA functionality.
{{< /warning >}}
The {{< docref "/components/web_server" >}} component has undergone a significant architectural change. Previously,
OTA functionality was built directly into the web server component. This has now been extracted into a dedicated
OTA platform: {{< docref "/components/ota/web_server" >}}.
@ -84,11 +83,10 @@ ota:
## ESP-IDF 4.x End of Life
{{< important >}}
**Major Platform Change:** This release completely removes support for ESP-IDF 4.x versions, marking the end of life
for these older framework versions.
> [!IMPORTANT]
> **Major Platform Change:** This release completely removes support for ESP-IDF 4.x versions, marking the end of life
> for these older framework versions.
{{< /important >}}
ESPHome 2025.7.0 removes all support for ESP-IDF 4.x versions as part of our commitment to supporting modern,
secure, and well-maintained development frameworks. Please see our
[developer blog post](https://developers.esphome.io/blog/2025/06/18/sunsetting-support-for-idf-4x/) for detailed
@ -130,11 +128,10 @@ esp32:
## ESP32 Arduino Framework 3.x
{{< note >}}
**Framework Update:** Arduino for ESP32 has been upgraded to version 3.1.3, bringing significant improvements
and maintaining compatibility with ESP-IDF 5.3.2.
> [!NOTE]
> **Framework Update:** Arduino for ESP32 has been upgraded to version 3.1.3, bringing significant improvements
> and maintaining compatibility with ESP-IDF 5.3.2.
{{< /note >}}
To maintain alignment and compatibility with the current ESP-IDF version of 5.3.2, the Arduino framework for ESP32
has been updated to version 3.1.3. This represents a major version jump from Arduino 2.x.
@ -152,24 +149,22 @@ has been updated to version 3.1.3. This represents a major version jump from Ard
- Timing-sensitive code might behave slightly differently due to framework optimizations
- Memory usage patterns may change slightly due to framework improvements
{{< note >}}
**Flash Usage Warning:** Arduino 3.x can use more flash memory than Arduino 2.x, which may cause some projects
with many components to exceed available flash space. If you encounter flash size issues, consider:
> [!NOTE]
> **Flash Usage Warning:** Arduino 3.x can use more flash memory than Arduino 2.x, which may cause some projects
> with many components to exceed available flash space. If you encounter flash size issues, consider:
>
> - Switching to ESP-IDF framework (recommended for large projects)
> - Reducing the number of enabled components
> - Using a board with more flash memory
- Switching to ESP-IDF framework (recommended for large projects)
- Reducing the number of enabled components
- Using a board with more flash memory
{{< /note >}}
Most users will see this as a transparent improvement with better performance and reliability.
## Sub-Device Support
{{< note >}}
**New Feature:** Entities can now be organized into logical sub-devices, enabling better organization
and area management in Home Assistant.
> [!NOTE]
> **New Feature:** Entities can now be organized into logical sub-devices, enabling better organization
> and area management in Home Assistant.
{{< /note >}}
ESPHome now supports **sub-devices**, a powerful new feature that allows you to logically group entities from a single
physical ESPHome device into multiple virtual devices within Home Assistant. This is particularly useful for complex
setups where one ESP32 controls sensors or actuators in different areas of your home.
@ -290,11 +285,10 @@ resource-constrained devices:
## Jinja2 Template Expressions in Substitutions
{{< note >}}
**New Feature:** ESPHome now supports Jinja2 template expressions within substitutions,
enabling more advanced and dynamic value generation.
> [!NOTE]
> **New Feature:** ESPHome now supports Jinja2 template expressions within substitutions,
> enabling more advanced and dynamic value generation.
{{< /note >}}
ESPHome 2025.7.0 introduces support for Jinja2 template expressions within the existing substitutions system.
This enhancement extends the current `${ }` substitution syntax to support Jinja2 expressions, allowing for
more sophisticated value calculations and transformations.
@ -365,11 +359,10 @@ For complete documentation and more examples, see the {{< docref "/components/su
## ArduinoJson Library 7.x
{{< warning >}}
**Breaking Change:** The ArduinoJson library has been upgraded from version 6.x to 7.2.0, introducing
breaking changes that may affect custom components and external integrations.
> [!WARNING]
> **Breaking Change:** The ArduinoJson library has been upgraded from version 6.x to 7.2.0, introducing
> breaking changes that may affect custom components and external integrations.
{{< /warning >}}
ESPHome 2025.7.0 upgrades the ArduinoJson library to version 7.2.0, bringing performance improvements and
reduced memory usage. Most users will not be affected as all standard ESPHome components have been updated.
However, if you have external components, or lambdas that directly use ArduinoJson, you may need

8
content/components/alarm_control_panel/_index.md
View File

@ -22,11 +22,9 @@ Configuration variables:
- **id** (*Optional*, string): Manually specify the ID for code generation. At least one of **id** and **name** must be specified.
- **name** (*Optional*, string): The name of the alarm control panel. At least one of **id** and **name** must be specified.
{{< note >}}
If you have a [friendly_name](#esphome-configuration_variables) set for your device and
you want the switch to use that name, you can set `name: None`.
{{< /note >}}
> [!NOTE]
> If you have a [friendly_name](#esphome-configuration_variables) set for your device and
> you want the switch to use that name, you can set `name: None`.
- **on_state** (*Optional*, [Action](#config-action)): An automation to perform
when the alarm changes state. See [`on_state` Trigger](#alarm_control_panel_on_state_trigger).

19
content/components/alarm_control_panel/template.md
View File

@ -56,11 +56,10 @@ alarm_control_panel:
- All other options from [Alarm Control Panel](#config-alarm_control_panel)
{{< note >}}
If `binary_sensors` is omitted then you're expected to trigger the alarm using
[`pending` Action](#alarm_control_panel_pending_action) or [`triggered` Action](#alarm_control_panel_triggered_action).
> [!NOTE]
> If `binary_sensors` is omitted then you're expected to trigger the alarm using
> [`pending` Action](#alarm_control_panel_pending_action) or [`triggered` Action](#alarm_control_panel_triggered_action).
{{< /note >}}
{{< anchor "template_alarm_control_panel-trigger_modes" >}}
## Trigger Modes
@ -129,13 +128,11 @@ or the pending timer expires.
1. If `trigger_time` greater than 0 and no sensors are `on` after `trigger_time` delay
the state returns to `ARM_...`
{{< note >}}
Although the interface supports all arming modes only `away`, `home` and `night` have been implemented for now.
`arm_...` is for either `arm_away` or `arm_home`
`arming_..._time` is for either `arming_away_time`, `arming_home_time`, or `arming_night_time`
`ARMED_...` is for either `ARMED_AWAY`, `ARMED_HOME`, or `ARMED_NIGHT`
{{< /note >}}
> [!NOTE]
> Although the interface supports all arming modes only `away`, `home` and `night` have been implemented for now.
> `arm_...` is for either `arm_away` or `arm_home`
> `arming_..._time` is for either `arming_away_time`, `arming_home_time`, or `arming_night_time`
> `ARMED_...` is for either `ARMED_AWAY`, `ARMED_HOME`, or `ARMED_NIGHT`
## Example

20
content/components/animation.md
View File

@ -35,17 +35,15 @@ display:
Additionally, you can use the `animation.next_frame`, `animation.prev_frame` or `animation.set_frame` actions.
{{< note >}}
To draw the next animation independent of Display draw cycle use an interval:
```yaml
interval:
- interval: 5s
then:
animation.next_frame: my_animation
```
{{< /note >}}
> [!NOTE]
> To draw the next animation independent of Display draw cycle use an interval:
>
> ```yaml
> interval:
> - interval: 5s
> then:
> animation.next_frame: my_animation
> ```
## Configuration variables

51
content/components/api.md
View File

@ -20,13 +20,11 @@ The ESPHome native API is based on a custom TCP protocol using protocol buffers.
the protocol data structure definitions here: [api.proto](https://github.com/esphome/esphome/blob/dev/esphome/components/api/api.proto)
A Python library that implements this protocol is [aioesphomeapi](https://github.com/esphome/aioesphomeapi).
{{< note >}}
**Actions** were previously called **Services**. ESPHome changed the name in line with
[Home Assistant](https://developers.home-assistant.io/blog/2024/07/16/service-actions/)
but will continue to support YAML with `services` and `homeassistant.service` for the foreseeable future.
Documentation will only refer to **Actions**.
{{< /note >}}
> [!NOTE]
> **Actions** were previously called **Services**. ESPHome changed the name in line with
> [Home Assistant](https://developers.home-assistant.io/blog/2024/07/16/service-actions/)
> but will continue to support YAML with `services` and `homeassistant.service` for the foreseeable future.
> Documentation will only refer to **Actions**.
```yaml
# Example configuration entry
@ -55,10 +53,8 @@ api:
If you need a key, you can use the key below; it is randomly generated by your browser each time this page loads:
{{< api-key-input >}}
{{< note >}}
Support for configuring the encryption key on-the-fly will be implemented in a future release of Home Assistant.
{{< /note >}}
> [!NOTE]
> Support for configuring the encryption key on-the-fly will be implemented in a future release of Home Assistant.
- **actions** (*Optional*, list): A list of user-defined actions. See [User-defined Actions](#api-device-actions).
- **batch_delay** (*Optional*, [Time](#config-time)): The delay time for batching multiple state update messages
@ -66,13 +62,11 @@ Support for configuring the encryption key on-the-fly will be implemented in a f
while higher values batch more efficiently but add latency. Must be between `0ms` and `65535ms`
(65.535 seconds). Defaults to `100ms`.
{{< note >}}
Setting `batch_delay: 0ms` enables immediate sending mode for state updates. This is useful for
applications that require real-time responsiveness, such as IR remote binary sensors where rapid
ON→OFF transitions must be preserved. However, this will increase network traffic and may impact
WiFi performance with many rapidly-changing sensors. Only use this setting when necessary.
{{< /note >}}
> [!NOTE]
> Setting `batch_delay: 0ms` enables immediate sending mode for state updates. This is useful for
> applications that require real-time responsiveness, such as IR remote binary sensors where rapid
> ON→OFF transitions must be preserved. However, this will increase network traffic and may impact
> WiFi performance with many rapidly-changing sensors. Only use this setting when necessary.
- **custom_services** (*Optional*, boolean): Enable compilation of custom API services for external components that use the C++ `CustomAPIDevice` class. Only needed when external components register their own services via the native API. Defaults to `false`.
- **homeassistant_services** (*Optional*, boolean): Enable compilation of Home Assistant service call support for external components that use the C++ `CustomAPIDevice::call_homeassistant_service()` or `CustomAPIDevice::fire_homeassistant_event()` methods. This is automatically enabled when using `homeassistant.service` or `homeassistant.event` actions, or the `homeassistant` platform for number or switch components. Only needs to be manually set when external components call Home Assistant services without using the built-in actions. Defaults to `false`.
@ -117,11 +111,10 @@ Then:
### `homeassistant.event` Action
{{< note >}}
Be sure to [follow the instructions above](#api-actions) to tell Home Assistant to allow
your device to perform actions.
> [!NOTE]
> Be sure to [follow the instructions above](#api-actions) to tell Home Assistant to allow
> your device to perform actions.
{{< /note >}}
When using the native API with Home Assistant, you can create events in the Home Assistant event bus
straight from ESPHome [Automations](#automation).
@ -149,11 +142,10 @@ on_...:
### `homeassistant.action` Action
{{< note >}}
Be sure to [follow the instructions above](#api-actions) to tell Home Assistant to allow
your device to perform actions.
> [!NOTE]
> Be sure to [follow the instructions above](#api-actions) to tell Home Assistant to allow
> your device to perform actions.
{{< /note >}}
When using the native API with Home Assistant, you can perform Home Assistant actions straight from ESPHome [Automations](#automation).
```yaml
@ -225,11 +217,10 @@ on_...:
### `homeassistant.tag_scanned` Action
{{< note >}}
Be sure to [follow the instructions above](#api-actions) to tell Home Assistant to allow
your device to make action calls.
> [!NOTE]
> Be sure to [follow the instructions above](#api-actions) to tell Home Assistant to allow
> your device to make action calls.
{{< /note >}}
When using the native API with Home Assistant, you can push tag_scanned to Home Assistant
straight from ESPHome [Automations](#automation).

7
content/components/at581x.md
View File

@ -103,11 +103,10 @@ switch:
### `at581x.settings` Action
{{< warning >}}
The hardware frontend reset option is only required to reset the frontend in case it is struck, before sending the
new configuration. However, a frontend reset is always performed after changing the settings.
> [!WARNING]
> The hardware frontend reset option is only required to reset the frontend in case it is struck, before sending the
> new configuration. However, a frontend reset is always performed after changing the settings.
{{< /warning >}}
The radar has several settings which can be changed. These settings are not saved in non-volatile memory
and need to be set on each boot.

54
content/components/binary_sensor/_index.md
View File

@ -30,11 +30,9 @@ Configuration variables:
- **id** (*Optional*, string): Manually specify the ID for code generation. At least one of **id** and **name** must be specified.
- **name** (*Optional*, string): The name for the binary sensor. At least one of **id** and **name** must be specified.
{{< note >}}
If you have a [friendly_name](#esphome-configuration_variables) set for your device and
you want the binary sensor to use that name, you can set `name: None`.
{{< /note >}}
> [!NOTE]
> If you have a [friendly_name](#esphome-configuration_variables) set for your device and
> you want the binary sensor to use that name, you can set `name: None`.
- **device_class** (*Optional*, string): The device class for the
sensor. See <https://www.home-assistant.io/integrations/binary_sensor/#device-class>
@ -357,26 +355,25 @@ Configuration variables:
- **max_length** (*Optional*, [Time](#config-time)): The maximum duration the click should last. Defaults to `350ms`.
- See [Automation](#automation).
{{< note >}}
Multiple `on_click` entries can be defined like this (see also [`on_multi_click`](#binary_sensor-on_multi_click)
for more complex matching):
> [!NOTE]
> Multiple `on_click` entries can be defined like this (see also [`on_multi_click`](#binary_sensor-on_multi_click)
> for more complex matching):
>
> ```yaml
> binary_sensor:
> - platform: gpio
> # ...
> on_click:
> - min_length: 50ms
> max_length: 350ms
> then:
> - switch.turn_off: relay_1
> - min_length: 500ms
> max_length: 1000ms
> then:
> - switch.turn_on: relay_1
> ```
```yaml
binary_sensor:
- platform: gpio
# ...
on_click:
- min_length: 50ms
max_length: 350ms
then:
- switch.turn_off: relay_1
- min_length: 500ms
max_length: 1000ms
then:
- switch.turn_on: relay_1
```
{{< /note >}}
{{< anchor "binary_sensor-on_double_click" >}}
### `on_double_click`
@ -437,12 +434,11 @@ Configuration variables:
- See [Automation](#automation).
{{< note >}}
Getting the timing right for your use-case can sometimes be a bit difficult. If you set the
[global log level](#logger-log_levels) to `VERBOSE`, the multi click trigger shows logs
about what stopped the trigger from happening.
> [!NOTE]
> Getting the timing right for your use-case can sometimes be a bit difficult. If you set the
> [global log level](#logger-log_levels) to `VERBOSE`, the multi click trigger shows logs
> about what stopped the trigger from happening.
{{< /note >}}
You can use an `OFF` timing at the end of the timing sequence to differentiate between different
kinds of presses. For example the configuration below will differentiate between double, long and short
presses.

21
content/components/binary_sensor/ble_presence.md
View File

@ -9,14 +9,13 @@ params:
The `ble_presence` binary sensor platform lets you track the presence of a Bluetooth Low Energy device.
{{< warning >}}
The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
> [!WARNING]
> The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
>
> **Crashes are likely to occur** if you include too many additional components in your device's
> configuration. Memory-intensive components such as {{< docref "/components/voice_assistant" >}} and other
> audio components are most likely to cause issues.
**Crashes are likely to occur** if you include too many additional components in your device's
configuration. Memory-intensive components such as {{< docref "/components/voice_assistant" >}} and other
audio components are most likely to cause issues.
{{< /warning >}}
{{< img src="esp32_ble-ui.png" alt="Image" width="80.0%" class="align-center" >}}
```yaml
@ -44,11 +43,9 @@ binary_sensor:
name: "ESP32 BLE Tracker Test Service iBeacon"
```
{{< note >}}
Service UUID can be 16 bit long, as in the example, but it can also be 32 bit long
like `1122aaff`, or 128 bit long like `11223344-5566-7788-99aa-bbccddeeff00`.
{{< /note >}}
> [!NOTE]
> Service UUID can be 16 bit long, as in the example, but it can also be 32 bit long
> like `1122aaff`, or 128 bit long like `11223344-5566-7788-99aa-bbccddeeff00`.
## Configuration variables

6
content/components/binary_sensor/cap1188.md
View File

@ -62,10 +62,8 @@ Configuration variables:
- **channel** (**Required**, int): The channel number the CAP1188 the touchkey is connected to.
- All other options from [Binary Sensor](#config-binary_sensor).
{{< note >}}
SPI is not currently supported. I²C must be used at this time.
{{< /note >}}
> [!NOTE]
> SPI is not currently supported. I²C must be used at this time.
## See Also

53
content/components/binary_sensor/esp32_touch.md
View File

@ -240,34 +240,33 @@ reduce the ESP's overall performance.
## S2 and S3 Variants
{{< note >}}
**ESP32-S2 and ESP32-S3 Touch Configuration**
> [!NOTE]
> **ESP32-S2 and ESP32-S3 Touch Configuration**
>
> The default `measurement_duration` and `sleep_duration` values are optimized for the original ESP32 and
> **may not work at all on S2/S3 variants**. The S2/S3 touch hardware requires different timing settings.
>
> Key differences:
>
> - **Touch values increase** when touched (opposite of ESP32 which decreases)
> - **Higher raw values** are returned compared to original ESP32
> - **Lower measurement duration required** - the default 8ms is often too high for S2/S3
>
> **Example settings for S2/S3:**
>
> ```yaml
> esp32_touch:
> setup_mode: false
> measurement_duration: 0.25ms # Much lower than the 8ms default
> sleep_duration: 0.5ms
>
> binary_sensor:
> - platform: esp32_touch
> name: "Touch Sensor"
> pin: GPIO1
> threshold: 1000 # Adjust based on your hardware
> ```
The default `measurement_duration` and `sleep_duration` values are optimized for the original ESP32 and
**may not work at all on S2/S3 variants**. The S2/S3 touch hardware requires different timing settings.
Key differences:
- **Touch values increase** when touched (opposite of ESP32 which decreases)
- **Higher raw values** are returned compared to original ESP32
- **Lower measurement duration required** - the default 8ms is often too high for S2/S3
**Example settings for S2/S3:**
```yaml
esp32_touch:
setup_mode: false
measurement_duration: 0.25ms # Much lower than the 8ms default
sleep_duration: 0.5ms
binary_sensor:
- platform: esp32_touch
name: "Touch Sensor"
pin: GPIO1
threshold: 1000 # Adjust based on your hardware
```
{{< /note >}}
If you're familiar with the ESP32 hardware and pick up an S2 or S3 variant, you're likely to notice some behavioral
differences between them. In particular:

27
content/components/binary_sensor/gpio.md
View File

@ -84,22 +84,19 @@ The GPIO binary sensor supports two modes of operation:
- Transitions shorter than the loop interval are ignored
- Use only when interrupts are not supported or for compatibility
{{< note >}}
Interrupt mode is only available on internal GPIO pins. External GPIO
expanders (like PCF8574) will automatically fall back to polling mode.
> [!NOTE]
> Interrupt mode is only available on internal GPIO pins. External GPIO
> expanders (like PCF8574) will automatically fall back to polling mode.
>
> LibreTiny-based platforms (BK72xx, RTL87xx, LN882x) default to polling mode
> due to hardware limitations with edge interrupts. You can explicitly enable
> interrupt mode if needed, but it may not work reliably on all pins.
LibreTiny-based platforms (BK72xx, RTL87xx, LN882x) default to polling mode
due to hardware limitations with edge interrupts. You can explicitly enable
interrupt mode if needed, but it may not work reliably on all pins.
{{< /note >}}
{{< note >}}
When a pin is configured with `allow_other_uses: true` (for sharing with
other components), interrupts are automatically disabled to prevent conflicts.
This ensures compatibility with components like `duty_cycle` sensors that
need to monitor pin state changes. The sensor will use polling mode instead.
{{< /note >}}
> [!NOTE]
> When a pin is configured with `allow_other_uses: true` (for sharing with
> other components), interrupts are automatically disabled to prevent conflicts.
> This ensures compatibility with components like `duty_cycle` sensors that
> need to monitor pin state changes. The sensor will use polling mode instead.
## Activating internal pullups

10
content/components/binary_sensor/homeassistant.md
View File

@ -10,12 +10,10 @@ params:
The `homeassistant` binary sensor platform allows you to create binary sensors that **import**
states from your Home Assistant instance using the {{< docref "/components/api" "native API" >}}.
{{< note >}}
Although you might not plan to *export* states from the node and you do not need an entity of the node
in Home Assistant, this component still requires you to register the node under Home Assistant. See:
[Connecting your device to Home Assistant](#connecting-your-device-to-home-assistant).
{{< /note >}}
> [!NOTE]
> Although you might not plan to *export* states from the node and you do not need an entity of the node
> in Home Assistant, this component still requires you to register the node under Home Assistant. See:
> [Connecting your device to Home Assistant](#connecting-your-device-to-home-assistant).
```yaml
# Example configuration entry

26
content/components/binary_sensor/nextion.md
View File

@ -55,11 +55,10 @@ binary_sensor:
The Nextion will send a **page_id** and **component_id** when the *Send Component ID* check box is selected for the component. To enable
this native event **page_id** and **component_id** are required. No [Nextion Custom Binary Sensor Protocol](#nextion_custom_binary_sensor_protocol) is required. If **page_id** and **component_id** are set then the component will only react to touch events from the Nextion. Setting **component_name** will allow setting options like foreground color.
{{< note >}}
`background_color(s)`, `foreground_color(s)` and `visible` do not retain their state on page change. [Binary Sensor Settings](#nextion_binary_sensor_settings).
A [Nextion Sensor](#nextion_sensor) with a custom protocol sending the current page can be used to execute the API call [Update Components By Prefix](#update_components_by_prefix) to update all the components for that page
> [!NOTE]
> `background_color(s)`, `foreground_color(s)` and `visible` do not retain their state on page change. [Binary Sensor Settings](#nextion_binary_sensor_settings).
> A [Nextion Sensor](#nextion_sensor) with a custom protocol sending the current page can be used to execute the API call [Update Components By Prefix](#update_components_by_prefix) to update all the components for that page
{{< /note >}}
Example:
```yaml
@ -123,10 +122,9 @@ on_...:
- **send_to_nextion** (*Optional*, bool, [templatable](#config-templatable)): Publish new state to Nextion
display which will update component. Default is true.
{{< note >}}
This action can also be written in lambdas. See [Lambda Calls](#nextion_binary_sensor_lambda_calls)
> [!NOTE]
> This action can also be written in lambdas. See [Lambda Calls](#nextion_binary_sensor_lambda_calls)
{{< /note >}}
{{< anchor "nextion_binary_sensor_lambda_calls" >}}
## Lambda Calls
@ -160,12 +158,11 @@ component or function you want to trigger the send. Typically this is in *Touch
set in the *Touch Release Event* to capture all the changes. Since this is a custom protocol it can be sent from anywhere (timers/functions/components)
in the Nextion.
{{< note >}}
There is no need to check the *Send Component ID* for the *Touch Press Event* or *Touch Release Event*
for an integer value component since this will be sending the real value to esphome,
but make sure you have both checked for a touch sensor.
> [!NOTE]
> There is no need to check the *Send Component ID* for the *Touch Press Event* or *Touch Release Event*
> for an integer value component since this will be sending the real value to esphome,
> but make sure you have both checked for a touch sensor.
{{< /note >}}
Using the above yaml example:
- "mode" is a touch sensor and will trigger when a user presess the component with ID `8` in page `0`
@ -174,10 +171,9 @@ Using the above yaml example:
- [Lambda Calls](#nextion_binary_sensor_lambda_calls).
{{< note >}}
No updates will be sent to the Nextion if it is sleeping. Once it wakes the components will be updated. If a component is invisible, `visible(false)`, then it won't update until it is set to be visible.
> [!NOTE]
> No updates will be sent to the Nextion if it is sleeping. Once it wakes the components will be updated. If a component is invisible, `visible(false)`, then it won't update until it is set to be visible.
{{< /note >}}
{{< anchor "nextion_custom_binary_sensor_protocol" >}}
## Nextion Custom Binary Sensor Protocol

14
content/components/binary_sensor/template.md
View File

@ -87,14 +87,12 @@ Configuration options:
- **state** (**Required**, boolean, [templatable](#config-templatable)):
The state to publish.
{{< note >}}
This action can also be written in lambdas:
```cpp
id(template_bin).publish_state(true);
```
{{< /note >}}
> [!NOTE]
> This action can also be written in lambdas:
>
> ```cpp
> id(template_bin).publish_state(true);
> ```
## See Also

32
content/components/ble_client.md
View File

@ -11,25 +11,23 @@ The `ble_client` component enables connections to Bluetooth Low Energy devices i
control them. This component does not expose any sensors or output components itself, but merely manages
connections to them for use by other components.
{{< warning >}}
The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
> [!WARNING]
> The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
>
> **Crashes are likely to occur** if you include too many additional components in your device's
> configuration. Memory-intensive components such as {{< docref "/components/voice_assistant" >}} and other
> audio components are most likely to cause issues.
**Crashes are likely to occur** if you include too many additional components in your device's
configuration. Memory-intensive components such as {{< docref "/components/voice_assistant" >}} and other
audio components are most likely to cause issues.
> [!NOTE]
> A maximum of three devices is supported due to limitations in the ESP32 BLE stack. If you wish to
> connect more devices, use additional ESP32 boards.
>
> This component supports devices that require a 6 digit PIN code for authentication.
>
> Currently, devices connected with the client cannot be supported by other components based on
> {{< docref "/components/esp32_ble_tracker" >}} as they listen to advertisements which are only sent by devices
> without an active connection.
{{< /warning >}}
{{< note >}}
A maximum of three devices is supported due to limitations in the ESP32 BLE stack. If you wish to
connect more devices, use additional ESP32 boards.
This component supports devices that require a 6 digit PIN code for authentication.
Currently, devices connected with the client cannot be supported by other components based on
{{< docref "/components/esp32_ble_tracker" >}} as they listen to advertisements which are only sent by devices
without an active connection.
{{< /note >}}
Despite the last point above, the `ble_client` component requires the `esp32_ble_tracker` component in order
to discover available client devices.

45
content/components/bluetooth_proxy.md
View File

@ -19,27 +19,25 @@ are supported.
If you're looking to create an ESPHome node that is just a Bluetooth Proxy, see
our [Bluetooth Proxy installer](https://esphome.github.io/bluetooth-proxies/) website.
{{< warning >}}
Active connections
The Bluetooth proxy of ESPHome provides Home Assistant with a maximum number of 3 simultaneous active connections.
Devices which maintain a *continuous active* connection will consume one of these constantly, whilst devices which
do *periodic disconnections and reconnections* will permit using more than 3 of them (on a statistical basis).
Passively broadcasted sensor data (that is advertised by certain devices without active connections) is received
separately from these, and is not limited to a specific number.
The {{< docref "esp32/" >}} component should be configured to use the `esp-idf` framework, as the `arduino` framework
uses significantly more memory and performs poorly with the Bluetooth proxy enabled. When switching from
`arduino` to `esp-idf`, make sure to update the device with a serial cable as the partition table is
different between the two frameworks as {{< docref "/components/ota" >}} updates will not change the partition table.
The {{< docref "web_server/" >}} component should be disabled as the device is likely
to run out of memory and will malfunction when both components are enabled simultaneously.
Not all devices are supported and ESPHome does not decode or keep a list. To find out if your device is supported,
please search for it in the [Home Assistant Integrations](https://www.home-assistant.io/integrations/) list.
{{< /warning >}}
> [!WARNING]
> Active connections
>
> The Bluetooth proxy of ESPHome provides Home Assistant with a maximum number of 3 simultaneous active connections.
> Devices which maintain a *continuous active* connection will consume one of these constantly, whilst devices which
> do *periodic disconnections and reconnections* will permit using more than 3 of them (on a statistical basis).
> Passively broadcasted sensor data (that is advertised by certain devices without active connections) is received
> separately from these, and is not limited to a specific number.
>
> The {{< docref "esp32/" >}} component should be configured to use the `esp-idf` framework, as the `arduino` framework
> uses significantly more memory and performs poorly with the Bluetooth proxy enabled. When switching from
> `arduino` to `esp-idf`, make sure to update the device with a serial cable as the partition table is
> different between the two frameworks as {{< docref "/components/ota" >}} updates will not change the partition table.
>
> The {{< docref "web_server/" >}} component should be disabled as the device is likely
> to run out of memory and will malfunction when both components are enabled simultaneously.
>
> Not all devices are supported and ESPHome does not decode or keep a list. To find out if your device is supported,
> please search for it in the [Home Assistant Integrations](https://www.home-assistant.io/integrations/) list.
## Configuration
@ -73,10 +71,9 @@ esp32_ble_tracker:
window: 1100ms
```
{{< note >}}
For WiFi-based proxies, changing the `interval` or `window` from their default values may result in an unstable WiFi connection. Using the default values for `interval` and `window` will usually resolve any instability.
> [!NOTE]
> For WiFi-based proxies, changing the `interval` or `window` from their default values may result in an unstable WiFi connection. Using the default values for `interval` and `window` will usually resolve any instability.
{{< /note >}}
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. Place your ESPHome devices close to the Bluetooth devices that you want to interact with for the best experience.
## Complete sample recommended configuration for an ethernet-connected Bluetooth proxy

31
content/components/button/_index.md
View File

@ -7,19 +7,17 @@ params:
image: folder-open.svg
---
{{< note >}}
To attach a physical button to ESPHome, see
{{< docref "/components/binary_sensor/gpio" "GPIO Binary Sensor" >}}.
> [!NOTE]
> To attach a physical button to ESPHome, see
> {{< docref "/components/binary_sensor/gpio" "GPIO Binary Sensor" >}}.
{{< /note >}}
ESPHome has support for components to create button entities in Home Assistant. A button entity is
represented in ESPHome as a momentary switch with no state and can be triggered in Home Assistant
via the UI or automations.
{{< note >}}
Home Assistant Core 2021.12 or higher is required for ESPHome button entities to work.
> [!NOTE]
> Home Assistant Core 2021.12 or higher is required for ESPHome button entities to work.
{{< /note >}}
{{< anchor "config-button" >}}
## Base Button Configuration
@ -44,11 +42,9 @@ Configuration variables:
- **id** (*Optional*, string): Manually specify the ID for code generation. At least one of **id** and **name** must be specified.
- **name** (*Optional*, string): The name for the button. At least one of **id** and **name** must be specified.
{{< note >}}
If you have a [friendly_name](#esphome-configuration_variables) set for your device and
you want the button to use that name, you can set `name: None`.
{{< /note >}}
> [!NOTE]
> If you have a [friendly_name](#esphome-configuration_variables) set for your device and
> you want the button to use that name, you can set `name: None`.
- **icon** (*Optional*, icon): Manually set the icon to use for the button in the frontend.
- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will
@ -110,13 +106,12 @@ Configuration variables:
- **id** (**Required**, [ID](#config-id)): The ID of the button to set.
{{< note >}}
Buttons are designed to trigger an action on a device from Home Assistant, and have an unidirectional flow from
Home Assistant to ESPHome. If you press a button using this action, no button press event will be triggered in Home
Assistant. If you want to trigger an automation in Home Assistant, you should use a
[Home Assistant event](#api-homeassistant_event_action) instead.
> [!NOTE]
> Buttons are designed to trigger an action on a device from Home Assistant, and have an unidirectional flow from
> Home Assistant to ESPHome. If you press a button using this action, no button press event will be triggered in Home
> Assistant. If you want to trigger an automation in Home Assistant, you should use a
> [Home Assistant event](#api-homeassistant_event_action) instead.
{{< /note >}}
{{< anchor "button-lambda_calls" >}}
### lambda calls

13
content/components/button/factory_reset.md
View File

@ -14,14 +14,13 @@ After reboot all states, parameters and variables will be reinitialized with the
- in case of moving a device to a new environment or starting a new use-case (e.g. reset counters or state)
- for privacy concerns when giving away a device
{{< note >}}
**USE WITH GREAT CAUTION!** All credentials, global variables, counters and saved states stored in non-volatile memory will be lost with no chance of recovering them.
Even raw reading of flash memory with `esptool` will not help, since data is physically erased from flash memory.
> [!NOTE]
> **USE WITH GREAT CAUTION!** All credentials, global variables, counters and saved states stored in non-volatile memory will be lost with no chance of recovering them.
> Even raw reading of flash memory with `esptool` will not help, since data is physically erased from flash memory.
>
> For devices configured using {{< docref "/components/captive_portal" "captive portal" >}}, this will reset WiFi settings as well, thus making such devices offline.
> You'll need to be in close proximity to your device to configure it again using a built-in WiFi access point and captive portal.
For devices configured using {{< docref "/components/captive_portal" "captive portal" >}}, this will reset WiFi settings as well, thus making such devices offline.
You'll need to be in close proximity to your device to configure it again using a built-in WiFi access point and captive portal.
{{< /note >}}
{{< img src="factory-rst-ui.png" alt="Image" width="80.0%" class="align-center" >}}
```yaml

10
content/components/button/output.md
View File

@ -32,12 +32,10 @@ button:
- **duration** (**Required**, [Time](#config-time)): How long the output should be set when the button is pressed.
- All other options from [Button](#config-button).
{{< note >}}
When used with a {{< docref "/components/output/gpio" >}}, the pin will be low by default and pulled high when the button is
pressed. To invert this behaviour and have the pin pulled low when the button is pressed, set the `inverted` option
in the [Pin Schema](#config-pin_schema).
{{< /note >}}
> [!NOTE]
> When used with a {{< docref "/components/output/gpio" >}}, the pin will be low by default and pulled high when the button is
> pressed. To invert this behaviour and have the pin pulled low when the button is pressed, set the `inverted` option
> in the [Pin Schema](#config-pin_schema).
## See Also

8
content/components/camera/_index.md
View File

@ -10,11 +10,9 @@ params:
The `camera` component is the base abstraction layer for camera implementations in ESPHome. It provides a
standardized interface between camera hardware/software implementations and the ESPHome API layer.
{{< note >}}
This component cannot be used directly. It serves as the base platform that specific camera
implementations (like {{< docref "/components/esp32_camera" >}}) build upon.
{{< /note >}}
> [!NOTE]
> This component cannot be used directly. It serves as the base platform that specific camera
> implementations (like {{< docref "/components/esp32_camera" >}}) build upon.
## Overview

9
content/components/camera/camera_encoder.md
View File

@ -15,11 +15,10 @@ It supports different encoder implementations, such as a ESP32 Camera software J
options like image quality and incremental encoding. These settings make it possible to balance image
quality and performance depending on the use case.
{{< note >}}
The default software JPEG encoder enables devices like the ESP32-S3 to stream images.
It is primarily intended for smallar images due to limited processing power and memory,
and supports only devices from the ESP32 family.
{{< /note >}}
> [!NOTE]
> The default software JPEG encoder enables devices like the ESP32-S3 to stream images.
> It is primarily intended for smallar images due to limited processing power and memory,
> and supports only devices from the ESP32 family.
```yaml
# Example configuration entry

13
content/components/canbus/_index.md
View File

@ -105,10 +105,8 @@ This automation will be triggered when a CAN frame is received. The variables `x
received CAN ID and `remote_transmission_request` (of type `bool` ) containing the corresponding field
from the CAN frame are passed to the automation for use in lambdas.
{{< note >}}
Messages this node sends to the same ID will not show up as received messages.
{{< /note >}}
> [!NOTE]
> Messages this node sends to the same ID will not show up as received messages.
```yaml
canbus:
@ -194,11 +192,10 @@ on_...:
Standard IDs and Extended IDs can coexist on the same segment.
{{< note >}}
It is important to know that "standard" and "extended" addresses denote different addresses. For example,
Standard `0x123` and Extended `0x123` are, in fact, different addresses.
> [!NOTE]
> It is important to know that "standard" and "extended" addresses denote different addresses. For example,
> Standard `0x123` and Extended `0x123` are, in fact, different addresses.
{{< /note >}}
Decimal or hexadecimal notation may be used for IDs:
- Standard IDs use `0x000` to `0x7ff` (hexadecimal) or `0` to `2047` (decimal)

22
content/components/canbus/mcp2515.md
View File

@ -33,13 +33,12 @@ canbus:
brightness: !lambda "return (x.size() > 0) ? (float) x[0]/255 : 0;"
```
{{< note >}}
The MCP2515 only provides two receive buffers which are read once per loop cycle.
This means, if more than two CAN frames arrive within a loop cycle (typically 16ms, possibly longer), frames are dropped.
This limitation makes the MCP2515 unsuitable for moderate- to high-speed CAN buses, especially automotive ones.
Use the [esp32_can](#esp32-can) component where possible.
{{< /note >}}
> [!NOTE]
> The MCP2515 only provides two receive buffers which are read once per loop cycle.
> This means, if more than two CAN frames arrive within a loop cycle (typically 16ms, possibly longer), frames are dropped.
>
> This limitation makes the MCP2515 unsuitable for moderate- to high-speed CAN buses, especially automotive ones.
> Use the [esp32_can](#esp32-can) component where possible.
## Configuration variables
@ -57,12 +56,11 @@ Use the [esp32_can](#esp32-can) component where possible.
- All other options from [Canbus](#config-canbus).
{{< note >}}
Not all combinations of clock and bitrate are supported. An unsupported combination will not be flagged at
compile time. Check your ESPHome device's logs for a message like `Invalid frequency/bitrate combination`
if you suspect this is an issue.
> [!NOTE]
> Not all combinations of clock and bitrate are supported. An unsupported combination will not be flagged at
> compile time. Check your ESPHome device's logs for a message like `Invalid frequency/bitrate combination`
> if you suspect this is an issue.
{{< /note >}}
{{< anchor "mcp2515-wiring" >}}
## Wiring options

6
content/components/ch422g.md
View File

@ -15,10 +15,8 @@ Within ESPHome they can be used in place of internal GPIO pins in many of ESPHom
Pins 0-7 correspond to the bidirectional I/O (segment) pins on the CH422G. Pins 8-11 correspond to the OC (digit) output pins 0-3.
{{< note >}}
This I/O Expander chip is used in several Waveshare ESP32-S3 display boards.
{{< /note >}}
> [!NOTE]
> This I/O Expander chip is used in several Waveshare ESP32-S3 display boards.
```yaml
# Example configuration entry

13
content/components/climate/_index.md
View File

@ -13,10 +13,9 @@ and can be put in different modes like `HEAT`, `COOL`, `HEAT_COOL` or `OFF`.
{{< img src="climate-ui.png" alt="Image" caption="Climate Device UI in Home Assistant." width="60.0%" class="align-center" >}}
{{< note >}}
Not all climate components support all possible features. Check the corresponding documentation page for details on what is supported.
> [!NOTE]
> Not all climate components support all possible features. Check the corresponding documentation page for details on what is supported.
{{< /note >}}
{{< anchor "config-climate" >}}
## Base Climate Configuration
@ -46,11 +45,9 @@ Configuration variables:
- **id** (*Optional*, string): Manually specify the ID for code generation. At least one of **id** and **name** must be specified.
- **name** (*Optional*, string): The name of the climate device. At least one of **id** and **name** must be specified.
{{< note >}}
If you have a [friendly_name](#esphome-configuration_variables) set for your device and
you want the climate to use that name, you can set `name: None`.
{{< /note >}}
> [!NOTE]
> If you have a [friendly_name](#esphome-configuration_variables) set for your device and
> you want the climate to use that name, you can set `name: None`.
- **icon** (*Optional*, icon): Manually set the icon to use for the climate device in the frontend.
- **visual** (*Optional*): Visual settings for the climate device - these do not

6
content/components/climate/anova.md
View File

@ -31,10 +31,8 @@ You need to specify unit_of_measurement as 'c' or 'f'. This ensures the stick's
uses the unit you intend. All values within ESPHome are converted to Celsius so you may
need to do conversion again within the frontend if you use Fahrenheit.
{{< warning >}}
The Anova Nano is not currently supported as it uses a different BLE protocol.
{{< /warning >}}
> [!WARNING]
> The Anova Nano is not currently supported as it uses a different BLE protocol.
```yaml
ble_client:

17
content/components/climate/bang_bang.md
View File

@ -10,12 +10,11 @@ params:
The `bang_bang` climate platform allows you to regulate a value with a
[bang-bang controller](https://en.wikipedia.org/wiki/Bang%E2%80%93bang_control) (also called hysteresis controller).
{{< note >}}
The {{< docref "thermostat" "thermostat" >}} component behaves more like a common thermostat; it is
essentially two bang-bang controllers in one. Please see the `Bang-bang vs. Thermostat`_ section below
if you are not sure which is appropriate for your application.
> [!NOTE]
> The {{< docref "thermostat" "thermostat" >}} component behaves more like a common thermostat; it is
> essentially two bang-bang controllers in one. Please see the `Bang-bang vs. Thermostat`_ section below
> if you are not sure which is appropriate for your application.
{{< /note >}}
The bang-bang controller's principle of operation is quite simple. First, you specify an observable
value (for example the temperature of a room). The controller will try to keep this observed value
in a defined range. To do this, the controller can activate objects like a heating unit to change
@ -101,11 +100,9 @@ Advanced options:
- **default_target_temperature_high** (**Required**, float): The default high target temperature for
the control algorithm during away mode.
{{< note >}}
While this platform uses the term temperature everywhere, it can also be used for other values.
For example, controlling humidity is also possible with this platform.
{{< /note >}}
> [!NOTE]
> While this platform uses the term temperature everywhere, it can also be used for other values.
> For example, controlling humidity is also possible with this platform.
## Bang-bang vs. Thermostat

56
content/components/climate/bedjet.md
View File

@ -174,38 +174,34 @@ sensor:
## Known issues
{{< warning >}}
BedJet V2 and other devices are not currently supported. Only BedJet V3 is supported.
> [!WARNING]
> BedJet V2 and other devices are not currently supported. Only BedJet V3 is supported.
{{< /warning >}}
{{< note >}}
Only one client can be connected to the BedJet BLE service at a time, so you cannot
use the BedJet mobile app to monitor or control the BedJet device while this component
is connected. To use the mobile app, you should disconnect the ESP client first.
> [!NOTE]
> Only one client can be connected to the BedJet BLE service at a time, so you cannot
> use the BedJet mobile app to monitor or control the BedJet device while this component
> is connected. To use the mobile app, you should disconnect the ESP client first.
>
> To set up a (dis-)connect switch, see {{< docref "/components/switch/ble_client" >}}.
To set up a (dis-)connect switch, see {{< docref "/components/switch/ble_client" >}}.
{{< /note >}}
{{< note >}}
When more than one device is configured and connected, the ESP device may become
overwhelmed and lead to timeouts while trying to install an updated version of the
configuration. If this occurs, see the previous note about adding disconnect switches,
and toggle those off while performing the installation. This will free up resources
on the ESP and allow the installation to complete.
Additionally, you may use an [ota.on_begin](#ota-on_begin) [Automation](#automation)
to do this automatically:
```yaml
ota:
on_begin:
then:
- logger.log: "Disconnecting clients for OTA update..."
- switch.turn_off: bedjet_1_monitor
- switch.turn_off: bedjet_2_monitor
```
{{< /note >}}
> [!NOTE]
> When more than one device is configured and connected, the ESP device may become
> overwhelmed and lead to timeouts while trying to install an updated version of the
> configuration. If this occurs, see the previous note about adding disconnect switches,
> and toggle those off while performing the installation. This will free up resources
> on the ESP and allow the installation to complete.
>
> Additionally, you may use an [ota.on_begin](#ota-on_begin) [Automation](#automation)
> to do this automatically:
>
> ```yaml
> ota:
> on_begin:
> then:
> - logger.log: "Disconnecting clients for OTA update..."
> - switch.turn_off: bedjet_1_monitor
> - switch.turn_off: bedjet_2_monitor
> ```
## See Also

85
content/components/climate/climate_ir.md
View File

@ -165,21 +165,18 @@ climate:
use_fahrenheit: true
```
{{< note >}}
> [!NOTE]
>
> - See [Transmit Midea](#remote_transmitter-transmit_midea) to send custom commands, including Follow Me mode.
> - See [Toshiba](#toshiba) below if you are looking for compatibility with Midea model MAP14HS1TBL or similar.
- See [Transmit Midea](#remote_transmitter-transmit_midea) to send custom commands, including Follow Me mode.
- See [Toshiba](#toshiba) below if you are looking for compatibility with Midea model MAP14HS1TBL or similar.
{{< /note >}}
{{< anchor "mitsubishi" >}}
### `mitsubishi`
{{< note >}}
- When using this component with Mitsubishi units that only support cooling mode, the Off command may not work. Set **supports_heat** to `false` to resolve that issue.
{{< /note >}}
> [!NOTE]
>
> - When using this component with Mitsubishi units that only support cooling mode, the Off command may not work. Set **supports_heat** to `false` to resolve that issue.
- **set_fan_mode** (*Optional*, string): Select the fan modes desired or that are supported on your remote. Defaults to `3levels`
@ -199,11 +196,9 @@ climate:
- Options are: `down`, `middle-down`, `middle`, `middle-up`, `up`, `auto`
{{< note >}}
- This climate IR component is also known to work with some Stiebel Eltron Units. It has been tested with Stiebel Eltron IR-Remote `KM07F` and unit `ACW 25 i`
{{< /note >}}
> [!NOTE]
>
> - This climate IR component is also known to work with some Stiebel Eltron Units. It has been tested with Stiebel Eltron IR-Remote `KM07F` and unit `ACW 25 i`
```yaml
# Example configuration entry
@ -227,25 +222,24 @@ climate:
- `RAC-PT1411HWRU-C` : Temperature range is from 16 to 30; unit displays temperature in degrees Celsius
- `RAC-PT1411HWRU-F` : Temperature range is from 16 to 30; unit displays temperature in degrees Fahrenheit
{{< note >}}
> [!NOTE]
>
> - While they are identified as separate models here, the `RAC-PT1411HWRU-C` and `RAC-PT1411HWRU-F` are
> in fact the same physical model/unit. They are separated here only because different IR codes are used
> depending on the desired unit of measurement. This only affects how temperature is displayed on the unit itself.
>
> - The `RAC-PT1411HWRU` model supports a feature Toshiba calls "Comfort Sense". The handheld remote control
> has a built-in temperature sensor and it will periodically transmit the temperature from this sensor to the
> AC unit. If a `sensor` is provided in the configuration with this model, the sensor's temperature will be
> transmitted to the `RAC-PT1411HWRU` in the same manner as the original remote controller. How often the
> temperature is transmitted is determined by the `update_interval` assigned to the `sensor`. Note that
> `update_interval` must be less than seven minutes or the `RAC-PT1411HWRU` will revert to using its own
> internal temperature sensor; a value of 30 seconds seems to work well. See {{< docref "/components/sensor" >}}
> for more information.
>
> - This climate IR component is also known to work with Midea model MAP14HS1TBL and may work with other similar
> models, as well. (Midea acquired Toshiba's product line and re-branded it.)
- While they are identified as separate models here, the `RAC-PT1411HWRU-C` and `RAC-PT1411HWRU-F` are
in fact the same physical model/unit. They are separated here only because different IR codes are used
depending on the desired unit of measurement. This only affects how temperature is displayed on the unit itself.
- The `RAC-PT1411HWRU` model supports a feature Toshiba calls "Comfort Sense". The handheld remote control
has a built-in temperature sensor and it will periodically transmit the temperature from this sensor to the
AC unit. If a `sensor` is provided in the configuration with this model, the sensor's temperature will be
transmitted to the `RAC-PT1411HWRU` in the same manner as the original remote controller. How often the
temperature is transmitted is determined by the `update_interval` assigned to the `sensor`. Note that
`update_interval` must be less than seven minutes or the `RAC-PT1411HWRU` will revert to using its own
internal temperature sensor; a value of 30 seconds seems to work well. See {{< docref "/components/sensor" >}}
for more information.
- This climate IR component is also known to work with Midea model MAP14HS1TBL and may work with other similar
models, as well. (Midea acquired Toshiba's product line and re-branded it.)
{{< /note >}}
{{< anchor "whirlpool" >}}
### `whirlpool`
@ -281,10 +275,9 @@ The `zhlt01` climate and protocol, based on the ZH/LT-01 remote controller, is u
## Using a Receiver
{{< note >}}
This is only supported with select climate devices, see "Supports receiver" in the table at the top of the page.
> [!NOTE]
> This is only supported with select climate devices, see "Supports receiver" in the table at the top of the page.
{{< /note >}}
Optionally, some platforms can listen to data the climate device sends over infrared to update their state (
for example what mode the device is in). By setting up a {{< docref "/components/remote_receiver" "remote_receiver" >}}
and passing its ID to the climate platform you can enable this mode.
@ -339,17 +332,15 @@ Additional configuration must be specified for this platform:
- **min_temperature** (**Required**, float): The minimum temperature that the AC unit supports being set to.
- **sensor** (*Optional*, [ID](#config-id)): The sensor that is used to measure the ambient temperature.
{{< note >}}
The `greeyac` protocol in `heatpumpir` supports a feature Gree calls "I-Feel". The handheld remote control
has a built-in temperature sensor and it will periodically transmit the temperature from this sensor to the
AC unit. If a `sensor` is provided in the configuration with this model, the sensor's temperature will be
transmitted to the `greeyac` device in the same manner as the original remote controller. How often the
temperature is transmitted is determined by the `update_interval` assigned to the `sensor`. Note that
`update_interval` must be less than 10 minutes or the `greeyac` device will revert to using its own
internal temperature sensor; a value of 2 minutes seems to work well. See {{< docref "/components/sensor" >}}
for more information.
{{< /note >}}
> [!NOTE]
> The `greeyac` protocol in `heatpumpir` supports a feature Gree calls "I-Feel". The handheld remote control
> has a built-in temperature sensor and it will periodically transmit the temperature from this sensor to the
> AC unit. If a `sensor` is provided in the configuration with this model, the sensor's temperature will be
> transmitted to the `greeyac` device in the same manner as the original remote controller. How often the
> temperature is transmitted is determined by the `update_interval` assigned to the `sensor`. Note that
> `update_interval` must be less than 10 minutes or the `greeyac` device will revert to using its own
> internal temperature sensor; a value of 2 minutes seems to work well. See {{< docref "/components/sensor" >}}
> for more information.
## See Also

27
content/components/climate/midea.md
View File

@ -9,21 +9,20 @@ params:
The `midea` component creates a Midea air conditioner climate device.
{{< note >}}
This protocol also used by some vendors:
> [!NOTE]
> This protocol also used by some vendors:
>
> - [Electrolux](https://www.electrolux.ru/)
> - [Qlima](https://www.qlima.com/)
> - [Artel](https://www.artelgroup.com/)
> - [Carrier](https://www.carrier.com/)
> - [Comfee](http://www.comfee-russia.ru/)
> - [Inventor](https://www.inventorairconditioner.com/)
> - [Senville](https://senville.com/)
> - and maybe others
>
> Control is possible with a custom dongle. Example of hardware implementation is [IoT Uni Dongle](https://github.com/dudanov/iot-uni-dongle) or [Midea SLWF-01pro](https://smartlight.me/smart-home-devices/wifi-devices/wifi-dongle-air-conditioners-midea-idea-electrolux-for-home-assistant) ([CloudFree](https://cloudfree.shop/product/ductless-hvac-wi-fi-module/), [Tindie](https://www.tindie.com/products/smartlightme/wifi-dongle-for-air-conditioners-midea-electrolux)).
- [Electrolux](https://www.electrolux.ru/)
- [Qlima](https://www.qlima.com/)
- [Artel](https://www.artelgroup.com/)
- [Carrier](https://www.carrier.com/)
- [Comfee](http://www.comfee-russia.ru/)
- [Inventor](https://www.inventorairconditioner.com/)
- [Senville](https://senville.com/)
- and maybe others
Control is possible with a custom dongle. Example of hardware implementation is [IoT Uni Dongle](https://github.com/dudanov/iot-uni-dongle) or [Midea SLWF-01pro](https://smartlight.me/smart-home-devices/wifi-devices/wifi-dongle-air-conditioners-midea-idea-electrolux-for-home-assistant) ([CloudFree](https://cloudfree.shop/product/ductless-hvac-wi-fi-module/), [Tindie](https://www.tindie.com/products/smartlightme/wifi-dongle-for-air-conditioners-midea-electrolux)).
{{< /note >}}
The Midea air conditioner requires the UART to be configured with `baud_rate: 9600`. The hardware requires **5V logic levels** and does not appear to work with 3.3V logic levels. Use a logic level shifter if building your own dongle.
```yaml

77
content/components/climate/pid.md
View File

@ -14,20 +14,19 @@ PID controllers are good at modulating an output signal to get a sensor reading
setpoint. For example, it can be used to modulate the power of a heating unit to get the
temperature to a user-specified setpoint.
{{< note >}}
PID is like cruise control in the cars: it keeps the car's speed constant by continuously
adjusting the fuel quantity, based on load measurements. Eg when the car has to go up on a hill,
the system notices the load increase thus immediately gives more fuel to the engine; and when it
goes down on the other side of the hill, it notices the load decrease thus reduces or cuts off fuel
completely so that car speed remains as constant as possible. The calculation takes in consideration
constants like car weight, wind resistance etc.
> [!NOTE]
> PID is like cruise control in the cars: it keeps the car's speed constant by continuously
> adjusting the fuel quantity, based on load measurements. Eg when the car has to go up on a hill,
> the system notices the load increase thus immediately gives more fuel to the engine; and when it
> goes down on the other side of the hill, it notices the load decrease thus reduces or cuts off fuel
> completely so that car speed remains as constant as possible. The calculation takes in consideration
> constants like car weight, wind resistance etc.
>
> This kind of math can be used for a heating or cooling system too, and an auto-tuning algorithm can help
> determining such constants, which mainly describe the heat loss of the room or building. Goal is to
> keep the temperature as constant as possible, and smooth out oscillations otherwise produced by
> classic thermostats.
This kind of math can be used for a heating or cooling system too, and an auto-tuning algorithm can help
determining such constants, which mainly describe the heat loss of the room or building. Goal is to
keep the temperature as constant as possible, and smooth out oscillations otherwise produced by
classic thermostats.
{{< /note >}}
Explaining how PID controllers work in detail is out of scope of this documentation entry,
but there's a nice article explaining the function principle at <https://blog.opticontrols.com/archives/344>.
@ -131,14 +130,12 @@ To set up a PID climate controller, you need a couple of components:
Please note the output *must* be controllable with continuous value (not only ON/OFF, but any state
in between for example 50% heating power).
{{< note >}}
The sensor should have a short update interval. The PID update frequency is tied to the update
interval of the sensor. Set a short `update_interval` like `5s` on the sensor.
We recommend putting a filter on the sensor (see filters in {{< docref "/components/sensor" >}}) and
using `output_averaging_samples` to calm the PID sensor from a noisy input sensor.
{{< /note >}}
> [!NOTE]
> The sensor should have a short update interval. The PID update frequency is tied to the update
> interval of the sensor. Set a short `update_interval` like `5s` on the sensor.
>
> We recommend putting a filter on the sensor (see filters in {{< docref "/components/sensor" >}}) and
> using `output_averaging_samples` to calm the PID sensor from a noisy input sensor.
## Deadband Setup
@ -252,17 +249,15 @@ To autotune the control parameters:
This induces an oscillation of the observed temperature and the measured period and amplitude
is automatically calculated. To do this, it needs to observe at least 3 oscillation cycles.
{{< note >}}
You **have to set the setpoint** of the climate controller to a value the
device can reach. For example if the temperature of a room is to be controlled, the setpoint needs
to be above the ambient temperature. If the ambient temperature is 20°C, the setpoint of the
climate device should be set to at least ~24°C so that an oscillation can be induced.
Also take care of external influences, like for example when room temperature is severely affected by
outdoor weather like sun, if it starts to warm up the room in parallel with the heating
autotune will likely fail or give false results.
{{< /note >}}
> [!NOTE]
> You **have to set the setpoint** of the climate controller to a value the
> device can reach. For example if the temperature of a room is to be controlled, the setpoint needs
> to be above the ambient temperature. If the ambient temperature is 20°C, the setpoint of the
> climate device should be set to at least ~24°C so that an oscillation can be induced.
>
> Also take care of external influences, like for example when room temperature is severely affected by
> outdoor weather like sun, if it starts to warm up the room in parallel with the heating
> autotune will likely fail or give false results.
1. Set an appropriate setpoint (see note above) and turn on the climate controller (Heat, Cool or Auto).
@ -281,16 +276,14 @@ To autotune the control parameters:
```
{{< note >}}
In the output above, the autotuner is driving the heating output at 100% and trying to reach 24.25 °C.
This will continue for some time until data for 3 phases (6 crossings of the setpoint; or a bit more, depending on
the data quality) have been acquired.
The autotune algorithm may take a long time to complete, it depends on the time needed to reproduce the
heating up and cooling down oscillations the required number of times.
{{< /note >}}
> [!NOTE]
> In the output above, the autotuner is driving the heating output at 100% and trying to reach 24.25 °C.
>
> This will continue for some time until data for 3 phases (6 crossings of the setpoint; or a bit more, depending on
> the data quality) have been acquired.
>
> The autotune algorithm may take a long time to complete, it depends on the time needed to reproduce the
> heating up and cooling down oscillations the required number of times.
1. When the PID autotuner has succeeded, output like the one below can be seen:

28
content/components/climate/thermostat.md
View File

@ -417,12 +417,10 @@ These configuration items determine default values the thermostat controller sho
- `memory` (default): The thermostat will restore any settings from last time it was running.
- `default_preset` : The thermostat will always switch to the preset specified by **default_preset**
{{< note >}}
You can specify a `default_preset` and set `on_boot_restore_from` to `memory`. In this mode when
the settings from last boot cannot be retrieved, for any reason, then the specified `default_preset`
will be applied.
{{< /note >}}
> [!NOTE]
> You can specify a `default_preset` and set `on_boot_restore_from` to `memory`. In this mode when
> the settings from last boot cannot be retrieved, for any reason, then the specified `default_preset`
> will be applied.
```yaml
# This climate controller, on first boot, will switch to "My Startup Preset". Subsequent boots would
@ -546,16 +544,14 @@ the range of allowed temperature values in the thermostat component. See {{< doc
- **heat_overrun** (*Optional*, float): The minimum temperature differential (heating beyond the set point)
before calling the idle [action](#config-action). Defaults to 0.5 °C.
{{< note >}}
- While this platform uses the term temperature everywhere, it can also be used to regulate other values.
For example, controlling humidity is also possible with this platform.
- `min_temperature` and `max_temperature` from the base climate component are used the define the range of
adjustability and the defaults will probably not make sense for control of things like humidity. See
{{< docref "/components/climate" >}}.
{{< /note >}}
> [!NOTE]
>
> - While this platform uses the term temperature everywhere, it can also be used to regulate other values.
> For example, controlling humidity is also possible with this platform.
>
> - `min_temperature` and `max_temperature` from the base climate component are used the define the range of
> adjustability and the defaults will probably not make sense for control of things like humidity. See
> {{< docref "/components/climate" >}}.
## Bang-Bang vs. Thermostat

95
content/components/cover/_index.md
View File

@ -30,11 +30,9 @@ Configuration variables:
- **id** (*Optional*, string): Manually specify the ID for code generation. At least one of **id** and **name** must be specified.
- **name** (*Optional*, string): The name for the cover. At least one of **id** and **name** must be specified.
{{< note >}}
If you have a [friendly_name](#esphome-configuration_variables) set for your device and
you want the cover to use that name, you can set `name: None`.
{{< /note >}}
> [!NOTE]
> If you have a [friendly_name](#esphome-configuration_variables) set for your device and
> you want the cover to use that name, you can set `name: None`.
- **device_class** (*Optional*, string): The device class for the
sensor. See <https://www.home-assistant.io/integrations/cover/#device-class> for a list of available options.
@ -86,16 +84,15 @@ on_...:
- cover.open: cover_1
```
{{< note >}}
This action can also be expressed in [lambdas](#config-lambda):
> [!NOTE]
> This action can also be expressed in [lambdas](#config-lambda):
>
> ```cpp
> auto call = id(cover_1).make_call();
> call.set_command_open();
> call.perform();
> ```
```cpp
auto call = id(cover_1).make_call();
call.set_command_open();
call.perform();
```
{{< /note >}}
{{< anchor "cover-close_action" >}}
## `cover.close` Action
@ -108,16 +105,15 @@ on_...:
- cover.close: cover_1
```
{{< note >}}
This action can also be expressed in [lambdas](#config-lambda):
> [!NOTE]
> This action can also be expressed in [lambdas](#config-lambda):
>
> ```cpp
> auto call = id(cover_1).make_call();
> call.set_command_close();
> call.perform();
> ```
```cpp
auto call = id(cover_1).make_call();
call.set_command_close();
call.perform();
```
{{< /note >}}
{{< anchor "cover-stop_action" >}}
## `cover.stop` Action
@ -130,16 +126,15 @@ on_...:
- cover.stop: cover_1
```
{{< note >}}
This action can also be expressed in [lambdas](#config-lambda):
> [!NOTE]
> This action can also be expressed in [lambdas](#config-lambda):
>
> ```cpp
> auto call = id(cover_1).make_call();
> call.set_command_stop();
> call.perform();
> ```
```cpp
auto call = id(cover_1).make_call();
call.set_command_stop();
call.perform();
```
{{< /note >}}
{{< anchor "cover-toggle_action" >}}
## `cover.toggle` Action
@ -154,16 +149,15 @@ on_...:
- cover.toggle: cover_1
```
{{< note >}}
This action can also be expressed in [lambdas](#config-lambda):
> [!NOTE]
> This action can also be expressed in [lambdas](#config-lambda):
>
> ```cpp
> auto call = id(cover_1).make_call();
> call.set_command_toggle();
> call.perform();
> ```
```cpp
auto call = id(cover_1).make_call();
call.set_command_toggle();
call.perform();
```
{{< /note >}}
{{< anchor "cover-control_action" >}}
## `cover.control` Action
@ -192,17 +186,16 @@ Configuration variables:
- **tilt** (*Optional*, float): The tilt position to set. In range 0% - 100%.
{{< note >}}
This action can also be expressed in [lambdas](#config-lambda):
> [!NOTE]
> This action can also be expressed in [lambdas](#config-lambda):
>
> ```cpp
> auto call = id(cover_1).make_call();
> // set attributes
> call.set_position(0.5);
> call.perform();
> ```
```cpp
auto call = id(cover_1).make_call();
// set attributes
call.set_position(0.5);
call.perform();
```
{{< /note >}}
{{< anchor "cover-lambda_calls" >}}
## Lambdas

15
content/components/cover/am43.md
View File

@ -13,12 +13,11 @@ as Zemismart and A-OK. The platform connects to the device over the
ESP32's BLE peripheral and both controls and fetches the position
and state of the motor.
{{< note >}}
This component does NOT support Tuya-based versions of this device,
as the protocol is completely different. If your device is controlled
with the SmartLife app, then it will not work.
> [!NOTE]
> This component does NOT support Tuya-based versions of this device,
> as the protocol is completely different. If your device is controlled
> with the SmartLife app, then it will not work.
{{< /note >}}
{{< img src="am43.jpg" alt="Image" class="align-right" >}}
```yaml
@ -60,10 +59,8 @@ To make use of the battery and light level sensors, see the
- **invert_position** (*Optional*, boolean): Inverts the position value to and from the device. Set if ESPHome is swapping around the open/close state of the cover.
- All other options from [Cover](#config-cover).
{{< note >}}
The BLE stack on the ESP32 has a limit of three connected devices.
{{< /note >}}
> [!NOTE]
> The BLE stack on the ESP32 has a limit of three connected devices.
## See Also

17
content/components/cover/current_based.md
View File

@ -23,12 +23,10 @@ This type of cover also provides safety features like current-based obstacle det
rollback as well as relay malfunction detection: operation cancels if there's a current flowing in the opposite
operation circuit (typically caused by welded relays).
{{< warning >}}
Depending on the cover and motor type, obstacles can physically damage the cover before being detectable.
Verify your setup to ensure the current consumption will increase enough to be detectable before causing
any physical damage. Use it at your own risk.
{{< /warning >}}
> [!WARNING]
> Depending on the cover and motor type, obstacles can physically damage the cover before being detectable.
> Verify your setup to ensure the current consumption will increase enough to be detectable before causing
> any physical damage. Use it at your own risk.
```yaml
# Example configuration entry
@ -119,11 +117,10 @@ These devices typically run hot (~55Cº at 20ºC room temperature). Long-term he
It is strongly recommended to monitor the device temperature using the NTC temperature sensor, shutting down the device if it exceeds 90ºC.
This safety feature is also present in the original firmware.
{{< warning >}}
The ADE7953 IRQ line is connected to the GPIO16. The `irq_pin` parameter for the {{< docref "/components/sensor/ade7953" "ADE7953" >}} MUST be
set to GPIO16 to prevent device overheat (>70ºC idling).
> [!WARNING]
> The ADE7953 IRQ line is connected to the GPIO16. The `irq_pin` parameter for the {{< docref "/components/sensor/ade7953" "ADE7953" >}} MUST be
> set to GPIO16 to prevent device overheat (>70ºC idling).
{{< /warning >}}
Configuration example:
```yaml

18
content/components/cover/template.md
View File

@ -123,16 +123,14 @@ Configuration options:
- **current_operation** (*Optional*, [templatable](#config-templatable), string):
The current operation mode to publish. One of `IDLE`, `OPENING` and `CLOSING`. If using a lambda, use `COVER_OPERATION_IDLE`, `COVER_OPERATION_OPENING`, and `COVER_OPERATION_CLOSING`.
{{< note >}}
This action can also be written in lambdas:
```cpp
id(template_cov).position = COVER_OPEN;
id(template_cov).tilt = 0.5;
id(template_cov).publish_state();
```
{{< /note >}}
> [!NOTE]
> This action can also be written in lambdas:
>
> ```cpp
> id(template_cov).position = COVER_OPEN;
> id(template_cov).tilt = 0.5;
> id(template_cov).publish_state();
> ```
## See Also

8
content/components/cover/time_based.md
View File

@ -70,11 +70,9 @@ cover:
- All other options from [Cover](#config-cover).
{{< note >}}
The stop button on the UI is always enabled even when the cover is stopped and each press
on the button will cause the `stop_action` to be performed.
{{< /note >}}
> [!NOTE]
> The stop button on the UI is always enabled even when the cover is stopped and each press
> on the button will cause the `stop_action` to be performed.
## Handle stop_action

17
content/components/cover/tormatic.md
View File

@ -18,16 +18,15 @@ be supported:
{{< img src="tormatic.png" alt="Image" caption="Tormatic Black 600 Garage Door Drive" class="align-center" >}}
{{< note >}}
This component was written against a Novoferm 423. It has been successfully
tested with Novoferm 423 and Tormatic Black 600, so compatibility with other
models is currently not guaranteed. Please update this documentation if you
confirm this to work on other models as well.
> [!NOTE]
> This component was written against a Novoferm 423. It has been successfully
> tested with Novoferm 423 and Tormatic Black 600, so compatibility with other
> models is currently not guaranteed. Please update this documentation if you
> confirm this to work on other models as well.
>
> The vendor's cloud-based remote is not known to perform model or feature
> detection, so it's assumed that the protocol is the same across all models.
The vendor's cloud-based remote is not known to perform model or feature
detection, so it's assumed that the protocol is the same across all models.
{{< /note >}}
As the communication with the garage door drive is done using UART, you need to
have an [UART bus](#uart) in your configuration with the `rx_pin`
connected unit's USB D- line and the `tx_pin` connected to the USB's D+ line.

13
content/components/datetime/_index.md
View File

@ -10,10 +10,9 @@ params:
ESPHome has support for components to create a datetime entity. A datetime entity
currently represents a date that can be set by the user/frontend.
{{< note >}}
Requires Home Assistant 2024.4 or newer.
> [!NOTE]
> Requires Home Assistant 2024.4 or newer.
{{< /note >}}
{{< anchor "config-datetime" >}}
## Base Datetime Configuration
@ -33,11 +32,9 @@ Configuration variables:
- **id** (*Optional*, string): Manually specify the ID for code generation. At least one of **id** and **name** must be specified.
- **name** (*Optional*, string): The name for the datetime. At least one of **id** and **name** must be specified.
{{< note >}}
If you have a [friendly_name](#esphome-configuration_variables) set for your device and
you want the datetime to use that name, you can set `name: None`.
{{< /note >}}
> [!NOTE]
> If you have a [friendly_name](#esphome-configuration_variables) set for your device and
> you want the datetime to use that name, you can set `name: None`.
- **icon** (*Optional*, icon): Manually set the icon to use for the datetime in the frontend.
- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will

71
content/components/deep_sleep.md
View File

@ -34,9 +34,8 @@ deep_sleep:
sleep_duration: 10min
```
{{< note >}}
Some ESP8266s have an onboard USB chip (e.g. D1 mini) on the chips' control line that is connected to the RST pin. This enables the flasher to reboot the ESP when required. This may interfere with deep sleep on some devices and prevent the ESP from waking when it's powered through its USB connector. Powering the ESP from a separate 3.3V source connected to the 3.3V pin and GND will solve this issue. In these cases, using a USB to TTL adapter will allow you to log ESP activity.
{{< /note >}}
> [!NOTE]
> Some ESP8266s have an onboard USB chip (e.g. D1 mini) on the chips' control line that is connected to the RST pin. This enables the flasher to reboot the ESP when required. This may interfere with deep sleep on some devices and prevent the ESP from waking when it's powered through its USB connector. Powering the ESP from a separate 3.3V source connected to the 3.3V pin and GND will solve this issue. In these cases, using a USB to TTL adapter will allow you to log ESP activity.
## Configuration variables
@ -72,10 +71,9 @@ Advanced features:
- `ALL_LOW`: wake up when all selected pins are LOW (ESP32 only)
- `ANY_HIGH`: wake up when any selected pin is HIGH
{{< note >}}
Only one deep sleep component may be configured.
> [!NOTE]
> Only one deep sleep component may be configured.
{{< /note >}}
{{< anchor "deep_sleep-esp32_wakeup_pin_mode" >}}
## ESP32 Wakeup Pin Mode
@ -171,38 +169,37 @@ on_...:
- deep_sleep.prevent: deep_sleep_1
```
{{< note >}}
For example, if you want to upload a binary via OTA with deep sleep mode it can be difficult to
catch the ESP being active.
> [!NOTE]
> For example, if you want to upload a binary via OTA with deep sleep mode it can be difficult to
> catch the ESP being active.
>
> You can use this automation to automatically prevent deep sleep when a MQTT message on the topic
> `livingroom/ota_mode` is received. Then, to do the OTA update, just
> use a MQTT client to publish a retained MQTT message described below. When the node wakes up again
> it will no longer enter deep sleep mode and you can upload your OTA update.
>
> Remember to turn "OTA mode" off again after the OTA update by sending a MQTT message with the payload
> `OFF`. To enter the deep sleep again after the OTA update send a message on the topic `livingroom/sleep_mode`
> with payload `ON`. Deep sleep will start immediately. Don't forget to delete the payload before the node
> wakes up again.
>
> ```yaml
> deep_sleep:
> # ...
> id: deep_sleep_1
> mqtt:
> # ...
> on_message:
> - topic: livingroom/ota_mode
> payload: 'ON'
> then:
> - deep_sleep.prevent: deep_sleep_1
> - topic: livingroom/sleep_mode
> payload: 'ON'
> then:
> - deep_sleep.enter: deep_sleep_1
> ```
You can use this automation to automatically prevent deep sleep when a MQTT message on the topic
`livingroom/ota_mode` is received. Then, to do the OTA update, just
use a MQTT client to publish a retained MQTT message described below. When the node wakes up again
it will no longer enter deep sleep mode and you can upload your OTA update.
Remember to turn "OTA mode" off again after the OTA update by sending a MQTT message with the payload
`OFF`. To enter the deep sleep again after the OTA update send a message on the topic `livingroom/sleep_mode`
with payload `ON`. Deep sleep will start immediately. Don't forget to delete the payload before the node
wakes up again.
```yaml
deep_sleep:
# ...
id: deep_sleep_1
mqtt:
# ...
on_message:
- topic: livingroom/ota_mode
payload: 'ON'
then:
- deep_sleep.prevent: deep_sleep_1
- topic: livingroom/sleep_mode
payload: 'ON'
then:
- deep_sleep.enter: deep_sleep_1
```
{{< /note >}}
{{< anchor "deep_sleep-allow_action" >}}
## `deep_sleep.allow` Action

9
content/components/dfrobot_sen0395.md
View File

@ -159,12 +159,11 @@ switch:
### `dfrobot_sen0395.settings` Action
{{< warning >}}
Each change to the configuration of the mmWave radar triggers a write to its internal flash/EEPROM.
Write cycles to this memory are limited, so avoid the practice of changing settings frequently.
Determine the appropriate settings for your device and avoid changing them unless absolutely necessary.
> [!WARNING]
> Each change to the configuration of the mmWave radar triggers a write to its internal flash/EEPROM.
> Write cycles to this memory are limited, so avoid the practice of changing settings frequently.
> Determine the appropriate settings for your device and avoid changing them unless absolutely necessary.
{{< /warning >}}
The DFRobot mmWave Radar has several settings which can be changed. These settings are saved in non-volatile memory
and do not need to be set on each boot.

57
content/components/display/_index.md
View File

@ -61,11 +61,10 @@ In this section we will be discussing how to use ESPHome's display rendering eng
and some basic commands. Please note that this only applies to displays that can control each pixel
individually.
{{< note >}}
Display hardware is complex and sometimes doesn't behave as expected. If you're having trouble with your display,
please see [Troubleshooting](#troubleshooting) below.
> [!NOTE]
> Display hardware is complex and sometimes doesn't behave as expected. If you're having trouble with your display,
> please see [Troubleshooting](#troubleshooting) below.
{{< /note >}}
So, first a few basics: When setting up a display platform in ESPHome there will be a configuration
option called `lambda:` which will be called every time ESPHome wants to re-render the display.
In each cycle, the display is automatically cleared before the lambda is executed. You can disable
@ -86,11 +85,10 @@ display:
it.line(0, 0, 50, 50);
```
{{< note >}}
Lambdas are essentially just a lightly modified version of C++. So don't forget to end each line
with a semicolon (`;` ). Otherwise you will be greeted by a long error message at the compilation stage.
> [!NOTE]
> Lambdas are essentially just a lightly modified version of C++. So don't forget to end each line
> with a semicolon (`;` ). Otherwise you will be greeted by a long error message at the compilation stage.
{{< /note >}}
If you compile and upload the configuration above, you should see a black (or white, depending on the display)
line which starts at the top left and goes a few pixels down at a 45° angle. (If it's in another corner, use the
`rotation:` option to rotate the display to your liking)
@ -369,11 +367,10 @@ display:
it.printf(0, 0, id(my_font), "State: %s", id(my_binary_sensor).state ? "ON" : "OFF");
```
{{< note >}}
For displaying external data on the display, for example data from your Home Assistant instance,
you can use the {{< docref "/components/text_sensor/mqtt_subscribe" >}} (see the example there for more information).
> [!NOTE]
> For displaying external data on the display, for example data from your Home Assistant instance,
> you can use the {{< docref "/components/text_sensor/mqtt_subscribe" >}} (see the example there for more information).
{{< /note >}}
{{< anchor "display-strftime" >}}
### Displaying Time
@ -536,20 +533,19 @@ on_...:
}
```
{{< note >}}
To trigger a redraw right after the page show use a [component.update](#component-update_action)
action:
> [!NOTE]
> To trigger a redraw right after the page show use a [component.update](#component-update_action)
> action:
>
> ```yaml
> # For example cycle through pages on a timer
> interval:
> - interval: 5s
> then:
> - display.page.show_next: my_display
> - component.update: my_display
> ```
```yaml
# For example cycle through pages on a timer
interval:
- interval: 5s
then:
- display.page.show_next: my_display
- component.update: my_display
```
{{< /note >}}
{{< anchor "display-is_displaying_page-condition" >}}
**display.is_displaying_page**: This condition returns true while the specified page is being shown.
@ -610,14 +606,11 @@ To help the graphics display team determine the best way to help you, **a pictur
Should you [create an issue](https://github.com/esphome/esphome/issues) in GitHub regarding your display, please
be sure to **include a link to where you purchased the display** so that we can validate the configuration you've used.
{{< note >}}
If you set `update_interval: never` in your config you will not see the test card because the `display:` component will not update the display with the test card. If you want to see a test card, set `update_interval:` to something other than `never`.
> [!NOTE]
> If you set `update_interval: never` in your config you will not see the test card because the `display:` component will not update the display with the test card. If you want to see a test card, set `update_interval:` to something other than `never`.
{{< /note >}}
{{< note >}}
For displays in 8 bit mode you will see distinct color blocks rather than a smooth gradient.
{{< /note >}}
> [!NOTE]
> For displays in 8 bit mode you will see distinct color blocks rather than a smooth gradient.
### See Also

20
content/components/display/addressable_light.md
View File

@ -57,17 +57,15 @@ display:
- **id** (*Optional*, [ID](#config-id)): Manually specify the ID used for code generation.
{{< note >}}
When enabled (the default, but also via `it.set_enabled(true)` ), any effect currently running on the
addressable light will be disabled. When disabled (`it.set_enabled(false)` ), the last configured effect will
be restored.
While the display is enabled, it is still possible to control the parent addressable light component in some
limited capacity. Changing the brightness will still work, but changing the color will have no affect. It is not
adivsable to enable any effects (ex: rainbow, color wipe, etc) while the display is enabled, as this will cause a
great deal of flickering while the effect competes with the display for rendering.
{{< /note >}}
> [!NOTE]
> When enabled (the default, but also via `it.set_enabled(true)` ), any effect currently running on the
> addressable light will be disabled. When disabled (`it.set_enabled(false)` ), the last configured effect will
> be restored.
>
> While the display is enabled, it is still possible to control the parent addressable light component in some
> limited capacity. Changing the brightness will still work, but changing the color will have no affect. It is not
> adivsable to enable any effects (ex: rainbow, color wipe, etc) while the display is enabled, as this will cause a
> great deal of flickering while the effect competes with the display for rendering.
## pixel_mapper

51
content/components/display/ili9xxx.md
View File

@ -44,22 +44,19 @@ ILI9341 ([datasheet](https://cdn-shop.adafruit.com/datasheets/ILI9341.pdf)) and
displays from the same chip family with ESPHome. As this is a somewhat higher resolution display and requires additional pins
beyond the basic SPI connections, and a reasonable amount of RAM, it is not well suited for the ESP8266.
{{< warning >}}
This component has been made redundant since this class of displays is now supported by the [MIPI SPI Display Driver](#mipi_spi).
This component may be removed in a future release.
{{< /warning >}}
> [!WARNING]
> This component has been made redundant since this class of displays is now supported by the [MIPI SPI Display Driver](#mipi_spi).
> This component may be removed in a future release.
{{< note >}}
PSRAM is not automatically enabled on the ESP32 (this changed with the 2025.2 release.) If PSRAM is available, you
should enable it with the {{< docref "/components/psram" "PSRAM configuration" >}}.
Use of 16 bit colors requires twice the amount of RAM as 8 bit, and may not be usable unless PSRAM is available.
> [!NOTE]
> PSRAM is not automatically enabled on the ESP32 (this changed with the 2025.2 release.) If PSRAM is available, you
> should enable it with the {{< docref "/components/psram" "PSRAM configuration" >}}.
> Use of 16 bit colors requires twice the amount of RAM as 8 bit, and may not be usable unless PSRAM is available.
{{< /note >}}
{{< note >}}
The default color depth is 16 bit (RGB565). 8 bit color is also supported, but the color palette must be set to one of the available options.
Use of 16 bit colors requires twice the amount of RAM as 8 bit, and may not be usable unless PSRAM is available.
> [!NOTE]
> The default color depth is 16 bit (RGB565). 8 bit color is also supported, but the color palette must be set to one of the available options.
> Use of 16 bit colors requires twice the amount of RAM as 8 bit, and may not be usable unless PSRAM is available.
{{< /note >}}
{{< img src="ili9341-full.jpg" alt="Image" caption="ILI9341 display" width="75.0%" class="align-center" >}}
```yaml
@ -89,11 +86,9 @@ All [graphical display configuration](#display-configuration) options are availa
- **reset_pin** (*Optional*, [Pin Schema](#config-pin_schema)): The RESET pin.
- **cs_pin** (*Optional*, [Pin Schema](#config-pin_schema)): The CS pin.
{{< note >}}
A DC pin is always required, the CS pin and RESET pin will only be needed if the specific board has those
pins wired to GPIOs.
{{< /note >}}
> [!NOTE]
> A DC pin is always required, the CS pin and RESET pin will only be needed if the specific board has those
> pins wired to GPIOs.
- **color_palette** (*Optional*): When using 8 bit colors, this controls the type of color palette that will be used in the ESP's internal 8-bits-per-pixel buffer. This can be used to improve color depth quality of the image. For example if you know that the display will only be showing grayscale images, the clarity of the display can be improved by targeting the available colors to monochrome only. Options are:
@ -120,17 +115,15 @@ pins wired to GPIOs.
- **mirror_x** (*Optional*, boolean): If true, mirror the x axis.
- **mirror_y** (*Optional*, boolean): If true, mirror the y axis.
{{< note >}}
The `rotation` variable will do a software based rotation.
It is better to use the `transform` option to rotate the display in hardware. Use one of the following combinations:
- 90 degrees - use `swap_xy` with `mirror_x`
- 180 degrees - use `mirror_x` with `mirror_y`
- 270 degrees - use `swap_xy` with `mirror_y`
With 90 and 270 rotations you will also need to swap the `height` and `width` in `dimensions` (see example below.
{{< /note >}}
> [!NOTE]
> The `rotation` variable will do a software based rotation.
> It is better to use the `transform` option to rotate the display in hardware. Use one of the following combinations:
>
> - 90 degrees - use `swap_xy` with `mirror_x`
> - 180 degrees - use `mirror_x` with `mirror_y`
> - 270 degrees - use `swap_xy` with `mirror_y`
>
> With 90 and 270 rotations you will also need to swap the `height` and `width` in `dimensions` (see example below.
- **init_sequence** (*Optional*): Allows custom initialisation sequences to be added. See below for more information.

15
content/components/display/inkplate.md
View File

@ -56,16 +56,13 @@ display:
number: 5
```
{{< warning >}}
When using the Inkplate epaper module, the GPIO pin numbers above *cannot be changed* as they are
hardwired within the module/PCB.
> [!WARNING]
> When using the Inkplate epaper module, the GPIO pin numbers above *cannot be changed* as they are
> hardwired within the module/PCB.
{{< /warning >}}
{{< warning >}}
Inkplate module cannot perform partial update if 3 bit mode is on.
It just ignores the function call in that case.
{{< /warning >}}
> [!WARNING]
> Inkplate module cannot perform partial update if 3 bit mode is on.
> It just ignores the function call in that case.
## Configuration variables

31
content/components/display/lcd_display.md
View File

@ -13,16 +13,15 @@ with ESPHome. This component is only for LCDs that display individual characters
{{< img src="lcd-hello_world.jpg" alt="Image" width="60.0%" class="align-center" >}}
{{< note >}}
Multiple versions of the display exist, supporting different character sets:
> [!NOTE]
> Multiple versions of the display exist, supporting different character sets:
>
> - HD44780UA00 English-Japanese which includes katakana characters, some Greek letters and mathematical symbols
> - HD44780UA02 English-European which includes Greek, Cyrillic and Western European characters (with some diacritics)
> - HD44780UBxx custom, manufacturer-specific character sets
>
> It is also possible to add eight user-defined characters.
- HD44780UA00 English-Japanese which includes katakana characters, some Greek letters and mathematical symbols
- HD44780UA02 English-European which includes Greek, Cyrillic and Western European characters (with some diacritics)
- HD44780UBxx custom, manufacturer-specific character sets
It is also possible to add eight user-defined characters.
{{< /note >}}
{{< anchor "lcd-pcf8574" >}}
## lcd_pcf8574 Component
@ -59,11 +58,10 @@ display:
- **update_interval** (*Optional*, [Time](#config-time)): The interval to re-draw the screen. Defaults to `1s`.
- **id** (*Optional*, [ID](#config-id)): Manually specify the ID used for code generation.
{{< note >}}
If you're not seeing anything on the display, try turning the contrast potentiometer around on the
PCF8574 board.
> [!NOTE]
> If you're not seeing anything on the display, try turning the contrast potentiometer around on the
> PCF8574 board.
{{< /note >}}
{{< anchor "lcd-gpio" >}}
## lcd_gpio Component
@ -109,11 +107,10 @@ display:
- **update_interval** (*Optional*, [Time](#config-time)): The interval to re-draw the screen. Defaults to `1s`.
- **id** (*Optional*, [ID](#config-id)): Manually specify the ID used for code generation.
{{< note >}}
If you're not seeing anything on the display, make sure you apply `3.3V` to the `VEE` (`03` ) contrast control
pin of the board. You can use a potentiometer to make it adjustable.
> [!NOTE]
> If you're not seeing anything on the display, make sure you apply `3.3V` to the `VEE` (`03` ) contrast control
> pin of the board. You can use a potentiometer to make it adjustable.
{{< /note >}}
{{< anchor "display-lcd_lambda" >}}
## Rendering Lambda

12
content/components/display/max7219.md
View File

@ -172,13 +172,11 @@ Please see [Formatted Text](#display-printf) for a quick introduction into the `
| {{< img src="seg1C.svg" alt="Image" >}} | `u`, `v` |
| {{< img src="seg8E.svg" alt="Image" >}} | `~` |
{{< note >}}
Original 7-segment display base image taken from Wikipedia at <https://de.wikipedia.org/wiki/Datei:7_Segment_Display.svg>
by user [h2g2bob](https://commons.wikimedia.org/wiki/User:H2g2bob) under
[Creative Commons BY-SA 3.0](https://creativecommons.org/licenses/by-sa/3.0/deed.de) and modified
for this documentation.
{{< /note >}}
> [!NOTE]
> Original 7-segment display base image taken from Wikipedia at <https://de.wikipedia.org/wiki/Datei:7_Segment_Display.svg>
> by user [h2g2bob](https://commons.wikimedia.org/wiki/User:H2g2bob) under
> [Creative Commons BY-SA 3.0](https://creativecommons.org/licenses/by-sa/3.0/deed.de) and modified
> for this documentation.
## See Also

10
content/components/display/mipi_spi.md
View File

@ -106,12 +106,10 @@ most of the configuration will be set by default, but can be overridden if neede
- **reset_pin** (*Optional*, [Pin Schema](#config-pin_schema)): The RESET pin.
- **cs_pin** (*Optional*, [Pin Schema](#config-pin_schema)): The CS pin.
{{< note >}}
A DC pin is required for single SPI and 8 bit parallel, the CS pin and RESET pin will only be needed if the specific board has those
pins wired to GPIOs. When using a board with integrated display, the pins will be set to the correct values by
default, but can be overridden in the config if needed.
{{< /note >}}
> [!NOTE]
> A DC pin is required for single SPI and 8 bit parallel, the CS pin and RESET pin will only be needed if the specific board has those
> pins wired to GPIOs. When using a board with integrated display, the pins will be set to the correct values by
> default, but can be overridden in the config if needed.
- **enable_pin** (*Optional*, [Pin Schema](#config-pin_schema)): An optional pin to enable the display, if required. A list of pins can be provided for displays that require multiple enable pins. A full pin configuration may be provided
to set the pin mode and inverted property. By default the pin will be driven high to enable the display.

95
content/components/display/nextion.md
View File

@ -28,16 +28,14 @@ bkcmd=0 // Tells the Nextion to not send responses on commands. This is th
This permits faster communication with the Nextion display and it is highly recommended when using
[Hardware UARTs](#uart-hardware_uarts).
{{< warning >}}
**We highly recommend using only** [Hardware UARTs](#uart-hardware_uarts) **with Nextion displays.**
*Use of software UARTs is known to result in unpredictable/inconsistent behavior.*
If you **must** use a software UART, note that baud rates greater than 9600 are extremely likely to cause problems.
In short, avoid using software UARTs with Nextion displays.
{{< /warning >}}
> [!WARNING]
> **We highly recommend using only** [Hardware UARTs](#uart-hardware_uarts) **with Nextion displays.**
>
> *Use of software UARTs is known to result in unpredictable/inconsistent behavior.*
>
> If you **must** use a software UART, note that baud rates greater than 9600 are extremely likely to cause problems.
>
> In short, avoid using software UARTs with Nextion displays.
```yaml
# Example configuration entry
@ -133,11 +131,10 @@ display:
it.set_component_text_printf("textview", "The uptime is: %.1f", id(uptime_sensor).state);
```
{{< note >}}
Although you can use the rendering lambda, most, if not all, updates to the Nextion can be handled by the
individual Nextion components/platforms. **See Below**
> [!NOTE]
> Although you can use the rendering lambda, most, if not all, updates to the Nextion can be handled by the
> individual Nextion components/platforms. **See Below**
{{< /note >}}
See [Formatted Text](#display-printf) for a quick introduction to the `printf` formatting rules and [Displaying Time](#display-strftime) for
an introduction to `strftime` time formatting.
@ -177,31 +174,29 @@ The list below calls out a few commonly-used methods:
- `set_nextion_sensor_state(int queue_type, std::string name, float state);`
- `set_nextion_text_state(std::string name, std::string state);`
{{< note >}}
The example below demonstrates how to define a user-API so Home Assistant can send updates to the Nextion by code.
```yaml
# Enable Home Assistant API
api:
actions:
- action: set_nextion_sensor
variables:
nextion_type: int
name: string
state: float
then:
- lambda: |-
id(nextion1).set_nextion_sensor_state(nextion_type,name,state);
- action: set_nextion_text
variables:
name: string
state: string
then:
- lambda: |-
id(nextion1).set_nextion_text_state(name,state);
```
{{< /note >}}
> [!NOTE]
> The example below demonstrates how to define a user-API so Home Assistant can send updates to the Nextion by code.
>
> ```yaml
> # Enable Home Assistant API
> api:
> actions:
> - action: set_nextion_sensor
> variables:
> nextion_type: int
> name: string
> state: float
> then:
> - lambda: |-
> id(nextion1).set_nextion_sensor_state(nextion_type,name,state);
> - action: set_nextion_text
> variables:
> name: string
> state: string
> then:
> - lambda: |-
> id(nextion1).set_nextion_text_state(name,state);
> ```
### Queue Types
@ -375,14 +370,13 @@ Once completed, both ESPHome and the Nextion will reboot. ESPHome will be unresp
logging or other {{< docref "/automations/index" "automations" >}} will occur. This process uses the same protocol as the
[Nextion Editor](https://nextion.tech/nextion-editor/) and only transfers required portions of the TFT file.
{{< warning >}}
*Use of software UARTs is known to result in unpredictable/inconsistent behavior and will likely result in the
update process failing.*
> [!WARNING]
> *Use of software UARTs is known to result in unpredictable/inconsistent behavior and will likely result in the
> update process failing.*
>
> If you experience problems with the update process and are using a software UART (for example, on the ESP8266), you
> should switch to an ESP32 or supported variant which has more available [Hardware UARTs](#uart-hardware_uarts).
If you experience problems with the update process and are using a software UART (for example, on the ESP8266), you
should switch to an ESP32 or supported variant which has more available [Hardware UARTs](#uart-hardware_uarts).
{{< /warning >}}
You can use Home Assistant itself or any other web server to host the TFT file. When using HTTPS (generally
recommended), you may notice reduced upload speeds as the encryption consumes more resources on the microcontroller.
@ -411,12 +405,11 @@ be `http(s)://your_home_assistant_url:port/local/tft/default.tft`
This library supports a few different components allowing communication between Home Assistant, ESPHome and Nextion.
{{< note >}}
If the Nextion is sleeping or if the component was set to be hidden, it will not update its components even if
updates are sent. To work around this, after the Nextion wakes up, all components will send their states to the
Nextion.
> [!NOTE]
> If the Nextion is sleeping or if the component was set to be hidden, it will not update its components even if
> updates are sent. To work around this, after the Nextion wakes up, all components will send their states to the
> Nextion.
{{< /note >}}
With the exception of the {{< docref "../binary_sensor/nextion" >}} that has the `page_id` /`component_id` options configured,
the example below illustrates:

7
content/components/display/qspi_dbi.md
View File

@ -13,10 +13,9 @@ params:
This display driver supports AMOLED and LCD displays with quad SPI interfaces, using the MIPI DBI interface.
{{< warning >}}
This component has been made redundant since this class of displays is now supported by the {{< docref "mipi_spi" >}}
This component will be removed in a future release.
{{< /warning >}}
> [!WARNING]
> This component has been made redundant since this class of displays is now supported by the {{< docref "mipi_spi" >}}
> This component will be removed in a future release.
This driver has been tested with the following displays:

7
content/components/display/rpi_dpi_rgb.md
View File

@ -14,10 +14,9 @@ params:
This display driver supports displays with 16 bit parallel interfaces, often referred to as "RPI_DPI_RGB" type.
These have a parallel interface but no SPI interface and require no configuration of the driver chip.
{{< warning >}}
This component has been made redundant since this class of displays is now supported by the {{< docref "mipi_rgb" >}}
This component will be removed in a future release.
{{< /warning >}}
> [!WARNING]
> This component has been made redundant since this class of displays is now supported by the {{< docref "mipi_rgb" >}}
> This component will be removed in a future release.
This driver has been tested with the following displays:

10
content/components/display/sdl.md
View File

@ -50,12 +50,10 @@ display:
- **skip_taskbar** (*Optional*, boolean): Whether to skip adding a taskbar icon for the display window or not
- **resizable** (*Optional*, boolean): Whether the display window can be manually resized
{{< note >}}
To build with this display you must have the
[SDL2](https://wiki.libsdl.org/SDL2/Installation) package installed. The Sodium encryption library will
also be required for any API calls. See below for installation hints.
{{< /note >}}
> [!NOTE]
> To build with this display you must have the
> [SDL2](https://wiki.libsdl.org/SDL2/Installation) package installed. The Sodium encryption library will
> also be required for any API calls. See below for installation hints.
## MacOS SDL2 Installation

5
content/components/display/ssd1306.md
View File

@ -82,10 +82,9 @@ display:
- **pages** (*Optional*, list): Show pages instead of a single lambda. See [Display Pages](#display-pages).
- **id** (*Optional*, [ID](#config-id)): Manually specify the ID used for code generation.
{{< note >}}
To speed up the display update process you can select higher I²C frequencies.
> [!NOTE]
> To speed up the display update process you can select higher I²C frequencies.
{{< /note >}}
{{< anchor "ssd1306-spi" >}}
## Over SPI

5
content/components/display/ssd1327.md
View File

@ -57,10 +57,9 @@ display:
- **pages** (*Optional*, list): Show pages instead of a single lambda. See [Display Pages](#display-pages).
- **id** (*Optional*, [ID](#config-id)): Manually specify the ID used for code generation.
{{< note >}}
To speed up the display update process you can select higher I²C frequencies.
> [!NOTE]
> To speed up the display update process you can select higher I²C frequencies.
{{< /note >}}
{{< anchor "ssd1327-spi" >}}
## Over SPI

21
content/components/display/st7567.md
View File

@ -21,18 +21,17 @@ It's a monochrome LCD graphic display.
{{< img src="st7567-full.jpg" alt="Image" caption="ST7567A based LCD Graphic Display (I²C)" width="75.0%" class="align-center" >}}
{{< note >}}
**Voltage:** Check your module specs for required power. Most of the modules are tolerant to range of voltages from 3.3V to 5V, but some might require either 5V or 3.3V.
> [!NOTE]
> **Voltage:** Check your module specs for required power. Most of the modules are tolerant to range of voltages from 3.3V to 5V, but some might require either 5V or 3.3V.
>
> **Electrical interference:** To reduce malfunction caused by noise, datasheet recommends to "use the refresh sequence regularly in a specified interval".
>
> Noone knows what exact interval is - it varies based on your electrical environment - some might need it every hour, for example.
> Without doing refresh sequence picture on LCD might get glitchy after some time.
>
> You can plan refresh by using `interval:` section and calling `request_refresh()` function, after that it will perform display
> refresh sequence on next component update.
**Electrical interference:** To reduce malfunction caused by noise, datasheet recommends to "use the refresh sequence regularly in a specified interval".
Noone knows what exact interval is - it varies based on your electrical environment - some might need it every hour, for example.
Without doing refresh sequence picture on LCD might get glitchy after some time.
You can plan refresh by using `interval:` section and calling `request_refresh()` function, after that it will perform display
refresh sequence on next component update.
{{< /note >}}
{{< anchor "st7567-i2c" >}}
## Over I²C

7
content/components/display/st7735.md
View File

@ -18,10 +18,9 @@ It uses the [SPI Bus](#spi) for communication.
{{< img src="st7735.jpg" alt="Image" caption="ST7735 Display" width="75.0%" class="align-center" >}}
{{< warning >}}
This component has been made redundant since the ST7735 is now supported by the {{< docref "mipi_spi" >}}.
This component will be removed in a future release.
{{< /warning >}}
> [!WARNING]
> This component has been made redundant since the ST7735 is now supported by the {{< docref "mipi_spi" >}}.
> This component will be removed in a future release.
There are numerous board types out there. Some initialize differently as well. This driver will take a few options to narrow down the right settings.

33
content/components/display/st7789v.md
View File

@ -22,18 +22,15 @@ The TTGO T-Display module shown has the display attached to the module's board a
cannot be changed. Other display modules have pin headers or other connectors which must be connected appropriately
to an ESP module.
{{< warning >}}
This component has been made redundant since the ST7789V is now supported by the [MIPI SPI Display Driver](#mipi_spi).
This component will be removed in a future release.
> [!WARNING]
> This component has been made redundant since the ST7789V is now supported by the [MIPI SPI Display Driver](#mipi_spi).
> This component will be removed in a future release.
{{< /warning >}}
{{< note >}}
Displays larger than the 135x240 pixel display on the TTGO T-Display shown require a significant amount of RAM
to operate correctly. Some ESP devices, such as the ESP8266, do not have sufficient memory to support this display.
If you attempt to use this component and experience repeated crashes, this is likely the cause of the issue.
The [MIPI SPI Display Driver](#mipi_spi) component has features that can be used to address this issue.
{{< /note >}}
> [!NOTE]
> Displays larger than the 135x240 pixel display on the TTGO T-Display shown require a significant amount of RAM
> to operate correctly. Some ESP devices, such as the ESP8266, do not have sufficient memory to support this display.
> If you attempt to use this component and experience repeated crashes, this is likely the cause of the issue.
> The [MIPI SPI Display Driver](#mipi_spi) component has features that can be used to address this issue.
```yaml
# Example minimal configuration entry
@ -53,10 +50,8 @@ font:
size: 20
```
{{< note >}}
For more information about the font options see: [Font Renderer Component](#display-fonts).
{{< /note >}}
> [!NOTE]
> For more information about the font options see: [Font Renderer Component](#display-fonts).
### Configuration variables
@ -131,11 +126,9 @@ For all boards you can override the presets by specifying any of the configurati
boards can change between versions so if it doesn't work with the presets check the board pinouts and override options as
required.
{{< note >}}
On memory-constrained devices, it may be possible to use *part* of the display area by
specifying a smaller `height` and/or `width` than that of the actual display.
{{< /note >}}
> [!NOTE]
> On memory-constrained devices, it may be possible to use *part* of the display area by
> specifying a smaller `height` and/or `width` than that of the actual display.
### Configuration examples

6
content/components/display/waveshare_epaper.md
View File

@ -128,10 +128,8 @@ lambda: |-
- `1.54in-m5coreink-m09` - GoodDisplay gdew0154m09, as used in the M5Stack Core Ink
- `13.3in-k` - 13.3in, with the K model, 960x680, B/W rendering only
{{< warning >}}
The BUSY pin on the `gdew0154m09`, the `Waveshare 7.30in-f` and the `Waveshare 7.50in V2` models must be inverted to prevent permanent display damage. Set the busy pin to `inverted: true` in the config.
{{< /warning >}}
> [!WARNING]
> The BUSY pin on the `gdew0154m09`, the `Waveshare 7.30in-f` and the `Waveshare 7.50in V2` models must be inverted to prevent permanent display damage. Set the busy pin to `inverted: true` in the config.
- **busy_pin** (*Optional*, [Pin Schema](#config-pin_schema)): The BUSY pin. Defaults to not connected.
- **reset_pin** (*Optional*, [Pin Schema](#config-pin_schema)): The RESET pin. Defaults to not connected.

14
content/components/display_menu/graphical_display_menu.md
View File

@ -70,11 +70,9 @@ When a **display** is specified the menu will create a [page](#display-pages) as
of the display when invoked. This is useful when you may want to use the display for other purposes but show a menu in response to user
interaction.
{{< note >}}
Pop Up Mode requires that your display makes use of [pages](#display-pages). If you are using a drawing lambda, without pages, it will not
behave as expected. Instead you will have to use Advanced Mode
{{< /note >}}
> [!NOTE]
> Pop Up Mode requires that your display makes use of [pages](#display-pages). If you are using a drawing lambda, without pages, it will not
> behave as expected. Instead you will have to use Advanced Mode
### Advanced Drawing Mode
@ -161,10 +159,8 @@ graphical_display_menu:
return label;
```
{{< note >}}
Ensure that all characters you use in the menu_item_value are available glyphs for your [font](#display-fonts)
{{< /note >}}
> [!NOTE]
> Ensure that all characters you use in the menu_item_value are available glyphs for your [font](#display-fonts)
## User Interaction Example

20
content/components/emc2101.md
View File

@ -15,13 +15,11 @@ The [I²C Bus](#i2c) is required to be set up in your configuration for this sen
{{< img src="emc2101-full.png" alt="Image" caption="EMC2101 Fan Controller and Temperature sensor" width="50.0%" class="align-center" >}}
{{< note >}}
Original image at <https://learn.adafruit.com/assets/97827> created by
by user [Bryan Siepert](https://learn.adafruit.com/u/siddacious) under
[Creative Commons BY-SA 3.0](https://creativecommons.org/licenses/by-sa/3.0/) and modified
for this documentation.
{{< /note >}}
> [!NOTE]
> Original image at <https://learn.adafruit.com/assets/97827> created by
> by user [Bryan Siepert](https://learn.adafruit.com/u/siddacious) under
> [Creative Commons BY-SA 3.0](https://creativecommons.org/licenses/by-sa/3.0/) and modified
> for this documentation.
## EMC2101 Component
@ -73,11 +71,9 @@ output:
- **id** (**Required**, [ID](#config-id)): The ID to use for code generation, and for reference by dependent components.
{{< note >}}
When using the `emc2101` output with a {{< docref "/components/fan/speed" >}} it is advised to configure the **speed_count**
as twice the **resolution** so the number of speeds in the fan matches the number of steps in the fan controller.
{{< /note >}}
> [!NOTE]
> When using the `emc2101` output with a {{< docref "/components/fan/speed" >}} it is advised to configure the **speed_count**
> as twice the **resolution** so the number of speeds in the fan matches the number of steps in the fan controller.
## EMC2101 Sensors

10
content/components/esp32.md
View File

@ -26,12 +26,10 @@ esp32:
to the name can be used to copy the board ID). *This only affects pin aliases and some internal settings*;
This setting is no longer recommended, `variant` should be used instead.
{{< note >}}
At least one of `board` or `variant` must be specified. If `variant` alone is specified (the recommended practice),
the board configuration will be automatically filled using a standard Espressif devkit board
suitable for that variant. Both may be specified (for backwards compatibility) but they must define the same variant.
{{< /note >}}
> [!NOTE]
> At least one of `board` or `variant` must be specified. If `variant` alone is specified (the recommended practice),
> the board configuration will be automatically filled using a standard Espressif devkit board
> suitable for that variant. Both may be specified (for backwards compatibility) but they must define the same variant.
- **flash_size** (*Optional*, string): The amount of flash memory available on the ESP32 board/module. One of `2MB`,
`4MB`, `8MB`, `16MB` or `32MB`. Defaults to `4MB`. **Warning: specifying a size larger than that available

49
content/components/esp32_ble.md
View File

@ -10,14 +10,12 @@ params:
The `esp32_ble` component in ESPHome sets up the Bluetooth LE stack on the device so that a {{< docref "esp32_ble_server/" >}}
can run.
{{< warning >}}
The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
**Crashes are likely to occur** if you include too many additional components in your device's
configuration. Memory-intensive components such as {{< docref "/components/voice_assistant" >}} and other
audio components are most likely to cause issues.
{{< /warning >}}
> [!WARNING]
> The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
>
> **Crashes are likely to occur** if you include too many additional components in your device's
> configuration. Memory-intensive components such as {{< docref "/components/voice_assistant" >}} and other
> audio components are most likely to cause issues.
```yaml
# Example configuration
@ -49,27 +47,21 @@ esp32_ble:
- **disable_bt_logs** (*Optional*, boolean): When enabled, disables Bluetooth logging categories that are not used by the configured components. This saves flash memory by only including the loggers needed by your configuration. Defaults to `true`.
{{< note >}}
The `disable_bt_logs` option intelligently disables only the Bluetooth logging categories that are not required by your configuration. Each Bluetooth component registers the specific loggers it needs, and all unused loggers are automatically disabled during compilation. This includes loggers for Classic Bluetooth features (like RFCOMM, A2DP, HID) that are not used by ESPHome's BLE implementation.
{{< /note >}}
> [!NOTE]
> The `disable_bt_logs` option intelligently disables only the Bluetooth logging categories that are not required by your configuration. Each Bluetooth component registers the specific loggers it needs, and all unused loggers are automatically disabled during compilation. This includes loggers for Classic Bluetooth features (like RFCOMM, A2DP, HID) that are not used by ESPHome's BLE implementation.
- **connection_timeout** (*Optional*, [Time](#config-time)): The maximum time to wait for a BLE connection to be established. Only available when using ESP-IDF framework. Defaults to `20s`.
- Range: 10 to 180 seconds
- This timeout should align with the timeout used by your BLE client software to prevent connection slot waste
{{< note >}}
The `connection_timeout` option is particularly important when using ESPHome as a Bluetooth proxy. The default of 20 seconds matches the timeout used by aioesphomeapi and bleak-retry-connector. If a connection attempt times out on the client side but ESP-IDF continues trying to connect, the connection slot remains occupied and unavailable for new connections. Setting this to match your client timeout ensures connection slots are freed immediately when a connection fails.
{{< /note >}}
> [!NOTE]
> The `connection_timeout` option is particularly important when using ESPHome as a Bluetooth proxy. The default of 20 seconds matches the timeout used by aioesphomeapi and bleak-retry-connector. If a connection attempt times out on the client side but ESP-IDF continues trying to connect, the connection slot remains occupied and unavailable for new connections. Setting this to match your client timeout ensures connection slots are freed immediately when a connection fails.
- **advertising** (*Optional*, boolean): Manually enable BLE advertising support. This is automatically enabled when using {{< docref "esp32_ble_server/" >}} or {{< docref "esp32_ble_beacon/" >}}. Only set this to `true` if you need advertising functionality without those components. Defaults to `false`.
{{< note >}}
The `advertising` option is an advanced feature that manually enables BLE advertising compilation. In most cases, you don't need to set this as advertising is automatically enabled when using components that require it (like `esp32_ble_server` or `esp32_ble_beacon` ). This option is primarily useful for custom components or special use cases where you need advertising functionality without the standard server or beacon components.
{{< /note >}}
> [!NOTE]
> The `advertising` option is an advanced feature that manually enables BLE advertising compilation. In most cases, you don't need to set this as advertising is automatically enabled when using components that require it (like `esp32_ble_server` or `esp32_ble_beacon` ). This option is primarily useful for custom components or special use cases where you need advertising functionality without the standard server or beacon components.
- **advertising_cycle_time** (*Optional*, [Time](#config-time)): The time interval for cycling through multiple advertisements. Only applicable when advertising is enabled. Defaults to `10s`.
- **max_notifications** (*Optional*, integer): The maximum number of BLE characteristics that can have notifications enabled across all connections. Only available when using ESP-IDF framework. Defaults to `12`.
@ -78,10 +70,8 @@ The `advertising` option is an advanced feature that manually enables BLE advert
- This is a global limit shared across all BLE connections
- Increase if you see `ESP_GATT_NO_RESOURCES` (status=128) errors when enabling notifications
{{< note >}}
The `max_notifications` option controls the `CONFIG_BT_GATTC_NOTIF_REG_MAX` ESP-IDF setting. This limit is per GATT client interface, not per connection. If you're using ESPHome as a Bluetooth proxy with multiple devices that have many characteristics requiring notifications, you may need to increase this value. The error `status=128` in logs indicates you've hit this limit.
{{< /note >}}
> [!NOTE]
> The `max_notifications` option controls the `CONFIG_BT_GATTC_NOTIF_REG_MAX` ESP-IDF setting. This limit is per GATT client interface, not per connection. If you're using ESPHome as a Bluetooth proxy with multiple devices that have many characteristics requiring notifications, you may need to increase this value. The error `status=128` in logs indicates you've hit this limit.
## `ble.disable` Action
@ -93,10 +83,8 @@ on_...:
- ble.disable:
```
{{< note >}}
The configuration option `enable_on_boot` can be set to `false` if you do not want BLE to be enabled on boot.
{{< /note >}}
> [!NOTE]
> The configuration option `enable_on_boot` can be set to `false` if you do not want BLE to be enabled on boot.
## `ble.enable` Action
@ -108,10 +96,9 @@ on_...:
- ble.enable:
```
{{< note >}}
The configuration option `enable_on_boot` can be set to `false` if you do not want BLE to be enabled on boot.
> [!NOTE]
> The configuration option `enable_on_boot` can be set to `false` if you do not want BLE to be enabled on boot.
{{< /note >}}
{{< anchor "ble-enabled_condition" >}}
## `ble.enabled` Condition

14
content/components/esp32_ble_beacon.md
View File

@ -11,14 +11,12 @@ The `esp32_ble_beacon` component creates a Bluetooth Low Energy Beacon with your
Beacons are BLE devices that repeatedly just send out a pre-defined packet of data. This packet
can then be received by devices like smartphones and can then be used to track a phone's location.
{{< warning >}}
The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
**Crashes are likely to occur** if you include too many additional components in your device's
configuration. Memory-intensive components such as {{< docref "/components/voice_assistant" >}} and other
audio components are most likely to cause issues.
{{< /warning >}}
> [!WARNING]
> The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
>
> **Crashes are likely to occur** if you include too many additional components in your device's
> configuration. Memory-intensive components such as {{< docref "/components/voice_assistant" >}} and other
> audio components are most likely to cause issues.
```yaml
# Example configuration entry

14
content/components/esp32_ble_server.md
View File

@ -10,14 +10,12 @@ params:
The `esp32_ble_server` component in ESPHome sets up a BLE GATT server that exposes the device name,
manufacturer and board. BLE GATT services and characteristics can be added to the server to expose data and control.
{{< warning >}}
The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
**Crashes are likely to occur** if you include too many additional components in your device's
configuration. Memory-intensive components such as {{< docref "/components/voice_assistant" >}} and other
audio components are most likely to cause issues.
{{< /warning >}}
> [!WARNING]
> The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
>
> **Crashes are likely to occur** if you include too many additional components in your device's
> configuration. Memory-intensive components such as {{< docref "/components/voice_assistant" >}} and other
> audio components are most likely to cause issues.
```yaml
# Example configuration

28
content/components/esp32_ble_tracker.md
View File

@ -13,14 +13,12 @@ using your ESP32 node.
See [Setting up devices](#esp32_ble_tracker-setting_up_devices) for information on how you can determine
the MAC address of a device and track it using ESPHome.
{{< warning >}}
The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
**Crashes are likely to occur** if you include too many additional components in your device's
configuration. Memory-intensive components such as {{< docref "/components/voice_assistant" >}} and other
audio components are most likely to cause issues.
{{< /warning >}}
> [!WARNING]
> The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
>
> **Crashes are likely to occur** if you include too many additional components in your device's
> configuration. Memory-intensive components such as {{< docref "/components/voice_assistant" >}} and other
> audio components are most likely to cause issues.
```yaml
# Example configuration entry
@ -58,12 +56,11 @@ sensor:
name: "Xiaomi MiJia Battery Level"
```
{{< note >}}
The first time this component is enabled for an ESP32, the code partition needs to be
resized. Please flash the ESP32 via USB when adding this to your configuration. After that,
you can use OTA updates again.
> [!NOTE]
> The first time this component is enabled for an ESP32, the code partition needs to be
> resized. Please flash the ESP32 via USB when adding this to your configuration. After that,
> you can use OTA updates again.
{{< /note >}}
{{< anchor "config-esp32_ble_tracker" >}}
## Configuration variables
@ -254,9 +251,8 @@ on_...:
- **continuous** (*Optional*, boolean): Whether to start the scan in continuous mode. Defaults to `false`
{{< note >}}
This action can also be written in [lambdas](#config-lambda):
{{< /note >}}
> [!NOTE]
> This action can also be written in [lambdas](#config-lambda):
```yaml
esp32_ble_tracker:

34
content/components/esp32_camera.md
View File

@ -180,22 +180,18 @@ Test Setting:
- **test_pattern** (*Optional*, boolean): For tests purposes, it's possible to replace picture get from sensor by a test color pattern. Defaults to `false`.
{{< note >}}
Camera uses PWM timer #1. If you need PWM (via the `ledc` platform) you need to manually specify
a channel there (with the `channel: 2` parameter)
{{< /note >}}
> [!NOTE]
> Camera uses PWM timer #1. If you need PWM (via the `ledc` platform) you need to manually specify
> a channel there (with the `channel: 2` parameter)
## Configuration examples
**Ai-Thinker Camera**:
{{< warning >}}
GPIO16 on this board (and possibly other boards below) is connected to onboard PSRAM.
Using this GPIO for other purposes (eg as a button) will trigger the watchdog.
Further information on pin notes can be found here: <https://github.com/raphaelbs/esp32-cam-ai-thinker/blob/master/docs/esp32cam-pin-notes.md>
{{< /warning >}}
> [!WARNING]
> GPIO16 on this board (and possibly other boards below) is connected to onboard PSRAM.
> Using this GPIO for other purposes (eg as a button) will trigger the watchdog.
> Further information on pin notes can be found here: <https://github.com/raphaelbs/esp32-cam-ai-thinker/blob/master/docs/esp32cam-pin-notes.md>
```yaml
# Example configuration entry
@ -222,15 +218,13 @@ esp32_camera:
**M5Stack Camera**:
{{< warning >}}
This camera board has insufficient cooling and will overheat over time,
ESPHome does only activate the camera when Home Assistant requests an image, but
the camera unit can still heat up considerably for some boards.
If the camera is not recognized after a reboot and the unit feels warm, try waiting for
it to cool down and check again - if that still doesn't work try enabling the test pattern.
{{< /warning >}}
> [!WARNING]
> This camera board has insufficient cooling and will overheat over time,
> ESPHome does only activate the camera when Home Assistant requests an image, but
> the camera unit can still heat up considerably for some boards.
>
> If the camera is not recognized after a reboot and the unit feels warm, try waiting for
> it to cool down and check again - if that still doesn't work try enabling the test pattern.
```yaml
# Example configuration entry

14
content/components/esp32_improv.md
View File

@ -12,14 +12,12 @@ for configuring Wi-Fi on an ESP32 device by using Bluetooth Low Energy (BLE) to
The `esp32_improv` component will automatically set up the {{< docref "esp32_ble" "BLE Server" >}}.
{{< warning >}}
The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
**Crashes are likely to occur** if you include too many additional components in your device's
configuration. Memory-intensive components such as {{< docref "/components/voice_assistant" >}} and other
audio components are most likely to cause issues.
{{< /warning >}}
> [!WARNING]
> The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
>
> **Crashes are likely to occur** if you include too many additional components in your device's
> configuration. Memory-intensive components such as {{< docref "/components/voice_assistant" >}} and other
> audio components are most likely to cause issues.
```yaml
# Example configuration entry

19
content/components/esphome.md
View File

@ -136,11 +136,9 @@ esphome:
This automation will be triggered when the ESP is about to shut down. Shutting down is usually caused by
too many WiFi/MQTT connection attempts, Over-The-Air updates being applied or through the {{< docref "deep_sleep/" >}}.
{{< note >}}
It's not guaranteed that all components are in a connected state when this automation is triggered. For
example, the MQTT client may have already disconnected. For use-cases that require specific shutdown ordering, look at the `priority` parameter.
{{< /note >}}
> [!NOTE]
> It's not guaranteed that all components are in a connected state when this automation is triggered. For
> example, the MQTT client may have already disconnected. For use-cases that require specific shutdown ordering, look at the `priority` parameter.
```yaml
esphome:
@ -343,13 +341,12 @@ Using `name_add_mac_suffix` allows {{< docref "/guides/creators" "creators" >}}
provision multiple devices at the factory with a single firmware and still
have unique identification for customer installs.
{{< note >}}
End users will need to create an individual YAML config file if they want to OTA update the
devices in the future. Creators can facilitate this process by providing `dashboard_import` URL
for end users. This allows them to easily update their devices as new features are made available
upstream.
> [!NOTE]
> End users will need to create an individual YAML config file if they want to OTA update the
> devices in the future. Creators can facilitate this process by providing `dashboard_import` URL
> for end users. This allows them to easily update their devices as new features are made available
> upstream.
{{< /note >}}
{{< anchor "esphome-creators_project" >}}
## Project information

8
content/components/espnow.md
View File

@ -11,11 +11,9 @@ This component allows ESPHome to communicate with esp32 devices in a simple and
It enables the option to interact with other esp32 devices over the Espressif's ESP-NOW protocol, see
[documentation](https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-reference/network/esp_now.html)
{{< note >}}
Broadcasting data is not recommended, this will also reach devices not controlled by you that use the esp-now protocol.
The best solution is to minimize the broadcasting as much as possible and use it only for identification purposes.
{{< /note >}}
> [!NOTE]
> Broadcasting data is not recommended, this will also reach devices not controlled by you that use the esp-now protocol.
> The best solution is to minimize the broadcasting as much as possible and use it only for identification purposes.
```yaml
# Example configuration entry

44
content/components/ethernet.md
View File

@ -141,18 +141,15 @@ If you are using a framework that does not support SPI-based ethernet modules wi
- **id** (*Optional*, [ID](#config-id)): Manually specify the ID used for code generation.
{{< note >}}
If your Ethernet board is not designed with an ESP32 built in, it's common to attempt
to use flying leads, dupont wires, etc. to connect the Ethernet controller to the ESP32.
This approach is likely to fail, however, as the Ethernet interface uses a high frequency
clock signal that will not travel reliably over these types of connections. For more
information and wiring details refer to the link in the *See also* section.
> [!NOTE]
> If your Ethernet board is not designed with an ESP32 built in, it's common to attempt
> to use flying leads, dupont wires, etc. to connect the Ethernet controller to the ESP32.
> This approach is likely to fail, however, as the Ethernet interface uses a high frequency
> clock signal that will not travel reliably over these types of connections. For more
> information and wiring details refer to the link in the *See also* section.
{{< /note >}}
{{< note >}}
SPI based chips do *not* use {{< docref "spi/" >}}. This means that SPI pins can't be shared with other devices.
{{< /note >}}
> [!NOTE]
> SPI based chips do *not* use {{< docref "spi/" >}}. This means that SPI pins can't be shared with other devices.
## Configuration examples
@ -170,10 +167,9 @@ ethernet:
power_pin: GPIO12
```
{{< note >}}
WROVER version of Olimex POE cards change CLK to pin GPIO0.
> [!NOTE]
> WROVER version of Olimex POE cards change CLK to pin GPIO0.
{{< /note >}}
**Olimex ESP32-EVB**:
```yaml
@ -284,10 +280,9 @@ ethernet:
page_id: 0x07
```
{{< 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.
> [!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.
{{< /note >}}
**OpenHacks LAN8720**:
```yaml
@ -298,12 +293,11 @@ ethernet:
phy_addr: 1
```
{{< note >}}
This board has an issue that might cause the ESP32 to boot in program mode. When testing, make sure
you are monitoring the serial output and reboot the device several times to see if it boots into the
program properly.
> [!NOTE]
> This board has an issue that might cause the ESP32 to boot in program mode. When testing, make sure
> you are monitoring the serial output and reboot the device several times to see if it boots into the
> program properly.
{{< /note >}}
**Esp32-Stick-Eth** and **Esp32-Stick-PoE-P** and **Esp32-Stick-PoE-A**:
```yaml
@ -365,10 +359,8 @@ ethernet:
clock_speed: 8MHz
```
{{< note >}}
Using a higher clock_speed, including default, might cause rx errors and dropped packets.
{{< /note >}}
> [!NOTE]
> Using a higher clock_speed, including default, might cause rx errors and dropped packets.
## See Also

22
content/components/event/_index.md
View File

@ -13,16 +13,14 @@ enabling complex automations and integrations. An event entity is represented as
entity associated with a device that has a pre-defined set of event types which can be
triggered in Home Assistant via automations.
{{< note >}}
Events in ESPHome are designed to trigger an action in Home Assistant, and have a unidirectional flow from ESPHome to Home Assistant.
Home Assistant event entities are different from events on event bus. If you just want to trigger an event on the
Home Assistant event bus, you should use a [Home Assistant event](#api-homeassistant_event_action) instead.
> [!NOTE]
> Events in ESPHome are designed to trigger an action in Home Assistant, and have a unidirectional flow from ESPHome to Home Assistant.
> Home Assistant event entities are different from events on event bus. If you just want to trigger an event on the
> Home Assistant event bus, you should use a [Home Assistant event](#api-homeassistant_event_action) instead.
{{< /note >}}
{{< note >}}
Home Assistant Core 2024.5 or higher is required for ESPHome event entities to work.
> [!NOTE]
> Home Assistant Core 2024.5 or higher is required for ESPHome event entities to work.
{{< /note >}}
{{< anchor "config-event" >}}
## Base Event Configuration
@ -51,11 +49,9 @@ One of `id` or `name` is required.
- **id** (*Optional*, [ID](#config-id)): Manually specify the ID used for code generation. At least one of **id** and **name** must be specified.
- **name** (*Optional*, string): The name for the event. At least one of **id** and **name** must be specified.
{{< note >}}
If you have a [friendly_name](#esphome-configuration_variables) set for your device and
you want the event to use that name, you can set `name: None`.
{{< /note >}}
> [!NOTE]
> If you have a [friendly_name](#esphome-configuration_variables) set for your device and
> you want the event to use that name, you can set `name: None`.
- **icon** (*Optional*, icon): Manually set the icon to use for the event in the frontend.
- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will

9
content/components/ezo_pmp.md
View File

@ -12,12 +12,11 @@ Both the EZO-PMP ([datasheet](https://files.atlas-scientific.com/EZO_PMP_Datashe
and EZO-PMP-L ([datasheet](https://files.atlas-scientific.com/EZO_PMP_L_Datasheet.pdf)) are supported.
The [I²C Bus](#i2c) is required to be set up in your configuration for this sensor to work.
{{< note >}}
This component will not be directly controllable in the Home Assistant front-end automatically because
Home Assistant doesn't have support for pumps. In order to control the pump from the frontend you will need to use
templates to offer access to the actions you need. Please see [Home Assistant Configuration](#ezo-pmp-ha-config).
> [!NOTE]
> This component will not be directly controllable in the Home Assistant front-end automatically because
> Home Assistant doesn't have support for pumps. In order to control the pump from the frontend you will need to use
> templates to offer access to the actions you need. Please see [Home Assistant Configuration](#ezo-pmp-ha-config).
{{< /note >}}
{{< img src="ezo-pmp.jpg" alt="Image" width="80.0%" class="align-center" >}}
## Component/Hub

14
content/components/factory_reset.md
View File

@ -13,14 +13,12 @@ After reboot all states, parameters and variables will be reinitialized with the
- in case of moving a device to a new environment or starting a new use-case (e.g. reset counters or state)
- for privacy concerns when giving away a device
{{< note >}}
**USE WITH GREAT CAUTION!** All credentials, global variables, counters and saved states stored in non-volatile memory will be lost with no chance of recovering them.
Even raw reading of flash memory with `esptool` will not help, since data is physically erased from flash memory.
For devices configured using {{< docref "/components/captive_portal" "captive portal" >}}, this will reset WiFi settings as well, thus making such devices offline.
You'll need to be in close proximity to your device to configure it again using a built-in WiFi access point and captive portal.
{{< /note >}}
> [!NOTE]
> **USE WITH GREAT CAUTION!** All credentials, global variables, counters and saved states stored in non-volatile memory will be lost with no chance of recovering them.
> Even raw reading of flash memory with `esptool` will not help, since data is physically erased from flash memory.
>
> For devices configured using {{< docref "/components/captive_portal" "captive portal" >}}, this will reset WiFi settings as well, thus making such devices offline.
> You'll need to be in close proximity to your device to configure it again using a built-in WiFi access point and captive portal.
## Reset by Fast Power Cycling

8
content/components/fan/_index.md
View File

@ -29,11 +29,9 @@ Configuration variables:
- **id** (*Optional*, string): Manually specify the ID for code generation. At least one of **id** and **name** must be specified.
- **name** (*Optional*, string): The name of the fan. At least one of **id** and **name** must be specified.
{{< note >}}
If you have a [friendly_name](#esphome-configuration_variables) set for your device and
you want the fan to use that name, you can set `name: None`.
{{< /note >}}
> [!NOTE]
> If you have a [friendly_name](#esphome-configuration_variables) set for your device and
> you want the fan to use that name, you can set `name: None`.
- **icon** (*Optional*, icon): Manually set the icon to use for the fan in the frontend.
- **restore_mode** (*Optional*): Control how the fan attempts to restore state on boot.

8
content/components/fan/tuya.md
View File

@ -57,11 +57,9 @@ fan:
- **speed_count** (*Optional*, int): Set the number of supported discrete speed levels. Defaults to `3`.
- All other options from [Fan](#config-fan).
{{< note >}}
The MCU on the Tuya dimmer handles the LEDs and they dont seem to be controllable
over the serial bus.
{{< /note >}}
> [!NOTE]
> The MCU on the Tuya dimmer handles the LEDs and they dont seem to be controllable
> over the serial bus.
## See Also

5
content/components/fingerprint_grow.md
View File

@ -125,10 +125,9 @@ fingerprint_grow:
## Setting a New Password
{{< warning >}}
Forgetting the password will render your fingerprint reader unusable!
> [!WARNING]
> Forgetting the password will render your fingerprint reader unusable!
{{< /warning >}}
You can set a new password for your fingerprint reader using the `new_password:` configuration option. The password is defined as a 32-bit unsigned integer.
```yaml

40
content/components/font.md
View File

@ -115,12 +115,11 @@ The Component provides some useful font metrics. Those include:
- **height** (`get_height()` ): The lineheight of the font measured from baseline to baseline.
{{< note >}}
The `capheight` and `xheight` values are typically calculated using glyphs with flat tops.
Rounded characters however might overshoot this value slightly to make them visually appear as the same size.
For special fonts like the Material Design Icons font, which do not contain any letters, these two metrics will be set to 0.
> [!NOTE]
> The `capheight` and `xheight` values are typically calculated using glyphs with flat tops.
> Rounded characters however might overshoot this value slightly to make them visually appear as the same size.
> For special fonts like the Material Design Icons font, which do not contain any letters, these two metrics will be set to 0.
{{< /note >}}
The following code snipped produces the image below. Note that the lines in the code are ordered as they appear in the image from top to bottom.
For this font the `descender` and `height` are only one pixel apart.
@ -215,24 +214,21 @@ it.horizontal_line(0, height, it.get_width());
- **file** (**Required**, string): The path of the font file with the extra glyphs.
- **glyphs** (**Required**, list): A list of glyphs you want to include. Can't repeat the same glyph codepoint if it was declared in the level above.
{{< note >}}
OpenType/TrueType font files offer icons at codepoints far from what's reachable on a standard keyboard, for these it's needed
to specify the unicode codepoint of the glyph as a hex address escaped with `\u` or `\U`.
> [!NOTE]
> OpenType/TrueType font files offer icons at codepoints far from what's reachable on a standard keyboard, for these it's needed
> to specify the unicode codepoint of the glyph as a hex address escaped with `\u` or `\U`.
>
> - Code points up to `0xFFFF` are encoded like `\uE6E8`. Lowercase `\u` and exactly 4 hexadecimal digits.
> - Code points above `0xFFFF` are encoded like `\U0001F5E9`. Capital `\U` and exactly 8 hexadecimal digits.
>
> The `extras` section only supports OpenType/TrueType files, `size` and `bpp` will be the same as the above level. This will allow printing icons alongside the characters in the same string, like `I \uF004 You \uF001`.
>
> Many font sizes with multiple glyphs at high bit depths will increase the binary size considerably. Make your choices carefully.
- Code points up to `0xFFFF` are encoded like `\uE6E8`. Lowercase `\u` and exactly 4 hexadecimal digits.
- Code points above `0xFFFF` are encoded like `\U0001F5E9`. Capital `\U` and exactly 8 hexadecimal digits.
The `extras` section only supports OpenType/TrueType files, `size` and `bpp` will be the same as the above level. This will allow printing icons alongside the characters in the same string, like `I \uF004 You \uF001`.
Many font sizes with multiple glyphs at high bit depths will increase the binary size considerably. Make your choices carefully.
{{< /note >}}
{{< note >}}
To use fonts you will need to have the python `pillow` package installed, as ESPHome uses that package
to translate the OpenType/TrueType and bitmap font files into an internal format. If you're running this as a Home Assistant add-on or with the official ESPHome docker image, it should already be installed. Otherwise you need
to install it using `pip install "pillow==10.4.0"`.
{{< /note >}}
> [!NOTE]
> To use fonts you will need to have the python `pillow` package installed, as ESPHome uses that package
> to translate the OpenType/TrueType and bitmap font files into an internal format. If you're running this as a Home Assistant add-on or with the official ESPHome docker image, it should already be installed. Otherwise you need
> to install it using `pip install "pillow==10.4.0"`.
## See Also

14
content/components/globals.md
View File

@ -74,14 +74,12 @@ on_...:
- **value** (**Required**, [templatable](#config-templatable)): The value to set the global
variable to.
{{< note >}}
This action can also be written in lambdas:
```cpp
id(my_global_var) = 10;
```
{{< /note >}}
> [!NOTE]
> This action can also be written in lambdas:
>
> ```cpp
> id(my_global_var) = 10;
> ```
## See Also

18
content/components/graph.md
View File

@ -163,13 +163,11 @@ color:
blue: 0%
```
{{< note >}}
Here are some things to note:
- Setting `y_grid` will expand any specified range to the nearest multiple of grid spacings.
- Axis labels are currently not possible without manually placing them.
- The grid and border color is set with `it.graph()`, while the traces are defined separately.
- Legends are drawn separately using `it.graph_legend()` and can be positioned independently of the graph.
- Legend dimensions are automatically calculated if not specified, based on font sizes and trace count.
{{< /note >}}
> [!NOTE]
> Here are some things to note:
>
> - Setting `y_grid` will expand any specified range to the nearest multiple of grid spacings.
> - Axis labels are currently not possible without manually placing them.
> - The grid and border color is set with `it.graph()`, while the traces are defined separately.
> - Legends are drawn separately using `it.graph_legend()` and can be positioned independently of the graph.
> - Legend dimensions are automatically calculated if not specified, based on font sizes and trace count.

13
content/components/host.md
View File

@ -13,13 +13,12 @@ to work on MacOS and Linux. On Windows [WSL](https://learn.microsoft.com/en-us/w
The only configuration required is to optionally set a dummy MAC address that will be used to identify the
configuration to Home Assistant (the native MAC address is not readily available.)
{{< note >}}
HA will not automatically discover an ESPHome instance running on `host` using mDNS, and you will need
to add it explicitly using the IP address of your host computer. If HA cannot establish a connection when
adding the device manually, the firewall settings of the local host computer may be the cause. The
ESPHome *API* port (`6053` ) must be allowed through the firewall.
See {{< docref "/components/api" >}} for details.
{{< /note >}}
> [!NOTE]
> HA will not automatically discover an ESPHome instance running on `host` using mDNS, and you will need
> to add it explicitly using the IP address of your host computer. If HA cannot establish a connection when
> adding the device manually, the firewall settings of the local host computer may be the cause. The
> ESPHome *API* port (`6053` ) must be allowed through the firewall.
> See {{< docref "/components/api" >}} for details.
Many components, especially those interfacing to actual hardware, will not be available when using `host`. Do not
configure wifi - network will automatically be available using the host computer.

43
content/components/http_request.md
View File

@ -53,31 +53,28 @@ http_request:
- HTTPS connections will not be possible
- `verify_ssl: false` is implied
{{< warning >}}
Setting `verify_ssl` to `false` **reduces security** when using HTTPS connections!
> [!WARNING]
> Setting `verify_ssl` to `false` **reduces security** when using HTTPS connections!
>
> Without the root certificate bundle, certificates used by the remote HTTPS server cannot be verified, opening the
> HTTPS connection up to person-in-the-middle attacks.
>
> To maximize security, do not set `verify_ssl` to `false` *unless:*
>
> - a custom CA/self-signed certificate is used,
> - the Arduino framework is used, or
> - the device does not have sufficient memory to store the certificate bundle
>
> **We strongly recommend using hardware which properly supports TLS/SSL.**
Without the root certificate bundle, certificates used by the remote HTTPS server cannot be verified, opening the
HTTPS connection up to person-in-the-middle attacks.
To maximize security, do not set `verify_ssl` to `false` *unless:*
- a custom CA/self-signed certificate is used,
- the Arduino framework is used, or
- the device does not have sufficient memory to store the certificate bundle
**We strongly recommend using hardware which properly supports TLS/SSL.**
{{< /warning >}}
**For the host platform:**
- **ca_certificate_path** (*Optional*, file path): Path to a CA certificate bundle. Not required on MacOS (the inbuilt CA bundle is used and SSL enabled by default).
On Linux this is required to enable SSL.
{{< note >}}
To use SSL on Linux you must have the `libssl-dev` package installed (e.g. `sudo apt install libssl-dev` ).
A typical value on Linux for `ca_certificate_path` would be `/etc/ssl/certs/ca-certificates.crt`.
{{< /note >}}
> [!NOTE]
> To use SSL on Linux you must have the `libssl-dev` package installed (e.g. `sudo apt install libssl-dev` ).
> A typical value on Linux for `ca_certificate_path` would be `/etc/ssl/certs/ca-certificates.crt`.
## Actions
@ -181,11 +178,9 @@ The following variables are available for use in [lambdas](#config-lambda):
- `body` as `std::string` which contains the response body when `capture_response`
(see [`http_request.get` Action](#http_request-get_action)) is set to `true`.
{{< note >}}
The `status_code` should be checked before using the `body` variable. A successful response will usually have
a status code of `200`. Server errors such as "not found" (404) or "internal server error" (500) will have an appropriate status code, and may contain an error message in the `body` variable.
{{< /note >}}
> [!NOTE]
> The `status_code` should be checked before using the `body` variable. A successful response will usually have
> a status code of `200`. Server errors such as "not found" (404) or "internal server error" (500) will have an appropriate status code, and may contain an error message in the `body` variable.
```yaml
on_...

43
content/components/i2c.md
View File

@ -47,29 +47,28 @@ i2c:
- **id** (*Optional*, [ID](#config-id)): Manually specify the ID for this I²C bus if you need multiple I²C buses.
{{< note >}}
If the device can support multiple I²C buses these buses need to be defined as below and sensors need to be setup specifying the correct bus:
> [!NOTE]
> If the device can support multiple I²C buses these buses need to be defined as below and sensors need to be setup specifying the correct bus:
>
> ```yaml
> # Example configuration entry
> i2c:
> - id: bus_a
> sda: GPIOXX
> scl: GPIOXX
> scan: true
> - id: bus_b
> sda: GPIOXX
> scl: GPIOXX
> scan: true
> # Sensors should be specified as follows
> sensor:
> - platform: bme680
> i2c_id: bus_b
> address: 0x76
> # ...
> ```
```yaml
# Example configuration entry
i2c:
- id: bus_a
sda: GPIOXX
scl: GPIOXX
scan: true
- id: bus_b
sda: GPIOXX
scl: GPIOXX
scan: true
# Sensors should be specified as follows
sensor:
- platform: bme680
i2c_id: bus_b
address: 0x76
# ...
```
{{< /note >}}
For I²C multiplexing see {{< docref "/components/tca9548a" >}}.
## See Also

12
content/components/image.md
View File

@ -83,13 +83,11 @@ image:
but you can override this by setting `byte_order` to `little_endian`. Options are `big_endian` (default) and `little_endian`.
Not applicable to other image formats.
{{< note >}}
To use images you will need to have the python `pillow` package installed.
Additionally, if you want to use SVG images (including MDI images), you will
additionally need to have the python `cairosvg` package installed. These are automatically installed when
setting up ESPHome via the usual methods.
{{< /note >}}
> [!NOTE]
> To use images you will need to have the python `pillow` package installed.
> Additionally, if you want to use SVG images (including MDI images), you will
> additionally need to have the python `cairosvg` package installed. These are automatically installed when
> setting up ESPHome via the usual methods.
## Setting defaults

10
content/components/libretiny.md
View File

@ -60,12 +60,10 @@ ln882x:
Defaults to the variant that is detected from the board, if a board that's unknown to ESPHome is used,
this option is mandatory. **It's recommended not to include this option**.
{{< note >}}
Support for the LibreTiny platform is still in development and there could be issues or missing components.
Please report any issues on [LibreTiny GitHub](https://github.com/kuba2k2/libretiny).
{{< /note >}}
> [!NOTE]
> Support for the LibreTiny platform is still in development and there could be issues or missing components.
>
> Please report any issues on [LibreTiny GitHub](https://github.com/kuba2k2/libretiny).
## Getting Started

186
content/components/light/_index.md
View File

@ -31,10 +31,9 @@ light:
- **name** (*Optional*, string): The name of the light. At least one of **id** and **name** must be specified.
{{< note >}}
If you have a [friendly_name](#esphome-configuration_variables) set for your device and you want the light
to use that name, you can set `name: None`.
{{< /note >}}
> [!NOTE]
> If you have a [friendly_name](#esphome-configuration_variables) set for your device and you want the light
> to use that name, you can set `name: None`.
- **icon** (*Optional*, icon): Manually set the icon to use for the light in the frontend.
- **effects** (*Optional*, list): A list of [light effects](#light-effects) to use for this light.
@ -177,16 +176,15 @@ on_...:
- **transition_length** (*Optional*, [Time](#config-time), [templatable](#config-templatable)): The length of the
transition if the light supports it.
{{< note >}}
This action can also be expressed in [lambdas](#config-lambda):
> [!NOTE]
> This action can also be expressed in [lambdas](#config-lambda):
>
> ```cpp
> auto call = id(light_1).toggle();
> // perform action:
> call.perform();
> ```
```cpp
auto call = id(light_1).toggle();
// perform action:
call.perform();
```
{{< /note >}}
{{< anchor "light-turn_on_action" >}}
### `light.turn_on` Action
@ -226,50 +224,47 @@ on_...:
- All other options from [light state](#light-state_config).
{{< note >}}
This action can also be expressed in [lambdas](#config-lambda):
> [!NOTE]
> This action can also be expressed in [lambdas](#config-lambda):
>
> ```cpp
> auto call = id(light_1).turn_on();
> // set parameters (optional)
> call.set_transition_length(1000); // in ms
> call.set_brightness(1.0); // 1.0 is full brightness
> call.set_color_mode(ColorMode::RGB_COLD_WARM_WHITE);
> call.set_rgb(0.5, 0.25, 1.0); // color in RGB order, this example is purple
> call.set_cold_white(0.5);
> call.set_warm_white(0.75);
> call.set_effect("The Effect");
> // perform action:
> call.perform();
> ```
>
> Shorter example using auto call, call.set_brightness and call.perform.
>
> ```cpp
> id(light_1).turn_on().set_brightness(1.0).perform();
> ```
```cpp
auto call = id(light_1).turn_on();
// set parameters (optional)
call.set_transition_length(1000); // in ms
call.set_brightness(1.0); // 1.0 is full brightness
call.set_color_mode(ColorMode::RGB_COLD_WARM_WHITE);
call.set_rgb(0.5, 0.25, 1.0); // color in RGB order, this example is purple
call.set_cold_white(0.5);
call.set_warm_white(0.75);
call.set_effect("The Effect");
// perform action:
call.perform();
```
> [!NOTE]
> The `red`, `green` and `blue` values only control the color of the light, not its brightness! If you assign
> `50%` to all RGB channels it will be interpreted as 100% on. Only use `brightness` or `color_brightness` to
> control the brightness of the light.
Shorter example using auto call, call.set_brightness and call.perform.
> [!NOTE]
> The master brightness (`brightness` ) and separate brightness controls for the color and white channels
> (`color_brightness`, `white`, `cold_white` and `warm_white` ) are multiplied together. Thus, this will
> result in color at 40% brightness and white at 60% brightness:
>
> ```yaml
> - light.turn_on:
> id: light_1
> brightness: 80%
> color_brightness: 50%
> white: 75%
> ```
```cpp
id(light_1).turn_on().set_brightness(1.0).perform();
```
{{< /note >}}
{{< note >}}
The `red`, `green` and `blue` values only control the color of the light, not its brightness! If you assign
`50%` to all RGB channels it will be interpreted as 100% on. Only use `brightness` or `color_brightness` to
control the brightness of the light.
{{< /note >}}
{{< note >}}
The master brightness (`brightness` ) and separate brightness controls for the color and white channels
(`color_brightness`, `white`, `cold_white` and `warm_white` ) are multiplied together. Thus, this will
result in color at 40% brightness and white at 60% brightness:
```yaml
- light.turn_on:
id: light_1
brightness: 80%
color_brightness: 50%
white: 75%
```
{{< /note >}}
{{< anchor "light-turn_off_action" >}}
### `light.turn_off` Action
@ -291,18 +286,17 @@ on_...:
- **transition_length** (*Optional*, [Time](#config-time), [templatable](#config-templatable)): The length of the
transition if the light supports it.
{{< note >}}
This action can also be expressed in [lambdas](#config-lambda):
> [!NOTE]
> This action can also be expressed in [lambdas](#config-lambda):
>
> ```cpp
> auto call = id(light_1).turn_off();
> // set parameters (optional)
> call.set_transition_length(1000); // in ms
> // perform action:
> call.perform();
> ```
```cpp
auto call = id(light_1).turn_off();
// set parameters (optional)
call.set_transition_length(1000); // in ms
// perform action:
call.perform();
```
{{< /note >}}
{{< anchor "light-control_action" >}}
### `light.control` Action
@ -358,29 +352,28 @@ on_...:
- `CLAMP` : Clamp the brightness to the limit range.
- `DO_NOTHING` : No dimming if the brightness is outside the limit range.
{{< note >}}
Example: dimming a light with a button press
> [!NOTE]
> Example: dimming a light with a button press
>
> ```yaml
> binary_sensor:
> - platform: gpio
> # ...
> id: my_binary_sensor
> on_press:
> - while:
> condition:
> binary_sensor.is_on: my_binary_sensor
> then:
> - light.dim_relative:
> id: light_1
> relative_brightness: 5%
> transition_length: 0.1s
> brightness_limits:
> max_brightness: 90%
> - delay: 0.1s
> ```
```yaml
binary_sensor:
- platform: gpio
# ...
id: my_binary_sensor
on_press:
- while:
condition:
binary_sensor.is_on: my_binary_sensor
then:
- light.dim_relative:
id: light_1
relative_brightness: 5%
transition_length: 0.1s
brightness_limits:
max_brightness: 90%
- delay: 0.1s
```
{{< /note >}}
{{< anchor "light-addressable_set_action" >}}
### `light.addressable_set` Action
@ -496,11 +489,9 @@ light:
update_interval: 5s
```
{{< note >}}
After setting a light effect, it is possible to reset the in-use effect back to a static light by setting the
`effect` to `none` when it is being called through Home Assistant or directly on the device.
{{< /note >}}
> [!NOTE]
> After setting a light effect, it is possible to reset the in-use effect back to a static light by setting the
> `effect` to `none` when it is being called through Home Assistant or directly on the device.
### Pulse Effect
@ -913,10 +904,8 @@ Available variables in the lambda:
- **initial_run** - A bool which is true on the first execution of the lambda. Useful to reset static variables when
restarting an effect.
{{< note >}}
ESPColor has been migrated to Color. See {{< apistruct "Color" "Color" >}} for more information.
{{< /note >}}
> [!NOTE]
> ESPColor has been migrated to Color. See {{< apistruct "Color" "Color" >}} for more information.
```yaml
light:
@ -1121,10 +1110,9 @@ light:
Sync Groups to listen to. Defaults to `0` (All Sync Groups). Sync Groups 1, 2, 3, 4, 5, 6, 7, 8 use masks 1, 2, 4,
8, 16, 32, 64, 128. Combine mask values to listen to multiple Sync Groups.
{{< note >}}
You can also set the `port` to `19446` for compatibility with Hyperion Classic using a UDP device with protocol 0.
> [!NOTE]
> You can also set the `port` to `19446` for compatibility with Hyperion Classic using a UDP device with protocol 0.
{{< /note >}}
The following realtime protocols are supported:
- WARLS

6
content/components/light/beken_spi_led_strip.md
View File

@ -9,10 +9,8 @@ params:
This is a component using the Beken SPI DMA interface to drive addressable LED strips.
{{< warning >}}
Only works on pin P16, which is not available on many tuya modules.
{{< /warning >}}
> [!WARNING]
> Only works on pin P16, which is not available on many tuya modules.
```yaml
light:

36
content/components/light/fastled.md
View File

@ -7,27 +7,25 @@ params:
image: color_lens.svg
---
{{< warning >}}
FastLED does **not** work as expected with Arduino 3 or newer for ESP8266. For now, you can either downgrade the arduino version or use {{< docref "neopixelbus/" >}}.
> [!WARNING]
> FastLED does **not** work as expected with Arduino 3 or newer for ESP8266. For now, you can either downgrade the arduino version or use {{< docref "neopixelbus/" >}}.
>
> ```yaml
> esp8266:
> framework:
> version: 2.7.4
> ```
>
> See these related issues:
>
> - <https://github.com/FastLED/FastLED/issues/1322>
> - <https://github.com/FastLED/FastLED/issues/1264>
```yaml
esp8266:
framework:
version: 2.7.4
```
> [!WARNING]
> FastLED does **not** work with ESP-IDF.
>
> For addressable lights, you can use {{< docref "esp32_rmt_led_strip/" >}} or for SPI LEDs see {{< docref "spi_led_strip/" >}}..
See these related issues:
- <https://github.com/FastLED/FastLED/issues/1322>
- <https://github.com/FastLED/FastLED/issues/1264>
{{< /warning >}}
{{< warning >}}
FastLED does **not** work with ESP-IDF.
For addressable lights, you can use {{< docref "esp32_rmt_led_strip/" >}} or for SPI LEDs see {{< docref "spi_led_strip/" >}}..
{{< /warning >}}
{{< anchor "fastled-clockless" >}}
## Clockless

6
content/components/light/hbridge.md
View File

@ -36,10 +36,8 @@ control the colors in the [light control actions](#light-turn_on_action), you ne
- **pin_b** (**Required**, [ID](#config-id)): The id of the second float [Output Component](#output) to use for this light.
- All other options from [Light](#config-light).
{{< note >}}
As we are switching the H-bridge in software, the light may glitch every so often when other tasks run on the MCU.
{{< /note >}}
> [!NOTE]
> As we are switching the H-bridge in software, the light may glitch every so often when other tasks run on the MCU.
## See Also

6
content/components/light/lvgl.md
View File

@ -26,10 +26,8 @@ light:
name: LVGL light
```
{{< note >}}
To have linear brightness control, `gamma_correct` of the light is set by default to `0`.
{{< /note >}}
> [!NOTE]
> To have linear brightness control, `gamma_correct` of the light is set by default to `0`.
## See Also

16
content/components/light/neopixelbus.md
View File

@ -7,12 +7,11 @@ params:
image: color_lens.svg
---
{{< warning >}}
NeoPixelBus does **not** work with ESP-IDF.
> [!WARNING]
> NeoPixelBus does **not** work with ESP-IDF.
>
> For clockless lights, you can use {{< docref "esp32_rmt_led_strip/" >}}, and for SPI LEDs see {{< docref "spi_led_strip/" >}}.
For clockless lights, you can use {{< docref "esp32_rmt_led_strip/" >}}, and for SPI LEDs see {{< docref "spi_led_strip/" >}}.
{{< /warning >}}
The `neopixelbus` light platform allows you to create RGB lights
in ESPHome for individually addressable lights like NeoPixel or WS2812.
@ -87,11 +86,10 @@ If you have one line, only specify `pin`, otherwise specify both `clock_pin` and
- All other options from [Light](#config-light).
{{< warning >}}
On ESP8266 it's highly recommended to connect the light strip to pin
GPIO3 to reduce flickering.
> [!WARNING]
> On ESP8266 it's highly recommended to connect the light strip to pin
> GPIO3 to reduce flickering.
{{< /warning >}}
{{< anchor "neopixelbus-methods" >}}
## Methods

14
content/components/light/partition.md
View File

@ -107,14 +107,12 @@ light:
- All other options from [Light](#config-light).
{{< note >}}
Do *not* use this platform to control each LED on your addressable light - the light
objects have a moderate overhead and if you try to create many lights you will run out
of memory quickly.
See [`light.addressable_set` Action](#light-addressable_set_action) for that.
{{< /note >}}
> [!NOTE]
> Do *not* use this platform to control each LED on your addressable light - the light
> objects have a moderate overhead and if you try to create many lights you will run out
> of memory quickly.
>
> See [`light.addressable_set` Action](#light-addressable_set_action) for that.
## See Also

6
content/components/light/rgb.md
View File

@ -47,10 +47,8 @@ output:
# Repeat for green and blue output
```
{{< note >}}
Remember that `gamma_correct` is enabled by default (`γ=2.8` ), and you may want take it into account for the calibration. For instance if you command a light to *50%* brightness and want it to be the new maximum: `max_PWM_power = max_light_power^2.8 = 0.5^2.8 = 0.144`, then you would set `max_power` to *14.4%*.
{{< /note >}}
> [!NOTE]
> Remember that `gamma_correct` is enabled by default (`γ=2.8` ), and you may want take it into account for the calibration. For instance if you command a light to *50%* brightness and want it to be the new maximum: `max_PWM_power = max_light_power^2.8 = 0.5^2.8 = 0.144`, then you would set `max_power` to *14.4%*.
## Configuration variables

Some files were not shown because too many files have changed in this diff Show More