View Changelog
diff --git a/changelog/2023.12.0.rst b/changelog/2023.12.0.rst
index 58ff62091..499288e89 100644
--- a/changelog/2023.12.0.rst
+++ b/changelog/2023.12.0.rst
@@ -14,7 +14,7 @@ ESPHome 2023.12.0 - 20th December 2023
GT911, components/touchscreen/gt911, esp32_s3_box_3.png
Pylontech Batteries, components/pylontech, pylontech.jpg
HE60R Cover, components/cover/he60r, he60r.jpg
- Graphical Display Menu, components/display_menu/graphical_display_menu, graphical_display_menu.jpg
+ Graphical Display Menu, components/display_menu/graphical_display_menu, graphical_display_menu.png
FT63X6, components/touchscreen/ft63x6, wt32-sc01.png
A02YYUW, components/sensor/a02yyuw, a02yyuw.jpg
PN7150, components/binary_sensor/pn7150, pn7150.jpg
diff --git a/changelog/2024.2.0.rst b/changelog/2024.2.0.rst
index 661920c98..08dc4c488 100644
--- a/changelog/2024.2.0.rst
+++ b/changelog/2024.2.0.rst
@@ -66,6 +66,14 @@ Release 2024.2.1 - February 26
- fix throttle average nan handling :esphomepr:`6275` by :ghuser:`ssieb`
- Fix thermostat supplemental actions :esphomepr:`6282` by :ghuser:`kbx81`
+Release 2024.2.2 - March 6
+--------------------------
+
+- CSE7766: Fix energy calculation :esphomepr:`6286` by :ghuser:`puuu`
+- handling with the negative temperature in the sensor tmp102 :esphomepr:`6316` by :ghuser:`FlyingFeng2021`
+- fix tmp102 negative calculation :esphomepr:`6320` by :ghuser:`ssieb`
+- auto load output for now :esphomepr:`6309` by :ghuser:`ssieb`
+- Add wake word phrase to voice assistant start command :esphomepr:`6290` by :ghuser:`jesserockz`
Full list of changes
--------------------
diff --git a/changelog/2024.3.0.rst b/changelog/2024.3.0.rst
new file mode 100644
index 000000000..570b004a4
--- /dev/null
+++ b/changelog/2024.3.0.rst
@@ -0,0 +1,311 @@
+ESPHome 2024.3.0 - 20th March 2024
+==================================
+
+.. seo::
+ :description: Changelog for ESPHome 2024.3.0.
+ :image: /_static/changelog-2024.3.0.png
+ :author: Jesse Hills
+ :author_twitter: @jesserockz
+
+.. imgtable::
+ :columns: 5
+
+ Datetime Core, components/datetime/index, clock-outline.svg, dark-invert
+ Template Datetime, components/datetime/template, description.svg, dark-invert
+
+ AM2315C, components/sensor/am2315c, am2315c.jpg
+ HTU31D, components/sensor/htu31d, htu31d.jpg,
+ MS8607, components/sensor/ms8607, ms8607.jpg
+
+ AGS10, components/sensor/ags10, ags10.jpg
+ VEML6030, components/sensor/veml7700, veml6030.jpg
+ VEML7700, components/sensor/veml7700, veml7700.jpg
+
+ MR24HPC1 mmWave, components/seeed_mr24hpc1, seeed-mr24hpc1.jpg
+
+ ADS1118, components/sensor/ads1118, ads1118.jpg
+
+ CST816, components/touchscreen/cst816, cst816.jpg
+ CST226, components/touchscreen/cst226, t4-s3.jpg
+
+ RPI_DPI_RGB, components/display/rpi_dpi_rgb, waveshare_touch-s3.jpg
+ Quad SPI AMOLED, components/display/qspi_amoled, t4-s3.jpg
+ ST7701S, components/display/st7701s, indicator.jpg
+
+ ADE7880, components/sensor/ade7880, ade7880.svg
+ Emmeti, components/climate/climate_ir, air-conditioner-ir.svg, dark-invert
+ Uponor Smatrix, components/uponor_smatrix, uponor.svg
+ Kamstrup KMP, components/sensor/kamstrup_kmp, kamstrup_kmp.jpg
+ Template Fan, components/fan/template, description.svg, dark-invert
+
+
+Dates
+-----
+
+ESPHome now has support for ``date`` entities that can be set from the frontend (like Home Assistant) for you to check against and execute
+automations in the future.
+
+ESPHome Dates require Home Assistant 2024.4 or later.
+
+
+IPv6
+----
+
+ESPHome is now prepared for the future! The future that is the old IPv6 that is.
+Dualstack is added and it could now have up to 5 ip addresses of any type, and communication with Home assistant,
+MQTT and NTP works with IPv6. ESPHome still depends on IPv4, but the crystal ball shows sign of IPv6-only networks.
+
+If you are building an :doc:`/components/external_components` or you use
+``network::get_ip_address()``, ``wifi::global_wifi_component->get_ip_address()`` or ``ethernet::global_eth_component->get_ip_address()``,
+these functions have been renamed to ``::get_ip_addresses()`` respectively and now return a list of all IP addresses.
+
+
+Release 2024.3.1 - March 27
+---------------------------
+
+- AHT10: Fix bug :esphomepr:`6409` by :ghuser:`clydebarrow`
+- microWakeWord: Fix model path joining :esphomepr:`6426` by :ghuser:`ebw44`
+- Don't compile strptime unless its required :esphomepr:`6424` by :ghuser:`gabest11`
+- Fix editor live validation :esphomepr:`6431` by :ghuser:`bdraco`
+
+Release 2024.3.2 - April 4
+--------------------------
+
+- Fix logger compile error on ESP32-C6 :esphomepr:`6323` by :ghuser:`DAVe3283`
+- Add missing ethernet types :esphomepr:`6444` by :ghuser:`ssieb`
+- fix: changing the content source when playing is paused blocks the player :esphomepr:`6454` by :ghuser:`NewoPL`
+
+Thank you for your support
+--------------------------
+
+We would like to thank all Home Assistant Cloud subscribers for their support. It allows `Nabu Casa ` - Experiencing problems flashing esphomelib firmwares using esphomeyaml?
+* ``esphomeflasher`` - Experiencing problems flashing esphomelib firmwares using esphomeyaml?
No problem, esphomeflasher is a tool designed to make that super easy. Just let esphomeyaml generate the binary and flash
from your PC.
* :doc:`Over-the-Air Updates ` have been completely re-written to make them a lot more
@@ -76,7 +76,7 @@ New Features
- esphomelib now has a new tool: `esphomeflasher `__ to simplify
flashing on Windows/MacOS machines **without having to install esphomeyaml**. So if esphomeyaml for some reason
- can't find your USB port, you now can use the esphomeflasher app. See :ref:`esphome-flasher`.
+ can't find your USB port, you now can use the esphomeflasher app. See ``esphomeflasher``.
- ESP8266s now save the states of lights/switches/... internally and restores them on boot.
Additionally, esphomelib can now operate in fully offline mode if your WiFi network goes down
diff --git a/components/alarm_control_panel/template.rst b/components/alarm_control_panel/template.rst
index 91796ff95..35f80ad5c 100644
--- a/components/alarm_control_panel/template.rst
+++ b/components/alarm_control_panel/template.rst
@@ -27,8 +27,8 @@ Configuration variables:
- **codes** (*Optional*, list of string): A list of codes for disarming the alarm, if *requires_code_to_arm* set to true then for arming the alarm too.
- **requires_code_to_arm** (*Optional*, boolean): Code required for arming the alarm, *codes* must be provided.
- **arming_away_time** (*Optional*, :ref:`config-time`): The exit delay before the alarm is armed to away mode. Defaults to ``0s``.
-- **arming_home_time** (*Optional*, :ref:`config-time`): The exit delay before the alarm is armed to home mode.
-- **arming_night_time** (*Optional*, :ref:`config-time`): The exit delay before the alarm is armed to night mode.
+- **arming_home_time** (*Optional*, :ref:`config-time`): The exit delay before the alarm is armed to home mode.
+- **arming_night_time** (*Optional*, :ref:`config-time`): The exit delay before the alarm is armed to night mode.
- **pending_time** (*Optional*, :ref:`config-time`): The entry delay before the alarm is triggered. Defaults to ``0s``.
- **trigger_time** (*Optional*, :ref:`config-time`): The time after a triggered alarm before resetting to previous state if the sensors are cleared/off. Defaults to ``0s``.
- **binary_sensors** (*Optional*, *list*): A list of binary sensors the panel should use. Each consists of:
@@ -169,7 +169,7 @@ Example:
name: Zone 1
device_class: door
pin:
- number: D1
+ number: GPIOXX
mode: INPUT_PULLUP
inverted: True
- platform: gpio
@@ -177,7 +177,7 @@ Example:
name: Zone 2
device_class: door
pin:
- number: D2
+ number: GPIOXX
mode: INPUT_PULLUP
inverted: True
- platform: gpio
@@ -185,7 +185,7 @@ Example:
name: Zone 3
device_class: motion
pin:
- number: D3
+ number: GPIOXX
mode: INPUT_PULLUP
inverted: True
- platform: gpio
@@ -193,7 +193,7 @@ Example:
name: Zone 4
device_class: door
pin:
- number: D4
+ number: GPIOXX
mode: INPUT_PULLUP
inverted: True
- platform: homeassistant
@@ -206,7 +206,7 @@ Example:
id: siren
name: Siren
icon: mdi:alarm-bell
- pin: D7
+ pin: GPIOXX
See Also
diff --git a/components/api.rst b/components/api.rst
index cb1a48116..a6386a845 100644
--- a/components/api.rst
+++ b/components/api.rst
@@ -75,20 +75,35 @@ Configuration variables:
.. _api-actions:
-.. note::
-
- Before a newly added ESPHome device can interact with the Home Assistant API it needs to be allowed to communicate
- with it. This setting can be found in the ESPHome integration (NOT in the Add-On) by clicking "CONFIGURE" for
- that device and enabling the "Allow device to make service calls" option.
-
Actions
-------
+Before using any of the actions below, you'll need to tell Home Assistant to allow your device to
+make service calls.
+
+Open the ESPHome integration page on your Home Assistant instance:
+
+.. raw:: html
+
+ 
+
+Then:
+
+#. Fnd your device in the device list
+#. Click the "configure" button next to it
+#. Check the "Allow the device to make Home Assistant service calls" box
+#. Then click "submit".
+
.. _api-homeassistant_event_action:
``homeassistant.event`` Action
******************************
+.. note::
+
+ Be sure to :ref:`follow the instructions above ` to tell Home Assistant to allow
+ your device to make service calls.
+
When using the native API with Home Assistant, you can create events in the Home Assistant event bus
straight from ESPHome :ref:`Automations `.
@@ -117,6 +132,11 @@ Configuration variables:
``homeassistant.service`` Action
********************************
+.. note::
+
+ Be sure to :ref:`follow the instructions above ` to tell Home Assistant to allow
+ your device to make service calls.
+
When using the native API with Home Assistant, you can create Home Assistant service
calls straight from ESPHome :ref:`Automations `.
@@ -189,6 +209,11 @@ Then, in ESPHome:
``homeassistant.tag_scanned`` Action
************************************
+.. note::
+
+ Be sure to :ref:`follow the instructions above ` to tell Home Assistant to allow
+ your device to make service calls.
+
When using the native API with Home Assistant, you can push tag_scanned to Home Assistant
straight from ESPHome :ref:`Automations `.
diff --git a/components/at581x.rst b/components/at581x.rst
new file mode 100644
index 000000000..9513112a2
--- /dev/null
+++ b/components/at581x.rst
@@ -0,0 +1,183 @@
+AirTouch AT581x Radar
+=====================
+
+.. seo::
+ :description: Instructions for setting up AirTouch AT581x Radar
+ :image: at581x.png
+ :keywords: radar
+
+The `AirTouch AT581x radar `__
+(aka ``AT581x``) is a familly of 5.8GHz radar which can be used for human presence detection. It can detect tiny movements
+and compared to a PIR sensor **it can detect presence continuously**. This can be useful, for example, to turn
+the lights on when you enter a room, keep them on as long as you are there (without waving your hands at the
+sensor) and turn them off almost immediately after you leave the room.
+
+They are ultra-low power (as low as 40µA of current consumption) and are extremely simple to use, yet can be setup by I2C.
+It's installed in many low cost appliance, like the ESP32S3-BOX-3, and can be found by many different manufacturer or reference,
+like the MoreSense MS58-3909S68U4.
+
+It is possible to use this sensor with only a single GPIO pin; however, if you wish to change its settings,
+a :doc:`/components/i2c` component (and its requisite GPIO pins) is required in your device's configuration.
+
+.. figure:: ../images/at581x.png
+ :align: center
+ :width: 75%
+
+ AirTouch AT581x Radar / presence detection sensor
+
+.. code-block:: yaml
+
+ # Example configuration entry
+ at581x:
+ id: "Radar"
+ i2c_id: bus_a
+
+.. _at581x-component:
+
+Component/Hub
+-------------
+
+You need to have the hub component (``at581x:`` entry) defined to be able to change the sensor's
+settings, get it listed as an motion entity or being able to turn on/off the radio frequency emmission.
+A :doc:`/components/binary_sensor/gpio` alone could be sufficient if you only want
+to determine presence/occupancy. When you define ``at581x:`` you'll need to have a ``i2c:`` entry in
+your configuration with both the SDA and SCL pins defined.
+
+Multiple instances of this component may be defined if multiple :doc:`/components/i2c` components are available:
+
+.. code-block:: yaml
+
+ at581x:
+ - id: mmWave_1
+ i2c_id: bus_a
+ address: 0x28
+ - id: mmWave_2
+ i2c_id: bus_a
+ address: 0x29
+ ...
+
+Configuration variables:
+************************
+
+- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. Necessary if you want
+ to define multiple instances of this component.
+- **i2c_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :doc:`/components/i2c` if you want
+ to use multiple I2C buses.
+
+.. _at581x-binary_sensor:
+
+Binary Sensor
+-------------
+
+The state of the radar detection is available via its GPIO pin. It's required to use a GPIO binary sensor to monitor the motion status
+
+.. code-block:: yaml
+
+ binary_sensor:
+ - platform: gpio
+ name: "Human in front"
+ pin: GPIOXX
+
+Configuration variables:
+************************
+
+- Refer to other options from :ref:`Binary Sensor ` and :doc:`GPIO Binary Sensor `.
+
+.. _at581x-switch:
+
+Switch
+------
+
+:ref:`Switch components ` are used to enable/disable radio frequency hardware.
+
+.. code-block:: yaml
+
+ switch:
+ - platform: at581x
+ at581x_id: Radar
+ name: "Enable Radar"
+
+Configuration variables:
+************************
+
+- **at581x_id** (*Optional*, :ref:`config-id`): The ID of the AT581x component defined above.
+ Required when multiple instances of the ``at581x`` component are defined.
+- All other options from :ref:`Switch `.
+
+.. _at581x-actions:
+
+Actions
+-------
+
+.. _at581x-action_settings:
+
+``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.
+
+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.
+
+The settings action allows changing of any number of the radar's internal parameters/settings. With this
+action, any unspecified parameters will remain unchanged.
+
+.. code-block:: yaml
+
+ on_...:
+ - at581x.settings:
+ id: "Waveradar"
+ hw_frontend_reset: false
+ frequency: 5800MHz
+ sensing_distance: 200 # 0-1023
+ poweron_selfcheck_time: 2000ms
+ protect_time: 1s
+ trigger_base: 500ms
+ trigger_keep: 10s
+ stage_gain: 3 # 0-12 the higher the value the smaller the gain
+ power_consumption: 70µA
+
+
+Configuration variables:
+````````````````````````
+
+- **id** (*Optional*, :ref:`config-id`): Manually specify the ID of the sensor on which settings should be
+ changed. If only one radar is defined, this is optional.
+- **hw_frontend_reset** (*Optional*, boolean): If set to true, a reset of the analog frontend will be performed before
+ changing other options. Ignored if not set or set to ``false``. Upon applying the settings a frontend reset
+ will be performed anyway, this is only useful if the sensor is not answering or locked up.
+- **frequency** (*Optional*, int): Any of the possible frequencies (5696, 5715, 5730, 5748, 5765, 5784, 5800, 5819, 5836, 5851, 5869, 5888) in MHz.
+- **sensing_distance** (*Optional*, int): A unitless number, in range 0-1023, specifying the maximum distance to detect motion
+- **poweron_selfcheck_time** (*Optional*, int): The delay to perform self check and calibration on power on. Recommanded not to change this
+- **protect_time** (*Optional*, int): The delay after an end-of-trigger event where the detection will not trigger anymore. Max 65535ms
+- **trigger_base** (*Optional*, int): The delay while a detection must be active to change the state of the sensor. Max 65535ms
+- **trigger_keep** (*Optional*, int): The delay that the output will stay high after a detection event. This is usually what you want to change.
+- **stage_gain** (*Optional*, int): The analog gain to use for threshold test. Any value in range 0-12, with 12 being the lowest gain and 0 the highest
+- **power_consumption** (*Optional*, int): Any of the possible power profile (48, 56, 63, 70, 77, 91, 105, 115, 40, 44, 47, 51, 54, 61, 68, 78) in µA
+
+
+``at581x.reset`` Action
+***********************
+
+Restart the sensor.
+
+.. code-block:: yaml
+
+ on_...:
+ at581x.reset:
+
+Configuration variables:
+````````````````````````
+
+- **id** (*Optional*, :ref:`config-id`): Manually specify the ID of the AT581x component. Useful when multiple instances of this component are defined.
+
+See Also
+--------
+- :ref:`I2C bus `
+- :ref:`Binary Sensor `
+- :doc:`GPIO Binary Sensor `
+- :ref:`config-id`
+- :ghedit:`Edit`
diff --git a/components/binary_sensor/cap1188.rst b/components/binary_sensor/cap1188.rst
index 0cc7a5113..016720311 100644
--- a/components/binary_sensor/cap1188.rst
+++ b/components/binary_sensor/cap1188.rst
@@ -30,7 +30,7 @@ required to be set up in your configuration for this sensor to work.
cap1188:
id: cap1188_component
address: 0x29
- reset_pin: 14
+ reset_pin: GPIOXX
touch_threshold: 0x40
allow_multiple_touches: true
diff --git a/components/binary_sensor/custom.rst b/components/binary_sensor/custom.rst
index d2ee55fdc..f983584cb 100644
--- a/components/binary_sensor/custom.rst
+++ b/components/binary_sensor/custom.rst
@@ -1,22 +1,28 @@
Custom Binary Sensor
====================
+.. seo::
+ :description: Instructions for setting up Custom C++ binary sensors with ESPHome.
+ :image: language-cpp.svg
+ :keywords: C++, Custom
+
.. warning::
- Custom components are deprecated, not recommended for new configurations
- and will be removed from ESPHome in a future release.
- Please look at creating a real ESPHome component and "importing" it into your
- configuration with :doc:`/components/external_components`.
+ Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
+ future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
+ :doc:`/components/external_components`.
- You can find some basic documentation on creating your own components
- at :ref:`contributing_to_esphome`.
+ You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
-This integration can be used to create custom binary sensors in ESPHome
-using the C++ (Arduino) API.
+.. warning::
-Please first read :doc:`/components/sensor/custom` guide,
-the same principles apply here and binary sensors are very similar
-to sensors internally.
+ While we try to keep the ESPHome YAML configuration options as stable as possible, the ESPHome API is less
+ stable. If something in the APIs needs to be changed in order for something else to work, we will do so.
+
+This component can be used to create custom binary sensors in ESPHome using the C++ (Arduino) API.
+
+Please first read :doc:`/components/sensor/custom` guide, the same principles apply here and binary
+sensors are very similar to sensors internally.
The example below is an example of a custom binary sensor; this custom sensor is essentially the
same as the gpio binary sensor.
diff --git a/components/binary_sensor/esp32_touch.rst b/components/binary_sensor/esp32_touch.rst
index e5bbcd2ed..7c6bc25f3 100644
--- a/components/binary_sensor/esp32_touch.rst
+++ b/components/binary_sensor/esp32_touch.rst
@@ -130,8 +130,8 @@ an ``OFF`` state.
binary_sensor:
- platform: esp32_touch
- name: "ESP32 Touch Pad GPIO27"
- pin: GPIO27
+ name: "ESP32 Touch Pad"
+ pin: GPIOXX
threshold: 1000
Configuration variables:
@@ -149,6 +149,35 @@ Configuration variables:
wake-up from a touch event. Note that no filter(s) is/are active during deep sleep.
- All other options from :ref:`Binary Sensor `.
+
+Raw Values
+----------
+
+If access to the raw values is required, a template sensor can be created that polls for them:
+
+.. code-block:: yaml
+
+ # Example configuration entry for accessing raw values
+ esp32_touch:
+ id: esp32_touch_1
+
+ binary_sensor:
+ - platform: esp32_touch
+ id: esp32_touch_pad
+ pin: GPIOXX
+ threshold: 0
+
+ sensor:
+ - platform: template
+ name: "Raw touch value"
+ lambda: |-
+ return id(esp32_touch_pad).get_value();
+ update_interval: 3s
+
+One example of use is a wide area pressure sensor that integrates a number of smaller sensors in an area. Make two strips
+of aluminium foil that sandwich paper, and connect one wire to a touch pin and the other to ground. Set up several sensors
+under a flexible object like a plastic mat, add the raw values, and apply a threshold.
+
.. _esp32-touch-pad-pins:
Touch Pad Pins
diff --git a/components/binary_sensor/haier.rst b/components/binary_sensor/haier.rst
index 29e5445f5..69a581bde 100644
--- a/components/binary_sensor/haier.rst
+++ b/components/binary_sensor/haier.rst
@@ -17,17 +17,17 @@ Additional sensors for Haier Climate device. **These sensors are supported only
# Example configuration entry
uart:
baud_rate: 9600
- tx_pin: 17
- rx_pin: 16
+ tx_pin: GPIOXX
+ rx_pin: GPIOXX
id: ac_port
-
+
climate:
- platform: haier
id: haier_ac
protocol: hOn
name: Haier AC
uart_id: ac_port
-
+
binary_sensor:
- platform: haier
haier_id: haier_ac
@@ -56,9 +56,9 @@ Configuration variables:
All options from :ref:`Binary Sensor `.
- **indoor_electric_heating_status** (*Optional*): A binary sensor that indicates electrical heating system activity.
All options from :ref:`Binary Sensor `.
-- **indoor_fan_status** (*Optional*): A binary sensor that indicates indoor fan activity.
+- **indoor_fan_status** (*Optional*): A binary sensor that indicates indoor fan activity.
All options from :ref:`Binary Sensor `.
-- **outdoor_fan_status** (*Optional*): A binary sensor that indicates outdoor fan activity.
+- **outdoor_fan_status** (*Optional*): A binary sensor that indicates outdoor fan activity.
All options from :ref:`Binary Sensor `.
See Also
diff --git a/components/binary_sensor/homeassistant.rst b/components/binary_sensor/homeassistant.rst
index f98924abd..2628c5d58 100644
--- a/components/binary_sensor/homeassistant.rst
+++ b/components/binary_sensor/homeassistant.rst
@@ -34,7 +34,6 @@ Configuration variables:
- **entity_id** (**Required**, string): The entity ID to import from Home Assistant.
- **attribute** (*Optional*, string): The name of the state attribute to import from the
specified entity. The entity state is used when this option is omitted.
- Requires Home Assistant 2021.6 or newer.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- All other options from :ref:`Binary Sensor `.
diff --git a/components/binary_sensor/hydreon_rgxx.rst b/components/binary_sensor/hydreon_rgxx.rst
index 844b9a0ca..47a5b7dba 100644
--- a/components/binary_sensor/hydreon_rgxx.rst
+++ b/components/binary_sensor/hydreon_rgxx.rst
@@ -12,12 +12,6 @@ For this sensor to work, a :doc:`/components/sensor/hydreon_rgxx` must be set up
.. code-block:: yaml
# Example RG-9 entry
-
- uart:
- rx_pin: GPIO16
- tx_pin: GPIO17
- baud_rate: 9600
-
sensor:
- platform: hydreon_rgxx
model: "RG_9"
diff --git a/components/binary_sensor/images/haier-climate.jpg b/components/binary_sensor/images/haier-climate.jpg
index 81c68df78..a6b738a98 100644
Binary files a/components/binary_sensor/images/haier-climate.jpg and b/components/binary_sensor/images/haier-climate.jpg differ
diff --git a/components/binary_sensor/index.rst b/components/binary_sensor/index.rst
index 0573e2f42..7cab5120d 100644
--- a/components/binary_sensor/index.rst
+++ b/components/binary_sensor/index.rst
@@ -66,12 +66,12 @@ Advanced options:
a ``name`` will implicitly set this to true.
- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
(usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
- Requires Home Assistant 2021.9 or newer. Defaults to ``false``.
+ Defaults to ``false``.
- **publish_initial_state** (*Optional*, boolean): If true, then the sensor will publish its initial state at boot or when
HA first connects, depending on the platform. This means that any applicable triggers will be run. Defaults to ``false``.
- **entity_category** (*Optional*, string): The category of the entity.
See https://developers.home-assistant.io/docs/core/entity/#generic-properties
- for a list of available options. Requires Home Assistant 2021.11 or newer.
+ for a list of available options.
Set to ``""`` to remove the default entity category.
- If MQTT enabled, all other options from :ref:`MQTT Component `.
diff --git a/components/binary_sensor/rc522.rst b/components/binary_sensor/rc522.rst
index 48e60e643..1c89732b1 100644
--- a/components/binary_sensor/rc522.rst
+++ b/components/binary_sensor/rc522.rst
@@ -42,7 +42,7 @@ you can then create individual binary sensors that track if an NFC/RFID tag is c
spi:
rc522_spi:
- cs_pin: GPIO15
+ cs_pin: GPIOXX
binary_sensor:
- platform: rc522
diff --git a/components/bluetooth_proxy.rst b/components/bluetooth_proxy.rst
index b976d10be..10c38bb32 100644
--- a/components/bluetooth_proxy.rst
+++ b/components/bluetooth_proxy.rst
@@ -32,7 +32,7 @@ our `Bluetooth Proxy installer ` | ``daikin_arc`` | yes |
++---------------------------------------+---------------------+----------------------+
| :ref:`Daikin BRC` | ``daikin_brc`` | yes |
+---------------------------------------+---------------------+----------------------+
| :ref:`Delonghi` | ``delonghi`` | yes |
+---------------------------------------+---------------------+----------------------+
+| Emmeti | ``emmeti`` | yes |
++---------------------------------------+---------------------+----------------------+
| Fujitsu General | ``fujitsu_general`` | yes |
+---------------------------------------+---------------------+----------------------+
| :ref:`GREE` | ``gree`` | |
@@ -72,7 +76,7 @@ controller unit.
# Example configuration entry
remote_transmitter:
- pin: GPIO32
+ pin: GPIOXX
carrier_duty_percent: 50%
climate:
@@ -152,7 +156,7 @@ IR receiver.
remote_receiver:
id: rcvr
pin:
- number: GPIO14
+ number: GPIOXX
inverted: true
mode:
input: true
@@ -220,6 +224,21 @@ Configuration variables:
header_high: 3265us # AC Units from LG in Brazil, for example use these timings
header_low: 9856us
+.. _daikin_arc:
+
+``daikin_arc`` Climate
+-------------------------
+
+The Daikin ARC remotes are used by the japanese model of Daikin.
+
+.. code-block:: yaml
+
+ # Example configuration entry
+ climate:
+ - platform: daikin_arc
+ name: "AC"
+ sensor: room_temperature
+
.. _daikin_brc:
``daikin_brc`` Climate
@@ -264,8 +283,8 @@ Configuration variables:
- **set_fan_mode** (*Optional*, string): Select the fan modes desired or that are supported on your remote. Defaults to ``3levels``
- - Options are: ``3levels`` , ``4levels``, ``quiet_4levels``.
-
+ - Options are: ``3levels`` , ``4levels``, ``quiet_4levels``.
+
- ``3levels``; Low [fan speed 1], Medium [2], High [3]
- ``4levels``; Low [1], Middle [2], Medium [3], High [4]
- ``quiet_4levels``; Low [1], Middle [2], Medium [3], High [4], Quiet [5]
@@ -273,10 +292,10 @@ Configuration variables:
- **supports_dry** (*Optional*, boolean): Enables setting dry mode for this unit. Defaults to ``false``.
- **supports_fan_only** (*Optional*, boolean): Enables setting fan only mode for this unit. Confirm that mode is supported on your remote. Defaults to ``false``.
-- **horizontal_default** (*Optional*, string): What to default to when the AC unit's horizontal direction is *not* set to swing. Defaults to ``middle``.
+- **horizontal_default** (*Optional*, string): What to default to when the AC unit's horizontal direction is *not* set to swing. Defaults to ``middle``.
- Options are: ``left``, ``middle-left``, ``middle``, ``middle-right``, ``right``, ``auto``
-- **vertical_default** (*Optional*, string): What to default to when the AC unit's vertical direction is *not* set to swing. Defaults to ``middle``.
+- **vertical_default** (*Optional*, string): What to default to when the AC unit's vertical direction is *not* set to swing. Defaults to ``middle``.
- Options are: ``down``, ``middle-down``, ``middle``, ``middle-up``, ``up``, ``auto``
@@ -404,8 +423,8 @@ Configuration variables:
``zhlt01`` Climate
---------------------
-ZH/LT-01 is a remote control that is used with many locally branded split airconditioners.
-Supported brands include:
+ZH/LT-01 is a remote control that is used with many locally branded split airconditioners.
+Supported brands include:
- Eurom
- Chigo
diff --git a/components/climate/custom.rst b/components/climate/custom.rst
index e4d86f19e..1544fa9f1 100644
--- a/components/climate/custom.rst
+++ b/components/climate/custom.rst
@@ -1,21 +1,27 @@
Custom Climate
==============
+.. seo::
+ :description: Instructions for setting up Custom C++ climate components with ESPHome.
+ :image: language-cpp.svg
+ :keywords: C++, Custom
+
.. warning::
- Custom components are deprecated, not recommended for new configurations
- and will be removed from ESPHome in a future release.
- Please look at creating a real ESPHome component and "importing" it into your
- configuration with :doc:`/components/external_components`.
+ Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
+ future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
+ :doc:`/components/external_components`.
- You can find some basic documentation on creating your own components
- at :ref:`contributing_to_esphome`.
+ You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
-This integration can be used to create custom climate devices in ESPHome
-using the C++ (Arduino) API.
+.. warning::
-Please first read :doc:`/components/sensor/custom` guide,
-the same principles apply here.
+ While we try to keep the ESPHome YAML configuration options as stable as possible, the ESPHome API is less
+ stable. If something in the APIs needs to be changed in order for something else to work, we will do so.
+
+This component can be used to create custom climate devices in ESPHome using the C++ (Arduino) API.
+
+Please first read :doc:`/components/sensor/custom` guide, the same principles apply here.
The example below is an example of a custom climate device - all climate devices must override
two methods (:apiclass:`Climate `):
diff --git a/components/climate/haier.rst b/components/climate/haier.rst
index caf04d18e..843ecfa0b 100644
--- a/components/climate/haier.rst
+++ b/components/climate/haier.rst
@@ -58,18 +58,11 @@ This component requires a :ref:`uart` to be setup.
.. code-block:: yaml
# Example configuration entry
-
- uart:
- baud_rate: 9600
- tx_pin: 17
- rx_pin: 16
- id: ac_port
-
climate:
- platform: haier
id: haier_ac
protocol: hOn
- name: Haier AC
+ name: Haier AC
uart_id: ac_port
wifi_signal: true
beeper: true
diff --git a/components/climate/index.rst b/components/climate/index.rst
index dde76b23b..263913e73 100644
--- a/components/climate/index.rst
+++ b/components/climate/index.rst
@@ -80,10 +80,10 @@ Advanced options:
a ``name`` will implicitly set this to true.
- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
(usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
- Requires Home Assistant 2021.9 or newer. Defaults to ``false``.
+ Defaults to ``false``.
- **entity_category** (*Optional*, string): The category of the entity.
See https://developers.home-assistant.io/docs/core/entity/#generic-properties
- for a list of available options. Requires Home Assistant 2021.11 or newer.
+ for a list of available options.
Set to ``""`` to remove the default entity category.
MQTT options:
diff --git a/components/climate/midea.rst b/components/climate/midea.rst
index fc560077e..cec59359c 100644
--- a/components/climate/midea.rst
+++ b/components/climate/midea.rst
@@ -25,17 +25,6 @@ The ``midea`` component creates a Midea air conditioner climate device.
.. code-block:: yaml
# Example configuration entry
-
- # Disable logging over UART (required)
- logger:
- baud_rate: 0
-
- # UART settings for Midea dongle (required)
- uart:
- tx_pin: 1 # hardware dependant
- rx_pin: 3 # hardware dependant
- baud_rate: 9600
-
# Main settings
climate:
- platform: midea
diff --git a/components/climate/tuya.rst b/components/climate/tuya.rst
index fe48beb1b..1879bc2a3 100644
--- a/components/climate/tuya.rst
+++ b/components/climate/tuya.rst
@@ -39,8 +39,10 @@ Based on this, you can create the climate device as follows:
switch_datapoint: 1
target_temperature_datapoint: 3
current_temperature_datapoint: 4
- eco_datapoint: 7
- eco_temperature: 20 °C
+ preset:
+ eco:
+ datapoint: 8
+ temperature: 28
Configuration variables:
------------------------
@@ -50,22 +52,46 @@ Configuration variables:
- **supports_heat** (*Optional*, boolean): Specifies if the device has a heating mode. Defaults to ``true``.
- **supports_cool** (*Optional*, boolean): Specifies if the device has a cooling mode. Defaults to ``false``.
- **switch_datapoint** (**Required**, int): The datapoint id number of the climate switch (device on/off).
-- **active_state_datapoint** (*Optional*, int): The datapoint id number of the active state - :ref:`see below `.
-- **active_state_heating_value** (*Optional*, int): The active state datapoint value the device reports when heating. Defaults to ``1`` - :ref:`see below `.
-- **active_state_cooling_value** (*Optional*, int): The active state datapoint value the device reports when cooling - :ref:`see below `.
+- **active_state** (*Optional*): Configuration for the Active State Configuration.
+
+ - **datapoint** (**Required**, int): The datapoint id number of the active state - :ref:`see below `.
+ - **heating_value** (*Optional*, int): The active state datapoint value the device reports when heating. Defaults to ``1`` - :ref:`see below `.
+ - **cooling_value** (*Optional*, int): The active state datapoint value the device reports when cooling - :ref:`see below `.
+ - **drying_value** (*Optional*, int): The active state datapoint value the device reports when in drying mode.
+ - **fanonly_value** (*Optional*, int): The active state datapoint value the device reports when in Fan Only mode.
+- **preset** (*Optional*): Configuration for presets.
+
+ - **eco** (*Optional*): Configuration for Eco preset.
+
+ - **datapoint** (**Required**, int): The datapoint id number of the Eco action.
+ - **temperature** (*Optional*, int): Temperature setpoint for Eco preset.
+ - **sleep** (*Optional*): Configuration for Sleep preset
+
+ - **datapoint** (**Required**, int): The Datapoint id number of the Sleep Action
+- **swing_mode** (*Optional*): Configuration for the swing (oscillation) modes.
+
+ - **vertical_datapoint** (*Optional*, int): The datapoint id number of the vertical swing action.
+ - **horizontal_datapoint** (*Optional*, int): The datapoint id number of the horizontal swing action.
+- **fan_mode** (*Optional*): Configuration for fan modes/fan speeds.
+
+ - **datapoint** (**Required**, int): The datapoint id number of the Fan value state.
+ - **auto_value** (*Optional*, int): The datapoint value the device reports when the fan is on ``auto`` speed.
+ - **low_value** (*Optional*, int): The datapoint value the device reports when the fan is on ``low`` speed.
+ - **medium_value** (*Optional*, int): The datapoint value the device reports when the fan is on ``medium`` speed.
+ - **middle_value** (*Optional*, int): The datapoint value the device reports when the fan is on ``middle`` speed. (May set to device's ``high`` value if you have a ``Turbo`` option).
+ - **high_value** (*Optional*, int): The datapoint value the device reports when the fan is on ``high`` speed. (Sometimes called ``Turbo``).
- **heating_state_pin** (*Optional*, :ref:`config-pin`): The input pin indicating that the device is heating - :ref:`see below `. Only used if **active_state_datapoint** is not configured.
- **cooling_state_pin** (*Optional*, :ref:`config-pin`): The input pin indicating that the device is cooling - :ref:`see below `. Only used if **active_state_datapoint** is not configured.
- **target_temperature_datapoint** (**Required**, int): The datapoint id number of the target temperature.
- **current_temperature_datapoint** (**Required**, int): The datapoint id number of the current temperature.
- **temperature_multiplier** (*Optional*, float): A multiplier to modify the incoming and outgoing temperature values - :ref:`see below `.
-- **eco_datapoint** (*Optional*, int): The datapoint id number of the eco mode state.
-- **eco_temperature** (*Optional*, float): The target temperature the controller uses while the eco mode is active.
+
- **reports_fahrenheit** (*Optional*, boolean): Set to ``true`` if the device reports temperatures in Fahrenheit. ESPHome expects all climate temperatures to be in Celcius, otherwise unexpected conversions will take place when it is published to Home Assistant. Defaults to ``false``.
If the device has different multipliers for current and target temperatures, **temperature_multiplier** can be replaced with both of:
-- **current_temperature_multiplier** (*Optional*, float): A multiplier to modify the current temperature value.
-- **target_temperature_multiplier** (*Optional*, float): A multiplier to modify the target temperature value.
+ - **current_temperature_multiplier** (*Optional*, float): A multiplier to modify the current temperature value.
+ - **target_temperature_multiplier** (*Optional*, float): A multiplier to modify the target temperature value.
- All other options from :ref:`Climate `.
diff --git a/components/copy.rst b/components/copy.rst
index 93f21c6d4..5cc7191c8 100644
--- a/components/copy.rst
+++ b/components/copy.rst
@@ -1,11 +1,11 @@
-Copy Integration
-================
+Copy Component
+==============
.. seo::
- :description: Instructions for setting up the copy integration in ESPHome
+ :description: Instructions for setting up the copy component in ESPHome
:image: content-copy.svg
-The ``copy`` integration can be used to copy an existing component (like a sensor, switch, etc.)
+The ``copy`` component can be used to copy an existing component (like a sensor, switch, etc.)
and create a duplicate mirroring the source's state and forwarding actions such as turning on to the source.
For each of the supported platforms, the configuration consists of the required configuration
diff --git a/components/cover/custom.rst b/components/cover/custom.rst
index 4b49dbc5c..c623a54f9 100644
--- a/components/cover/custom.rst
+++ b/components/cover/custom.rst
@@ -1,24 +1,29 @@
Custom Cover
============
+.. seo::
+ :description: Instructions for setting up Custom C++ covers with ESPHome.
+ :image: language-cpp.svg
+ :keywords: C++, Custom
+
.. warning::
- Custom components are deprecated, not recommended for new configurations
- and will be removed from ESPHome in a future release.
- Please look at creating a real ESPHome component and "importing" it into your
- configuration with :doc:`/components/external_components`.
+ Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
+ future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
+ :doc:`/components/external_components`.
- You can find some basic documentation on creating your own components
- at :ref:`contributing_to_esphome`.
+ You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
-This integration can be used to create custom covers in ESPHome
-using the C++ (Arduino) API.
+.. warning::
-Please first read :doc:`/components/sensor/custom` guide,
-the same principles apply here.
+ While we try to keep the ESPHome YAML configuration options as stable as possible, the ESPHome API is less
+ stable. If something in the APIs needs to be changed in order for something else to work, we will do so.
-The example below is an example of a custom cover - all covers must override
-two methods:
+This component can be used to create custom covers in ESPHome using the C++ (Arduino) API.
+
+Please first read :doc:`/components/sensor/custom` guide, the same principles apply here.
+
+The example below is an example of a custom cover - all covers must override two methods:
- ``get_traits``: This should return a :apiclass:`CoverTraits ` object
representing the capabilities of the cover.
diff --git a/components/cover/images/he60r-sch.jpg b/components/cover/images/he60r-sch.jpg
index aaf74702c..b69d95f30 100644
Binary files a/components/cover/images/he60r-sch.jpg and b/components/cover/images/he60r-sch.jpg differ
diff --git a/components/cover/images/he60r.jpg b/components/cover/images/he60r.jpg
index 025c76db6..9b539f09a 100644
Binary files a/components/cover/images/he60r.jpg and b/components/cover/images/he60r.jpg differ
diff --git a/components/cover/index.rst b/components/cover/index.rst
index abc95bec2..146f4db9e 100644
--- a/components/cover/index.rst
+++ b/components/cover/index.rst
@@ -46,10 +46,10 @@ Advanced options:
a ``name`` will implicitly set this to true.
- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
(usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
- Requires Home Assistant 2021.9 or newer. Defaults to ``false``.
+ Defaults to ``false``.
- **entity_category** (*Optional*, string): The category of the entity.
See https://developers.home-assistant.io/docs/core/entity/#generic-properties
- for a list of available options. Requires Home Assistant 2021.11 or newer.
+ for a list of available options.
Set to ``""`` to remove the default entity category.
MQTT options:
diff --git a/components/cover/time_based.rst b/components/cover/time_based.rst
index 0f5e542dd..e5a5150e9 100644
--- a/components/cover/time_based.rst
+++ b/components/cover/time_based.rst
@@ -77,7 +77,22 @@ Configuration variables:
``esp8266_restore_from_flash: true`` option set.
See :doc:`esp8266_restore_from_flash ` for details.
+Handle stop_action:
+------------------------
+For some cover controllers, separate switches for UP and DOWN action are used while a stop is issued when sending a counter command.
+This can be handled at the **stop_action** by using the folling lamda function:
+.. code-block:: yaml
+
+ stop_action:
+ - lambda: !lambda |-
+ if (id(cover).last_operation() == CoverOperation::COVER_OPERATION_OPENING) {
+ // Cover is currently opening
+ id(cover_button_down).press();
+ } else if (id(cover).last_operation() == CoverOperation::COVER_OPERATION_CLOSING) {
+ // Cover is currently closing
+ id(cover_button_up).press();
+ }
See Also
--------
diff --git a/components/cover/tuya.rst b/components/cover/tuya.rst
index 2293cdd63..917b87545 100644
--- a/components/cover/tuya.rst
+++ b/components/cover/tuya.rst
@@ -45,7 +45,7 @@ Configuration variables:
Supported devices
-----------------
-Tuya cover devices known to be supported by this integration:
+Tuya cover devices known to be supported by this component:
- Tuya ``M515EGWT`` (motor for bead chain roller blinds)
diff --git a/components/datetime/index.rst b/components/datetime/index.rst
index 2b0713d41..c13c979a5 100644
--- a/components/datetime/index.rst
+++ b/components/datetime/index.rst
@@ -42,22 +42,27 @@ Configuration variables:
a ``name`` will implicitly set this to true.
- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
(usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
- Requires Home Assistant 2021.9 or newer. Defaults to ``false``.
+ Defaults to ``false``.
- **entity_category** (*Optional*, string): The category of the entity.
See https://developers.home-assistant.io/docs/core/entity/#generic-properties
- for a list of available options. Requires Home Assistant 2021.11 or newer.
+ for a list of available options.
Set to ``""`` to remove the default entity category.
+- **time_id** (**Required**, :ref:`config-id`): The ID of the time entity. Automatically set
+ to the ID of a time component if only a single one is defined.
MQTT Options:
- All other options from :ref:`MQTT Component `.
-Datetime Automation
--------------------
+Time and DateTime Options:
-You can access the most recent state as a string of the datetime in :ref:`lambdas ` using
-``id(datetime_id).state``.
-You can also access it as a ``ESPTime`` object by ``id(datetime_id).state_as_time``
+- **on_time** (*Optional*, :ref:`automation`): Automation to run when the current datetime or time matches the current state.
+ Only valid on ``time`` or ``datetime`` types.
+
+Automation
+----------
+
+You can access the most recent state as a ``ESPTime`` object by ``id(datetime_id).state_as_esptime()``
.. _datetime-on_value:
@@ -83,6 +88,9 @@ you can get the value as a ESPTime object from the trigger with ``x``.
Configuration variables: See :ref:`Automation `.
+Date Automation
+---------------
+
.. _datetime-date_set_action:
``datetime.date.set`` Action
@@ -151,12 +159,165 @@ advanced stuff (see the full API Reference for more info).
// For example, create a custom log message when a value is received:
ESP_LOGI("main", "Value of my datetime: %04d-%02d-%02d", id(my_date).year, id(my_date).month, id(my_date).day);
+Time Automation
+---------------
+
+.. _datetime-time_set_action:
+
+``datetime.time.set`` Action
+****************************
+
+This is an :ref:`Action ` for setting a datetime time state.
+The ``time`` provided can be in one of 3 formats:
+
+.. code-block:: yaml
+
+ # String time
+ - datetime.time.set:
+ id: my_time
+ time: "12:34:56"
+
+ # Individual time parts
+ - datetime.time.set:
+ id: my_time
+ time:
+ hour: 12
+ minute: 34
+ second: 56
+
+ # Using a lambda
+ - datetime.time.set:
+ id: my_time
+ time: !lambda |-
+ // Return an ESPTime struct
+ return {.second: 56, .minute: 34, .hour: 12};
+
+Configuration variables:
+
+- **id** (**Required**, :ref:`config-id`): The ID of the datetime to set.
+- **time** (**Required**, string, time parts, :ref:`templatable `):
+ The value to set the datetime to.
+
+
+.. _datetime-time-lambda_calls:
+
+lambda calls
+************
+
+From :ref:`lambdas `, you can call several methods on all datetimes to do some
+advanced stuff (see the full API Reference for more info).
+
+- ``.make_call()``: Make a call for updating the datetime value.
+
+ .. code-block:: cpp
+
+ // Within lambda, set the time to 12:34:56
+ auto call = id(my_time).make_call();
+ call.set_date("12:34:56");
+ call.perform();
+
+ Check the API reference for information on the methods that are available for
+ the ``TimeCall`` object.
+
+- ``.hour``: Retrieve the current hour of the ``time``. It will be ``0`` if no value has been set.
+- ``.minute``: Retrieve the current minute of the ``time``. It will be ``0`` if no value has been set.
+- ``.second``: Retrieve the current second of the ``time``. It will be ``0`` if no value has been set.
+- ``.state_as_esptime()``: Retrieve the current value of the datetime as a :apistruct:`ESPTime` object.
+
+ .. code-block:: cpp
+
+ // For example, create a custom log message when a value is received:
+ ESP_LOGI("main", "Value of my datetime: %0d:%02d:%02d", id(my_time).hour, id(my_time).minute, id(my_time).second);
+
+
+DateTime Automation
+-------------------
+
+.. _datetime-datetime_set_action:
+
+``datetime.datetime.set`` Action
+********************************
+
+This is an :ref:`Action ` for setting a datetime datetime state.
+The ``datetime`` provided can be in one of 3 formats:
+
+.. code-block:: yaml
+
+ # String datetime
+ - datetime.time.set:
+ id: my_datetime
+ datetime: "2024-12-31 12:34:56"
+
+ # Individual datetime parts
+ - datetime.datetime.set:
+ id: my_datetime
+ datetime:
+ year: 2024
+ month: 12
+ day: 31
+ hour: 12
+ minute: 34
+ second: 56
+
+ # Using a lambda
+ - datetime.datetime.set:
+ id: my_datetime
+ datetime: !lambda |-
+ // Return an ESPTime struct
+ return {.second: 56, .minute: 34, .hour: 12, .day_of_month: 31, .month: 12, .year: 2024};
+
+Configuration variables:
+
+- **id** (**Required**, :ref:`config-id`): The ID of the datetime to set.
+- **datetime** (**Required**, string, datetime parts, :ref:`templatable `):
+ The value to set the datetime to.
+
+
+.. _datetime-datetime-lambda_calls:
+
+Lambda calls
+************
+
+For more complex use cases, several methods are available for use on datetimes from within :ref:`lambdas `. See the full API Reference for more information.
+
+- ``.make_call()``: Make a call for updating the datetime value.
+
+ .. code-block:: cpp
+
+ // Within lambda, set the datetime to 2024-12-31 12:34:56
+ auto call = id(my_datetime).make_call();
+ call.set_date("2024-12-31 12:34:56");
+ call.perform();
+
+ Check the API reference for information on the methods that are available for
+ the ``DateTimeCall`` object.
+
+- ``.year``: Retrieve the current year of the ``datetime``. It will be ``0`` if no value has been set.
+- ``.month``: Retrieve the current month of the ``datetime``. It will be ``0`` if no value has been set.
+- ``.day``: Retrieve the current day of the ``datetime``. It will be ``0`` if no value has been set.
+- ``.hour``: Retrieve the current hour of the ``datetime``. It will be ``0`` if no value has been set.
+- ``.minute``: Retrieve the current minute of the ``datetime``. It will be ``0`` if no value has been set.
+- ``.second``: Retrieve the current second of the ``datetime``. It will be ``0`` if no value has been set.
+- ``.state_as_esptime()``: Retrieve the current value of the datetime as a :apistruct:`ESPTime` object.
+
+ .. code-block:: cpp
+
+ // For example, create a custom log message when a value is received:
+ ESP_LOGI("main", "Value of my datetime: %04d-%02d-%02d %0d:%02d:%02d",
+ id(my_datetime).year, id(my_datetime).month, id(my_datetime).day,
+ id(my_datetime).hour, id(my_datetime).minute, id(my_datetime).second);
+
+
See Also
--------
- :apiref:`DateTimeBase `
- :apiref:`DateEntity `
- :apiref:`DateCall `
+- :apiref:`TimeEntity `
+- :apiref:`TimeCall `
+- :apiref:`DateTimeEntity `
+- :apiref:`DateTimeCall `
- :ghedit:`Edit`
.. toctree::
diff --git a/components/datetime/template.rst b/components/datetime/template.rst
index b2eca7772..e99161908 100644
--- a/components/datetime/template.rst
+++ b/components/datetime/template.rst
@@ -10,8 +10,8 @@ using :ref:`lambdas `.
.. code-block:: yaml
- # Example configuration entry
datetime:
+ # Example Date
- platform: template
id: my_date
type: date
@@ -20,10 +20,28 @@ using :ref:`lambdas `.
initial_value: "2024-01-30"
restore_value: true
+ # Example Time
+ - platform: template
+ id: my_time
+ type: time
+ name: Pick a Time
+ optimistic: yes
+ initial_value: "12:34:56"
+ restore_value: true
+
+ # Example DateTime
+ - platform: template
+ id: my_datetime
+ type: datetime
+ name: Pick a DateTime
+ optimistic: yes
+ initial_value: "2024-12-31 12:34:56"
+ restore_value: true
+
Configuration variables:
------------------------
-- **type** (*Required*, enum): The type of the datetime. Can only be ``date``.
+- **type** (*Required*, enum): The type of the datetime. Can be one of ``date`` or ``time``.
- **lambda** (*Optional*, :ref:`lambda `):
Lambda to be evaluated every update interval to get the current value of the datetime.
- **set_action** (*Optional*, :ref:`Action `): The action that should
@@ -39,15 +57,44 @@ Configuration variables:
- **initial_value** (*Optional*, string): The value to set the state to on setup if not
restored with ``restore_value``. Can be one of:
- - A string in the format ``%Y-%m-%d``, eg: ``"2023-12-04"``.
- - An object including ``year``, ``month``, ``day``.
+ - For ``type: date``:
- .. code-block:: yaml
+ - A string in the format ``%Y-%m-%d`` , eg: ``"2023-12-04"``.
+ - An object including ``year``, ``month``, ``day``.
- initial_value:
- year: 2023
- month: 12
- day: 4
+ .. code-block:: yaml
+
+ initial_value:
+ year: 2023
+ month: 12
+ day: 4
+
+ - For ``type: time``:
+
+ - A string in the format ``%H:%M:%S`` , eg: ``"12:34:56"``.
+ - An object including ``hour``, ``minute``, ``second``.
+
+ .. code-block:: yaml
+
+ initial_value:
+ hour: 12
+ minute: 34
+ second: 56
+
+ - For ``type: datetime``:
+
+ - A string in the format ``%Y-%m-%d %H:%M:%S`` , eg: ``"2023-12-04 12:34:56"``.
+ - An object including ``year``, ``month``, ``day``, ``hour``, ``minute``, ``second``.
+
+ .. code-block:: yaml
+
+ initial_value:
+ year: 2023
+ month: 12
+ day: 4
+ hour: 12
+ minute: 34
+ second: 56
- All other options from :ref:`Datetime `.
diff --git a/components/deep_sleep.rst b/components/deep_sleep.rst
index 01b8470ab..92e890766 100644
--- a/components/deep_sleep.rst
+++ b/components/deep_sleep.rst
@@ -87,6 +87,34 @@ when the deep sleep should start? There are three ways of handling this using th
then re-configure deep sleep to wake up on a LOW signal and vice versa. Useful in situations when you want to
use observe the state changes of a pin using deep sleep and the ON/OFF values last longer.
+ESP32 Wakeup Cause
+------------------
+
+On the ESP32, the ``esp_sleep_get_wakeup_cause()`` function can be used to check which wakeup source has triggered
+wakeup from sleep mode.
+
+.. code-block:: yaml
+
+ sensor:
+ - platform: template
+ name: "Wakeup Cause"
+ accuracy_decimals: 0
+ lambda: return esp_sleep_get_wakeup_cause();
+
+The following integers are the wakeup causes:
+ - **0** - ``ESP_SLEEP_WAKEUP_UNDEFINED``: In case of deep sleep, reset was not caused by exit from deep sleep
+ - **1** - ``ESP_SLEEP_WAKEUP_ALL``: Not a wakeup cause, used to disable all wakeup sources with esp_sleep_disable_wakeup_source
+ - **2** - ``ESP_SLEEP_WAKEUP_EXT0``: Wakeup caused by external signal using RTC_IO
+ - **3** - ``ESP_SLEEP_WAKEUP_EXT1``: Wakeup caused by external signal using RTC_CNTL
+ - **4** - ``ESP_SLEEP_WAKEUP_TIMER``: Wakeup caused by timer
+ - **5** - ``ESP_SLEEP_WAKEUP_TOUCHPAD``: Wakeup caused by touchpad
+ - **6** - ``ESP_SLEEP_WAKEUP_ULP``: Wakeup caused by ULP program
+ - **7** - ``ESP_SLEEP_WAKEUP_GPIO``: Wakeup caused by GPIO (light sleep only on ESP32, S2 and S3)
+ - **8** - ``ESP_SLEEP_WAKEUP_UART``: Wakeup caused by UART (light sleep only)
+ - **9** - ``ESP_SLEEP_WAKEUP_WIFI``: Wakeup caused by WIFI (light sleep only)
+ - **10** - ``ESP_SLEEP_WAKEUP_COCPU``: Wakeup caused by COCPU int
+ - **11** - ``ESP_SLEEP_WAKEUP_COCPU_TRAP_TRIG``: Wakeup caused by COCPU crash
+ - **12** - ``ESP_SLEEP_WAKEUP_BT``: Wakeup caused by BT (light sleep only)
.. _deep_sleep-enter_action:
diff --git a/components/demo.rst b/components/demo.rst
index faccce99f..65eef4b51 100644
--- a/components/demo.rst
+++ b/components/demo.rst
@@ -1,12 +1,12 @@
-Demo Integration
-================
+Demo Component
+==============
.. seo::
- :description: Instructions for setting up the demo integration in ESPHome
+ :description: Instructions for setting up the demo component in ESPHome
:image: description.svg
-The ``demo`` integration can be used for testing to generate sample instances of many
-different integrations (sensors, lights, ...)
+The ``demo`` component can be used for testing to generate sample instances of many
+different components (sensors, lights, ...)
.. figure:: images/demo-ui.png
:align: center
@@ -20,7 +20,7 @@ different integrations (sensors, lights, ...)
Configuration variables:
------------------------
-This integration has no configuration variables
+This component has no configuration variables
See Also
--------
diff --git a/components/dfplayer.rst b/components/dfplayer.rst
index 9b2f5e655..672cc4615 100644
--- a/components/dfplayer.rst
+++ b/components/dfplayer.rst
@@ -2,7 +2,7 @@ DF-Player mini
==============
.. seo::
- :description: Instructions for setting up DF Player Mini integration in ESPHome.
+ :description: Instructions for setting up DF Player Mini component in ESPHome.
:image: dfplayer.svg
The ``dfplayer`` (`datasheet `__), component
@@ -14,8 +14,7 @@ allows you to play sound and music stored in an SD card or USB flash drive.
DF-Player mini Module.
-For this integration to work you need to have set up a :ref:`UART bus `
-in your configuration.
+For this component to work you need to have set up a :ref:`UART bus ` in your configuration.
Overview
--------
@@ -31,16 +30,7 @@ will be required.
.. code-block:: yaml
# Example configuration entry
- uart:
- tx_pin: GPIO2
- rx_pin: GPIO5
- baud_rate: 9600
-
- # Declare DFPlayer mini module
dfplayer:
- on_finished_playback:
- then:
- logger.log: 'Somebody press play!'
Configuration variables:
------------------------
@@ -114,11 +104,11 @@ Configuration options:
``dfplayer.play_mp3`` Action
----------------------------
-Plays a track inside the folder ``mp3``. Files inside the folder must be numbered from 1
+Plays a track inside the folder ``mp3``. Files inside the folder must be numbered from 1
to 9999, like ``0001.mp3``, ``0002.mp3``, ... etc.
-The folder name needs to be ``mp3``, placed under the SD card root directory, and the
-mp3 file name needs to be 4 digits, for example, "0001.mp3", placed under the mp3 folder.
-If you want, you can add additional text after the number in the filename, for example,
+The folder name needs to be ``mp3``, placed under the SD card root directory, and the
+mp3 file name needs to be 4 digits, for example, "0001.mp3", placed under the mp3 folder.
+If you want, you can add additional text after the number in the filename, for example,
``0001hello.mp3``, but must always be referenced by number only in yaml.
.. code-block:: bash
@@ -345,8 +335,8 @@ Sample code
.. code-block:: yaml
uart:
- tx_pin: GPIO2
- rx_pin: GPIO5
+ tx_pin: GPIOXX
+ rx_pin: GPIOXX
baud_rate: 9600
dfplayer:
diff --git a/components/display/addressable_light.rst b/components/display/addressable_light.rst
index 44c125b7e..8f9e39481 100644
--- a/components/display/addressable_light.rst
+++ b/components/display/addressable_light.rst
@@ -19,18 +19,6 @@ The display requires that an :apiclass:`AddressableLight `): A lambda that returns the integer address of the LED
- given the supplied the ``x`` and ``y`` pixel coordinate. By default, a left-to-right direct pixel mapper is used.
+ given the supplied the ``x`` and ``y`` pixel coordinate. By default, a left-to-right direct pixel mapper is used.
- **lambda** (*Optional*, :ref:`lambda `): The lambda to use for rendering the content on the display.
``it`` will be an instance of :apiclass:`DisplayBuffer `.
- See :ref:`display-engine` for more information.
+ See :ref:`display-engine` for more information.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
@@ -73,7 +61,7 @@ Configuration variables:
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
diff --git a/components/display/fonts.rst b/components/display/fonts.rst
index 0a1ed8574..47ab89461 100644
--- a/components/display/fonts.rst
+++ b/components/display/fonts.rst
@@ -7,11 +7,14 @@ Font Renderer Component
:description: Instructions for setting up fonts in ESPHome.
:image: format-font.svg
-ESPHome's graphical rendering engine also has a powerful font drawer which integrates seamlessly into the system. You have the option to use **any** OpenType/TrueType (``.ttf``, ``.otf``, ``.woff``) font file at **any** size, as well as fixed-size `PCF `_ and `BDF `_ bitmap fonts.
+ESPHome's graphical rendering engine also has a powerful font drawer which integrates seamlessly into the system. You have the option to use **any** OpenType/TrueType (``.ttf``, ``.otf``, ``.woff``) font file at **any** size, as well as fixed-size `PCF `_ and `BDF `_ bitmap fonts.
These fonts can be used in ESPHome's :ref:`own rendering engine `.
-To use fonts you first have to define a font object in your ESPHome configuration file. Just grab a ``.ttf``, ``.otf``, ``.woff``, ``.pcf``, or ``.bdf`` file from somewhere on the internet and place it, for example, inside a ``fonts`` folder next to your configuration file.
+To use fonts you can either
+ - Just grab a ``.ttf``, ``.otf``, ``.woff``, ``.pcf``, or ``.bdf`` file from somewhere on the internet and place it, for example, inside a ``fonts`` folder next to your configuration file.
+ - Use the ``gfonts://`` short form to use Google Fonts directly.
+ - Load a font from a URL directly on build.
Next, create a ``font:`` section in your configuration:
@@ -68,6 +71,15 @@ Next, create a ``font:`` section in your configuration:
"\U000F05D4", # mdi-airplane-landing
]
+ - file: "https://github.com/IdreesInc/Monocraft/releases/download/v3.0/Monocraft.ttf"
+ id: web_font
+ size: 20
+ - file:
+ url: "https://github.com/IdreesInc/Monocraft/releases/download/v3.0/Monocraft.ttf"
+ type: web
+ id: web_font2
+ size: 24
+
display:
# ...
@@ -77,7 +89,7 @@ Configuration variables:
- **file** (**Required**, string): The path (relative to where the .yaml file is) of the font
file. You can also use the ``gfonts://`` short form to use Google Fonts, or use the below structure:
- - **type** (**Required**, string): Can be ``local`` or ``gfonts``.
+ - **type** (**Required**, string): Can be ``local``, ``gfonts`` or ``web``.
**Local Fonts**:
@@ -101,6 +113,10 @@ Configuration variables:
- **extra-bold**: 800
- **black**: 900
+ **Web Fonts**:
+
+ - **url** (**Required**, string): The URL of the TrueType or bitmap font file.
+
- **id** (**Required**, :ref:`config-id`): The ID with which you will be able to reference the font later
in your display code.
- **size** (*Optional*, int): The size of the font in pt (not pixel!).
@@ -117,14 +133,14 @@ Configuration variables:
.. 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.
+ 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``.
-
+
+ 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.
@@ -142,4 +158,3 @@ See Also
- `MDI cheatsheet ` . The default **data_rate** is set to ``40MHz`` and the **spi_mode** mode is ``MODE0`` but some displays require ``MODE3`` (*).
+
+**Note:** The maximum achievable data rate will depend on the chip type (e.g. ESP32 vs ESP32-S3) the pins used (on ESP32 using the default SPI pins allows higher rates) and the connection type (on-board connections will support higher rates than long cables or DuPont wires.) If in doubt, start with a low speed and test higher rates to find what works. A MISO pin should preferably not be specified, as this will limit the maximum rate in some circumstances, and is not required if the SPI bus is used only for the display.
+
Configuration examples
**********************
@@ -132,8 +134,6 @@ height 320 and width 480 into portrait. Note that the dimensions are those of th
width: 320
-
-
To utilize the color capabilities of this display module, you'll likely want to add a ``color:`` section to your
YAML configuration; please see :ref:`color ` for more detail on this configuration section.
@@ -180,13 +180,13 @@ To configure a dimmable backlight:
# Define a PWM output on the ESP32
output:
- platform: ledc
- pin: 32
- id: gpio_32_backlight_pwm
+ pin: GPIOXX
+ id: backlight_pwm
# Define a monochromatic, dimmable light for the backlight
light:
- platform: monochromatic
- output: gpio_32_backlight_pwm
+ output: backlight_pwm
name: "Display Backlight"
id: back_light
restore_mode: ALWAYS_ON
@@ -204,8 +204,8 @@ To configure an image adaptive color pallet to show greater than 8 bit color dep
display:
- platform: ili9xxx
model: ili9341
- dc_pin: 4
- reset_pin: 22
+ dc_pin: GPIOXX
+ reset_pin: GPIOXX
rotation: 90
id: tft_ha
color_palette: IMAGE_ADAPTIVE
@@ -234,7 +234,7 @@ This config rotates the display into landscape mode using the driver chip.
mirror_y: true
color_order: bgr
data_rate: 80MHz
- cs_pin: 10
+ cs_pin: GPIOXX
dc_pin: GPIO13
reset_pin: GPIO9
diff --git a/components/display/images/display_rendering_colors.png b/components/display/images/display_rendering_colors.png
new file mode 100644
index 000000000..df5830179
Binary files /dev/null and b/components/display/images/display_rendering_colors.png differ
diff --git a/components/display/images/display_rendering_graph.png b/components/display/images/display_rendering_graph.png
new file mode 100644
index 000000000..9c2c30d45
Binary files /dev/null and b/components/display/images/display_rendering_graph.png differ
diff --git a/components/display/images/display_rendering_line.png b/components/display/images/display_rendering_line.png
new file mode 100644
index 000000000..633c0d42a
Binary files /dev/null and b/components/display/images/display_rendering_line.png differ
diff --git a/components/display/images/display_rendering_shapes.png b/components/display/images/display_rendering_shapes.png
new file mode 100644
index 000000000..b6a034710
Binary files /dev/null and b/components/display/images/display_rendering_shapes.png differ
diff --git a/components/display/images/display_rendering_text.png b/components/display/images/display_rendering_text.png
new file mode 100644
index 000000000..3e5fb7834
Binary files /dev/null and b/components/display/images/display_rendering_text.png differ
diff --git a/components/display/images/graph_dualtrace.png b/components/display/images/graph_dualtrace.png
deleted file mode 100644
index 4beeacf91..000000000
Binary files a/components/display/images/graph_dualtrace.png and /dev/null differ
diff --git a/components/display/images/graph_screen.png b/components/display/images/graph_screen.png
deleted file mode 100644
index a47ed6ca5..000000000
Binary files a/components/display/images/graph_screen.png and /dev/null differ
diff --git a/components/display/images/indicator.jpg b/components/display/images/indicator.jpg
index 57397d6f5..14ec131c2 100644
Binary files a/components/display/images/indicator.jpg and b/components/display/images/indicator.jpg differ
diff --git a/components/display/images/st7567-full.jpg b/components/display/images/st7567-full.jpg
index 5abdd49a7..be850c491 100644
Binary files a/components/display/images/st7567-full.jpg and b/components/display/images/st7567-full.jpg differ
diff --git a/components/display/images/t-display-amoled.jpg b/components/display/images/t-display-amoled.jpg
new file mode 100644
index 000000000..59163f509
Binary files /dev/null and b/components/display/images/t-display-amoled.jpg differ
diff --git a/components/display/images/t4-s3.jpg b/components/display/images/t4-s3.jpg
new file mode 100644
index 000000000..00448c410
Binary files /dev/null and b/components/display/images/t4-s3.jpg differ
diff --git a/components/display/images/test_card.jpg b/components/display/images/test_card.jpg
new file mode 100644
index 000000000..49ba2cf8a
Binary files /dev/null and b/components/display/images/test_card.jpg differ
diff --git a/components/display/images/waveshare_touch-s3.jpg b/components/display/images/waveshare_touch-s3.jpg
index ac719bb54..111284a7e 100644
Binary files a/components/display/images/waveshare_touch-s3.jpg and b/components/display/images/waveshare_touch-s3.jpg differ
diff --git a/components/display/index.rst b/components/display/index.rst
index 55b38afc6..0dd4a1eab 100644
--- a/components/display/index.rst
+++ b/components/display/index.rst
@@ -2,7 +2,7 @@ Display Component
=================
.. seo::
- :description: Instructions for setting up the display integration.
+ :description: Instructions for setting up the display component.
:image: folder-open.svg
The ``display`` component houses ESPHome's powerful rendering and display
@@ -45,6 +45,9 @@ this behavior by setting ``auto_clear_enabled: false``.
In the lambda, you can write code like in any :ref:`lambda ` in ESPHome. Display
lambdas are additionally passed a variable called ``it`` which represents the rendering engine object.
+.. figure:: images/display_rendering_line.png
+ :align: center
+
.. code-block:: yaml
display:
@@ -74,8 +77,10 @@ the rendering engine is always first specify the ``x`` coordinate and then the `
Basic Shapes
------------
-Now that you know a bit more about ESPHome's coordinate system, let's draw some basic shapes like lines, rectangles
-and circles:
+Now that you know a bit more about ESPHome's coordinate system, let's draw some basic shapes like lines, rectangles, circles or even polygons:
+
+.. figure:: images/display_rendering_shapes.png
+ :align: center
.. code-block:: yaml
@@ -85,27 +90,27 @@ and circles:
lambda: |-
// Draw a line from [0,0] to [100,50]
it.line(0, 0, 100, 50);
- // Draw the outline of a rectangle with the top left at [50,60], a width of 30 and a height of 42
- it.rectangle(50, 60, 30, 42);
- // Draw the same rectangle, but this time filled.
- it.filled_rectangle(50, 60, 30, 42);
+ // Draw the outline of a rectangle with the top left at [5,20], a width of 30 and a height of 42
+ it.rectangle(5, 20, 30, 42);
+ // Draw the same rectangle a few pixels apart, but this time filled
+ it.filled_rectangle(40, 40, 30, 42);
- // Circles! Let's draw one with the center at [25,25] and a radius of 10
- it.circle(25, 25, 10);
+ // Circles! Let's draw one with the center at [20,40] and a radius of 10
+ it.circle(20, 40, 10);
// ... and the same thing filled again
- it.filled_circle(25, 25, 10);
+ it.filled_circle(20, 75, 10);
// Triangles... Let's draw the outline of a triangle from the [x,y] coordinates of its three points
- // [25,5], [5,25], [50,50]
- it.triangle(25, 5, 5, 25, 50, 50);
+ // [25,5], [100,5], [80,25]
+ it.triangle(25, 5, 100, 5, 80, 25);
// and a filled triangle !
- it.filled_triangle(125, 5, 105, 25, 150, 50);
+ it.filled_triangle(115, 5, 95, 25, 125, 70);
- // Regular Polygons? Let's draw the outline of a pointy-topped hexagon inscribed in a circle
- // centered on [x1=100,y1=100] with a radius of 50
- it.regular_polygon(100, 100, 50, EDGES_HEXAGON);
- // and a filled flat-topped octagon!
- it.filled_regular_polygon(200, 200, 50, EDGES_OCTAGON, VARIATION_FLAT_TOP);
+ // Regular Polygons? Let's draw a filled, pointy-topped hexagon inscribed in a circle
+ // centered on [170,45] with a radius of 20
+ it.filled_regular_polygon(170, 45, 20, EDGES_HEXAGON);
+ // and the outline of flat-topped octagon around it!
+ it.regular_polygon(170, 45, 40, EDGES_OCTAGON, VARIATION_FLAT_TOP);
// Need to rotate the polygon, or retrieve the coordinates of its vertices? Check the API!
All the above methods can optionally also be called with an argument at the end which specifies in which
@@ -117,33 +122,35 @@ color to draw. For monochrome displays, only ``COLOR_ON`` (the default if color
- platform: ...
# ...
lambda: |-
- // Turn the whole display on.
+ // Turn the whole display on
it.fill(COLOR_ON);
- // Turn the whole display off.
+ // Turn the whole display off
it.fill(COLOR_OFF);
// Turn a single pixel off at [50,60]
it.draw_pixel_at(50, 60, COLOR_OFF);
- // Turn off a whole display portion.
- it.rectangle(50, 50, 30, 42, COLOR_OFF);
-
For color displays (e.g. TFT displays), you can use the Color class.
+.. figure:: images/display_rendering_colors.png
+ :align: center
+
.. code-block:: yaml
display:
- platform: ...
# ...
lambda: |-
+ auto black = Color(0, 0, 0);
auto red = Color(255, 0, 0);
auto green = Color(0, 255, 0);
auto blue = Color(0, 0, 255);
auto white = Color(255, 255, 255);
- it.rectangle(20, 50, 30, 30, white);
- it.rectangle(25, 55, 30, 30, red);
- it.rectangle(30, 60, 30, 30, green);
- it.rectangle(35, 65, 30, 30, blue);
+ it.filled_circle(20, 32, 15, black);
+ it.filled_circle(40, 32, 15, red);
+ it.filled_circle(60, 32, 15, green);
+ it.filled_circle(80, 32, 15, blue);
+ it.filled_circle(100, 32, 15, white);
Additionally, you have access to two helper methods which will fetch the width and height of the display:
@@ -156,6 +163,8 @@ Additionally, you have access to two helper methods which will fetch the width a
// Draw a circle in the middle of the display
it.filled_circle(it.get_width() / 2, it.get_height() / 2, 20);
+ // Turn off bottom half of the screen
+ it.filled_rectangle(0, it.get_height()/2, it.get_width(), it.get_height()/2, COLOR_OFF);
You can view the full API documentation for the rendering engine in the "API Reference" in the See Also section.
@@ -218,6 +227,10 @@ In case of fonts rendered at higher bit depths, the background color has to be s
// Syntax is always: it.print(, , , [color=COLOR_ON], [align], , [color=COLOR_OFF]);
it.print(0, 0, id(my_font_with_icons), COLOR_ON, TextAlign::CENTER, "Just\U000f05d4here. Already\U000F02D1this.", COLOR_OFF);
+
+.. figure:: images/display_rendering_text.png
+ :align: center
+
.. _display-printf:
Formatted Text
@@ -457,13 +470,8 @@ memory at the time the sensor updates and will be lost when the device reboots.
Examples:
-.. figure:: images/graph_screen.png
+.. figure:: images/display_rendering_graph.png
:align: center
- :width: 60.0%
-
-.. figure:: images/graph_dualtrace.png
- :align: center
- :width: 60.0%
Graph component with options for grids, border and line-types.
@@ -602,6 +610,12 @@ To draw the QR-code, call the ``it.qr_code`` function from your render lambda:
// Draw the QR-code at position [x=50,y=0] with white color and a 2x scale
it.qr_code(50, 0, id(homepage_qr), Color(255,255,255), 2);
+ // Draw the QR-code in the center of the screen with white color and a 2x scale
+ auto size = id(homepage_qr).get_size() * 2; // Multiply by scale
+ auto x = (it.get_width() / 2) - (size / 2);
+ auto y = (it.get_height() / 2) - (size / 2);
+ it.qr_code(x, y, id(homepage_qr), Color(255,255,255), 2);
+
.. _display-image:
@@ -921,49 +935,30 @@ Additionally the old page will be given as the variable ``from`` and the new one
Troubleshooting
---------------
-Color Test Pattern
-------------------
+Using the Color Test Card
+-------------------------
-If you're experiencing issues with your color display, the script below can help you to identify what might be wrong.
-It will show 3 color bars in **RED**, **GREEN** and **BLUE**. To help the graphics display team determine
-the best way to help you, **a picture of the result of this script is very helpful.**
+If you're experiencing issues with your color display, the ``show_test_card: true`` option can help you to identify what might be wrong.
+
+- It will show bars for Red, Green and Blue, graduating to black and white.
+- Together with that it will show the letters "**R**", "**G**" and "**B**" to validate the display geometry.
+- There will be a rectangle around the corners of the display with a marker at the 0,0 corner which should be at the top left of the screen.
+
+.. figure:: images/test_card.jpg
+ :align: center
+ :width: 50.0%
+
+
+
+When all points above are shown correctly then the display is working as expected.
+To help the graphics display team determine the best way to help you, **a picture of the result of this option is very helpful.**
Should you `create an issue `__ in GitHub regarding your display, please
-be sure to **include a link to where you purchased it** so that we can validate the configuration you've used.
+be sure to **include a link to where you purchased the display** so that we can validate the configuration you've used.
-.. code-block:: yaml
+.. note::
- display:
- - platform: ...
- ...
- lambda: |-
- int shift_x = (it.get_width()-310)/2;
- int shift_y = (it.get_height()-256)/2;
- for(auto i = 0; i<256; i++) {
- it.horizontal_line(shift_x+ 0,i+shift_y,50, my_red.fade_to_white(i));
- it.horizontal_line(shift_x+ 50,i+shift_y,50, my_red.fade_to_black(i));
-
- it.horizontal_line(shift_x+105,i+shift_y,50, my_green.fade_to_white(i));
- it.horizontal_line(shift_x+155,i+shift_y,50, my_green.fade_to_black(i));
-
- it.horizontal_line(shift_x+210,i+shift_y,50, my_blue.fade_to_white(i));
- it.horizontal_line(shift_x+260,i+shift_y,50, my_blue.fade_to_black(i));
- }
- it.rectangle(shift_x+ 0, 0+shift_y, shift_x+ 310, 256+shift_y, my_yellow);
-
- color:
- - id: my_blue
- blue: 100%
- - id: my_red
- red: 100%
- - id: my_green
- green: 100%
- - id: my_white
- red: 100%
- blue: 100%
- green: 100%
- - id: my_yellow
- hex: ffff00
+ For displays in 8 bit mode you will see distinct color blocks rather than a smooth gradient.
See Also
--------
diff --git a/components/display/lcd_display.rst b/components/display/lcd_display.rst
index 005de6c4c..c1bbf04e3 100644
--- a/components/display/lcd_display.rst
+++ b/components/display/lcd_display.rst
@@ -2,12 +2,12 @@ Character-Based LCD Display
===========================
.. seo::
- :description: Instructions for setting up character-based HD44780 LCD displays.
+ :description: Instructions for setting up character-based HD44780 LCDs.
:image: lcd.jpg
-The ``lcd_pcf8574`` and ``lcd_gpio`` display components allow you to use HD44780-compatible, character-based LCD displays
-with ESPHome. This integration is only for LCD displays that display individual characters on a screen
-(usually 8-40 columns and 2-4 rows), and not for LCD displays that can control each pixel individually.
+The ``lcd_pcf8574`` and ``lcd_gpio`` display components allow you to use HD44780-compatible, character-based LCDs
+with ESPHome. This component is only for LCDs that display individual characters on a screen
+(usually 8-40 columns and 2-4 rows), and not for LCDs that can control each pixel individually.
.. figure:: images/lcd-hello_world.jpg
:align: center
@@ -15,12 +15,12 @@ with ESPHome. This integration is only for LCD displays that display individual
.. note::
- Multiple versions of the display exist, supporting different character sets:
-
+ 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.
.. _lcd-pcf8574:
@@ -28,7 +28,7 @@ with ESPHome. This integration is only for LCD displays that display individual
lcd_pcf8574 Component
---------------------
-``lcd_pcf8574`` is for LCD displays with a PCF8574 GPIO expander module connected to all the data pins. This has the
+``lcd_pcf8574`` is for LCD displays with a PCF8574 GPIO expander module connected to all the data pins. This has the
benefit that you only need to connect two data wires to the ESP instead of the six or ten as with the :ref:`lcd-gpio`.
The communication happens via :ref:`I²C Bus `, you need to have an ``i2c:`` section in your configuration.
@@ -65,7 +65,7 @@ Configuration variables:
.. note::
- If you're not seeing anything on the display, try turning the contrast potentiometer around on the
+ If you're not seeing anything on the display, try turning the contrast potentiometer around on the
PCF8574 board.
.. _lcd-gpio:
@@ -74,7 +74,7 @@ lcd_gpio Component
------------------
The ``lcd_gpio`` version of this component addresses the screen directly and does not employ a GPIO expander module.
-Each of the data pins of the LCD needs a dedicated GPIO pin on the ESP. Connecting the screen this way offers
+Each of the data pins of the LCD needs a dedicated GPIO pin on the ESP. Connecting the screen this way offers
faster refresh, especially in conjunction with an :ref:`LCD Menu `.
.. figure:: images/lcd_gpio.svg
@@ -90,12 +90,12 @@ faster refresh, especially in conjunction with an :ref:`LCD Menu `.
- platform: lcd_gpio
dimensions: 20x4
data_pins:
- - GPIO32
- - GPIO33
- - GPIO5
- - GPIO17
- enable_pin: D4
- rs_pin: D5
+ - GPIOXX
+ - GPIOXX
+ - GPIOXX
+ - GPIOXX
+ enable_pin: GPIOXX
+ rs_pin: GPIOXX
lambda: |-
it.print("Hello World!");
@@ -105,8 +105,8 @@ Configuration variables:
- **dimensions** (**Required**, string): The dimensions of the display with ``COLUMNSxROWS``. If you're not
sure, power the display on, turn contrast high up and just count them.
- **data_pins** (**Required**, list of :ref:`pins `): A list of the data pins you
- have hooked up to the LCD. The list can either be 4 items long (operating in 4-bit mode with
- either the first 4 data pins connected or the last 4 data pins connected), or 8 items long (when you have
+ have hooked up to the LCD. The list can either be 4 items long (operating in 4-bit mode with
+ either the first 4 data pins connected or the last 4 data pins connected), or 8 items long (when you have
connected all 8 data pins).
- **enable_pin** (**Required**, :ref:`pin `): The pin you have ``E`` (``06``) hooked up to.
- **rs_pin** (**Required**, :ref:`pin `): The pin you have ``RS`` (``04``) hooked up to.
@@ -118,7 +118,7 @@ Configuration variables:
.. note::
- If you're not seeing anything on the display, make sure you apply ``3.3V`` to the ``VEE`` (``03``) contrast control
+ 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.
@@ -177,7 +177,7 @@ The LCD display has the possibility to define up to eight user defined character
``0`` to ``7`` and mirrored at ``8`` to ``15`` (i.e. ``\x08`` can be used instead of the ``\0`` that can
be problematic in strings). Each character has eight lines of five bits, with the first line on the top
and the most significant bit on the left, meaning that ``0b10000`` followed by six zeros and a ``0b00001``
-defines a dot at the upper left and lower right of the character.
+defines a dot at the upper left and lower right of the character.
.. code-block:: yaml
@@ -221,7 +221,7 @@ Keep in mind that the display lambda runs for every ``update_interval``, so if t
it cannot be overridden from other parts.
With the ``lcd_gpio``, the backlight is lit by applying ``Vcc`` to the ``BLA`` (``15``) pin and connect ``BLK`` (``16``)
-pin to ``GND``. The backlight can draw more power than the microcontroller output pins can supply, so it is advisable
+pin to ``GND``. The backlight can draw more power than the microcontroller output pins can supply, so it is advisable
to use a transistor as a switch to control the power for the backlight pins.
Below an example for a typical use-case where the backlight is turned on when a motion sensor activates and
diff --git a/components/display/max7219.rst b/components/display/max7219.rst
index ad1b1c6c5..11e069f1c 100644
--- a/components/display/max7219.rst
+++ b/components/display/max7219.rst
@@ -8,7 +8,7 @@ MAX7219 7-Segment Display
The ``max7219`` display platform allows you to use MAX7219 7-segment display drivers (
`datasheet `__,
`hobbycomponents `__)
-with ESPHome. Please note that this integration is *only* for 7-segment display, not matrix configurations.
+with ESPHome. Please note that this component is *only* for 7-segment display, not matrix configurations.
.. figure:: images/max7219-full.jpg
:align: center
@@ -16,7 +16,7 @@ with ESPHome. Please note that this integration is *only* for 7-segment display,
MAX7219 7-Segment Display.
-As the communication with the MAX7219 is done using SPI for this integration, you need
+As the communication with the MAX7219 is done using SPI for this component, you need
to have an :ref:`SPI bus ` in your configuration with both the **mosi_pin** set (miso_pin is not required).
Connect VCC to 3.3V (the manufacturer recommends 4+ V, but 3.3V seems to work fine), DIN to your ``mosi_pin`` and
CS to your set ``cs_pin`` and finally GND to GND.
diff --git a/components/display/max7219digit.rst b/components/display/max7219digit.rst
index 2c7923c43..650ef878e 100644
--- a/components/display/max7219digit.rst
+++ b/components/display/max7219digit.rst
@@ -5,7 +5,7 @@ MAX7219 Digit Display
:description: Instructions for setting up MAX7219 Digit displays.
:image: max7219digit.jpg
-The ``max7219`` display platform allows you to use MAX7219 digit with ESPHome. Please note that this integration
+The ``max7219`` display platform allows you to use MAX7219 digit with ESPHome. Please note that this component
is *only* for the digit "matrix" display, for the 7 segment display see :doc:`max7219`.
.. figure:: images/max7219digit.png
@@ -14,7 +14,7 @@ is *only* for the digit "matrix" display, for the 7 segment display see :doc:`ma
MAX7219 Digit Display.
-As the communication with the MAX7219 Digit is done using SPI for this integration, you need
+As the communication with the MAX7219 Digit is done using SPI for this component, you need
to have an :ref:`SPI bus ` in your configuration with both the **mosi_pin** set (miso_pin is not required).
Connect VCC to 3.3V (the manufacturer recommends 4+ V, but 3.3V seems to work fine), DIN to your ``mosi_pin`` and
CS to your set ``cs_pin`` and finally GND to GND.
diff --git a/components/display/nextion.rst b/components/display/nextion.rst
index 95c29a89e..09d8a85f9 100644
--- a/components/display/nextion.rst
+++ b/components/display/nextion.rst
@@ -18,15 +18,15 @@ with ESPHome.
As the communication with the Nextion LCD display is done using UART, you need to have an :ref:`UART bus `
in your configuration with ``rx_pin`` both the ``tx_pin`` set to the respective pins on the display.
The Nextion uses a baud rate of 9600 by default. It may be configured to use a faster speed by adding (for
-example)
+example)
.. code-block:: c++
baud=115200 // Sets the baud rate to 115200
bkcmd=0 // Tells the Nextion to not send responses on commands. This is the current default but can be set just in case
-
-
+
+
to the ``program.s`` source file (in the Nextion Editor) before the ``page`` line.
This permits faster communication with the Nextion display and it is highly recommended when using :ref:`uart-hardware_uarts`. Without a hardware uart make sure to set the baud rate to 9600.
@@ -36,17 +36,9 @@ The below example configures a UART for the Nextion display to use
.. code-block:: yaml
# Example configuration entry
- uart:
- id: uart_2
- rx_pin: GPIO16
- tx_pin: GPIO17
- baud_rate: 115200
-
-
display:
- platform: nextion
id: nextion1
- uart_id: uart_2
lambda: |-
it.set_component_value("gauge", 50);
it.set_component_text("textview", "Hello World!");
@@ -73,7 +65,7 @@ Configuration variables:
- **on_wake** (*Optional*, :ref:`Action `): An action to be performed when the Nextion wakes up. See :ref:`Nextion Automation `.
- **on_page** (*Optional*, :ref:`Action `): An action to be performed after a page change. See :ref:`Nextion Automation `.
- **on_touch** (*Optional*, :ref:`Action `): An action to be performed after a touch event (press or release). See :ref:`Nextion Automation `.
-
+
.. _display-nextion_lambda:
Rendering Lambda
@@ -113,7 +105,7 @@ Lambda Calls
************
Several methods are available for use within :ref:`lambdas `; these permit advanced functionality beyond simple
-display updates. See the full :apiref:`nextion/nextion.h` for more info.
+display updates. See the full :apiref:`nextion/nextion.h` for more info.
.. _nextion_upload_tft:
@@ -126,7 +118,7 @@ The developer tools in Home Assistant can be used to trigger the update. The bel
services:
- service: update_nextion
then:
- - lambda: 'id(nextion1)->upload_tft();'
+ - lambda: 'id(nextion1)->upload_tft();'
.. _nextion_update_all_components:
@@ -178,7 +170,7 @@ The developer tools in Home Assistant can be used to trigger the update. The bel
.. _nextion_queue_types:
- Queue Types:
+ Queue Types:
- SENSOR 0
- BINARY_SENSOR 1
- SWITCH 2
@@ -291,7 +283,7 @@ The following arguments will be available:
Uploading A TFT File
--------------------
This will download the file from the tft_url and will transfer it over the UART to the Nextion.
-Once completed both the ESP and Nextion will reboot. During the upload process esphome will be
+Once completed both the ESP and Nextion will reboot. During the upload process esphome will be
unresponsive and no logging will take place. This uses the same protocol as the Nextion editor and
only updates the changes of the TFT file. If HTTPS/SSL is enabled it will be about 1kB/sec.
@@ -304,7 +296,7 @@ To host the TFT file you can use Home Assistant itself or any other web server.
Home Assistant
**************
-To host the TFT file from Home Assistant, create a www directory if it doesn't exist in your config
+To host the TFT file from Home Assistant, create a www directory if it doesn't exist in your config
directory. You can create a subdirectory for those files as well.
For example if the file is located
@@ -321,8 +313,8 @@ The below NGINX example configuration will serve files out of the /var/www/nexti
.. code-block:: nginx
server {
- listen 80;
- access_log /var/log/nginx/nextion_access.log;
+ listen 80;
+ access_log /var/log/nginx/nextion_access.log;
error_log /var/log/nginx/nextion_error.log;
root /var/www/nextion;
}
diff --git a/components/display/qspi_amoled.rst b/components/display/qspi_amoled.rst
new file mode 100644
index 000000000..5d65d8b46
--- /dev/null
+++ b/components/display/qspi_amoled.rst
@@ -0,0 +1,186 @@
+Quad SPI AMOLED Displays
+========================
+
+.. seo::
+ :description: Instructions for setting up quad SPI AMOLED displays.
+ :image: t4-s3.jpg
+
+.. _qspi_amoled:
+
+Models
+------
+This display driver supports AMOLED displays with quad SPI interfaces.
+
+This driver has been tested with the following displays:
+
+ - Lilygo T4-S3
+ - Lilygo T-Display S3 AMOLED
+
+Usage
+-----
+This component requires an ESP32 and the use of
+ESP-IDF. PSRAM is a requirement due to the size of the display buffer. A :ref:`quad SPI bus ` interface must be configured.
+
+.. figure:: images/t4-s3.jpg
+ :align: center
+ :width: 75.0%
+
+ Lilygo T4-S3
+
+.. figure:: images/t-display-amoled.jpg
+ :align: center
+ :width: 75.0%
+
+ Lilygo T-Display S3 AMOLED
+
+
+.. code-block:: yaml
+
+ # Example minimal configuration entry
+
+ display:
+ - platform: qspi_amoled
+ model: RM690B0
+ data_rate: 80MHz
+ spi_mode: mode0
+ dimensions:
+ width: 450
+ height: 600
+ offset_width: 16
+ color_order: rgb
+ invert_colors: false
+ brightness: 255
+ cs_pin: GPIOXX
+ reset_pin: GPIOXX
+ enable_pin: GPIOXX
+
+
+Configuration variables:
+************************
+
+- **model** (**Required**): One of ``RM67162`` or ``RM690B0``.
+- **cs_pin** (**Required**, :ref:`Pin Schema `): The chip select pin.
+- **reset_pin** (*Optional*, :ref:`Pin Schema `): The RESET pin.
+- **enable_pin** (*Optional*, :ref:`Pin Schema `): The display enable pin.
+- **brightness** (*Optional*, int): A brightness value in the range 0-255
+- **update_interval** (*Optional*, :ref:`config-time`): The interval to re-draw the screen. Defaults to ``5s``.
+- **auto_clear_enabled** (*Optional*, boolean): Whether to automatically clear the display in each loop (''true'', default),
+ or to keep the existing display content (must overwrite explicitly, e.g., only on data change).
+- **pages** (*Optional*, list): Show pages instead of a single lambda. See :ref:`display-pages`.
+- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
+- **color_order** (*Optional*): Should be one of ``rgb`` (default) or ``bgr``.
+- **dimensions** (**Required**): Dimensions of the screen, specified either as *width* **x** *height* (e.g ``320x240``) or with separate config keys.
+ - **height** (**Required**, int): Specifies height of display in pixels.
+ - **width** (**Required**, int): Specifies width of display.
+ - **offset_width** (*Optional*, int): Specify an offset for the x-direction of the display, typically used when a display is smaller than the maximum supported by the driver chip. Default is 0
+ - **offset_height** (*Optional*, int): Specify an offset for the y-direction of the display. Default is 0.
+
+- **rotation** (*Optional*): Rotate the display presentation in software. Choose one of ``0°``, ``90°``, ``180°``, or ``270°``.
+- **transform** (*Optional*): Transform the display presentation using hardware. All defaults are ``false``. This option cannot be used with ``rotation``.
+
+ - **swap_xy** (*Optional*, boolean): If true, exchange the x and y axes.
+ - **mirror_x** (*Optional*, boolean): If true, mirror the x axis.
+ - **mirror_y** (*Optional*, boolean): If true, mirror the y axis.
+- **data_rate** (*Optional*): Set the data rate of the SPI interface to the display. One of ``80MHz``, ``40MHz``, ``20MHz``, ``10MHz`` (default), ``5MHz``, ``2MHz`` or ``1MHz``.
+- **spi_mode** (*Optional*): Set the mode for the SPI interface to the display. Default is ``MODE0``.
+- **invert_colors** (*Optional*): With this boolean option you can invert the display colors.
+- **lambda** (*Optional*, :ref:`lambda `): The lambda to use for rendering the content on the display.
+ See :ref:`display-engine` for more information.
+
+
+
+Example configurations
+----------------------
+
+
+Lilygo T4-S3
+************
+
+.. code-block:: yaml
+
+ spi:
+ id: quad_spi
+ type: quad
+ clk_pin: 15
+ data_pins: [14, 10, 16, 12]
+
+ i2c:
+ sda: 6
+ scl: 7
+
+ touchscreen:
+ - platform: cst226
+ id: my_touchscreen
+ interrupt_pin: 8
+ reset_pin: 17
+
+ display:
+ - platform: qspi_amoled
+ model: RM690B0
+ data_rate: 80MHz
+ spi_mode: mode0
+ dimensions:
+ width: 450
+ height: 600
+ offset_width: 16
+ color_order: rgb
+ invert_colors: false
+ brightness: 255
+ cs_pin: 11
+ reset_pin: 13
+ enable_pin: 9
+ update_interval: never
+ auto_clear_enabled: false
+
+ psram:
+ mode: octal
+ speed: 80MHz
+
+Lilygo T-Display S3 AMOLED
+**************************
+
+.. code-block:: yaml
+
+ spi:
+ id: quad_spi
+ type: quad
+ clk_pin: 47
+ data_pins:
+ - 18
+ - 7
+ - 48
+ - 5
+
+ i2c:
+ sda: 3
+ scl: 2
+
+ touchscreen:
+ - platform: cst816
+ id: my_touchscreen
+ interrupt_pin:
+ number: 21
+
+ display:
+ - platform: qspi_amoled
+ model: RM67162
+ id: main_lcd
+ dimensions:
+ height: 240
+ width: 536
+ transform:
+ mirror_x: true
+ swap_xy: true
+ color_order: rgb
+ brightness: 255
+ cs_pin: 6
+ reset_pin: 17
+ enable_pin: 38
+
+
+See Also
+--------
+
+- :doc:`index`
+- :apiref:`qspi_amoled/qspi_amoled.h`
+- :ghedit:`Edit`
diff --git a/components/display/st7789v.rst b/components/display/st7789v.rst
index 1395d5d01..e56924b6c 100644
--- a/components/display/st7789v.rst
+++ b/components/display/st7789v.rst
@@ -40,17 +40,13 @@ to an ESP module.
.. code-block:: yaml
# Example minimal configuration entry
- spi:
- clk_pin: GPIO18
- mosi_pin: GPIO19
-
display:
- platform: st7789v
model: TTGO TDisplay 135x240
- backlight_pin: GPIO4
- cs_pin: GPIO5
- dc_pin: GPIO16
- reset_pin: GPIO23
+ backlight_pin: GPIOXX
+ cs_pin: GPIOXX
+ dc_pin: GPIOXX
+ reset_pin: GPIOXX
lambda: |-
it.print(0, 0, id(font), "Hello World!");
@@ -191,7 +187,7 @@ Items marked RQ are hardware dependent but required and not preset. Items marked
- 22
- 23
- 4
- -
+ -
- 18
- 19
* - Custom
diff --git a/components/display/tm1621.rst b/components/display/tm1621.rst
index 169ff2e95..e1619a965 100644
--- a/components/display/tm1621.rst
+++ b/components/display/tm1621.rst
@@ -22,10 +22,10 @@ The LCD have four signal, ``cs`` for chip select, ``data`` for data signal, ``re
display:
platform: tm1621
id: tm1621_display
- cs_pin: GPIO17
- data_pin: GPIO5
- read_pin: GPIO23
- write_pin: GPIO18
+ cs_pin: GPIOXX
+ data_pin: GPIOXX
+ read_pin: GPIOXX
+ write_pin: GPIOXX
lambda: |-
it.printf(0, "%.1f", id(my_sensor1).state);
it.display_celsius(true);
@@ -82,7 +82,7 @@ Also we have five function to display or not some unites:
- °F on the first line : ``display_fahrenheit(bool)``
- %HR on the second line : ``display_humidity(bool)``
- V on the first line and A on the second line : ``display_voltage(bool)``
- - kW/h on the first line and W on the second line : ``display_kwh(bool)``
+ - kW/h on the first line and W on the second line : ``display_kwh(bool)``
See Also
--------
diff --git a/components/display/tm1638.rst b/components/display/tm1638.rst
index 742f1ccbd..025d1ab99 100644
--- a/components/display/tm1638.rst
+++ b/components/display/tm1638.rst
@@ -23,9 +23,9 @@ The module can be powered with 5v DC. To display the colon punctuation use the
display:
platform: tm1638
id: tm1638_display
- stb_pin: 5
- clk_pin: 18
- dio_pin: 23
+ stb_pin: GPIOXX
+ clk_pin: GPIOXX
+ dio_pin: GPIOXX
intensity: 5
update_interval: 5s
lambda: |-
@@ -113,9 +113,9 @@ The following example creates a typical digital clock with the ``:`` colon flash
display:
platform: tm1638
- clk_pin: 18
- dio_pin: 23
- stb_pin: 5
+ clk_pin: GPIOXX
+ dio_pin: GPIOXX
+ stb_pin: GPIOXX
update_interval: 500ms
lambda: |-
static int i = 0;
@@ -132,16 +132,16 @@ The TM1638 7 Segment Display Keypad & LED Module has 8 LED lights across the top
.. code-block:: yaml
- switch:
+ switch:
- platform: tm1638
id: TM1638Led1
led: 0
-
+
output:
- platform: tm1638
id: TM1638Led2
led: 1
-
+
Buttons
@@ -163,7 +163,7 @@ The TM1638 7 Segment Display Keypad & LED Module has 8 buttons across the top or
on_release:
then:
- switch.turn_off: TM1638Led1
-
+
- platform: tm1638
name: "TM1638 Button 2"
id: TM1638Button2
diff --git a/components/display/waveshare_epaper.rst b/components/display/waveshare_epaper.rst
index 44a194a81..73be28b28 100644
--- a/components/display/waveshare_epaper.rst
+++ b/components/display/waveshare_epaper.rst
@@ -23,7 +23,7 @@ single-color E-Ink displays are implemented and of those only a few modules.
Waveshare E-Paper 2.9 Inch E-Paper Display.
-The communication ESPHome has chosen to use for this integration is 4-wire :ref:`SPI `, as it's the most stable
+The communication ESPHome has chosen to use for this component is 4-wire :ref:`SPI `, as it's the most stable
and high-speed. So you need to make sure your board is set to the 4-wire SPI mode and have an ``spi:`` section in your
configuration.
@@ -96,6 +96,7 @@ Configuration variables:
- ``2.70in-b`` - Black/White/Red
- ``2.70in-bv2`` - Black/White/Red
- ``2.90in``
+ - ``2.90in-dke``
- ``2.90inv2``
- ``2.90inv2-r2`` - 2.9in V2 display, but with different initialization and full/partial display refresh management than ``2.90inv2``
- ``2.90in-b`` - B/W rendering only
diff --git a/components/display_menu/graphical_display_menu.rst b/components/display_menu/graphical_display_menu.rst
index 4e70782fc..9949b8b4e 100644
--- a/components/display_menu/graphical_display_menu.rst
+++ b/components/display_menu/graphical_display_menu.rst
@@ -12,14 +12,14 @@ on graphical displays. This offers the user an interactive method to display
labels, control entities like ``switch``, ``select``, ``number`` available locally on the
ESPHome node, without the requirement of a network connection.
-.. figure:: images/graphical_display_menu.jpg
+.. figure:: images/graphical_display_menu.png
:align: center
:width: 60.0%
Overview
--------
-The integration implements the :ref:`Display Menu ` integration providing
+The component implements the :ref:`Display Menu ` component providing
a hierarchical menu primarily intended to be controlled either by a rotary encoder
with a button or a five-button joystick controller.
@@ -34,7 +34,7 @@ engine such as :doc:`E-Paper displays ` or
display: my_display_component
on_redraw:
then:
- component.update: my_dispay_component
+ component.update: my_display_component
active: false
mode: rotary
items:
@@ -194,7 +194,7 @@ The below example is a more complete example showing how you might use a rotary
display: my_display_component
on_redraw:
then:
- component.update: my_dispay_component
+ component.update: my_display_component
active: false
mode: rotary
items:
diff --git a/components/display_menu/images/graphical_display_menu.jpg b/components/display_menu/images/graphical_display_menu.jpg
deleted file mode 100644
index eaed932d3..000000000
Binary files a/components/display_menu/images/graphical_display_menu.jpg and /dev/null differ
diff --git a/components/display_menu/images/graphical_display_menu.png b/components/display_menu/images/graphical_display_menu.png
new file mode 100644
index 000000000..0f624696a
Binary files /dev/null and b/components/display_menu/images/graphical_display_menu.png differ
diff --git a/components/display_menu/index.rst b/components/display_menu/index.rst
index 752c2ae94..9a38ecbf8 100644
--- a/components/display_menu/index.rst
+++ b/components/display_menu/index.rst
@@ -7,7 +7,7 @@ Display Menu
.. _display_menu:
-The integration provides a menu primarily intended to be controlled either by a rotary encoder
+The component provides a menu primarily intended to be controlled either by a rotary encoder
with a button or a five-button joystick controller. It allows to navigate a hierarchy of items
and submenus with the ability to change the values and execute commands. The menu can
be activated and deactivated on demand, allowing alternating between using the screen for
@@ -17,8 +17,8 @@ Overview
--------
This document describes the configuration and automations common for the components implementing
-this integration. At the moment the character based LCD displays are supported using
-the :ref:`lcd_menu ` integration and an instance of this is used in the configuration
+this component. At the moment the character based LCD displays are supported using
+the :ref:`lcd_menu ` component and an instance of this is used in the configuration
examples.
diff --git a/components/display_menu/lcd_menu.rst b/components/display_menu/lcd_menu.rst
index 676c6d474..9645ece37 100644
--- a/components/display_menu/lcd_menu.rst
+++ b/components/display_menu/lcd_menu.rst
@@ -19,7 +19,7 @@ ESPHome node, without the requirement of a network connection.
Overview
--------
-The integration implements the :ref:`Display Menu ` integration providing
+The component implements the :ref:`Display Menu ` component providing
a hierarchical menu primarily intended to be controlled either by a rotary encoder
with a button or a five-button joystick controller.
diff --git a/components/esp32_camera.rst b/components/esp32_camera.rst
index 793e08887..0de4c1ffd 100644
--- a/components/esp32_camera.rst
+++ b/components/esp32_camera.rst
@@ -14,16 +14,16 @@ directly integrate into Home Assistant through the native API.
esp32_camera:
name: My Camera
external_clock:
- pin: GPIO27
+ pin: GPIOXX
frequency: 20MHz
i2c_pins:
- sda: GPIO25
- scl: GPIO23
- data_pins: [GPIO17, GPIO35, GPIO34, GPIO5, GPIO39, GPIO18, GPIO36, GPIO19]
- vsync_pin: GPIO22
- href_pin: GPIO26
- pixel_clock_pin: GPIO21
- reset_pin: GPIO15
+ sda: GPIOXX
+ scl: GPIOXX
+ data_pins: [GPIOXX, GPIOXX, GPIOXX, GPIOXX, GPIOXX, GPIOXX, GPIOXX, GPIOXX]
+ vsync_pin: GPIOXX
+ href_pin: GPIOXX
+ pixel_clock_pin: GPIOXX
+ reset_pin: GPIOXX
resolution: 640x480
jpeg_quality: 10
@@ -37,10 +37,10 @@ Configuration variables:
a ``name`` will implicitly set this to true.
- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
(usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
- Requires Home Assistant 2021.9 or newer. Defaults to ``false``.
+ Defaults to ``false``.
- **entity_category** (*Optional*, string): The category of the entity.
See https://developers.home-assistant.io/docs/core/entity/#generic-properties
- for a list of available options. Requires Home Assistant 2021.11 or newer.
+ for a list of available options.
Set to ``""`` to remove the default entity category.
Connection Options:
@@ -179,7 +179,7 @@ Configuration for Ai-Thinker Camera
.. warning::
- GPIO16 on this board (and possibly other boards below) is connected to onboard PSRAM.
+ 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
diff --git a/components/ethernet.rst b/components/ethernet.rst
index 306dcd098..b10165883 100644
--- a/components/ethernet.rst
+++ b/components/ethernet.rst
@@ -17,8 +17,8 @@ This component and the Wi-Fi component may **not** be used simultaneously, even
# Example configuration entry for RMII chips
ethernet:
type: LAN8720
- mdc_pin: GPIO23
- mdio_pin: GPIO18
+ mdc_pin: GPIOXX
+ mdio_pin: GPIOXX
clk_mode: GPIO0_IN
phy_addr: 0
@@ -33,12 +33,12 @@ This component and the Wi-Fi component may **not** be used simultaneously, even
# Example configuration entry for SPI chips
ethernet:
type: W5500
- clk_pin: GPIO19
- mosi_pin: GPIO21
- miso_pin: GPIO23
- cs_pin: GPIO18
- interrupt_pin: GPIO36
- reset_pin: GPIO22
+ clk_pin: GPIOXX
+ mosi_pin: GPIOXX
+ miso_pin: GPIOXX
+ cs_pin: GPIOXX
+ interrupt_pin: GPIOXX
+ reset_pin: GPIOXX
Configuration variables:
------------------------
@@ -264,7 +264,7 @@ Configuration examples
clk_mode: GPIO17_OUT
phy_addr: 1
-**LILYGO T-ETH-Lite**:
+**LILYGO T-ETH-Lite ESP32**:
.. code-block:: yaml
diff --git a/components/event/index.rst b/components/event/index.rst
new file mode 100644
index 000000000..85004ac46
--- /dev/null
+++ b/components/event/index.rst
@@ -0,0 +1,147 @@
+Event Component
+===============
+
+.. seo::
+ :description: Instructions for setting up event components in ESPHome.
+ :image: folder-open.svg
+
+ESPHome supports the creation of event entities in Home Assistant.
+These entities allow for the triggering of custom events within the Home Assistant ecosystem,
+enabling complex automations and integrations. An event entity is represented as a stateless
+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 :ref:`Home Assistant event ` instead.
+
+
+.. note::
+
+ Home Assistant Core 2024.5 or higher is required for ESPHome event entities to work.
+
+.. _config-event:
+
+Base Event Configuration
+------------------------
+
+Each event in ESPHome needs to be configured with a list of event types it can trigger and an optional device class.
+
+.. code-block:: yaml
+
+ # Example event configuration
+ event:
+ - platform: ...
+ name: Motion Detected Event
+ id: my_event
+
+ # Optional variables:
+ icon: "mdi:motion-sensor"
+ device_class: "motion"
+ on_event:
+ then:
+ - logger.log: "Event triggered"
+
+Configuration variables:
+
+One of ``id`` or ``name`` is required.
+
+- **id** (**Required**, :ref:`config-id`): Manually specify the ID used for code generation, allowing for further customization or interaction with this event within ESPHome scripts or lambda functions.
+- **name** (**Required**, string): The name for the event.
+
+ .. note::
+
+ If you have a :ref:`friendly_name ` 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
+ not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without
+ a ``name`` will implicitly set this to true.
+- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
+ (usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
+- **entity_category** (*Optional*, string): The category of the entity.
+ See https://developers.home-assistant.io/docs/core/entity/#generic-properties
+ for a list of available options. Set to ``""`` to remove the default entity category.
+- **device_class** (*Optional*, string): The device class for the event. The following device classes are supported by event entities:
+
+ - None: Generic event. This is the default and doesn't need to be set.
+ - ``button``: For remote control buttons.
+ - ``doorbell``: Specifically for buttons that are used as a doorbell.
+ - ``motion``: For motion events detected by a motion sensor.
+
+ See https://www.home-assistant.io/integrations/event/#device-class
+ for a list of available options.
+
+Automations:
+
+- **on_event** (*Optional*, :ref:`Automation `): An automation to perform when an event is triggered.
+
+MQTT options:
+
+- All other options from :ref:`MQTT Component `.
+
+Event Automation
+----------------
+
+.. _event-on_event:
+
+``on_event``
+************
+
+This automation will be triggered when an event of the specified types is triggered.
+
+.. code-block:: yaml
+
+ event:
+ - platform: template
+ # ...
+ on_event:
+ then:
+ - logger.log: "Event Triggered"
+
+Configuration variables: see :ref:`Automation `.
+
+``event.trigger`` Action
+************************
+
+This action allows for the triggering of an event from within an automation.
+
+.. code-block:: yaml
+
+ - event.trigger:
+ id: my_event
+ event_type: "custom_event"
+
+Configuration variables:
+
+- **id** (**Required**, :ref:`config-id`): The ID of the event.
+- **event_type** (**Required**, string): The type of event to trigger.
+
+.. _event-lambda_calls:
+
+lambda Calls
+************
+
+From :ref:`lambdas `, you can trigger an event.
+
+- ``trigger(std::string event_type)``: Trigger an event with the specified type.
+
+ .. code-block:: cpp
+
+ // Within lambda, trigger the event.
+ id(my_event).trigger("custom_event");
+
+See Also
+--------
+
+- :apiref:`event/event.h`
+- :ghedit:`Edit`
+
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ *
diff --git a/components/event/template.rst b/components/event/template.rst
new file mode 100644
index 000000000..d0a8d5533
--- /dev/null
+++ b/components/event/template.rst
@@ -0,0 +1,31 @@
+Template Event
+==============
+
+.. seo::
+ :description: Instructions for setting up template events that can trigger arbitrary automations when an event occurs.
+ :image: description.svg
+
+The ``template`` event platform enables you to define events that trigger specific automations or actions within Home Assistant. These custom events can be utilized to orchestrate complex behaviors across your smart home ecosystem based on conditions or sequences defined in your ESPHome configuration.
+
+.. code-block:: yaml
+
+ # Example configuration entry
+ event:
+ - platform: template
+ name: "Template Event"
+ event_types:
+ - "custom_event_1"
+ - "custom_event_2"
+
+Configuration variables:
+------------------------
+
+- **event_types** (**Required**, list): A list of custom event identifiers that this template event is capable of triggering. These identifiers can be used in Home Assistant automations or ESPHome scripts to perform actions when the event occurs.
+- All other options from :ref:`Event `.
+
+See Also
+--------
+
+- :doc:`/guides/automations`
+- :doc:`/components/event/index`
+- :ghedit:`Edit`
diff --git a/components/exposure_notifications.rst b/components/exposure_notifications.rst
index 75f323de3..1007cf55f 100644
--- a/components/exposure_notifications.rst
+++ b/components/exposure_notifications.rst
@@ -52,7 +52,7 @@ minute, the indicator will be on.
switch:
- platform: gpio
- pin: GPIO22
+ pin: GPIOXX
id: led
script:
diff --git a/components/external_components.rst b/components/external_components.rst
index 32a89747b..d24482171 100644
--- a/components/external_components.rst
+++ b/components/external_components.rst
@@ -46,6 +46,7 @@ Configuration variables:
- **ref** (*Optional*, string): Git ref (branch or tag). If not specified the default branch is used.
- **username** (*Optional*, string): Username for the Git server, if one is required
- **password** (*Optional*, string): Password for the Git server, if one is required
+ - **path** (*Optional*, string): Path inside the repo, if different from ``components`` or ``esphome/components``
local options:
diff --git a/components/fan/binary.rst b/components/fan/binary.rst
index eefad56e1..c7328c5e7 100644
--- a/components/fan/binary.rst
+++ b/components/fan/binary.rst
@@ -14,18 +14,13 @@ The ``binary`` fan platform lets you represent any binary :ref:`output` as a fan
.. code-block:: yaml
# Example configuration entry
- output:
- - id: fan_output
- platform: gpio
- pin: GPIO16
-
fan:
- platform: binary
output: fan_output
name: "Living Room Fan"
-
-
-
+
+
+
Configuration variables:
------------------------
diff --git a/components/fan/hbridge.rst b/components/fan/hbridge.rst
index 4ed716697..7e4295f8c 100644
--- a/components/fan/hbridge.rst
+++ b/components/fan/hbridge.rst
@@ -23,14 +23,6 @@ The ``hbridge`` fan platform allows you to use a compatible *h-bridge* (L298N, D
.. code-block:: yaml
# Example configuration entry
- output:
- - platform: ...
- id: motor_forward_pin
- pin: GPIO5
- - platform: ...
- id: motor_reverse_pin
- pin: GPIO4
-
fan:
- platform: hbridge
id: my_fan
diff --git a/components/fan/index.rst b/components/fan/index.rst
index 415e3d562..08039308a 100644
--- a/components/fan/index.rst
+++ b/components/fan/index.rst
@@ -49,10 +49,10 @@ Configuration variables:
a ``name`` will implicitly set this to true.
- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend
(usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
- Requires Home Assistant 2021.9 or newer. Defaults to ``false``.
+ Defaults to ``false``.
- **entity_category** (*Optional*, string): The category of the entity.
See https://developers.home-assistant.io/docs/core/entity/#generic-properties
- for a list of available options. Requires Home Assistant 2021.11 or newer.
+ for a list of available options.
Set to ``""`` to remove the default entity category.
MQTT options:
diff --git a/components/fingerprint_grow.rst b/components/fingerprint_grow.rst
index c36a2e2c1..cdba66074 100644
--- a/components/fingerprint_grow.rst
+++ b/components/fingerprint_grow.rst
@@ -2,7 +2,7 @@ Grow Fingerprint Reader
=======================
.. seo::
- :description: Instructions for setting up Grow Fingerprint Reader integration in ESPHome.
+ :description: Instructions for setting up Grow Fingerprint Reader component in ESPHome.
:image: fingerprint.svg
The ``fingerprint_grow`` component allows you to use your R307, R503, R503-RGB, ZFM-20, ... fingerprint sensors with ESPHome.
@@ -30,16 +30,10 @@ If available on your reader model, it's recommended to connect 3.3VT (touch indu
.. code-block:: yaml
# Example configuration entry
- uart:
- rx_pin: GPIO13
- tx_pin: GPIO15
- baud_rate: 57600
-
- # Declare Grow Fingerprint Reader
fingerprint_grow:
- sensing_pin: GPIO12
+ sensing_pin: GPIOXX
sensor_power_pin:
- number: GPIO18
+ number: GPIOXX
inverted: true
idle_period_to_sleep: 5s
@@ -93,46 +87,27 @@ Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- All other options from :ref:`Binary Sensor `.
-Optional Sensor Configuration:
Sensor
------
- **fingerprint_count**: The number of enrolled fingerprints stored on the reader.
-
- - **name** (**Required**, string): The name for the sensor.
- - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- - All other options from :ref:`Sensor `.
+ All options from :ref:`Sensor `.
- **last_finger_id**: The last matched enrolled fingerprint as set by :ref:`fingerprint_grow-on_finger_scan_matched`.
-
- - **name** (**Required**, string): The name for the sensor.
- - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- - All other options from :ref:`Sensor `.
+ All options from :ref:`Sensor `.
- **last_confidence**: The last matched confidence as set by :ref:`fingerprint_grow-on_finger_scan_matched`.
-
- - **name** (**Required**, string): The name for the sensor.
- - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- - All other options from :ref:`Sensor `.
+ All options from :ref:`Sensor `.
- **status**: The integer representation of the internal status register of the reader.
-
- - **name** (**Required**, string): The name for the sensor.
- - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- - All other options from :ref:`Sensor `.
+ All options from :ref:`Sensor `.
- **capacity**: The fingerprint storage capacity of the reader.
-
- - **name** (**Required**, string): The name for the sensor.
- - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- - All other options from :ref:`Sensor `.
+ All options from :ref:`Sensor `.
- **security_level**: The integer representation of the currently configured security level of the reader. Higher security levels reduce the false acceptance rate (FAR) at the expense of increasing the false rejection rate (FRR). Range is 1 (lowest) to 5 (highest).
-
- - **name** (**Required**, string): The name for the sensor.
- - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- - All other options from :ref:`Sensor `.
+ All options from :ref:`Sensor `.
.. _fingerprint_grow-sleep_mode:
@@ -150,14 +125,14 @@ This is a wiring example for the R503 and below you can find the respective conf
.. code-block:: yaml
uart:
- rx_pin: GPIO16
- tx_pin: GPIO17
+ rx_pin: GPIOXX
+ tx_pin: GPIOXX
baud_rate: 57600
-
+
fingerprint_grow:
- sensing_pin: GPIO4
+ sensing_pin: GPIOXX
sensor_power_pin:
- number: GPIO18
+ number: GPIOXX
inverted: true
idle_period_to_sleep: 5s
@@ -191,7 +166,7 @@ The ``new_password:`` configuration option is meant to be compiled, flashed to t
``on_finger_scan_start`` Trigger
------------------------------------
-With this configuration option, you can trigger an automation when a finger is detected touching the sensor. Very useful to indicate to the user via AuraLed that the sensor has detected the finger touch and will perform the scan. This trigger will **only** activate if your fingerprint sensor is configured with the ``sensing_pin`` option.
+With this configuration option, you can trigger an automation when a finger is detected touching the sensor. Very useful to indicate to the user via AuraLed that the sensor has detected the finger touch and will perform the scan. This trigger will **only** activate if your fingerprint sensor is configured with the ``sensing_pin`` option.
.. code-block:: yaml
@@ -513,12 +488,12 @@ Sample code
.. code-block:: yaml
uart:
- rx_pin: GPIO13
- tx_pin: GPIO15
+ rx_pin: GPIOXX
+ tx_pin: GPIOXX
baud_rate: 57600
fingerprint_grow:
- sensing_pin: GPIO12
+ sensing_pin: GPIOXX
on_finger_scan_invalid:
- homeassistant.event:
event: esphome.test_node_finger_scan_invalid
diff --git a/components/gps.rst b/components/gps.rst
index a391a2c46..94a4efbc0 100644
--- a/components/gps.rst
+++ b/components/gps.rst
@@ -2,7 +2,7 @@ GPS Component
=============
.. seo::
- :description: Instructions for setting up GPS integration in ESPHome.
+ :description: Instructions for setting up GPS component in ESPHome.
:image: crosshairs-gps.svg
The ``gps`` component allows you to connect GPS modules to your ESPHome project.
@@ -16,15 +16,12 @@ Any GPS module that uses the standardized NMEA communication protocol will work.
.. _Adafruit: https://www.adafruit.com/product/746
-For this integration to work you need to have set up a :ref:`UART bus `
+For this component to work you need to have set up a :ref:`UART bus `
in your configuration - only the RX pin should be necessary.
.. code-block:: yaml
# Example configuration entry
- uart:
- rx_pin: D7
- baud_rate: 9600
# Declare GPS module
gps:
diff --git a/components/i2c.rst b/components/i2c.rst
index 9e16eacdb..a4fe7a4df 100644
--- a/components/i2c.rst
+++ b/components/i2c.rst
@@ -20,8 +20,8 @@ connecting the wires from each device back to the two I²C pins on the ESP.
# Example configuration entry for ESP32
i2c:
- sda: 21
- scl: 22
+ sda: GPIOXX
+ scl: GPIOXX
scan: true
id: bus_a
@@ -37,6 +37,9 @@ Configuration variables:
Defaults to ``true``.
- **frequency** (*Optional*, float): Set the frequency the I²C bus should operate on.
Defaults to ``50kHz``. Values are ``10kHz``, ``50kHz``, ``100kHz``, ``200kHz``, ... ``800kHz``
+- **timeout** (*Optional*, :ref:`config-time`): Set the I²C bus timeout.
+ Defaults to the framework defaults (``100us`` on ``esp32`` with ``esp-idf``, ``50ms`` on ``esp32`` with ``Arduino``,
+ ``1s`` on ``esp8266`` and ``1s`` on ``rp2040``). Maximum on ``esp-idf`` is 13ms.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID for this I²C bus if you need multiple I²C buses.
.. note::
@@ -48,12 +51,12 @@ Configuration variables:
# Example configuration entry
i2c:
- id: bus_a
- sda: 13
- scl: 16
+ sda: GPIOXX
+ scl: GPIOXX
scan: true
- id: bus_b
- sda: 14
- scl: 15
+ sda: GPIOXX
+ scl: GPIOXX
scan: true
# Sensors should be specified as follows
- platform: bme680
diff --git a/components/i2s_audio.rst b/components/i2s_audio.rst
index 3eb07a8f6..424fc5b1d 100644
--- a/components/i2s_audio.rst
+++ b/components/i2s_audio.rst
@@ -14,8 +14,8 @@ This component only works on ESP32 based chips.
# Example configuration entry
i2s_audio:
- i2s_lrclk_pin: GPIO33
- i2s_bclk_pin: GPIO19
+ i2s_lrclk_pin: GPIOXX
+ i2s_bclk_pin: GPIOXX
Configuration variables:
------------------------
diff --git a/components/images/DFR0627.jpg b/components/images/DFR0627.jpg
new file mode 100644
index 000000000..5a112ccc9
Binary files /dev/null and b/components/images/DFR0627.jpg differ
diff --git a/components/images/fingeprint_grow-sleep_mode_wiring.jpg b/components/images/fingeprint_grow-sleep_mode_wiring.jpg
index c4d319560..76b3a0230 100644
Binary files a/components/images/fingeprint_grow-sleep_mode_wiring.jpg and b/components/images/fingeprint_grow-sleep_mode_wiring.jpg differ
diff --git a/components/images/micronova_optocouplers.png b/components/images/micronova_optocouplers.png
index ee08139c8..a4660699e 100644
Binary files a/components/images/micronova_optocouplers.png and b/components/images/micronova_optocouplers.png differ
diff --git a/components/images/micronova_serial.png b/components/images/micronova_serial.png
index 86a2f8de2..d444f344e 100644
Binary files a/components/images/micronova_serial.png and b/components/images/micronova_serial.png differ
diff --git a/components/images/micronova_serial_layout.png b/components/images/micronova_serial_layout.png
index 60be6fc25..3dc40c24a 100644
Binary files a/components/images/micronova_serial_layout.png and b/components/images/micronova_serial_layout.png differ
diff --git a/components/images/rj45_pinout.jpg b/components/images/rj45_pinout.jpg
index ce898adeb..177338c8e 100644
Binary files a/components/images/rj45_pinout.jpg and b/components/images/rj45_pinout.jpg differ
diff --git a/components/images/seeed-mr24hpc1-mmwave-kit.png b/components/images/seeed-mr24hpc1-mmwave-kit.png
index effbc383e..a01a4a1f1 100644
Binary files a/components/images/seeed-mr24hpc1-mmwave-kit.png and b/components/images/seeed-mr24hpc1-mmwave-kit.png differ
diff --git a/components/images/seeed-mr24hpc1.jpg b/components/images/seeed-mr24hpc1.jpg
index 416d901b7..80426a813 100644
Binary files a/components/images/seeed-mr24hpc1.jpg and b/components/images/seeed-mr24hpc1.jpg differ
diff --git a/components/images/sun_gtil2_controller_board.png b/components/images/sun_gtil2_controller_board.png
new file mode 100644
index 000000000..869a676c1
Binary files /dev/null and b/components/images/sun_gtil2_controller_board.png differ
diff --git a/components/images/sun_gtil2_display_board.png b/components/images/sun_gtil2_display_board.png
new file mode 100644
index 000000000..39c05fea8
Binary files /dev/null and b/components/images/sun_gtil2_display_board.png differ
diff --git a/components/images/sun_gtil2_schematic.png b/components/images/sun_gtil2_schematic.png
new file mode 100644
index 000000000..347311f25
Binary files /dev/null and b/components/images/sun_gtil2_schematic.png differ
diff --git a/components/index.rst b/components/index.rst
index b9aba9769..b1f4c8739 100644
--- a/components/index.rst
+++ b/components/index.rst
@@ -17,6 +17,7 @@ Components
sensor/index
switch/index
button/index
+ event/index
display/index
text_sensor/index
stepper/index
@@ -29,4 +30,5 @@ Components
time/index
alarm_control_panel/index
text/index
+ valve/index
*
diff --git a/components/light/binary.rst b/components/light/binary.rst
index 43e1ee7bc..4a3bf44e5 100644
--- a/components/light/binary.rst
+++ b/components/light/binary.rst
@@ -20,10 +20,6 @@ The ``binary`` light platform creates a simple ON/OFF-only light from a
name: "Desk Lamp"
output: light_output
- output:
- - id: light_output
- platform: gpio
- pin: GPIO16
Configuration variables:
------------------------
diff --git a/components/light/custom.rst b/components/light/custom.rst
index 03353f6f1..0ebf96564 100644
--- a/components/light/custom.rst
+++ b/components/light/custom.rst
@@ -1,21 +1,27 @@
Custom Light Output
===================
+.. seo::
+ :description: Instructions for setting up Custom C++ lights with ESPHome.
+ :image: language-cpp.svg
+ :keywords: C++, Custom
+
.. warning::
- Custom components are deprecated, not recommended for new configurations
- and will be removed from ESPHome in a future release.
- Please look at creating a real ESPHome component and "importing" it into your
- configuration with :doc:`/components/external_components`.
+ Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
+ future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
+ :doc:`/components/external_components`.
- You can find some basic documentation on creating your own components
- at :ref:`contributing_to_esphome`.
+ You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
-This integration can be used to create custom lights in ESPHome
-using the C++ (Arduino) API.
+.. warning::
-Please first read :doc:`/components/sensor/custom` guide,
-the same principles apply here.
+ While we try to keep the ESPHome YAML configuration options as stable as possible, the ESPHome API is less
+ stable. If something in the APIs needs to be changed in order for something else to work, we will do so.
+
+This component can be used to create custom lights in ESPHome using the C++ (Arduino) API.
+
+Please first read :doc:`/components/sensor/custom` guide, the same principles apply here.
All internal stuff (like effects, transitions etc) is handled by the light core
and cannot be overridden. Light outputs are only responsible for displaying some state
diff --git a/components/light/esp32_rmt_led_strip.rst b/components/light/esp32_rmt_led_strip.rst
index 45df3de40..cb1914244 100644
--- a/components/light/esp32_rmt_led_strip.rst
+++ b/components/light/esp32_rmt_led_strip.rst
@@ -12,7 +12,7 @@ This is a component using the ESP32 RMT peripheral to drive most addressable LED
light:
- platform: esp32_rmt_led_strip
rgb_order: GRB
- pin: GPIO13
+ pin: GPIOXX
num_leds: 30
rmt_channel: 0
chipset: ws2812
@@ -24,10 +24,14 @@ Configuration variables
- **pin** (**Required**, :ref:`config-pin`): The pin for the data line of the light.
- **num_leds** (**Required**, int): The number of LEDs in the strip.
- **rmt_channel** (**Required**, int): The RMT channel to use. If using multiple strips, you need to use different channels.
- - **ESP32**: ``0`` to ``7``
- - **ESP32-S2**: ``0`` to ``3``
- - **ESP32-S3**: ``0`` to ``3``
- - **ESP32-C3**: ``0`` or ``1``
+
+ .. csv-table::
+ :header: "ESP32 Variant", "Channels"
+
+ "ESP32", "0, 1, 2, 3, 4, 5, 6, 7"
+ "ESP32-S2", "0, 1, 2, 3"
+ "ESP32-S3", "0, 1, 2, 3"
+ "ESP32-C3", "0, 1"
- **chipset** (**Required**, enum): The chipset to apply known timings from. Not used if specifying the timings manually, see below.
- ``WS2812``
diff --git a/components/light/fastled.rst b/components/light/fastled.rst
index 41c61a060..f1799fca0 100644
--- a/components/light/fastled.rst
+++ b/components/light/fastled.rst
@@ -47,7 +47,7 @@ Clockless FastLED lights differ from the
light:
- platform: fastled_clockless
chipset: WS2811
- pin: GPIO23
+ pin: GPIOXX
num_leds: 60
rgb_order: BRG
name: "FastLED WS2811 Light"
@@ -126,8 +126,8 @@ whereas the clockless lights only need a single pin.
light:
- platform: fastled_spi
chipset: WS2801
- data_pin: GPIO23
- clock_pin: GPIO22
+ data_pin: GPIOXX
+ clock_pin: GPIOXX
num_leds: 60
rgb_order: BRG
name: "FastLED SPI Light"
diff --git a/components/light/hbridge.rst b/components/light/hbridge.rst
index 6dcd095d6..07b8c23cc 100644
--- a/components/light/hbridge.rst
+++ b/components/light/hbridge.rst
@@ -12,23 +12,12 @@ The ``hbridge`` light platform creates a dual color brightness controlled light
:align: center
:width: 40.0%
-H-bridge lights are very common for Christmas lighting and they use 2 wires for a bunch of LEDs.
+H-bridge lights are very common for Christmas lighting and they use 2 wires for a bunch of LEDs.
The pins are switched alternatively to allow two sets of lights to operate.
.. code-block:: yaml
# Example configuration entry
-
- # Specify the two pins of the h-bridge as PWM pins
- output:
- - platform: esp8266_pwm
- id: pina
- pin: GPIO12
- - platform: esp8266_pwm
- id: pinb
- pin: GPIO14
-
- # Create a light using the hbridge
light:
- platform: hbridge
id: mainlight
diff --git a/components/light/index.rst b/components/light/index.rst
index c57c9470a..2f3550a14 100644
--- a/components/light/index.rst
+++ b/components/light/index.rst
@@ -77,10 +77,10 @@ Advanced options:
a ``name`` will implicitly set this to true.
- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
(usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
- Requires Home Assistant 2021.9 or newer. Defaults to ``false``.
+ Defaults to ``false``.
- **entity_category** (*Optional*, string): The category of the entity.
See https://developers.home-assistant.io/docs/core/entity/#generic-properties
- for a list of available options. Requires Home Assistant 2021.11 or newer.
+ for a list of available options.
Set to ``""`` to remove the default entity category.
- If MQTT enabled, all other options from :ref:`MQTT Component `.
@@ -583,6 +583,7 @@ Configuration variables:
- **cold_white** (*Optional*, percentage): The cold white channel of the light, if applicable. Defaults to ``100%``.
- **warm_white** (*Optional*, percentage): The warm white channel of the light, if applicable. Defaults to ``100%``.
- **duration** (**Required**, :ref:`config-time`): The duration this color should be active.
+ - **transition_length** (*Optional*, :ref:`config-time`): The duration of each transition. Defaults to ``0s``.
See `light.turn_on ` for more information on the various color fields.
diff --git a/components/light/monochromatic.rst b/components/light/monochromatic.rst
index 2b86555d2..c24a9787a 100644
--- a/components/light/monochromatic.rst
+++ b/components/light/monochromatic.rst
@@ -26,11 +26,6 @@ The ``monochromatic`` light platform creates a simple brightness-only light from
name: "Kitchen Lights"
output: output_component1
- # Example output entry
- output:
- - platform: esp8266_pwm
- id: output_component1
- pin: D1
Configuration variables:
------------------------
diff --git a/components/light/neopixelbus.rst b/components/light/neopixelbus.rst
index 271af0c6e..852978677 100644
--- a/components/light/neopixelbus.rst
+++ b/components/light/neopixelbus.rst
@@ -18,7 +18,7 @@ in ESPHome for individually addressable lights like NeoPixel or WS2812.
It is very similar to the :doc:`fastled` platform.
In fact, most addressable lights are supported through both light platforms. The
difference is that they use different libraries: while the fastled platform uses
-the `FastLED `__ library, this integration uses
+the `FastLED `__ library, this component uses
the `NeoPixelBus ` can theoretically be used.
@@ -48,7 +48,7 @@ Configuration variables:
- **brightness_global** (*Optional*): Set the value of the current to be sink by all pins configured as led driver.
Defaults to ``0``
- **brightness_mode** (*Optional*): Define if the current to be sink will be confgured globaly or per pin configured as led driver.
- Defaults to ``global``
+ Defaults to ``global``
Binary Sensor Example
@@ -58,19 +58,7 @@ Binary Sensor Example
.. code-block:: yaml
- # Example configuration : pin as input with pullup
- i2c:
- id: bus_a
- sda: GPIO13
- scl: GPIO16
- scan: false
-
- max6956:
- - id: max6956_1
- address: 0x40
- i2c_id: bus_a
-
- # Individual input
+ # Example configuration
binary_sensor:
- platform: gpio
name: "MaxIn Pin 4"
@@ -78,7 +66,7 @@ Binary Sensor Example
pin:
max6956: max6956_1
number: 4
- mode:
+ mode:
input: true
pullup: true
inverted: False
@@ -91,18 +79,7 @@ Switch Example
.. code-block:: yaml
- # Example configuration : pin as output
- i2c:
- id: bus_a
- sda: GPIO13
- scl: GPIO16
-
- max6956:
- - id: max6956_1
- address: 0x40
- i2c_id: bus_a
-
- # Individual output
+ # Example configuration
switch:
- platform: gpio
name: "MaxIn Pin 8"
@@ -110,9 +87,9 @@ Switch Example
pin:
max6956: max6956_1
number: 8
- mode:
+ mode:
output: true
- inverted: False
+ inverted: False
Led driver Example
@@ -126,8 +103,8 @@ Led driver Example
# Example configuration : pin as led driver, current globaly
i2c:
id: bus_a
- sda: GPIO13
- scl: GPIO16
+ sda: GPIOXX
+ scl: GPIOXX
switch:
- platform: template
@@ -153,7 +130,7 @@ Led driver Example
- max6956.set_brightness_global:
id: max6956_1
brightness_global: !lambda return x;
-
+
max6956:
- id: max6956_1
address: 0x40
@@ -166,7 +143,7 @@ Led driver Example
- platform: max6956
pin: 4
id: maxOut_pin4
-
+
#led binded to output
light:
- platform: monochromatic
@@ -178,8 +155,8 @@ Led driver Example
# Example configuration : pin as led driver, current managed individualy (RBG led)
i2c:
id: bus_a
- sda: GPIO13
- scl: GPIO16
+ sda: GPIOXX
+ scl: GPIOXX
max6956:
- id: max6956_1
@@ -229,7 +206,7 @@ Led driver Example
- output.set_level:
id: maxOut_pin4
level: !lambda return x/100;
-
+
- platform: template
name: "Number Green"
id: number_LedGreen
@@ -256,7 +233,7 @@ Led driver Example
on_value:
- output.set_level:
id: maxOut_pin6
- level: !lambda return x/100;
+ level: !lambda return x/100;
output:
- platform: max6956
pin: 4
@@ -275,7 +252,7 @@ Led driver Example
gamma_correct: 1
red: maxOut_pin4
green: maxOut_pin5
- blue: maxOut_pin6
+ blue: maxOut_pin6
diff --git a/components/mcp23Sxx.rst b/components/mcp23Sxx.rst
index c058eaf65..af26d0876 100644
--- a/components/mcp23Sxx.rst
+++ b/components/mcp23Sxx.rst
@@ -26,7 +26,7 @@ The MCP23S08 component (`datasheet `): The GPIO pin to use to mute the media player.
- **mode** (*Optional*, string): The mode of the I²S bus. Can be ``mono`` or ``stereo``. Defaults to ``mono``.
- **i2s_audio_id** (*Optional*, :ref:`config-id`): The ID of the :ref:`I²S Audio ` you wish to use for this media player.
-- **i2s_comm_fmt** (*Optional*, string): I2S communication format. By default MSB format is used (AC101, PCM5102A).
- Set to ``lsb`` if using an external DAC that uses Japanese (Least Significant Bit Justified) format (like PT8211).
+- **i2s_comm_fmt** (*Optional*, string): I2S communication format. By default MSB format is used (AC101, PCM5102A).
+ Set to ``lsb`` if using an external DAC that uses Japanese (Least Significant Bit Justified) format (like PT8211).
Can be ``msb`` or ``lsb``. Defaults to ``msb``.
For best results, keep the wires as short as possible.
diff --git a/components/micronova.rst b/components/micronova.rst
index 8ccda83bd..f350588c2 100644
--- a/components/micronova.rst
+++ b/components/micronova.rst
@@ -18,7 +18,7 @@ The :ref:`UART ` must be configured with a baud rate 1200, 8 data bits, 2
Also, switching your stove on or off can behave different on the various MicroNova flavours.
- Use this integration at your own risk.
+ Use this component at your own risk.
Connecting your stove
---------------------
diff --git a/components/microphone/i2s_audio.rst b/components/microphone/i2s_audio.rst
index 468a0e1db..7e84843f9 100644
--- a/components/microphone/i2s_audio.rst
+++ b/components/microphone/i2s_audio.rst
@@ -24,12 +24,12 @@ This platform only works on ESP32 based chips.
- platform: i2s_audio
id: external_mic
adc_type: external
- i2s_din_pin: GPIO23
+ i2s_din_pin: GPIOXX
- platform: i2s_audio
id: adc_mic
adc_type: internal
- adc_pin: GPIO35
+ adc_pin: GPIOXX
Configuration variables:
@@ -80,7 +80,7 @@ M5Stack Atom Echo
microphone:
- platform: i2s_audio
adc_type: external
- i2s_din_pin: GPIO23
+ i2s_din_pin: GPIOXX
pdm: true
RaspiAudio Muse Luxe
@@ -90,7 +90,7 @@ RaspiAudio Muse Luxe
microphone:
- platform: i2s_audio
- i2s_din_pin: GPIO35
+ i2s_din_pin: GPIOXX
adc_type: external
pdm: false
diff --git a/components/modbus_controller.rst b/components/modbus_controller.rst
index c21b0a13e..00fcfd135 100644
--- a/components/modbus_controller.rst
+++ b/components/modbus_controller.rst
@@ -78,7 +78,7 @@ Technically there is no difference between the "inline" and the standard definit
...
modbus:
- flow_control_pin: 5
+ flow_control_pin: GPIOXX
id: modbus1
modbus_controller:
@@ -129,43 +129,43 @@ Bitmasks
Some devices use decimal values in read registers to show multiple binary states occupying only one register address. To decode them, you can use bitmasks according to the table below. The decimal value corresponding to a bit is always double of the previous one in the row. Multiple bits can be represented in a single register by making a sum of all the values corresponding to the bits.
-+------------+------------------+-----------+-----------+
++------------+------------------+-----------+-----------+
| Alarm bit | Description | DEC value | HEX value |
-+============+==================+===========+===========+
++============+==================+===========+===========+
| bit 0 | Binary Sensor 0 | 1 | 1 |
-+------------+------------------+-----------+-----------+
++------------+------------------+-----------+-----------+
| bit 1 | Binary Sensor 1 | 2 | 2 |
-+------------+------------------+-----------+-----------+
++------------+------------------+-----------+-----------+
| bit 2 | Binary Sensor 2 | 4 | 4 |
-+------------+------------------+-----------+-----------+
++------------+------------------+-----------+-----------+
| bit 3 | Binary Sensor 3 | 8 | 8 |
-+------------+------------------+-----------+-----------+
++------------+------------------+-----------+-----------+
| bit 4 | Binary Sensor 4 | 16 | 10 |
-+------------+------------------+-----------+-----------+
++------------+------------------+-----------+-----------+
| bit 5 | Binary Sensor 5 | 32 | 20 |
-+------------+------------------+-----------+-----------+
++------------+------------------+-----------+-----------+
| bit 6 | Binary Sensor 6 | 64 | 40 |
-+------------+------------------+-----------+-----------+
++------------+------------------+-----------+-----------+
| bit 7 | Binary Sensor 7 | 128 | 80 |
-+------------+------------------+-----------+-----------+
++------------+------------------+-----------+-----------+
| bit 8 | Binary Sensor 8 | 256 | 100 |
-+------------+------------------+-----------+-----------+
++------------+------------------+-----------+-----------+
| bit 9 | Binary Sensor 9 | 512 | 200 |
-+------------+------------------+-----------+-----------+
++------------+------------------+-----------+-----------+
| bit 10 | Binary Sensor 10 | 1024 | 400 |
-+------------+------------------+-----------+-----------+
++------------+------------------+-----------+-----------+
| bit 11 | Binary Sensor 11 | 2048 | 800 |
-+------------+------------------+-----------+-----------+
++------------+------------------+-----------+-----------+
| bit 12 | Binary Sensor 12 | 4096 | 1000 |
-+------------+------------------+-----------+-----------+
++------------+------------------+-----------+-----------+
| bit 13 | Binary Sensor 13 | 8192 | 2000 |
-+------------+------------------+-----------+-----------+
++------------+------------------+-----------+-----------+
| bit 14 | Binary Sensor 14 | 16384 | 4000 |
-+------------+------------------+-----------+-----------+
++------------+------------------+-----------+-----------+
| bit 15 | Binary Sensor 15 | 32768 | 8000 |
-+------------+------------------+-----------+-----------+
++------------+------------------+-----------+-----------+
-In the example below, register ``15``, holds several binary values. It stores the decimal value ``12288``, which is the sum of ``4096`` + ``8192``, meaning the corresponding bits ``12`` and ``13`` are ``1``, the other bits are ``0``.
+In the example below, register ``15``, holds several binary values. It stores the decimal value ``12288``, which is the sum of ``4096`` + ``8192``, meaning the corresponding bits ``12`` and ``13`` are ``1``, the other bits are ``0``.
To gather some of these bits as binary sensors in ESPHome, use ``bitmask``:
@@ -513,7 +513,7 @@ The response is mapped to the sensor based on ``register_count`` and offset in b
The code synchronizes the localtime of MCU to the epever controller
The time is set by writing 12 bytes to register 0x9013.
Then battery charge settings are sent.
-
+
.. code-block:: yaml
esphome:
@@ -565,7 +565,7 @@ The response is mapped to the sensor based on ``register_count`` and offset in b
0x04BA, // 900d Low Volt. Disconnect Volt. 11.8
0x04BA // 900E Discharging Limit Voltage 11.8
};
-
+
// Boost and equalization periods
std::vector battery_settings2 = {
0x0000, // 906B Equalize Duration (min.) 0
@@ -574,7 +574,7 @@ The response is mapped to the sensor based on ``register_count`` and offset in b
esphome::modbus_controller::ModbusCommandItem set_battery1_command =
esphome::modbus_controller::ModbusCommandItem::create_write_multiple_command(controller, 0x9000, battery_settings1.size() ,
battery_settings1);
-
+
esphome::modbus_controller::ModbusCommandItem set_battery2_command =
esphome::modbus_controller::ModbusCommandItem::create_write_multiple_command(controller, 0x906B, battery_settings3.size(),
battery_settings2);
@@ -583,19 +583,19 @@ The response is mapped to the sensor based on ``register_count`` and offset in b
delay(200) ;
controller->queue_command(set_battery2_command);
ESP_LOGI("ModbusLambda", "EPSOLAR Battery set");
-
+
uart:
id: mod_bus
- tx_pin: 19
- rx_pin: 18
+ tx_pin: GPIOXX
+ rx_pin: GPIOXX
baud_rate: 115200
stop_bits: 1
-
+
modbus:
- #flow_control_pin: 23
+ #flow_control_pin: GPIOXX
send_wait_time: 200ms
id: mod_bus_epever
-
+
modbus_controller:
- id: epever
## the Modbus device addr
@@ -604,7 +604,7 @@ The response is mapped to the sensor based on ``register_count`` and offset in b
command_throttle: 0ms
setup_priority: -10
update_interval: ${updates}
-
+
sensor:
- platform: modbus_controller
modbus_controller_id: epever
@@ -617,7 +617,7 @@ The response is mapped to the sensor based on ``register_count`` and offset in b
accuracy_decimals: 1
filters:
- multiply: 0.01
-
+
- platform: modbus_controller
modbus_controller_id: epever
id: array_rated_current
@@ -629,7 +629,7 @@ The response is mapped to the sensor based on ``register_count`` and offset in b
accuracy_decimals: 2
filters:
- multiply: 0.01
-
+
- platform: modbus_controller
modbus_controller_id: epever
id: array_rated_power
diff --git a/components/mqtt.rst b/components/mqtt.rst
index a62bdd94d..c255d8ef2 100644
--- a/components/mqtt.rst
+++ b/components/mqtt.rst
@@ -184,13 +184,12 @@ Home Assistant generates entity names for all discovered devices based on entity
entity name (e.g. ``sensor.uptime``). Numeric suffixes are appended to entity names when
multiple devices use the same name for a sensor, making it harder to distinguish between
similar sensors on different devices. Home Assistant 2021.12 allows MQTT devices to change
-this behaviour by specifying ``object_id`` discovery attribute which replaces the sensor
+this behaviour by specifying the ``object_id`` discovery attribute which replaces the sensor
name part of the generated entity name. Setting ``discovery_object_id_generator: device_name``
-in ESPHome MQTT integration configuration will cause Home Assistant to include device name
+in the ESPHome MQTT component configuration will cause Home Assistant to include device name
in the generated entity names (e.g. ``sensor.uptime`` becomes ``sensor._uptime``),
making it easier to distinguish the entities in various entity lists.
-
.. _mqtt-defaults:
Defaults
@@ -266,7 +265,7 @@ then run the ``mqtt-fingerprint`` script of ESPHome to get the certificate:
.. code-block:: bash
- esphome livingroom.yaml mqtt-fingerprint
+ esphome mqtt-fingerprint livingroom.yaml
> SHA1 Fingerprint: a502ff13999f8b398ef1834f1123650b3236fc07
> Copy above string into mqtt.ssl_fingerprints section of livingroom.yaml
diff --git a/components/network.rst b/components/network.rst
index 34b1d1c71..31e717ab7 100644
--- a/components/network.rst
+++ b/components/network.rst
@@ -22,6 +22,12 @@ Configuration variables:
- **enable_ipv6** (*Optional*, boolean): Enables IPv6 support. Defaults to ``false``.
- **min_ipv6_addr_count** (*Optional*, integer): ESPHome considers the network to be connected when it has one IPv4 address and this number of IPv6 addresses. Defaults to ``0`` so as to not hang on boot with networks where IPv6 is not enabled. ``2`` is typically a reasonable value for configurations requiring IPv6.
+.. note::
+
+ The `lwIP `__.
+There are several already made boards which are compatible with this component, such as the
+`RobotDyn dimmer `__.
.. figure:: images/robotdyn_dimmer.jpg
:align: center
@@ -34,9 +33,9 @@ for example the `RobotDyn dimmer
output:
- platform: ac_dimmer
id: dimmer1
- gate_pin: D7
+ gate_pin: GPIOXX
zero_cross_pin:
- number: D6
+ number: GPIOXX
mode:
input: true
inverted: yes
diff --git a/components/output/bp1658cj.rst b/components/output/bp1658cj.rst
index 84aeb2136..2743b77ba 100644
--- a/components/output/bp1658cj.rst
+++ b/components/output/bp1658cj.rst
@@ -24,8 +24,8 @@ It is used in some smart light bulbs:
# Example configuration entry
bp1658cj:
- data_pin: GPIO6
- clock_pin: GPIO7
+ data_pin: GPIOXX
+ clock_pin: GPIOXX
max_power_color_channels: 4 # Valid values 0-15
max_power_white_channels: 6 # Valid values 0-15
diff --git a/components/output/bp5758d.rst b/components/output/bp5758d.rst
index ffbcc2340..adde2757b 100644
--- a/components/output/bp5758d.rst
+++ b/components/output/bp5758d.rst
@@ -24,8 +24,8 @@ It is used in some smart light bulbs:
# Example configuration entry
bp5758d:
- data_pin: GPIO3
- clock_pin: GPIO5
+ data_pin: GPIOXX
+ clock_pin: GPIOXX
Configuration variables:
diff --git a/components/output/custom.rst b/components/output/custom.rst
index 501d46725..ad37e1bf0 100644
--- a/components/output/custom.rst
+++ b/components/output/custom.rst
@@ -1,17 +1,25 @@
Custom Output
=============
+.. seo::
+ :description: Instructions for setting up Custom C++ outputs with ESPHome.
+ :image: language-cpp.svg
+ :keywords: C++, Custom
+
.. warning::
- Custom components are deprecated, not recommended for new configurations
- and will be removed from ESPHome in a future release.
- Please look at creating a real ESPHome component and "importing" it into your
- configuration with :doc:`/components/external_components`.
+ Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
+ future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
+ :doc:`/components/external_components`.
- You can find some basic documentation on creating your own components
- at :ref:`contributing_to_esphome`.
+ You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
-This integration can be used to create custom binary and float :doc:`outputs `
+.. warning::
+
+ While we try to keep the ESPHome YAML configuration options as stable as possible, the ESPHome API is less
+ stable. If something in the APIs needs to be changed in order for something else to work, we will do so.
+
+This component can be used to create custom binary and float :doc:`outputs `
in ESPHome using the C++ (Arduino) API.
Please first read :doc:`/components/sensor/custom` guide, the same principles apply here.
diff --git a/components/output/esp8266_pwm.rst b/components/output/esp8266_pwm.rst
index e55a2dd43..ba2c572f7 100644
--- a/components/output/esp8266_pwm.rst
+++ b/components/output/esp8266_pwm.rst
@@ -15,7 +15,7 @@ like the one on the ESP32 (see :doc:`ledc`) are preferred.
# Example configuration entry
output:
- platform: esp8266_pwm
- pin: D1
+ pin: GPIOXX
frequency: 1000 Hz
id: pwm_output
diff --git a/components/output/gpio.rst b/components/output/gpio.rst
index de9547819..26fdf0db9 100644
--- a/components/output/gpio.rst
+++ b/components/output/gpio.rst
@@ -14,7 +14,7 @@ will not show up in Home Assistant. See :doc:`/components/switch/gpio`.
# Example configuration entry
output:
- platform: gpio
- pin: D1
+ pin: GPIOXX
id: gpio_d1
Configuration variables:
diff --git a/components/output/images/tlc5971.jpg b/components/output/images/tlc5971.jpg
new file mode 100644
index 000000000..a5215f8a4
Binary files /dev/null and b/components/output/images/tlc5971.jpg differ
diff --git a/components/output/ledc.rst b/components/output/ledc.rst
index fe6dd62ab..a2e25b185 100644
--- a/components/output/ledc.rst
+++ b/components/output/ledc.rst
@@ -12,6 +12,32 @@ of the ESP32 as an output component.
The frequency range of LEDC is from 10Hz to 40MHz - however, higher frequencies require a smaller
bit depth which means the output is not that accurate for frequencies above ~300kHz.
+
+Configuration variables:
+------------------------
+
+- **pin** (**Required**, :ref:`config-pin`): The pin to use LEDC on. Can only be GPIO0-GPIO33.
+- **id** (**Required**, :ref:`config-id`): The id to use for this output component.
+- **frequency** (*Optional*, float): At which frequency to run the LEDC
+ channel’s timer. Defaults to 1000Hz.
+- All other options from :ref:`Output `.
+
+Advanced options:
+
+- **channel** (*Optional*, int): Manually set the `LEDC
+ channel `__
+ to use. Two adjacent channels share the same timer. Defaults to an automatic selection.
+
+Note: When configuring custom frequencies for two or more outputs, ensure that you manually specify
+channel 0, 2, 4, 6 for each output. This will prevent issues that arise from automatic selection,
+which chooses adjacent channels with shared timers. See
+`Issue #3114 `__ for more details.
+
+- **phase_angle** (*Optional*, float): Set a phase angle to the other channel of this timer.
+ Range 0-360°, defaults to 0°
+
+Note: this variable is only available for the esp-idf framework
+
Example Usage For a Light
*************************
@@ -20,8 +46,8 @@ Example Usage For a Light
# Example configuration entry
output:
- platform: ledc
- pin: GPIO19
- id: gpio_19
+ pin: GPIOXX
+ id: gpio_
# Example usage in a light
light:
@@ -63,26 +89,6 @@ Example Usage For a Piezo Buzzer
id: buzzer
level: "50%"
-Configuration variables:
-------------------------
-
-- **pin** (**Required**, :ref:`config-pin`): The pin to use LEDC on. Can only be GPIO0-GPIO33.
-- **id** (**Required**, :ref:`config-id`): The id to use for this output component.
-- **frequency** (*Optional*, float): At which frequency to run the LEDC
- channel’s timer. Defaults to 1000Hz.
-- All other options from :ref:`Output `.
-
-Advanced options:
-
-- **channel** (*Optional*, int): Manually set the `LEDC
- channel `__
- to use. Two adjacent channels share the same timer. Defaults to an automatic selection.
-
-Note: When configuring custom frequencies for two or more outputs, ensure that you manually specify
-channel 0, 2, 4, 6 for each output. This will prevent issues that arise from automatic selection,
-which chooses adjacent channels with shared timers. See
-`Issue #3114 `__ for more details.
-
Recommended frequencies
-----------------------
diff --git a/components/output/my9231.rst b/components/output/my9231.rst
index db062f5b6..c195b46dd 100644
--- a/components/output/my9231.rst
+++ b/components/output/my9231.rst
@@ -31,14 +31,9 @@ global ``my9231`` hub and give it an id, and then define the
# Example configuration entry
my9231:
- - data_pin: GPIO12
- clock_pin: GPIO14
+ - data_pin: GPIOXX
+ clock_pin: GPIOXX
- # Individual outputs
- output:
- - platform: my9231
- id: 'my9231_output1'
- channel: 0
Configuration variables:
************************
@@ -68,11 +63,6 @@ The MY931/MY9291 output component exposes a MY931/MY9291 channel of a global
.. code-block:: yaml
- # Example configuration entry
- my9231:
- - data_pin: GPIO12
- clock_pin: GPIO14
-
# Individual outputs
output:
- platform: my9231
diff --git a/components/output/pca9685.rst b/components/output/pca9685.rst
index 42772ecbf..00e9b6293 100644
--- a/components/output/pca9685.rst
+++ b/components/output/pca9685.rst
@@ -44,7 +44,7 @@ global ``pca9685`` hub and give it an id, and then define the
output:
# generate PWM from ESP32 ledc
- platform: ledc
- pin: 25
+ pin: GPIOXX
id: extclk
min_power: 1
frequency: 40MHz
@@ -118,10 +118,10 @@ This output can be used for different PWM functions. E.g. output for light, fan
- platform: pca9685
channel: 0
id: pwm01
-
+
light:
- - platform: monochromatic
- name: 'main light'
+ - platform: monochromatic
+ name: 'main light'
output: pwm01
See Also
diff --git a/components/output/sigma_delta_output.rst b/components/output/sigma_delta_output.rst
index 9884f00b9..55b69a8a2 100644
--- a/components/output/sigma_delta_output.rst
+++ b/components/output/sigma_delta_output.rst
@@ -1,7 +1,7 @@
Sigma-Delta Output
==================
-This integration uses `sigma-delta modulation `__
+This component uses `sigma-delta modulation `__
to output a floating-point value on a binary output. Unlike with :doc:`/components/output/slow_pwm`,
it is possible to update the output value with each update cycle, not just at the end of a longer period.
@@ -14,13 +14,13 @@ it is possible to update the output value with each update cycle, not just at th
For example, if you choose to toggle the output at most once every 1 second and decide on a
PWM period of 10 seconds, for reasonably frequent updates, with :doc:`/components/output/slow_pwm`
there are only 10 possible levels, and for higher precision a longer update interval is needed,
-restricting the update rate.
+restricting the update rate.
A *sigma-delta* output is updated during each cycle, thus a higher precision can be achieved, without
being constrained by a calculation timeframe (=period).
So instead of having to define a ``period`` where the width of the pulse determines the output level, here you
-choose an ``update_interval`` which acts like a clock signal from where the pulse density determines the output level.
+choose an ``update_interval`` which acts like a clock signal from where the pulse density determines the output level.
This component can be used as a drop-in replacement for :doc:`/components/output/slow_pwm` by changing the ``platform`` to
``sigma_delta_output`` and changing ``period`` to ``update_interval`` (you usually want to set the *sigma-delta*'s
@@ -35,7 +35,7 @@ This component can be used as a drop-in replacement for :doc:`/components/output
id: sd_heater_output
# Output to a pin
- pin: 15
+ pin: GPIOXX
# Use the same output, but through automations
turn_on_action:
@@ -44,9 +44,9 @@ This component can be used as a drop-in replacement for :doc:`/components/output
turn_off_action:
then:
- output.turn_off: heater_relay
-
+
- platform: gpio
- pin: 15
+ pin: GPIOXX
id: heater_relay
Configuration variables:
diff --git a/components/output/slow_pwm.rst b/components/output/slow_pwm.rst
index 34d6c8aa7..bef7ae0ec 100644
--- a/components/output/slow_pwm.rst
+++ b/components/output/slow_pwm.rst
@@ -22,7 +22,7 @@ heating element through a relay where a fast PWM update cycle would not be appro
# Example configuration entry
output:
- platform: slow_pwm
- pin: D1
+ pin: GPIOXX
id: my_slow_pwm
period: 15s
diff --git a/components/output/sm16716.rst b/components/output/sm16716.rst
index e5fc31826..d8e8bd856 100644
--- a/components/output/sm16716.rst
+++ b/components/output/sm16716.rst
@@ -28,22 +28,11 @@ global ``sm16716`` hub and give it an id, and then define the
# Example configuration entry
sm16716:
- data_pin: GPIO14
- clock_pin: GPIO4
+ data_pin: GPIOXX
+ clock_pin: GPIOXX
num_channels: 3
num_chips: 1
- # Individual outputs
- output:
- - platform: sm16716
- id: output_red
- channel: 0
- - platform: sm16716
- id: output_green
- channel: 1
- - platform: sm16716
- id: output_blue
- channel: 2
Configuration variables:
************************
@@ -69,13 +58,6 @@ The SM16716 output component exposes a SM16716 channel of a global
.. code-block:: yaml
- # Example configuration entry
- sm16716:
- data_pin: GPIO14
- clock_pin: GPIO4
- num_channels: 3
- num_chips: 1
-
# Individual outputs
output:
- platform: sm16716
@@ -174,7 +156,7 @@ A complete configuration for a Feit Electric A19 looks like:
The white LEDs are much brighter than the color LEDs and will fully overpower
the set color when the white level is set even a little bit high. You will need
to set the white level to 0 in order to get usable colors from this bulb.
-
+
Alternative Costco Feit A19 RGBCT bulb configuration:
.. code-block:: yaml
@@ -224,8 +206,8 @@ Alternative Costco Feit A19 RGBCT bulb configuration:
power_supply:
- id: rgb_power
pin: GPIO13
-
-
+
+
See Also
--------
diff --git a/components/output/sm2135.rst b/components/output/sm2135.rst
index 120cef50b..df6b064d2 100644
--- a/components/output/sm2135.rst
+++ b/components/output/sm2135.rst
@@ -27,31 +27,9 @@ global ``sm2135`` hub and give it an id, and then define the
# Example configuration entry
sm2135:
- data_pin: GPIO12
- clock_pin: GPIO14
+ data_pin: GPIOXX
+ clock_pin: GPIOXX
- # Individual outputs
- output:
- - platform: sm2135
- id: output_red
- channel: 0
- max_power: 0.8
- - platform: sm2135
- id: output_green
- channel: 1
- max_power: 0.8
- - platform: sm2135
- id: output_blue
- channel: 2
- max_power: 0.8
- - platform: sm2135
- id: output_white
- channel: 3
- max_power: 0.8
- - platform: sm2135
- id: output_warmwhite
- channel: 4
- max_power: 0.8
Configuration variables:
************************
@@ -62,12 +40,15 @@ Configuration variables:
- **id** (*Optional*, :ref:`config-id`): The id to use for
this ``sm2135`` component. Use this if you have multiple SM2135 chains
connected at the same time.
-- **cw_current** (*Optional*, current): The current used for the white channel.
+- **cw_current** (*Optional*, current): The current used for the white channel.
Defaults to ``10mA``.
Can be one of ``10mA``, ``15mA``, ``20mA``, ``25mA``, ``30mA``, ``35mA``, ``40mA``, ``45mA``, ``50mA``, ``55mA``, ``60mA``.
- **rgb_current** (*Optional*, current): The current used for the RGB channel.
Defaults to ``20mA``.
Can be one of ``10mA``, ``15mA``, ``20mA``, ``25mA``, ``30mA``, ``35mA``, ``40mA``, ``45mA``.
+- **separate_modes** (*Optional*, bool): Use separate RGB/CW modes instead of writing all 5 values as RGB.
+ Defaults to ``true``, keep it at ``true`` if your SM2135 chip variant does not support simultaneous CW and RGB modes (e.g. SM2135E).
+ Set this to ``false`` when your SM2135 chip variant supports having CW and RGB leds on at the same time (e.g. SM2135EH/SM2135EJ).
.. _sm2135-output:
@@ -79,11 +60,6 @@ The SM2135 output component exposes a SM2135 channel of a global
.. code-block:: yaml
- # Example configuration entry
- sm2135:
- data_pin: GPIO12
- clock_pin: GPIO14
-
# Individual outputs
output:
- platform: sm2135
diff --git a/components/output/sm2235.rst b/components/output/sm2235.rst
index 71cbb7c30..e3008a032 100644
--- a/components/output/sm2235.rst
+++ b/components/output/sm2235.rst
@@ -21,8 +21,8 @@ global ``sm2235`` hub and give it an id, and then define the
# Example configuration entry
sm2235:
- data_pin: GPIO4
- clock_pin: GPIO5
+ data_pin: GPIOXX
+ clock_pin: GPIOXX
max_power_color_channels: 9
max_power_white_channels: 9
diff --git a/components/output/sm2335.rst b/components/output/sm2335.rst
index 011df7bc9..9ed107cbe 100644
--- a/components/output/sm2335.rst
+++ b/components/output/sm2335.rst
@@ -24,8 +24,8 @@ global ``sm2335`` hub and give it an id, and then define the
# Example configuration entry
sm2335:
- data_pin: GPIO4
- clock_pin: GPIO5
+ data_pin: GPIOXX
+ clock_pin: GPIOXX
max_power_color_channels: 9
max_power_white_channels: 9
diff --git a/components/output/template.rst b/components/output/template.rst
index 267c47cca..b479bcff7 100644
--- a/components/output/template.rst
+++ b/components/output/template.rst
@@ -22,14 +22,10 @@ The ``template`` output component can be used to create templated binary and flo
id: output2
level: !lambda return state;
- - platform: esp8266_pwm
+ - platform: ...
id: output1
- pin: GPIO12
- inverted: true
- - platform: esp8266_pwm
+ - platform: ...
id: output2
- pin: GPIO14
- inverted: true
diff --git a/components/output/tlc5947.rst b/components/output/tlc5947.rst
index 57b84345d..0a880d44e 100644
--- a/components/output/tlc5947.rst
+++ b/components/output/tlc5947.rst
@@ -27,21 +27,9 @@ global ``tlc5947`` hub and give it an id, and then define the
# Example configuration entry
tlc5947:
- data_pin: GPIO12
- clock_pin: GPIO14
- lat_pin: GPIO15
-
- # Individual outputs
- output:
- - platform: tlc5947
- id: output_red
- channel: 0
- - platform: tlc5947
- id: output_green
- channel: 1
- - platform: tlc5947
- id: output_blue
- channel: 2
+ data_pin: GPIOXX
+ clock_pin: GPIOXX
+ lat_pin: GPIOXX
Configuration variables:
************************
@@ -66,12 +54,6 @@ The tlc5947 output component exposes a tlc5947 channel of a global
.. code-block:: yaml
- # Example configuration entry
- tlc5947:
- data_pin: GPIO12
- clock_pin: GPIO14
- lat_pin: GPIO15
-
# Individual outputs
output:
- platform: tlc5947
diff --git a/components/output/tlc5971.rst b/components/output/tlc5971.rst
new file mode 100644
index 000000000..5701b3627
--- /dev/null
+++ b/components/output/tlc5971.rst
@@ -0,0 +1,85 @@
+TLC5971 LED driver
+==================
+
+.. seo::
+ :description: Instructions for setting up TLC5971 LED drivers in ESPHome.
+ :image: tlc5971.jpg
+ :keywords: tlc5971,
+
+.. _tlc5971-component:
+
+Component/Hub
+-------------
+.. figure:: images/tlc5971.jpg
+ :align: center
+ :width: 75.0%
+
+ Adafruit's TLC59711 board
+
+This component represents a chain of `TLC5971 12-Channel, 16-Bit PWM LED Drivers `_,
+which is used e.g. on this `board from Adafruit `_.
+
+To use the channels of this components, you first need to setup the
+global ``tlc5971`` hub and give it an id, and then define the
+:ref:`individual output channels `.
+
+.. code-block:: yaml
+
+ # Example configuration entry
+ tlc5971:
+ data_pin: GPIOXX
+ clock_pin: GPIOXX
+
+
+Configuration variables:
+************************
+
+- **data_pin** (**Required**, :ref:`Pin Schema `): The pin connected to DIN.
+- **clock_pin** (**Required**, :ref:`Pin Schema `): The pin connected to CLK.
+- **num_chips** (*Optional*, int): Number of chips in the chain. Must be
+ in range from 1 to 85. Defaults to 1.
+- **id** (*Optional*, :ref:`config-id`): The id to use for
+ this ``tlc5971`` component. Use this if you have multiple TLC5971 chains
+ connected at the same time.
+
+.. _tlc5971-output:
+
+Output
+------
+
+The tlc5971 output component exposes a tlc5971 channel of a global
+:ref:`tlc5971-component` as a float output.
+
+.. code-block:: yaml
+
+ # Individual outputs
+ output:
+ - platform: tlc5971
+ id: output_red
+ channel: 0
+ - platform: tlc5971
+ id: output_green
+ channel: 1
+ - platform: tlc5971
+ id: output_blue
+ channel: 2
+
+Configuration variables:
+************************
+
+- **id** (**Required**, :ref:`config-id`): The id to use for this output component.
+- **channel** (**Required**, int): Chose the channel of the TLC5971 chain of
+ this output component.
+- **tlc5971_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the
+ :ref:`TLC5971-component`.
+ Use this if you have multiple TLC5971 chains you want to use at the same time.
+- All other options from :ref:`Output `.
+
+See Also
+--------
+
+- :doc:`/components/output/index`
+- :doc:`/components/light/monochromatic`
+- :doc:`/components/power_supply`
+- :apiref:`tlc5971/tlc5971.h`
+- :ghedit:`Edit`
diff --git a/components/output/x9c.rst b/components/output/x9c.rst
index ce7732d91..4a1ffebc8 100644
--- a/components/output/x9c.rst
+++ b/components/output/x9c.rst
@@ -15,7 +15,7 @@ The ``x9c`` output platform allows you to add an output that controls a `X9C dig
The X9C family of digital potentiometers are available in different resistance values.
-==================== =====================
+==================== =====================
``X9C102`` ``1kΩ``
-------------------- ---------------------
``X9C103`` ``10kΩ``
@@ -33,9 +33,9 @@ All chips are controlled by a three wire interface and feature 100 possible wipe
output:
- platform: x9c
id: x9c_pot
- cs_pin: GPIO25
- inc_pin: GPIO27
- ud_pin: GPIO26
+ cs_pin: GPIOXX
+ inc_pin: GPIOXX
+ ud_pin: GPIOXX
initial_value: 0.5
Configuration variables:
diff --git a/components/pca9554.rst b/components/pca9554.rst
index 0acc4db6a..cc175f7ed 100644
--- a/components/pca9554.rst
+++ b/components/pca9554.rst
@@ -59,7 +59,7 @@ binary sensor or GPIO switch.
- platform: gpio
name: "PCF9554A Pin #0"
pin:
- pca9554: pcf9554a_device
+ pca9554: pca9554a_device
# Use pin number 0
number: 0
# One of INPUT or OUTPUT
diff --git a/components/pipsolar.rst b/components/pipsolar.rst
index d7f20ca46..5597ec1da 100644
--- a/components/pipsolar.rst
+++ b/components/pipsolar.rst
@@ -37,16 +37,8 @@ There is a buffer to buffer up to 10 commands.
.. code-block:: yaml
# Example configuration entry
- uart:
- - id: uart_bus
- tx_pin: GPIO18
- rx_pin: GPIO19
- # most devices use 2400 as baud_rate
- baud_rate: 2400
-
pipsolar:
- - uart_id: uart_bus
- id: inverter0
+ - id: inverter0
Configuration variables:
~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/components/pn7150.rst b/components/pn7150.rst
index b76e6e2df..498f713ac 100644
--- a/components/pn7150.rst
+++ b/components/pn7150.rst
@@ -30,10 +30,10 @@ In addition, the :doc:`binary_sensor/nfc` platform may be used to quickly and ea
.. code-block:: yaml
pn7150_i2c:
- dwl_req_pin: 17
- irq_pin: 35
- ven_pin: 16
- wkup_req_pin: 21
+ dwl_req_pin: GPIOXX
+ irq_pin: GPIOXX
+ ven_pin: GPIOXX
+ wkup_req_pin: GPIOXX
emulation_message: https://www.home-assistant.io/tag/pulse_ce
tag_ttl: 1000ms
@@ -348,7 +348,7 @@ NDEF Writing
The examples below illustrate how NDEF messages may be written to cards/tags via the PN7150. Note that a
:doc:`button ` is a great mechanism to use to trigger these actions.
-The first example will write a simple, fixed NDEF message to a tag.
+The first example will write a simple, fixed NDEF message to a tag.
.. code-block:: yaml
diff --git a/components/pn7160.rst b/components/pn7160.rst
index f359a7b5d..dd8d6b5ca 100644
--- a/components/pn7160.rst
+++ b/components/pn7160.rst
@@ -42,11 +42,11 @@ The ``pn7160_spi`` component allows you to use :ref:`SPI-equipped ` PN7160
.. code-block:: yaml
pn7160_spi:
- cs_pin: 15
- dwl_req_pin: 17
- irq_pin: 35
- ven_pin: 16
- wkup_req_pin: 21
+ cs_pin: GPIOXX
+ dwl_req_pin: GPIOXX
+ irq_pin: GPIOXX
+ ven_pin: GPIOXX
+ wkup_req_pin: GPIOXX
emulation_message: https://www.home-assistant.io/tag/pulse_ce
tag_ttl: 1000ms
@@ -87,10 +87,10 @@ The ``pn7160_i2c`` component allows you to use :ref:`I²C-equipped ` PN7160
.. code-block:: yaml
pn7160_i2c:
- dwl_req_pin: 17
- irq_pin: 35
- ven_pin: 16
- wkup_req_pin: 21
+ dwl_req_pin: GPIOXX
+ irq_pin: GPIOXX
+ ven_pin: GPIOXX
+ wkup_req_pin: GPIOXX
emulation_message: https://www.home-assistant.io/tag/pulse_ce
tag_ttl: 1000ms
@@ -406,7 +406,7 @@ NDEF Writing
The examples below illustrate how NDEF messages may be written to cards/tags via the PN7160. Note that a
:doc:`button ` is a great mechanism to use to trigger these actions.
-The first example will write a simple, fixed NDEF message to a tag.
+The first example will write a simple, fixed NDEF message to a tag.
.. code-block:: yaml
diff --git a/components/power_supply.rst b/components/power_supply.rst
index f4e69c574..bdd734a8a 100644
--- a/components/power_supply.rst
+++ b/components/power_supply.rst
@@ -21,7 +21,7 @@ after the last output has been disabled.
# Example configuration entry
power_supply:
- id: 'power_supply1'
- pin: 13
+ pin: GPIOXX
Configuration variables:
------------------------
diff --git a/components/remote_receiver.rst b/components/remote_receiver.rst
index b74b4c694..c7bb7ff63 100644
--- a/components/remote_receiver.rst
+++ b/components/remote_receiver.rst
@@ -20,7 +20,7 @@ which will trigger when they hear their own configured signal.
# Example configuration entry
remote_receiver:
- pin: GPIO32
+ pin: GPIOXX
dump: all
Configuration variables:
@@ -30,12 +30,14 @@ Configuration variables:
- **dump** (*Optional*, list): Decode and dump these remote codes in the logs (at log.level=DEBUG).
Set to ``all`` to dump all available codecs:
+ - **abbwelcome**: Decode and dump ABB-Welcome codes. Messages are sent via copper wires. See :ref:`remote_transmitter-transmit_abbwelcome`
- **aeha**: Decode and dump AEHA infrared codes.
- **byronsx**: Decode and dump Byron SX doorbell RF codes.
- **canalsat**: Decode and dump CanalSat infrared codes.
- **canalsatld**: Decode and dump CanalSatLD infrared codes.
- **coolix**: Decode and dump Coolix infrared codes.
- **dish**: Decode and dump Dish infrared codes.
+ - **dooya**: Decode and dump Dooya RF codes.
- **drayton**: Decode and dump Drayton Digistat RF codes.
- **jvc**: Decode and dump JVC infrared codes.
- **keeloq**: Decode and dump KeeLoq RF codes.
@@ -52,23 +54,43 @@ Configuration variables:
- **rc5**: Decode and dump RC5 IR codes.
- **rc6**: Decode and dump RC6 IR codes.
- **rc_switch**: Decode and dump RCSwitch RF codes.
+ - **roomba**: Decode and dump Roomba infrared codes.
- **samsung**: Decode and dump Samsung infrared codes.
- **samsung36**: Decode and dump Samsung36 infrared codes.
- **sony**: Decode and dump Sony infrared codes.
- **toshiba_ac**: Decode and dump Toshiba AC infrared codes.
-- **tolerance** (*Optional*, int): The percentage that the remote signal lengths can deviate in the
- decoding process. Defaults to ``25%``.
+- **tolerance** (*Optional*, int, :ref:`config-time` or mapping): The percentage or time that the remote signal lengths can
+ deviate in the decoding process. Defaults to ``25%``.
+
+ - **type** (**Required**, enum): Set the type of the tolerance. Can be ``percentage`` or ``time``.
+ - **value** (**Required**, int or :ref:`config-time`): The percentage or time value. Allowed values are in range ``0`` to
+ ``100%`` or ``0`` to ``4294967295us``.
+
- **buffer_size** (*Optional*, int): The size of the internal buffer for storing the remote codes. Defaults to ``10kB``
on the ESP32 and ``1kB`` on the ESP8266.
-- **memory_blocks** (*Optional*, int): The number of RMT memory blocks used. Only used on ESP32 platform. Defaults to
- ``3``.
+- **rmt_channel** (*Optional*, int): The RMT channel to use. Only on **esp32**.
+ The following ESP32 variants have these channels available:
+
+ .. csv-table::
+ :header: "ESP32 Variant", "Channels"
+
+ "ESP32", "0, 1, 2, 3, 4, 5, 6, 7"
+ "ESP32-S2", "0, 1, 2, 3"
+ "ESP32-S3", "4, 5, 6, 7"
+ "ESP32-C3", "2, 3"
+
+- **memory_blocks** (*Optional*, int): The number of RMT memory blocks used. Only used on ESP32 platform. The maximum
+ number of blocks shared by all receivers and transmitters depends on the ESP32 variant. Defaults to ``3``.
- **filter** (*Optional*, :ref:`config-time`): Filter any pulses that are shorter than this. Useful for removing
- glitches from noisy signals. Defaults to ``50us``.
+ glitches from noisy signals. Allowed values are in range ``0`` to ``4294967295us``. Defaults to ``50us``.
- **idle** (*Optional*, :ref:`config-time`): The amount of time that a signal should remain stable (i.e. not
- change) for it to be considered complete. Defaults to ``10ms``.
+ change) for it to be considered complete. Allowed values are in range ``0`` to ``4294967295us``. Defaults to ``10ms``.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. Use this if you have
multiple remote receivers.
+- **clock_divider** (*Optional*, int): The clock divider used by the RMT peripheral. A clock divider of ``80`` leads to
+ a resolution of 1 µs per tick, ``160`` leads to 2 µs. Allowed values are in range ``1`` to ``255``. Only used on ESP32
+ platform. Defaults to ``80``.
.. note::
@@ -79,6 +101,9 @@ Configuration variables:
Automations:
------------
+- **on_abbwelcome** (*Optional*, :ref:`Automation `): An automation to perform when a
+ ABB-Welcome code has been decoded. A variable ``x`` of type :apiclass:`remote_base::ABBWelcomeData`
+ is passed to the automation for use in lambdas.
- **on_aeha** (*Optional*, :ref:`Automation `): An automation to perform when a
AEHA remote code has been decoded. A variable ``x`` of type :apiclass:`remote_base::AEHAData`
is passed to the automation for use in lambdas.
@@ -98,6 +123,9 @@ Automations:
dish network remote code has been decoded. A variable ``x`` of type :apistruct:`remote_base::DishData`
is passed to the automation for use in lambdas.
Beware that Dish remotes use a different carrier frequency (57.6kHz) that many receiver hardware don't decode.
+- **on_dooya** (*Optional*, :ref:`Automation `): An automation to perform when a
+ Dooya RF remote code has been decoded. A variable ``x`` of type :apistruct:`remote_base::DooyaData`
+ is passed to the automation for use in lambdas.
- **on_drayton** (*Optional*, :ref:`Automation `): An automation to perform when a
Drayton Digistat RF code has been decoded. A variable ``x`` of type :apistruct:`remote_base::DraytonData`
is passed to the automation for use in lambdas.
@@ -146,6 +174,9 @@ Automations:
- **on_rc_switch** (*Optional*, :ref:`Automation `): An automation to perform when a
RCSwitch RF code has been decoded. A variable ``x`` of type :apistruct:`remote_base::RCSwitchData`
is passed to the automation for use in lambdas.
+- **on_roomba** (*Optional*, :ref:`Automation `): An automation to perform when a
+ Roomba remote code has been decoded. A variable ``x`` of type :apistruct:`remote_base::RoombaData`
+ is passed to the automation for use in lambdas.
- **on_samsung** (*Optional*, :ref:`Automation `): An automation to perform when a
Samsung remote code has been decoded. A variable ``x`` of type :apistruct:`remote_base::SamsungData`
is passed to the automation for use in lambdas.
@@ -187,10 +218,6 @@ then immediately OFF.
.. code-block:: yaml
# Example configuration entry
- remote_receiver:
- pin: GPIO32
- dump: all
-
binary_sensor:
- platform: remote_receiver
name: "Panasonic Remote Input"
@@ -207,6 +234,21 @@ Configuration variables:
Remote code selection (exactly one of these has to be included):
+- **abbwelcome**: Trigger on a decoded ABB-Welcome code with the given data.
+
+ - **source_address** (**Required**, int): The source address to trigger on, see :ref:`remote_transmitter-transmit_abbwelcome`
+ for more info.
+ - **destination_address** (**Required**, int): The destination address to trigger on, see
+ :ref:`remote_transmitter-transmit_abbwelcome` for more info.
+ - **three_byte_address** (**Optional**, boolean): The length of the source and destination address. ``false`` means two bytes
+ and ``true`` means three bytes. Defaults to ``false``.
+ - **retransmission** (**Optional**, boolean): ``true`` if the message was re-transmitted. Defaults to ``false``.
+ - **message_type** (**Required**, int): The message type to trigger on, see :ref:`remote_transmitter-transmit_abbwelcome`
+ for more info.
+ - **message_id** (**Optional**, int): The random message ID to trigger on, see dumper output for more info. Defaults to any ID.
+ - **data** (**Optional**, 0-7 bytes list): The code to listen for. Usually you only need to copy this directly from the
+ dumper output. Defaults to ``[]``
+
- **aeha**: Trigger on a decoded AEHA remote code with the given data.
- **address** (**Required**, int): The address to trigger on, see dumper output for more info.
@@ -243,6 +285,13 @@ Remote code selection (exactly one of these has to be included):
- **address** (*Optional*, int): The number of the receiver to target, between 1 and 16 inclusive. Defaults to ``1``.
- **command** (**Required**, int): The Dish command to listen for, between 0 and 63 inclusive.
+- **dooya**: Trigger on a decoded Dooya RF remote code with the given data.
+
+ - **id** (**Required**, int): The 24-bit ID code to trigger on.
+ - **channel** (**Required**, int): The 8-bit channel to listen for.
+ - **button** (**Required**, int): The 4-bit button to listen for.
+ - **check** (**Required**, int): The 4-bit check to listen for. Includes an indication that a button is being held down.
+
- **drayton**: Trigger on a decoded Drayton Digistat RF remote code with the given data.
- **address** (**Required**, int): The 16-bit ID code to trigger on, see dumper output for more info.
@@ -304,6 +353,8 @@ Remote code selection (exactly one of these has to be included):
- **data** (**Required**, string): The code to listen for, see :ref:`remote_transmitter-transmit_raw`
for more info. Usually you only need to copy this directly from the dumper output.
+ - **delta** (**Optional**, integer): This parameter allows you to manually specify the allowed difference
+ between what Pronto code is specified, and what IR signal has been sent by the remote control.
- **raw**: Trigger on a raw remote code with the given code.
@@ -355,6 +406,10 @@ Remote code selection (exactly one of these has to be included):
- **state** (**Required**, boolean): The on/off state to trigger on.
- **protocol** (*Optional*): The RC Switch protocol to use, see :ref:`remote_transmitter-rc_switch-protocol` for more info.
+- **roomba**: Trigger on a decoded Roomba remote code with the given data.
+
+ - **data** (**Required**, int): The Roomba code to trigger on, see dumper output for more info.
+
- **samsung**: Trigger on a decoded Samsung remote code with the given data.
- **data** (**Required**, int): The data to trigger on, see dumper output for more info.
@@ -396,7 +451,7 @@ Remote code selection (exactly one of these has to be included):
remote_receiver:
pin:
- number: D4
+ number: GPIOXX
inverted: true
mode:
input: true
diff --git a/components/remote_transmitter.rst b/components/remote_transmitter.rst
index 53666ab9b..342d74539 100644
--- a/components/remote_transmitter.rst
+++ b/components/remote_transmitter.rst
@@ -24,18 +24,9 @@ remote signals.
# Example configuration entry
remote_transmitter:
- pin: GPIO32
+ pin: GPIOXX
carrier_duty_percent: 50%
- # Individual switches
- switch:
- - platform: template
- name: "Panasonic TV Off"
- turn_on_action:
- remote_transmitter.transmit_panasonic:
- address: 0x4004
- command: 0x100BCBD
-
Configuration variables:
------------------------
@@ -43,6 +34,17 @@ Configuration variables:
- **carrier_duty_percent** (*Optional*, int): How much of the time the remote is on. For example, infrared
protocols modulate the signal using a carrier signal. Set this to ``50%`` if you're working with IR LEDs and to
``100%`` if working with other things like 433MHz transmitters.
+- **rmt_channel** (*Optional*, int): The RMT channel to use. Only on **esp32**.
+ The following ESP32 variants have these channels available:
+
+ .. csv-table::
+ :header: "ESP32 Variant", "Channels"
+
+ "ESP32", "0, 1, 2, 3, 4, 5, 6, 7"
+ "ESP32-S2", "0, 1, 2, 3"
+ "ESP32-S3", "0, 1, 2, 3"
+ "ESP32-C3", "0, 1"
+
- **id** (*Optional*, :ref:`config-id`): Manually specify
the ID used for code generation. Use this if you have multiple remote transmitters.
@@ -78,6 +80,56 @@ Configuration variables:
If you're looking for the same functionality as is default in the ``rpi_rf`` integration in
Home Assistant, you'll want to set the **times** to 10 and the **wait_time** to 0s.
+.. _remote_transmitter-transmit_abbwelcome:
+
+``remote_transmitter.transmit_abbwelcome`` Action
+*************************************************
+
+This :ref:`action ` sends a ABB-Welcome message to the intercom bus. The
+message type, addresses, address length and data can vary a lot between ABB-Welcome
+systems. Please refer to the received messages while performing actions like ringing a
+doorbell or opening a door.
+
+.. code-block:: yaml
+
+ on_...:
+ - remote_transmitter.transmit_abbwelcome:
+ source_address: 0x1001 # your indoor station address
+ destination_address: 0x4001 # door address
+ three_byte_address: false # address length of your system
+ message_type: 0x0d # unlock door, on some systems 0x0e is used instead
+ data: [0xab, 0xcd, 0xef] # message data, see receiver dump
+
+Configuration variables:
+
+- **source_address** (**Required**, int):The source address to send the command from,
+ see received messages for more info. For indoor stations the last byte of the address
+ represents the apartment number set by the dials on the back of the indoor station and is
+ transmitted in hexadecimal format.
+- **destination_address** (**Required**, int): The destination address to send the command to,
+ see received messages for more info.
+- **three_byte_address** (**Required**, int): The destination address to send the command to,
+ see received messages for more info.
+- **three_byte_address** (**Optional**, boolean): The length of the source and destination address. ``false``
+ means two bytes and ``true`` means three bytes. Please check the received messages to see which address length
+ is used by your system. For example, ``[XXXX > XXXX]`` appears in the receiver log for two byte addresses and
+ ``[XXXXXX > XXXXXX]`` for three byte addresses. Defaults to ``false``.
+- **retransmission** (**Optional**, boolean): Should only be ``true`` if this message has been transmitted
+ before with the same ``message_id``. Typically, messages are transmitted up to three times with a 1 second
+ interval if no reply is received. Defaults to ``false``.
+- **message_type** (**Required**, int): The message type, see dumper output for more info.
+ The highest bit indicates a reply.
+- **message_id** (**Optional**, int): The message ID, see dumper output for more info.
+ Defaults to a randomly generated ID if this message is not a reply or retransmission.
+- **data** (**Optional**, 0-7 bytes list): The code to send.
+ Usually you only need to copy this directly from the dumper output. Defaults to ``[]``
+
+.. note::
+
+ ABB-Welcome messages are sent over the two-wire bus of your intercom system.
+ A custom receiver and transmitter circuit is required.
+ `More info `__
+
.. _remote_transmitter-transmit_aeha:
``remote_transmitter.transmit_aeha`` Action
@@ -212,6 +264,30 @@ Configuration variables:
You can find a list of commands in the `LIRC project `__.
+.. _remote_transmitter-transmit_dooya:
+
+``remote_transmitter.transmit_dooya`` Action
+**********************************************
+
+This :ref:`action ` sends a Dooya RF remote code to a remote transmitter.
+
+.. code-block:: yaml
+
+ on_...:
+ - remote_transmitter.transmit_dooya:
+ id: 0x001612E5
+ channel: 142
+ button: 12
+ check: 3
+
+Configuration variables:
+
+- **id** (**Required**, int): The 24-bit ID to send. Each remote has a unique one.
+- **channel** (**Required**, int): The 8-bit channel to send, between 0 and 255 inclusive.
+- **button** (**Required**, int): The 4-bit button to send, between 0 and 15 inclusive.
+- **check** (**Required**, int): The 4-bit check to send. Includes an indication that a button is being held down. See dumper output for more info.
+- All other options from :ref:`remote_transmitter-transmit_action`.
+
.. _remote_transmitter-transmit_drayton:
``remote_transmitter.transmit_drayton`` Action
@@ -267,7 +343,7 @@ This :ref:`action ` sends KeeLoq RF remote code to a remote trans
code: '0xd19ef0a9'
repeat:
times: 3
- wait_time: 15ms
+ wait_time: 15ms
Configuration variables:
@@ -696,6 +772,29 @@ Configuration variables:
for more information.
- All other options from :ref:`remote_transmitter-transmit_action`.
+.. _remote_transmitter-transmit_roomba:
+
+``remote_transmitter.transmit_roomba`` Action
+*********************************************
+
+This :ref:`action ` sends a Roomba infrared remote code to a remote transmitter.
+
+.. code-block:: yaml
+
+ on_...:
+ - remote_transmitter.transmit_roomba:
+ data: 0x88 # clean
+ repeat:
+ times: 3
+ wait_time: 17ms
+
+Configuration variables:
+
+- **data** (**Required**, int): The Roomba code to send, see dumper output for more info.
+- Note that ``repeat`` is still optional, however **Roomba vacuums require that a given code is received at least three times before they will act on it.** If your Roomba still does not respond to sent command increase this value.
+- Note that ``wait_time`` is still optional; it will even work without this parameter, but Roomba Remote uses this 17 ms wait time between sent commands.
+- All other options from :ref:`remote_transmitter-transmit_action`.
+
.. _remote_transmitter-transmit_samsung:
``remote_transmitter.transmit_samsung`` Action
@@ -826,7 +925,7 @@ remote_receiver instance:
.. code-block:: yaml
remote_receiver:
- pin: D0
+ pin: GPIOXX
dump: all
Compile and upload the code. While viewing the log output from the ESP,
@@ -855,7 +954,7 @@ IR diode to a new pin on the ESP and configure a global ``remote_transmitter`` i
.. code-block:: yaml
remote_transmitter:
- pin: D1
+ pin: GPIOXX
# Infrared remotes use a 50% carrier signal
carrier_duty_percent: 50%
@@ -901,7 +1000,7 @@ First, connect the RF module to a pin on the ESP and set up a remote_receiver in
.. code-block:: yaml
remote_receiver:
- pin: D0
+ pin: GPIOXX
dump: all
# Settings to optimize recognition of RF devices
tolerance: 50%
@@ -933,7 +1032,7 @@ You should see log output like below:
.. code-block:: yaml
remote_receiver:
- pin: D0
+ pin: GPIOXX
dump:
- rc_switch
tolerance: 50%
@@ -951,7 +1050,7 @@ RF transmitter to a new pin on the ESP and configure a global ``remote_transmitt
.. code-block:: yaml
remote_transmitter:
- pin: D1
+ pin: GPIOXX
# RF uses a 100% carrier signal
carrier_duty_percent: 100%
diff --git a/components/rp2040.rst b/components/rp2040.rst
index 0bead367b..4b1b36082 100644
--- a/components/rp2040.rst
+++ b/components/rp2040.rst
@@ -10,6 +10,9 @@ This component contains platform-specific options for the RP2040 platform.
.. note::
Support for all aspects of ESPHome on the RP2040 is still in development.
+
+ Only the original model of Raspberry Pi Pico W board is supported, which has the Cypress **CYW43455** chip providing wireless connectivity. It can be identified by a metallic shield encapsulating the radio circuitry. Pico W boards with radio module chips like ESP8285 or similar (labelled as ``RP2040 Pico W-2023`` etc.), are not supported.
+
Please search for or create an `issue `__ if you encounter an unknown problem.
.. code-block:: yaml
diff --git a/components/rtttl.rst b/components/rtttl.rst
index d8e6e2c70..b502a649e 100644
--- a/components/rtttl.rst
+++ b/components/rtttl.rst
@@ -127,7 +127,7 @@ Common beeps
You can do your own beep patterns too! Here's a short collection so you can just use right away or tweak them to your like:
-.. code-block::
+.. code-block::
two_short:d=4,o=5,b=100:16e6,16e6
long:d=1,o=5,b=100:e6
@@ -165,7 +165,7 @@ Sample code
output:
- platform: esp8266_pwm
- pin: D1
+ pin: GPIOXX
id: rtttl_out
rtttl:
diff --git a/components/select/index.rst b/components/select/index.rst
index 756964340..77fc53891 100644
--- a/components/select/index.rst
+++ b/components/select/index.rst
@@ -43,10 +43,10 @@ Configuration variables:
a ``name`` will implicitly set this to true.
- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
(usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
- Requires Home Assistant 2021.9 or newer. Defaults to ``false``.
+ Defaults to ``false``.
- **entity_category** (*Optional*, string): The category of the entity.
See https://developers.home-assistant.io/docs/core/entity/#generic-properties
- for a list of available options. Requires Home Assistant 2021.11 or newer.
+ for a list of available options.
Set to ``""`` to remove the default entity category.
Automations:
@@ -70,7 +70,7 @@ For more information on using lambdas with select, see :ref:`select-lambda_calls
``on_value``
************
-This automation will be triggered when a new value is published. In :ref:`Lambdas `
+This automation will be triggered whenever a value is set/published, even if the value is the same as before. In :ref:`Lambdas `
you can get the value from the trigger with ``x`` and the index offset of the selected value with ``i``.
.. code-block:: yaml
diff --git a/components/sensor/adc.rst b/components/sensor/adc.rst
index 3f6145292..fdb43a66a 100644
--- a/components/sensor/adc.rst
+++ b/components/sensor/adc.rst
@@ -22,7 +22,7 @@ ADC in your device to measure a voltage on certain pins.
# Example configuration entry
sensor:
- platform: adc
- pin: A0
+ pin: GPIOXX
name: "Living Room Brightness"
update_interval: 60s
diff --git a/components/sensor/adc128s102.rst b/components/sensor/adc128s102.rst
index 779997910..780d016d4 100644
--- a/components/sensor/adc128s102.rst
+++ b/components/sensor/adc128s102.rst
@@ -6,8 +6,8 @@ ADC128S102 8-Channel 12-Bit A/D Converter
:keywords: ADC128S102
:image: adc128s102.png
-The ADC128S102 is a low-power, eight-channel CMOS 12-bit analog-to-digital converter specified for conversion
-throughput rates of 500 ksps to 1 MSPS. The converter is based on a successive-approximation register architecture
+The ADC128S102 is a low-power, eight-channel CMOS 12-bit analog-to-digital converter specified for conversion
+throughput rates of 500 ksps to 1 MSPS. The converter is based on a successive-approximation register architecture
with an internal track-and-hold circuit.
.. figure:: images/adc128s102.png
@@ -31,16 +31,9 @@ sensors for your projects.
# Example configuration entry
adc128s102:
- cs_pin: GPIO15
+ cs_pin: GPIOXX
id: my_adc
- sensor:
- - platform: adc128s102 # Attached to pin 0 of the ADC128S102.
- update_interval: 1s
- adc128s102_id: my_adc
- id: freezer_temp_source
- channel: 0 # ADC128S102 channel
-
Configuration variables:
- **id** (**Required**, :ref:`config-id`): The id to use for this ADC128S102 component.
- **cs_pin** (**Required**, int): The SPI cable select pin to use
@@ -52,6 +45,15 @@ The ``adc128s102`` sensor allows you to use your ADC128S102 12-Bit A/D Converter
First, setup a :ref:`ADC128S102 Hub ` for your ADC128S102 sensor and then use this
sensor platform to create individual sensors that will report the voltage to Home Assistant.
+.. code-block:: yaml
+
+ sensor:
+ - platform: adc128s102 # Attached to pin 0 of the ADC128S102.
+ update_interval: 1s
+ adc128s102_id: my_adc
+ id: freezer_temp_source
+ channel: 0 # ADC128S102 channel
+
Configuration variables:
- **adc128s102_id** (**Required**, :ref:`config-id`): The id of the parent ADC128S102 component.
diff --git a/components/sensor/ade7880.rst b/components/sensor/ade7880.rst
index aca0c5a90..139aaf8e7 100644
--- a/components/sensor/ade7880.rst
+++ b/components/sensor/ade7880.rst
@@ -190,9 +190,9 @@ configured).
sensor:
- platform: ade7880
irq0_pin:
- number: GPIO13
+ number: GPIOXX
irq1_pin:
- number: GPIO5
+ number: GPIOXX
phase_a:
name: Room Heater
voltage: Voltage
@@ -217,9 +217,9 @@ Heater Current', etc.
sensor:
- platform: ade7880
irq0_pin:
- number: GPIO13
+ number: GPIOXX
irq1_pin:
- number: GPIO5
+ number: GPIOXX
phase_a:
voltage: Voltage
current:
@@ -249,11 +249,11 @@ configuration mode.
sensor:
- platform: ade7880
irq0_pin:
- number: GPIO13
+ number: GPIOXX
irq1_pin:
- number: GPIO5
+ number: GPIOXX
reset_pin:
- number: GPIO16
+ number: GPIOXX
frequency: 60Hz
phase_a:
name: Phase A
diff --git a/components/sensor/ade7953.rst b/components/sensor/ade7953.rst
index 4e486fc9d..c9aa54c02 100644
--- a/components/sensor/ade7953.rst
+++ b/components/sensor/ade7953.rst
@@ -35,7 +35,7 @@ Over I²C
# Example configuration entry for i2c
sensor:
- platform: ade7953_i2c
- irq_pin: GPIO16
+ irq_pin: GPIOXX
voltage:
name: ADE7953 Voltage
frequency:
@@ -122,75 +122,42 @@ Configuration variables:
- **active_power_gain_a** (*Optional*, int): Set the active power amplification of the A channel. Defaults to ``0x400000``.
- **active_power_gain_b** (*Optional*, int): Set the active power amplification of the B channel. Defaults to ``0x400000``.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``.
+- **use_accumulated_energy_registers** (*Optional*, boolean): Use ADE7935 accumulated energy registers instead of instant power registers. These registers store the accumulated energy since the last read and should provide better accuracy for power calculation. Defaults to ``false``.
Over SPI
--------
.. code-block:: yaml
- # Example configuration entry for SPI (taken from a Shelly Pro 4PM)
+ # Example configuration entry for SPI
sensor:
- platform: ade7953_spi
- cs_pin: GPIO04
- irq_pin: GPIO35
- current_pga_gain_a: 2x
- current_pga_gain_b: 2x
- current_gain_a: 0x600000
- current_gain_b: 0x600000
+ cs_pin: GPIOXX
+ irq_pin: GPIOXX
voltage:
name: "Voltage"
- filters:
- - delta: 1
frequency:
name: ADE7953 Frequency
- filters:
- - delta: 0.1
current_a:
name: "Current A"
- filters:
- - delta: 0.01
current_b:
name: "Current B"
- filters:
- - delta: 0.01
power_factor_a:
name: "Power Factor A"
- filters:
- - delta: 5
power_factor_b:
name: "ADE7953 Power Factor B"
- filters:
- - delta: 5
apparent_power_a:
name: "Apparent Power A"
- filters:
- - delta: 1
apparent_power_b:
name: "Apparent Power B"
- filters:
- - delta: 1
active_power_a:
name: "Power A"
- id: active_power_1
- # active_power is inverted, so multiply by -1
- filters:
- - multiply: -1
- - delta: 1
active_power_b:
name: "Power B"
- id: active_power_2
- # active_power is inverted, so multiply by -1
- filters:
- - multiply: -1
- - delta: 1
reactive_power_a:
name: "Reactive Power A"
- filters:
- - delta: 1
reactive_power_b:
name: "Reactive Power B"
- filters:
- - delta: 1
Configuration variables:
************************
@@ -253,6 +220,7 @@ Configuration variables:
- **active_power_gain_a** (*Optional*, int): Set the active power amplification of the A channel. Defaults to ``0x400000``.
- **active_power_gain_b** (*Optional*, int): Set the active power amplification of the B channel. Defaults to ``0x400000``.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``.
+- **use_accumulated_energy_registers** (*Optional*, boolean): Use ADE7935 accumulated energy registers instead of instant power registers. These registers store the accumulated energy since the last read and should provide better accuracy for power calculation. Defaults to ``false``.
Use with Shelly 2.5
-------------------
diff --git a/components/sensor/ads1115.rst b/components/sensor/ads1115.rst
index cc1640bcc..3e2eb83c4 100644
--- a/components/sensor/ads1115.rst
+++ b/components/sensor/ads1115.rst
@@ -36,7 +36,7 @@ Configuration variables:
- **address** (**Required**, int): The i²c address of the sensor.
See :ref:`I²C Addresses ` for more information.
- **continuous_mode** (*Optional*, boolean): Set if the ADS1115 should continuously measure voltages or
- only measure them when an update is called. Please enable this for the :doc:`ct_clamp` integration.
+ only measure them when an update is called. Please enable this for the :doc:`ct_clamp` component.
Defaults to ``off``.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID for this ADS1115 Hub. Use this if you
want to use multiple ADS1115 hubs at once.
diff --git a/components/sensor/ads1118.rst b/components/sensor/ads1118.rst
index 52947293b..416fcc05f 100644
--- a/components/sensor/ads1118.rst
+++ b/components/sensor/ads1118.rst
@@ -25,7 +25,7 @@ It uses the :ref:`SPI Bus ` for communication.
.. code-block:: yaml
ads1118:
- cs_pin: GPIO15
+ cs_pin: GPIOXX
Configuration variables:
************************
@@ -46,14 +46,12 @@ sensor platform to create individual sensors that will report the voltage.
.. code-block:: yaml
- ads1118:
- cs_pin: GPIO15
sensor:
- platform: ads1118
- type: 'adc'
- id: 'batt_volt'
- name: "Battery Voltage"
- multiplexer: 'A3_GND'
+ type: adc
+ id: batt_volt
+ name: Battery Voltage
+ multiplexer: A3_GND
gain: 4.096
update_interval: .01s
diff --git a/components/sensor/airthings_ble.rst b/components/sensor/airthings_ble.rst
index c29f966b4..e6fad15e7 100644
--- a/components/sensor/airthings_ble.rst
+++ b/components/sensor/airthings_ble.rst
@@ -135,8 +135,7 @@ Battery Level Reporting
***********************
If you wish to have the 'percentage of battery life remaining'
-reported as a sensor, you can make use of the :ref:`copy-sensor`
-integration.
+reported as a sensor, you can make use of the :ref:`copy-sensor` component.
The examples below are based on standard alkaline-chemistry batteries;
if you use other types of batteries you may need to adjust the
diff --git a/components/sensor/as3935.rst b/components/sensor/as3935.rst
index 7bc0aa4f0..c8e20951f 100644
--- a/components/sensor/as3935.rst
+++ b/components/sensor/as3935.rst
@@ -19,7 +19,7 @@ Component/Hub
The AS3935 can be configured to use either the SPI **or** I²C protocol for data communication.
First choose which communication method you want to use for the sensor, set the SI pin for the appropriate
-level and set up the ESPHome integration for the chosen communication method.
+level and set up the ESPHome component for the chosen communication method.
Module Pins
-----------
@@ -58,20 +58,10 @@ The ``as3935_spi`` sensor platform allows you to use your AS3935 sensor
.. code-block:: yaml
- # Example configuration for SPI (decide for one!)
+ # Example configuration for SPI
as3935_spi:
- cs_pin: GPIO12
- irq_pin: GPIO13
- # Example lightning and energy sensor
- sensor:
- - platform: as3935
- lightning_energy:
- name: "Lightning Energy"
- distance:
- name: "Distance Storm"
- binary_sensor:
- - platform: as3935
- name: "Storm Alert"
+ cs_pin: GPIOXX
+ irq_pin: GPIOXX
Configuration variables:
@@ -117,19 +107,9 @@ The ``as3935_i2c`` sensor platform allows you to use your AS3935 sensor
.. code-block:: yaml
- # Example configuration for I²C (decide for one!)
+ # Example configuration for I²C
as3935_i2c:
- irq_pin: GPIO12
- # Example shared configuration
- sensor:
- - platform: as3935
- lightning_energy:
- name: "Lightning Energy"
- distance:
- name: "Distance Storm"
- binary_sensor:
- - platform: as3935
- name: "Storm Alert"
+ irq_pin: GPIOXX
Configuration variables:
************************
@@ -173,19 +153,22 @@ Sensor
A sensor platform to read lightning data
+.. code-block:: yaml
+
+ sensor:
+ - platform: as3935
+ lightning_energy:
+ name: Lightning Energy
+ distance:
+ name: Distance Storm
+
Configuration variables:
- **lightning_energy** (*Optional*): Lightning energy value. According to the datasheet this is only a pure value that doesn't have any physical meaning.
-
- - **name** (**Required**, string): The name for the lightning energy sensor.
- - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- - All other options from :ref:`Sensor `.
+ All options from :ref:`Sensor `.
- **distance** (*Optional*): Distance in km to the front of the storm and not the distance to a lightning strike.
-
- - **name** (**Required**, string): The name for the distance sensor.
- - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- - All other options from :ref:`Sensor `.
+ All options from :ref:`Sensor `.
Binary Sensor
@@ -193,11 +176,16 @@ Binary Sensor
Binary sensor that indicates if a lightning strike was detected.
+.. code-block:: yaml
+
+ # Example storm alert binary sensor
+ binary_sensor:
+ - platform: as3935
+ name: Storm Alert
+
Configuration variables:
-- **name** (**Required**, string): The name of the binary sensor.
-- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
-- All other options from :ref:`Binary Sensor `.
+- All options from :ref:`Binary Sensor `.
See Also
diff --git a/components/sensor/as5600.rst b/components/sensor/as5600.rst
index 51fe34b41..80126e3f5 100644
--- a/components/sensor/as5600.rst
+++ b/components/sensor/as5600.rst
@@ -30,7 +30,7 @@ the :ref:`I²C Bus ` and connect the sensor to the pins specified there.
.. code-block:: yaml
as5600:
- dir_pin: 22
+ dir_pin: GPIOXX
start_position: 0deg
range: 180deg
@@ -39,7 +39,7 @@ Configuration variables:
- **dir_pin** (*Optional*, int): The pin connected to the AS5600's direction pin.
See :ref:`Direction ` for more information.
-- **direction** (*Optional*, string): The direction that the magnet should rotate to increase values.
+- **direction** (*Optional*, string): The direction that the magnet should rotate to increase values.
Used in combination with the **dir_pin**.
- ``clockwise`` (default)
@@ -57,7 +57,7 @@ Configuration variables:
- ``lsb2``
- ``lsb3``
-- **power_mode** (*Optional*, string): The power mode to run the sensor. Note: When **watchdog** is enabled,
+- **power_mode** (*Optional*, string): The power mode to run the sensor. Note: When **watchdog** is enabled,
it will switch the device to ``low3`` when there is not much change in position.
- ``nominal`` (default)
@@ -65,7 +65,7 @@ Configuration variables:
- ``low2``
- ``low3``
-- **watchdog** (*Optional*, boolean): Whether to enable the watchdog that puts the the chip in to
+- **watchdog** (*Optional*, boolean): Whether to enable the watchdog that puts the the chip in to
low power mode 3. Check the datasheet for more information.
Defaults to ``off``.
- **slow_filter** (*Optional*, string): See datasheet.
@@ -98,9 +98,9 @@ Direction
The AS5600 has ``direction`` pin that controls which rotation direction will cause the position value to **increase**.
This pin should be pulled low for clockwise, and pulled high for counterclockwise. If left floating, you are likely
-to encounter erratic behavior.
+to encounter erratic behavior.
-If you would like the ESP controller to pull that pin high or low, you may configure the ``dir_pin`` and optionally, the
+If you would like the ESP controller to pull that pin high or low, you may configure the ``dir_pin`` and optionally, the
``direction`` option to have the ESP controller pull the pin high or low.
.. _as5600_position_range:
@@ -136,7 +136,7 @@ For example, let's say we have the following component config:
start_position: 90deg
range: 180deg
direction: clockwise
- dir_pin: 22
+ dir_pin: GPIOXX
- If the magnet north was at the right side of the chip (i.e. 1024 / 90deg raw position), the scaled position would report a value of ``0``.
- If the magnet north was at the bottom of the chip (i.e. 2048 / 180deg raw position), the scaled position would report a value of ``2048``.
@@ -147,7 +147,7 @@ For example, let's say we have the following component config:
.. note::
You may specify an ``end_position`` that is less than the ``start_position``. When doing so, the allowable range will start at the
- ``start_position`` and continue through to the highest position value (i.e. ``4095``) and then continue from ``0`` until it reaches
+ ``start_position`` and continue through to the highest position value (i.e. ``4095``) and then continue from ``0`` until it reaches
the ``end_position``.
@@ -180,7 +180,7 @@ sensor platform to create individual sensors that will report the position to Ho
.. code-block:: yaml
as5600:
- dir_pin: 22
+ dir_pin: GPIOXX
sensor:
- platform: as5600
diff --git a/components/sensor/atm90e26.rst b/components/sensor/atm90e26.rst
index 63394ab26..ffbfcd271 100644
--- a/components/sensor/atm90e26.rst
+++ b/components/sensor/atm90e26.rst
@@ -21,8 +21,8 @@ Configuration variables:
- **cs_pin** (**Required**, :ref:`Pin Schema `): The pin CS is connected to. For the 6 channel meter main board, this will always be 5 and 4. For the add-on boards a jumper can be selected for each CS pin, but default to 0 and 16.
- **line_frequency** (**Required**, string): The AC line frequency of the supply voltage. One of ``50Hz``, ``60Hz``.
-- **meter_constant** (**Required**, float): The number of pulses per kWh. The ATM90E26 internally works based on pulses and
- this value converts a pulse into Wh, which are emitted as ``forward_active_energy`` etc. Matching it against an existing
+- **meter_constant** (**Required**, float): The number of pulses per kWh. The ATM90E26 internally works based on pulses and
+ this value converts a pulse into Wh, which are emitted as ``forward_active_energy`` etc. Matching it against an existing
meter is useful in that it allows visual confirmation for some devices that blink an LED for each pulse. Common values are
1000 pulses/kWh, 1666.66 pulses/kWh, or 3200 pulses/kWh. See also **gain_metering** which determines after how much energy
a pulse is emitted.
@@ -111,13 +111,13 @@ Keeping the calibration values at the top of your yaml might make editing easier
metering_cal: '7481' # default: 7481 - Calibrate this to match your meter based on the CF1 (CFx) pulse.
spi:
- clk_pin: 18
- miso_pin: 19
- mosi_pin: 23
+ clk_pin: GPIOXX
+ miso_pin: GPIOXX
+ mosi_pin: GPIOXX
sensor:
- platform: atm90e26
- cs_pin: 5
+ cs_pin: GPIOXX
voltage:
name: House Voltage
accuracy_decimals: 1
diff --git a/components/sensor/atm90e32.rst b/components/sensor/atm90e32.rst
index 198c3d118..000ccbd9a 100644
--- a/components/sensor/atm90e32.rst
+++ b/components/sensor/atm90e32.rst
@@ -168,7 +168,7 @@ a time-series-database, e.g. InfluxDB.
sensor:
#IC1 Main
- platform: atm90e32
- cs_pin: 5
+ cs_pin: GPIOXX
phase_a:
forward_active_energy:
name: ${disp_name} ct1 FAWattHours
@@ -208,13 +208,13 @@ Additional Examples
# Example configuration entry for split single phase meter
spi:
- clk_pin: 18
- miso_pin: 19
- mosi_pin: 23
+ clk_pin: GPIOXX
+ miso_pin: GPIOXX
+ mosi_pin: GPIOXX
sensor:
- platform: atm90e32
- cs_pin: 5
+ cs_pin: GPIOXX
phase_a:
voltage:
name: "EMON Line Voltage A"
diff --git a/components/sensor/binary_sensor_map.rst b/components/sensor/binary_sensor_map.rst
index 82e4ccf49..e23d0a014 100644
--- a/components/sensor/binary_sensor_map.rst
+++ b/components/sensor/binary_sensor_map.rst
@@ -6,17 +6,17 @@ Binary Sensor Map
:image: binary_sensor_map.jpg
The ``binary_sensor_map`` sensor platform allows you to map multiple :doc:`binary sensor `
-to an individual value. Depending on the state of each binary sensor, its associated configured parameters, and this sensor's mapping type,
+to an individual value. Depending on the state of each binary sensor, its associated configured parameters, and this sensor's mapping type,
the ``binary_sensor_map`` publishes a single numerical value.
-Use this sensor to combine one or more binary sensors' ``ON`` or ``OFF`` states into a numerical value. Some possible use cases include
+Use this sensor to combine one or more binary sensors' ``ON`` or ``OFF`` states into a numerical value. Some possible use cases include
touch devices and determining Bayesian probabilities for an event.
This platform supports three measurement types: ``BAYESIAN``, ``GROUP``, and ``SUM``.
You need to specify your desired mapping with the ``type:`` configuration value.
-When using the ``BAYESIAN`` type, add your binary sensors as ``observations`` to the binary sensor map.
-If you use the ``GROUP`` or ``SUM`` type, add your binary sensors as ``channels``.
+When using the ``BAYESIAN`` type, add your binary sensors as ``observations`` to the binary sensor map.
+If you use the ``GROUP`` or ``SUM`` type, add your binary sensors as ``channels``.
The maximum amount of observations/channels supported is 64.
- ``BAYESIAN`` This type replicates Home Assistant's `Bayesian sensor `.
+The communication with this component is done via a :ref:`UART `.
You must therefore have a ``uart:`` entry in your configuration with both the TX and RX pins set
to some pins on your board and the baud rate set to 4800 with 1 stop bit.
diff --git a/components/sensor/bl0942.rst b/components/sensor/bl0942.rst
index bd5d2921e..b2757725e 100644
--- a/components/sensor/bl0942.rst
+++ b/components/sensor/bl0942.rst
@@ -1,5 +1,5 @@
Belling BL0942 Energy Monitor
-==================================
+=============================
.. seo::
:description: Instructions for setting up BL0942 power monitors.
@@ -9,7 +9,7 @@ Belling BL0942 Energy Monitor
The ``bl0942`` sensor platform allows you to use BL0942 energy monitors sensors with
ESPHome. These are used in some Tuya-devices (e.g. Aubess Tuya WiFi Mini Smart Switch With Energy Monitor)
-The communication with this integration is done over a :ref:`UART bus `.
+The communication with this component is done via a :ref:`UART `.
You must therefore have a ``uart:`` entry in your configuration with both the TX and RX pins set
to some pins on your board and the baud rate set to 4800 with 1 stop bit.
@@ -50,7 +50,7 @@ Configuration variables:
- **current** (*Optional*): The current value of the sensor in Amperes. All options from
:ref:`Sensor `.
- **power** (*Optional*): The (active) power value of the sensor in Watts. Note that some power meters will report this in negative values (probably wired backwards), so you may want to use a filter to multiply it by -1. All options from :ref:`Sensor `.
-- **energy** (*Optional*): Use the voltage value of the sensor in kWh.
+- **energy** (*Optional*): Use the energy value of the sensor in kWh.
All options from :ref:`Sensor `.
- **frequency** (*Optional*): The frequency value of the sensor in Hertz. All options from
:ref:`Sensor `.
diff --git a/components/sensor/bme280.rst b/components/sensor/bme280.rst
index 15b667518..36c597df5 100644
--- a/components/sensor/bme280.rst
+++ b/components/sensor/bme280.rst
@@ -9,7 +9,7 @@ BME280 Temperature+Pressure+Humidity Sensor
The ``bme280`` sensor platform allows you to use your BME280
(`datasheet `__,
`Adafruit`_) temperature, pressure and humidity sensors with ESPHome. The sensor
-is used in *Forced Mode* where measurement is performed and then
+is used in *Forced Mode* where measurement is performed and then
the sensor returns to sleep mode until next measurement. The :ref:`I²C ` or :ref:`SPI ` is
required to be set up in your configuration for this sensor to work.
@@ -28,13 +28,10 @@ required to be set up in your configuration for this sensor to work.
- platform: bme280_i2c
temperature:
name: "BME280 Temperature"
- oversampling: 16x
pressure:
name: "BME280 Pressure"
humidity:
name: "BME280 Humidity"
- address: 0x77
- update_interval: 60s
# Example configuration entry SPI
@@ -42,40 +39,31 @@ required to be set up in your configuration for this sensor to work.
- platform: bme280_spi
temperature:
name: "BME280 Temperature"
- oversampling: 16x
pressure:
name: "BME280 Pressure"
humidity:
name: "BME280 Humidity"
- cs_pin: GPIO5
- update_interval: 60s
+ cs_pin: GPIOXX
Configuration variables:
------------------------
- **temperature** (*Optional*): The information for the temperature sensor.
- - **name** (**Required**, string): The name for the temperature
- sensor.
- **oversampling** (*Optional*): The oversampling parameter for the temperature sensor.
See :ref:`Oversampling Options `.
- - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor `.
- **pressure** (*Optional*): The information for the pressure sensor.
- - **name** (**Required**, string): The name for the pressure sensor.
- **oversampling** (*Optional*): The oversampling parameter for the temperature sensor.
See :ref:`Oversampling Options `.
- - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor `.
- **humidity** (*Optional*): The information for the pressure sensor.
- - **name** (**Required**, string): The name for the humidity sensor.
- **oversampling** (*Optional*): The oversampling parameter for the temperature sensor.
See :ref:`Oversampling Options `.
- - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor `.
- **address** (*Optional*, int): Manually specify the I²C address of
diff --git a/components/sensor/bme680_bsec.rst b/components/sensor/bme680_bsec.rst
index a182b1ec1..2b3e0780b 100644
--- a/components/sensor/bme680_bsec.rst
+++ b/components/sensor/bme680_bsec.rst
@@ -30,7 +30,7 @@ The :ref:`I²C ` is required to be set up in your configuration for this se
BME680 Temperature, Pressure, Humidity & Gas Sensor.
-.. _BSEC license agreement: https://www.bosch-sensortec.com/media/boschsensortec/downloads/bsec/2017-07-17_clickthrough_license_terms_environmentalib_sw_clean.pdf
+.. _BSEC license agreement: https://www.bosch-sensortec.com/media/boschsensortec/downloads/software/bme688_development_software/2023_04/license_terms_bme688_bme680_bsec.pdf
.. _Adafruit: https://www.adafruit.com/product/3660
diff --git a/components/sensor/bmp3xx.rst b/components/sensor/bmp3xx.rst
index 28ebee1db..af4f4d99e 100644
--- a/components/sensor/bmp3xx.rst
+++ b/components/sensor/bmp3xx.rst
@@ -7,8 +7,8 @@ BMP388 / BMP390 Temperature+Pressure Sensor
:keywords: BMP388 BMP390
The ``bmp3xx`` sensor platform allows you to use your BMP388 or BMP390
-(`datasheet `__, `BMP390 product page ` bus is
-required to be set up in your configuration for this sensor to work.
+(`datasheet `__, `BMP390 product page ` bus or :ref:`SPI ` bus is required to be set up in your configuration for this sensor to work.
.. figure:: images/bmp388.jpg
:align: center
@@ -16,11 +16,16 @@ required to be set up in your configuration for this sensor to work.
BMP388/BMP390 Temperature and Pressure Sensor.
+
+Over I²C
+--------
+The ``bmp3xx_i2c`` component allows you to use the device over :ref:`I²C ` interface.
+
.. code-block:: yaml
- # Example configuration entry
+ # Example configuration entry for I2C connection
sensor:
- - platform: bmp3xx
+ - platform: bmp3xx_i2c
temperature:
name: "Outside Temperature"
oversampling: 16x
@@ -29,34 +34,72 @@ required to be set up in your configuration for this sensor to work.
address: 0x77
update_interval: 60s
-Configuration variables:
-------------------------
+Configuration variables:
+************************
+
+- **address** (*Optional*, int): Manually specify the I²C address of the sensor. Defaults to ``0x77``.
+ Another address can be ``0x76``.
- **temperature** (*Optional*): The information for the temperature sensor.
- - **name** (**Required**, string): The name for the temperature
- sensor.
- **oversampling** (*Optional*): The oversampling parameter for the temperature sensor.
See :ref:`Oversampling Options `.
- - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor `.
- **pressure** (*Optional*): The information for the pressure sensor.
- - **name** (**Required**, string): The name for the pressure sensor.
- **oversampling** (*Optional*): The oversampling parameter for the temperature sensor.
See :ref:`Oversampling Options `.
- - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor `.
-- **address** (*Optional*, int): Manually specify the I²C address of
- the sensor. Defaults to ``0x77``. Another address can be ``0x76``.
- **iir_filter** (*Optional*): Set up an Infinite Impulse Response filter to increase accuracy. One of
``OFF``, ``2x``, ``4x``, ``16x``, ``32``, ``64x``, ``128x``. Defaults to ``OFF``.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the
sensor. Defaults to ``60s``.
+Over SPI
+--------
+The ``bmp3xx_spi`` component allows you to use the device over :ref:`SPI ` interface.
+
+.. code-block:: yaml
+
+ # Example configuration entry for SPI connection
+ sensor:
+ - platform: bmp3xx_spi
+ temperature:
+ name: "Outside Temperature"
+ oversampling: 16x
+ pressure:
+ name: "Outside Pressure"
+ cs_pin: 13
+ update_interval: 60s
+
+
+Configuration variables:
+************************
+
+- **cs_pin** (**Required**, :ref:`Pin Schema `): The Chip Select (CS) pin.
+- **temperature** (*Optional*): The information for the temperature sensor.
+
+ - **oversampling** (*Optional*): The oversampling parameter for the temperature sensor.
+ See :ref:`Oversampling Options `.
+ - All other options from :ref:`Sensor `.
+
+- **pressure** (*Optional*): The information for the pressure sensor.
+
+ - **oversampling** (*Optional*): The oversampling parameter for the temperature sensor.
+ See :ref:`Oversampling Options `.
+ - All other options from :ref:`Sensor `.
+
+- **iir_filter** (*Optional*): Set up an Infinite Impulse Response filter to increase accuracy. One of
+ ``OFF``, ``2x``, ``4x``, ``16x``, ``32``, ``64x``, ``128x``. Defaults to ``OFF``.
+- **address** (*Optional*, int): *I2C* only. Manually specify the I²C address of
+ the sensor. Defaults to ``0x77``. Another address can be ``0x76``.
+- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the
+ sensor. Defaults to ``60s``.
+
+
.. _bmp3xx-oversampling:
Oversampling Options
@@ -80,7 +123,7 @@ See Also
- :doc:`bmp280`
- :doc:`bme680`
- :doc:`bmp085`
-- :apiref:`bmp3xx/bmp3xx.h`
+- :apiref:`bmp3xx_base/bmp3xx_base.h`
- `BMP3 sensor API `__
- `BMP388/BMP390 Library `__ by Martin Lindupp
- :ghedit:`Edit`
diff --git a/components/sensor/ccs811.rst b/components/sensor/ccs811.rst
index 831d95ea8..95b4bde42 100644
--- a/components/sensor/ccs811.rst
+++ b/components/sensor/ccs811.rst
@@ -23,7 +23,7 @@ The ``ccs811`` sensor platform allows you to use CCS811 eCO_2 and volatile organ
.. _Adafruit: https://www.adafruit.com/product/3566
The communication with this sensor is done via :ref:`I²C Bus `, so you need to have
-an ``i2c:`` section in your config for this integration to work.
+an ``i2c:`` section in your config for this component to work.
.. code-block:: yaml
diff --git a/components/sensor/cs5460a.rst b/components/sensor/cs5460a.rst
index 0caa5b7ad..61a4136ce 100644
--- a/components/sensor/cs5460a.rst
+++ b/components/sensor/cs5460a.rst
@@ -35,11 +35,6 @@ driven by a GPIO or wired to VCC.
.. code-block:: yaml
# Example configuration entry
- spi:
- clk_pin: 18
- mosi_pin: 23
- miso_pin: 19
-
sensor:
- platform: cs5460a
current:
@@ -58,7 +53,7 @@ driven by a GPIO or wired to VCC.
current_gain: 0.01
voltage_gain: 0.000573
pulse_energy: 1 Wh
- cs_pin: 33
+ cs_pin: GPIOXX
Configuration variables:
------------------------
diff --git a/components/sensor/cse7761.rst b/components/sensor/cse7761.rst
index 64bb889c0..b1e856586 100644
--- a/components/sensor/cse7761.rst
+++ b/components/sensor/cse7761.rst
@@ -20,16 +20,6 @@ Additionally, you need to set the baud rate to 38400 and parity to ``EVEN``.
.. code-block:: yaml
# Example configuration entry
- # Disable logging over serial
- logger:
- baud_rate: 0
-
- uart:
- tx_pin: GPIO25
- rx_pin: GPIO26
- baud_rate: 38400
- parity: EVEN
-
sensor:
- platform: cse7761
voltage:
@@ -42,7 +32,6 @@ Additionally, you need to set the baud rate to 38400 and parity to ``EVEN``.
name: 'CSE7761 Active Power 1'
active_power_2:
name: 'CSE7761 Active Power 2'
- update_interval: 5s
.. note::
diff --git a/components/sensor/cse7766.rst b/components/sensor/cse7766.rst
index dcf6acd73..5b820555d 100644
--- a/components/sensor/cse7766.rst
+++ b/components/sensor/cse7766.rst
@@ -9,7 +9,7 @@ CSE7766 Power Sensor
The ``cse7766`` sensor platform allows you to use your CSE7766 voltage/current and power sensors
(`datasheet `__) sensors with
ESPHome. This sensor is commonly found in Sonoff POW R2. CSE7759B is similar to CSE7766
-and works with this integration.
+and works with this component.
.. note::
diff --git a/components/sensor/custom.rst b/components/sensor/custom.rst
index 76caada78..ad52cbeb5 100644
--- a/components/sensor/custom.rst
+++ b/components/sensor/custom.rst
@@ -1,16 +1,6 @@
Custom Sensor Component
=======================
-.. warning::
-
- Custom components are deprecated, not recommended for new configurations
- and will be removed from ESPHome in a future release.
- Please look at creating a real ESPHome component and "importing" it into your
- configuration with :doc:`/components/external_components`.
-
- You can find some basic documentation on creating your own components
- at :ref:`contributing_to_esphome`.
-
.. seo::
:description: Instructions for setting up Custom C++ sensors with ESPHome.
:image: language-cpp.svg
@@ -18,11 +8,18 @@ Custom Sensor Component
.. warning::
- While I do try to keep the ESPHome configuration options as stable as possible
- and back-port them, the ESPHome API is less stable. If something in the APIs needs
- to be changed in order for something else to work, I will do so.
+ Custom components are deprecated, not recommended for new configurations and will be removed from ESPHome in a
+ future release. Please look at creating a real ESPHome component and "importing" it into your configuration with
+ :doc:`/components/external_components`.
-So, you just set up ESPHome for your ESP32/ESP8266, but sadly ESPHome is missing a sensor integration
+ You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
+
+.. warning::
+
+ While we try to keep the ESPHome YAML configuration options as stable as possible, the ESPHome API is less
+ stable. If something in the APIs needs to be changed in order for something else to work, we will do so.
+
+So, you just set up ESPHome for your ESP32/ESP8266, but sadly ESPHome is missing a sensor component
you'd really like to have 😕. It's pretty much impossible to support every single sensor, as there are simply too many.
That's why ESPHome has a really simple API for you to create your own **custom sensors** 🎉
diff --git a/components/sensor/dallas.rst b/components/sensor/dallas.rst
index 45032c2d7..d5c046d9d 100644
--- a/components/sensor/dallas.rst
+++ b/components/sensor/dallas.rst
@@ -28,13 +28,7 @@ if you don't have massively long wires.
# Example configuration entry
dallas:
- - pin: 23
-
- # Individual sensors
- sensor:
- - platform: dallas
- address: 0x1c0000031edd2a28
- name: "Livingroom Temperature"
+ - pin: GPIOXX
Configuration variables:
************************
@@ -71,10 +65,6 @@ To initialize a sensor, first supply either ``address`` **or** ``index`` to iden
.. code-block:: yaml
- # Example configuration entry
- dallas:
- - pin: GPIO23
-
# Individual sensors
sensor:
- platform: dallas
@@ -114,7 +104,7 @@ the scanning will happen even with no sensors connected. For example with this c
# Example configuration entry
dallas:
- - pin: GPIO23
+ - pin: GPIOXX
# Note you don't have to add any sensors at this point
@@ -128,7 +118,7 @@ Now we can add the individual sensors to our configuration:
# Example configuration entry
dallas:
- - pin: GPIO23
+ - pin: GPIOXX
sensor:
- platform: dallas
@@ -154,9 +144,9 @@ Use this if you have multiple dallas hubs:
# Example configuration entry
dallas:
- - pin: GPIO23
+ - pin: GPIOXX
id: hub_1
- - pin: GPIO24
+ - pin: GPIOXX
id: hub_2
sensor:
diff --git a/components/sensor/daly_bms.rst b/components/sensor/daly_bms.rst
index cdb28600b..7fca68c04 100644
--- a/components/sensor/daly_bms.rst
+++ b/components/sensor/daly_bms.rst
@@ -15,18 +15,29 @@ The BMS communicates via :ref:`UART `.
:align: center
:width: 100.0%
+Component/Hub
+-------------
.. code-block:: yaml
- # Example configuration entry (ESP8266)
- uart:
- tx_pin: GPIO1
- rx_pin: GPIO3
- baud_rate: 9600
-
+ # Example configuration entry
daly_bms:
update_interval: 20s
+
+Configuration variables:
+************************
+
+- **update_interval** (*Optional*, :ref:`config-time`): Delay between data requests.
+- **address** (*Optional*, int): Address to use, defaults to ``0x80``.
+
+Sensor
+------
+
+A sensor platform to read BMS data
+
+.. code-block:: yaml
+
sensor:
- platform: daly_bms
voltage:
@@ -68,11 +79,81 @@ The BMS communicates via :ref:`UART `.
cell_4_voltage:
name: "Cell 4 Voltage"
+Configuration variables:
+************************
+
+- **voltage** (*Optional*): Voltage of the battery pack connected to Daly BMS.
+ All options from :ref:`Sensor `.
+
+- **current** (*Optional*): Current flowing trough the BMS (input or output from batttery).
+ All options from :ref:`Sensor `.
+
+- **battery_level** (*Optional*): Battery level in % (SoC).
+ All options from :ref:`Sensor `.
+
+- **max_cell_voltage** (*Optional*): The cell of the battery with the higher voltage.
+ All options from :ref:`Sensor `.
+
+- **max_cell_voltage_number** (*Optional*): The cell number of the battery with the higher voltage.
+ All options from :ref:`Sensor `.
+
+- **min_cell_voltage** (*Optional*): The cell of the battery with the lower voltage.
+ All options from :ref:`Sensor `.
+
+- **min_cell_voltage_number** (*Optional*): The cell number of the battery with the lower voltage.
+ All options from :ref:`Sensor `.
+
+- **max_temperature** (*Optional*): The higher temperature measured from the temperature sensors.
+ All options from :ref:`Sensor `.
+
+- **max_temperature_probe_number** (*Optional*): The sensor number which has measured the higher temperature.
+ All options from :ref:`Sensor `.
+
+- **min_temperature** (*Optional*): The lower temperature measured from the temperature sensors.
+ All options from :ref:`Sensor `.
+
+- **min_temperature_probe_number** (*Optional*): The sensor number which has measured the lower temperature.
+ All options from :ref:`Sensor `.
+
+- **remaining_capacity** (*Optional*): The capacity in Ah left in the battery.
+ All options from :ref:`Sensor `.
+
+- **cells_number** (*Optional*): The number of cells in series in the battery pack.
+ All options from :ref:`Sensor `.
+
+- **temperature_1** (*Optional*): The first temperature sensor.
+ All options from :ref:`Sensor `.
+
+- **temperature_2** (*Optional*): The second temperature sensor.
+ All options from :ref:`Sensor `.
+
+- **cell_1_voltage** (*Optional*): The voltage of cell number 1. Cell number can be from 1 to 16.
+ All options from :ref:`Sensor `.
+
+Text Sensor
+-----------
+
+Text sensor that indicates the status of BMS.
+
+.. code-block:: yaml
+
text_sensor:
- platform: daly_bms
status:
name: "BMS Status"
+Configuration variables:
+************************
+
+- **status** (*Optional*): The BMS Status (Charging, Discharging, Stationary).
+ All options from :ref:`Text Sensor `.
+
+Binary Sensor
+-------------
+
+Binary sensor that indicates the status of MOS.
+
+.. code-block:: yaml
binary_sensor:
- platform: daly_bms
@@ -81,163 +162,25 @@ The BMS communicates via :ref:`UART `.
discharging_mos_enabled:
name: "Discharging MOS"
-Component/Hub
--------------
-
-Configuration variables:
-************************
-
-- **update_interval** (*Optional*, :ref:`config-time`): Delay between data requests.
-- **address** (*Optional*, int): Address to use, defaults to ``0x80``.
-
-Sensor
-------
-
-A sensor platform to read BMS data
-
-Configuration variables:
-************************
-
-- **voltage** (*Optional*): Voltage of the battery pack connected to Daly BMS.
-
- - **name** (**Required**, string): The name for the voltage sensor.
- - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- - All other options from :ref:`Sensor `.
-
-- **current** (*Optional*): Current flowing trough the BMS (input or output from batttery).
-
- - **name** (**Required**, string): The name for the current sensor.
- - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- - All other options from :ref:`Sensor `.
-
-- **battery_level** (*Optional*): Battery level in % (SoC).
-
- - **name** (**Required**, string): The name for the SoC sensor.
- - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- - All other options from :ref:`Sensor `.
-
-- **max_cell_voltage** (*Optional*): The cell of the battery with the higher voltage.
-
- - **name** (**Required**, string): The name for the Max Cell Voltage sensor.
- - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- - All other options from :ref:`Sensor `.
-
-- **max_cell_voltage_number** (*Optional*): The cell number of the battery with the higher voltage.
-
- - **name** (**Required**, string): The name for the Max Cell Voltage Number sensor.
- - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- - All other options from :ref:`Sensor `.
-
-- **min_cell_voltage** (*Optional*): The cell of the battery with the lower voltage.
-
- - **name** (**Required**, string): The name for the Min Cell Voltage sensor.
- - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- - All other options from :ref:`Sensor `.
-
-- **min_cell_voltage_number** (*Optional*): The cell number of the battery with the lower voltage.
-
- - **name** (**Required**, string): The name for the Min Cell Voltage Number sensor.
- - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- - All other options from :ref:`Sensor `.
-
-- **max_temperature** (*Optional*): The higher temperature measured from the temperature sensors.
-
- - **name** (**Required**, string): The name for the Max Temperature sensor.
- - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- - All other options from :ref:`Sensor `.
-
-- **max_temperature_probe_number** (*Optional*): The sensor number which has measured the higher temperature.
-
- - **name** (**Required**, string): The name for the Max Temperature Probe Number sensor.
- - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- - All other options from :ref:`Sensor
+
+Then:
+
+#. Fnd your device in the device list
+#. Click the "configure" button next to it
+#. Check the "Allow the device to make Home Assistant service calls" box
+#. Then click "submit".
+
.. _api-homeassistant_event_action:
``homeassistant.event`` Action
******************************
+.. note::
+
+ Be sure to :ref:`follow the instructions above