diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 3bffa5717e..45e0099628 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -21,7 +21,7 @@ jobs: steps: - uses: actions/checkout@v4.1.0 - name: Set up Python 3.8 - uses: actions/setup-python@v4 + uses: actions/setup-python@v5 with: python-version: 3.8 - name: Install dependencies diff --git a/Doxygen b/Doxygen index f34b621964..8c56823599 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.12.0-dev +PROJECT_NUMBER = 2024.1.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/_static/changelog-2023.12.0.png b/_static/changelog-2023.12.0.png new file mode 100644 index 0000000000..907ecb08ca Binary files /dev/null and b/_static/changelog-2023.12.0.png differ diff --git a/_static/custom.css b/_static/custom.css index b442b6a9e1..451d5cb4b1 100644 --- a/_static/custom.css +++ b/_static/custom.css @@ -256,7 +256,7 @@ div.body p, div.body dd, div.body li, div.body blockquote { background: #212121; color: #ececec; } - + } body, div.body { @@ -281,7 +281,7 @@ div.body p, div.body dd, div.body li, div.body blockquote { color: #ececec; background-color: #212121; } - + a, a.reference, a:visited { color: #00bfff; border-bottom: 1px dotted #00bfff; @@ -326,7 +326,7 @@ div.body p, div.body dd, div.body li, div.body blockquote { color: #e2e2e2; } - div.note, div.tip { + div.note, div.tip, div.important { background-color: #2d2c2c; border: 1px solid #808080; } @@ -339,4 +339,4 @@ div.body p, div.body dd, div.body li, div.body blockquote { background-color: #8e8129; } -} \ No newline at end of file +} diff --git a/_static/version b/_static/version index 2bc414f426..dd273dfb14 100644 --- a/_static/version +++ b/_static/version @@ -1 +1 @@ -2023.12.0-dev \ No newline at end of file +2024.1.0-dev \ No newline at end of file diff --git a/changelog/2023.11.0.rst b/changelog/2023.11.0.rst index b4c58d05f6..fdd02dcf3d 100644 --- a/changelog/2023.11.0.rst +++ b/changelog/2023.11.0.rst @@ -106,6 +106,12 @@ Release 2023.11.5 - November 28 - Add 'voice_assistant.connected' condition :esphomepr:`5845` by :ghuser:`jesserockz` +Release 2023.11.6 - November 28 +------------------------------- + +- Fix write_speaker without speaker in config :esphomepr:`5847` by :ghuser:`jesserockz` + + Full list of changes -------------------- diff --git a/changelog/2023.12.0.rst b/changelog/2023.12.0.rst new file mode 100644 index 0000000000..53e95261ab --- /dev/null +++ b/changelog/2023.12.0.rst @@ -0,0 +1,306 @@ +ESPHome 2023.12.0 - 20th December 2023 +====================================== + +.. seo:: + :description: Changelog for ESPHome 2023.12.0. + :image: /_static/changelog-2023.12.0.png + :author: Jesse Hills + :author_twitter: @jesserockz + +.. imgtable:: + :columns: 3 + + ENS160, components/sensor/ens160, ens160.jpg, CO2 & Air Quality + GT911, components/touchscreen/gt911, esp32_s3_box_3.png + Pylontech Batteries, components/pylontech, pylontech.jpg + HE60R Cover, components/cover/he60r, he60r.jpg + Graphical Display Menu, components/display_menu/graphical_display_menu, graphical_display_menu.jpg + FT63X6, components/touchscreen/ft63x6, wt32-sc01.png + A02YYUW, components/sensor/a02yyuw, a02yyuw.jpg + PN7150, components/binary_sensor/pn7150, pn7150.jpg + PN716X, components/binary_sensor/pn7160, pn716x.jpg + +Graphical Menu +-------------- + +Following on from the previous :doc:`/components/display_menu/lcd_menu` that was only for LCD displays, +there is now a new :doc:`/components/display_menu/graphical_display_menu` that can be used with any +graphical/pixel based display. + +Pin Reuse validation +-------------------- + +There is a new validation performed on configurations to ensure that pins are not reused unintentionally. +This is a common source of issues and generally a pin does not need to be reused across multiple components +in a single configuration. Pins should only be reused in a very limited set of circumstances and seeing the +error will generally mean that you need to reorganise your configuration to not reuse the pins. +The error can be bypassed by specifically adding another config item to all of the +duplicate pin definitions. See the :ref:`config-pin_schema` for details. + +Touchscreen internal changes +---------------------------- + +The touchscreen compoenent code has had a big overhaul which breaks any external components or open PRs for +new touchscreens. See :esphomepr:`4596` for details if this affects you. + +MCP3008 breaking changes +------------------------ + +The MCP3008 has has a restructure of the code and at the same time the default update interval has been changed to 60 seconds, +the units, device class and state class default have also been set to sane defaults expected for a voltage sensor. + +Release 2023.12.1 - December 21 +------------------------------- + +- Fix replaced - in allowed characters during object_id sanitizing :esphomepr:`5983` by :ghuser:`jesserockz` + +Release 2023.12.2 - December 22 +------------------------------- + +- ESP32-S3 and ESP-IDF don't play well with USB_CDC and need USB_SERIAL_JTAG :esphomepr:`5929` by :ghuser:`clydebarrow` +- Update libtiff6 :esphomepr:`5985` by :ghuser:`cvandesande` +- Override GPIOs 12 and 13 on the airm2m (LuatOS) board :esphomepr:`5982` by :ghuser:`davidmonro` +- Add workaround for crash in Arduino 2.0.9 when CDC is configured :esphomepr:`5987` by :ghuser:`kbx81` +- web_server.py: return empty content when file doesn't exist :esphomepr:`5980` by :ghuser:`jessicah` + +Full list of changes +-------------------- + +New Components +^^^^^^^^^^^^^^ + +- Add ENS160 Sensor :esphomepr:`4243` by :ghuser:`vincentscode` (new-integration) +- Create GT911 Touchscreen component :esphomepr:`4027` by :ghuser:`jesserockz` (new-integration) +- Pylontech integration (solar battery bank) :esphomepr:`4688` by :ghuser:`functionpointer` (new-integration) +- Add Chamberlain/HomEntry HE60R garage door opener :esphomepr:`5834` by :ghuser:`clydebarrow` (new-integration) +- Add graphical display menu :esphomepr:`4105` by :ghuser:`MrMDavidson` (new-integration) +- Updating the touchscreen interface structure :esphomepr:`4596` by :ghuser:`nielsnl68` (new-integration) (breaking-change) +- Added the A02YYUW distance sensor :esphomepr:`5729` by :ghuser:`TH-Braemer` (new-integration) +- Add support for PN7160 :esphomepr:`5486` by :ghuser:`kbx81` (new-integration) +- Add support for PN7150 :esphomepr:`5487` by :ghuser:`kbx81` (new-integration) + +Breaking Changes +^^^^^^^^^^^^^^^^ + +- Add proper support for SH1107 to SSD1306 component :esphomepr:`5166` by :ghuser:`nikitakuklev` (breaking-change) +- sen5x fix temperature compensation and gas tuning :esphomepr:`4901` by :ghuser:`matt7aylor` (breaking-change) +- Ensure names containing characters other than `a-z` `A-Z` `0-9` or `_` are unique :esphomepr:`5810` by :ghuser:`bdraco` (breaking-change) +- mcp3008: Tidy up and fix auto load bug :esphomepr:`5842` by :ghuser:`jesserockz` (breaking-change) +- Nextion colors parameters :esphomepr:`5699` by :ghuser:`edwardtfn` (breaking-change) +- Checks for pins used in multiple places :esphomepr:`5666` by :ghuser:`clydebarrow` (breaking-change) +- Updating the touchscreen interface structure :esphomepr:`4596` by :ghuser:`nielsnl68` (new-integration) (breaking-change) + +Beta Changes +^^^^^^^^^^^^ + +- Allow use of CDC/JTAG loggers on esp32 variants with Arduino :esphomepr:`4658` by :ghuser:`jesserockz` +- [Logger] ESP32 S3 serial logger :esphomepr:`4853` by :ghuser:`Fabian-Schmidt` +- Support toggle action for template cover :esphomepr:`5917` by :ghuser:`jochenvg` +- Fix SplitDefault with variants :esphomepr:`5928` by :ghuser:`jesserockz` +- Update ENS160 TVOC device_class and AQI units to match required by HA :esphomepr:`5939` by :ghuser:`mrtoy-me` +- Bump zeroconf from 0.128.4 to 0.130.0 :esphomepr:`5950` by :ghuser:`dependabot[bot]` +- UARTComponent inline doc :esphomepr:`5930` by :ghuser:`edwardtfn` +- Fix - Tuya Fan - Allow integer speed datapoint :esphomepr:`5948` by :ghuser:`cram42` +- i2s_audio: Set player_task's prio to 1 :esphomepr:`5945` by :ghuser:`gaaf` +- esp32_camera: Set framebuffer task prio to 1 :esphomepr:`5943` by :ghuser:`gaaf` +- web_server_idf: fix call with hardcoded http code :esphomepr:`5942` by :ghuser:`dentra` +- Revert pure virtual functions in UART component from #5920 :esphomepr:`5932` by :ghuser:`DrCoolzic` +- Use the correct UART/`Serial` when CDC is enabled :esphomepr:`5957` by :ghuser:`kbx81` +- rename ``set_raw_touch_position_`` to ``add_raw_touch_position_`` :esphomepr:`5962` by :ghuser:`nielsnl68` +- Fix build issue with UART component when building with Arduino and CDC :esphomepr:`5964` by :ghuser:`kbx81` +- Fix ``I2CBus::write()`` bug and add i2c documentation :esphomepr:`5947` by :ghuser:`DrCoolzic` +- Add deep sleep between updates for waveshare epaper 1.54in and 1.54inv2 :esphomepr:`5961` by :ghuser:`mathieu-mp` +- Speed up writing protobuf strings/bytes :esphomepr:`5828` by :ghuser:`bdraco` +- Bump aioesphomeapi to 21.0.1 :esphomepr:`5969` by :ghuser:`bdraco` +- image: allow the image to by auto-loaded by animation :esphomepr:`5139` by :ghuser:`ayufan` +- Fix pin reuse error with pin expanders :esphomepr:`5973` by :ghuser:`jesserockz` + +All changes +^^^^^^^^^^^ + +- Nextion support to ``esp-idf`` :esphomepr:`5667` by :ghuser:`edwardtfn` +- fix pin range for xl9535 :esphomepr:`5722` by :ghuser:`ssieb` +- Bump black from 23.10.1 to 23.11.0 :esphomepr:`5702` by :ghuser:`dependabot[bot]` +- Speed up YAML by using YAML C loader when available :esphomepr:`5721` by :ghuser:`bdraco` +- Bump Arduino Pico Framework to 3.6.0 and Platform to 1.10.0 :esphomepr:`5731` by :ghuser:`HeMan` +- Correct url for Arduino platform :esphomepr:`5744` by :ghuser:`HeMan` +- remote_base: added helper class and schemas :esphomepr:`5169` by :ghuser:`dudanov` +- Bump zeroconf from 0.123.0 to 0.126.0 :esphomepr:`5748` by :ghuser:`dependabot[bot]` +- Make precommit checks happy :esphomepr:`5751` by :ghuser:`HeMan` +- dashboard: Use mdns cache when available if device connection is OTA :esphomepr:`5724` by :ghuser:`bdraco` +- Speed up OTAs :esphomepr:`5720` by :ghuser:`bdraco` +- dashboard: convert ping thread to use asyncio :esphomepr:`5749` by :ghuser:`bdraco` +- dashboard: Break apart dashboard into separate modules :esphomepr:`5764` by :ghuser:`bdraco` +- dashboard: split dashboard web server code into its own module :esphomepr:`5770` by :ghuser:`bdraco` +- Bump zeroconf from 0.126.0 to 0.127.0 :esphomepr:`5768` by :ghuser:`dependabot[bot]` +- dashboard: fix subprocesses blocking the event loop :esphomepr:`5772` by :ghuser:`bdraco` +- dashboard: use fastest available yaml loader in the dashboard :esphomepr:`5771` by :ghuser:`bdraco` +- dashboard: Centralize dashboard entries into DashboardEntries class :esphomepr:`5774` by :ghuser:`bdraco` +- Pass the name to the log runner when available :esphomepr:`5759` by :ghuser:`bdraco` +- Add proper support for SH1107 to SSD1306 component :esphomepr:`5166` by :ghuser:`nikitakuklev` (breaking-change) +- Split release workflow jobs per system arch :esphomepr:`5723` by :ghuser:`jesserockz` +- Bump aioesphomeapi to 18.5.3 :esphomepr:`5785` by :ghuser:`bdraco` +- Refactor log api client to let aioesphomeapi manage zeroconf :esphomepr:`5783` by :ghuser:`bdraco` +- dashboard: Add support for firing events :esphomepr:`5775` by :ghuser:`bdraco` +- dashboard: Ensure disk I/O happens in the executor :esphomepr:`5789` by :ghuser:`bdraco` +- dashboard: Add lookup by name to entries :esphomepr:`5790` by :ghuser:`bdraco` +- Refactor StorageJSON to keep loaded_integrations a set until its converted to JSON :esphomepr:`5793` by :ghuser:`bdraco` +- wifi: Don't build SoftAP/DHCPS support unless 'ap' is in config. :esphomepr:`5649` by :ghuser:`kpfleming` +- ssd1306: handle V_COM differently for SH1106 :esphomepr:`5796` by :ghuser:`papillon81` +- Bump aioesphomeapi from 18.5.3 to 18.5.5 :esphomepr:`5804` by :ghuser:`dependabot[bot]` +- dashboard: Fix online status when api is disabled :esphomepr:`5792` by :ghuser:`bdraco` +- Haier component updated to support new protocol variations :esphomepr:`5713` by :ghuser:`paveldn` +- sen5x fix temperature compensation and gas tuning :esphomepr:`4901` by :ghuser:`matt7aylor` (breaking-change) +- Add startup_delay to interval. :esphomepr:`5327` by :ghuser:`clydebarrow` +- Pillow: bump to 10.1.0 :esphomepr:`5815` by :ghuser:`hostcc` +- dashboard: set nodelay on the websocket to avoid a delay seeing log messages :esphomepr:`5802` by :ghuser:`bdraco` +- Bump aioesphomeapi from 18.5.5 to 18.5.7 :esphomepr:`5822` by :ghuser:`dependabot[bot]` +- Ensure names containing characters other than `a-z` `A-Z` `0-9` or `_` are unique :esphomepr:`5810` by :ghuser:`bdraco` (breaking-change) +- Add ENS160 Sensor :esphomepr:`4243` by :ghuser:`vincentscode` (new-integration) +- Bump actions/github-script from 6.4.1 to 7.0.1 :esphomepr:`5803` by :ghuser:`dependabot[bot]` +- Run all tests when local testing. :esphomepr:`5717` by :ghuser:`Fabian-Schmidt` +- Bump aioesphomeapi from 18.5.7 to 18.5.9 :esphomepr:`5830` by :ghuser:`dependabot[bot]` +- Allow split uart pin inversion for ESP-IDF :esphomepr:`5831` by :ghuser:`clydebarrow` +- Add ``is_detected()`` for Nextion displays :esphomepr:`5825` by :ghuser:`edwardtfn` +- Pull PollingComponent up from individual display drivers to Display. :esphomepr:`5444` by :ghuser:`clydebarrow` +- Implement variable length single word SPI writes. :esphomepr:`5678` by :ghuser:`clydebarrow` +- Add 'enable_on_boot' feature to power_supply :esphomepr:`5826` by :ghuser:`clydebarrow` +- mcp3008: Tidy up and fix auto load bug :esphomepr:`5842` by :ghuser:`jesserockz` (breaking-change) +- Create GT911 Touchscreen component :esphomepr:`4027` by :ghuser:`jesserockz` (new-integration) +- Bump aioesphomeapi from 18.5.9 to 19.1.2 :esphomepr:`5844` by :ghuser:`dependabot[bot]` +- Nextion - Standardizing log messages :esphomepr:`5837` by :ghuser:`edwardtfn` +- dashboard: Small cleanups to dashboard :esphomepr:`5841` by :ghuser:`bdraco` +- Pylontech integration (solar battery bank) :esphomepr:`4688` by :ghuser:`functionpointer` (new-integration) +- Implement deep sleep and clear screen on Waveshare 7.5in B V3 :esphomepr:`5239` by :ghuser:`lucasprim` +- Fix ESP-IDF uart initialisation sequence to match Espressif docs. :esphomepr:`5838` by :ghuser:`clydebarrow` +- Nextion - Align strings on ``dump_config`` :esphomepr:`5824` by :ghuser:`edwardtfn` +- Speed up (and fix) ili9xxx display component. :esphomepr:`5406` by :ghuser:`clydebarrow` +- Fix regex for 'byte' custom CI check :esphomepr:`5851` by :ghuser:`jesserockz` +- Pass through additional arguments to create number :esphomepr:`5849` by :ghuser:`clydebarrow` +- Nextion ``on_touch`` trigger :esphomepr:`5833` by :ghuser:`edwardtfn` +- Nextion colors parameters :esphomepr:`5699` by :ghuser:`edwardtfn` (breaking-change) +- dashboard: fix supervisor auth doing I/O in the event loop :esphomepr:`5807` by :ghuser:`bdraco` +- Improve reliability of Nextion TFT uploads (Arduino) :esphomepr:`5683` by :ghuser:`edwardtfn` +- Add Pro Check Universal sensor support. :esphomepr:`5798` by :ghuser:`spbrogan` +- Bump aioesphomeapi from 19.1.2 to 19.1.7 :esphomepr:`5859` by :ghuser:`dependabot[bot]` +- Pn532 non blocking scan :esphomepr:`5191` by :ghuser:`sharkydog` +- Add Chamberlain/HomEntry HE60R garage door opener :esphomepr:`5834` by :ghuser:`clydebarrow` (new-integration) +- Bump aioesphomeapi from 19.1.7 to 19.2.1 :esphomepr:`5863` by :ghuser:`dependabot[bot]` +- Bump tornado from 6.3.3 to 6.4 :esphomepr:`5862` by :ghuser:`dependabot[bot]` +- add missing ifdef to pvvx_mithermometer :esphomepr:`5880` by :ghuser:`ssieb` +- Fix un-initialized version string :esphomepr:`5865` by :ghuser:`descipher` +- fix a01nyub data reading :esphomepr:`5882` by :ghuser:`ssieb` +- Bump pytest-asyncio from 0.21.1 to 0.23.2 :esphomepr:`5888` by :ghuser:`dependabot[bot]` +- Bump zeroconf from 0.127.0 to 0.128.0 :esphomepr:`5889` by :ghuser:`dependabot[bot]` +- Bump pylint from 2.17.6 to 3.0.2 :esphomepr:`5592` by :ghuser:`dependabot[bot]` +- Bump voluptuous from 0.13.1 to 0.14.1 :esphomepr:`5784` by :ghuser:`dependabot[bot]` +- Security improvement: Support wifi ap_timeout=0s (disable) :esphomepr:`5887` by :ghuser:`fornellas` +- Suppress full config output of "esphome config" when -q option is used. :esphomepr:`5852` by :ghuser:`clydebarrow` +- Checks for pins used in multiple places :esphomepr:`5666` by :ghuser:`clydebarrow` (breaking-change) +- Nextion support to idf with `cinttypes` :esphomepr:`5876` by :ghuser:`edwardtfn` +- Fix test4.yaml after #5666 :esphomepr:`5890` by :ghuser:`kbx81` +- Fix template text component length check :esphomepr:`5881` by :ghuser:`fornellas` +- RC522 - Fix error counter error :esphomepr:`5873` by :ghuser:`kbx81` +- feat(packages): support removing components :esphomepr:`5821` by :ghuser:`TMaYaD` +- dashboard: Add some basic tests for the dashboard :esphomepr:`5870` by :ghuser:`bdraco` +- Nextion exit reparse mode on startup :esphomepr:`5868` by :ghuser:`edwardtfn` +- Bump aioesphomeapi from 19.2.1 to 19.3.0 :esphomepr:`5895` by :ghuser:`dependabot[bot]` +- Add framework info to Nextion log tags :esphomepr:`5864` by :ghuser:`edwardtfn` +- Handle case where using enetity level name: None with MQTT :esphomepr:`5897` by :ghuser:`mtl010957` +- Bump actions/setup-python from 4.7.1 to 5.0.0 :esphomepr:`5896` by :ghuser:`dependabot[bot]` +- Bump zeroconf from 0.128.0 to 0.128.4 :esphomepr:`5906` by :ghuser:`dependabot[bot]` +- Fix 18 bit displays. :esphomepr:`5908` by :ghuser:`clydebarrow` +- fix RGBW Mode on RP2040 :esphomepr:`5907` by :ghuser:`firegore` +- Add graphical display menu :esphomepr:`4105` by :ghuser:`MrMDavidson` (new-integration) +- Added on_image callback to ESP32 Cam :esphomepr:`4860` by :ghuser:`freekode` +- Bump actions/stale from 8.0.0 to 9.0.0 :esphomepr:`5899` by :ghuser:`dependabot[bot]` +- Bump pylint from 3.0.2 to 3.0.3 :esphomepr:`5905` by :ghuser:`dependabot[bot]` +- Bump frenck/action-yamllint from 1.4.1 to 1.4.2 :esphomepr:`5716` by :ghuser:`dependabot[bot]` +- Bump dessant/lock-threads from 4.0.1 to 5.0.1 :esphomepr:`5820` by :ghuser:`dependabot[bot]` +- Add support for fan preset modes :esphomepr:`5694` by :ghuser:`mill1000` +- Fix uninitialized climate target temperature :esphomepr:`5795` by :ghuser:`ckoca` +- Bump aioesphomeapi from 19.3.0 to 20.0.0 :esphomepr:`5911` by :ghuser:`dependabot[bot]` +- Bump black from 23.11.0 to 23.12.0 :esphomepr:`5912` by :ghuser:`dependabot[bot]` +- Updating the touchscreen interface structure :esphomepr:`4596` by :ghuser:`nielsnl68` (new-integration) (breaking-change) +- Added the A02YYUW distance sensor :esphomepr:`5729` by :ghuser:`TH-Braemer` (new-integration) +- Fix AHT10 / AHT20 communication :esphomepr:`5198` by :ghuser:`flaminggoat` +- Fix crash when handling pin_check error :esphomepr:`5915` by :ghuser:`clydebarrow` +- Bump aioesphomeapi to 20.1.0 :esphomepr:`5914` by :ghuser:`bdraco` +- Remove setpoint-change from error when calculating derivative in pid controller :esphomepr:`4737` by :ghuser:`Newspaperman57` +- ir_transmitter: add support for repeated commands in NEC protocol :esphomepr:`4995` by :ghuser:`ngilles` +- BP1658CJ - Fix timing for all platforms, now consistent with other drivers :esphomepr:`5799` by :ghuser:`Cossid` +- Add humidity support to climate :esphomepr:`5732` by :ghuser:`kroimon` +- Remove lingering note :esphomepr:`5916` by :ghuser:`jesserockz` +- Fix typo added in esp32 post_build filename :esphomepr:`5918` by :ghuser:`jesserockz` +- Copy esp32 custom partition files to build folder :esphomepr:`5919` by :ghuser:`jesserockz` +- UART change at runtime :esphomepr:`5909` by :ghuser:`edwardtfn` +- Bump aioesphomeapi from 20.1.0 to 21.0.0 :esphomepr:`5922` by :ghuser:`dependabot[bot]` +- Fix the initial run of lambda light effects :esphomepr:`5921` by :ghuser:`smithjacobj` +- Exposes ``load_settings`` to `UARTComponent` class :esphomepr:`5920` by :ghuser:`edwardtfn` +- Add support for PN7160 :esphomepr:`5486` by :ghuser:`kbx81` (new-integration) +- Add support for PN7150 :esphomepr:`5487` by :ghuser:`kbx81` (new-integration) +- Allow use of CDC/JTAG loggers on esp32 variants with Arduino :esphomepr:`4658` by :ghuser:`jesserockz` +- [Logger] ESP32 S3 serial logger :esphomepr:`4853` by :ghuser:`Fabian-Schmidt` +- Support toggle action for template cover :esphomepr:`5917` by :ghuser:`jochenvg` +- Fix SplitDefault with variants :esphomepr:`5928` by :ghuser:`jesserockz` +- Update ENS160 TVOC device_class and AQI units to match required by HA :esphomepr:`5939` by :ghuser:`mrtoy-me` +- Bump zeroconf from 0.128.4 to 0.130.0 :esphomepr:`5950` by :ghuser:`dependabot[bot]` +- UARTComponent inline doc :esphomepr:`5930` by :ghuser:`edwardtfn` +- Fix - Tuya Fan - Allow integer speed datapoint :esphomepr:`5948` by :ghuser:`cram42` +- i2s_audio: Set player_task's prio to 1 :esphomepr:`5945` by :ghuser:`gaaf` +- esp32_camera: Set framebuffer task prio to 1 :esphomepr:`5943` by :ghuser:`gaaf` +- web_server_idf: fix call with hardcoded http code :esphomepr:`5942` by :ghuser:`dentra` +- Revert pure virtual functions in UART component from #5920 :esphomepr:`5932` by :ghuser:`DrCoolzic` +- Use the correct UART/`Serial` when CDC is enabled :esphomepr:`5957` by :ghuser:`kbx81` +- rename ``set_raw_touch_position_`` to ``add_raw_touch_position_`` :esphomepr:`5962` by :ghuser:`nielsnl68` +- Fix build issue with UART component when building with Arduino and CDC :esphomepr:`5964` by :ghuser:`kbx81` +- Fix I2CBus::write() bug and add i2c documentation :esphomepr:`5947` by :ghuser:`DrCoolzic` +- Add deep sleep between updates for waveshare epaper 1.54in and 1.54inv2 :esphomepr:`5961` by :ghuser:`mathieu-mp` +- Speed up writing protobuf strings/bytes :esphomepr:`5828` by :ghuser:`bdraco` +- Bump aioesphomeapi to 21.0.1 :esphomepr:`5969` by :ghuser:`bdraco` +- image: allow the image to by auto-loaded by animation :esphomepr:`5139` by :ghuser:`ayufan` +- Fix pin reuse error with pin expanders :esphomepr:`5973` by :ghuser:`jesserockz` + +Past Changelogs +--------------- + +- :doc:`2023.11.0` +- :doc:`2023.10.0` +- :doc:`2023.9.0` +- :doc:`2023.8.0` +- :doc:`2023.7.0` +- :doc:`2023.6.0` +- :doc:`2023.5.0` +- :doc:`2023.4.0` +- :doc:`2023.3.0` +- :doc:`2023.2.0` +- :doc:`2022.12.0` +- :doc:`2022.11.0` +- :doc:`2022.10.0` +- :doc:`2022.9.0` +- :doc:`2022.8.0` +- :doc:`2022.6.0` +- :doc:`2022.5.0` +- :doc:`2022.4.0` +- :doc:`2022.3.0` +- :doc:`2022.2.0` +- :doc:`2022.1.0` +- :doc:`2021.12.0` +- :doc:`2021.11.0` +- :doc:`2021.10.0` +- :doc:`2021.9.0` +- :doc:`2021.8.0` +- :doc:`v1.20.0` +- :doc:`v1.19.0` +- :doc:`v1.18.0` +- :doc:`v1.17.0` +- :doc:`v1.16.0` +- :doc:`v1.15.0` +- :doc:`v1.14.0` +- :doc:`v1.13.0` +- :doc:`v1.12.0` +- :doc:`v1.11.0` +- :doc:`v1.10.0` +- :doc:`v1.9.0` +- :doc:`v1.8.0` +- :doc:`v1.7.0` diff --git a/changelog/index.rst b/changelog/index.rst index 75b72a8433..6549def71f 100644 --- a/changelog/index.rst +++ b/changelog/index.rst @@ -2,7 +2,7 @@ Changelog ========= .. redirect:: - :url: /changelog/2023.11.0.html + :url: /changelog/2023.12.0.html .. toctree:: :glob: diff --git a/components/alarm_control_panel/index.rst b/components/alarm_control_panel/index.rst index 24610ace1d..af178a8b14 100644 --- a/components/alarm_control_panel/index.rst +++ b/components/alarm_control_panel/index.rst @@ -44,6 +44,11 @@ Configuration variables: when the alarm state changes to ``disarmed``. See :ref:`alarm_control_panel_on_disarmed_trigger`. - **on_cleared** (*Optional*, :ref:`Action `): An automation to perform when the alarm clears. See :ref:`alarm_control_panel_on_cleared_trigger`. +- **on_ready** (*Optional*, :ref:`Action `): An automation to perform + when the logical 'and' of all the zone sensors change state. See :ref:`alarm_control_panel_on_ready_trigger`. +- **on_chime** (*Optional*, :ref:`Action `): An automation to perform + when a zone has been marked as chime in the configuration, and it changes from closed to open. + See :ref:`alarm_control_panel_on_chime_trigger`. Automation: @@ -184,6 +189,39 @@ This trigger is activated when the alarm changes from to disarmed. then: - logger.log: "Alarm Disarmed!" +.. _alarm_control_panel_on_ready_trigger: + +``on_ready`` Trigger +******************** + +This trigger is activated when the logical 'and' of all the alarm sensors change state. This is useful for implementing "alarm ready" LEDs. +Once this trigger is called, you can get the ready state by calling get_all_sensors_ready() in a lambda block. + +.. code-block:: yaml + + alarm_control_panel: + # ... + on_disarmed: + then: + - lambda: !lambda |- + ESP_LOGI("AlarmPanel", "Sensor ready change to: %s", ((id(acp1).get_all_sensors_ready()) ? (const char *) "True" : (const char *) "False")); + +.. _alarm_control_panel_on_chime_trigger: + +``on_chime`` Trigger +******************** + +This trigger is activated when a zone sensor marked with chime:true changes from closed to open. This is useful for implementing keypad chimes when a zone +opens. + +.. code-block:: yaml + + alarm_control_panel: + # ... + on_chime: + then: + - logger.log: "Alarm Chime!" + .. _alarm_control_panel_arm_away_action: ``arm_away`` Action @@ -296,6 +334,7 @@ From :ref:`lambdas `, you can call the following methods: - ``arm_home(code)`` - ``arm_night(code)`` - ``disarm(code)`` +- ``get_all_sensors_ready()`` .. code-block:: cpp @@ -303,6 +342,7 @@ From :ref:`lambdas `, you can call the following methods: id(acp1).arm_home(); id(acp1).arm_night(); id(acp1).disarm(std::string("1234")); + bool all_sensors_ready = id(acp1).get_all_sensors_ready(); Platforms diff --git a/components/alarm_control_panel/template.rst b/components/alarm_control_panel/template.rst index 71d214d469..91796ff958 100644 --- a/components/alarm_control_panel/template.rst +++ b/components/alarm_control_panel/template.rst @@ -36,6 +36,8 @@ Configuration variables: - **input** (**Required**, string): The id of the binary sensor component - **bypass_armed_home** (*Optional*, boolean): This binary sensor will not trigger the alarm when in ``armed_home`` state. - **bypass_armed_night** (*Optional*, boolean): This binary sensor will not trigger the alarm when in ``armed_night`` state. + - **trigger_mode** (*Optional*, string): Sets the trigger mode for this sensor. One of ``delayed``, ``instant``, or ``delayed_follower``. (``delayed`` is the default if not specified) + - **chime** (*Optional*, boolean): When set ``true``, the chime callback will be called whenever the sensor goes from closed to open. (``false`` is the default if not specified) - **restore_mode** (*Optional*, enum): @@ -46,9 +48,33 @@ Configuration variables: .. note:: - If ``binary_sensors`` is ommited then you're expected to trigger the alarm using + If ``binary_sensors`` is omitted 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-trigger_modes: + +Trigger Modes +------------- + +Each binary sensor "zone" supports 3 trigger modes. The 3 trigger modes are: + +- delayed +- instant +- delayed_follower + +The ``delayed`` trigger mode is typically specified for exterior doors where entry is required to access an alarm keypad or other arm/disarm method. If the alarm panel is armed, and a zone set to ``delayed`` is "faulted" (i.e. the zone state is ``true``) the alarm state will change from the ``armed`` state to the ``pending`` state. During the ``pending`` state, the user has a preset time to disarm the alarm before it changes to the ``triggered`` state. This is the default trigger mode if not specified. + +The ``instant`` trigger mode is typically used for exterior zones (e.g. windows, and glass break detectors). If the alarm control panel is armed, a fault on this type of zone will cause the alarm to go from the ``armed`` state directly to the ``triggered`` state. + +The ``delayed_follower`` trigger mode is typically specifed for interior passive infared (PIR) or microwave sensors. One of two things happen when a ``delayed_follower`` zone is faulted: + +1. When the alarm panel is in the armed state, a fault on a zone with ``delayed_follower`` specified will cause the alarm control panel to go directly to the ``triggered`` state. + +2. When the alarm panel is in the pending state, a fault on a zone with ``delayed_follower`` specified will remain in the ``pending`` state. + +The ``delayed_follower`` trigger mode offers better protection if someone enters a premises via an unprotected window or door. If there is a PIR guarding the main hallway, it will cause an instant trigger of the alarm panel as someone +entered the premises in a unusual manner. Likewise, if someone enters the premises though a door set to the ``delayed`` trigger mode, and then triggers the PIR, the alarm will stay in the ``pending`` state until either they disarm the alarm, or +the pending timer expires. .. _template_alarm_control_panel-state_flow: @@ -63,18 +89,29 @@ State Flow: 3. When the alarm is tripped by a sensor state changing to ``on`` or ``alarm_control_panel_pending_action`` invoked - 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`` + 1. If trigger_mode is set to ``delayed``: + + 1. ``pending_time`` greater than 0 the state is ``PENDING`` + 2. ``pending_time`` is 0 or after the ``pending_time`` delay the state is ``TRIGGERED`` + + 2. If trigger_mode is set to ``instant``: + + 1. The state is set to ``TRIGGERED`` + + 3. If the trigger_mode is set to ``interior_follower``: + + 1. If the current state is ``ARMED_...`` the state will be set to ``TRIGGERED`` + 2. If the current state is ``PENDING`` then nothing will happen and it will stay in the ``PENDING`` state. 4. If ``trigger_time`` greater than 0 and no sensors are ``on`` after ``trigger_time`` delay the state returns to ``ARM_...`` .. note:: - Although the interface supports all arming modes only ``away`` and ``home`` have been implemented for now. + Although the interface supports all arming modes only ``away``, ``home`` and ``night`` have been implemented for now. ``arm_...`` is for either ``arm_away`` or ``arm_home`` - ``arming_..._time`` is for either ``arming_away_time`` or ``arming_home_time`` - ``ARMED_...`` is for either ``ARMED_AWAY`` or ``ARMED_HOME`` + ``arming_..._time`` is for either ``arming_away_time``, ``arming_home_time``, or ``arming_night_time`` + ``ARMED_...`` is for either ``ARMED_AWAY``, ``ARMED_HOME``, or ``ARMED_NIGHT`` Example: @@ -95,8 +132,16 @@ Example: trigger_time: 5min binary_sensors: - input: zone_1 + chime: true + trigger_mode: delayed - input: zone_2 + chime: true + trigger_mode: delayed + - input: zone_3 bypass_armed_home: true + trigger_mode: delayed_follower + - input: zone_4 + trigger_mode: instant - input: ha_test on_state: then: @@ -108,6 +153,15 @@ Example: on_cleared: then: - switch.turn_off: siren + on_ready: + then: + - lambda: !lambda |- + ESP_LOGD("TEST", "Sensor ready change to: %s", + (id(acp1).get_all_sensors_ready())) ? (const char *) "True" : (const char *) "False"); + on_chime: + then: + - lambda: !lambda |- + ESP_LOGD("TEST", "Zone with chime mode set opened"); binary_sensor: - platform: gpio @@ -121,14 +175,30 @@ Example: - platform: gpio id: zone_2 name: Zone 2 - device_class: motion + device_class: door pin: number: D2 mode: INPUT_PULLUP inverted: True + - platform: gpio + id: zone_3 + name: Zone 3 + device_class: motion + pin: + number: D3 + mode: INPUT_PULLUP + inverted: True + - platform: gpio + id: zone_4 + name: Zone 4 + device_class: door + pin: + number: D4 + mode: INPUT_PULLUP + inverted: True - platform: homeassistant id: ha_test - name: Zone 3 + name: HA Test entity_id: input_boolean.test_switch switch: diff --git a/components/binary_sensor/images/pn7150-full.jpg b/components/binary_sensor/images/pn7150-full.jpg new file mode 100644 index 0000000000..da4a97241d Binary files /dev/null and b/components/binary_sensor/images/pn7150-full.jpg differ diff --git a/components/binary_sensor/images/pn716x-full.jpg b/components/binary_sensor/images/pn716x-full.jpg new file mode 100644 index 0000000000..da4a97241d Binary files /dev/null and b/components/binary_sensor/images/pn716x-full.jpg differ diff --git a/components/binary_sensor/index.rst b/components/binary_sensor/index.rst index cd6611fb25..bfbdf14eb1 100644 --- a/components/binary_sensor/index.rst +++ b/components/binary_sensor/index.rst @@ -208,6 +208,16 @@ Specify any :ref:`lambda ` for more complex filters. The input va the binary sensor is ``x`` and you can return ``true`` for ON, ``false`` for OFF, and ``{}`` to stop the filter chain. +``settle`` +********** + +(**Required**, time, :ref:`templatable `): When a signal is received, publish the state +but wait for the received state to remain the same for specified time period before publishing any +additional state changes. This filter complements the ``delayed_on_off`` filter but publishes value changes at +the beginning of the delay period. +When using a lambda call, you should return the delay value in milliseconds. +**Useful for debouncing binary switches**. + Binary Sensor Automation ------------------------ diff --git a/components/binary_sensor/pn7150.rst b/components/binary_sensor/pn7150.rst new file mode 100644 index 0000000000..3fafd6d668 --- /dev/null +++ b/components/binary_sensor/pn7150.rst @@ -0,0 +1,379 @@ +PN7150 NFC +========== + +.. seo:: + :description: Instructions for setting up PN7150 NFC tag readers and tags in ESPHome + :image: pn7150.jpg + :keywords: PN7150, NFC, RFID + +.. _pn7150-component: + +Component/Hub +------------- + +The ``pn7150`` component allows you to use PN7150 NFC controllers with ESPHome. This component is a global hub that +establishes a connection to the PN7150 via :ref:`I²C `. + +.. figure:: images/pn7150-full.jpg + :align: center + :width: 70.0% + +An :ref:`I²C ` bus must be defined within your device's ESPHome configuration to use the PN7150. + +ESPHome supports both card/tag reading/writing as well as card/tag emulation with this component. By default, +only read/write mode is enabled; card/tag emulation is enabled only if the ``emulation_message`` configuration +variable is defined (see below). Regardless, reader/writer (polling) mode and card/tag emulation mode may be +independently enabled and disabled by using the corresponding :ref:`pn7150-actions` (see below). + +.. code-block:: yaml + + pn7150_i2c: + dwl_req_pin: 17 + irq_pin: 35 + ven_pin: 16 + wkup_req_pin: 21 + emulation_message: https://www.home-assistant.io/tag/pulse_ce + tag_ttl: 1000ms + +Configuration variables: +************************ + +- **dwl_req_pin** (*Optional*, :ref:`Pin Schema `): The pin connected to the PN7150's + ``DWL_REQ`` line. Used to invoke the PN7150's firmware update mode; may be used in a future release. +- **irq_pin** (**Required**, :ref:`Pin Schema `): The pin connected to the PN7150's ``IRQ`` line. +- **ven_pin** (**Required**, :ref:`Pin Schema `): The pin connected to the PN7150's ``VEN`` line. +- **wkup_req_pin** (*Optional*, :ref:`Pin Schema `): The pin connected to the PN7150's + ``WKUP_REQ`` line. May be used to improve power management in a future release. +- **emulation_message** (*Optional*, string): When scanned by another NFC card/tag reader (such as a smartphone), this + string is used as the content for an NDEF-formatted response. This allows the PN7150 to act as a tag in addition to a + tag reader/writer. +- **tag_ttl** (*Optional*, :ref:`config-time`): The duration that must elapse after the PN7150 is no longer able to + "see" a tag before it is considered to have been removed from the reader. +- **on_tag** (*Optional*, :ref:`Automation `): An automation to perform when a tag is first read. See + :ref:`pn7150-on_tag`. +- **on_tag_removed** (*Optional*, :ref:`Automation `): An automation to perform after a tag is removed. See + :ref:`pn7150-on_tag_removed`. +- **on_emulated_tag_scan** (*Optional*, :ref:`Automation `): An automation to perform when the PN7150 is + scanned by another tag reader (such as a smartphone). See :ref:`pn7150-on_emulated_tag_scan`. +- **i2c_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`I²C Component ` if you need + to use multiple I²C buses. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID for this component. + + +.. _pn7150-actions: + +Actions +------- + +.. _pn7150-set_clean_mode: + +``tag.set_clean_mode`` Action +***************************** + +Use this action to invoke "clean mode" -- the next tag presented to the PN7150 will be "cleaned", removing all data +from the tag. + +.. code-block:: yaml + + on_...: + then: + - tag.set_clean_mode: my_pn7150_id + +.. _pn7150-set_format_mode: + +``tag.set_format_mode`` Action +****************************** + +Use this action to invoke "format mode" -- the next tag presented to the PN7150 will be "formatted", leaving only an +empty NDEF message structure on the tag. + +.. code-block:: yaml + + on_...: + then: + - tag.set_format_mode: my_pn7150_id + +.. _pn7150-set_read_mode: + +``tag.set_read_mode`` Action +**************************** + +Use this action to invoke "read mode" -- the next tag presented to the PN7150 will be read. This is the default mode +that the component operates in. + +.. code-block:: yaml + + on_...: + then: + - tag.set_read_mode: my_pn7150_id + +.. _pn7150-set_write_message: + +``tag.set_write_message`` Action +******************************** + +Use this action to set the NDEF message used for "write mode" (see below). + +.. code-block:: yaml + + on_...: + then: + - tag.set_write_message: + message: https://www.home-assistant.io/tag/pulse + include_android_app_record: false + +- **message** (**Required**, string, templatable): The string to include in the tag's first NDEF record; typically + a URL as shown. +- **include_android_app_record** (*Optional*, boolean): Include a second NDEF record required for some Android + operating systems. Defaults to ``true``. + +.. _pn7150-set_write_mode: + +``tag.set_write_mode`` Action +***************************** + +Use this action to invoke "write mode" -- the next tag presented to the PN7150 will have its NDEF message set to the +message defined by the ``tag.set_write_message`` action (see above). **Note that a message must be set before this mode +may be invoked.** + +.. code-block:: yaml + + on_...: + then: + - tag.set_write_mode: my_pn7150_id + +.. _pn7150-set_emulation_message: + +``tag.set_emulation_message`` Action +************************************ + +Use this action to set the NDEF message used for card (tag) emulation mode, when enabled (see below). + +.. code-block:: yaml + + on_...: + then: + - tag.set_emulation_message: + message: https://www.home-assistant.io/tag/pulse + include_android_app_record: false + +- **message** (**Required**, string, templatable): The string to include in the (emulated) tag's first NDEF record; + typically a URL as shown. +- **include_android_app_record** (*Optional*, boolean): Include a second NDEF record required for some Android + operating systems. Defaults to ``true``. + +.. _pn7150-emulation_off: + +``tag.emulation_off`` Action +**************************** + +Use this action to disable card (tag) emulation mode. The PN7150 will no longer respond to requests from other readers, +such as smartphones. + +.. code-block:: yaml + + on_...: + then: + - tag.emulation_off: my_pn7150_id + +.. _pn7150-emulation_on: + +``tag.emulation_on`` Action +*************************** + +Use this action to enable card (tag) emulation mode. The PN7150 will respond to requests from other readers, such as +smartphones. + +**Note:** when card/tag emulation is enabled, polling (detecting a nearby card/tag) frequency is decreased; this +typically results in slightly slower detection of cards/tags presented to the PN7150. This behavior is normal and should +be expected; it is the result of the PN7150 toggling between polling and listening modes to support both functions. + +.. code-block:: yaml + + on_...: + then: + - tag.emulation_on: my_pn7150_id + +.. _pn7150-polling_off: + +``tag.polling_off`` Action +**************************** + +Use this action to disable card (tag) reading/writing. The PN7150 will no longer read or write cards/tags. + +.. code-block:: yaml + + on_...: + then: + - tag.polling_off: my_pn7150_id + +.. _pn7150-polling_on: + +``tag.polling_on`` Action +*************************** + +Use this action to enable card (tag) reading/writing. The PN7150 will read or write cards/tags. + +.. code-block:: yaml + + on_...: + then: + - tag.polling_on: my_pn7150_id + +Triggers +-------- + +.. _pn7150-on_tag: + +``on_tag`` Trigger +****************** + +This automation will be triggered immediately after the PN7150 module identifies a tag and reads its NDEF +message (if one is present). + +The parameter ``x`` this trigger provides is of type ``std::string`` and is the tag UID in the format +``74-10-37-94``. The example configuration below will publish the tag ID on the MQTT topic ``pn7150/tag``. + +See :ref:`pn7150-ndef_reading` below for how to use the second ``tag`` parameter that is provided to this trigger. + +.. code-block:: yaml + + pn7150_i2c: + # ... + on_tag: + then: + - mqtt.publish: + topic: pn7150/tag + payload: !lambda 'return x;' + +A tag scanned event can also be sent to the Home Assistant tag component +using :ref:`api-homeassistant_tag_scanned_action`. + +.. code-block:: yaml + + pn7150_i2c: + # ... + on_tag: + then: + - homeassistant.tag_scanned: !lambda 'return x;' + +You could also send the value to Home Assistant via a :doc:`template sensor `: + +.. code-block:: yaml + + pn7150_i2c: + # ... + on_tag: + then: + - text_sensor.template.publish: + id: nfc_tag + state: !lambda 'return x;' + + text_sensor: + - platform: template + name: "NFC Tag" + id: nfc_tag + +.. _pn7150-on_tag_removed: + +``on_tag_removed`` Trigger +************************** + +This automation will be triggered after the ``tag_ttl`` interval (see above) when the PN7150 no longer "sees" a +previously scanned tag. + +The parameter ``x`` this trigger provides is of type ``std::string`` and is the removed tag UID in the format +``74-10-37-94``. The example configuration below will publish the removed tag ID on the MQTT topic ``pn7150/tag_removed``. + +.. code-block:: yaml + + pn7150_i2c: + # ... + on_tag_removed: + then: + - mqtt.publish: + topic: pn7150/tag_removed + payload: !lambda 'return x;' + +.. _pn7150-on_emulated_tag_scan: + +``on_emulated_tag_scan`` Trigger +******************************** + +If card/tag emulation is enabled, this automation will be triggered when another reader (such as a smartphone) scans +the PN7150 and reads the NDEF message it responds with. No parameters are available to this action because data is only +sent *from* the PN7150 *to* the scanning device. + +.. code-block:: yaml + + pn7150_i2c: + # ... + on_emulated_tag_scan: + then: + - rtttl.play: "alert:d=32,o=5,b=160:e6,p,e6,p,e6" + +.. _pn7150-ndef: + +NDEF +==== + +The PN7150 supports reading NDEF messages from and writing NDEF messages to cards/tags. + +.. _pn7150-ndef_reading: + +NDEF Reading +------------ + +Given an NFC tag formatted and written using the Home Assistant Companion App, the following example will send the tag +ID contained within its NDEF message to Home Assistant using the :ref:`api-homeassistant_tag_scanned_action`. +If no NDEF record is found with a tag ID, the tag's UID will be sent to Home Assistant, instead. + +The ``tag`` variable is available to any actions that run within the ``on_tag`` and ``on_tag_removed`` triggers. + +.. code-block:: yaml + + pn7150_i2c: + # ... + on_tag: + then: + - homeassistant.tag_scanned: !lambda "return tag.has_ha_tag_id() ? tag.get_ha_tag_id() : x;" + +.. _pn7150-ndef_writing: + +NDEF Writing +------------ + +The examples below illustrate how NDEF messages may be written to cards/tags via the PN7150. Note that a +:doc:`button ` is a great mechanism to use to trigger these actions. + +The first example will write a simple, fixed NDEF message to a tag. + +.. code-block:: yaml + + on_... + then: + - tag.set_write_message: + message: https://www.home-assistant.io/tag/pulse + include_android_app_record: false # optional + - tag.set_write_mode: my_pn7150_id + +The next example can be used to write a (pseudo) random UUID to a tag in the same manner as the Home Assistant +Companion App. + +.. code-block:: yaml + + on_... + then: + - tag.set_write_message: + message: !lambda "return nfc::get_random_ha_tag_ndef();" + - tag.set_write_mode: my_pn7150_id + +See Also +-------- + +- :doc:`index` +- :doc:`pn532` +- :doc:`rc522` +- :doc:`rdm6300` +- :apiref:`pn7150/pn7150.h` +- :ghedit:`Edit` diff --git a/components/binary_sensor/pn7160.rst b/components/binary_sensor/pn7160.rst new file mode 100644 index 0000000000..674ee66937 --- /dev/null +++ b/components/binary_sensor/pn7160.rst @@ -0,0 +1,437 @@ +PN7160 NFC +========== + +.. seo:: + :description: Instructions for setting up PN7160 NFC tag readers and tags in ESPHome + :image: pn716x.jpg + :keywords: PN7160, NFC, RFID + +.. _pn7160-component: + +Component/Hub +------------- + +The ``pn7160`` component allows you to use PN7160 NFC controllers with ESPHome. This component is a global hub that +establishes a connection to the PN7160 via :ref:`SPI ` or :ref:`I²C `. + +.. figure:: images/pn716x-full.jpg + :align: center + :width: 70.0% + +Within ESPHome, the PN7160 can be configured to use either the SPI **or** I²C protocol for data communication. +Note that there are different versions of the IC for each bus type, each with a different part number; in other +words, **the bus type cannot be changed by jumpers/switches as it is determed at the time of manufacture.** + +You must determine which version of the IC you have and then configure the corresponding bus -- either the +:ref:`SPI bus ` or the :ref:`I²C bus `. + +ESPHome supports both card/tag reading/writing as well as card/tag emulation with this component. By default, +only read/write mode is enabled; card/tag emulation is enabled only if the ``emulation_message`` configuration +variable is defined (see below). Regardless, reader/writer (polling) mode and card/tag emulation mode may be +independently enabled and disabled by using the corresponding :ref:`pn7160-actions` (see below). + +.. _pn7160-spi: + +Over SPI +-------- + +The ``pn7160_spi`` component allows you to use :ref:`SPI-equipped ` PN7160 NFC controllers with with ESPHome. + +.. code-block:: yaml + + pn7160_spi: + cs_pin: 15 + dwl_req_pin: 17 + irq_pin: 35 + ven_pin: 16 + wkup_req_pin: 21 + emulation_message: https://www.home-assistant.io/tag/pulse_ce + tag_ttl: 1000ms + +Configuration variables: +************************ + +- **cs_pin** (**Required**, :ref:`Pin Schema `): The pin connected to the PN7160's ``NSS`` (chip + select) line. +- **dwl_req_pin** (*Optional*, :ref:`Pin Schema `): The pin connected to the PN7160's + ``DWL_REQ`` line. Used to invoke the PN7160's firmware update mode; may be used in a future release. +- **irq_pin** (**Required**, :ref:`Pin Schema `): The pin connected to the PN7160's ``IRQ`` line. +- **ven_pin** (**Required**, :ref:`Pin Schema `): The pin connected to the PN7160's ``VEN`` line. +- **wkup_req_pin** (*Optional*, :ref:`Pin Schema `): The pin connected to the PN7160's + ``WKUP_REQ`` line. May be used to improve power management in a future release. +- **emulation_message** (*Optional*, string): When scanned by another NFC card/tag reader (such as a smartphone), this + string is used as the content for an NDEF-formatted response. This allows the PN7160 to act as a tag in addition to a + tag reader/writer. +- **tag_ttl** (*Optional*, :ref:`config-time`): The duration that must elapse after the PN7160 is no longer able to + "see" a tag before it is considered to have been removed from the reader. +- **on_tag** (*Optional*, :ref:`Automation `): An automation to perform when a tag is first read. See + :ref:`pn7160-on_tag`. +- **on_tag_removed** (*Optional*, :ref:`Automation `): An automation to perform after a tag is removed. See + :ref:`pn7160-on_tag_removed`. +- **on_emulated_tag_scan** (*Optional*, :ref:`Automation `): An automation to perform when the PN7160 is + scanned by another tag reader (such as a smartphone). See :ref:`pn7160-on_emulated_tag_scan`. +- **spi_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`SPI Component ` if you want + to use multiple SPI buses. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID for this component. + +.. _pn7160-i2c: + +Over I²C +-------- + +The ``pn7160_i2c`` component allows you to use :ref:`I²C-equipped ` PN7160 NFC controllers with ESPHome. + + +.. code-block:: yaml + + pn7160_i2c: + dwl_req_pin: 17 + irq_pin: 35 + ven_pin: 16 + wkup_req_pin: 21 + emulation_message: https://www.home-assistant.io/tag/pulse_ce + tag_ttl: 1000ms + +Configuration variables: +************************ + +- **dwl_req_pin** (*Optional*, :ref:`Pin Schema `): The pin connected to the PN7160's + ``DWL_REQ`` line. Used to invoke the PN7160's firmware update mode; may be used in a future release. +- **irq_pin** (**Required**, :ref:`Pin Schema `): The pin connected to the PN7160's ``IRQ`` line. +- **ven_pin** (**Required**, :ref:`Pin Schema `): The pin connected to the PN7160's ``VEN`` line. +- **wkup_req_pin** (*Optional*, :ref:`Pin Schema `): The pin connected to the PN7160's + ``WKUP_REQ`` line. May be used to improve power management in a future release. +- **emulation_message** (*Optional*, string): When scanned by another NFC card/tag reader (such as a smartphone), this + string is used as the content for an NDEF-formatted response. This allows the PN7160 to act as a tag in addition to a + tag reader/writer. +- **tag_ttl** (*Optional*, :ref:`config-time`): The duration that must elapse after the PN7160 is no longer able to + "see" a tag before it is considered to have been removed from the reader. +- **on_tag** (*Optional*, :ref:`Automation `): An automation to perform when a tag is first read. See + :ref:`pn7160-on_tag`. +- **on_tag_removed** (*Optional*, :ref:`Automation `): An automation to perform after a tag is removed. See + :ref:`pn7160-on_tag_removed`. +- **on_emulated_tag_scan** (*Optional*, :ref:`Automation `): An automation to perform when the PN7160 is + scanned by another tag reader (such as a smartphone). See :ref:`pn7160-on_emulated_tag_scan`. +- **i2c_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`I²C Component ` if you need + to use multiple I²C buses. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID for this component. + + +.. _pn7160-actions: + +Actions +------- + +.. _pn7160-set_clean_mode: + +``tag.set_clean_mode`` Action +***************************** + +Use this action to invoke "clean mode" -- the next tag presented to the PN7160 will be "cleaned", removing all data +from the tag. + +.. code-block:: yaml + + on_...: + then: + - tag.set_clean_mode: my_pn7160_id + +.. _pn7160-set_format_mode: + +``tag.set_format_mode`` Action +****************************** + +Use this action to invoke "format mode" -- the next tag presented to the PN7160 will be "formatted", leaving only an +empty NDEF message structure on the tag. + +.. code-block:: yaml + + on_...: + then: + - tag.set_format_mode: my_pn7160_id + +.. _pn7160-set_read_mode: + +``tag.set_read_mode`` Action +**************************** + +Use this action to invoke "read mode" -- the next tag presented to the PN7160 will be read. This is the default mode +that the component operates in. + +.. code-block:: yaml + + on_...: + then: + - tag.set_read_mode: my_pn7160_id + +.. _pn7160-set_write_message: + +``tag.set_write_message`` Action +******************************** + +Use this action to set the NDEF message used for "write mode" (see below). + +.. code-block:: yaml + + on_...: + then: + - tag.set_write_message: + message: https://www.home-assistant.io/tag/pulse + include_android_app_record: false + +- **message** (**Required**, string, templatable): The string to include in the tag's first NDEF record; typically + a URL as shown. +- **include_android_app_record** (*Optional*, boolean): Include a second NDEF record required for some Android + operating systems. Defaults to ``true``. + +.. _pn7160-set_write_mode: + +``tag.set_write_mode`` Action +***************************** + +Use this action to invoke "write mode" -- the next tag presented to the PN7160 will have its NDEF message set to the +message defined by the ``tag.set_write_message`` action (see above). **Note that a message must be set before this mode +may be invoked.** + +.. code-block:: yaml + + on_...: + then: + - tag.set_write_mode: my_pn7160_id + +.. _pn7160-set_emulation_message: + +``tag.set_emulation_message`` Action +************************************ + +Use this action to set the NDEF message used for card (tag) emulation mode, when enabled (see below). + +.. code-block:: yaml + + on_...: + then: + - tag.set_emulation_message: + message: https://www.home-assistant.io/tag/pulse + include_android_app_record: false + +- **message** (**Required**, string, templatable): The string to include in the (emulated) tag's first NDEF record; + typically a URL as shown. +- **include_android_app_record** (*Optional*, boolean): Include a second NDEF record required for some Android + operating systems. Defaults to ``true``. + +.. _pn7160-emulation_off: + +``tag.emulation_off`` Action +**************************** + +Use this action to disable card (tag) emulation mode. The PN7160 will no longer respond to requests from other readers, +such as smartphones. + +.. code-block:: yaml + + on_...: + then: + - tag.emulation_off: my_pn7160_id + +.. _pn7160-emulation_on: + +``tag.emulation_on`` Action +*************************** + +Use this action to enable card (tag) emulation mode. The PN7160 will respond to requests from other readers, such as +smartphones. + +**Note:** when card/tag emulation is enabled, polling (detecting a nearby card/tag) frequency is decreased; this +typically results in slightly slower detection of cards/tags presented to the PN7160. This behavior is normal and should +be expected; it is the result of the PN7160 toggling between polling and listening modes to support both functions. + +.. code-block:: yaml + + on_...: + then: + - tag.emulation_on: my_pn7160_id + +.. _pn7160-polling_off: + +``tag.polling_off`` Action +**************************** + +Use this action to disable card (tag) reading/writing. The PN7160 will no longer read or write cards/tags. + +.. code-block:: yaml + + on_...: + then: + - tag.polling_off: my_pn7160_id + +.. _pn7160-polling_on: + +``tag.polling_on`` Action +*************************** + +Use this action to enable card (tag) reading/writing. The PN7160 will read or write cards/tags. + +.. code-block:: yaml + + on_...: + then: + - tag.polling_on: my_pn7160_id + +Triggers +-------- + +.. _pn7160-on_tag: + +``on_tag`` Trigger +****************** + +This automation will be triggered immediately after the PN7160 module identifies a tag and reads its NDEF +message (if one is present). + +The parameter ``x`` this trigger provides is of type ``std::string`` and is the tag UID in the format +``74-10-37-94``. The example configuration below will publish the tag ID on the MQTT topic ``pn7160/tag``. + +See :ref:`pn7160-ndef_reading` below for how to use the second ``tag`` parameter that is provided to this trigger. + +.. code-block:: yaml + + pn7160_...: + # ... + on_tag: + then: + - mqtt.publish: + topic: pn7160/tag + payload: !lambda 'return x;' + +A tag scanned event can also be sent to the Home Assistant tag component +using :ref:`api-homeassistant_tag_scanned_action`. + +.. code-block:: yaml + + pn7160_...: + # ... + on_tag: + then: + - homeassistant.tag_scanned: !lambda 'return x;' + +You could also send the value to Home Assistant via a :doc:`template sensor `: + +.. code-block:: yaml + + pn7160_...: + # ... + on_tag: + then: + - text_sensor.template.publish: + id: nfc_tag + state: !lambda 'return x;' + + text_sensor: + - platform: template + name: "NFC Tag" + id: nfc_tag + +.. _pn7160-on_tag_removed: + +``on_tag_removed`` Trigger +************************** + +This automation will be triggered after the ``tag_ttl`` interval (see above) when the PN7160 no longer "sees" a +previously scanned tag. + +The parameter ``x`` this trigger provides is of type ``std::string`` and is the removed tag UID in the format +``74-10-37-94``. The example configuration below will publish the removed tag ID on the MQTT topic ``pn7160/tag_removed``. + +.. code-block:: yaml + + pn7160_...: + # ... + on_tag_removed: + then: + - mqtt.publish: + topic: pn7160/tag_removed + payload: !lambda 'return x;' + +.. _pn7160-on_emulated_tag_scan: + +``on_emulated_tag_scan`` Trigger +******************************** + +If card/tag emulation is enabled, this automation will be triggered when another reader (such as a smartphone) scans +the PN7160 and reads the NDEF message it responds with. No parameters are available to this action because data is only +sent *from* the PN7160 *to* the scanning device. + +.. code-block:: yaml + + pn7160_...: + # ... + on_emulated_tag_scan: + then: + - rtttl.play: "alert:d=32,o=5,b=160:e6,p,e6,p,e6" + + +.. _pn7160-ndef: + +NDEF +==== + +The PN7160 supports reading NDEF messages from and writing NDEF messages to cards/tags. + +.. _pn7160-ndef_reading: + +NDEF Reading +------------ + +Given an NFC tag formatted and written using the Home Assistant Companion App, the following example will send the tag +ID contained within its NDEF message to Home Assistant using the :ref:`api-homeassistant_tag_scanned_action`. +If no NDEF record is found with a tag ID, the tag's UID will be sent to Home Assistant, instead. + +The ``tag`` variable is available to any actions that run within the ``on_tag`` and ``on_tag_removed`` triggers. + +.. code-block:: yaml + + pn7160_...: + # ... + on_tag: + then: + - homeassistant.tag_scanned: !lambda "return tag.has_ha_tag_id() ? tag.get_ha_tag_id() : x;" + +.. _pn7160-ndef_writing: + +NDEF Writing +------------ + +The examples below illustrate how NDEF messages may be written to cards/tags via the PN7160. Note that a +:doc:`button ` is a great mechanism to use to trigger these actions. + +The first example will write a simple, fixed NDEF message to a tag. + +.. code-block:: yaml + + on_... + then: + - tag.set_write_message: + message: https://www.home-assistant.io/tag/pulse + include_android_app_record: false # optional + - tag.set_write_mode: my_pn7160_id + +The next example can be used to write a (pseudo) random UUID to a tag in the same manner as the Home Assistant +Companion App. + +.. code-block:: yaml + + on_... + then: + - tag.set_write_message: + message: !lambda "return nfc::get_random_ha_tag_ndef();" + - tag.set_write_mode: my_pn7160_id + +See Also +-------- + +- :doc:`index` +- :doc:`pn532` +- :doc:`rc522` +- :doc:`rdm6300` +- :apiref:`pn7160/pn7160.h` +- :ghedit:`Edit` diff --git a/components/climate/bang_bang.rst b/components/climate/bang_bang.rst index cbe696c9f4..78a160cd8b 100644 --- a/components/climate/bang_bang.rst +++ b/components/climate/bang_bang.rst @@ -70,6 +70,8 @@ Configuration variables: ------------------------ - **sensor** (**Required**, :ref:`config-id`): The sensor that is used to measure the current temperature. +- **humidity_sensor** (**Optional**, :ref:`config-id`): If specified, this sensor is used to measure the current humidity. + This is used for information only and does not influence temperature control. - **default_target_temperature_low** (**Required**, float): The default low target temperature for the control algorithm. This can be dynamically set in the frontend later. - **default_target_temperature_high** (**Required**, float): The default high target temperature for diff --git a/components/climate/haier.rst b/components/climate/haier.rst index 9f818f100d..775161519f 100644 --- a/components/climate/haier.rst +++ b/components/climate/haier.rst @@ -2,14 +2,14 @@ Haier Climate ============= .. seo:: - :description: Instructions for setting up a Haier climate devices. + :description: Instructions for setting up Haier climate devices. :image: air-conditioner.svg 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). -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. +There are two versions of the Haier protocol: the older version uses an application called SmartAir2 while the newer version uses an application called hOn. Both protocols are compatible on the transport level but utilize different commands to control appliances. -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. +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 or RPI Pico W module. The USB connector on the 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 @@ -43,7 +43,7 @@ Older Haier models controlled by the SmartAir2 application are using the KZW-W00 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. +**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 the 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 @@ -51,7 +51,7 @@ Newer Haier models using a module called ESP32-for-Haier. It is an ESP32 single- 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) +Also, you can use any other ESP32, ESP8266, or an 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. @@ -92,10 +92,23 @@ This component requires a :ref:`uart` to be setup. - VERTICAL - HORIZONTAL - BOTH - supported_presets: - - ECO - - BOOST - - SLEEP + supported_presets: + - AWAY + - ECO + - BOOST + - SLEEP + on_alarm_start: + then: + - logger.log: + level: WARN + format: "Alarm activated. Code: %d. Message: \"%s\"" + args: [ code, message] + on_alarm_end: + then: + - logger.log: + level: INFO + format: "Alarm deactivated. Code: %d. Message: \"%s\"" + args: [ code, message] Configuration variables: @@ -103,14 +116,14 @@ 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. +- **protocol** (*Optional*, string): Defines communication protocol with AC. Possible values: hon or smartair2. The 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. -- **answer_timeout** (*Optional*, :ref:`config-time`): Responce timeout. Default value is 200ms. +- **answer_timeout** (*Optional*, :ref:`config-time`): Responce timeout. The default value is 200ms. - **alternative_swing_control** (*Optional*, boolean): (supported by smartAir2 only) If true - use alternative values to control swing mode. Use only if the original control method is not working for your AC. -- **control_packet_size** (*Optional*, int): (supported only by hOn) Define the size of the control packet. Can help with some newer models of ACs that use bigger packets. Default value: 10. +- **control_packet_size** (*Optional*, int): (supported only by hOn) Define the size of the control packet. Can help with some newer models of ACs that use bigger packets. The default value: 10. - **control_method** (*Optional*, list): (supported only by hOn) Defines control method (should be supported by AC). Supported values: MONITOR_ONLY - no control, just monitor status, SET_GROUP_PARAMETERS - set all AC parameters with one command (default method), SET_SINGLE_PARAMETER - set each parameter individually (this method is supported by some new ceiling ACs like AD71S2SM3FA) -- **display** (*Optional*, boolean): Can be used to set AC display off. +- **display** (*Optional*, boolean): Can be used to set the AC display off. - **beeper** (*Optional*, boolean): Can be used to disable beeping on commands from AC. Supported only by hOn protocol. - **outdoor_temperature** (*Optional*): Temperature sensor for outdoor temperature. Supported only by hOn protocol. @@ -119,14 +132,52 @@ Configuration variables: - All other options from :ref:`Sensor `. - **supported_modes** (*Optional*, list): Can be used to disable some of AC modes. Possible values: 'OFF', HEAT_COOL, COOL, HEAT, DRY, FAN_ONLY - **supported_swing_modes** (*Optional*, list): Can be used to disable some swing modes if your AC does not support it. Possible values: 'OFF', VERTICAL, HORIZONTAL, BOTH -- **supported_presets** (*Optional*, list): Can be used to disable some presets. Possible values for smartair2 are: BOOST, COMFORT. Possible values for hOn are: ECO, BOOST, SLEEP +- **supported_presets** (*Optional*, list): Can be used to disable some presets. Possible values for smartair2 are: AWAY, BOOST, COMFORT. Possible values for hOn are: AWAY, ECO, BOOST, SLEEP. AWAY preset can be enabled only in HEAT mode, it is disabled by default +- **on_alarm_start (Optional, :ref:`Automation `):** (supported only by hOn) Automation to perform when AC activates a new alarm. See :ref:`haier-on_alarm_start` +- **on_alarm_end (Optional, :ref:`Automation `):** (supported only by hOn) Automation to perform when AC deactivates a new alarm. See :ref:`haier-on_alarm_end` - All other options from :ref:`Climate `. Automations ----------- -climate.haier.power_on Action -***************************** +.. _haier-on_alarm_start: + +``on_alarm_start`` Trigger +************************** + +This automation will be triggered when a new alarm is activated by AC. The error code of the alarm will be given in the variable "code" (type uint8_t), error message in the variable "message" (type char*). Those variables can be used in :ref:`lambdas ` + +.. code-block:: yaml + + climate: + - protocol: hOn + on_alarm_start: + then: + - logger.log: + level: WARN + format: "Alarm activated. Code: %d. Message: \"%s\"" + args: [ code, message] + +.. _haier-on_alarm_end: + +``on_alarm_end`` Trigger +************************ + +This automation will be triggered when a previously activated alarm is deactivated by AC. The error code of the alarm will be given in the variable "code" (type uint8_t), error message in the variable "message" (type char*). Those variables can be used in :ref:`lambdas ` + +.. code-block:: yaml + + climate: + - protocol: hOn + on_alarm_end: + then: + - logger.log: + level: INFO + format: "Alarm deactivated. Code: %d. Message: \"%s\"" + args: [ code, message] + +``climate.haier.power_on`` Action +********************************* This action turns AC power on. @@ -136,8 +187,8 @@ This action turns AC power on. then: climate.haier.power_on: device_id -climate.haier.power_off Action -****************************** +``climate.haier.power_off`` Action +********************************** This action turns AC power off @@ -147,8 +198,8 @@ This action turns AC power off then: climate.haier.power_off: device_id -climate.haier.power_toggle Action -********************************* +``climate.haier.power_toggle`` Action +************************************* This action toggles AC power @@ -158,8 +209,8 @@ This action toggles AC power then: climate.haier.power_toggle: device_id -climate.haier.display_on Action -******************************* +``climate.haier.display_on`` Action +*********************************** This action turns the AC display on @@ -169,8 +220,8 @@ This action turns the AC display on then: climate.haier.display_on: device_id -climate.haier.display_off Action -******************************** +``climate.haier.display_off`` Action +************************************ This action turns the AC display off @@ -180,8 +231,8 @@ This action turns the AC display off then: climate.haier.display_off: device_id -climate.haier.health_on Action -****************************** +``climate.haier.health_on`` Action +********************************** Turn on health mode (`UV light sterilization `__) @@ -191,8 +242,8 @@ Turn on health mode (`UV light sterilization `__ @@ -261,8 +312,8 @@ climate.haier.start_self_cleaning Action then: - climate.haier.start_self_cleaning: device_id -climate.haier.start_steri_cleaning Action -***************************************** +``climate.haier.start_steri_cleaning`` Action +********************************************* (supported only by hOn) Start 56°C steri-cleaning diff --git a/components/climate/index.rst b/components/climate/index.rst index bc5ebf601e..dde76b23b9 100644 --- a/components/climate/index.rst +++ b/components/climate/index.rst @@ -15,6 +15,10 @@ and can be put in different modes like ``HEAT``, ``COOL``, ``HEAT_COOL`` or ``OF Climate Device UI in Home Assistant. +.. note:: + + Not all climate components support all possible features. Check the corresponding documentation page for details on what is supported. + .. _config-climate: Base Climate Configuration @@ -30,6 +34,15 @@ All climate platforms in ESPHome inherit from the climate configuration schema. min_temperature: 18 max_temperature: 25 temperature_step: 0.1 + min_humidity: 30% + max_humidity: 99% + - platform: ... + visual: + min_temperature: 18 + max_temperature: 25 + temperature_step: + target_temperature: 0.5 + current_temperature: 0.1 Configuration variables: @@ -55,6 +68,11 @@ Configuration variables: - **target_temperature** (**Required**, float): The granularity for target temperature - **current_temperature** (**Required**, float): The granularity for current temperature + - **min_humidity** (*Optional*, percentage): The minimum humidity the climate device can reach. + Used to set the range of the frontend gauge. + - **max_humidity** (*Optional*, percentage): The maximum humidity the climate device can reach. + Used to set the range of the frontend gauge. + Advanced options: - **internal** (*Optional*, boolean): Mark this component as internal. Internal components will @@ -74,6 +92,8 @@ MQTT options: climate device action changes to. - **current_temperature_state_topic** (*Optional*, string): The topic to publish current temperature changes to. +- **current_humidity_state_topic** (*Optional*, string): The topic to publish + current humidity changes to. - **fan_mode_state_topic** (*Optional*, string): The topic to publish fan mode changes to. - **fan_mode_command_topic** (*Optional*, string): The topic to receive @@ -102,19 +122,12 @@ MQTT options: lower target temperature changes to. - **target_temperature_low_command_topic** (*Optional*, string): The topic to receive lower target temperature commands on. +- **target_humidity_state_topic** (*Optional*, string): The topic to publish + target humidity changes to. +- **target_humidity_command_topic** (*Optional*, string): The topic to receive + target humidity commands on. - All other options from :ref:`MQTT Component `. -.. code-block:: yaml - - climate: - - platform: ... - visual: - min_temperature: 18 - max_temperature: 25 - temperature_step: - target_temperature: 0.5 - current_temperature: 0.1 - Climate Automation ------------------ @@ -152,6 +165,8 @@ Configuration variables: lower target temperature of a climate device with a two-point target temperature. - **target_temperature_high** (*Optional*, float, :ref:`templatable `): Set the higher target temperature of a climate device with a two-point target temperature. +- **target_humidity** (*Optional*, float, :ref:`templatable `): Set the + target humidity of a climate device. - **preset** (*Optional*, string, :ref:`templatable `): Set the preset of the climate device. One of ``ECO``, ``AWAY``, ``BOOST``, ``COMFORT``, ``HOME``, ``SLEEP``, ``ACTIVITY``. @@ -181,12 +196,16 @@ advanced stuff. id(my_climate).mode // Current temperature, type: float (degrees) id(my_climate).current_temperature + // Current humidity, type: float (percentage) + id(my_climate).current_humidity // Target temperature, type: float (degrees) id(my_climate).target_temperature // Lower Target temperature, type: float (degrees) id(my_climate).target_temperature_low // High Target temperature, type: float (degrees) id(my_climate).target_temperature_high + // Target humidity, type: float (percentage) + id(my_climate).target_humidity // Fan mode, type: FanMode (enum) id(my_climate).fan_mode // Custom Fan mode, type: string diff --git a/components/climate/pid.rst b/components/climate/pid.rst index 9bb3d8881e..c8bdad802c 100644 --- a/components/climate/pid.rst +++ b/components/climate/pid.rst @@ -53,6 +53,8 @@ Configuration variables: - **sensor** (**Required**, :ref:`config-id`): The sensor that is used to measure the current temperature. +- **humidity_sensor** (**Optional**, :ref:`config-id`): If specified, this sensor is used to measure the current humidity. + This is used for information only and does not influence temperature control. - **default_target_temperature** (**Required**, float): The default target temperature (setpoint) for the control algorithm. This can be dynamically set in the frontend later. - **heat_output** (*Optional*, :ref:`config-id`): The ID of a :ref:`float output ` diff --git a/components/climate/thermostat.rst b/components/climate/thermostat.rst index 2c281f1024..6f72c15e48 100644 --- a/components/climate/thermostat.rst +++ b/components/climate/thermostat.rst @@ -168,6 +168,8 @@ Configuration Variables: The thermostat controller uses the sensor to determine whether it should heat or cool. - **sensor** (**Required**, :ref:`config-id`): The sensor that is used to measure the current temperature. +- **humidity_sensor** (**Optional**, :ref:`config-id`): If specified, this sensor is used to measure the current humidity. + This is used for information only and does not influence temperature control. Heating and Cooling Actions *************************** diff --git a/components/cover/template.rst b/components/cover/template.rst index e93b54c617..8b6a5f430c 100644 --- a/components/cover/template.rst +++ b/components/cover/template.rst @@ -52,6 +52,8 @@ Configuration variables: be performed when the remote requests the cover to be closed. - **stop_action** (*Optional*, :ref:`Action `): The action that should be performed when the remote requests the cover to be stopped. +- **toggle_action** (*Optional*, :ref:`Action `): The action that should + be performed when the remote requests to toggle the the cover. - **optimistic** (*Optional*, boolean): Whether to operate in optimistic mode - when in this mode, any command sent to the template cover will immediately update the reported state and no lambda needs to be used. Defaults to ``false``. diff --git a/components/display/st7789v.rst b/components/display/st7789v.rst index 3073b8194f..a04eb23060 100644 --- a/components/display/st7789v.rst +++ b/components/display/st7789v.rst @@ -72,6 +72,7 @@ If you do specify them they will override any default. - ``Adafruit RR 280x240`` (round-rectangular display -- some pixels are "deleted" from corners to form rounded shape) - ``Adafruit S2 TFT FEATHER 240X135`` - ``LILYGO T-Embed 170X320`` + - ``Waveshare 1.47in 172X320`` (round-rectangular display -- some pixels are "deleted" from corners to form rounded shape) - ``Custom`` For other displays not listed above - **height** (**Required**, int): Sets height of display in pixels. Defaults depends ``model``. @@ -177,6 +178,16 @@ Items marked RQ are hardware dependent but required and not preset. Items marked - 46 - 12 - 11 + * - Waveshare 1.47in 172X320 + - 320/172 + - 34/0 + - 21 + - 22 + - 23 + - 4 + - + - 18 + - 19 * - Custom - RQ - RQ diff --git a/components/display/waveshare_epaper.rst b/components/display/waveshare_epaper.rst index 83f842129e..73a02825a4 100644 --- a/components/display/waveshare_epaper.rst +++ b/components/display/waveshare_epaper.rst @@ -89,9 +89,11 @@ Configuration variables: - ``2.13in-ttgo-b1`` - T5_V2.3 with B1 display tested - ``2.13in-ttgo-dke`` - T5_V2.3 with DKE group display (DEPG0213BN) tested - ``2.70in`` - currently not working with the HAT Rev 2.1 version + - ``2.70inv2`` - ``2.90in`` - ``2.90inv2`` - ``2.90in-b`` - B/W rendering only + - ``2.90in-bV3`` - B/W rendering only - ``4.20in`` - ``4.20in-bV2`` - B/W rendering only - ``5.83in`` diff --git a/components/display_menu/graphical_display_menu.rst b/components/display_menu/graphical_display_menu.rst new file mode 100644 index 0000000000..1c8629e76b --- /dev/null +++ b/components/display_menu/graphical_display_menu.rst @@ -0,0 +1,206 @@ +.. _graphical_display_menu: + +Graphical Display Menu +====================== + +.. seo:: + :description: Instructions for setting up a simple hierarchical menu on displays. + :image: lcd_menu.png + +The component provides an infrastructure for setting up a hierarchical menu +on graphical displays. This offers the user an interactive method to display +labels, control entities like ``switch``, ``select``, ``number`` available locally on the +ESPHome node, without the requirement of a network connection. + +.. figure:: images/graphical_display_menu.jpg + :align: center + :width: 60.0% + +Overview +-------- + +The integration implements the :ref:`Display Menu ` integration providing +a hierarchical menu primarily intended to be controlled either by a rotary encoder +with a button or a five-button joystick controller. + +The component needs to be connected to an instance of a display supporting ESPHome's rendering +engine such as :doc:`E-Paper displays ` or :doc:`OLED displays `. + +.. code-block:: yaml + + # Example configuration entry + graphical_display_menu: + id: my_graphical_display_menu + display: my_display_component + on_redraw: + then: + component.update: my_dispay_component + active: false + mode: rotary + items: + ... + +Configuration variables: + +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- **display** (*Optional*, :ref:`config-id`): ID of the display to render to. See + :ref:`drawing_modes` for more details +- **font** (:ref:`Font `): Specifies the font to use +- **foreground_color** (*Optional*, :ref:`config-color`): Specifies the foreground color to use. + Defaults to COLOR_ON +- **background_color** (*Optional*, :ref:`config-color`): Specifies the background color to use. + Defaults to COLOR_OFF + +Automations: + +- **on_redraw** (*Optional*, :ref:`Automation `): An automation to perform + when the menu needs to be redrawn. This can be useful if your display has slow refresh rates. + For example E-Ink displays that are used with `display_interval: never` + +Additional configuration is described in the :ref:`Display Menu ` component. + +.. _drawing_modes: + +Drawing Modes +------------- + +Pop Up Mode +*********** + +When a **display** is specified the menu will create a :ref:`page ` as part of the initialisation. It will render to the entire +of the display when invoked. This is useful when you may want to use the display for other purposes but show a menu in response to user +interaction. + +Advanced Drawing Mode +********************* + +If you do not specify a **display** when setting up a menu you will be responsible for controlling drawing of the menu. This also allows you to +render the menu to a smaller portion than the available screen size. It May be useful in situations where you want to display a menu as part of a +larger user interface (for example rendering a sensor graph and a control menu next to it) + +.. code-block:: yaml + + # Example configuration entry + graphical_display_menu: + - id: my_menu + # Note: No display specified + active: true + + display: + - platform: waveshare_epaper + id: my_display_component + pages: + - id: advanced_drawing_mode_page + lambda: |- + const auto display_width = it.get_width(); + const auto display_height = it.get_height(); + auto half_display_width = (int)(display_width / 2.0f); + + // This will render the menu to the right half of the screen leaving the left half for other drawing purposes + // Arguments: it.menu(x, y, menu, width, height); + it.menu(half_display_width, 0, id(my_menu), half_display_width, display_height); + + + +Controlling Menu Item Rendering +------------------------------- + +By default menu items with a value will be rendered between a set of parenthesis. This can be +controlled via the `menu_item_value` parameter. + +- **menu_item_value** (*Optional*, :ref:`config-lambda`): Specifies how to render values for + menu items that have values (eg. Selects, numbers). Defaults to rendering the value as + "(value here)". Receives a MenuItemValueArguments as the argument`it`. + +.. code-block:: yaml + + graphical_display_menu: + menu_item_value: !lambda |- + // Will render your menu item value as "My menu label ~my value here~"" normally and "My menu label *my value here*" when in edit mode + std::string label = " "; + if (it->is_item_selected && it->is_menu_editing) { + label.append("*"); + label.append(it->item->get_value_text()); + label.append("*"); + } else { + label.append("~"); + label.append(it->item->get_value_text()); + label.append("~"); + } + return label; + +.. note:: + + Ensure that all characters you use in the menu_item_value are available glyphs for your :ref:`font ` + +User Interaction Example +------------------------ + +The below example is a more complete example showing how you might use a rotary encoder and button to display/hide the menu and move through the available options + +.. code-block:: yaml + + # Example configuration entry + display: + - platform: waveshare_epaper + id: my_display_component + pages: + - id: graph_page + lambda: |- + it.print(0, 0, id(my_font), "My menu is not currently active"); + + font: + - file: ... + id: my_font + size: 16 + + graphical_display_menu: + id: my_graphical_display_menu + display: my_display_component + on_redraw: + then: + component.update: my_dispay_component + active: false + mode: rotary + items: + - type: Label + text: Menu Item 1 + - type: Label + text: Menu Item 2 + + # Rotary encoder to provide navigation + sensor: + - platform: rotary_encoder + ... + filters: + debounce: 30ms + on_anticlockwise: + - display_menu.up: my_graphical_display_menu + on_clockwise: + - display_menu.down: my_graphical_display_menu + + # A debounced GPIO push button is used to 'click' + binary_sensor: + - platform: gpio + ... + filters: + - delayed_on: 30ms + - delayed_off: 30ms + on_press: + - if: + condition: + display_menu.is_active: my_graphical_display_menu + then: + - display_menu.enter: my_graphical_display_menu + else: + - display_menu.show: my_graphical_display_menu + +See Also +-------- + +- :ref:`Display Menu ` +- :ref:`Display ` +- :ref:`display-fonts` +- :ref:`display-pages` +- :apiref:`graphical_display_menu/graphical_display_menu.h` +- :ghedit:`Edit` diff --git a/components/display_menu/images/graphical_display_menu.jpg b/components/display_menu/images/graphical_display_menu.jpg new file mode 100644 index 0000000000..eaed932d3f Binary files /dev/null and b/components/display_menu/images/graphical_display_menu.jpg differ diff --git a/components/esp32_camera.rst b/components/esp32_camera.rst index 8f5d5c7ad9..793e08887e 100644 --- a/components/esp32_camera.rst +++ b/components/esp32_camera.rst @@ -162,6 +162,7 @@ Automations: when a stream starts. - **on_stream_stop** (*Optional*, :ref:`Automation `): An automation to perform when a stream stops. +- **on_image** (*Optional*, :ref:`Automation `): An automation called when image taken. Image is available as ``image`` variable of type :apistruct:`esp32_camera::CameraImageData`. Test Setting: diff --git a/components/fan/hbridge.rst b/components/fan/hbridge.rst index 3035ab45c2..4ed7166972 100644 --- a/components/fan/hbridge.rst +++ b/components/fan/hbridge.rst @@ -56,6 +56,7 @@ Configuration variables: will allow 1% increments in the output. Defaults to ``100``. - **name** (**Required**, string): The name for this fan. - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- **preset_modes** (*Optional*): A list of preset modes for this fan. Preset modes can be used in automations (i.e. `on_preset_set`). - All other options from :ref:`Fan Component `. .. _fan-hbridge_brake_action: diff --git a/components/fan/index.rst b/components/fan/index.rst index 112c1eff70..7dfdb0ef62 100644 --- a/components/fan/index.rst +++ b/components/fan/index.rst @@ -79,6 +79,8 @@ Automation triggers: when the fan is turned off. See :ref:`fan-on_turn_on_off_trigger`. - **on_speed_set** (*Optional*, :ref:`Action `): An automation to perform when the fan speed is set/changed. See :ref:`fan-on_speed_set_trigger`. +- **on_preset_set** (*Optional*, :ref:`Action `): An automation to perform + when the fan preset mode is set/changed. See :ref:`fan-on_preset_set_trigger`. .. _fan-toggle_action: @@ -206,6 +208,21 @@ This trigger is activated each time the fan speed is changed. It will fire when on_speed_set: - logger.log: "Fan Speed was changed!" +.. _fan-on_preset_set_trigger: + +``fan.on_preset_set`` Trigger +----------------------------- + +This trigger is activated each time the fan preset mode is changed. It will fire when the preset mode is either set via API e.g. in Home Assistant or locally by an automation or a lambda function. + +.. code-block:: yaml + + fan: + - platform: speed # or any other platform + # ... + on_preset_set: + - logger.log: "Fan preset mode was changed!" + Lambda calls ------------ @@ -256,6 +273,17 @@ advanced stuff (see the full API Reference for more info). // Fan direction is reverse, do something else here } +- ``preset_mode``: Retrieve the current preset mode of the fan. + + .. code-block:: yaml + + // Within lambda, get the fan preset mode and conditionally do something + if (id(my_fan).preset_mode == "auto") { + // Fan preset mode is "auto", do something here + } else { + // Fan preset mode is not "auto", do something else here + } + - ``turn_off()``/``turn_on()``/``toggle()``: Manually turn the fan ON/OFF from code. Similar to the ``fan.turn_on``, ``fan.turn_off``, and ``fan.toggle`` actions, but can be used in complex lambda expressions. @@ -273,6 +301,11 @@ advanced stuff (see the full API Reference for more info). call.set_direction(FanDirection::REVERSE); call.perform(); + // Set a preset mode + auto call = id(my_fan).turn_on(); + call.set_preset_mode("auto"); + call.perform(); + // Toggle the fan on/off auto call = id(my_fan).toggle(); call.perform(); diff --git a/components/fan/speed.rst b/components/fan/speed.rst index 9969d0cdcb..2f9f5bc6b5 100644 --- a/components/fan/speed.rst +++ b/components/fan/speed.rst @@ -34,6 +34,7 @@ Configuration variables: to calculate the percentages for each speed. E.g. ``2`` means that you have 50% and 100% while ``100`` will allow 1% increments in the output. Defaults to ``100``. - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- **preset_modes** (*Optional*): A list of preset modes for this fan. Preset modes can be used in automations (i.e. `on_preset_set`). - All other options from :ref:`Fan Component `. See Also diff --git a/components/fingerprint_grow.rst b/components/fingerprint_grow.rst index 79c8d4ffa2..c21e25a81a 100644 --- a/components/fingerprint_grow.rst +++ b/components/fingerprint_grow.rst @@ -42,6 +42,8 @@ If available on your reader model, it's recommended to connect 3.3VT (touch indu ... on_finger_scan_unmatched: ... + on_finger_scan_invalid: + ... on_enrollment_scan: ... on_enrollment_done: @@ -64,6 +66,7 @@ Base Configuration: - **new_password** (*Optional*, int): Sets a new password to use for authentication. See :ref:`fingerprint_grow-set_new_password` for more information. - **on_finger_scan_matched** (*Optional*, :ref:`Automation `): An action to be performed when an enrolled fingerprint is scanned. See :ref:`fingerprint_grow-on_finger_scan_matched`. - **on_finger_scan_unmatched** (*Optional*, :ref:`Automation `): An action to be performed when an unknown fingerprint is scanned. See :ref:`fingerprint_grow-on_finger_scan_unmatched`. +- **on_finger_scan_invalid** (*Optional*, :ref:`Automation `): An action to be performed when the scan of a fingerprint failed. See :ref:`fingerprint_grow-on_finger_scan_invalid`. - **on_enrollment_scan** (*Optional*, :ref:`Automation `): An action to be performed when a fingerprint is scanned during enrollment. See :ref:`fingerprint_grow-on_enrollment_scan`. - **on_enrollment_done** (*Optional*, :ref:`Automation `): An action to be performed when a fingerprint is enrolled. See :ref:`fingerprint_grow-on_enrollment_done`. - **on_enrollment_failed** (*Optional*, :ref:`Automation `): An action to be performed when a fingerprint enrollment failed. See :ref:`fingerprint_grow-on_enrollment_failed`. @@ -144,6 +147,20 @@ The ``new_password:`` configuration option is meant to be compiled, flashed to t password: 0x72AB96CD # Update the existing password with the new one +.. _fingerprint_grow-on_finger_scan_invalid: + +``on_finger_scan_invalid`` Trigger +---------------------------------- + +With this configuration option you can write complex automations whenever a scan fails, e.g. when the finger is not placed correctly on the reader. This is different from ``on_finger_scan_unmatched`` which is triggered when an unknown fingerprint is scanned. This option works best with the ``sensing_pin`` option defined. + +.. code-block:: yaml + + on_finger_scan_invalid: + - text_sensor.template.publish: + id: fingerprint_state + state: "Invalid finger" + .. _fingerprint_grow-on_finger_scan_matched: ``on_finger_scan_matched`` Trigger @@ -420,6 +437,9 @@ Sample code fingerprint_grow: sensing_pin: GPIO12 + on_finger_scan_invalid: + - homeassistant.event: + event: esphome.test_node_finger_scan_invalid on_finger_scan_matched: - homeassistant.event: event: esphome.test_node_finger_scan_matched diff --git a/components/light/index.rst b/components/light/index.rst index 9d44914eb8..5e57c4d4cb 100644 --- a/components/light/index.rst +++ b/components/light/index.rst @@ -708,6 +708,7 @@ the strip and shifts them forward every ``add_led_interval``. num_leds: 1 add_led_interval: 100ms reverse: false + gradient: false Configuration variables: @@ -720,7 +721,8 @@ Configuration variables: - **blue** (*Optional*, percentage): The percentage the blue color channel should be on. Defaults to ``100%``. - **random** (*Optional*, boolean): If set to ``true``, will overwrite the RGB colors by a new, randomly-chosen color each time. Defaults to ``false``. - - **num_leds** (*Optional*, int): The number of leds of this type to have before moving on to the next color. + - **num_leds** (**Required**, positive int): The number of LEDs of this type to have before transitioning to the next color. If ``gradient`` is true, this will be the number of LEDs over which the color transition will occur. + - **gradient** (*Optional*, boolean): If ``true`` the current color will transition with a gradient over ``num_leds`` to the next color. Defaults to ``false``. - **add_led_interval** (*Optional*, :ref:`config-time`): The interval with which to shift in new leds at the beginning of the strip. Defaults to ``100ms``. diff --git a/components/light/spi_led_strip.rst b/components/light/spi_led_strip.rst index 18f10fc262..d6cb4a75d1 100644 --- a/components/light/spi_led_strip.rst +++ b/components/light/spi_led_strip.rst @@ -8,8 +8,8 @@ SPI LED Strip Light The ``spi_led_strip`` light platform drives one or more SPI interfaced RGB LEDs. These LEDs are often used in strips, where each LED is individually addressable. This component requires an SPI interface to be configured. -This component has been tested with APA102 LEDs and should also work with HD107 and SK9822 type LEDs, or any others -with a similar interface - SPI, 8 bits per colour and BGR ordering. +This component has been tested with APA102 LEDs and the P9813 LED driver. It should also work with HD107 and SK9822 type +LEDs, or any others with a similar interface - SPI, 8 bits per colour and BGR ordering. .. figure:: images/apa102.jpg :align: center diff --git a/components/logger.rst b/components/logger.rst index 95d420962f..4db85eb2cb 100644 --- a/components/logger.rst +++ b/components/logger.rst @@ -35,8 +35,8 @@ Advanced settings: - **tx_buffer_size** (*Optional*, int): The size of the buffer used for log messages. Decrease this if you’re having memory problems. Defaults to ``512``. -- **hardware_uart** (*Optional*, string): The Hardware UART to use for logging. - Defaults to ``UART0``. +- **hardware_uart** (*Optional*, string): The Hardware UART to use for logging. The default varies depending on + the specific processor/chip and framework you are using. See the :ref:`table below `. - **esp8266_store_log_strings_in_flash** (*Optional*, boolean): If set to false, disables storing log strings in the flash section of the device (uses more memory). Defaults to true. - **on_message** (*Optional*, :ref:`Automation `): An action to be @@ -52,23 +52,99 @@ Advanced settings: Hardware UARTs -------------- -The logger component makes use of platform-specific hardware UARTs for serial logging. -By default, the logger will occupy ``UART0``. The ESP32 has three hardware UARTs, all of -which can be used for both transmit and receive. The ESP8266 only has two hardware UARTs, -one of which is transmit-only. The ESP8266 ``UART0`` can also be 'swapped' to TX/RX on the -CTS/RTS pins, if you need to use GPIO1 and GPIO3 for something else. Note that the common -NodeMCU boards have their USB-UART Adapters fixed to the default GPIOs used by ``UART0``, -so if you use anything else you will not get log messages over the on-board USB. - -Possible Hardware UART configurations: - -- ``UART0`` - TX: GPIO1, RX: GPIO3 -- ``UART0_SWAP`` - TX: GPIO15, RX: GPIO13 (Only on ESP8266) -- ``UART1`` - TX: GPIO2, RX: None (Only on ESP8266) -- ``UART1`` - TX: GPIO9, RX: GPIO10 (Only on ESP32) -- ``UART2`` - TX: GPIO16, RX: GPIO17 (Only on ESP32 but not ESP32S2, ESP32S3 or ESP32C3) -- ``USB_CDC`` - uses the USB CDC driver (Only on ESP32S2 and ESP32S3) -- ``USB_SERIAL_JTAG`` - uses the USB Serial/JTAG driver (Only on ESP32S3 and ESP32C3) +The logger component makes use of platform-specific hardware UARTs for serial logging. For example, the ESP32 +has three hardware UARTs, all of which can be used for both transmit and receive. The ESP8266 only has two +hardware UARTs, one of which is transmit-only. The ESP8266's ``UART0`` can also be "swapped" to TX/RX on the +CTS/RTS pins in the event that you need to use GPIO1 and GPIO3 for something else. + +Note that many common boards have their USB-to-serial adapters fixed to the default GPIOs used by ``UART0``, +so if you use any other configuration you will not get log messages over the on-board USB. + +Default UART GPIO Pins +********************** + +.. list-table:: + :header-rows: 1 + + * - + - ``UART0`` + - ``UART0_SWAP`` + - ``UART1`` + - ``UART2`` + - ``USB_CDC`` + - ``USB_SERIAL_JTAG`` + * - ESP8266 + - TX: 1, RX: 3 + - TX: 15, RX: 13 + - TX: 2, RX: N/A + - N/A + - N/A + - N/A + * - ESP32 + - TX: 1, RX: 3 + - N/A + - TX: 9, RX: 10 + - TX: 16, RX: 17 + - N/A + - N/A + * - ESP32-C3 + - TX: 21, RX: 20 + - N/A + - Undefined + - N/A + - N/A + - 18/19 + * - ESP32-S2 + - TX: 43, RX: 44 + - N/A + - TX: 17, RX: 18 + - N/A + - 19/20 + - N/A + * - ESP32-S3 + - TX: 43, RX: 44 + - N/A + - TX: 17, RX: 18 + - Undefined + - 19/20 + - 19/20 + +*Undefined* means that the logger component cannot use this harware UART at this time. + +.. _logger-default_hardware_interfaces: + +Default Hardware Interfaces +--------------------------- + +Because of the wide variety of boards and processors/chips available, we've selected varying default +hardware interfaces for logging. Many newer boards based on ESP32 variants (such as the C3, S2 and S3) +are using the ESP's on-board USB hardware peripheral while boards based on older processors (such as +the original ESP32 or ESP8266) continue to use USB-to-serial bridge ICs for communication. + +.. list-table:: + :header-rows: 1 + + * - + - Arduino + - ESP-IDF + * - ESP8266 + - ``UART0`` + - N/A + * - ESP32 + - ``UART0`` + - ``UART0`` + * - ESP32-C3 + - ``USB_CDC`` + - ``USB_SERIAL_JTAG`` + * - ESP32-S2 + - ``USB_CDC`` + - ``USB_CDC`` + * - ESP32-S3 + - ``USB_CDC`` + - ``USB_SERIAL_JTAG`` + * - RP2040 + - ``USB_CDC`` + - N/A .. _logger-log_levels: diff --git a/components/remote_receiver.rst b/components/remote_receiver.rst index 38d250ad5b..b74b4c694d 100644 --- a/components/remote_receiver.rst +++ b/components/remote_receiver.rst @@ -38,6 +38,7 @@ Configuration variables: - **dish**: Decode and dump Dish infrared codes. - **drayton**: Decode and dump Drayton Digistat RF codes. - **jvc**: Decode and dump JVC infrared codes. + - **keeloq**: Decode and dump KeeLoq RF codes. - **haier**: Decode and dump Haier infrared codes. - **lg**: Decode and dump LG infrared codes. - **magiquest**: Decode and dump MagiQuest wand infrared codes. @@ -103,6 +104,9 @@ Automations: - **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. +- **on_keeloq** (*Optional*, :ref:`Automation `): An automation to perform when a + KeeLoq RF code has been decoded. A variable ``x`` of type :apistruct:`remote_base::KeeloqData` + is passed to the automation for use in lambdas. - **on_haier** (*Optional*, :ref:`Automation `): An automation to perform when a Haier remote code has been decoded. A variable ``x`` of type :apiclass:`remote_base::HaierData` is passed to the automation for use in lambdas. @@ -249,6 +253,11 @@ Remote code selection (exactly one of these has to be included): - **data** (**Required**, int): The JVC code to trigger on, see dumper output for more info. +- **keeloq**: Trigger on a decoded KeeLoq RF remote code with the given data. + + - **address** (**Required**, int): The 32-bit ID code to trigger on, see dumper output for more info. + - **command** (**Required**, int): The 8-bit switch/command to listen for. If omitted, will match on any command/button. + - **haier**: Trigger on a Haier remote code with the given code. - **code** (**Required**, 13-bytes list): The code to listen for, see :ref:`remote_transmitter-transmit_haier` diff --git a/components/remote_transmitter.rst b/components/remote_transmitter.rst index be7d769f07..19ecc3de2b 100644 --- a/components/remote_transmitter.rst +++ b/components/remote_transmitter.rst @@ -111,7 +111,7 @@ This :ref:`action ` sends a Byron Doorbell RF protocol code to a on_...: - remote_transmitter.transmit_byronsx: address: '0x4f' - command: '0x2' + command: '0x2' Configuration variables: @@ -225,7 +225,7 @@ This :ref:`action ` sends a Draton Digistat RF remote code to a r - remote_transmitter.transmit_drayton: address: '0x6180' channel: '0x12' - command: '0x02' + command: '0x02' Configuration variables: @@ -251,6 +251,33 @@ Configuration variables: - **data** (**Required**, int): The JVC code to send, see dumper output for more info. +.. _remote_transmitter-transmit_keeloq: + +``remote_transmitter.transmit_keeloq`` Action +********************************************** + +This :ref:`action ` sends KeeLoq RF remote code to a remote transmitter. + +.. code-block:: yaml + + on_...: + - remote_transmitter.transmit_keeloq: + address: '0x57ffe7b' + command: '0x02' + code: '0xd19ef0a9' + repeat: + times: 3 + wait_time: 15ms + +Configuration variables: + +- **address** (**Required**, int): The 32-bit address to send, see dumper output for more info. +- **command** (**Required**, int): The 4 bit command/button code to send, see dumper output for more info. +- **code** (**Optional**, int): The 32 bit encrypted field to send. Defaults to all zeros. +- **level** (**Optional**, boolean): Low battery level status bit. Defaults to false. +- All other options from :ref:`remote_transmitter-transmit_action`. +- A repeat **wait_time** of 15ms as shown replicates the repetition of an HCS301. + .. _remote_transmitter-transmit_haier: ``remote_transmitter.transmit_haier`` Action @@ -343,6 +370,8 @@ This :ref:`action ` sends an NEC infrared remote code to a remote In version 2021.12, the order of transferring bits was corrected from MSB to LSB in accordance with the NEC standard. Therefore, if the configuration file has come from an earlier version of ESPhome, it is necessary to reverse the order of the address and command bits when moving to 2021.12 or above. For example, address: 0x84ED, command: 0x13EC becomes 0xB721 and 0x37C8 respectively. + Additionally, ESPHome does not automatically generate parity bits or pad values to 2 bytes. + So, in order to send command 0x0, you need to use 0xFF00 (0x00 being the command and 0xFF being the logical inverse). .. code-block:: yaml @@ -350,11 +379,13 @@ This :ref:`action ` sends an NEC infrared remote code to a remote - remote_transmitter.transmit_nec: address: 0x1234 command: 0x78AB + command_repeats: 1 Configuration variables: -- **address** (**Required**, int): The address to send, see dumper output for more details. -- **command** (**Required**, int): The NEC command to send. +- **address** (**Required**, int): The 16-bit address to send, see dumper output for more details. +- **command** (**Required**, int): The 16-bit NEC command to send. +- **command_repeats** (*Optional*, int): The number of times the command bytes are sent in one transmission. Defaults to `1`. - All other options from :ref:`remote_transmitter-transmit_action`. ``remote_transmitter.transmit_nexa`` Action @@ -936,7 +967,7 @@ earlier, create a new template switch that sends the RF code when triggered: - remote_transmitter.transmit_rc_switch_raw: code: '100010000000000010111110' protocol: 2 - repeat: + repeat: times: 10 wait_time: 0s @@ -956,9 +987,9 @@ in the frontend. Click on it and you should see the remote signal being transmit .. 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. + 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. diff --git a/components/sensor/a02yyuw.rst b/components/sensor/a02yyuw.rst new file mode 100644 index 0000000000..e6a08463e6 --- /dev/null +++ b/components/sensor/a02yyuw.rst @@ -0,0 +1,46 @@ +A02YYUW Waterproof Ultrasonic Sensor +==================================== + +.. seo:: + :description: Instructions for setting up A02YYUW waterproof ultrasonic distance sensor in ESPHome. + :image: a02yyuw.jpg + :keywords: ultrasonic, DFRobot, A02YYUW + +This sensor allows you to use A02YYUW waterproof ultrasonic sensor by DFRobot +(`datasheet `__) +with ESPHome to measure distances. This sensor can measure +ranges between 3 centimeters and 450 centimeters with a resolution of 1 milimeter. + +Since this sensor reads multiple times per second, :ref:`sensor-filters` are highly recommended. + +To use the sensor, first set up an :ref:`uart` with a baud rate of 9600 and connect the sensor to the specified pin. + +.. figure:: images/a02yyuw-full.jpg + :align: center + :width: 50.0% + + A02YYUW Waterproof Ultrasonic Distance Sensor. + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: "a02yyuw" + name: "Distance" + + +Configuration variables: +------------------------ + +- **name** (**Required**, string): The name of the sensor. +- **uart_id** (*Optional*, :ref:`config-id`): The ID of the :ref:`UART bus ` you wish to use for this sensor. + Use this if you want to use multiple UART buses at once. +- All other options from :ref:`Sensor `. + +See Also +-------- + +- :ref:`sensor-filters` +- :ref:`uart` +- :apiref:`a02yyuw/a02yyuw.h` +- :ghedit:`Edit` diff --git a/components/sensor/aht10.rst b/components/sensor/aht10.rst index e5a859e7a3..80c7c89e7a 100644 --- a/components/sensor/aht10.rst +++ b/components/sensor/aht10.rst @@ -4,10 +4,10 @@ AHT10 Temperature+Humidity Sensor .. seo:: :description: Instructions for setting up AHT10 temperature and humidity sensors :image: aht10.jpg - :keywords: aht10 aht20 aht21 dht20 + :keywords: aht10 aht20 dht20 The ``aht10`` Temperature+Humidity sensor allows you to use your AHT10 -(`datasheet `__), AHT20 (`datasheet `__), AHT21 (`datasheet `__) :ref:`I²C `-based sensor with ESPHome. +(`datasheet `__) or AHT20 (`datasheet `__) :ref:`I²C `-based sensor with ESPHome. The DHT20 (`datasheet `__) sensor has the packaging of the :doc:`dht` series, but has the AHT20 inside and is speaking :ref:`I²C ` as well. @@ -30,6 +30,7 @@ The DHT20 (`datasheet `__) # Example configuration entry sensor: - platform: aht10 + variant: AHT10 temperature: name: "Living Room Temperature" humidity: @@ -39,6 +40,11 @@ The DHT20 (`datasheet `__) Configuration variables: ------------------------ +- **variant** (*Optional*, enum): Set the variant of the device in use. Defaults to ``AHT10``. + + - ``AHT10`` - For AHT10 devices. + - ``AHT20`` - For AHT20 devices. + - **temperature** (**Required**): The information for the temperature sensor. - **name** (**Required**, string): The name for the temperature sensor. diff --git a/components/sensor/airthings_ble.rst b/components/sensor/airthings_ble.rst index d808255260..c29f966b4b 100644 --- a/components/sensor/airthings_ble.rst +++ b/components/sensor/airthings_ble.rst @@ -53,6 +53,7 @@ Configuration example: sensor: - platform: airthings_wave_plus + name: wave_plus ble_client_id: airthings01 update_interval: 5min # default battery_update_interval: 24h # default diff --git a/components/sensor/as5600.rst b/components/sensor/as5600.rst new file mode 100644 index 0000000000..51fe34b416 --- /dev/null +++ b/components/sensor/as5600.rst @@ -0,0 +1,303 @@ +AS5600 12-Bit Magnetic Position Sensor +====================================== + +.. seo:: + :description: Instructions for setting up AS5600 magnetic position sensor / encoder. + :image: as5600.jpg + :keywords: AS5600 AS5600L + +.. _as5600-component: + +Component/Hub +------------- + +The ``as5600`` sensor platform you to use your AS5600 (`datasheet `__, +`AMS `__) or AS5600L (`datasheet `__, +`AMS `__) 12-bit magnetic position sensor with ESPHome. Individual sensors will be added +using the :ref:`AS5600 Sensor Platform `. To use this hub, first setup +the :ref:`I²C Bus ` and connect the sensor to the pins specified there. + +.. figure:: images/as5600-full.jpg + :align: center + :width: 50.0% + + AS5600 12-Bit Magnetic Position Sensor. + +.. _AMS_AS5600: https://ams.com/en/as5600 + +.. _AMS_AS5600L: https://ams.com/en/as5600l + +.. code-block:: yaml + + as5600: + dir_pin: 22 + start_position: 0deg + range: 180deg + +Configuration variables: +************************ + +- **dir_pin** (*Optional*, int): The pin connected to the AS5600's direction pin. + See :ref:`Direction ` for more information. +- **direction** (*Optional*, string): The direction that the magnet should rotate to increase values. + Used in combination with the **dir_pin**. + + - ``clockwise`` (default) + - ``counterclockwise`` +- **start_position** (*Optional*, int): The raw position that should be considered the start (i.e. ``0``). + See :ref:`Position / Range `. +- **end_position** (*Optional*, int): The raw position that should be considered the end (e.g. 180deg) + of the allowable rotation range. Mutually exclusive with **range**. See :ref:`Position / Range `. +- **range** (*Optional*, int): The allowable rotation range from the **start_position**. Mutually + exclusive with **end_position**. See :ref:`Position / Range `. +- **hysteresis** (*Optional*, string): See datasheet. + + - ``none`` (default) + - ``lsb1`` + - ``lsb2`` + - ``lsb3`` + +- **power_mode** (*Optional*, string): The power mode to run the sensor. Note: When **watchdog** is enabled, + it will switch the device to ``low3`` when there is not much change in position. + + - ``nominal`` (default) + - ``low1`` + - ``low2`` + - ``low3`` + +- **watchdog** (*Optional*, boolean): Whether to enable the watchdog that puts the the chip in to + low power mode 3. Check the datasheet for more information. + Defaults to ``off``. +- **slow_filter** (*Optional*, string): See datasheet. + + - ``16x`` (default) + - ``8x`` + - ``4x`` + - ``2x`` + +- **fast_filter** (*Optional*, string): See datasheet. + + - ``none`` (default) + - ``lsb6`` + - ``lsb7`` + - ``lsb9`` + - ``lsb18`` + - ``lsb21`` + - ``lsb24`` + - ``lsb10`` + +- **address** (*Optional*, int): The i²c address of the sensor. + See :ref:`I²C Addresses ` for more information. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID for this AS5600 Hub. +- All other options for I²C devices described at :ref:`I²C Bus `. + +.. _as5600_direction: + +Direction +--------- + +The AS5600 has ``direction`` pin that controls which rotation direction will cause the position value to **increase**. +This pin should be pulled low for clockwise, and pulled high for counterclockwise. If left floating, you are likely +to encounter erratic behavior. + +If you would like the ESP controller to pull that pin high or low, you may configure the ``dir_pin`` and optionally, the +``direction`` option to have the ESP controller pull the pin high or low. + +.. _as5600_position_range: + +Position / Range +---------------- + +.. figure:: images/as5600-magnet-position.png + :align: center + :width: 80.0% + +Position and range may be configured as one of the following: + +- a value between ``-4095`` and ``4095`` +- an angle between ``-360deg`` and ``360deg`` +- a percentage between ``-100%`` and ``100%`` + +.. note:: + + Negative position values will be normalized to their respective positive position (e.g. -90deg would translate to 270deg). + +The AS5600 reports 2 position values. The value for both types of position values will always be a whole number between 0 and 4095. + +A "raw" position value is not filtered, scaled, etc. So a value of `0` is always when the north end of the magnet is at the top of +the chip, 2048 is always when the north end of the magnet is as the bottom of the chip, etc. + +The regular/scaled position is filtered and scaled based on the sensor configuration (e.g. ``start_position``, ``end_position``, ``range``, etc). +For example, let's say we have the following component config: + +.. code-block:: yaml + + as5600: + start_position: 90deg + range: 180deg + direction: clockwise + dir_pin: 22 + +- If the magnet north was at the right side of the chip (i.e. 1024 / 90deg raw position), the scaled position would report a value of ``0``. +- If the magnet north was at the bottom of the chip (i.e. 2048 / 180deg raw position), the scaled position would report a value of ``2048``. +- If the magnet north was at the left of the chip (i.e. 3096 / 270deg raw position), the scaled position would report a value of ``4095``. +- If the magnet north was at the top of the chipe (i.e. 0 / 0deg raw position), the scaled position would be out of range (which also has + it's own caveats discussed below). + +.. note:: + + You may specify an ``end_position`` that is less than the ``start_position``. When doing so, the allowable range will start at the + ``start_position`` and continue through to the highest position value (i.e. ``4095``) and then continue from ``0`` until it reaches + the ``end_position``. + + +.. warning:: + + The datasheet calls out that the minimum angle that can be configured (start and end position, or start and range) it 18 degrees. + Configuring anything less than that may yield un-expected results. + +.. _as5600_i2c_addresses: + +I²C Addresses +------------- + +The AS5600 address is not configurable and must be ``0x36``. However, if using an AS5600L, +the default address should be ``0x40`` and it is configurable. + +.. _as5600-sensor: + +Sensor +------ + +The ``as5600`` sensor allows you to publish the angle/position measurement from your AS5600 with ESPHome. +First, setup an :ref:`AS5600 Hub ` for your AS5600 sensor and then use this +sensor platform to create individual sensors that will report the position to Home Assistant. + +.. figure:: images/as5600-ui.jpg + :align: center + :width: 80.0% + +.. code-block:: yaml + + as5600: + dir_pin: 22 + + sensor: + - platform: as5600 + name: Position + raw_position: + name: Raw Position + gain: + name: Gain + magnitude: + name: Magnitude + status: + name: Status + +.. _as5600-sensor-config: + +Configuration variables: +************************ + +- **out_of_range_mode** (*Optional*, string): How to treat out of range values. Only applicable if configured + for a range less than 360 degrees. Defaults to ``min_max``. See :ref:`Out of Range Mode `. +- **as5600_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the + :ref:`AS5600 Hub ` you want to use this sensor. +- **update_interval** (*Optional*, :ref:`config-time`): The interval + to check the sensor. Defaults to ``60s``. +- **raw_position** (*Optional*): Reports the raw (un-scaled, un-filtered) position of the magnet. + + - All other options from :ref:`Sensor `. +- **gain** (*Optional*): Information about the automatic gain control. Typically for diagnostic purposes. + The datasheet says this will be between 0-255 when powered by 5v and between 0-128 when powered by 3.3v. + Ideally the value should be close to the middle of the respective range. + + - All other options from :ref:`Sensor `. +- **magnitude** (*Optional*): Information about the detected magnitude. Typically for diagnostic purposes. + The expected scale does not appear to be defined in the datasheet, however, AMS provides a + `user guide `__ + which contains pictures that show it as a scale between ``0`` and ``3000``. Typically this value is seen somewhere + in the neighborhood of ``2100`` for a well positioned magnet. + + - All other options from :ref:`Sensor `. +- **status** (*Optional*): Information about the magnet status. Typically for diagnostic purposes. + See :ref:`Magnet Status ` + + - All other options from :ref:`Sensor `. +- All other options from :ref:`Sensor `. + + +.. _as5600-out-of-range-mode: + +Out of Range Mode +***************** + +- ``min_max`` (default) +- ``nan`` + +When using a range less that 360deg, there would be a range of raw values that would be considered "out of range". By default (``min_max`` mode), the AS5600 +splits that range in half and reports ``0`` while in the half of the "out-of-range" range closest to the ``start_position`` and it reports +``4095`` while in the half of the "out-of-range" range closest to the ``end_position`` / end of the ``range``. Alternatively, you may set to ``nan`` +mode where the sensor will publish ``NAN`` (i.e. "Unknown") when the position falls outside the narrowed range. + +.. _as5600-magnet-status: + +Magnet Status +************* + +The magnet status should report one of the following values: + +- ``2`` indicates that no magnet was detected. +- ``4`` indicates that the magnet was detected and has good reading. +- ``5`` indicates that the magnet was detected, but is too strong. Measurements may appear to be stuck if the magnet is too strong. +- ``6`` indicates that the magnet was detected, but is too weak. Measurements may still be possible in this state. + +.. _as5600-converting-position: + +Converting Position +******************* + +You may desire the position to be converted from the native ``0`` thru ``4095`` to degrees, or perhaps a percentage of the allowable range. +Here are some examples to make that happen: + +.. figure:: images/as5600-ui-derived.jpg + :align: center + :width: 80.0% + +.. code-block:: yaml + + as5600: + id: my_as5600 + sensor: + - platform: as5600 + update_interval: 1s + name: Angle + unit_of_measurement: '°' + accuracy_decimals: 2 + icon: mdi:rotate-right + filters: + - delta: 1 + - lambda: 'return x * as5600::RAW_TO_DEGREES * id(my_as5600).get_range_scale();' + +.. code-block:: yaml + + as5600: + id: my_as5600 + sensor: + - platform: as5600 + update_interval: 1s + name: Percent + unit_of_measurement: '%' + accuracy_decimals: 2 + icon: mdi:rotate-right + filters: + - delta: 1 + - lambda: 'return (x / as5600::POSITION_COUNT) * 100;' + +See Also +-------- + +- :ref:`i2c` +- :ref:`sensor-filters` +- :apiref:`as5600/as5600.h` +- :ghedit:`Edit` diff --git a/components/sensor/dsmr.rst b/components/sensor/dsmr.rst index 5741806763..0f664b0e72 100644 --- a/components/sensor/dsmr.rst +++ b/components/sensor/dsmr.rst @@ -419,6 +419,9 @@ or a transistor-based circuit are not feasible options. Here's an example circui .. figure:: images/dsmr-request-pin-circuit-example.png +When using a type of MCU that provides 5V on the GPIO outputs instead of 3.3V, then use a 330 Ohm +resistor instead of the 200 Ohm resistor. + .. _sensor-dsmr-improving_reader_results: Improving reader results diff --git a/components/sensor/ens160.rst b/components/sensor/ens160.rst index fd13e9c64b..ffa7931637 100644 --- a/components/sensor/ens160.rst +++ b/components/sensor/ens160.rst @@ -6,7 +6,7 @@ ENS160 Sensor :keywords: ENS160 The ``ens160`` sensor platform allows you to use your ENS160 -(`datasheet `__) air-quality sensors with ESPHome. The :ref:`I²C ` component is +(`datasheet `__) air-quality sensors with ESPHome. The :ref:`I²C ` component is required to be set up in your configuration for this sensor to work. .. note:: diff --git a/components/sensor/hlw8012.rst b/components/sensor/hlw8012.rst index 42a462387b..eb1dcf0f74 100644 --- a/components/sensor/hlw8012.rst +++ b/components/sensor/hlw8012.rst @@ -71,7 +71,8 @@ Advanced Options: Possible values are ``HLW8012``, ``CSE7759``, ``BL0937``. Defaults to ``HLW8012``. CSE7759 uses same constants and it also works with default. Must be set for BL0937 to be able to calibrate all three measurements at the same time. - **change_mode_every** (*Optional*, int): After how many updates to cycle between the current/voltage measurement mode. - Note that the first value after switching is discarded because it is often inaccurate. Defaults to ``8``. + Note that the first value after switching is discarded because it is often inaccurate. When set to ``"never"`` the measurement mode will stay at the + set ``initial_mode``. Defaults to ``8``. - **initial_mode** (*Optional*, string): The initial measurement mode. Defaults to ``VOLTAGE``. Possible initial measurement modes are ``VOLTAGE`` or ``CURRENT``. @@ -97,7 +98,7 @@ the initial measurement mode to match whichever mode the device uses, and disabl name: "HLW8012 Power" update_interval: 60s initial_mode: CURRENT - change_mode_every: 4294967295 + change_mode_every: "never" SEL Pin Inversion ----------------- diff --git a/components/sensor/images/a02yyuw-full.jpg b/components/sensor/images/a02yyuw-full.jpg new file mode 100644 index 0000000000..8ca90d2fa7 Binary files /dev/null and b/components/sensor/images/a02yyuw-full.jpg differ diff --git a/components/sensor/images/as5600-full.jpg b/components/sensor/images/as5600-full.jpg new file mode 100644 index 0000000000..c287a46b78 Binary files /dev/null and b/components/sensor/images/as5600-full.jpg differ diff --git a/components/sensor/images/as5600-magnet-position.png b/components/sensor/images/as5600-magnet-position.png new file mode 100644 index 0000000000..3851cc8806 Binary files /dev/null and b/components/sensor/images/as5600-magnet-position.png differ diff --git a/components/sensor/images/as5600-ui-derived.jpg b/components/sensor/images/as5600-ui-derived.jpg new file mode 100644 index 0000000000..0764be8885 Binary files /dev/null and b/components/sensor/images/as5600-ui-derived.jpg differ diff --git a/components/sensor/images/as5600-ui.jpg b/components/sensor/images/as5600-ui.jpg new file mode 100644 index 0000000000..d483f68d07 Binary files /dev/null and b/components/sensor/images/as5600-ui.jpg differ diff --git a/components/sensor/images/dsmr-request-pin-circuit-example.png b/components/sensor/images/dsmr-request-pin-circuit-example.png index 3680431f16..06f66398f3 100644 Binary files a/components/sensor/images/dsmr-request-pin-circuit-example.png and b/components/sensor/images/dsmr-request-pin-circuit-example.png differ diff --git a/components/sensor/index.rst b/components/sensor/index.rst index 3010c0cded..65e63965bd 100644 --- a/components/sensor/index.rst +++ b/components/sensor/index.rst @@ -570,7 +570,7 @@ However, if the last value passed through was 100 only values greater than 120 o ``or`` ****** -Pass forward a value with the first child filter that returns. Above example +Pass forward a value with the first child filter that returns. Below example will only pass forward values that are *either* at least 1s old or are if the absolute difference is at least 5.0. diff --git a/components/sensor/teleinfo.rst b/components/sensor/teleinfo.rst index c601a44c52..5f3d786aa7 100644 --- a/components/sensor/teleinfo.rst +++ b/components/sensor/teleinfo.rst @@ -10,7 +10,7 @@ Component/Hub ------------- The ``teleinfo`` component allows you to retrieve data from a -French electrical counter using Teleinformation (`datasheet `__). It works with Linky electrical +French electrical counter using Teleinformation (`datasheet `__). It works with Linky electrical counter but also legacy EDF electrical counter. .. figure:: images/teleinfo-full.jpg diff --git a/components/time/sntp.rst b/components/time/sntp.rst index 4da7b7fd4a..e69ac89c27 100644 --- a/components/time/sntp.rst +++ b/components/time/sntp.rst @@ -7,6 +7,11 @@ SNTP Time Source time: - platform: sntp id: sntp_time + timezone: Europe/Sofia + servers: + - 0.pool.ntp.org + - 1.pool.ntp.org + - 2.pool.ntp.org Configuration variables diff --git a/components/touchscreen/ft5x06.rst b/components/touchscreen/ft5x06.rst new file mode 100644 index 0000000000..0e784cbe73 --- /dev/null +++ b/components/touchscreen/ft5x06.rst @@ -0,0 +1,44 @@ +FT5X06 Touch Screen Controller +=============================== + +.. seo:: + :description: Instructions for setting up ft5x06 touch screen controller with ESPHome + :image: indicator.jpg + :keywords: FT5X06, Seeed Indicator + +The ``ft5x06`` touchscreen platform allows using the touch screen controllers based on the ft5x06 chip with ESPHome. +The :ref:`I²C ` is required to be set up in your configuration for this touchscreen to work. + +This controller is used in the Seeed Studio Sensecap Indicator. + + +.. figure:: images/indicator.jpg + :align: center + :width: 50.0% + + ft5x06 touchscreen in Seeed Studio Sensecap Indicator. + +Base Touchscreen Configuration +------------------------------ + +.. code-block:: yaml + + # Example configuration entry + touchscreen: + platform: ft5x06 + id: my_touchscreen + +Configuration variables: +************************ + +- **id** (*Optional*, :ref:`config-id`): Manually set the ID of this touchscreen. +- **rotation** (*Optional*): Set the rotation of the touchscreen. By default this will be set to match the display associated with the touchscreen, but this allows more control. Choices are ``0``, ``90``, ``180`` and ``270``. + +- All other options from :ref:`Touchscreen `. + + +See Also +-------- + +- :apiref:`ft5x06/touchscreen/ft5x06_touchscreen.h` +- :ghedit:`Edit` diff --git a/components/touchscreen/ft63x6.rst b/components/touchscreen/ft63x6.rst new file mode 100644 index 0000000000..b206d21cbb --- /dev/null +++ b/components/touchscreen/ft63x6.rst @@ -0,0 +1,61 @@ +FT63X6 Touchscreen Controller +================================ + +.. seo:: + :description: Instructions for setting up FT63X6 touchscreen controller with ESPHome + :image: wt32-sc01.png + :keywords: FT63X6, WT32-SC01 + +The ``ft63x6`` component allows using the touchscreen controller found in +`Seeed Studio's WT32-SC01 `__ +with ESPHome. +The :ref:`I²C ` is required to be set up in your configuration for this sensor to work. + +.. code-block:: yaml + + # Example configuration entry + esp32: + board: m5stack-core2 + framework: + type: arduino + + i2c: + sda: GPIO18 + scl: GPIO19 + scan: false + + output: + - platform: ledc + pin: GPIO23 + id: screen_led + + light: + - platform: monochromatic + output: screen_led + default_transition_length: 0.2s + name: 'Backlight' + restore_mode: ALWAYS_ON + + touchscreen: + - platform: ft63x6 + interrupt_pin: GPIO39 + on_touch: + - logger.log: + format: Touch %d at (%d, %d) + args: [touch.id, touch.x, touch.y] + +Configuration variables: +------------------------ + +- **id** (*Optional*, :ref:`config-id`): Manually set the ID of this touchscreen. +- **reset_pin** (*Optional*, :ref:`Pin Schema `): The reset pin of the controller. +- **interrupt_pin** (*Optional*, :ref:`Pin Schema `): The touch detection pin. + +- All other options from :ref:`config-touchscreen`. + +See Also +-------- + +- :doc:`Touchscreen ` +- :apiref:`ft63x6/ft63x6.h` +- :ghedit:`Edit` diff --git a/components/touchscreen/images/indicator.jpg b/components/touchscreen/images/indicator.jpg new file mode 100644 index 0000000000..57397d6f5a Binary files /dev/null and b/components/touchscreen/images/indicator.jpg differ diff --git a/components/touchscreen/index.rst b/components/touchscreen/index.rst index 586ec40af4..26ea94196c 100644 --- a/components/touchscreen/index.rst +++ b/components/touchscreen/index.rst @@ -5,7 +5,7 @@ Touchscreen Components :description: Instruction for using touchscreen components. :image: folder-open.svg -The ``touchscreen`` component holds the base code for most touchscreen components +The ``touchscreen`` component contains the base code for most touchscreen driver components available in ESPHome and is responsible for passing the touch events to ``binary_sensors`` with the ``touchscreen`` platform. @@ -19,28 +19,82 @@ Base Touchscreen Configuration # Example touchscreen touchscreen: - platform: ... + display: display1 on_touch: then: ... + on_update: + then: + ... + on_release: + then: + ... Configuration variables: ************************ +- **display** (*Required*, :ref:`config-id`): The display to use this touchscreen with. This will be provided automatically if only one display is configured on the device. - **on_touch** (*Optional*, :ref:`Automation `): An automation to perform when the touchscreen is touched. See :ref:`touchscreen-on_touch`. -- **display** (**Required**, :ref:`config-id`): The display to use. If only one display is - available, this can be omitted. +- **on_update** (*Optional*, :ref:`Automation `): An automation to perform + when the touchscreen is touched. See :ref:`touchscreen-on_update`. +- **on_release** (*Optional*, :ref:`Automation `): An automation to perform + when the touchscreen is no longer touched. See :ref:`touchscreen-on_release`. + + +.. _touchscreen-touchpoint: + +``TouchPoint`` Argument Type +---------------------------- + +Both the :ref:`touchscreen-on_touch` and :ref:`touchscreen-on_update` have an argument of the type :apistruct:`touchscreen::TouchPoint` in a +list (``on_update``) or as an ``optional`` (``on_touch``). + +The integer members for the touch positions below are in relation to the display width and height: + +- ``x`` and ``y`` are the current position. +- ``x_last`` and ``y_last`` are the previous position. +- ``x_first`` and ``y_first`` are the position of the touch when it was first detected. +- ``x_raw`` and ``y_raw`` are for calibrating the touchscreen in relation of the display. This replaces the properties with the same name in the touchscreen classes. + +- ``id`` is a number provided by the touchscreen to uniquely identify the touch on a multi-touch screen. +- ``state`` indicates the state of the touch. This can be **1**, indicating it is an initial touch, or **2** indicating the touch position has changed/moved. .. _touchscreen-on_touch: ``on_touch`` Trigger -------------------- -This automation will be triggered when the touchscreen detects a touch. +This automation will be triggered when the touchscreen initially detects a touch on the touchscreen; it will not be fired again until +all touches (for multi-touch supported drivers) are released. + +NOTE: This has changed (from ESPHome 2023.11.6.) To receive continuous updates from touch drags, use :ref:`touchscreen-on_update`. + +This trigger provides two arguments named ``touch`` of type *touchpoint* and ``touches`` with a list of all touches. + +.. _touchscreen-on_update: + +``on_update`` Trigger +--------------------- + +This new automation will be triggered when the touchscreen detects an extra touch or that a touch has moved around on the screen. + + +This trigger provides one argument named ``touches`` of type :apiref:`touchscreen::TouchPoints_t` which has a list of + :ref:`touchscreen-touchpoint`. + +This trigger may be useful to detect gestures such as swiping across the display. + + +.. _touchscreen-on_release: + +``on_release`` Trigger +---------------------- + +This automation will be triggered when all touches are released from the touchscreen. + +At this point of time it has no extra arguments. -This trigger provides one argument named ``touch`` of type :apistruct:`touchscreen::TouchPoint` which has two integer members: ``x`` and ``y`` which -represent the position of the touch in relation to the display width and height. It also has optional members that will be set -depending on the touchscreen platform. Binary Sensor ------------- diff --git a/components/touchscreen/xpt2046.rst b/components/touchscreen/xpt2046.rst index d000fa9703..f3b8ac79a1 100644 --- a/components/touchscreen/xpt2046.rst +++ b/components/touchscreen/xpt2046.rst @@ -108,10 +108,10 @@ values nor ``swap_x_y``. on_touch: - lambda: |- ESP_LOGI("cal", "x=%d, y=%d, x_raw=%d, y_raw=%0d", - id(my_touchscreen).x, - id(my_touchscreen).y, - id(my_touchscreen).x_raw, - id(my_touchscreen).y_raw + touch.x, + touch.y, + touch.x_raw, + touch.y_raw ); Get a stylus or a similar object, run the project and touch the corners of the screen at @@ -175,9 +175,9 @@ using a display lambda similar to the following. display: - platform: ili9341 lambda: |- - it.fill(BLACK); - if (id(my_touchscreen).touched) - it.filled_circle(id(my_touchscreen).x, id(my_touchscreen).y, 10, RED); + auto touch = id(my_touchscreen)->get_touch(); + if (touch) // or touch.has_value() + it.filled_circle(touch.value().x, touch.value().y, 10, RED); To be exact, the component does the following diff --git a/components/uart.rst b/components/uart.rst index 0b8a6b3907..e38db45afc 100644 --- a/components/uart.rst +++ b/components/uart.rst @@ -180,6 +180,84 @@ In that case, either make sure that the debugger outputs less data per log line ``after.bytes`` option to a lower value) or increase the logger buffer size using the logger ``tx_buffer_size`` option. +.. _uart-runtime_change: + +Changing at runtime +------------------- + +There are scenarios where you might need to adjust UART parameters during runtime to enhance communication efficiency +and adapt to varying operational conditions. ESPHome facilitates this through lambda calls. +Below are the methods to read current settings and modify them dynamically: + +- **Reading Current Settings:** Access UART's current configuration using these read-only attributes: + + .. code-block:: cpp + + // RX buffer size + id(my_uart).get_rx_buffer_size(); + // Stop bits + id(my_uart).get_stop_bits(); + // Data bits + id(my_uart).get_data_bits(); + // Parity + id(my_uart).get_parity(); + // Baud rate + id(my_uart).get_baud_rate(); + +- **Modifying Settings at Runtime:** You can change certain UART parameters during runtime. + After setting new values, invoke ``load_settings()`` (ESP32 only) to apply these changes: + + .. code-block:: yaml + + select: + - id: change_baud_rate + name: Baud rate + platform: template + options: + - "2400" + - "9600" + - "38400" + - "57600" + - "115200" + - "256000" + - "512000" + - "921600" + initial_option: "115200" + optimistic: true + restore_value: True + internal: false + entity_category: config + icon: mdi:swap-horizontal + set_action: + - lambda: |- + id(my_uart).flush(); + uint32_t new_baud_rate = stoi(x); + ESP_LOGD("change_baud_rate", "Changing baud rate from %i to %i",id(my_uart).get_baud_rate(), new_baud_rate); + if (id(my_uart).get_baud_rate() != new_baud_rate) { + id(my_uart).set_baud_rate(new_baud_rate); + id(my_uart).load_settings(); + } + + Available methods for runtime changes: + + .. code-block:: cpp + + // Set TX/RX pins + id(my_uart).set_tx_pin(InternalGPIOPin *tx_pin); + id(my_uart).set_rx_pin(InternalGPIOPin *rx_pin); + // RX buffer size + id(my_uart).set_rx_buffer_size(size_t rx_buffer_size); + // Stop bits + id(my_uart).set_stop_bits(uint8_t stop_bits); + // Data bits + id(my_uart).set_data_bits(uint8_t data_bits); + // Parity + id(my_uart).set_parity(UARTParityOptions parity); + // Baud rate + id(my_uart).set_baud_rate(uint32_t baud_rate); + +This flexibility allows for dynamic adaptation to different communication requirements, enhancing the versatility of your ESPHome setup. + See Also -------- diff --git a/conf.py b/conf.py index 3666621ad7..6133991d74 100644 --- a/conf.py +++ b/conf.py @@ -67,9 +67,9 @@ # built documents. # # The short X.Y version. -version = "2023.12" +version = "2024.1" # The full version, including alpha/beta/rc tags. -release = "2023.12.0-dev" +release = "2024.1.0-dev" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/guides/cli.rst b/guides/cli.rst index c8a31f3330..56dfedb429 100644 --- a/guides/cli.rst +++ b/guides/cli.rst @@ -20,7 +20,7 @@ ESPHome's command line interface always has the following format .. code-block:: console - esphome run livingroom.yaml kitchen.yaml + esphome run livingroom.yaml kitchen.yaml ``--help`` Option -------------------- diff --git a/guides/configuration-types.rst b/guides/configuration-types.rst index 248aafb537..29e32a9060 100644 --- a/guides/configuration-types.rst +++ b/guides/configuration-types.rst @@ -344,7 +344,8 @@ Another way to modularize and reuse your configuration is to use packages. This you to put common pieces of configuration in separate files and keep only unique pieces of your config in the main yaml file. All definitions from packages will be merged with your main config in non-destructive way so you could always override some bits and pieces of package -configuration. +configuration. Substitutions in your main config will override substitutions with the same +name in a package. Dictionaries are merged key-by-key. Lists of components are merged by component ID if specified. Other lists are merged by concatenation. All other config @@ -471,6 +472,8 @@ 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. +Additionally packages could contain a ``defaults`` block which provides +subsitutions for variables not provided by the ``!include`` block. As an example, if the configuration needed to support three garage doors using the ``gpio`` switch platform and the ``time_based`` cover @@ -501,11 +504,17 @@ platform, it could be constructed like this: door_location: right open_switch_gpio: 15 close_switch_gpio: 18 + open_duration: "1min" + close_duration: "50s" .. code-block:: yaml # In garage-door.yaml + defaults: + open_duration: "2.1min" + close_duration: "2min" + switch: - id: open_${door_location}_door_switch name: ${door_name} Garage Door Open Switch @@ -523,11 +532,11 @@ platform, it could be constructed like this: open_action: - switch.turn_on: open_${door_location}_door_switch - open_duration: 2.1min + open_duration: ${open_duration} close_action: - switch.turn_on: close_${door_location}_door_switch - close_duration: 2min + close_duration: ${close_duration} stop_action: - switch.turn_off: open_${door_location}_door_switch diff --git a/guides/contributing.rst b/guides/contributing.rst index 13d018af9f..e1b37be328 100644 --- a/guides/contributing.rst +++ b/guides/contributing.rst @@ -373,6 +373,10 @@ a fork of the repository that you can modify and create git branches on. git clone https://github.com//.git # For example: git clone https://github.com/OttoWinter/esphome.git + # To continue you now need to enter the directory you created above + cd + # For example: cd esphome + # Add "upstream" remote git remote add upstream https://github.com/esphome/.git # For example: git remote add upstream https://github.com/esphome/esphome.git @@ -691,6 +695,27 @@ Standard for the esphome-core codebase: docker run --rm -v "$($current_dir):/esphome" -it ghcr.io/esphome/esphome-lint script/quicklint +PRs are being drafted when changes are needed +--------------------------------------------- + +If there have been changes requested to your PR, our bot will automatically mark your PR as a draft. +This means that the PR is not ready to be merged or further reviewed for the moment. + +Draft PRs tell other reviewers that look at the list of all PRs that this PR is currently in progress and doesn't require their attention yet. + +Once you have made the requested changes, you can mark the PR as ready for review again by clicking the "Ready for review button": + +.. figure:: images/pr-draft-ready.png + :align: center + :width: 100.0% + :alt: The ready for review button in the bottom of a PR in draft mode + +Before you click the "Ready for review" button, ensure you have addressed all requested changes, +there are no merge conflicts, and that all our CI jobs and checks are passing successfully. + +Once you've clicked the "Ready for review" button, the PR will return to a normal state again, +and our bot will automatically notify the reviewers who requested the changes that the PR is ready to go! + See Also diff --git a/guides/diy.rst b/guides/diy.rst index e3c7579ea8..b173e46020 100644 --- a/guides/diy.rst +++ b/guides/diy.rst @@ -91,6 +91,7 @@ Custom Components & Code - `ZclMqttBridge custom component `__ by :ghuser:`HyperReap` - `Custom esp32 media player and notifier `__ by :ghuser:`rananna` - `Blauberg recuperator S22 controller replacement `__ by :ghuser:`Benas09` +- `Rheem Econet Water Heater and Furnace Controller `__ by `ESPHome-econet `__ Sample Configurations --------------------- diff --git a/guides/images/pr-draft-ready.png b/guides/images/pr-draft-ready.png new file mode 100644 index 0000000000..216ae2d880 Binary files /dev/null and b/guides/images/pr-draft-ready.png differ diff --git a/guides/migrate_sonoff_tasmota.rst b/guides/migrate_sonoff_tasmota.rst index f61c1d0a30..c8ae78f655 100644 --- a/guides/migrate_sonoff_tasmota.rst +++ b/guides/migrate_sonoff_tasmota.rst @@ -8,6 +8,11 @@ Migrating from Tasmota Migrating from previous Tasmota setups is very easy. You just need to have ESPHome create a binary for you and then upload that in the Tasmota web interface. +Incompatible versions +--------------------- +WARNING! Migrating via OTA on ESP32, from Tasmota v12 (with boot partition) and up is currently not possible! Trying it could soft-brick your device! + + Getting the Binary ------------------ diff --git a/guides/supporters.rst b/guides/supporters.rst index 6483dfbf8a..26296355ba 100644 --- a/guides/supporters.rst +++ b/guides/supporters.rst @@ -36,6 +36,7 @@ Contributors - `Abel Matser (@abelmatser) `__ - `Abílio Costa (@abmantis) `__ - `Antonio (@acarvajalperez) `__ +- `aceindy (@aceindy) `__ - `Avula Chandra Kiran Reddy (@ackr-8) `__ - `Zhenyu Wu (@Adam5Wu) `__ - `Chris Byrne (@adapt0) `__ @@ -80,6 +81,7 @@ Contributors - `Andreas Mandel (@amandel) `__ - `Amish Vishwakarma (@amishv) `__ - `Amit Keret (@amitkeret) `__ +- `Ammar Askar (@ammaraskar) `__ - `Jason Nader (@ammgws) `__ - `Branden Cash (@ammmze) `__ - `Alexander Momchilov (@amomchilov) `__ @@ -169,7 +171,6 @@ Contributors - `Bryan Berg (@berg) `__ - `BerlinJoker (@BerlinJoker) `__ - `Bert Hertogen (@berthertogen) `__ -- `Ivan Bessarabov (@bessarabov) `__ - `Brandon (@bgulla) `__ - `Benedikt Hübschen (@bhuebschen) `__ - `Bierchermuesli (@Bierchermuesli) `__ @@ -178,11 +179,11 @@ Contributors - `Brian Kaufman (@bkaufx) `__ - `JDavid (@blackhack) `__ - `blackshoals (@blackshoals) `__ -- `blacktirion (@blacktirion) `__ - `blakadder (@blakadder) `__ - `Branimir Lambov (@blambov) `__ - `bleeisme (@bleeisme) `__ - `Jim Ekman (@blejdfist) `__ +- `blindguynar (@blindguynar) `__ - `Scott Smith (@blurfl) `__ - `Bruno Medici (@bmedici) `__ - `Bob (@Bmooij) `__ @@ -231,6 +232,7 @@ Contributors - `Stroe Andrei Catalin (@catalin2402) `__ - `Carter Nelson (@caternuson) `__ - `cathelest (@cathelest) `__ +- `Chris AtLee (@catlee) `__ - `cbialobos (@cbialobos) `__ - `Cameron Bulock (@cbulock) `__ - `Ciprian Constantinescu (@cciprian5) `__ @@ -264,6 +266,7 @@ Contributors - `Casey Burnett (@codeangler) `__ - `CODeRUS (@CODeRUS) `__ - `Alex Miller (@Codex-) `__ +- `Ricardo Salinas (@codingric) `__ - `Cody James (@codyjamestechnical) `__ - `Coenie Richards (@coenier) `__ - `Ashton Lafferty (@cogneato) `__ @@ -280,6 +283,7 @@ Contributors - `Cougar (@Cougar) `__ - `Connor Prussin (@cprussin) `__ - `cptquad (@cptquad) `__ +- `Grant Le Roux (@cram42) `__ - `Corey Rice (@crice009) `__ - `crp500 (@crp500) `__ - `cryptelli (@cryptelli) `__ @@ -322,6 +326,7 @@ Contributors - `Dave Wongillies (@davewongillies) `__ - `David De Sloovere (@DavidDeSloovere) `__ - `David Beitey (@davidjb) `__ +- `davidmonro (@davidmonro) `__ - `David Newgas (@davidn) `__ - `David Noyes (@davidnoyes) `__ - `David Zovko (@davidzovko) `__ @@ -373,6 +378,7 @@ Contributors - `DrZoid (@docteurzoidberg) `__ - `DominikBitzer (@DominikBitzer) `__ - `Dominik (@DomiStyle) `__ +- `Don Burch (@donburch888) `__ - `Derek M. (@doolbneerg) `__ - `Dorian Zedler (@dorianim) `__ - `Sebastian Krzyszkowiak (@dos1) `__ @@ -380,6 +386,7 @@ Contributors - `Robert Schütz (@dotlambda) `__ - `Daniel Hyles (@DotNetDann) `__ - `dr-oblivium (@dr-oblivium) `__ +- `Jean Louis-Guerin (@DrCoolzic) `__ - `Drew Perttula (@drewp) `__ - `drmodding (@drmodding) `__ - `drmpf (@drmpf) `__ @@ -421,7 +428,7 @@ Contributors - `Elkropac (@Elkropac) `__ - `Elliot Wood (@elliot-wood) `__ - `Eduard Llull (@ellull) `__ -- `Joakim Plate (@elupus) `__ +- `Andrew Elwell (@Elwell) `__ - `EmbeddedDevver (@EmbeddedDevver) `__ - `EmmanuelLM (@EmmanuelLM) `__ - `Emory Dunn (@emorydunn) `__ @@ -431,6 +438,7 @@ Contributors - `Bert (@Engelbert) `__ - `Engineer_Will (@EngineerWill) `__ - `Evan Petousis (@epetousis) `__ +- `erapade (@erapade) `__ - `Josh Gwosdz (@erdii) `__ - `Eric Coffman (@ericbrian) `__ - `Eric Hiller (@erichiller) `__ @@ -439,6 +447,7 @@ Contributors - `escoand (@escoand) `__ - `Eric Severance (@esev) `__ - `esphomebot (@esphomebot) `__ +- `espressif2022 (@espressif2022) `__ - `Daniel Dunn (@EternityForest) `__ - `EtienneMD (@EtienneMD) `__ - `Evan Coleman (@evandcoleman) `__ @@ -455,15 +464,18 @@ Contributors - `Fabian Bläse (@fblaese) `__ - `Fabian Berthold (@fbrthld) `__ - `F.D.Castel (@fdcastel) `__ +- `Sun Xiangyu (@feizi) `__ - `felixlungu (@felixlungu) `__ - `Felix Storm (@felixstorm) `__ - `Christian Ferbar (@ferbar) `__ +- `ferbulous (@ferbulous) `__ - `FeuerSturm (@FeuerSturm) `__ - `Florian Golemo (@fgolemo) `__ - `Federico G. Schwindt (@fgsch) `__ - `Frank Riley (@fhriley) `__ - `Frederik (@fightforlife) `__ - `finity69x2 (@finity69x2) `__ +- `Clemens (@firegore) `__ - `Fredrik Jansson (@fjansson) `__ - `Frédéric Jouault (@fjouault) `__ - `Sean Vig (@flacjacket) `__ @@ -473,6 +485,7 @@ Contributors - `fluffymonster (@fluffymonster) `__ - `flyize (@flyize) `__ - `风飘雨 (@flyrainning) `__ +- `Fabio Pugliese Ornellas (@fornellas) `__ - `Fractal147 (@Fractal147) `__ - `Francis-labo (@Francis-labo) `__ - `Francisk0 (@Francisk0) `__ @@ -493,6 +506,7 @@ Contributors - `functionpointer (@functionpointer) `__ - `mr G1K (@G1K) `__ - `Aljaž Srebrnič (@g5pw) `__ +- `Alex Hermann (@gaaf) `__ - `Gabe Cook (@gabe565) `__ - `Gareth Cooper (@gaco79) `__ - `gazoodle (@gazoodle) `__ @@ -520,7 +534,6 @@ Contributors - `Germán Martín (@gmag11) `__ - `Germain Masse (@gmasse) `__ - `Garret Buell (@gmbuell) `__ -- `Jelle Raaijmakers (@gmta) `__ - `gnicolasb (@gnicolasb) `__ - `Go0oSer (@Go0oSer) `__ - `Dario Gogliandolo (@godario) `__ @@ -541,6 +554,7 @@ Contributors - `Jadson Santos (@gtjadsonsantos) `__ - `Guillaume DELVIT (@guiguid) `__ - `guillempages (@guillempages) `__ +- `Fabian Pflug (@gumulka) `__ - `Guyohms (@Guyohms) `__ - `Gilles van den Hoven (@gvdhoven) `__ - `h0jeZvgoxFepBQ2C (@h0jeZvgoxFepBQ2C) `__ @@ -554,6 +568,7 @@ Contributors - `Gavin Mogan (@halkeye) `__ - `Charles (@hallard) `__ - `Aniket (@HandyHat) `__ +- `Harrison Jones (@harrisonhjones) `__ - `Charles Thompson (@haryadoon) `__ - `Ha Thach (@hathach) `__ - `Cong Hoang Nguyen (@HcNguyen111) `__ @@ -562,6 +577,7 @@ Contributors - `hellotomtom (@hellotomtom) `__ - `Jimmy Hedman (@HeMan) `__ - `Hemi03 (@Hemi03) `__ +- `HengYongChao (@HengYongChao) `__ - `HepoH3 (@HepoH3) `__ - `Hermann Kraus (@herm) `__ - `Herr Frei (@herrfrei) `__ @@ -588,6 +604,7 @@ Contributors - `Jan Pobořil (@iBobik) `__ - `igg (@igg) `__ - `Ignacio Hernandez-Ros (@IgnacioHR) `__ +- `Ivan Grokhotkov (@igrr) `__ - `ikatkov (@ikatkov) `__ - `iKK001 (@iKK001) `__ - `ilium007 (@ilium007) `__ @@ -597,10 +614,8 @@ Contributors - `imwoo90 (@imwoo90) `__ - `Dom (@Ing-Dom) `__ - `Ingo Becker (@ingobecker) `__ -- `Ingurum (@Ingurum) `__ - `Marc J (@InvncibiltyCloak) `__ - `IoT-devices LLC (@iotdevicesdev) `__ -- `Ivo Roefs (@ironirc) `__ - `irtimaled (@irtimaled) `__ - `Ingo Theiss (@itn3rd77) `__ - `itpeters (@itpeters) `__ @@ -609,14 +624,12 @@ Contributors - `Ivan Lisenkov (@ivlis) `__ - `Ivo-tje (@Ivo-tje) `__ - `J0RD4N300 (@J0RD4N300) `__ +- `jacobswe (@jacobswe) `__ - `Fredrik Gustafsson (@jagheterfredrik) `__ -- `Jan Harkes (@jaharkes) `__ - `jakehdk (@jakehdk) `__ - `Jake Shirley (@JakeShirley) `__ - `jakub-medrzak (@jakub-medrzak) `__ - `James Braid (@jamesbraid) `__ -- `James Duke (@jamesduke) `__ -- `James Gao (@jamesgao) `__ - `James Hirka (@jameshirka) `__ - `James Lakin (@jamesorlakin) `__ - `Jason (@jamman9000) `__ @@ -628,7 +641,6 @@ Contributors - `Jared Ring (@jaredring) `__ - `Jason-nz (@Jason-nz) `__ - `Jason2866 (@Jason2866) `__ -- `JasperPlant (@JasperPlant) `__ - `Jas Strong (@jasstrong) `__ - `Jay Greco (@jaygreco) `__ - `Jay Newstrom (@JayNewstrom) `__ @@ -637,7 +649,6 @@ Contributors - `Josh Willox (@jcwillox) `__ - `JeeCee1 (@JeeCee1) `__ - `jeff-h (@jeff-h) `__ -- `Jeffrey Borg (@jeffborg) `__ - `Jeff Eberl (@jeffeb3) `__ - `Jeff Rescignano (@JeffResc) `__ - `Jej (@jej) `__ @@ -647,9 +658,9 @@ Contributors - `Jesse Hills (@jesserockz) `__ - `Yuval Brik (@jhamhader) `__ - `Joe (@jhansche) `__ -- `Jim Bauwens (@jimbauwens) `__ - `jimtng (@jimtng) `__ - `jivesinger (@jivesinger) `__ +- `jj-uk (@jj-uk) `__ - `John K. Luebs (@jkl1337) `__ - `Jeppe Ladefoged (@jladefoged) `__ - `Jean-Luc Béchennec (@jlbirccyn) `__ @@ -660,6 +671,7 @@ Contributors - `jmichiel (@jmichiel) `__ - `JMoratelli (@JMoratelli) `__ - `Jonathas Barbosa (@jnthas) `__ +- `jochenvg (@jochenvg) `__ - `Johboh (@Johboh) `__ - `John Moxley (@johnmoxley) `__ - `Dave Johnston (@johnsto) `__ @@ -668,8 +680,10 @@ Contributors - `Jonas Niesner (@jonasniesner) `__ - `Jonathan Adams (@jonathanadams) `__ - `JonnyaiR (@jonnyair) `__ +- `jonOfrie (@jonOfrie) `__ - `Joris S (@Jorre05) `__ - `Jared Sanson (@jorticus) `__ +- `JosephTang (@JosephTang) `__ - `Joshua Spence (@joshuaspence) `__ - `joskfg (@joskfg) `__ - `Joscha Wagner (@jowgn) `__ @@ -679,13 +693,13 @@ Contributors - `Jules-R (@Jules-R) `__ - `Julie Koubová (@juliekoubova) `__ - `Mike Ryan (@justfalter) `__ -- `Jasper van der Neut - Stulen (@jvanderneutstulen) `__ - `Jack Wozny (@jwozny) `__ - `Kris (@K-r-i-s-t-i-a-n) `__ - `k0rtina (@k0rtina) `__ - `Harald Nagel (@k7hpn) `__ - `kaegi (@kaegi) `__ - `kahrendt (@kahrendt) `__ +- `Kaldek (@Kaldek) `__ - `Kamahat (@kamahat) `__ - `Karl0ss (@karl0ss) `__ - `Kattni (@kattni) `__ @@ -711,6 +725,7 @@ Contributors - `konsulten (@konsulten) `__ - `Kevin P. Fleming (@kpfleming) `__ - `Karl Q. (@kquinsland) `__ +- `Anandha Saravanan (@KratosMr) `__ - `kroimon (@kroimon) `__ - `krunkel (@krunkel) `__ - `kryptonitecb3 (@kryptonitecb3) `__ @@ -733,7 +748,9 @@ Contributors - `Leo Winter (@LeoWinterDE) `__ - `Lubos Horacek (@lhoracek) `__ - `Juraj Liso (@LiJu09) `__ +- `Li Junru (@lijunru-hub) `__ - `lillborje71 (@lillborje71) `__ +- `Citric Lee (@limengdu) `__ - `lingex (@lingex) `__ - `Markus (@Links2004) `__ - `LinusHeu (@LinusHeu) `__ @@ -742,6 +759,7 @@ Contributors - `Lazar Obradovic (@lobradov) `__ - `Barry Loong (@loongyh) `__ - `LuBeDa (@lubeda) `__ +- `Lucas Prim (@lucasprim) `__ - `Joakim Sørensen (@ludeeus) `__ - `ludrao (@ludrao) `__ - `luka6000 (@luka6000) `__ @@ -785,12 +803,14 @@ Contributors - `Masterz69 (@Masterz69) `__ - `Christopher Masto (@masto) `__ - `Mat931 (@Mat931) `__ +- `mathieu-mp (@mathieu-mp) `__ - `matikij (@matikij) `__ - `Michel Marti (@matoxp) `__ - `matt123p (@matt123p) `__ - `matthias882 (@matthias882) `__ - `Matus Ivanecky (@maty535) `__ - `Christian (@max246) `__ +- `Max Bachmann (@maxbachmann) `__ - `Maximilian Gerhardt (@maxgerhardt) `__ - `mbo18 (@mbo18) `__ - `mcmuller (@mcmuller) `__ @@ -811,11 +831,13 @@ Contributors - `M Hightower (@mhightower83) `__ - `Michael Muré (@MichaelMure) `__ - `Michal Fapso (@michalfapso) `__ +- `Michał (@michau-krakow) `__ - `Michel Munzert (@michelde) `__ - `micw (@micw) `__ - `Pauline Middelink (@middelink) `__ - `Joel Midstjärna (@midstar) `__ - `Mike_Went (@MikeWent) `__ +- `Tucker Kern (@mill1000) `__ - `André Klitzing (@misery) `__ - `Tomasz (@Misiu) `__ - `MisterSilvereagle (@MisterSilvereagle) `__ @@ -830,6 +852,7 @@ Contributors - `mmanza (@mmanza) `__ - `mnltake (@mnltake) `__ - `Matt N. (@mnoorenberghe) `__ +- `Moriah Morgan (@moriahmorgan) `__ - `moritzj29 (@moritzj29) `__ - `Chris Laplante (@mostthingsweb) `__ - `MrEditor97 (@mreditor97) `__ @@ -837,6 +860,7 @@ Contributors - `Michael Davidson (@MrMDavidson) `__ - `mrred2k (@mrred2k) `__ - `André Cirne (@MrSuicideParrot) `__ +- `mrtoy-me (@mrtoy-me) `__ - `Murray Scott (@mscottco) `__ - `MSe-5-14 (@MSe-5-14) `__ - `mtl010957 (@mtl010957) `__ @@ -852,6 +876,7 @@ Contributors - `Mykle (@myklemykle) `__ - `Mynasru (@Mynasru) `__ - `Kevin Uhlir (@n0bel) `__ +- `n6ham (@n6ham) `__ - `N6RDV (@N6RDV) `__ - `Erik Näsström (@Naesstrom) `__ - `H. Árkosi Róbert (@nagyrobi) `__ @@ -860,6 +885,7 @@ Contributors - `NanoSector (@NanoSector) `__ - `Oskar Napieraj (@napieraj) `__ - `Patrick ZAJDA (@Nardol) `__ +- `NatashaLi-ESPRESSIF (@NatashaLi-ESPRESSIF) `__ - `Nate Lust (@natelust) `__ - `Nathan Marlor (@nathanmarlor) `__ - `ueno (@nayuta-ueno) `__ @@ -867,12 +893,14 @@ Contributors - `Bergont Nicolas (@nbergont) `__ - `neilger (@neilger) `__ - `Nejc Koncan (@nejc-cc) `__ +- `Nerijus Baliūnas (@nerijus) `__ - `Nicolas Graziano (@ngraziano) `__ - `nickrout (@nickrout) `__ - `Nick Whyte (@nickw444) `__ - `Nicky Ivy (@nickyivyca) `__ - `NP v/d Spek (@nielsnl68) `__ - `Niels Zeilemaker (@NielsZeilemaker) `__ +- `Nigel VH (@nigelvh) `__ - `nikito7 (@nikito7) `__ - `niklasweber (@niklasweber) `__ - `Nippey (@Nippey) `__ @@ -886,6 +914,7 @@ Contributors - `Łukasz Śliwiński (@nonameplum) `__ - `Greg Johnson (@notgwj) `__ - `JJ (@notjj) `__ +- `Geoffrey Mayo (@notmayo) `__ - `notsonominal (@notsonominal) `__ - `nouser2013 (@nouser2013) `__ - `Paul Read (@nsolvepaul) `__ @@ -941,6 +970,7 @@ Contributors - `per1234 (@per1234) `__ - `David (@perldj) `__ - `Peter Galantha (@peterg79) `__ +- `Peter Kieser (@pfak) `__ - `Philippe Delodder (@phdelodder) `__ - `Philipp Helo Rehs (@Phhere) `__ - `philbowers (@philbowers) `__ @@ -951,6 +981,7 @@ Contributors - `Philip Persson (@PhPersson) `__ - `Pierre Gordon (@pierlon) `__ - `pieterbrink123 (@pieterbrink123) `__ +- `Jakub Augustynowicz (@pingwiniasty) `__ - `Piotr Kubiak (@piotr-kubiak) `__ - `Peter Kuehne (@pkuehne) `__ - `Plácido Revilla (@placidorevilla) `__ @@ -960,7 +991,6 @@ Contributors - `poloswiss (@poloswiss) `__ - `Pontus Oldberg (@PontusO) `__ - `poptix (@poptix) `__ -- `Iván Povedano (@pove) `__ - `Peter Provost (@PProvost) `__ - `Q. Marchi (@preeefix) `__ - `Francesco Ciocchetti (@primeroz) `__ @@ -976,6 +1006,7 @@ Contributors - `[pʲɵs] (@pyos) `__ - `Qc (@qc24) `__ - `Quinn Casey (@qcasey) `__ +- `qianh-wan (@qianh-wan) `__ - `Tommy Jonsson (@quazzie) `__ - `Quentin Smith (@quentinmit) `__ - `Richard Kuhnt (@r15ch13) `__ @@ -985,6 +1016,7 @@ Contributors - `Florian Ragwitz (@rafl) `__ - `raineth (@raineth) `__ - `Ben V. Brown (@Ralim) `__ +- `Benjamin G. (@Randomblock1) `__ - `randomllama (@randomllama) `__ - `Rodrigo Martín (@Rapsssito) `__ - `Marc Seeger (@rb2k) `__ @@ -1068,6 +1100,7 @@ Contributors - `Alexander Dimitrov (@sharkydog) `__ - `Fabio Todaro (@SharpEdgeMarshall) `__ - `ShellAddicted (@ShellAddicted) `__ +- `shenxiaozheng (@shenxiaozheng) `__ - `sherbang (@sherbang) `__ - `Shish (@shish) `__ - `signix (@signix) `__ @@ -1082,6 +1115,7 @@ Contributors - `Jordan W. Cobb (@skykingjwc) `__ - `Sebastian Lövdahl (@slovdahl) `__ - `smischny (@smischny) `__ +- `Jacob Masen-Smith (@smithjacobj) `__ - `John Mueller (@softplus) `__ - `Sourabh Jaiswal (@sourabhjaiswal) `__ - `Philip Allgaier (@spacegaier) `__ @@ -1106,6 +1140,7 @@ Contributors - `stubs12 (@stubs12) `__ - `sud33p (@sud33p) `__ - `sumirati (@sumirati) `__ +- `Sun Xiang yu (@sun-xiangyu) `__ - `swhaat (@swhaat) `__ - `swifty99 (@swifty99) `__ - `Jan Gutowski (@Switch123456789) `__ @@ -1200,6 +1235,7 @@ Contributors - `Aaron Mildenstein (@untergeek) `__ - `uPesy Electronics (@uPesy) `__ - `UT2UH (@UT2UH) `__ +- `Vlad Yarotsky (@v-yarotsky) `__ - `Vc (@Valcob) `__ - `Nad (@valordk) `__ - `Veli Veromann (@velijv) `__ @@ -1211,6 +1247,7 @@ Contributors - `VitaliyKurokhtin (@VitaliyKurokhtin) `__ - `voed (@voed) `__ - `Xuming Feng (@voicevon) `__ +- `vozvivan (@vozvivan) `__ - `vt-vaio (@vt-vaio) `__ - `vtechun (@vtechun) `__ - `vxider (@Vxider) `__ @@ -1221,7 +1258,6 @@ Contributors - `Wauter (@Wauter) `__ - `WeekendWarrior1 (@WeekendWarrior1) `__ - `Thomas Aldrian (@Weissnix4711) `__ -- `Ian Wells (@wellsi) `__ - `Andrew Garrett (@werdnum) `__ - `whimsee (@whimsee) `__ - `wifwucite (@wifwucite) `__ @@ -1236,6 +1272,7 @@ Contributors - `workingmanrob (@workingmanrob) `__ - `Sven Serlier (@wrt54g) `__ - `Wolfgang Tremmel (@wtremmel) `__ +- `Jiangang Wu (@wujiangang) `__ - `wysiwyng (@wysiwyng) `__ - `De Cock Xavier (@xdecock) `__ - `Jakob (@XDjackieXD) `__ @@ -1247,7 +1284,6 @@ Contributors - `Yaroslav (@Yarikx) `__ - `Marcin Jaworski (@yawor) `__ - `yousaf465 (@yousaf465) `__ -- `Jevgeni Kiski (@yozik04) `__ - `Yuval Aboulafia (@yuvalabou) `__ - `Björn Stenberg (@zagor) `__ - `david reid (@zathras777) `__ @@ -1260,4 +1296,4 @@ Contributors - `Zsolt Zsiros (@ZsZs73) `__ - `Christian Zufferey (@zuzu59) `__ -*This page was last updated November 28, 2023.* +*This page was last updated December 22, 2023.* diff --git a/images/a02yyuw.jpg b/images/a02yyuw.jpg new file mode 100644 index 0000000000..dc1782cc5a Binary files /dev/null and b/images/a02yyuw.jpg differ diff --git a/images/as5600.jpg b/images/as5600.jpg new file mode 100644 index 0000000000..378b976a0d Binary files /dev/null and b/images/as5600.jpg differ diff --git a/images/graphical_display_menu.jpg b/images/graphical_display_menu.jpg new file mode 100644 index 0000000000..d224e96a8a Binary files /dev/null and b/images/graphical_display_menu.jpg differ diff --git a/images/indicator.jpg b/images/indicator.jpg new file mode 100644 index 0000000000..57397d6f5a Binary files /dev/null and b/images/indicator.jpg differ diff --git a/images/pn7150.jpg b/images/pn7150.jpg new file mode 100644 index 0000000000..b9cef4e520 Binary files /dev/null and b/images/pn7150.jpg differ diff --git a/images/pn716x.jpg b/images/pn716x.jpg new file mode 100644 index 0000000000..b9cef4e520 Binary files /dev/null and b/images/pn716x.jpg differ diff --git a/images/wt32-sc01.png b/images/wt32-sc01.png new file mode 100644 index 0000000000..1c0ccfa034 Binary files /dev/null and b/images/wt32-sc01.png differ diff --git a/index.rst b/index.rst index 48da583de2..3af314342b 100644 --- a/index.rst +++ b/index.rst @@ -250,6 +250,7 @@ Distance .. imgtable:: A01NYUB, components/sensor/a01nyub, a01nyub.jpg, Acoustic distance + A02YYUW, components/sensor/a02yyuw, a02yyuw.jpg, Acoustic distance HRXL MaxSonar WR, components/sensor/hrxl_maxsonar_wr, hrxl_maxsonar_wr.jpg, Acoustic distance TOF10120, components/sensor/tof10120, tof10120.jpg, IR optical distance Ultrasonic Sensor, components/sensor/ultrasonic, ultrasonic.jpg, Acoustic distance @@ -367,6 +368,7 @@ Magnetic .. imgtable:: ESP32 Hall Sensor, components/sensor/esp32_hall, magnet.svg, ESP internal, dark-invert + AS5600, components/sensor/as5600, as5600.jpg, 12-Bit Magnetic Position Sensor HMC5883L, components/sensor/hmc5883l, hmc5883l.jpg, 3-Axis magnetometer MMC5603, components/sensor/mmc5603, mmc5603.jpg, 3-Axis magnetometer MMC5983, components/sensor/mmc5983, mmc5983.jpg, 3-Axis magnetometer @@ -482,6 +484,8 @@ Often known as "tag" or "card" readers within the community. .. imgtable:: PN532, components/binary_sensor/pn532, pn532.jpg + PN7150, components/binary_sensor/pn7150, pn7150.jpg + PN716X, components/binary_sensor/pn7160, pn716x.jpg RC522, components/binary_sensor/rc522, rc522.jpg RDM6300, components/binary_sensor/rdm6300, rdm6300.jpg @@ -492,6 +496,7 @@ Touchscreen Nextion Binary Sensor, components/binary_sensor/nextion, nextion.jpg Touchscreen, components/touchscreen/index, touch.svg, dark-invert TT21100, components/touchscreen/tt21100, esp32-s3-korvo-2-lcd.png + FT5X06, components/touchscreen/ft5x06, indicator.jpg GT911, components/touchscreen/gt911, esp32_s3_box_3.png Presence Detection @@ -680,10 +685,10 @@ Touchscreen Components EKTF2232, components/touchscreen/ektf2232, ektf2232.svg, Inkplate 6 Plus Lilygo T5 4.7", components/touchscreen/lilygo_t5_47, lilygo_t5_47_touch.jpg TT21100, components/touchscreen/tt21100, esp32-s3-korvo-2-lcd.png - GT911, components/touchscreen/gt911, esp32_s3_box_3.png XPT2046, components/touchscreen/xpt2046, xpt2046.jpg - - + GT911, components/touchscreen/gt911, esp32_s3_box_3.png + FT63X6, components/touchscreen/ft63x6, wt32-sc01.png + Cover Components ---------------- @@ -841,6 +846,7 @@ Miscellaneous Components Status LED, components/status_led, led-on.svg, dark-invert Display Menu Core, components/display_menu/index, folder-open.svg, dark-invert LCD Menu, components/display_menu/lcd_menu, lcd_menu.png + Graphical Display Menu, components/display_menu/graphical_display_menu, graphical_display_menu.jpg Matrix Keypad, components/matrix_keypad, matrix_keypad.jpg Wiegand Reader, components/wiegand, wiegand.jpg HTTP Request, components/http_request, connection.svg, dark-invert diff --git a/projects/installer.html b/projects/installer.html index 3865356ba1..11d9b44bc1 100644 --- a/projects/installer.html +++ b/projects/installer.html @@ -543,7 +543,7 @@

For advanced users

  • The YAML configuration is on - GitHub + GitHub