diff --git a/Doxygen b/Doxygen index 64ab705a890..73c4f555468 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.5.0-dev +PROJECT_NUMBER = 2023.7.0-dev # 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/_redirects b/_redirects index 8e185bd7314..8532c1d6985 100644 --- a/_redirects +++ b/_redirects @@ -9,6 +9,7 @@ /changelog/2022.12.4.html /changelog/2022.12.0.html 301 /components/display/ili9341.html /components/display/ili9xxx.html 301 +/components/sensor/mmc5063.html /components/sensor/mmc5603.html 301 /cookbook/brilliant-mirabella-genio-smart-plugs.html https://devices.esphome.io/devices/Mirabella-Genio-Wi-Fi-1-USB 301 /cookbook/zemismart-rgbw-downlights.html https://devices.esphome.io/devices/Zemismart-LED-RGBWW-Downlight 301 diff --git a/_static/changelog-2022.12.0.png b/_static/changelog-2022.12.0.png index 7eff5ae2ee4..ec027251f13 100644 Binary files a/_static/changelog-2022.12.0.png and b/_static/changelog-2022.12.0.png differ diff --git a/_static/changelog-2023.2.0.png b/_static/changelog-2023.2.0.png index fca4fc7312e..538a180ca1d 100644 Binary files a/_static/changelog-2023.2.0.png and b/_static/changelog-2023.2.0.png differ diff --git a/_static/changelog-2023.3.0.png b/_static/changelog-2023.3.0.png index 2ca6298c271..e6e76b13cb3 100644 Binary files a/_static/changelog-2023.3.0.png and b/_static/changelog-2023.3.0.png differ diff --git a/_static/changelog-2023.5.0.png b/_static/changelog-2023.5.0.png new file mode 100644 index 00000000000..964b215e6cc Binary files /dev/null and b/_static/changelog-2023.5.0.png differ diff --git a/_static/changelog-2023.6.0.png b/_static/changelog-2023.6.0.png new file mode 100644 index 00000000000..b7a75bd06bf Binary files /dev/null and b/_static/changelog-2023.6.0.png differ diff --git a/_static/version b/_static/version index 448988caa37..fbecf950ca3 100644 --- a/_static/version +++ b/_static/version @@ -1 +1 @@ -2023.5.0-dev \ No newline at end of file +2023.7.0-dev \ No newline at end of file diff --git a/changelog/2023.4.0.rst b/changelog/2023.4.0.rst index aa863df177d..375fd8540a1 100644 --- a/changelog/2023.4.0.rst +++ b/changelog/2023.4.0.rst @@ -22,7 +22,7 @@ Voice Assistant This year is the Year of the Voice for Home Assistant, and ESPHome is charging ahead with this in mind. We've added a new :doc:`/components/voice_assistant` component that allows you to use ESPHome devices as an input -for `assist `__ in Home Assistant. +for `assist `__ in Home Assistant **2023.5 or later**. With this also comes preliminary :doc:`microphone ` support, which has been built in a way that multiple components, like ``voice_assistant`` can request start / stop of the microphone and get the data. We @@ -42,13 +42,38 @@ Home Assistant is hosting a live stream all about the Year of the Voice - Chapte Keith joins Nabu Casa --------------------- -Nabu Casa is pleased to annouce that long time contributor Keith Burzinski (:ghuser:`kbx81`) is joining the +Nabu Casa is pleased to announce that long time contributor Keith Burzinski (:ghuser:`kbx81`) is joining the team as a full time developer to help out on ESPHome. Keith created the :doc:`/components/sprinkler`, :doc:`/components/climate/thermostat`, a bunch of the ``ssd`` display components and a few other components as well as fixing many bug along the way. I expect his house climate and garden area are kept well in line. Looking forward to working with you Keith. +Release 2023.4.1 - April 24 +--------------------------- + +- fix flip_x :esphomepr:`4727` by :ghuser:`ssieb` +- Use proper schema for delta filter :esphomepr:`4723` by :ghuser:`jesserockz` + +Release 2023.4.2 - April 27 +--------------------------- + +- I2c scan recovery reset fix :esphomepr:`4724` by :ghuser:`gcopeland` +- Debug component doesn't work on RP2040 :esphomepr:`4728` by :ghuser:`HeMan` +- Only request VA port from first client that is subscribed :esphomepr:`4747` by :ghuser:`jesserockz` +- Don't allow fingerprint_grow enroll cancellation when no enrollment started :esphomepr:`4745` by :ghuser:`itpeters` + +Release 2023.4.3 - May 2 +------------------------ + +- Fix sprinkler switch restore_mode :esphomepr:`4756` by :ghuser:`kbx81` +- Fix i2s media player on devices with no internal DAC :esphomepr:`4768` by :ghuser:`jesserockz` + +Release 2023.4.4 - May 4 +------------------------ + +- Fixes for Arduino 2.7.4 (for FastLED) :esphomepr:`4777` by :ghuser:`timn` + Breaking Changes ---------------- diff --git a/changelog/2023.5.0.rst b/changelog/2023.5.0.rst new file mode 100644 index 00000000000..f2e8583dec9 --- /dev/null +++ b/changelog/2023.5.0.rst @@ -0,0 +1,239 @@ +ESPHome 2023.5.0 - 17th May 2023 +================================ + +.. seo:: + :description: Changelog for ESPHome 2023.5.0. + :image: /_static/changelog-2023.5.0.png + :author: Jesse Hills + :author_twitter: @jesserockz + +.. imgtable:: + :columns: 4 + + Speaker Core, components/speaker/index, speaker.svg + I2S Speaker, components/speaker/i2s_audio, i2s_audio.svg + MLX90614, components/sensor/mlx90614, mlx90614.jpg + MAX6956 I/O expander - I²C Bus, components/max6956, max6956.jpg + PCA6416A I/O Expander, components/pca6416a, pca6416a.svg + HYT271, components/sensor/hyt271, hyt271.jpg + GP8403, components/output/gp8403, gp8403.svg + ESP32 RMT LED Strip, components/light/esp32_rmt_led_strip, color_lens.svg + + +Speakers!!! +----------- + +Following on from last months release adding :doc:`microphones `, +this release adds :doc:`speaker ` support! + +These new changes allows the :doc:`/components/voice_assistant` to request the raw audio +stream response from Home Assistant to playback without using a full :doc:`/components/media_player/index`. +This has much lower latency and allows for a much more responsive voice assistant experience. + + +More Microphones +---------------- + +This release also adds a bit more configuration for the i2s_audio microphone components. +There is a breaking-change that requires new configuration fields to be added in YAML. +See the :doc:`microphone documentation ` for the configuration details, +but below is a small example for the M5Stack Atom Echo. + +.. code-block:: yaml + + # Old + microphone: + platform: i2s_audio + i2s_din_pin: GPIO23 + id: my_microphone + + # New + microphone: + platform: i2s_audio + i2s_din_pin: GPIO23 + adc_type: external + pdm: false + +Release 2023.5.1 - May 18 +------------------------- + +- Remove i2c dependency from ttp229_bsf :esphomepr:`4851` by :ghuser:`jesserockz` +- Sprinkler fixes :esphomepr:`4816` by :ghuser:`kbx81` + +Release 2023.5.2 - May 22 +------------------------- + +- Fix i2s_audio media_player mutex acquisition :esphomepr:`4867` by :ghuser:`kroimon` + +Release 2023.5.3 - May 22 +------------------------- + +- Allow microphone channel to be specified in config :esphomepr:`4871` by :ghuser:`jesserockz` +- [PSRam] Change log unit to KB to minimize rounding error. :esphomepr:`4872` by :ghuser:`Fabian-Schmidt` + +Release 2023.5.4 - May 24 +------------------------- + +- [internal_temperature] ESP32-S3 needs ESP IDF V4.4.3 or higher :esphomepr:`4873` by :ghuser:`Fabian-Schmidt` +- Update cover.h for compile errors with stop() :esphomepr:`4879` by :ghuser:`Davrosx` +- Print ESPHome version when running commands :esphomepr:`4883` by :ghuser:`jesserockz` +- fix modbus sending FP32_R values :esphomepr:`4882` by :ghuser:`ssieb` +- Fix esp32_rmt_led_strip color modes :esphomepr:`4886` by :ghuser:`jesserockz` + +Release 2023.5.5 - May 29 +------------------------- + +- Fix version printing not breaking yaml parsing :esphomepr:`4904` by :ghuser:`jesserockz` + +Full list of changes +-------------------- + +New Components +^^^^^^^^^^^^^^ + +- Add mlx90614 sensors :esphomepr:`3749` by :ghuser:`jesserockz` (new-integration) +- Add PCA6416A Support :esphomepr:`4681` by :ghuser:`Mat931` (new-integration) +- Add support for hyt271 :esphomepr:`4282` by :ghuser:`Philippe12` (new-integration) +- Max6956 support added :esphomepr:`3764` by :ghuser:`looping40` (new-integration) +- Speaker support :esphomepr:`4743` by :ghuser:`jesserockz` (new-integration) +- Add gp8403 output component :esphomepr:`4495` by :ghuser:`jesserockz` (new-integration) +- Create esp32 rmt addressable light driver :esphomepr:`4708` by :ghuser:`jesserockz` (new-integration) +- Add host target platform :esphomepr:`4783` by :ghuser:`jesserockz` (new-integration) + +Breaking Changes +^^^^^^^^^^^^^^^^ + +- Remove climate legacy away flags :esphomepr:`4744` by :ghuser:`jesserockz` (breaking-change) +- Revert "Template sensors always publish on update interval (#2224)" :esphomepr:`4774` by :ghuser:`nuttytree` (breaking-change) + +Beta Changes +^^^^^^^^^^^^ + +- Fixed access point for ESP32 IDF platform :esphomepr:`4784` by :ghuser:`HeMan` +- Remove AUTO_LOAD from apds9960 :esphomepr:`4746` by :ghuser:`jesserockz` +- Supposed to fix #4069, by changing the default value to 0s (timeunit … :esphomepr:`4806` by :ghuser:`Alex1602` +- Wording :esphomepr:`4805` by :ghuser:`fgsch` +- Tuya: Prevent loop when setting colors on case-sensitive dps :esphomepr:`4809` by :ghuser:`richardhopton` +- Fix i2s media player volume control :esphomepr:`4813` by :ghuser:`jesserockz` +- Dont try stop if not actually started :esphomepr:`4814` by :ghuser:`jesserockz` +- Fix missing stop trait in send_cover_info :esphomepr:`4826` by :ghuser:`RoboMagus` +- Bump aioesphomeapi from 13.7.2 to 13.7.5 :esphomepr:`4830` by :ghuser:`dependabot[bot]` +- Update PulseLightEffect with range brightness :esphomepr:`4820` by :ghuser:`max246` +- Bump esphome-dashboard to 20230516.0 :esphomepr:`4831` by :ghuser:`jesserockz` +- Fix time period validation for the auto cleaning interval :esphomepr:`4811` by :ghuser:`fgsch` +- Bump tzlocal from 4.2 to 5.0.1 :esphomepr:`4829` by :ghuser:`dependabot[bot]` +- Start UART assignment at UART0 if the logger is not enabled or is not configured for hardware logging on ESP32 :esphomepr:`4762` by :ghuser:`spectrumjade` +- Synchronise Device Classes from Home Assistant :esphomepr:`4825` by :ghuser:`github-actions[bot]` +- support sending keys to the collector :esphomepr:`4838` by :ghuser:`ssieb` +- handle Wiegand 8-bit keys :esphomepr:`4837` by :ghuser:`ssieb` + +All changes +^^^^^^^^^^^ + +- Only allow 5 jobs from each CI run to be in parallel :esphomepr:`4682` by :ghuser:`jesserockz` +- Add Bayesian type for binary_sensor_map component :esphomepr:`4640` by :ghuser:`kahrendt` +- Bump aioesphomeapi from 13.5.1 to 13.7.0 :esphomepr:`4676` by :ghuser:`dependabot[bot]` +- Bump peter-evans/create-pull-request from 4 to 5 :esphomepr:`4661` by :ghuser:`dependabot[bot]` +- Bump docker/build-push-action from 3 to 4 :esphomepr:`4367` by :ghuser:`dependabot[bot]` +- Keep Device Class in Flash. :esphomepr:`4639` by :ghuser:`Fabian-Schmidt` +- Add support for passive WiFi scanning :esphomepr:`4666` by :ghuser:`BellaCoola` +- Initial attempt at supporting ESP-IDF 5.0.0 :esphomepr:`4364` by :ghuser:`kbx81` +- Get Sunrise & Sunset for a Specific Date :esphomepr:`4712` by :ghuser:`RebbePod` +- Add `supports_stop` trait to Cover :esphomepr:`3897` by :ghuser:`amomchilov` +- Bump aioesphomeapi from 13.7.0 to 13.7.1 :esphomepr:`4725` by :ghuser:`dependabot[bot]` +- Add on_tag_removed trigger for RC522 :esphomepr:`4742` by :ghuser:`kbx81` +- Fix 'blutooth' typo in esp32_ble component :esphomepr:`4738` by :ghuser:`RoboMagus` +- Bump pylint from 2.17.2 to 2.17.3 :esphomepr:`4740` by :ghuser:`dependabot[bot]` +- Bump tornado from 6.2 to 6.3.1 :esphomepr:`4741` by :ghuser:`dependabot[bot]` +- Bump pytest from 7.3.0 to 7.3.1 :esphomepr:`4686` by :ghuser:`dependabot[bot]` +- Expand the platformio dep installer to also install platforms and tools :esphomepr:`4716` by :ghuser:`jesserockz` +- Remove climate legacy away flags :esphomepr:`4744` by :ghuser:`jesserockz` (breaking-change) +- Add mlx90614 sensors :esphomepr:`3749` by :ghuser:`jesserockz` (new-integration) +- Move am43 sensor code and remove auto load on cover :esphomepr:`4631` by :ghuser:`jesserockz` +- Fix assumed_state switch webserver :esphomepr:`4259` by :ghuser:`RoboMagus` +- Bump aioesphomeapi from 13.7.1 to 13.7.2 :esphomepr:`4753` by :ghuser:`dependabot[bot]` +- Bump git version in Dockerfile :esphomepr:`4763` by :ghuser:`jesserockz` +- Power down PN532 before deep sleep :esphomepr:`4707` by :ghuser:`tracestep` +- Switch ESPAsyncTCP-esphome to esphome fork :esphomepr:`4764` by :ghuser:`jesserockz` +- Bump pyupgrade from 3.3.1 to 3.3.2 :esphomepr:`4751` by :ghuser:`dependabot[bot]` +- Only pre-install libraries in docker images :esphomepr:`4766` by :ghuser:`jesserockz` +- Add PCA6416A Support :esphomepr:`4681` by :ghuser:`Mat931` (new-integration) +- play_folder bugfix and addition of play_mp3 :esphomepr:`4758` by :ghuser:`llluis` +- RF Codec for Drayton Digistat heating controller :esphomepr:`4494` by :ghuser:`marshn` +- Add support for hyt271 :esphomepr:`4282` by :ghuser:`Philippe12` (new-integration) +- Add support for BLE passkey authentication :esphomepr:`4258` by :ghuser:`Mat931` +- Add support for V2 of the waveshare 5.83in e-paper display. :esphomepr:`3660` by :ghuser:`cooki35` +- Max6956 support added :esphomepr:`3764` by :ghuser:`looping40` (new-integration) +- Bump zeroconf from 0.56.0 to 0.60.0 :esphomepr:`4767` by :ghuser:`dependabot[bot]` +- Revert "Template sensors always publish on update interval (#2224)" :esphomepr:`4774` by :ghuser:`nuttytree` (breaking-change) +- update schema gen to 2023.4.0 :esphomepr:`4772` by :ghuser:`glmnet` +- Speaker support :esphomepr:`4743` by :ghuser:`jesserockz` (new-integration) +- Add gp8403 output component :esphomepr:`4495` by :ghuser:`jesserockz` (new-integration) +- Create esp32 rmt addressable light driver :esphomepr:`4708` by :ghuser:`jesserockz` (new-integration) +- Bump ESP32-audioI2s to 2.0.7 :esphomepr:`4796` by :ghuser:`jesserockz` +- SM2135 Add optional current configuration, avoid communication failures. :esphomepr:`3850` by :ghuser:`BoukeHaarsma23` +- Fix ezo parsing :esphomepr:`4792` by :ghuser:`alfredopironti` +- [ili9xxx] Improve fill operation performance :esphomepr:`4702` by :ghuser:`Fabian-Schmidt` +- Add host target platform :esphomepr:`4783` by :ghuser:`jesserockz` (new-integration) +- Add more envs to root platformio :esphomepr:`4799` by :ghuser:`jesserockz` +- Keep Unit of Measurement in Flash. :esphomepr:`4719` by :ghuser:`Fabian-Schmidt` +- [display] Small display print performance improvement :esphomepr:`4788` by :ghuser:`Fabian-Schmidt` +- Fixed calculation of start and end dhcp range :esphomepr:`4785` by :ghuser:`HeMan` +- Add more configuration for microphones - i2s/pdm/adc :esphomepr:`4775` by :ghuser:`jesserockz` +- Wrap VA code :esphomepr:`4800` by :ghuser:`jesserockz` +- Make i2s_audio bclk_pin optional :esphomepr:`4801` by :ghuser:`jesserockz` +- Validate project details are set for dashboard_import :esphomepr:`4802` by :ghuser:`jesserockz` +- Fixed access point for ESP32 IDF platform :esphomepr:`4784` by :ghuser:`HeMan` +- Remove AUTO_LOAD from apds9960 :esphomepr:`4746` by :ghuser:`jesserockz` +- Supposed to fix #4069, by changing the default value to 0s (timeunit … :esphomepr:`4806` by :ghuser:`Alex1602` +- Wording :esphomepr:`4805` by :ghuser:`fgsch` +- Tuya: Prevent loop when setting colors on case-sensitive dps :esphomepr:`4809` by :ghuser:`richardhopton` +- Fix i2s media player volume control :esphomepr:`4813` by :ghuser:`jesserockz` +- Dont try stop if not actually started :esphomepr:`4814` by :ghuser:`jesserockz` +- Fix missing stop trait in send_cover_info :esphomepr:`4826` by :ghuser:`RoboMagus` +- Bump aioesphomeapi from 13.7.2 to 13.7.5 :esphomepr:`4830` by :ghuser:`dependabot[bot]` +- Update PulseLightEffect with range brightness :esphomepr:`4820` by :ghuser:`max246` +- Bump esphome-dashboard to 20230516.0 :esphomepr:`4831` by :ghuser:`jesserockz` +- Fix time period validation for the auto cleaning interval :esphomepr:`4811` by :ghuser:`fgsch` +- Bump tzlocal from 4.2 to 5.0.1 :esphomepr:`4829` by :ghuser:`dependabot[bot]` +- Start UART assignment at UART0 if the logger is not enabled or is not configured for hardware logging on ESP32 :esphomepr:`4762` by :ghuser:`spectrumjade` +- Synchronise Device Classes from Home Assistant :esphomepr:`4825` by :ghuser:`github-actions[bot]` +- support sending keys to the collector :esphomepr:`4838` by :ghuser:`ssieb` +- handle Wiegand 8-bit keys :esphomepr:`4837` by :ghuser:`ssieb` + +Past Changelogs +--------------- + +- :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/2023.6.0.rst b/changelog/2023.6.0.rst new file mode 100644 index 00000000000..5b6115e1a1a --- /dev/null +++ b/changelog/2023.6.0.rst @@ -0,0 +1,242 @@ +ESPHome 2023.6.0 - 21st June 2023 +================================= + +.. seo:: + :description: Changelog for ESPHome 2023.6.0. + :image: /_static/changelog-2023.6.0.png + :author: Jesse Hills + :author_twitter: @jesserockz + +.. imgtable:: + :columns: 2 + + Alarm Control Panel Core, components/alarm_control_panel/index, alarm-panel.svg + Template Alarm Control Panel, components/alarm_control_panel/template, description.svg + RP2040 PIO LED Strip, components/light/rp2040_pio_led_strip, color_lens.svg + TMP1075, components/sensor/tmp1075, tmp1075.jpg + +Dark Mode 😎 +------------ + +Thanks to :ghuser:`grahambrown11` for implement a dark mode for the ESPHome dashboard! +It will take the preference of your browser and is not configurable at this time. + +Alarm Control Panel +------------------- + +:ghuser:`grahambrown11` also has contributed the base alarm control panel code and a template alarm control panel. +This is available to use now in ESPHome, but will require Home Assistant 2023.7 or newer for the entity to show up +and be control from that side. + +MDI icons +--------- + +You can now specify MDI icons as ESPHome images using the ``mdi:`` prefix, for example: + +.. code-block:: yaml + + image: + - file: "my_image.png" + id: my_image + - file: "mdi:chip" + resize: 32x32 + id: chip_icon + +Wi-Fi enable and disable +------------------------ + +Wi-Fi can now be enabled and disabled on demand using the ``wifi.enable`` and ``wifi.disable`` actions. +It can also be set to not enable on bootup. See the :doc:`Wi-Fi documentation ` for more details. + + +Release 2023.6.1 - June 23 +-------------------------- + +- Make ethernet_info work with esp-idf framework :esphomepr:`4976` by :ghuser:`HeMan` +- display: fix white screen on binary displays :esphomepr:`4991` by :ghuser:`ayufan` + + +Breaking Changes +---------------- + +VOC sensors +^^^^^^^^^^^ + +Some VOC sensors have had their default device class changed from ``volatile_organic_compounds`` to ``volatile_organic_compounds_parts`` +to better align with what they are returning. + + +Microphone +^^^^^^^^^^ + +The ``on_data`` trigger (and the internal callback) for the microphone now provides ``std::vector`` instead of a ``std::vector``. + + +Header files moved +^^^^^^^^^^^^^^^^^^ + +There are a couple of breaking changes for users who publish ``external_components`` and may use the internal APIs. +See the list below for the pull requests that have been marked as breaking changes. + + +Full list of changes +-------------------- + +New Components +^^^^^^^^^^^^^^ + +- Rp2040 pio ledstrip :esphomepr:`4818` by :ghuser:`Papa-DMan` (new-integration) +- Add support for TMP1075 temperature sensor :esphomepr:`4776` by :ghuser:`sybrenstuvel` (new-integration) +- Add Alarm Control Panel :esphomepr:`4770` by :ghuser:`grahambrown11` (new-integration) + +Breaking Changes +^^^^^^^^^^^^^^^^ + +- Add transparency support to all image types :esphomepr:`4600` by :ghuser:`guillempages` (breaking-change) +- Allow i2s microphone bits per sample to be configured :esphomepr:`4884` by :ghuser:`jesserockz` (breaking-change) +- Move ESPTime into core esphome namespace :esphomepr:`4926` by :ghuser:`jesserockz` (breaking-change) +- display: add `BaseImage` and provide only `Image::get_pixel` method :esphomepr:`4932` by :ghuser:`ayufan` (breaking-change) +- Migrate VOC sensors that use ppb to use volatile_organic_compounds_parts device class :esphomepr:`4982` by :ghuser:`bdraco` (breaking-change) + +Beta Changes +^^^^^^^^^^^^ + +- Add support in vbus component for Deltasol BS 2009 :esphomepr:`4943` by :ghuser:`clydebarrow` +- fix vbus sensor offsets :esphomepr:`4952` by :ghuser:`ssieb` +- Add support for ESP32-S3-BOX-Lite displays :esphomepr:`4941` by :ghuser:`guillempages` +- Split display_buffer sub-components into own files :esphomepr:`4950` by :ghuser:`guillempages` +- Add support for S3 box display :esphomepr:`4942` by :ghuser:`guillempages` +- display: allow to align image with `ImageAlign` :esphomepr:`4933` by :ghuser:`ayufan` +- Use HW SPI for rp2040 :esphomepr:`4955` by :ghuser:`jesserockz` +- Fix for Fujitsu AC not having Quiet Fan Mode :esphomepr:`4962` by :ghuser:`TaruDesigns` +- Store app comment and compilation_time in flash :esphomepr:`4945` by :ghuser:`bdraco` +- Construct web_server assets at build time instead of run time :esphomepr:`4944` by :ghuser:`bdraco` +- Update pca9685_output.cpp :esphomepr:`4929` by :ghuser:`standahabich` +- Apply configured IIR filter setting in generated BMP280 code :esphomepr:`4975` by :ghuser:`murrayma` +- airthings_wave: refactor to eliminate code duplication :esphomepr:`4910` by :ghuser:`kpfleming` (new-integration) +- Make growatt play nicer with other modbus components. :esphomepr:`4947` by :ghuser:`onnlucky` +- Bump esphome-dashboard to 20230621.0 :esphomepr:`4980` by :ghuser:`jesserockz` +- Fix pypi release :esphomepr:`4983` by :ghuser:`jesserockz` +- Add configuration option to disable the log UI. :esphomepr:`4419` by :ghuser:`dd32` +- Update webserver and captive portal pages to 67c48ee9 :esphomepr:`4986` by :ghuser:`jesserockz` +- Migrate VOC sensors that use ppb to use volatile_organic_compounds_parts device class :esphomepr:`4982` by :ghuser:`bdraco` (breaking-change) +- dashboard: Adds "compressed=1" to /download.bin endpoint. (...) :esphomepr:`4966` by :ghuser:`fdcastel` + +All changes +^^^^^^^^^^^ + +- Add minimum RSSI check to ble presence :esphomepr:`4646` by :ghuser:`nielsnl68` +- Run black over tests folder :esphomepr:`4824` by :ghuser:`jesserockz` +- Use token so PR checks are run :esphomepr:`4834` by :ghuser:`jesserockz` +- Fix stale bot ignoring not-stale :esphomepr:`4836` by :ghuser:`jesserockz` +- Rework CI into multiple dependent jobs :esphomepr:`4823` by :ghuser:`jesserockz` +- Add DNS to Text info :esphomepr:`4821` by :ghuser:`max246` +- allow to use MQTT for discovery of IPs if mDNS is no option :esphomepr:`3887` by :ghuser:`Links2004` +- Move some I2C logic out of header file :esphomepr:`4839` by :ghuser:`CarsonF` +- Allow substitutions to be valid names :esphomepr:`4726` by :ghuser:`jgoguen` +- Insert Europe Tank Types from mopeka_std_check :esphomepr:`4757` by :ghuser:`lukasl96` +- Bump tornado from 6.3.1 to 6.3.2 :esphomepr:`4841` by :ghuser:`dependabot[bot]` +- Bump pylint from 2.17.3 to 2.17.4 :esphomepr:`4843` by :ghuser:`dependabot[bot]` +- Bump zeroconf from 0.60.0 to 0.62.0 :esphomepr:`4781` by :ghuser:`dependabot[bot]` +- Bump pyupgrade from 3.3.2 to 3.4.0 :esphomepr:`4842` by :ghuser:`dependabot[bot]` +- Bump platformio from 6.1.6 to 6.1.7 :esphomepr:`4795` by :ghuser:`dependabot[bot]` +- Migrate e131 to use socket instead of WiFiUDP arduino library :esphomepr:`4832` by :ghuser:`jesserockz` +- Add transparency support to all image types :esphomepr:`4600` by :ghuser:`guillempages` (breaking-change) +- Run YAML test 8 during CI and fix board used :esphomepr:`4862` by :ghuser:`kroimon` +- Rp2040 pio ledstrip :esphomepr:`4818` by :ghuser:`Papa-DMan` (new-integration) +- [ILI9xxx] Update ili9xxx_init.h code for the ILI9488 display for correct white balance :esphomepr:`4849` by :ghuser:`lucasreiners` +- Update codeowners :esphomepr:`4875` by :ghuser:`freekode` +- Fix rp2040_pio_led_strip color modes :esphomepr:`4887` by :ghuser:`jesserockz` +- Add i2s mclk :esphomepr:`4885` by :ghuser:`rpatel3001` +- Allow partially looping animations :esphomepr:`4693` by :ghuser:`guillempages` +- Allow i2s microphone bits per sample to be configured :esphomepr:`4884` by :ghuser:`jesserockz` (breaking-change) +- Add support for TMP1075 temperature sensor :esphomepr:`4776` by :ghuser:`sybrenstuvel` (new-integration) +- move pio tools to LED component :esphomepr:`4903` by :ghuser:`ssieb` +- add SUB_SELECT macro :esphomepr:`4897` by :ghuser:`regevbr` +- add SUB_SWITCH macro :esphomepr:`4898` by :ghuser:`regevbr` +- esp32_rmt_led_strip: fix compile with ESP-IDF >= 5 :esphomepr:`4856` by :ghuser:`stintel` +- Bump aioesphomeapi from 13.7.5 to 13.9.0 :esphomepr:`4907` by :ghuser:`dependabot[bot]` +- ota: fix compile with ESP-IDF >= 5 :esphomepr:`4857` by :ghuser:`stintel` +- ota: fix TWDT with ESP-IDF >= 5 :esphomepr:`4858` by :ghuser:`stintel` +- light: fix compile with ESP-IDF >= 5 :esphomepr:`4855` by :ghuser:`stintel` +- Continuous voice_assistant and silence detection :esphomepr:`4892` by :ghuser:`jesserockz` +- Allow WIFI to be disabled and enabled :esphomepr:`4810` by :ghuser:`jesserockz` +- Bump frenck/action-yamllint from 1.4.0 to 1.4.1 :esphomepr:`4876` by :ghuser:`dependabot[bot]` +- Bump pytest-cov from 4.0.0 to 4.1.0 :esphomepr:`4888` by :ghuser:`dependabot[bot]` +- Bump zeroconf from 0.62.0 to 0.63.0 :esphomepr:`4890` by :ghuser:`dependabot[bot]` +- Bump esptool from 4.5.1 to 4.6 :esphomepr:`4906` by :ghuser:`dependabot[bot]` +- prometheus: fix compilation with EntityBase :esphomepr:`4895` by :ghuser:`mischief` +- Support for Adafruit ESP32-S2 TFT Feather :esphomepr:`4912` by :ghuser:`PlainTechEnthusiast` +- Add support for mdi images :esphomepr:`4654` by :ghuser:`guillempages` +- Increase SNTP setup priority :esphomepr:`4917` by :ghuser:`droscy` +- Bump aioesphomeapi from 13.9.0 to 14.0.0 :esphomepr:`4925` by :ghuser:`dependabot[bot]` +- Bluetooth Proxy: Raw bundled advertisements :esphomepr:`4924` by :ghuser:`jesserockz` +- Move ESPTime into core esphome namespace :esphomepr:`4926` by :ghuser:`jesserockz` (breaking-change) +- Allow multiple MAC addresses for 'on_ble_advertise' filter :esphomepr:`4773` by :ghuser:`RoboMagus` +- Add SVG image support :esphomepr:`4922` by :ghuser:`guillempages` +- Add !extend to devcontainer's customTags :esphomepr:`4749` by :ghuser:`jimtng` +- [max7219digit] fix 270° rotation :esphomepr:`4930` by :ghuser:`spezifisch` +- proto generation updates :esphomepr:`4653` by :ghuser:`jesserockz` +- I2S media player allow setting communication format for external DACs :esphomepr:`4918` by :ghuser:`ccorderor` +- Add MULTI_CONF to pn53_i2c :esphomepr:`4938` by :ghuser:`jesserockz` +- display: Improve Image rendering by removing usage of virtual functions :esphomepr:`4931` by :ghuser:`ayufan` +- display: add `BaseImage` and provide only `Image::get_pixel` method :esphomepr:`4932` by :ghuser:`ayufan` (breaking-change) +- Add Alarm Control Panel :esphomepr:`4770` by :ghuser:`grahambrown11` (new-integration) +- Add support in vbus component for Deltasol BS 2009 :esphomepr:`4943` by :ghuser:`clydebarrow` +- fix vbus sensor offsets :esphomepr:`4952` by :ghuser:`ssieb` +- Add support for ESP32-S3-BOX-Lite displays :esphomepr:`4941` by :ghuser:`guillempages` +- Split display_buffer sub-components into own files :esphomepr:`4950` by :ghuser:`guillempages` +- Add support for S3 box display :esphomepr:`4942` by :ghuser:`guillempages` +- display: allow to align image with `ImageAlign` :esphomepr:`4933` by :ghuser:`ayufan` +- Use HW SPI for rp2040 :esphomepr:`4955` by :ghuser:`jesserockz` +- Fix for Fujitsu AC not having Quiet Fan Mode :esphomepr:`4962` by :ghuser:`TaruDesigns` +- Store app comment and compilation_time in flash :esphomepr:`4945` by :ghuser:`bdraco` +- Construct web_server assets at build time instead of run time :esphomepr:`4944` by :ghuser:`bdraco` +- Update pca9685_output.cpp :esphomepr:`4929` by :ghuser:`standahabich` +- Apply configured IIR filter setting in generated BMP280 code :esphomepr:`4975` by :ghuser:`murrayma` +- airthings_wave: refactor to eliminate code duplication :esphomepr:`4910` by :ghuser:`kpfleming` (new-integration) +- Make growatt play nicer with other modbus components. :esphomepr:`4947` by :ghuser:`onnlucky` +- Bump esphome-dashboard to 20230621.0 :esphomepr:`4980` by :ghuser:`jesserockz` +- Fix pypi release :esphomepr:`4983` by :ghuser:`jesserockz` +- Add configuration option to disable the log UI. :esphomepr:`4419` by :ghuser:`dd32` +- Update webserver and captive portal pages to 67c48ee9 :esphomepr:`4986` by :ghuser:`jesserockz` +- Migrate VOC sensors that use ppb to use volatile_organic_compounds_parts device class :esphomepr:`4982` by :ghuser:`bdraco` (breaking-change) +- dashboard: Adds "compressed=1" to /download.bin endpoint. (...) :esphomepr:`4966` by :ghuser:`fdcastel` + +Past Changelogs +--------------- + +- :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 432d0558251..89115021478 100644 --- a/changelog/index.rst +++ b/changelog/index.rst @@ -2,7 +2,7 @@ Changelog ========= .. redirect:: - :url: /changelog/2023.4.0.html + :url: /changelog/2023.6.0.html .. toctree:: :glob: diff --git a/components/alarm_control_panel/index.rst b/components/alarm_control_panel/index.rst new file mode 100644 index 00000000000..4fe03ccbe23 --- /dev/null +++ b/components/alarm_control_panel/index.rst @@ -0,0 +1,203 @@ +Alarm Control Panel Component +============================= + +.. seo:: + :description: Instructions for setting up generic Alarm Control Panels in ESPHome. + :image: alarm-panel.svg + +.. _config-alarm_control_panel: + +Base Alarm Control Panel Configuration +-------------------------------------- + +.. code-block:: yaml + + alarm_control_panel: + - platform: ... + name: Alarm Panel + + +Configuration variables: + +- **name** (**Required**, string): The name of the alarm control panel. + + .. note:: + + If you have a :ref:`friendly_name ` set for your device and + you want the switch to use that name, you can set ``name: None``. + +- **on_state** (*Optional*, :ref:`Action `): An automation to perform + when the alarm changes state. See :ref:`alarm_control_panel_on_state_trigger`. +- **on_triggered** (*Optional*, :ref:`Action `): An automation to perform + when the alarm triggers. See :ref:`alarm_control_panel_on_triggered_trigger`. +- **on_cleared** (*Optional*, :ref:`Action `): An automation to perform + when the alarm clears. See :ref:`alarm_control_panel_on_cleared_trigger`. + + +Automation: +----------- + +.. _alarm_control_panel_on_state_trigger: + +``on_state`` Trigger +******************** + +This trigger is activated each time the alarm changes state. + +.. code-block:: yaml + + alarm_control_panel: + # ... + on_state: + then: + - logger.log: "Alarm Panel State Changed!" + +.. _alarm_control_panel_on_triggered_trigger: + +``on_triggered`` Trigger +************************ + +This trigger is activated when the alarm changes to triggered state. + +.. code-block:: yaml + + alarm_control_panel: + # ... + on_triggered: + then: + - logger.log: "Alarm Triggered!" + +.. _alarm_control_panel_on_cleared_trigger: + +``on_cleared`` Trigger +********************** + +This trigger is activated when the alarm changes from triggered back to either the previous armed state or disarmed. + +.. code-block:: yaml + + alarm_control_panel: + # ... + on_cleared: + then: + - logger.log: "Alarm Cleared!" + +.. _alarm_control_panel_arm_away_action: + +``arm_away`` Action +******************* + +This action arms the alarm in away mode. The ``code`` is required when *requires_code_to_arm* is *true*. + +.. code-block:: yaml + + on_...: + then: + - alarm_control_panel.arm_away: + id: alarm + code: "1234" + +.. _alarm_control_panel_arm_home_action: + +``arm_home`` Action +******************* + +This action arms the alarm in home mode. The ``code`` is required when *requires_code_to_arm* is *true*. + +.. code-block:: yaml + + on_...: + then: + - alarm_control_panel.arm_home: + id: alarm + code: "1234" + +.. _alarm_control_panel_disarm_action: + +``disarm`` Action +***************** + +This action disarms the alarm. The ``code`` is required when *codes* is not empty. + +.. code-block:: yaml + + on_...: + then: + - alarm_control_panel.disarm: + id: alarm + code: "1234" + +.. _alarm_control_panel_pending_action: + +``pending`` Action +****************** + +This action puts the alarm in pending state (the state before triggered after *pending_time*). + +.. code-block:: yaml + + on_...: + then: + - alarm_control_panel.pending: alarm + +.. _alarm_control_panel_triggered_action: + +``triggered`` Action +******************** + +This action puts the alarm in triggered state. + +.. code-block:: yaml + + on_...: + then: + - alarm_control_panel.triggered: alarm + +.. _alarm_control_panel_is_armed_condition: + +``is_armed`` Condition +********************** + +This :ref:`Condition ` checks if the alarm control panel is armed. + +.. code-block:: yaml + + on_...: + if: + condition: + alarm_control_panel.is_armed: alarm + + +.. _alarm_control_panel_lambda_calls: + +lambda calls +************ + +From :ref:`lambdas `, you can call the following methods: + +- ``arm_away(code)`` +- ``arm_home(code)`` +- ``disarm(code)`` + +.. code-block:: cpp + + id(alarm).arm_away(); + id(alarm).arm_home(); + id(alarm).disarm("1234"); + + +Platforms +--------- + +.. toctree:: + :maxdepth: 1 + :glob: + + * + +See Also +-------- + +- :doc:`/components/binary_sensor/index` +- :apiref:`alarm_control_panel/alarm_control_panel.h` +- :ghedit:`Edit` diff --git a/components/alarm_control_panel/template.rst b/components/alarm_control_panel/template.rst new file mode 100644 index 00000000000..9a9d3bc778a --- /dev/null +++ b/components/alarm_control_panel/template.rst @@ -0,0 +1,135 @@ +Template Alarm Control Panel +============================ + +.. seo:: + :description: Instructions for setting up template Alarm Control Panels in ESPHome. + :image: description.svg + +The ``template`` alarm control panel platform allows you to turn your binary sensors into a state machine +managed alarm control panel. + +.. code-block:: yaml + + # Example configuration entry + alarm_control_panel: + - platform: template + name: Alarm Panel + codes: + - "1234" + binary_sensors: + - input: zone_1 + - input: zone_2 + bypass_armed_home: true + +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_time** (*Optional*, :ref:`config-time`): The exit delay before the alarm is armed. +- **pending_time** (*Optional*, :ref:`config-time`): The entry delay before the alarm is triggered. +- **trigger_time** (*Optional*, :ref:`config-time`): The time after a triggered alarm before resetting to previous state if the sensors are cleared/off. +- **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. + +- **restore_mode** (*Optional*, enum): + + - ``ALWAYS_DISARMED`` (Default): Always start in ``disarmed`` state. + - ``RESTORE_DEFAULT_DISARMED``: Restore state or default to ``disarmed`` state if no saved state was found. + +- All other options from :ref:`Alarm Control Panel ` + +.. note:: + + If ``binary_sensors`` is ommited then you're expected to trigger the alarm using + :ref:`alarm_control_panel_pending_action` or :ref:`alarm_control_panel_triggered_action`. + + +.. _template_alarm_control_panel-state_flow: + +State Flow: +----------- + +1. The alarm starts in ``DISARMED`` state +2. When the ``arm_...`` method is invoked + + a. ``arming_time`` greater than 0 the state is ``ARMING`` + b. ``arming_time`` is 0 or after the ``arming_time`` delay the state is ``ARM_AWAY`` or ``ARM_HOME`` + +3. When the alarm is tripped by a sensor state changing to ``on`` + + a. ``pending_time`` greater than 0 the state is ``PENDING`` + b. ``pending_time`` is 0 or after the ``pending_time`` delay the state is ``TRIGGERED`` + +4. If ``trigger_time`` greater than 0 and no sensors are ``on`` after ``trigger_time`` delay + the state returns to ``ARM_AWAY`` or ``ARM_HOME`` + +Example: +-------- + +.. code-block:: yaml + + alarm_control_panel: + platform: template + name: Alarm Panel + codes: + - "1234" + requires_code_to_arm: true + arming_time: 10s + pending_time: 15s + trigger_time: 5min + binary_sensors: + - input: zone_1 + - input: zone_2 + bypass_armed_home: true + - input: ha_test + on_state: + then: + - lambda: !lambda |- + ESP_LOGD("TEST", "State change %s", alarm_control_panel_state_to_string(id(acp1)->get_state())); + on_triggered: + then: + - switch.turn_on: siren + on_cleared: + then: + - switch.turn_off: siren + + binary_sensor: + - platform: gpio + id: zone_1 + name: Zone 1 + device_class: door + pin: + number: D1 + mode: INPUT_PULLUP + inverted: True + - platform: gpio + id: zone_2 + name: Zone 2 + device_class: motion + pin: + number: D2 + mode: INPUT_PULLUP + inverted: True + - platform: homeassistant + id: ha_test + name: Zone 3 + entity_id: input_boolean.test_switch + + switch: + - platform: gpio + id: siren + name: Siren + icon: mdi:alarm-bell + pin: D7 + + +See Also +-------- + +- :doc:`index` +- :doc:`/components/binary_sensor/index` +- :apiref:`template/alarm_control_panel/template_alarm_control_panel.h` +- :ghedit:`Edit` diff --git a/components/binary_sensor/ble_presence.rst b/components/binary_sensor/ble_presence.rst index 60d53f7cf7a..9d75e472ae9 100644 --- a/components/binary_sensor/ble_presence.rst +++ b/components/binary_sensor/ble_presence.rst @@ -22,6 +22,7 @@ Bluetooth Low Energy device. - platform: ble_presence mac_address: AC:37:43:77:5F:4C name: "ESP32 BLE Tracker Google Home Mini" + min_rssi: -80dB # Presence based on BLE Service UUID - platform: ble_presence service_uuid: '11aa' @@ -58,6 +59,7 @@ Configuration variables: to be tracked. Usually used to identify beacons within an iBeacon group. - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- **min_rssi** (*Optional*, int): at which minimum RSSI level would the component report the device be precent - All other options from :ref:`Binary Sensor `. .. _esp32_ble_tracker-setting_up_devices: diff --git a/components/ble_client.rst b/components/ble_client.rst index 44b2c03d208..7424ecf7012 100644 --- a/components/ble_client.rst +++ b/components/ble_client.rst @@ -21,8 +21,8 @@ but merely manages connections to them for use by other components. ESP32 BLE stack. If you wish to connect more devices, use additional ESP32 boards. - This component does not (yet) support devices that require - security settings (eg connecting with a PIN). + This component supports devices that require a 6 digit PIN code + for authentication. Currently, devices connected with the client cannot be supported by other components based on :doc:`/components/esp32_ble_tracker` @@ -53,6 +53,12 @@ Automations: when the client connects to a device. See :ref:`ble_client-on_connect`. - **on_disconnect** (*Optional*, :ref:`Automation `): An automation to perform when the client disconnects from a device. See :ref:`ble_client-on_disconnect`. +- **on_passkey_request** (*Optional*, :ref:`Automation `): An automation to enter + the passkey required by the other BLE device. See :ref:`ble_client-on_passkey_request`. +- **on_passkey_notification** (*Optional*, :ref:`Automation `): An automation to + display the passkey to the user. See :ref:`ble_client-on_passkey_notification`. +- **on_numeric_comparison_request** (*Optional*, :ref:`Automation `): An automation to + compare the passkeys shown on the two BLE devices. See :ref:`ble_client-on_numeric_comparison_request`. BLE Client Automation --------------------- @@ -91,6 +97,64 @@ This automation is triggered when the client disconnects from a BLE device. - lambda: |- ESP_LOGD("ble_client_lambda", "Disconnected from BLE device"); + +.. _ble_client-on_passkey_request: + +``on_passkey_request`` +********************** + +This automation is triggered when the BLE device requests a passkey for authentication. + +.. code-block:: yaml + + ble_client: + - mac_address: 11:22:33:44:55:66 + id: ble_itag + on_passkey_request: + then: + - ble_client.passkey_reply: + id: ble_itag + passkey: 123456 + +.. _ble_client-on_passkey_notification: + +``on_passkey_notification`` +*************************** + +This automation is triggered when a passkey is received from the BLE device. + +.. code-block:: yaml + + ble_client: + - mac_address: 11:22:33:44:55:66 + id: ble_itag + on_passkey_notification: + then: + - logger.log: + format: "Enter this passkey on your BLE device: %06d" + args: [ passkey ] + +.. _ble_client-on_numeric_comparison_request: + +``on_numeric_comparison_request`` +********************************* + +This automation is triggered when a numeric comparison is requested by the BLE device. + +.. code-block:: yaml + + ble_client: + - mac_address: 11:22:33:44:55:66 + id: ble_itag + on_numeric_comparison_request: + then: + - logger.log: + format: "Compare this passkey with the one on your BLE device: %06d" + args: [ passkey ] + - ble_client.numeric_comparison_reply: + id: ble_itag + accept: True + .. _ble_client-ble_write_action: ``ble_client.ble_write`` Action @@ -133,6 +197,75 @@ Configuration variables: - **characteristic_uuid** (**Required**, UUID): UUID of the service's characteristic to write to. - **value** (**Required**, Array of bytes or :ref:`lambda `): The value to be written. +.. _ble_client-passkey_reply_action: + +``ble_client.passkey_reply`` Action +----------------------------------- + +This action triggers an authentication attempt using the specified ``passkey``. + +Example usage: + +.. code-block:: yaml + + on_...: + then: + - ble_client.passkey_reply: + id: my_ble_client + passkey: 123456 + +Configuration variables: + +- **id** (**Required**, :ref:`config-id`): ID of the associated BLE client. +- **passkey** (**Required**, int): The 6-digit passkey. + +.. _ble_client-numeric_comparison_reply_action: + +``ble_client.numeric_comparison_reply`` Action +---------------------------------------------- + +This action triggers an authentication attempt after a numeric comparison. + +Example usage: + +.. code-block:: yaml + + on_...: + then: + - ble_client.numeric_comparison_reply: + id: my_ble_client + accept: True + +Configuration variables: + +- **id** (**Required**, :ref:`config-id`): ID of the associated BLE client. +- **accept** (**Required**, boolean): Should be ``true`` if the passkeys + displayed on both BLE devices are matching. + +.. _ble_client-remove_bond_action: + +``ble_client.remove_bond`` Action +---------------------------------------------- + +This action removes a device from the security database and manages +unpairing. + +Example usage: + +.. code-block:: yaml + + ble_client: + - mac_address: 11:22:33:44:55:66 + id: my_ble_client + on_connect: + then: + - ble_client.remove_bond: + id: my_ble_client + +Configuration variables: + +- **id** (**Required**, :ref:`config-id`): ID of the associated BLE client. + BLE Overview ------------ This section gives a brief overview of the Bluetooth LE architecture @@ -186,9 +319,8 @@ characteristics and descriptors also provide a small 2-byte Setting Up Devices ------------------ -Whilst the component can connect to most BLE devices (that do not -require authentication/pin), useful functionality is only obtained -through dependent components, such as :doc:`/components/sensor/ble_client`. +Whilst the component can connect to most BLE devices, useful functionality +is only obtained through dependent components, such as :doc:`/components/sensor/ble_client`. See the documentation for these components for details on setting up specific devices. @@ -247,6 +379,78 @@ The discovered services can then be used to enable and configure other ESPHome components, for example Service UUID 0xFFE0 is used for iTag style keychain button events, used by the :doc:`/components/sensor/ble_client` component. +Passkey examples +---------------- + +Secure connection with a fixed passkey: + +.. code-block:: yaml + + esp32_ble: + io_capability: keyboard_only + + esp32_ble_tracker: + + ble_client: + - mac_address: A4:C1:38:B1:CD:7F + id: pvvx_ble_display + on_passkey_request: + then: + - logger.log: "Authenticating with passkey" + - ble_client.passkey_reply: + id: pvvx_ble_display + passkey: 123456 + +Secure connection with a dynamically generated passkey: + +.. code-block:: yaml + + api: + services: + - service: passkey_reply + variables: + passkey: int + then: + - logger.log: "Authenticating with passkey" + - ble_client.passkey_reply: + id: my_ble_client + passkey: !lambda return passkey; + - service: numeric_comparison_reply + variables: + accept: bool + then: + - logger.log: "Authenticating with numeric comparison" + - ble_client.numeric_comparison_reply: + id: my_ble_client + accept: !lambda return accept; + + esp32_ble: + io_capability: keyboard_display + + esp32_ble_tracker: + + ble_client: + - mac_address: AA:BB:CC:DD:EE:FF + id: my_ble_client + on_passkey_request: + then: + - logger.log: "Enter the passkey displayed on your BLE device" + - logger.log: " Go to https://my.home-assistant.io/redirect/developer_services/ and select passkey_reply" + on_passkey_notification: + then: + - logger.log: + format: "Enter this passkey on your BLE device: %06d" + args: [ passkey ] + on_numeric_comparison_request: + then: + - logger.log: + format: "Compare this passkey with the one on your BLE device: %06d" + args: [ passkey ] + - logger.log: " Go to https://my.home-assistant.io/redirect/developer_services/ and select numeric_comparison_reply" + on_connect: + then: + - logger.log: "Connected" + See Also -------- diff --git a/components/captive_portal.rst b/components/captive_portal.rst index 4b25433470a..74305f44c16 100644 --- a/components/captive_portal.rst +++ b/components/captive_portal.rst @@ -16,7 +16,7 @@ After 1 minute of unsuccessful WiFi connection attempts, the ESP will start a Wi :width: 70.0% In this web interface, you can manually override the WiFi settings of the device (please note -this will be overwritten by any subsequent upload so make sure to also update your YAML configuration). +this will be overwritten by any subsequent serial upload so make sure to also update your YAML configuration). Additionally, you can upload a new firmware file. diff --git a/components/climate/haier.rst b/components/climate/haier.rst index 62be4289333..040bf87c7f6 100644 --- a/components/climate/haier.rst +++ b/components/climate/haier.rst @@ -5,47 +5,11 @@ Haier Climate :description: Instructions for setting up a Haier climate devices. :image: air-conditioner.svg -The `haier` climate platform creates a Haier climate device. -The component can be used as a replacement of a Haier proprietary WiFi modules such as KZW-W001 and KZW-W002. +This is an implementation of the ESPHome component to control HVAC on the base of the SmartAir2 and hOn Haier protocols (AC that is controlled by the hOn or SmartAir2 application). -This component requires a :ref:`uart` to be setup. - -.. code-block:: yaml - - logger: - baud_rate: 0 #Disable UART logging for ESP8266 - - uart: - rx_pin: GPIO3 - tx_pin: GPIO1 - baud_rate: 9600 - - climate: - platform: haier - name: Haier AC - supported_swing_modes: - - VERTICAL - - HORIZONTAL - - BOTH - -Configuration variables: ------------------------- - -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- **name** (**Required**, string): The name of the climate device. -- **update_interval** (*Optional*, :ref:`config-time`): How often device will be polled for status. Defaults to `5s`. -- **supported_swing_modes** (*Optional*, list): List of supported swing modes. Possible values are: ``VERTICAL``, ``HORIZONTAL``, ``BOTH``. -- All other options from :ref:`Climate `. - -Hardware setup --------------- - -Most units will have a dedicated USB-A port for Haier WiFi module. -The physical USB port is in fact UART and does not "speak" USB protocol. -It uses four USB pins as 5V, GND, RX, TX. -You can use spare male USB cable to connect esphome device directly to the climate appliance. +There are two versions of the Haier protocol. The older one is using an application called SmartAir2 and the newer one - an application called hOn. Both protocols are compatible on the transport level but have different commands to control appliances. -Other units will not have USB ports, but will still probably have UART exposed somewhere on the main board. +Older Haier models controlled by the SmartAir2 application are using the KZW-W002 module. This module can’t be reused, and you need to replace it with an ESP (RPI pico w) module. The USB connector on a board doesn’t support the USB protocol. It is a UART port that just uses a USB connector. To connect the ESP board to your AC you can cut a USB type A cable and connect wires to the climate connector. .. list-table:: Haier UART pinout :header-rows: 1 @@ -75,12 +39,232 @@ Other units will not have USB ports, but will still probably have UART exposed s :align: center :width: 70.0% - USB Pinout + KZW-W002 module pinout + +Newer Haier models using a module called ESP32-for-Haier. It is an ESP32 single-core board with an ESP32-S0WD chip. In some cases, you can reuse this module and flash it with ESPHome, but some new modules don’t support this. They look the same but have encryption enabled. + +**Warning!** The new generation of ESP32-Haier devices has encryption enabled, so they can only be flashed with firmware that is signed with a private key. There is no way to make them work with ESPHome, so if you try to do it, the board will get into a boot loop with error ``rst:0x10 (RTCWDT_RTC_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)`` The only way to recover this board is to flash it with the original image. So before starting your experiments make a backup image. + +.. figure:: images/haier_pinout.jpg + :align: center + :width: 70.0% + + ESP32-for-Haier UART0 pinout + +Also, you can use any other ESP32, ESP8266 or a RPI pico W board. In this case, you will need to cut the original wire or make a connector yourself (the board has a JST SM04B-GHS-TB connector) + +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 + uart_id: ac_port + wifi_signal: true + beeper: true + outdoor_temperature: + name: Haier AC outdoor temperature + visual: + min_temperature: 16 °C + max_temperature: 30 °C + temperature_step: 1 °C + supported_modes: + - 'OFF' + - AUTO + - COOL + - HEAT + - DRY + - FAN_ONLY + supported_swing_modes: + - 'OFF' + - VERTICAL + - HORIZONTAL + - BOTH + + +Configuration variables: +------------------------ + +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- **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. +- **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. + + - **name** (**Required**, string): The name of the sensor. + - **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 +- All other options from :ref:`Climate `. + +Automations +----------- + +climate.haier.power_on Action +***************************** + +This action turns AC power on. + +.. code-block:: yaml + + on_...: + then: + climate.haier.power_on: device_id + +climate.haier.power_off Action +****************************** + +This action turns AC power off + +.. code-block:: yaml + + on_...: + then: + climate.haier.power_off: device_id + +climate.haier.power_toggle Action +********************************* + +This action toggles AC power + +.. code-block:: yaml + + on_...: + then: + climate.haier.power_toggle: device_id + +climate.haier.display_on Action +******************************* + +This action turns the AC display on + +.. code-block:: yaml + + on_...: + then: + climate.haier.display_on: device_id + +climate.haier.display_off Action +******************************** + +This action turns the AC display off + +.. code-block:: yaml + + on_...: + then: + climate.haier.display_off: device_id + +climate.haier.health_on Action +****************************** + +Turn on health mode (`UV light sterilization `__) + +.. code-block:: yaml + + on_...: + then: + climate.haier.health_on: device_id + +climate.haier.health_off Action +******************************* + +Turn off health mode + +.. code-block:: yaml + + on_...: + then: + climate.haier.health_off: device_id + +climate.haier.beeper_on Action +****************************** + +(supported only by hOn) This action enables beep feedback on every command sent to AC + +.. code-block:: yaml + + on_...: + then: + climate.haier.beeper_on: device_id + +climate.haier.beeper_off Action +******************************* + +(supported only by hOn) This action disables beep feedback on every command sent to AC (keep in mind that this will not work for IR remote commands) + +.. code-block:: yaml + + on_...: + then: + climate.haier.beeper_off: device_id + +climate.haier.set_vertical_airflow Action +***************************************** + +(supported only by hOn) Set direction for vertical airflow if the vertical swing is disabled. Possible values: Health_Up, Max_Up, Up, Center, Down, Health_Down. + +.. code-block:: yaml + + on_...: + then: + - climate.haier.set_vertical_airflow: + id: device_id + vertical_airflow: Up + +climate.haier.set_horizontal_airflow Action +******************************************* + +(supported only by hOn) Set direction for horizontal airflow if the horizontal swing is disabled. Possible values: Max_Left, Left, Center, Right, Max_Right. + +.. code-block:: yaml + + on_...: + then: + - climate.haier.set_horizontal_airflow: + id: device_id + vertical_airflow: Right + +climate.haier.start_self_cleaning Action +**************************************** + +(supported only by hOn) Start `self-cleaning `__ + +.. code-block:: yaml + + on_...: + then: + - climate.haier.start_self_cleaning: device_id + +climate.haier.start_steri_cleaning Action +***************************************** + +(supported only by hOn) Start 56°C steri-cleaning + +.. code-block:: yaml + + on_...: + then: + - climate.haier.start_steri_cleaning: device_id See Also -------- -- `esphaier `__ +- `haier-esphome `__ - :doc:`/components/climate/index` - :apiref:`haier/climate/haier.h` - :ghedit:`Edit` diff --git a/components/climate/images/deadband1.png b/components/climate/images/deadband1.png index a16a6edcfa6..563271df448 100644 Binary files a/components/climate/images/deadband1.png and b/components/climate/images/deadband1.png differ diff --git a/components/climate/images/deadband2.png b/components/climate/images/deadband2.png index 1ef8ee649b4..e805558c925 100644 Binary files a/components/climate/images/deadband2.png and b/components/climate/images/deadband2.png differ diff --git a/components/climate/images/haier_pinout.jpg b/components/climate/images/haier_pinout.jpg new file mode 100644 index 00000000000..24580f7662c Binary files /dev/null and b/components/climate/images/haier_pinout.jpg differ diff --git a/components/climate/index.rst b/components/climate/index.rst index ceebe2525da..7a49b5e1252 100644 --- a/components/climate/index.rst +++ b/components/climate/index.rst @@ -52,8 +52,8 @@ Configuration variables: - **temperature_step** (*Optional*, float): The granularity with which the target temperature can be controlled. Can be a single number, or split as below: - - **target_temperature** (**Required**, float) - - **current_temperature** (**Required**, float) + - **target_temperature** (**Required**, float): The granularity for target temperature + - **current_temperature** (**Required**, float): The granularity for current temperature Advanced options: diff --git a/components/climate/pid.rst b/components/climate/pid.rst index 38f711eecb7..32a3175608a 100644 --- a/components/climate/pid.rst +++ b/components/climate/pid.rst @@ -15,12 +15,12 @@ temperature to a user-specified setpoint. .. note:: PID is like cruise control in the cars: it keeps the car's speed constant by continuously - adjusting the fuel quantity, based on load measurements. Eg when the car has to go up on a hill, + adjusting the fuel quantity, based on load measurements. Eg when the car has to go up on a hill, the system notices the load increase thus immediately gives more fuel to the engine; and when it goes down on the other side of the hill, it notices the load decrease thus reduces or cuts off fuel completely so that car speed remains as constant as possible. The calculation takes in consideration - constants like car weight, wind resistance etc. - + constants like car weight, wind resistance etc. + This kind of math can be used for a heating or cooling system too, and an auto-tuning algorithm can help determining such constants, which mainly describe the heat loss of the room or building. Goal is to keep the temperature as constant as possible, and smooth out oscillations otherwise produced by @@ -47,12 +47,12 @@ but there's a nice article explaining the function principle `here ` @@ -72,37 +72,35 @@ Configuration variables: ``ki`` to prevent windup. Defaults to ``-1``. - **max_integral** (*Optional*, float): The minimum value of the integral term multiplied by ``ki`` to prevent windup. Defaults to ``1``. - - **starting_integral_term** (*Optional*, float): Set the initial output, by priming the integral - term. This is useful for when your system is rebooted and you don't want to wait + - **starting_integral_term** (*Optional*, float): Set the initial output, by priming the integral + term. This is useful for when your system is rebooted and you don't want to wait for it to get back equilibrium. - - **output_averaging_samples** (*Optional*, int): average the output over this many samples. PID controllers - can be quite sensitive to small changes on the input sensor. By averaging the last X output samples, - the temperature can be more stable. However, the larger the sampling window, the less responsive the + - **output_averaging_samples** (*Optional*, int): average the output over this many samples. PID controllers + can be quite sensitive to small changes on the input sensor. By averaging the last X output samples, + the temperature can be more stable. However, the larger the sampling window, the less responsive the PID controller. Defaults to ``1`` which is no sampling/averaging. - - **derivative_averaging_samples** (*Optional*, int): average the derivative term over this many samples. Many - controllers don't use the derivative term because it is sensitive to slight changes in the input sensor. - By taking an average of the derivative term it might become more useful for you. Most PID controllers call - this derivative filtering. The derivative term is used to pre-act so don't filter too much. Defaults to ``1`` + - **derivative_averaging_samples** (*Optional*, int): average the derivative term over this many samples. Many + controllers don't use the derivative term because it is sensitive to slight changes in the input sensor. + By taking an average of the derivative term it might become more useful for you. Most PID controllers call + this derivative filtering. The derivative term is used to pre-act so don't filter too much. Defaults to ``1`` which is no sampling/averaging. -- **deadband_parameters** (*Optional*): Enables a deadband to stabilise and minimise changes in the +- **deadband_parameters** (*Optional*): Enables a deadband to stabilise and minimise changes in the output when the temperature is close to the target temperature. See `Deadband Setup`_. - - **threshold_low/threshold_high** (**Required**, float): Specifies a high/low - threshold defining the deadband - around the target temperature. For instance with `default_target_temperature` of ``21°C`` and - thresholds of ``+/-0.5°C``, the deadband will be + - **threshold_high/threshold_low** (**Required**, float): Specifies a high/low + threshold defining the deadband around the target temperature. For instance with + ``default_target_temperature`` of ``21°C`` and thresholds of ``+/-0.5°C``, the deadband will be between ``20.5°C - 21.5°C``. The PID controller will limit output changes within the deadband. + - **kp_multiplier** (*Optional*, float): Set the ``kp`` gain when inside the deadband. Defaults to ``0``. + - **ki_multiplier** (*Optional*, float): Set the ``ki`` gain when inside the deadband. Defaults to ``0``. + - **kd_multiplier** (*Optional*, float): Set the ``kd`` gain when inside the deadband. Recommended this + is set to ``0``. Defaults to ``0``. - - **kp_multiplier** (**Optional**, float): Set the ``kp`` gain when inside the deadband. Defaults to ``0``. - - **ki_multiplier** (**Optional**, float): Set the ``ki`` gain when inside the deadband. Defaults to ``0``. - - **kd_multiplier** (**Optional**, float): Set the ``kd`` gain when inside the deadband. Recommended this - is set to 0. Defaults to ``0``. - - - **deadband_output_averaging_samples** (**Optional**, int): Typically when inside the deadband the PID Controller has - reached a state of equilibrium, so it advantageous to use a higher number of output samples + - **deadband_output_averaging_samples** (*Optional*, int): Typically when inside the deadband the PID Controller has + reached a state of equilibrium, so it advantageous to use a higher number of output samples like 10-30 samples. Defaults to ``1`` which is no sampling/averaging. - All other options from :ref:`Climate `. @@ -116,7 +114,7 @@ To set up a PID climate controller, you need a couple of components: - A :ref:`Sensor ` to read the current temperature (``sensor``). - At least one :ref:`float output ` to drive for heating or cooling (or both). - This could for example be a PWM output via :doc:`/components/output/sigma_delta` or :doc:`/components/output/slow_pwm` that drives a heating unit. + This could for example be a PWM output via :doc:`/components/output/sigma_delta_output` or :doc:`/components/output/slow_pwm` that drives a heating unit. Please note the output *must* be controllable with continuous value (not only ON/OFF, but any state in between for example 50% heating power). @@ -126,22 +124,22 @@ To set up a PID climate controller, you need a couple of components: The sensor should have a short update interval. The PID update frequency is tied to the update interval of the sensor. Set a short ``update_interval`` like ``5s`` on the sensor. - We recommend putting a filter on the sensor (see filters in :doc:`/components/sensor/index`) and + We recommend putting a filter on the sensor (see filters in :doc:`/components/sensor/index`) and using ``output_averaging_samples`` to calm the PID sensor from a noisy input sensor. Deadband Setup -------------- -A deadband is used to prevent the PID controller from further adjusting the power -once the temperature has settled within a range of the target temperature. +A deadband is used to prevent the PID controller from further adjusting the power +once the temperature has settled within a range of the target temperature. -We do this by specifying a high/low threshold of the target temperature. +We do this by specifying a high/low threshold of the target temperature. -To understand the benefit, consider a heating/cooling HVAC which is constantly -oscillating between heating and cooling as the thermostat records very minor -changes from +0.1º to -0.1º. Clearly this is undesirable and will cause wear -and tear as the HVAC oscillates. With a deadband in place the heater won't -activate until the thermostat breaches the low_threshold and the cooler won't activate -until the thermostat breaches the high_threshold. +To understand the benefit, consider a heating/cooling HVAC which is constantly +oscillating between heating and cooling as the thermostat records very minor +changes from +0.1º to -0.1º. Clearly this is undesirable and will cause wear +and tear as the HVAC oscillates. With a deadband in place the heater won't +activate until the thermostat breaches the low_threshold and the cooler won't activate +until the thermostat breaches the high_threshold. The most basic setup specifies the threshold around the target temperature as follows: @@ -153,7 +151,7 @@ The most basic setup specifies the threshold around the target temperature as fo threshold_high: 0.5°C threshold_low: -1.0°C -In this example the deadband is between ``20.0°C - 21.5°C``. The PID controller will limit any output +In this example the deadband is between ``20.0°C - 21.5°C``. The PID controller will limit any output variation inside this deadband. How it limits depends on how you set the `Deadband Multipliers`_. .. figure:: images/deadband1.png @@ -161,19 +159,19 @@ variation inside this deadband. How it limits depends on how you set the `Deadba Deadband Multipliers ******************** -Deadband Multipliers tell the controller how to operate when inside of the deadband. +Deadband Multipliers tell the controller how to operate when inside of the deadband. -Each of the p,i and d terms can be controlled using the kp, ki and kd multipliers. For instance, if the kp_multiplier -is set to 0.05 then the final proportional term will be set to 5% of its normal value within the deadband. +Each of the p,i and d terms can be controlled using the kp, ki and kd multipliers. For instance, if the kp_multiplier +is set to 0.05 then the final proportional term will be set to 5% of its normal value within the deadband. -If all of the multipliers are set to 0, then the controller will not adjust power at all within the +If all of the multipliers are set to 0, then the controller will not adjust power at all within the deadband. This is the default behavior. -Most deadband implementations set kp and ki multipliers to a small gain like ``0.05`` and set -derivative to 0. This means that the PID output will calmly make minor adjustments over a 20x longer -timeframe to stay within the deadband zone. +Most deadband implementations set kp and ki multipliers to a small gain like ``0.05`` and set +derivative to 0. This means that the PID output will calmly make minor adjustments over a 20x longer +timeframe to stay within the deadband zone. -To start with we recommend just setting the ``ki_multiplier`` to ``0.05`` (5%). Then +To start with we recommend just setting the ``ki_multiplier`` to ``0.05`` (5%). Then set ``kp_multiplier`` to ``0.05`` (5%) if the controller is falling out of the deadband too often. .. code-block:: yaml @@ -184,7 +182,7 @@ set ``kp_multiplier`` to ``0.05`` (5%) if the controller is falling out of the d threshold_high: 0.5°C threshold_low: -1.0°C kp_multiplier: 0.0 # proportional gain turned off inside deadband - ki_multiplier: 0.05 # integral accumulates at only 5% of normal ki + ki_multiplier: 0.05 # integral accumulates at only 5% of normal ki kd_multiplier: 0.0 # derviative is turned off inside deadband deadband_output_averaging_samples: 15 # average the output over 15 samples within the deadband @@ -192,8 +190,8 @@ set ``kp_multiplier`` to ``0.05`` (5%) if the controller is falling out of the d Deadband Output Averaging Samples ********************************* -Since we expect the PID Controller to be at equilibrium while inside the deadband, we can -average the output over a longer range of samples, like 15 samples. This helps even further +Since we expect the PID Controller to be at equilibrium while inside the deadband, we can +average the output over a longer range of samples, like 15 samples. This helps even further with temperature and controller stability. .. _pid-autotune: @@ -249,7 +247,7 @@ is automatically calculated. To do this, it needs to observe at least 3 oscillat device can reach. For example if the temperature of a room is to be controlled, the setpoint needs to be above the ambient temperature. If the ambient temperature is 20°C, the setpoint of the climate device should be set to at least ~24°C so that an oscillation can be induced. - + Also take care of external influences, like for example when room temperature is severely affected by outdoor weather like sun, if it starts to warm up the room in parallel with the heating autotune will likely fail or give false results. @@ -273,10 +271,10 @@ is automatically calculated. To do this, it needs to observe at least 3 oscillat .. note:: In the output above, the autotuner is driving the heating output at 100% and trying to reach 24.25 °C. - + This will continue for some time until data for 3 phases (6 crossings of the setpoint; or a bit more, depending on the data quality) have been acquired. - + The autotune algorithm may take a long time to complete, it depends on the time needed to reproduce the heating up and cooling down oscillations the required number of times. @@ -298,7 +296,7 @@ is automatically calculated. To do this, it needs to observe at least 3 oscillat As soon as the the autotune procedure finishes, the climate starts to work with the calculated parameters so that expected operation can be immediately verified. - + If satisfied, copy the values in ``control_parameters`` into your configuration: .. code-block:: yaml @@ -349,7 +347,7 @@ Configuration variables: Defaults to ``-1.0``. The ``positive_output`` and ``negative_output`` parameters can be used to compensate the heating or the -cooling process during the autotune, in the cases when they are not changing the temperature at the +cooling process during the autotune, in the cases when they are not changing the temperature at the same rate, resulting in a not symmetrical oscillation. The autotune result will print a message when it's recommended to repeat the entire procedure with such parameters configured. @@ -435,7 +433,7 @@ See Also - Åström, K. J. and T. Hägglund (1984a), 'Automatic tuning of simple regulators', Proceedings of IFAC 9th World Congress, Budapest, 1867-1872 - :doc:`/components/climate/index` -- :doc:`/components/output/sigma_delta` +- :doc:`/components/output/sigma_delta_output` - :doc:`/components/output/slow_pwm` - `Principles of PID `__ - :apiref:`pid/pid_climate.h` diff --git a/components/cover/custom.rst b/components/cover/custom.rst index 305e1a5f9f4..dcd4a164380 100644 --- a/components/cover/custom.rst +++ b/components/cover/custom.rst @@ -30,6 +30,7 @@ two methods: traits.set_is_assumed_state(false); traits.set_supports_position(true); traits.set_supports_tilt(false); + traits.set_supports_stop(true); return traits; } void control(const CoverCall &call) override { diff --git a/components/deep_sleep.rst b/components/deep_sleep.rst index 3eb6b2d6102..c9914a96a89 100644 --- a/components/deep_sleep.rst +++ b/components/deep_sleep.rst @@ -32,7 +32,7 @@ even Over The Air updates. .. note:: - ESP8266 that have an onboard USB chip (e.g. D1 mini) one the chips' control lines is connected to the RST pin. This enables the flasher can reboot the ESP when required. This may interfere with deep sleep on some devices and prevent the ESP from waking when it's powered through its USB connector. Powering the ESP from a separate 3.3V source connected to the 3.3V pin and GND will solve this issue. In these cases using a USB to TTL adapter will allow you to log ESP activity. + Some ESP8266s have an onboard USB chip (e.g. D1 mini) on the chips' control line that is connected to the RST pin. This enables the flasher to reboot the ESP when required. This may interfere with deep sleep on some devices and prevent the ESP from waking when it's powered through its USB connector. Powering the ESP from a separate 3.3V source connected to the 3.3V pin and GND will solve this issue. In these cases, using a USB to TTL adapter will allow you to log ESP activity. Configuration variables: ------------------------ diff --git a/components/dfplayer.rst b/components/dfplayer.rst index 9bc19771e68..9b2f5e65501 100644 --- a/components/dfplayer.rst +++ b/components/dfplayer.rst @@ -111,6 +111,39 @@ Configuration options: - **loop** (*Optional*, boolean, :ref:`templatable `): Repeats playing the same track. Defaults to ``false``. +``dfplayer.play_mp3`` Action +---------------------------- + +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, +``0001hello.mp3``, but must always be referenced by number only in yaml. + +.. code-block:: bash + + /mp3 + /0001hello.mp3 + /0002.mp3 + /0003_thisistheway.mp3 + .. + +.. code-block:: yaml + + on_...: + then: + - dfplayer.play_mp3: + file: 1 + # Shorthand + - dfplayer.play_mp3: 1 + +Configuration options: + +- **file** (**Required**, int, :ref:`templatable `): The file number + inside the ``mp3`` folder to play. + + ``dfplayer.play_folder`` Action ------------------------------- diff --git a/components/display/ili9xxx.rst b/components/display/ili9xxx.rst index 030e287cd8e..b34c1129f77 100644 --- a/components/display/ili9xxx.rst +++ b/components/display/ili9xxx.rst @@ -33,7 +33,6 @@ beyond the typical SPI connections, it is better suited for use with the ESP32. display: - platform: ili9xxx model: ili9341 - cs_pin: 14 dc_pin: 27 reset_pin: 33 lambda: |- @@ -45,10 +44,11 @@ Configuration variables: - **model** (**Required**): The model of the display. Options are: - - ``M5STACK``, ``TFT 2.4``, ``TFT 2.4R`` + - ``M5STACK``, ``TFT 2.4``, ``TFT 2.4R``, ``S3BOX``, ``S3BOX_LITE`` - ``ILI9341``, ``ILI9342``, ``ILI9481``, ``ILI9486``, ``ILI9488``, ``ST7796`` -- **cs_pin** (*Optional*, :ref:`Pin Schema `): The CS pin. +.. note:: According to its documentation, the ESP32 S3 Box Lite has an ST7789V display driver. We've found, however, that it works with the ILIxxxx component here, instead. This could change in the future. + - **dc_pin** (**Required**, :ref:`Pin Schema `): The DC pin. - **reset_pin** (*Optional*, :ref:`Pin Schema `): The RESET pin. - **rotation** (*Optional*): Set the rotation of the display. Everything drawn in the ``lambda:`` will be rotated @@ -66,6 +66,7 @@ Configuration variables: - ``GRAYSCALE`` - ``IMAGE_ADAPTIVE`` - **color_palette_images** (*Optional*): A list of image files that will be used to generate the color pallet for the display. This should only be used in conjunction with ``-color_palette: IMAGE_ADAPTIVE`` above. The images will be analysed at compile time and a custom color pallet will be created based on the most commonly occuring colors. A typical setting would be a sample image that represented the fully populated display. This can significantly improve the quality of displayed images. Note that these images are not stored on the ESP device, just the 256byte color pallet created from them. +- **dimensions** (*Optional*): Dimensions of the screen with WIDTHxHEIGHT. Usually not needed since ``model:`` has good defaults. Configuration examples ********************** @@ -140,7 +141,6 @@ To configure an image adaptive color pallet to show greater than 8 bit color dep display: - platform: ili9xxx model: ili9341 - cs_pin: 5 dc_pin: 4 reset_pin: 22 rotation: 90 diff --git a/components/display/index.rst b/components/display/index.rst index b33c6859865..4b2883fc8c6 100644 --- a/components/display/index.rst +++ b/components/display/index.rst @@ -660,22 +660,35 @@ Use this component to store graphical images on the device, you can then draw th id: my_image resize: 100x100 +.. code-block:: yaml + + image: + - file: mdi:alert-outline + id: alert + resize: 80x80 + Configuration variables: -- **file** (**Required**, string): The path (relative to where the .yaml file is) of the image file. +- **file** (**Required**, string): + + - **Local files**: The path (relative to where the .yaml file is) of the image file. + - **Material Design Icons**: Specify the `Material Design Icon `_ id in the format ``mdi:icon-name``, and that icon will automatically be downloaded and added to the configuration. - **id** (**Required**, :ref:`config-id`): The ID with which you will be able to reference the image later in your display code. - **resize** (*Optional*, string): If set, this will resize the image to fit inside the given dimensions ``WIDTHxHEIGHT`` and preserve the aspect ratio. -- **type** (*Optional*): Specifies how to encode image internally. Defaults to ``BINARY``. +- **type** (*Optional*): Specifies how to encode image internally. Defaults to ``BINARY`` for local images and ``TRANSPARENT_BINARY`` for MDIs. - ``BINARY``: Two colors, suitable for 1 color displays or 2 color image in color displays. Uses 1 bit per pixel, 8 pixels per byte. - - ``GRAYSCALE``: Full scale grey. Uses 8 bits per pixel, 1 pixel per byte. - - ``RGB24``: Full RGB color stored. Uses 3 bytes per pixel. - - ``RGB565``: Lossy RGB color stored. Uses 2 bytes per pixel. - ``TRANSPARENT_BINARY``: One color, any pixel that is fully transparent will not be drawn, and any other pixel will be the on color. Uses 1 bit per pixel, 8 pixels per byte. + - ``GRAYSCALE``: Full scale grey. Uses 8 bits per pixel, 1 pixel per byte. + - ``RGB565``: Lossy RGB color stored. Uses 2 bytes per pixel. + - ``RGB24``: Full RGB color stored. Uses 3 bytes per pixel. + - ``RGBA``: Full RGB color stored. Uses 4 bytes per pixel. Any pixel with an alpha value < 127 will not be drawn. + +- **use_transparency** (*Optional*): If set the alpha channel of the input image will be taken into account, and pixels with alpha < 127 will not be drawn. For image types without explicit alpha channel, the color (0, 0, 1) (very dark blue) will be mapped to black, to be able to store transparency information within the image. Explicitly transparent types (``TRANSPARENT_BINARY`` and ``RGBA``) default to ``True`` and cannot be set to ``False``; other types default to ``False``. - **dither** (*Optional*): Specifies which dither method used to process the image, only used in GRAYSCALE and BINARY type image. Defaults to ``NONE``. You can read more about it `here `__ and `here `__. @@ -687,6 +700,9 @@ Configuration variables: To use images you will need to have the python ``pillow`` package installed. If you're running this as a Home Assistant add-on or with the official ESPHome docker image, it should already be installed. Otherwise you need to install it using ``pip install pillow``. + Additionally, if you want to use SVG images (including MDI images), you will additionally need to have the python ``cairosvg`` package installed. + If you're running this as a Home Assistant add-on or with the official ESPHome docker image, it should also already be + installed. Otherwise you need to install it using ``pip install cairosvg``. And then later in code: @@ -699,6 +715,25 @@ And then later in code: // Draw the image my_image at position [x=0,y=0] it.image(0, 0, id(my_image)); +By default, ESPHome will *align* the image at the top left. That means if you enter the coordinates +``[0,10]`` for your image, the top left of the image will be at ``[0,10]``. If you want to draw some +image at the right side of the display, it is however sometimes useful to choose a different **image alignment**. +When you enter ``[0,10]`` you're really telling ESPHome that it should position the **anchor point** of the image +at ``[0,10]``. When using a different alignment, like ``TOP_RIGHT``, the image will be positioned left of the anchor +pointed, so that, as the name implies, the anchor point is a the *top right* corner of the image. + +.. code-block:: yaml + + display: + - platform: ... + # ... + lambda: |- + // Aligned on left by default + it.image(0, 0, id(my_image)); + + // Aligned on right edge + it.image(it.get_width(), 0, id(my_image), ImageAlign::TOP_RIGHT); + For binary images the ``image`` method accepts two additional color parameters which can be supplied to modify the color used to represent the on and off bits respectively. e.g. @@ -712,6 +747,9 @@ be supplied to modify the color used to represent the on and off bits respective // with front color red and back color blue it.image(0, 0, id(my_image), id(red), id(blue)); + // Aligned on right edge + it.image(it.get_width(), 0, id(my_image), ImageAlign::TOP_RIGHT, id(red), id(blue)); + You can also use this to invert images in two colors display, use ``COLOR_OFF`` then ``COLOR_ON`` as the additional parameters. @@ -744,6 +782,8 @@ This can be combined with all Lambdas: // Draw the animation my_animation at position [x=0,y=0] it.image(0, 0, id(my_animation), COLOR_ON, COLOR_OFF); +Additionally, you can use the ``animation.next_frame``, ``animation.prev_frame`` or ``animation.set_frame`` actions. + .. note:: To draw the next animation independent of Display draw cycle use an interval: @@ -753,8 +793,7 @@ This can be combined with all Lambdas: interval: - interval: 5s then: - lambda: |- - id(my_animation).next_frame(); + animation.next_frame: my_animation Configuration variables: @@ -769,9 +808,35 @@ Configuration variables: - ``BINARY``: Two colors, suitable for 1 color displays or 2 color image in color displays. Uses 1 bit per pixel, 8 pixels per byte. + - ``TRANSPARENT_BINARY``: One color, any pixel that is fully transparent will not be drawn, and any other pixel + will be the on color. Uses 1 bit per pixel, 8 pixels per byte. - ``GRAYSCALE``: Full scale grey. Uses 8 bits per pixel, 1 pixel per byte. - - ``RGB24``: Full RGB color stored. Uses 3 bytes per pixel. - ``RGB565``: Lossy RGB color stored. Uses 2 bytes per pixel. + - ``RGB24``: Full RGB color stored. Uses 3 bytes per pixel. + - ``RGBA``: Full RGB color stored. Uses 4 bytes per pixel. Any pixel with an alpha value < 127 will not be drawn. + +- **use_transparency** (*Optional*): If set the alpha channel of the input image will be taken into account, and pixels with alpha < 127 will not be drawn. For image types without explicit alpha channel, the color (0, 0, 1) (very dark blue) will be mapped to black, to be able to store transparency information within the image. Explicitly transparent types (``TRANSPARENT_BINARY`` and ``RGBA``) default to ``True`` and cannot be set to ``False``; other types default to ``False``. +- **loop** (*Optional*): If you want to loop over a subset of your animation (e.g. a fire animation where the fire "starts", then "burns" and "dies") you can specify some frames to loop over. + + - **start_frame** (*Optional*, int): The frame to loop back to when ``end_frame`` is reached. Defaults to the first frame in the animation. + - **end_frame** (*Optional*, int): The last frame to show in the loop; when this frame is reached it will loop back to ``start_frame``. Defaults to the last frame in the animation. + - **repeat** (*Optional*, int): Specifies how many times the loop will run. When the count is reached, the animation will continue with the next frame after ``end_frame``, or restart from the beginning if ``end_frame`` was the last frame. Defaults to "loop forever". + +Actions: +^^^^^^^^ + +- **animation.next_frame**: Moves the animation to the next frame. This is equivalent to the ``id(my_animation).next_frame();`` lambda call. + + - **id** (**Required**, :ref:`config-id`): The ID of the animation to animate. + +- **animation.prev_frame**: Moves the animation to the previous frame. This is equivalent to the ``id(my_animation).prev_frame();`` lambda call. + + - **id** (**Required**, :ref:`config-id`): The ID of the animation to animate. + +- **animation.set_frame**: Moves the animation to a specific frame. This is equivalent to the ``id(my_animation).set_frame(frame);`` lambda call. + + - **id** (**Required**, :ref:`config-id`): The ID of the animation to animate. + - **frame** (**Required**, int): The frame index to show next. .. _display-pages: diff --git a/components/display/st7789v.rst b/components/display/st7789v.rst index b640fc2a852..c8594029328 100644 --- a/components/display/st7789v.rst +++ b/components/display/st7789v.rst @@ -70,6 +70,7 @@ Configuration variables: - ``TTGO TDisplay 135x240`` - ``Adafruit Funhouse 240x240`` - ``Adafruit RR 280x240`` (round-rectangular display -- some pixels are "deleted" from corners to form rounded shape) + - ``Adafruit S2 TFT FEATHER 240X135`` (requires ``power_supply`` be specified, see below) - ``Custom`` (see details below) - **cs_pin** (*Optional*, :ref:`Pin Schema `): The CS pin. @@ -86,6 +87,10 @@ Configuration variables: - **eightbitcolor** (*Optional*, boolean): Limits the supported color depth to eight bits. May be useful on memory-constrained devices. - **backlight_pin** (*Optional*, :ref:`Pin Schema `): The display's backlight pin. +- **power_supply** (*Optional*, :ref:`config-id`): The :doc:`power supply ` to connect to + this display. The power supply will be turned on before attempting to initialize the display. When ``model`` is set + to "Adafruit S2 TFT FEATHER 240X135" this option is required as there are variations of this board sold with differing + pin assignments. - **lambda** (*Optional*, :ref:`lambda `): The lambda to use for rendering the content on the display. See :ref:`display-engine` for more information. - **update_interval** (*Optional*, :ref:`config-time`): The interval to re-draw the screen. Defaults to ``5s``. @@ -271,5 +276,6 @@ See Also -------- - :doc:`index` +- :doc:`Power Supply Component ` - :apiref:`st7789v_base/st7789v_base.h` - :ghedit:`Edit` diff --git a/components/display/waveshare_epaper.rst b/components/display/waveshare_epaper.rst index 6eeb9d23029..664bc544df3 100644 --- a/components/display/waveshare_epaper.rst +++ b/components/display/waveshare_epaper.rst @@ -91,6 +91,7 @@ Configuration variables: - ``4.20in`` - ``4.20in-bV2`` - B/W rendering only - ``5.83in`` + - ``5.83inv2`` - ``7.50in`` - ``7.50in-bV2`` - also supports v3, B/W rendering only - ``7.50in-bc`` - display with version sticker '(C)' on the back, B/W rendering only diff --git a/components/esp32_ble.rst b/components/esp32_ble.rst index 07def025de1..325ce59f03d 100644 --- a/components/esp32_ble.rst +++ b/components/esp32_ble.rst @@ -13,9 +13,18 @@ can run. # Example configuration esp32_ble: + io_capability: keyboard_only +Configuration variables: +------------------------ -No configuration variables. +- **io_capability** (*Optional*, enum): The IO capability of this ESP32, used for securely connecting to other BLE devices. Defaults to ``none``. + + - ``none`` - No IO capability (Connections that require PIN code authentication will fail) + - ``keyboard_only`` - Only a keyboard to enter PIN codes (or a fixed PIN code) + - ``display_only`` - Only a display to show PIN codes + - ``keyboard_display`` - A keyboard and a display + - ``display_yes_no`` - A display to show PIN codes and buttons to confirm or deny the connection See Also -------- diff --git a/components/esp32_ble_tracker.rst b/components/esp32_ble_tracker.rst index 46725292c95..f1b59149dfd 100644 --- a/components/esp32_ble_tracker.rst +++ b/components/esp32_ble_tracker.rst @@ -108,7 +108,9 @@ This automation will be triggered when a Bluetooth advertising is received. A va esp32_ble_tracker: on_ble_advertise: - - mac_address: 11:22:33:44:55:66 + - mac_address: + - 11:11:11:11:11:11 + - 22:22:22:22:22:22 then: - lambda: |- ESP_LOGD("ble_adv", "New BLE device"); @@ -129,7 +131,7 @@ This automation will be triggered when a Bluetooth advertising is received. A va Configuration variables: -- **mac_address** (*Optional*, MAC Address): The MAC address to filter for this automation. +- **mac_address** (*Optional*, list of MAC Address): The MAC address to filter for this automation. - See :ref:`Automation `. .. _esp32_ble_tracker-on_ble_manufacturer_data_advertise: diff --git a/components/fan/binary.rst b/components/fan/binary.rst index 78e967d091a..eefad56e1b7 100644 --- a/components/fan/binary.rst +++ b/components/fan/binary.rst @@ -14,10 +14,18 @@ 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: my_output_1 + output: fan_output name: "Living Room Fan" + + + Configuration variables: ------------------------ diff --git a/components/i2s_audio.rst b/components/i2s_audio.rst index f7d59ea7abb..3eb07a8f69f 100644 --- a/components/i2s_audio.rst +++ b/components/i2s_audio.rst @@ -1,3 +1,5 @@ +.. _i2s_audio: + I²S Audio Component =================== @@ -18,12 +20,15 @@ This component only works on ESP32 based chips. Configuration variables: ------------------------ -- **i2s_lrclk_pin** (**Required**, :ref:`Pin Schema `): The GPIO pin to use for the I²S LRCLK (Word Select or Left/Right Clock) signal. -- **i2s_bclk_pin** (**Required**, :ref:`Pin Schema `): The GPIO pin to use for the I²S BCLK (Bit Clock) signal. +- **i2s_lrclk_pin** (**Required**, :ref:`config-pin`): The GPIO pin to use for the I²S ``LRCLK`` *(Left/Right Clock)* signal, also referred to as ``WS`` *(Word Select)* or ``FS`` *(Frame Sync)*. +- **i2s_bclk_pin** (*Optional*, :ref:`config-pin`): The GPIO pin to use for the I²S ``BCLK`` *(Bit Clock)* signal, also referred to as ``SCK`` *(Serial Clock)*. +- **i2s_mclk_pin** (*Optional*, :ref:`config-pin`): The GPIO pin to use for the I²S ``MCLK`` *(Master Clock)* signal. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID for this I²S bus if you need multiple. See also -------- - :doc:`microphone/i2s_audio` - :doc:`media_player/i2s_audio` +- :doc:`speaker/i2s_audio` - :ghedit:`Edit` diff --git a/components/images/max6956.jpg b/components/images/max6956.jpg new file mode 100644 index 00000000000..81bde116a2b Binary files /dev/null and b/components/images/max6956.jpg differ diff --git a/components/images/vbus_serial_optocoupler.png b/components/images/vbus_serial_optocoupler.png new file mode 100644 index 00000000000..4ebfafed902 Binary files /dev/null and b/components/images/vbus_serial_optocoupler.png differ diff --git a/components/index.rst b/components/index.rst index 737a782af3c..d26885a1ac6 100644 --- a/components/index.rst +++ b/components/index.rst @@ -24,5 +24,7 @@ Components display_menu/index media_player/index microphone/index + speaker/index time/index + alarm_control_panel/index * diff --git a/components/key_collector.rst b/components/key_collector.rst index ff9db7e3d10..552522b5bfb 100644 --- a/components/key_collector.rst +++ b/components/key_collector.rst @@ -83,6 +83,10 @@ Automations: if the timeout happens. The current sequence of pressed keys is placed in a ``vector`` variable ``x`` and ``start`` holds the start key that activated this sequence or else ``0``. +Lambda: +------- + +- **send_key(uint8_t key)**: Send a key to the collector directly. See Also -------- diff --git a/components/light/esp32_rmt_led_strip.rst b/components/light/esp32_rmt_led_strip.rst new file mode 100644 index 00000000000..03e192acf53 --- /dev/null +++ b/components/light/esp32_rmt_led_strip.rst @@ -0,0 +1,69 @@ +ESP32 RMT LED Strip +=================== + +.. seo:: + :description: Instructions for setting up addressable lights like NEOPIXEL on an ESP32 using the RMT peripheral. + :image: color_lens.svg + +This is a component using the ESP32 RMT peripheral to drive most addressable LED strips. + +.. code-block:: yaml + + light: + - platform: esp32_rmt_led_strip + rgb_order: GRB + pin: GPIO13 + num_leds: 30 + rmt_channel: 0 + chipset: ws2812 + name: "My Light" + +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`` + +- **chipset** (**Required**, enum): The chipset to apply known timings from. Not used if specifying the timings manually, see below. + - ``WS2812`` + - ``SK6812`` + - ``APA106`` + - ``SM16703`` + +- **rgb_order** (**Required**, string): The RGB order of the strip. + - ``RGB`` + - ``RBG`` + - ``GRB`` + - ``GBR`` + - ``BGR`` + - ``BRG`` + +- **is_rgbw** (*Optional*, boolean): Set to ``true`` if the strip is RGBW. Defaults to ``false``. +- **max_refresh_rate** (*Optional*, :ref:`config-time`): + A time interval used to limit the number of commands a light can handle per second. For example + 16ms will limit the light to a refresh rate of about 60Hz. Defaults to sending commands as quickly as + changes are made to the lights. + +Manual Timings +************** + +These can be used if you know the timings and your chipset is not set above. If you have a new specific chipset, +please consider adding support to the codebase and add it to the list above. + +- **bit0_high** (*Optional*, :ref:`config-time`): The time to hold the data line high for a ``0`` bit. +- **bit0_low** (*Optional*, :ref:`config-time`): The time to hold the data line low for a ``0`` bit. +- **bit1_high** (*Optional*, :ref:`config-time`): The time to hold the data line high for a ``1`` bit. +- **bit1_low** (*Optional*, :ref:`config-time`): The time to hold the data line low for a ``1`` bit. + +See Also +-------- + +- :doc:`/components/light/index` +- :doc:`/components/power_supply` +- :apiref:`esp32_rmt_led_strip/esp32_rmt_led_strip.h` +- :ghedit:`Edit` diff --git a/components/light/fastled.rst b/components/light/fastled.rst index 9cf7cb48210..5cceb0992c6 100644 --- a/components/light/fastled.rst +++ b/components/light/fastled.rst @@ -20,6 +20,12 @@ FastLED Light - https://github.com/FastLED/FastLED/issues/1322 - https://github.com/FastLED/FastLED/issues/1264 +.. warning:: + + FastLED does **not** work with ESP-IDF. + + For addressable lights, you can use :doc:`esp32_rmt_led_strip`. + .. _fastled-clockless: Clockless diff --git a/components/light/index.rst b/components/light/index.rst index 7c71549c62d..80c52ea9c18 100644 --- a/components/light/index.rst +++ b/components/light/index.rst @@ -486,6 +486,8 @@ This effect makes a pulsating light. The period can be defined by ``update_inter name: "Fast Pulse" transition_length: 0.5s update_interval: 0.5s + min_brightness: 0% + max_brightness: 100% - pulse: name: "Slow Pulse" # transition_length: 1s # defaults to 1s @@ -496,6 +498,8 @@ Configuration variables: - **name** (*Optional*, string): The name of the effect. Defaults to ``Pulse``. - **transition_length** (*Optional*, :ref:`config-time`): The duration of each transition. Defaults to ``1s``. - **update_interval** (*Optional*, :ref:`config-time`): The interval when the new transition is started. Defaults to ``1s``. +- **min_brightness** (*Optional*, percentage): The minimum brightness value. Defaults to ``0%`` +- **max_brightness** (*Optional*, percentage): The maximum brightness value. Defaults to ``100%`` Random Effect diff --git a/components/light/neopixelbus.rst b/components/light/neopixelbus.rst index cc5808a113a..3eed9eff0bf 100644 --- a/components/light/neopixelbus.rst +++ b/components/light/neopixelbus.rst @@ -5,6 +5,12 @@ NeoPixelBus Light :description: Instructions for setting up Neopixel addressable lights. :image: color_lens.svg +.. warning:: + + NeoPixelBus does **not** work with ESP-IDF. + + For addressable lights, you can use :doc:`esp32_rmt_led_strip`. + The ``neopixelbus`` light platform allows you to create RGB lights in ESPHome for an individually addressable lights like NeoPixel or WS2812. diff --git a/components/light/rp2040_pio_led_strip.rst b/components/light/rp2040_pio_led_strip.rst new file mode 100644 index 00000000000..7dc70a0ac16 --- /dev/null +++ b/components/light/rp2040_pio_led_strip.rst @@ -0,0 +1,63 @@ +RP2040 PIO LED Strip +==================== + +.. seo:: + :description: Instructions for setting up addressable lights like NEOPIXEL on an RP2040 using the PIO peripheral. + :image: color_lens.svg + +This is a component using the RP2040 PIO peripheral to drive most addressable LED strips. + +.. code-block:: yaml + + light: + - platform: rp2040_pio_led_strip + name: led_strip + id: led_strip + pin: GPIO13 + num_leds: 10 + pio: 0 + rgb_order: GRB + chipset: WS2812B + +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. +- **pio** (**Required**, int): The PIO peripheral to use. If using multiple strips, you can use up to 4 strips per PIO. Must be one of ``0`` or ``1``. + +- **chipset** (**Required**, enum): The chipset to apply known timings from. + - ``WS2812`` + - ``WS2812B`` + - ``SK6812`` + - ``SM16703`` + +- **rgb_order** (**Required**, string): The RGB order of the strip. + - ``RGB`` + - ``RBG`` + - ``GRB`` + - ``GBR`` + - ``BGR`` + - ``BRG`` + +- **is_rgbw** (*Optional*, boolean): Set to ``true`` if the strip is RGBW. Defaults to ``false``. + + + +Manual Timings +************** + +These can be used if you know the timings and your chipset is not set above. If you have a new specific chipset, +please consider adding support to the codebase and add it to the list above. + +- **bit0_high** (*Optional*, :ref:`config-time`): The time to hold the data line high for a ``0`` bit. +- **bit0_low** (*Optional*, :ref:`config-time`): The time to hold the data line low for a ``0`` bit. +- **bit1_high** (*Optional*, :ref:`config-time`): The time to hold the data line high for a ``1`` bit. +- **bit1_low** (*Optional*, :ref:`config-time`): The time to hold the data line low for a ``1`` bit. + +See Also +-------- + +- :doc:`/components/light/index` +- :doc:`/components/power_supply` +- :ghedit:`Edit` diff --git a/components/matrix_keypad.rst b/components/matrix_keypad.rst index c546e026174..caf143c245a 100644 --- a/components/matrix_keypad.rst +++ b/components/matrix_keypad.rst @@ -7,8 +7,8 @@ Matrix keypad :description: Matrix key input panel The ``matrix_keypad`` component allows you to integrate pads which -have the keys connected at the intersection points of the rows and columns -of a matrix. +have the keys connected at the intersection points of the rows and columns +of a matrix. .. figure:: ../images/matrix_keypad.jpg :align: center @@ -44,14 +44,14 @@ Configuration variables: - **columns** (**Required**, list): A list of :ref:`pins ` where the vertical matrix lines are connected, in order from left to right. These pins need to be input capable with pullups enabled. If there is no internal pullup, then an external one is required. -- **keys** (*Optional*, string): The keys present on the matrix, from top left to bottom right, +- **keys** (*Optional*, string): The keys present on the matrix, from top left to bottom right, row by row. Required for ``key_collector`` and ``binary_sensor`` (if using key selection). -- **has_diodes** (*Optional*, boolean): For pads where row pins are outputs, and the keys are +- **has_diodes** (*Optional*, boolean): For pads where row pins are outputs, and the keys are connected with diodes. Defaults to ``false``. -Binary Sensors --------------- +Binary Sensor +------------- Individual keys can be added independently to ESPHome as ``binary_sensor``: @@ -82,7 +82,7 @@ Either the ``row`` and ``col`` parameters, or the ``key`` parameter has to be pr .. note:: - Automatic handling of multiple keys (e.g. PIN code entry) is possible with the + Automatic handling of multiple keys (e.g. PIN code entry) is possible with the the :ref:`Key Collector ` component. See Also diff --git a/components/max6956.rst b/components/max6956.rst new file mode 100644 index 00000000000..968ee0dee7f --- /dev/null +++ b/components/max6956.rst @@ -0,0 +1,290 @@ +MAX6956 I/O Expander +==================== + +.. seo:: + :description: Instructions for setting up MAX6956 port expanders in ESPHome. + :image: max6956.jpg + :keywords: MAX6956 + +The MAX6956 component allows you to use MAX6956 I/O expanders +(`datasheet `__) in ESPHome. It uses :ref:`I²C Bus ` for communication. + +The ``max6956`` exists in 2 versions 20 or 28 ports, depending on the packaging. +Once configured, you can use any of the 20 or 28 pins for your projects. Within ESPHome they emulate a real internal GPIO pin +and can therefore be used with many of ESPHome's components such as the GPIO binary sensor or GPIO switch. Interrupt-on-change for inputs is not possible. + +Pins can also be individualy configured as led driver and used with Light components. Current value can be set globaly or for each pin, through 16 possible levels. Driving RGB +led requires 3 pins. + +Any option accepting a :ref:`Pin Schema ` can theoretically be used. + +Component/Hub +------------- + +.. figure:: images/max6956.jpg + :align: center + :width: 80.0% + + MAX6956 I/O Expander. + +The ``max6956`` is an :ref:`I²C Bus ` slave. Its address is configured using A0 and A1 hardware pins from 0x40 to 0x4F. + +.. code-block:: yaml + + max6956: + - id: max6956_1 + address: 0x40 + i2c_id: bus_a + + +Configuration variables: +************************ + +- **id** (**Required**, :ref:`config-id`): The id to use for this ``max6956`` component. +- **address** (*Optional*, int): The I²C address of the driver. + Defaults to ``0x40``. +- **i2c_id** (*Optional*): The I²C Bus ID + Defaults to ``false`` +- **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`` + + +Binary Sensor +------------- +``max6956`` pins can be use as binary sensor. Individual pullup are supported. + +.. 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 + binary_sensor: + - platform: gpio + name: "MaxIn Pin 4" + id: In_4 + pin: + max6956: max6956_1 + number: 4 + mode: + input: true + pullup: true + inverted: False + + +Switch +------------- +``max6956`` pins can be use as switch. + +.. 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 + switch: + - platform: gpio + name: "MaxIn Pin 8" + id: In_8 + pin: + max6956: max6956_1 + number: 8 + mode: + output: true + inverted: False + + +Led driver +------------- +``max6956`` can control a constant-current sink to drive leds, with 16 equal steps from 1.5mA to 24mA. + + +.. code-block:: yaml + + # Example configuration : pin as led driver, current globaly + i2c: + id: bus_a + sda: GPIO13 + scl: GPIO16 + + switch: + - platform: template + name: "Led" + id: MaxOut4 + optimistic: true + turn_on_action: + - output.turn_on: maxOut_pin4 + turn_off_action: + - output.turn_off: maxOut_pin4 + + number: + - platform: template + name: "Global brightness" + id: global_brightness + optimistic: true + min_value: 0 + max_value: 15 + initial_value: 1 + step: 1 + mode: slider + on_value: + - max6956.set_brightness_global: + id: max6956_1 + brightness_global: !lambda return x; + + max6956: + - id: max6956_1 + address: 0x40 + i2c_id: bus_a + brightness_mode: global + brightness_global: 5 + + #output to use + output: + - platform: max6956 + pin: 4 + id: maxOut_pin4 + + #led binded to output + light: + - platform: monochromatic + id: Light_1 + output: maxOut_pin4 + +.. code-block:: yaml + + # Example configuration : pin as led driver, current managed individualy (RBG led) + i2c: + id: bus_a + sda: GPIO13 + scl: GPIO16 + + max6956: + - id: max6956_1 + address: 0x40 + i2c_id: bus_a + brightness_mode: segment + + switch: + - platform: template + name: "Led Red" + id: MaxOut4 + optimistic: true + turn_on_action: + - output.turn_on: maxOut_pin4 + turn_off_action: + - output.turn_off: maxOut_pin4 + + - platform: template + name: "Led Green" + id: MaxOut5 + optimistic: true + turn_on_action: + - output.turn_on: maxOut_pin5 + turn_off_action: + - output.turn_off: maxOut_pin5 + + - platform: template + name: "Led Blue" + id: MaxOut6 + optimistic: true + turn_on_action: + - output.turn_on: maxOut_pin6 + turn_off_action: + - output.turn_off: maxOut_pin6 + + number: + - platform: template + name: "Number Red" + id: number_LedRed + optimistic: true + min_value: 0 + max_value: 100 + initial_value: 10 + step: 1 + mode: slider + on_value: + - output.set_level: + id: maxOut_pin4 + level: !lambda return x/100; + + - platform: template + name: "Number Green" + id: number_LedGreen + optimistic: true + min_value: 0 + max_value: 100 + initial_value: 10 + step: 1 + mode: slider + on_value: + - output.set_level: + id: maxOut_pin5 + level: !lambda return x/100; + + - platform: template + name: "Number Blue" + id: number_LedBlue + optimistic: true + min_value: 0 + max_value: 100 + initial_value: 10 + step: 1 + mode: slider + on_value: + - output.set_level: + id: maxOut_pin6 + level: !lambda return x/100; + output: + - platform: max6956 + pin: 4 + id: maxOut_pin4 + - platform: max6956 + pin: 5 + id: maxOut_pin5 + - platform: max6956 + pin: 6 + id: maxOut_pin6 + + light: + - platform: rgb + id: Light_1 + default_transition_length: 0.1s + gamma_correct: 1 + red: maxOut_pin4 + green: maxOut_pin5 + blue: maxOut_pin6 + + + + +See Also +-------- + +- :ref:`i2c` +- :doc:`switch/gpio` +- :doc:`/components/binary_sensor/index` +- :doc:`binary_sensor/gpio` +- :doc:`light/binary` +- :doc:`light/rgb` +- :apiref:`max6956/max6956.h` +- :ghedit:`Edit` diff --git a/components/mdns.rst b/components/mdns.rst index ed388627de9..6b14f6dca05 100644 --- a/components/mdns.rst +++ b/components/mdns.rst @@ -48,7 +48,7 @@ Configuration variables: - **disabled** (*Optional*, boolean): Set to true to disable mDNS usage. Defaults to false. - **services** (*Optional*, list): List of additional services to expose. - - **service** (*Required*, string): Name of extra service - - **protocol** (*Required*, string): Protocol of service (_udp or _tcp) - - **port** (*Optional*, int): Port number of extra service - - **txt** (*Optional*, mapping): Additional text records to add to service + - **service** (**Required**, string): Name of extra service. + - **protocol** (**Required**, string): Protocol of service (_udp or _tcp). + - **port** (*Optional*, int): Port number of extra service. + - **txt** (*Optional*, mapping): Additional text records to add to service. diff --git a/components/media_player/i2s_audio.rst b/components/media_player/i2s_audio.rst index 68e8a846e94..be6b880d253 100644 --- a/components/media_player/i2s_audio.rst +++ b/components/media_player/i2s_audio.rst @@ -1,4 +1,4 @@ -I2S Audio Media Player +I²S Audio Media Player ====================== .. seo:: @@ -31,8 +31,13 @@ Configuration variables: External DAC ************ -- **i2s_dout_pin** (**Required**, :ref:`Pin Schema `): The GPIO pin to use for the I²S DOUT (Data Out) signal. +- **i2s_dout_pin** (**Required**, :ref:`config-pin`): The GPIO pin to use for the I²S ``DOUT/SDOUT`` *(Data Out)* signal, also referred to as ``SD/SDATA`` *(Serial Data)* or ``DACDAT`` *(Digital to Analog Converter Data)*. +- **mute_pin** (*Optional*, :ref:`Pin Schema `): 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). + Can be ``msb`` or ``lsb``. Defaults to ``msb``. For best results, keep the wires as short as possible. diff --git a/components/microphone/i2s_audio.rst b/components/microphone/i2s_audio.rst index 255cb515ab1..2afb3f9c04f 100644 --- a/components/microphone/i2s_audio.rst +++ b/components/microphone/i2s_audio.rst @@ -13,15 +13,77 @@ The ``i2s_audio`` microphone platform allows you to receive audio via the the # Example configuration entry microphone: - platform: i2s_audio + id: external_mic + adc_type: external i2s_din_pin: GPIO23 + - platform: i2s_audio + id: adc_mic + adc_type: internal + adc_pin: GPIO35 + + Configuration variables: ------------------------ -- **i2s_din_pin** (**Required**, :ref:`Pin Schema `): The GPIO pin to use for the I²S DIN (Data In) signal. +- **adc_type** (**Required**, enum): + + - ``external``: Use an external ADC connected to the I²S bus. + - ``internal``: Use the internal ADC of the ESP32. Only supported on ESP32, no variant support. +- **channel** (*Optional*, enum): The channel of the microphone. One of ``left`` or ``right``. Defaults to ``right``. +- **bits_per_sample** (*Optional*, enum): The bit depth of the audio samples. Note that while set to ``32bit``, the samples + will be scaled down to 16bit before being forwarded. + One of ``16bit`` or ``32bit``. Defaults to ``16bit``. +- **i2s_audio_id** (*Optional*, :ref:`config-id`): The ID of the :ref:`I²S Audio ` you wish to use for this microphone. - All other options from :ref:`Microphone ` +External ADC +------------ + +- **i2s_din_pin** (**Required**, :ref:`Pin Schema `): The GPIO pin to use for the I²S ``DIN/SDIN`` *(Data In)* signal, also referred to as ``SD/SDATA`` *(Serial Data)* or ``ADCDAT`` *(Analog to Digital Converter Data)*. +- **pdm** (**Required**, boolean): Set this to ``true`` if your external ADC uses PDM (Pulse Density Modulation) instead of I²S. + + .. note:: + + PDM microphones are only supported on ESP32 and ESP32-S3. + +Internal ADC +------------ + + .. note:: + + Internal ADC microphones are only supported on a regular ESP32, not the variants. + +- **adc_pin** (**Required**, :ref:`Pin Schema `): The GPIO pin to use for the ADC input. + + +Known Devices +------------- + +M5Stack Atom Echo +***************** + +.. code-block:: yaml + + microphone: + - platform: i2s_audio + adc_type: external + i2s_din_pin: GPIO23 + pdm: true + +RaspiAudio Muse Luxe +******************** + +.. code-block:: yaml + + microphone: + - platform: i2s_audio + i2s_din_pin: GPIO35 + adc_type: external + pdm: false + + See also -------- diff --git a/components/output/gp8403.rst b/components/output/gp8403.rst new file mode 100644 index 00000000000..8638219ef1a --- /dev/null +++ b/components/output/gp8403.rst @@ -0,0 +1,53 @@ +GP8403 Component +================ + +.. seo:: + :description: Instructions for setting up GP8403 outputs in ESPHome. + :image: gp8403.svg + +The ``gp8403`` is a 2-channel DAC output module. It requires an :doc:`/components/i2c` to be setup. + +Component/Hub +------------- + +.. code-block:: yaml + + gp8403: + id: my_gp8403 + voltage: 5V + +Configuration variables: + +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- **voltage** (**Required**, voltage): The output voltage range of the DAC. Must be one of ``5V`` or ``10V``. + +Output +------ + +.. code-block:: yaml + + output: + - platform: gp8403 + id: my_gp8403_output_1 + gp8403_id: my_gp8403 + channel: 0 + - platform: gp8403 + id: my_gp8403_output_2 + gp8403_id: my_gp8403 + channel: 1 + +Configuration variables: + +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- **gp8403_id** (*Optional*, :ref:`config-id`): The ID of the GP8403 component. + Defaults to the only GP8403 component if there is only one. +- **channel** (**Required**, int): The channel of the GP8403 to use. Must be ``0`` or ``1``. +- All other options from :ref:`config-output`. + + +See Also +-------- + +- :doc:`/components/output/esp32_dac` +- :doc:`/components/output/index` +- :ghedit:`Edit` diff --git a/components/output/images/sigma-delta-example.png b/components/output/images/sigma-delta-example.png index c4cebdc2808..c055f992aa6 100644 Binary files a/components/output/images/sigma-delta-example.png and b/components/output/images/sigma-delta-example.png differ diff --git a/components/output/images/x9c.jpg b/components/output/images/x9c.jpg index b355f267997..331c5fbc8da 100644 Binary files a/components/output/images/x9c.jpg and b/components/output/images/x9c.jpg differ diff --git a/components/output/index.rst b/components/output/index.rst index 66f689fd6f7..7c00c46dc01 100644 --- a/components/output/index.rst +++ b/components/output/index.rst @@ -98,7 +98,7 @@ This action turns the output with the given ID off when executed. *************************** This action sets the float output to the given level when executed. Note: This only -works with floating point outputs like :doc:`/components/output/esp8266_pwm`, :doc:`/components/output/ledc`, :doc:`/components/output/sigma_delta`, :doc:`/components/output/slow_pwm`. +works with floating point outputs like :doc:`/components/output/esp8266_pwm`, :doc:`/components/output/ledc`, :doc:`/components/output/sigma_delta_output`, :doc:`/components/output/slow_pwm`. .. code-block:: yaml diff --git a/components/output/sigma_delta.rst b/components/output/sigma_delta_output.rst similarity index 100% rename from components/output/sigma_delta.rst rename to components/output/sigma_delta_output.rst diff --git a/components/output/slow_pwm.rst b/components/output/slow_pwm.rst index 9c129f4d99d..34d6c8aa76a 100644 --- a/components/output/slow_pwm.rst +++ b/components/output/slow_pwm.rst @@ -70,7 +70,7 @@ Example: .. note:: If the duty cycle is not constrained to a maximum value, the - :doc:`/components/output/sigma_delta` component offers faster updates and + :doc:`/components/output/sigma_delta_output` component offers faster updates and greater control over the switching frequency. This is better for loads that need some time to fully change between on and off, like eletric thermal actuator heads or fans. @@ -81,7 +81,7 @@ See Also - :doc:`/components/output/index` - :doc:`/components/output/esp8266_pwm` - :doc:`/components/output/ledc` -- :doc:`/components/output/sigma_delta` +- :doc:`/components/output/sigma_delta_output` - :doc:`/components/light/monochromatic` - :doc:`/components/fan/speed` - :doc:`/components/power_supply` diff --git a/components/output/sm2135.rst b/components/output/sm2135.rst index 8a0eca34a98..120cef50bc1 100644 --- a/components/output/sm2135.rst +++ b/components/output/sm2135.rst @@ -62,6 +62,12 @@ 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. + 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``. .. _sm2135-output: @@ -117,6 +123,10 @@ Configuration variables: The white LEDs are much brighter than the color LEDs. To get uniform brightness for both color and white you will need to limit the white led power. +.. warning:: + + Setting to high currents (either RGB, CW or both) could damage your bulb. + .. note:: This driver does not support enabling of both the color and the white channels diff --git a/components/pca6416a.rst b/components/pca6416a.rst new file mode 100644 index 00000000000..8b6038b281b --- /dev/null +++ b/components/pca6416a.rst @@ -0,0 +1,103 @@ +PCA6416A I/O Expander +===================== + +.. seo:: + :description: Instructions for setting up PCA6416A and PCAL6416A, digital port expanders in ESPHome. + :image: pca6416a.svg + +The PCA6416A component allows you to use **PCA6416A** or **PCAL6416A** I/O expanders in ESPHome. +It uses :ref:`I²C Bus ` for communication. + +Once configured, you can use any of the **16** pins for your projects. Within ESPHome they emulate a real internal +GPIO pin and can therefore be used with many of ESPHome's components such as the GPIO binary sensor or GPIO switch. + +.. note:: + + The 7 bit I²C device address ranges are: + + - PCA6416A: ``0x20`` to ``0x21`` + - PCAL6416A: ``0x20`` to ``0x21`` + + For the PCA6416A and PCAL6416A, the actual choice of the I²C device address depends on state of the address pin. + Please refer to the individual datasheets linked at the bottom of the page for further details to set the address. + + Up to two PCA6416A or PCAL6416A devices can reside on the same I²C bus. + + The PCA6416A and PCAL6416A provide 16 bits of GPIO's (pin numbers 0-15). + + Only the PCAL6416A supports pull-up resistors. + + Any option accepting a :ref:`Pin Schema ` can theoretically be used, but some more + complicated components that do communication through this I/O expander will not work. + +.. code-block:: yaml + + # Example configuration entry + pca6416a: + - id: 'pca6416a_device' + address: 0x20 + + # Individual outputs + switch: + - platform: gpio + name: "PCA6416A Pin #0" + pin: + pca6416a: pca6416a_device + # Use pin number 0 + number: 0 + # One of INPUT or OUTPUT + mode: + output: true + inverted: false + + +.. code-block:: yaml + + # Example configuration entry + pca6416a: + - id: 'pcal6416a_device' + address: 0x20 + + # Individual outputs + switch: + - platform: gpio + name: "PCAL6416A Pin #0" + pin: + pca6416a: pcal6416a_device + # Use pin number 0 + number: 0 + # One of INPUT, INPUT_PULLUP or OUTPUT + mode: + input: true + pullup: true + inverted: false + +Configuration variables: +************************ + +- **id** (**Required**, :ref:`config-id`): The id to use for this ``pca6416a`` component. +- **address** (*Optional*, int): The I²C address of the driver. + Defaults to ``0x20``. + + + +Pin configuration variables: +**************************** + +- **pca6416a** (**Required**, :ref:`config-id`): The id of the ``pca6416a`` component of the pin. +- **number** (**Required**, int): The pin number. +- **inverted** (*Optional*, boolean): If all read and written values + should be treated as inverted. Defaults to ``false``. +- **mode** (*Optional*, string): A pin mode to set for the pin at. One of ``INPUT`` or ``OUTPUT``. + + +See Also +-------- + +- :ref:`i2c` +- :doc:`switch/gpio` +- :doc:`binary_sensor/gpio` +- `PCA6416A datasheet `__ +- `PCAL6416A datasheet `__ +- :apiref:`pca6416a/pca6416a.h` +- :ghedit:`Edit` diff --git a/components/prometheus.rst b/components/prometheus.rst index 151a8c6cbe1..5df1dfa00ac 100644 --- a/components/prometheus.rst +++ b/components/prometheus.rst @@ -71,5 +71,9 @@ Set the ``id`` and ``name`` label values of the Prometheus metric for the sensor See Also -------- +- :doc:`/components/web_server` +- :ref:`api-rest` +- :doc:`/components/http_request` - :apiref:`prometheus/prometheus_handler.h` +- `Prometheus `__ - :ghedit:`Edit` diff --git a/components/remote_receiver.rst b/components/remote_receiver.rst index 1333615fedd..640a3170cbf 100644 --- a/components/remote_receiver.rst +++ b/components/remote_receiver.rst @@ -35,6 +35,7 @@ Configuration variables: - **canalsatld**: Decode and dump CanalSatLD infrared codes. - **coolix**: Decode and dump Coolix infrared codes. - **dish**: Decode and dump Dish infrared codes. + - **drayton**: Decode and dump Drayton Digistat RF codes. - **jvc**: Decode and dump JVC infrared codes. - **lg**: Decode and dump LG infrared codes. - **magiquest**: Decode and dump MagiQuest wand infrared codes. @@ -91,6 +92,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_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. - **on_jvc** (*Optional*, :ref:`Automation `): An automation to perform when a JVC remote code has been decoded. A variable ``x`` of type :apistruct:`remote_base::JVCData` is passed to the automation for use in lambdas. @@ -200,13 +204,13 @@ Remote code selection (exactly one of these has to be included): - **canalsat**: Trigger on a decoded CanalSat remote code with the given data. - **device** (**Required**, int): The device to trigger on, see dumper output for more info. - - **address** (**Optional**, int): The address (or subdevice) to trigger on, see dumper output for more info. Defaults to ``0`` + - **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. - **canalsatld**: Trigger on a decoded CanalSatLD remote code with the given data. - **device** (**Required**, int): The device to trigger on, see dumper output for more info. - - **address** (**Optional**, int): The address (or subdevice) to trigger on, see dumper output for more info. Defaults to ``0`` + - **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. @@ -219,6 +223,12 @@ 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. +- **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. + - **channel** (**Required**, int): The 7-bit switch/channel to listen for. + - **command** (**Required**, int): The 5-bit command to listen for. + - **jvc**: Trigger on a decoded JVC remote code with the given data. - **data** (**Required**, int): The JVC code to trigger on, see dumper output for more info. diff --git a/components/remote_transmitter.rst b/components/remote_transmitter.rst index 15bf0efe881..beb47db41a6 100644 --- a/components/remote_transmitter.rst +++ b/components/remote_transmitter.rst @@ -122,7 +122,7 @@ This :ref:`action ` sends a CanalSat infrared remote code to a re Configuration variables: - **device** (**Required**, int): The device to send to, see dumper output for more details. -- **address** (**Optional**, int): The address (or subdevice) to send to, see dumper output for more details. Defaults to ``0`` +- **address** (*Optional*, int): The address (or subdevice) to send to, see dumper output for more details. Defaults to ``0`` - **command** (**Required**, int): The command to send. - All other options from :ref:`remote_transmitter-transmit_action`. @@ -149,7 +149,7 @@ This :ref:`action ` sends a CanalSatLD infrared remote code to a Configuration variables: - **device** (**Required**, int): The device to send to, see dumper output for more details. -- **address** (**Optional**, int): The address (or subdevice) to send to, see dumper output for more details. Defaults to ``0`` +- **address** (*Optional*, int): The address (or subdevice) to send to, see dumper output for more details. Defaults to ``0`` - **command** (**Required**, int): The command to send. - All other options from :ref:`remote_transmitter-transmit_action`. @@ -192,6 +192,28 @@ Configuration variables: You can find a list of commands in the `LIRC project `__. +.. _remote_transmitter-transmit_drayton: + +``remote_transmitter.transmit_drayton`` Action +********************************************** + +This :ref:`action ` sends a Draton Digistat RF remote code to a remote transmitter. + +.. code-block:: yaml + + on_...: + - remote_transmitter.transmit_drayton: + address: '0x6180' + channel: '0x12' + command: '0x02' + +Configuration variables: + +- **address** (**Required**, int): The 16-bit ID to send, see dumper output for more info. +- **channel** (**Required**, int): The switch/channel to send, between 0 and 127 inclusive. +- **command** (**Required**, int): The command to send, between 0 and 63 inclusive. +- All other options from :ref:`remote_transmitter-transmit_action`. + .. _remote_transmitter-transmit_jvc: ``remote_transmitter.transmit_jvc`` Action @@ -261,7 +283,7 @@ This :ref:`action ` sends a 40-bit Midea code to a remote transmi on_...: - remote_transmitter.transmit_midea: code: [0xA2, 0x08, 0xFF, 0xFF, 0xFF] - + on_...: - remote_transmitter.transmit_midea: code: !lambda |- @@ -876,6 +898,10 @@ earlier, create a new template switch that sends the RF code when triggered: - remote_transmitter.transmit_rc_switch_raw: code: '100010000000000010111110' protocol: 2 + repeat: + times: 10 + wait_time: 0s + # Or for raw code switch: @@ -890,6 +916,15 @@ earlier, create a new template switch that sends the RF code when triggered: Recompile again, when you power up the device the next time you will see a new switch in the frontend. Click on it and you should see the remote signal being transmitted. Done! +.. note:: + + Some devices require that the transmitted code be repeated for the signal to be picked up + as valid. Also the interval between repetitions can be important. Check that the pace of + repetition logs are consistent between the remote controller and the transmitter node. + You can adjust the ``repeat:`` settings accordingly. + + + See Also -------- diff --git a/components/rtttl.rst b/components/rtttl.rst index ea66970b4f1..51f35978f43 100644 --- a/components/rtttl.rst +++ b/components/rtttl.rst @@ -55,7 +55,7 @@ Plays an rtttl tone. on_...: then: - - rtttl.play: 'MissionImp:d=16,o=6,b=95:32d,32d#,32d,32d#,32d,32d#,32d,32d#,32d,32d,32d#,32e,32f,32f#,32g,g,8p,g,8p,a#,p,c7,p,g,8p,g,8p,f,p,f#,p,g,8p,g,8p,a#,p,c7,p,g,8p,g,8p,f,p,f#,p,a#,g,2d,32p,a#,g,2c#,32p,a#,g,2c,a#5,8c,2p,32p,a#5,g5,2f#,32p,a#5,g5,2f,32p,a#5,g5,2e,d#,8d' + - rtttl.play: 'siren:d=8,o=5,b=100:d,e,d,e,d,e,d,e' Configuration options: @@ -101,15 +101,17 @@ This Condition returns true while playback is active. Common beeps ------------ -You can do your own beep patterns too! Here are a few I made so you can just use right away or tweak them to your -like: +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:: yaml - two short:d=4,o=5,b=100:16e6,16e6 + two_short:d=4,o=5,b=100:16e6,16e6 long:d=1,o=5,b=100:e6 siren:d=8,o=5,b=100:d,e,d,e,d,e,d,e scale_up:d=32,o=5,b=100:c,c#,d#,e,f#,g#,a#,b + star_wars:d=16,o=5,b=100:4e,4e,4e,8c,p,g,4e,8c,p,g,4e,4p,4b,4b,4b,8c6,p,g,4d#,8c,p,g,4e,8p + mission_imp:d=16,o=6,b=95:32d,32d#,32d,32d#,32d,32d#,32d,32d#,32d,32d,32d#,32e,32f,32f#,32g,g,8p,g,8p,a#,p,c7,p,g,8p,g,8p,f,p,f#,p,g,8p,g,8p,a#,p,c7,p,g,8p,g,8p,f,p,f#,p,a#,g,2d,32p,a#,g,2c#,32p,a#,g,2c,a#5,8c,2p,32p,a#5,g5,2f#,32p,a#5,g5,2f,32p,a#5,g5,2e,d#,8d + mario:d=4,o=5,b=100:16e6,16e6,32p,8e6,16c6,8e6,8g6,8p,8g,8p,8c6,16p,8g,16p,8e,16p,8a,8b,16a#,8a,16g.,16e6,16g6,8a6,16f6,8g6,8e6,16c6,16d6,8b,16p,8c6,16p,8g,16p,8e,16p,8a,8b,16a#,8a,16g.,16e6,16g6,8a6,16f6,8g6,8e6,16c6,16d6,8b,8p,16g6,16f#6,16f6,16d#6,16p,16e6,16p,16g#,16a,16c6,16p,16a,16c6,16d6,8p,16g6,16f#6,16f6,16d#6,16p,16e6,16p,16c7,16p,16c7,16c7,p,16g6,16f#6,16f6,16d#6,16p,16e6,16p,16g#,16a,16c6,16p,16a,16c6,16d6,8p,16d#6,8p,16d6,8p,16c6 Test setup @@ -120,7 +122,7 @@ E.g. for calling ``rtttl.play`` select the service ``esphome.test_esp8266_rtttl_ .. code-block:: yaml - song_str: "mario:d=4,o=5,b=100:16e6,16e6,32p,8e6,16c6,8e6,8g6,8p,8g,8p,8c6,16p,8g,16p,8e,16p,8a,8b,16a#,8a,16g.,16e6,16g6,8a6,16f6,8g6,8e6,16c6,16d6,8b,16p,8c6,16p,8g,16p,8e,16p,8a,8b,16a#,8a,16g.,16e6,16g6,8a6,16f6,8g6,8e6,16c6,16d6,8b,8p,16g6,16f#6,16f6,16d#6,16p,16e6,16p,16g#,16a,16c6,16p,16a,16c6,16d6,8p,16g6,16f#6,16f6,16d#6,16p,16e6,16p,16c7,16p,16c7,16c7,p,16g6,16f#6,16f6,16d#6,16p,16e6,16p,16g#,16a,16c6,16p,16a,16c6,16d6,8p,16d#6,8p,16d6,8p,16c6" + song_str: 'scale_up:d=32,o=5,b=100:c,c#,d#,e,f#,g#,a#,b' Sample code *********** diff --git a/components/sensor/ads1115.rst b/components/sensor/ads1115.rst index 09ef99c5446..cc1640bcce8 100644 --- a/components/sensor/ads1115.rst +++ b/components/sensor/ads1115.rst @@ -96,8 +96,8 @@ Configuration variables: - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - **resolution** (*Optional*, string): the resolution of this sensor. Defaults to ``16 bits``. - - **16 bits** - - **12 bits** + - ``16 bits`` + - ``12 bits`` Multiplexer and Gain @@ -105,10 +105,10 @@ Multiplexer and Gain .. note:: - As per (`datasheet `__, `Adafruit`_) Section 7.3 Note 2: + As per (`datasheet `__, `Adafruit`_) Section 7.3 Note 2: "No more than VDD + 0.3V must be applied to the analog inputs of the device." This means if you power the device with 3.3V, take care not to supply the 4 AIN pins with more than 3.6V. - + The ADS1115 has a multiplexer that can be configured to measure voltage between several pin configurations. These are: - ``A0_A1`` (between Pin 0 and Pin 1) @@ -128,11 +128,11 @@ Additionally, the ADS1115 has a Programmable Gain Amplifier (PGA) that can help - ``1.024`` (measures up to 1.024V) - ``0.512`` (measures up to 0.512V) - ``0.256`` (measures up to 0.256V) - + The ADS1115 can be used with defaults settings. When using an ADS1015, the resolution has to be specified and should be defined to ``12_BITS`` (or equivalent notations like ``12 BITS`` or ``12 bits``). - + See Also -------- diff --git a/components/sensor/ee895.rst b/components/sensor/ee895.rst index d56db15795c..dfb5f2b7dd3 100644 --- a/components/sensor/ee895.rst +++ b/components/sensor/ee895.rst @@ -36,19 +36,19 @@ The :ref:`I²C Bus ` is required to be set up in your configuration for thi Configuration variables: ------------------------ -- **temperature** (*Required*): The information for the Temperature sensor. +- **temperature** (**Required**): The information for the Temperature sensor. - **name** (**Required**, string): The name for the temperature sensor. - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - All other options from :ref:`Sensor `. -- **co2** (*Required*): The information for the CO₂ sensor. +- **co2** (**Required**): The information for the CO₂ sensor. - **name** (**Required**, string): The name for the CO₂eq sensor. - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - All other options from :ref:`Sensor `. -- **Pressure** (*Required*): The information for the Pressure sensor. +- **pressure** (**Required**): The information for the Pressure sensor. - **name** (**Required**, string): The name for the Pressure sensor. - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. diff --git a/components/sensor/growatt_solar.rst b/components/sensor/growatt_solar.rst index f6f5c8855bf..cd6bd18c992 100644 --- a/components/sensor/growatt_solar.rst +++ b/components/sensor/growatt_solar.rst @@ -22,13 +22,13 @@ to some pins on your board and the baud rate set to 9600. # Example configuration entry uart: - - id: uart1 + - id: gw_uart baud_rate: 9600 tx_pin: GPIO1 rx_pin: GPIO3 modbus: - uart_id: uart1 + uart_id: gw_uart flow_control_pin: GPIO4 sensor: diff --git a/components/sensor/havells_solar.rst b/components/sensor/havells_solar.rst index 9e6992007ea..5338e6f5ec3 100644 --- a/components/sensor/havells_solar.rst +++ b/components/sensor/havells_solar.rst @@ -24,14 +24,14 @@ to some pins on your board and the baud rate set to 9600. # Example configuration entry uart: - - id: uart1 + - id: modbus_uart baud_rate: 9600 tx_pin: GPIO1 rx_pin: GPIO3 modbus: - uart_id: uart1 + uart_id: modbus_uart flow_control_pin: GPIO4 sensor: diff --git a/components/sensor/hmc5883l.rst b/components/sensor/hmc5883l.rst index c2551acb0e9..1430b54f911 100644 --- a/components/sensor/hmc5883l.rst +++ b/components/sensor/hmc5883l.rst @@ -26,7 +26,7 @@ for this sensor to work. # Example configuration entry sensor: - platform: hmc5883l - address: 0x68 + address: 0x1E field_strength_x: name: "HMC5883L Field Strength X" field_strength_y: diff --git a/components/sensor/hyt271.rst b/components/sensor/hyt271.rst new file mode 100644 index 00000000000..658b66f830a --- /dev/null +++ b/components/sensor/hyt271.rst @@ -0,0 +1,49 @@ +HYT271 Temperature & Humidity Sensor +===================================================== + +.. seo:: + :description: Instructions for setting up HYT271 temperature and humidity sensors. + :image: hyt271.jpg + :keywords: HYT271 + +The HYT271 Temperature & Humidity sensors with ESPHome. +The :ref:`I²C Bus ` is required to be set up in your configuration for this sensor to work. + +Example sensors: + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: hyt271 + temperature: + name: "Living Room Temperature" + humidity: + name: "Living Room Humidity" + update_interval: 60s + +Configuration variables: +------------------------ + +- **temperature** (**Required**): The information for the temperature sensor. + + - **name** (**Required**, string): The name for the temperature sensor. + - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. + - All other options from :ref:`Sensor `. + +- **humidity** (**Required**): The information for the humidity sensor. + + - **name** (**Required**, string): The name for the humidity sensor. + - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. + - All other options from :ref:`Sensor `. + +- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. + + +See Also +-------- + +- :ref:`sensor-filters` +- :apiref:`hyt271/hyt271.h` +- `i2cdevlib `__ by `Jeff Rowberg `__ +- :ghedit:`Edit` diff --git a/components/sensor/images/EE895.png b/components/sensor/images/EE895.png index f1cecf047ce..e667a46bd9f 100644 Binary files a/components/sensor/images/EE895.png and b/components/sensor/images/EE895.png differ diff --git a/components/sensor/images/as7341-full.jpg b/components/sensor/images/as7341-full.jpg index 22aa8359098..68ab5b93ca8 100644 Binary files a/components/sensor/images/as7341-full.jpg and b/components/sensor/images/as7341-full.jpg differ diff --git a/components/sensor/images/hyt271.jpg b/components/sensor/images/hyt271.jpg new file mode 100644 index 00000000000..a0103530a7a Binary files /dev/null and b/components/sensor/images/hyt271.jpg differ diff --git a/components/sensor/images/ld2410.jpg b/components/sensor/images/ld2410.jpg index 5052b9110df..6884df9e922 100644 Binary files a/components/sensor/images/ld2410.jpg and b/components/sensor/images/ld2410.jpg differ diff --git a/components/sensor/images/mopeka_pro_check_lippert.jpg b/components/sensor/images/mopeka_pro_check_lippert.jpg index c795d34684a..34c95c7f7dc 100644 Binary files a/components/sensor/images/mopeka_pro_check_lippert.jpg and b/components/sensor/images/mopeka_pro_check_lippert.jpg differ diff --git a/components/sensor/images/sen21231.png b/components/sensor/images/sen21231.png index c78af266b86..d2727c66e5b 100644 Binary files a/components/sensor/images/sen21231.png and b/components/sensor/images/sen21231.png differ diff --git a/components/sensor/images/tmp1075.jpg b/components/sensor/images/tmp1075.jpg new file mode 100644 index 00000000000..f5e7a98c2bc Binary files /dev/null and b/components/sensor/images/tmp1075.jpg differ diff --git a/components/sensor/index.rst b/components/sensor/index.rst index 3b15ff77e93..3fb874c7e8b 100644 --- a/components/sensor/index.rst +++ b/components/sensor/index.rst @@ -415,7 +415,7 @@ Configuration variables: ``skip_initial`` **************** -A simple skip filter; `skip_initial: N` skips the first `N` sensor readings and passes on the +A simple skip filter; ``skip_initial: N`` skips the first ``N`` sensor readings and passes on the rest. This can be used when the sensor needs a few readings to 'warm up'. After the initial readings have been skipped, this filter does nothing. diff --git a/components/sensor/internal_temperature.rst b/components/sensor/internal_temperature.rst index 3949346f88b..2aca16fab42 100644 --- a/components/sensor/internal_temperature.rst +++ b/components/sensor/internal_temperature.rst @@ -12,7 +12,7 @@ temperature sensor of the ESP32 and RP2040 chip. .. note:: Some ESP32 variants return a large amount of invalid temperature - values. Invalid measurements are ignored by this component. + values, including 53.3°C which equates to a raw value of 128. Invalid measurements are ignored by this component. .. figure:: images/internal_temperature-ui.png :align: center diff --git a/components/sensor/kuntze.rst b/components/sensor/kuntze.rst index b4727c693df..6bd2372d7fd 100644 --- a/components/sensor/kuntze.rst +++ b/components/sensor/kuntze.rst @@ -5,7 +5,7 @@ Kuntze pool monitor :description: Instructions for setting up Kuntze pool monitor in ESPHome. :image: kuntze.jpg -The ``kuntze`` component allows you to integrate the Kuntze water measurement +The ``kuntze`` component allows you to integrate the Kuntze water measurement instrument in ESPHome. It uses :ref:`UART ` (ModBUS) for communication. Once configured you can use sensors as described below for your projects. @@ -19,25 +19,25 @@ Once configured you can use sensors as described below for your projects. Overview -------- -Kuntze devices have an RS485 (ModBUS RTU) communication port. Please see the +Kuntze devices have an RS485 (ModBUS RTU) communication port. Please see the Kuntze papers for the pinout of the RS485 connector on your unit. ModBUS line has to be terminated properly (with a ``120Ω`` resistor), and since this is likely your only unit connected to ESPHome, you should activate bus termination in the -Network menu (this component doesn't support multiple Kuntze devices on the same +Network menu (this component doesn't support multiple Kuntze devices on the same bus). ModBUS address should remain at factory default value. -The device communicates at ``19200`` baud ``8E1``. To connect to ESPHome, an RS485 -transceiver is needed. Choose a type which does not need a trigger to send and +The device communicates at ``19200`` baud ``8E1``. To connect to ESPHome, an RS485 +transceiver is needed. Choose a type which does not need a trigger to send and receive data, for example: .. figure:: ../../images/rs485.jpg -The controller connects to the UART of the MCU. For ESP32 GPIO `16` to `TXD` and `17` +The controller connects to the UART of the MCU. For ESP32 GPIO `16` to `TXD` and `17` to RXD are the default ones but any other pins can be used as well. 3.3V to VCC and GND to GND. .. warning:: - If you are using the :ref:`logger` make sure you are not using the same pins for it or otherwise disable the UART + If you are using the :ref:`logger` make sure you are not using the same pins for it or otherwise disable the UART logging with the ``baud_rate: 0`` option. Component @@ -66,14 +66,13 @@ A configured modbus component is optional. It will be automatically created. Configuration variables: -- **ph**: Measured pH value -- **temperature**: Measured temperature value -- **dis1**: Measured DIS 1 value -- **dis2**: Measured DIS 2 value -- **redox**: Measured Redox value -- **ec**: Measured EC value -- **oci**: Measured OCI value - +- **ph** (*Optional*): Measured pH value. +- **temperature** (*Optional*): Measured temperature value. +- **dis1** (*Optional*): Measured DIS 1 value. +- **dis2** (*Optional*): Measured DIS 2 value. +- **redox** (*Optional*): Measured Redox value. +- **ec** (*Optional*): Measured EC value. +- **oci** (*Optional*): Measured OCI value. All sensors are *Optional* and support all other options from :ref:`Sensor `. diff --git a/components/sensor/ld2410.rst b/components/sensor/ld2410.rst index dd07982399f..751388ca2ff 100644 --- a/components/sensor/ld2410.rst +++ b/components/sensor/ld2410.rst @@ -25,7 +25,6 @@ Use of hardware UART pins is highly recommended, in order to support the out-of- # Example configuration entry uart: - id: uart1 tx_pin: REPLACEME rx_pin: REPLACEME baud_rate: 256000 @@ -76,7 +75,7 @@ and binary sensors. 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). +- **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``. .. list-table:: Default values for gate threshold diff --git a/components/sensor/mhz19.rst b/components/sensor/mhz19.rst index 58ab84a26c6..62bc8258a8f 100644 --- a/components/sensor/mhz19.rst +++ b/components/sensor/mhz19.rst @@ -7,7 +7,7 @@ MH-Z19 CO_2 and Temperature Sensor :keywords: mh-z19 The ``mhz19`` sensor platform allows you to use MH-Z19 CO_2 and temperature sensors -(`refspace`_) with ESPHome. +(`Revspace`_) with ESPHome. The CO_2 measurement also works with the MH-Z16 and MH-Z14 sensors. .. figure:: images/mhz19-full.jpg @@ -16,7 +16,7 @@ The CO_2 measurement also works with the MH-Z16 and MH-Z14 sensors. MH-Z19 CO_2 and Temperature Sensor. -.. _refspace: https://revspace.nl/MHZ19 +.. _Revspace: https://revspace.nl/MHZ19 As the communication with the MH-Z19 is done using UART, you need to have an :ref:`UART bus ` in your configuration with the ``rx_pin`` connected to the TX pin of the diff --git a/components/sensor/mics_4514.rst b/components/sensor/mics_4514.rst index 731e89b1c26..1fb366c3a57 100644 --- a/components/sensor/mics_4514.rst +++ b/components/sensor/mics_4514.rst @@ -6,7 +6,7 @@ MiCS 4514 Gas Sensor :image: mics_4514.jpg :keywords: MiCS, 4514, MICS-4514 -This component exposes the different gas concentration sensors from the `MiCS-4514 `__. +This component exposes the different gas concentration sensors from the `MiCS-4514 `__. This is a differnet sensor than the MICS-4514 being sold on AliExpress. .. note:: diff --git a/components/sensor/mmc5063.rst b/components/sensor/mmc5603.rst similarity index 98% rename from components/sensor/mmc5063.rst rename to components/sensor/mmc5603.rst index 5b18557bad3..3e88922aaa3 100644 --- a/components/sensor/mmc5063.rst +++ b/components/sensor/mmc5603.rst @@ -25,7 +25,7 @@ for this sensor to work. # Example configuration entry sensor: - - platform: MMC5603 + - platform: mmc5603 address: 0x30 field_strength_x: name: "MMC5603 Field Strength X" diff --git a/components/sensor/mopeka_pro_check.rst b/components/sensor/mopeka_pro_check.rst index 0bf4f3601e4..accd95e9153 100644 --- a/components/sensor/mopeka_pro_check.rst +++ b/components/sensor/mopeka_pro_check.rst @@ -105,6 +105,9 @@ Currently supported Tank types are: - ``20LB_V`` - 20 LB vertical tank - ``30LB_V`` - 30 LB vertical tank - ``40LB_V`` - 40 LB vertical tank +- ``EUROPE_6KG`` - 6kg vertical tank +- ``EUROPE_11KG`` - 11kg vertical tank +- ``EUROPE_14KG`` - 14kg vertical tank - ``CUSTOM`` - Allows you to define your own full and empty points Setting Up Devices diff --git a/components/sensor/scd30.rst b/components/sensor/scd30.rst index c33f622ad09..4081d8a140d 100644 --- a/components/sensor/scd30.rst +++ b/components/sensor/scd30.rst @@ -6,7 +6,7 @@ SCD30 CO₂, Temperature and Relative Humidity Sensor :image: scd30.jpg The ``scd30`` sensor platform allows you to use your Sensirion SCD30 CO₂ -(`datasheet `__) sensors with ESPHome. +(`datasheet `__) sensors with ESPHome. The :ref:`I²C Bus ` is required to be set up in your configuration for this sensor to work. .. figure:: images/scd30.jpg diff --git a/components/sensor/sdp3x.rst b/components/sensor/sdp3x.rst index 4bbfd715920..8944c1b1b29 100644 --- a/components/sensor/sdp3x.rst +++ b/components/sensor/sdp3x.rst @@ -7,8 +7,8 @@ SDP3x / SDP800 Series Differential Pressure Sensor :keywords: SDP3x, SDP31, SDP32, SDP800 Series, SDP810, SDP810 The SDP3x Differential Pressure sensor allows you to use your SDP3x -(`datasheet `__, -`sparkfun `__) or SDP800 Series (`datasheet `__) +(`datasheet `__, +`sparkfun `__) or SDP800 Series (`datasheet `__) sensors with ESPHome. .. figure:: images/sdp31.jpg diff --git a/components/sensor/sht4x.rst b/components/sensor/sht4x.rst index c671f8a0140..4cb37c1b29c 100644 --- a/components/sensor/sht4x.rst +++ b/components/sensor/sht4x.rst @@ -6,7 +6,7 @@ SHT4X Temperature and Humidity Sensor :image: sht4x.jpg The ``sht4x`` sensor platform allows you to use your SHT4X temperature and humidity sensor -(`datasheet `__, `Adafruit`_) with ESPHome. +(`datasheet `__, `Adafruit`_) with ESPHome. The :ref:`I²C Bus ` is required to be set up in your configuration for this sensor to work. @@ -58,7 +58,7 @@ The heater can be enabled by setting ``heater_max_duty`` up to a maximum duty cy of ``5%`` (``0.05``). This runs the heater on a regular interval. While the heater is in operation the sensor disables measurements so no updates will be published. -See the (`datasheet `__) +See the (`datasheet `__) for more information about heater operation. See Also diff --git a/components/sensor/shtcx.rst b/components/sensor/shtcx.rst index e69b2595e25..a5fce79eb11 100644 --- a/components/sensor/shtcx.rst +++ b/components/sensor/shtcx.rst @@ -6,10 +6,10 @@ SHTCx Temperature+Humidity Sensors :image: shtc3.jpg The ``shtcx`` sensor platform Temperature+Humidity sensor allows you to use your Sensirion SHTC1 -(`datasheet `__, +(`datasheet `__, `Sensirion STHC1 `__) and the newer SHTC3 -(`datasheet `__, +(`datasheet `__, `SparkFun`_ ) sensors with ESPHome. The :ref:`I²C Bus ` is required to be set up in your configuration for this sensor to work. diff --git a/components/sensor/sps30.rst b/components/sensor/sps30.rst index f80081032d6..ac085be2c2c 100644 --- a/components/sensor/sps30.rst +++ b/components/sensor/sps30.rst @@ -6,7 +6,7 @@ SPS30 Particulate Matter Sensor :image: sps30.jpg The ``sps30`` sensor platform allows you to use your Sensirion SPS30 -(`datasheet `__) sensors with ESPHome. +(`datasheet `__) sensors with ESPHome. The :ref:`I²C Bus ` is required to be set up in your configuration for this sensor to work. This sensor supports both UART and I²C communication. However, at the moment only I²C communication is implemented. diff --git a/components/sensor/sts3x.rst b/components/sensor/sts3x.rst index 4797600590c..b3f1b84be35 100644 --- a/components/sensor/sts3x.rst +++ b/components/sensor/sts3x.rst @@ -6,7 +6,7 @@ STS3X Temperature Sensor :image: sts3x.jpg The ``sts3x`` sensor platform Temperature sensor allows you to use your Sensirion STS30-DIS, STS31-DIS or STS35-DIS -(`datasheet `__, +(`datasheet `__, `Sensirion STS3x `__) sensors with ESPHome. The :ref:`I²C Bus ` is required to be set up in your configuration for this sensor to work. diff --git a/components/sensor/template.rst b/components/sensor/template.rst index 01304dea718..8c971a06610 100644 --- a/components/sensor/template.rst +++ b/components/sensor/template.rst @@ -35,9 +35,8 @@ Configuration variables: - **name** (**Required**, string): The name of the sensor. - **lambda** (*Optional*, :ref:`lambda `): Lambda to be evaluated every update interval to get the new value of the sensor -- **update_interval** (*Optional*, :ref:`config-time`): The interval to publish the value of the - sensor, either the result of the lambda function or if no lambda function the last value - published using the publish action. Set to ``never`` to disable updates. Defaults to ``60s``. +- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the + sensor. Set to ``never`` to disable updates. Defaults to ``60s``. - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Sensor `. diff --git a/components/sensor/tmp1075.rst b/components/sensor/tmp1075.rst new file mode 100644 index 00000000000..49a051e1f5b --- /dev/null +++ b/components/sensor/tmp1075.rst @@ -0,0 +1,78 @@ +TMP1075 Temperature Sensor +========================== + +.. seo:: + :description: Instructions for setting up the TMP1075 Temperature sensor. + :image: tmp1075.jpg + :keywords: TMP1075 + +The TMP1075 Temperature sensor allows you to use your TMP1075 +(`datasheet `__) +sensors with ESPHome. + +.. figure:: images/tmp1075.jpg + :align: center + :width: 30.0% + + TMP1075 Temperature Sensor. + (Credit: `Texas Instruments `__, image cropped and compressed) + +The TMP1075 is a high precision temperature sensor that communicates over I²C. +Each sensor is tested on a NIST tracable test setup during Texas Instruments' +production process. Accuracy is typically ±0.25°C across the -55°C to +125°C +range, with a maximum error of ±2°C in that same range and ±1°C in the -40°C to ++110°C range. + +To use the sensor, first set up an :ref:`I²C Bus ` and connect the sensor +to the specified pins. + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: tmp1075 + name: "Temperature TMP1075" + update_interval: 10s + i2c_id: i2c_bus + conversion_rate: 27.5ms + alert: + function: comparator + polarity: active_high + limit_low: 50 + limit_high: 75 + fault_count: 1 + +Configuration variables: +------------------------ + +- **name** (**Required**, string): The name for the temperature sensor. +- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for lambdas/multiple sensors. +- **address** (*Optional*, int): The I²C address of the sensor. + See :ref:`I²C Addresses ` for more information. Defaults to ``0x48``. +- **update_interval** (*Optional*, :ref:`config-time`): The interval to check + the sensor temperature. Defaults to ``60s``. +- **conversion_rate** (*Optional*): The interval at which the IC performs a + temperature measurement. This setting also determines how fast the alert pin + responds to temperature changes, and is thus independent of how often ESPHome + checks the sensor. Possible values are ``27.5ms``, ``55ms``, ``110ms``, and + ``220ms``. Defaults to ``27.5ms``. +- **alert** (*Optional*): Configure the alert pin behaviour. + - **function** (*Optional*, enum): Function of the alert pin, either ``comparator`` or ``interrupt``. Defaults to ``comparator``. + - **polarity** (*Optional*, enum): Polarity of the alert pin, either ``active_high`` or ``active_low``. Defaults to ``active_high``. + - **limit_low** (*Optional*, int): Lower temperature limit, in °C. Defaults to ``-128`` (the lowest possible limit value). + - **limit_high** (*Optional*, int): Higher temperature limit, in °C. Defaults to ``127.9375`` (the highest possible limit value). + - **fault_count** (*Optional*, int): Number of measurements. required for the alert pin to act. Must be between ``1`` and ``4``, inclusive. Defaults to ``1``. + +.. _tmp1075_i2c_addresses: + +I²C Addresses +------------- + +In order to allow multiple sensors to be connected to the same I²C bus, the +creators of this sensor hardware have included some options to change the I²C +address. Three address pins can be connected to GND, VCC, SDA, or SCL, creating +32 possible addresses. See section 9.3.2.2 of the `datasheet +`__ for the mapping table. + +When all address pins are connected to GND, the address is ``0x48``, which is +the default address for this sesnsor component. diff --git a/components/sensor/total_daily_energy.rst b/components/sensor/total_daily_energy.rst index 45729da1424..66eb8b78148 100644 --- a/components/sensor/total_daily_energy.rst +++ b/components/sensor/total_daily_energy.rst @@ -5,7 +5,7 @@ Total Daily Energy Sensor :description: Instructions for setting up sensors that track the total daily energy usage per day and accumulate the power usage. :image: sigma.svg -The ``total_daily_energy`` sensor is a helper sensor that can use the energy value of +The ``total_daily_energy`` sensor is a helper sensor that can use the power value of other sensors like the :doc:`HLW8012 `, :doc:`CSE7766 `, :doc:`ATM90E32 `, etc and integrate it over time. diff --git a/components/servo.rst b/components/servo.rst index 2e680ddc003..7cca13f52c4 100644 --- a/components/servo.rst +++ b/components/servo.rst @@ -150,6 +150,7 @@ configuration. See :ref:`Number ` for more information. - platform: template name: Servo Control min_value: -100 + initial_value: 0 max_value: 100 step: 1 optimistic: true diff --git a/components/speaker/i2s_audio.rst b/components/speaker/i2s_audio.rst new file mode 100644 index 00000000000..3ece5e99a13 --- /dev/null +++ b/components/speaker/i2s_audio.rst @@ -0,0 +1,49 @@ +I²S Audio Speaker +================= + +.. seo:: + :description: Instructions for setting up I²S based speakers in ESPHome. + :image: i2s_audio.svg + +The ``i2s_audio`` speaker platform allows you to receive audio via the the +:doc:`/components/i2s_audio`. This platform only works on ESP32 based chips. + +.. code-block:: yaml + + # Example configuration entry + speaker: + - platform: i2s_audio + dac_type: external + i2s_dout_pin: GPIO22 + mode: mono + +Configuration variables: +------------------------ + +- **dac_type** (**Required**, enum): + + - ``external``: Use an external DAC, for example the NS4168, or UDA1334A. + - ``internal``: Use the internal DAC + +External DAC +************ + +- **i2s_dout_pin** (**Required**, :ref:`Pin Schema `): The GPIO pin to use for the I²S DOUT (Data Out) signal. +- **mode** (*Optional*, string): The mode of the I²S bus. Can be ``mono`` or ``stereo``. Defaults to ``mono``. + +For best results, keep the wires as short as possible. + +Internal DAC +************ + +- **mode** (**Required**, enum): The channel mode of the internal DAC. + + - ``left`` + - ``right`` + - ``stereo`` + +See also +-------- + +- :doc:`index` +- :ghedit:`Edit` diff --git a/components/speaker/index.rst b/components/speaker/index.rst new file mode 100644 index 00000000000..85f110c3cce --- /dev/null +++ b/components/speaker/index.rst @@ -0,0 +1,96 @@ +Speaker Components +================== + +.. seo:: + :description: Instructions for setting up speakers in ESPHome. + :image: speaker.svg + +The ``speaker`` domain contains common functionality shared across the +speaker platforms. + +.. _config-speaker: + +Base Speaker Configuration +-------------------------- + +No configuration variables + +.. _speaker-actions: + +Speaker Actions +------------------ + +All ``speaker`` actions can be used without specifying an ``id`` if you have only one ``speaker`` in +your configuration YAML. + +Configuration variables: + +**id** (*Optional*, :ref:`config-id`): The speaker to control. Defaults to the only one in YAML. + + +.. _speaker-play: + +``speaker.play`` Action +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This action will start playing raw audio data from the speaker. + +.. code-block:: yaml + + on_...: + # Static raw audio data + - speaker.play: [...] + + # Templated, return type is std::vector + - speaker.play: !lambda return {...}; + + # in case you need to specify the speaker id + - speaker.play: + id: my_speaker + data: [...] + +Configuration variables: + +**id** (*Optional*, :ref:`config-id`): The speaker to control. Defaults to the only one in YAML. +**data** (*Required*, list of bytes): The raw audio data to play. + +.. _speaker-stop: + +``speaker.stop`` Action +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This action will stop playing audio data from the speaker and discard the unplayed data. + +.. _speaker-conditions: + +Speaker Conditions +--------------------- + +All ``speaker`` conditions can be used without specifying an ``id`` if you have only one ``speaker`` in +your configuration YAML. + +Configuration variables: + +**id** (*Optional*, :ref:`config-id`): The speaker to check. Defaults to the only one in YAML. + +.. _speaker-is_playing: + +``speaker.is_playing`` Condition +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This condition will check if the speaker is currently playing audio data. + + +Platforms +--------- + +.. toctree:: + :maxdepth: 1 + :glob: + + * + +See Also +-------- + +- :ghedit:`Edit` diff --git a/components/spi.rst b/components/spi.rst index 8cac04e9c8c..5b61fa36b00 100644 --- a/components/spi.rst +++ b/components/spi.rst @@ -44,6 +44,8 @@ Configuration variables: - **force_sw** (*Optional*, boolean): Whether software implementation should be used even if hardware one is available. - **id** (*Optional*, :ref:`config-id`): Manually specify the ID for this SPI hub if you need multiple SPI hubs. +**Please note:** while both ESP8266 and ESP32 support the reassignment of the default SPI pins to other GPIO pins, using the dedicated SPI pins can improve performance and stability for certain ESP/device combinations. + See Also -------- diff --git a/components/text_sensor/template.rst b/components/text_sensor/template.rst index ac65bbd933b..5886e5dcf31 100644 --- a/components/text_sensor/template.rst +++ b/components/text_sensor/template.rst @@ -31,9 +31,8 @@ Configuration variables: - **name** (**Required**, string): The name of the text sensor. - **lambda** (*Optional*, :ref:`lambda `): Lambda to be evaluated every update interval to get the new value of the text sensor -- **update_interval** (*Optional*, :ref:`config-time`): The interval to publish the value of the - text sensor, either the result of the lambda function or if no lambda function the last value - published using the publish action. Defaults to ``60s``. +- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the + text sensor. Set to ``never`` to disable updates. Defaults to ``60s``. - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - All other options from :ref:`Text Sensor `. diff --git a/components/text_sensor/wifi_info.rst b/components/text_sensor/wifi_info.rst index 502ad7206c6..0d7883d8f4a 100644 --- a/components/text_sensor/wifi_info.rst +++ b/components/text_sensor/wifi_info.rst @@ -23,6 +23,8 @@ via text sensors. name: ESP Mac Wifi Address scan_results: name: ESP Latest Scan Results + dns_address: + name: ESP DNS Address Configuration variables: ------------------------ @@ -37,6 +39,9 @@ Configuration variables: :ref:`Text Sensor `. - **scan_results** (*Optional*): Expose the latest networks found during the latest scan. All options from :ref:`Text Sensor `. +- **dns_address** (*Optional*): Expose the DNS Address of the ESP as text sensor. + :ref:`Text Sensor `. + See Also -------- diff --git a/components/vbus.rst b/components/vbus.rst index 9cb76c84be2..f0a278b6171 100644 --- a/components/vbus.rst +++ b/components/vbus.rst @@ -8,22 +8,56 @@ VBus Component The ``VBus`` Component provides status reading connectivity to solar heat energy collector controllers using VBus protocol. These devices are mainly produced by Resol, often also found under different brand names like Viessmann, -Kioto, Wagner etc. The component currently supports natively Resol DeltaSol C, DeltaSol CS2, DeltaSol CS Plus, and DeltaSol BS Plus +Kioto, Wagner etc. The component currently supports natively the models in the table below but any device can be added via lambda by knowing `its packet structure `__. .. figure:: ../images/resol_deltasol_bs_plus.jpg :align: center +Supported Models +---------------- + +The following table shows the currently supported models of Vbus devices. + +.. csv-table:: Supported Models + :header: "Name", "Config Value", "Hex Address", "Notes" + + "DeltaSol BS Plus","deltasol_bs_plus","4221" + "DeltaSol BS 2009","deltasol_bs_2009","427B" + "Dux H3214","deltasol_bs_2009","427B", "Pump 2 unsupported" + "DeltaSol C","deltasol_c","4212" + "DeltaSol CS2","deltasol_cs2","1121" + "DeltaSol CS2 Plus","deltasol_cs2_plus","2211" + +The ``Config Value`` should be used for the ``model`` parameter in your ``sensor`` and ``binary_sensor`` entries. + +The ``Hex Address`` field is the value sent by a device in the ``from`` field of a message. To identify an unknown +model, set the logger level to ``VERBOSE`` and look for lines like this in the log output: + +``[10:53:48][V][vbus:068]: P1 C0500 427b->0000: 0000 0000 (0)`` + +The value before the ``->`` symbol is the device source address. If it matches one of the entries in the table above +then that model should work with your unit. + + +Hardware Connection +------------------- + The device must be connected via a :doc:`UART bus ` supporting the receiving line only. The UART bus must be configured at the same speed of the module which is by default 9600bps. The controller outputs data every second. To connect to this and read data from the bus a level shifting is needed as the voltage is around 8V (direct connection -would damage the MCU). Although this is a symmetric connection supporting long wires, for our read-only purposes it's -enough to adapt the level appropriately to 3.3V using a circuit like below: +would damage the MCU). For our read-only purposes it's +sufficient to adapt the level appropriately to 3.3V using a circuit like below: .. figure:: ../images/resol_vbus_adapter_schematic.png :align: center +An electrically isolated version using an opto-coupler: + +.. figure:: images/vbus_serial_optocoupler.png + :align: center + Another approach, with PCB design ready to be manufactured `can be found here `__. .. warning:: @@ -62,7 +96,7 @@ Configuration variables: .. note:: - Functionality of the sensors depends on the type of the device and the the scheme arrangement of the hydraulic + Functionality of the sensors depends on the type of the device and the scheme arrangement of the hydraulic system it controls. The actual arrangement number set up can be determined from the settings of the device. Please check the user manual and assess your arrangement to determine the functionality of each sensor and name them accordingly. @@ -103,12 +137,11 @@ Sensor Configuration variables: -- **model** (**Required**): Specify the model of the connected controller. Currently supported models are: ``deltasol_bs_plus``, ``deltasol_c``, ``deltasol_cs2``, ``deltasol_cs_plus``. - +- **model** (**Required**): Specify the model of the connected controller. Choose one of the config values listed in the table of supported models above. Supported sensors: -- for **deltasol_bs_plus**: ``temperature_1``, ``temperature_2``, ``temperature_3``, ``temperature_4``, ``pump_speed_1``, ``pump_speed_2``, ``operating_hours_1``, ``operating_hours_2``, ``heat_quantity``, ``time``, ``version``. +- for **deltasol_bs_plus** and **deltasol_bs_2009**: ``temperature_1``, ``temperature_2``, ``temperature_3``, ``temperature_4``, ``pump_speed_1``, ``pump_speed_2``, ``operating_hours_1``, ``operating_hours_2``, ``heat_quantity``, ``time``, ``version``. - for **deltasol_c**: ``temperature_1``, ``temperature_2``, ``temperature_3``, ``temperature_4``, ``pump_speed_1``, ``pump_speed_2``, ``operating_hours_1``, ``operating_hours_2``, ``heat_quantity``, ``time``. - for **deltasol_cs2**: ``temperature_1``, ``temperature_2``, ``temperature_3``, ``temperature_4``, ``pump_speed``, ``operating_hours``, ``heat_quantity``, ``version``. - for **deltasol_cs_plus**: ``temperature_1``, ``temperature_2``, ``temperature_3``, ``temperature_4``, ``temperature_5``, ``pump_speed_1``, ``pump_speed_2``, ``operating_hours_1``, ``operating_hours_2``, ``heat_quantity``, ``time``, ``version``, ``flow_rate``. @@ -160,24 +193,24 @@ Binary Sensor Configuration variables: -- **model** (**Required**): Specify the model of the connected controller. Currently supported models are: ``deltasol_bs_plus``, ``deltasol_c``, ``deltasol_cs2``, ``deltasol_cs_plus``. +- **model** (**Required**): Specify the model of the connected controller. Choose one of the config values listed in the table of supported models above. Supported sensors: - for **deltasol_bs_plus**: ``relay1``, ``relay2``, ``sensor1_error``, ``sensor2_error``, ``sensor3_error``, ``sensor4_error``, ``collector_max``, ``collector_min``, ``collector_frost``, ``tube_collector``, ``recooling``, ``hqm``. +- for **deltasol_bs_2009**: ``sensor1_error``, ``sensor2_error``, ``sensor3_error``, ``sensor4_error``, ``frost_protection_active``. - for **deltasol_c**: ``sensor1_error``, ``sensor2_error``, ``sensor3_error``, ``sensor4_error``. - for **deltasol_cs2**: ``sensor1_error``, ``sensor2_error``, ``sensor3_error``, ``sensor4_error``. - for **deltasol_cs_plus**: ``sensor1_error``, ``sensor2_error``, ``sensor3_error``, ``sensor4_error``. - All binary sensors are *Optional* and support all other options from :ref:`Binary Sensor `. ``Custom`` VBus sensors ----------------------- -Devices on a VBus are identified with a source address. There can be multiple devices on the same bus, -each device type has a different address. +Devices on a VBus are identified with a source address. There can be multiple devices on the same bus, +each device type has a different address. .. code-block:: yaml @@ -203,7 +236,7 @@ Configuration variables: - **sensors** (**Required**): A list of :ref:`Sensor ` definitions that include a ``lambda`` to do the decoding and return a ``float`` value. - **lambda** (**Required**, :ref:`lambda `): Code to parse a value from the incoming data packets and return it. - The data packet is in a `std::vector` called `x`. + The data packet is in a ``std::vector`` called ``x``. ``custom`` VBus binary sensors @@ -218,7 +251,7 @@ Configuration variables: - **binary_sensors** (**Required**): A list of :ref:`Binary Sensor ` definitions that include a ``lambda`` to do the decoding and return a ``bool`` value. - **lambda** (**Required**, :ref:`lambda `): Code to parse a value from the incoming data packets and return it. - The data packet is in a `std::vector` called `x`. + The data packet is in a ``std::vector`` called ``x``. To determine the correct values for the parameters above, visit `packet definitions list `__. In the search field of the **Packets** table, enter the name of your device. diff --git a/components/voice_assistant.rst b/components/voice_assistant.rst index 8bd5c1b1862..9349b2f1e75 100644 --- a/components/voice_assistant.rst +++ b/components/voice_assistant.rst @@ -5,7 +5,7 @@ Voice Assistant :description: Instructions for setting up a Voice Assistant in ESPHome. :image: voice-assistant.svg -ESPHome devices with a microphone are able to stream the audio to Home Assistant and be processed there by `assist `__. +ESPHome devices with a microphone are able to stream the audio to Home Assistant and be processed there by `assist `__. .. note:: @@ -23,7 +23,15 @@ Configuration: voice_assistant: microphone: mic_id -- **microphone** (**Required**, :ref:`config-id`): The microphone to use for input. +- **microphone** (**Required**, :ref:`config-id`): The :doc:`microphone ` to use for input. +- **speaker** (*Optional*, :ref:`config-id`): The :doc:`speaker ` to use to output the response. + Cannot be used with ``media_player`` below. +- **media_player** (*Optional*, :ref:`config-id`): The :doc:`media_player ` to use + to output the response. Cannot be used with ``speaker`` above. +- **silence_detection** (*Optional*, bool): Whether Home Assistant uses Voice Activity Detection to detect when you + have stopped talking and start processing the command. Defaults to ``true``. +- **on_listening** (*Optional*, :ref:`Automation `): An automation to + perform when the voice assistant starts listening. - **on_start** (*Optional*, :ref:`Automation `): An automation to perform when the voice assistant starts listening. - **on_end** (*Optional*, :ref:`Automation `): An automation to perform @@ -49,8 +57,16 @@ Voice Assistant Actions The following actions are available for use in automations: - ``voice_assistant.start`` - Start listening for voice commands. +- ``voice_assistant.start_continuous`` - Start listening for voice commands. This will start listening again after + the response audio has finished playing. Errors will stop the cycle. Call ``voice_assistant.stop`` to stop the cycle. - ``voice_assistant.stop`` - Stop listening for voice commands. +Voice Assistant Conditions +-------------------------- + +The following conditions are available for use in automations: + +- ``voice_assistant.is_running`` - Returns true if the voice assistant is currently running. Push to Talk ------------ @@ -60,7 +76,8 @@ Here is an example offering Push to Talk with a :doc:`/components/binary_sensor/ .. code-block:: yaml voice_assistant: - microphone: mic_id + microphone: ... + speaker: ... binary_sensor: - platform: gpio @@ -70,6 +87,26 @@ Here is an example offering Push to Talk with a :doc:`/components/binary_sensor/ on_release: - voice_assistant.stop: +Click to Converse +----------------- + +.. code-block:: yaml + + voice_assistant: + microphone: ... + speaker: ... + + binary_sensor: + - platform: gpio + pin: ... + on_click: + - if: + condition: voice_assistant.is_running + then: + - voice_assistant.stop: + else: + - voice_assistant.start_continuous: + See Also -------- diff --git a/components/web_server.rst b/components/web_server.rst index 4e1e29efeab..50fdb638e2a 100644 --- a/components/web_server.rst +++ b/components/web_server.rst @@ -7,27 +7,26 @@ Web Server Component :keywords: web server, http, REST API The ``web_server`` component creates a simple web server on the node that can be accessed -through any browser and a simple `REST API`_. Please note that enabling this component -will take up *a lot* of memory and can lead to problems, especially on the ESP8266. +through any browser and a simple :ref:`api-rest`. Please note that enabling this component +will take up *a lot* of memory and may decrease stability, especially on ESP8266. -To navigate to the web server in your browser, either use the IP address of the node or -use ``.local/`` (note the trailing forward slash) via mDNS. +.. figure:: /components/images/web_server.png + :align: center + :width: 86.0% -To conserve flash size, the CSS and JS files used on the root page to show a simple user -interface are hosted by esphome.io. If you want to use your own service, use the -``css_url`` and ``js_url`` options in your configuration. + Web server version 1 -.. _REST API: /web-api/index.html -.. figure:: /components/images/web_server.png +.. figure:: /components/images/web_server-v2.png + :align: center + :width: 86.0% - Example web server frontend (Version 1) + Web server version 2 -Version 2: ----------- -.. figure:: /components/images/web_server-v2.png - Web Components (Version 2) +To navigate to the web server in your browser, either use the IP address of the node or +use ``.local/`` (note the trailing forward slash) via mDNS. + .. code-block:: yaml @@ -50,7 +49,7 @@ Configuration variables: - **js_include** (*Optional*, local file): Path to local file to be included in web server index page. Contents of this file will be served as ``/0.js`` and used as JS script by internal webserver. Useful when building device without internet access, where you want to use built-in AP and webserver. -- **auth** (*Optional*): Enables basic authentication with username and password. +- **auth** (*Optional*): Enables a simple *Digest* authentication with username and password. - **username** (**Required**, string): The username to use for authentication. - **password** (**Required**, string): The password to check for authentication. @@ -62,52 +61,53 @@ Configuration variables: - **local** (*Optional*, boolean): Include supporting javascript locally allowing it to work without internet access. Defaults to ``false``. - **version** (*Optional*, string): ``1`` or ``2``. Version 1 displays as a table. Version 2 uses web components and has more functionality. Defaults to ``2``. -.. note:: - - Example web_server configuration using HTTP authentication: +To conserve flash size, the CSS and JS files used on the root page to show a simple user +interface are hosted by esphome.io. If you want to use your own service, use the +``css_url`` and ``js_url`` options in your configuration. - .. code-block:: yaml +Example configurations: +----------------------- - # Example configuration entry - web_server: - port: 80 - auth: - username: admin - password: !secret web_server_password +Enabling HTTP authentication: - Example web_server configuration using version 1 (previous behaviour): +.. code-block:: yaml - .. code-block:: yaml + # Example configuration entry + web_server: + port: 80 + auth: + username: !secret web_server_username + password: !secret web_server_password - # Example configuration entry - web_server: - port: 80 - version: 1 +Use version 1 user interface: - Example web_server configuration using version 2 - no internet/intranet required: +.. code-block:: yaml - .. code-block:: yaml + # Example configuration entry + web_server: + port: 80 + version: 1 - # Example configuration entry - web_server: - local: true +No internet/intranet required on the clients (all assets are inlined, compressed and served from flash): +.. code-block:: yaml + # Example configuration entry + web_server: + local: true - All of the assets are inlined, compressed and served from flash -Here be Dragons -=============== +Advanced usage +-------------- The following assume copies of the files with local paths - which are config dependant. -Example web_server version 1 configuration with CSS and JS included from esphome-docs. +Example ``web_server`` version 1 configuration with CSS and JS included from esphome-docs. CSS and JS URL's are set to empty value, so no internet access is needed for this device to show it's web interface. Force to turn off OTA function because the missing authentication. .. code-block:: yaml - # Example configuration entry V1 web_server: port: 80 version: 1 @@ -117,26 +117,26 @@ Force to turn off OTA function because the missing authentication. js_include: "../../../esphome-docs/_static/webserver-v1.min.js" js_url: "" -Example web_server version 2 configuration with JS included from a local file. - +Example ``web_server`` version 2 configuration with JS included from a local file. CSS and JS URL's are set to empty value, so no internet access is needed for this device to show it's web interface. V2 embeds the css within the js file so is not required, however you could include your own CSS. .. code-block:: yaml - # Example configuration entry V2 + # Example configuration entry v2 web_server: js_include: "./v2/www.js" js_url: "" version: 2 - Copy https://oi.esphome.io/v2/www.js to a V2 folder in your yaml folder. See Also -------- +- :ref:`api-event-source` +- :ref:`api-rest` - :apiref:`web_server/web_server.h` - :doc:`prometheus` - :ghedit:`Edit` diff --git a/components/wifi.rst b/components/wifi.rst index 5fecb4b40ef..128b8b851c2 100644 --- a/components/wifi.rst +++ b/components/wifi.rst @@ -89,6 +89,8 @@ Configuration variables: - **enable_btm** (*Optional*, bool): Only on ``esp32`` with ``esp-idf``. Enable 802.11v BSS Transition Management support. - **enable_rrm** (*Optional*, bool): Only on ``esp32`` with ``esp-idf``. Enable 802.11k Radio Resource Management support. +- **enable_on_boot** (*Optional*, boolean): If enabled, the WiFi interface will be enabled on boot. Defaults to ``true``. + - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. Access Point Mode @@ -270,6 +272,39 @@ Configuration variables: - **key** (*Optional*, string): Path to a PEM encoded private key matching ``certificate`` for EAP-TLS authentication. Optionally encrypted with ``password``. + +``wifi.disable`` Action +----------------------- + +This action turns off the WiFi interface on demand. + +.. code-block:: yaml + + on_...: + then: + - wifi.disable: + +.. note:: + + Be aware that if you disable WiFi, the API timeout will need to be disabled otherwise the device will reboot. + + +``wifi.enable`` Action +---------------------- + +This action turns on the WiFi interface on demand. + +.. code-block:: yaml + + on_...: + then: + - wifi.enable: + +.. note:: + + The configuration option ``enable_on_boot`` can be set to ``false`` if you do not want wifi to be enabled on boot. + + .. _wifi-connected_condition: ``wifi.connected`` Condition @@ -286,6 +321,31 @@ This :ref:`Condition ` checks if the WiFi client is currently then: - logger.log: WiFi is connected! + +The lambda equivalent for this is ``id(wifi_id).is_connected()``. + + +.. _wifi-enabled_condition: + +``wifi.enabled`` Condition +-------------------------- + +This :ref:`Condition ` checks if WiFi is currently enabled or not. + +.. code-block:: yaml + + on_...: + - if: + condition: wifi.enabled + then: + - wifi.disable: + else: + - wifi.enable: + + +The lambda equivalent for this is ``!id(wifi_id).is_disabled()``. + + See Also -------- @@ -294,5 +354,6 @@ See Also - :doc:`sensor/wifi_signal` - :doc:`network` - :doc:`/components/ethernet` +- :doc:`api` - :apiref:`wifi/wifi_component.h` - :ghedit:`Edit` diff --git a/components/xl9535.rst b/components/xl9535.rst new file mode 100644 index 00000000000..6eeae601007 --- /dev/null +++ b/components/xl9535.rst @@ -0,0 +1,67 @@ +XL9535 I/O Expander +==================== + +.. seo:: + :description: Instructions for setting up XL9535 digital port expanders in ESPHome. + :image: xl9535.svg + + +The XL9535 component allows you to use **XL9535** I/O expander in ESPHome. +It uses :ref:`I²C Bus ` for communication. + +Once configured, you can use any of the **16** available pins for your projects. +Within ESPHome they emulate a real internal GPIO pin +and can therefore be used with many of ESPHome's components such as the GPIO +Binary Sensor or GPIO Switch. + +.. note:: + + This I/O Expander chip is used in the *Lilygo T-RGB 2.1" Round Display* + +.. code-block:: yaml + + # Example configuration entry + xl9535: + - id: xl9535_hub + address: 0x20 + + # Individual outputs + switch: + - platform: gpio + name: XL9535 Pin 0 + pin: + xl9535: xl9535_hub + number: 0 + mode: + output: true + inverted: false + + +Configuration variables: +************************ + +- **id** (**Required**, :ref:`config-id`): The id to use for this ``xl9535`` component. +- **address** (*Optional*, int): The I²C address of the driver. + Defaults to ``0x20``. + + + +Pin configuration variables: +**************************** + +- **xl9535** (**Required**, :ref:`config-id`): The id of the ``xl9535`` component of the pin. +- **number** (**Required**, int): The pin number. +- **inverted** (*Optional*, boolean): If all read and written values + should be treated as inverted. Defaults to ``false``. +- **mode** (*Optional*, string): A pin mode to set for the pin at. One of ``INPUT`` or ``OUTPUT``. + + +See Also +-------- + +- :ref:`i2c` +- :doc:`switch/gpio` +- :doc:`binary_sensor/gpio` +- `XL9535 datasheet `__ +- :apiref:`xl9535/xl9535.h` +- :ghedit:`Edit` diff --git a/conf.py b/conf.py index 1280ef3c658..4080f7a633f 100644 --- a/conf.py +++ b/conf.py @@ -67,9 +67,9 @@ # built documents. # # The short X.Y version. -version = "2023.5" +version = "2023.7" # The full version, including alpha/beta/rc tags. -release = "2023.5.0-dev" +release = "2023.7.0-dev" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/cookbook/http_request_sensor.rst b/cookbook/http_request_sensor.rst new file mode 100644 index 00000000000..86cedeb010d --- /dev/null +++ b/cookbook/http_request_sensor.rst @@ -0,0 +1,121 @@ +Share data directly between ESPHome nodes +========================================= + +In certain special cases it might be desired to avoid placing any middleware like an MQTT or a home automation server just to transfer small bits of data from one node to another. Direct data polling is possibvle using HTTP, but beware that the involved components are resource hungry and may be less stable on long term. The webserver embedded in the node is not designed to constantly serve a large amount of requests. + +The primary node holding the data we need to retrieve from will be the server, and the others polling for it will be the clients (can be multiple). + +Server part +----------- + +Setting up a webserver using the :doc:`/components/web_server` on the primary node will make available the required sensor data through a :ref:`api-rest` interface. + +.. code-block:: yaml + + web_server: + port: 80 + +Client part +----------- + +On the client nodes we need an :doc:`/components/http_request` with an ``id`` set, and a :doc:`/components/sensor/template` to make it accessible locally. + +.. code-block:: yaml + + http_request: + useragent: esphome/device + id: http_request_id + + sensor: + - platform: template + name: "Template sensor on client" + id: template_sensor_id + + +Pulling the data +**************** + +To automate the request for data, we use an :ref:`interval` requesting the URL pointing to the sensor id for which the state is needed. See :ref:`api-rest` on how to build up the URL for your sensors. + +In the example below we request the value of a sensor from the server node, and after parsing the resulted JSON string we publish it to the local template sensor: + +.. code-block:: yaml + + interval: + - interval: 60s + then: + - http_request.get: + url: http://ip or nodename.local/sensor/ID_of_the_sensor + on_response: + then: + - lambda: |- + json::parse_json(id(http_request_id).get_string(), [](JsonObject root) { + id(template_sensor_id).publish_state(root["value"]); + }); + + +Result +------ + +.. figure:: images/server.png + :align: center + :width: 95.0% + + Server side real sensor + + +.. figure:: images/clients.png + :align: center + :width: 95.0% + + Client side template sensor + + +Increasing security +------------------- + +For security reasons, it's always recommended to protect the web interface of the nodes with authentication, even if you're using them on your local network. + +Server part +*********** + +Add authentication to the ``web_server`` component on the primary node: + +.. code-block:: yaml + + web_server: + port: 80 + auth: + username: !secret admin + password: !secret web_server_password + +Client part +*********** + +Add an ``Authorization`` header to your ``http_request.get`` action. The simplest way to determine a working authorization header is to visit the password-protected REST URL of the primary node using a browser while watching the network traffic in the browser's developer tools. If you look at the headers of the request sent by the browser, you'll find the ``Authorization`` header it sends to the node, and you can copy it for your own replay: + +.. code-block:: yaml + + interval: + - interval: 60s + then: + - http_request.get: + url: http://ip or nodename.local/sensor/ID_of_the_sensor + headers: + Authorization: 'Digest username="admin", realm="asyncesp", nonce="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", uri="/sensor/ID_of_the_sensor", response="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", opaque="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", qop=auth, nc=xxxxxxxx, cnonce="xxxxxxxxxxxxxxxx"' + on_response: + then: + - lambda: |- + json::parse_json(id(http_request_id).get_string(), [](JsonObject root) { + id(template_sensor_id).publish_state(root["value"]); + }); + +See Also +-------- + +- :doc:`/components/web_server` +- :doc:`/components/http_request` +- :doc:`/components/sensor/template` +- :ref:`interval` +- :ref:`api-rest` +- :ghedit:`Edit` diff --git a/cookbook/images/clients.png b/cookbook/images/clients.png new file mode 100644 index 00000000000..5b96deb8420 Binary files /dev/null and b/cookbook/images/clients.png differ diff --git a/cookbook/images/ehmtx.jpg b/cookbook/images/ehmtx.jpg index f1ec551cbed..2040ef7f43d 100644 Binary files a/cookbook/images/ehmtx.jpg and b/cookbook/images/ehmtx.jpg differ diff --git a/cookbook/images/server.png b/cookbook/images/server.png new file mode 100644 index 00000000000..93ab1ab0edb Binary files /dev/null and b/cookbook/images/server.png differ diff --git a/custom/i2c.rst b/custom/i2c.rst index ce1c30c71f6..78b68fa2de7 100644 --- a/custom/i2c.rst +++ b/custom/i2c.rst @@ -29,6 +29,64 @@ them publish values. } }; + +I²C Write +--------- +It may be useful to write to a register via I²C using a numerical input. For example, the following yaml code snippet captures a user-supplied numerical input in the range 1--255 from the dashboard: + +.. code-block:: yaml + + number: + - platform: template + name: "Input 1" + optimistic: true + min_value: 1 + max_value: 255 + initial_value: 20 + step: 1 + mode: box + id: input_1 + icon: "mdi:counter" + +We want to write this number to a ``REGISTER_ADDRESS`` on the slave device via I²C. The Arduino-based looping code shown above is modified following the guidance in :doc:`Custom Sensor Component `. + +.. code-block:: cpp + + #include "esphome.h" + + const uint16_t I2C_ADDRESS = 0x21; + const uint16_t REGISTER_ADDRESS = 0x78; + const uint16_t POLLING_PERIOD = 15000; //milliseconds + char temp = 20; //Initial value of the register + + class MyCustomComponent : public PollingComponent { + public: + MyCustomComponent() : PollingComponent(POLLING_PERIOD) {} + float get_setup_priority() const override { return esphome::setup_priority::BUS; } //Access I2C bus + + void setup() override { + //Add code here as needed + Wire.begin(); + } + + void update() override { + char register_value = id(input_1).state; //Read the number set on the dashboard + //Did the user change the input? + if(register_value != temp){ + Wire.beginTransmission(I2C_ADDRESS); + Wire.write(REGISTER_ADDRESS); + Wire.write(register_value); + Wire.endTransmission(); + temp = register_value; //Swap in the new value + } + } + }; + +The ``Component`` class has been replaced with ``PollingComponent`` and the free-running ``loop()`` is changed to the ``update()`` method with period set by ``POLLING_PERIOD``. The numerical value from the dashboard is accessed with its ``id`` tag and its state is set to the byte variable that we call ``register_value``. To prevent an I²C write on every iteration, the contents of the register are stored in ``temp`` and checked for a change. Configuring the hardware with ``get_setup_priority()`` is explained in :doc:`Step 1 `. + + + + See Also -------- diff --git a/guides/configuration-types.rst b/guides/configuration-types.rst index a8a0dcc53f0..cf9661eb7f7 100644 --- a/guides/configuration-types.rst +++ b/guides/configuration-types.rst @@ -451,6 +451,76 @@ them locally with their own subsitution value. # shorthand form github://username/repository/[folder/]file-path.yml[@branch-or-tag] remote_package_three: github://esphome/non-existant-repo/file1.yml@main +Packages as Templates +********************* + +Since packages are incorporated using the ``!include`` system, +variables can be provided to them. This means that packages can be +used as `templates`, allowing complex or repetitive configurations to +be stored in a package file and then incorporated into the +configuration more than once. + +As an example, if the configuration needed to support three garage +doors using the ``gpio`` switch platform and the ``time_based`` cover +platform, it could be constructed like this: + +.. code-block:: yaml + + # In config.yaml + packages: + left_garage_door: !include + file: garage-door.yaml + vars: + door_name: Left + door_location: left + open_switch_gpio: 25 + close_switch_gpio: 26 + middle_garage_door: !include + file: garage-door.yaml + vars: + door_name: Middle + door_location: middle + open_switch_gpio: 27 + close_switch_gpio: 29 + right_garage_door: !include + file: garage-door.yaml + vars: + door_name: Right + door_location: right + open_switch_gpio: 15 + close_switch_gpio: 18 + + +.. code-block:: yaml + + # In garage-door.yaml + switch: + - id: open_${door_location}_door_switch + name: ${door_name} Garage Door Open Switch + platform: gpio + pin: ${open_switch_gpio} + + - id: close_${door_location}_door_switch + name: ${door_name} Garage Door Close Switch + platform: gpio + pin: ${close_switch_gpio} + + cover: + - platform: time_based + name: ${door_name} Garage Door + + open_action: + - switch.turn_on: open_${door_location}_door_switch + open_duration: 2.1min + + close_action: + - switch.turn_on: close_${door_location}_door_switch + close_duration: 2min + + stop_action: + - switch.turn_off: open_${door_location}_door_switch + - switch.turn_off: close_${door_location}_door_switch + See Also -------- diff --git a/guides/creators.rst b/guides/creators.rst index 134f2ce0e3e..5aed84e01cd 100644 --- a/guides/creators.rst +++ b/guides/creators.rst @@ -79,10 +79,16 @@ Relevant Documentation credentials and they must be set by the user via either the ``ap`` + ``captive_portal`` or the ``esp32_improv`` / ``improv_serial`` components. - ``dashboard_import`` - - ``package_import_url`` - This should point to the public repository containing - the configuration for the device so that the user's ESPHome dashboard can autodetect this device and - create a minimal YAML using :ref:`config-git_packages`. - - ``import_full_config`` - This signals if ESPHome should download the entire YAML file as the user's config YAML instead of referencing the package. Set this to `true` if you are creating a tutorial to let users easily tweak the whole configuration or be able to uncomment follow-up tutorial steps. + .. note:: + + The :ref:`esphome-creators_project` above is required for adoption to work in the Dashboard. + + - ``package_import_url`` - This should point to the public repository containing + the configuration for the device so that the user's ESPHome dashboard can autodetect this device and + create a minimal YAML using :ref:`config-git_packages`. + - ``import_full_config`` - This signals if ESPHome should download the entire YAML file as the user's config + YAML instead of referencing the package. Set this to ``true`` if you are creating a tutorial to let users + easily tweak the whole configuration or be able to uncomment follow-up tutorial steps. - ``improv_serial`` - :doc:`/components/improv_serial` See Also diff --git a/guides/getting_started_command_line.rst b/guides/getting_started_command_line.rst index a58ed579893..da532d7c7cf 100644 --- a/guides/getting_started_command_line.rst +++ b/guides/getting_started_command_line.rst @@ -40,6 +40,12 @@ If you want to use `docker-compose` instead, here's a sample file: privileged: true network_mode: host +.. note:: + + If you are using NFS share to back your container's config volume, you may + need to mount the volume with the `nolock` option, otherwise platformio may + freeze on container startup as per `platformIO-core Issue 3089 `__ + The project provides multiple docker tags; please pick the one that suits you better: diff --git a/guides/supporters.rst b/guides/supporters.rst index 4c0d6ef55ad..02cd8c27d41 100644 --- a/guides/supporters.rst +++ b/guides/supporters.rst @@ -27,6 +27,7 @@ Contributors - `Alessandro Campolo (@a13ssandr0) `__ - `Aalian Khan (@AalianKhan) `__ - `Adam Liddell (@aaliddell) `__ +- `Aapeli Vuorinen (@aapeliv) `__ - `Aaron Gamble (@aarongamble) `__ - `Aaron S. Jackson (@AaronJackson) `__ - `Abel Matser (@abelmatser) `__ @@ -40,7 +41,6 @@ Contributors - `Andrea Donno (@adonno) `__ - `Adrien Brault (@adrienbrault) `__ - `Ian Blais (@aeonsablaze) `__ -- `Johan Bloemberg (@aequitas) `__ - `Stefan Agner (@agners) `__ - `Anders (@ahd71) `__ - `Alexander Pohl (@ahpohl) `__ @@ -57,6 +57,7 @@ Contributors - `Albin Kauffmann (@albinou) `__ - `Andre Lengwenus (@alengwenus) `__ - `Alex (@alex-richards) `__ +- `Alex Dekker (@Alex1602) `__ - `Alexander Leisentritt (@Alex9779) `__ - `Alex Barcelo (@alexbarcelo) `__ - `AlexCPU (@AlexCPU) `__ @@ -96,6 +97,7 @@ Contributors - `aquaticus (@aquaticus) `__ - `Andy Allsopp (@arallsopp) `__ - `arantius (@arantius) `__ +- `Ariff Saad (@arffsaad) `__ - `arturo182 (@arturo182) `__ - `arunderwood (@arunderwood) `__ - `Arya (@Arya11111) `__ @@ -104,7 +106,6 @@ Contributors - `ashp8i (@ashp8i) `__ - `Ashton Kemerling (@AshtonKem) `__ - `杨成锴 (@asjdf) `__ -- `Pavel Pletenev (@ASMfreaK) `__ - `Andreas Soehlke (@asoehlke) `__ - `Mike Dunston (@atanisoft) `__ - `Glenn Morrison (@atomicpapa) `__ @@ -135,6 +136,8 @@ Contributors - `beaudeanadams (@beaudeanadams) `__ - `Benjamin Freeman (@Beetix) `__ - `beikeland (@beikeland) `__ +- `Bella Coola (@BellaCoola) `__ +- `Pierre (@bemble) `__ - `Ben-Schwabe (@Ben-Schwabe) `__ - `Ben Hoff (@benhoff) `__ - `Benno Pütz (@bennop) `__ @@ -144,6 +147,7 @@ Contributors - `Berend Haan (@berendhaan) `__ - `Arturo Casal (@berfenger) `__ - `Bryan Berg (@berg) `__ +- `BerlinJoker (@BerlinJoker) `__ - `Bert Hertogen (@berthertogen) `__ - `Ivan Bessarabov (@bessarabov) `__ - `Brandon (@bgulla) `__ @@ -192,18 +196,20 @@ Contributors - `Carlos Garcia Saura (@CarlosGS) `__ - `Carlos Ruiz (@CarlosRDomin) `__ - `carlywarly (@carlywarly) `__ +- `Carson Full (@CarsonF) `__ - `carstenschroeder (@carstenschroeder) `__ - `Valentin Ochs (@Cat-Ion) `__ - `Stroe Andrei Catalin (@catalin2402) `__ +- `cathelest (@cathelest) `__ - `cbialobos (@cbialobos) `__ - `Cameron Bulock (@cbulock) `__ - `Ciprian Constantinescu (@cciprian5) `__ +- `Carlos Cordero (@ccorderor) `__ - `cdmonk (@cdmonk) `__ - `ceaswaran (@ceaswaran) `__ - `Cellie (@CelliesProjects) `__ - `Chris Feenstra (@cfeenstra1024) `__ - `cg089 (@cg089) `__ -- `Kostas Chatzikokolakis (@chatziko) `__ - `Audric Schiltknecht (@chemicalstorm) `__ - `chris-jennings (@chris-jennings) `__ - `Chris (@chrismaki) `__ @@ -216,6 +222,7 @@ Contributors - `Colby Rome (@cisasteelersfan) `__ - `Chris Debenham (@cjd) `__ - `Chester (@clowrey) `__ +- `Clyde Stubbs (@clydebarrow) `__ - `Colin McCambridge (@cmccambridge) `__ - `Clifford Roche (@cmroche) `__ - `Casey Burnett (@codeangler) `__ @@ -235,6 +242,7 @@ Contributors - `Cossid (@Cossid) `__ - `Cougar (@Cougar) `__ - `Connor Prussin (@cprussin) `__ +- `cptquad (@cptquad) `__ - `Corey Rice (@crice009) `__ - `cryptelli (@cryptelli) `__ - `Christian Schwarzgruber (@cslux) `__ @@ -273,6 +281,7 @@ Contributors - `David Newgas (@davidn) `__ - `David Noyes (@davidnoyes) `__ - `David Zovko (@davidzovko) `__ +- `Davrosx (@Davrosx) `__ - `Davy Landman (@DavyLandman) `__ - `Dawid Cieszyński (@dawidcieszynski) `__ - `Darren Tucker (@daztucker) `__ @@ -280,6 +289,7 @@ Contributors - `David Buezas (@dbuezas) `__ - `dckiller51 (@dckiller51) `__ - `Daniel Correa Lobato (@dclobato) `__ +- `Dion Hulse (@dd32) `__ - `DeadEnd (@DeadEnded) `__ - `Debashish Sahu (@debsahu) `__ - `declanshanaghy (@declanshanaghy) `__ @@ -292,6 +302,8 @@ Contributors - `Davide Depau (@depau) `__ - `dependabot[bot] (@dependabot[bot]) `__ - `Joeri Colman (@depuits) `__ +- `Mike La Spina (@descipher) `__ +- `Stephan Martin (@designer2k2) `__ - `Destix (@Destix) `__ - `Deun Lee (@deunlee) `__ - `Develo (@devyte) `__ @@ -310,6 +322,7 @@ Contributors - `Dmitriy Lopatko (@dmitriy5181) `__ - `Farzad E. (@dnetguru) `__ - `DrZoid (@docteurzoidberg) `__ +- `DominikBitzer (@DominikBitzer) `__ - `Dominik (@DomiStyle) `__ - `Derek M. (@doolbneerg) `__ - `Dorian Zedler (@dorianim) `__ @@ -320,6 +333,7 @@ Contributors - `Daniel Hyles (@DotNetDann) `__ - `dr-oblivium (@dr-oblivium) `__ - `Drew Perttula (@drewp) `__ +- `drmodding (@drmodding) `__ - `drmpf (@drmpf) `__ - `drogfild (@drogfild) `__ - `DrRob (@DrRob) `__ @@ -349,6 +363,7 @@ Contributors - `Erwin Kooi (@egeltje) `__ - `Eike (@ei-ke) `__ - `Elazar Leibovich (@elazarl) `__ +- `Eli (@eli-xciv) `__ - `Eli Yu (@elizhyu) `__ - `Elkropac (@Elkropac) `__ - `Elliot Wood (@elliot-wood) `__ @@ -360,7 +375,6 @@ Contributors - `Eric Muehlstein (@emuehlstein) `__ - `Anders Persson (@emwap) `__ - `Bert (@Engelbert) `__ -- `Nico Weichbrodt (@envy) `__ - `Evan Petousis (@epetousis) `__ - `Josh Gwosdz (@erdii) `__ - `Eric Coffman (@ericbrian) `__ @@ -384,11 +398,13 @@ Contributors - `C W (@fake-name) `__ - `Florian idB (@fbeek) `__ - `Fabian Berthold (@fbrthld) `__ +- `F.D.Castel (@fdcastel) `__ - `felixlungu (@felixlungu) `__ - `Felix Storm (@felixstorm) `__ - `Christian Ferbar (@ferbar) `__ - `FeuerSturm (@FeuerSturm) `__ - `Florian Golemo (@fgolemo) `__ +- `Federico G. Schwindt (@fgsch) `__ - `Frank Riley (@fhriley) `__ - `finity69x2 (@finity69x2) `__ - `Frédéric Jouault (@fjouault) `__ @@ -420,6 +436,7 @@ Contributors - `Gabe Cook (@gabe565) `__ - `Gareth Cooper (@gaco79) `__ - `gazoodle (@gazoodle) `__ +- `gcopeland (@gcopeland) `__ - `GeekVisit (@GeekVisit) `__ - `Ian Reinhart Geiser (@geiseri) `__ - `R Huish (@genestealer) `__ @@ -441,11 +458,12 @@ Contributors - `Germán Martín (@gmag11) `__ - `Germain Masse (@gmasse) `__ - `Garret Buell (@gmbuell) `__ -- `Jelle Raaijmakers (@GMTA) `__ +- `Jelle Raaijmakers (@gmta) `__ - `Go0oSer (@Go0oSer) `__ - `Gonzalo Paniagua Javier (@gonzalop) `__ - `gordon-zhao (@gordon-zhao) `__ - `Gustavo Ambrozio (@gpambrozio) `__ +- `Graham Brown (@grahambrown11) `__ - `Granville Barker (@granvillebarker) `__ - `Antoine GRÉA (@grea09) `__ - `Greg Arnold (@GregJArnold) `__ @@ -484,7 +502,6 @@ Contributors - `highground88 (@highground88) `__ - `Hamish Moffatt (@hmoffatt) `__ - `Marcel Hoppe (@hobbypunk90) `__ -- `MoA (@honomoa) `__ - `Hopperpop (@Hopperpop) `__ - `Yang Hau (@howjmay) `__ - `hpineapples (@hpineapples) `__ @@ -502,10 +519,10 @@ Contributors - `Jan Pobořil (@iBobik) `__ - `igg (@igg) `__ - `Ignacio Hernandez-Ros (@IgnacioHR) `__ -- `Petko Bordjukov (@ignisf) `__ - `ikatkov (@ikatkov) `__ - `iKK001 (@iKK001) `__ - `ilium007 (@ilium007) `__ +- `Iman Ahmadvand (@IMAN4K) `__ - `imgbot[bot] (@imgbot[bot]) `__ - `ImSorryButWho (@ImSorryButWho) `__ - `Dom (@Ing-Dom) `__ @@ -515,6 +532,7 @@ Contributors - `Ivo Roefs (@ironirc) `__ - `irtimaled (@irtimaled) `__ - `Ingo Theiss (@itn3rd77) `__ +- `itpeters (@itpeters) `__ - `Ivan Shvedunov (@ivan4th) `__ - `Ivan Kravets (@ivankravets) `__ - `Ivan Lisenkov (@ivlis) `__ @@ -522,6 +540,7 @@ Contributors - `J0RD4N300 (@J0RD4N300) `__ - `Fredrik Gustafsson (@jagheterfredrik) `__ - `Jan Harkes (@jaharkes) `__ +- `jakehdk (@jakehdk) `__ - `Jake Shirley (@JakeShirley) `__ - `Jakob Reiter (@jakommo) `__ - `James Braid (@jamesbraid) `__ @@ -534,7 +553,6 @@ Contributors - `Juraj Andrássy (@JAndrassy) `__ - `Delio Castillo (@jangeador) `__ - `Jan Grewe (@jangrewe) `__ -- `János Rusiczki (@janosrusiczki) `__ - `Jan Pieper (@janpieper) `__ - `Jared Ring (@jaredring) `__ - `Jarek.P (@JaroslawPrzybyl) `__ @@ -543,6 +561,7 @@ Contributors - `Jason Hines (@jasonehines) `__ - `JasperPlant (@JasperPlant) `__ - `Jas Strong (@jasstrong) `__ +- `Jay Newstrom (@JayNewstrom) `__ - `Jeff (@jazzmonger) `__ - `Jonas Bergler (@jbergler) `__ - `JbLb (@jblb) `__ @@ -561,6 +580,7 @@ Contributors - `Jeroen (@jeroen85) `__ - `Jérôme Laban (@jeromelaban) `__ - `Jesse Hills (@jesserockz) `__ +- `Joel Goguen (@jgoguen) `__ - `Yuval Brik (@jhamhader) `__ - `Joe (@jhansche) `__ - `Jan Pieter Waagmeester (@jieter) `__ @@ -570,13 +590,13 @@ Contributors - `Jérémy JOURDIN (@JJK801) `__ - `Jonathan Jefferies (@jjok) `__ - `John K. Luebs (@jkl1337) `__ -- `Justin Maxwell (@jkmaxwell) `__ - `Jeppe Ladefoged (@jladefoged) `__ - `Jean-Luc Béchennec (@jlbirccyn) `__ - `Jonas De Kegel (@jlsjonas) `__ - `Jeff Anderson (@jman203) `__ - `Jonathan Martens (@jmartens) `__ - `jmichiel (@jmichiel) `__ +- `JMoratelli (@JMoratelli) `__ - `Jonathas Barbosa (@jnthas) `__ - `Joe Gross (@joegross) `__ - `Johan van der Kuijl (@johanvanderkuijl) `__ @@ -601,12 +621,9 @@ Contributors - `James Szalay (@jtszalay) `__ - `Jules-R (@Jules-R) `__ - `Julie Koubová (@juliekoubova) `__ -- `Justahobby01 (@Justahobby01) `__ - `Mike Ryan (@justfalter) `__ - `Justin Gerhardt (@justin-gerhardt) `__ -- `Justyn Shull (@justyns) `__ - `Jasper van der Neut - Stulen (@jvanderneutstulen) `__ -- `João Vitor M. Roma (@jvmr1) `__ - `Jack Wozny (@jwozny) `__ - `Jozef Zuzelka (@jzlka) `__ - `Kris (@K-r-i-s-t-i-a-n) `__ @@ -614,19 +631,14 @@ Contributors - `Harald Nagel (@k7hpn) `__ - `kaegi (@kaegi) `__ - `kahrendt (@kahrendt) `__ -- `Kamahat (@kamahat) `__ - `Karl0ss (@karl0ss) `__ -- `Karol Zlot (@karolzlot) `__ - `Kattni (@kattni) `__ -- `Krasimir Nedelchev (@kaykayehnn) `__ - `Krzysztof Białek (@kbialek) `__ - `Keilin Bickar (@kbickar) `__ - `Keith Burzinski (@kbx81) `__ - `Ken Piper (@Kealper) `__ - `Kelvie Wong (@kelvie) `__ -- `Kenny Stier (@KennyStier) `__ - `kernelpanic85 (@kernelpanic85) `__ -- `Kevin O'Rourke (@kevinior) `__ - `kevlar10 (@kevlar10) `__ - `kfulko (@kfulko) `__ - `Kai Gerken (@KG3RK3N) `__ @@ -638,12 +650,11 @@ Contributors - `Klaas Schoute (@klaasnicolaas) `__ - `Klarstein (@Klarstein) `__ - `Marcus Klein (@kleini) `__ -- `Kevin Lewis (@kll) `__ - `KNXBroker (@KNXBroker) `__ -- `Koen Vervloesem (@koenvervloesem) `__ - `kokangit (@kokangit) `__ -- `Petr Vraník (@konikvranik) `__ +- `konsulten (@konsulten) `__ - `Kevin Pelzel (@kpelzel) `__ +- `Kevin P. Fleming (@kpfleming) `__ - `Karl Q. (@kquinsland) `__ - `Kodey Converse (@krconv) `__ - `KristopherMackowiak (@KristopherMackowiak) `__ @@ -654,12 +665,11 @@ Contributors - `Kuba Szczodrzyński (@kuba2k2) `__ - `Jakub Šimo (@kubik369) `__ - `Mark Kuchel (@kuchel77) `__ -- `Ken Davidson (@kwdavidson) `__ - `Kyle Hill (@kylhill) `__ -- `Kalashnikov Ilya (@l1bbcsg) `__ - `Limor "Ladyada" Fried (@ladyada) `__ - `Luca Adrian L (@lal12) `__ - `Fredrik Lindqvist (@Landrash) `__ +- `lanik (@lanik) `__ - `Lawrie George (@lawriege) `__ - `Laszlo Gazdag (@lazlyhu) `__ - `Ludovic BOUÉ (@lboue) `__ @@ -675,15 +685,19 @@ Contributors - `Juraj Liso (@LiJu09) `__ - `lillborje71 (@lillborje71) `__ - `lingex (@lingex) `__ +- `Markus (@Links2004) `__ - `lkomurcu (@lkomurcu) `__ +- `Luis Andrade (@llluis) `__ - `loadrunner42 (@loadrunner42) `__ - `Lazar Obradovic (@lobradov) `__ - `Barry Loong (@loongyh) `__ - `Michael Bisbjerg (@LordMike) `__ - `LuBeDa (@lubeda) `__ +- `Lucas Reiners (@lucasreiners) `__ - `Joakim Sørensen (@ludeeus) `__ - `ludrao (@ludrao) `__ - `Lukas Klass (@LukasK13) `__ +- `Lukas Lindner (@lukasl96) `__ - `Łukasz Świtaj (@lukaszswitaj) `__ - `Luke (@Lukeskaiwalker) `__ - `Jayden (@lukyjay) `__ @@ -716,6 +730,7 @@ Contributors - `Mario (@mario-tux) `__ - `Mark Schabacker (@markschabacker) `__ - `Marek Marczykowski-Górecki (@marmarek) `__ +- `marshn (@marshn) `__ - `marsjan155 (@marsjan155) `__ - `Martin (@martgras) `__ - `Martin Hjelmare (@MartinHjelmare) `__ @@ -731,6 +746,7 @@ Contributors - `Matthew Mazzanti (@matthewmazzanti) `__ - `matthias882 (@matthias882) `__ - `Matus Ivanecky (@maty535) `__ +- `Christian (@max246) `__ - `Maximilian Gerhardt (@maxgerhardt) `__ - `mbo18 (@mbo18) `__ - `mcmuller (@mcmuller) `__ @@ -744,14 +760,18 @@ Contributors - `megabitdragon (@megabitdragon) `__ - `meijerwynand (@meijerwynand) `__ - `Marco (@Melkor82) `__ +- `melyux (@melyux) `__ - `Merlin Schumacher (@merlinschumacher) `__ - `Martin Flasskamp (@MFlasskamp) `__ - `Michael Gorven (@mgorven) `__ +- `M Hightower (@mhightower83) `__ - `Jörg Thalheim (@Mic92) `__ - `Michael Muré (@MichaelMure) `__ +- `Michal Fapso (@michalfapso) `__ - `Micha Nordmann (@Michanord) `__ - `Michel Munzert (@michelde) `__ - `Pauline Middelink (@middelink) `__ +- `Joel Midstjärna (@midstar) `__ - `Mike_Went (@MikeWent) `__ - `Mikko Tervala (@MikkoTervala) `__ - `MiKuBB (@MiKuBB) `__ @@ -770,12 +790,12 @@ Contributors - `mnltake (@mnltake) `__ - `Matt N. (@mnoorenberghe) `__ - `Michał Obrembski (@mobrembski) `__ -- `Moritz Glöckl (@moritzgloeckl) `__ +- `moritzj29 (@moritzj29) `__ - `Chris Laplante (@mostthingsweb) `__ -- `Sam Hughes (@MrEditor97) `__ -- `Morgan Robertson (@mrgnr) `__ +- `MrEditor97 (@mreditor97) `__ - `Mariusz Kryński (@mrk-its) `__ - `Michael Davidson (@MrMDavidson) `__ +- `mrred2k (@mrred2k) `__ - `Murray Scott (@mscottco) `__ - `MSe-5-14 (@MSe-5-14) `__ - `mtl010957 (@mtl010957) `__ @@ -789,6 +809,7 @@ Contributors - `Mynasru (@Mynasru) `__ - `Mikhail Zakharov (@mzakharo) `__ - `Kevin Uhlir (@n0bel) `__ +- `N6RDV (@N6RDV) `__ - `Erik Näsström (@Naesstrom) `__ - `H. Árkosi Róbert (@nagyrobi) `__ - `Viktor Nagy (@nagyv) `__ @@ -798,11 +819,9 @@ Contributors - `ueno (@nayuta-ueno) `__ - `Nazar Mokrynskyi (@nazar-pc) `__ - `Bergont Nicolas (@nbergont) `__ -- `NMC (@ncareau) `__ -- `NeoAcheron (@NeoAcheron) `__ +- `Nejc Koncan (@nejc-cc) `__ - `Mike Meessen (@netmikey) `__ - `Nicolas Graziano (@ngraziano) `__ -- `Nick B. (@NickB1) `__ - `nickrout (@nickrout) `__ - `Nick Whyte (@nickw444) `__ - `Nicky Ivy (@nickyivyca) `__ @@ -811,7 +830,6 @@ Contributors - `Joakim Vindgard (@nigobo) `__ - `nikito7 (@nikito7) `__ - `niklasweber (@niklasweber) `__ -- `Niorix (@Niorix) `__ - `Zvonimir Haramustek (@nitko12) `__ - `Nixspers (@Nixspers) `__ - `Dennis (@Nizzle) `__ @@ -822,6 +840,7 @@ Contributors - `Álvaro Fernández Rojas (@Noltari) `__ - `Łukasz Śliwiński (@nonameplum) `__ - `Greg Johnson (@notgwj) `__ +- `notsonominal (@notsonominal) `__ - `nouser2013 (@nouser2013) `__ - `Nick (@ntompson) `__ - `Stephen Edgar (@ntwb) `__ @@ -848,24 +867,22 @@ Contributors - `Ben Owen (@owenb321) `__ - `Oxan van Leeuwen (@oxan) `__ - `Pablo Clemente Maseda (@paclema) `__ +- `Victor Tseng (@Palatis) `__ - `Derrick Lyndon Pallas (@pallas) `__ - `Panuruj Khambanonda (PK) (@panuruj) `__ -- `Pasi Suominen (@pasiz) `__ +- `Daniel Mahaney (@Papa-DMan) `__ - `Patrick Collins (@patrickcollins12) `__ -- `Patrick van der Leer (@patvdleer) `__ - `Paul Deen (@PaulAntonDeen) `__ - `Paul Monigatti (@paulmonigatti) `__ - `Paul Nicholls (@pauln) `__ - `Bartłomiej Biernacki (@pax0r) `__ -- `Paul Doidge (@pdoidge) `__ +- `pcr20 (@pcr20) `__ - `peddamat (@peddamat) `__ - `pedjas (@pedjas) `__ - `pedrobsm (@pedrobsm) `__ - `per1234 (@per1234) `__ - `David (@perldj) `__ -- `Peter Valkov (@peter-valkov) `__ - `Peter Galantha (@peterg79) `__ -- `Peter Halicky (@peterhalicky) `__ - `Philippe Delodder (@phdelodder) `__ - `philbowers (@philbowers) `__ - `Philippe FOUQUET (@Philippe12) `__ @@ -892,22 +909,20 @@ Contributors - `[pʲɵs] (@pyos) `__ - `Qc (@qc24) `__ - `Quinn Casey (@qcasey) `__ -- `Karol Zlot (@qqgg231) `__ - `Tommy Jonsson (@quazzie) `__ - `Quentin Smith (@quentinmit) `__ -- `Quinn Hosler (@quinnhosler) `__ - `Johannes Rebling (@r0oland) `__ - `Richard Kuhnt (@r15ch13) `__ - `Richard Miles (@r89m) `__ - `Aaron Zhang (@rabbit-aaron) `__ - `RadekHvizdos (@RadekHvizdos) `__ -- `Raph (@rafal83) `__ - `Florian Ragwitz (@rafl) `__ -- `Rai-Rai (@Rai-Rai) `__ +- `Ben V. Brown (@Ralim) `__ - `randomllama (@randomllama) `__ - `Marc Seeger (@rb2k) `__ - `rbaron (@rbaron) `__ - `Robert Cambridge (@rcambrj) `__ +- `Russell Cloran (@rcloran) `__ - `Rebbe Pod (@RebbePod) `__ - `reddn (@reddn) `__ - `Alex (@redwngsrul) `__ @@ -915,7 +930,6 @@ Contributors - `Regev Brody (@regevbr) `__ - `Alex Reid (@reidprojects) `__ - `RenierM26 (@RenierM26) `__ -- `Reuben (@reubn) `__ - `Robin Pronk (@rfpronk) `__ - `Robert Gabrielson (@rgabrielson11) `__ - `Rafael Goes (@rgriffogoes) `__ @@ -925,20 +939,20 @@ Contributors - `Richard Lewis (@richrd) `__ - `Andre Borie (@Rjevski) `__ - `rjlexx (@rjlexx) `__ -- `René Klomp (@rklomp) `__ - `rlowens (@rlowens) `__ - `Ryan Mounce (@rmounce) `__ - `rnauber (@rnauber) `__ - `Rob Deutsch (@rob-deutsch) `__ - `Robert Alfaro (@robert-alfaro) `__ -- `Rob Gridley (@robgridley) `__ - `Robinson1999 (@Robinson1999) `__ - `RoboMagus (@RoboMagus) `__ - `Roeland Lutters (@Roeland54) `__ - `RoganDawes (@RoganDawes) `__ +- `Roman Ondráček (@Roman3349) `__ - `Jérôme W. (@RomRider) `__ - `roscoegray (@roscoegray) `__ - `rotarykite (@rotarykite) `__ +- `Rajan Patel (@rpatel3001) `__ - `Bob Perciaccante (@rperciaccante) `__ - `rradar (@rradar) `__ - `rspaargaren (@rspaargaren) `__ @@ -947,14 +961,17 @@ Contributors - `RubyBailey (@RubyBailey) `__ - `Rus Ti (@Rusti-gotrage) `__ - `rweather (@rweather) `__ +- `rwilson131 (@rwilson131) `__ - `Ryan Lang (@ryan-lang) `__ - `ryanalden (@ryanalden) `__ +- `ryansmigley (@ryansmigley) `__ - `Lukas Bachschwell (@s00500) `__ - `Sabesto (@Sabesto) `__ - `Jan Čermák (@sairon) `__ - `Sam Turner (@samturner3) `__ - `Sender (@sanderlv) `__ - `sascha lammers (@sascha432) `__ +- `Davide Perini (@sblantipodi) `__ - `sbur83 (@sbur83) `__ - `Søren Christian Aarup (@scaarup) `__ - `Matthew Schinckel (@schinckel) `__ @@ -974,6 +991,7 @@ Contributors - `Abdelkader Boudih (@seuros) `__ - `SharkSharp (@SharkSharp) `__ - `Sebastiaan (@SharkWipf) `__ +- `Alexander Dimitrov (@sharkydog) `__ - `Fabio Todaro (@SharpEdgeMarshall) `__ - `ShellAddicted (@ShellAddicted) `__ - `sherbang (@sherbang) `__ @@ -986,7 +1004,6 @@ Contributors - `Stephen Tierney (@sjtrny) `__ - `Dominik Skalník (@skaldo) `__ - `Niklas Wagner (@Skaronator) `__ -- `Rafael Treviño (@skasi7) `__ - `Brian Slesinsky (@skybrian) `__ - `Jordan W. Cobb (@skykingjwc) `__ - `Sebastian Lövdahl (@slovdahl) `__ @@ -997,6 +1014,7 @@ Contributors - `sparkydave1981 (@sparkydave1981) `__ - `spattinson (@spattinson) `__ - `Sean Brogan (@spbrogan) `__ +- `Justin Gerace (@spectrumjade) `__ - `Spegs21 (@Spegs21) `__ - `Eric Lind (@sperly) `__ - `Samuel Sieb (@ssieb) `__ @@ -1020,18 +1038,20 @@ Contributors - `Marcel Feix (@Syndlex) `__ - `Suryandaru Triandana (@syndtr) `__ - `SyXavier (@SyXavier) `__ +- `Szewcson (@Szewcson) `__ - `Peter (@szpeter80) `__ - `Taigar2015 (@Taigar2015) `__ - `Stefan Dragnev (@tailsu) `__ - `Levente Tamas (@tamisoft) `__ - `Aleksandr Oleinikov (@tannisroot) `__ - `tantive (@tantive) `__ +- `Hawawa McTaru (@TaruDesigns) `__ - `Ryan Hoffman (@tekmaven) `__ - `testbughub (@testbughub) `__ - `Greg Lincoln (@tetious) `__ - `Terry Hardie (@thardie) `__ +- `thatslolo (@thatslolo) `__ - `The-Paran0id-Andr0id (@The-Paran0id-Andr0id) `__ -- `Nejc (@thedexboy) `__ - `Thomas Eckerstorfer (@TheEggi) `__ - `Theexternaldisk (@Theexternaldisk) `__ - `Martijn van der Pol (@TheFes) `__ @@ -1054,7 +1074,7 @@ Contributors - `tiagofreire-pt (@tiagofreire-pt) `__ - `Tijs-B (@Tijs-B) `__ - `Tim Laurence (@timdaman) `__ -- `Aidan Timson (@timmo001) `__ +- `Tim Niemueller (@timn) `__ - `Tim Savage (@timsavage) `__ - `Tinkerfish (@tinkerfish) `__ - `TJ Horner (@tjhorner) `__ @@ -1110,6 +1130,7 @@ Contributors - `Ian Wells (@wellsi) `__ - `wifwucite (@wifwucite) `__ - `wilberforce (@wilberforce) `__ +- `wildekek (@wildekek) `__ - `Wingman3434 (@Wingman3434) `__ - `Emil Hesslow (@WizKid) `__ - `WJCarpenter (@wjcarpenter) `__ @@ -1122,11 +1143,11 @@ Contributors - `wysiwyng (@wysiwyng) `__ - `Jakob (@XDjackieXD) `__ - `Mike Brown (@xenoxaos) `__ +- `Xose Pérez (@xoseperez) `__ - `WitchKing (@xvil) `__ - `Yaroslav (@Yarikx) `__ - `Marcin Jaworski (@yawor) `__ -- `Pavel (@yekm) `__ -- `Nico B (@youknow0) `__ +- `yousaf465 (@yousaf465) `__ - `Yuval Aboulafia (@yuvalabou) `__ - `Björn Stenberg (@zagor) `__ - `david reid (@zathras777) `__ @@ -1134,9 +1155,10 @@ Contributors - `Geek_cat (@zhzhzhy) `__ - `I. Tomita (@ziceva) `__ - `Michael Labuschke (@zigman79) `__ +- `Stefan Goethals (@zipkid) `__ - `zivillian (@zivillian) `__ - `Loïc (@zoic21) `__ - `Zack Barett (@zsarnett) `__ - `Christian Zufferey (@zuzu59) `__ -*This page was last updated April 20, 2023.* +*This page was last updated June 23, 2023.* diff --git a/images/alarm-panel.svg b/images/alarm-panel.svg new file mode 100644 index 00000000000..cf033c712c9 --- /dev/null +++ b/images/alarm-panel.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/images/as7341.jpg b/images/as7341.jpg index aac6137e1c3..ca9512f6aa6 100644 Binary files a/images/as7341.jpg and b/images/as7341.jpg differ diff --git a/images/ehmtx.jpg b/images/ehmtx.jpg index 9e53a5460d4..c8333efdf03 100644 Binary files a/images/ehmtx.jpg and b/images/ehmtx.jpg differ diff --git a/images/garage-variant.svg b/images/garage-variant.svg index a0b6880a312..eb3715fd2dc 100644 --- a/images/garage-variant.svg +++ b/images/garage-variant.svg @@ -1 +1 @@ - \ No newline at end of file + \ No newline at end of file diff --git a/images/gp8403.svg b/images/gp8403.svg new file mode 100644 index 00000000000..5ee72b007dc --- /dev/null +++ b/images/gp8403.svg @@ -0,0 +1 @@ + diff --git a/images/haier.svg b/images/haier.svg index 887c22f62e9..41d052f0693 100644 --- a/images/haier.svg +++ b/images/haier.svg @@ -1,25 +1 @@ - - - - - - - - - - - - - - - + \ No newline at end of file diff --git a/images/head-lightbulb-outline.svg b/images/head-lightbulb-outline.svg index 2e83e14bb95..be351a75292 100644 --- a/images/head-lightbulb-outline.svg +++ b/images/head-lightbulb-outline.svg @@ -1 +1 @@ - \ No newline at end of file + \ No newline at end of file diff --git a/images/hyt271.jpg b/images/hyt271.jpg new file mode 100644 index 00000000000..cfebba4cae9 Binary files /dev/null and b/images/hyt271.jpg differ diff --git a/images/ld2410.jpg b/images/ld2410.jpg index 5052b9110df..6884df9e922 100644 Binary files a/images/ld2410.jpg and b/images/ld2410.jpg differ diff --git a/images/matrix_keypad.jpg b/images/matrix_keypad.jpg index eec629e7df7..c99b2df6b73 100644 Binary files a/images/matrix_keypad.jpg and b/images/matrix_keypad.jpg differ diff --git a/images/max6956.jpg b/images/max6956.jpg new file mode 100644 index 00000000000..2a17ace4ab9 Binary files /dev/null and b/images/max6956.jpg differ diff --git a/images/mics_4514.jpg b/images/mics_4514.jpg index da99e90f16d..b0e6871ffbb 100644 Binary files a/images/mics_4514.jpg and b/images/mics_4514.jpg differ diff --git a/images/pca6416a.svg b/images/pca6416a.svg new file mode 100644 index 00000000000..67c5a3723c5 --- /dev/null +++ b/images/pca6416a.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/images/resol_vbus_adapter_schematic.png b/images/resol_vbus_adapter_schematic.png index c77c57cb3e9..cbde7dab39c 100644 Binary files a/images/resol_vbus_adapter_schematic.png and b/images/resol_vbus_adapter_schematic.png differ diff --git a/images/sigma-delta.svg b/images/sigma-delta.svg index 56a417c2fe2..3e9e8c44448 100644 --- a/images/sigma-delta.svg +++ b/images/sigma-delta.svg @@ -1,50 +1 @@ - - - - - - - - - - - + \ No newline at end of file diff --git a/images/speaker.svg b/images/speaker.svg new file mode 100644 index 00000000000..22a96737d14 --- /dev/null +++ b/images/speaker.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/images/thermometer.svg b/images/thermometer.svg index f3ea40ba600..dec6e174290 100644 --- a/images/thermometer.svg +++ b/images/thermometer.svg @@ -1 +1 @@ - + \ No newline at end of file diff --git a/images/tmp1075.jpg b/images/tmp1075.jpg new file mode 100644 index 00000000000..f5e7a98c2bc Binary files /dev/null and b/images/tmp1075.jpg differ diff --git a/images/x9c.jpg b/images/x9c.jpg index b355f267997..331c5fbc8da 100644 Binary files a/images/x9c.jpg and b/images/x9c.jpg differ diff --git a/images/xl9535.svg b/images/xl9535.svg new file mode 100644 index 00000000000..1eb535273ba --- /dev/null +++ b/images/xl9535.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/index.rst b/index.rst index 6c45f2203ac..a8b78a3025a 100644 --- a/index.rst +++ b/index.rst @@ -5,13 +5,13 @@ .. seo:: :description: ESPHome Homepage - Reimagining DIY Home Automation. ESPHome is a framework that - tries to provide the best possible use experience for using ESP8266 and ESP32 microcontrollers + tries to provide the best possible use experience for using ESP8266, ESP32 and RP2040 microcontrollers for Home Automation. Just write a simple YAML configuration file and get your own customized firmware. :image: logo.svg .. image:: /images/logo-text.svg -ESPHome is a system to control your ESP8266/ESP32 by simple yet powerful configuration files and control them remotely through Home Automation systems. +ESPHome is a system to control your ESP8266/ESP32 and RP2040 by simple yet powerful configuration files and control them remotely through Home Automation systems. .. image:: /images/hero.png @@ -318,6 +318,8 @@ Environmental TEE501, components/sensor/tee501, TEE501.png, Temperature TMP102, components/sensor/tmp102, tmp102.jpg, Temperature TMP117, components/sensor/tmp117, tmp117.jpg, Temperature + TMP1075, components/sensor/tmp1075, tmp1075.jpg, Temperature + HYT271, components/sensor/hyt271, hyt271.jpg, Temperature & Humidity Light @@ -499,11 +501,12 @@ Output Components BLE Binary Output, components/output/ble_client, bluetooth.svg Modbus Output, components/output/modbus_controller, modbus.png Custom Output, components/output/custom, language-cpp.svg - Sigma-Delta Output, components/output/sigma_delta, sigma-delta.svg + Sigma-Delta Output, components/output/sigma_delta_output, sigma-delta.svg Template Output, components/output/template, description.svg BP1658CJ, components/output/bp1658cj, bp1658cj.svg BP5758D, components/output/bp5758d, bp5758d.svg X9C Potentiometer, components/output/x9c, x9c.jpg + GP8403, components/output/gp8403, gp8403.svg Light Components ---------------- @@ -522,6 +525,8 @@ Light Components RGBWW Light, components/light/rgbww, rgbw.png RGBCT Light, components/light/rgbct, rgbw.png + ESP32 RMT, components/light/esp32_rmt_led_strip, color_lens.svg + RP2040 PIO, components/light/rp2040_pio_led_strip, color_lens.svg FastLED Light, components/light/fastled, color_lens.svg NeoPixelBus Light, components/light/neopixelbus, color_lens.svg Light Partition, components/light/partition, color_lens.svg @@ -715,6 +720,14 @@ Microphone Components Microphone Core, components/microphone/index, microphone.svg I2S Microphone, components/microphone/i2s_audio, i2s_audio.svg +Speaker Components +------------------ + +.. imgtable:: + + Speaker Core, components/speaker/index, speaker.svg + I2S Speaker, components/speaker/i2s_audio, i2s_audio.svg + Time Components --------------- @@ -738,6 +751,14 @@ Home Assistant Companion Components Text Sensor, components/text_sensor/homeassistant, home-assistant.svg Binary Sensor, components/binary_sensor/homeassistant, home-assistant.svg +Alarm Control Panel Components +------------------------------ + +.. imgtable:: + + Alarm Control Panel Core, components/alarm_control_panel/index, alarm-panel.svg + Template Alarm Control Panel, components/alarm_control_panel/template, description.svg + Miscellaneous Components ------------------------ @@ -771,14 +792,17 @@ Miscellaneous Components Servo, components/servo, servo.svg Sprinkler, components/sprinkler, sprinkler-variant.svg + PCA6416A I/O Expander, components/pca6416a, pca6416a.svg PCA9554 I/O Expander, components/pca9554, pca9554a.jpg PCF8574 I/O Expander, components/pcf8574, pcf8574.jpg + MAX6956 I/O expander - I²C Bus, components/max6956, max6956.jpg MCP230XX I/O Expander - I²C Bus, components/mcp230xx, mcp230xx.svg TCA9548A I²C Multiplexer, components/tca9548a, tca9548a.jpg MCP23SXX I/O Expander - SPI Bus, components/mcp23Sxx, mcp230xx.svg SX1509 I/O Expander, components/sx1509, sx1509.jpg SN74HC165 I/O Expander, components/sn74hc165, sn74hc595.jpg SN74HC595 I/O Expander, components/sn74hc595, sn74hc595.jpg + XL9535 I/O Expander, components/xl9535, xl9535.svg SIM800L, components/sim800l, sim800l.jpg DFPlayer, components/dfplayer, dfplayer.svg Captive Portal, components/captive_portal, wifi-strength-alert-outline.svg @@ -826,6 +850,7 @@ Cookbook Sonoff Fishpond Pump, cookbook/sonoff-fishpond-pump, cookbook-sonoff-fishpond-pump.jpg Arduino Port Extender, cookbook/arduino_port_extender, arduino_logo.svg EHMTX a matrix status/text display, cookbook/ehmtx, ehmtx.jpg + Share data directly between ESPHome nodes, cookbook/http_request_sensor, connection.svg Do you have other awesome automations or cool setups? Please feel free to add them to the documentation for others to copy. See :doc:`Contributing `. diff --git a/schema_doc.py b/schema_doc.py index 9dc5869eb33..9607ff4159c 100644 --- a/schema_doc.py +++ b/schema_doc.py @@ -81,6 +81,8 @@ def doctree_resolved(app, doctree, docname): "Stepper": "stepper", "Switch": "switch", "I²C": "i2c", + "Media Player": "media_player", + "Microphone": "microphone", } CUSTOM_DOCS = { @@ -196,6 +198,8 @@ def doctree_resolved(app, doctree, docname): }, } +REQUIRED_OPTIONAL_TYPE_REGEX = r"(\(((\*\*Required\*\*)|(\*Optional\*))(,\s(.*))*)\):\s" + def get_node_title(node): return list(node.traverse(nodes.title))[0].astext() @@ -250,7 +254,6 @@ def __init__(self, app, doctree, docname): ] else: # sub component, e.g. output/esp8266_pwm - # components here might have a core / hub, eg. dallas, ads1115 # and then they can be a binary_sensor, sensor, etc. self.platform = self.path[1] @@ -775,7 +778,6 @@ def visit_bullet_list(self, node): and (self.props or self.multi_component) and self.bullet_list_level > 1 ): - self.prop_stack.append((self.current_prop, node)) self.accept_props = True return @@ -844,7 +846,7 @@ def getMarkdownParagraph(self, node): try: name_type = markdown[: markdown.index(": ") + 2] ntr = re.search( - r"(\(((\*\*Required\*\*)|(\*Optional\*))(,\s(.*))*)\):\s", + REQUIRED_OPTIONAL_TYPE_REGEX, name_type, re.IGNORECASE, ) @@ -875,7 +877,6 @@ def getMarkdownParagraph(self, node): return markdown def update_prop(self, node, props): - prop_name = None for s_prop, n in self.prop_stack: @@ -901,10 +902,10 @@ def update_prop(self, node, props): found = True if enum_docs: enum_docs = enum_docs.strip() - if "values_docs" not in inner: - inner["values_docs"] = {name: enum_docs} + if inner["values"][name] is None: + inner["values"][name] = {"docs": enum_docs} else: - inner["values_docs"][name] = enum_docs + inner["values"][name]["docs"] = enum_docs statistics.props_documented += 1 statistics.enums_good += 1 if not found: @@ -941,12 +942,19 @@ def update_prop(self, node, props): return prop_name, False # Example properties formats are: - # **name** (**Required**, string): Long Description... - # **name** (*Optional*, string): Long Description... Defaults to ``value``. - # **name** (*Optional*): Long Description... Defaults to ``value``. + # **prop_name** (**Required**, string): Long Description... + # **prop_name** (*Optional*, string): Long Description... Defaults to ``value``. + # **prop_name** (*Optional*): Long Description... Defaults to ``value``. + # **prop_name** can be a list of names separated by / e.g. **name1/name2** (*Optional*) see climate/pid/ threshold_low/threshold_high + + PROP_NAME_REGEX = r"\*\*(\w*(?:/\w*)*)\*\*" + + FULL_ITEM_PROP_NAME_TYPE_REGEX = ( + r"\* " + PROP_NAME_REGEX + r"\s" + REQUIRED_OPTIONAL_TYPE_REGEX + ) ntr = re.search( - r"\* \*\*(\w*)\*\*\s(\(((\*\*Required\*\*)|(\*Optional\*))(,\s(.*))*)\):\s", + FULL_ITEM_PROP_NAME_TYPE_REGEX, name_type, re.IGNORECASE, ) @@ -956,14 +964,14 @@ def update_prop(self, node, props): param_type = ntr.group(7) else: s2 = re.search( - r"\* \*\*(\w*)\*\*\s(\(((\*\*Required\*\*)|(\*Optional\*))(,\s(.*))*)\):\s", + FULL_ITEM_PROP_NAME_TYPE_REGEX, markdown, re.IGNORECASE, ) if s2: # this is e.g. when a property has a list inside, and the list inside are the options. # just validate **prop_name** - s3 = re.search(r"\* \*\*(\w*)\*\*:\s", name_type) + s3 = re.search(r"\* " + PROP_NAME_REGEX + r"*:\s", name_type) if s3 is not None: prop_name = s3.group(1) else: @@ -977,61 +985,61 @@ def update_prop(self, node, props): ) return prop_name, False - k = str(prop_name) - - config_var = props.get(k) - - if not config_var: - # Create docs for common properties when descriptions are overridden - # in the most specific component. - - if k in [ - "id", - "name", - "internal", - # i2c - "address", - "i2c_id", - # polling component - "update_interval", - # uart - "uart_id", - # light - "effects", - "gamma_correct", - "default_transition_length", - "flash_transition_length", - "color_correct", - # display - "lambda", - "pages", - "rotation", - # spi - "spi_id", - "cs_pin", - # output (binary/float output) - "inverted", - "power_supply", - # climate - "receiver_id", - ]: - config_var = props[k] = {} - else: - if self.path[1] == "esphome" and k in [ - # deprecated esphome - "platform", - "board", - "arduino_version", - "esp8266_restore_from_flash", + prop_names = str(prop_name) + for k in prop_names.split("/"): + config_var = props.get(k) + + if not config_var: + # Create docs for common properties when descriptions are overridden + # in the most specific component. + + if k in [ + "id", + "name", + "internal", + # i2c + "address", + "i2c_id", + # polling component + "update_interval", + # uart + "uart_id", + # light + "effects", + "gamma_correct", + "default_transition_length", + "flash_transition_length", + "color_correct", + # display + "lambda", + "pages", + "rotation", + # spi + "spi_id", + "cs_pin", + # output (binary/float output) + "inverted", + "power_supply", + # climate + "receiver_id", ]: - return prop_name, True - return prop_name, False - - desc = markdown[markdown.index(": ") + 2 :].strip() - if param_type: - desc = "**" + param_type + "**: " + desc - - config_var["docs"] = desc + config_var = props[k] = {} + else: + if self.path[1] == "esphome" and k in [ + # deprecated esphome + "platform", + "board", + "arduino_version", + "esp8266_restore_from_flash", + ]: + return prop_name, True + return prop_name, False + + desc = markdown[markdown.index(": ") + 2 :].strip() + if param_type: + desc = "**" + param_type + "**: " + desc + + config_var["docs"] = desc statistics.props_documented += 1 @@ -1084,7 +1092,11 @@ def _get_props(self, component, fail_silently): def _find_extended(self, component, key): for extended in component.get("extends", []): - schema = self.visitor.get_component_schema(extended).get("schema", {}) + c = self.visitor.get_component_schema(extended) + if c.get("type") == "typed": + p = self.visitor.Props(self.visitor, c) + return p[key] + schema = c.get("schema", {}) for k, cv in schema.get("config_vars", {}).items(): if k == key: return SetObservable( @@ -1124,7 +1136,7 @@ def __getitem__(self, key): ) def _set_typed(self, inner_key, original_dict, key, value): - if inner_key == self.component.get("typed_key"): + if inner_key == self.component.get("typed_key", "type"): self.component[key] = value else: for tk, tv in self.component["types"].items(): diff --git a/web-api/index.rst b/web-api/index.rst index 481ab6c1ef2..3abe30003cf 100644 --- a/web-api/index.rst +++ b/web-api/index.rst @@ -24,6 +24,8 @@ While it's currently recommended to use ESPHome directly through Home Assistant, to integrate ESPHome with an external or self-built application you can use two available APIs: the real-time event source API and REST API. +.. _api-event-source: + Event Source API ~~~~~~~~~~~~~~~~ @@ -56,6 +58,8 @@ states so that the client can catch up with reality. The payloads of these state events are also the same as the payloads of the REST API GET calls. I would recommend just opening the network debug panel of your web browser to see what's sent. +.. _api-rest: + REST API -------- @@ -297,3 +301,11 @@ method is ``set``. The following parameter can be used: minimum and maximum range of the number otherwise it will be ignored. For example POST ``/number/desired_delay/set?value=24`` will set the number to 24. + +See Also +-------- + +- :doc:`/components/web_server` +- :doc:`/components/prometheus` +- :doc:`/components/http_request` +- :ghedit:`Edit`