diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml index 23c7dca4c4a..293e90d2eb4 100644 --- a/.github/workflows/docker.yml +++ b/.github/workflows/docker.yml @@ -20,7 +20,7 @@ jobs: steps: - name: Checkout source code - uses: actions/checkout@v3.3.0 + uses: actions/checkout@v3.5.2 - name: Set up Docker Buildx uses: docker/setup-buildx-action@v2 @@ -39,7 +39,7 @@ jobs: - name: Build and push id: docker_build - uses: docker/build-push-action@v3 + uses: docker/build-push-action@v4 with: context: . push: true diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index d56bc4401fe..8cd0c44dca4 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -19,7 +19,7 @@ jobs: build: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3.3.0 + - uses: actions/checkout@v3.5.2 - name: Set up Python 3.8 uses: actions/setup-python@v4 with: diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml index 0617396287c..13bfc8e051d 100644 --- a/.github/workflows/stale.yml +++ b/.github/workflows/stale.yml @@ -16,7 +16,7 @@ jobs: stale: runs-on: ubuntu-latest steps: - - uses: actions/stale@v7 + - uses: actions/stale@v8 with: days-before-pr-stale: 60 days-before-pr-close: 7 @@ -35,7 +35,7 @@ jobs: close-issues: runs-on: ubuntu-latest steps: - - uses: actions/stale@v7 + - uses: actions/stale@v8 with: days-before-pr-stale: -1 days-before-pr-close: -1 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index c56ce094a86..39fd255a7af 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,15 +1,15 @@ # See https://pre-commit.com for more information # See https://pre-commit.com/hooks.html for more hooks repos: - - repo: https://github.com/ambv/black - rev: 20.8b1 + - repo: https://github.com/psf/black + rev: 23.1.0 hooks: - id: black args: - --safe - --quiet - - repo: https://gitlab.com/pycqa/flake8 - rev: 3.8.4 + - repo: https://github.com/pycqa/flake8 + rev: 6.0.0 hooks: - id: flake8 additional_dependencies: diff --git a/.vscode/tasks.json b/.vscode/tasks.json new file mode 100644 index 00000000000..f1a91940fae --- /dev/null +++ b/.vscode/tasks.json @@ -0,0 +1,11 @@ +{ + "version": "2.0.0", + "tasks": [ + { + "label": "Live HTML build", + "type": "shell", + "command": "make live-html", + "problemMatcher": [] + }, + ] +} diff --git a/Doxygen b/Doxygen index 6e2b07ec9db..64ab705a890 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.3.0-dev +PROJECT_NUMBER = 2023.5.0-dev # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a diff --git a/_redirects b/_redirects index c288519ff40..8e185bd7314 100644 --- a/_redirects +++ b/_redirects @@ -8,3 +8,31 @@ /devices/esp32.html /components/esp32.html /changelog/2022.12.4.html /changelog/2022.12.0.html 301 +/components/display/ili9341.html /components/display/ili9xxx.html 301 + +/cookbook/brilliant-mirabella-genio-smart-plugs.html https://devices.esphome.io/devices/Mirabella-Genio-Wi-Fi-1-USB 301 +/cookbook/zemismart-rgbw-downlights.html https://devices.esphome.io/devices/Zemismart-LED-RGBWW-Downlight 301 +/cookbook/relay.html https://devices.esphome.io/devices/Generic-Relay 301 +/cookbook/pir.html https://devices.esphome.io/devices/Generic-PIR 301 +/cookbook/mirabella-genio-bulb.html https://devices.esphome.io/devices/Mirabella-Genio-Monochromatic-Bulbs 301 +/cookbook/air_gradient_diy_air_quality_sensor.html https://devices.esphome.io/devices/AirGradient-DIY 301 +/cookbook/ble_itag.html https://devices.esphome.io/devices/ble_itag 301 +/cookbook/bruh.html https://devices.esphome.io/devices/bruh 301 +/cookbook/esw01-eu.html https://devices.esphome.io/devices/Etekcity-Voltson-ESW01-EU 301 +/cookbook/geiger-counter.html https://devices.esphome.io/devices/geiger-counter 301 +/cookbook/h801.html https://devices.esphome.io/devices/H801-RGBW-LED-Controller 301 +/cookbook/iaq_board.html https://devices.esphome.io/devices/iaq_board 301 +/cookbook/ifan02.html https://devices.esphome.io/devices/Sonoff-iFan02 301 +/cookbook/ilonda-wifi-smart-fish-feeder.html https://devices.esphome.io/devices/ilonda-wifi-smart-fish-feeder 301 +/cookbook/iwoole_rgbw_table_lamp.html https://devices.esphome.io/devices/iwoole_rgbw_table_lamp 301 +/cookbook/teckin_sb50.html https://devices.esphome.io/devices/Teckin-SB50_rgbww 301 +/cookbook/temt6000.html https://devices.esphome.io/devices/temt6000 301 +/cookbook/tracer-an.html https://devices.esphome.io/devices/epever_mptt_tracer_an 301 +/cookbook/tuya_rgbw.html https://devices.esphome.io/devices/tuya_rgbw 301 +/cookbook/uart_text_sensor.html /cookbook/lambda_magic.html#custom-uart-text-sensor 301 +/cookbook/endstop-cover.html /components/cover/endstop.html 301 +/cookbook/sonoff-light-switch.html https://devices.esphome.io/devices/Sonoff-Dual-DIY-light 301 +/cookbook/sonoff-basic-light-switch.html https://devices.esphome.io/devices/Sonoff-Basic-DIY-light 301 +/cookbook/sonoff-dual-light-switch.html https://devices.esphome.io/devices/Sonoff-Dual-DIY-light 301 +/cookbook/sonoff-t1-3.html https://devices.esphome.io/devices/Sonoff-T1-T2-T3 301 +/cookbook/dual-r2-cover.html /cookbook/lambda_magic.html#one-button-cover-control 301 diff --git a/_static/changelog-2023.3.0.png b/_static/changelog-2023.3.0.png new file mode 100644 index 00000000000..2ca6298c271 Binary files /dev/null and b/_static/changelog-2023.3.0.png differ diff --git a/_static/changelog-2023.4.0.png b/_static/changelog-2023.4.0.png new file mode 100644 index 00000000000..38b11330094 Binary files /dev/null and b/_static/changelog-2023.4.0.png differ diff --git a/_static/version b/_static/version index 49b1cfc07ee..448988caa37 100644 --- a/_static/version +++ b/_static/version @@ -1 +1 @@ -2023.3.0-dev \ No newline at end of file +2023.5.0-dev \ No newline at end of file diff --git a/changelog/2023.2.0.rst b/changelog/2023.2.0.rst index 124146c7c7f..1d8bbc6bee4 100644 --- a/changelog/2023.2.0.rst +++ b/changelog/2023.2.0.rst @@ -67,6 +67,19 @@ Release 2023.2.2 - February 17 - Fix adoption of variants and pico-w :esphomepr:`4455` by :ghuser:`jesserockz` +Release 2023.2.3 - February 20 +------------------------------ + +- Fix MQTT discovery for climate after preset implementation :esphomepr:`4451` by :ghuser:`jmichiel` +- Update distribution manifest :esphomepr:`4459` by :ghuser:`jesserockz` + +Release 2023.2.4 - February 23 +------------------------------ + +- BL0939 state_class set for energy sensors :esphomepr:`4463` by :ghuser:`konsulten` +- fix wiegand tag parity :esphomepr:`4476` by :ghuser:`ssieb` +- Fix multiple remote_receivers with triggers :esphomepr:`4477` by :ghuser:`jesserockz` + Full list of changes -------------------- diff --git a/changelog/2023.3.0.rst b/changelog/2023.3.0.rst new file mode 100644 index 00000000000..9924054b03c --- /dev/null +++ b/changelog/2023.3.0.rst @@ -0,0 +1,231 @@ +ESPHome 2023.3.0 - 15th March 2023 +================================== + +.. seo:: + :description: Changelog for ESPHome 2023.3.0. + :image: /_static/changelog-2023.3.0.png + :author: Jesse Hills + :author_twitter: @jesserockz + +.. imgtable:: + :columns: 4 + + Internal Temperature, components/sensor/internal_temperature, thermometer.svg + Mopeka Standard Check LP, components/sensor/mopeka_std_check, mopeka_std_check.jpg + Person Sensor (SEN21231), components/sensor/sen21231, sen21231.png + Haier Climate, components/climate/haier, haier.svg + FS3000, components/sensor/fs3000, fs3000.jpg + Absolute Humidity, components/sensor/absolute_humidity, water-drop.svg + AS7341, components/sensor/as7341, as7341.jpg, Spectral Color Sensor + + +Sprinkler updates +----------------- + +The sprinkler component has had a big update thanks to :ghuser:`kbx81`. +The method ``time_remaining()`` has been renamed to ``time_remaining_active_valve()`` for clarity. +If you use this to display time remaining, simply update the name of the method in your code/lambda(s). + + +Tuya lights +----------- + +Tuya Lights have had a configuration change and replaced ``rgb_datapoint`` and ``hsv_datapoint`` with a new +combination of ``color_datapoint`` and ``color_type``. See the updated documentation (:doc:`/components/light/tuya`) for more information. + + +SN74HC165 +--------- + +The pin/bit order has been reversed per shift register so that ``pin 0`` is now ``input A``. + + +Release 2023.3.1 - March 22 +--------------------------- + +- climate: brown paper bag fix for on_configure :esphomepr:`4573` by :ghuser:`nwf` +- rp2040: Use fake Mutex lock :esphomepr:`4602` by :ghuser:`jesserockz` + +Release 2023.3.2 - March 27 +--------------------------- + +- Fix compile error on pzemdc.h :esphomepr:`4583` by :ghuser:`KG3RK3N` +- Swap curly brackets for round on LockGuard :esphomepr:`4610` by :ghuser:`jesserockz` +- Fix animation resizing :esphomepr:`4608` by :ghuser:`guillempages` +- SX1509 minimum loop period (fixes esphome/issues#4325) :esphomepr:`4613` by :ghuser:`tracestep` + +Full list of changes +-------------------- + +New Components +^^^^^^^^^^^^^^ + +- Add internal_temperature component :esphomepr:`4330` by :ghuser:`Mat931` (new-integration) +- Support Mopeka Standard LPG tank bluetooth sensor :esphomepr:`4351` by :ghuser:`Fabian-Schmidt` (new-integration) +- add person sensor (SEN21231) from usefulsensors :esphomepr:`4454` by :ghuser:`shreyaskarnik` (new-integration) +- add kuntze component :esphomepr:`4411` by :ghuser:`ssieb` (new-integration) +- Add Haier climate component :esphomepr:`4001` by :ghuser:`Yarikx` (new-integration) +- FS3000 sensor :esphomepr:`4502` by :ghuser:`kahrendt` (new-integration) +- Add absolute humidity component :esphomepr:`4519` by :ghuser:`DAVe3283` (new-integration) +- Add AS7341 spectral color sensor :esphomepr:`4331` by :ghuser:`mrgnr` (new-integration) +- Renaming and extending the ili9341 to the ili9xxx component :esphomepr:`4275` by :ghuser:`nielsnl68` (new-integration) (breaking-change) + +Breaking Changes +^^^^^^^^^^^^^^^^ + +- Add configurable color datapoint :esphomepr:`4383` by :ghuser:`irtimaled` (breaking-change) +- Sprinkler "v2" updates :esphomepr:`4159` by :ghuser:`kbx81` (breaking-change) +- sn74hc165 fixes :esphomepr:`4457` by :ghuser:`jesserockz` (breaking-change) +- Renaming and extending the ili9341 to the ili9xxx component :esphomepr:`4275` by :ghuser:`nielsnl68` (new-integration) (breaking-change) + +Beta Changes +^^^^^^^^^^^^ + +- Fix ethernet clk_mode for GPIO0_OUT :esphomepr:`4307` by :ghuser:`jorticus` +- Add ESP32-S3 support in NeoPixelBus component :esphomepr:`4114` by :ghuser:`rcloran` +- Renaming and extending the ili9341 to the ili9xxx component :esphomepr:`4275` by :ghuser:`nielsnl68` (new-integration) (breaking-change) +- Drop unused, broken logging macros :esphomepr:`4534` by :ghuser:`oxan` +- Revert storing Font glyphs in manually-allocated memory :esphomepr:`4516` by :ghuser:`oxan` +- Correct BME680 gas calculation and heater_off :esphomepr:`4498` by :ghuser:`CarlosGS` +- Add support for new mpu6050 clones responding with 0x70 address :esphomepr:`4546` by :ghuser:`jakehdk` +- Add carbon dioxide device class to scd30 sensor schema. :esphomepr:`4547` by :ghuser:`murrayma` +- Feat: add support for hex color in color component :esphomepr:`4493` by :ghuser:`dorianim` +- Allow AUTO_LOAD to be a function :esphomepr:`4550` by :ghuser:`jesserockz` +- On the ILI9xxx display's enable the psram on esp32 and allow big screen :esphomepr:`4551` by :ghuser:`nielsnl68` +- Map gpio pins for touch on esp32-s2/s3 :esphomepr:`4552` by :ghuser:`jesserockz` +- pipsolar component. Correct the sscanf format for QPIG command parsin… :esphomepr:`4165` by :ghuser:`eroldan` +- Add state class back to uptime sensor :esphomepr:`4557` by :ghuser:`DAVe3283` +- Added response for Tuya RSSI command :esphomepr:`4549` by :ghuser:`catalin2402` +- Remove switch actions during config; bump setup priority :esphomepr:`4563` by :ghuser:`kbx81` +- Mark esp32_touch supported only on standard esp32 variant :esphomepr:`4562` by :ghuser:`jesserockz` +- fixing ``shrink`` and ``extend`` functions of the displaybuffer's Rect class :esphomepr:`4565` by :ghuser:`nielsnl68` + +All changes +^^^^^^^^^^^ + +- socket: Format IPv4-mapped IPv6 addresses as regular IPv4 address :esphomepr:`4382` by :ghuser:`oxan` +- Bump frenck/action-yamllint from 1.3.1 to 1.4.0 :esphomepr:`4289` by :ghuser:`dependabot[bot]` +- Bump pyupgrade from 3.3.0 to 3.3.1 :esphomepr:`4160` by :ghuser:`dependabot[bot]` +- Bump black from 22.12.0 to 23.1.0 :esphomepr:`4375` by :ghuser:`dependabot[bot]` +- Improve tuya network status command :esphomepr:`4415` by :ghuser:`Rjevski` +- Gracefully reject vacuum map upload requests :esphomepr:`4414` by :ghuser:`Rjevski` +- Fixed PlatformIO Build on DEV :esphomepr:`4422` by :ghuser:`Expaso` +- Bump platformio from 6.1.5 to 6.1.6 :esphomepr:`4341` by :ghuser:`dependabot[bot]` +- Bump pylint from 2.15.10 to 2.16.2 :esphomepr:`4426` by :ghuser:`dependabot[bot]` +- Bump aioesphomeapi from 13.1.0 to 13.3.1 :esphomepr:`4427` by :ghuser:`dependabot[bot]` +- Add concurrency limit to ci-docker :esphomepr:`4407` by :ghuser:`jesserockz` +- Add final job so branch protection can require matrix ci steps :esphomepr:`4432` by :ghuser:`jesserockz` +- Deep Sleep capable ports for ESP32S3 :esphomepr:`4230` by :ghuser:`LeDominik` +- Initialize all fields in ESPTime in PCF85063 :esphomepr:`4439` by :ghuser:`oxan` +- Bump zeroconf from 0.47.1 to 0.47.3 :esphomepr:`4437` by :ghuser:`dependabot[bot]` +- Automate syncing device classes with HA :esphomepr:`4438` by :ghuser:`oxan` +- NeoPixel - Add support for ESP32-S3 :esphomepr:`4435` by :ghuser:`ajacques` +- add SUB_BINARY_SENSOR macro to binary sensor :esphomepr:`4447` by :ghuser:`regevbr` +- add SUB_TEXT_SENSOR macro to text sensor :esphomepr:`4448` by :ghuser:`regevbr` +- Simplify sensor schema generation :esphomepr:`4462` by :ghuser:`balloob` +- add SUB_NUMBER macro and schema to number :esphomepr:`4449` by :ghuser:`regevbr` +- add SUB_BUTTON macro and ability to button schema to define the class :esphomepr:`4450` by :ghuser:`regevbr` +- Simplify number_schema function :esphomepr:`4467` by :ghuser:`jesserockz` +- Simplify button_schema function :esphomepr:`4468` by :ghuser:`jesserockz` +- Simplify binary_sensor_schema function :esphomepr:`4469` by :ghuser:`jesserockz` +- Add configurable color datapoint :esphomepr:`4383` by :ghuser:`irtimaled` (breaking-change) +- Add internal_temperature component :esphomepr:`4330` by :ghuser:`Mat931` (new-integration) +- Move remaining SENSOR_SCHEMA to use sensor_schema() :esphomepr:`4471` by :ghuser:`jesserockz` +- Allow specifying target and current visual steps for climate :esphomepr:`4440` by :ghuser:`jesserockz` +- Bump aioesphomeapi from 13.3.1 to 13.4.0 :esphomepr:`4472` by :ghuser:`dependabot[bot]` +- toshiba: add support for quiet fan mode :esphomepr:`4283` by :ghuser:`MichaelMure` +- Bump esptool from 4.4 to 4.5 :esphomepr:`4428` by :ghuser:`dependabot[bot]` +- Support Mopeka Standard LPG tank bluetooth sensor :esphomepr:`4351` by :ghuser:`Fabian-Schmidt` (new-integration) +- fix library override logic :esphomepr:`4474` by :ghuser:`mzakharo` +- Sprinkler "v2" updates :esphomepr:`4159` by :ghuser:`kbx81` (breaking-change) +- add person sensor (SEN21231) from usefulsensors :esphomepr:`4454` by :ghuser:`shreyaskarnik` (new-integration) +- Initial stab at importing idf components :esphomepr:`4000` by :ghuser:`jesserockz` +- add kuntze component :esphomepr:`4411` by :ghuser:`ssieb` (new-integration) +- Add Haier climate component :esphomepr:`4001` by :ghuser:`Yarikx` (new-integration) +- Bump esp-idf to 4.4.3 via platformio/espressif32 @ 5.3.0 :esphomepr:`4254` by :ghuser:`bdraco` +- Add energy to pzemdc :esphomepr:`3626` by :ghuser:`andreashergert1984` +- Update esp32 esp-idf dev and latest version numbers :esphomepr:`4479` by :ghuser:`jesserockz` +- [ExternalRAMAllocator] Use same `heap_caps_malloc` parameter as `ps_malloc`. :esphomepr:`4484` by :ghuser:`Fabian-Schmidt` +- Lock scheduler items while modifying them :esphomepr:`4410` by :ghuser:`oxan` +- Move Font glyphs to SPI RAM. :esphomepr:`4485` by :ghuser:`Fabian-Schmidt` +- Run CI on merge group :esphomepr:`4489` by :ghuser:`jesserockz` +- Fix parallel invocations of repeat action :esphomepr:`4480` by :ghuser:`oxan` +- Make test3 use huge_app :esphomepr:`4488` by :ghuser:`jesserockz` +- Change variable "skip_updates" and "skip_updates_counter" type from "uint8_t" to "uint16_t" :esphomepr:`4487` by :ghuser:`GitforZhangXL` +- Fix copy-pasta mistake :esphomepr:`4492` by :ghuser:`jesserockz` +- Add int16 to codegen :esphomepr:`4507` by :ghuser:`jesserockz` +- Update __init__.py :esphomepr:`4514` by :ghuser:`dashkhaneh` +- Remove idf components before checking if any in config :esphomepr:`4506` by :ghuser:`jesserockz` +- substitutions: Don't warn when passwords look like a substitution :esphomepr:`4161` by :ghuser:`tljuniper` +- Fix typo :esphomepr:`4515` by :ghuser:`oxan` +- implement pairing for bluetooth proxy :esphomepr:`4475` by :ghuser:`jagheterfredrik` +- Bump docker dependencies :esphomepr:`4526` by :ghuser:`jesserockz` +- Bump aioesphomeapi from 13.4.0 to 13.5.0 :esphomepr:`4525` by :ghuser:`dependabot[bot]` +- Ensure component is ready before update. :esphomepr:`4523` by :ghuser:`Fabian-Schmidt` +- climate: add on_control callbacks :esphomepr:`4511` by :ghuser:`nwf` +- FS3000 sensor :esphomepr:`4502` by :ghuser:`kahrendt` (new-integration) +- Bump esptool from 4.5 to 4.5.1 :esphomepr:`4497` by :ghuser:`dependabot[bot]` +- Add support for multiple devices in bme680_bsec :esphomepr:`3550` by :ghuser:`bisbastuner` +- Bump pytest from 7.2.1 to 7.2.2 :esphomepr:`4505` by :ghuser:`dependabot[bot]` +- Bump pylint from 2.16.2 to 2.16.4 :esphomepr:`4524` by :ghuser:`dependabot[bot]` +- Add absolute humidity component :esphomepr:`4519` by :ghuser:`DAVe3283` (new-integration) +- Add ability to await safe mode in codegen :esphomepr:`4529` by :ghuser:`oxan` +- sn74hc165 fixes :esphomepr:`4457` by :ghuser:`jesserockz` (breaking-change) +- Add AS7341 spectral color sensor :esphomepr:`4331` by :ghuser:`mrgnr` (new-integration) +- Fix ethernet driver setting gpio 5 high when no power pin defined :esphomepr:`4531` by :ghuser:`jesserockz` +- Use PSRam for BLE scan results. :esphomepr:`4486` by :ghuser:`Fabian-Schmidt` +- Bump esp-idf to 4.4.4 :esphomepr:`4528` by :ghuser:`bdraco` +- Added pzemdc reset energy action :esphomepr:`4481` by :ghuser:`KG3RK3N` +- Fix ethernet clk_mode for GPIO0_OUT :esphomepr:`4307` by :ghuser:`jorticus` +- Add ESP32-S3 support in NeoPixelBus component :esphomepr:`4114` by :ghuser:`rcloran` +- Renaming and extending the ili9341 to the ili9xxx component :esphomepr:`4275` by :ghuser:`nielsnl68` (new-integration) (breaking-change) +- Drop unused, broken logging macros :esphomepr:`4534` by :ghuser:`oxan` +- Revert storing Font glyphs in manually-allocated memory :esphomepr:`4516` by :ghuser:`oxan` +- Correct BME680 gas calculation and heater_off :esphomepr:`4498` by :ghuser:`CarlosGS` +- Add support for new mpu6050 clones responding with 0x70 address :esphomepr:`4546` by :ghuser:`jakehdk` +- Add carbon dioxide device class to scd30 sensor schema. :esphomepr:`4547` by :ghuser:`murrayma` +- Feat: add support for hex color in color component :esphomepr:`4493` by :ghuser:`dorianim` +- Allow AUTO_LOAD to be a function :esphomepr:`4550` by :ghuser:`jesserockz` +- On the ILI9xxx display's enable the psram on esp32 and allow big screen :esphomepr:`4551` by :ghuser:`nielsnl68` +- Map gpio pins for touch on esp32-s2/s3 :esphomepr:`4552` by :ghuser:`jesserockz` +- pipsolar component. Correct the sscanf format for QPIG command parsin… :esphomepr:`4165` by :ghuser:`eroldan` +- Add state class back to uptime sensor :esphomepr:`4557` by :ghuser:`DAVe3283` +- Added response for Tuya RSSI command :esphomepr:`4549` by :ghuser:`catalin2402` +- Remove switch actions during config; bump setup priority :esphomepr:`4563` by :ghuser:`kbx81` +- Mark esp32_touch supported only on standard esp32 variant :esphomepr:`4562` by :ghuser:`jesserockz` +- fixing ``shrink`` and ``extend`` functions of the displaybuffer's Rect class :esphomepr:`4565` by :ghuser:`nielsnl68` + +Past Changelogs +--------------- + +- :doc:`2023.2.0` +- :doc:`2022.12.0` +- :doc:`2022.11.0` +- :doc:`2022.10.0` +- :doc:`2022.9.0` +- :doc:`2022.8.0` +- :doc:`2022.6.0` +- :doc:`2022.5.0` +- :doc:`2022.4.0` +- :doc:`2022.3.0` +- :doc:`2022.2.0` +- :doc:`2022.1.0` +- :doc:`2021.12.0` +- :doc:`2021.11.0` +- :doc:`2021.10.0` +- :doc:`2021.9.0` +- :doc:`2021.8.0` +- :doc:`v1.20.0` +- :doc:`v1.19.0` +- :doc:`v1.18.0` +- :doc:`v1.17.0` +- :doc:`v1.16.0` +- :doc:`v1.15.0` +- :doc:`v1.14.0` +- :doc:`v1.13.0` +- :doc:`v1.12.0` +- :doc:`v1.11.0` +- :doc:`v1.10.0` +- :doc:`v1.9.0` +- :doc:`v1.8.0` +- :doc:`v1.7.0` diff --git a/changelog/2023.4.0.rst b/changelog/2023.4.0.rst new file mode 100644 index 00000000000..aa863df177d --- /dev/null +++ b/changelog/2023.4.0.rst @@ -0,0 +1,245 @@ +ESPHome 2023.4.0 - 19th April 2023 +================================== + +.. seo:: + :description: Changelog for ESPHome 2023.4.0. + :image: /_static/changelog-2023.4.0.png + :author: Jesse Hills + :author_twitter: @jesserockz + +.. imgtable:: + :columns: 3 + + Voice Assistant, components/voice_assistant, voice-assistant.svg + Microphone Core, components/microphone/index, microphone.svg + I2S Microphone, components/microphone/i2s_audio, i2s_audio.svg + MMC5603, components/sensor/mmc5603, mmc5603.jpg + KSZ8081 Ethernet, components/ethernet, ethernet.svg + + +Voice Assistant +--------------- + +This year is the Year of the Voice for Home Assistant, and ESPHome is charging ahead with this in mind. +We've added a new :doc:`/components/voice_assistant` component that allows you to use ESPHome devices as an input +for `assist `__ in Home Assistant. + +With this also comes preliminary :doc:`microphone ` support, which has been built in a way that multiple +components, like ``voice_assistant`` can request start / stop of the microphone and get the data. We +hope this leads to more interesting use cases for the microphone in the future. + +Home Assistant is hosting a live stream all about the Year of the Voice - Chapter 2. + +.. raw:: html + + + + +Keith joins Nabu Casa +--------------------- + +Nabu Casa is pleased to annouce that long time contributor Keith Burzinski (:ghuser:`kbx81`) is joining the +team as a full time developer to help out on ESPHome. Keith created the :doc:`/components/sprinkler`, +:doc:`/components/climate/thermostat`, a bunch of the ``ssd`` display components and a few other components +as well as fixing many bug along the way. I expect his house climate and garden area are kept well in line. + +Looking forward to working with you Keith. + +Breaking Changes +---------------- + +I²S Media Player +^^^^^^^^^^^^^^^^ + +With the introduction of the :doc:`/components/microphone/i2s_audio`, the media player platform has some +required breaking changes to the YAML configuration. This involves moving the ``i2s_lrclk_pin`` and +``i2s_bclk_pin`` to a new :doc:`/components/i2s_audio` component. + +.. code-block:: yaml + + # Before + media_player: + - platform: i2s_audio + name: ESPHome I2S Media Player + dac_type: external + i2s_lrclk_pin: GPIO33 + i2s_bclk_pin: GPIO19 + i2s_dout_pin: GPIO22 + mode: mono + + # After + i2s_audio: + i2s_lrclk_pin: GPIO33 + i2s_bclk_pin: GPIO19 + + media_player: + - platform: i2s_audio + name: ESPHome I2S Media Player + dac_type: external + i2s_dout_pin: GPIO22 + mode: mono + +Default restore mode for Switches, Fans and Lights +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The default ``restore_mode`` for switches, fans and lights has been changed +from ``RESTORE_DEFAULT_OFF`` to ``ALWAYS_OFF`` with the intention that restoring values +from flash should be manually specified by a user if desired in their YAML configuration. + +Number ``step`` +^^^^^^^^^^^^^^^ + +The ``number`` components have always internally set a ``step`` required in config, +but allowed it to be not specified at all. This caused issues on the Home Assistant side +of things. This is only a breaking change for external components that have a ``number`` platform. + +UART ids +^^^^^^^^ + +Due to ``uart0`` / ``uart1`` / ``uart2`` being defined in some of the platform code ESPHome uses, +ESPHome will now disallow these ids from being used in the config. You can simply change them to +``uart_0`` to continue using. + +Full list of changes +-------------------- + +New Components +^^^^^^^^^^^^^^ + +- Added in mmc5603 code :esphomepr:`4175` by :ghuser:`benhoff` (new-integration) +- Add push to talk voice assistant :esphomepr:`4648` by :ghuser:`jesserockz` (new-integration) + +Breaking Changes +^^^^^^^^^^^^^^^^ + +- Disallow uart0/1/2 as ids in config :esphomepr:`4446` by :ghuser:`jesserockz` (breaking-change) +- Require step to be set when calling register_number :esphomepr:`4622` by :ghuser:`jesserockz` (breaking-change) +- Fix restore :esphomepr:`4655` by :ghuser:`spacemanspiff2007` (breaking-change) + +Beta Changes +^^^^^^^^^^^^ + +- debug component, allow without debug logging :esphomepr:`4685` by :ghuser:`jesserockz` +- Fixed dns2 for ethernet :esphomepr:`4698` by :ghuser:`HeMan` +- Add timeout to i2c write error logs :esphomepr:`4697` by :ghuser:`Szewcson` +- Add event triggers to voice_assistant :esphomepr:`4699` by :ghuser:`jesserockz` +- Call on_error if no api client connected that handles voice :esphomepr:`4709` by :ghuser:`jesserockz` +- Add ethernet powerdown (fixes esphome/issues#4420) :esphomepr:`4706` by :ghuser:`tracestep` +- Bump arduino platform version to 5.3.0 :esphomepr:`4713` by :ghuser:`jesserockz` + +All changes +^^^^^^^^^^^ + +- Mark unique_id() virtual method as deprecated :esphomepr:`4538` by :ghuser:`oxan` +- Drop deprecated entity property base methods :esphomepr:`4539` by :ghuser:`oxan` +- Format test files :esphomepr:`4541` by :ghuser:`jesserockz` +- EntityBase: Icon string can stay in flash. :esphomepr:`4566` by :ghuser:`Fabian-Schmidt` +- Update the delta filter to be able to take a percentage change :esphomepr:`4391` by :ghuser:`TrentHouliston` +- Added missing PM_1_0 and PM_10_0 for PMS5003T and PMS5003ST :esphomepr:`4560` by :ghuser:`genestealer` +- Add an option to force SPI into software mode :esphomepr:`4556` by :ghuser:`wupeka` +- allow using a binary output for the status led :esphomepr:`4532` by :ghuser:`ssieb` +- Add option flip_x :esphomepr:`4555` by :ghuser:`rafal83` +- Bump aioesphomeapi from 13.5.0 to 13.5.1 :esphomepr:`4572` by :ghuser:`dependabot[bot]` +- Verbose output of define. :esphomepr:`4576` by :ghuser:`Fabian-Schmidt` +- Add support for ESP32 CAM 3MP and 5MP resolutions and arbitrary camera clock. :esphomepr:`4580` by :ghuser:`peterhalicky` +- Add a simple 'skip_initial' filter :esphomepr:`4582` by :ghuser:`sybrenstuvel` +- Fix outdated filter string in platformio_api :esphomepr:`4587` by :ghuser:`LordMike` +- Split test3.yaml :esphomepr:`4591` by :ghuser:`jesserockz` +- Disallow uart0/1/2 as ids in config :esphomepr:`4446` by :ghuser:`jesserockz` (breaking-change) +- Upgrade clang-format to v13 :esphomepr:`4535` by :ghuser:`oxan` +- B/W support for GooDisplay GDEY029T94 (as used on Adafruit MagTag) :esphomepr:`4222` by :ghuser:`AaronJackson` +- Fix negative sqrt root in ct_clamp_sensor.cpp :esphomepr:`4236` by :ghuser:`jerome992` +- Wrap ipv6 code a bit more :esphomepr:`4574` by :ghuser:`jesserockz` +- Remove EntityBase from sprinkler :esphomepr:`4606` by :ghuser:`jesserockz` +- Fix wrong port multiplexer name in dump GPIO function of sx1509 :esphomepr:`4592` by :ghuser:`skaldo` +- Bump zeroconf from 0.47.3 to 0.47.4 :esphomepr:`4597` by :ghuser:`dependabot[bot]` +- Bump pytest-asyncio from 0.20.3 to 0.21.0 :esphomepr:`4599` by :ghuser:`dependabot[bot]` +- Limit range on filter time period for remote_receiver :esphomepr:`4604` by :ghuser:`RoboMagus` +- add select_schema to select component :esphomepr:`4545` by :ghuser:`regevbr` +- Add ability to clear the gatt cache :esphomepr:`4621` by :ghuser:`bdraco` +- Bump actions/stale from 7 to 8 :esphomepr:`4615` by :ghuser:`dependabot[bot]` +- Require step to be set when calling register_number :esphomepr:`4622` by :ghuser:`jesserockz` (breaking-change) +- Lower range of CONF_FREQUENCY :esphomepr:`4619` by :ghuser:`berendhaan` +- Allow entity names to be set to None :esphomepr:`4607` by :ghuser:`jesserockz` +- Fix platform restriction for bme680_bsec :esphomepr:`4616` by :ghuser:`jesserockz` +- Fix EzoCommandType enum :esphomepr:`4593` by :ghuser:`alfredopironti` +- `EntityBase` Name can stay in flash. :esphomepr:`4594` by :ghuser:`Fabian-Schmidt` +- feat: Add support to unsubscribe from BLE advertisements :esphomepr:`4620` by :ghuser:`richardhopton` +- EntityBase: Move ObjectId to Flash :esphomepr:`4569` by :ghuser:`Fabian-Schmidt` +- Add workflow to sync device classes with HA dev :esphomepr:`4629` by :ghuser:`jesserockz` +- Synchronise Device Classes from Home Assistant :esphomepr:`4633` by :ghuser:`github-actions[bot]` +- Remove AUTO_LOAD from as3935 :esphomepr:`4630` by :ghuser:`jesserockz` +- Add ifdef to new bt proxy unsubscribe :esphomepr:`4634` by :ghuser:`jesserockz` +- add bluetooth mac address in dump_config() :esphomepr:`4628` by :ghuser:`felixlungu` +- Binary map bugfixes :esphomepr:`4636` by :ghuser:`kahrendt` +- entity_base avoid padding bytes. :esphomepr:`4637` by :ghuser:`Fabian-Schmidt` +- Avoid sensor padding. :esphomepr:`4638` by :ghuser:`Fabian-Schmidt` +- Support advanced UART customization :esphomepr:`4465` by :ghuser:`Fabian-Schmidt` +- Log calibration results at level INFO :esphomepr:`4240` by :ghuser:`Duckle29` +- Number step not optional :esphomepr:`4649` by :ghuser:`RoboMagus` +- VSCode / devcontainer updates :esphomepr:`4647` by :ghuser:`jesserockz` +- Retry PN532_COMMAND_VERSION_DATA on setup() (fixes esphome/issues#3823) :esphomepr:`4651` by :ghuser:`tracestep` +- Bump pylint from 2.16.4 to 2.17.2 :esphomepr:`4650` by :ghuser:`dependabot[bot]` +- Bump black from 23.1.0 to 23.3.0 :esphomepr:`4635` by :ghuser:`dependabot[bot]` +- Added in mmc5603 code :esphomepr:`4175` by :ghuser:`benhoff` (new-integration) +- fix compilation with latest esp-idf :esphomepr:`4671` by :ghuser:`Mic92` +- Bump zeroconf from 0.47.4 to 0.56.0 :esphomepr:`4674` by :ghuser:`dependabot[bot]` +- Bump pytest from 7.2.2 to 7.3.0 :esphomepr:`4673` by :ghuser:`dependabot[bot]` +- Add push to talk voice assistant :esphomepr:`4648` by :ghuser:`jesserockz` (new-integration) +- Fix ESP32 SPI hardware assignment in Arduino fw :esphomepr:`4669` by :ghuser:`kbx81` +- Fix some NFC/PN532 crashes :esphomepr:`4678` by :ghuser:`kbx81` +- Add support for SSD1306 72x40 displays :esphomepr:`4659` by :ghuser:`johnsto` +- Fix pin schema for i2s microphone :esphomepr:`4680` by :ghuser:`jesserockz` +- Fix BedJet setup priority [fixes esphome/issues#3807] :esphomepr:`4677` by :ghuser:`jhansche` +- Add always trigger stop :esphomepr:`4249` by :ghuser:`X-Ryl669` +- Fix graph limits for negative values and other corner cases :esphomepr:`4253` by :ghuser:`unhold` +- Fix cut-off on 2.13" waveshare/ttgo epaper displays :esphomepr:`4255` by :ghuser:`unhold` +- [Ethernet] Add PHY KSZ8081 support :esphomepr:`4668` by :ghuser:`Fabian-Schmidt` +- Fix restore :esphomepr:`4655` by :ghuser:`spacemanspiff2007` (breaking-change) +- debug component, allow without debug logging :esphomepr:`4685` by :ghuser:`jesserockz` +- Fixed dns2 for ethernet :esphomepr:`4698` by :ghuser:`HeMan` +- Add timeout to i2c write error logs :esphomepr:`4697` by :ghuser:`Szewcson` +- Add event triggers to voice_assistant :esphomepr:`4699` by :ghuser:`jesserockz` +- Call on_error if no api client connected that handles voice :esphomepr:`4709` by :ghuser:`jesserockz` +- Add ethernet powerdown (fixes esphome/issues#4420) :esphomepr:`4706` by :ghuser:`tracestep` +- Bump arduino platform version to 5.3.0 :esphomepr:`4713` by :ghuser:`jesserockz` + +Past Changelogs +--------------- + +- :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 c53744b1ab9..432d0558251 100644 --- a/changelog/index.rst +++ b/changelog/index.rst @@ -2,7 +2,7 @@ Changelog ========= .. redirect:: - :url: /changelog/2023.2.0.html + :url: /changelog/2023.4.0.html .. toctree:: :glob: diff --git a/components/binary_sensor/index.rst b/components/binary_sensor/index.rst index 8dd0a88706f..1f87eb7ea5e 100644 --- a/components/binary_sensor/index.rst +++ b/components/binary_sensor/index.rst @@ -27,6 +27,13 @@ you can always override it. Configuration variables: +- **name** (**Required**, string): The name for the binary sensor. + + .. note:: + + If you have a :ref:`friendly_name ` set for your device and + you want the binary sensor to use that name, you can set ``name: None``. + - **device_class** (*Optional*, string): The device class for the sensor. See https://developers.home-assistant.io/docs/core/entity/binary-sensor/#available-device-classes for a list of available options. diff --git a/components/binary_sensor/rc522.rst b/components/binary_sensor/rc522.rst index 0de0ef3e58c..48e60e6434c 100644 --- a/components/binary_sensor/rc522.rst +++ b/components/binary_sensor/rc522.rst @@ -1,39 +1,41 @@ -RC522 RFID -========== +RC522 NFC/RFID +============== .. seo:: - :description: Instructions for setting up RC522 RFID tag readers and tags in ESPHome + :description: Instructions for setting up RC522 NFC/RFID tag readers and tags in ESPHome :image: rc522.jpg - :keywords: RC522, RFID + :keywords: RC522, NFC, RFID .. _rc522-component: -The ``rc522`` component allows you to use RC522 RFID controllers +.. figure:: images/rc522-full.jpg + :align: center + :width: 60.0% + +The ``rc522`` component allows you to use RC522 NFC/RFID controllers (`datasheet `__, `Ali Express `__) -with ESPHome. ESPHome can read the tag UID from it, every RFID tag comes with a unique -UID value. Each known tag can be associated to a binary sensor, or you can use the tag information directly. -See :ref:`rc522-setting_up_tags` for information on how to setup individual binary sensors for this component. -The RC522 supports SPI, I²C and UART communication protocols, ESPHome can use either SPI or I²C. +with ESPHome. ESPHome can read the UID from the tag. Every NFC/RFID tag has a unique "UID" value assigned at the time +of manufacture. Tags can be associated with binary sensors, making it easy to determine when a specific tag is present. +You can also use the tag information directly within ESPHome automations/lambdas. See :ref:`rc522-setting_up_tags` for +information on how to setup individual binary sensors using this component. + +The RC522 IC supports SPI, I²C and UART communication protocols; ESPHome can use either SPI or I²C. Component/Hub ------------- -* If you have a module like the image above, it can only be used in SPI mode (`unless hacked `__) - and you need to have an :ref:`SPI bus ` in your configuration with both the **miso_pin** and **mosi_pin** set. +- If you have a module as shown in the image above, it can only be used in SPI mode + (`unless hacked `__) and you must define a :ref:`SPI bus ` + in your configuration with both the **miso_pin** and **mosi_pin** set. -* If you have a RC522 which communicates via I²C like in the M5 Stack then you need to have an :ref:`I²C ` bus configured. - -.. figure:: images/rc522-full.jpg - :align: center - :width: 60.0% +- If you have a RC522 which communicates via I²C (as on the M5 Stack), you need to have an :ref:`I²C ` bus configured. Over SPI -------- -The ``rc522_spi`` component allows you to use RC522 RFID controllers with ESPHome. This component is a global hub that -establishes the connection to the RC522 via :ref:`SPI ` (also available over I²C). Using the -:ref:`RC522 binary sensors ` you can then create individual binary sensors that track if -an RFID tag is currently detected by the RC522. +The ``rc522_spi`` component allows you to use RC522 NFC/RFID controllers with ESPHome. This component is a global hub +that establishes the connection to the RC522 via :ref:`SPI `. Using :ref:`RC522 binary sensors `, +you can then create individual binary sensors that track if an NFC/RFID tag is currently detected by the RC522. .. code-block:: yaml @@ -52,24 +54,26 @@ Configuration variables: - **cs_pin** (**Required**, :ref:`Pin Schema `): The pin on the ESP that the chip select line is connected to. -- **spi_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`SPI Component ` if you want - to use multiple SPI buses. -- **on_tag** (*Optional*, :ref:`Automation `): An automation to perform when a tag is read. See - :ref:`rc522-on_tag`. - **reset_pin** (*Optional*, :ref:`Pin Schema `): The pin connected to the RST line. Some tests shows the RC522 working okay without this. - **update_interval** (*Optional*, :ref:`config-time`): The duration of each scan on the RC522. This affects the duration that the individual binary sensors stay active when they're found. If a device is not found within this time window, it will be marked as not present. Defaults to ``1s``. +- **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. +- **on_tag** (*Optional*, :ref:`Automation `): An automation to perform when a tag is read. See + :ref:`rc522-on_tag`. +- **on_tag_removed** (*Optional*, :ref:`Automation `): An automation to perform after a tag is removed. See + :ref:`rc522-on_tag_removed`. Over I²C -------- -The ``rc522_i2c`` component allows you to use RC522 RFID controllers with ESPHome. This component is a global hub that -establishes the connection to the RC522 via :ref:`I²C ` (also available over SPI). Using the -:ref:`RC522 binary sensors ` you can then create individual binary sensors that track if -an RFID tag is currently detected by the RC522. +The ``rc522_i2c`` component allows you to use RC522 NFC/RFID controllers with ESPHome. This component is a global hub +that establishes the connection to the RC522 via :ref:`I²C ` (also available over SPI). Using the +:ref:`RC522 binary sensors ` you can then create individual binary sensors that track if +an NFC/RFID tag is currently detected by the RC522. .. code-block:: yaml @@ -86,27 +90,28 @@ Configuration variables: ************************ - **address** (*Optional*, int): Manually specify the I²C address of the sensor. Defaults to ``0x28``. -- **i2c_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`I²C Component ` if you want - to use multiple I²C buses. -- **on_tag** (*Optional*, :ref:`Automation `): An automation to perform when a tag is read. See - :ref:`rc522-on_tag`. - **reset_pin** (*Optional*, :ref:`Pin Schema `): The pin connected to the RST line. Some tests shows the RC522 working okay without this. - **update_interval** (*Optional*, :ref:`config-time`): The duration of each scan on the RC522. This affects the duration that the individual binary sensors stay active when they're found. If a device is not found within this time window, it will be marked as not present. Defaults to ``1s``. +- **i2c_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`I²C Component ` if you want + to use multiple I²C buses. - **id** (*Optional*, :ref:`config-id`): Manually specify the ID for this component. +- **on_tag** (*Optional*, :ref:`Automation `): An automation to perform when a tag is read. See + :ref:`rc522-on_tag`. +- **on_tag_removed** (*Optional*, :ref:`Automation `): An automation to perform after a tag is removed. See + :ref:`rc522-on_tag_removed`. - +Triggers +-------- .. _rc522-on_tag: -``on_tag`` Action ------------------ +``on_tag`` Trigger +****************** -This automation will be triggered when the RC522 module responds with a tag. Please note that this -can be called quite often (with an interval of ``update_interval``) as it's triggered repeatedly -if the tag is re-read many times. +This automation will be triggered immediately after the RC522 identifies a tag. The parameter ``x`` this trigger provides is of type ``std::string`` and is the tag UID in the format ``74-10-37-94``. The configuration below will for example publish the tag ID on the MQTT topic ``rc522/tag``. @@ -132,13 +137,35 @@ using :ref:`api-homeassistant_tag_scanned_action`. then: - homeassistant.tag_scanned: !lambda 'return x;' -.. _rc522-tag: +.. _rc522-on_tag_removed: + +``on_tag_removed`` Trigger +************************** + +This automation will be triggered when the RC522 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 + + rc522_spi: # or rc522_i2c + # ... + on_tag_removed: + then: + - mqtt.publish: + topic: rc522/tag_removed + payload: !lambda 'return x;' + + + +.. _rc522-binary_sensor: ``rc522`` Binary Sensor ----------------------- -The ``rc522`` binary sensor platform lets you track if an RFID tag with a given -unique id (``uid``) is currently being detected by the RC522 or not. +The ``rc522`` binary sensor platform lets you track if an NFC/RFID tag with a given unique id (``uid``) is currently +being detected by the RC522 or not. .. code-block:: yaml @@ -160,7 +187,7 @@ unique id (``uid``) is currently being detected by the RC522 or not. Configuration variables: ************************ -- **uid** (**Required**, string): The unique ID of the RFID tag. This is a hyphen-separated list +- **uid** (**Required**, string): The unique ID of the NFC/RFID tag. This is a hyphen-separated list of hexadecimal values. For example ``74-10-37-94``. - **name** (**Required**, string): The name of the binary sensor. - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. @@ -171,17 +198,16 @@ Configuration variables: Setting Up Tags --------------- -To set up binary sensors for specific RFID tags you first have to know their unique IDs. To obtain this +To set up binary sensors for specific NFC/RFID tags you first have to know their unique IDs. To obtain this id, first set up a simple RC522 configuration without any binary sensors like above. -When your code is running and you approach the RC522 with an RFID Tag, you should see a message like this: +When your code is running and you approach the RC522 with an NFC/RFID Tag, you should see a message like this: .. code:: Found new tag '74-10-37-94' -Then copy this id and create a ``binary_sensor`` entry as in the configuration example. Repeat this process for -each tag. +Then copy this id and create a ``binary_sensor`` entry as in the configuration example. Repeat this process for each tag. See Also -------- diff --git a/components/bluetooth_proxy.rst b/components/bluetooth_proxy.rst index 0f83cbe70e5..4084b6d2778 100644 --- a/components/bluetooth_proxy.rst +++ b/components/bluetooth_proxy.rst @@ -61,13 +61,16 @@ To maximize the chances of catching advertisements of the sensors, you can set ` scan_parameters: interval: 1100ms window: 1100ms +.. note:: + + For WiFi-based proxies, changing the ``interval`` or ``window`` from their default values may result in an unstable WiFi connection. Using the default values for ``interval`` and ``window`` will usually resolve any instability. Avoid placing the ESP node in racks, close to routers/switches or other network equipment as EMI interference will degrade Bluetooth signal reception. For best results put as far away as possible, at least 3 meters distance from any other such equipment. Place your ESPHome devices close to the Bluetooth devices that you want to interact with for the best experience. -Complete sample recommended configuration ------------------------------------------ +Complete sample recommended configuration for an ethernet-connected Bluetooth proxy +----------------------------------------------------------------------------------- -Below is a complete sample recommended configuration for a Bluetooth proxy. If you experience issues with your proxy, try reducing your configuration to be as similar to this as possible. +Below is a complete sample recommended configuration for an ethernet-connected Bluetooth proxy. This configuration is not for a Wi-Fi based proxy. If you experience issues with your proxy, try reducing your configuration to be as similar to this as possible. This configuration is for an Olimex ESP32-PoE-ISO board with an Ethernet connection to the network. If you use a different board, you must change the ``board`` substitution to match your board. diff --git a/components/button/index.rst b/components/button/index.rst index c91b1fac8ce..330ef4852a8 100644 --- a/components/button/index.rst +++ b/components/button/index.rst @@ -41,6 +41,12 @@ All buttons in ESPHome have a name and an optional icon. Configuration variables: - **name** (**Required**, string): The name for the button. + + .. note:: + + If you have a :ref:`friendly_name ` set for your device and + you want the button to use that name, you can set ``name: None``. + - **icon** (*Optional*, icon): Manually set the icon to use for the button in the frontend. - **internal** (*Optional*, boolean): Mark this component as internal. Internal components will not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without diff --git a/components/climate/anova.rst b/components/climate/anova.rst index a05daf1c9a4..0cfa3eac71c 100644 --- a/components/climate/anova.rst +++ b/components/climate/anova.rst @@ -26,7 +26,7 @@ You cannot use the Anova app over BLE whilst this component is connected, you should disconnect it first. To setup a (dis-)connect switch, see :doc:`/components/switch/ble_client`. You need to specify unit_of_measurement as 'c' or 'f'. This ensures the stick's display -uses the unit you intend. All values within ESPHome are converted to Celcius so you may +uses the unit you intend. All values within ESPHome are converted to Celsius so you may need to do conversion again within the frontend if you use Fahrenheit. .. warning:: diff --git a/components/climate/haier.rst b/components/climate/haier.rst new file mode 100644 index 00000000000..62be4289333 --- /dev/null +++ b/components/climate/haier.rst @@ -0,0 +1,86 @@ +Haier Climate +============= + +.. seo:: + :description: Instructions for setting up a Haier climate devices. + :image: air-conditioner.svg + +The `haier` climate platform creates a Haier climate device. +The component can be used as a replacement of a Haier proprietary WiFi modules such as KZW-W001 and KZW-W002. + +This component requires a :ref:`uart` to be setup. + +.. code-block:: yaml + + logger: + baud_rate: 0 #Disable UART logging for ESP8266 + + uart: + rx_pin: GPIO3 + tx_pin: GPIO1 + baud_rate: 9600 + + climate: + platform: haier + name: Haier AC + supported_swing_modes: + - VERTICAL + - HORIZONTAL + - BOTH + +Configuration variables: +------------------------ + +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- **name** (**Required**, string): The name of the climate device. +- **update_interval** (*Optional*, :ref:`config-time`): How often device will be polled for status. Defaults to `5s`. +- **supported_swing_modes** (*Optional*, list): List of supported swing modes. Possible values are: ``VERTICAL``, ``HORIZONTAL``, ``BOTH``. +- All other options from :ref:`Climate `. + +Hardware setup +-------------- + +Most units will have a dedicated USB-A port for Haier WiFi module. +The physical USB port is in fact UART and does not "speak" USB protocol. +It uses four USB pins as 5V, GND, RX, TX. +You can use spare male USB cable to connect esphome device directly to the climate appliance. + +Other units will not have USB ports, but will still probably have UART exposed somewhere on the main board. + +.. list-table:: Haier UART pinout + :header-rows: 1 + + * - Board + - USB + - Wire color + - ESP8266 + * - 5V + - VCC + - red + - 5V + * - GND + - GND + - black + - GND + * - TX + - DATA+ + - green + - RX + * - RX + - DATA- + - white + - TX + +.. figure:: images/usb_pinout.png + :align: center + :width: 70.0% + + USB Pinout + +See Also +-------- + +- `esphaier `__ +- :doc:`/components/climate/index` +- :apiref:`haier/climate/haier.h` +- :ghedit:`Edit` diff --git a/components/climate/images/usb_pinout.png b/components/climate/images/usb_pinout.png new file mode 100644 index 00000000000..b2d3a61df97 Binary files /dev/null and b/components/climate/images/usb_pinout.png differ diff --git a/components/climate/index.rst b/components/climate/index.rst index ad5eab2b4b0..ceebe2525da 100644 --- a/components/climate/index.rst +++ b/components/climate/index.rst @@ -20,7 +20,7 @@ and can be put in different modes like ``HEAT``, ``COOL``, ``HEAT_COOL`` or ``OF Base Climate Configuration -------------------------- -All climate platforms in ESPHome inherit from the climate configuration schema. +All climate platforms in ESPHome inherit from the climate configuration schema. In ESPHome, ``°C`` is assumed for all temperature values. Some platforms allow conversion or setting in ``°F``, this is specified separately. .. code-block:: yaml @@ -33,6 +33,13 @@ All climate platforms in ESPHome inherit from the climate configuration schema. Configuration variables: +- **name** (**Required**, string): The name of the climate device. + + .. note:: + + If you have a :ref:`friendly_name ` set for your device and + you want the climate to use that name, you can set ``name: None``. + - **icon** (*Optional*, icon): Manually set the icon to use for the climate device in the frontend. - **visual** (*Optional*): Visual settings for the climate device - these do not affect operation and are solely for controlling how the climate device shows up in the @@ -61,6 +68,41 @@ Advanced options: for a list of available options. Requires Home Assistant 2021.11 or newer. Set to ``""`` to remove the default entity category. +MQTT options: + +- **action_state_topic** (*Optional*, string): The topic to publish + climate device action changes to. +- **current_temperature_state_topic** (*Optional*, string): The topic to publish + current temperature 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 + fan mode commands on. +- **mode_state_topic** (*Optional*, string): The topic to publish + climate device mode changes to. +- **mode_command_topic** (*Optional*, string): The topic to receive + climate device mode commands on. +- **preset_state_topic** (*Optional*, string): The topic to publish + preset changes to. +- **preset_command_topic** (*Optional*, string): The topic to receive + preset commands on. +- **swing_mode_state_topic** (*Optional*, string): The topic to publish + swing mode changes to. +- **swing_mode_command_topic** (*Optional*, string): The topic to receive + swing mode commands on. +- **target_temperature_state_topic** (*Optional*, string): The topic to publish + target temperature changes to. +- **target_temperature_command_topic** (*Optional*, string): The topic to receive + target temperature commands on. +- **target_temperature_high_state_topic** (*Optional*, string): The topic to publish + higher target temperature changes to. +- **target_temperature_high_command_topic** (*Optional*, string): The topic to receive + higher target temperature commands on. +- **target_temperature_low_state_topic** (*Optional*, string): The topic to publish + lower target temperature changes to. +- **target_temperature_low_command_topic** (*Optional*, string): The topic to receive + lower target temperature commands on. +- All other options from :ref:`MQTT Component `. .. code-block:: yaml @@ -184,42 +226,24 @@ This trigger is activated each time the state of the climate device is updated on_state: - logger.log: "State updated!" -MQTT options: +.. _climate-on_control_trigger: -- **action_state_topic** (*Optional*, string): The topic to publish - climate device action changes to. -- **current_temperature_state_topic** (*Optional*, string): The topic to publish - current temperature 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 - fan mode commands on. -- **mode_state_topic** (*Optional*, string): The topic to publish - climate device mode changes to. -- **mode_command_topic** (*Optional*, string): The topic to receive - climate device mode commands on. -- **preset_state_topic** (*Optional*, string): The topic to publish - preset changes to. -- **preset_command_topic** (*Optional*, string): The topic to receive - preset commands on. -- **swing_mode_state_topic** (*Optional*, string): The topic to publish - swing mode changes to. -- **swing_mode_command_topic** (*Optional*, string): The topic to receive - swing mode commands on. -- **target_temperature_state_topic** (*Optional*, string): The topic to publish - target temperature changes to. -- **target_temperature_command_topic** (*Optional*, string): The topic to receive - target temperature commands on. -- **target_temperature_high_state_topic** (*Optional*, string): The topic to publish - higher target temperature changes to. -- **target_temperature_high_command_topic** (*Optional*, string): The topic to receive - higher target temperature commands on. -- **target_temperature_low_state_topic** (*Optional*, string): The topic to publish - lower target temperature changes to. -- **target_temperature_low_command_topic** (*Optional*, string): The topic to receive - lower target temperature commands on. -- All other options from :ref:`MQTT Component `. +``climate.on_control`` Trigger +****************************** +This trigger is activated each time a *control* input of the climate device +is updated via a ``ClimateCall`` (which includes changes coming in from Home +Assistant). That is, this trigger is activated for, for example, changes to +the mode, *but not* on temperature measurements. It will be invoked prior to +the ``on_state`` trigger, if both are defined. + +.. code-block:: yaml + + climate: + - platform: midea # or any other platform + # ... + on_control: + - logger.log: "Control input received; configuration updated!" See Also -------- diff --git a/components/climate/midea.rst b/components/climate/midea.rst index 38b89930461..fc560077e9f 100644 --- a/components/climate/midea.rst +++ b/components/climate/midea.rst @@ -20,7 +20,7 @@ The ``midea`` component creates a Midea air conditioner climate device. - `Senville `_ - and maybe others - Control is possible with a custom dongle. Example of hardware implementation is `IoT Uni Dongle `_ or `Midea SLWF-01pro `_ (`store `_, `Tindie `_). + Control is possible with a custom dongle. Example of hardware implementation is `IoT Uni Dongle `_ or `Midea SLWF-01pro `_ (`CloudFree `_, `Tindie `_). .. code-block:: yaml diff --git a/components/climate/tuya.rst b/components/climate/tuya.rst index 10f61618d85..fe48beb1bab 100644 --- a/components/climate/tuya.rst +++ b/components/climate/tuya.rst @@ -7,7 +7,7 @@ Tuya Climate The ``tuya`` climate platform creates a climate device from a tuya component. -The Tuya fan requires a :doc:`/components/tuya` to be configured. +Tuya climate requires a :doc:`/components/tuya` to be configured. .. code-block:: text diff --git a/components/cover/index.rst b/components/cover/index.rst index 4e1170faa33..d6eaeff3b16 100644 --- a/components/cover/index.rst +++ b/components/cover/index.rst @@ -28,6 +28,13 @@ All cover config schemas inherit from this schema - you can set these keys for c Configuration variables: +- **name** (**Required**, string): The name for the cover. + + .. note:: + + If you have a :ref:`friendly_name ` set for your device and + you want the cover to use that name, you can set ``name: None``. + - **device_class** (*Optional*, string): The device class for the sensor. See https://www.home-assistant.io/components/cover/ for a list of available options. - **icon** (*Optional*, icon): Manually set the icon to use for the cover in the frontend. diff --git a/components/cover/time_based.rst b/components/cover/time_based.rst index e5b3217138b..0f5e542dd0f 100644 --- a/components/cover/time_based.rst +++ b/components/cover/time_based.rst @@ -52,6 +52,13 @@ Configuration variables: detectors. In this configuration the ``stop_action`` is not performed when the open or close time is completed and if the cover is commanded to open or close the corresponding actions will be performed without checking current state. Defaults to ``false``. +- **manual_control** (*Optional*, boolean): For covers with manual external controls. With this + configuration if the cover is commanded to open or close the corresponding actions will be + performed even if the current state fully open or fully closed matches desired state, then + ``stop_action`` will be called after the full duration of the action elapses. + The current state will then be relearned upon completion. + It's recommended to set ``assumed_state`` to true so the cover control button aren't disabled + in the interface. Defaults to ``false``. - **assumed_state** (*Optional*, boolean): Whether the true state of the cover is not known. This will make the Home Assistant frontend show buttons for both OPEN and CLOSE actions, instead of hiding or disabling one of them. Defaults to ``true``. diff --git a/components/display/ili9341.rst b/components/display/ili9xxx.rst similarity index 83% rename from components/display/ili9341.rst rename to components/display/ili9xxx.rst index 58da05c1694..030e287cd8e 100644 --- a/components/display/ili9341.rst +++ b/components/display/ili9xxx.rst @@ -1,21 +1,25 @@ -ILI9341 TFT LCD -=============== + +ILI9xxx TFT LCD Series +====================== .. seo:: - :description: Instructions for setting up ILI9341 TFT LCD display drivers. + :description: Instructions for setting up ILI9xxx TFT LCD display drivers. :image: ili9341.jpg -.. _ili9341: +.. _ili9xxx: Usage ----- +This component is the successor of the ILI9341 component allowing to control more display drivers and use 16bit colors when enough free ram. -The ``ili9341`` display platform allows you to use +The ``ILI9xxx`` display platform allows you to use ILI9341 (`datasheet `__, -`Aliexpress `__) -displays with ESPHome. As this is a somewhat higher resolution display and may require pins +`Aliexpress `__) and other +displays from the same chip family with ESPHome. As this is a somewhat higher resolution display and may require pins beyond the typical SPI connections, it is better suited for use with the ESP32. +**Note:** To use 16bit instead of 8bit colors use a esp32 with enough PSRAM the display. + .. figure:: images/ili9341-full.jpg :align: center :width: 75.0% @@ -27,15 +31,13 @@ beyond the typical SPI connections, it is better suited for use with the ESP32. # Example minimal configuration entry display: - - platform: ili9341 - model: TFT 2.4 + - platform: ili9xxx + model: ili9341 cs_pin: 14 dc_pin: 27 - led_pin: 32 ### see note below ### reset_pin: 33 - lambda: |- - it.fill(Color::BLACK); + it.fill(COLOR_BLACK); it.print(0, 0, id(my_font), id(my_red), TextAlign::TOP_LEFT, "Hello World!"); Configuration variables: @@ -43,15 +45,12 @@ Configuration variables: - **model** (**Required**): The model of the display. Options are: - - ``M5STACK`` - - ``TFT 2.4`` - - ``TFT 2.4R`` (ILI9342) + - ``M5STACK``, ``TFT 2.4``, ``TFT 2.4R`` + - ``ILI9341``, ``ILI9342``, ``ILI9481``, ``ILI9486``, ``ILI9488``, ``ST7796`` - **cs_pin** (*Optional*, :ref:`Pin Schema `): The CS pin. - **dc_pin** (**Required**, :ref:`Pin Schema `): The DC pin. - **reset_pin** (*Optional*, :ref:`Pin Schema `): The RESET pin. -- **led_pin** (*Optional*, :ref:`Pin Schema `): The display's backlight pin. **Note:** Connect to a - PWM-capable pin to switch/dim the display's backlight **or** save a pin by connecting it through a 3.3K resistor to the +3V supply. - **rotation** (*Optional*): Set the rotation of the display. Everything drawn in the ``lambda:`` will be rotated per this option. One of ``0°`` (default), ``90°``, ``180°``, or ``270°``. - **lambda** (*Optional*, :ref:`lambda `): The lambda to use for rendering the content on the display. @@ -62,7 +61,7 @@ Configuration variables: - **pages** (*Optional*, list): Show pages instead of a single lambda. See :ref:`display-pages`. - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - **color_palette** (*Optional*): The type of color pallet that will be used in the ESP's internal 8-bits-per-pixel buffer. This can be used to improve color depth quality of the image. For example if you know that the display will only be showing grayscale images, the clarity of the display can be improved by targeting the available colors to monochrome only. Options are: - + - ``NONE`` (default) - ``GRAYSCALE`` - ``IMAGE_ADAPTIVE`` @@ -124,7 +123,7 @@ To configure a dimmable backlight: light: - platform: monochromatic output: gpio_32_backlight_pwm - name: "ILI9341 Display Backlight" + name: "Display Backlight" id: back_light restore_mode: ALWAYS_ON @@ -139,11 +138,10 @@ To configure an image adaptive color pallet to show greater than 8 bit color dep type: RGB24 display: - - platform: ili9341 - model: TFT 2.4 + - platform: ili9xxx + model: ili9341 cs_pin: 5 dc_pin: 4 - led_pin: 15 reset_pin: 22 rotation: 90 id: tft_ha @@ -158,5 +156,5 @@ See Also -------- - :doc:`index` -- :apiref:`ili9341/ili9341_display.h` +- :apiref:`ili9xxx/ili9xxx_display.h` - :ghedit:`Edit` diff --git a/components/display/index.rst b/components/display/index.rst index 6994b087807..b33c6859865 100644 --- a/components/display/index.rst +++ b/components/display/index.rst @@ -465,13 +465,36 @@ A ``color`` component exists for just this purpose: blue: 25% white: 0% +Alternatively, you can use ``_int`` to specify the color as an int value: + +.. code-block:: yaml + + color: + - id: my_light_red + red_int: 255 + green_int: 51 + blue_int: 64 + white_int: 0 + +Or, if you are more comforatble with hex values, you can use ``hex``: + +.. code-block:: yaml + + color: + - id: my_light_red + hex: FF3340 Configuration variables: - **red** (*Optional*, percentage): The percentage of the red component. Defaults to ``100%``. +- **red_int** (*Optional*, integer): The brightness of the red component on a scale of ``0`` to ``255``. Defaults to ``255``. - **green** (*Optional*, percentage): The percentage of the green component. Defaults to ``100%``. +- **green_int** (*Optional*, integer): The brightness of the green component on a scale of ``0`` to ``255``. Defaults to ``255``. - **blue** (*Optional*, percentage): The percentage of the blue component. Defaults to ``100%``. +- **blue_int** (*Optional*, integer): The brightness of the blue component on a scale of ``0`` to ``255``. Defaults to ``255``. - **white** (*Optional*, percentage): The percentage of the white component. Defaults to ``100%``. +- **white_int** (*Optional*, integer): The brightness of the white component on a scale of ``0`` to ``255``. Defaults to ``255``. +- **hex** (*Optional*, string): The color in hexadecimal representation. Defaults to ``FFFFFF``. RGB displays use red, green, and blue, while grayscale displays may use white. diff --git a/components/display/lcd_display.rst b/components/display/lcd_display.rst index 8527c9b39a4..bf83f011383 100644 --- a/components/display/lcd_display.rst +++ b/components/display/lcd_display.rst @@ -266,6 +266,7 @@ See Also - :doc:`/components/switch/gpio` - :doc:`/components/binary_sensor/gpio` - :ref:`LCD Menu ` +- :ref:`Add pages to LCD display ` - :doc:`/components/pcf8574` - `HD44780U (LCD-II) datasheet `__ - `Charset cheatsheet `__ diff --git a/components/display/max7219.rst b/components/display/max7219.rst index b60386cae62..4959dbb1032 100644 --- a/components/display/max7219.rst +++ b/components/display/max7219.rst @@ -104,7 +104,7 @@ segment of the previous position will be enabled. // Print the current time it.print(" "); - it.strftime("%H.%M.%S"); + it.strftime("%H.%M.%S", id(esptime).now()); // Result for 10:06:42 -> "10.06.42 " // Change the display intnsity based on another id. diff --git a/components/display/max7219digit.rst b/components/display/max7219digit.rst index dd4db5f1307..2c7923c43cc 100644 --- a/components/display/max7219digit.rst +++ b/components/display/max7219digit.rst @@ -68,6 +68,7 @@ Configuration variables: - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - **num_chip_lines** (*Optional*, int): Number of lines if you want to use the displays in Multiline Mode. Defaults to ``1`` Example: https://github.com/esphome/esphome/pull/1622#issue-836179156 - **chip_lines_style** (*Optional*): How are the lines in Multiline Mode connected? Possible values are ``zigzag`` and ``snake``. Defaults to ``snake`` +- **flip_x** (*Optional*, boolean): Flip the horizontal axis on the screen. Defaults to ``false``. .. _display-max7219digit_lambda: diff --git a/components/display/ssd1306.rst b/components/display/ssd1306.rst index 6733cceb637..6b322309ef4 100644 --- a/components/display/ssd1306.rst +++ b/components/display/ssd1306.rst @@ -51,6 +51,7 @@ Configuration variables: - ``SSD1306 128x32`` - SSD1306 with 128 columns and 32 rows - ``SSD1306 128x64`` - ``SSD1306 96x16`` + - ``SSD1306 72x40`` - ``SSD1306 64x48`` - ``SH1106 128x32`` - ``SH1106 128x64`` @@ -130,6 +131,7 @@ Configuration variables: - ``SSD1306 128x32`` (SSD1306 with 128 columns and 32 rows) - ``SSD1306 128x64`` - ``SSD1306 96x16`` + - ``SSD1306 72x40`` - ``SSD1306 64x48`` - ``SH1106 128x32`` - ``SH1106 128x64`` diff --git a/components/display/st7789v.rst b/components/display/st7789v.rst index 642e986145b..b640fc2a852 100644 --- a/components/display/st7789v.rst +++ b/components/display/st7789v.rst @@ -218,37 +218,37 @@ appropriate lines of C code in the lambda to hide or show the image or text as y id: tdisplay_button_input_1 # Allow dimmable control of the backlight (pin GPIO4) - output: - - platform: ledc - pin: GPIO4 - id: gpio4 - - light: - - platform: monochromatic - output: gpio4 - name: "Backlight" - - image: - - file: "image.png" - id: my_image - resize: 200x200 - type: RGB24 - - time: - - platform: homeassistant - id: esptime - - spi: - clk_pin: GPIO18 - mosi_pin: GPIO19 - - display: - - platform: st7789v - cs_pin: GPIO5 - dc_pin: GPIO16 - reset_pin: GPIO23 - rotation: 270 - lambda: |- + output: + - platform: ledc + pin: GPIO4 + id: gpio4 + + light: + - platform: monochromatic + output: gpio4 + name: "Backlight" + + image: + - file: "image.png" + id: my_image + resize: 200x200 + type: RGB24 + + time: + - platform: homeassistant + id: esptime + + spi: + clk_pin: GPIO18 + mosi_pin: GPIO19 + + display: + - platform: st7789v + cs_pin: GPIO5 + dc_pin: GPIO16 + reset_pin: GPIO23 + rotation: 270 + lambda: |- it.rectangle(0, 0, it.get_width(), it.get_height(), id(my_blue)); it.rectangle(0, 20, it.get_width(), it.get_height(), id(my_blue)); // header bar diff --git a/components/display/waveshare_epaper.rst b/components/display/waveshare_epaper.rst index b883d9e535c..6eeb9d23029 100644 --- a/components/display/waveshare_epaper.rst +++ b/components/display/waveshare_epaper.rst @@ -97,6 +97,7 @@ Configuration variables: - ``7.50inV2`` - Can't use with an ESP8266 as it runs out of RAM - ``7.50inV2alt`` (alternative version to the above ``7.50inV2``) - ``7.50in-hd-b`` - Can't use with an ESP8266 as it runs out of RAM + - ``gdey029t94`` - GooDisplay GDEY029T94, as used on the AdaFruit MagTag - **busy_pin** (*Optional*, :ref:`Pin Schema `): The BUSY pin. Defaults to not connected. - **reset_pin** (*Optional*, :ref:`Pin Schema `): The RESET pin. Defaults to not connected. diff --git a/components/esp32_camera.rst b/components/esp32_camera.rst index 73e402401ae..8361f0daf44 100644 --- a/components/esp32_camera.rst +++ b/components/esp32_camera.rst @@ -53,8 +53,8 @@ Connection Options: - **external_clock** (**Required**): The configuration of the external clock to drive the camera. - **pin** (**Required**, pin): The pin the external clock line is connected to. - - **frequency** (*Optional*, float): The frequency of the external clock, must be either 20MHz - or 10MHz. Defaults to ``20MHz``. + - **frequency** (*Optional*, float): The frequency of the external clock, must be between 10 + and 20MHz. Defaults to ``20MHz``. - **i2c_pins** (**Required**): The I²C control pins of the camera. @@ -90,6 +90,15 @@ Image Settings: - ``1024x768`` (XGA) - ``1280x1024`` (SXGA) - ``1600x1200`` (UXGA) + - ``1920x1080`` (FHD) + - ``720x1280`` (Portrait HD) + - ``864x1536`` (Portrait 3MP) + - ``2048x1536`` (QXGA) + - ``2560x1440`` (QHD) + - ``2560x1600`` (WQXGA) + - ``1080x1920`` (Portrait FHD) + - ``2560x1920`` (QSXGA) + - **jpeg_quality** (*Optional*, int): The JPEG quality that the camera should encode images with. From 10 (best) to 63 (worst). Defaults to ``10``. diff --git a/components/esphome.rst b/components/esphome.rst index c5a25ac384d..bbd4781d2dc 100644 --- a/components/esphome.rst +++ b/components/esphome.rst @@ -29,6 +29,9 @@ Configuration variables: characters, digits and hyphens, and can be at most 24 characters long by default, or 31 characters long if ``name_add_mac_suffix`` is ``false``. See :ref:`esphome-changing_node_name`. +- **friendly_name** (*Optional*, string): This is the name sent to the frontend. It is used + by Home Assistant as the integration name, device name, and is automatically prefixed to entities + where necessary. Advanced options: @@ -318,10 +321,16 @@ The same procedure can be done for changing the static IP of a device. Adding the MAC address as a suffix to the device name ----------------------------------------------------- -Using ``name_add_mac_suffix`` allows the user to compile a single binary file to flash -many of the same device and they will all have unique names/hostnames. -Note that you will still need to create an individual YAML config file if you want to -OTA update the devices in the future. +Using ``name_add_mac_suffix`` allows :doc:`creators ` to +provision multiple devices at the factory with a single firmware and still +have unique identification for customer installs. + +.. note:: + + End users will need to create an individual YAML config file if they want to OTA update the + devices in the future. Creators can facilitate this process by providing ``dashboard_import`` URL + for end users. This allows them to easily update their devices as new features are made available + upstream. .. _esphome-creators_project: diff --git a/components/ethernet.rst b/components/ethernet.rst index cd49e13084d..c6405d9fa98 100644 --- a/components/ethernet.rst +++ b/components/ethernet.rst @@ -40,6 +40,7 @@ Configuration variables: - ``DP83848`` - ``IP101`` - ``JL1101`` + - ``KSZ8081`` - **mdc_pin** (**Required**, :ref:`config-pin`): The MDC pin of the board. Usually this is ``GPIO23``. diff --git a/components/fan/hbridge.rst b/components/fan/hbridge.rst index 19501f5c065..0eca3db8377 100644 --- a/components/fan/hbridge.rst +++ b/components/fan/hbridge.rst @@ -50,7 +50,7 @@ Configuration variables: - **enable_pin** (*Optional*, :ref:`config-id`): The id of the :ref:`float output ` connected to the Enable pin of the h-bridge (if h-bridge uses enable). - **decay_mode** (*Optional*, string): The decay mode you want to use with - the h-bridge. Either ``slow`` (braking) or ``fast`` (coasting). Defaults to ``slow``. + the h-bridge. Either ``slow`` (coasting) or ``fast`` (braking). Defaults to ``slow``. - **speed_count** (*Optional*, int): Set the number of supported discrete speed levels. The value is used 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``. diff --git a/components/fan/index.rst b/components/fan/index.rst index 1fe4f2b518a..c6ffb649381 100644 --- a/components/fan/index.rst +++ b/components/fan/index.rst @@ -27,15 +27,21 @@ Base Fan Configuration Configuration variables: - **name** (**Required**, string): The name of the fan. + + .. note:: + + If you have a :ref:`friendly_name ` set for your device and + you want the fan to use that name, you can set ``name: None``. + - **icon** (*Optional*, icon): Manually set the icon to use for the fan in the frontend. - **restore_mode** (*Optional*): Control how the fan attempts to restore state on boot. - ``NO_RESTORE`` - Don't restore any state. - - ``RESTORE_DEFAULT_OFF`` - Attempt to restore state and default to OFF if not possible to restore (default). + - ``RESTORE_DEFAULT_OFF`` - Attempt to restore state and default to OFF if not possible to restore. - ``RESTORE_DEFAULT_ON`` - Attempt to restore state and default to ON. - ``RESTORE_INVERTED_DEFAULT_OFF`` - Attempt to restore state inverted from the previous state and default to OFF. - ``RESTORE_INVERTED_DEFAULT_ON`` - Attempt to restore state inverted from the previous state and default to ON. - - ``ALWAYS_OFF`` - Always initialize the fan as OFF on bootup. + - ``ALWAYS_OFF`` (Default) - Always initialize the fan as OFF on bootup. - ``ALWAYS_ON`` - Always initialize the fan as ON on bootup. - **internal** (*Optional*, boolean): Mark this component as internal. Internal components will diff --git a/components/gps.rst b/components/gps.rst index b674cf1ff9d..a391a2c463a 100644 --- a/components/gps.rst +++ b/components/gps.rst @@ -58,31 +58,31 @@ Configuration variables: - **longitude** (*Optional*): Include the Longitude as a sensor - - **name** (**Required**, string): The name to give the latitude sensor + - **name** (**Required**, string): The name to give the longitude sensor - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - All other options from :ref:`Sensor `. - **speed** (*Optional*): Include the measured speed as a sensor - - **name** (**Required**, string): The name to give the latitude sensor + - **name** (**Required**, string): The name to give the speed sensor - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - All other options from :ref:`Sensor `. - **course** (*Optional*): Include the measured course as a sensor - - **name** (**Required**, string): The name to give the latitude sensor + - **name** (**Required**, string): The name to give the course sensor - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - All other options from :ref:`Sensor `. - **altitude** (*Optional*): Include the measured altitude as a sensor - - **name** (**Required**, string): The name to give the latitude sensor + - **name** (**Required**, string): The name to give the altitude sensor - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - All other options from :ref:`Sensor `. - **satellites** (*Optional*): Include the number of tracking satellites being used as a sensor - - **name** (**Required**, string): The name to give the latitude sensor + - **name** (**Required**, string): The name to give the tracking satellites sensor - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - All other options from :ref:`Sensor `. diff --git a/components/i2s_audio.rst b/components/i2s_audio.rst new file mode 100644 index 00000000000..f7d59ea7abb --- /dev/null +++ b/components/i2s_audio.rst @@ -0,0 +1,29 @@ +I²S Audio Component +=================== + +.. seo:: + :description: Instructions for setting up I²S based devices in ESPHome. + :image: i2s_audio.svg + +The ``i2s_audio`` component allows for sending and receiving audio via I²S. +This component only works on ESP32 based chips. + +.. code-block:: yaml + + # Example configuration entry + i2s_audio: + i2s_lrclk_pin: GPIO33 + i2s_bclk_pin: GPIO19 + +Configuration variables: +------------------------ + +- **i2s_lrclk_pin** (**Required**, :ref:`Pin Schema `): The GPIO pin to use for the I²S LRCLK (Word Select or Left/Right Clock) signal. +- **i2s_bclk_pin** (**Required**, :ref:`Pin Schema `): The GPIO pin to use for the I²S BCLK (Bit Clock) signal. + +See also +-------- + +- :doc:`microphone/i2s_audio` +- :doc:`media_player/i2s_audio` +- :ghedit:`Edit` diff --git a/components/index.rst b/components/index.rst index 1b2dd79a247..737a782af3c 100644 --- a/components/index.rst +++ b/components/index.rst @@ -23,5 +23,6 @@ Components lock/index display_menu/index media_player/index + microphone/index time/index * diff --git a/components/light/index.rst b/components/light/index.rst index 6dd4506dddd..7c71549c62d 100644 --- a/components/light/index.rst +++ b/components/light/index.rst @@ -26,6 +26,13 @@ All light configuration schemas inherit these options. Configuration variables: +- **name** (**Required**, string): The name of the light. + + .. note:: + + If you have a :ref:`friendly_name ` set for your device and + you want the light to use that name, you can set ``name: None``. + - **icon** (*Optional*, icon): Manually set the icon to use for the light in the frontend. - **effects** (*Optional*, list): A list of :ref:`light effects ` to use for this light. - **gamma_correct** (*Optional*, float): Apply a `gamma correction @@ -39,13 +46,13 @@ Configuration variables: For restoring on ESP8266s, also see ``esp8266_restore_from_flash`` in the :doc:`esphome section `. - - ``RESTORE_DEFAULT_OFF`` (Default) - Attempt to restore state and default to OFF if not possible to restore. + - ``RESTORE_DEFAULT_OFF`` - Attempt to restore state and default to OFF if not possible to restore. - ``RESTORE_DEFAULT_ON`` - Attempt to restore state and default to ON. - ``RESTORE_INVERTED_DEFAULT_OFF`` - Attempt to restore state inverted from the previous state and default to OFF. - ``RESTORE_INVERTED_DEFAULT_ON`` - Attempt to restore state inverted from the previous state and default to ON. - ``RESTORE_AND_OFF`` - Attempt to restore state but initialize the light as OFF. - ``RESTORE_AND_ON`` - Attempt to restore state but initialize the light as ON. - - ``ALWAYS_OFF`` - Always initialize the light as OFF on bootup. + - ``ALWAYS_OFF`` (Default) - Always initialize the light as OFF on bootup. - ``ALWAYS_ON`` - Always initialize the light as ON on bootup. - **on_turn_on** (*Optional*, :ref:`Action `): An automation to perform diff --git a/components/light/neopixelbus.rst b/components/light/neopixelbus.rst index b136d5ab2ec..cc5808a113a 100644 --- a/components/light/neopixelbus.rst +++ b/components/light/neopixelbus.rst @@ -127,7 +127,8 @@ settings vary by method: - **async** (*Optional*, boolean): Use an asynchronous transfer. Defaults to ``false``. If enabled, the logger must be disabled even if bus 1 is used. -- **esp32_i2s**: The recommended method for ESP32. Available on all output pins. Additional options: +- **esp32_i2s**: The recommended method for ESP32, but not available on the ESP32-S3 or ESP32-C3. + Available on all output pins. Additional options: - **bus** (*Optional*): The I2S bus to use. The ESP32 has bus 0 or 1 available, but the ESP32-S2 only bus 0. One of ``0``, ``1``, ``dynamic``. @@ -135,7 +136,7 @@ settings vary by method: - **esp32_rmt**: An alternative method for ESP32 that uses the RMT peripheral to send data. Available on all output pins. Additional options: - - **channel** (*Optional*): The RMT channel to use. The ESP32 has channels 0-7, ESP32-S2 0-3 and ESP32-C3 0-1. + - **channel** (*Optional*): The RMT channel to use. The ESP32 has channels 0-7, ESP32-S2 0-3, ESP32-S3 0-3, and ESP32-C3 0-1. Defaults to 6 on ESP32, and 1 on other ESP32 variants. The following method is available only for two-wire chips (specify ``data_pin`` and ``clock_pin``): diff --git a/components/light/status_led.rst b/components/light/status_led.rst index 93170d9f691..99d1fa52f0d 100644 --- a/components/light/status_led.rst +++ b/components/light/status_led.rst @@ -8,6 +8,7 @@ Status LED Light The ``status_led`` light platform allows to share a single LED for indicating the status of the device (when on error/warning state) or as binary light (when on OK state). This is useful for devices with only one LED available. +You can also use a binary :ref:`output`. It provides the combined functionality of :doc:`status_led component ` and a :doc:`binary light component ` over a single shared GPIO led. @@ -33,9 +34,10 @@ When the device is in OK state, the LED will be restored to the state of the ``b Configuration variables: ------------------------ -- **name** (**Required**, string): The name of the light. -- **pin** (**Required**, :ref:`Pin Schema `): The GPIO pin to operate the LED on. +- **name** (*Optional*, string): The name of the light. - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- **pin** (*Optional*, :ref:`Pin Schema `): The GPIO pin to operate the LED on. +- **output** (*Optional*, :ref:`config-id`): The id of the binary :ref:`output` to use for this light. - **effects** (*Optional*, list): A list of :ref:`light effects ` to use for this light, though binary lights only support very few of them. - All other options from :ref:`Light `. diff --git a/components/lock/index.rst b/components/lock/index.rst index 2924e9cf25d..0428510cb88 100644 --- a/components/lock/index.rst +++ b/components/lock/index.rst @@ -6,7 +6,7 @@ Lock Component :image: folder-open.svg The ``lock`` domain includes all platforms that should function like a lock -with lock/unlock actions. +with lock/unlock actions. .. note:: @@ -26,6 +26,12 @@ Base Lock Configuration Configuration variables: - **name** (**Required**, string): The name of the lock. + + .. note:: + + If you have a :ref:`friendly_name ` set for your device and + you want the lock to use that name, you can set ``name: None``. + - **icon** (*Optional*, icon): Manually set the icon to use for the lock in the frontend. - **internal** (*Optional*, boolean): Mark this component as internal. Internal components will diff --git a/components/logger.rst b/components/logger.rst index b059efbba67..27250dab621 100644 --- a/components/logger.rst +++ b/components/logger.rst @@ -1,3 +1,5 @@ +.. _logger: + Logger Component ================ diff --git a/components/matrix_keypad.rst b/components/matrix_keypad.rst index 3fd3e579f56..c546e026174 100644 --- a/components/matrix_keypad.rst +++ b/components/matrix_keypad.rst @@ -40,9 +40,10 @@ Configuration variables: - **id** (*Optional*, :ref:`config-id`): Set the ID of this device for use in lambdas. - **rows** (**Required**, list): A list of :ref:`pins ` where the horrizontal - matrix lines are connected, in order from top to bottom. + matrix lines are connected, in order from top to bottom. These pins need to be output capable. - **columns** (**Required**, list): A list of :ref:`pins ` where the vertical - matrix lines are connected, in order from left to right. + matrix lines are connected, in order from left to right. These pins need to be input capable + with pullups enabled. If there is no internal pullup, then an external one is required. - **keys** (*Optional*, string): The keys present on the matrix, from top left to bottom right, row by row. Required for ``key_collector`` and ``binary_sensor`` (if using key selection). - **has_diodes** (*Optional*, boolean): For pads where row pins are outputs, and the keys are @@ -63,7 +64,7 @@ Individual keys can be added independently to ESPHome as ``binary_sensor``: id: key4 row: 1 col: 0 - - platform: keypad + - platform: matrix_keypad id: keyA key: A diff --git a/components/media_player/i2s_audio.rst b/components/media_player/i2s_audio.rst index 7d01e3bf33a..68e8a846e94 100644 --- a/components/media_player/i2s_audio.rst +++ b/components/media_player/i2s_audio.rst @@ -2,11 +2,11 @@ I2S Audio Media Player ====================== .. seo:: - :description: Instructions for setting up I2S based media players in ESPHome. + :description: Instructions for setting up I²S based media players in ESPHome. :image: i2s_audio.svg The ``i2s_audio`` media player platform allows you to play media from webservers and web streams -via the I2S bus. This platform only works on ESP32 based chips. +via the :doc:`/components/i2s_audio`. This platform only works on ESP32 based chips. .. code-block:: yaml @@ -15,9 +15,7 @@ via the I2S bus. This platform only works on ESP32 based chips. - platform: i2s_audio name: ESPHome I2S Media Player dac_type: external - i2s_lrclk_pin: GPIO33 i2s_dout_pin: GPIO22 - i2s_bclk_pin: GPIO19 mode: mono Configuration variables: @@ -33,10 +31,8 @@ Configuration variables: External DAC ************ -- **i2s_lrclk_pin** (**Required**, :ref:`Pin Schema `): The GPIO pin to use for the I2S LRCLK (Word Select or Left/Right Clock) signal. -- **i2s_dout_pin** (**Required**, :ref:`Pin Schema `): The GPIO pin to use for the I2S DOUT (Data Out) signal. -- **i2s_bclk_pin** (**Required**, :ref:`Pin Schema `): The GPIO pin to use for the I2S BCLK (Bit Clock) signal. -- **mode** (*Optional*, string): The mode of the I2S bus. Can be ``mono`` or ``stereo``. Defaults to ``mono``. +- **i2s_dout_pin** (**Required**, :ref:`Pin Schema `): The GPIO pin to use for the I²S DOUT (Data Out) signal. +- **mode** (*Optional*, string): The mode of the I²S bus. Can be ``mono`` or ``stereo``. Defaults to ``mono``. For best results, keep the wires as short as possible. diff --git a/components/media_player/index.rst b/components/media_player/index.rst index f5b288f844f..01a33e595b7 100644 --- a/components/media_player/index.rst +++ b/components/media_player/index.rst @@ -26,6 +26,12 @@ Base Media Player Configuration Configuration variables: - **name** (**Required**, string): The name of the media player. + + .. note:: + + If you have a :ref:`friendly_name ` set for your device and + you want the media player to use that name, you can set ``name: None``. + - **icon** (*Optional*, icon): Manually set the icon to use for the media player in the frontend. - **internal** (*Optional*, boolean): Mark this component as internal. Internal components will diff --git a/components/microphone/i2s_audio.rst b/components/microphone/i2s_audio.rst new file mode 100644 index 00000000000..255cb515ab1 --- /dev/null +++ b/components/microphone/i2s_audio.rst @@ -0,0 +1,29 @@ +I²S Audio Microphone +==================== + +.. seo:: + :description: Instructions for setting up I²S based microphones in ESPHome. + :image: i2s_audio.svg + +The ``i2s_audio`` microphone platform allows you to receive audio via the the +:doc:`/components/i2s_audio`. This platform only works on ESP32 based chips. + +.. code-block:: yaml + + # Example configuration entry + microphone: + - platform: i2s_audio + i2s_din_pin: GPIO23 + +Configuration variables: +------------------------ + +- **i2s_din_pin** (**Required**, :ref:`Pin Schema `): The GPIO pin to use for the I²S DIN (Data In) signal. + +- All other options from :ref:`Microphone ` + +See also +-------- + +- :doc:`index` +- :ghedit:`Edit` diff --git a/components/microphone/index.rst b/components/microphone/index.rst new file mode 100644 index 00000000000..405e98c662f --- /dev/null +++ b/components/microphone/index.rst @@ -0,0 +1,109 @@ +Microphone Components +===================== + +.. seo:: + :description: Instructions for setting up microphones in ESPHome. + :image: folder-open.svg + +The ``microphone`` domain contains common functionality shared across the +microphone platforms. + +.. _config-microphone: + +Base Microphone Configuration +----------------------------- + +Configuration variables: + +- **on_data** (*Optional*, :ref:`Automation `): An automation to + perform when new data is received. + +.. _microphone-actions: + +Microphone Actions +------------------ + +All ``microphone`` actions can be used without specifying an ``id`` if you have only one ``microphone`` in +your configuration YAML. + +Configuration variables: + +**id** (*Optional*, :ref:`config-id`): The microphone to control. Defaults to the only one in YAML. + + +.. _microphone-capture: + +``microphone.capture`` Action +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This action will start capturing audio data from the microphone. The data will be passed to any components listening +and will be available in the ``on_data`` trigger. + +.. _microphone-stop_capture: + +``microphone.stop_capture`` Action +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This action will stop capturing audio data from the microphone. + + +.. _microphone-triggers: + +Microphone Triggers +------------------- + +.. _microphone-on_data: + +``microphone.on_data`` Trigger +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This trigger will fire when new data is received from the microphone. +The data is available as a ``std::vector`` in the variable ``x``. + +.. code-block:: yaml + + microphone: + - platform: ... + on_data: + - logger.log: + format: "Received %d bytes" + args: ['x.size()'] + +Configuration variables: + +- **id** (*Optional*, :ref:`config-id`): The microphone to check. Defaults to the only one in YAML. + + +.. _microphone-conditions: + +Microphone Conditions +--------------------- + +All ``microphone`` conditions can be used without specifying an ``id`` if you have only one ``microphone`` in +your configuration YAML. + +Configuration variables: + +**id** (*Optional*, :ref:`config-id`): The microphone to check. Defaults to the only one in YAML. + +.. _microphone-is_capturing: + +``microphone.is_capturing`` Condition +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This condition will check if the microphone is currently capturing audio data. + + +Platforms +--------- + +.. toctree:: + :maxdepth: 1 + :glob: + + * + +See Also +-------- + +- :ghedit:`Edit` diff --git a/components/modbus.rst b/components/modbus.rst index 21f319560bf..903a0b5b8f4 100644 --- a/components/modbus.rst +++ b/components/modbus.rst @@ -44,7 +44,7 @@ See Also - :doc:`/components/switch/modbus_controller` - :doc:`/components/number/modbus_controller` - :doc:`/components/output/modbus_controller` -- :doc:`EPEVER MPPT Solar Charge Controller Tracer-AN Series` +- `EPEVER MPPT Solar Charge Controller (Tracer-AN Series) `__ - `Modbus RTU Protocol Description `__ - :ref:`uart` - :apiref:`modbus/modbus.h` diff --git a/components/modbus_controller.rst b/components/modbus_controller.rst index fe8fe947559..24d630b5fcc 100644 --- a/components/modbus_controller.rst +++ b/components/modbus_controller.rst @@ -53,7 +53,7 @@ Configuration variables: - **address** (**Required**, :ref:`config-id`): The modbus address of the device Specify the modbus device address of the. -- **command_throttle** (*Optional*, int): minimum time in milliseconds between 2 requests to the device. Default is 0ms +- **command_throttle** (*Optional*, :ref:`config-time`): minimum time in between 2 requests to the device. Default is 0ms Because some modbus devices limit the rate of requests the interval between sending requests to the device can be modified. - **update_interval** (*Optional*, :ref:`config-time`): The interval that the sensors should be checked. @@ -529,6 +529,6 @@ See Also - :doc:`/components/switch/modbus_controller` - :doc:`/components/number/modbus_controller` - :doc:`/components/output/modbus_controller` -- :doc:`EPEVER MPPT Solar Charge Controller Tracer-AN Series` +- `EPEVER MPPT Solar Charge Controller (Tracer-AN Series) `__ - `Modbus RTU Protocol Description `__ - :ghedit:`Edit` diff --git a/components/mqtt.rst b/components/mqtt.rst index 6ca647a1974..38589c5ffe2 100644 --- a/components/mqtt.rst +++ b/components/mqtt.rst @@ -83,7 +83,7 @@ Configuration variables: - **skip_cert_cn_check** (*Optional*, bool): Only with ``esp-idf``. Don't verify if the common name in the server certificate matches the value of ``broker``. - **idf_send_async** (*Optional*, bool): Only with ``esp-idf``. If true publishing the message happens from the internal mqtt task. The client only enqueues the message. Defaults to ``false``. The advantage of asyncronous publishing is that it doesn't block the esphome main thread. The disadvantage is a delay (up to 1-2 seconds) until the messages are actually sent out. - Set this to true if ypi send large amounts of of data over mqtt. + Set this to true if you send large amounts of of data over mqtt. - **reboot_timeout** (*Optional*, :ref:`config-time`): The amount of time to wait before rebooting when no MQTT connection exists. Can be disabled by setting this to ``0s``. Defaults to ``15min``. - **keepalive** (*Optional*, :ref:`config-time`): The time @@ -149,7 +149,6 @@ discovery in your Home Assistant configuration with the following: # Example Home Assistant configuration.yaml entry mqtt: broker: ... - discovery: true And that should already be it 🎉 All devices defined through ESPHome should show up automatically in the entities section of Home Assistant. @@ -172,7 +171,7 @@ With Docker: .. code-block:: bash - docker run --rm -v "${PWD}":/config -it esphome/esphome clean-mqtt configuration.yaml + docker run --rm -v "${PWD}":/config -it ghcr.io/esphome/esphome clean-mqtt configuration.yaml This will remove all retained messages with the topic ``/+/NODE_NAME/#``. If you want to purge on another @@ -308,7 +307,6 @@ Also make sure to change the ``port`` of the mqtt broker. Most brokers use port mqtt: broker: test.mymqtt.local port: 8883 - discovery: true discovery_prefix: ${mqtt_prefix}/homeassistant log_topic: ${mqtt_prefix}/logs # Evaluate carefully skip_cert_cn_check @@ -353,7 +351,6 @@ MQTT can have some overrides for specific options. name: "Component Name" # Optional variables: retain: true - discovery: true availability: topic: livingroom/status payload_available: online diff --git a/components/number/index.rst b/components/number/index.rst index e3a708bcca3..34e82cec9de 100644 --- a/components/number/index.rst +++ b/components/number/index.rst @@ -31,6 +31,12 @@ All numbers in ESPHome have a name and an optional icon. Configuration variables: - **name** (**Required**, string): The name for the number. + + .. note:: + + If you have a :ref:`friendly_name ` set for your device and + you want the number to use that name, you can set ``name: None``. + - **icon** (*Optional*, icon): Manually set the icon to use for the number in the frontend. - **internal** (*Optional*, boolean): Mark this component as internal. Internal components will not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without @@ -278,7 +284,7 @@ using a generic templatable action call. - number.operation: id: my_number operation: !lambda "return NUMBER_OP_INCREMENT;" - cycle: !lambda: "return true;" + cycle: !lambda "return true;" Configuration variables: diff --git a/components/output/bp1658cj.rst b/components/output/bp1658cj.rst index 72532934f33..84aeb213620 100644 --- a/components/output/bp1658cj.rst +++ b/components/output/bp1658cj.rst @@ -39,9 +39,9 @@ Configuration variables: this ``bp1658cj`` component. Use this if you have multiple BP1658CJ chains connected at the same time. - **max_power_color_channels** (*Optional*, int 0-15): Adjusts the current supplied to the - color channels, higher is more power. Default is 2 per BP1658CJ datasheet. See table below. + color channels, higher is more power. Default is 4 per BP1658CJ datasheet. See table below. - **max_power_white_channels** (*Optional*, int 0-15): Adjusts the current supplied to the - white channels, higher is more power. Default is 4 per BP1658CJ datasheet. See table below. + white channels, higher is more power. Default is 6 per BP1658CJ datasheet. See table below. .. note:: diff --git a/components/output/pca9685.rst b/components/output/pca9685.rst index 63c8d9f56ce..42772ecbf79 100644 --- a/components/output/pca9685.rst +++ b/components/output/pca9685.rst @@ -12,7 +12,7 @@ Component/Hub ------------- The PCA9685 component represents a PCA9685 12-bit PWM driver -(`datasheet `__, +(`datasheet `__, `adafruit `__) in ESPHome. It uses :ref:`I²C Bus ` for communication. diff --git a/components/output/template.rst b/components/output/template.rst index 6a60c249a81..267c47cca91 100644 --- a/components/output/template.rst +++ b/components/output/template.rst @@ -72,7 +72,7 @@ It is possible to access the state value inside Lambdas: - output.turn_off: button_off -Complete example from the cookbook: :doc:`Sonoff Dual Light Switch`. +Complete example: `Sonoff Dual Light Switch `__. See Also -------- diff --git a/components/pca9554.rst b/components/pca9554.rst index 373466cf403..fbeb69b141f 100644 --- a/components/pca9554.rst +++ b/components/pca9554.rst @@ -1,37 +1,44 @@ PCA9554 I/O Expander ==================== -The PCA9554 component allows you to use PCA9554, PCA9554A or PCA9536 I/O expanders -(`PCA9554 datasheet `__, -`PCA9554A datasheet `__, -`PCA9536 datasheet `__) in ESPHome. +.. seo:: + :description: Instructions for setting up PCA9554, PCA9554A, PCA9536 digital port expanders in ESPHome. + :image: ../images/pca9554a.jpg + + +The PCA9554 component allows you to use **PCA9554**, **PCA9554A** or **PCA9536** I/O expanders in ESPHome. It uses :ref:`I²C Bus ` for communication. -Once configured, you can use any of the 8 pins (PCA9554, PCA9554A) or 4 pins (PCA9536) as +.. figure:: ../images/pca9554a.jpg + :align: center + + PCA9554A I/O Expander chip + +Once configured, you can use any of the **8** pins (PCA9554, PCA9554A) or **4** pins (PCA9536) as pins for your projects. Within ESPHome they emulate a real internal GPIO pin and can therefore be used with many of ESPHome's components such as the GPIO binary sensor or GPIO switch. -The 7 bit I2C device address ranges are: +.. note:: -PCA9554 : 0x20 to 0x27 + The 7 bit I²C device address ranges are: -PCA9554A : 0x38 to 0x3F + - PCA9554: ``0x20`` to ``0x27`` + - PCA9554A: ``0x38`` to ``0x3F`` + - PCA9536: ``0x41`` -PCA9536 : 0x41 + For the PCA9554 and PCA9554A, the actual choice of the I²C device address depends on state of the 3 address pins. + Please refer to the individual datasheets linked at the bottom of the page for further details to set the address. -For the PCA9554 and PCA9554A, the actual choice of the I2C device address depends on state of the 3 address pins. -Please refer to the individual datasheets for further details. + Up to eight PCA9554 and an additional eight PCA9554A devices can reside on the same I²C bus. + Please note that only one PCA9536 device is allowed per I²C bus due to its fixed address. -Up to eight PCA9554 and an additional eight PCA9554A devices can reside on the same I2C bus. -Please note that only one PCA9536 device is allowed per I2C bus due to its fixed address. + The PCA9554 and PCA9554A provide 8 bits of GPIO's (pin numbers 0-7). + + The PCA9536 provides 4 bits of GPIO's (pin numbers 0-3). -The PCA9554 and PCA9554A provide 8 bits of GPIO's (pin numbers 0-7) -The PCA9536 provides 4 bits of GPIO's (pin numbers 0-3). - -Any option accepting a :ref:`Pin Schema ` can theoretically be used, but some more -complicated components that do communication through this I/O expander will -not work. + Any option accepting a :ref:`Pin Schema ` can theoretically be used, but some more + complicated components that do communication through this I/O expander will not work. .. code-block:: yaml @@ -40,7 +47,6 @@ not work. - id: 'pca9554a_device' address: 0x38 - # Individual outputs switch: - platform: gpio @@ -54,10 +60,11 @@ not work. output: true inverted: false + Configuration variables: ************************ -- **id** (**Required**, :ref:`config-id`): The id to use for this PCF9554 component. +- **id** (**Required**, :ref:`config-id`): The id to use for this ``pca9554`` component. - **address** (*Optional*, int): The I²C address of the driver. Defaults to ``0x20``. @@ -66,7 +73,7 @@ Configuration variables: Pin configuration variables: **************************** -- **pca9554** (**Required**, :ref:`config-id`): The id of the PCA9554 component of the pin. +- **pca9554** (**Required**, :ref:`config-id`): The id of the ``pca9554`` component of the pin. - **number** (**Required**, int): The pin number. - **inverted** (*Optional*, boolean): If all read and written values should be treated as inverted. Defaults to ``false``. @@ -79,5 +86,8 @@ See Also - :ref:`i2c` - :doc:`switch/gpio` - :doc:`binary_sensor/gpio` +- `PCA9554 datasheet `__ +- `PCA9554A datasheet `__ +- `PCA9536 datasheet `__ - :apiref:`pca9554/pca9554.h` - :ghedit:`Edit` diff --git a/components/prometheus.rst b/components/prometheus.rst index 37b9dd0b0d6..151a8c6cbe1 100644 --- a/components/prometheus.rst +++ b/components/prometheus.rst @@ -56,7 +56,7 @@ and then adding a block with ``id`` and/or ``name`` fields for each sensor whose ``relabel`` *********** -Set the the ``id`` and ``name`` label values of the Prometheus metric for the sensor with the specified ID. +Set the ``id`` and ``name`` label values of the Prometheus metric for the sensor with the specified ID. .. code-block:: yaml diff --git a/components/remote_receiver.rst b/components/remote_receiver.rst index 25954d0099d..1333615fedd 100644 --- a/components/remote_receiver.rst +++ b/components/remote_receiver.rst @@ -66,7 +66,14 @@ Configuration variables: - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. Use this if you have multiple remote receivers. +.. note:: + + The dumped **raw** code is sequence of pulse widths (durations in microseconds), positive for on-pulses (mark) + and negative for off-pulses (space). Usually you can to copy this directly to the configuration or automation to be used later. + + Automations: +------------ - **on_aeha** (*Optional*, :ref:`Automation `): An automation to perform when a AEHA remote code has been decoded. A variable ``x`` of type :apiclass:`remote_base::AEHAData` @@ -99,13 +106,6 @@ Automations: - **on_nec** (*Optional*, :ref:`Automation `): An automation to perform when a NEC remote code has been decoded. A variable ``x`` of type :apistruct:`remote_base::NECData` is passed to the automation for use in lambdas. - - .. note:: - - 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. - - **on_nexa** (*Optional*, :ref:`Automation `): An automation to perform when a Nexa RF code has been decoded. A variable ``x`` of type :apiclass:`remote_base::NexaData` is passed to the automation for use in lambdas. @@ -143,6 +143,21 @@ Automations: Toshiba AC remote code has been decoded. A variable ``x`` of type :apistruct:`remote_base::ToshibaAcData` is passed to the automation for use in lambdas. +.. code-block:: yaml + + # Example automation for decoded signals + remote_receiver: + ... + on_samsung: + then: + - if: + condition: + or: + - lambda: 'return (x.data == 0xE0E0E01F);' # VOL+ newer type + - lambda: 'return (x.data == 0xE0E0E01F0);' # VOL+ older type + then: + - ... + .. _remote-receiver-binary-sensor: Binary Sensor @@ -184,22 +199,12 @@ Remote code selection (exactly one of these has to be included): - **canalsat**: Trigger on a decoded CanalSat remote code with the given data. - .. note:: - - The CanalSat and CanalSatLD protocols use a higher carrier frequency (56khz) and are very similar. - Depending on the hardware used they may interfere with each other when enabled simultaneously. - - **device** (**Required**, int): The device to trigger on, see dumper output for more info. - **address** (**Optional**, int): The address (or subdevice) to trigger on, see dumper output for more info. Defaults to ``0`` - **command** (**Required**, int): The command to listen for. - **canalsatld**: Trigger on a decoded CanalSatLD remote code with the given data. - .. note:: - - The CanalSat and CanalSatLD protocols use a higher carrier frequency (56khz) and are very similar. - Depending on the hardware used they may interfere with each other when enabled simultaneously. - - **device** (**Required**, int): The device to trigger on, see dumper output for more info. - **address** (**Optional**, int): The address (or subdevice) to trigger on, see dumper output for more info. Defaults to ``0`` - **command** (**Required**, int): The command to listen for. @@ -235,12 +240,6 @@ Remote code selection (exactly one of these has to be included): - **nec**: Trigger on a decoded NEC remote code with the given data. - .. note:: - - 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. - - **address** (**Required**, int): The address to trigger on, see dumper output for more info. - **command** (**Required**, int): The NEC command to listen for. @@ -338,18 +337,16 @@ Remote code selection (exactly one of these has to be included): .. note:: - For the Sonoff RF Bridge you can use `this hack `__ - created by the GitHub user wildwiz. Then use this configuration for the remote receiver/transmitter hubs: + The **CanalSat** and **CanalSatLD** protocols use a higher carrier frequency (56khz) and are very similar. + Depending on the hardware used they may interfere with each other when enabled simultaneously. - .. code-block:: yaml - remote_receiver: - pin: 4 - dump: all +.. note:: + + **NEC codes**: 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. - remote_transmitter: - pin: 5 - carrier_duty_percent: 100% .. note:: @@ -367,11 +364,30 @@ Remote code selection (exactly one of these has to be included): dump: all +.. note:: + + For the Sonoff RF Bridge, you can bypass the EFM8BB1 microcontroller handling RF signals with + `this hack `__ + created by the GitHub user wildwiz. Then use this configuration for the remote receiver/transmitter hubs: + + .. code-block:: yaml + + remote_receiver: + pin: 4 + dump: all + + remote_transmitter: + pin: 5 + carrier_duty_percent: 100% + + + See Also -------- - :doc:`index` - :doc:`/components/remote_transmitter` +- :doc:`/components/rf_bridge` - `RCSwitch `__ by `Suat Özgür `__ - `IRRemoteESP8266 `__ by `Mark Szabo-Simon `__ - :apiref:`remote/remote_receiver.h` diff --git a/components/remote_transmitter.rst b/components/remote_transmitter.rst index dcc159f2365..15bf0efe881 100644 --- a/components/remote_transmitter.rst +++ b/components/remote_transmitter.rst @@ -895,6 +895,7 @@ See Also - :doc:`index` - :doc:`/components/remote_receiver` +- :ref:`lambda_magic_rf_queues` - `RCSwitch `__ by `Suat Özgür `__ - `IRRemoteESP8266 `__ by `Mark Szabo-Simon `__ - :apiref:`remote_transmitter/remote_transmitter.h` diff --git a/components/rf_bridge.rst b/components/rf_bridge.rst index f8c6a96441a..0ab8e3b73a4 100644 --- a/components/rf_bridge.rst +++ b/components/rf_bridge.rst @@ -6,8 +6,8 @@ RF Bridge Component :image: rf_bridge.jpg :keywords: RF Bridge -The ``RF Bridge`` Component provides the ability to send and receive 433MHz remote codes without hardware -hacking the circuit board to bypass the ``efm8bb1`` MCU. This component implements the communication protocol +The ``RF Bridge`` Component provides the ability to send and receive 433MHz remote codes using the +embedded EFM8BB1 microcontroller. This component implements the communication protocol that the original ``efm8bb1`` firmware implements. The device is connected via the :doc:`UART bus `. The uart bus must be configured at the same speed of the module which is 19200bps. @@ -402,5 +402,9 @@ See Also -------- - :apiref:`rf_bridge/rf_bridge.h` +- :ref:`lambda_magic_rf_queues` +- `RF-Bridge-EFM8BB1 `__ by `Portisch `__ - :doc:`/components/uart` +- :doc:`/components/remote_receiver` +- :doc:`/components/remote_transmitter` - :ghedit:`Edit` diff --git a/components/select/index.rst b/components/select/index.rst index bc5e8dc5d93..6d7e84bb884 100644 --- a/components/select/index.rst +++ b/components/select/index.rst @@ -31,6 +31,12 @@ All selects in ESPHome have a name and an optional icon. Configuration variables: - **name** (**Required**, string): The name for the select. + + .. note:: + + If you have a :ref:`friendly_name ` set for your device and + you want the select to use that name, you can set ``name: None``. + - **icon** (*Optional*, icon): Manually set the icon to use for the select in the frontend. - **internal** (*Optional*, boolean): Mark this component as internal. Internal components will not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without @@ -334,8 +340,8 @@ advanced stuff (see the full API Reference for more info). if (id(my_select).has_index(index)) { ESP_LOGI("main", "Select has index offset %d", index); } - - + + Example ------- @@ -347,13 +353,13 @@ Setting up three options and set component state to selected option value. - platform: template name: Mode id: mode - options: + options: - "Option1" - "Option2" - "Option3" initial_option: "OFF" optimistic: true - set_action: + set_action: - logger.log: format: "Chosen option: %s" args: ["x.c_str()"] diff --git a/components/select/modbus_controller.rst b/components/select/modbus_controller.rst index bbdaa79f0b1..4cc9244a668 100644 --- a/components/select/modbus_controller.rst +++ b/components/select/modbus_controller.rst @@ -40,7 +40,7 @@ Configuration variables: - ``U_DWORD_R`` (unsigned 32 bit integer from 2 registers low word first) - ``S_DWORD_R`` (signed 32 bit integer from 2 registers low word first) - ``U_QWORD`` (unsigned 64 bit integer from 4 registers = 64bit) - - ``S_QWORD`` (unsigned 64 bit integer from 4 registers = 64bit) + - ``S_QWORD`` (signed 64 bit integer from 4 registers = 64bit) - ``U_QWORD_R`` (unsigned 64 bit integer from 4 registers low word first) - ``U_QWORD_R`` (signed 64 bit integer from 4 registers low word first) diff --git a/components/sensor/absolute_humidity.rst b/components/sensor/absolute_humidity.rst new file mode 100644 index 00000000000..3ba963a81a6 --- /dev/null +++ b/components/sensor/absolute_humidity.rst @@ -0,0 +1,58 @@ +Absolute Humidity +================= + +.. seo:: + :description: Instructions for setting up absolute humidity calculation + :image: water-drop.svg + +The ``absolute_humidity`` platform allows you to calculate absolute humidity from air temperature and relative humidity. + +See the links at the bottom of the page for details on absolute humidity and the different saturated vapor pressure equations. + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: absolute_humidity + name: Absolute Humidity + temperature: air_temperature + humidity: relative_humidity + + # Use any temperature and relative humidity source, e.g. a BME280: + - platform: ... + temperature: + name: Temperature + id: air_temperature + humidity: + name: Relative Humidity + id: relative_humidity + +Configuration variables: +------------------------ + +- **name** (**Required**, string): The name for the absolute humidity sensor. +- **temperature** (**Required**, :ref:`config-id`): The sensor that is used to measure the current temperature, in °C. +- **humidity** (**Required**, :ref:`config-id`): The sensor that is used to measure the current relative humidity, in %. +- **equation** (*Optional*): The saturated vapor pressure equation to use (see below). +- All other options from :ref:`Sensor `. + +Saturated vapor pressure equations +---------------------------------- + +There are several different equations for calculating saturated vapor pressure. +``Wobus`` is used by default, as it is notionally the most accurate, but any of the following can be used: + +- ``Buck``: `Arden Buck equation `__ +- ``Tetens``: `Tetens equation `__ +- ``Wobus``: `Wobus equation `__ + +See Also +-------- + +- :ref:`sensor-filters` +- :apiref:`absolute_humidity/absolute_humidity.h` +- `NOAA Discussion on Humidity `__ +- `Absolute humidity on Wikipedia `__ +- `How to calculate absolute humidity `__ +- `How to convert relative humidity to absolute humidity `__ +- :ghedit:`Edit` diff --git a/components/sensor/adc.rst b/components/sensor/adc.rst index a8c03e99ca5..0b1267b9f5e 100644 --- a/components/sensor/adc.rst +++ b/components/sensor/adc.rst @@ -63,7 +63,7 @@ ESP32 Attenuation On the ESP32 the voltage measured with the ADC caps out at ~1.1V by default as the sensing range (attenuation of the ADC) is set to ``0db`` by default. Measuring higher voltages requires setting ``attenuation`` to one of the following values: ``0db``, ``2.5db``, ``6db``, ``11db``. -There's more information `at the manufacturer's website `__. +There's more information `at the manufacturer's website `__. To simplify this, we provide the setting ``attenuation: auto`` for an automatic/seamless transition among scales. `Our implementation `__ combines all available ranges to allow the best resolution without having to compromise on a specific attenuation. diff --git a/components/sensor/ads1115.rst b/components/sensor/ads1115.rst index ae2c30c1021..09ef99c5446 100644 --- a/components/sensor/ads1115.rst +++ b/components/sensor/ads1115.rst @@ -1,5 +1,5 @@ -ADS1115 Sensor -============== +ADS1115 4-Channel 16-Bit A/D Converter +====================================== .. seo:: :description: Instructions for setting up ADS1115/ADS1015 multiplexed analog voltage sensors. diff --git a/components/sensor/aht10.rst b/components/sensor/aht10.rst index 4e05a9893bc..e5a859e7a3e 100644 --- a/components/sensor/aht10.rst +++ b/components/sensor/aht10.rst @@ -58,6 +58,7 @@ See Also -------- - :ref:`sensor-filters` +- :doc:`absolute_humidity` - :apiref:`aht10/aht10.h` - `AHT10 Library `__ by `Thinary Electronic `__ - `Unofficial Translated AHT10 Datasheet (en) `__ diff --git a/components/sensor/am2320.rst b/components/sensor/am2320.rst index 574e880c530..9ed04dde965 100644 --- a/components/sensor/am2320.rst +++ b/components/sensor/am2320.rst @@ -57,6 +57,7 @@ See Also -------- - :ref:`sensor-filters` +- :doc:`absolute_humidity` - :doc:`dht` - :doc:`dht12` - :doc:`hdc1080` diff --git a/components/sensor/as7341.rst b/components/sensor/as7341.rst new file mode 100644 index 00000000000..b6a14c68b19 --- /dev/null +++ b/components/sensor/as7341.rst @@ -0,0 +1,96 @@ +AS7341 Spectral Color Sensor +============================ + +.. seo:: + :description: Instructions for setting up AS7341 spectral color sensor. + :image: as7341.jpg + :keywords: AS7341 + +The ``as7341`` sensor platform allows you to use your AS7341 spectral color sensor +(`datasheet `__, +`Adafruit`_) with ESPHome. The :ref:`I²C Bus ` is required to be set up in +your configuration for this sensor to work. + +.. figure:: images/as7341-full.jpg + :align: center + :width: 50.0% + + AS7341 Spectral Color Sensor + +.. _Adafruit: https://www.adafruit.com/product/4698 + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: as7341 + f1: + name: "415nm" + f2: + name: "445nm" + f3: + name: "480nm" + f4: + name: "515nm" + f5: + name: "555nm" + f6: + name: "590nm" + f7: + name: "630nm" + f8: + name: "680nm" + clear: + name: "Clear" + nir: + name: "NIR" + + +Configuration variables +----------------------- + +- **f1** (*Optional*): The reading for the 415nm channel. All options from :ref:`Sensor `. +- **f2** (*Optional*): The reading for the 445nm channel. All options from :ref:`Sensor `. +- **f3** (*Optional*): The reading for the 480nm channel. All options from :ref:`Sensor `. +- **f4** (*Optional*): The reading for the 515nm channel. All options from :ref:`Sensor `. +- **f5** (*Optional*): The reading for the 555nm channel. All options from :ref:`Sensor `. +- **f6** (*Optional*): The reading for the 590nm channel. All options from :ref:`Sensor `. +- **f7** (*Optional*): The reading for the 630nm channel. All options from :ref:`Sensor `. +- **f8** (*Optional*): The reading for the 680nm channel. All options from :ref:`Sensor `. +- **clear** (*Optional*): The reading for the clear channel. All options from :ref:`Sensor `. +- **nir** (*Optional*): The reading for the NIR (near-infrared) channel. All options from :ref:`Sensor `. +- **gain** (*Optional*): The gain used by the device. A higher gain may be more suitable for lower-light environments. Must be one of: + + - ``X0.5`` + - ``X1`` + - ``X2`` + - ``X4`` + - ``X8`` (*default*) + - ``X16`` + - ``X32`` + - ``X64`` + - ``X128`` + - ``X256`` + - ``X512`` + +- **astep** (*Optional*): The number of integration steps. Default is ``599``. Must be between ``0`` and ``65534``. +- **atime** (*Optional*): The integration time per step in increments of 2.78µs. Default is ``29``. Must be between ``0`` and ``255``. +- All other options for I²C devices described at :ref:`I²C Bus `. + +Integration time +---------------- + +The integration time determines how long a channel measurement takes and depends on ``ATIME`` and ``ASTEP``. The formula for the total integration time is: + +.. math:: + + \text{t} = \text{(ATIME + 1)} \times \text{(ASTEP + 1)} \times \text{2.78µS} + +See Also +-------- + +- :ref:`sensor-filters` +- `Adafruit_AS7341 `__ +- `SparkFun_AS7341X_Arduino_Library `__ +- :apiref:`as7341/as7341.h` +- :ghedit:`Edit` diff --git a/components/sensor/b_parasite.rst b/components/sensor/b_parasite.rst index e38ddd3e3a3..ce738a98a4a 100644 --- a/components/sensor/b_parasite.rst +++ b/components/sensor/b_parasite.rst @@ -66,4 +66,5 @@ See Also - `b-parasite on GitHub `__ - :doc:`/components/esp32_ble_tracker` +- :doc:`absolute_humidity` - :ghedit:`Edit` diff --git a/components/sensor/binary_sensor_map.rst b/components/sensor/binary_sensor_map.rst index 7c682c827ca..82e4ccf49db 100644 --- a/components/sensor/binary_sensor_map.rst +++ b/components/sensor/binary_sensor_map.rst @@ -5,19 +5,50 @@ Binary Sensor Map :description: Instructions for setting up a Binary Sensor Map :image: binary_sensor_map.jpg -The ``binary_sensor_map`` sensor platform allows you to map :doc:`binary sensor ` -to values. When a given binary sensor is on, the value associated with it in this platform's configuration will be published. +The ``binary_sensor_map`` sensor platform allows you to map multiple :doc:`binary sensor ` +to an individual value. Depending on the state of each binary sensor, its associated configured parameters, and this sensor's mapping type, +the ``binary_sensor_map`` publishes a single numerical value. -This sensor is **mostly used for touch** devices but could be used for any ``binary_sensor`` that publishes its ``ON`` or ``OFF`` state. +Use this sensor to combine one or more binary sensors' ``ON`` or ``OFF`` states into a numerical value. Some possible use cases include +touch devices and determining Bayesian probabilities for an event. -Add your binary sensors as ``channels`` to the binary sensor map. The binary sensor map then publishes a value depending -on the type of the binary sensor map and the values specified with each channel. +This platform supports three measurement types: ``BAYESIAN``, ``GROUP``, and ``SUM``. +You need to specify your desired mapping with the ``type:`` configuration value. -This platform currently supports two measurement types: ``GROUP`` and ``SUM``, and others might get added later. -You need to specify which type of mapping you want with the ``type:`` configuration value: +When using the ``BAYESIAN`` type, add your binary sensors as ``observations`` to the binary sensor map. +If you use the ``GROUP`` or ``SUM`` type, add your binary sensors as ``channels``. +The maximum amount of observations/channels supported is 64. -- ``GROUP`` Each channel has its own value. The sensor publishes the average value of all active - binary sensors. +- ``BAYESIAN`` This type replicates Home Assistant's `Bayesian sensor `__. Based on the observation states, this sensor returns the Bayesian probability of a particular event occurring. The configured ``prior:`` probability is the likelihood that the Bayesian event is true, ignoring all external influences. Every observation has its own ``prob_given_true`` and ``prob_given_false`` parameters. The ``prob_given_true:`` value is the probability that the observation's binary sensor is ``ON`` when the Bayesian event is ``true``. The ``prob_given_false:`` value is the probability that the observation's binary sensor is ``ON`` when the Bayesian event is ``false``. Use an :doc:`/components/binary_sensor/analog_threshold` to convert this sensor's probability to a binary ``ON`` or ``OFF`` by setting an appropriate threshold. + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: binary_sensor_map + id: bayesian_prob + name: 'Bayesian Event Probability' + type: bayesian + prior: 0.4 + observations: + - binary_sensor: binary_sensor_0 + prob_given_true: 0.9 + prob_given_false: 0.2 + - binary_sensor: binary_sensor_1 + prob_given_true: 0.6 + prob_given_false: 0.1 + + binary_sensor: + # If the Bayesian probability is greater than 0.6, + # then predict the event is occuring + - platform: analog_threshold + name: "Bayesian Event Predicted State" + sensor_id: bayesian_prob + threshold: 0.6 + # ... + +- ``GROUP`` Each channel has its own ``value``. The sensor publishes the average value of all active + binary sensors or ``NAN`` if no sensors are active. .. code-block:: yaml @@ -48,8 +79,8 @@ You need to specify which type of mapping you want with the ``type:`` configurat id: touchkey0 # ... -- ``SUM`` Each channel has its own value. The sensor publishes the sum of all active - binary sensors values. +- ``SUM`` Each channel has its own ``value``. The sensor publishes the sum of all the active + binary sensors values or ``0`` if no sensors are active. .. code-block:: yaml @@ -91,12 +122,19 @@ Configuration variables: ------------------------ - **name** (**Required**, string): The name of the sensor. -- **type** (**Required**, string): The sensor type. Should be one of: ``GROUP``. -- **channels** (**Required**): A list of channels that are mapped to certain values. +- **type** (**Required**, string): The sensor type. Should be one of: ``BAYESIAN``, ``GROUP``, or ``SUM``. +- **channels** (**Required for GROUP or SUM types**): A list of channels that are mapped to certain values. - **binary_sensor** (**Required**): The id of the :doc:`binary sensor ` to add as a channel for this sensor. - **value** (**Required**): The value this channel should report when its binary sensor is active. +- **prior** (**Required for BAYESIAN type**, float between 0 and 1): The prior probability of the event. +- **observations** (**Required for BAYESIAN type**): A list of observations that influence the Bayesian probability of the event. + + - **binary_sensor** (**Required**): The id of the :doc:`binary sensor ` + to add as an observation. + - **prob_given_true** (**Required**, float between 0 and 1): Assuming the event is true, the probability this observation is on. + - **prob_given_false** (**Required**, float between 0 and 1): Assuming the event is false, the probability this observation is on. - All other options from :ref:`Sensor `. @@ -104,6 +142,8 @@ See Also -------- - :doc:`/components/binary_sensor/mpr121` +- :doc:`/components/binary_sensor/analog_threshold` - :ref:`sensor-filters` - :apiref:`binary_sensor_map/binary_sensor_map.h` +- `Bayesian sensor in Home Assistant `__ - :ghedit:`Edit` diff --git a/components/sensor/bme280.rst b/components/sensor/bme280.rst index e4ce7bdd058..037f36c9924 100644 --- a/components/sensor/bme280.rst +++ b/components/sensor/bme280.rst @@ -8,7 +8,9 @@ BME280 Temperature+Pressure+Humidity Sensor The ``bme280`` sensor platform allows you to use your BME280 (`datasheet `__, -`Adafruit`_) temperature, pressure and humidity sensors with ESPHome. The :ref:`I²C ` is +`Adafruit`_) temperature, pressure and humidity sensors with ESPHome. The sensor +is used in *Forced Mode* where measurement is performed and then +the sensor returns to sleep mode until next measurement. The :ref:`I²C ` is required to be set up in your configuration for this sensor to work. .. figure:: images/bme280-full.jpg @@ -89,6 +91,7 @@ See Also -------- - :ref:`sensor-filters` +- :doc:`absolute_humidity` - :doc:`bme680` - :doc:`bmp085` - :apiref:`bme280/bme280.h` diff --git a/components/sensor/bme680.rst b/components/sensor/bme680.rst index 7522a301e76..e5c00804279 100644 --- a/components/sensor/bme680.rst +++ b/components/sensor/bme680.rst @@ -107,6 +107,7 @@ See Also -------- - :ref:`sensor-filters` +- :doc:`absolute_humidity` - :doc:`bme280` - :doc:`bmp085` - :apiref:`bme680/bme680.h` diff --git a/components/sensor/bme680_bsec.rst b/components/sensor/bme680_bsec.rst index fa7c0f5d7f1..e0b3146c49c 100644 --- a/components/sensor/bme680_bsec.rst +++ b/components/sensor/bme680_bsec.rst @@ -2,7 +2,7 @@ BME680 Temperature+Pressure+Humidity+Gas Sensor via BSEC ======================================================== .. seo:: - :description: Instructions for setting up BME680 temperature, humidity, pressure and gas sensors via BSEC. + :description: Instructions for setting up BME680 temperature, humidity, pressure, and gas sensors via BSEC. :image: bme680.jpg :keywords: BME680 @@ -12,12 +12,13 @@ Component/Hub The ``bme680_bsec`` sensor platform allows you to use your BME680 (`datasheet `__, `Adafruit`_) temperature, pressure and humidity and gas sensors with ESPHome via the Bosch Sensortec Environmental Cluster (BSEC) -software library. The use of Bosch's proprietary algorithms provides additional Indoor Air Quality (IAQ), CO2 equivalent and Breath -Volatile Organic Compounds (VOC) equivalent measurements. +software library. The use of Bosch's proprietary algorithms provide an Index for Air Quality (IAQ) measurement derived from the +gas resistance sensor's response to specific Volatile Organic Compounds (VOC). The BSEC software also provides estimated values +for CO₂ and Breath Volatile Organic Compounds (b-VOC) using a correlation between VOC and CO₂ in a human's exhaled breath. .. note:: - The Bosch BSEC library is only available for use after accepting its software license agreement. By enabling this component, + The BSEC library is only available for use after accepting its software license agreement. By enabling this component, you are explicitly agreeing to the terms of the `BSEC license agreement`_. You must not distribute any compiled firmware binaries that include this component. @@ -60,7 +61,7 @@ The :ref:`I²C ` is required to be set up in your configuration for this se - platform: bme680_bsec iaq_accuracy: name: "BME680 IAQ Accuracy" - + - platform: template name: "BME680 IAQ Classification" icon: "mdi:checkbox-marked-circle-outline" @@ -92,7 +93,7 @@ The :ref:`I²C ` is required to be set up in your configuration for this se Configuration variables: -- **address** (*Optional*, int): Manually specify the I^2C address of the sensor. Defaults to ``0x76``. Another address can be ``0x77``. +- **address** (*Optional*, int): Manually specify the I²C address of the sensor. Defaults to ``0x76``. Another address can be ``0x77``. - **temperature_offset** (*Optional*, float): Temperature offset if device is in enclosure and reads too high. This value is subtracted from the reading (e.g. if the sensor reads 5°C higher than expected, set this to ``5``) and also corrects the relative humidity readings. Defaults to ``0``. @@ -101,37 +102,41 @@ Configuration variables: Can be ``mobile`` for mobile applications (e.g. carry-on devices). - **sample_rate** (*Optional*, string): Sample rate. Default is ``lp`` for low power consumption, sampling every 3 seconds. - Can be ``ulp`` for ultra low power, sampling every 5 minutes. - This controls the sampling rate for gas-dependant sensors and will govern the interval at which the sensor heater is operated. - By default this rate will also be used for temperature, pressure and humidity sensors but these can be overridden on a per-sensor level if required. + Can be ``ulp`` for ultra-low power, sampling every 5 minutes. + This controls the sampling rate for gas-dependent sensors and will govern the interval at which the sensor heater is operated. + By default, this rate will also be used for temperature, pressure, and humidity sensors but these can be overridden on a per-sensor level if required. - **state_save_interval** (*Optional*, :ref:`config-time`): The minimum interval at which to save calibrated BSEC algorithm state to flash so that calibration doesn't have to start from zero on device restart. Defaults to ``6h``. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. Use this ID in the sensor section to refer to the correct BME680 if you have more than one device. This will also be used to refer to the calibrated BSEC algorithm state saved to flash. + Sensor ------ Configuration variables: +- **bme680_bsec_id** (*Optional*, :ref:`config-id`): Sets the ID of the bme680_bsec component to refer to. Useful when working with multiple devices. + - **temperature** (*Optional*): The information for the temperature sensor. - **name** (**Required**, string): The name for the temperature sensor. - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - **sample_rate** (*Optional*, string): Optional sample rate override for this sensor. Can be ``lp`` for low power consumption, sampling every 3 seconds or ``ulp`` for ultra low power, sampling every 5 minutes. + - **sample_rate** (*Optional*, string): Optional sample rate override for this sensor. Can be ``lp`` for low power consumption, sampling every 3 seconds or ``ulp`` for ultra-low power, sampling every 5 minutes. - All other options from :ref:`Sensor `. - **pressure** (*Optional*): The information for the pressure sensor. - **name** (**Required**, string): The name for the pressure sensor. - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - **sample_rate** (*Optional*, string): Optional sample rate override for this sensor. Can be ``lp`` for low power consumption, sampling every 3 seconds or ``ulp`` for ultra low power, sampling every 5 minutes. + - **sample_rate** (*Optional*, string): Optional sample rate override for this sensor. Can be ``lp`` for low power consumption, sampling every 3 seconds or ``ulp`` for ultra-low power, sampling every 5 minutes. - All other options from :ref:`Sensor `. - **humidity** (*Optional*): The information for the humidity sensor. - **name** (**Required**, string): The name for the humidity sensor. - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - - **sample_rate** (*Optional*, string): Optional sample rate override for this sensor. Can be ``lp`` for low power consumption, sampling every 3 seconds or ``ulp`` for ultra low power, sampling every 5 minutes. + - **sample_rate** (*Optional*, string): Optional sample rate override for this sensor. Can be ``lp`` for low power consumption, sampling every 3 seconds or ``ulp`` for ultra-low power, sampling every 5 minutes. - All other options from :ref:`Sensor `. - **gas_resistance** (*Optional*): The information for the gas sensor. @@ -152,9 +157,9 @@ Configuration variables: - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - All other options from :ref:`Sensor `. -- **co2_equivalent** (*Optional*): The information for the CO2 equivalent sensor. +- **co2_equivalent** (*Optional*): The information for the CO₂ equivalent sensor. - - **name** (**Required**, string): The name for the CO2 equivalent sensor. + - **name** (**Required**, string): The name for the CO₂ equivalent sensor. - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - All other options from :ref:`Sensor `. @@ -171,6 +176,8 @@ Accuracy can be reported in text format. Configuration variables: +- **bme680_bsec_id** (*Optional*, :ref:`config-id`): Sets the ID of the bme680_bsec component to refer to. Useful when working with multiple devices. + - **iaq_accuracy** (*Optional*): The information for the IAQ accuracy sensor. Shows: Stabilizing, Uncertain, Calibrating, Calibrated. @@ -188,11 +195,18 @@ Advanced configuration The following configuration shows all the available sensors and optional settings for the component. It also includes an example of filtering to guard against outliers, limit the number of updates sent to home assistant and reduce storage requirements in other systems such as influxdb used to store historical data. -For each sensor all other options from :ref:`Sensor ` and :ref:`TextSensor ` are also available for filtering, automation and so on. +For each sensor, all other options from :ref:`Sensor ` and :ref:`TextSensor ` are also available for filtering, automation and so on. .. code-block:: yaml bme680_bsec: + # id + # ----------- + # Identifier for this component, useful when working with multiple devices. + # Must be unique, and can be used in the sensor sections to refer to the correct device. + # Default: auto-computed + id: bme680_internal + # i2c address # ----------- # Common values are: @@ -204,7 +218,7 @@ For each sensor all other options from :ref:`Sensor ` and :ref:`T # Temperature offset # ------------------ # Useful if device is in enclosure and reads too high - # For example if it reads 5C too high, set this to 5 + # For example, if it reads 5C too high, set this to 5 # This also corrects the relative humidity readings # Default: 0 temperature_offset: 0 @@ -213,7 +227,7 @@ For each sensor all other options from :ref:`Sensor ` and :ref:`T # -------------------- # Available options: # - static (for fixed position devices) - # - mobile (for on person or other moveable devices) + # - mobile (for on a person or other moveable devices) # Default: static iaq_mode: static @@ -221,7 +235,7 @@ For each sensor all other options from :ref:`Sensor ` and :ref:`T # ----------- # Available options: # - lp (low power - samples every 3 seconds) - # - ulp (ultra low power - samples every 5 minutes) + # - ulp (ultra-low power - samples every 5 minutes) # Default: lp sample_rate: ulp @@ -232,6 +246,10 @@ For each sensor all other options from :ref:`Sensor ` and :ref:`T sensor: - platform: bme680_bsec + # ID of the bme680_bsec component to use for the next sensors. + # Useful when working with multiple devices + bme680_bsec_id: bme680_internal + temperature: # Temperature in °C name: "BME680 Temperature" @@ -281,19 +299,133 @@ For each sensor all other options from :ref:`Sensor ` and :ref:`T name: "BME680 IAQ Accuracy" -Indoor Air Quality (IAQ) Measurement ------------------------------------- +Multiple sensors +---------------------- + +The following configuration shows how to set up multiple BME680 devices. They can be configured to use the same I²C bus or to use different busses, but remember that the BME680 can only be set to operate on I²C address ``0x76`` or ``0x77``. There is no limit on the number of BME680 devices that can be connected. + + +.. code-block:: yaml + + # I2C bus for the BME680 devices + i2c: + - id: "i2cbus_bme" + sda: GPIO18 + scl: GPIO19 + scan: true + + # BME680 devices using BSEC library + bme680_bsec: + - id: bme680_internal + i2c_id: "i2cbus_bme" + address: 0x76 + - id: bme680_external + i2c_id: "i2cbus_bme" + address: 0x77 + + sensor: + # Sensors for the internal BME680 device + - platform: bme680_bsec + bme680_bsec_id: bme680_internal + temperature: + name: "IN_Temp" + pressure: + name: "IN_Press" + humidity: + name: "IN_RH" + iaq: + name: "IN_IAQ" + co2_equivalent: + name: "IN_CO2eq" + breath_voc_equivalent: + name: "IN_VOCeq" + + # Sensors for the external BME680 device + - platform: bme680_bsec + bme680_bsec_id: bme680_external + temperature: + name: "OUT_Temperatura" + pressure: + name: "OUT_Pressione" + humidity: + name: "OUT_RH" + iaq: + name: "OUT_IAQ" + co2_equivalent: + name: "OUT_CO2eq" + breath_voc_equivalent: + name: "OUT_VOCeq" + + text_sensor: + # Text sensor for the internal BME680 device + - platform: bme680_bsec + bme680_bsec_id: bme680_internal + iaq_accuracy: + name: "IN_IAQaccuracy" + + # Text sensor for the external BME680 device + - platform: bme680_bsec + bme680_bsec_id: bme680_external + iaq_accuracy: + name: "OUT_IAQaccuracy" + +Index for Air Quality (IAQ) Measurement +--------------------------------------- + +The measurements are expressed with an index scale ranging from 0 to 500. The index itself is deduced +from tests using ethanol gas, as well as important VOC in the exhaled breath of healthy humans. +The VOC values themselves are derived from several publications on breath analysis studies. The BSEC +software library defines the levels as follows: + ++-----------+---------------------+ +| IAQ Index | Air Quality | ++===========+=====================+ +| 0 - 50 | Excellent | ++-----------+---------------------+ +| 51 - 100 | Good | ++-----------+---------------------+ +| 101 - 150 | Lightly polluted | ++-----------+---------------------+ +| 151 - 200 | Moderately polluted | ++-----------+---------------------+ +| 201 - 250 | Heavily polluted | ++-----------+---------------------+ +| 251 - 350 | Severely polluted | ++-----------+---------------------+ +| > 351 | Extremely polluted | ++-----------+---------------------+ + +The selected b-VOC gasses are as follows: + ++--------------------+----------------+ +| Compound | Molar fraction | ++====================+================+ +| `Ethane`_ | 5 ppm | ++--------------------+----------------+ +| `Isoprene`_ | 10 ppm | ++--------------------+----------------+ +| `Ethanol`_ | 10 ppm | ++--------------------+----------------+ +| `Acetone`_ | 50 ppm | ++--------------------+----------------+ +| `Carbon Monoxide`_ | 15 ppm | ++--------------------+----------------+ + +.. _Ethane: https://en.wikipedia.org/wiki/Ethane +.. _Isoprene: https://en.wikipedia.org/wiki/Isoprene +.. _Ethanol: https://en.wikipedia.org/wiki/Ethanol +.. _Acetone: https://en.wikipedia.org/wiki/Acetone +.. _Carbon Monoxide: https://en.wikipedia.org/wiki/Carbon_monoxide -Indoor Air Quality measurements are expressed in the IAQ index scale with 25IAQ corresponding to typical good air and 250IAQ -indicating typical polluted air after calibration. .. _bsec-calibration: IAQ Accuracy and Calibration ---------------------------- -The BSEC algorithm automatically gathers data in order to calibrate the IAQ measurements. The IAQ Accuracy sensor will give one -of the following values: +The BSEC software automatically calibrates automatically in the background to provide consistent IAQ performance. The +calibration process considers the recent measurement history so that a value of 50 corresponds to a “typical good” +level and a value of 200 to a “typical polluted” level. The IAQ Accuracy sensor will give one of the following values: - ``Stabilizing``: The device has just started, and the sensor is stabilizing (this typically lasts 5 minutes) - ``Uncertain``: The background history of BSEC is uncertain. This typically means the gas sensor data was too @@ -308,8 +440,10 @@ See Also -------- - :ref:`sensor-filters` +- :doc:`absolute_humidity` - :doc:`bme680` - :apiref:`bme680_bsec/bme680_bsec.h` +- `BME680 Datasheet `__ - `BME680 VOC classification `__ - `BSEC Arduino Library `__ by `Bosch Sensortec `__ - `Bosch Sensortec Community `__ diff --git a/components/sensor/dallas.rst b/components/sensor/dallas.rst index 2c0698774db..8f6e2e55773 100644 --- a/components/sensor/dallas.rst +++ b/components/sensor/dallas.rst @@ -145,6 +145,29 @@ You will see the outputted sensor values changing when they're being warmed. When you're finished mapping each address to a name, just change the ``Temperature #1`` to your assigned names and you should be ready. +Multiple dallas hubs +******************** + +Use this if you have multiple dallas hubs: + +.. code-block:: yaml + + # Example configuration entry + dallas: + - pin: GPIO23 + id: hub_1 + - pin: GPIO24 + id: hub_2 + + sensor: + - platform: dallas + dallas_id: hub_1 + # ... + - platform: dallas + dallas_id: hub_2 + # ... + + See Also -------- diff --git a/components/sensor/dht.rst b/components/sensor/dht.rst index 6c54c47d532..812f960b97a 100644 --- a/components/sensor/dht.rst +++ b/components/sensor/dht.rst @@ -81,6 +81,7 @@ See Also -------- - :ref:`sensor-filters` +- :doc:`absolute_humidity` - :doc:`dht12` - :doc:`hdc1080` - :doc:`htu21d` diff --git a/components/sensor/dht12.rst b/components/sensor/dht12.rst index 2ebac081c4a..0588bbcf295 100644 --- a/components/sensor/dht12.rst +++ b/components/sensor/dht12.rst @@ -55,6 +55,7 @@ See Also -------- - :ref:`sensor-filters` +- :doc:`absolute_humidity` - :doc:`dht` - :doc:`hdc1080` - :doc:`htu21d` diff --git a/components/sensor/ee895.rst b/components/sensor/ee895.rst index f5b4f1b8a5f..d56db15795c 100644 --- a/components/sensor/ee895.rst +++ b/components/sensor/ee895.rst @@ -7,7 +7,7 @@ EE895 CO₂, Temperature and Pressure Sensor The ``ee895`` sensor platform allows you to use your EE895 CO₂ (`datasheet `__, -`E+E TEE501 `__) sensor with ESPHome. +`E+E EE895 `__) sensor with ESPHome. The :ref:`I²C Bus ` is required to be set up in your configuration for this sensor to work. We recommend the use of pull up resistors. .. figure:: images/EE895.png diff --git a/components/sensor/ens210.rst b/components/sensor/ens210.rst index 462454789fb..782af1510b4 100644 --- a/components/sensor/ens210.rst +++ b/components/sensor/ens210.rst @@ -23,7 +23,7 @@ The ``ENS210`` Temperature+Humidity sensor allows you to use your ENS210 # Example configuration entry sensor: - - platform: ENS210 + - platform: ens210 temperature: name: "Living Room Temperature" humidity: @@ -52,6 +52,7 @@ See Also -------- - :ref:`sensor-filters` +- :doc:`absolute_humidity` - :apiref:`ENS210/ENS210.h` - `ENS210 Library `__ by `Maarten Pennings `__ - :ghedit:`Edit` diff --git a/components/sensor/fs3000.rst b/components/sensor/fs3000.rst new file mode 100644 index 00000000000..1a61b17d827 --- /dev/null +++ b/components/sensor/fs3000.rst @@ -0,0 +1,47 @@ +FS3000 Air Velocity Sensor +========================== + +.. seo:: + :description: Instructions for setting up the FS3000 Air Velocity sensor. + :image: fs3000.jpg + :keywords: FS3000 + +The FS3000 Air Velocity sensor allows you to use your FS3000 +(`datasheet `__, +`sparkfun `__) +sensors with ESPHome. + +.. figure:: images/fs3000.jpg + :align: center + :width: 30.0% + + FS3000 Air Velocity Sensor. + (Credit: `Sparkfun `__, image compressed) + +.. _Sparkfun: https://www.sparkfun.com/products/15805 + +The FS3000 is a solid state air velocity sensor that communicates over over I²C. It is based on a MEMS thermopile sensor. There are two subtypes available: the FS3000-1005 measures air velocities between 0 meters/second and 7.23 meters/second, and the FS3000-1015 measures air velocities between 0 meters/second and 15 meters/second. + +To use the sensor, first set up an :ref:`I²C Bus ` and connect the sensor to the specified pins. + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: fs3000 + name: "Air Velocity" + model: 1005 + update_interval: 60s + +Configuration variables: +------------------------ + +- **model** (**Required**, string): Specify FS3000 model, can be ``1005`` or ``1015``. +- **address** (*Optional*, int): Manually specifiy the I²C address of the sensor. Defaults to ``0x28``. +- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. +- All other options from :ref:`Sensor `. + +See Also +-------- + +- :ghedit:`Edit` diff --git a/components/sensor/hdc1080.rst b/components/sensor/hdc1080.rst index 63a1bab14ca..19bc5a7fdfc 100644 --- a/components/sensor/hdc1080.rst +++ b/components/sensor/hdc1080.rst @@ -80,6 +80,7 @@ See Also -------- - :ref:`sensor-filters` +- :doc:`absolute_humidity` - :doc:`dht` - :doc:`dht12` - :doc:`htu21d` diff --git a/components/sensor/homeassistant.rst b/components/sensor/homeassistant.rst index c30f7e95ffa..fd2096fa141 100644 --- a/components/sensor/homeassistant.rst +++ b/components/sensor/homeassistant.rst @@ -32,7 +32,7 @@ Entity state attributes can also be imported: This component is only for numeral states. If you want to import arbitrary text states from Home Assistant, use the :doc:`Home Assistant Text Sensor `. - Albeit you might not plan to *export* states from the node and you do not need an entity of the node + Although you might not plan to *export* states from the node and you do not need an entity of the node in Home Assistant, this component still requires you to register the node under Home Assistant. See: :doc:`Getting started with Home Assistant ` @@ -50,7 +50,7 @@ Configuration variables: .. note:: - The sensors implemented by this component are by default ``internal``, to avoid exporting back them to + The sensors implemented by this component are by default ``internal``, to avoid exporting them back to Home Assistant. Should you still want to do that (eg. because you use ESPHome's very efficient filters on them) you need to specifically configure ``internal: false``. Also, ``state_class``, ``unit_of_measurement`` are not inherited from the imported sensor so you need to set them manually. diff --git a/components/sensor/hte501.rst b/components/sensor/hte501.rst index 6f9badbaa9b..4e052de0ead 100644 --- a/components/sensor/hte501.rst +++ b/components/sensor/hte501.rst @@ -52,6 +52,7 @@ See Also -------- - :ref:`sensor-filters` +- :doc:`absolute_humidity` - :doc:`tee501` - :doc:`ee895` - :doc:`dht` diff --git a/components/sensor/htu21d.rst b/components/sensor/htu21d.rst index a429d01de8d..238f845efe3 100644 --- a/components/sensor/htu21d.rst +++ b/components/sensor/htu21d.rst @@ -58,6 +58,7 @@ See Also -------- - :ref:`sensor-filters` +- :doc:`absolute_humidity` - :doc:`dht` - :doc:`dht12` - :doc:`hdc1080` diff --git a/components/sensor/images/as7341-full.jpg b/components/sensor/images/as7341-full.jpg new file mode 100644 index 00000000000..22aa8359098 Binary files /dev/null and b/components/sensor/images/as7341-full.jpg differ diff --git a/components/sensor/images/fs3000.jpg b/components/sensor/images/fs3000.jpg new file mode 100644 index 00000000000..071040ae3ea Binary files /dev/null and b/components/sensor/images/fs3000.jpg differ diff --git a/components/sensor/images/mlx90614.jpg b/components/sensor/images/mlx90614.jpg new file mode 100644 index 00000000000..86131b4a93a Binary files /dev/null and b/components/sensor/images/mlx90614.jpg differ diff --git a/components/sensor/images/mopeka_std_check.jpg b/components/sensor/images/mopeka_std_check.jpg new file mode 100644 index 00000000000..6619507f252 Binary files /dev/null and b/components/sensor/images/mopeka_std_check.jpg differ diff --git a/components/sensor/images/sen21231.png b/components/sensor/images/sen21231.png new file mode 100644 index 00000000000..c78af266b86 Binary files /dev/null and b/components/sensor/images/sen21231.png differ diff --git a/components/sensor/index.rst b/components/sensor/index.rst index edbcf8e104f..3b15ff77e93 100644 --- a/components/sensor/index.rst +++ b/components/sensor/index.rst @@ -40,6 +40,12 @@ Configuration variables: - **id** (*Optional*, string): Manually specify the ID for code generation. At least one of **id** and **name** must be specified. - **name** (*Optional*, string): The name for the sensor. At least one of **id** and **name** must be specified. + + .. note:: + + If you have a :ref:`friendly_name ` set for your device and + you want the sensor to use that name, you can set ``name: None``. + - **unit_of_measurement** (*Optional*, string): Manually set the unit of measurement the sensor should advertise its values with. This does not actually do any maths (conversion between units). @@ -349,7 +355,7 @@ Configuration variables: when pushing out a value. Defaults to ``5``. - **send_every** (*Optional*, int): How often a sensor value should be pushed out. For - example, in above configuration the min is calculated after every 4th + example, in above configuration the max is calculated after every 4th received sensor value, over the last 7 received values. Defaults to ``5``. - **send_first_at** (*Optional*, int): By default, the very first raw value on boot is immediately @@ -406,6 +412,21 @@ Configuration variables: published. With this parameter you can specify when the very first value is to be sent. Defaults to ``1``. +``skip_initial`` +**************** + +A simple skip filter; `skip_initial: N` skips the first `N` sensor readings and passes on the +rest. This can be used when the sensor needs a few readings to 'warm up'. After the initial +readings have been skipped, this filter does nothing. + +.. code-block:: yaml + + # Example configuration entry + - platform: wifi_signal + # ... + filters: + - skip_initial: 3 + ``throttle`` ************ @@ -456,11 +477,28 @@ values. ``delta`` ********* -This filter stores the last value passed through this filter and only -passes incoming values through if the absolute difference is greater than the configured -value. For example if a value of 1.0 first comes in, it's passed on. If the delta filter -is configured with a value of 5, it will now not pass on an incoming value of 2.0, only values -that are at least 6.0 big or -4.0. +This filter stores the last value passed through this filter and only passes incoming values through +if incoming value is sufficiently different from the previously passed one. +This difference can be calculated in two ways an absolute difference or a percentage difference. + +If a number is specified, it will be used as the absolute difference required. +For example if the filter were configured with a value of 2 and the last value passed through was 10, +only values greater than 12 or less than 8 would be passed through. + +.. code-block:: yaml + + filters: + - delta: 2.0 + +If a percentage is specified a percentage of the last value will be used as the required difference. +For example if the filter were configured with a value of 20% and the last value passed through was 10, +only values greater than 12 or less than 8 would be passed through. +However, if the last value passed through was 100 only values greater than 120 or less than 80 would be passed through. + +.. code-block:: yaml + + filters: + - delta: 20% ``or`` ****** @@ -493,6 +531,16 @@ the result of the lambda is used as the output (use ``return``). Make sure to add ``.0`` to all values in the lambda, otherwise divisions of integers will result in integers (not floating point values). +To prevent values from being published, return ``{}``: + +.. code-block:: yaml + + filters: + - lambda: !lambda |- + if (x < 10) return {}; + return x-10; + + Example: Converting Celsius to Fahrenheit ----------------------------------------- @@ -633,7 +681,7 @@ From :ref:`lambdas `, you can call several methods on all sensors advanced stuff (see the full API Reference for more info). - ``publish_state()``: Manually cause the sensor to push out a value. It will then - be processed by the sensor filters, and once filtered will propagate though ESPHome and though the API to Home Assistant or out via MQTT if configured. + be processed by the sensor filters, and once filtered will propagate though ESPHome and though the API to Home Assistant or out via MQTT if configured. .. code-block:: cpp diff --git a/components/sensor/inkbird_ibsth1_mini.rst b/components/sensor/inkbird_ibsth1_mini.rst index a7512f3d815..4b641aab51b 100644 --- a/components/sensor/inkbird_ibsth1_mini.rst +++ b/components/sensor/inkbird_ibsth1_mini.rst @@ -115,6 +115,7 @@ See Also - :doc:`/components/esp32_ble_tracker` - :doc:`/components/sensor/index` +- :doc:`absolute_humidity` - :apiref:`inkbird_ibsth1_mini/inkbird_ibsth1_mini.h` - `OpenMQTTGateway `__ by `@1technophile `__ - :ghedit:`Edit` diff --git a/components/sensor/kuntze.rst b/components/sensor/kuntze.rst new file mode 100644 index 00000000000..b4727c693df --- /dev/null +++ b/components/sensor/kuntze.rst @@ -0,0 +1,88 @@ +Kuntze pool monitor +=================== + +.. seo:: + :description: Instructions for setting up Kuntze pool monitor in ESPHome. + :image: kuntze.jpg + +The ``kuntze`` component allows you to integrate the Kuntze water measurement +instrument in ESPHome. It uses :ref:`UART ` (ModBUS) for communication. + +Once configured you can use sensors as described below for your projects. + + +.. figure:: ../../images/kuntze.jpg + :align: center + + Kuntze Neon® Multi instrument + +Overview +-------- + +Kuntze devices have an RS485 (ModBUS RTU) communication port. Please see the +Kuntze papers for the pinout of the RS485 connector on your unit. ModBUS line +has to be terminated properly (with a ``120Ω`` resistor), and since this is likely +your only unit connected to ESPHome, you should activate bus termination in the +Network menu (this component doesn't support multiple Kuntze devices on the same +bus). ModBUS address should remain at factory default value. + +The device communicates at ``19200`` baud ``8E1``. To connect to ESPHome, an RS485 +transceiver is needed. Choose a type which does not need a trigger to send and +receive data, for example: + +.. figure:: ../../images/rs485.jpg + +The controller connects to the UART of the MCU. For ESP32 GPIO `16` to `TXD` and `17` +to RXD are the default ones but any other pins can be used as well. 3.3V to VCC and GND to GND. + +.. warning:: + + If you are using the :ref:`logger` make sure you are not using the same pins for it or otherwise disable the UART + logging with the ``baud_rate: 0`` option. + +Component +--------- + +A configured modbus component is optional. It will be automatically created. + +.. code-block:: yaml + + # Example configuration entry + uart: + - id: uart_bus + tx_pin: GPIO16 + rx_pin: GPIO17 + baud_rate: 19200 + parity: EVEN + + sensor: + - platform: kuntze + id: my_kuntze + ph: + id: ph + temperature: + id: temperature + + +Configuration variables: + +- **ph**: Measured pH value +- **temperature**: Measured temperature value +- **dis1**: Measured DIS 1 value +- **dis2**: Measured DIS 2 value +- **redox**: Measured Redox value +- **ec**: Measured EC value +- **oci**: Measured OCI value + + +All sensors are *Optional* and support all other options from :ref:`Sensor `. + +See Also +-------- + +- :ref:`uart` +- :ref:`logger` +- :ref:`Sensor ` +- `Kuntze manuals `__ +- `Communication protocol `__ +- :ghedit:`Edit` diff --git a/components/sensor/ltr390.rst b/components/sensor/ltr390.rst index 867ccff306a..3a0a751ed31 100644 --- a/components/sensor/ltr390.rst +++ b/components/sensor/ltr390.rst @@ -111,7 +111,7 @@ See Also - :doc:`/components/sensor/bh1750` - :doc:`/components/sensor/tsl2561` -- :doc:`/cookbook/temt6000` +- `TEMT6000 `__ - :ref:`sensor-filters` - :apiref:`ltr390/ltr390.h` - :ghedit:`Edit` diff --git a/components/sensor/mhz19.rst b/components/sensor/mhz19.rst index 2d4a3e7e8a8..58ab84a26c6 100644 --- a/components/sensor/mhz19.rst +++ b/components/sensor/mhz19.rst @@ -8,7 +8,7 @@ MH-Z19 CO_2 and Temperature Sensor The ``mhz19`` sensor platform allows you to use MH-Z19 CO_2 and temperature sensors (`refspace`_) with ESPHome. -The CO_2 measurement also works with the MH-Z16 sensor. +The CO_2 measurement also works with the MH-Z16 and MH-Z14 sensors. .. figure:: images/mhz19-full.jpg :align: center diff --git a/components/sensor/mics_4514.rst b/components/sensor/mics_4514.rst index b337c59ef92..731e89b1c26 100644 --- a/components/sensor/mics_4514.rst +++ b/components/sensor/mics_4514.rst @@ -10,9 +10,12 @@ This component exposes the different gas concentration sensors from the `MiCS-45 .. note:: + The sensor has a 3-minute warmup period where data is unreliable and ESPHome will only start publishing sensor values after this time. If the sensor was already powered only, such as if you restarted or updated your ESPHome device, then it will start publishing immediately. + The :ref:`I²C Bus ` is required to be set up in your configuration for this sensor to work. + .. code-block:: yaml # Example configuration entry @@ -35,7 +38,6 @@ This component exposes the different gas concentration sensors from the `MiCS-45 Configuration variables: ------------------------ -- **pin** (**Required**, :ref:`config-pin`): The pin where the DHT bus is connected. - **nitrogen_dioxide** (*Optional*): All options from :ref:`Sensor ` - **carbon_monoxide** (*Optional*): All options from :ref:`Sensor ` - **hydrogen** (*Optional*): All options from :ref:`Sensor ` diff --git a/components/sensor/mlx90614.rst b/components/sensor/mlx90614.rst new file mode 100644 index 00000000000..51af337a946 --- /dev/null +++ b/components/sensor/mlx90614.rst @@ -0,0 +1,57 @@ +MLX90614 non-contact thermometer +================================= + +.. seo:: + :description: Instructions for setting up Melexis MLX90614 non-contact thermometer. + :image: mlx90614.jpg + :keywords: MLX90614 + +The ``mlx90614`` sensor platform allows you to use your Melexis MLX90614 non-contact infrared thermometer +(`Datasheet `__, +`Product Page`_) with ESPHome. Sensor measures both ambient and object temperature that can be enabled independently. + +The :ref:`I²C Bus ` is required to be set up in your configuration for this sensor to work. + +.. figure:: images/mlx90614.jpg + :align: center + :width: 50.0% + + MLX90614 non-contact thermometer + +.. _Product Page: https://www.melexis.com/en/product/MLX90614/Digital-Plug-Play-Infrared-Thermometer-TO-Can + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: mlx90614 + ambient: + name: Ambient + object: + name: Object + + + +Configuration variables +----------------------- +- **ambient** (*Optional*): Enables sensor entity for ambient temperature reading. + + - All options from :ref:`Sensor `. + +- **object** (*Optional*): Enables sensor entity for object temperature reading. + + - **emissivity** (*Optional*): Emissivity coefficient is the measure of an object's ability to emit infrared energy + compared to a theoretical perfect black body emitter. See `Emissivity Application note `__ + for details on determining custom emissivity. Default is 1.0 which is 100% and corresponds to the ideal black body. + + - All options from :ref:`Sensor `. + +- All other options for I²C devices described at :ref:`I²C Bus `. + + +See Also +-------- + +- :ref:`sensor-filters` +- :apiref:`mlx90614/mlx90614.h` +- :ghedit:`Edit` diff --git a/components/sensor/mmc5063.rst b/components/sensor/mmc5063.rst new file mode 100644 index 00000000000..5b18557bad3 --- /dev/null +++ b/components/sensor/mmc5063.rst @@ -0,0 +1,63 @@ +.. _mmc5603: + +MMC5603 Magnetometer +===================== + +.. seo:: + :description: Instructions for setting up MMC5693 IMU compass sensors. + :image: mmc5603.jpg + :keywords: MMC5603 + +The ``mmc5603`` allows you to use your MMC5603 triple-axis magnetometers +(`datasheet `__, +`Adafruit`_) with ESPHome. The :ref:`I²C Bus ` is required to be set up in your configuration +for this sensor to work. + +.. figure:: ../../images/mmc5603.jpg + :align: center + :width: 30.0% + + MMC5603 Magnetometer. + +.. _Adafruit: https://www.adafruit.com/product/5579 + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: MMC5603 + address: 0x30 + field_strength_x: + name: "MMC5603 Field Strength X" + field_strength_y: + name: "MMC5603 Field Strength Y" + field_strength_z: + name: "MMC5603 Field Strength Z" + heading: + name: "MMC5603 Heading" + update_interval: 60s + +Configuration variables: +------------------------ + +- **address** (*Optional*, int): Manually specify the I²C address of the sensor. Defaults to ``0x1E``. +- **field_strength_x** (*Optional*): The field strength in microtesla along the X-Axis. All options from + :ref:`Sensor `. +- **field_strength_y** (*Optional*): The field strength in microtesla along the Y-Axis. All options from + :ref:`Sensor `. +- **field_strength_z** (*Optional*): The field strength in microtesla along the Z-Axis. All options from + :ref:`Sensor `. +- **heading** (*Optional*): The heading of the sensor in degrees. All options from + :ref:`Sensor `. +- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. + +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. + + +See Also +-------- + +- :ref:`sensor-filters` +- :doc:`template` +- :apiref:`mmc5603/mmc5603.h` +- :ghedit:`Edit` diff --git a/components/sensor/modbus_controller.rst b/components/sensor/modbus_controller.rst index e5bd03f9fc5..cd20e676438 100644 --- a/components/sensor/modbus_controller.rst +++ b/components/sensor/modbus_controller.rst @@ -271,5 +271,5 @@ See Also - :doc:`/components/binary_sensor/modbus_controller` - :doc:`/components/text_sensor/modbus_controller` - :doc:`/components/switch/modbus_controller` -- :doc:`EPEVER MPPT Solar Charge Controller Tracer-AN Series` +- `EPEVER MPPT Solar Charge Controller (Tracer-AN Series) `__ - :ghedit:`Edit` diff --git a/components/sensor/mopeka_pro_check.rst b/components/sensor/mopeka_pro_check.rst index 49f63091d39..0bf4f3601e4 100644 --- a/components/sensor/mopeka_pro_check.rst +++ b/components/sensor/mopeka_pro_check.rst @@ -19,6 +19,9 @@ sensor sends out a BLE broadcast. + Mopeka Pro Check devices + Mopeka Pro Plus devices + Lippert Propane Tank Sensor, part number 2021130655 + + See :doc:`/components/sensor/mopeka_std_check` for original Mopeka Check sensors support. + (images/mopeka_pro_check.jpg) (images/mopeka_pro_check_lippert.jpg) @@ -119,11 +122,12 @@ and the ``mopeka_ble`` component like so: After uploading, the ESP32 will immediately try to scan for BLE devices. For Mopeka Pro Check / Pro Plus / Lippert devices you must press and hold the green sync button for it to be identified. +Or alternativly set the configuration flag ``show_sensors_without_sync: true`` to see all devices. For all sensors found the ``mopeka_ble`` component will print a message like this one: .. code:: - [20:43:26][I][mopeka_ble:040]: SENSOR FOUND: D3:75:F2:DC:16:91 + [20:43:26][I][mopeka_ble:074]: MOPEKA PRO (NRF52) SENSOR FOUND: D3:75:F2:DC:16:91 Then just copy the address (``D3:75:F2:DC:16:91``) into a new ``sensor.mopeka_pro_check`` platform entry like in the configuration example at the top. diff --git a/components/sensor/mopeka_std_check.rst b/components/sensor/mopeka_std_check.rst new file mode 100644 index 00000000000..43911030e11 --- /dev/null +++ b/components/sensor/mopeka_std_check.rst @@ -0,0 +1,150 @@ +Mopeka Standard Check BLE Sensor +================================ + +.. seo:: + :description: Instructions for setting up Mopeka Standard Check bluetooth-based sensors in ESPHome. + :image: mopeka_std_check.jpg + :keywords: Mopeka, Mopeka Standard Check, Mopeka Std Check, BLE, Bluetooth + +The ``mopeka_std_check`` sensor platform lets you track the output of Mopeka +Standard Check LP Bluetooth Low Energy devices using the +:doc:`/components/esp32_ble_tracker`. This component will track the tank level, +distance, temperature, and battery percentage of a Mopeka Standard Check LP BLE +device every time the sensor sends out a BLE broadcast. + +.. warning:: + + This sensor component only supports the Mopeka Standard Check devices. + See :doc:`/components/sensor/mopeka_pro_check` for Mopeka Pro Check sensors support. + +.. figure:: images/mopeka_std_check.jpg + :align: center + + Mopeka Std Check LP over BLE. + +.. code-block:: yaml + + esp32_ble_tracker: + + sensor: + # Example using 11kg 100% propane tank. + - platform: mopeka_std_check + mac_address: D3:75:F2:DC:16:91 + tank_type: Europe_11kg + temperature: + name: "Propane test temp" + level: + name: "Propane test level" + distance: + name: "Propane test distance" + battery_level: + name: "Propane test battery level" + + # Custom example - user defined empty / full points and 80% butane and 20% propane. + - platform: mopeka_std_check + mac_address: D3:75:F2:DC:16:91 + tank_type: CUSTOM + custom_distance_full: 40cm + custom_distance_empty: 32mm + propane_butane_mix: 20% + temperature: + name: "Propane c test temp" + level: + name: "Propane c test level" + distance: + name: "Propane c test distance" + battery_level: + name: "Propane c test battery level" + + +Configuration variables: +------------------------ + +- **mac_address** (**Required**, MAC Address): The MAC address of the Mopeka + device. + +- **tank_type** (**Required**): The tank type the sensor is measuring. See below. + +- **custom_distance_full** (*Optional*): distance sensor will read when it should be + considered full (100%). This is only used when tank_type = CUSTOM + +- **custom_distance_empty** (*Optional*): distance sensor will read when it should be + considered empty (0%). This is only used when tank_type = CUSTOM + +- **propane_butane_mix** (*Optional*): Mixture of propane and butane. + + - 100% - (*default*) 100% Propane + + - 80% - 80% Propane and 20% Butane + + - 20% - 20% Propane and 80% Butane + + - 0% - 100% Butane + +- **level** (*Optional*): The percentage of full for the tank sensor + + - All options from :ref:`Sensor `. + +- **distance** (*Optional*): The raw distance/depth of the liquid for the sensor in mm. + + - All options from :ref:`Sensor `. + +- **temperature** (*Optional*): The information for the temperature sensor. + This temperature is on the sensor and is not calibrated to ambient temperature. + + - All options from :ref:`Sensor `. + +- **battery_level** (*Optional*): The information for the battery percentage + sensor. Sensor uses a standard CR2032 battery. + + - All options from :ref:`Sensor `. + +Tank Types +---------- + +Currently supported Tank types are: + +- ``NORTH_AMERICA_20LB_VERTICAL`` - 20 LB vertical tank +- ``NORTH_AMERICA_30LB_VERTICAL`` - 30 LB vertical tank +- ``NORTH_AMERICA_40LB_VERTICAL`` - 40 LB vertical tank +- ``EUROPE_6KG`` - 6kg vertical tank +- ``EUROPE_11KG`` - 11kg vertical tank +- ``EUROPE_14KG`` - 14kg vertical tank +- ``CUSTOM`` - Allows you to define your own full and empty points + +Setting Up Devices +------------------ + +To set up Mopeka Standard Check devices you first need to find their MAC Address so that +ESPHome can identify them. So first, create a simple configuration with the ``esp32_ble_tracker`` +and the ``mopeka_ble`` component like so: + +.. code-block:: yaml + + esp32_ble_tracker: + + mopeka_ble: + +After uploading, the ESP32 will immediately try to scan for BLE devices. For Mopeka Standard devices you must press and hold the green sync button for it to be identified. +Or alternativly set the configuration flag ``show_sensors_without_sync: true`` to see all devices. +For all sensors found the ``mopeka_ble`` component will print a message like this one: + +.. code:: + + [20:43:26][I][mopeka_ble:056]: MOPEKA STD (CC2540) SENSOR FOUND: D3:75:F2:DC:16:91 + +Then just copy the address (``D3:75:F2:DC:16:91``) into a new +``sensor.mopeka_std_check`` platform entry like in the configuration example at the top. + +.. note:: + + The ESPHome Mopeka Standard Check BLE integration listens passively to packets the Mopeka device sends by itself. + ESPHome therefore has no impact on the battery life of the device. + +See Also +-------- + +- :doc:`/components/esp32_ble_tracker` +- :doc:`/components/sensor/index` +- :apiref:`mopeka_std_check/mopeka_std_check.h` +- :ghedit:`Edit` diff --git a/components/sensor/pmsx003.rst b/components/sensor/pmsx003.rst index df879a418c5..0ecee8b542e 100644 --- a/components/sensor/pmsx003.rst +++ b/components/sensor/pmsx003.rst @@ -5,7 +5,7 @@ PMSX003 Particulate Matter Sensor :description: Instructions for setting up PMSX003 Particulate matter sensors :image: pmsx003.svg -The ``pmsx003`` sensor platform allows you to use your PMS5003, PMS7003, ... particulate matter +The ``pmsx003`` sensor platform allows you to use your Plantower PMS5003, PMS7003, ... laser based particulate matter sensors (`datasheet `__) sensors with ESPHome. @@ -18,9 +18,16 @@ value: - ``PMSX003`` for generic PMS5003, PMS7003, ...; these sensors support ``pm_1_0``, ``pm_2_5`` and ``pm_10_0`` output. - ``PMS5003S`` for PMS5003S. These support ``pm_1_0``, ``pm_2_5`` and ``pm_10_0`` and ``formaldehyde``. -- ``PMS5003T`` for PMS5003T. These support ``pm_2_5``, ``temperature`` and ``humidity``. +- ``PMS5003T`` for PMS5003T. These support ``pm_1_0``, ``pm_2_5`` and ``pm_10_0``, ``temperature`` and ``humidity``. - ``PMS5003ST`` for PMS5003ST. These support ``pm_2_5``, ``temperature``, ``humidity`` and ``formaldehyde``. +Sensor Longevity +------------------------ +The laser diode inside the PMSX003 has a lifetime of about 8000 hours, nearly one year. + +If you wish to use the optional ``update_interval`` ensure you have a ``tx_pin`` set in the UART configuration and connected to the RECEIVE/RX pin +(may also be called the TX pin, depending on the model) of the PMS. Setting ``update_interval`` to 120 seconds or higher may help extend the life span of the sensor. + .. code-block:: yaml # Example configuration entry @@ -38,34 +45,34 @@ value: name: "Particulate Matter <2.5µm Concentration" pm_10_0: name: "Particulate Matter <10.0µm Concentration" - update_interval: 60000ms + update_interval: 120s Configuration variables: ------------------------ -- **pm_1_0_std** (*Optional*): Use the concentration of particulates of size less than 1.0µm in µg per cubic meter at standard particle +- **pm_1_0_std** (*Optional*): Use the concentration of particulates of size less than 1.0µm in µg per cubic meter at standard particle. All options from :ref:`Sensor `. -- **pm_2_5_std** (*Optional*): Use the concentration of particulates of size less than 2.5µm in µg per cubic meter at standard particle +- **pm_2_5_std** (*Optional*): Use the concentration of particulates of size less than 2.5µm in µg per cubic meter at standard particle. All options from :ref:`Sensor `. -- **pm_10_0_std** (*Optional*): Use the concentration of particulates of size less than 10.0µm in µg per cubic meter at standard particle +- **pm_10_0_std** (*Optional*): Use the concentration of particulates of size less than 10.0µm in µg per cubic meter at standard particle. All options from :ref:`Sensor `. -- **pm_1_0** (*Optional*): Use the concentration of particulates of size less than 1.0µm in µg per cubic meter under atmospheric environment +- **pm_1_0** (*Optional*): Use the concentration of particulates of size less than 1.0µm in µg per cubic meter under atmospheric environment. All options from :ref:`Sensor `. -- **pm_2_5** (*Optional*): Use the concentration of particulates of size less than 2.5µm in µg per cubic meter under atmospheric environment +- **pm_2_5** (*Optional*): Use the concentration of particulates of size less than 2.5µm in µg per cubic meter under atmospheric environment. All options from :ref:`Sensor `. -- **pm_10_0** (*Optional*): Use the concentration of particulates of size less than 10.0µm in µg per cubic meter under atmospheric environment +- **pm_10_0** (*Optional*): Use the concentration of particulates of size less than 10.0µm in µg per cubic meter under atmospheric environment. All options from :ref:`Sensor `. -- **pm_0_3um** (*Optional*): Use the number of particles with diameter beyond 0.3um in 0.1L of air +- **pm_0_3um** (*Optional*): Use the number of particles with diameter beyond 0.3um in 0.1L of air. All options from :ref:`Sensor `. -- **pm_0_5um** (*Optional*): Use the number of particles with diameter beyond 0.5um in 0.1L of air +- **pm_0_5um** (*Optional*): Use the number of particles with diameter beyond 0.5um in 0.1L of air. All options from :ref:`Sensor `. -- **pm_1_0um** (*Optional*): Use the number of particles with diameter beyond 1.0um in 0.1L of air +- **pm_1_0um** (*Optional*): Use the number of particles with diameter beyond 1.0um in 0.1L of air. All options from :ref:`Sensor `. -- **pm_2_5um** (*Optional*): Use the number of particles with diameter beyond 2.5um in 0.1L of air +- **pm_2_5um** (*Optional*): Use the number of particles with diameter beyond 2.5um in 0.1L of air. All options from :ref:`Sensor `. -- **pm_5_0um** (*Optional*): Use the number of particles with diameter beyond 5.0um in 0.1L of air +- **pm_5_0um** (*Optional*): Use the number of particles with diameter beyond 5.0um in 0.1L of air. Not supported by the ``PMS5003T`` type sensors. All options from :ref:`Sensor `. -- **pm_10_0um** (*Optional*): Use the number of particles with diameter beyond 10.0um in 0.1L of air +- **pm_10_0um** (*Optional*): Use the number of particles with diameter beyond 10.0um in 0.1L of air. Not supported by the ``PMS5003T`` type sensors. All options from :ref:`Sensor `. - **temperature** (*Optional*): Use the temperature value in °C for the ``PMS5003T`` and ``PMS5003ST`` type sensors. All options from :ref:`Sensor `. diff --git a/components/sensor/pzemdc.rst b/components/sensor/pzemdc.rst index 5d769649e1f..6a7d2909198 100644 --- a/components/sensor/pzemdc.rst +++ b/components/sensor/pzemdc.rst @@ -42,6 +42,8 @@ to some pins on your board and the baud rate set to 9600. name: "PZEM-003 Voltage" power: name: "PZEM-003 Power" + energy: + name: "PZEM-003 Energy" update_interval: 60s Configuration variables: @@ -53,11 +55,27 @@ Configuration variables: :ref:`Sensor `. - **voltage** (*Optional*): Use the voltage value of the sensor in volts. All options from :ref:`Sensor `. +- **energy** (*Optional*): Use the energy value of the sensor in kWh. + All options from :ref:`Sensor `. - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. - **address** (*Optional*, int): The address of the sensor if multiple sensors are attached to the same UART bus. You will need to set the address of each device manually. Defaults to ``1``. +.. _pzemdc-reset_energy_action: + +``pzemdc.reset_energy`` Action +****************************** + +This action resets the total energy value of the pzemdc device with the given ID when executed. + +.. code-block:: yaml + + on_...: + then: + - pzemdc.reset_energy: pzemdc_1 + + See Also -------- diff --git a/components/sensor/resistance.rst b/components/sensor/resistance.rst index 21d42c2c4fc..cc6ce039eff 100644 --- a/components/sensor/resistance.rst +++ b/components/sensor/resistance.rst @@ -44,6 +44,19 @@ is close to GND (DOWNSTREAM) or it is closer to VCC (UPSTREAM). id: source_sensor pin: A0 +Note: +------------------------ +Some boards like NodeMCUv2 needs to multiply ADC reading by 3.3 to provide accurate result because they have built-in voltage divider on ADC pin (https://arduino.stackexchange.com/a/71952) + +.. code-block:: yaml + + # Example source sensor: + - platform: adc + id: source_sensor + pin: A0 + filters: + - multiply: 3.3 + Configuration variables: ------------------------ diff --git a/components/sensor/ruuvitag.rst b/components/sensor/ruuvitag.rst index 8c2a7be2ebf..92a3ae9d772 100644 --- a/components/sensor/ruuvitag.rst +++ b/components/sensor/ruuvitag.rst @@ -184,6 +184,7 @@ See Also - :doc:`/components/esp32_ble_tracker` - :doc:`/components/sensor/index` +- :doc:`absolute_humidity` - :apiref:`ruuvitag/ruuvitag.h` - `Ruuvi `__ - :ghedit:`Edit` diff --git a/components/sensor/scd30.rst b/components/sensor/scd30.rst index 73fd2a45271..c33f622ad09 100644 --- a/components/sensor/scd30.rst +++ b/components/sensor/scd30.rst @@ -108,6 +108,7 @@ See Also -------- - :ref:`sensor-filters` +- :doc:`absolute_humidity` - :doc:`dht` - :doc:`dht12` - :doc:`hdc1080` diff --git a/components/sensor/scd4x.rst b/components/sensor/scd4x.rst index 04796d3d323..ff52756a72f 100644 --- a/components/sensor/scd4x.rst +++ b/components/sensor/scd4x.rst @@ -105,15 +105,19 @@ As of April 2022 the average fresh air Co² concentration is 419 ppm. value: 419 # outside average April 2022 id: my_scd41 -value can be a template +value can also be a template, for example to define a Home Assistant calibration service: .. code-block:: yaml - on_...: - then: - - scd4x._perform_forced_calibration_action: - value: !lambda "{ return 419 };" - id: my_scd41 + api: + services: + - service: calibrate_co2_value + variables: + co2_ppm: int + then: + - scd4x.perform_forced_calibration: + value: !lambda 'return co2_ppm;' + id: my_scd41 .. _factory_reset_action: @@ -129,45 +133,60 @@ This :ref:`action ` triggers a factory reset of the sensor. Calib then: - scd4x.factory_reset: my_scd41 -Automation ------------------ +Pressure compensation +--------------------- -Ambient pressure compensation compensation can be changed from :ref:`lambdas ` +A static ambient pressure value can be set with `ambient_pressure_compensation` or `altitude_compensation`. It can also be changed dynamically with :ref:`lambdas ` using `set_ambient_pressure_compensation()`, or by pointing `ambient_pressure_compensation_source` to a local pressure sensor. +Example with a local sensor +*************************** -``set_ambient_pressure_compensation( set_ambient_pressure_compensation(pressure_mbar);" + sensor: - platform: scd4x - id: scd41 - i2c_id: bus_a + id: my_scd41 + measurement_mode: low_power_periodic + temperature_offset: 0 co2: - name: co2 - id: co2 - - - platform: bme280 - pressure: - name: "BME280-Pressure" - id: bme280_pressure - oversampling: 1x - on_value: - then: - - lambda: "id(scd41)->set_ambient_pressure_compensation(x / 1000.0);" + name: "CO2 level" See Also -------- - :ref:`sensor-filters` +- :doc:`absolute_humidity` - :doc:`scd30` - :apiref:`scd4x/scd4x.h` - :ghedit:`Edit` diff --git a/components/sensor/sen21231.rst b/components/sensor/sen21231.rst new file mode 100644 index 00000000000..bad23504184 --- /dev/null +++ b/components/sensor/sen21231.rst @@ -0,0 +1,36 @@ +SEN21231 Person Sensor from Useful Sensors +========================================== + +.. seo:: + :description: Instructions for setting up a SEN21231 Person Sensor from Useful Sensors with ESPHome. + :image: description.svg + +`Person Sensor (SEN21231) from Useful Sensors `__ has built in facial recognition that can detect how many people are facing the sensor and relative positions of the faces. + +.. figure:: images/sen21231.png + :align: center + :width: 70.0% + + + Person Sensor + +This sensor requires an :doc:`/components/i2c`. The I2C address is ``0x62`` + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: sen21231 + id: person_sensor + +Configuration variables: +------------------------ + +- All options from :ref:`Sensor `. + +See Also +-------- + +- :doc:`/components/sensor/index` +- :apiref:`sen21231/sen21231.h` +- :ghedit:`Edit` diff --git a/components/sensor/sen5x.rst b/components/sensor/sen5x.rst index e0b5043d60b..f8424ce8541 100644 --- a/components/sensor/sen5x.rst +++ b/components/sensor/sen5x.rst @@ -114,7 +114,7 @@ Configuration variables: - All other options from :ref:`Sensor `. -- **nox** (*Optional*): NOx Index. Note: Only available with Sen54 or Sen55. The sensor will be ignored on unsupported models. +- **nox** (*Optional*): NOx Index. Note: Only available with Sen55. The sensor will be ignored on unsupported models. - **name** (**Required**, string): The name of the sensor. - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. @@ -162,7 +162,7 @@ Configuration variables: Wiring: ------- -The sensor has a JST GHR-06V-S 6 pin type connector, with a 1.5mm pitch. The cable needs this connector: +The sensor has a JST GHR-06V-S 6 pin type connector, with a 1.25mm pitch. The cable needs this connector: .. figure:: images/jst6pin.png :align: center @@ -208,6 +208,7 @@ See Also -------- - :ref:`sensor-filters` +- :doc:`absolute_humidity` - :doc:`sds011` - :doc:`pmsx003` - :doc:`ccs811` diff --git a/components/sensor/sht3xd.rst b/components/sensor/sht3xd.rst index 0d340d3e032..5cee64e954e 100644 --- a/components/sensor/sht3xd.rst +++ b/components/sensor/sht3xd.rst @@ -2,10 +2,10 @@ SHT3X-D Temperature+Humidity Sensor =================================== .. seo:: - :description: Instructions for setting up SHT31-D temperature and humidity sensors + :description: Instructions for setting up SHT31-D/SHT3x temperature and humidity sensors :image: sht3xd.jpg -The ``sht3xd`` sensor platform Temperature+Humidity sensor allows you to use your Sensirion SHT31-D +The ``sht3xd`` sensor platform Temperature+Humidity sensor allows you to use your Sensirion SHT31-D/SHT3x (`datasheet `__, `Adafruit`_ ) sensors with ESPHome. The :ref:`I²C Bus ` is @@ -53,6 +53,7 @@ See Also -------- - :ref:`sensor-filters` +- :doc:`absolute_humidity` - :doc:`dht` - :doc:`dht12` - :doc:`hdc1080` diff --git a/components/sensor/sht4x.rst b/components/sensor/sht4x.rst index 60205edd2ad..c671f8a0140 100644 --- a/components/sensor/sht4x.rst +++ b/components/sensor/sht4x.rst @@ -67,5 +67,6 @@ See Also - :doc:`/components/sensor/sht3xd` - :doc:`/components/sensor/shtcx` - :ref:`sensor-filters` +- :doc:`absolute_humidity` - :apiref:`sht4x/sht4x.h` - :ghedit:`Edit` diff --git a/components/sensor/shtcx.rst b/components/sensor/shtcx.rst index 8cf0d267b07..e69b2595e25 100644 --- a/components/sensor/shtcx.rst +++ b/components/sensor/shtcx.rst @@ -56,6 +56,7 @@ See Also -------- - :ref:`sensor-filters` +- :doc:`absolute_humidity` - :doc:`dht` - :doc:`dht12` - :doc:`hdc1080` diff --git a/components/sensor/zyaura.rst b/components/sensor/zyaura.rst index 5c71c01aa6c..1f7f81619f6 100644 --- a/components/sensor/zyaura.rst +++ b/components/sensor/zyaura.rst @@ -76,6 +76,7 @@ See Also -------- - :ref:`sensor-filters` +- :doc:`absolute_humidity` - :doc:`mhz19` - `CO2mon-esp firmware `__ by `@anonym-tsk `__ - `Some information about hacking MT8060 `__ diff --git a/components/spi.rst b/components/spi.rst index d6a433ced01..8cac04e9c8c 100644 --- a/components/spi.rst +++ b/components/spi.rst @@ -41,6 +41,7 @@ Configuration variables: - **clk_pin** (**Required**, :ref:`Pin Schema `): The pin used for the clock line of the SPI bus. - **mosi_pin** (*Optional*, :ref:`Pin Schema `): The pin used for the MOSI line of the SPI bus. - **miso_pin** (*Optional*, :ref:`Pin Schema `): The pin used for the MISO line of the SPI bus. +- **force_sw** (*Optional*, boolean): Whether software implementation should be used even if hardware one is available. - **id** (*Optional*, :ref:`config-id`): Manually specify the ID for this SPI hub if you need multiple SPI hubs. See Also diff --git a/components/sprinkler.rst b/components/sprinkler.rst index 894a2eeab64..2f7ec30ddb9 100644 --- a/components/sprinkler.rst +++ b/components/sprinkler.rst @@ -51,8 +51,9 @@ It reaches even further, however, offering several more advanced features, as we :align: center :width: 60.0% - Example Sprinkler Controller UI -- Note that this example leverages :ref:`number ` components - for setting run durations, repeat and multiplier values. More details below. + Example Sprinkler Controller UI -- Note that this example leverages :doc:`number ` + components for setting run durations, repeat and multiplier values. + :ref:`More details below. ` .. code-block:: yaml @@ -105,29 +106,32 @@ Configuration variables: the valves in reverse order (last-to-first as they appear in the controller's configuration). When this switch is turned off or not provided, the controller will iterate through the valves first-to-last. This switch will not appear in the front end if the controller is configured with only one valve. +- **standby_switch** (*Optional*, *string*): The name for the sprinkler controller's standby switch + as it will appear in the front end. When this switch is turned on, the controller *will not start any valves.* + **This can result in confusing/unexpected behavior if there is no visual indication of this condition!** - **valve_open_delay** (*Optional*, :ref:`config-time`): The *minimum* delay in seconds that should be inserted between (distribution) valve switching -- in other words, the amount of time that must elapse between one valve switching off and the next one switching on. Useful for systems with valves which depend - on sufficient water pressure to close. May not be used with *valve_overlap*. + on sufficient water pressure to close. May not be used with ``valve_overlap``. - **valve_overlap** (*Optional*, :ref:`config-time`): The amount of time in seconds that the current valve and the next valve should run simultaneously as the next valve/zone starts up. This may help prevent pipes - from banging as valves close. May not be used with *valve_open_delay*. + from banging as valves close. May not be used with ``valve_open_delay``. - **pump_switch_off_during_valve_open_delay** (*Optional*, boolean): If set to ``true``, the pump will be switched off during the ``valve_open_delay`` interval; otherwise, it remains on. This may only be specified when ``valve_open_delay`` is configured (see above). Defaults to ``false``. - **pump_start_pump_delay** (*Optional*, :ref:`config-time`): The delay in seconds from when a distribution valve is opened to when the associated pump is activated. Useful to ensure pressure does not build - up from running the pump when no distribution valves are open. May not be used with *pump_start_valve_delay*. + up from running the pump when no distribution valves are open. May not be used with ``pump_start_valve_delay``. - **pump_start_valve_delay** (*Optional*, :ref:`config-time`): The delay in seconds from when a pump is started to when the associated distribution valve is opened. Useful for systems where distribution - valves require sufficient pressure to fully/quickly close. May not be used with *pump_start_pump_delay*. + valves require sufficient pressure to fully/quickly close. May not be used with ``pump_start_pump_delay``. - **pump_stop_pump_delay** (*Optional*, :ref:`config-time`): The delay in seconds from when a distribution valve is closed to when the respective pump is deactivated. Useful for systems where distribution valves - require sufficient pressure to fully/quickly close. May not be used with *pump_stop_valve_delay*. + require sufficient pressure to fully/quickly close. May not be used with ``pump_stop_valve_delay``. - **pump_stop_valve_delay** (*Optional*, :ref:`config-time`): The delay in seconds from when a pump is deactivated to when the respective distribution valve is closed. Useful to ensure pressure does not build up from running the pump when no distribution valves are open or to allow the main line out to distribution - valves to drain. May not be used with *pump_stop_pump_delay*. + valves to drain. May not be used with ``pump_stop_pump_delay``. - **pump_pulse_duration** (*Optional*, :ref:`config-time`): The *minimum* length of the pulse generated to operate a pump in milliseconds. *Required* when one or more latching pumps is configured. Note that the *exact* length of the pulse is determined by the frequency of the main application loop (as are other ``delay`` timers @@ -140,7 +144,18 @@ Configuration variables: used in ESPHome). Typically this is expected to provide a resolution of approximately 16 milliseconds, however this may vary somewhat depending on your exact configuration. Regardless, it should provide more-than-sufficient precision to operate any such valve. -- **repeat** (*Optional*, int): The number of times a full cycle should be repeated. Defaults to 0. +- **multiplier_number** (*Optional*, *string*): The name of the :doc:`number ` component that + should be presented to the front end (Home Assistant) to enable control of the sprinkler controller's ``multiplier`` + value. See :ref:`sprinkler-controller-sprinkler_controller_numbers` below for more detail. +- **repeat_number** (*Optional*, *string*): The name of the :doc:`number ` component that + should be presented to the front end (Home Assistant) to enable control of the sprinkler controller's ``repeat`` + value. May not be used with ``repeat``. See :ref:`sprinkler-controller-sprinkler_controller_numbers` below for more + detail. +- **repeat** (*Optional*, int): The number of times a full cycle should be repeated. Defaults to 0. May not be used + with ``repeat_number``. +- **next_prev_ignore_disabled** (*Optional*, boolean): Set to ``true`` to cause + :ref:`sprinkler-controller-action_next_valve` and :ref:`sprinkler-controller-action_previous_valve` to skip + over valves that are not enabled. Defaults to ``false``. - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. While optional, this is necessary to identify the controller instance (particularly in cases where more than one is defined) when calling controller actions (see below) such as ``start_full_cycle`` or ``shutdown``. @@ -173,10 +188,16 @@ Configuration variables: would *switch on* the respective pump/valve. *It is not recommended to expose this switch to the front end; please see* :ref:`sprinkler-controller-an_important_note_about_gpio_switches_and_control` *below for more detail.* May not be specified with *pump_switch_id*. - - **run_duration** (**Required**, :ref:`config-time`): The duration in seconds this valve should - remain on/open after it is activated. When a given valve is activated, the controller's multiplier value - is multiplied by this value to determine the actual run duration for the valve, thus allowing the run - duration for all valves/zones to be proportionally increased or decreased as desired. + - **run_duration_number** (*Optional*, *string*): The name of the :doc:`number ` component + that should be presented to the front end (Home Assistant) to enable control of the valve's ``run_duration`` value. + May not be used with ``run_duration``. See :ref:`sprinkler-controller-sprinkler_controller_numbers` below for more + detail. **Pro tip:** Want times in minutes? Add ``unit_of_measurement: min`` to the number configuration. See + :ref:`sprinkler-controller-sprinkler_controller_numbers` for more detail. + - **run_duration** (*Optional*, :ref:`config-time`): Required when ``run_duration_number`` is not provided. The + duration in seconds this valve should remain on/open after it is activated. When a given valve is activated, the + controller's multiplier value is multiplied by this value to determine the actual run duration for the valve, thus + allowing the run duration for all valves/zones to be proportionally increased or decreased as desired. May not be + used with ``run_duration_number``. - **valve_switch_id** (**Required**, :ref:`Switch `): This is the :ref:`switch ` component to be used to control the valve that operates the given section or zone of the sprinkler system. Typically this would be a :doc:`GPIO switch ` wired to control a relay @@ -213,7 +234,7 @@ off, **not** the :doc:`GPIO switch ` the zone is configured with. Keep in mind that a :doc:`GPIO switch ` directly controls the state of the GPIO pin it is associated with. While it's technically feasible to "override" this behavior, it might not always be desirable. For example, if you *wanted* to control the state of the switch/pin manually during testing of your system/configuration, this -would make that impossible (or at least more difficult than necessary), presenting other complications. Ultimately, +would make doing so impossible (or at least more difficult than necessary), presenting other complications. Ultimately, flexibility is key, as we've learned from any number of conversations on the ESPHome Discord server. As mentioned in the introduction, the sprinkler controller automates control of the :doc:`GPIO switches ` @@ -295,11 +316,11 @@ See :ref:`sprinkler-controller-sprinkler_controller_queue` section below for mor ``sprinkler.start_single_valve`` action *************************************** -Starts a single valve. This disables the controller's "auto-advance" and queue features so that -only this valve/zone will run. The valve will remain on for its configured ``run_duration`` -multiplied by the controller's multiplier value. *Note that this action ignores whether the valve -is enabled; that is, when called, the specified valve will always run.* Valves are numbered in the -order they appear in the sprinkler controller's configuration starting at zero (0). +Starts a single valve. This disables the controller's "auto-advance" and queue features so that only this valve/zone +will run. The valve will remain on for the specified duration or (if ``run_duration`` is not specified or is zero) for +its configured ``run_duration`` multiplied by the controller's multiplier value. *Note that this action ignores whether +the valve is enabled; that is, when called, the specified valve will always run.* Valves are numbered in the order they +appear in the sprinkler controller's configuration starting at zero (0). .. code-block:: yaml @@ -308,14 +329,14 @@ order they appear in the sprinkler controller's configuration starting at zero ( - sprinkler.start_single_valve: id: sprinkler_ctrlr valve_number: 0 + run_duration: 600s # optional .. _sprinkler-controller-action_shutdown: ``sprinkler.shutdown`` action ***************************** -Immediately (begins to) turns off all valves, effectively shutting down the system, respecting any -configured pump or valve stop delays. +Initiates a shutdown of all valves/the system, respecting any configured pump or valve stop delays. .. code-block:: yaml @@ -330,7 +351,8 @@ configured pump or valve stop delays. Advances to the next valve (numerically). If ``manual_selection_delay`` is configured, the controller will wait before activating the selected valve. If no valve is active, the first valve (as they appear -in the controller's configuration) will be started. +in the controller's configuration) will be started. Setting ``next_prev_ignore_disabled`` to ``true`` +will cause this action to skip valves that are not enabled via their valve enable switch (see above). .. code-block:: yaml @@ -345,7 +367,8 @@ in the controller's configuration) will be started. Advances to the previous valve (numerically). If ``manual_selection_delay`` is configured, the controller will wait before activating the selected valve. If no valve is active, the last valve (as they appear in -the controller's configuration) will be started. +the controller's configuration) will be started. Setting ``next_prev_ignore_disabled`` to ``true`` will +cause this action to skip valves that are not enabled via their valve enable switch (see above). .. code-block:: yaml @@ -438,8 +461,13 @@ section below for more detail and examples. *********************************** Sets the multiplier value used to proportionally increase or decrease the run duration for all valves/zones. -When a given valve is activated, this value is multiplied by the valve's run duration (see below) to -determine the valve's actual run duration. +For seasonal changes, it’s easier to use the multiplier to adjust the watering time instead of adjusting the +run durations directly. Set your run duration to the time you want for ‘mild’ weather (spring/autumn) and then +use the multiplier to increase (summer) or decrease (winter) the calculated run times. When a given valve is +activated, this value is multiplied by the valve's run duration (see below) to determine the valve's actual +run duration. *Note that a multiplier value of zero is allowed; if the multiplier value is zero, the +sprinkler controller will not start any valves.* **This can result in confusing/unexpected behavior if +a visual indication of this condition is not available!** .. code-block:: yaml @@ -466,6 +494,30 @@ of 1, the initial cycle will run, then the repeat cycle will run, resulting in a id: sprinkler_ctrlr repeat: 2 # would run three cycles +.. _sprinkler-controller-action_set_divider: + +``sprinkler.set_divider`` action +******************************** + +The divider value sets both the multiplier and repeat values as follows: + +- The multiplier value is set to the value of 1 / ``divider`` +- The repeat value is set to ``divider`` - 1 + +As an example, given a divider value of 4, the multiplier would be set to 0.25 and the repeat value +would be set to 3. + +This can be useful for dividing the run duration for each valve into multiple shorter cycles, therefore +avoiding run-off by allowing the ground more time to absorb the water. + +.. code-block:: yaml + + on_...: + then: + - sprinkler.set_divider: + id: sprinkler_ctrlr + divider: 2 + .. _sprinkler-controller-action_set_valve_run_duration: ``sprinkler.set_valve_run_duration`` action @@ -485,8 +537,7 @@ by the multiplier value (see above) to determine the valve's actual run duration .. note:: - - The ``next_valve``, ``previous_valve`` and ``start_single_valve`` actions ignore whether a valve - is enabled via its enable switch. + - The ``start_single_valve`` action ignores whether a valve is enabled via its enable switch. - The ``next_valve`` and ``previous_valve`` actions may not appear to respond immediately if either ``manual_selection_delay`` or any of the various delay mechanisms described in the :ref:`sprinkler-controller-pump_and_distribution_valve_coordination` section below are configured. @@ -636,19 +687,21 @@ This example illustrates a complete, simple three-valve system with no pump/upst main_switch: "Lawn Sprinklers" auto_advance_switch: "Lawn Sprinklers Auto Advance" reverse_switch: "Lawn Sprinklers Reverse" + multiplier_number: "Lawn Sprinkler Multiplier" + repeat_number: "Lawn Sprinkler Repeat" valve_overlap: 5s valves: - valve_switch: "Front Lawn" enable_switch: "Enable Front Lawn" - run_duration: 900s + run_duration_number: "Front Yard Run Duration" valve_switch_id: lawn_sprinkler_valve_sw0 - valve_switch: "Side Lawn" enable_switch: "Enable Side Lawn" - run_duration: 900s + run_duration_number: "Front Yard Run Duration" valve_switch_id: lawn_sprinkler_valve_sw1 - valve_switch: "Back Lawn" enable_switch: "Enable Back Lawn" - run_duration: 900s + run_duration_number: "Front Yard Run Duration" valve_switch_id: lawn_sprinkler_valve_sw2 switch: @@ -853,12 +906,20 @@ valves, each of which are shared between the two controllers: - valve_switch: "Front Garden" enable_switch: "Enable Front Garden" pump_switch_id: sprinkler_pump_sw0 - run_duration: 900s + run_duration_number: + id: garden_sprinkler_ctrlr_front_run_duration + name: "Front Garden Run Duration" + initial_value: 10 + unit_of_measurement: min valve_switch_id: garden_sprinkler_valve_sw0 - valve_switch: "Back Garden" enable_switch: "Enable Back Garden" pump_switch_id: sprinkler_pump_sw1 - run_duration: 900s + run_duration_number: + id: garden_sprinkler_ctrlr_back_run_duration + name: "Back Garden Run Duration" + initial_value: 10 + unit_of_measurement: min valve_switch_id: garden_sprinkler_valve_sw1 switch: @@ -891,6 +952,59 @@ valves, each of which are shared between the two controllers: communicate to ensure any given pump is activated and deactivated only as necessary, even when the controllers are operating simultaneously. +.. _sprinkler-controller-sprinkler_controller_numbers: + +Using the Sprinkler Controller's Numbers +**************************************** + +The sprinkler controller can leverage ESPHome's/Home Assistant's :doc:`number ` component to +make valve run durations easily adjustable from the front end (Home Assistant). + +.. code-block:: yaml + + sprinkler: + - id: lawn_sprinkler_ctrlr + multiplier_number: "Lawn Sprinkler Multiplier" + repeat_number: "Lawn Sprinkler Repeat" + ... + +An added benefit of using :doc:`number ` components is that modified valve run durations, +multiplier and repeat values can persist across resets/reboots of the ESP device. If this is your desired behavior, you +should configure the :doc:`number ` components within your sprinkler controller configuration. + +The sprinkler controller's implementation of the :doc:`number ` component is based on +ESPHome's :doc:`/components/number/index`, supporting all of its :ref:`configuration variables ` in +addition to a subset of the :doc:`Template Number Component's ` configuration variables, +including: + +- ``initial_value`` (Defaults to 900 for valves, 1 for multiplier, 0 for repeat) +- ``max_value`` (Defaults to 86400 for valves, 10 for multiplier and repeat) +- ``min_value`` (Defaults to 1 for valves, 0 for multiplier and repeat) +- ``step`` (Defaults to 1 for valves and repeat, 0.1 for multiplier) +- ``restore_value`` (Defaults to ``true``; set to ``false`` to always restore ``initial_value`` at boot) +- ``set_action`` +- ``unit_of_measurement`` (For run durations only; defaults to ``s`` for seconds or specify ``min`` for minutes) + +Here's a brief example: + +.. code-block:: yaml + + sprinkler: + - id: lawn_sprinkler_ctrlr + main_switch: "Lawn Sprinklers" + ... + multiplier_number: + id: controller_multiplier_number + name: "Lawn Sprinkler Multiplier" + initial_value: 1.5 + min_value: 0.1 + max_value: 5 + set_action: + - lambda: "some_function();" + ... + +.. _sprinkler-controller-sprinkler_controller_extending_switches: + Extending the Sprinkler Controller's Switches ********************************************* @@ -970,30 +1084,6 @@ queue entry will be picked up *before* the next valve that would run as a part o behavior cannot be changed. It should also be noted that the queue has a hard-coded limit of 100 entries to limit memory use. -Additional Tricks -***************** - -Beyond what is shown in the configuration examples above, other ESPHome elements may be called into -play to help build out an extensive interface for the controller in the front end (Home Assistant). -For example, the :ref:`number ` component may be used to set valve run durations or -the controller's multiplier value: - -.. code-block:: yaml - - # Example configuration to set multiplier via number - number: - - platform: template - id: sprinkler_ctrlr_multiplier - name: "Sprinkler Controller Multiplier" - min_value: 0.1 - max_value: 10.0 - step: 0.1 - lambda: "return id(lawn_sprinkler_ctrlr).multiplier();" - set_action: - - sprinkler.set_multiplier: - id: lawn_sprinkler_ctrlr - multiplier: !lambda 'return x;' - Expose Sprinkler Controller Actions via user-API ************************************************ @@ -1032,6 +1122,168 @@ and/or trigger sprinkler controller actions using automations. then: - sprinkler.shutdown: lawn_sprinkler_ctrlr +.. _sprinkler-controller-sprinkler_controller_understanding_state: + +Understanding the Sprinkler Controller's State +---------------------------------------------- + +A number of people have asked about how to determine the sprinkler controller's state. This section aims to outline how +to use the sprinkler controller's :apiref:`API ` to determine what it is doing, generally with +the goal of indicating this on some form of :doc:`display ` hardware. Note that this +discussion largely revolves around C++ code (as is used in ESPHome lambdas). + +Many of the methods used to determine the sprinkler controller's state return a type of value known as an ``optional``. +If you are curious, a general reference for the ``optional`` type may be found +`here `__, but what is important for now is: + +- The ``optional`` type *may* or *may not* contain a value + + - The method ``has_value()`` is used to determine if a value is present. For example: + ``id(lawn_sprinkler_ctrlr).active_valve().has_value()`` + - The method ``value()`` is used to determine the value, *if* it is determined that a value is present. For example: + ``auto running_valve = id(lawn_sprinkler_ctrlr).active_valve().value()`` + +- The ``optional`` type can contain a value of any C++ type (``bool``, ``int``, ``float``, etc.) (In C++ terms, it is a + template.) + +The examples that follow illustrate use of the the sprinkler controller's methods within a +:doc:`display ` lambda. The examples are intended to illustrate a pattern and (for sake of +brevity) *are not complete*; at very least you'll need to fill out the :doc:`display ` +component's specific configuration details before you can use them. + +With these points in mind, let's discuss some of the methods which indicate the state of the sprinkler controller. +We'll approach this from the angle of *"how do I..."* + +.. _sprinkler-controller-sprinkler_controller_understanding_state_how_do_i: + +How Do I... +*********** + +- **...determine if the sprinkler controller is running?** + + Use the method ``optional active_valve()`` to check if there is an active valve. If the ``optional`` returned + ``has_value()``, the sprinkler controller is running and you may use the ``value()`` method to check which specific + valve is active. + + *Example:* + + .. code-block:: c++ + + display: + - platform: ... + # ...display configuration... + lambda: |- + if (id(lawn_sprinkler_ctrlr).active_valve().has_value()) { + // the controller is running, get the active valve into running_valve and print it + auto running_valve = id(lawn_sprinkler_ctrlr).active_valve().value(); + it.printf(0, 0, "Valve %u active", running_valve); + } else { + // the controller is NOT running + it.print(0, 0, "Idle"); + } + +- **...determine if the sprinkler controller is paused and, if so, which valve is paused?** + + Use the method ``optional paused_valve()`` to check if there is a paused valve. If the ``optional`` returned + ``has_value()``, the sprinkler controller is paused and you may use the ``value()`` method to check which specific + valve is paused. In general, this follows the same pattern as the + :ref:`active_valve() example above `. + +- **...determine the sprinkler controller's current mode?** + + If by this you mean, "is auto-advance/the queue/reverse/standby enabled?", you are in the right spot. Methods exist + for just this purpose: + + - ``bool auto_advance()`` + - ``bool queue_enabled()`` + - ``bool reverse()`` + - ``bool standby()`` + + Each will return ``true`` if the respective "mode" is enabled. + + *Examples:* + + .. code-block:: c++ + + display: + - platform: ... + # ...display configuration... + lambda: |- + if (id(lawn_sprinkler_ctrlr).auto_advance()) { + // auto-advance is enabled + it.print(0, 0, "Auto-advance enabled"); + } else { + // auto-advance is NOT enabled + it.print(0, 0, "Auto-advance disabled"); + } + if (id(lawn_sprinkler_ctrlr).queue_enabled()) { + // queue is enabled + it.print(0, 10, "Queue enabled"); + } else { + // queue is NOT enabled + it.print(0, 10, "Queue disabled"); + } + +- **...determine the sprinkler controller's multiplier/repeat values?** + + Methods of interest in this case are: + + - ``float multiplier()`` + - ``optional repeat()`` + - ``optional repeat_count()`` + + Note again that each of the ``repeat`` methods returns an ``optional`` type; if the ``optional`` returned + ``has_value()``, repeating is enabled and you can get the repeat target (``repeat()``) or current repeat + count (``repeat_count()``) with ``optional``'s ``value()`` method. + + The ``multiplier()`` method returns a ``float`` type and, as such, it always has a value. + + *Examples:* + + .. code-block:: c++ + + display: + - platform: ... + # ...display configuration... + lambda: |- + it.printf(0, 0, "Multiplier: %f", id(lawn_sprinkler_ctrlr).multiplier()); + + if (id(lawn_sprinkler_ctrlr).repeat().has_value()) { + // the controller is repeating, print the repeat target value + it.printf(0, 10, "Repeat %u times", id(lawn_sprinkler_ctrlr).repeat().value()); + } + +- **...determine how much time is left/required?** + + Several methods are available for this purpose: + + - ``uint32_t total_cycle_time_all_valves()`` + - ``uint32_t total_cycle_time_enabled_valves()`` + - ``uint32_t total_cycle_time_enabled_incomplete_valves()`` + - ``uint32_t total_queue_time()`` + - ``optional time_remaining_active_valve()`` + - ``optional time_remaining_current_operation()`` + + Note that, as with several of the earlier examples, the ``time_remaining_...`` methods each return an ``optional`` + type. If the ``optional`` returned ``has_value()``, a valve is active/running; if it does not ``has_value()``, no + valve is active, meaning the controller is idle. + + *Example:* + + .. code-block:: c++ + + display: + - platform: ... + # ...display configuration... + lambda: |- + if (id(lawn_sprinkler_ctrlr).time_remaining_active_valve().has_value()) { + // the controller is running, print the number of seconds remaining + it.printf(0, 0, "Time left: %u sec.", id(lawn_sprinkler_ctrlr).time_remaining_active_valve().value()); + } else { + // the controller is NOT running + it.print(0, 0, "Idle"); + } + See Also -------- diff --git a/components/switch/custom.rst b/components/switch/custom.rst index ffea90bfe07..a5837b94b71 100644 --- a/components/switch/custom.rst +++ b/components/switch/custom.rst @@ -50,6 +50,7 @@ And in YAML: switches: name: "My Custom Switches" + id: my_custom_switch Configuration variables: diff --git a/components/switch/index.rst b/components/switch/index.rst index e14ddf99ccf..881e4e046c3 100644 --- a/components/switch/index.rst +++ b/components/switch/index.rst @@ -23,6 +23,12 @@ Base Switch Configuration Configuration variables: - **name** (**Required**, string): The name of the switch. + + .. note:: + + If you have a :ref:`friendly_name ` set for your device and + you want the switch to use that name, you can set ``name: None``. + - **icon** (*Optional*, icon): Manually set the icon to use for the sensor in the frontend. - **inverted** (*Optional*, boolean): Whether to invert the binary @@ -41,11 +47,11 @@ Configuration variables: - ``RESTORE_DEFAULT_ON`` - Attempt to restore state and default to ON. - ``RESTORE_INVERTED_DEFAULT_OFF`` - Attempt to restore state inverted from the previous state and default to OFF. - ``RESTORE_INVERTED_DEFAULT_ON`` - Attempt to restore state inverted from the previous state and default to ON. - - ``ALWAYS_OFF`` - Always initialize the switch as OFF on bootup. + - ``ALWAYS_OFF`` (Default) - Always initialize the switch as OFF on bootup. - ``ALWAYS_ON`` - Always initialize the switch as ON on bootup. - - ``DISABLED`` - Does nothing and leaves it up to the downstream platform component to decide. For example, the component could read hardware and determine the state, or have a specific configuration option to regulate initial state. + - ``DISABLED`` - Does nothing and leaves it up to the downstream platform component to decide. For example, the component could read hardware and determine the state, or have a specific configuration option to regulate initial state. - Unless a specific platform defines another default value, the default is ``RESTORE_DEFAULT_OFF``. + Unless a specific platform defines another default value, the default is ``ALWAYS_OFF``. - **on_turn_on** (*Optional*, :ref:`Action `): An automation to perform when the switch is turned on. See :ref:`switch-on_turn_on_off_trigger`. diff --git a/components/switch/safe_mode.rst b/components/switch/safe_mode.rst index 73ae6384a0e..24c4e6a5d20 100644 --- a/components/switch/safe_mode.rst +++ b/components/switch/safe_mode.rst @@ -5,8 +5,7 @@ Safe Mode Switch :description: Instructions for setting up switches that can remotely reboot the ESP in ESPHome into safe mode. :image: restart.svg -The ``safe_mode`` switch allows you to remotely reboot your node into :ref:`Safe Mode `. This is useful in certain situations -where a misbehaving component is preventing Over-The-Air updates from completing successfully. +The ``safe_mode`` switch allows you to remotely reboot your node into :ref:`Safe Mode `. This is useful in certain situations where a misbehaving component, or low memory state is preventing Over-The-Air updates from completing successfully. This component requires :ref:`OTA ` to be configured. diff --git a/components/text_sensor/index.rst b/components/text_sensor/index.rst index d5379c67d6b..c91a0997d27 100644 --- a/components/text_sensor/index.rst +++ b/components/text_sensor/index.rst @@ -25,6 +25,12 @@ Base Text Sensor Configuration Configuration variables: - **name** (**Required**, string): The name for the sensor. + + .. note:: + + If you have a :ref:`friendly_name ` set for your device and + you want the text sensor to use that name, you can set ``name: None``. + - **icon** (*Optional*, icon): Manually set the icon to use for the sensor in the frontend. - **internal** (*Optional*, boolean): Mark this component as internal. Internal components will not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without @@ -145,7 +151,7 @@ The arguments are a list of substitutions, each in the form ``TO_FIND -> REPLACE ``map`` ******* -Lookup the current value of the text sensor in a list, and return the matching item if found. +Lookup the current value of the text sensor in a list, and return the matching item if found. Does not change the value of the text sensor if the current value wasn't found. diff --git a/components/time/index.rst b/components/time/index.rst index 1ea6b694db2..ac6d4ff271e 100644 --- a/components/time/index.rst +++ b/components/time/index.rst @@ -21,9 +21,10 @@ Configuration variables: - **id** (*Optional*, :ref:`config-id`): Specify the ID of the time for use in lambdas. - **timezone** (*Optional*, string): Manually tell ESPHome what time zone to use with `this format - `__ (warning: the format is quite complicated) + `__ + (warning: the format is quite complicated, see `examples `__) or the simpler `TZ database name `__ in the form - /. ESPHome tries to automatically infer the time zone string based on the time zone of the computer + :code:`/`. ESPHome tries to automatically infer the time zone string based on the time zone of the computer that is running ESPHome, but this might not always be accurate. - **on_time** (*Optional*, :ref:`Automation `): Automation to run at specific intervals using a cron-like syntax. See :ref:`time-on_time`. @@ -39,12 +40,19 @@ This :ref:`Condition ` checks if time has been set and is vali .. code-block:: yaml + # Example configuration on_...: if: condition: time.has_time: then: - logger.log: Time has been set and is valid! + + # Example lambda + lambda: |- + if (id(my_time).now().is_valid()) { + //do something here + } .. _time-on_time: diff --git a/components/touchscreen/index.rst b/components/touchscreen/index.rst index 5efa2da00b3..8e3e463efbd 100644 --- a/components/touchscreen/index.rst +++ b/components/touchscreen/index.rst @@ -38,7 +38,7 @@ Configuration variables: This automation will be triggered when the touchscreen detects a touch. -This trigger provides one arguments of type :apistruct:`touchscreen::TouchPoint` which has two integer members: ``x`` and ``y`` which +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. diff --git a/components/uart.rst b/components/uart.rst index 3c98d7b8f45..c17caa2128f 100644 --- a/components/uart.rst +++ b/components/uart.rst @@ -30,12 +30,12 @@ In some cases only **TX** or **RX** exists as the device at the other end only a On the ESP32, this component uses the hardware UART units and is thus very accurate. On the ESP8266 however, ESPHome has to use a software implementation as there are no other hardware UART units available other than the ones used for logging. Therefore the UART data on the ESP8266 can have occasional data glitches especially with - higher baud rates.. + higher baud rates. .. note:: From ESPHome 2021.8 the ``ESP8266SoftwareSerial`` UART ``write_byte`` function had the parity bit fixed to be correct - for the data being sent. This could cause unexpected issues if you are using the Software Serial and have devices that + for the data being sent. This could cause unexpected issues if you are using the Software UART and have devices that explicity check the parity. Most likely you will need to flip the ``parity`` flag in YAML. @@ -65,7 +65,7 @@ Configuration variables: Hardware UARTs -------------- -Whenever possible, ESPHome will use the hardware UART unit on the processor for fast and accurate communication. +Whenever possible, ESPHome will use the hardware UART unit on the ESP8266 for fast and accurate communication. When the hardware UARTs are all occupied, ESPHome will fall back to a software implementation that may not be accurate at higher baud rates. @@ -74,12 +74,16 @@ be accurate at higher baud rates. logger and leave others available. If you have configured the logger to use a different hardware UART, the pins used for hardware sharing change accordingly. -The ESP32 has three UARTs. Any pair of GPIO pins can be used, as long as they support the proper output/input modes. +The ESP32 has three UARTs. ESP32 lite variant chips (ESP32-S3, ESP32-C3, ESP32-S2, etc) may have fewer UARTs (usually two). Any pair of GPIO pins can be used, as long as they support the proper output/input modes. The ESP8266 has two UARTs; the second of which is TX-only. Only a limited set of pins can be used. ``UART0`` may use either ``tx_pin: GPIO1`` and ``rx_pin: GPIO3``, or ``tx_pin: GPIO15`` and ``rx_pin: GPIO13``. ``UART1`` must use ``tx_pin: GPIO2``. Any other combination of pins will result in use of a software UART. +.. note:: + + The the Software UART is only available on the ESP8266. It is not available on ESP32 and variants. + .. _uart-write_action: ``uart.write`` Action diff --git a/components/voice_assistant.rst b/components/voice_assistant.rst new file mode 100644 index 00000000000..8bd5c1b1862 --- /dev/null +++ b/components/voice_assistant.rst @@ -0,0 +1,79 @@ +Voice Assistant +=============== + +.. seo:: + :description: Instructions for setting up a Voice Assistant in ESPHome. + :image: voice-assistant.svg + +ESPHome devices with a microphone are able to stream the audio to Home Assistant and be processed there by `assist `__. + +.. note:: + + Voice Assistant requires Home Assistant 2023.5 or later. + +Configuration: +-------------- + +.. code-block:: yaml + + microphone: + - platform: ... + id: mic_id + + voice_assistant: + microphone: mic_id + +- **microphone** (**Required**, :ref:`config-id`): The microphone to use for input. +- **on_start** (*Optional*, :ref:`Automation `): An automation to + perform when the voice assistant starts listening. +- **on_end** (*Optional*, :ref:`Automation `): An automation to perform + when the voice assistant is finished all tasks. +- **on_stt_end** (*Optional*, :ref:`Automation `): An automation to perform + when the voice assistant has finished speech-to-text. The resulting text is + available to automations as the variable ``x``. +- **on_tts_start** (*Optional*, :ref:`Automation `): An automation to perform + when the voice assistant has started text-to-speech. The text to be spoken is + available to automations as the variable ``x``. +- **on_tts_end** (*Optional*, :ref:`Automation `): An automation to perform + when the voice assistant has finished text-to-speech. A URL containing the audio response + is available to automations as the variable ``x``. +- **on_error** (*Optional*, :ref:`Automation `): An automation to perform + when the voice assistant has encountered an error. The error code and message are available to + automations as the variables ``code`` and ``message``. + +.. _voice_assistant-actions: + +Voice Assistant Actions +----------------------- + +The following actions are available for use in automations: + +- ``voice_assistant.start`` - Start listening for voice commands. +- ``voice_assistant.stop`` - Stop listening for voice commands. + + +Push to Talk +------------ + +Here is an example offering Push to Talk with a :doc:`/components/binary_sensor/index`. + +.. code-block:: yaml + + voice_assistant: + microphone: mic_id + + binary_sensor: + - platform: gpio + pin: ... + on_press: + - voice_assistant.start: + on_release: + - voice_assistant.stop: + + +See Also +-------- + +- :doc:`microphone/index` +- :apiref:`voice_assistant/voice_assistant.h` +- :ghedit:`Edit` diff --git a/components/wifi.rst b/components/wifi.rst index 0fafb5ca6ec..5fecb4b40ef 100644 --- a/components/wifi.rst +++ b/components/wifi.rst @@ -84,6 +84,7 @@ Configuration variables: first. This is required for hidden networks and can significantly improve connection times. Defaults to ``off``. The downside is that this option connects to the first network the ESP sees, even if that network is very far away and better ones are available. +- **passive_scan** (*Optional*, boolean): If enabled, then the device will perform WiFi scans in a passive fashion. Defaults to ``false``. - **enable_btm** (*Optional*, bool): Only on ``esp32`` with ``esp-idf``. Enable 802.11v BSS Transition Management support. - **enable_rrm** (*Optional*, bool): Only on ``esp32`` with ``esp-idf``. Enable 802.11k Radio Resource Management support. diff --git a/conf.py b/conf.py index a848ff807f6..1280ef3c658 100644 --- a/conf.py +++ b/conf.py @@ -67,9 +67,9 @@ # built documents. # # The short X.Y version. -version = "2023.3" +version = "2023.5" # The full version, including alpha/beta/rc tags. -release = "2023.3.0-dev" +release = "2023.5.0-dev" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/cookbook/air_gradient_diy_air_quality_sensor.rst b/cookbook/air_gradient_diy_air_quality_sensor.rst deleted file mode 100644 index 2fc067c8aa1..00000000000 --- a/cookbook/air_gradient_diy_air_quality_sensor.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. seo:: - :description: AirGradient DIY Air Quality Sensor - :image: air_gradient_diy_air_quality_sensor.jpg - :keywords: Air Quality Sensor DIY - -AirGradient DIY Air Quality Sensor -================================== - -.. figure:: images/air_gradient_diy_air_quality_sensor.jpg - :align: center - :width: 100.0% - -AirGradient has created a DIY Air Quality sensor. -They offer a PCB, PCB + components kit, etc. -A pretty neat package. -To use this you have to run their software but you can use the kit with ESPHome as well! - -Here is what it can measure: - -- **Temperature** -- **Humidity** -- **Air particles PM2.5** -- **Carbon Dioxide** - -Additionally: - -- There is a display so show off your data or whatever you desire from Home Assistant -- You can download a 3D printable case including a wall mount bracket - - -ESPHome Configuration ---------------------- -Documentation: - -- `Blog Article: Measuring Air Quality in your Home Office `__ -- `ESPHome code with a setup guide for Home Assistant `__ -- `AirGradient Shop for the PCB or PCB plus components `__ -- `AirGradient Setup Guide (3D printeable case, setup guide, etc.) `__ - -`YAML configuration `__ - -Soldering and setup video: - -.. raw:: html - - - -See Also --------- - -- :doc:`/devices/nodemcu_esp8266` -- :doc:`/components/display/ssd1306` -- :doc:`/components/i2c` -- :doc:`/components/uart` -- :doc:`/components/sensor/sht3xd` -- :doc:`/components/sensor/pmsx003` -- :doc:`/components/sensor/senseair` -- :doc:`/components/wifi` -- :doc:`/components/api` -- :doc:`/components/logger` -- :doc:`/components/ota` -- :doc:`/components/switch/safe_mode` -- :ghedit:`Edit` diff --git a/cookbook/ble_itag.rst b/cookbook/ble_itag.rst deleted file mode 100644 index a797ad5503a..00000000000 --- a/cookbook/ble_itag.rst +++ /dev/null @@ -1,121 +0,0 @@ -BLE iTag Button -=============== - -.. seo:: - :description: Receive events from a cheap BLE keyring button. - :image: bluetooth.svg - -This example shows how to use a cheap BLE keyring tag to trigger arbitrary -events. An ESP32 is used, which provides a BLE peripheral. - -.. figure:: images/esp32_ble_itag.png - :align: center - :width: 40% - -These tags can be had for a couple of dollars each and run for several months -on a coin cell. Using the BLE features of ESPHome, you can use these as small -and cheap remotes to control any automation. - -Quickstart ----------- - -Use the configuration block below for a basic setup which will provide a -binary_sensor that is momentarily turned on when the button is pressed. - -You will need to find the MAC address of your tag. See the documentation -for :doc:`/components/ble_client` for how to find this out. You may also -wish to change the name and id fields where appropriate to suit your -device(s). - -Note that a maximum of three devices are supported due to limitations in -the ESP32's BLE stack. - -Configuration example: ------------------------- - -.. code-block:: yaml - - esp32_ble_tracker: - - ble_client: - # Replace with the MAC address of your device. - - mac_address: FF:FF:20:00:0F:15 - id: itag_black - - binary_sensor: - - platform: template - id: black_button - name: "Black iTag Button" - filters: - delayed_off: 200ms - - sensor: - # This entry registers and awaits notifications for the - # characteristic that signals button presses. Each time - # a notification is received, the corresponding binary_sensor - # is briefly toggled. - - platform: ble_client - type: characteristic - ble_client_id: itag_black - name: "Black iTag btn" - service_uuid: 'ffe0' - characteristic_uuid: 'ffe1' - notify: true - update_interval: never - on_notify: - then: - - binary_sensor.template.publish: - id: black_button - state: ON - - binary_sensor.template.publish: - id: black_button - state: OFF - # This entry queries the battery level. Some tags may not - # support this characteristic, you will see 'Unknown' in the - # HA frontend. - - platform: ble_client - type: characteristic - ble_client_id: itag_black - name: "Black iTag Battery" - service_uuid: '180f' - characteristic_uuid: '2a19' - icon: 'mdi:battery' - unit_of_measurement: '%' - # This entry queries polls the RSSI when the tag is connected. - - platform: ble_client - type: rssi - ble_client_id: itag_black - name: "Black iTag RSSI" - -Explanation ------------ - -The first thing enabled is the ``esp32_ble_tracker`` component. This sets up -the BLE stack on the device and listens for available devices. - -Next, the ``ble_client`` component will listen to devices discovered by -the tracker, and establish a connection to the given device when it is -available. - -The ``binary_sensor`` provides a template sensor which will export to the -HA frontend the sensor that's switched by the BLE tag's button. - -The first entry in the ``sensor`` component is used to configure the specific -Service and Characteristic UUIDs for an iTag's button. It also enables BLE -notifications and sets up an automation to toggle the ``binary_sensor`` when -a notification is received from the tag. Automatic updates are disabled, there -is no point querying the tag for the device state, as we will be immediately -notified when the button is pressed. - -The next ``sensor`` entry listens for a well-known Service and Chacteristic -that is used by many BLE devices to give battery level information. This sensor -will be exposed in the HA frontend to determine the state of the tag's battery. -Note that many tags will not provide this service, so you will not see a valid -value. If not, you can remove this from the config. - -See Also --------- - -- :doc:`/components/ble_client` -- :doc:`/components/sensor/ble_client` -- :ghedit:`Edit` diff --git a/cookbook/bme280_environment.rst b/cookbook/bme280_environment.rst index d06805c7416..68d93178c7b 100644 --- a/cookbook/bme280_environment.rst +++ b/cookbook/bme280_environment.rst @@ -42,18 +42,10 @@ After validating the sensor is working, we can proceed and add some formulas. update_interval: 15s icon: 'mdi:signal' unit_of_measurement: 'm' - - platform: template + - platform: absolute_humidity name: "Absolute Humidity" - lambda: |- - const float mw = 18.01534; // molar mass of water g/mol - const float r = 8.31447215; // Universal gas constant J/mol/K - return (6.112 * powf(2.718281828, (17.67 * id(bme280_temperature).state) / - (id(bme280_temperature).state + 243.5)) * id(bme280_humidity).state * mw) / - ((273.15 + id(bme280_temperature).state) * r); // in grams/m^3 - accuracy_decimals: 2 - update_interval: 15s - icon: 'mdi:water' - unit_of_measurement: 'g/m³' + temperature: bme280_temperature + humidity: bme280_humidity - platform: template name: "Dew Point" lambda: |- @@ -73,7 +65,7 @@ The variable ``STANDARD_SEA_LEVEL_PRESSURE`` (in hPa), should be filled in for y The formula derived from `here `__, converts the currently measured pressure to the altitudes in meters including temperature compensation. -The lambda in the second :doc:`/components/sensor/template` defines two physical constants and +The second block uses the :doc:`/components/sensor/absolute_humidity` component which converts the currently measured temperature and relative humidity to absolute humidity (grams/m^3). .. note:: @@ -120,13 +112,13 @@ Calculating the sea level pressure with a statically mounted sensor can be used Formula explanation ------------------- -- `Relative humidity calculations `__ - `Altitude calculation `__ - `Dew Point calculation `__ See Also -------- +- :doc:`/components/sensor/absolute_humidity` - :doc:`/components/sensor/template` - :doc:`/components/sensor/bme280` - :ghedit:`Edit` diff --git a/cookbook/brilliant-mirabella-genio-smart-plugs.rst b/cookbook/brilliant-mirabella-genio-smart-plugs.rst deleted file mode 100644 index 1c0e24592df..00000000000 --- a/cookbook/brilliant-mirabella-genio-smart-plugs.rst +++ /dev/null @@ -1,550 +0,0 @@ -Brilliant / Mirabella Genio Smart Plugs -======================================= - -Brilliant / Mirabella Genio Smart Plugs are a Tuya-based smart plugs sold by Bunnings and Kmart respectively in Australia. - -.. figure:: images/brilliant-mirabella-genio-smart-plugs.jpg - :align: center - :width: 50.0% - -Originally intended to be used with their companion apps once flashed using `tuya-convert `__ ESPHome generated -firmware can be uploaded allowing you to control the smart plugs via Home Assistant. - -1. Create the ESPHome Firmware ------------------------------- - -#. Refer to either :doc:`/guides/getting_started_command_line` or :doc:`/guides/getting_started_hassio` before moving onto the next step. -#. Select a plug configuration below based on the plug/s you have and copy all of the text in the code block and paste into your - ``name_of_esphome_configuration.yaml`` file. -#. Compile the firmware, again depending on your chosen setup refer to the guides in the first point. - -2. Flashing ------------ - -2.1 Prerequisites -***************** - -#. Before you begin you'll need one of the following Linux machines running the latest copy of `Raspbian Stretch Lite - `__ - - a. Raspberry Pi 2B/B+ with `USB WiFi Dongle `__. - b. Raspberry Pi 3B/B+. - -.. note:: - - As per the `tuya-convert documentation `__: - - Any Linux with a Wifi adapter which can act as an Access Point should also work. Please note that we have tested the Raspberry Pi with clean installations - only. If you use your Raspberry Pi for anything else, we recommend using another SD card with a clean installation. - -#. A microSD card (minimum 2GB, 8GB+ recommended). -#. Any WiFi device which can connect to the SSID generated by the Raspberry Pi and eventually the flashed Tuya device. **This cannot be an iOS / Apple device. - Android devices will work.** - -2.2 Installing the OS -********************* - -#. It's recommended to read the documentation provided by the Raspberry Pi Foundation on the best way to flash the OS to the microSD card depending on your - platform - `Installing operating system images `__. -#. After you've flashed the microSD card browse to the "boot" partition and add a blank file called "ssh" **(without any extension)** which will enable the - SSH server upon first boot, extended information on this step can be found `here - `__. -#. Plug the microSD card into the Raspberry Pi, connect network cable and power, the Raspberry Pi will start to boot. - -2.3 Connecting to the Pi via SSH -******************************** - -#. Download and install `Putty `__. -#. Open Putty. -#. Enter the IP of Raspberry Pi in the box that says "Host Name", leaving the port set to 22 (default for SSH). A list of recommended ways can be found `here - `__, but the easiest is to download and use `Fing `__ - (`Android `__ / `iOS - `__). -#. In the "Saved Sessions" input box, name the Raspberry Pi connection and then press "Save". -#. Select your new saved session from the list. -#. Press "Open". - -2.4 Configuring the Pi -********************** - -#. In the putty window login with the **pi** as the user and **raspberry** for the password. -#. Type ``sudo apt-get update && sudo apt-get dist-upgrade -y`` and wait for the upgrades to install. -#. Type ``sudo apt-get install git`` and wait for it to install. - -2.5 Setup and Install tuya-convert -********************************** - -#. In the putty window type ``git clone https://github.com/ct-Open-Source/tuya-convert`` press enter and wait while the repository is cloned. -#. Type ``cd tuya-convert`` and press enter. -#. Type ``./install_prereq.sh`` press enter and wait as the script gathers all the required components needed to function. - -2.6 Upload ESPHome Firmware using SFTP -************************************** - -#. Download `FileZilla `__ or `WinSCP `__ or use your preferred FTP - client. -#. Depending on the program you need to connect to the Pi using the IP address as the hostname and the username and password the same as you used to connect - via SSH and ensure your connection type is set to **SFTP** -#. Browse to ``/root/tuya-convert/files``. -#. Upload your compiled ``firmware.bin`` file to this directory. For command line based installs you can access the file under - ``//.pioenvs//firmware.bin`` alternatively Home Assistant add-on users can download the file directly from the web ui. - -2.7 Use tuya-convert to install ESPHome Firmware -************************************************ - -#. Type ``./start_flash.sh`` -#. Type ``yes`` to accept the warning. -#. Connect your alternative WiFi device (non iOS / Apple based) to the ``vtrust-flash`` SSID using ``flashmeifyoucan`` as the password. This is the network - being broadcast by the Pi from the tuya flash script. -#. If you haven't already connect your smart plug and turn it on. It should automatically enter pairing mode, if it doesn't follow the instructions below: - - * Brilliant `(PDF Manual) `__ - - * To connect the Smart WiFi Plug to your WiFi press and hold the manual control button for about 5 seconds until you hear a click. Let go of the button - as soon as you hear the **click**. Then press button once again to activate blinking. **The red indicator light should now blink rapidly (2 times per - second)**. - - * Mirabella `(PDF Manual) `__ - - * To do this, ensure your plug is on (the indicator light should be blue), hold the power button down for 5 seconds until you hear a click, let go of the - power button and then press the button once to activate. - -#. Press enter on your putty window to start the flash process and wait. If the connection is successful you should see a large amount of scrolling text, this - is the script backing up the factory shipped firmware. -#. Once the process is complete you can type ``curl http://10.42.42.42/flashURL?url=http://10.42.42.1/files/firmware.bin`` -#. The plug will restart and if everything is working correctly after a few seconds you should be able to press the button triggering the relay and turning the - blue led on. - -3. Smart Plug Configurations ----------------------------- - -Thanks to the existing work by `@ideasman69 `__ and -`afalzon `__ -which these adaptions created by `@cryptelli `__ are based on. - - -3.1 Brilliant Smart Plug -************************ - -.. code-block:: yaml - - substitutions: - name: brilliant_smart_plug - friendly_name: Brilliant Smart Plug - - esphome: - name: ${name} - - esp8266: - board: esp01_1m - - wifi: - ssid: !secret wifi_ssid - password: !secret wifi_password - - logger: - - api: - - ota: - - binary_sensor: - - platform: gpio - pin: - number: 14 - mode: - input: true - pullup: true - inverted: true - name: "${friendly_name} Power Button" - on_press: - - switch.toggle: relay - - switch: - - platform: gpio - id: red_led - pin: - number: GPIO12 - inverted: true - - - platform: gpio - name: "${friendly_name}" - pin: GPIO5 - id: relay - - # Turn off red LED to show blue when turned on - on_turn_on: - - switch.turn_off: red_led - - # Turns on the red LED once the plug is turned off. Stock plug doesn't do this, to restore normal behavior remove the on_turn_on and on_turn_off - # blocks. - on_turn_off: - - switch.turn_on: red_led - - -3.2 Mirabella Genio Wi-Fi 1 USB Adaptor -*************************************** - -.. code-block:: yaml - - substitutions: - name: mirabella_genio_smart_plug - friendly_name: Mirabella Genio Smart Plug - - esphome: - name: ${name} - - esp8266: - board: esp01_1m - - wifi: - ssid: !secret wifi_ssid - password: !secret wifi_password - - logger: - - api: - - ota: - - binary_sensor: - - platform: gpio - pin: - number: GPIO13 - mode: - input: true - pullup: true - inverted: true - name: "${friendly_name} Button" - on_press: - - switch.toggle: relay - - switch: - - platform: gpio - id: red_led - pin: - number: GPIO4 - inverted: true - - - platform: gpio - name: "${friendly_name}" - pin: GPIO12 - id: relay - - # Turn on red LED - on_turn_on: - - switch.turn_on: red_led - - # Turns off red LED - on_turn_off: - - switch.turn_off: red_led - -3.3 Gosund SP1 -************** - -.. code-block:: yaml - - substitutions: - name: gosund_sp1_smart_plug - friendly_name: Gosund SP1 - - esphome: - name: gosund_sp1_smart_plug - - esp8266: - board: esp8285 - - wifi: - ssid: !secret wifi_ssid - password: !secret wifi_password - - logger: - - api: - - ota: - - binary_sensor: - - platform: gpio - pin: - number: GPIO3 - inverted: true - name: "Power Button" - on_press: - - switch.toggle: relay - - switch: - - platform: gpio - id: led - pin: GPIO1 - - - platform: gpio - name: "Gosund SP1 Smart Plug" - pin: GPIO14 - id: relay - on_turn_on: - - switch.turn_on: led - on_turn_off: - - switch.turn_off: led - - sensor: - - platform: hlw8012 - sel_pin: - number: GPIO12 - inverted: true - cf_pin: GPIO04 - cf1_pin: GPIO05 - current_resistor: 0.00221 - voltage_divider: 871 - current: - name: "Gosund SP1 Smart Plug current" - unit_of_measurement: A - voltage: - name: "Gosund SP1 Smart Plug Voltage" - unit_of_measurement: V - power: - name: "Gosund SP1 Smart Plug Wattage" - unit_of_measurement: W - id: "energy_temp_Wattage" - change_mode_every: 8 - update_interval: 10s - -Check the following page for calibrating the measurements: :ref:`sensor-filter-calibrate_linear`. - -3.4 Topersun WL-SC01 Smart Plug -******************************* - -.. code-block:: yaml - - substitutions: - name: topersun_smart_plug - friendly_name: Topersun Smart Plug - - esphome: - name: ${name} - - esp8266: - board: esp01_1m - - wifi: - ssid: !secret wifi_ssid - password: !secret wifi_password - - logger: - - api: - - ota: - - binary_sensor: - - platform: gpio - pin: - number: 14 - mode: - input: true - pullup: true - inverted: true - name: "${friendly_name} Power Button" - on_press: - - switch.toggle: relay - - switch: - - platform: gpio - id: green_led - pin: - number: GPIO4 - inverted: true - - - platform: gpio - name: "friendly_name Relay" - pin: GPIO12 - id: relay - - # Turn off green LED to show red when turned on. - on_turn_on: - - switch.turn_off: green_led - - # Turns on the green LED once the plug is turned off. - on_turn_off: - - switch.turn_on: green_led - -3.5 NEO Coolcam wifi smart plug -******************************* - -.. code-block:: yaml - - substitutions: - name: coolcam_plug1 - friendly_name: Coolcam Smart Plug - # Higher value gives lower watt readout - current_res: "0.00221" - # Lower value gives lower voltage readout - voltage_div: "800" - - esphome: - name: ${name} - - esp8266: - board: esp8285 - - wifi: - ssid: !secret wifi_ssid - password: !secret wifi_password - - logger: - - api: - - ota: - - binary_sensor: - - platform: gpio - pin: - number: GPIO0 - inverted: true - name: "${friendly_name} Button" - on_press: - - switch.toggle: relay - - switch: - - platform: gpio - name: "${friendly_name} LED Red" - pin: GPIO13 - inverted: true - restore_mode: ALWAYS_OFF - id: red_led - - - platform: gpio - name: "${friendly_name} Relay" - pin: GPIO14 - restore_mode: ALWAYS_ON - id: relay - - on_turn_on: - - switch.turn_on: red_led - - on_turn_off: - - switch.turn_off: red_led - - sensor: - - platform: hlw8012 - sel_pin: - number: GPIO12 - inverted: true - cf_pin: GPIO04 - cf1_pin: GPIO05 - current_resistor: ${current_res} - voltage_divider: ${voltage_div} - current: - name: "${friendly_name} Amperage" - unit_of_measurement: A - voltage: - name: "${friendly_name} Voltage" - unit_of_measurement: V - power: - name: "${friendly_name} Power" - unit_of_measurement: W - id: power_sensor - change_mode_every: 8 - update_interval: 10s - - - platform: total_daily_energy - name: "${friendly_name} Total Daily Energy" - power_id: power_sensor - filters: - # Multiplication factor from W to kW is 0.001 - - multiply: 0.001 - unit_of_measurement: kWh - - -3.6 Arlec Grid Connect Smart Plug In Socket With 2.1A USB Charger -***************************************************************** - -.. code-block:: yaml - - substitutions: - name: arlec_pc389ha_001 - friendly_name: Arlec Smart Plug - - esphome: - name: ${name} - - esp8266: - board: esp01_1m - - wifi: - ssid: !secret wifi_ssid - password: !secret wifi_password - - # Enable fallback hotspot (captive portal) in case wifi connection fails - ap: {} - - captive_portal: - - # Enable logging - logger: - - # Enable Home Assistant API - api: - - ota: - - binary_sensor: - - platform: gpio - pin: - number: 14 - mode: - input: true - pullup: true - inverted: true - name: "${friendly_name} Button" - on_press: - - switch.toggle: relay - - switch: - - platform: gpio - id: blue_led - pin: - number: GPIO4 - inverted: true - - - platform: gpio - id: red_led - pin: - number: GPIO13 - inverted: true - - - platform: gpio - name: "${friendly_name} Power" - pin: GPIO12 - id: relay - on_turn_on: - # Turn off blue LED to show blue when turned on - - switch.turn_off: red_led - - switch.turn_on: blue_led - on_turn_off: - # Turns on the blue LED once the plug is turned off - - switch.turn_off: blue_led - - switch.turn_on: red_led - - -4. Adding to Home Assistant ---------------------------- - -You can now add your smart plug to home assistant via the configurations page, look for 'ESPHome' under the Integrations option and click 'Configure'. - -.. figure:: images/brilliant-mirabella-genio-smart-plugs-homeassistant.jpg - :align: center - :width: 50.0% - -See Also --------- - -- :doc:`/components/switch/index` -- :doc:`/components/binary_sensor/index` -- :doc:`/components/light/index` -- :doc:`/components/light/monochromatic` -- :doc:`/components/output/index` -- :doc:`/components/output/esp8266_pwm` -- :doc:`/guides/automations` -- :ghedit:`Edit` diff --git a/cookbook/bruh.rst b/cookbook/bruh.rst deleted file mode 100644 index d15e4b05667..00000000000 --- a/cookbook/bruh.rst +++ /dev/null @@ -1,89 +0,0 @@ -BRUH Multisensor -================ - -.. seo:: - :description: Instructions for re-creating a BRUH multisensor using ESPHome. - :image: bruh.png - -The BRUH Multisensor is a great introductory project into Home Automation with an -amazing setup tutorial. And fortunately ESPHome has complete support for all the -stuff used by the Multisensor 🎉 - -.. raw:: html - - - -Thank you very much to `@jackjohnsonuk `__ for providing this -configuration file 😀 - -.. code-block:: yaml - - esphome: - name: - - esp8266: - board: nodemcuv2 - - wifi: - ssid: !secret wifi_ssid - password: !secret wifi_password - - api: - - # Enable logging - logger: - - ota: - - sensor: - - platform: dht - pin: D7 - temperature: - name: "Multisensor Temperature" - humidity: - name: "Multisensor Humidity" - - platform: adc - pin: A0 - name: "Multisensor Brightness" - unit_of_measurement: lux - filters: - - lambda: |- - return (x / 10000.0) * 2000000.0; - - binary_sensor: - - platform: gpio - pin: D5 - name: "Multisensor Motion" - device_class: motion - - output: - - platform: esp8266_pwm - pin: D1 - id: redgpio - - platform: esp8266_pwm - pin: D2 - id: greengpio - - platform: esp8266_pwm - pin: D3 - id: bluegpio - - light: - - platform: rgb - name: "Multisensor Light" - red: redgpio - green: greengpio - blue: bluegpio - - -See Also --------- - -- :doc:`/devices/nodemcu_esp8266` -- :doc:`pir` -- :doc:`temt6000` -- :doc:`/components/light/rgb` -- :doc:`/components/output/esp8266_pwm` -- :doc:`/components/sensor/dht` -- :doc:`/components/sensor/adc` -- :doc:`/components/binary_sensor/gpio` -- :ghedit:`Edit` diff --git a/cookbook/dual-r2-cover.rst b/cookbook/dual-r2-cover.rst deleted file mode 100644 index fa24ccd5823..00000000000 --- a/cookbook/dual-r2-cover.rst +++ /dev/null @@ -1,101 +0,0 @@ -Dual relay cover motor control -============================== - -.. seo:: - :description: An example of how to integrate covers that are controlled by two relays into ESPHome. - :image: sonoff_dual_r2.jpg - :keywords: Relay, Sonoff Dual R2, Cover - -The following is a possible configuration file for common covers that use a motor with 2 inputs. -Only one should be powered at a time (interlocking) to either move the cover up or down. For this -the `Sonoff Dual R2 `__ can be used which has two independent -relays. Additionally this configuration allows the single button on the Sonoff to control the motion -by cycling between: open->stop->close->stop->... - -These kind of motors automatically stop when the end of the cover movement is reached. However, -to be safe, this automation stops powering the motor after 1 minute of movement. In the rare case -of the end-stop switch in the motor failing this will reduce the risk for damage or fire. - -Of the four main components (button sensor, 2 relays switches and the cover), only the cover will be -visible to the end-user. The other three are hidden by means of not including a ``name``. This is to -prevent accidentally switching on both relays simultaneously from Home Assistant as that might be harmful -for some motors. - -.. note:: - - Controlling the cover to quickly (sending new open/close commands within a minute of previous commands) - might cause unexpected behaviour (eg: cover stopping halfway). This is because the delayed relay off - feature is implemented using asynchronous automations. So every time an open/close command is sent a - delayed relay off command is added and old ones are not removed. - -.. code-block:: yaml - - esphome: - name: cover - - esp8266: - board: esp01_1m - - wifi: - ssid: !secret wifi_ssid - password: !secret wifi_password - - api: - - logger: - - ota: - - binary_sensor: - - platform: gpio - pin: - number: GPIO10 - inverted: true - id: button - on_press: - then: - # logic for cycling through movements: open->stop->close->stop->... - - lambda: | - if (id(my_cover).current_operation == COVER_OPERATION_IDLE) { - // Cover is idle, check current state and either open or close cover. - if (id(my_cover).is_fully_closed()) { - id(my_cover).open(); - } else { - id(my_cover).close(); - } - } else { - // Cover is opening/closing. Stop it. - id(my_cover).stop(); - } - - switch: - - platform: gpio - pin: GPIO12 - interlock: &interlock [open_cover, close_cover] - id: open_cover - - platform: gpio - pin: GPIO5 - interlock: *interlock - id: close_cover - - cover: - - platform: time_based - name: "Cover" - id: my_cover - open_action: - - switch.turn_on: open_cover - open_duration: 60s - close_action: - - switch.turn_on: close_cover - close_duration: 60s - stop_action: - - switch.turn_off: open_cover - - switch.turn_off: close_cover - -See Also --------- - -- :doc:`/guides/automations` -- :doc:`/components/cover/time_based` -- :doc:`/devices/sonoff` -- :ghedit:`Edit` diff --git a/cookbook/ehmtx.rst b/cookbook/ehmtx.rst new file mode 100644 index 00000000000..03914d71e34 --- /dev/null +++ b/cookbook/ehmtx.rst @@ -0,0 +1,43 @@ +ehmtx a matrix status display +============================= + +.. seo:: + :description: A simple DIY status display, build with a flexible 8x32 RGB LED panel. + :image: ehmtx.jpg + :keywords: DIY matrix display RGB + +Based on a cheap 8x32 RGB matrix you can build flexible status displays for all kind of informations. It is expandable with sensors etc. + +.. figure:: images/ehmtx.jpg + :align: center + :width: 40% + + +Introduction +------------ + +Based a on a 8x32 RGB flexible matrix it displays a clock, the date and up to 16 other screens provided by home assistant. +Each screen (value/text) can be associated with a 8x8 bit RGB icon or gif animation (see installation). +The values/text can be updated or deleted from the display queue. Each screen has a lifetime, if not refreshed in its lifetime it will disapear. + +ESPHome Configuration +--------------------- +Documentation: + +- `Source for the component on github `__ +- `Discussion in the homeassistant community `__ +- `Second discussion in the homeassistant community `__ +- `Optional notify component `__ + +`YAML configuration example for ESP32 `__. + +Sample video: + +.. raw:: html + + + + +See Also +-------- +- :ghedit:`Edit` diff --git a/cookbook/endstop-cover.rst b/cookbook/endstop-cover.rst deleted file mode 100644 index eafc4c86e4e..00000000000 --- a/cookbook/endstop-cover.rst +++ /dev/null @@ -1,94 +0,0 @@ -Template Cover with Endstops -============================ - -.. seo:: - :description: An example of how to integrate covers with endstops in ESPHome. - :image: window-open.svg - -The following is an example configuration for controlling covers (like window blinds etc) -with ESPHome. This guide assumes that the cover is set up with two endstops at the top -and the bottom. When these endstops are reached, the cover will automatically stop. - -To protect the motors from spinning indefinitely (in case an endstop fails) the motors -also have a maximum run time - after 3 minutes they will automatically turn off even if the -endstop is not reached. - -ESPHome uses Home Assistant's cover architecture model which has two states: "OPEN" or -"CLOSED". We will map OPEN to "cover is at the top endstop" and CLOSE to "cover is at the bottom". - -.. code-block:: yaml - - switch: - # The switch that turns the UP direction on - - platform: gpio - pin: D1 - id: up_pin - # Use interlocking to keep at most one of the two directions on - interlock: &interlock_group [up_pin, down_pin] - # If ESP reboots, do not attempt to restore switch state - restore_mode: always off - - # The switch that turns the DOWN direction on - - platform: gpio - pin: D2 - id: down_pin - interlock: *interlock_group - restore_mode: always off - - - binary_sensor: - - platform: gpio - pin: D4 - id: top_endstop - - platform: gpio - pin: D5 - id: bottom_endstop - - cover: - - platform: endstop - name: "My Endstop Cover" - id: my_cover - open_action: - - switch.turn_on: up_pin - open_duration: 2min - open_endstop: top_endstop - - close_action: - - switch.turn_on: down_pin - close_duration: 2min - close_endstop: bottom_endstop - stop_action: - - switch.turn_off: up_pin - - switch.turn_off: down_pin - max_duration: 3min - -You can then optionally also add manual controls to the cover with three buttons: -open, close, and stop. - -.. code-block:: yaml - - binary_sensor: - # [...] - Previous binary sensors - - platform: gpio - id: open_button - pin: D3 - on_press: - - cover.open: my_cover - - platform: gpio - id: close_button - pin: D6 - on_press: - - cover.close: my_cover - - platform: gpio - id: stop_button - pin: D7 - on_press: - - cover.stop: my_cover - -See Also --------- - -- :doc:`/guides/automations` -- :doc:`/components/cover/template` -- :doc:`dual-r2-cover` -- :ghedit:`Edit` diff --git a/cookbook/esw01-eu.rst b/cookbook/esw01-eu.rst deleted file mode 100644 index c92b364ebe7..00000000000 --- a/cookbook/esw01-eu.rst +++ /dev/null @@ -1,124 +0,0 @@ -Etekcity Voltson (ESW01-EU) -=========================== - -.. seo:: - :description: Configure an Etekcity Voltson and calculate the missing current sensor - :image: esw01-eu.jpg - :keywords: Etekcity, Voltson, ESW01, ESW01-EU, HLW8012, Home Assistant, ESPHome - - -The Etekcity Voltson brings a 10A relay, two LEDs (blue and yellow), a push button and a :doc:`/components/sensor/hlw8012` -in a very small package and at a reasonable price. - -.. note:: - - There are quite a few hardware revisions out there. Also reginal versions like US, UK and EU are different. - -Flashing --------- - -Opening the case for flashing varies a lot for different hardware revisions. Mine was easy as it had two tiny T5 Torx screws in the front and four Philipps screws inside. -Once you have opened the case, remove the PCB from it and attach your TTL as follows: - -5V and GND go to the bottom: - -.. figure:: images/esw01-eu-pcb-bottom.jpg - :align: center - :width: 75.0% - -On the opposite side, T12 is TX, T13 is RX. During boot you need to connect T11 and T16 pads to GND. Easiest is to flash with pogo pins. - -.. figure:: images/esw01-eu-pcb-top.jpg - :align: center - :width: 75.0% - -Configuration -------------- - -As the Voltson has its SEL pin permanently pulled high, we are unable to switch from voltage measurement to current measurement. -This will be circumvented by defining the initial mode to be voltage measurement (see :doc:`/components/sensor/hlw8012` documentation) -and calculating the current with `Ohm's law `_: ``P (watts) = V (volts) x I (amps)`` - -.. code-block:: yaml - - esphome: - name: voltson - - esp8266: - board: esp01_1m - - ### you wifi and other settings here ### - - ### pins ### - # D1 GPIO5 | LED blue | status_led - # D0 GPIO16 | LED yellow | led1 - # D5 GPIO14 | SW1 | button1 - # D2 GPIO4 | REL1 | relay1 - # D6 GPIO12 | HLW8012/CF1 | cf1_pin - # D7 GPIO13 | HLW8012/CF | cf_pin - - status_led: - pin: - number: GPIO5 - - output: - - platform: gpio - id: relay1 - pin: GPIO4 - - platform: gpio - id: led1 - pin: GPIO16 - - switch: - - platform: output - name: "Voltson Relay" - id: switch1 - output: relay1 - on_turn_on: - - output.turn_on: led1 - on_turn_off: - - output.turn_off: led1 - - binary_sensor: - - platform: gpio - id: button1 - pin: - number: GPIO14 - mode: - input: true - pullup: true - inverted: true - on_press: - - switch.toggle: switch1 - - sensor: - - platform: hlw8012 - sel_pin: 0 # not connected - cf_pin: GPIO13 - cf1_pin: GPIO12 - voltage: - id: hlw8012_voltage - name: "HLW8012 Voltage" - power: - id: hlw8012_power - name: "HLW8012 Power" - on_value: - - sensor.template.publish: - id: hlw8012_current_calculated - state: !lambda 'return id(hlw8012_power).state / id(hlw8012_voltage).state;' - update_interval: 10s - initial_mode: VOLTAGE - change_mode_every: 4294967295 # basically never - - platform: template - id: hlw8012_current_calculated - name: "HLW8012 Current (calculated)" - unit_of_measurement: A - accuracy_decimals: 2 - - - -See Also --------- - -- :doc:`/components/sensor/hlw8012` -- :ghedit:`Edit` diff --git a/cookbook/geiger-counter.rst b/cookbook/geiger-counter.rst deleted file mode 100644 index 9e81062c0f8..00000000000 --- a/cookbook/geiger-counter.rst +++ /dev/null @@ -1,80 +0,0 @@ -Geiger counter RadiationD v1.1 (CAJOE) -====================================== - -.. seo:: - :description: Instructions for setting up RadiationD v1.1(CAJOE) sensor in ESPHome and calculate the current radation level. - :image: radiationD-v1-1-cajoe_small.jpg - :keywords: Radiation Geiger counter - -With the help of :doc:`/components/sensor/pulse_counter` and the RadiationD v1.1(CAJOE) you can make your own Geiger counter, which will give you -a more or less precise messurement of the current radation level. But it should be good enough to warn you about critical events. - - -Assembly: ---------- - -.. figure:: images/radiationD-v1-1-cajoe_small.jpg - :align: center - :width: 100.0% - -The first step is to connect the sensor. - -You just need to connect the +5V, the ground and a GPIO pin to the ESP. -In my case I used the pin 34 for the signal. (The print on the PCB is wrong VIN is the signal.) -This setup should give you the pulse of each messurement or count. For more information check the Video of `Andreas Spiess `__. - -Housing: -********* -I just 3D printed an small housing the avoid touching the high voltage Geiger Mueller tube. -`Counter Tube Case `__ -(The tube should not be in direct sunlight. So maybe you will need another case.) - - -Configuration: ---------------- - -The block :doc:`/components/sensor/pulse_counter` will count the radation events per minute. -With the found specs of the tube you will be able to calculate the radiation in μSv/h. - -It's just the counts per minute (CPM) times the factor of your Geiger Mueller tube you're using. It should be the J305ß, which comes with the PCB. -(To make sure - check your printing on the tube) - -μSv/h = (CPM - Tube noise) * Factor -According to the video of `Andreas Spiess `__ the tube should have about 12 CPM as background noise. - -.. note:: - - The current version of the pack comes with the J305ß Geiger tube which detectes Beta and Gamma radiation. Specifications: - Manufacturer: North Optic Radiation Detection: β, γ Length: 111mm Diameter: 11mm Recommended Voltage: 350V Plateau Voltage: 360-440V - Sensitivy γ (60Co): 65cps/(μR/s) - Sensitivy γ (equivalent Sievert): 108cpm / (μSv/h) - Max cpm: 30000 - cps/mR/h: 18 - cpm/m/h: 1080 - cpm/μSv/h: 123.147092360319 - Factor: 0.00812037037037 - - -`Source: opengeiger.de/LibeliumDoku.pdf `__. - - -.. code-block:: yaml - - sensor: - - platform: pulse_counter - pin: 34 - name: "Radiation" - unit_of_measurement: 'μSv/h' - count_mode: - rising_edge: DISABLE - falling_edge: INCREMENT - filters: - - offset: -12.0 # J305ß Geiger Mueller tube background noise 0.2 pulses / sec x 60 sec = 12 CPM (Counts per Minute) - - multiply: 0.00812037037037 # Factor: 0.00812037037037 - - -See Also --------- - -- :doc:`/components/sensor/pulse_counter` -- :ghedit:`Edit` diff --git a/cookbook/h801.rst b/cookbook/h801.rst deleted file mode 100644 index 6021575e3a0..00000000000 --- a/cookbook/h801.rst +++ /dev/null @@ -1,121 +0,0 @@ -H801 RGBW LED controller -======================== - -The H801 is pretty affordable and easy to hack and adapt to your needs. It can be found on `AliExpress `__ -`Here `__ is an article about the -hardware for those who have an interest for more details about the board. -It can be used as a RGB, RGBW, RGB dual white or even control 5 individual monochromatic strips if you want or combinations of these. - -.. figure:: images/h801.jpg - :align: center - :width: 80.0% - -For ESPHome, you can then use the :doc:`RGBW ` -and the :doc:`ESP8266 Software PWM output ` components using below configuration: - -.. code-block:: yaml - - esphome: - name: h801light - - esp8266: - board: esp01_1m - - wifi: - ssid: !secret wifi_ssid - password: !secret wifi_password - - logger: - api: - ota: - - output: - - platform: esp8266_pwm - pin: 12 - frequency: 1000 Hz - id: pwm_b - - platform: esp8266_pwm - pin: 13 - frequency: 1000 Hz - id: pwm_g - - platform: esp8266_pwm - pin: 15 - frequency: 1000 Hz - id: pwm_r - - platform: esp8266_pwm - pin: 14 - frequency: 1000 Hz - id: pwm_w - light: - - platform: rgbw - name: "H801 Light" - red: pwm_r - green: pwm_g - blue: pwm_b - white: pwm_w - - -Make your node in the ESPHome dashboard and compile/upload it. -(if it fails OTA it must be uploaded manually with your favorite ESP flasher, -e.g. :ref:`esphome-flasher `) - -.. figure:: images/gpio.jpg - :align: center - :width: 80.0% - -Front side of board with pins soldered on - -.. figure:: images/back.jpg - :align: center - :width: 80.0% - -Back side of the board (don't melt the blue and red wire when soldering) - -.. figure:: images/rgbwarm.jpg - :align: center - :width: 80.0% - -This LED strip can be used with the sketch as-is - -.. figure:: images/rgbw.jpg - :align: center - :width: 80.0% - -For this type of led strip you have to swap the white and blue GPIO numbers in the sketch. - -You will need to solder pins to the board inside the H801 (fortunately it's pretty roomy and -not a lot of components or stuff in the way apart from the 2 wires on the back). - -3.3V, GND, TX and RX (RX to RX and TX to TX) needs to be connected to your serial adapter, the -two other pins must be shorted throughout the flashing process by a jumper or a breadboard cable. -(Remember to remove it after flashing) - -Add A PIR(Motion) Sensor ------------------------- - -It's possible to use the header that was soldered on for flashing as an input. -The example below uses the TX pin as a PIR motion sensor input: - -.. figure:: images/h801-pir_sensor.jpg - :align: center - :width: 80.0% - -H801 shown with PIR connected to header pins - -The following can be appended to the YAML file for your H801 to configure the TX pin as a motion -sensor input. - -.. code-block:: yaml - - binary_sensor: - - platform: gpio - pin: GPIO3 - name: "GPIO3-TX Motion" - device_class: motion - -See Also --------- - -- :doc:`/components/light/rgbw` -- :doc:`/components/output/esp8266_pwm` -- :ghedit:`Edit` diff --git a/cookbook/iaq_board.rst b/cookbook/iaq_board.rst deleted file mode 100644 index 260866611d4..00000000000 --- a/cookbook/iaq_board.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. seo:: - :description: IAQ (Indoor Air Quality) Board - :image: iaq_board2.jpg - :keywords: IAQ Board - -IAQ (Indoor Air Quality) Board -============================== - -.. figure:: images/iaq_board2.jpg - :align: center - :width: 100.0% - -IAQ Board is a DIY device for measuring internal air quality running with esphome. It's quite small and is based on a custom PCB where part of the components are soldered and connected. - -Here is what it can measure: - -- **Temperature / Humidity / Pressure** -- **Air particles PM1, PM2.5, PM10** -- **Carbon Dioxide with NDIR sensor** -- **Air Quality Index by EPA, based on 24h average PM2.5 particles** -- **Ambient light** -- **Total VOC (volatile organic compound)** -- **equivalent CO2 (not very correct compared with the NDIR sensor, but it's provided by the VOC sensor)** - -On top of that: - -- **At least one OLED display to show the data (can have one more on the top of the MCU board)** -- **three RGB wide angle LEDs with auto brightness. LED1 indicates PM2.5, LED2 - Air quality index, LED3 - CO2.** -- **auto night dimming of the displays and LEDs (can be disabled)** -- **MIN/MAX values of Temperature, PM2.5 and CO2, and 24h average PM2.5 value.** -- **multi function button for selection of the data to show on the display** - -ESPHome Configuration ---------------------- -Full documentation (PCB, Schematic, esphome yaml config) is published here: `https://github.com/nkitanov/iaq_board `__ - -YAML configuration is about 700 lines and can be downloaded from here: `iaq_board.yaml `__ - -.. figure:: images/iaq_board1.jpg - :align: center - :width: 100.0% - -.. raw:: html - - - -See Also --------- - -- :doc:`/devices/nodemcu_esp8266` -- :doc:`/components/display/ssd1306` -- :doc:`/components/sensor/bme280` -- :doc:`/components/sensor/ee895` -- :doc:`/components/sensor/pmsx003` -- :doc:`/components/sensor/mhz19` -- :doc:`/components/sensor/sgp30` -- :doc:`/components/sensor/sgp4x` -- :doc:`/components/sensor/tsl2561` -- :doc:`/components/binary_sensor/gpio` -- :doc:`/components/sensor/template` -- :doc:`/components/light/neopixelbus` -- :doc:`/guides/automations` -- :doc:`/components/i2c` -- :doc:`/components/uart` -- :ghedit:`Edit` diff --git a/cookbook/ifan02.rst b/cookbook/ifan02.rst deleted file mode 100644 index cfa310a9101..00000000000 --- a/cookbook/ifan02.rst +++ /dev/null @@ -1,214 +0,0 @@ -Sonoff iFan02 -============= - -.. seo:: - :description: Instructions for using Sonoff ifan02 in ESPHome. - :keywords: Fan, Sonoff, ifan02 - :image: fan.svg - -Sonoff iFan02 is a driver for ceiling fans with lights. -By replacing the old driver with iFan02, your non-smart led ceiling fan will be converted to a smart ceiling fan. -For more information see `iFan02 `__ - -This configuration will expose a :doc:`/components/light/binary` and a :doc:`/components/fan/speed`. - -To get this working in ESPHome you first need to create a :doc:`/components/output/custom` to control the iFan02. - -Create an ifan02.h file: - -.. code-block:: c++ - - #include "esphome.h" - using namespace esphome; - - class IFan02Output : public Component, public FloatOutput { - public: - void write_state(float state) override { - if (state < 0.3) { - // OFF - digitalWrite(5, LOW); - digitalWrite(4, LOW); - digitalWrite(15, LOW); - } else if (state < 0.6) { - // low speed - digitalWrite(5, HIGH); - digitalWrite(4, LOW); - digitalWrite(15, LOW); - } else if (state < 0.9) { - // medium speed - digitalWrite(5, HIGH); - digitalWrite(4, HIGH); - digitalWrite(15, LOW); - } else { - // high speed - digitalWrite(5, HIGH); - digitalWrite(4, LOW); - digitalWrite(15, HIGH); - } - } - }; - -Then you need to set it up with yaml. - -.. code-block:: yaml - - esphome: - name: ifan02 - includes: - - ifan02.h - on_boot: - priority: 225 - # turn off the light as early as possible - then: - - light.turn_off: ifan02_light - - esp8266: - board: esp8285 - - wifi: - ssid: !secret wifi_ssid - password: !secret wifi_password - - api: - - logger: - - ota: - - binary_sensor: - - platform: gpio - id: vbutton_light - pin: - number: GPIO0 - inverted: true - on_press: - then: - - light.toggle: ifan02_light - - - platform: gpio - id: vbutton_relay_1 - pin: - number: GPIO9 - inverted: true - on_press: - then: - - switch.toggle: fan_relay1 - - switch.turn_on: update_fan_speed - - - platform: gpio - id: vbutton_relay_2 - pin: - number: GPIO10 - inverted: true - on_press: - then: - - switch.toggle: fan_relay2 - - switch.turn_on: update_fan_speed - - - platform: gpio - id: vbutton_relay_3 - pin: - number: GPIO14 - inverted: true - on_press: - then: - - switch.toggle: fan_relay3 - - switch.turn_on: update_fan_speed - - output: - - platform: custom - type: float - outputs: - id: fanoutput - lambda: |- - auto ifan02_fan = new IFan02Output(); - App.register_component(ifan02_fan); - return {ifan02_fan}; - - - platform: gpio - pin: GPIO12 - id: light_output - - light: - - platform: binary - name: "iFan02 Light" - output: light_output - id: ifan02_light - - switch: - - platform: template - id: update_fan_speed - optimistic: true - turn_on_action: - then: - - delay: 200ms - - if: - condition: - and: - - switch.is_off: fan_relay1 - - switch.is_off: fan_relay2 - - switch.is_off: fan_relay3 - then: - - fan.turn_off: ifan02_fan - - if: - condition: - and: - - switch.is_on: fan_relay1 - - switch.is_off: fan_relay2 - - switch.is_off: fan_relay3 - then: - - fan.turn_on: - id: ifan02_fan - speed: 1 - - if: - condition: - and: - - switch.is_on: fan_relay1 - - switch.is_on: fan_relay2 - - switch.is_off: fan_relay3 - then: - - fan.turn_on: - id: ifan02_fan - speed: 2 - - if: - condition: - and: - - switch.is_on: fan_relay1 - - switch.is_off: fan_relay2 - - switch.is_on: fan_relay3 - then: - - fan.turn_on: - id: ifan02_fan - speed: 3 - - switch.turn_off: update_fan_speed - - - platform: gpio - pin: GPIO5 - id: fan_relay1 - - - platform: gpio - pin: GPIO4 - id: fan_relay2 - - - platform: gpio - pin: GPIO15 - id: fan_relay3 - - fan: - - platform: speed - output: fanoutput - id: ifan02_fan - speed_count: 3 - name: "iFan02 Fan" - -See Also --------- - -- :doc:`/components/light/index` -- :doc:`/components/light/binary` -- :doc:`/components/fan/index` -- :doc:`/components/fan/speed` -- :doc:`/components/output/index` -- :doc:`/components/output/custom` -- :doc:`/guides/automations` -- :ghedit:`Edit` diff --git a/cookbook/ilonda-wifi-smart-fish-feeder.rst b/cookbook/ilonda-wifi-smart-fish-feeder.rst deleted file mode 100644 index 55a5bbe9bb8..00000000000 --- a/cookbook/ilonda-wifi-smart-fish-feeder.rst +++ /dev/null @@ -1,105 +0,0 @@ -Ilonda Wifi Smart Fish Feeder (L88) -=================================== - -Ilonda Wifi Smart Fish Feeder (L88) is a Tuya-based device sold by Amazon (not only under Ilonda, but also under other brand names). - -.. figure:: images/ilonda-wifi-smart-fish-feeder.jpg - :align: center - :width: 50.0% - -Originally intended to be used with its companion app, once flashed using `tuya-convert `__, ESPHome generated -firmware can be uploaded allowing you to control the Wifi Smart Fish Feeder via Home Assistant. - -Wifi Smart Fish Feeder Configuration ------------------------------------- - -Thanks to the amazing `Tasmota template `__, -managed to build a fully working esphome configuration. This assumes you have a secret.yaml with ssid and password keys. - -.. code-block:: yaml - - esphome: - name: wifi_smart_fish_feeder - - esp8266: - board: esp01_1m - - wifi: - ssid: !secret wifi_ssid - password: !secret wifi_password - - logger: - - api: - - ota: - - # Binary Sensor to allow relay to be switched when physical button is pressed - binary_sensor: - - platform: gpio - id: button - pin: - number: GPIO4 - mode: - input: true - pullup: true - inverted: True - name: 'Switch feeder' - on_press: - - switch.turn_on: relay - - - platform: status - name: "Status" - - switch: - # Switch to turn feeder on for 3 seconds/off and turn on/off LED - - platform: gpio - name: 'Relay feeder' - id: relay - pin: GPIO14 - on_turn_on: - - light.turn_on: led - - delay: 3s - - switch.turn_off: relay - - light.turn_off: led - restore_mode: ALWAYS_OFF - - sensor: - # Feeder counter - - platform: pulse_meter - pin: GPIO12 - name: 'Counter/min' - unit_of_measurement: 'time(s)' - internal: true - total: - unit_of_measurement: 'time(s)' - name: 'Counter feeder' - - # To allow led to be controlled via GPIO - output: - - platform: esp8266_pwm - id: blue_led - pin: - number: GPIO5 - inverted: true - - # LED control - light: - - platform: monochromatic - output: blue_led - id: led - - -You can now add your Wifi Smart Fish Feeder to Home Assistant via the configurations page, look for 'ESPHome' under the Integrations option and click 'Configure'. - -See Also --------- - -- :doc:`/components/binary_sensor/gpio` -- :doc:`/components/switch/gpio` -- :doc:`/components/sensor/pulse_meter` -- :doc:`/components/output/esp8266_pwm` -- :doc:`/components/light/monochromatic` -- :doc:`/guides/automations` -- `Fish Feeder diagrams and pictures `__. -- :ghedit:`Edit` diff --git a/cookbook/images/air_gradient_diy_air_quality_sensor.jpg b/cookbook/images/air_gradient_diy_air_quality_sensor.jpg deleted file mode 100644 index 069aac132f2..00000000000 Binary files a/cookbook/images/air_gradient_diy_air_quality_sensor.jpg and /dev/null differ diff --git a/cookbook/images/back.jpg b/cookbook/images/back.jpg deleted file mode 100644 index b69e310b8b1..00000000000 Binary files a/cookbook/images/back.jpg and /dev/null differ diff --git a/cookbook/images/brilliant-mirabella-genio-smart-plugs-homeassistant.jpg b/cookbook/images/brilliant-mirabella-genio-smart-plugs-homeassistant.jpg deleted file mode 100644 index d8c4e891866..00000000000 Binary files a/cookbook/images/brilliant-mirabella-genio-smart-plugs-homeassistant.jpg and /dev/null differ diff --git a/cookbook/images/brilliant-mirabella-genio-smart-plugs.jpg b/cookbook/images/brilliant-mirabella-genio-smart-plugs.jpg deleted file mode 100644 index 1e32b4daeb6..00000000000 Binary files a/cookbook/images/brilliant-mirabella-genio-smart-plugs.jpg and /dev/null differ diff --git a/cookbook/images/ehmtx.jpg b/cookbook/images/ehmtx.jpg new file mode 100644 index 00000000000..f1ec551cbed Binary files /dev/null and b/cookbook/images/ehmtx.jpg differ diff --git a/cookbook/images/esw01-eu-pcb-bottom.jpg b/cookbook/images/esw01-eu-pcb-bottom.jpg deleted file mode 100644 index 106a64d2030..00000000000 Binary files a/cookbook/images/esw01-eu-pcb-bottom.jpg and /dev/null differ diff --git a/cookbook/images/esw01-eu-pcb-top.jpg b/cookbook/images/esw01-eu-pcb-top.jpg deleted file mode 100644 index 29e6d5f0c2d..00000000000 Binary files a/cookbook/images/esw01-eu-pcb-top.jpg and /dev/null differ diff --git a/cookbook/images/esw01-eu.jpg b/cookbook/images/esw01-eu.jpg deleted file mode 100644 index 4adda23acc3..00000000000 Binary files a/cookbook/images/esw01-eu.jpg and /dev/null differ diff --git a/cookbook/images/gpio.jpg b/cookbook/images/gpio.jpg deleted file mode 100644 index 3524ff2d341..00000000000 Binary files a/cookbook/images/gpio.jpg and /dev/null differ diff --git a/cookbook/images/h801-header.jpg b/cookbook/images/h801-header.jpg deleted file mode 100644 index 4a4dd51864b..00000000000 Binary files a/cookbook/images/h801-header.jpg and /dev/null differ diff --git a/cookbook/images/h801-pir_sensor.jpg b/cookbook/images/h801-pir_sensor.jpg deleted file mode 100644 index 8029a374848..00000000000 Binary files a/cookbook/images/h801-pir_sensor.jpg and /dev/null differ diff --git a/cookbook/images/h801.jpg b/cookbook/images/h801.jpg deleted file mode 100644 index 979091f3fe8..00000000000 Binary files a/cookbook/images/h801.jpg and /dev/null differ diff --git a/cookbook/images/iaq_board1.jpg b/cookbook/images/iaq_board1.jpg deleted file mode 100644 index e87781af008..00000000000 Binary files a/cookbook/images/iaq_board1.jpg and /dev/null differ diff --git a/cookbook/images/iaq_board2.jpg b/cookbook/images/iaq_board2.jpg deleted file mode 100644 index 61cf79a5bef..00000000000 Binary files a/cookbook/images/iaq_board2.jpg and /dev/null differ diff --git a/cookbook/images/ilonda-wifi-smart-fish-feeder-cookbook.jpg b/cookbook/images/ilonda-wifi-smart-fish-feeder-cookbook.jpg deleted file mode 100644 index 8432769609c..00000000000 Binary files a/cookbook/images/ilonda-wifi-smart-fish-feeder-cookbook.jpg and /dev/null differ diff --git a/cookbook/images/ilonda-wifi-smart-fish-feeder.jpg b/cookbook/images/ilonda-wifi-smart-fish-feeder.jpg deleted file mode 100644 index cc648d1c6e1..00000000000 Binary files a/cookbook/images/ilonda-wifi-smart-fish-feeder.jpg and /dev/null differ diff --git a/cookbook/images/iwoole_rgbw_table_lamp.png b/cookbook/images/iwoole_rgbw_table_lamp.png deleted file mode 100644 index f560c9e9f4f..00000000000 Binary files a/cookbook/images/iwoole_rgbw_table_lamp.png and /dev/null differ diff --git a/cookbook/images/iwoole_rgbw_table_lamp_connections_bottom.jpg b/cookbook/images/iwoole_rgbw_table_lamp_connections_bottom.jpg deleted file mode 100644 index e7294a681a0..00000000000 Binary files a/cookbook/images/iwoole_rgbw_table_lamp_connections_bottom.jpg and /dev/null differ diff --git a/cookbook/images/iwoole_rgbw_table_lamp_connections_top.jpg b/cookbook/images/iwoole_rgbw_table_lamp_connections_top.jpg deleted file mode 100644 index 03cf17fe331..00000000000 Binary files a/cookbook/images/iwoole_rgbw_table_lamp_connections_top.jpg and /dev/null differ diff --git a/cookbook/images/iwoole_rgbw_table_lamp_internal_1.jpg b/cookbook/images/iwoole_rgbw_table_lamp_internal_1.jpg deleted file mode 100644 index 4cf5296dc3f..00000000000 Binary files a/cookbook/images/iwoole_rgbw_table_lamp_internal_1.jpg and /dev/null differ diff --git a/cookbook/images/iwoole_rgbw_table_lamp_internal_2.jpg b/cookbook/images/iwoole_rgbw_table_lamp_internal_2.jpg deleted file mode 100644 index 67833244859..00000000000 Binary files a/cookbook/images/iwoole_rgbw_table_lamp_internal_2.jpg and /dev/null differ diff --git a/cookbook/images/iwoole_rgbw_table_lamp_internal_3.jpg b/cookbook/images/iwoole_rgbw_table_lamp_internal_3.jpg deleted file mode 100644 index eb5e107dd15..00000000000 Binary files a/cookbook/images/iwoole_rgbw_table_lamp_internal_3.jpg and /dev/null differ diff --git a/cookbook/images/iwoole_rgbw_table_lamp_wires_bottom.jpg b/cookbook/images/iwoole_rgbw_table_lamp_wires_bottom.jpg deleted file mode 100644 index 4fcfe4857b7..00000000000 Binary files a/cookbook/images/iwoole_rgbw_table_lamp_wires_bottom.jpg and /dev/null differ diff --git a/cookbook/images/iwoole_rgbw_table_lamp_wires_top.jpg b/cookbook/images/iwoole_rgbw_table_lamp_wires_top.jpg deleted file mode 100644 index 982c0ce7006..00000000000 Binary files a/cookbook/images/iwoole_rgbw_table_lamp_wires_top.jpg and /dev/null differ diff --git a/cookbook/images/mirabella-genio-b22-rgbw-homeassistant.jpg b/cookbook/images/mirabella-genio-b22-rgbw-homeassistant.jpg deleted file mode 100644 index 7ba9f7441d4..00000000000 Binary files a/cookbook/images/mirabella-genio-b22-rgbw-homeassistant.jpg and /dev/null differ diff --git a/cookbook/images/mirabella-genio-b22-rgbw.jpg b/cookbook/images/mirabella-genio-b22-rgbw.jpg deleted file mode 100644 index ed6a16d3df8..00000000000 Binary files a/cookbook/images/mirabella-genio-b22-rgbw.jpg and /dev/null differ diff --git a/cookbook/images/pir-header.jpg b/cookbook/images/pir-header.jpg deleted file mode 100644 index 160c370a0f3..00000000000 Binary files a/cookbook/images/pir-header.jpg and /dev/null differ diff --git a/cookbook/images/pir-inside.jpg b/cookbook/images/pir-inside.jpg deleted file mode 100644 index 8091d3601fb..00000000000 Binary files a/cookbook/images/pir-inside.jpg and /dev/null differ diff --git a/cookbook/images/pir-pins.jpg b/cookbook/images/pir-pins.jpg deleted file mode 100644 index 52d2ebb8efb..00000000000 Binary files a/cookbook/images/pir-pins.jpg and /dev/null differ diff --git a/cookbook/images/pir-ui.png b/cookbook/images/pir-ui.png deleted file mode 100644 index 2d7d189b555..00000000000 Binary files a/cookbook/images/pir-ui.png and /dev/null differ diff --git a/cookbook/images/radiationD-v1-1-cajoe_small.jpg b/cookbook/images/radiationD-v1-1-cajoe_small.jpg deleted file mode 100644 index ee6325bc71d..00000000000 Binary files a/cookbook/images/radiationD-v1-1-cajoe_small.jpg and /dev/null differ diff --git a/cookbook/images/relay-full.jpg b/cookbook/images/relay-full.jpg deleted file mode 100644 index 029dc7784cf..00000000000 Binary files a/cookbook/images/relay-full.jpg and /dev/null differ diff --git a/cookbook/images/rgbw.jpg b/cookbook/images/rgbw.jpg deleted file mode 100644 index 1134363b54f..00000000000 Binary files a/cookbook/images/rgbw.jpg and /dev/null differ diff --git a/cookbook/images/rgbwarm.jpg b/cookbook/images/rgbwarm.jpg deleted file mode 100644 index 90c800d1b69..00000000000 Binary files a/cookbook/images/rgbwarm.jpg and /dev/null differ diff --git a/cookbook/images/teckin_sb50.jpg b/cookbook/images/teckin_sb50.jpg deleted file mode 100644 index 580b6c72657..00000000000 Binary files a/cookbook/images/teckin_sb50.jpg and /dev/null differ diff --git a/cookbook/images/temt6000-header.jpg b/cookbook/images/temt6000-header.jpg deleted file mode 100644 index bb3a83d35ec..00000000000 Binary files a/cookbook/images/temt6000-header.jpg and /dev/null differ diff --git a/cookbook/images/temt6000-pins.jpg b/cookbook/images/temt6000-pins.jpg deleted file mode 100644 index 54c6a4a1884..00000000000 Binary files a/cookbook/images/temt6000-pins.jpg and /dev/null differ diff --git a/cookbook/images/tracer-an.jpg b/cookbook/images/tracer-an.jpg deleted file mode 100644 index 41f95959ca0..00000000000 Binary files a/cookbook/images/tracer-an.jpg and /dev/null differ diff --git a/cookbook/images/tuya_rgbw.jpg b/cookbook/images/tuya_rgbw.jpg deleted file mode 100644 index f9c02948959..00000000000 Binary files a/cookbook/images/tuya_rgbw.jpg and /dev/null differ diff --git a/cookbook/images/zemismart-rgbw-downlight-homeassistant.jpg b/cookbook/images/zemismart-rgbw-downlight-homeassistant.jpg deleted file mode 100644 index c8f1ab0ad57..00000000000 Binary files a/cookbook/images/zemismart-rgbw-downlight-homeassistant.jpg and /dev/null differ diff --git a/cookbook/images/zemismart-rgbw-downlight.jpg b/cookbook/images/zemismart-rgbw-downlight.jpg deleted file mode 100644 index 0d01461749d..00000000000 Binary files a/cookbook/images/zemismart-rgbw-downlight.jpg and /dev/null differ diff --git a/cookbook/iwoole_rgbw_table_lamp.rst b/cookbook/iwoole_rgbw_table_lamp.rst deleted file mode 100644 index bae99a99443..00000000000 --- a/cookbook/iwoole_rgbw_table_lamp.rst +++ /dev/null @@ -1,141 +0,0 @@ -IWOOLE Table Lamp -=================================== - -.. seo:: - :description: Instructions for flashing and configuring IWOOLE Table Lamps. - -The IWOOLE Table Lamp is a RGBW lamp normally configured using the Tuya Smart App. -It is available from various retailers online or directly from `iwoole.com `__. - -.. figure:: images/iwoole_rgbw_table_lamp.png - :align: center - :width: 50.0% - -1. Device overview -================== -.. note:: - - The following information relates to the desk model depicted above. A free-standing version and a desk version with a longer arm are available. They are likely to share the same internals and configuration, but I can not be certain. - -My device had no external markings at all. - -The device is a basic 4-channel PWM RGBW light in a simple elegant housing. -The LEDs are not individually addressable. -No other sensors, outputs or status LEDs are available. - -The MOSFETs for the different color channels are connected as follows: - -- GPIO04: White -- GPIO12: Green -- GPIO13: Blue -- GPIO14: Red - -1.1 Internal markings ----------------------- -.. figure:: images/iwoole_rgbw_table_lamp_internal_1.jpg - :align: center - :width: 40.0% - -.. figure:: images/iwoole_rgbw_table_lamp_internal_2.jpg - :align: center - :width: 40.0% - -.. figure:: images/iwoole_rgbw_table_lamp_internal_3.jpg - :align: center - :width: 40.0% - -2. ESPHome configuration -======================== -Since there is only one RGBW light to configure the .yaml file is fairly straightforward. -Alternatively, you could configure each channel as a separate light if desired. -I prefer to use the :ref:`color-interlock ` option along with the configuration below. - -2.1 Example configuration -------------------------- -.. code-block:: yaml - - esphome: - name: "IWOOLE Table Lamp" - #ESP type is ESP8266EX with 1MB flash - - esp8266: - board: esp01_1m - - # Insert wifi and api configuration here - - # Configuration for IWOOLE PWM light - light: - - platform: rgbw - name: "Light" - red: output_red - green: output_green - blue: output_blue - white: output_white - - output: - - platform: esp8266_pwm - id: output_red - pin: GPIO14 - - platform: esp8266_pwm - id: output_green - pin: GPIO12 - - platform: esp8266_pwm - id: output_blue - pin: GPIO13 - - platform: esp8266_pwm - id: output_white - pin: GPIO4 - -3. Flashing -=========== - -.. warning:: - - The circuit inside will be exposed to mains voltage. Do not connect your device to the mains when flashing. Flashing this device via a serial connection will involve precarious soldering and cutting through insulating heat-shrink tubing which will have to be replaced. - If you are uncomfortable with this, or are not confident around mains voltage, do not attempt to do this! Using the Tuya-convert method is preferred. - -1. Disconnect the device from mains voltage! -2. Open the device. The plastic and aluminum halves can be separated by twisting the plastic part counter-clockwise. If you're okay with a few scuffs you can also use a screwdriver (or a spudger) to separate the two halves. -3. Remove the two screws holding the round plate with the LEDs. It is connected to the main PCB with a little cable. Make note of the orientation of this connection to ensure you reconnect it correctly later. -4. Carefully remove the heat-shrink tubing around the two main PCBs. -5. Like any ESP device, to flash this chip using serial you'll need 3V3, GND, RX, TX and GPIO0 - -.. figure:: images/iwoole_rgbw_table_lamp_connections_top.jpg - :align: left - :width: 60.0% - -There are pads available for 3V3 and GPIO0 on the back. I have tried to find easier solder points on the front, marked in the image above. -Be aware that the pin labeled VCC does not carry 3V3, but 24V DC. If, for any reason, you wanted to connect any other sensor or component, the exposed pin for GPIO5 can be used, in addition to RX (GPIO3) and TX (GPIO1). - -.. figure:: images/iwoole_rgbw_table_lamp_connections_bottom.jpg - :align: left - :width: 60.0% - -I have made the following connections, I used the pad for GPIO0 because I did not know of the other connection point yet. - -.. figure:: images/iwoole_rgbw_table_lamp_wires_top.jpg - :align: left - :width: 60.0% - -.. figure:: images/iwoole_rgbw_table_lamp_wires_bottom.jpg - :align: left - :width: 60.0% - -6. Flash the chip as you would with any other, using `ESPHome-Flasher `__ or any other tool of your choosing. While this is not meant as a tutorial on flashing ESP chips, some general hints: - -- Always double-check your connections, and don't change any when the ESP is powered. I fried one of these mood lights this way. -- Ensure GPIO0 is connected to ground to get the device into programming mode, but also don't forget to disconnect this when you expect the device to start in normal mode. -- When working with a breadboard, an FTDI adapter and jumper wires, it is very easy for something to become disconnected. Try to use as few wires as possible. - -7. Re-apply some heat-shrink tubing or cover the PCBs in electrical tape. Make sure none of the traces or solder joints are exposed anymore. Re-connect the LEDs (see cable orientation in one of the images above). - -8. Screw down the plate with LEDs and close the device. - -See Also -======== - -- :doc:`/components/light/index` -- :doc:`/components/light/rgbw` -- :doc:`/components/output/index` -- :doc:`/components/output/esp8266_pwm` -- :ghedit:`Edit` diff --git a/cookbook/lambda_magic.rst b/cookbook/lambda_magic.rst new file mode 100644 index 00000000000..c3bb42e7e26 --- /dev/null +++ b/cookbook/lambda_magic.rst @@ -0,0 +1,374 @@ +Lambda Magic +============ + +.. seo:: + :description: Recipes for various interesting things you can do with Lambdas in ESPHome + :image: language-cpp.svg + +Here are a couple recipes for various interesting things you can do with :ref:`Lambdas ` in ESPHome. +These things don't need external or custom components, and show how powerful :ref:`Lambda ` usage can be. + +.. _lambda_magic_pages: + +Display pages alternative +------------------------- + +Some displays like :ref:`lcd-pcf8574` don't support pages natively, but you can easily implement them +using Lambdas: + +.. code-block:: yaml + + display: + - platform: lcd_pcf8574 + dimensions: 20x4 + address: 0x27 + id: lcd + lambda: |- + switch (id(page)){ + case 1: + it.print(0, 1, "Page1"); + break; + case 2: + it.print(0, 1, "Page2"); + break; + case 3: + it.print(0, 1, "Page3"); + break; + } + + globals: + - id: page + type: int + initial_value: "1" + + interval: + - interval: 5s + then: + - lambda: |- + id(page) = (id(page) + 1); + if (id(page) > 3) { + id(page) = 1; + } + + +.. _lambda_magic_udp_sender: + +Send UDP commands +----------------- + +There are various network devices which can be commanded with UDP packets containing command strings. +You can send such UDP commands from ESPHome using a Lambda in a script. + +.. code-block:: yaml + + script: + - id: send_udp + parameters: + msg: string + host: string + port: int + then: + - lambda: |- + int sock = ::socket(AF_INET, SOCK_DGRAM, 0); + struct sockaddr_in destination, source; + + destination.sin_family = AF_INET; + destination.sin_port = htons(port); + destination.sin_addr.s_addr = inet_addr(host.c_str()); + + // you can remove the next 4 lines if you don't want to set the source port for outgoing packets + source.sin_family = AF_INET; + source.sin_addr.s_addr = htonl(INADDR_ANY); + source.sin_port = htons(64998); // the source port number + bind(sock, (struct sockaddr*)&source, sizeof(source)); + + int n_bytes = ::sendto(sock, msg.c_str(), msg.length(), 0, reinterpret_cast(&destination), sizeof(destination)); + ESP_LOGD("lambda", "Sent %s to %s:%d in %d bytes", msg.c_str(), host.c_str(), port, n_bytes); + ::close(sock); + + button: + - platform: template + id: button_udp_sender + name: "Send UDP Command" + on_press: + - script.execute: + id: send_udp + msg: "Hello World!" + host: "192.168.1.10" + port: 5000 + +Tested on both `arduino` and `esp-idf` platforms. + +.. _lambda_magic_uart_text_sensor: + +Custom UART Text Sensor +----------------------- + +Lots of devices communicate using the UART protocol. If you want to read +lines from uart to a Text Sensor you can do so using this code example. + +With this you can use automations or lambda to set switch or sensor states. + +.. code-block:: cpp + + #include "esphome.h" + + class UartReadLineSensor : public Component, public UARTDevice, public TextSensor { + public: + UartReadLineSensor(UARTComponent *parent) : UARTDevice(parent) {} + + void setup() override { + // nothing to do here + } + + int readline(int readch, char *buffer, int len) + { + static int pos = 0; + int rpos; + + if (readch > 0) { + switch (readch) { + case '\n': // Ignore new-lines + break; + case '\r': // Return on CR + rpos = pos; + pos = 0; // Reset position index ready for next time + return rpos; + default: + if (pos < len-1) { + buffer[pos++] = readch; + buffer[pos] = 0; + } + } + } + // No end of line has been found, so return -1. + return -1; + } + + void loop() override { + const int max_line_length = 80; + static char buffer[max_line_length]; + while (available()) { + if(readline(read(), buffer, max_line_length) > 0) { + publish_state(buffer); + } + } + } + }; + +(Store this file in your configuration directory, for example ``uart_read_line_sensor.h``) + +And in YAML: + +.. code-block:: yaml + + # Example configuration entry + esphome: + includes: + - uart_read_line_sensor.h + + logger: + level: VERBOSE #makes uart stream available in esphome logstream + baud_rate: 0 #disable logging over uart + + uart: + id: uart_bus + tx_pin: D0 + rx_pin: D1 + baud_rate: 9600 + + text_sensor: + - platform: custom + lambda: |- + auto my_custom_sensor = new UartReadLineSensor(id(uart_bus)); + App.register_component(my_custom_sensor); + return {my_custom_sensor}; + text_sensors: + id: "uart_readline" + +For more details see :doc:`/custom/uart` and :doc:`/components/uart`. + +.. _lambda_magic_uart_switch: + +Custom UART Switch +------------------ + +Here is an example switch using the uart text sensor above to set switch state. + +Here we use interval to request status from the device. The response will be stored in uart text sensor. +Then the switch uses the text sensor state to publish its own state. + +.. code-block:: yaml + + switch: + - platform: template + name: "Switch" + lambda: |- + if (id(uart_readline).state == "*POW=ON#") { + return true; + } else if(id(uart_readline).state == "*POW=OFF#") { + return false; + } else { + return {}; + } + turn_on_action: + - uart.write: "\r*pow=on#\r" + turn_off_action: + - uart.write: "\r*pow=off#\r" + + interval: + - interval: 10s + then: + - uart.write: "\r*pow=?#\r" + +.. _lambda_magic_rf_queues: + +Delaying Remote Transmissions +----------------------------- + +The solution below handles the problem of RF frames being sent out by :doc:`/components/rf_bridge` (or +:doc:`/components/remote_transmitter`) too quickly one after another when operating radio controlled +covers. The cover motors seem to need at least 600-700ms of silence between the individual code transmissions +to be able to recognize them. + +This can be solved by building up a queue of raw RF codes and sending them out one after the other with +(a configurable) delay between them. Delay is only added to the next commands coming from a list of +covers which have to be operated at once from Home Assistant. This is transparent to the system, which +will still look like they operate simultaneously. + +.. code-block:: yaml + + rf_bridge: + + number: + - platform: template + name: Delay commands + icon: mdi:clock-fast + entity_category: config + optimistic: true + restore_value: true + initial_value: 750 + unit_of_measurement: "ms" + id: queue_delay + min_value: 10 + max_value: 1000 + step: 50 + mode: box + + globals: + - id: rf_code_queue + type: 'std::vector' + + script: + - id: rf_transmitter_queue + mode: single + then: + while: + condition: + lambda: 'return !id(rf_code_queue).empty();' + then: + - rf_bridge.send_raw: + raw: !lambda |- + std::string rf_code = id(rf_code_queue).front(); + id(rf_code_queue).erase(id(rf_code_queue).begin()); + return rf_code; + - delay: !lambda 'return id(queue_delay).state;' + + cover: + # have multiple covers + - platform: time_based + name: 'My Room 1' + disabled_by_default: false + device_class: shutter + assumed_state: true + has_built_in_endstop: true + + close_action: + - lambda: id(rf_code_queue).push_back("AAB0XXXXX..the.closing.code..XXXXXXXXXX"); + - script.execute: rf_transmitter_queue + close_duration: 26s + + stop_action: + - lambda: id(rf_code_queue).push_back("AAB0YXXXX..the.stopping.code..XXXXXXXXXX"); + - script.execute: rf_transmitter_queue + + open_action: + - lambda: id(rf_code_queue).push_back("AAB0ZXXXX..the.opening.code..XXXXXXXXXX"); + - script.execute: rf_transmitter_queue + open_duration: 27s + +.. _lambda_magic_1button_coover: + +One Button Cover Control +------------------------ + +The configuration below shows how with a single button you can control the motion of a motorized cover +by cycling between: open->stop->close->stop->... + +In this example a :doc:`/components/cover/time_based` is used with the GPIO configuration of a Sonoff Dual R2. + +.. note:: + + Controlling the cover to quickly (sending new open/close commands within a minute of previous commands) + might cause unexpected behaviour (eg: cover stopping halfway). This is because the delayed relay off + feature is implemented using asynchronous automations. So every time an open/close command is sent a + delayed relay off command is added and old ones are not removed. + +.. code-block:: yaml + + esp8266: + board: esp01_1m + + binary_sensor: + - platform: gpio + pin: + number: GPIO10 + inverted: true + id: button + on_press: + then: + # logic for cycling through movements: open->stop->close->stop->... + - lambda: | + if (id(my_cover).current_operation == COVER_OPERATION_IDLE) { + // Cover is idle, check current state and either open or close cover. + if (id(my_cover).is_fully_closed()) { + id(my_cover).open(); + } else { + id(my_cover).close(); + } + } else { + // Cover is opening/closing. Stop it. + id(my_cover).stop(); + } + + switch: + - platform: gpio + pin: GPIO12 + interlock: &interlock [open_cover, close_cover] + id: open_cover + - platform: gpio + pin: GPIO5 + interlock: *interlock + id: close_cover + + cover: + - platform: time_based + name: "Cover" + id: my_cover + open_action: + - switch.turn_on: open_cover + open_duration: 60s + close_action: + - switch.turn_on: close_cover + close_duration: 60s + stop_action: + - switch.turn_off: open_cover + - switch.turn_off: close_cover + +See Also +-------- + +- :ref:`config-lambda` +- :ref:`automation` + +- :ghedit:`Edit` diff --git a/cookbook/mirabella-genio-bulb.rst b/cookbook/mirabella-genio-bulb.rst deleted file mode 100644 index aca96b8d033..00000000000 --- a/cookbook/mirabella-genio-bulb.rst +++ /dev/null @@ -1,309 +0,0 @@ -Mirabella Genio Bulbs -===================== - -The Mirabella Genio is a Tuya-based smart bulb sold by Kmart in Australia. - -.. figure:: images/mirabella-genio-b22-rgbw.jpg - :align: center - :width: 50.0% - -Originally intended to be used with their companion app once flashed using `tuya-convert `__ ESPHome generated -firmware can be uploaded allowing you to control the bulbs via Home Assistant. - -.. note:: - - Please note that the new version of this bulb that comes in a cardboard box are using the TYLC5 module which does not work via tuya-convert. - These bulbs are also using the SM2135 chipset and not PWM anymore. - -1. Create the ESPHome Firmware ------------------------------- - -#. Refer to either :doc:`/guides/getting_started_command_line` or :doc:`/guides/getting_started_hassio` before moving onto the next step. -#. Select a bulb configuration below based on the bulb/s you have and copy all of the text in the code block and paste into your - ``name_of_esphome_configuration.yaml`` file. -#. Compile the firmware, again depending on your chosen setup refer to the guides in the first point. - -2. Flashing ------------ - -2.1 Prerequisites -***************** - -#. Before you begin you'll need one of the following Linux machines running the latest copy of `Raspbian Stretch Lite - `__ - - a. Raspberry Pi 2B/B+ with `USB WiFi Dongle `__. - b. Raspberry Pi 3B/B+. - -.. note:: - - As per the `tuya-convert documentation `__: - - Any Linux with a Wifi adapter which can act as an Access Point should also work. Please note that we have tested the Raspberry Pi with clean installations - only. If you use your Raspberry Pi for anything else, we recommend using another SD card with a clean installation. - -#. A microSD card (minimum 2GB, 8GB+ recommended). -#. Any WiFi device which can connect to the SSID generated by the Raspberry Pi and eventually the flashed Tuya device. **This cannot be an iOS / Apple device. - Android devices will work.** - -2.2 Installing the OS -********************* - -#. It's recommended to read the documentation provided by the Raspberry Pi Foundation on the best way to flash the OS to the microSD card depending on your - platform - `Installing operating system images `__. -#. After you've flashed the microSD card browse to the "boot" partition and add a blank file called "ssh" **(without any extension)** which will enable the - SSH server upon first boot, extended information on this step can be found `here - `__. -#. Plug the microSD card into the Raspberry Pi, connect network cable and power, the Raspberry Pi will start to boot. - -2.3 Connecting to the Pi via SSH -******************************** - -#. Download and install `Putty `__. -#. Open Putty. -#. Enter the IP of Raspberry Pi in the box that says "Host Name", leaving the port set to 22 (default for SSH). A list of recommended ways can be found `here - `__, but the easiest is to download and use `Fing `__ - (`Android `__ / `iOS - `__). -#. In the "Saved Sessions" input box, name the Raspberry Pi connection and then press "Save". -#. Select your new saved session from the list. -#. Press "Open". - -2.4 Configuring the Pi -********************** - -#. In the putty window login with the **pi** as the user and **raspberry** for the password. -#. Type ``sudo apt-get update && sudo apt-get dist-upgrade -y`` and wait for the upgrades to install. -#. Type ``sudo apt-get install git`` and wait for it to install. - -2.5 Setup and Install tuya-convert -********************************** - -#. In the putty window type ``git clone https://github.com/ct-Open-Source/tuya-convert`` press enter and wait while the repository is cloned. -#. Type ``cd tuya-convert`` and press enter. -#. Type ``./install_prereq.sh`` press enter and wait as the script gathers all the required components needed to function. - -2.6 Upload ESPHome Firmware using SFTP -************************************** - -#. Download `FileZilla `__ or `WinSCP `__ or use your preferred FTP - client. -#. Depending on the program you need to connect to the Pi using the IP address as the hostname and the username and password the same as you used to connect - via SSH and ensure your connection type is set to **SFTP** -#. Browse to ``/root/tuya-convert/files``. -#. Upload your compiled ``firmware.bin`` file to this directory. For command line based installs you can access the file under - ``//.pioenvs//firmware.bin`` alternatively Home Assistant add-on users can download the file directly from the web ui. - -2.7 Use tuya-convert to install ESPHome Firmware -************************************************ - -#. Type ``./start_flash.sh`` -#. Type ``yes`` to accept the warning. -#. Connect your alternative WiFi device (non iOS / Apple based) to the ``vtrust-flash`` SSID using ``flashmeifyoucan`` as the password. This is the network - being broadcast by the Pi from the tuya flash script. -#. If you haven't already install your bulb and flip the switch. It should automatically enter pairing mode represented by the bulb flashing on and off. If it - doesn't, switch your bulb, on-off-on-off-on as per the instructions `here - `__. -#. Press enter on your putty window to start the flash process and wait. The bulb will stop flashing followed by a large amount of scrolling text, this is the - script backing up the factory shipped firmware. -#. Once the process is complete you can type ``curl http://10.42.42.42/flashURL?url=http://10.42.42.1/files/firmware.bin`` -#. The bulb will restart and if everything is working correctly after a few seconds the light should be on. - -3. Bulb Configurations ----------------------- - -Thanks to the `existing work `__ by -`@so3n `__ which these adaptions created by `@cryptelli -`__ and `@bircoe `__ are based on. - - -3.1 Monochromatic Bulbs -*********************** - -The brightness of the bulb can be controlled using the ``esp8266_pwm`` output component connected to the light component using the id configuration -variable ``output_component1``. - -.. code-block:: yaml - - esphome: - name: mirabella_genio_cw_1 - - esp8266: - board: esp01_1m - - wifi: - ssid: !secret wifi_ssid - password: !secret wifi_password - - logger: - - api: - - ota: - - light: - - platform: monochromatic - name: "Mirabella Genio Smart Bulb" - id: light - output: output_component1 - - # Ensure the light turns on by default if the physical switch is actuated. - restore_mode: ALWAYS_ON - - output: - - platform: esp8266_pwm - id: output_component1 - # May need to use GPIO14 instead for certain globes - pin: GPIO13 - - -3.2 Cold + Warm White Bulbs -*************************** - -.. code-block:: yaml - - esphome: - name: mirabella_genio_cwww_1 - - esp8266: - board: esp01_1m - - wifi: - ssid: !secret wifi_ssid - password: !secret wifi_password - - logger: - - api: - - ota: - - output: - - platform: esp8266_pwm - id: output_warm_white - pin: GPIO13 - - platform: esp8266_pwm - id: output_daylight - pin: GPIO5 - - light: - - platform: cwww - name: "Mirabella Genio Smart Bulb" - id: light - cold_white: output_daylight - warm_white: output_warm_white - cold_white_color_temperature: 6500 K - warm_white_color_temperature: 2700 K - - # Ensure the light turns on by default if the physical switch is actuated. - restore_mode: ALWAYS_ON - -3.3 RGBW Color Bulbs -******************** - -.. code-block:: yaml - - esphome: - name: rgbw_e27_01 - - esp8266: - board: esp01_1m - - wifi: - ssid: !secret wifi_ssid - password: !secret wifi_password - - logger: - - api: - - ota: - - output: - - platform: esp8266_pwm - id: output_red - pin: GPIO4 - - platform: esp8266_pwm - id: output_green - pin: GPIO12 - - platform: esp8266_pwm - id: output_blue - pin: GPIO14 - - platform: esp8266_pwm - id: output_white - pin: GPIO5 - - light: - - platform: rgbw - name: "rgbw_e27_01" - id: light - red: output_red - green: output_green - blue: output_blue - white: output_white - - # Ensure the light turns on by default if the physical switch is actuated. - restore_mode: ALWAYS_ON - -3.4 CWWW Mirabella Genio Downlights -*********************************** - -.. code-block:: yaml - - esphome: - name: rgbw_e27_01 - - esp8266: - board: esp01_1m - - wifi: - ssid: !secret wifi_ssid - password: !secret wifi_password - - logger: - - api: - - ota: - - output: - - platform: esp8266_pwm - id: output1 - pin: GPIO14 - - platform: esp8266_pwm - id: output2 - pin: GPIO12 - - light: - - platform: cwww2 - id: LED - name: "Downlight" - color_temperature: output2 - brightness: output1 - cold_white_color_temperature: 6500 K - warm_white_color_temperature: 2700 K - - # Ensure the light turns on by default if the physical switch is actuated. - restore_mode: ALWAYS_ON - - -4. Adding to Home Assistant ---------------------------- - -You can now add your bulb to home assistant via the configurations page, look for 'ESPHome' under the Integrations option and click 'Configure'. - -.. figure:: images/mirabella-genio-b22-rgbw-homeassistant.jpg - :align: center - :width: 50.0% - -See Also --------- - -- :doc:`/components/light/index` -- :doc:`/components/light/monochromatic` -- :doc:`/components/light/cwww` -- :doc:`/components/light/rgbw` -- :doc:`/components/output/index` -- :doc:`/components/output/esp8266_pwm` -- :doc:`/guides/automations` -- :ghedit:`Edit` diff --git a/cookbook/pir.rst b/cookbook/pir.rst deleted file mode 100644 index 2e81d6fe03b..00000000000 --- a/cookbook/pir.rst +++ /dev/null @@ -1,66 +0,0 @@ -Passive Infrared Sensor -======================= - -.. seo:: - :description: Instructions for setting up PIR (passive infrared) motion detection sensors in ESPHome - :image: pir.jpg - :keywords: PIR - -.. figure:: images/pir-header.jpg - :align: center - :width: 75.0% - -Passive Infrared Sensors (or PIR sensors for short) are completely supported by -ESPHome. These sensors measure the infrared light emitted from objects in its -field of view, and if it detects a sudden change between different parts of the -sensing area, the signal is pulled high. - -.. figure:: images/pir-inside.jpg - :align: center - :width: 60.0% - -Connecting the PIR sensor is also quite simple. You need to connect ``GND`` to a GND pin -on your board and ``VCC`` to a ``5V`` or ``12V`` pin. Technically you can also connect -``VCC`` to ``3.3V``, but the sensor measurements won't be as stable. - -Next you need to connect the signal pin (``OUT``). Fortunately, the sensor signal has -a voltage of ``3.3V`` max, so we can directly connect it to a free GPIO pin on the ESP board. -Otherwise, we would need to step down the voltage in order to not damage the ESP. - -.. figure:: images/pir-pins.jpg - :align: center - :width: 75.0% - -.. warning:: - - Some PIR sensors have the GND and power supply pins swapped, please open the front - cover to see which pin mapping your PIR sensor is using to make sure. - -On the back side you will additionally find two knobs that you can turn to change the sensor -sensitivity and time the signal will stay active for once motion has been detected. Turning -these clockwise will increase sensitivity/re-trigger time. - -To configure ESPHome for use with the PIR sensor, use a -:doc:`GPIO Binary Sensor `. It can detect -if a pin is pulled HIGH/LOW and reports those values to Home Assistant. Optionally also -set a ``device_class`` so that Home Assistant uses a nice icon for the binary sensor. - -.. code-block:: yaml - - binary_sensor: - - platform: gpio - pin: - name: "PIR Sensor" - device_class: motion - -.. figure:: images/pir-ui.png - :align: center - :width: 60.0% - -See Also --------- - -- `Awesome article explaining how PIR Sensors work `__. -- :doc:`/components/binary_sensor/gpio` -- :doc:`bruh` -- :ghedit:`Edit` diff --git a/cookbook/relay.rst b/cookbook/relay.rst deleted file mode 100644 index bc841f7e605..00000000000 --- a/cookbook/relay.rst +++ /dev/null @@ -1,51 +0,0 @@ -Relay -===== - -.. seo:: - :description: Instructions for using relays in ESPHome. - :image: relay.jpg - :keywords: Relay - -.. figure:: images/relay-full.jpg - :align: center - :width: 80.0% - -Relays are simple electronics components that allow you to switch a high load -using only a single pin on your board. - -On the inside of a relay there is a coil that's connected to the input signal. -Every time the input signal switches on, the current flowing through the coil induces -a magnetic field that closes a contact. - -On the output side you have three pins: common (``COM``), normally open (``NO``) and -normally closed (``NC``). Connect ``COM`` and one of ``NO`` and ``NC`` in series -with your load. When the input turns on, ``NO`` is connected to ``COM`` and -when the input turns off, ``NC`` is connected to ``COM``. - -.. warning:: - - Relays are a very common component in electronics, so there are *many* types of them and - I won't attempt to describe all of them (partly due to my own lack of knowledge). Please - check with the datasheet of your relay to see its current limits, what voltage it requires - and so on. Please also note that relays are physical components - as such, they have a limited - number of switches that can happen before they break. - -To use a relay with ESPHome, use a :doc:`GPIO Switch `. - -.. code-block:: yaml - - switch: - - platform: gpio - name: "Relay" - pin: - -For a more complete example, check :doc:`Simple Garage Door `. - -See Also --------- - -- :doc:`/components/switch/gpio` -- :doc:`/components/output/gpio` -- :doc:`/cookbook/garage-door` -- `How do relays work `__. -- :ghedit:`Edit` diff --git a/cookbook/sonoff-basic-light-switch.rst b/cookbook/sonoff-basic-light-switch.rst deleted file mode 100644 index d2bb23b1239..00000000000 --- a/cookbook/sonoff-basic-light-switch.rst +++ /dev/null @@ -1,172 +0,0 @@ -DIY Light switch using a Sonoff Basic -===================================== - -.. seo:: - :description: An example of how to integrate a light switch into Home Assistant using ESPHome - :keywords: Relay, Sonoff Basic, Sonoff Dual Dual R1, Light, HASS, Home Assistant, ESPHome - -.. note:: - - This is a DIY solution, and you will need to have some knowledge of electrical wiring and enough - capabilities to do this work safely. - - The author, and the ESPHome team, take no responsibility for any actions, injuries or outcomes - from following this guide. - - In some countries you may need specific qualifications before you can carry out such work in - a residential property. - -Background ----------- - -Moving your entire house to smart lighting can end up being very expense, for instance if you have a -light fitting with 5 lamps in it that's 5 expensive smart bulbs to buy just for one room! Smart bulbs -clearly have some great advantages, dimmable, colour temperature or even full colour changing. What -if all you're after is a cost effective way to turn them on and off? - -The ideal solution would be to replace the light switch with one that can be controlled by home -assistant, whilst retaining the ease of use of a standard light that would also continue to work if -the network went down, or Home Assistant failed etc. - -It turns out Sonoff do exactly this product, it called a T1-UK (other country options available), -however you soon found the touch aspect of them might not 'feel right' and certainly might not get the -approval of other members of your household. However if this solution appeals to you, check out the -:doc:`Cookbook guide for T1/T2/T3` - -The other option to consider is a standard '2 way' light switch (like you might have on an upstairs -/ downstairs control in your house) but using relays for the second switch. For many this will have -the disadvantage that if you remotely changed the light status the switch is then 'upside down'. - -The Solution ------------- - -Use a 'retractive' style light switch. That is one that is spring loaded and so always returns to the -'off' position. It's effectively a push button, that looks like a light switch. Combining this with a -Sonoff Basic gives you the ideal solution for somewhere around £5. That's much cheaper than buying lots -of expensive smart bulbs, but of course you only get on / off control. - -You will have several potential hurdles to overcome: - -1. The first is that you do need to have a neutral at the location of the Sonoff. Many houses will not have - this as standard at the light switch. - -2. You need enough space to accommodate your Sonoff Basic at your chosen location. - -If you're lucky most of the locations will have plasterboard walls, and you will be able to simply drop a neutral -wire down the inside of the wall to the lights switch (where you locate the Sonoff). - -Also, if you have plasterboard walls, most of the light switch back boxes are the plastic dry lining style boxes. -This can come in useful because if you remove the PCB from the plastic case it actually fits in the back box nicely. - -.. warning:: - - If you plan to take the PCB out of the plastic case you need to make sure it's properly insulated, and that the back - box is deep enough to hold the PCB as well as the switch. You should also insulate the PCB, for instance by dropping it - in a heavy duty glue lined heat shrink sleeve. - - **The PCB has mains electricity flowing through it, if you are in any doubt about your capabilities do not attempt to do - this.** - -If you have a light switch in a brick wall, an option might be to place the Sonoff Basic above the light in the ceiling void, -and use the cable that ran from the light to the switch as a low voltage cable to connect the Sonoff GPIO. - -.. warning:: - - If you are going to reuse existing wiring to connect to the GPIO, you must make sure it's connected directly to the switch - and does not have mains voltage on it from another circuit. - -Implementation --------------- - -So having established the pitfalls that you need to overcome lets crack on with making this work. - -Please make sure you have read up about :doc:`the Sonoff Basic and how to flash it with ESPHome `. -As that won't be covered here.Also make sure you know your way around a soldering iron and can find the relevant information -about the location of the GPIO pins on the Sonoff Basic if you need to. - -If you have a Sonoff Basic V1 devices GPIO14 is already presented on a pin header on the PCB next to the programming pins. -On the V2 and V3 PCBs, there is a solder pad underneath the PCB that will let you get at this GPIO. - -You have 2 choices when it comes to picking which GPIO to use. GPIO0 or GPIO14. GPIO0 is used by the push button switch on the -the PCB so you will need to locate the right pin on the switch and solder a wire onto it if you're going to use that one. Whichever -one you pick, you will also need to use the ground or 0V pin for the other side of the switch. Once you have soldered your wires -into place, a handy tip is to add a drop of glue over the wire, a little way away from the solder joint, so give some strain relief -to the joint. - -Now you have a pair of wires from the GPIO and 0V to your retractive switch lets look at the code. - -.. code-block:: yaml - - esphome: - name: my_ls - - esp8266: - board: esp01_1m - - wifi: - ssid: !secret wifi_ssid - password: !secret wifi_password - - logger: - - api: - - ota: - - binary_sensor: - - platform: gpio - pin: - number: GPIO14 - mode: - input: true - pullup: true - inverted: true - id: button_1 - on_press: - then: - - light.toggle: light_1 - - - platform: status - name: "My LS Status" - - output: - - platform: gpio - pin: GPIO12 - id: relay_1 - - light: - - platform: binary - name: "My Light" - id: light_1 - output: relay_1 - - status_led: - pin: - number: GPIO13 - inverted: yes - -In the above code block, there is a *secrets.yaml* file so that you have just one place to change WiFi -details for all your devices. - -Although not visible day to day, there is also the status LED configured so that it can be used when setting -up / debugging. Also a configured binary sensor to give status in case you want to perform an action / alert -if the light switch disconnects for any reason. - -.. note:: - - If you wanted to use a pull cord switch (in a bathroom for instance) that works like a standard switch and - changes state each pull (as opposed to a retractive switch that you press and let go) then you can change - a single line *on_press:* to *on_state:* which will trigger the light toggle every time the state of the - switch changes. - - If you do this it's important that you do not use GPIO0, otherwise if the device reboots and the switch happens - to be in the closed state the Sonoff will boot into flash mode and not work. - - - -See Also --------- - -- :doc:`/cookbook/sonoff-light-switch` -- :doc:`/guides/automations` -- :doc:`/devices/sonoff_basic` diff --git a/cookbook/sonoff-dual-light-switch.rst b/cookbook/sonoff-dual-light-switch.rst deleted file mode 100644 index ee27c2c60ac..00000000000 --- a/cookbook/sonoff-dual-light-switch.rst +++ /dev/null @@ -1,260 +0,0 @@ -DIY Light switch using a Sonoff Dual -==================================== - -.. seo:: - :description: An example of how to integrate a dual light switch into Home Assistant using ESPHome - :keywords: Relay, Sonoff Dual Dual R1, Light, HASS, Home Assistant, ESPHome - -.. note:: - - This is a DIY solution, and you will need to have some knowledge of electrical wiring and enough - capabilities to do this work safely. - - The author, and the ESPHome team, take no responsibility for any actions, injuries or outcomes - from following this guide. - - In some countries you may need specific qualifications before you can carry out such work in - a residential property. - -Please read up on :doc:`/cookbook/sonoff-basic-light-switch` to get the background and principals of -the this project. It's all basically the same, but with a double switch. - -So we will be using GPIO4 and GPIO14 for the two retractive switches, again they will both short to 0V -when the switch is clicked. - -R1 --- - -The R1 version of the Dual controls the relays via the UART, so the code gets a bit complex here. - -.. code-block:: yaml - - esphome: - name: dual_ls - - esp8266: - board: esp01_1m - - wifi: - ssid: !secret wifi_ssid - password: !secret wifi_password - - logger: - baud_rate: 0 - - # Enable Home Assistant API - api: - - ota: - - uart: - tx_pin: GPIO01 - rx_pin: GPIO03 - baud_rate: 19200 - - switch: - - platform: template - id: relay_1 - turn_on_action: - if: - condition: - switch.is_off: relay_2 - then: - - uart.write: [0xA0, 0x04, 0x01, 0xA1] - else: - - uart.write: [0xA0, 0x04, 0x03, 0xA1] - turn_off_action: - if: - condition: - switch.is_off: relay_2 - then: - - uart.write: [0xA0, 0x04, 0x00, 0xA1] - else: - - uart.write: [0xA0, 0x04, 0x02, 0xA1] - optimistic: true - - - platform: template - id: relay_2 - turn_on_action: - if: - condition: - switch.is_off: relay_1 - then: - - uart.write: [0xA0, 0x04, 0x02, 0xA1] - else: - - uart.write: [0xA0, 0x04, 0x03, 0xA1] - turn_off_action: - if: - condition: - switch.is_off: relay_1 - then: - - uart.write: [0xA0, 0x04, 0x00, 0xA1] - else: - - uart.write: [0xA0, 0x04, 0x01, 0xA1] - optimistic: true - - binary_sensor: - - platform: gpio - pin: - number: GPIO4 - mode: - input: true - pullup: true - inverted: true - id: button_1 - on_press: - then: - - light.toggle: light_1 - - - platform: gpio - pin: - number: GPIO14 - mode: - input: true - pullup: true - inverted: true - id: button_2 - on_press: - then: - - light.toggle: light_2 - - - platform: status - name: "Dual LS Status" - - status_led: - pin: - number: GPIO13 - inverted: yes - - output: - - platform: template - type: binary - id: out_1 - write_action: - if: - condition: - light.is_on: light_1 - then: - - switch.turn_on: relay_1 - else: - - switch.turn_off: relay_1 - - - platform: template - type: binary - id: out_2 - write_action: - if: - condition: - light.is_on: light_2 - then: - - switch.turn_on: relay_2 - else: - - switch.turn_off: relay_2 - - light: - - platform: binary - name: "Dual L1" - id: light_1 - output: out_1 - - - platform: binary - name: "Dual L2" - id: light_2 - output: out_2 - - -In the above code block, there is a *secrets.yaml* file so that you have just one place to change WiFi -details for all your devices. - -The logger baud_rate: 0 is required to make sure the logged does not send any data over the UART or it would -mess with the relays. - -Although not visible day to day, there is also the status LED configured so that it can be used when setting -up / debugging. Also a configured binary sensor to give status in case you want to perform an action / alert -if the light switch disconnects for any reason. - -R2 --- - -This one is a lot simpler as it uses real GPIO for its relays. Please note this is untested, but should work! -It's basically the same as the :doc:`T2 ` - -.. code-block:: yaml - - esphome: - name: dual_ls - - esp8266: - board: esp01_1m - - wifi: - ssid: !secret wifi_ssid - password: !secret wifi_password - - logger: - - api: - - ota: - - binary_sensor: - - platform: gpio - pin: - number: GPIO0 - mode: - input: true - pullup: true - inverted: true - id: button - on_press: - then: - - light.toggle: light_1 - - - platform: gpio - pin: - number: GPIO14 - mode: - input: true - pullup: true - inverted: true - id: button - on_press: - then: - - light.toggle: light_2 - - - platform: status - name: "Dual LS Status" - - output: - - platform: gpio - pin: GPIO12 - id: relay_1 - - - platform: gpio - pin: GPIO5 - id: relay_2 - - light: - - platform: binary - name: "Dual L1" - id: light_1 - output: relay_1 - - - platform: binary - name: "Dual L2" - id: light_2 - output: relay_2 - - status_led: - pin: - number: GPIO13 - inverted: yes - - - -See Also --------- - -- :doc:`/cookbook/sonoff-light-switch` -- :doc:`/guides/automations` -- :doc:`/devices/sonoff_basic` diff --git a/cookbook/sonoff-light-switch.rst b/cookbook/sonoff-light-switch.rst deleted file mode 100644 index e6cf29a9abb..00000000000 --- a/cookbook/sonoff-light-switch.rst +++ /dev/null @@ -1,23 +0,0 @@ -Sonoff Light switch options -=========================== - -.. seo:: - :description: A series of options on using Sonoff devices as a light switch within ESPHome - :keywords: Relay, Sonoff Basic, Sonoff Dual Dual R1, Light, HASS, Home Assistant, ESPHome - -There are a number of options for using Sonoff Devices as light switches, including purpose built ones -like the T1/2/3 Series - -.. imgtable:: - - Sonoff T1/T2/T3, cookbook/sonoff-T1-3, sonoff_1t_t3.png - Sonoff Basic, cookbook/sonoff-basic-light-switch, sonoff_basic.jpg - Sonoff Dual, cookbook/sonoff-dual-light-switch, sonoff_dual_r2.jpg - -See Also --------- - -- :doc:`/guides/automations` -- :doc:`/devices/sonoff_basic` - - diff --git a/cookbook/sonoff-t1-3.rst b/cookbook/sonoff-t1-3.rst deleted file mode 100644 index 59b5d4c7a52..00000000000 --- a/cookbook/sonoff-t1-3.rst +++ /dev/null @@ -1,255 +0,0 @@ -Sonoff T1/T2/T3 UK -================== - -.. seo:: - :description: An example of how to integrate a T1 T2 or T3 Sonoff light switch into Home Assistant - using ESPHome - :image: sonoff_1t_t3.png - :keywords: Relay, Sonoff Basic, Sonoff Dual Dual R1, Light, HASS, Home Assistant, ESPHome - -Please make sure you have read up about :doc:`the Sonoff T1 / T2 / T3 and how to flash it with ESPHome `. - -So let's get straight on with the code! - -T1 --- - -.. code-block:: yaml - - esphome: - name: my_t1 - - esp8266: - board: esp01_1m - - wifi: - ssid: !secret wifi_ssid - password: !secret wifi_password - - logger: - - api: - - ota: - - binary_sensor: - - platform: gpio - pin: - number: GPIO0 - mode: - input: true - pullup: true - inverted: true - id: button_1 - on_press: - then: - - light.toggle: light_1 - - - platform: status - name: "T1 Status" - - output: - - platform: gpio - pin: GPIO12 - id: relay_1 - - light: - - platform: binary - name: "T1" - id: light_1 - output: relay_1 - - status_led: - pin: - number: GPIO13 - inverted: yes - - -In the above code block, there is a *secrets.yaml* file so that you have just one place to change WiFi -details for all your devices. - -The use_address is required because the Sonoff T series don't work with mDNS properly. This means that it will -show as off line in the dashboard, and you will need to use the IP address to view the logs or upload new versions -of the firmware. You will also need to manually add the device in integrations by IP address. You will need to -assign a fixed IP in the above configuration, or use a fixed IP assigned by your DHCP server. - -See `issue #810 `__ for further details. - - -T2 --- - -.. code-block:: yaml - - esphome: - name: my_t2 - - esp8266: - board: esp01_1m - - wifi: - ssid: !secret wifi_ssid - password: !secret wifi_password - - logger: - - api: - - ota: - - binary_sensor: - - platform: gpio - pin: - number: GPIO0 - mode: - input: true - pullup: true - inverted: true - id: button_1 - on_press: - then: - - light.toggle: light_1 - - - platform: gpio - pin: - number: GPIO9 - mode: - input: true - pullup: true - inverted: true - id: button_2 - on_press: - then: - - light.toggle: light_2 - - - platform: status - name: "T2 Status" - - output: - - platform: gpio - pin: GPIO12 - id: relay_1 - - - platform: gpio - pin: GPIO5 - id: relay_2 - - light: - - platform: binary - name: "T2 L1" - id: light_1 - output: relay_1 - - - platform: binary - name: "T2 L2" - id: light_2 - output: relay_2 - - status_led: - pin: - number: GPIO13 - inverted: yes - - -T3 --- - -.. code-block:: yaml - - esphome: - name: my_t3 - - esp8266: - board: esp01_1m - - wifi: - ssid: !secret wifi_ssid - password: !secret wifi_password - - logger: - - api: - - ota: - - binary_sensor: - - platform: gpio - pin: - number: GPIO0 - mode: - input: true - pullup: true - inverted: true - id: button_1 - on_press: - then: - - light.toggle: light_1 - - - platform: gpio - pin: - number: GPIO9 - mode: - input: true - pullup: true - inverted: true - id: button_2 - on_press: - then: - - light.toggle: light_2 - - - platform: gpio - pin: - number: GPIO10 - mode: - input: true - pullup: true - inverted: true - id: button_3 - on_press: - then: - - light.toggle: light_3 - - - platform: status - name: "T3 Status" - - output: - - platform: gpio - pin: GPIO12 - id: relay_1 - - - platform: gpio - pin: GPIO5 - id: relay_2 - - - platform: gpio - pin: GPIO4 - id: relay_3 - - light: - - platform: binary - name: "T3 L1" - id: light_1 - output: relay_1 - - - platform: binary - name: "T3 L2" - id: light_2 - output: relay_2 - - - platform: binary - name: "T3 L3" - id: light_3 - output: relay_3 - - status_led: - pin: - number: GPIO13 - inverted: yes - - -See Also --------- - -- :doc:`/cookbook/sonoff-light-switch` -- :doc:`/guides/automations` -- :doc:`/devices/sonoff_t1_uk_3gang_v1.1` diff --git a/cookbook/teckin_sb50.rst b/cookbook/teckin_sb50.rst deleted file mode 100644 index edb1369a4a2..00000000000 --- a/cookbook/teckin_sb50.rst +++ /dev/null @@ -1,88 +0,0 @@ -TECKIN SB50 LED Bulb -==================== - -.. seo:: - :description: ESPHome configuration for Teckin SB50 LED Bulb. - :image: teckin_sb50.jpg - :keywords: Teckin SB50 - -.. figure:: images/teckin_sb50.jpg - :align: center - :width: 50.0% - -.. warning:: - - It is not currently possible to flash these bulbs with ``tuya-convert`` due to shipping with an updated/patched firmware. - Please check `this issue `__ for details and progress on a workaround. - -The Teckin SB50 Bulb's are a great option for lighting that could previously be flashed with tuya-convert. More details can be found at tuya-convert `github page `__. -Below is the ESPHome configuration file that will get you up and running. This assumes you have a ``secret.yaml`` with ssid, password, api_password and ota_password keys. - -.. code-block:: yaml - - substitutions: - devicename: - - esphome: - name: $devicename - - esp8266: - board: esp01_1m - - wifi: - ssid: !secret wifi_ssid - password: !secret wifi_password - - # Enable logging to ESPHome - logger: - # Disable logging to serial - baud_rate: 0 - - # Enable Home Assistant API - api: - - # Setup OTA - ota: - - # Define output pins - output: - - platform: esp8266_pwm - id: output_red - pin: GPIO4 - - platform: esp8266_pwm - id: output_green - pin: GPIO12 - - platform: esp8266_pwm - id: output_blue - pin: GPIO14 - - platform: esp8266_pwm - id: output_warm_white - pin: GPIO13 - - platform: esp8266_pwm - id: output_cold_white - pin: GPIO5 - - # Define a light entity - light: - - platform: rgbww - name: $devicename - id: $devicename - red: output_red - green: output_green - blue: output_blue - warm_white: output_warm_white - cold_white: output_cold_white - cold_white_color_temperature: 6200 K - warm_white_color_temperature: 2800 K - color_interlock: true # avoids simultaneous RGB and W/W - - -See Also --------- - -- :doc:`/devices/nodemcu_esp8266` -- :doc:`/cookbook/mirabella-genio-bulb` -- :doc:`/components/light/rgb` -- :doc:`/components/output/esp8266_pwm` -- :doc:`/components/binary_sensor/gpio` -- :ghedit:`Edit` diff --git a/cookbook/temt6000.rst b/cookbook/temt6000.rst deleted file mode 100644 index 2e3ec01d387..00000000000 --- a/cookbook/temt6000.rst +++ /dev/null @@ -1,74 +0,0 @@ -TEMT6000 -======== - -.. seo:: - :description: Instructions for setting up TEMT6000 ambient light sensors in ESPHome using the ADC sensor component. - :image: temt6000.jpg - :keywords: TEMT6000 - -The TEMT6000 is a simple and cheap ambient light sensor. The sensor itself -changes its resistance based on how much light hits the sensor. In order -for us to read this resistance the breakout boards you can buy these chips on -often have a small constant value resistor and three pins: ``GND``, ``VCC`` and -``SIG``. Connect ``VCC`` to ``3.3V``, ``GND`` to ``GND`` and ``SIG`` to any -available :doc:`analog pin `. - -.. figure:: images/temt6000-header.jpg - :align: center - :width: 75.0% - -To get the brightness the sensor measures, we then simply have to measure the voltage -on the ``SIG`` (also called ``OUT``) pin using the :doc:`/components/sensor/adc` -and convert those voltage measurements to illuminance values in lux using a formula: - -.. code-block:: yaml - - sensor: - - platform: adc - pin: A0 - name: "TEMT6000 Illuminance" - device_class: illuminance - unit_of_measurement: lx - filters: - - lambda: |- - return (x / 10000.0) * 2000000.0; - -.. figure:: images/temt6000-pins.jpg - :align: center - :width: 75.0% - - Pins on the TEMT6000. Connect ``OUT`` to an ADC pin, ``GND`` to ``GND``, and ``VCC`` - to ``3.3V`` - -Formula Explanation: --------------------- - -To get the illuminance in lux, we first need to convert the measured voltage to the -current flowing across the TEMT6000 sensor. This current is also equal to the current -flowing across the 10kΩ resistor in the voltage divider circuit, which is -``I = adc_value/10000kΩ``. - -The `datasheet for the TEMT6000 `__ -specifies a proportional correlation between current and illuminance: Every 2 µA of current -correlates to 1 lx in the illuminance. - -.. note:: - - The default voltage range of the ADC for the ESP8266 and ESP32 are from 0 to 1.0V. - So you won't be able to measure any value above 200 lx using the default setup. - - For the ESP32, you have the option of setting a :ref:`Voltage Attenuation ` - (note that the formula doesn't need to be adjusted if you set an attenuation, as the value ``x`` - is automatically converted to volts). - - For the ESP8266, you unfortunately need to tinker with the hardware a bit to decrease - the voltage a bit. So one option would be to create another voltage divider on the ``SIG`` pin - to divide the analog voltage by a constant value. - -See Also --------- - -- :doc:`/components/sensor/adc` -- `TEMT6000 datasheet `__ -- :doc:`bruh` -- :ghedit:`Edit` diff --git a/cookbook/tracer-an.rst b/cookbook/tracer-an.rst deleted file mode 100644 index e4111ab47f0..00000000000 --- a/cookbook/tracer-an.rst +++ /dev/null @@ -1,1286 +0,0 @@ -EPEVER® MPPT Solar Charge Controller Tracer-AN Series -===================================================== -.. seo:: - :description: ESPHome configuration for EPEVER® MPPT Solar Charge Controller Tracer-AN Series - :image: tracer-an.jpg - :keywords: EPEVER Tracer - -.. figure:: images/tracer-an.jpg - :align: center - :width: 50.0% - -.. warning:: - - Enabling all modbus registers will probably cause a stack overflow in main - - -Tested with Tracer-AN Series 10A/20A/30A/40A and XTRA Series 10A/20A/30A/40A. -Probably works for other EPEver MPPT controllers as well. - - -Below is the ESPHome configuration file that will get you up and running. This assumes you have a ``secret.yaml`` with ssid, password, api_password and ota_password keys. - -.. code-block:: yaml - - substitutions: - updates: 30s - name: solarstation-x - - esphome: - name: ${name} - platformio_options: - ## larger stack size required with all registers enable_load_test - ## reduce registers or wait for integration of 2.0.0 arduinoespressif32 - ## not yet working needs 2.0 - build_flags: - - -DCONFIG_ARDUINO_LOOP_STACK_SIZE=32768 - - on_boot: - ## configure controller settings at setup - ## make sure priority is lower than setup_priority of modbus_controller - priority: -100 - then: - - lambda: |- - // get local time and sync to controller - time_t now = ::time(nullptr); - struct tm *time_info = ::localtime(&now); - int seconds = time_info->tm_sec; - int minutes = time_info->tm_min; - int hour = time_info->tm_hour; - int day = time_info->tm_mday; - int month = time_info->tm_mon + 1; - int year = time_info->tm_year % 100; - esphome::modbus_controller::ModbusController *controller = id(epever); - // if there is no internet connection localtime returns year 70 - if (year != 70) { - // create the payload - std::vector rtc_data = {uint16_t((minutes << 8) | seconds), uint16_t((day << 8) | hour), - uint16_t((year << 8) | month)}; - // Create a modbus command item with the time information as the payload - esphome::modbus_controller::ModbusCommandItem set_rtc_command = - esphome::modbus_controller::ModbusCommandItem::create_write_multiple_command(controller, 0x9013, 3, rtc_data); - // Submit the command to the send queue - epever->queue_command(set_rtc_command); - ESP_LOGI("ModbusLambda", "EPSOLAR RTC set to %02d:%02d:%02d %02d.%02d.%04d", hour, minutes, seconds, day, month, - year + 2000); - } - // Battery settings - // Note: these values are examples only and apply my AGM Battery - std::vector battery_settings1 = { - 0, // 9000 Battery Type 0 = User - 0x0073, // 9001 Battery Cap 0x55 == 115AH - 0x012C, // 9002 Temp compensation -3V /°C/2V - 0x05DC, // 9003 0x5DC == 1500 Over Voltage Disconnect Voltage 15,0 - 0x058C, // 9004 0x58C == 1480 Charging Limit Voltage 14,8 - 0x058C, // 9005 Over Voltage Reconnect Voltage 14,8 - 0x05BF, // 9006 Equalize Charging Voltage 14,6 - 0x05BE, // 9007 Boost Charging Voltage 14,7 - 0x0550, // 9008 Float Charging Voltage 13,6 - 0x0528, // 9009 Boost Reconnect Charging Voltage 13,2 - 0x04C4, // 900A Low Voltage Reconnect Voltage 12,2 - 0x04B0, // 900B Under Voltage Warning Reconnect Voltage 12,0 - 0x04BA, // 900c Under Volt. Warning Volt 12,1 - 0x04BA, // 900d Low Volt. Disconnect Volt. 11.8 - 0x04BA // 900E Discharging Limit Voltage 11.8 - }; - - // Boost and equalization periods - std::vector battery_settings3 = { - 0x0000, // 906B Equalize Duration (min.) 0 - 0x0075 // 906C Boost Duration (aka absorb) 117 mins - }; - esphome::modbus_controller::ModbusCommandItem set_battery1_command = - esphome::modbus_controller::ModbusCommandItem::create_write_multiple_command(controller, 0x9000, battery_settings1.size() , - battery_settings1); - // esphome::modbus_controller::ModbusCommandItem set_battery2_command = - // esphome::modbus_controller::ModbusCommandItem::create_write_multiple_command(controller, 0x900A, battery_settings2.size() , - // battery_settings2); - - esphome::modbus_controller::ModbusCommandItem set_battery3_command = - esphome::modbus_controller::ModbusCommandItem::create_write_multiple_command(controller, 0x906B, battery_settings3.size(), - battery_settings3); - delay(200) ; - controller->queue_command(set_battery1_command); - delay(200) ; - // controller->queue_command(set_battery2_command); - // delay(200) ; - controller->queue_command(set_battery3_command); - ESP_LOGI("ModbusLambda", "EPSOLAR Battery set"); - - esp32: - board: pico32 - framework: - type: arduino - version: latest - - wifi: - ssid: !secret wifi_sid - password: !secret wifi_password - - time: - - platform: sntp - id: sntp_time - timezone: "CET-1CEST,M3.5.0,M10.5.0/3" - servers: "de.pool.ntp.org" - - # Enable logging - logger: - level: INFO - - # Enable Home Assistant API - api: - reboot_timeout: 0s - - ota: - - uart: - id: mod_bus - tx_pin: 19 - rx_pin: 18 - baud_rate: 115200 - stop_bits: 1 - - modbus: - #flow_control_pin: 23 - send_wait_time: 200ms - id: mod_bus_epever - - modbus_controller: - - id: epever - ## the Modbus device addr - address: 0x1 - modbus_id: mod_bus_epever - command_throttle: 200ms - setup_priority: -10 - update_interval: ${updates} - - packages: - tracer-rated-datum: !include tracer-rated-datum.yaml - tracer-real-time: !include tracer-real-time.yaml - tracer-stats: !include tracer-stats.yaml - #tracer-settings: !include tracer-settings.yaml - - sensor: - - platform: template - accuracy_decimals: 0 - name: "Generated Charge today" - id: generated_charge_today - unit_of_measurement: "Ah" - - - platform: wifi_signal - name: "WiFi Signal" - update_interval: ${updates} - - binary_sensor: - - platform: modbus_controller - modbus_controller_id: epever - id: charging_input_volt_failure - name: "Charging Input Volt Failure" - register_type: read - address: 0x3201 - bitmask: 0xC000 - - switch: - - platform: modbus_controller - modbus_controller_id: epever - id: manual_control_load - register_type: coil - address: 2 - name: "manual control the load" - bitmask: 1 - - - platform: modbus_controller - modbus_controller_id: epever - id: default_control_the_load - register_type: coil - address: 3 - name: "default control the load" - bitmask: 1 - - - platform: modbus_controller - modbus_controller_id: epever - id: enable_load_test - register_type: coil - address: 5 - name: "enable load test mode" - bitmask: 1 - - - platform: modbus_controller - modbus_controller_id: epever - id: force_load - register_type: coil - address: 6 - name: "Force Load on/off" - bitmask: 1 - - # - platform: modbus_controller - # modbus_controller_id: epever - # id: clear_energy_stats - # register_type: coil - # address: 0x14 - # name: "Clear generating electricity statistic" - # bitmask: 1 - - # - platform: modbus_controller - # modbus_controller_id: epever - # id: reset_to_fabric_default - # name: "Reset to Factory Default" - # register_type: coil - # address: 0x15 - # bitmask: 1 - - text_sensor: - - platform: modbus_controller - modbus_controller_id: epever - name: "rtc_clock" - id: rtc_clock - internal: true - register_type: holding - address: 0x9013 - register_count: 3 - raw_encode: HEXBYTES - response_size: 6 - # /* - # E20 Real time clock 9013 D7-0 Sec, D15-8 Min - # E21 Real time clock 9014 D7-0 Hour, D15-8 Day - # E22 Real time clock 9015 D7-0 Month, D15-8 Year - # */ - on_value: - then: - - lambda: |- - ESP_LOGV("main", "decoding rtc hex encoded raw data: %s", x.c_str()); - uint8_t h=0,m=0,s=0,d=0,month_=0,y = 0 ; - m = esphome::modbus_controller::byte_from_hex_str(x,0); - s = esphome::modbus_controller::byte_from_hex_str(x,1); - d = esphome::modbus_controller::byte_from_hex_str(x,2); - h = esphome::modbus_controller::byte_from_hex_str(x,3); - y = esphome::modbus_controller::byte_from_hex_str(x,4); - month_ = esphome::modbus_controller::byte_from_hex_str(x,5); - // Now check if the rtc time of the controller is ok and correct it - time_t now = ::time(nullptr); - struct tm *time_info = ::localtime(&now); - int seconds = time_info->tm_sec; - int minutes = time_info->tm_min; - int hour = time_info->tm_hour; - int day = time_info->tm_mday; - int month = time_info->tm_mon + 1; - int year = time_info->tm_year % 100; - // correct time if needed (ignore seconds) - if (d != day || month_ != month || y != year || h != hour || m != minutes) { - // create the payload - std::vector rtc_data = {uint16_t((minutes << 8) | seconds), uint16_t((day << 8) | hour), - uint16_t((year << 8) | month)}; - // Create a modbus command item with the time information as the payload - esphome::modbus_controller::ModbusCommandItem set_rtc_command = esphome::modbus_controller::ModbusCommandItem::create_write_multiple_command(epever, 0x9013, 3, rtc_data); - // Submit the command to the send queue - epever->queue_command(set_rtc_command); - ESP_LOGI("ModbusLambda", "EPSOLAR RTC set to %02d:%02d:%02d %02d.%02d.%04d", hour, minutes, seconds, day, month, year + 2000); - } - char buffer[20]; - // format time as YYYY-mm-dd hh:mm:ss - sprintf(buffer,"%04d-%02d-%02d %02d:%02d:%02d",y+2000,month_,d,h,m,s); - id(template_rtc).publish_state(buffer); - - - platform: template - name: "RTC Time Sensor" - id: template_rtc - - - platform: modbus_controller - modbus_controller_id: epever - name: "rtc clock test 2" - id: rtc_clock_test2 - internal: true - register_type: holding - address: 0x9013 - register_count: 3 - raw_encode: HEXBYTES - response_size: 6 - - web_server: - port: 80 - -The definitions for most sensors is included using Packages - -Rated Datum registers - -tracer-rated-datum.yaml - -.. code-block:: yaml - - sensor: - - platform: modbus_controller - modbus_controller_id: epever - id: array_rated_voltage - name: "array_rated_voltage" - address: 0x3000 - skip_updates: 60 - unit_of_measurement: "V" - register_type: read - value_type: U_WORD - accuracy_decimals: 1 - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: array_rated_current - name: "array_rated_current" - address: 0x3001 - unit_of_measurement: "A" - register_type: read - value_type: U_WORD - accuracy_decimals: 2 - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: array_rated_power - name: "array_rated_power" - address: 0x3002 - register_count: 2 - unit_of_measurement: "W" - register_type: read - value_type: U_DWORD_R - accuracy_decimals: 1 - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: battery_rated_voltage - name: "battery_rated_voltage" - address: 0x3004 - unit_of_measurement: "V" - register_type: read - value_type: U_WORD - accuracy_decimals: 1 - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: battery_rated_current - name: "battery_rated_current" - address: 0x3005 - unit_of_measurement: "A" - register_type: read - value_type: U_WORD - accuracy_decimals: 1 - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: battery_rated_power - name: "battery_rated_power" - address: 0x3006 - unit_of_measurement: "W" - register_type: read - value_type: U_DWORD_R - accuracy_decimals: 1 - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: charging_mode - name: "charging_mode" - address: 0x3008 - unit_of_measurement: "" - register_type: read - value_type: U_WORD - accuracy_decimals: 0 - - - platform: modbus_controller - modbus_controller_id: epever - id: rated_current_of_load - name: "rated_current_of_load" - address: 0x300E - skip_updates: 60 - unit_of_measurement: "A" - register_type: read - value_type: U_WORD - accuracy_decimals: 1 - filters: - - multiply: 0.01 - - -Real TimeDatum registers -tracer-real-time.yaml - -.. code-block:: yaml - - sensor: - - platform: modbus_controller - modbus_controller_id: epever - id: pv_input_voltage - name: "PV array input voltage" - address: 0x3100 - unit_of_measurement: "V" ## for any other unit the value is returned in minutes - register_type: read - value_type: U_WORD - accuracy_decimals: 1 - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: pv_input_current - name: "PV array input current" - address: 0x3101 - unit_of_measurement: "A" ## for any other unit the value is returned in minutes - register_type: read - value_type: U_WORD - accuracy_decimals: 2 - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: pv_input_power - name: "PV array input power" - address: 0x3102 - unit_of_measurement: "W" ## for any other unit the value is returned in minutes - register_type: read - value_type: U_DWORD_R - accuracy_decimals: 1 - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: charging_voltage - name: "Charging voltage" - address: 0x3104 - unit_of_measurement: "V" - register_type: read - value_type: U_WORD - accuracy_decimals: 1 - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: charging_current - name: "Charging current" - address: 0x3105 - unit_of_measurement: "A" - register_type: read - value_type: U_WORD - accuracy_decimals: 1 - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: charging_power - name: "Charging power" - address: 0x3106 - unit_of_measurement: "W" - register_type: read - value_type: U_DWORD_R - accuracy_decimals: 1 - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: load_voltage - name: "Load voltage" - address: 0x310C - unit_of_measurement: "V" - register_type: read - value_type: U_WORD - accuracy_decimals: 1 - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: load_current - name: "Load Current" - address: 0x310D - unit_of_measurement: "A" - register_type: read - value_type: U_WORD - accuracy_decimals: 2 - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: load_power - name: "Load power" - address: 0x310E - unit_of_measurement: "W" - register_type: read - value_type: U_DWORD_R - accuracy_decimals: 1 - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: battery_temperature - name: "Battery temperature" - address: 0x3110 - unit_of_measurement: °C - register_type: read - value_type: S_WORD - accuracy_decimals: 1 - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: device_temperature - name: "Device temperature" - address: 0x3111 - unit_of_measurement: °C - register_type: read - value_type: S_WORD - accuracy_decimals: 1 - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: power_components_temperature - name: "Power components temperature" - address: 0x3112 - unit_of_measurement: °C - register_type: read - value_type: S_WORD - accuracy_decimals: 1 - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: battery_soc - name: "Battery SOC" - address: 0x311A - unit_of_measurement: "%" - register_type: read - value_type: U_WORD - accuracy_decimals: 0 - - - platform: modbus_controller - modbus_controller_id: epever - id: remote_battery_temperature - name: "Remote battery temperature" - address: 0x311B - unit_of_measurement: °C - register_type: read - value_type: S_WORD - accuracy_decimals: 1 - filters: - - multiply: 0.01 - - platform: modbus_controller - modbus_controller_id: epever - id: battery_volt_settings - name: "Remote real voltage" - address: 0x311D - unit_of_measurement: "°C" - register_type: read - value_type: S_WORD - accuracy_decimals: 1 - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: Battery_status_volt - name: "Battery status voltage" - address: 0x3200 - register_type: read - value_type: U_WORD - bitmask: 7 #(Bits 0-3) - accuracy_decimals: 0 - - - platform: modbus_controller - modbus_controller_id: epever - id: Battery_status_temp - name: "Battery status temeratur" - address: 0x3200 - register_type: read - value_type: U_WORD - bitmask: 0x38 #(Bits 4-7) - accuracy_decimals: 0 - - - platform: modbus_controller - modbus_controller_id: epever - id: Charger_status - name: "Charger status" - address: 0x3201 - register_type: read - value_type: U_WORD - accuracy_decimals: 0 - - Statistic registers - tracer-stats.yaml - - .. code-block:: yaml - - sensor: - - platform: modbus_controller - modbus_controller_id: epever - id: max_pv_voltage_today - name: "Maximum PV voltage today" - address: 0x3300 - register_type: read - value_type: U_WORD - accuracy_decimals: 1 - unit_of_measurement: "V" - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: min_pv_voltage_today - name: "Minimum PV voltage today" - address: 0x3301 - register_type: read - value_type: U_WORD - accuracy_decimals: 1 - unit_of_measurement: "V" - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: max_battery_voltage_today - name: "Maximum battery voltage today" - address: 0x3302 - register_type: read - value_type: U_WORD - accuracy_decimals: 1 - unit_of_measurement: "V" - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: min_battery_today - name: "Minimum battery voltage today" - address: 0x3303 - register_type: read - value_type: U_WORD - accuracy_decimals: 1 - unit_of_measurement: "V" - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: consumed_energy_today - name: "Consumed energy today" - address: 0x3304 - register_type: read - value_type: U_DWORD_R - accuracy_decimals: 0 - unit_of_measurement: "Wh" - filters: - - multiply: 10.0 - - - platform: modbus_controller - modbus_controller_id: epever - id: consumed_energy_month - name: "Consumed Energy Month" - address: 0x3306 - register_type: read - value_type: U_DWORD_R - accuracy_decimals: 0 - unit_of_measurement: "Wh" - filters: - - multiply: 10.0 - - - platform: modbus_controller - modbus_controller_id: epever - id: consumed_energy_year - name: "Consumed energy year" - address: 0x3308 - register_type: read - value_type: U_DWORD_R - accuracy_decimals: 1 - unit_of_measurement: "kWh" - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: consumed_energy_total - name: "Consumed energy total" - address: 0x330A - register_type: read - value_type: U_DWORD_R - accuracy_decimals: 1 - unit_of_measurement: "kWh" - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: generated_energy_today - name: "Generated energy today" - address: 0x330C - register_type: read - value_type: U_DWORD_R - accuracy_decimals: 0 - unit_of_measurement: "Wh" - on_value: - then: - - sensor.template.publish: - id: generated_charge_today - state: !lambda "return x/12.0;" - filters: - - multiply: 10.0 - - - platform: modbus_controller - modbus_controller_id: epever - id: generated_energy_month - name: "Generated energy month" - address: 0x330E - register_type: read - value_type: U_DWORD_R - accuracy_decimals: 0 - unit_of_measurement: "Wh" - filters: - - multiply: 10.0 - - - platform: modbus_controller - modbus_controller_id: epever - id: generated_energy_year - name: "Generated energy year" - address: 0x3310 - register_type: read - value_type: U_DWORD_R - accuracy_decimals: 1 - unit_of_measurement: "kWh" - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: generated_energy_total - name: "Generated energy total" - address: 0x3312 - register_type: read - value_type: U_DWORD_R - accuracy_decimals: 1 - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: co2_reduction - name: "CO2 reduction" - address: 0x3314 - register_type: read - value_type: U_DWORD_R - accuracy_decimals: 1 - unit_of_measurement: "kg" - filters: - - multiply: 10.0 - - - platform: modbus_controller - modbus_controller_id: epever - id: battery_voltage - name: "Battery voltage" - address: 0x331A - register_type: read - value_type: U_WORD - accuracy_decimals: 1 - unit_of_measurement: "V" - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: battery_current - name: "Battery current" - address: 0x331B - register_type: read - value_type: S_DWORD_R - register_count: 2 - accuracy_decimals: 2 - unit_of_measurement: "A" - filters: - - multiply: 0.01 - - -Setting registers (commented out to save stack space) -tracer-settings.yaml - -.. code-block:: yaml - - sensor: - - platform: modbus_controller - modbus_controller_id: epever - id: battery_type - address: 0x9000 - name: "Battery Type" - register_type: holding - value_type: U_WORD - skip_updates: 50 - - - platform: modbus_controller - modbus_controller_id: epever - id: battery_capacity - address: 0x9001 - name: "Battery Capacity" - register_type: holding - value_type: U_WORD - - - platform: modbus_controller - modbus_controller_id: epever - id: temperature_compensation_coefficient - address: 0x9002 - name: "Temperature compensation coefficient" - unit_of_measurement: "mV/°C/2V" - register_type: holding - value_type: U_WORD - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: high_voltage_disconnect - address: 0x9003 - name: "High Voltage disconnect" - unit_of_measurement: "V" - register_type: holding - value_type: U_WORD - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: charging_limit_voltage - address: 0x9004 - name: "Charging limit voltage" - unit_of_measurement: "V" - register_type: holding - value_type: U_WORD - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: over_voltage_reconnect - address: 0x9005 - name: "Over voltage reconnect" - unit_of_measurement: "V" - register_type: holding - value_type: U_WORD - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: equalization_voltage - address: 0x9006 - name: "Equalization voltage" - unit_of_measurement: "V" - register_type: holding - value_type: U_WORD - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: boost_voltage - address: 0x9007 - name: "Boost voltage" - unit_of_measurement: "V" - register_type: holding - value_type: U_WORD - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: float_voltage - address: 0x9008 - name: "Float voltage" - unit_of_measurement: "V" - register_type: holding - value_type: U_WORD - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: boost_reconnect_voltage - address: 0x9009 - name: "Boost reconnect voltage" - unit_of_measurement: "V" - register_type: holding - value_type: U_WORD - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: low_voltage_reconnect - address: 0x900A - name: "Low voltage reconnect" - unit_of_measurement: "V" - register_type: holding - value_type: U_WORD - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: under_voltage_recover - address: 0x900B - name: "Under voltage recover" - unit_of_measurement: "V" - register_type: holding - value_type: U_WORD - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: under_voltage_warning - address: 0x900C - name: "Under voltage warning" - unit_of_measurement: "V" - register_type: holding - value_type: U_WORD - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: low_voltage_disconnect - address: 0x900D - name: "Low voltage disconnect" - unit_of_measurement: "V" - register_type: holding - value_type: U_WORD - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: discharging_limit_voltage - address: 0x900E - name: "Discharging limit voltage" - unit_of_measurement: "V" - register_type: holding - value_type: U_WORD - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: battery_temperature_warning_upper_limit - address: 0x9017 - name: "Battery temperature warning upper limit" - unit_of_measurement: "°C" - register_type: holding - value_type: S_WORD - # new range add 'skip_updates' again - skip_updates: 50 - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: battery_temperature_warning_lower_limit - address: 0x9018 - name: "Battery temperature warning lower limit" - unit_of_measurement: "°C" - register_type: holding - value_type: S_WORD - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: controller_inner_temperature_upper_limit - address: 0x9019 - name: "Controller inner temperature upper limit" - unit_of_measurement: "°C" - register_type: holding - value_type: S_WORD - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: controller_inner_temperature_upper_limit_recover - address: 0x901A - name: "Controller inner temperature upper limit recover" - unit_of_measurement: "°C" - register_type: holding - value_type: S_WORD - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: power_component_temperature_upper_limit - address: 0x901B - name: "Power component temperature upper limit" - unit_of_measurement: "°C" - register_type: holding - value_type: S_WORD - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: power_component_temperature_upper_limit_recover - address: 0x901C - name: "Power component temperature upper limit recover" - unit_of_measurement: "°C" - register_type: holding - value_type: S_WORD - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: line_impedance - address: 0x901D - name: "Line Impedance" - unit_of_measurement: "mOhm" - register_type: holding - value_type: U_WORD - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: dttv - address: 0x901E - name: "Day Time Threshold Voltage" - unit_of_measurement: "V" - register_type: holding - value_type: U_WORD - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: light_signal_startup_delay_time - address: 0x901F - name: "Light signal startup delay time" - unit_of_measurement: "mins" - register_type: holding - value_type: U_WORD - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: nttv - address: 0x9020 - name: "Light Time Threshold Voltage" - unit_of_measurement: "mins" - register_type: holding - value_type: U_WORD - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: light_signal_close_delay_time - address: 0x9021 - name: "Light signal close delay time" - unit_of_measurement: "mins" - register_type: holding - value_type: U_WORD - filters: - - multiply: 0.01 - - - platform: modbus_controller - modbus_controller_id: epever - id: - load_controlling_modes - # 0000H Manual Control - # 0001H Light ON/OFF - # 0002H Light ON+ Timer/ - # 0003H Time Control - address: 0x903D - name: "Load controlling modes" - register_type: holding - accuracy_decimals: 0 - value_type: U_WORD - skip_updates: 50 - - - platform: modbus_controller - modbus_controller_id: epever - id: working_time_length_1 - # The length of load output timer1, - # D15-D8,hour, D7-D0, minute - address: 0x903E - name: "Working_time length 1" - register_type: holding - accuracy_decimals: 0 - value_type: U_WORD - - - platform: modbus_controller - modbus_controller_id: epever - id: working_time_length_2 - address: 0x903F - name: "Working_time length 1" - register_type: holding - accuracy_decimals: 0 - value_type: U_WORD - - - platform: modbus_controller - modbus_controller_id: epever - id: turn_on_timing_1_seconds - address: 0x9042 - name: "Turn on timing 1 seconds" - register_type: holding - accuracy_decimals: 0 - value_type: U_WORD - skip_updates: 50 - - - platform: modbus_controller - modbus_controller_id: epever - id: turn_on_timing_1_minutes - address: 0x9043 - name: "Turn on timing 1 minutes" - register_type: holding - accuracy_decimals: 0 - value_type: U_WORD - - - platform: modbus_controller - modbus_controller_id: epever - id: turn_on_timing_1_hours - address: 0x9044 - name: "Turn on timing 1 hours" - register_type: holding - accuracy_decimals: 0 - value_type: U_WORD - - - platform: modbus_controller - modbus_controller_id: epever - id: turn_off_timing_1_seconds - address: 0x9045 - name: "Turn off timing 1 seconds" - register_type: holding - accuracy_decimals: 0 - value_type: U_WORD - - - platform: modbus_controller - modbus_controller_id: epever - id: turn_off_timing_1_minutes - address: 0x9046 - name: "Turn off timing 1 minutes" - register_type: holding - accuracy_decimals: 0 - value_type: U_WORD - - - platform: modbus_controller - modbus_controller_id: epever - id: turn_off_timing_1_hours - address: 0x9047 - name: "Turn off timing 1 hours" - register_type: holding - accuracy_decimals: 0 - value_type: U_WORD - - - platform: modbus_controller - modbus_controller_id: epever - id: turn_on_timing_2_seconds - address: 0x9048 - name: "Turn on timing 2 seconds" - register_type: holding - accuracy_decimals: 0 - value_type: U_WORD - - - platform: modbus_controller - modbus_controller_id: epever - id: turn_on_timing_2_minutes - address: 0x9049 - name: "Turn on timing 2 minutes" - register_type: holding - accuracy_decimals: 0 - value_type: U_WORD - - - platform: modbus_controller - modbus_controller_id: epever - id: turn_on_timing_2_hours - address: 0x904A - name: "Turn on timing 2 hours" - register_type: holding - accuracy_decimals: 0 - value_type: U_WORD - - - platform: modbus_controller - modbus_controller_id: epever - id: turn_off_timing_2_seconds - address: 0x904B - name: "Turn off timing 2 seconds" - register_type: holding - accuracy_decimals: 0 - value_type: U_WORD - - - platform: modbus_controller - modbus_controller_id: epever - id: turn_off_timing_2_minutes - address: 0x904C - name: "Turn off timing 2 minutes" - register_type: holding - accuracy_decimals: 0 - value_type: U_WORD - - - platform: modbus_controller - modbus_controller_id: epever - id: turn_off_timing_2_hours - address: 0x904D - name: "Turn off timing 2 hours" - register_type: holding - accuracy_decimals: 0 - value_type: U_WORD - - - platform: modbus_controller - modbus_controller_id: epever - id: backlight_time - address: 0x9063 - name: "Backlight time" - register_type: holding - accuracy_decimals: 0 - unit_of_measurement: "s" - value_type: U_WORD - - - platform: modbus_controller - modbus_controller_id: epever - id: length_of_night_minutes - address: 0x9065 - internal: true - bitmask: 0xFF - unit_of_measurement: "m" - name: "Length of night-mins" - register_type: holding - value_type: U_WORD - - - platform: modbus_controller - modbus_controller_id: epever - id: length_of_night - address: 0x9065 - bitmask: 0xFF00 - unit_of_measurement: "m" - name: "Length of night" - register_type: holding - value_type: U_WORD - skip_updates: 50 - filters: - - lambda: return id(length_of_night_minutes).state + ( 60 * x); - - -See Also --------- - -- :doc:`/components/modbus_controller` -- `EPEVER Tracer Modbus Registers `__ -- :ghedit:`Edit` diff --git a/cookbook/tuya_rgbw.rst b/cookbook/tuya_rgbw.rst deleted file mode 100644 index 08d34b8b3ee..00000000000 --- a/cookbook/tuya_rgbw.rst +++ /dev/null @@ -1,88 +0,0 @@ -Tuya RGBW LED controller -======================== - -The Tuya RGBW controller is inexpensive, available on ebay, and can be OTA flashed using `tuya-convert `__, after which it can be OTA flashed via the ESPHome web interface (NOTE: a port must be explicitly set if using a Home Assistant add-on for this, and you need to connect directly to that port instead of using the proxied port via Home Assistant). - -.. figure:: images/tuya_rgbw.jpg - :align: center - :width: 80.0% - -The configuration below shows an example that can be compiled to a binary firmware file that works correctly for this device, and that cycles through three different brightnesses and an off state based on the number of button presses. The device can also be controlled via Home Assistant, of course, setting specific RGBW combinations and brightness levels. - -.. code-block:: yaml - - # Example configuration entry - output: - - platform: esp8266_pwm - id: output_red - pin: GPIO14 - - platform: esp8266_pwm - id: output_green - pin: GPIO5 - - platform: esp8266_pwm - id: output_blue - pin: GPIO12 - - platform: esp8266_pwm - id: output_white - pin: GPIO15 - - globals: - - id: action_state - type: int - restore_value: no - initial_value: '0' - - binary_sensor: - - platform: gpio - pin: GPIO13 - name: "RGBW Controller Button" - filters: - - invert: - - delayed_on_off: 20ms - on_press: - then: - - lambda: id(action_state) = (id(action_state) + 1) % 4; - - if: - condition: - lambda: 'return id(action_state) == 0;' - then: - - light.turn_off: rgbw_lightstrip1 - - if: - condition: - lambda: 'return id(action_state) == 1;' - then: - - light.turn_on: - id: rgbw_lightstrip1 - brightness: 60% - - if: - condition: - lambda: 'return id(action_state) == 2;' - then: - - light.turn_on: - id: rgbw_lightstrip1 - brightness: 40% - - if: - condition: - lambda: 'return id(action_state) == 3;' - then: - - light.turn_on: - id: rgbw_lightstrip1 - brightness: 15% - light: - - platform: rgbw - name: "rgbw_strip_01" - id: rgbw_lightstrip1 - red: output_red - green: output_green - blue: output_blue - white: output_white - - # Ensure the light turns on by default if the physical switch is actuated. - restore_mode: ALWAYS_OFF - -See Also --------- - -- :doc:`/components/light/rgbw` -- :doc:`/components/output/esp8266_pwm` -- :ghedit:`Edit` diff --git a/cookbook/uart_text_sensor.rst b/cookbook/uart_text_sensor.rst deleted file mode 100644 index 5278d8fb5ec..00000000000 --- a/cookbook/uart_text_sensor.rst +++ /dev/null @@ -1,126 +0,0 @@ -Custom UART Text Sensor -======================= - -.. seo:: - :description: Instructions for setting up a custom uart text sensor. - :image: language-cpp.svg - -Lots of devices communicate using the UART protocol. If you want to read -lines from uart to a Text Sensor you can do so using this code example. - -With this you can use automations or lambda to set switch or sensor states. - -.. code-block:: cpp - - #include "esphome.h" - - class UartReadLineSensor : public Component, public UARTDevice, public TextSensor { - public: - UartReadLineSensor(UARTComponent *parent) : UARTDevice(parent) {} - - void setup() override { - // nothing to do here - } - - int readline(int readch, char *buffer, int len) - { - static int pos = 0; - int rpos; - - if (readch > 0) { - switch (readch) { - case '\n': // Ignore new-lines - break; - case '\r': // Return on CR - rpos = pos; - pos = 0; // Reset position index ready for next time - return rpos; - default: - if (pos < len-1) { - buffer[pos++] = readch; - buffer[pos] = 0; - } - } - } - // No end of line has been found, so return -1. - return -1; - } - - void loop() override { - const int max_line_length = 80; - static char buffer[max_line_length]; - while (available()) { - if(readline(read(), buffer, max_line_length) > 0) { - publish_state(buffer); - } - } - } - }; - -(Store this file in your configuration directory, for example ``uart_read_line_sensor.h``) - -And in YAML: - -.. code-block:: yaml - - # Example configuration entry - esphome: - includes: - - uart_read_line_sensor.h - - logger: - level: VERBOSE #makes uart stream available in esphome logstream - baud_rate: 0 #disable logging over uart - - uart: - id: uart_bus - tx_pin: D0 - rx_pin: D1 - baud_rate: 9600 - - text_sensor: - - platform: custom - lambda: |- - auto my_custom_sensor = new UartReadLineSensor(id(uart_bus)); - App.register_component(my_custom_sensor); - return {my_custom_sensor}; - text_sensors: - id: "uart_readline" - -Example usage -------------- - -Here is an example switch using the uart text sensor to set switch state. - -Here we use interval to request status from the device. The response will be stored in uart text sensor. -Then the switch uses the text sensor state to set its own state. - -.. code-block:: yaml - - switch: - - platform: template - name: "Switch" - lambda: |- - if (id(uart_readline).state == "*POW=ON#") { - return true; - } else if(id(uart_readline).state == "*POW=OFF#") { - return false; - } else { - return {}; - } - turn_on_action: - - uart.write: "\r*pow=on#\r" - turn_off_action: - - uart.write: "\r*pow=off#\r" - - interval: - - interval: 10s - then: - - uart.write: "\r*pow=?#\r" - -See Also --------- - -- :doc:`/components/uart` -- :doc:`/custom/uart` -- :ghedit:`Edit` diff --git a/cookbook/zemismart-rgbw-downlights.rst b/cookbook/zemismart-rgbw-downlights.rst deleted file mode 100644 index 8cc9761f458..00000000000 --- a/cookbook/zemismart-rgbw-downlights.rst +++ /dev/null @@ -1,234 +0,0 @@ -Zemismart LED RGBW/RGBWW Downlights -=================================== - -The Zemismart LED RGBW Downlight is a Tuya-based downlight available from various retailers online or from `zemismart.com `__ direct. - -.. figure:: images/zemismart-rgbw-downlight.jpg - :align: center - :width: 50.0% - -Originally intended to be used with their companion app once flashed using `tuya-convert `__ ESPHome generated -firmware can be uploaded allowing you to control the smart plugs via Home Assistant. - -1. Create the ESPHome Firmware ------------------------------- - -#. Refer to either :doc:`/guides/getting_started_command_line` or :doc:`/guides/getting_started_hassio` before moving onto the next step. -#. Select a plug configuration below based on the plug/s you have and copy all of the text in the code block and paste into your - ``name_of_esphome_configuration.yaml`` file. -#. Compile the firmware, again depending on your chosen setup refer to the guides in the first point. - -2. Flashing ------------ - -2.1 Prerequisites -***************** - -#. Before you begin you'll need one of the following Linux machines running the latest copy of `Raspbian Stretch Lite - `__ - - a. Raspberry Pi 2B/B+ with `USB WiFi Dongle `__. - b. Raspberry Pi 3B/B+. - -.. note:: - - As per the `tuya-convert documentation `__: - - Any Linux with a Wifi adapter which can act as an Access Point should also work. Please note that we have tested the Raspberry Pi with clean installations - only. If you use your Raspberry Pi for anything else, we recommend using another SD card with a clean installation. - -#. A microSD card (minimum 2GB, 8GB+ recommended). -#. Any WiFi device which can connect to the SSID generated by the Raspberry Pi and eventually the flashed Tuya device. **This cannot be an iOS / Apple device. - Android devices will work.** - -2.2 Installing the OS -********************* - -#. It's recommended to read the documentation provided by the Raspberry Pi Foundation on the best way to flash the OS to the microSD card depending on your - platform - `Installing operating system images `__. -#. After you've flashed the microSD card browse to the "boot" partition and add a blank file called "ssh" **(without any extension)** which will enable the - SSH server upon first boot, extended information on this step can be found `here - `__. -#. Plug the microSD card into the Raspberry Pi, connect network cable and power, the Raspberry Pi will start to boot. - -2.3 Connecting to the Pi via SSH -******************************** - -#. Download and install `Putty `__. -#. Open Putty. -#. Enter the IP of Raspberry Pi in the box that says "Host Name", leaving the port set to 22 (default for SSH). A list of recommended ways can be found `here - `__, but the easiest is to download and use `Fing `__ - (`Android `__ / `iOS - `__). -#. In the "Saved Sessions" input box, name the Raspberry Pi connection and then press "Save". -#. Select your new saved session from the list. -#. Press "Open". - -2.4 Configuring the Pi -********************** - -#. In the putty window login with the **pi** as the user and **raspberry** for the password. -#. Type ``sudo apt-get update && sudo apt-get dist-upgrade -y`` and wait for the upgrades to install. -#. Type ``sudo apt-get install git`` and wait for it to install. - -2.5 Setup and Install tuya-convert -********************************** - -#. In the putty window type ``git clone https://github.com/ct-Open-Source/tuya-convert`` press enter and wait while the repository is cloned. -#. Type ``cd tuya-convert`` and press enter. -#. Type ``./install_prereq.sh`` press enter and wait as the script gathers all the required components needed to function. - -2.6 Upload ESPHome Firmware using SFTP -************************************** - -#. Download `FileZilla `__ or `WinSCP `__ or use your preferred FTP - client. -#. Depending on the program you need to connect to the Pi using the IP address as the hostname and the username and password the same as you used to connect - via SSH and ensure your connection type is set to **SFTP** -#. Browse to ``/root/tuya-convert/files``. -#. Upload your compiled ``firmware.bin`` file to this directory. For command line based installs you can access the file under - ``//.pioenvs//firmware.bin`` alternatively Home Assistant add-on users can download the file directly from the web UI. - -2.7 Use tuya-convert to install ESPHome Firmware -************************************************ - -#. Type ``./start_flash.sh`` -#. Type ``yes`` to accept the warning. -#. Connect your alternative WiFi device (non iOS / Apple based) to the ``vtrust-flash`` SSID using ``flashmeifyoucan`` as the password. This is the network - being broadcast by the Pi from the Tuya flash script. -#. If you haven't already plug your downlight into a power point and turn it on and follow the instructions below: - - #. Once turned on a stable white light will be emitted. - #. Switch off, then back on **3** times ensuring each off-on cycle is no longer 10 seconds apart and between each the light visibly turns off. - #. The light should have entered into a fast flashing state, if this is the case continue onto **Step 5** below. *Otherwise please turn the downlight off-on - within 3 minutes which will restore it back to a stable white light.* - - -#. Press enter on your putty window to start the flash process and wait. If the connection is successful you should see a large amount of scrolling text, this - is the script backing up the factory shipped firmware. -#. Once the process is complete you can type ``curl http://10.42.42.42/flashURL?url=http://10.42.42.1/files/firmware.bin`` -#. The plug will restart and if everything is working correctly after a few seconds you should be able to press the button triggering the relay and turning the - blue led on. - -3. Downlight Configuration --------------------------- - -Thanks to `@1972rx2 `__ for creating the below ESPHome configuration -which this cookbook article by `@cryptelli `__ is based on. - -Depending on the type of your light you either need a config using my9231 driver (RGBW) or 5 PWM channels (RGBWW). - -3.1 Zemismart LED RGBW Downlight YAML -************************************* - -.. code-block:: yaml - - esphome: - name: downlight01 - - esp8266: - board: esp01_1m - - wifi: - ssid: !secret wifi_ssid - password: !secret wifi_password - - # Enable logging - logger: - - # Enable Home Assistant API - api: - - ota: - - my9231: - data_pin: GPIO13 - clock_pin: GPIO15 - num_channels: 4 - num_chips: 1 - - output: - - platform: my9231 - id: output_blue - channel: 1 - - platform: my9231 - id: output_red - channel: 3 - - platform: my9231 - id: output_green - channel: 2 - - platform: my9231 - id: output_white - channel: 0 - - light: - - platform: rgbw - name: Downlight01 - red: output_red - green: output_green - blue: output_blue - white: output_white - -3.2. Zemismart LED RGBWw Downlight YAML -*************************************** - -Known devices: *Zemismart 2,5 zoll WiFi RGBW Led Downlight 7w* - -.. code-block:: yaml - - output: - - platform: esp8266_pwm - pin: 14 - id: output_blue - - platform: esp8266_pwm - pin: 12 - id: output_green - - platform: esp8266_pwm - pin: 4 - id: output_red - - platform: esp8266_pwm - pin: 5 - id: output_coldwhite - - platform: esp8266_pwm - pin: 13 - id: output_warmwhite - - light: - - platform: rgbww - name: '${device_name} Light' - default_transition_length: 0s - red: output_red - green: output_green - blue: output_blue - cold_white: output_coldwhite - warm_white: output_warmwhite - cold_white_color_temperature: 6500 K - warm_white_color_temperature: 2700 K - -4. Adding to Home Assistant ---------------------------- - -You can now add your downlight to Home Assistant using the below instructions: - -#. In the left hand sidebar, select **Configuration**. -#. Select **Integrations** -#. Click the **Orange** plus button *(lower right hand corner)* and look for **ESPHome** in the list of available integrations and select. -#. Type the host of the downlight, in most cases this is simply the IP address. -#. Leave the port set to the default of ``6053``. -#. Click **Submit** - -If you've gotten this far, congratulations! Below is the card you should see inside Home Assistant which allows you to control the downlight. - - -.. figure:: images/zemismart-rgbw-downlight-homeassistant.jpg - :align: center - :width: 50.0% - -See Also --------- - -- :doc:`/components/light/index` -- :doc:`/components/light/rgbw` -- :doc:`/components/output/index` -- :doc:`/components/output/my9231` -- :ghedit:`Edit` diff --git a/guides/automations.rst b/guides/automations.rst index 6383763640c..e53126a300f 100644 --- a/guides/automations.rst +++ b/guides/automations.rst @@ -332,7 +332,8 @@ All Triggers - :ref:`time.on_time ` / - :ref:`time.on_time_sync ` - :ref:`mqtt.on_message ` / :ref:`mqtt.on_json_message ` / :ref:`mqtt.on_connect / mqtt.on_disconnect ` -- :ref:`pn532.on_tag ` / :ref:`rdm6300.on_tag ` +- :ref:`pn532.on_tag ` / :ref:`pn532.on_tag_removed ` / :ref:`rc522.on_tag ` + / :ref:`rc522.on_tag_removed ` / :ref:`rdm6300.on_tag ` - :ref:`interval.interval ` - :ref:`switch.on_turn_on / switch.on_turn_off ` - :doc:`remote_receiver.on_* ` @@ -379,7 +380,8 @@ All Actions :ref:`sprinkler.pause ` / :ref:`sprinkler.resume ` / :ref:`sprinkler.resume_or_start_full_cycle ` / :ref:`sprinkler.queue_valve ` / :ref:`sprinkler.clear_queued_valves ` / :ref:`sprinkler.set_multiplier ` / - :ref:`sprinkler.set_repeat ` / :ref:`sprinkler.set_valve_run_duration ` + :ref:`sprinkler.set_repeat ` / :ref:`sprinkler.set_divider ` / + :ref:`sprinkler.set_valve_run_duration ` - :ref:`globals.set ` - :ref:`remote_transmitter.transmit_* ` - :ref:`climate.control ` diff --git a/guides/contributing.rst b/guides/contributing.rst index 93cc0d53146..2d7d5536c91 100644 --- a/guides/contributing.rst +++ b/guides/contributing.rst @@ -93,11 +93,11 @@ Build .. note:: - The easiest way is to use the `esphome-docs Docker image `__: + The easiest way is to use the `esphome-docs container image `__: .. code-block:: bash - docker run --rm -v "${PWD}/":/data/esphomedocs -p 8000:8000 -it esphome/esphome-docs + docker run --rm -v "${PWD}/":/data/esphomedocs -p 8000:8000 -it ghcr.io/esphome/esphome-docs With ``PWD`` referring to the root of the ``esphome-docs`` git repository. Then go to ``:8000`` in your browser. @@ -662,10 +662,10 @@ Standard for the esphome-core codebase: .. code-block:: bash # Full lint+test suite - docker run --rm -v "${PWD}/":/esphome -it esphome/esphome-lint script/fulltest + docker run --rm -v "${PWD}/":/esphome -it ghcr.io/esphome/esphome-lint script/fulltest # Run lint only over changed files - docker run --rm -v "${PWD}/":/esphome -it esphome/esphome-lint script/quicklint + docker run --rm -v "${PWD}/":/esphome -it ghcr.io/esphome/esphome-lint script/quicklint If you are using Windows and have docker installed the syntax is slightly different. @@ -676,7 +676,7 @@ Standard for the esphome-core codebase: # convert the volume format $current_dir=(Get-Location).Path.ToLower().Replace(':','').Replace('\','/') # Run lint only over changed files from powershell - docker run --rm -v "$($current_dir):/esphome" -it esphome/esphome-lint script/quicklint + docker run --rm -v "$($current_dir):/esphome" -it ghcr.io/esphome/esphome-lint script/quicklint diff --git a/guides/creators.rst b/guides/creators.rst index 4f7bc7189b4..134f2ce0e3e 100644 --- a/guides/creators.rst +++ b/guides/creators.rst @@ -7,6 +7,10 @@ Sharing ESPHome devices We have added configuration options to ESPHome to make it easier to create, configure, install and distribute devices running ESPHome. +No part of a "template" configuration should have any references to secrets, +or have passwords pre-applied. ESPHome makes it easy for the end-user to add these +themselves after they adopt the device into their own ESPHome dashboard. + Example configuration --------------------- @@ -14,10 +18,13 @@ Example configuration # These substitutions allow the end user to override certain values substitutions: - name: "project-template-32" + name: "project-template" + friendly_name: "Project Template" esphome: name: "${name}" + # Friendly names are used where appropriate in Home Assistant + friendly_name: "${friendly_name}" # Automatically add the mac address to the name # so you can use a single firmware for all devices name_add_mac_suffix: true @@ -50,9 +57,6 @@ Example configuration # In combination with the `ap` this allows the user # to provision wifi credentials to the device. captive_portal: - # Optionally, preserve provisioned credentials - # over subsequent OTA updates. - keep_user_credentials: true # Sets up Bluetooth LE (Only on ESP32) to allow the user # to provision wifi credentials to the device. diff --git a/guides/diy.rst b/guides/diy.rst index 5c328f1a1aa..b025b4531b2 100644 --- a/guides/diy.rst +++ b/guides/diy.rst @@ -122,3 +122,4 @@ Sample Configurations - `ESPHome Curtain/Cover/Shutter Switch from a noname Tuya switch `__ by :ghuser:`ludrao` - `ESPHome Free your Thomson Guardian gate controller `__ by :ghuser:`ludrao` - `Ambient Light Sensor tcs34725 example `__ by :ghuser:`RubenKelevra` +- `9 Valve Sprinkler Controller configuration `__ by :ghuser:`hwstar` diff --git a/guides/faq.rst b/guides/faq.rst index 3a064b783d2..aef2611181c 100644 --- a/guides/faq.rst +++ b/guides/faq.rst @@ -36,7 +36,7 @@ Tips for using ESPHome .. code-block:: yaml - - timing: !include click-single.yaml + - timing: !include click-single.yaml then: - mqtt.publish: topic: ${device_name}/button${id}/status @@ -158,7 +158,7 @@ It's simple. Run: pip3 install -U esphome # From docker: - docker pull esphome/esphome:latest + docker pull ghcr.io/esphome/esphome:stable And in Home Assistant, there's a simple UPDATE button when there's an update available as with all add-ons. @@ -178,7 +178,7 @@ by installing the tested beta: pip3 install --pre -U esphome # For docker-based installs - docker run [...] -it esphome/esphome:beta run livingroom.yaml + docker run [...] -it ghcr.io/esphome/esphome:beta run livingroom.yaml For Home Assistant supervised installs add the community addons beta repository by adding @@ -198,11 +198,11 @@ To install the dev version of ESPHome: - In Home Assistant: Add the ESPHome repository `https://github.com/esphome/home-assistant-addon `__ in Add-on store -> Repositories. Then install the add-on ``ESPHome Dev`` - From ``pip``: Run ``pip3 install https://github.com/esphome/esphome/archive/dev.zip`` -- From docker, use the `esphome/esphome:dev `__ image +- From docker, use the `ghcr.io/esphome/esphome:dev `__ image .. code-block:: bash - docker run [...] -it esphome:dev livingroom.yaml compile + docker run [...] -it ghcr.io/esphome/esphome:dev livingroom.yaml compile The latest dev docs are here: `next.esphome.io `__ @@ -305,37 +305,37 @@ Install versions: .. code-block:: bash # Stable Release - docker pull esphome/esphome + docker pull ghcr.io/esphome/esphome # Beta - docker pull esphome/esphome:beta + docker pull ghcr.io/esphome/esphome:beta # Dev version - docker pull esphome/esphome:dev + docker pull ghcr.io/esphome/esphome:dev Command reference: .. code-block:: bash # Start a new file wizard for file livingroom.yaml - docker run --rm -v "${PWD}":/config -it esphome/esphome wizard livingroom.yaml + docker run --rm -v "${PWD}":/config -it ghcr.io/esphome/esphome wizard livingroom.yaml # Compile and upload livingroom.yaml - docker run --rm -v "${PWD}":/config -it esphome/esphome run livingroom.yaml + docker run --rm -v "${PWD}":/config -it ghcr.io/esphome/esphome run livingroom.yaml # View logs - docker run --rm -v "${PWD}":/config -it esphome/esphome logs livingroom.yaml + docker run --rm -v "${PWD}":/config -it ghcr.io/esphome/esphome logs livingroom.yaml # Map /dev/ttyUSB0 into container - docker run --rm -v "${PWD}":/config --device=/dev/ttyUSB0 -it esphome/esphome ... + docker run --rm -v "${PWD}":/config --device=/dev/ttyUSB0 -it ghcr.io/esphome/esphome ... # Start dashboard on port 6052 (general command) # Warning: this command is currently not working with Docker on MacOS. (see note below) - docker run --rm -v "${PWD}":/config --net=host -it esphome/esphome + docker run --rm -v "${PWD}":/config --net=host -it ghcr.io/esphome/esphome # Start dashboard on port 6052 (MacOS specific command) - docker run --rm -p 6052:6052 -e ESPHOME_DASHBOARD_USE_PING=true -v "${PWD}":/config -it esphome/esphome + docker run --rm -p 6052:6052 -e ESPHOME_DASHBOARD_USE_PING=true -v "${PWD}":/config -it ghcr.io/esphome/esphome # Setup a bash alias: - alias esphome='docker run --rm -v "${PWD}":/config --net=host -it esphome/esphome' + alias esphome='docker run --rm -v "${PWD}":/config --net=host -it ghcr.io/esphome/esphome' And a docker compose file looks like this: @@ -345,7 +345,7 @@ And a docker compose file looks like this: services: esphome: - image: esphome/esphome + image: ghcr.io/esphome/esphome volumes: - ./:/config:rw # Use local time for logging timestamps @@ -356,7 +356,7 @@ And a docker compose file looks like this: - /dev/ttyACM0:/dev/ttyACM0 network_mode: host restart: always - + .. _docker-reference-notes: .. note:: @@ -420,7 +420,7 @@ If an external pullup/down changes the configured voltage levels boot failures o While the use of them in software is not a problem, if there's something attached to the pins (particularly if they're not floating during the bootup) you may run into problems. It's recommended to avoid them unless you have a pressing need to use them and you have reviewed the expected boot voltage levels of these pins from the ESP datasheet. -Some development boards connect GPIO 0 to a button, often labeled "boot". Holding this button while the ESP is turning on will cause it to go into bootloader mode. Once the ESP is fully booted up, this button can be used as a normal input safely. +Some development boards connect GPIO 0 to a button, often labeled "boot". Holding this button while the ESP is turning on will cause it to go into bootloader mode. Once the ESP is fully booted up, this button can be used as a normal input safely. How can I test a Pull Request? ------------------------------ diff --git a/guides/getting_started_command_line.rst b/guides/getting_started_command_line.rst index ca025755399..a58ed579893 100644 --- a/guides/getting_started_command_line.rst +++ b/guides/getting_started_command_line.rst @@ -14,15 +14,15 @@ Installation See :doc:`installing_esphome`. -If you're familiar with Docker, you can use that instead! -Note that on macOS Docker `can not pass USB devices through `__. +If you're familiar with Docker, you can use that instead! +Note that on macOS Docker `can not pass USB devices through `__. You will not be able to flash ESP devices through USB on Mac, all other features will work. Flashing with web dashboard is still possible. Our image supports AMD64, ARM and ARM64 (AARCH64), and can be downloaded with: .. code-block:: bash - docker pull esphome/esphome + docker pull ghcr.io/esphome/esphome If you want to use `docker-compose` instead, here's a sample file: @@ -32,7 +32,7 @@ If you want to use `docker-compose` instead, here's a sample file: services: esphome: container_name: esphome - image: esphome/esphome + image: ghcr.io/esphome/esphome volumes: - /path/to/esphome/config:/config - /etc/localtime:/etc/localtime:ro @@ -80,7 +80,7 @@ file called ``livingroom.yaml``: esphome wizard livingroom.yaml # On Docker: - docker run --rm -v "${PWD}":/config -it esphome/esphome wizard livingroom.yaml + docker run --rm -v "${PWD}":/config -it ghcr.io/esphome/esphome wizard livingroom.yaml At the end of this step, you will have your first YAML configuration file ready. It doesn't do much yet and only makes your device connect to @@ -133,7 +133,7 @@ to your docker command to map a local USB device. Docker on Mac will not be able .. code-block:: bash - docker run --rm --privileged -v "${PWD}":/config --device=/dev/ttyUSB0 -it esphome/esphome run livingroom.yaml + docker run --rm --privileged -v "${PWD}":/config --device=/dev/ttyUSB0 -it ghcr.io/esphome/esphome run livingroom.yaml Now when you go to the Home Assistant "Integrations" screen (under "Configuration" panel), you should see the ESPHome device show up in the discovered section (although this can take up to 5 minutes). @@ -179,7 +179,7 @@ for docker you need to supply an additional parameter: esphome livingroom.yaml run # On docker - docker run --rm -v "${PWD}":/config -it esphome/esphome run livingroom.yaml + docker run --rm -v "${PWD}":/config -it ghcr.io/esphome/esphome run livingroom.yaml .. figure:: /components/binary_sensor/images/gpio-ui.png @@ -215,11 +215,11 @@ To start the ESPHome dashboard, simply start ESPHome with the following command esphome dashboard config/ # On Docker, host networking mode is required for online status indicators - docker run --rm --net=host -v "${PWD}":/config -it esphome/esphome + docker run --rm --net=host -v "${PWD}":/config -it ghcr.io/esphome/esphome # On Docker with MacOS, the host networking option doesn't work as expected. An # alternative is to use the following command if you are a MacOS user. - docker run --rm -p 6052:6052 -e ESPHOME_DASHBOARD_USE_PING=true -v "${PWD}":/config -it esphome/esphome + docker run --rm -p 6052:6052 -e ESPHOME_DASHBOARD_USE_PING=true -v "${PWD}":/config -it ghcr.io/esphome/esphome After that, you will be able to access the dashboard through ``localhost:6052``. diff --git a/guides/getting_started_hassio.rst b/guides/getting_started_hassio.rst index 271358796f1..f5ffa51344d 100644 --- a/guides/getting_started_hassio.rst +++ b/guides/getting_started_hassio.rst @@ -78,7 +78,14 @@ in ``/config/esphome/garage-door.yaml``. .. note:: - Since Home Assistant add-ons run as individual containers, accessing these through command line is not very straightforward, but it's possible. To do that, install Home Assistant's SSH addon, configure a username and a password, and disable `Protection Mode` (please assess the risks you take with that). Then, for example to access the logs form a device through an SSH client, log in, and you can use a command like `docker exec -it addon_15ef4d2f_esphome esphome logs /config/esphome/garage-door.yaml`. See :doc:`getting_started_command_line` for more. + Since Home Assistant add-ons run as individual containers, accessing these through + command line is not very straightforward, but it's possible. To do that, + install Home Assistant's SSH addon, configure a username and a password, + and disable `Protection Mode` (please assess the risks you take with that). + Then, for example to access the logs form a device through an SSH client, + log in, and you can use a command like + `docker exec -it addon_15ef4d2f_esphome esphome logs /config/esphome/garage-door.yaml`. + See :doc:`getting_started_command_line` for more. Now go ahead and use one of the :ref:`devices guides ` to extend your configuration. diff --git a/guides/made_for_esphome.rst b/guides/made_for_esphome.rst index 3c7ec61cefa..83f9d8d0269 100644 --- a/guides/made_for_esphome.rst +++ b/guides/made_for_esphome.rst @@ -17,11 +17,13 @@ Requirements Your product has to match the following requirements: - Your project is powered by ESPHome + - Your project is powered by an ESP32 - Your ESPHome configuration is open source - Users should be able to apply updates if your project sells ready-made devices - Your project supports adoption via the ``dashboard_import`` feature of ESPHome (see :doc:`Sharing `) - Your product name cannot contain **ESPHome** except in the case of *ending with* **for ESPHome** + - Your configuration utilises ``esp32_improv`` and ``improv_serial`` (if a USB connection is available) for easy end-user provisioning. When your project matches all requirements of the Made for ESPHome program, you can apply for permission to carry the logo by emailing esphome@nabucasa.com diff --git a/guides/supporters.rst b/guides/supporters.rst index b9b6310c8d6..4c0d6ef55ad 100644 --- a/guides/supporters.rst +++ b/guides/supporters.rst @@ -16,9 +16,9 @@ Contributors (in alphabetical order) +- `007hacky007 (@007hacky007) `__ - `0hax (@0hax) `__ - `0x0a11c0de (@0x0a11c0de) `__ -- `Tercio Filho (@0x3333) `__ - `Denis Bodor (aka Lefinnois) (@0xDRRB) `__ - `2016for (@2016for) `__ - `2mikrobi (@2mikrobi) `__ @@ -27,9 +27,12 @@ Contributors - `Alessandro Campolo (@a13ssandr0) `__ - `Aalian Khan (@AalianKhan) `__ - `Adam Liddell (@aaliddell) `__ +- `Aaron Gamble (@aarongamble) `__ +- `Aaron S. Jackson (@AaronJackson) `__ - `Abel Matser (@abelmatser) `__ - `Abílio Costa (@abmantis) `__ - `Antonio (@acarvajalperez) `__ +- `Avula Chandra Kiran Reddy (@ackr-8) `__ - `Zhenyu Wu (@Adam5Wu) `__ - `Chris Byrne (@adapt0) `__ - `Attila Darazs (@adarazs) `__ @@ -41,8 +44,12 @@ Contributors - `Stefan Agner (@agners) `__ - `Anders (@ahd71) `__ - `Alexander Pohl (@ahpohl) `__ +- `aidbish (@aidbish) `__ - `Airy André (@airy10) `__ +- `Airyzz (@Airyzz) `__ +- `Adam Jacques (@ajacques) `__ - `Andrej Friesen (@ajfriesen) `__ +- `akennerly (@akennerly) `__ - `akoivist (@akoivist) `__ - `Andrej Komelj (@akomelj) `__ - `Alex Konradi (@akonradi) `__ @@ -52,17 +59,22 @@ Contributors - `Alex (@alex-richards) `__ - `Alexander Leisentritt (@Alex9779) `__ - `Alex Barcelo (@alexbarcelo) `__ +- `AlexCPU (@AlexCPU) `__ - `Alexandre Danault (@AlexDanault) `__ - `Alex Iribarren (@alexiri) `__ - `Alex Mekkering (@AlexMekkering) `__ - `Alex (@alexyao2015) `__ +- `Alfredo (@alfredopironti) `__ - `Andreas Mandel (@amandel) `__ - `Amish Vishwakarma (@amishv) `__ +- `Amit Keret (@amitkeret) `__ - `Jason Nader (@ammgws) `__ - `Branden Cash (@ammmze) `__ - `Alexander Momchilov (@amomchilov) `__ - `anatoly-savchenkov (@anatoly-savchenkov) `__ - `andig (@andig) `__ +- `Andi Egli (@andilge) `__ +- `Kieren (@ando023) `__ - `András Bíró (@andrasbiro) `__ - `Andreas Hergert (@andreashergert1984) `__ - `Andrew J.Swan (@andrewjswan) `__ @@ -71,13 +83,17 @@ Contributors - `Andrzej (@andriej) `__ - `Andreas (@anduchs) `__ - `Andy2No (@Andy2No) `__ +- `AndyRPH (@AndyRPH) `__ - `Vegetto (@angelnu) `__ - `Sergey Anisimov (@anisimovsergey) `__ - `Nikolay Vasilchuk (@Anonym-tsk) `__ +- `Anthony Keane (@anthonykeane) `__ +- `Rémi K. (@antibill51) `__ - `Antonio Fiol (@antonio-fiol) `__ - `Adriaan Peeters (@apeeters) `__ - `apendley (@apendley) `__ - `Darius Ratkevičius (@aphex008) `__ +- `aquaticus (@aquaticus) `__ - `Andy Allsopp (@arallsopp) `__ - `arantius (@arantius) `__ - `arturo182 (@arturo182) `__ @@ -85,53 +101,75 @@ Contributors - `Arya (@Arya11111) `__ - `Borys Pierov (@ashald) `__ - `Ash McKenzie (@ashmckenzie) `__ +- `ashp8i (@ashp8i) `__ - `Ashton Kemerling (@AshtonKem) `__ - `杨成锴 (@asjdf) `__ - `Pavel Pletenev (@ASMfreaK) `__ - `Andreas Soehlke (@asoehlke) `__ - `Mike Dunston (@atanisoft) `__ +- `Glenn Morrison (@atomicpapa) `__ +- `Alexander Turlov (@aturlov) `__ +- `aus (@aus) `__ - `AustinMorris (@AustinMorris) `__ - `Avirsaam (@Avirsaam) `__ - `Arsène von Wyss (@avonwyss) `__ +- `Andrew Weddle (@aweddle2) `__ - `Achilleas Pipinellis (@axilleas) `__ - `Kamil Trzciński (@ayufan) `__ - `Nicholas Peters (@Azimath) `__ - `Daniel (@azrael783) `__ +- `B48D81EFCC (@B48D81EFCC) `__ - `Florian Mösch (@badbadc0ffee) `__ +- `Baden (@baden03) `__ - `Marco Tombesi (@baggior) `__ - `balk77 (@balk77) `__ - `Paulus Schoutsen (@balloob) `__ - `Andrew Zaborowski (@balrog-kun) `__ - `BarryMar (@BarryMar) `__ +- `bartoszpierzchlewicz (@bartoszpierzchlewicz) `__ +- `BartoszPierzchlewiczMacrix (@BartoszPierzchlewiczMacrix) `__ - `Bascht74 (@Bascht74) `__ - `Viktr (@BbIKTOP) `__ - `J. Nick Koston (@bdraco) `__ - `Maxim Ocheretianko (@bearpawmaxim) `__ +- `beaudeanadams (@beaudeanadams) `__ - `Benjamin Freeman (@Beetix) `__ +- `beikeland (@beikeland) `__ +- `Ben-Schwabe (@Ben-Schwabe) `__ +- `Ben Hoff (@benhoff) `__ - `Benno Pütz (@bennop) `__ - `Benoit3 (@Benoit3) `__ +- `Ben Shaner (@bens545) `__ - `Ben Suffolk (@bensuffolk) `__ +- `Berend Haan (@berendhaan) `__ - `Arturo Casal (@berfenger) `__ - `Bryan Berg (@berg) `__ - `Bert Hertogen (@berthertogen) `__ - `Ivan Bessarabov (@bessarabov) `__ - `Brandon (@bgulla) `__ +- `Benedikt Hübschen (@bhuebschen) `__ - `Bierchermuesli (@Bierchermuesli) `__ - `Bill Church (@billchurch) `__ - `Brian Kaufman (@bkaufx) `__ - `JDavid (@blackhack) `__ - `blakadder (@blakadder) `__ - `Branimir Lambov (@blambov) `__ +- `bleeisme (@bleeisme) `__ - `Jim Ekman (@blejdfist) `__ - `Scott Smith (@blurfl) `__ - `Bob (@Bmooij) `__ - `Benjamin Klotz (@bnw) `__ +- `Bob Kersten (@bobkersten) `__ - `Bodmer (@Bodmer) `__ +- `Anthony Todd (@bohregard) `__ +- `Bomaker (@Bomaker) `__ - `Mauricio Bonani (@bonanitech) `__ - `Casey Olson (@bookcasey) `__ +- `Borja Burgos (@borjaburgos) `__ - `BoukeHaarsma23 (@BoukeHaarsma23) `__ - `brambo123 (@brambo123) `__ - `Bram Kragten (@bramkragten) `__ +- `Brandan Cotton (@Brando47) `__ - `Brad Davidson (@brandond) `__ - `Daniel H Brown (@brauhausdc) `__ - `Jens Bretschneider (@breti) `__ @@ -141,35 +179,52 @@ Contributors - `brianrjones69 (@brianrjones69) `__ - `Ben Brooks (@brooksben11) `__ - `buddydvd (@buddydvd) `__ +- `Matt Burke (@burkemw3) `__ - `Jon Little (@burundiocibu) `__ - `buxtronix (@buxtronix) `__ - `bvansambeek (@bvansambeek) `__ +- `c0ffeeca7 (@c0ffeeca7) `__ +- `Captain Haddock (@ca-haddock) `__ - `Cal Howard (@calhoward) `__ +- `callacomp (@callacomp) `__ +- `Callum Gare (@callumgare) `__ - `Carlos Gustavo Sarmiento (@carlos-sarmiento) `__ - `Carlos Garcia Saura (@CarlosGS) `__ - `Carlos Ruiz (@CarlosRDomin) `__ +- `carlywarly (@carlywarly) `__ - `carstenschroeder (@carstenschroeder) `__ - `Valentin Ochs (@Cat-Ion) `__ - `Stroe Andrei Catalin (@catalin2402) `__ - `cbialobos (@cbialobos) `__ +- `Cameron Bulock (@cbulock) `__ - `Ciprian Constantinescu (@cciprian5) `__ +- `cdmonk (@cdmonk) `__ +- `ceaswaran (@ceaswaran) `__ - `Cellie (@CelliesProjects) `__ - `Chris Feenstra (@cfeenstra1024) `__ +- `cg089 (@cg089) `__ - `Kostas Chatzikokolakis (@chatziko) `__ +- `Audric Schiltknecht (@chemicalstorm) `__ - `chris-jennings (@chris-jennings) `__ - `Chris (@chrismaki) `__ +- `Christoph Wagner (@Christoph-Wagner) `__ - `Christian Taedcke (@chrta) `__ - `Pavel Skuratovich (@Chupaka) `__ - `Chris Johnson (@ciband) `__ +- `CircuitGuy (@CircuitGuy) `__ - `John (@CircuitSetup) `__ - `Colby Rome (@cisasteelersfan) `__ - `Chris Debenham (@cjd) `__ - `Chester (@clowrey) `__ +- `Colin McCambridge (@cmccambridge) `__ - `Clifford Roche (@cmroche) `__ - `Casey Burnett (@codeangler) `__ - `CODeRUS (@CODeRUS) `__ +- `Alex Miller (@Codex-) `__ - `Cody James (@codyjamestechnical) `__ +- `Ashton Lafferty (@cogneato) `__ - `Colin Leroy-Mira (@colinleroy) `__ +- `Max (@coltoncat) `__ - `Conclusio (@Conclusio) `__ - `John Coggeshall (@coogle) `__ - `James Crook (@cooljimy84) `__ @@ -182,22 +237,31 @@ Contributors - `Connor Prussin (@cprussin) `__ - `Corey Rice (@crice009) `__ - `cryptelli (@cryptelli) `__ +- `Christian Schwarzgruber (@cslux) `__ - `cstaahl (@cstaahl) `__ - `Chris Talkington (@ctalkington) `__ - `Massimo Cetra (@ctrix) `__ - `cvwillegen (@cvwillegen) `__ - `Christoph Wempe (@CWempe) `__ +- `Steven Webb (@cy1701) `__ - `Alex Solomaha (@CyanoFresh) `__ - `Luar Roji (@cyberplant) `__ +- `Petr Diviš (@czechdude) `__ - `Aleš Komárek (@cznewt) `__ +- `d-rez (@d-rez) `__ - `Dale Higgs (@dale3h) `__ - `damanti-me (@damanti-me) `__ +- `Dan C Williams (@dancwilliams) `__ - `Daniel Bjørnbakk (@danibjor) `__ - `Daniel Kucera (@danielkucera) `__ +- `Daniel O'Connor (@DanielO) `__ - `Daniel Rheinbay (@danielrheinbay) `__ - `Daniel Schramm (@danielschramm) `__ +- `Daniel Martin Gonzalez (@danimart1991) `__ +- `danlimlu (@danlimlu) `__ - `Chris (@darthsebulba04) `__ - `Dan Gentry (@dashdrum) `__ +- `Aliasghar Dashkhaneh (@dashkhaneh) `__ - `Anthony Uk (@dataway) `__ - `Dav-id (@dav-id-org) `__ - `DAVe3283 (@DAVe3283) `__ @@ -206,13 +270,17 @@ Contributors - `Dave Wongillies (@davewongillies) `__ - `David De Sloovere (@DavidDeSloovere) `__ - `David Beitey (@davidjb) `__ +- `David Newgas (@davidn) `__ +- `David Noyes (@davidnoyes) `__ - `David Zovko (@davidzovko) `__ - `Davy Landman (@DavyLandman) `__ +- `Dawid Cieszyński (@dawidcieszynski) `__ - `Darren Tucker (@daztucker) `__ - `Donovan Baarda (@dbaarda) `__ - `David Buezas (@dbuezas) `__ - `dckiller51 (@dckiller51) `__ - `Daniel Correa Lobato (@dclobato) `__ +- `DeadEnd (@DeadEnded) `__ - `Debashish Sahu (@debsahu) `__ - `declanshanaghy (@declanshanaghy) `__ - `Maximilian (@DeerMaximum) `__ @@ -224,12 +292,13 @@ Contributors - `Davide Depau (@depau) `__ - `dependabot[bot] (@dependabot[bot]) `__ - `Joeri Colman (@depuits) `__ -- `Stephan Martin (@designer2k2) `__ - `Destix (@Destix) `__ - `Deun Lee (@deunlee) `__ - `Develo (@devyte) `__ - `Dezorian (@Dezorian) `__ +- `Damian Gołda (@dgolda) `__ - `Dan Halbert (@dhalbert) `__ +- `Dustin L. Howett (@DHowett) `__ - `Alain Turbide (@Dilbert66) `__ - `Mark (@Diramu) `__ - `Dirk Heinke (@DirkHeinke) `__ @@ -243,21 +312,27 @@ Contributors - `DrZoid (@docteurzoidberg) `__ - `Dominik (@DomiStyle) `__ - `Derek M. (@doolbneerg) `__ +- `Dorian Zedler (@dorianim) `__ - `Mark Dietzer (@Doridian) `__ - `Jiang Sheng (@doskoi) `__ +- `Artem Sheremet (@dotdoom) `__ - `Robert Schütz (@dotlambda) `__ - `Daniel Hyles (@DotNetDann) `__ - `dr-oblivium (@dr-oblivium) `__ - `Drew Perttula (@drewp) `__ - `drmpf (@drmpf) `__ +- `drogfild (@drogfild) `__ - `DrRob (@DrRob) `__ - `Daniel Müller (@dtmuller) `__ +- `Tom Soer (@dtx3k) `__ - `dubit0 (@dubit0) `__ - `Mikkel Jeppesen (@Duckle29) `__ - `Sergey V. DUDANOV (@dudanov) `__ - `David Girón (@duhow) `__ - `Duncan Findlay (@duncf) `__ - `Jannick (@DutchDeffy) `__ +- `David van der Leij (@dvanderleij) `__ +- `dxta1986 (@dxta1986) `__ - `dyarkovoy (@dyarkovoy) `__ - `Janez Troha (@dz0ny) `__ - `Dimitris Zervas (@dzervas) `__ @@ -270,10 +345,13 @@ Contributors - `Eduardo Pérez (@eduperez) `__ - `Eenoo (@Eenoo) `__ - `Eli Fidler (@efidler) `__ +- `egandro (@egandro) `__ - `Erwin Kooi (@egeltje) `__ - `Eike (@ei-ke) `__ - `Elazar Leibovich (@elazarl) `__ +- `Eli Yu (@elizhyu) `__ - `Elkropac (@Elkropac) `__ +- `Elliot Wood (@elliot-wood) `__ - `Joakim Plate (@elupus) `__ - `EmbeddedDevver (@EmbeddedDevver) `__ - `EmmanuelLM (@EmmanuelLM) `__ @@ -284,10 +362,12 @@ Contributors - `Bert (@Engelbert) `__ - `Nico Weichbrodt (@envy) `__ - `Evan Petousis (@epetousis) `__ +- `Josh Gwosdz (@erdii) `__ - `Eric Coffman (@ericbrian) `__ - `Eric Hiller (@erichiller) `__ - `Matt Hamilton (@Eriner) `__ - `Ernst Klamer (@Ernst79) `__ +- `Eduardo Roldan (@eroldan) `__ - `escoand (@escoand) `__ - `Eric Severance (@esev) `__ - `esphomebot (@esphomebot) `__ @@ -297,19 +377,27 @@ Contributors - `Evgeni Golov (@evgeni) `__ - `Expaso (@Expaso) `__ - `Malte Franken (@exxamalte) `__ +- `f0rdprefect (@f0rdprefect) `__ - `Fabian Affolter (@fabaff) `__ +- `Fabian (@Fabian-Schmidt) `__ - `Federico Ariel Castagnini (@facastagnini) `__ - `C W (@fake-name) `__ - `Florian idB (@fbeek) `__ - `Fabian Berthold (@fbrthld) `__ +- `felixlungu (@felixlungu) `__ - `Felix Storm (@felixstorm) `__ - `Christian Ferbar (@ferbar) `__ - `FeuerSturm (@FeuerSturm) `__ +- `Florian Golemo (@fgolemo) `__ - `Frank Riley (@fhriley) `__ +- `finity69x2 (@finity69x2) `__ - `Frédéric Jouault (@fjouault) `__ - `Sean Vig (@flacjacket) `__ - `Diego Elio Pettenò (@Flameeyes) `__ - `Flaviu Tamas (@flaviut) `__ +- `fluffymadness (@fluffymadness) `__ +- `fluffymonster (@fluffymonster) `__ +- `flyize (@flyize) `__ - `风飘雨 (@flyrainning) `__ - `Fractal147 (@Fractal147) `__ - `Francis-labo (@Francis-labo) `__ @@ -322,9 +410,9 @@ Contributors - `Evgeny (@freekode) `__ - `Brett McKenzie (@freerangeeggs) `__ - `Franck Nijhof (@frenck) `__ +- `Kenneth Fribert (@fribse) `__ - `frippe75 (@frippe75) `__ - `Fritz Mueller (@fritzm) `__ -- `Marc Egli (@frog32) `__ - `Florian Trück (@ftrueck) `__ - `functionpointer (@functionpointer) `__ - `mr G1K (@G1K) `__ @@ -334,12 +422,16 @@ Contributors - `gazoodle (@gazoodle) `__ - `GeekVisit (@GeekVisit) `__ - `Ian Reinhart Geiser (@geiseri) `__ +- `R Huish (@genestealer) `__ - `Geoff Davis (@geoffdavis) `__ - `Geoffrey Van Landeghem (@geoffrey-vl) `__ - `Gérald Guiony (@gerald-guiony) `__ - `Gerard (@gerard33) `__ - `Giampiero Baggiani (@giampiero7) `__ +- `Gideon Kanikevich (@gid204) `__ +- `Giel Janssens (@gieljnssns) `__ - `Giovanni (@Gio-dot) `__ +- `GitforZhangXL (@GitforZhangXL) `__ - `github-actions[bot] (@github-actions[bot]) `__ - `gitolicious (@gitolicious) `__ - `The Gitter Badger (@gitter-badger) `__ @@ -350,47 +442,62 @@ Contributors - `Germain Masse (@gmasse) `__ - `Garret Buell (@gmbuell) `__ - `Jelle Raaijmakers (@GMTA) `__ +- `Go0oSer (@Go0oSer) `__ - `Gonzalo Paniagua Javier (@gonzalop) `__ - `gordon-zhao (@gordon-zhao) `__ - `Gustavo Ambrozio (@gpambrozio) `__ +- `Granville Barker (@granvillebarker) `__ - `Antoine GRÉA (@grea09) `__ +- `Greg Arnold (@GregJArnold) `__ +- `Greg MacLellan (@gregmac) `__ - `Gil Peeters (@grillp) `__ - `George (@grob6000) `__ -- `Stefan Grufman (@GruffyPuffy) `__ +- `groovejumper (@groovejumper) `__ - `gsexton (@gsexton) `__ - `Gabriel Sieben (@gsieben) `__ - `Jadson Santos (@gtjadsonsantos) `__ +- `guardmedia (@guardmedia) `__ - `Guillaume DELVIT (@guiguid) `__ - `guillempages (@guillempages) `__ - `Guyohms (@Guyohms) `__ - `Gilles van den Hoven (@gvdhoven) `__ +- `h0jeZvgoxFepBQ2C (@h0jeZvgoxFepBQ2C) `__ - `h3ndrik (@h3ndrik) `__ +- `Andi (@h4de5) `__ - `haade (@haade-administrator) `__ - `Peter van Dijk (@Habbie) `__ - `Hagai Shatz (@hagai-shatz) `__ - `Boris Hajduk (@hajdbo) `__ - `Gavin Mogan (@halkeye) `__ - `Charles (@hallard) `__ +- `Alex Griffith (@halomademeapc) `__ +- `Aniket (@HandyHat) `__ - `Charles Thompson (@haryadoon) `__ - `Ha Thach (@hathach) `__ - `hcoohb (@hcoohb) `__ - `Héctor Giménez (@hectorgimenez) `__ - `Jimmy Hedman (@HeMan) `__ +- `Hemi03 (@Hemi03) `__ - `HepoH3 (@HepoH3) `__ - `Hermann Kraus (@herm) `__ +- `Herr Frei (@herrfrei) `__ +- `highground88 (@highground88) `__ - `Hamish Moffatt (@hmoffatt) `__ - `Marcel Hoppe (@hobbypunk90) `__ -- `Sebastian Raff (@hobbyquaker) `__ - `MoA (@honomoa) `__ - `Hopperpop (@Hopperpop) `__ - `Yang Hau (@howjmay) `__ +- `hpineapples (@hpineapples) `__ - `Antonio Vanegas (@hpsaturn) `__ - `hreintke (@hreintke) `__ - `Jan Hubík (@hubikj) `__ - `Huub Eikens (@huubeikens) `__ - `Steve Rodgers (@hwstar) `__ +- `hificat (@hzkincony) `__ - `Arjan Filius (@iafilius) `__ +- `Iain Hay (@IainPHay) `__ - `Adrián Panella (@ianchi) `__ +- `Ian Anderson (@ianderso) `__ - `Ian Leeder (@ianleeder) `__ - `Jan Pobořil (@iBobik) `__ - `igg (@igg) `__ @@ -398,27 +505,38 @@ Contributors - `Petko Bordjukov (@ignisf) `__ - `ikatkov (@ikatkov) `__ - `iKK001 (@iKK001) `__ +- `ilium007 (@ilium007) `__ - `imgbot[bot] (@imgbot[bot]) `__ - `ImSorryButWho (@ImSorryButWho) `__ -- `Lorenzo Ortiz (@Infinitte) `__ - `Dom (@Ing-Dom) `__ +- `Ingo Becker (@ingobecker) `__ - `Ingurum (@Ingurum) `__ +- `IoT-devices LLC (@iotdevicesdev) `__ - `Ivo Roefs (@ironirc) `__ - `irtimaled (@irtimaled) `__ - `Ingo Theiss (@itn3rd77) `__ - `Ivan Shvedunov (@ivan4th) `__ - `Ivan Kravets (@ivankravets) `__ +- `Ivan Lisenkov (@ivlis) `__ - `Ivo-tje (@Ivo-tje) `__ +- `J0RD4N300 (@J0RD4N300) `__ +- `Fredrik Gustafsson (@jagheterfredrik) `__ - `Jan Harkes (@jaharkes) `__ +- `Jake Shirley (@JakeShirley) `__ - `Jakob Reiter (@jakommo) `__ - `James Braid (@jamesbraid) `__ - `James Duke (@jamesduke) `__ - `James Gao (@jamesgao) `__ +- `James Hirka (@jameshirka) `__ - `James Lakin (@jamesorlakin) `__ +- `James Swift (@JamesSwift) `__ +- `Jason (@jamman9000) `__ - `Juraj Andrássy (@JAndrassy) `__ +- `Delio Castillo (@jangeador) `__ - `Jan Grewe (@jangrewe) `__ - `János Rusiczki (@janosrusiczki) `__ - `Jan Pieper (@janpieper) `__ +- `Jared Ring (@jaredring) `__ - `Jarek.P (@JaroslawPrzybyl) `__ - `Jason-nz (@Jason-nz) `__ - `Jason2866 (@Jason2866) `__ @@ -439,6 +557,7 @@ Contributors - `Jeff Rescignano (@JeffResc) `__ - `Jej (@jej) `__ - `Jens-Christian Skibakk (@jenscski) `__ +- `Jeremy Willans (@jeremywillans) `__ - `Jeroen (@jeroen85) `__ - `Jérôme Laban (@jeromelaban) `__ - `Jesse Hills (@jesserockz) `__ @@ -447,6 +566,7 @@ Contributors - `Jan Pieter Waagmeester (@jieter) `__ - `Jim Bauwens (@jimbauwens) `__ - `jimtng (@jimtng) `__ +- `jivesinger (@jivesinger) `__ - `Jérémy JOURDIN (@JJK801) `__ - `Jonathan Jefferies (@jjok) `__ - `John K. Luebs (@jkl1337) `__ @@ -454,24 +574,32 @@ Contributors - `Jeppe Ladefoged (@jladefoged) `__ - `Jean-Luc Béchennec (@jlbirccyn) `__ - `Jonas De Kegel (@jlsjonas) `__ +- `Jeff Anderson (@jman203) `__ - `Jonathan Martens (@jmartens) `__ +- `jmichiel (@jmichiel) `__ +- `Jonathas Barbosa (@jnthas) `__ - `Joe Gross (@joegross) `__ - `Johan van der Kuijl (@johanvanderkuijl) `__ - `Johboh (@Johboh) `__ - `John Britton (@johndbritton) `__ - `John Erik Halse (@johnerikhalse) `__ - `John Moxley (@johnmoxley) `__ +- `Dave Johnston (@johnsto) `__ +- `joiboi (@joiboi) `__ - `JonasEr (@JonasEr) `__ - `Jonathan Adams (@jonathanadams) `__ - `Jonathan Treffler (@JonathanTreffler) `__ - `JonnyaiR (@jonnyair) `__ - `Jonathan V (@jonofmac) `__ - `Joppy (@JoppyFurr) `__ +- `Jared Sanson (@jorticus) `__ - `Joshua Spence (@joshuaspence) `__ +- `joskfg (@joskfg) `__ - `Joscha Wagner (@jowgn) `__ - `Javier Peletier (@jpeletier) `__ - `jsuanet (@jsuanet) `__ - `James Szalay (@jtszalay) `__ +- `Jules-R (@Jules-R) `__ - `Julie Koubová (@juliekoubova) `__ - `Justahobby01 (@Justahobby01) `__ - `Mike Ryan (@justfalter) `__ @@ -482,9 +610,12 @@ Contributors - `Jack Wozny (@jwozny) `__ - `Jozef Zuzelka (@jzlka) `__ - `Kris (@K-r-i-s-t-i-a-n) `__ +- `k0rtina (@k0rtina) `__ - `Harald Nagel (@k7hpn) `__ - `kaegi (@kaegi) `__ - `kahrendt (@kahrendt) `__ +- `Kamahat (@kamahat) `__ +- `Karl0ss (@karl0ss) `__ - `Karol Zlot (@karolzlot) `__ - `Kattni (@kattni) `__ - `Krasimir Nedelchev (@kaykayehnn) `__ @@ -492,16 +623,25 @@ Contributors - `Keilin Bickar (@kbickar) `__ - `Keith Burzinski (@kbx81) `__ - `Ken Piper (@Kealper) `__ -- `Robert Kiss (@kepten) `__ +- `Kelvie Wong (@kelvie) `__ +- `Kenny Stier (@KennyStier) `__ +- `kernelpanic85 (@kernelpanic85) `__ - `Kevin O'Rourke (@kevinior) `__ +- `kevlar10 (@kevlar10) `__ +- `kfulko (@kfulko) `__ +- `Kai Gerken (@KG3RK3N) `__ +- `kghandi (@kghandi) `__ - `Khoi Hoang (@khoih-prog) `__ +- `Kilowatt (@Kilowatt-W) `__ - `Ed (@kixtarter) `__ - `Kurt Kellner (@kkellner) `__ - `Klaas Schoute (@klaasnicolaas) `__ - `Klarstein (@Klarstein) `__ - `Marcus Klein (@kleini) `__ - `Kevin Lewis (@kll) `__ +- `KNXBroker (@KNXBroker) `__ - `Koen Vervloesem (@koenvervloesem) `__ +- `kokangit (@kokangit) `__ - `Petr Vraník (@konikvranik) `__ - `Kevin Pelzel (@kpelzel) `__ - `Karl Q. (@kquinsland) `__ @@ -509,24 +649,26 @@ Contributors - `KristopherMackowiak (@KristopherMackowiak) `__ - `kroimon (@kroimon) `__ - `krunkel (@krunkel) `__ +- `kryptonitecb3 (@kryptonitecb3) `__ - `Kendell R (@KTibow) `__ - `Kuba Szczodrzyński (@kuba2k2) `__ - `Jakub Šimo (@kubik369) `__ +- `Mark Kuchel (@kuchel77) `__ - `Ken Davidson (@kwdavidson) `__ -- `Kyle Hendricks (@kylehendricks) `__ -- `Kyle Manna (@kylemanna) `__ +- `Kyle Hill (@kylhill) `__ - `Kalashnikov Ilya (@l1bbcsg) `__ - `Limor "Ladyada" Fried (@ladyada) `__ -- `Lakshantha Dissanayake (@lakshanthad) `__ - `Luca Adrian L (@lal12) `__ - `Fredrik Lindqvist (@Landrash) `__ +- `Lawrie George (@lawriege) `__ - `Laszlo Gazdag (@lazlyhu) `__ +- `Ludovic BOUÉ (@lboue) `__ - `lcavalli (@lcavalli) `__ - `Craig Fletcher (@leakypixel) `__ - `Dominik Wagenknecht (@LeDominik) `__ - `Benny de Leeuw (@leeuwte) `__ - `Leonardo La Rocca (@leoli51) `__ -- `Lerosen (@Lerosen) `__ +- `Leo Winter (@LeoWinterDE) `__ - `Leon Loopik (@Lewn) `__ - `Luca Gugelmann (@lgugelmann) `__ - `Lubos Horacek (@lhoracek) `__ @@ -534,45 +676,51 @@ Contributors - `lillborje71 (@lillborje71) `__ - `lingex (@lingex) `__ - `lkomurcu (@lkomurcu) `__ +- `loadrunner42 (@loadrunner42) `__ - `Lazar Obradovic (@lobradov) `__ -- `Lode Vermeiren (@lodev) `__ - `Barry Loong (@loongyh) `__ +- `Michael Bisbjerg (@LordMike) `__ - `LuBeDa (@lubeda) `__ -- `Lukáš Maňas (@LucasCZE) `__ - `Joakim Sørensen (@ludeeus) `__ - `ludrao (@ludrao) `__ - `Lukas Klass (@LukasK13) `__ +- `Łukasz Świtaj (@lukaszswitaj) `__ +- `Luke (@Lukeskaiwalker) `__ +- `Jayden (@lukyjay) `__ - `Lumpusz (@Lumpusz) `__ - `Ohad Lutzky (@lutzky) `__ - `Luke Fitzgerald (@lwfitzgerald) `__ -- `Lewis Juggins (@lwis) `__ - `Alex Peters (@Lx) `__ - `M95D (@M95D) `__ - `maaadc (@maaadc) `__ - `Marc-Antoine Courteau (@macourteau) `__ - `Massimiliano Ravelli (@madron) `__ - `Alexandre-Jacques St-Jacques (@Maelstrom96) `__ -- `magnus (@magnusja) `__ +- `Scott Cappellani (@maeneak) `__ - `Magnus Nordlander (@magnusnordlander) `__ -- `Magnus Øverli (@magnusoverli) `__ - `majbthrd (@majbthrd) `__ - `Major Péter (@majorpeter) `__ +- `Kasper Malfroid (@malfroid) `__ +- `Malle355 (@Malle355) `__ - `raymonder jin (@mamil) `__ - `Manuel Díez (@manutenfruits) `__ +- `marcelolcosta (@marcelolcosta) `__ - `Marcel van der Veldt (@marcelveldt) `__ - `Marc (@MarcHagen) `__ +- `marcinkowalczyk (@marcinkowalczyk) `__ - `Marcio Granzotto Rodrigues (@marciogranzotto) `__ -- `Marc Teale (@marcteale) `__ - `marecabo (@marecabo) `__ - `Ben Marengo (@marengaz) `__ - `Marvin Gaube (@margau) `__ - `maringeph (@maringeph) `__ - `Mario (@mario-tux) `__ +- `Mark Schabacker (@markschabacker) `__ - `Marek Marczykowski-Górecki (@marmarek) `__ - `marsjan155 (@marsjan155) `__ - `Martin (@martgras) `__ - `Martin Hjelmare (@MartinHjelmare) `__ - `MartinWelsch (@MartinWelsch) `__ +- `M-A (@maruel) `__ - `MasterTim17 (@MasterTim17) `__ - `Christopher Masto (@masto) `__ - `Mat931 (@Mat931) `__ @@ -585,29 +733,38 @@ Contributors - `Matus Ivanecky (@maty535) `__ - `Maximilian Gerhardt (@maxgerhardt) `__ - `mbo18 (@mbo18) `__ +- `mcmuller (@mcmuller) `__ +- `Miguel Diaz Gonçalves (@mdiazgoncalves) `__ - `Matthew Donoughe (@mdonoughe) `__ - `Me No Dev (@me-no-dev) `__ - `Alexandr Zarubkin (@me21) `__ - `Joseph Mearman (@Mearman) `__ - `mechanarchy (@mechanarchy) `__ - `Bas (@Mechazawa) `__ +- `megabitdragon (@megabitdragon) `__ - `meijerwynand (@meijerwynand) `__ - `Marco (@Melkor82) `__ - `Merlin Schumacher (@merlinschumacher) `__ - `Martin Flasskamp (@MFlasskamp) `__ - `Michael Gorven (@mgorven) `__ +- `Jörg Thalheim (@Mic92) `__ - `Michael Muré (@MichaelMure) `__ - `Micha Nordmann (@Michanord) `__ +- `Michel Munzert (@michelde) `__ - `Pauline Middelink (@middelink) `__ +- `Mike_Went (@MikeWent) `__ - `Mikko Tervala (@MikkoTervala) `__ - `MiKuBB (@MiKuBB) `__ - `André Klitzing (@misery) `__ - `Tomasz (@Misiu) `__ +- `mjbogusz (@mjbogusz) `__ - `Matthew Garrett (@mjg59) `__ -- `Maarten (@mjkl-gh) `__ - `Morton Jonuschat (@mjonuschat) `__ - `mjoshd (@mjoshd) `__ +- `Matt Kaatman (@mkaatman) `__ +- `Marcel Karger (@mkar1984) `__ - `mknjc (@mknjc) `__ +- `Matthew Kosmoski (@mkosmo) `__ - `Maurice Makaay (@mmakaay) `__ - `mmanza (@mmanza) `__ - `mnltake (@mnltake) `__ @@ -616,20 +773,26 @@ Contributors - `Moritz Glöckl (@moritzgloeckl) `__ - `Chris Laplante (@mostthingsweb) `__ - `Sam Hughes (@MrEditor97) `__ +- `Morgan Robertson (@mrgnr) `__ - `Mariusz Kryński (@mrk-its) `__ - `Michael Davidson (@MrMDavidson) `__ +- `Murray Scott (@mscottco) `__ +- `MSe-5-14 (@MSe-5-14) `__ - `mtl010957 (@mtl010957) `__ - `mulcmu (@mulcmu) `__ +- `Martin Murray (@murrayma) `__ - `Michel van de Wetering (@mvdwetering) `__ - `Michiel van Turnhout (@mvturnho) `__ - `Martin Weinelt (@mweinelt) `__ - `myhomeiot (@myhomeiot) `__ - `Igor Scheller (@MyIgel) `__ - `Mynasru (@Mynasru) `__ +- `Mikhail Zakharov (@mzakharo) `__ - `Kevin Uhlir (@n0bel) `__ - `Erik Näsström (@Naesstrom) `__ - `H. Árkosi Róbert (@nagyrobi) `__ - `Viktor Nagy (@nagyv) `__ +- `NanoSector (@NanoSector) `__ - `Oskar Napieraj (@napieraj) `__ - `Nate Lust (@natelust) `__ - `ueno (@nayuta-ueno) `__ @@ -642,36 +805,46 @@ Contributors - `Nick B. (@NickB1) `__ - `nickrout (@nickrout) `__ - `Nick Whyte (@nickw444) `__ +- `Nicky Ivy (@nickyivyca) `__ - `NP v/d Spek (@nielsnl68) `__ +- `Niels Zeilemaker (@NielsZeilemaker) `__ - `Joakim Vindgard (@nigobo) `__ - `nikito7 (@nikito7) `__ - `niklasweber (@niklasweber) `__ - `Niorix (@Niorix) `__ - `Zvonimir Haramustek (@nitko12) `__ +- `Nixspers (@Nixspers) `__ - `Dennis (@Nizzle) `__ - `nldroid (@nldroid) `__ - `Niccolò Maggioni (@nmaggioni) `__ +- `nmeachen (@nmeachen) `__ - `Jan Sandbrink (@NobodysNightmare) `__ +- `Álvaro Fernández Rojas (@Noltari) `__ - `Łukasz Śliwiński (@nonameplum) `__ - `Greg Johnson (@notgwj) `__ - `nouser2013 (@nouser2013) `__ +- `Nick (@ntompson) `__ - `Stephen Edgar (@ntwb) `__ - `Stanislav Meduna (@numo68) `__ - `Nuno Sousa (@nunofgs) `__ - `Maksym Lunin (@nut-code-monkey) `__ - `Chris Nussbaum (@nuttytree) `__ +- `Michał Sochoń (@nvtkaszpir) `__ +- `Nathaniel Wesley Filardo (@nwf) `__ - `obrain17 (@obrain17) `__ - `Ockert Marais (@OckertM) `__ - `Dave Walker (@oddsockmachine) `__ - `Andrey Ganzevich (@odya) `__ - `ogatatsu (@ogatatsu) `__ - `Oğuzhan Başer (@oguzhanbaser) `__ +- `OkhammahkO (@OkhammahkO) `__ - `Omar Ghader (@omarghader) `__ - `Ömer Şiar Baysal (@omersiar) `__ - `optimusprimespace (@optimusprimespace) `__ - `Oscar Bolmsten (@oscar-b) `__ - `Otamay (@Otamay) `__ - `Otto Winter (@OttoWinter) `__ +- `Maxime Dufour (@outscale-mdr) `__ - `Ben Owen (@owenb321) `__ - `Oxan van Leeuwen (@oxan) `__ - `Pablo Clemente Maseda (@paclema) `__ @@ -685,20 +858,30 @@ Contributors - `Paul Nicholls (@pauln) `__ - `Bartłomiej Biernacki (@pax0r) `__ - `Paul Doidge (@pdoidge) `__ +- `peddamat (@peddamat) `__ - `pedjas (@pedjas) `__ +- `pedrobsm (@pedrobsm) `__ - `per1234 (@per1234) `__ +- `David (@perldj) `__ - `Peter Valkov (@peter-valkov) `__ - `Peter Galantha (@peterg79) `__ +- `Peter Halicky (@peterhalicky) `__ +- `Philippe Delodder (@phdelodder) `__ +- `philbowers (@philbowers) `__ - `Philippe FOUQUET (@Philippe12) `__ +- `Philip Rosenberg-Watt (@PhilRW) `__ - `pieterbrink123 (@pieterbrink123) `__ - `Piotr Kubiak (@piotr-kubiak) `__ - `Peter Kuehne (@pkuehne) `__ - `Plácido Revilla (@placidorevilla) `__ - `Marcus Kempe (@plopp) `__ +- `Jan Pluskal (@pluskal) `__ - `DK (@poldim) `__ +- `poloswiss (@poloswiss) `__ - `Pontus Oldberg (@PontusO) `__ - `poptix (@poptix) `__ - `Iván Povedano (@pove) `__ +- `Peter Provost (@PProvost) `__ - `probonopd (@probonopd) `__ - `Mike Lynch (@Prow7) `__ - `Peter Tatrai (@ptatrai) `__ @@ -708,6 +891,7 @@ Contributors - `Alex (@pxe-la) `__ - `[pʲɵs] (@pyos) `__ - `Qc (@qc24) `__ +- `Quinn Casey (@qcasey) `__ - `Karol Zlot (@qqgg231) `__ - `Tommy Jonsson (@quazzie) `__ - `Quentin Smith (@quentinmit) `__ @@ -717,138 +901,176 @@ Contributors - `Richard Miles (@r89m) `__ - `Aaron Zhang (@rabbit-aaron) `__ - `RadekHvizdos (@RadekHvizdos) `__ +- `Raph (@rafal83) `__ - `Florian Ragwitz (@rafl) `__ - `Rai-Rai (@Rai-Rai) `__ - `randomllama (@randomllama) `__ +- `Marc Seeger (@rb2k) `__ - `rbaron (@rbaron) `__ - `Robert Cambridge (@rcambrj) `__ - `Rebbe Pod (@RebbePod) `__ +- `reddn (@reddn) `__ - `Alex (@redwngsrul) `__ +- `Refferic (@Refferic) `__ +- `Regev Brody (@regevbr) `__ - `Alex Reid (@reidprojects) `__ +- `RenierM26 (@RenierM26) `__ - `Reuben (@reubn) `__ - `Robin Pronk (@rfpronk) `__ +- `Robert Gabrielson (@rgabrielson11) `__ +- `Rafael Goes (@rgriffogoes) `__ +- `rheinz (@rheinz) `__ +- `richardhopton (@richardhopton) `__ - `Richard Klingler (@richardklingler) `__ - `Richard Lewis (@richrd) `__ - `Andre Borie (@Rjevski) `__ - `rjlexx (@rjlexx) `__ - `René Klomp (@rklomp) `__ - `rlowens (@rlowens) `__ -- `LMR (@rmooreID) `__ - `Ryan Mounce (@rmounce) `__ - `rnauber (@rnauber) `__ - `Rob Deutsch (@rob-deutsch) `__ -- `Rob de Jonge (@robdejonge) `__ - `Robert Alfaro (@robert-alfaro) `__ - `Rob Gridley (@robgridley) `__ -- `Robin Smidsrød (@robinsmidsrod) `__ +- `Robinson1999 (@Robinson1999) `__ - `RoboMagus (@RoboMagus) `__ -- `Roi Tagar (@roitagar) `__ +- `Roeland Lutters (@Roeland54) `__ +- `RoganDawes (@RoganDawes) `__ - `Jérôme W. (@RomRider) `__ +- `roscoegray (@roscoegray) `__ - `rotarykite (@rotarykite) `__ - `Bob Perciaccante (@rperciaccante) `__ - `rradar (@rradar) `__ - `rspaargaren (@rspaargaren) `__ - `rsumner (@rsumner) `__ -- `Ruben De Smet (@rubdos) `__ - `@RubenKelevra (@RubenKelevra) `__ - `RubyBailey (@RubyBailey) `__ +- `Rus Ti (@Rusti-gotrage) `__ - `rweather (@rweather) `__ +- `Ryan Lang (@ryan-lang) `__ - `ryanalden (@ryanalden) `__ -- `Silvio (@s1lvi0) `__ +- `Lukas Bachschwell (@s00500) `__ +- `Sabesto (@Sabesto) `__ - `Jan Čermák (@sairon) `__ +- `Sam Turner (@samturner3) `__ +- `Sender (@sanderlv) `__ - `sascha lammers (@sascha432) `__ +- `sbur83 (@sbur83) `__ - `Søren Christian Aarup (@scaarup) `__ - `Matthew Schinckel (@schinckel) `__ -- `Lukas Schulte (@Schluggi) `__ - `Nils Schulte (@Schnilz) `__ - `Wolle (@schreibfaul1) `__ - `Ville Skyttä (@scop) `__ - `Jeremy Pack (@scriptengine) `__ +- `Sean True (@seantrue) `__ - `sebcaps (@sebcaps) `__ - `Stefan Seyfried (@seife) `__ - `SenexCrenshaw (@SenexCrenshaw) `__ -- `Sergio (@sergio303) `__ +- `Jason Sepinsky (@Sepinsky) `__ +- `Sergey Popov (@Sergey-SRG) `__ - `Sergio Mayoral Martínez (@sermayoral) `__ +- `Seth Girvan (@sethgirvan) `__ - `Emanuele Tessore (@setola) `__ - `Abdelkader Boudih (@seuros) `__ - `SharkSharp (@SharkSharp) `__ +- `Sebastiaan (@SharkWipf) `__ - `Fabio Todaro (@SharpEdgeMarshall) `__ - `ShellAddicted (@ShellAddicted) `__ - `sherbang (@sherbang) `__ - `Shish (@shish) `__ +- `signix (@signix) `__ - `SiliconAvatar (@SiliconAvatar) `__ +- `Mark Lopez (@Silvenga) `__ - `Francisco J. Solis (@sisco0) `__ - `Derek Hageman (@Sizurka) `__ - `Stephen Tierney (@sjtrny) `__ +- `Dominik Skalník (@skaldo) `__ - `Niklas Wagner (@Skaronator) `__ - `Rafael Treviño (@skasi7) `__ - `Brian Slesinsky (@skybrian) `__ - `Jordan W. Cobb (@skykingjwc) `__ - `Sebastian Lövdahl (@slovdahl) `__ - `smischny (@smischny) `__ -- `Luca Zimmermann (@soundstorm) `__ - `Sourabh Jaiswal (@sourabhjaiswal) `__ - `Philip Allgaier (@spacegaier) `__ - `spacemanspiff2007 (@spacemanspiff2007) `__ +- `sparkydave1981 (@sparkydave1981) `__ +- `spattinson (@spattinson) `__ - `Sean Brogan (@spbrogan) `__ - `Spegs21 (@Spegs21) `__ -- `Stephan Peijnik-Steinwender (@speijnik) `__ - `Eric Lind (@sperly) `__ - `Samuel Sieb (@ssieb) `__ - `Stefan Staub (@sstaub) `__ -- `St4n (@St4n) `__ - `Stanislav Habich (@standahabich) `__ -- `Stas (@stas-sl) `__ - `stegm (@stegm) `__ -- `Steve Baxter (@stevebaxter) `__ - `Stewart (@stewiem2000) `__ +- `sthorley (@sthorley) `__ - `sticilface (@sticilface) `__ - `Stijn Tintel (@stintel) `__ - `Mathias Stock (@Stock-M) `__ +- `Strixx76 (@Strixx76) `__ - `stubs12 (@stubs12) `__ - `Jordan Vohwinkel (@sublime93) `__ +- `sud33p (@sud33p) `__ - `sumirati (@sumirati) `__ - `swifty99 (@swifty99) `__ +- `Jan Gutowski (@Switch123456789) `__ - `Sybren A. Stüvel (@sybrenstuvel) `__ -- `Sympatron GmbH (@Sympatron) `__ - `synco (@synco) `__ - `Marcel Feix (@Syndlex) `__ - `Suryandaru Triandana (@syndtr) `__ - `SyXavier (@SyXavier) `__ -- `Teemu Mikkonen (@T3m3z) `__ +- `Peter (@szpeter80) `__ - `Taigar2015 (@Taigar2015) `__ +- `Stefan Dragnev (@tailsu) `__ - `Levente Tamas (@tamisoft) `__ - `Aleksandr Oleinikov (@tannisroot) `__ - `tantive (@tantive) `__ -- `Team Super Panda (@teamsuperpanda) `__ - `Ryan Hoffman (@tekmaven) `__ - `testbughub (@testbughub) `__ - `Greg Lincoln (@tetious) `__ +- `Terry Hardie (@thardie) `__ +- `The-Paran0id-Andr0id (@The-Paran0id-Andr0id) `__ - `Nejc (@thedexboy) `__ - `Thomas Eckerstorfer (@TheEggi) `__ - `Theexternaldisk (@Theexternaldisk) `__ +- `Martijn van der Pol (@TheFes) `__ - `TheGroundZero (@TheGroundZero) `__ - `thejonesyboy (@thejonesyboy) `__ - `TheJulianJES (@TheJulianJES) `__ - `Zixuan Wang (@TheNetAdmin) `__ - `Dominik Bruhn (@theomega) `__ +- `Brian Levinsen (@therealeldaria) `__ +- `Steve Scott (@thewishy) `__ - `Florian Gareis (@TheZoker) `__ +- `Thibault Maekelbergh (@thibmaek) `__ +- `Matt (@ThisIsTheOnlyUsernameAvailable) `__ +- `Thomas Heiser (@thomasheiser85) `__ - `Andrew Thompson (@thompsa) `__ - `John (@thorrak) `__ +- `Thomas Langewouters (@thouters) `__ +- `Transylvania High Tech (@thtro) `__ +- `Thunderbiscuits (@Thunderbiscuits) `__ - `tiagofreire-pt (@tiagofreire-pt) `__ - `Tijs-B (@Tijs-B) `__ +- `Tim Laurence (@timdaman) `__ - `Aidan Timson (@timmo001) `__ - `Tim Savage (@timsavage) `__ -- `Snōwball (@tobias-) `__ +- `Tinkerfish (@tinkerfish) `__ +- `TJ Horner (@tjhorner) `__ +- `Christian (@Tntdruid) `__ - `Philipp Tölke (@toelke) `__ - `tomaszduda23 (@tomaszduda23) `__ - `Tom Brien (@TomBrien) `__ +- `Tom Hartogs (@TomHartogs) `__ - `tomlut (@tomlut) `__ - `tomle (@tomole444) `__ - `Tom Price (@tomtom5152) `__ - `David Kiliani (@torfbolt) `__ +- `tracestep (@tracestep) `__ - `Felix Eckhofer (@tribut) `__ - `Trick van Staveren (@trickv) `__ +- `TripitakaBC (@TripitakaBC) `__ - `Tobias (@tripplet) `__ - `Tyler Bules (@Troublebrewing) `__ - `Olli Salonen (@trsqr) `__ @@ -859,20 +1081,25 @@ Contributors - `tubalainen (@tubalainen) `__ - `tube0013 (@tube0013) `__ - `Alexey Vlasov (@turbulator) `__ -- `Seppel Hardt (@tuxBurner) `__ -- `TVDLoewe (@TVDLoewe) `__ +- `tvan0076 (@tvan0076) `__ - `Thorsten von Eicken (@tve) `__ - `Ubi de Feo (@ubidefeo) `__ +- `ulic75 (@ulic75) `__ +- `unhold (@unhold) `__ +- `Aaron Mildenstein (@untergeek) `__ - `uPesy Electronics (@uPesy) `__ -- `user897943 (@user897943) `__ - `UT2UH (@UT2UH) `__ - `Vc (@Valcob) `__ - `Nad (@valordk) `__ +- `Veli Veromann (@velijv) `__ - `André Lademann (@vergissberlin) `__ - `Austin (@vidplace7) `__ - `Vincèn (@vincegre) `__ +- `Virage Laboratories (@viragelabs) `__ - `VitaliyKurokhtin (@VitaliyKurokhtin) `__ - `Xuming Feng (@voicevon) `__ +- `vt-vaio (@vt-vaio) `__ +- `vtechun (@vtechun) `__ - `vxider (@Vxider) `__ - `Wai Weng (@waiweng83) `__ - `WallyCZ (@WallyCZ) `__ @@ -883,6 +1110,7 @@ Contributors - `Ian Wells (@wellsi) `__ - `wifwucite (@wifwucite) `__ - `wilberforce (@wilberforce) `__ +- `Wingman3434 (@Wingman3434) `__ - `Emil Hesslow (@WizKid) `__ - `WJCarpenter (@wjcarpenter) `__ - `Wouter van der Wal (@wjtje) `__ @@ -892,6 +1120,8 @@ Contributors - `Sven Serlier (@wrt54g) `__ - `Wolfgang Tremmel (@wtremmel) `__ - `wysiwyng (@wysiwyng) `__ +- `Jakob (@XDjackieXD) `__ +- `Mike Brown (@xenoxaos) `__ - `WitchKing (@xvil) `__ - `Yaroslav (@Yarikx) `__ - `Marcin Jaworski (@yawor) `__ @@ -900,11 +1130,13 @@ Contributors - `Yuval Aboulafia (@yuvalabou) `__ - `Björn Stenberg (@zagor) `__ - `david reid (@zathras777) `__ -- `San (@zhujunsan) `__ +- `Brynley McDonald (@ZephireNZ) `__ - `Geek_cat (@zhzhzhy) `__ - `I. Tomita (@ziceva) `__ - `Michael Labuschke (@zigman79) `__ +- `zivillian (@zivillian) `__ +- `Loïc (@zoic21) `__ - `Zack Barett (@zsarnett) `__ - `Christian Zufferey (@zuzu59) `__ -*This page was last updated February 17, 2023.* +*This page was last updated April 20, 2023.* diff --git a/images/as7341.jpg b/images/as7341.jpg new file mode 100644 index 00000000000..aac6137e1c3 Binary files /dev/null and b/images/as7341.jpg differ diff --git a/images/ehmtx.jpg b/images/ehmtx.jpg new file mode 100644 index 00000000000..9e53a5460d4 Binary files /dev/null and b/images/ehmtx.jpg differ diff --git a/images/fs3000.jpg b/images/fs3000.jpg new file mode 100644 index 00000000000..05eb0a51f58 Binary files /dev/null and b/images/fs3000.jpg differ diff --git a/images/garage-variant.svg b/images/garage-variant.svg new file mode 100644 index 00000000000..a0b6880a312 --- /dev/null +++ b/images/garage-variant.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/images/haier.svg b/images/haier.svg new file mode 100644 index 00000000000..887c22f62e9 --- /dev/null +++ b/images/haier.svg @@ -0,0 +1,25 @@ + + + + + + + + + + + + + + + diff --git a/images/head-lightbulb-outline.svg b/images/head-lightbulb-outline.svg new file mode 100644 index 00000000000..2e83e14bb95 --- /dev/null +++ b/images/head-lightbulb-outline.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/images/kuntze.jpg b/images/kuntze.jpg new file mode 100644 index 00000000000..29824aaaeec Binary files /dev/null and b/images/kuntze.jpg differ diff --git a/images/microphone.svg b/images/microphone.svg new file mode 100644 index 00000000000..33084ec26e9 --- /dev/null +++ b/images/microphone.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/images/mlx90614.jpg b/images/mlx90614.jpg new file mode 100644 index 00000000000..1c9a37dd22c Binary files /dev/null and b/images/mlx90614.jpg differ diff --git a/images/mmc5603.jpg b/images/mmc5603.jpg new file mode 100644 index 00000000000..de5897286df Binary files /dev/null and b/images/mmc5603.jpg differ diff --git a/images/mopeka_std_check.jpg b/images/mopeka_std_check.jpg new file mode 100644 index 00000000000..6619507f252 Binary files /dev/null and b/images/mopeka_std_check.jpg differ diff --git a/images/sen21231.png b/images/sen21231.png new file mode 100644 index 00000000000..924b7869ad8 Binary files /dev/null and b/images/sen21231.png differ diff --git a/images/voice-assistant.svg b/images/voice-assistant.svg new file mode 100644 index 00000000000..4e2e8e01b42 --- /dev/null +++ b/images/voice-assistant.svg @@ -0,0 +1 @@ + diff --git a/images/water-drop.svg b/images/water-drop.svg new file mode 100644 index 00000000000..2cfce236241 --- /dev/null +++ b/images/water-drop.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/index.rst b/index.rst index 527c990ff7a..6c45f2203ac 100644 --- a/index.rst +++ b/index.rst @@ -149,7 +149,7 @@ Core Components Sensor Components ----------------- -Sensors have been split into categories. If a sensor fits into more than one category, it will be listed multiple times. +Sensors are split into categories. If a sensor fits into more than one category, it will be listed multiple times. Core **** @@ -215,6 +215,7 @@ Bluetooth Low Energy (BLE) BLE RSSI, components/sensor/ble_rssi, bluetooth.svg Inkbird IBS-TH1 Mini, components/sensor/inkbird_ibsth1_mini, inkbird_isbth1_mini.jpg, Temperature & Humidity Mopeka Pro Check LP, components/sensor/mopeka_pro_check, mopeka_pro_check.jpg, tank level + Mopeka Standard Check LP, components/sensor/mopeka_std_check, mopeka_std_check.jpg, tank level RuuviTag, components/sensor/ruuvitag, ruuvitag.jpg, Temperature & Humidity & Accelerometer Xiaomi BLE, components/sensor/xiaomi_ble, xiaomi_mijia_logo.jpg, Various @@ -274,6 +275,7 @@ Environmental .. imgtable:: + Absolute Humidity, components/sensor/absolute_humidity, water-drop.svg AHT10 / AHT20 / AHT21 / DHT20, components/sensor/aht10, aht10.jpg, Temperature & Humidity AirThings BLE, components/sensor/airthings_ble, airthings_logo.png, Temperature & Humidity & Pressure AM2320, components/sensor/am2320, am2320.jpg, Temperature & Humidity @@ -298,6 +300,7 @@ Environmental Internal Temperature, components/sensor/internal_temperature, thermometer.svg, Temperature MCP9808, components/sensor/mcp9808, mcp9808.jpg, Temperature MH-Z19, components/sensor/mhz19, mhz19.jpg, CO2 & Temperature + MLX90614, components/sensor/mlx90614, mlx90614.jpg, Temperature MPL3115A2, components/sensor/mpl3115a2, mpl3115a2.jpg, Temperature & Pressure MS5611, components/sensor/ms5611, ms5611.jpg, Pressure NTC Thermistor, components/sensor/ntc, ntc.jpg, Temperature @@ -323,6 +326,7 @@ Light AM43, components/sensor/am43, am43.jpg, Lux APDS9960, components/sensor/apds9960, apds9960.jpg, Colour & Gesture + AS7341, components/sensor/as7341, as7341.jpg, Spectral Color Sensor BH1750, components/sensor/bh1750, bh1750.jpg, Lux LTR390, components/sensor/ltr390, ltr390.jpg, Lux & UV MAX44009, components/sensor/max44009, max44009.svg, Lux @@ -337,6 +341,7 @@ Magnetic ESP32 Hall Sensor, components/sensor/esp32_hall, magnet.svg, ESP internal HMC5883L, components/sensor/hmc5883l, hmc5883l.jpg, 3-Axis magnetometer + MMC5603, components/sensor/mmc5603, mmc5603.jpg, 3-Axis magnetometer MLX90393, components/sensor/mlx90393, mlx90393.jpg, 3-Axis magnetometer QMC5883L, components/sensor/qmc5883l, qmc5883l.jpg, 3-Axis magnetometer @@ -349,6 +354,7 @@ Miscellaneous Binary Sensor Map, components/sensor/binary_sensor_map, binary_sensor_map.jpg, Map binary to value b-parasite, components/sensor/b_parasite, b_parasite.jpg, Moisture & Temperature & Humidity & Light EZO sensor circuits, components/sensor/ezo, ezo-ph-circuit.png, (pH) + FS3000, components/sensor/fs3000, fs3000.jpg, Air velocity Havells Solar, components/sensor/havells_solar, havellsgti5000d_s.jpg, Solar rooftop Growatt Solar, components/sensor/growatt_solar, growatt.jpg, Solar rooftop Kalman Combinator, components/sensor/kalman_combinator, function.svg @@ -361,6 +367,8 @@ Miscellaneous uFire EC sensor, components/sensor/ufire_ec, ufire_ec.png, EC & Temperature uFire ISE sensor, components/sensor/ufire_ise, ufire_ise.png, pH & Temperature Resol VBus, components/vbus, resol_deltasol_bs_plus.jpg + Person Sensor (SEN21231), components/sensor/sen21231, sen21231.png + Kuntze pool sensor, components/sensor/kuntze, kuntze.jpg Motion @@ -394,38 +402,75 @@ Weight Looking for a sensor that outputs its values as an analog voltage? Have a look at the -:doc:`ADC Sensor ` together with a formula like in the :doc:`TEMT6000 -example `. +:doc:`ADC Sensor ` together with a formula like in the `TEMT6000 +configuration `__. Binary Sensor Components ------------------------ +Binary Sensors are split into categories. If a sensor fits into more than one category, it will be listed multiple times. + +Core +**** .. imgtable:: Binary Sensor Core, components/binary_sensor/index, folder-open.svg + Custom Binary Sensor, components/binary_sensor/custom, language-cpp.svg GPIO, components/binary_sensor/gpio, pin.svg Home Assistant, components/binary_sensor/homeassistant, home-assistant.svg Status, components/binary_sensor/status, server-network.svg - Analog Threshold, components/binary_sensor/analog_threshold, analog_threshold.svg - ESP32 BLE Presence, components/binary_sensor/ble_presence, bluetooth.svg + Template Binary Sensor, components/binary_sensor/template, description.svg + +Capacitive Touch +**************** +.. imgtable:: + + CAP1188 Capacitive Touch Sensor, components/binary_sensor/cap1188, cap1188.jpg ESP32 Touch Pad, components/binary_sensor/esp32_touch, touch.svg - Hydreon Rain Sensor Binary Sensor, components/binary_sensor/hydreon_rgxx, hydreon_rg9.jpg MPR121 Capacitive Touch Sensor, components/binary_sensor/mpr121, mpr121.jpg - Nextion Binary Sensor, components/binary_sensor/nextion, nextion.jpg - Template Binary Sensor, components/binary_sensor/template, description.svg + TTP229, components/binary_sensor/ttp229, ttp229.jpg + +Mechanical +********** +.. imgtable:: + + Matrix Keypad, components/matrix_keypad, matrix_keypad.jpg + TM1637, components/display/tm1637, tm1637.jpg + TM1638, components/display/tm1638, tm1638.jpg + +NFC/RFID Components +******************* + +Often known as "tag" or "card" readers within the community. + +.. imgtable:: + PN532, components/binary_sensor/pn532, pn532.jpg RC522, components/binary_sensor/rc522, rc522.jpg RDM6300, components/binary_sensor/rdm6300, rdm6300.jpg - TTP229, components/binary_sensor/ttp229, ttp229.jpg - Tuya Binary Sensor, components/binary_sensor/tuya, tuya.png - Modbus Binary Sensor, components/binary_sensor/modbus_controller, modbus.png - XPT2046, components/binary_sensor/xpt2046, xpt2046.jpg - CAP1188 Capacitive Touch Sensor, components/binary_sensor/cap1188, cap1188.jpg + +Touchscreen +*********** +.. imgtable:: + + Nextion Binary Sensor, components/binary_sensor/nextion, nextion.jpg Touchscreen, components/touchscreen/index, touch.svg - Resol VBus, components/vbus, resol_deltasol_bs_plus.jpg + XPT2046, components/binary_sensor/xpt2046, xpt2046.jpg + +Miscellaneous +************* +.. imgtable:: + + Analog Threshold, components/binary_sensor/analog_threshold, analog_threshold.svg + ESP32 BLE Presence, components/binary_sensor/ble_presence, bluetooth.svg + Hydreon Rain Sensor Binary Sensor, components/binary_sensor/hydreon_rgxx, hydreon_rg9.jpg LD2410, components/sensor/ld2410, ld2410.jpg - Custom Binary Sensor, components/binary_sensor/custom, language-cpp.svg + Modbus Binary Sensor, components/binary_sensor/modbus_controller, modbus.png + PipSolar - compatible PV Inverter, components/pipsolar, pipsolar.jpg + Remote Receiver, components/remote_receiver, remote.svg + Resol VBus, components/vbus, resol_deltasol_bs_plus.jpg + Tuya Binary Sensor, components/binary_sensor/tuya, tuya.png Output Components ----------------- @@ -560,7 +605,7 @@ Display Components ST7735, components/display/st7735, st7735.jpg ST7789V, components/display/st7789v, st7789v.jpg ST7920, components/display/st7920, st7920.jpg - ILI9341, components/display/ili9341, ili9341.jpg + ILI9xxx, components/display/ili9xxx, ili9341.jpg Waveshare E-Paper, components/display/waveshare_epaper, waveshare_epaper.jpg Inkplate, components/display/inkplate6, inkplate6.jpg PCD8544 (Nokia 5110/ 3310), components/display/pcd8544, pcd8544.jpg @@ -623,6 +668,7 @@ Climate Components Midea, components/climate/midea, midea.svg Anova Cooker, components/climate/anova, anova.png BedJet Climate System, components/climate/bedjet, bedjet.png + Haier Climate, components/climate/haier, haier.svg Number Components ----------------- @@ -645,7 +691,7 @@ Select Components Tuya Select, components/select/tuya, tuya.png Lock Components ------------------ +--------------- .. imgtable:: @@ -661,6 +707,14 @@ Media Player Components Media Player Core, components/media_player/index, folder-open.svg I2S Audio, components/media_player/i2s_audio, i2s_audio.svg +Microphone Components +--------------------- + +.. imgtable:: + + Microphone Core, components/microphone/index, microphone.svg + I2S Microphone, components/microphone/i2s_audio, i2s_audio.svg + Time Components --------------- @@ -673,8 +727,19 @@ Time Components DS1307 RTC, components/time/ds1307, clock-outline.svg PCF85063 RTC, components/time/pcf85063, clock-outline.svg -Misc Components ---------------- +Home Assistant Companion Components +----------------------------------- + +.. imgtable:: + + Bluetooth Proxy, components/bluetooth_proxy, bluetooth.svg + Voice Assistant, components/voice_assistant, voice-assistant.svg + Sensor, components/sensor/homeassistant, home-assistant.svg + Text Sensor, components/text_sensor/homeassistant, home-assistant.svg + Binary Sensor, components/binary_sensor/homeassistant, home-assistant.svg + +Miscellaneous Components +------------------------ .. imgtable:: @@ -700,6 +765,8 @@ Misc Components ESP32 Camera, components/esp32_camera, camera.svg ESP32 Camera Web Server, components/esp32_camera_web_server, camera.svg + I²S Audio, components/i2s_audio, i2s_audio.svg + Stepper, components/stepper/index, stepper.svg Servo, components/servo, servo.svg Sprinkler, components/sprinkler, sprinkler-variant.svg @@ -750,40 +817,21 @@ Cookbook .. imgtable:: - Arduino Port Extender, cookbook/arduino_port_extender, arduino_logo.svg - Endstop Cover, cookbook/endstop-cover, window-open.svg - PIR Sensor, cookbook/pir, pir.jpg - Relay, cookbook/relay, relay.jpg - BRUH Multisensor, cookbook/bruh, bruh.png - TEMT6000, cookbook/temt6000, temt6000.jpg - Non-Invasive Power Meter, cookbook/power_meter, power_meter.jpg - Dual Relay Motor Cover, cookbook/dual-r2-cover, sonoff_dual_r2.jpg - BME280 Environment, cookbook/bme280_environment, bme280.jpg - Sonoff Fishpond Pump, cookbook/sonoff-fishpond-pump, cookbook-sonoff-fishpond-pump.jpg - H801 LED Controller, cookbook/h801, h801.jpg + Lambda Magic: Tips and Tricks, cookbook/lambda_magic, head-lightbulb-outline.svg + Garage Door Template Cover, cookbook/garage-door, garage-variant.svg Time & Temperature on OLED Display, cookbook/display_time_temp_oled, display_time_temp_oled_2.jpg - Mirabella Genio Bulb, cookbook/mirabella-genio-bulb, cookbook-mirabella-genio-b22-rgbw.jpg - Garage Door, cookbook/garage-door, window-open.svg - Brilliant / Mirabella Genio Smart Plugs, cookbook/brilliant-mirabella-genio-smart-plugs, cookbook-brilliant-mirabella-genio-smart-plugs.jpg - Etekcity Voltson (ESW01-EU) , cookbook/esw01-eu, esw01-eu.jpg - Sonoff iFan02, cookbook/ifan02, fan.svg - Zemismart RGBW Downlights, cookbook/zemismart-rgbw-downlights, cookbook-zemismart-rgbw-downlight.jpg - Teckin SB50, cookbook/teckin_sb50, teckin_sb50.jpg - Sonoff light switch options, cookbook/sonoff-light-switch, light_switch.png ESP32 Water Leak Detector, cookbook/leak-detector-m5stickC, leak-detector-m5stickC_main_index.jpg - ESP32 BLE iTag Button, cookbook/ble_itag, esp32_ble_itag.jpg - IAQ (Indoor Air Quality) Board, cookbook/iaq_board, iaq_board2.jpg - TUYA Smart Life RGBW Controller, cookbook/tuya_rgbw, tuya_rgbw.jpg - Custom UART Text Sensor, cookbook/uart_text_sensor, language-cpp.svg - IWOOLE Table Lamp, cookbook/iwoole_rgbw_table_lamp, iwoole_rgbw_table_lamp.png - EPEVER Tracer, cookbook/tracer-an, tracer-an.jpg - Ilonda Wifi Smart Fish Feeder, cookbook/ilonda-wifi-smart-fish-feeder, ilonda-wifi-smart-fish-feeder-cookbook.jpg - AirGradient DIY Air Quality Sensor, cookbook/air_gradient_diy_air_quality_sensor, air_gradient_diy_air_quality_sensor.jpg - Geiger Counter, cookbook/geiger-counter, radiationD-v1-1-cajoe_small.jpg + BME280 Environment extras, cookbook/bme280_environment, bme280.jpg + Non-Invasive Power Meter, cookbook/power_meter, power_meter.jpg + Sonoff Fishpond Pump, cookbook/sonoff-fishpond-pump, cookbook-sonoff-fishpond-pump.jpg + Arduino Port Extender, cookbook/arduino_port_extender, arduino_logo.svg + EHMTX a matrix status/text display, cookbook/ehmtx, ehmtx.jpg Do you have other awesome automations or cool setups? Please feel free to add them to the documentation for others to copy. See :doc:`Contributing `. +If you'd like to share configurations for specific devices, please contribute to our `ESPHome Devices `__ database. + .. toctree:: :hidden: diff --git a/web-api/index.rst b/web-api/index.rst index 4ef75a9614a..481ab6c1ef2 100644 --- a/web-api/index.rst +++ b/web-api/index.rst @@ -2,8 +2,8 @@ Web Server API ============== .. seo:: - :description: Migration guide for installing ESPHome on ESPs running ESPEasy. - :image: espeasy.svg + :description: Information on Web Server APIs, including Event Source APIs and REST APIs. + :image: logo-text.svg Since version 1.3, ESPHome includes a built-in web server that can be used to view states and send commands. In addition to the web-frontend available under the root index of the