diff --git a/Doxygen b/Doxygen index dfa8248bae..9617eeba8e 100644 --- a/Doxygen +++ b/Doxygen @@ -38,7 +38,7 @@ PROJECT_NAME = "ESPHome" # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = 2023.7.1 +PROJECT_NUMBER = 2023.8.0 # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a diff --git a/Makefile b/Makefile index b2b918c5f4..5257a2d447 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,5 @@ ESPHOME_PATH = ../esphome -ESPHOME_REF = 2023.7.1 +ESPHOME_REF = 2023.8.0 .PHONY: html html-strict cleanhtml deploy help live-html Makefile netlify netlify-api api netlify-dependencies svg2png copy-svg2png minify diff --git a/_static/changelog-2023.8.0.png b/_static/changelog-2023.8.0.png new file mode 100644 index 0000000000..f043242443 Binary files /dev/null and b/_static/changelog-2023.8.0.png differ diff --git a/_static/version b/_static/version index 94cb2296c0..a4fb2c1264 100644 --- a/_static/version +++ b/_static/version @@ -1 +1 @@ -2023.7.1 \ No newline at end of file +2023.8.0 \ No newline at end of file diff --git a/changelog/2023.8.0.rst b/changelog/2023.8.0.rst new file mode 100644 index 0000000000..06fe5cac67 --- /dev/null +++ b/changelog/2023.8.0.rst @@ -0,0 +1,192 @@ +ESPHome 2023.8.0 - 16th August 2023 +=================================== + +.. seo:: + :description: Changelog for ESPHome 2023.8.0. + :image: /_static/changelog-2023.8.0.png + :author: Jesse Hills + :author_twitter: @jesserockz + +.. imgtable:: + :columns: 2 + + A01NYUB, components/sensor/a01nyub, a01nyub.jpg + KMeterISO, components/sensor/kmeteriso, kmeteriso.jpg + BMP581, components/sensor/bmp581, bmp581.jpg + GCJA5, components/sensor/gcja5, gcja5.svg + +LD2410 +------ + +The LD2410 component has had a massive upgrade thanks to :ghuser:`regevbr`! +It now supports settings most if not all configuration parameters via ``switches`` / ``numbers`` and ``selects`` +and exposes more data via various ``sensors``. +This includes breaking changes that mean the existing gate configuration options have been moved to the ``number`` platform. + +Full list of changes +-------------------- + +New Components +^^^^^^^^^^^^^^ + +- Add support for a01nyub :esphomepr:`4863` by :ghuser:`MrSuicideParrot` (new-integration) +- Add KMeterISO component. :esphomepr:`5170` by :ghuser:`Rudd-O` (new-integration) +- New component: Add support for bmp581 pressure and temperature sensors :esphomepr:`4657` by :ghuser:`kahrendt` (new-integration) +- New PM sensor Panasonic SN-GCJA5 :esphomepr:`4988` by :ghuser:`gcormier` (new-integration) +- Add configuration flow abilites to the ld2410 component :esphomepr:`4434` by :ghuser:`regevbr` (new-integration) (notable-change) (breaking-change) + +Breaking Changes +^^^^^^^^^^^^^^^^ + +- Coolix IR protocol improvements :esphomepr:`5105` by :ghuser:`dudanov` (breaking-change) +- Speaker return bytes written and do not wait for queue :esphomepr:`5182` by :ghuser:`jesserockz` (breaking-change) +- Change device name in MQTT discovery messages to friendly names :esphomepr:`5205` by :ghuser:`pidpawel` (breaking-change) +- Add configuration flow abilites to the ld2410 component :esphomepr:`4434` by :ghuser:`regevbr` (new-integration) (notable-change) (breaking-change) + +Beta Changes +^^^^^^^^^^^^ + +- Read string of bool env and match against well known values :esphomepr:`5232` by :ghuser:`jesserockz` +- fix aeha data template :esphomepr:`5231` by :ghuser:`ssieb` +- Expose start to speaker interface :esphomepr:`5228` by :ghuser:`jesserockz` +- New features added for Haier integration :esphomepr:`5196` by :ghuser:`paveldn` +- pca9554 cache reads :esphomepr:`5137` by :ghuser:`hwstar` +- fix midea: undo approved PR#4053 :esphomepr:`5233` by :ghuser:`dudanov` +- Fixing smartair2 protocol implementation if no Wi-Fi :esphomepr:`5238` by :ghuser:`paveldn` +- tuya: add time sync callback only once to prevent memleak :esphomepr:`5234` by :ghuser:`afflux` +- Fix duplicate tuya time warning :esphomepr:`5243` by :ghuser:`jesserockz` +- Change XL9535 `setup_priority` to IO :esphomepr:`5246` by :ghuser:`mreditor97` +- rmt_base additional minor changes :esphomepr:`5245` by :ghuser:`dudanov` +- Fix 24 bit signed integer parsing in sml parser :esphomepr:`5250` by :ghuser:`mulder-fbi` +- Fix IDFI2CBus::writev ignoring stop parameter :esphomepr:`4840` by :ghuser:`CarsonF` +- Add configuration flow abilites to the ld2410 component :esphomepr:`4434` by :ghuser:`regevbr` (new-integration) (notable-change) (breaking-change) + +Notable Changes +^^^^^^^^^^^^^^^ + +- Change MQTT client for ESP32 Arduino :esphomepr:`5157` by :ghuser:`HeMan` (notable-change) +- Add configuration flow abilites to the ld2410 component :esphomepr:`4434` by :ghuser:`regevbr` (new-integration) (notable-change) (breaking-change) + +All changes +^^^^^^^^^^^ + +- Mk2 to prepare color.h for idf >= 5 :esphomepr:`5070` by :ghuser:`HeMan` +- display: Add helper methods to `Display::clip` and `Display::clamp_x/y_` :esphomepr:`5003` by :ghuser:`ayufan` +- Mark repo as safe directory to git config :esphomepr:`5102` by :ghuser:`davet2001` +- Bump click from 8.1.3 to 8.1.5 :esphomepr:`5099` by :ghuser:`dependabot[bot]` +- Bump pyyaml from 6.0 to 6.0.1 :esphomepr:`5117` by :ghuser:`dependabot[bot]` +- ignore components folder in root :esphomepr:`5130` by :ghuser:`jesserockz` +- Add size getter to CallbackManager :esphomepr:`5129` by :ghuser:`jesserockz` +- Make docker use pip installed pillow :esphomepr:`5074` by :ghuser:`HeMan` +- Change datatype in e131 addressable light :esphomepr:`5127` by :ghuser:`HeMan` +- Streamer mode :esphomepr:`5119` by :ghuser:`grahambrown11` +- Version bump for ESP32 IDF and Arduino :esphomepr:`5035` by :ghuser:`HeMan` +- Synchronise Device Classes from Home Assistant :esphomepr:`5136` by :ghuser:`esphomebot` +- Update known boards to 5.4.0 :esphomepr:`5134` by :ghuser:`jesserockz` +- Init colorama in ESPHome main :esphomepr:`5111` by :ghuser:`kuba2k2` +- Coolix IR protocol improvements :esphomepr:`5105` by :ghuser:`dudanov` (breaking-change) +- Allow esp32 idf components to specify submodules and specific components :esphomepr:`5128` by :ghuser:`jesserockz` +- Synchronise Device Classes from Home Assistant :esphomepr:`5147` by :ghuser:`esphomebot` +- Prepare some components for IDF >= 5 :esphomepr:`5061` by :ghuser:`HeMan` +- Bump clang-tidy from 11 to 14 :esphomepr:`5160` by :ghuser:`dudanov` +- climate triggers Climate and ClimateCall references :esphomepr:`5028` by :ghuser:`dudanov` +- remote_base changes :esphomepr:`5124` by :ghuser:`dudanov` +- Add 'map_linear' and 'clamp' sensor filters :esphomepr:`5040` by :ghuser:`Mat931` +- Adding Inkplate 6 v2 model variant :esphomepr:`5165` by :ghuser:`mullerdavid` +- duty_time: fix build without binary_sensor. Parented in automations. :esphomepr:`5156` by :ghuser:`dudanov` +- Add standardized CRC helper functions :esphomepr:`4798` by :ghuser:`Mat931` +- Enable IPv6 for ESP32 Arduino, wifi and ethernet :esphomepr:`4865` by :ghuser:`HeMan` +- Bump zeroconf from 0.69.0 to 0.71.4 :esphomepr:`5148` by :ghuser:`dependabot[bot]` +- Bump black from 23.3.0 to 23.7.0 :esphomepr:`5126` by :ghuser:`dependabot[bot]` +- Bump pylint from 2.17.4 to 2.17.5 :esphomepr:`5172` by :ghuser:`dependabot[bot]` +- Bump pyupgrade from 3.7.0 to 3.9.0 :esphomepr:`5083` by :ghuser:`dependabot[bot]` +- Vertical and horizontal airflow actions fix for Haier climate :esphomepr:`5164` by :ghuser:`paveldn` +- Microphone add is_stopped :esphomepr:`5183` by :ghuser:`jesserockz` +- Add get_board function to esp32 module :esphomepr:`5184` by :ghuser:`jesserockz` +- Speaker return bytes written and do not wait for queue :esphomepr:`5182` by :ghuser:`jesserockz` (breaking-change) +- Update components "if x in config" :esphomepr:`5181` by :ghuser:`jesserockz` +- Bump click from 8.1.5 to 8.1.6 :esphomepr:`5179` by :ghuser:`dependabot[bot]` +- PWM Output on RP2040 for high frequencies :esphomepr:`5204` by :ghuser:`matemaciek` +- Fix some configs after #5181 :esphomepr:`5209` by :ghuser:`jesserockz` +- Improved compensation sgp30 :esphomepr:`5208` by :ghuser:`arno1801` +- Add support for a01nyub :esphomepr:`4863` by :ghuser:`MrSuicideParrot` (new-integration) +- Change device name in MQTT discovery messages to friendly names :esphomepr:`5205` by :ghuser:`pidpawel` (breaking-change) +- Add ESP32-S2/S3 capacitive touch support :esphomepr:`5116` by :ghuser:`kbx81` +- Bump zeroconf from 0.71.4 to 0.74.0 :esphomepr:`5199` by :ghuser:`dependabot[bot]` +- Implemented Waveshare 7.5in B V3 :esphomepr:`5210` by :ghuser:`lucasprim` +- Refactor `pulse_meter` to better handle higher frequencies :esphomepr:`4231` by :ghuser:`TrentHouliston` +- Change MQTT client for ESP32 Arduino :esphomepr:`5157` by :ghuser:`HeMan` (notable-change) +- Add read interface to microphone :esphomepr:`5131` by :ghuser:`jesserockz` +- i2c: fix build on ESP-IDF >= 5.1 :esphomepr:`5200` by :ghuser:`stintel` +- Add socket define for rp2040 dev :esphomepr:`4968` by :ghuser:`jesserockz` +- core: read ESP32 MAC address from eFuse if IEEE802.15.4 is supported :esphomepr:`5176` by :ghuser:`stintel` +- esp32_ble_beacon: enable CONFIG_BT_BLE_42_FEATURES_SUPPORTED :esphomepr:`5211` by :ghuser:`stintel` +- Bump pytest-asyncio from 0.21.0 to 0.21.1 :esphomepr:`5187` by :ghuser:`dependabot[bot]` +- ledc: check SOC_LEDC_SUPPORT_APB_CLOCK :esphomepr:`5212` by :ghuser:`stintel` +- Add arm night to alarm control panel :esphomepr:`5186` by :ghuser:`primeroz` +- Bump pyupgrade from 3.9.0 to 3.10.1 :esphomepr:`5189` by :ghuser:`dependabot[bot]` +- Add KMeterISO component. :esphomepr:`5170` by :ghuser:`Rudd-O` (new-integration) +- Bump platformio from 6.1.7 to 6.1.9 :esphomepr:`5066` by :ghuser:`dependabot[bot]` +- New component: Add support for bmp581 pressure and temperature sensors :esphomepr:`4657` by :ghuser:`kahrendt` (new-integration) +- New PM sensor Panasonic SN-GCJA5 :esphomepr:`4988` by :ghuser:`gcormier` (new-integration) +- Daly BMS improvements :esphomepr:`3388` by :ghuser:`matthias882` +- Add missing `on_(arming|pending|armed_home|armed_night|armed_away|disarmed)` triggers to alarm_control_panel :esphomepr:`5219` by :ghuser:`primeroz` +- add value option to timeout filter :esphomepr:`5222` by :ghuser:`ssieb` +- Tweak Color init because IDF 5+ :esphomepr:`5221` by :ghuser:`kbx81` +- Read string of bool env and match against well known values :esphomepr:`5232` by :ghuser:`jesserockz` +- fix aeha data template :esphomepr:`5231` by :ghuser:`ssieb` +- Expose start to speaker interface :esphomepr:`5228` by :ghuser:`jesserockz` +- New features added for Haier integration :esphomepr:`5196` by :ghuser:`paveldn` +- pca9554 cache reads :esphomepr:`5137` by :ghuser:`hwstar` +- fix midea: undo approved PR#4053 :esphomepr:`5233` by :ghuser:`dudanov` +- Fixing smartair2 protocol implementation if no Wi-Fi :esphomepr:`5238` by :ghuser:`paveldn` +- tuya: add time sync callback only once to prevent memleak :esphomepr:`5234` by :ghuser:`afflux` +- Fix duplicate tuya time warning :esphomepr:`5243` by :ghuser:`jesserockz` +- Change XL9535 `setup_priority` to IO :esphomepr:`5246` by :ghuser:`mreditor97` +- rmt_base additional minor changes :esphomepr:`5245` by :ghuser:`dudanov` +- Fix 24 bit signed integer parsing in sml parser :esphomepr:`5250` by :ghuser:`mulder-fbi` +- Fix IDFI2CBus::writev ignoring stop parameter :esphomepr:`4840` by :ghuser:`CarsonF` +- Add configuration flow abilites to the ld2410 component :esphomepr:`4434` by :ghuser:`regevbr` (new-integration) (notable-change) (breaking-change) +- Add `libfreetype-dev` Debian package for armv7 Docker builds :esphomepr:`5262` by :ghuser:`pierlon` +- Add delay before enabling ipv6 :esphomepr:`5256` by :ghuser:`HeMan` +- Bump zeroconf from 0.74.0 to 0.80.0 :esphomepr:`5260` by :ghuser:`dependabot[bot]` + +Past Changelogs +--------------- + +- :doc:`2023.7.0` +- :doc:`2023.6.0` +- :doc:`2023.5.0` +- :doc:`2023.4.0` +- :doc:`2023.3.0` +- :doc:`2023.2.0` +- :doc:`2022.12.0` +- :doc:`2022.11.0` +- :doc:`2022.10.0` +- :doc:`2022.9.0` +- :doc:`2022.8.0` +- :doc:`2022.6.0` +- :doc:`2022.5.0` +- :doc:`2022.4.0` +- :doc:`2022.3.0` +- :doc:`2022.2.0` +- :doc:`2022.1.0` +- :doc:`2021.12.0` +- :doc:`2021.11.0` +- :doc:`2021.10.0` +- :doc:`2021.9.0` +- :doc:`2021.8.0` +- :doc:`v1.20.0` +- :doc:`v1.19.0` +- :doc:`v1.18.0` +- :doc:`v1.17.0` +- :doc:`v1.16.0` +- :doc:`v1.15.0` +- :doc:`v1.14.0` +- :doc:`v1.13.0` +- :doc:`v1.12.0` +- :doc:`v1.11.0` +- :doc:`v1.10.0` +- :doc:`v1.9.0` +- :doc:`v1.8.0` +- :doc:`v1.7.0` diff --git a/changelog/index.rst b/changelog/index.rst index 433d87bacd..dd73ab54e5 100644 --- a/changelog/index.rst +++ b/changelog/index.rst @@ -2,7 +2,7 @@ Changelog ========= .. redirect:: - :url: /changelog/2023.7.0.html + :url: /changelog/2023.8.0.html .. toctree:: :glob: diff --git a/components/alarm_control_panel/index.rst b/components/alarm_control_panel/index.rst index 124e7e5056..6fe6b8656d 100644 --- a/components/alarm_control_panel/index.rst +++ b/components/alarm_control_panel/index.rst @@ -28,8 +28,20 @@ Configuration variables: - **on_state** (*Optional*, :ref:`Action `): An automation to perform when the alarm changes state. See :ref:`alarm_control_panel_on_state_trigger`. +- **on_arming** (*Optional*, :ref:`Action `): An automation to perform + when the alarm state changes to `arming`. See :ref:`alarm_control_panel_on_arming_trigger`. +- **on_pending** (*Optional*, :ref:`Action `): An automation to perform + when the alarm state changes to `pending`. See :ref:`alarm_control_panel_on_pending_trigger`. +- **on_armed_home** (*Optional*, :ref:`Action `): An automation to perform + when the alarm state changes to `armed_home`. See :ref:`alarm_control_panel_on_armed_home_trigger`. +- **on_armed_night** (*Optional*, :ref:`Action `): An automation to perform + when the alarm state changes to `armed_night`. See :ref:`alarm_control_panel_on_armed_night_trigger`. +- **on_armed_away** (*Optional*, :ref:`Action `): An automation to perform + when the alarm state changes to `armed_away`. See :ref:`alarm_control_panel_on_armed_away_trigger`. - **on_triggered** (*Optional*, :ref:`Action `): An automation to perform when the alarm triggers. See :ref:`alarm_control_panel_on_triggered_trigger`. +- **on_disarmed** (*Optional*, :ref:`Action `): An automation to perform + when the alarm state changes to `disarmed`. See :ref:`alarm_control_panel_on_disarmed_trigger`. - **on_cleared** (*Optional*, :ref:`Action `): An automation to perform when the alarm clears. See :ref:`alarm_control_panel_on_cleared_trigger`. @@ -52,6 +64,81 @@ This trigger is activated each time the alarm changes state. then: - logger.log: "Alarm Panel State Changed!" +.. _alarm_control_panel_on_pending_trigger: + +``on_pending`` Trigger +********************** + +This trigger is activated when the alarm changes to pending state. + +.. code-block:: yaml + + alarm_control_panel: + # ... + on_pending: + then: + - logger.log: "Alarm Pending!" + +.. _alarm_control_panel_on_arming_trigger: + +``on_arming`` Trigger +********************* + +This trigger is activated when the alarm changes to arming state. + +.. code-block:: yaml + + alarm_control_panel: + # ... + on_arming: + then: + - logger.log: "Alarm Arming!" + +.. _alarm_control_panel_on_armed_home_trigger: + +``on_armed_home`` Trigger +************************* + +This trigger is activated when the alarm changes to armed_home state. + +.. code-block:: yaml + + alarm_control_panel: + # ... + on_armed_home: + then: + - logger.log: "Alarm armed_home!" + +.. _alarm_control_panel_on_armed_night_trigger: + +``on_armed_night`` Trigger +************************** + +This trigger is activated when the alarm changes to armed_night state. + +.. code-block:: yaml + + alarm_control_panel: + # ... + on_armed_night: + then: + - logger.log: "Alarm armed_night!" + +.. _alarm_control_panel_on_armed_away_trigger: + +``on_armed_away`` Trigger +************************* + +This trigger is activated when the alarm changes to armed_away state. + +.. code-block:: yaml + + alarm_control_panel: + # ... + on_armed_away: + then: + - logger.log: "Alarm armed_away!" + .. _alarm_control_panel_on_triggered_trigger: ``on_triggered`` Trigger @@ -82,6 +169,21 @@ This trigger is activated when the alarm changes from triggered back to either t then: - logger.log: "Alarm Cleared!" +.. _alarm_control_panel_on_disarmed_trigger: + +``on_disarmed`` Trigger +*********************** + +This trigger is activated when the alarm changes from to disarmed. + +.. code-block:: yaml + + alarm_control_panel: + # ... + on_disarmed: + then: + - logger.log: "Alarm Disarmed!" + .. _alarm_control_panel_arm_away_action: ``arm_away`` Action @@ -112,6 +214,21 @@ This action arms the alarm in home mode. The ``code`` is required when *requires id: acp1 code: "1234" +.. _alarm_control_panel_arm_night_action: + +``arm_night`` Action +******************** + +This action arms the alarm in night mode. The ``code`` is required when *requires_code_to_arm* is *true*. + +.. code-block:: yaml + + on_...: + then: + - alarm_control_panel.arm_night: + id: acp1 + code: "1234" + .. _alarm_control_panel_disarm_action: ``disarm`` Action @@ -177,12 +294,14 @@ From :ref:`lambdas `, you can call the following methods: - ``arm_away(code)`` - ``arm_home(code)`` +- ``arm_night(code)`` - ``disarm(code)`` .. code-block:: cpp id(acp1).arm_away(); id(acp1).arm_home(); + id(acp1).arm_night(); id(acp1).disarm(std::string("1234")); diff --git a/components/alarm_control_panel/template.rst b/components/alarm_control_panel/template.rst index 1336a422a9..71d214d469 100644 --- a/components/alarm_control_panel/template.rst +++ b/components/alarm_control_panel/template.rst @@ -28,12 +28,14 @@ Configuration variables: - **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. - **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: - **input** (**Required**, string): The id of the binary sensor component - **bypass_armed_home** (*Optional*, boolean): This binary sensor will not trigger the alarm when in ``armed_home`` state. + - **bypass_armed_night** (*Optional*, boolean): This binary sensor will not trigger the alarm when in ``armed_night`` state. - **restore_mode** (*Optional*, enum): diff --git a/components/binary_sensor/esp32_touch.rst b/components/binary_sensor/esp32_touch.rst index 30b301d9bb..e5bbcd2ed3 100644 --- a/components/binary_sensor/esp32_touch.rst +++ b/components/binary_sensor/esp32_touch.rst @@ -2,16 +2,23 @@ ESP32 Touch Pad =============== .. seo:: - :description: Instructions for setting up the touch pad on the ESP32. + :description: Instructions for setting up the touch pad on the ESP32 :image: touch.svg +Capacitive touch detection is possible on ESP32, ESP32-S2 or ESP32-S3 processors. +In ESPHome, it is configured in two parts: + +- :ref:`esp32-touch-component` +- :ref:`esp32-touch-binary-sensor` + .. _esp32-touch-component: Component/Hub ------------- -The ``esp32_touch`` component creates a global hub for detecting touches on -the eight touch pads of the ESP32 as :ref:`binary sensors `. +The ``esp32_touch`` component creates a global hub enabling (capacitive) touch detection on GPIO pins +:ref:`supported by ESP32, ESP32-S2 or ESP32-S3 processors `. With this enabled, +:ref:`binary sensors ` may then be configured to permit touch detection. .. code-block:: yaml @@ -19,42 +26,85 @@ the eight touch pads of the ESP32 as :ref:`binary sensors ` - for more information. Defaults to false. + will spam the logs. See :ref:`setting up touch pads ` + for more information. Defaults to ``false``. - **id** (*Optional*, :ref:`config-id`): Manually specify the ID for code generation. -Advanced options (the defaults are usually quite good, but if you're having accuracy issues, use these): +**Advanced options** + +These variables may be added to the hub component's configuration (above) and are useful for fine-tuning and/or when +the sensors aren't behaving as expected. + +*All processors:* -- **iir_filter** (*Optional*, :ref:`config-time`): Optionally set up an - `Infinite Impulse Response `__ - filter should be applied to all touch pads. This can increase the accuracy of the touch pads a lot, but - higher values decrease the response time. A good value to start with is ``10ms``. Default is no IIR filter. - **sleep_duration** (*Optional*, :ref:`config-time`): Set a time period denoting the amount of time the touch peripheral should sleep between measurements. This can decrease power usage but make the sensor slower. Default is about 27 milliseconds. - **measurement_duration** (*Optional*, :ref:`config-time`): Set the conversion time for all touch pads. A longer conversion time means that more charge/discharge cycles of the touch pad can be performed, therefore increasing accuracy. Default is about 8ms, the maximum amount. -- **low_voltage_reference** (*Optional*): The low voltage reference to use for the charge cycles. See - the `esp-idf docs `__ - for a nice explanation of this. One of ``0.5V``, ``0.6V``, ``0.7V``, ``0.8V``. Default is ``0.5V``. -- **high_voltage_reference** (*Optional*): The high voltage reference to use for the charge cycles. See - the `esp-idf docs `__ - for a nice explanation of this. One of ``2.4V``, ``2.5V``, ``2.6V``, ``2.7V``. Default is ``2.7V``. -- **voltage_attenuation** (*Optional*): The voltage attenuation to use for the charge cycles. See - the `esp-idf docs `__ - for a nice explanation of this. One of ``1.5V``, ``1V``, ``0.5V``, ``0V``. Default is ``0V``. +- **low_voltage_reference** (*Optional*): The low voltage reference to use for the charge cycles. One of ``0.5V``, + ``0.6V``, ``0.7V``, ``0.8V``. Default is ``0.5V``. +- **high_voltage_reference** (*Optional*): The high voltage reference to use for the charge cycles. One of ``2.4V``, + ``2.5V``, ``2.6V``, ``2.7V``. Default is ``2.7V``. +- **voltage_attenuation** (*Optional*): The voltage attenuation to use for the charge cycles. One of ``1.5V``, ``1V``, + ``0.5V``, ``0V``. Default is ``0V``. + +For a more detailed explanation of the parameters above, please see the +`ESP-IDF documentation. `__ + +*ESP32 only* + +- **iir_filter** (*Optional*, :ref:`config-time`): Optionally set up an + `Infinite Impulse Response `__ + filter should be applied to all touch pads. This can increase the accuracy of the touch pads a lot, but higher values + decrease the response time. A good value to start with is ``10ms``. By default, the IIR filter is inactive. + +*ESP32-S2 and ESP32-S3 only* + +**For each configuration category below, if one option is specified, all options must be specified.** The configuration +options below do not have any default values; in other words, they are inactive by default. + +Filter configuration: + +- **filter_mode** (*Optional*): Sets the filter mode. Must be one of ``IIR_4``, ``IIR_8``, ``IIR_16``, + ``IIR_32``, ``IIR_64``, ``IIR_128``, ``IIR_256`` or ``JITTER``. +- **debounce_count** (*Optional*, ``int`` range 0-7): Sets the debounce count; if the measured values continue to + exceed the threshold for ``n + 1`` times, the touch sensor state changes. +- **noise_threshold** (*Optional*, ``int`` range 0-3): Noise threshold coefficient. Higher = More noise resistance. The + actual noise should be less than (noise coefficient * touch threshold). The coefficient is 0: 4/8; 1: 3/8; 2: 2/8; 3: 1. +- **jitter_step** (*Optional*, ``int`` range 0-15): Set jitter filter step size. +- **smooth_mode** (*Optional*): Level of filter applied on the original data against large noise interference. + Must be one of ``OFF``, ``IIR_2``, ``IIR_4`` or ``IIR_8``. + +For a more detailed explanation of the filter configuration, please see the +`ESP-IDF documentation. `__ + +Denoise configuration: + +- **denoise_grade** (*Optional*): Sets the denoise range of the denoise channel. Determined by measuring the noise + amplitude of the denoise channel. Must be one of ``BIT12``, ``BIT10``, ``BIT8`` or ``BIT4``. +- **denoise_cap_level** (*Optional*): Select internal reference capacitance of denoise channel. Must be one + of ``L0``, ``L1``, ``L2``, ``L3``, ``L4``, ``L5``, ``L6`` or ``L7``. + +For a more detailed explanation of the denoise configuration, please see the +`ESP-IDF documentation. `__ + +Waterproof configuration: + +- **waterproof_guard_ring** (*Optional*, :ref:`config-pin`): Sets the touch channel to use for the guard pad. The guard + pad is used to detect the large area of water covering the touch panel. +- **waterproof_shield_driver** (*Optional*): Shield channel drive capability configuration; the larger the + parasitic capacitance on the shielding channel, the higher the drive capability needs to be set. Must be one of + ``L0``, ``L1``, ``L2``, ``L3``, ``L4``, ``L5``, ``L6`` or ``L7``. + +For a more detailed explanation of the waterproof configuration, please see the +`ESP-IDF documentation. `__ .. _esp32-touch-binary-sensor: @@ -89,47 +139,51 @@ Configuration variables: - **pin** (**Required**, :ref:`config-pin`): The pin to detect touch events on. -- **threshold** (**Required**, int): The threshold to use to detect touch events. Smaller values mean - a higher probability that the pad is being touched. +- **threshold** (**Required**, ``int``): The threshold to use to detect touch events. See + :ref:`esp32-finding-thresholds` below for help determining this value. - **name** (**Required**, string): The name of the binary sensor. -- **id** (*Optional*, - :ref:`config-id`): Manually specify - the ID used for code generation. -- **wakeup_threshold** (*Optional*, int): The threshold to use to detect touch events to wakeup from deep - sleep. Smaller values mean a higher probability that the pad is being touched. All touch pad sensors that - should trigger a wakeup from deep sleep must specify this value. The :ref:`deep_sleep-component` must also - be configured to enable a wakeup from a touch event. Note that no filter is active during deep sleep. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- **wakeup_threshold** (*Optional*, ``int``): The threshold to use to detect touch events to wake-up from deep sleep. + See :ref:`esp32-finding-thresholds` below for help determining this value. Touch pad sensors that should trigger a + wake-up from deep sleep must specify this value. The :ref:`deep_sleep-component` must also be configured to enable + wake-up from a touch event. Note that no filter(s) is/are active during deep sleep. - All other options from :ref:`Binary Sensor `. +.. _esp32-touch-pad-pins: + Touch Pad Pins -------------- -8 pins on the ESP32 can be used to detect touches. These are (in the default "raw" pin names): +Various pins on the ESP32, ESP32-S2 and ESP32-S3 can be used to detect touches. They are as follows (using the default +"raw" pin names/numbers): -- ``GPIO0`` -- ``GPIO2`` -- ``GPIO4`` -- ``GPIO12`` -- ``GPIO13`` -- ``GPIO14`` -- ``GPIO15`` -- ``GPIO27`` -- ``GPIO32`` -- ``GPIO33`` +.. list-table:: + :header-rows: 1 -Finding thresholds + * - ESP32 + - ESP32-S2 + - ESP32-S3 + * - GPIO4, GPIO0, GPIO2, GPIO15, GPIO13, GPIO12, GPIO14, GPIO27, GPIO33, GPIO32 + - GPIO1 - GPIO14 + - GPIO1 - GPIO14 + +.. _esp32-finding-thresholds: + +Finding Thresholds ------------------ -For each touch pad you want to monitor, you need to find a threshold first. This threshold is -used to determine if a pad is being touched or not using the raw values from the sensor. Lower -raw values mean that it is more likely that a touch is happening. For example, values around -1000 to 1600 usually mean the pad is not being touched, and values in the range of 600 and less -mean the pad is probably being touched. +For each touch pad you want to monitor, you need to find a threshold value first. This threshold is used to determine +if a pad is being touched or not using the raw values read from the processor's internal sensor hardware. When no +contact is made with the sensor, the values will typically hover within a certain range; when the sensor's pad is +touched, the value will change significantly, enabling the touch to be detected. + +Exact values reported by the sensor hardware will vary based on the processor, PCB layout and potentially even +environmental factors. -To find suitable threshold values, first configure the :ref:`ESP32 touch hub ` -to output measured values using the ``setup_mode:`` configuration option. Next, add some binary sensors -for the touch pads you want to observe. Also put some threshold in the configuration as seen below -to make the validator happy, we are going to find good thresholds in a moment anyway. +To find suitable threshold values, first configure the :ref:`ESP32 touch hub ` to log measured +values using the ``setup_mode:`` configuration option. Next, add some binary sensors for the touch pads you want to +observe. You'll also need to put some (temporary) threshold values into the configuration (as shown below) to make the +validator happy; we'll replace these in a moment once we determine suitable values. .. code-block:: yaml @@ -143,17 +197,36 @@ to make the validator happy, we are going to find good thresholds in a moment an pin: GPIO27 threshold: 1000 -Then upload the program and open the logs, you will see values like these. Try touching the pins -and you will (hopefully) see the value decreasing a bit. Play around with different amounts of -force you put on the touch pad until you find a good value that can differentiate between -touch/non-touch events. +Upload the program/configuration and watch the device's logs; you'll see values being logged by the hub component. +Touching the sensor's pins/pads should result in a (significant) change in the values being logged. Experiment with +different amounts of force applied to the touch pad; a pattern should emerge, revealing a value that falls between +"touched" and "not touched" which the binary sensor will then use to differentiate between the two states. .. figure:: images/esp32_touch-finding_thresholds.png :align: center -Finally, put your threshold parameter in the configuration. Do not forget to disable the ``setup_mode`` -option again by setting it to ``false``. Otherwise you will end up spamming the logs and slowing the device -down. +Once you've determined an appropriate value, update the threshold parameter in your configuration and test the updated +configuration. You may need to repeat this process a few times to fine-tune the behavior and get it just right. + +Finally, don't forget to disable the ``setup_mode`` option by setting it back to ``false``; leaving it enabled will +reduce the ESP's overall performance. + +.. _esp32-note-about-variants: + +A Note About S2 and S3 Variants +------------------------------- + +If you're familiar with the ESP32 hardware and pick up an S2 or S3 variant, you're likely to notice some behavioral +differences between them. In particular: + +- Raw touch sensor readings on the S2 and S3 variants will generally return larger numeric values than the original + ESP32 hardware. +- Contact with the touch sensor on the S2 and S3 variants will result in the raw sensor value reading *increasing*; on + the original ESP32, contact would cause this value to *decrease*. + +These behavioral differences are due to changes in the hardware and software (ESP-IDF) interfaces and should be +expected -- if you are moving your configuration from an original ESP32 to an S2 or S3 variant, expect that you'll need +to make some adjustments to your configuration to accommodate this behavior. See Also -------- diff --git a/components/binary_sensor/gpio.rst b/components/binary_sensor/gpio.rst index 96bbca3be7..65aefcb127 100644 --- a/components/binary_sensor/gpio.rst +++ b/components/binary_sensor/gpio.rst @@ -1,3 +1,5 @@ +.. _gpio-binary-sensor: + GPIO Binary Sensor ================== diff --git a/components/climate/haier.rst b/components/climate/haier.rst index 040bf87c7f..b0e5ce5a01 100644 --- a/components/climate/haier.rst +++ b/components/climate/haier.rst @@ -73,6 +73,7 @@ This component requires a :ref:`uart` to be setup. uart_id: ac_port wifi_signal: true beeper: true + display: true outdoor_temperature: name: Haier AC outdoor temperature visual: @@ -91,6 +92,10 @@ This component requires a :ref:`uart` to be setup. - VERTICAL - HORIZONTAL - BOTH + supported_presets: + - ECO + - BOOST + - SLEEP Configuration variables: @@ -100,7 +105,9 @@ Configuration variables: - **uart_id** (*Optional*, :ref:`config-id`): ID of the UART port to communicate with AC. - **protocol** (*Optional*, string): Defines protocol of communication with AC. Possible values: hon or smartair2. Default value is smartair2. - **name** (**Required**, string): The name of the climate device. -- **wifi_signal** (*Optional*, boolean): If true - send wifi signal level to AC. Supported only by hOn protocol. +- **wifi_signal** (*Optional*, boolean): If true - send wifi signal level to AC. +- **answer_timeout** (*Optional*, :ref:`config-time`): Responce timeout. Default value is 150ms. +- **display** (*Optional*, boolean): Can be used to set AC display off. - **beeper** (*Optional*, boolean): Can be used to disable beeping on commands from AC. Supported only by hOn protocol. - **outdoor_temperature** (*Optional*): Temperature sensor for outdoor temperature. Supported only by hOn protocol. @@ -108,7 +115,8 @@ Configuration variables: - **id** (*Optional*, :ref:`config-id`): ID of the sensor, can be used for code generation - All other options from :ref:`Sensor `. - **supported_modes** (*Optional*, list): Can be used to disable some of AC modes. Possible values: 'OFF', AUTO, COOL, HEAT, DRY, FAN_ONLY -- **supported_swing_modes** (*Optional*, list): Can be used to disablesome swing modes if your AC does not support it. Possible values: 'OFF', VERTICAL, HORIZONTAL, BOTH +- **supported_swing_modes** (*Optional*, list): Can be used to disable some swing modes if your AC does not support it. Possible values: 'OFF', VERTICAL, HORIZONTAL, BOTH +- **supported_presets** (*Optional*, list): Can be used to disable some presets. Possible values for smartair2 are: BOOST, COMFORT. Possible values for hOn are: ECO, BOOST, SLEEP - All other options from :ref:`Climate `. Automations diff --git a/components/climate/index.rst b/components/climate/index.rst index 7a49b5e125..bc5ebf601e 100644 --- a/components/climate/index.rst +++ b/components/climate/index.rst @@ -217,6 +217,7 @@ advanced stuff. This trigger is activated each time the state of the climate device is updated (for example, if the current temperature measurement or the mode set by the users changes). +The ``Climate`` itself is available to automations as the reference ``x``. .. code-block:: yaml @@ -224,7 +225,11 @@ This trigger is activated each time the state of the climate device is updated - platform: midea # or any other platform # ... on_state: - - logger.log: "State updated!" + - logger.log: "State updated!" + - lambda: |- + if (x.mode != CLIMATE_MODE_OFF) + id(some_binary_sensor).publish_state(true); + .. _climate-on_control_trigger: @@ -235,15 +240,22 @@ This trigger is activated each time a *control* input of the climate device is updated via a ``ClimateCall`` (which includes changes coming in from Home Assistant). That is, this trigger is activated for, for example, changes to the mode, *but not* on temperature measurements. It will be invoked prior to -the ``on_state`` trigger, if both are defined. +the ``on_state`` trigger, if both are defined. The ``ClimateCall`` control +object is available to automations as the reference ``x`` that can be changed. .. code-block:: yaml climate: - - platform: midea # or any other platform + - platform: ... # ... on_control: - - logger.log: "Control input received; configuration updated!" + - logger.log: "Control input received; configuration updated!" + - lambda: |- + if (x.get_mode() != CLIMATE_MODE_OFF) { + id(turnoff_script).stop(); + x.set_target_temperature(25.0f); + } + See Also -------- diff --git a/components/display/inkplate6.rst b/components/display/inkplate6.rst index dfe76f76da..d5069fc34a 100644 --- a/components/display/inkplate6.rst +++ b/components/display/inkplate6.rst @@ -78,6 +78,7 @@ Configuration variables: - ``inkplate_6`` - ``inkplate_10`` - ``inkplate_6_plus`` + - ``inkplate_6_v2`` - **greyscale** (*Optional*, boolean): Makes the screen display 3 bit colors. Defaults to ``false`` - **partial_updating** (*Optional*, boolean): Makes the screen update partially, which is faster, but leaves burnin. Defaults to ``false`` @@ -332,6 +333,51 @@ Below is a config example: id: backlight default_transition_length: 0.2s name: '${friendly_name} Backlight' + +Inkplate 6 v2 +*************************** + +The Inkplate 6 v2 has a slightly different configuration. The main difference is that it is using pca6416a instead of the mcp23017. +Below is a config example: + +.. code-block:: yaml + + # Example minimal configuration entry + pca6416a: + - id: pca6416a_hub + address: 0x20 + + display: + - platform: inkplate6 + id: inkplate_display + greyscale: true + partial_updating: false + update_interval: never + model: inkplate_6_v2 + + ckv_pin: 32 + sph_pin: 33 + gmod_pin: + pca6416a: pca6416a_hub + number: 1 + gpio0_enable_pin: + pca6416a: pca6416a_hub + number: 8 + oe_pin: + pca6416a: pca6416a_hub + number: 0 + spv_pin: + pca6416a: pca6416a_hub + number: 2 + powerup_pin: + pca6416a: pca6416a_hub + number: 4 + wakeup_pin: + pca6416a: pca6416a_hub + number: 3 + vcom_pin: + pca6416a: pca6416a_hub + number: 5 See Also -------- diff --git a/components/display/waveshare_epaper.rst b/components/display/waveshare_epaper.rst index 2f4f976620..376156fe64 100644 --- a/components/display/waveshare_epaper.rst +++ b/components/display/waveshare_epaper.rst @@ -98,6 +98,7 @@ Configuration variables: - ``5.83inv2`` - ``7.50in`` - ``7.50in-bV2`` - also supports v3, B/W rendering only + - ``7.50in-bV3`` - display with the '(V3)' sticker on the back, B/W rendering only - ``7.50in-bc`` - display with version sticker '(C)' on the back, B/W rendering only - ``7.50inV2`` - Can't use with an ESP8266 as it runs out of RAM - ``7.50inV2alt`` (alternative version to the above ``7.50inV2``) diff --git a/components/remote_receiver.rst b/components/remote_receiver.rst index 640a3170cb..8e042af9f1 100644 --- a/components/remote_receiver.rst +++ b/components/remote_receiver.rst @@ -213,9 +213,12 @@ Remote code selection (exactly one of these has to be included): - **address** (*Optional*, int): The address (or subdevice) to trigger on, see dumper output for more info. Defaults to ``0`` - **command** (**Required**, int): The command to listen for. -- **coolix**: Trigger on a decoded Coolix remote code with the given data. +- **coolix**: Trigger on a decoded Coolix remote code with the given data. It is possible to directly specify a 24-bit code, + it will be checked for a match to at least one of the two received packets. The main configuration scheme is below. - - **data** (**Required**, int): The 24-bit Coolix code to trigger on, see dumper output for more info. + - **first** (**Required**, uint32_t): The first 24-bit Coolix code to trigger on, see dumper output for more info. + - **second** (**Optional**, uint32_t): The second 24-bit Coolix code to trigger on, see dumper output for more info. + If not set, trigger on on only single non-strict packet, specified by the ``first`` parameter. - **dish**: Trigger on a decoded Dish Network remote code with the given data. Beware that Dish remotes use a different carrier frequency (57.6kHz) that many receiver hardware don't decode. diff --git a/components/remote_transmitter.rst b/components/remote_transmitter.rst index db7d5712af..7a8144ccc1 100644 --- a/components/remote_transmitter.rst +++ b/components/remote_transmitter.rst @@ -158,17 +158,19 @@ Configuration variables: ``remote_transmitter.transmit_coolix`` Action ********************************************* -This :ref:`action ` sends a 24-bit Coolix infrared remote code to a remote transmitter. +This :ref:`action ` sends one or two (stricted or not) 24-bit Coolix infrared remote codes to a remote transmitter. .. code-block:: yaml on_...: - remote_transmitter.transmit_coolix: - data: 0xB23FE4 + first: 0xB23FE4 + second: 0xB23FE4 Configuration variables: -- **data** (**Required**, int): The Coolix code to send, see dumper output for more info. +- **first** (**Required**, :ref:`templatable `, uint32_t): The first 24-bit Coolix code to send, see dumper output for more info. +- **second** (**Optional**, :ref:`templatable `, uint32_t): The second 24-bit Coolix code to send, see dumper output for more info. .. _remote_transmitter-transmit_dish: diff --git a/components/sensor/a01nyub.rst b/components/sensor/a01nyub.rst new file mode 100644 index 0000000000..04371bd0a5 --- /dev/null +++ b/components/sensor/a01nyub.rst @@ -0,0 +1,46 @@ +A01NYUB Waterproof Ultrasonic Sensor +==================================== + +.. seo:: + :description: Instructions for setting up A01NYUB waterproof ultrasonic distance sensor in ESPHome. + :image: a01nyub.jpg + :keywords: ultrasonic, DFRobot, A01NYUB + +This sensor allows you to use A01NYUB waterproof ultrasonic sensor by DFRobot +(`datasheet `__) +with ESPHome to measure distances. This sensor can measure +ranges between 28 centimeters and 750 centimeters with a resolution of 1 milimeter. + +Since this sensor reads multiple times per second, :ref:`sensor-filters` are highly recommended. + +To use the sensor, first set up an :ref:`uart` with a baud rate of 9600 and connect the sensor to the specified pin. + +.. figure:: images/a01nyub-full.jpg + :align: center + :width: 50.0% + + A01NYUB Waterproof Ultrasonic Distance Sensor. + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: "a01nyub" + name: "Distance" + + +Configuration variables: +------------------------ + +- **name** (**Required**, string): The name of the sensor. +- **uart_id** (*Optional*, :ref:`config-id`): The ID of the :ref:`UART bus ` you wish to use for this sensor. + Use this if you want to use multiple UART buses at once. +- All other options from :ref:`Sensor `. + +See Also +-------- + +- :ref:`sensor-filters` +- :ref:`uart` +- :apiref:`a01nyub/a01nyub.h` +- :ghedit:`Edit` diff --git a/components/sensor/bh1750.rst b/components/sensor/bh1750.rst index 3c5326afcd..b571bef6ed 100644 --- a/components/sensor/bh1750.rst +++ b/components/sensor/bh1750.rst @@ -1,3 +1,5 @@ +.. _BH1750: + BH1750 Ambient Light Sensor =========================== diff --git a/components/sensor/bmp581.rst b/components/sensor/bmp581.rst new file mode 100644 index 0000000000..79054c97eb --- /dev/null +++ b/components/sensor/bmp581.rst @@ -0,0 +1,138 @@ +BMP581 Temperature+Pressure Sensor +=========================================== + +.. seo:: + :description: Instructions for setting up BMP581 temperature and pressure sensors with ESPHome + :image: bmp581.jpg + :keywords: BMP581 + +The ``bmp581`` sensor platform allows you to use your BMP581 +(`datasheet `__, `SparkFun `__) temperature and pressure sensors with ESPHome. The :ref:`I²C ` bus is +required to be set up in your configuration for this sensor to work. + +.. figure:: images/bmp581.jpg + :align: center + :width: 50.0% + + BMP581 Temperature and Pressure Sensor. + (Credit: `SparkFun `__, image cropped and compressed) + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: bmp581 + temperature: + name: "Indoor Temperature" + pressure: + name: "Indoor Pressure" + +Configuration variables: +------------------------ + +- **temperature** (*Optional*): The information for the temperature sensor. + + - **oversampling** (*Optional*): The oversampling rate for the temperature sensor. + See :ref:`Oversampling Options `. + - **iir_filter** (*Optional*): The Infinite Impulse Response Filter level for the temperature sensor. + See :ref:`Infinite Impulse Response Filter Options `. + - All other options from :ref:`Sensor `. + +- **pressure** (*Optional*): The information for the pressure sensor. + + - **oversampling** (*Optional*): The oversampling rate for the pressure sensor. + See :ref:`Oversampling Options `. + - **iir_filter** (*Optional*): The Infinite Impulse Response Filter level for the pressure sensor. + See :ref:`Infinite Impulse Response Filter Options `. + - All other options from :ref:`Sensor `. + +- **address** (*Optional*, int): Manually specify the I²C address of + the sensor. Defaults to ``0x46``. Another address can be ``0x47``. +- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the + sensor. Defaults to ``60s``. + +.. _bmp581-oversampling: + +Oversampling Options +-------------------- + +By default, the BMP581 sensor measures the pressure 16 times and temperature once when requesting a new value to reduce measurement noise. You can, however, configure this amount. Possible oversampling values: + +- ``NONE`` (sensor is sampled once, default for temperature) +- ``2x`` +- ``4x`` +- ``8x`` +- ``16x`` (default for pressure) +- ``32x`` +- ``64x`` +- ``128x`` + +The datasheet (page 19) gives suggestions for oversampling combinations: + +.. list-table:: Oversampling Settings + :header-rows: 1 + + * - Oversampling setting + - Pressure oversampling + - Temperature oversampling + * - Lowest power + - ``NONE`` + - ``NONE`` + * - + - ``2x`` + - ``NONE`` + * - Standard resolution + - ``4x`` + - ``NONE`` + * - + - ``8x`` + - ``NONE`` + * - High resolution (default) + - ``16x`` + - ``NONE`` + * - + - ``32x`` + - ``2x`` + * - + - ``64x`` + - ``4x`` + * - Highest resolution + - ``128x`` + - ``8x`` + +.. note:: + + High oversampling rates increase power consumption and the time it takes for the sensor to measure temperature and pressure. For example, with no oversampling enabled, the measurement time is approximately 3 ms. The measurement time is approximately 107 ms if the temperature and pressure oversampling rates are ``128x``. The BMP581 component waits the minimum time necessary for the specfically configured oversampling rates before attempting to read a measurement. Consider using lower oversampling rates to reduce power consumption or to speed up measurements for small update intervals. + +.. _bmp581-iir: + +Infinite Impule Response Filter Options +--------------------------------------- + +The BMP581's Infinite Impulse Response filter reduces noise in measurement values due to ambient conditions, for example, a door slamming or a window opening. The BMP581 disables the IIR filter for the temperature and pressure sensors by default, but you may configure the amount of filtering for each sensor independently. Possible IIR filter values: + +- ``OFF`` (default) +- ``2x`` +- ``4x`` +- ``8x`` +- ``16x`` +- ``32x`` +- ``64x`` +- ``128x`` + +.. warning:: + + The BMP581's deep standby mode is disabled when you enable an IIR filter, which increases power consumption. Consider using a mathematically equivalent ESPHome exponential moving average filter instead, especially if you configure a long update interval. See the :ref:`exponential moving average filter` for implementation information. + + +See Also +-------- + +- :ref:`sensor-filters` +- :doc:`bme280` +- :doc:`bmp280` +- :doc:`bmp3xx` +- :doc:`bme680` +- :doc:`bmp085` +- `BMP5 sensor API `__ +- :ghedit:`Edit` diff --git a/components/sensor/gcja5.rst b/components/sensor/gcja5.rst new file mode 100644 index 0000000000..104a8776c3 --- /dev/null +++ b/components/sensor/gcja5.rst @@ -0,0 +1,51 @@ +Panasonic SN-GCJA5 Particulate Matter Sensor +============================================ + +.. seo:: + :description: Instructions for setting up Panasonic SN-GCJA5 Particulate matter sensors + :image: gcja5.svg + +The ``gcja5`` sensor platform allows you to use your Panasonic SN-GCJA5 laser based particulate matter sensor +(`datasheet `__) +sensors with ESPHome. + +As the communication with the GCJA5 is done using UART, you need +to have an :ref:`UART bus ` in your configuration with the ``rx_pin`` connected to the SEND/TX. Additionally, you need to set the baud rate to 9600, and you +MUST have `EVEN`` parity. + +The sensor itself will push values every second. You may wish to :ref:`filter ` this value to reduce the amount of data you are ingesting. +The sensor will internally track changes to the Laser Diode and Photo Diode over time to adjust and ensure accuracy. +Based on continous runtime, the sensor is rated to last at least 5 years. + +.. code-block:: yaml + + # Example configuration entry + + sensor: + - platform: gcja5 + pm_1_0: + name: "Particulate Matter <1.0µm Concentration" + pm_2_5: + name: "Particulate Matter <2.5µm Concentration" + pm_10_0: + name: "Particulate Matter <10.0µm Concentration" + +Configuration variables: +------------------------ + +- **pm_1_0_std** (*Optional*): Use the concentration of particulates of size less than 1.0µm in µg per cubic meter at standard particle. + All options from :ref:`Sensor `. +- **pm_2_5_std** (*Optional*): Use the concentration of particulates of size less than 2.5µm in µg per cubic meter at standard particle. + All options from :ref:`Sensor `. +- **pm_10_0_std** (*Optional*): Use the concentration of particulates of size less than 10.0µm in µg per cubic meter at standard particle. + All options from :ref:`Sensor `. +- **pm_1_0** (*Optional*): Use the concentration of particulates of size less than 1.0µm in µg per cubic meter under atmospheric environment. + + +See Also +-------- + +- :doc:`/components/sensor/gcja5` +- :ref:`sensor-filters` +- :apiref:`gcja5/gcja5.h` +- :ghedit:`Edit` diff --git a/components/sensor/images/a01nyub-full.jpg b/components/sensor/images/a01nyub-full.jpg new file mode 100644 index 0000000000..6060496d86 Binary files /dev/null and b/components/sensor/images/a01nyub-full.jpg differ diff --git a/components/sensor/images/bmp581.jpg b/components/sensor/images/bmp581.jpg new file mode 100644 index 0000000000..fb1daf506f Binary files /dev/null and b/components/sensor/images/bmp581.jpg differ diff --git a/components/sensor/images/ld2410-card.png b/components/sensor/images/ld2410-card.png new file mode 100644 index 0000000000..c5a6b1d3e4 Binary files /dev/null and b/components/sensor/images/ld2410-card.png differ diff --git a/components/sensor/images/sensor_filter_calibrate_linear.png b/components/sensor/images/sensor_filter_calibrate_linear.png new file mode 100644 index 0000000000..0e5989bd99 Binary files /dev/null and b/components/sensor/images/sensor_filter_calibrate_linear.png differ diff --git a/components/sensor/index.rst b/components/sensor/index.rst index 8be768dbf1..b6c704984e 100644 --- a/components/sensor/index.rst +++ b/components/sensor/index.rst @@ -184,6 +184,12 @@ Multiplies each value by a constant value. Calibrate your sensor values by using values you measured with an accurate "truth" source. +Configuration variables: + +- **method** (*Optional*, string): The method for calculating the linear function(s). + One of ``least_squares`` or ``exact``. Defaults to ``least_squares``. +- **datapoints** (**Required**): The list of datapoints. + First, collect a bunch of values of what the sensor shows and what the real value should be. For temperature, this can for example be achieved by using an accurate thermometer. For other sensors like power sensor this can be done by connecting a known load and then writing down @@ -198,14 +204,21 @@ the value the sensor shows. name: "DHT22 Temperature" filters: - calibrate_linear: - # Map 0.0 (from sensor) to 0.0 (true value) - - 0.0 -> 0.0 + method: least_squares + datapoints: + # Map 0.0 (from sensor) to 1.0 (true value) + - 0.0 -> 1.0 - 10.0 -> 12.1 -The arguments are a list of data points, each in the form ``MEASURED -> TRUTH``. ESPHome will -then fit a linear equation to the values (using least squares). So you need to supply at least -two values. If more than two values are given a linear solution will be calculated and may not -represent each value exactly. +The arguments are a list of data points, each in the form ``MEASURED -> TRUTH``. Depending on +the ``method`` ESPHome will then either fit a linear equation to the values (using least squares) +or connect the values exactly using multiple linear equations. You need to supply at least two +values. When using ``least_squares`` and more than two values are given a linear solution will be +calculated and may not represent each value exactly. + +.. figure:: images/sensor_filter_calibrate_linear.png + :align: center + :width: 50.0% .. _sensor-calibrate_polynomial: @@ -246,6 +259,17 @@ degree with a least squares solver. filters: - filter_out: 85.0 +``clamp`` +********* + +Limits the value to the range between ``min_value`` and ``max_value``. If ``min_value`` is not set, there is +no lower bound, if ``max_value`` is not set there is no upper bound. + +Configuration variables: + +- **min_value** (*Optional*, float): The lower bound of the range. +- **max_value** (*Optional*, float): The upper bound of the range. + ``quantile`` ************ @@ -471,10 +495,19 @@ of the input values. ************ After the first value has been sent, if no subsequent value is published within the -``specified time period``, send ``NaN``. +``specified time period``, send a value which defaults to ``NaN``. Especially useful when data is derived from some other communication channel, e.g. a serial port, which can potentially be interrupted. +.. code-block:: yaml + + # Example filters: + filters: + - timeout: 10s # sent value will be NaN + - timeout: + timeout: 10s + value: 0 + ``debounce`` ************ diff --git a/components/sensor/kmeteriso.rst b/components/sensor/kmeteriso.rst new file mode 100644 index 0000000000..c8aa46dfce --- /dev/null +++ b/components/sensor/kmeteriso.rst @@ -0,0 +1,48 @@ +M5Stack KMeterISO I2C K-Type probe temperature sensor +===================================================== + +.. seo:: + :description: Instructions for setting up KMeterISO temperature sensors + :image: kmeteriso.jpg + :keywords: BME280 + +The ``kmeteriso`` sensor platform allows you to use your KMeterISO +(`product `__, +`M5Stack`_) K-Type thermocouple temperature sensor with ESPHome. +The :ref:`I²C ` is required to be set up in your configuration +for this sensor to work. + +.. figure:: ../../images/kmeteriso.jpg + :align: center + :width: 50.0% + + M5Stack KMeterISO temperature sensor. + +.. _M5Stack: https://docs.m5stack.com/en/unit/KMeterISO%20Unit + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: kmeteriso + temperature: + name: Temperature + internal_temperature: + name: Internal temperature + +Configuration variables: +------------------------ + +- **temperature** (*Optional*): The information for the temperature sensor. All options from :ref:`Sensor `. +- **internal_temperature** (*Optional*): The information for the temperature sensor inside the probe. All options from :ref:`Sensor `. +- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the + sensor. Defaults to ``5s``. + +See Also +-------- + +- :ref:`sensor-filters` +- :doc:`absolute_humidity` +- :apiref:`kmeteriso/kmeteriso.h` +- `M5Stack Unit code `__ by `M5Stack `__ +- :ghedit:`Edit` diff --git a/components/sensor/ld2410.rst b/components/sensor/ld2410.rst index 8dbcc3652c..0a032b55ea 100644 --- a/components/sensor/ld2410.rst +++ b/components/sensor/ld2410.rst @@ -11,8 +11,8 @@ Component/Hub The ``ld2410`` sensor platform allows you to use HI-LINK LD2410 motion and presence sensor (`datasheet and user manual `__) with ESPHome. -The :ref:`UART ` is required to be set up in your configuration for this sensor to work. +The :ref:`UART ` is required to be set up in your configuration for this sensor to work, ``parity`` and ``stop_bits`` **must be** respectively ``NONE`` and ``1``. Use of hardware UART pins is highly recommended, in order to support the out-of-the-box 256000 baud rate of the LD2410 sensor. .. figure:: images/ld2410.jpg @@ -24,59 +24,265 @@ Use of hardware UART pins is highly recommended, in order to support the out-of- .. code-block:: yaml # Example configuration entry - uart: - tx_pin: REPLACEME - rx_pin: REPLACEME - baud_rate: 256000 - parity: NONE - stop_bits: 1 - ld2410: - timeout: 150s - max_move_distance : 6m - max_still_distance: 0.75m - g0_move_threshold: 10 - g0_still_threshold: 20 - g1_move_threshold: 10 - g1_still_threshold: 20 - g2_move_threshold: 20 - g2_still_threshold: 21 - g3_move_threshold: 30 - g3_still_threshold: 31 - g4_move_threshold: 40 - g4_still_threshold: 41 - g5_move_threshold: 50 - g5_still_threshold: 51 - g6_move_threshold: 60 - g6_still_threshold: 61 - g7_move_threshold: 70 - g7_still_threshold: 71 - g8_move_threshold: 80 - g8_still_threshold: 81 - - -.. note:: - - For UART configuration, ``baud_rate``, ``parity`` and ``stop_bits`` **must be** respectively ``256000``, ``NONE`` and ``1``. - - Use of hardware UART pins is highly recommended, in order to support the out-of-the-box 256000 baud rate of the LD2410 sensor. Configuration variables: ************************ -The configuration is made up of three parts: The central component, individual sensors, -and binary sensors. +- **uart_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`UART Component ` if you want + to use multiple UART buses. +- **throttle** (*Optional*, int): Time in milliseconds to control the rate of data updates. Defaults to ``1000ms``. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID for this :doc:`ld2410` component if you need multiple components. + +Binary Sensor +------------- + +The ``ld2410`` binary sensor allows you to use your :doc:`ld2410` to perform different +measurements. + +.. code-block:: yaml + + binary_sensor: + - platform: ld2410 + has_target: + name: Presence + has_moving_target: + name: Moving Target + has_still_target: + name: Still Target + out_pin_presence_status: + name: out pin presence status + +Configuration variables: +************************ + +- **has_target** (*Optional*): If true target detect either still or in movement. + All options from :ref:`Binary Sensor `. +- **has_moving_target** (*Optional*): If true a moving target is detected. + All options from :ref:`Binary Sensor `. +- **has_still_target** (*Optional*): If true a still target is detected. + All options from :ref:`Binary Sensor `. +- **out_pin_presence_status** (*Optional*): When in :ref:`engineering mode`, indicates whether the OUT pin indicates presence or not, otherwise ``false``. + OUT pin indication depends on the :ref:`light function` configuration. Might need latest firmware to work. + All options from :ref:`Binary Sensor `. +- **ld2410_id** (*Optional*, :ref:`config-id`): Manually specify the ID for the :doc:`ld2410` component if you are using multiple components. + +Sensor +------ + +The ``ld2410`` sensor allows you to use your :doc:`ld2410` to perform different +measurements. + +.. code-block:: yaml + + sensor: + - platform: ld2410 + light: + name: light + moving_distance: + name : Moving Distance + still_distance: + name: Still Distance + moving_energy: + name: Move Energy + still_energy: + name: Still Energy + detection_distance: + name: Detection Distance + g0: + move_energy: + name: g0 move energy + still_energy: + name: g0 still energy + g1: + move_energy: + name: g1 move energy + still_energy: + name: g1 still energy + g2: + move_energy: + name: g2 move energy + still_energy: + name: g2 still energy + g3: + move_energy: + name: g3 move energy + still_energy: + name: g3 still energy + g4: + move_energy: + name: g4 move energy + still_energy: + name: g4 still energy + g5: + move_energy: + name: g5 move energy + still_energy: + name: g5 still energy + g6: + move_energy: + name: g6 move energy + still_energy: + name: g6 still energy + g7: + move_energy: + name: g7 move energy + still_energy: + name: g7 still energy + g8: + move_energy: + name: g8 move energy + still_energy: + name: g8 still energy + +.. _ld2410-sensors: + +Configuration variables: +************************ + +- **light** (*Optional*, int): When in :ref:`engineering mode`, indicates the light sensitivity, otherwise ``unknown``. + Value between ``0`` and ``255`` inclusive. Though it seems that the value ``85`` is the lowest value at complete darkness. + All options from :ref:`Sensor `. +- **moving_distance** (*Optional*, int): Distance in cm of detected moving target. + All options from :ref:`Sensor `. +- **still_distance** (*Optional*, int): Distance in cm of detected still target. + All options from :ref:`Sensor `. +- **moving_energy** (*Optional*, int): Energy for moving target. + Value between ``0`` and ``100`` inclusive. + All options from :ref:`Sensor `. +- **still_energy** (*Optional*, int): Energy for still target. + Value between ``0`` and ``100`` inclusive. + All options from :ref:`Sensor `. +- **detection_distance** (*Optional*, int): Distance in cm of target. + All options from :ref:`Sensor `. +- **gX** (*Optional*): Energies for the Xth gate (X => 0 to 8). + - **move_energy** (*Optional*, int): When in :ref:`engineering mode`, the move energy of the gate, otherwise ``unknown``. + Value between ``0`` and ``100`` inclusive. + All options from :ref:`Sensor `. + - **still_energy** (*Optional*, int): When in :ref:`engineering mode`, the still energy of the gate, otherwise ``unknown``. + Value between ``0`` and ``100`` inclusive. + All options from :ref:`Sensor `. +- **ld2410_id** (*Optional*, :ref:`config-id`): Manually specify the ID for the :doc:`ld2410` component if you are using multiple components. + +Switch +------ + +The ``ld2410`` switch allows you to control your :doc:`ld2410`. + +.. code-block:: yaml + + switch: + - platform: ld2410 + engineering_mode: + name: "engineering mode" + bluetooth: + name: "control bluetooth" + +.. _ld2410-engineering-mode: + +Configuration variables: +************************ + +- **engineering_mode** (*Optional*): enable/disable engineering mode. Defaults to ``false``. + Notice this requires more resources and is not recommended to be enabled when not necessary. + All options from :ref:`Switch `. +- **bluetooth** (*Optional*): Turn on/off the bluetooth adapter. Defaults to ``true``. + All options from :ref:`Switch `. +- **ld2410_id** (*Optional*, :ref:`config-id`): Manually specify the ID for the :doc:`ld2410` component if you are using multiple components. + + +.. _ld2410-number: + +Number +------ + +The ``ld2410`` number allows you to control the configuration of your :doc:`ld2410`. + +.. code-block:: yaml + + number: + - platform: ld2410 + timeout: + name: timeout + light_threshold: + name: light threshold + max_move_distance_gate: + name: max move distance gate + max_still_distance_gate: + name: max still distance gate + g0: + move_threshold: + name: g0 move threshold + still_threshold: + name: g0 still threshold + g1: + move_threshold: + name: g1 move threshold + still_threshold: + name: g1 still threshold + g2: + move_threshold: + name: g2 move threshold + still_threshold: + name: g2 still threshold + g3: + move_threshold: + name: g3 move threshold + still_threshold: + name: g3 still threshold + g4: + move_threshold: + name: g4 move threshold + still_threshold: + name: g4 still threshold + g5: + move_threshold: + name: g5 move threshold + still_threshold: + name: g5 still threshold + g6: + move_threshold: + name: g6 move threshold + still_threshold: + name: g6 still threshold + g7: + move_threshold: + name: g7 move threshold + still_threshold: + name: g7 still threshold + g8: + move_threshold: + name: g8 move threshold + still_threshold: + name: g8 still threshold + +.. _ld2410-light-threshold: + +Configuration variables: +************************ - **timeout** (*Optional*, int): Time in seconds during which presence state will stay present - after leaving. Defaults to ``5s``. -- **max_move_distance** (*Optional*, int): Maximum distance for movement detection. - Value between ``0.75m`` and ``6m`` inclusive. Defaults to ``4.5m``. -- **max_still_distance** (*Optional*, int): Maximum distance for still detection. - Value between ``0.75m`` and ``6m`` inclusive. Defaults to ``4.5m``. -- **gX_move_threshold** (*Optional*, int): Threshold for the Xth gate for motion detection (X => 0 to 8). - Above this level for the considered gate (distance), movement detection will be triggered. Defaults to ``see table below``. -- **gX_still_threshold** (*Optional*, int): Threshold for the Xth gate for still detection. (X => 0 to 8). - Above this level for the considered gate (distance), still detection will be triggered. Defaults to ``see table below``. + after leaving. Defaults to ``5s`` + All options from :ref:`Number `. +- **light_threshold** (*Optional*, int): Sets the light threshold for the :ref:`light function`. + Value between ``0`` and ``255`` inclusive. Defaults to ``128``. + All options from :ref:`Number `. +- **max_move_distance_gate** (*Optional*, int): Maximum distance gate for movement detection. + Value between ``2`` and ``8`` inclusive. Defaults to ``8``. + All options from :ref:`Number `. +- **max_still_distance_gate** (*Optional*, int): Maximum distance gate for still detection. + Value between ``2`` and ``8`` inclusive. Defaults to ``8``. + All options from :ref:`Number `. +- **gX** (*Optional*): Thresholds for the Xth gate (X => 0 to 8). + - **move_threshold** (**Required**, int): Threshold for the gate for motion detection. + Above this level for the considered gate (distance), movement detection will be triggered. + Value between ``0`` and ``100`` inclusive. See default values below. + All options from :ref:`Number `. + - **still_threshold** (**Required**, int): Threshold for the gate for still detection. + Above this level for the considered gate (distance), still detection will be triggered. + Value between ``0`` and ``100`` inclusive. See default values below. + All options from :ref:`Number `. +- **ld2410_id** (*Optional*, :ref:`config-id`): Manually specify the ID for the :doc:`ld2410` component if you are using multiple components. .. list-table:: Default values for gate threshold :widths: 25 25 25 @@ -95,86 +301,418 @@ and binary sensors. - 40 - 40 * - 3 - - 40 + - 30 - 40 * - 4 - - 40 - - 40 + - 20 + - 30 * - 5 - - 40 - - 40 - * - 6 + - 15 - 30 + * - 6 - 15 + - 20 * - 7 - - 30 - 15 + - 20 * - 8 - - 30 - 15 + - 20 -Sensor +Button ------ -The ``ld2410`` sensor allows you to use your :doc:`ld2410` to perform different -measurements. +The ``ld2410`` button allows you to perfrom actions on your :doc:`ld2410`. .. code-block:: yaml - sensor: + button: - platform: ld2410 - moving_distance: - name : Moving Distance - still_distance: - name: Still Distance - moving_energy: - name: Move Energy - still_energy: - name: Still Energy - detection_distance: - name: Detection Distance + factory_reset: + name: "factory reset" + restart: + name: "restart" + query_params: + name: query params Configuration variables: ************************ -- **moving_distance** (*Optional*): Distance of detected moving target. - All options from :ref:`Sensor `. -- **still_distance** (*Optional*): Distance of detected still target. - All options from :ref:`Sensor `. -- **moving_energy** (*Optional*): Energy for moving target. - All options from :ref:`Sensor `. -- **still_energy** (*Optional*): Energy for still target. - All options from :ref:`Sensor `. -- **detection_distance** (*Optional*): Distance in cm of target. - All options from :ref:`Sensor `. +- **factory_reset** (*Optional*): This command is used to restore all configuration values to their original values. + All options from :ref:`Button `. +- **restart** (*Optional*): Restart the device. + All options from :ref:`Button `. +- **query_params** (*Optional*): Refresh all sensors values of the device. + All options from :ref:`Button `. +- **ld2410_id** (*Optional*, :ref:`config-id`): Manually specify the ID for the :doc:`ld2410` component if you are using multiple components. -Binary Sensor -------------- +Text Sensor +----------- -The ``ld2410`` binary sensor allows you to use your :doc:`ld2410` to perform different -measurements. +The ``ld2410`` text sensor allows you get information about your :doc:`ld2410`. .. code-block:: yaml - binary_sensor: + text_sensor: - platform: ld2410 - has_target: - name: Presence - has_moving_target: - name: Moving Target - has_still_target: - name: Still Target + version: + name: "firmware version" + mac_address: + name: "mac address" Configuration variables: ************************ -- **has_target** (*Optional*): If true target detect either still or in movement. - All options from :ref:`Binary Sensor `. -- **has_moving_target** (*Optional*): If true a moving target is detected. - All options from :ref:`Binary Sensor `. -- **has_still_target** (*Optional*): If true a still target is detected. - All options from :ref:`Binary Sensor `. +- **version** (*Optional*): The firmware version. + All options from :ref:`Text Sensor `. +- **mac_address** (*Optional*): The bluetooth mac address. Will be set to ``unknown`` when bluetooth is off. + All options from :ref:`Text Sensor `. +- **ld2410_id** (*Optional*, :ref:`config-id`): Manually specify the ID for the :doc:`ld2410` component if you are using multiple components. + +Select +----------- + +The ``ld2410`` select allows you control your :doc:`ld2410`. + +.. code-block:: yaml + + select: + - platform: ld2410 + distance_resolution: + name: "distance resolution" + baud_rate: + name: "baud rate" + light_function: + name: light function + out_pin_level: + name: out pin level + +.. _ld2410-light-function: + +Configuration variables: +************************ + +- **distance_resolution** (*Optional*): Control the gates distance resolution. Can be ``0.75m`` or ``0.2m``. Defaults to ``0.75m``. + All options from :ref:`Select `. +- **baud_rate** (*Optional*): Control the serial port baud rate. Defaults to ``256000``. + Once changed, all sensors will stop working until a fresh install with an updated :ref:`UART Component ` configuration. + All options from :ref:`Select `. +- **light_function** (*Optional*): If set, will affect the OUT pin value, based on :ref:`light threshold`. Can be ``off``, ``low`` or ``above``. Defaults to ``off``. + All options from :ref:`Select `. +- **out_pin_level** (*Optional*): Control OUT pin ``away`` value. Can be ``low`` or ``high``. Defaults to ``low``. + All options from :ref:`Select `. +- **ld2410_id** (*Optional*, :ref:`config-id`): Manually specify the ID for the :doc:`ld2410` component if you are using multiple components. + +Automations +----------- + +``bluetooth_password.set`` Action +********************************* + +This is an :ref:`Action ` for setting the bluetooth password. + +.. code-block:: yaml + + - bluetooth_password.set: + id: my_ld2410 + password: "HiLink" + +Configuration variables: + +- **id** (**Required**, :ref:`config-id`): The ID of the :doc:`ld2410` component to set. +- **password** (**Required**, string, :ref:`templatable `): + The password to set. Case sensitive. Must be exactly 6 characters long. Default password is `HiLink`. +To change the password from HA you can use the following example config: + +.. code-block:: yaml + + ld2410: + id: my_ld2410 + + api: + services: + - service: set_ld2410_bluetooth_password + variables: + password: string + then: + - bluetooth_password.set: + id: my_ld2410 + password: !lambda 'return password;' + +OUT pin +------- + +In order to monitor the presence indicated by the component, with the :ref:`light function` taken +under account, you can set up a :ref:`GPIO Binary Sensor `: + +.. code-block:: yaml + + binary_sensor: + - platform: gpio + pin: REPLACEME + name: gpio out pin presence + device_class: presence + + +Calibration Process +------------------- + +In order to calibrate your ``ld2410`` sensor perform the following: + +1. Enable :ref:`engineering mode`. +2. Monitor the ``gX_move_energy`` and ``gX_still_energy`` :ref:`sensors`. +3. Change the :ref:`thresholds` and repeat step 2 until satisfaction. +4. Disable :ref:`engineering mode`. + +Home Assistant Card +******************* + +For easy calibration process you can use the following custom manual card. + +.. code-block:: yaml + + type: vertical-stack + title: 'DEVICE' + cards: + - type: horizontal-stack + cards: + - type: entities + entities: + - entity: 'switch.DEVICE_engineering_mode' + name: engineering mode + - type: vertical-stack + cards: + - type: entities + entities: + - entity: 'number.DEVICE_timeout' + name: timeout + - entity: 'number.DEVICE_max_move_distance_gate' + name: max move distance gate + - entity: 'number.DEVICE_max_still_distance_gate' + name: max still distance gate + - entity: 'select.DEVICE_light_function' + name: light function + - entity: 'number.DEVICE_light_threshold' + name: light threshold + - type: horizontal-stack + cards: + - type: entity + entity: 'sensor.DEVICE_distance_detection_cm' + name: distance + - type: entity + entity: 'sensor.DEVICE_moving_distance_cm' + name: move + - type: entity + entity: 'sensor.DEVICE_still_distance_cm' + name: still + - type: horizontal-stack + cards: + - type: entity + entity: 'sensor.DEVICE_move_energy' + name: move energy + - type: entity + entity: 'sensor.DEVICE_still_energy' + name: still energy + - type: horizontal-stack + cards: + - type: entity + entity: 'binary_sensor.DEVICE_gpio_out_pin_presence' + name: gpio presence + state_color: true + - type: entity + entity: 'binary_sensor.DEVICE_presence' + name: presence + state_color: true + - type: entity + entity: 'binary_sensor.DEVICE_movement' + name: movement + state_color: true + - type: entity + entity: 'binary_sensor.DEVICE_still' + name: still + state_color: true + - type: conditional + conditions: + - entity: 'switch.DEVICE_engineering_mode' + state: 'on' + card: + type: vertical-stack + cards: + - type: horizontal-stack + cards: + - type: entity + entity: 'sensor.DEVICE_light' + name: light + - type: entity + entity: 'binary_sensor.DEVICE_out_pin_presence_status' + name: out pin presence + state_color: true + - type: horizontal-stack + cards: + - type: entity + entity: 'sensor.DEVICE_g0_move_energy' + name: 'g0' + - type: entity + entity: 'number.DEVICE_g0_move_threshold' + name: ' ' + - type: entity + entity: 'sensor.DEVICE_g0_still_energy' + name: ' ' + - type: entity + entity: 'number.DEVICE_g0_still_threshold' + name: ' ' + - type: horizontal-stack + cards: + - type: entity + entity: 'sensor.DEVICE_g1_move_energy' + name: 'g1' + icon: ' ' + - type: entity + entity: 'number.DEVICE_g1_move_threshold' + name: ' ' + icon: ' ' + - type: entity + entity: 'sensor.DEVICE_g1_still_energy' + name: ' ' + icon: ' ' + - type: entity + entity: 'number.DEVICE_g1_still_threshold' + name: ' ' + icon: ' ' + - type: horizontal-stack + cards: + - type: entity + entity: 'sensor.DEVICE_g2_move_energy' + name: 'g2' + icon: ' ' + - type: entity + entity: 'number.DEVICE_g2_move_threshold' + name: ' ' + icon: ' ' + - type: entity + entity: 'sensor.DEVICE_g2_still_energy' + name: ' ' + icon: ' ' + - type: entity + entity: 'number.DEVICE_g2_still_threshold' + name: ' ' + icon: ' ' + - type: horizontal-stack + cards: + - type: entity + entity: 'sensor.DEVICE_g3_move_energy' + name: 'g3' + icon: ' ' + - type: entity + entity: 'number.DEVICE_g3_move_threshold' + name: ' ' + icon: ' ' + - type: entity + entity: 'sensor.DEVICE_g3_still_energy' + name: ' ' + icon: ' ' + - type: entity + entity: 'number.DEVICE_g3_still_threshold' + name: ' ' + icon: ' ' + - type: horizontal-stack + cards: + - type: entity + entity: 'sensor.DEVICE_g4_move_energy' + name: 'g4' + icon: ' ' + - type: entity + entity: 'number.DEVICE_g4_move_threshold' + name: ' ' + icon: ' ' + - type: entity + entity: 'sensor.DEVICE_g4_still_energy' + name: ' ' + icon: ' ' + - type: entity + entity: 'number.DEVICE_g4_still_threshold' + name: ' ' + icon: ' ' + - type: horizontal-stack + cards: + - type: entity + entity: 'sensor.DEVICE_g5_move_energy' + name: 'g5' + icon: ' ' + - type: entity + entity: 'number.DEVICE_g5_move_threshold' + name: ' ' + icon: ' ' + - type: entity + entity: 'sensor.DEVICE_g5_still_energy' + name: ' ' + icon: ' ' + - type: entity + entity: 'number.DEVICE_g5_still_threshold' + name: ' ' + icon: ' ' + - type: horizontal-stack + cards: + - type: entity + entity: 'sensor.DEVICE_g6_move_energy' + name: 'g6' + icon: ' ' + - type: entity + entity: 'number.DEVICE_g6_move_threshold' + name: ' ' + icon: ' ' + - type: entity + entity: 'sensor.DEVICE_g6_still_energy' + name: ' ' + icon: ' ' + - type: entity + entity: 'number.DEVICE_g6_still_threshold' + name: ' ' + icon: ' ' + - type: horizontal-stack + cards: + - type: entity + entity: 'sensor.DEVICE_g7_move_energy' + name: 'g7' + icon: ' ' + - type: entity + entity: 'number.DEVICE_g7_move_threshold' + name: ' ' + icon: ' ' + - type: entity + entity: 'sensor.DEVICE_g7_still_energy' + name: ' ' + icon: ' ' + - type: entity + entity: 'number.DEVICE_g7_still_threshold' + name: ' ' + icon: ' ' + - type: horizontal-stack + cards: + - type: entity + entity: 'sensor.DEVICE_g8_move_energy' + name: 'g8' + icon: ' ' + - type: entity + entity: 'number.DEVICE_g8_move_threshold' + name: ' ' + icon: ' ' + - type: entity + entity: 'sensor.DEVICE_g8_still_energy' + name: ' ' + icon: ' ' + - type: entity + entity: 'number.DEVICE_g8_still_threshold' + name: ' ' + icon: ' ' + +Then replace all instances of ``DEVICE`` with your device name + +The result: + +.. figure:: images/ld2410-card.png + :align: center See Also -------- diff --git a/conf.py b/conf.py index 9a6cba81ad..0e0a3ea7b1 100644 --- a/conf.py +++ b/conf.py @@ -67,9 +67,9 @@ # built documents. # # The short X.Y version. -version = "2023.7" +version = "2023.8" # The full version, including alpha/beta/rc tags. -release = "2023.7.1" +release = "2023.8.0" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/guides/supporters.rst b/guides/supporters.rst index b3dde9b601..3decac47be 100644 --- a/guides/supporters.rst +++ b/guides/supporters.rst @@ -40,8 +40,10 @@ Contributors - `Attila Darazs (@adarazs) `__ - `ADeadPixel (@ADeadPixel) `__ - `Andrea Donno (@adonno) `__ +- `Adrian Fretwell (@AdrianFretwell) `__ - `Adrien Brault (@adrienbrault) `__ - `Ian Blais (@aeonsablaze) `__ +- `Kjell Braden (@afflux) `__ - `Stefan Agner (@agners) `__ - `Anders (@ahd71) `__ - `Alexander Pohl (@ahpohl) `__ @@ -168,13 +170,13 @@ Contributors - `bleeisme (@bleeisme) `__ - `Jim Ekman (@blejdfist) `__ - `Scott Smith (@blurfl) `__ +- `Bruno Medici (@bmedici) `__ - `Bob (@Bmooij) `__ - `Benjamin Klotz (@bnw) `__ - `Bob Kersten (@bobkersten) `__ - `Bodmer (@Bodmer) `__ - `Anthony Todd (@bohregard) `__ - `Bomaker (@Bomaker) `__ -- `Mauricio Bonani (@bonanitech) `__ - `Casey Olson (@bookcasey) `__ - `Borja Burgos (@borjaburgos) `__ - `Brian Orpin (@borpin) `__ @@ -291,6 +293,7 @@ Contributors - `Anthony Uk (@dataway) `__ - `Dav-id (@dav-id-org) `__ - `DAVe3283 (@DAVe3283) `__ +- `DaveCorder (@DaveCorder) `__ - `David Marín (@davefx) `__ - `Dave Richer (@davericher) `__ - `Dave T (@davet2001) `__ @@ -312,7 +315,6 @@ Contributors - `ddt154 (@ddt154) `__ - `DeadEnd (@DeadEnded) `__ - `Debashish Sahu (@debsahu) `__ -- `Maximilian (@DeerMaximum) `__ - `definitio (@definitio) `__ - `Christiaan Blom (@Deinara) `__ - `Mickaël Le Baillif (@demikl) `__ @@ -406,7 +408,6 @@ Contributors - `Josh Gwosdz (@erdii) `__ - `Eric Coffman (@ericbrian) `__ - `Eric Hiller (@erichiller) `__ -- `Matt Hamilton (@Eriner) `__ - `Ernst Klamer (@Ernst79) `__ - `Eduardo Roldan (@eroldan) `__ - `escoand (@escoand) `__ @@ -466,6 +467,7 @@ Contributors - `Gareth Cooper (@gaco79) `__ - `gazoodle (@gazoodle) `__ - `gcopeland (@gcopeland) `__ +- `Greg Cormier (@gcormier) `__ - `GeekVisit (@GeekVisit) `__ - `Ian Reinhart Geiser (@geiseri) `__ - `R Huish (@genestealer) `__ @@ -519,7 +521,6 @@ Contributors - `Boris Hajduk (@hajdbo) `__ - `Gavin Mogan (@halkeye) `__ - `Charles (@hallard) `__ -- `Alex Griffith (@halomademeapc) `__ - `Aniket (@HandyHat) `__ - `Charles Thompson (@haryadoon) `__ - `Ha Thach (@hathach) `__ @@ -603,6 +604,7 @@ Contributors - `JbLb (@jblb) `__ - `Jonathan Burns (@jburns20) `__ - `James Callaghan (@jcallaghan) `__ +- `Jc Miñarro (@JcMinarro) `__ - `Josh Willox (@jcwillox) `__ - `JeeCee1 (@JeeCee1) `__ - `Jeef (@jeeftor) `__ @@ -645,7 +647,6 @@ Contributors - `joiboi (@joiboi) `__ - `JonasEr (@JonasEr) `__ - `Jonathan Adams (@jonathanadams) `__ -- `Jonathan Treffler (@JonathanTreffler) `__ - `JonnyaiR (@jonnyair) `__ - `Jonathan V (@jonofmac) `__ - `Joppy (@JoppyFurr) `__ @@ -734,6 +735,7 @@ Contributors - `Lazar Obradovic (@lobradov) `__ - `Barry Loong (@loongyh) `__ - `LuBeDa (@lubeda) `__ +- `Lucas Prim (@lucasprim) `__ - `Lucas Reiners (@lucasreiners) `__ - `Joakim Sørensen (@ludeeus) `__ - `ludrao (@ludrao) `__ @@ -784,11 +786,11 @@ Contributors - `Masterz69 (@Masterz69) `__ - `Christopher Masto (@masto) `__ - `Mat931 (@Mat931) `__ +- `Maciej Sokołowski (@matemaciek) `__ - `Mateus Demboski (@mateusdemboski) `__ - `matikij (@matikij) `__ - `Michel Marti (@matoxp) `__ - `matt123p (@matt123p) `__ -- `Matthew Mazzanti (@matthewmazzanti) `__ - `matthias882 (@matthias882) `__ - `Matus Ivanecky (@maty535) `__ - `Christian (@max246) `__ @@ -796,7 +798,6 @@ Contributors - `mbo18 (@mbo18) `__ - `mcmuller (@mcmuller) `__ - `Miguel Diaz Gonçalves (@mdiazgoncalves) `__ -- `Matthew Donoughe (@mdonoughe) `__ - `Me No Dev (@me-no-dev) `__ - `Alexandr Zarubkin (@me21) `__ - `mechanarchy (@mechanarchy) `__ @@ -818,12 +819,10 @@ Contributors - `Pauline Middelink (@middelink) `__ - `Joel Midstjärna (@midstar) `__ - `Mike_Went (@MikeWent) `__ -- `MiKuBB (@MiKuBB) `__ - `André Klitzing (@misery) `__ - `Tomasz (@Misiu) `__ - `MisterSilvereagle (@MisterSilvereagle) `__ - `mjbogusz (@mjbogusz) `__ -- `Matthew Garrett (@mjg59) `__ - `Morton Jonuschat (@mjonuschat) `__ - `mjoshd (@mjoshd) `__ - `Matt Kaatman (@mkaatman) `__ @@ -840,6 +839,7 @@ Contributors - `Mariusz Kryński (@mrk-its) `__ - `Michael Davidson (@MrMDavidson) `__ - `mrred2k (@mrred2k) `__ +- `André Cirne (@MrSuicideParrot) `__ - `Murray Scott (@mscottco) `__ - `MSe-5-14 (@MSe-5-14) `__ - `mtl010957 (@mtl010957) `__ @@ -940,6 +940,7 @@ Contributors - `Philippe FOUQUET (@Philippe12) `__ - `Philipp Molitor (@PhilippMolitor) `__ - `Philip Rosenberg-Watt (@PhilRW) `__ +- `Philip Persson (@PhPersson) `__ - `pieterbrink123 (@pieterbrink123) `__ - `Piotr Kubiak (@piotr-kubiak) `__ - `Peter Kuehne (@pkuehne) `__ @@ -954,6 +955,7 @@ Contributors - `Iván Povedano (@pove) `__ - `Peter Provost (@PProvost) `__ - `Q. Marchi (@preeefix) `__ +- `Francesco Ciocchetti (@primeroz) `__ - `probonopd (@probonopd) `__ - `Mike Lynch (@Prow7) `__ - `Peter Tatrai (@ptatrai) `__ @@ -1032,7 +1034,6 @@ Contributors - `Davide Perini (@sblantipodi) `__ - `sbur83 (@sbur83) `__ - `Søren Christian Aarup (@scaarup) `__ -- `Matthew Schinckel (@schinckel) `__ - `Nils Schulte (@Schnilz) `__ - `Wolle (@schreibfaul1) `__ - `Ville Skyttä (@scop) `__ @@ -1119,6 +1120,7 @@ Contributors - `TheGroundZero (@TheGroundZero) `__ - `thejonesyboy (@thejonesyboy) `__ - `TheJulianJES (@TheJulianJES) `__ +- `Bart (@TheNameIsBart) `__ - `Zixuan Wang (@TheNetAdmin) `__ - `Dominik Bruhn (@theomega) `__ - `Brian Levinsen (@therealeldaria) `__ @@ -1154,6 +1156,7 @@ Contributors - `Tom Price (@tomtom5152) `__ - `David Kiliani (@torfbolt) `__ - `tracestep (@tracestep) `__ +- `Trent Houliston (@TrentHouliston) `__ - `Felix Eckhofer (@tribut) `__ - `Trick van Staveren (@trickv) `__ - `TripitakaBC (@TripitakaBC) `__ @@ -1226,9 +1229,8 @@ Contributors - `I. Tomita (@ziceva) `__ - `Stefan Goethals (@zipkid) `__ - `zivillian (@zivillian) `__ -- `Loïc (@zoic21) `__ - `Zack Barett (@zsarnett) `__ - `Zsolt Zsiros (@ZsZs73) `__ - `Christian Zufferey (@zuzu59) `__ -*This page was last updated August 1, 2023.* +*This page was last updated August 17, 2023.* diff --git a/images/a01nyub.jpg b/images/a01nyub.jpg new file mode 100644 index 0000000000..49d48c545d Binary files /dev/null and b/images/a01nyub.jpg differ diff --git a/images/bmp581.jpg b/images/bmp581.jpg new file mode 100644 index 0000000000..bc2135afe2 Binary files /dev/null and b/images/bmp581.jpg differ diff --git a/images/gcja5.svg b/images/gcja5.svg new file mode 100644 index 0000000000..e9227174fb --- /dev/null +++ b/images/gcja5.svg @@ -0,0 +1 @@ + diff --git a/images/kmeteriso.jpg b/images/kmeteriso.jpg new file mode 100644 index 0000000000..5db95eaf80 Binary files /dev/null and b/images/kmeteriso.jpg differ diff --git a/index.rst b/index.rst index cafa44213a..bc7f3bc984 100644 --- a/index.rst +++ b/index.rst @@ -174,6 +174,7 @@ Air Quality AirThings BLE, components/sensor/airthings_ble, airthings_logo.png, Radon, CO2, Volatile organics CCS811, components/sensor/ccs811, ccs811.jpg, CO2 & Volatile organics EE895, components/sensor/ee895, EE895.png, CO2 & Temperature & Pressure + GCJA5, components/sensor/gcja5, gcja5.svg, Particulate HM3301, components/sensor/hm3301, hm3301.jpg, Particulate MH-Z19, components/sensor/mhz19, mhz19.jpg, CO2 & Temperature MiCS-4514, components/sensor/mics_4514, mics_4514.jpg, Gas concentration @@ -236,6 +237,7 @@ Distance ******** .. imgtable:: + A01NYUB, components/sensor/a01nyub, a01nyub.jpg, Acoustic distance HRXL MaxSonar WR, components/sensor/hrxl_maxsonar_wr, hrxl_maxsonar_wr.jpg, Acoustic distance TOF10120, components/sensor/tof10120, tof10120.jpg, IR optical distance Ultrasonic Sensor, components/sensor/ultrasonic, ultrasonic.jpg, Acoustic distance @@ -289,6 +291,7 @@ Environmental BMP085, components/sensor/bmp085, bmp180.jpg, Temperature & Pressure BMP280, components/sensor/bmp280, bmp280.jpg, Temperature & Pressure BMP388 and BMP390, components/sensor/bmp3xx, bmp388.jpg, Temperature & Pressure + BMP581, components/sensor/bmp581, bmp581.jpg, Temperature & Pressure b-parasite, components/sensor/b_parasite, b_parasite.jpg, Moisture & Temperature & Humidity & Light Dallas DS18B20, components/sensor/dallas, dallas.jpg, Temperature DHT, components/sensor/dht, dht.jpg, Temperature & Humidity @@ -394,6 +397,7 @@ Thermocouple ************ .. imgtable:: + KMeterISO, components/sensor/kmeteriso, kmeteriso.jpg, K-Type, MAX31855, components/sensor/max31855, max31855.jpg, K-Type MAX31856, components/sensor/max31856, max31856.jpg, All types MAX31865, components/sensor/max31865, max31865.jpg, Platinum RTD