diff --git a/Doxygen b/Doxygen index 3b46ff747..aaf38408a 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 = 2022.3.2 +PROJECT_NUMBER = 2022.4.0 # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a diff --git a/Makefile b/Makefile index 2477c3578..58edd6027 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,5 @@ ESPHOME_PATH = ../esphome -ESPHOME_REF = 2022.3.2 +ESPHOME_REF = 2022.4.0 .PHONY: html html-strict cleanhtml deploy help live-html Makefile netlify netlify-api api netlify-dependencies svg2png copy-svg2png minify diff --git a/_static/changelog-2022.4.0.png b/_static/changelog-2022.4.0.png new file mode 100644 index 000000000..3ac123e8a Binary files /dev/null and b/_static/changelog-2022.4.0.png differ diff --git a/_static/version b/_static/version index 95efab8ce..a1350699d 100644 --- a/_static/version +++ b/_static/version @@ -1 +1 @@ -2022.3.2 \ No newline at end of file +2022.4.0 \ No newline at end of file diff --git a/changelog/2022.4.0.rst b/changelog/2022.4.0.rst new file mode 100644 index 000000000..9d07df909 --- /dev/null +++ b/changelog/2022.4.0.rst @@ -0,0 +1,240 @@ +ESPHome 2022.4.0 - 20th April 2022 +================================== + +.. seo:: + :description: Changelog for ESPHome 2022.4.0. + :image: /_static/changelog-2022.4.0.png + :author: Jesse Hills + :author_twitter: @jesserockz + +.. imgtable:: + :columns: 3 + + QMP6988, components/sensor/qmp6988, qmp6988_env3.png + Hydreon Rain Sensor, components/binary_sensor/hydreon_rgxx, hydreon_rg9.jpg + Mi Motion Sensor 2, components/sensor/xiaomi_ble, xiaomi_rtcgq02lm.jpg + Sonoff D1 Dimmer, components/light/sonoff_d1, sonoff_d1.jpg + MCP3208, components/sensor/mcp3204, mcp3204.jpg + Shelly Dimmer, components/light/shelly_dimmer, shellydimmer2.jpg + + +Home Assistant Addon Repo +------------------------- + +This is a repeat from the 2022.2 release notes. + +The `ESPHome Home Assistant addon repository `__ +is added by default to new Home Assistant installations. Because of this, we have decided that we would +deprecate the ESPHome addon inside the `Community Addons `__ +and everyone should move to the ESPHome repo. It is safe to delete the Community ESPHome addon as +your configuration YAML files are stored in the Home Assistant configuration folder. + +You can add the repository here: + +.. raw:: html + + + Open your Home Assistant instance and show the add add-on repository dialog with a specific repository URL pre-filled. + + +And then install the latest ESPHome addon here: + +.. raw:: html + + + Open your Home Assistant instance and show the dashboard of a Supervisor add-on. + + +Python 3.8 Minimum +------------------ + +A friendly reminder that 2022.3 set the minimum Python version to 3.8. +Please upgrade your local python if you are unable to update ESPHome further. +This is taken care of automatically if you are using the Home Assistant Add-on, or the +ESPHome docker container. + +Shelly Dimmer 2 +--------------- + +Support for the STM32 chip of the Shelly Dimmer has been added in this release. The component also supports flashing custom firmware to the +stm32 via ESPHome which is required to use the component. See the :doc:`documentation ` for more details. + +Google Fonts +------------ + +:ghuser:`OttoWinter` has given everyone a way to use Google Fonts in their yaml and displays without having to manually download +ttf font files. The exqample below will automatically download and cache the Roboto ttf font file required so you can utilise it. +See the :ref:`display-static_text` documentation for more details. + +.. code-block:: yaml + + font: + - file: "gfonts://Roboto" + id: roboto + size: 20 + + +Deep sleep wakeup time +---------------------- + +Deep sleep for ESP32 has had a new feature added. + +.. code-block:: yaml + + on_...: + - deep_sleep.enter: + until: "14:00:00" + time_id: ... + +This will automatically calculate the time required to deep sleep to ensure that the device will +wake up at "14:00:00". The time format here is local time to match the timezone you have configured and +this requires a time component to be configured. + + +Sensors imported from Home Assistant +------------------------------------ + +In this release there is a breaking change on the sensors that are imported from homeassistant, ``platform: homeassistant``. +They will now default to being internal to ESPHome and will not be re-exported back to Home Assistant, MQTT or the web server. +This change makes sense as it was just extra sensors and netowkr traffic. You are able to add these back as non internal by +adding ``internal: false`` to the yaml for each of the sensors. + + +Full list of changes +-------------------- + +New Features +^^^^^^^^^^^^ + +- Allow to set user defined characters on LCD :esphomepr:`3322` by :ghuser:`numo68` (new-feature) +- Font allow using google fonts directly :esphomepr:`3243` by :ghuser:`OttoWinter` (new-feature) (notable-change) +- Add mqtt for idf :esphomepr:`2930` by :ghuser:`martgras` (new-feature) +- Extend mcp3204 to support 8 channels (mcp3208 variant) :esphomepr:`3332` by :ghuser:`RadekHvizdos` (new-feature) +- Add cover toggle support to endstop cover :esphomepr:`3358` by :ghuser:`rrooggiieerr` (new-feature) +- Remote base pronto receive :esphomepr:`2826` by :ghuser:`cvwillegen` (new-feature) +- Allow specifying deep sleep wakup clock time :esphomepr:`3312` by :ghuser:`jesserockz` (new-feature) + +New Components +^^^^^^^^^^^^^^ + +- Add support for QMP6988 Pressure sensor :esphomepr:`3192` by :ghuser:`andrewpc` (new-integration) +- Add integration hydreon_rgxx for rain sensors by Hydreon :esphomepr:`2711` by :ghuser:`functionpointer` (new-integration) +- Add Xiaomi RTCGQ02LM - Mi Motion Sensor 2 :esphomepr:`3186` by :ghuser:`jesserockz` (new-integration) +- Add Sonoff D1 Dimmer support :esphomepr:`2775` by :ghuser:`anatoly-savchenkov` (new-integration) +- Refactor Sensirion Sensors :esphomepr:`3374` by :ghuser:`martgras` (new-integration) +- Add support for Shelly Dimmer 2 :esphomepr:`2954` by :ghuser:`rnauber` (new-integration) + +Breaking Changes +^^^^^^^^^^^^^^^^ + +- Make home_assistant imported sensors internal by default :esphomepr:`3372` by :ghuser:`jesserockz` (breaking-change) + +Beta Changes +^^^^^^^^^^^^ + +- Actually increase request memory for json parsing :esphomepr:`3331` by :ghuser:`jesserockz` +- Actually increase request memory for json parsing :esphomepr:`3331` by :ghuser:`jesserockz` +- Changes accuracy of single cell voltage :esphomepr:`3387` by :ghuser:`matthias882` +- Add support for Shelly Dimmer 2 :esphomepr:`2954` by :ghuser:`rnauber` (new-integration) +- Allocate smaller amount of buffer for JSON :esphomepr:`3384` by :ghuser:`dz0ny` +- Fix power_delivered/produced_phase sensor deviceclass in DSMR :esphomepr:`3395` by :ghuser:`mvdwetering` +- Shelly Dimmer: Delete obsolete LICENSE.txt :esphomepr:`3394` by :ghuser:`rnauber` +- Dont require empty object for wifi ap with defaults :esphomepr:`3404` by :ghuser:`jesserockz` + +Notable Changes +^^^^^^^^^^^^^^^ + +- Font allow using google fonts directly :esphomepr:`3243` by :ghuser:`OttoWinter` (new-feature) (notable-change) + +All changes +^^^^^^^^^^^ + +- Bump pytest-asyncio from 0.18.1 to 0.18.2 :esphomepr:`3262` by :ghuser:`dependabot[bot]` +- Bump zeroconf from 0.38.3 to 0.38.4 :esphomepr:`3257` by :ghuser:`dependabot[bot]` +- Bump click from 8.0.3 to 8.0.4 :esphomepr:`3248` by :ghuser:`dependabot[bot]` +- Bump docker dependencies :esphomepr:`3281` by :ghuser:`OttoWinter` +- Fixed wrong comment :esphomepr:`3286` by :ghuser:`Rai-Rai` +- Add support for QMP6988 Pressure sensor :esphomepr:`3192` by :ghuser:`andrewpc` (new-integration) +- Adds support for b-parasite's v2 BLE protocol :esphomepr:`3290` by :ghuser:`rbaron` +- increase delay for Ethernet module warm up Safe Mode :esphomepr:`3326` by :ghuser:`nagyrobi` +- Bump esptool from 3.2 to 3.3 :esphomepr:`3327` by :ghuser:`dependabot[bot]` +- Allow to set user defined characters on LCD :esphomepr:`3322` by :ghuser:`numo68` (new-feature) +- Font allow using google fonts directly :esphomepr:`3243` by :ghuser:`OttoWinter` (new-feature) (notable-change) +- Actually increase request memory for json parsing :esphomepr:`3331` by :ghuser:`jesserockz` +- Actually increase request memory for json parsing :esphomepr:`3331` by :ghuser:`jesserockz` +- Change beginning of file comments to avoid creating doxygen tag for `esphome` namespace :esphomepr:`3314` by :ghuser:`e28eta` +- Publish custom data when modbus number lambda fills vector :esphomepr:`3295` by :ghuser:`jesserockz` +- Define touchscreen support when in use. :esphomepr:`3296` by :ghuser:`geiseri` +- New vscode schema gen :esphomepr:`3336` by :ghuser:`glmnet` +- protobuf: fix incomplete 64 bits implementation :esphomepr:`3341` by :ghuser:`ianchi` +- feat: support ble_client that use security w/o pin codes :esphomepr:`3320` by :ghuser:`ammmze` +- Add mqtt for idf :esphomepr:`2930` by :ghuser:`martgras` (new-feature) +- Added a function to load custom characters in LCD display :esphomepr:`3279` by :ghuser:`andrewjswan` +- CAN bus: support remote transmission request flag for canbus.send :esphomepr:`3193` by :ghuser:`felixstorm` +- Tm1637 binarysensor :esphomepr:`2792` by :ghuser:`mvturnho` +- Bump click from 8.0.4 to 8.1.2 :esphomepr:`3351` by :ghuser:`dependabot[bot]` +- Bump pylint from 2.12.2 to 2.13.4 :esphomepr:`3348` by :ghuser:`dependabot[bot]` +- Bump pytest-asyncio from 0.18.2 to 0.18.3 :esphomepr:`3335` by :ghuser:`dependabot[bot]` +- Bump pytest from 7.0.1 to 7.1.1 :esphomepr:`3313` by :ghuser:`dependabot[bot]` +- Bump docker dependencies :esphomepr:`3354` by :ghuser:`OttoWinter` +- Bump voluptuous from 0.12.2 to 0.13.0 :esphomepr:`3355` by :ghuser:`dependabot[bot]` +- Bump tzlocal from 4.1 to 4.2 :esphomepr:`3356` by :ghuser:`dependabot[bot]` +- Bump pyupgrade from 2.31.0 to 2.31.1 :esphomepr:`3292` by :ghuser:`dependabot[bot]` +- Bump black from 22.1.0 to 22.3.0 :esphomepr:`3357` by :ghuser:`dependabot[bot]` +- Allow on_value_range for sensor and number to be templated :esphomepr:`3359` by :ghuser:`jesserockz` +- Add support for Electrolux heatpump and bump arduino-heatpumpir version :esphomepr:`3353` by :ghuser:`ikilledmypc` +- Implement newer RTU protocol of Growatt inverters :esphomepr:`3315` by :ghuser:`djwlindenaar` +- Add parameter to control i2c stop signal at endTransmission :esphomepr:`3370` by :ghuser:`kbickar` +- Fix SHTC3 sensor detection :esphomepr:`3365` by :ghuser:`ssieb` +- Extend mcp3204 to support 8 channels (mcp3208 variant) :esphomepr:`3332` by :ghuser:`RadekHvizdos` (new-feature) +- Bump pyupgrade from 2.31.1 to 2.32.0 :esphomepr:`3366` by :ghuser:`dependabot[bot]` +- Bump voluptuous from 0.13.0 to 0.13.1 :esphomepr:`3364` by :ghuser:`dependabot[bot]` +- Bump pylint from 2.13.4 to 2.13.5 :esphomepr:`3363` by :ghuser:`dependabot[bot]` +- Fix HM3301 AQI int8 overflow :esphomepr:`3361` by :ghuser:`calco88` +- Add cover toggle support to endstop cover :esphomepr:`3358` by :ghuser:`rrooggiieerr` (new-feature) +- Make home_assistant imported sensors internal by default :esphomepr:`3372` by :ghuser:`jesserockz` (breaking-change) +- Add integration hydreon_rgxx for rain sensors by Hydreon :esphomepr:`2711` by :ghuser:`functionpointer` (new-integration) +- Addition of Deep Sleep RTC pin definition for ESP32-S2 :esphomepr:`3303` by :ghuser:`andrewpc` +- Add Xiaomi RTCGQ02LM - Mi Motion Sensor 2 :esphomepr:`3186` by :ghuser:`jesserockz` (new-integration) +- Add Sonoff D1 Dimmer support :esphomepr:`2775` by :ghuser:`anatoly-savchenkov` (new-integration) +- Remote base pronto receive :esphomepr:`2826` by :ghuser:`cvwillegen` (new-feature) +- Use correct http defines :esphomepr:`3378` by :ghuser:`dz0ny` +- Refactor Sensirion Sensors :esphomepr:`3374` by :ghuser:`martgras` (new-integration) +- Fix silent config errors :esphomepr:`3380` by :ghuser:`jesserockz` +- Move PN532OnTagTrigger to nfc::NfcOnTagTrigger :esphomepr:`3379` by :ghuser:`jesserockz` +- Allow specifying deep sleep wakup clock time :esphomepr:`3312` by :ghuser:`jesserockz` (new-feature) +- Changes accuracy of single cell voltage :esphomepr:`3387` by :ghuser:`matthias882` +- Add support for Shelly Dimmer 2 :esphomepr:`2954` by :ghuser:`rnauber` (new-integration) +- Allocate smaller amount of buffer for JSON :esphomepr:`3384` by :ghuser:`dz0ny` +- Fix power_delivered/produced_phase sensor deviceclass in DSMR :esphomepr:`3395` by :ghuser:`mvdwetering` +- Shelly Dimmer: Delete obsolete LICENSE.txt :esphomepr:`3394` by :ghuser:`rnauber` +- Dont require empty object for wifi ap with defaults :esphomepr:`3404` by :ghuser:`jesserockz` + +Past Changelogs +--------------- + +- :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 b58aecd0b..61c3a9a30 100644 --- a/changelog/index.rst +++ b/changelog/index.rst @@ -2,7 +2,7 @@ Changelog ========= .. redirect:: - :url: /changelog/2022.3.0.html + :url: /changelog/2022.4.0.html .. toctree:: :glob: diff --git a/components/binary_sensor/hydreon_rgxx.rst b/components/binary_sensor/hydreon_rgxx.rst new file mode 100644 index 000000000..88879093b --- /dev/null +++ b/components/binary_sensor/hydreon_rgxx.rst @@ -0,0 +1,55 @@ +Hydreon Rain Sensor Binary Sensor +================================= + +.. seo:: + :description: Instructions for setting up Hydreon rain sensors + :image: hydreon_rg9.jpg + :keywords: hydreon + +The ``hydreon_rgxx`` binary sensor platform gives access to information provided by a Hydreon Rain Sensor. +For this sensor to work, a :doc:`/components/sensor/hydreon_rgxx` must be set up. + +.. code-block:: yaml + + # Example RG-9 entry + + uart: + rx_pin: GPIO16 + tx_pin: GPIO17 + baud_rate: 9600 + + sensor: + - platform: hydreon_rgxx + model: "RG_9" + id: "hydreon_1" + update_interval: 1s + moisture: + name: "rain" + expire_after: 30s + + binary_sensor: + - platform: hydreon_rgxx + hydreon_rgxx_id: "hydreon_1" + too_cold: + name: "too cold" + +Configuration variables: +------------------------ + +- **hydreon_rgxx_id** (*Optional*, :ref:`config-id`): The ID of the Hydreon Rain Sensor display. + +- **too_cold** (*Optional*): `true` if the sensor reports being too cold. Hydreon only mentions this feature for the RG-9. + + - **name** (**Required**, string): The name for the voltage sensor. + + - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. + + - All other options from :ref:`Binary Sensor `. + + +See Also +-------- + +- :doc:`/components/sensor/hydreon_rgxx` +- :doc:`index` +- :ghedit:`Edit` diff --git a/components/canbus.rst b/components/canbus.rst index 5e6c2b806..86e1fd11c 100644 --- a/components/canbus.rst +++ b/components/canbus.rst @@ -83,16 +83,17 @@ Configuration variables: Automations: ------------ -- **on_frame** (*Optional*, :ref:`Automation `): An automation to perform when ability - CAN Frame is received. See :ref:`canbus-on-frame`. +- **on_frame** (*Optional*, :ref:`Automation `): An automation to perform when a + CAN frame is received. See :ref:`canbus-on-frame`. .. _canbus-on-frame: ``on_frame`` ************ -This automation will be triggered when a can frame is received. A variable ``x`` of type -``std::vector`` is passed to the automation for use in lambdas. +This automation will be triggered when a CAN frame is received. A variable ``x`` of type +``std::vector`` containing the frame data and a variable ``can_id`` of type ``uint32_t`` +containing the actual received CAN id are passed to the automation for use in lambdas. .. note:: @@ -110,6 +111,34 @@ This automation will be triggered when a can frame is received. A variable ``x` lambda: 'return (x.size() > 0) ? x[0] == 0x11 : false;' then: light.toggle: light1 + - can_id: 0b00000000000000000000001000000 + can_id_mask: 0b11111000000000011111111000000 + use_extended_id: true + then: + - lambda: |- + auto pdo_id = can_id >> 14; + switch (pdo_id) + { + case 117: + ESP_LOGD("canbus", "exhaust_fan_duty"); + break; + case 118: + ESP_LOGD("canbus", "supply_fan_duty"); + break; + case 119: + ESP_LOGD("canbus", "supply_fan_flow"); + break; + // to be continued... + } + + +Configuration variables: +************************ + +- **can_id** (**Required**, int): The received CAN id to trigger this automation on. +- **can_id_mask** (*Optional*, int): The bit mask to apply to the received CAN id before trying to match it + with *can_id*, defaults to ``0x1fffffff`` (all bits of received CAN id are compared with *can_id*). +- **use_extended_id** (*Optional*, boolean): Identifies the type of *can_id* to match on, defaults to *false*. ``canbus.send`` Action ********************** @@ -144,6 +173,8 @@ Configuration variables: the can bus device. - **use_extended_id** (*Optional*, boolean): default *false* identifies the type of *can_id*: *false*: Standard 11 Bit IDs, *true*: Extended 29Bit ID +- **remote_transmission_request** (*Optional*, boolean): Set to send CAN bus frame to request data from another node + (defaults to *false*). If a certain data length code needs to be sent, provide as many (dummy) bytes in *data*. ESP32 CAN Component ------------------- diff --git a/components/climate/climate_ir.rst b/components/climate/climate_ir.rst index 0b36e7d67..19d6626eb 100644 --- a/components/climate/climate_ir.rst +++ b/components/climate/climate_ir.rst @@ -98,7 +98,7 @@ This platform utilises the library's generic one-size-fits-all API, which might Additional configuration must be specified for this platform: -- **protocol** (**Required**, string): Choose one of Arduino-HeatpumpIR's supported protcols: ``aux``, ``ballu``, ``carrier_mca``, ``carrier_nqv``, ``daikin_arc417``, ``daikin_arc480``, ``daikin``, ``fuego``, ``fujitsu_awyz``, ``gree``, ``greeya``, ``greeyac``, ``greeyan``, ``hisense_aud``, ``hitachi``, ``hyundai``, ``ivt``, ``midea``, ``mitsubishi_fa``, ``mitsubishi_fd``, ``mitsubishi_fe``, ``mitsubishi_heavy_fdtc``, ``mitsubishi_heavy_zj``, ``mitsubishi_heavy_zm``, ``mitsubishi_heavy_zmp``, ``mitsubishi_heavy_kj``, ``mitsubishi_msc``, ``mitsubishi_msy``, ``mitsubishi_sez``, ``panasonic_ckp``, ``panasonic_dke``, ``panasonic_jke``, ``panasonic_lke``, ``panasonic_nke``, ``samsung_aqv``, ``samsung_fjm``, ``sharp``, ``toshiba_daiseikai``, ``toshiba`` +- **protocol** (**Required**, string): Choose one of Arduino-HeatpumpIR's supported protcols: ``aux``, ``ballu``, ``carrier_mca``, ``carrier_nqv``, ``daikin_arc417``, ``daikin_arc480``, ``daikin``, ``electroluxyal``, ``fuego``, ``fujitsu_awyz``, ``gree``, ``greeya``, ``greeyac``, ``greeyan``, ``hisense_aud``, ``hitachi``, ``hyundai``, ``ivt``, ``midea``, ``mitsubishi_fa``, ``mitsubishi_fd``, ``mitsubishi_fe``, ``mitsubishi_heavy_fdtc``, ``mitsubishi_heavy_zj``, ``mitsubishi_heavy_zm``, ``mitsubishi_heavy_zmp``, ``mitsubishi_heavy_kj``, ``mitsubishi_msc``, ``mitsubishi_msy``, ``mitsubishi_sez``, ``panasonic_ckp``, ``panasonic_dke``, ``panasonic_jke``, ``panasonic_lke``, ``panasonic_nke``, ``samsung_aqv``, ``samsung_fjm``, ``sharp``, ``toshiba_daiseikai``, ``toshiba`` - **horizontal_default** (**Required**, string): What to default to when the AC unit's horizontal direction is *not* set to swing. Options are: ``left``, ``mleft``, ``middle``, ``mright``, ``right``, ``auto`` - **vertical_default** (**Required**, string): What to default to when the AC unit's vertical direction is *not* set to swing. Options are: ``down``, ``mdown``, ``middle``, ``mup``, ``up``, ``auto`` - **max_temperature** (**Required**, float): The maximum temperature that the AC unit supports being set to. diff --git a/components/deep_sleep.rst b/components/deep_sleep.rst index 9516524ab..144bb337e 100644 --- a/components/deep_sleep.rst +++ b/components/deep_sleep.rst @@ -97,9 +97,20 @@ This action makes the given deep sleep component enter deep sleep immediately. id: deep_sleep_1 sleep_duration: 20min + + # ESP32 can sleep until a specific time of day. + on_...: + then: + - deep_sleep.enter: + id: deep_sleep_1 + until: "16:00:00" + time_id: sntp_id + Configuration options: - **sleep_duration** (*Optional*, :ref:`templatable `, :ref:`config-time`): The time duration to stay in deep sleep mode. +- **until** (*Optional*, string): The time of day to wake up. Only on ESP32. +- **time_id** (*Optional*, :ref:`config-id`): The ID of the time component to use for the ``until`` option. Only on ESP32. .. _deep_sleep-prevent_action: diff --git a/components/display/images/tm1637_2devices.png b/components/display/images/tm1637_2devices.png new file mode 100644 index 000000000..3f1222878 Binary files /dev/null and b/components/display/images/tm1637_2devices.png differ diff --git a/components/display/images/tm1637_3plus_devices.png b/components/display/images/tm1637_3plus_devices.png new file mode 100644 index 000000000..56fd1835c Binary files /dev/null and b/components/display/images/tm1637_3plus_devices.png differ diff --git a/components/display/images/tm1637_key_connections.png b/components/display/images/tm1637_key_connections.png new file mode 100644 index 000000000..3d419f9a0 Binary files /dev/null and b/components/display/images/tm1637_key_connections.png differ diff --git a/components/display/index.rst b/components/display/index.rst index 719868705..bb45f0fff 100644 --- a/components/display/index.rst +++ b/components/display/index.rst @@ -143,8 +143,8 @@ You can view the full API documentation for the rendering engine in the "API Ref .. _display-static_text: -Drawing Static Text -******************* +Fonts +***** The rendering engine also has a powerful font drawer which integrates seamlessly into ESPHome. Whereas in most Arduino display projects you have to use one of a few pre-defined fonts in very @@ -164,13 +164,44 @@ Next, create a ``font:`` section in your configuration: id: my_font size: 20 + # gfonts://family[@weight] + - file: "gfonts://Roboto" + id: roboto + size: 20 + display: # ... Configuration variables: -- **file** (**Required**, string): The path (relative to where the .yaml file is) of the TrueType font - file. +- **file** (**Required**): The path (relative to where the .yaml file is) of the TrueType font + file. You can use the ``gfonts://`` short form to use Google Fonts, or use the below structure: + + - **type** (**Required**, string): Can be ``gfonts`` or ``local``. + + **Google Fonts**: + + Each Google Font will be downloaded once and cached for future use. + + - **family** (**Required**, string): The name of the Google Font family. + - **weight** (*Optional*, enum): The weight of the font. Can be either the text name or the integer value: + + - **thin**: 100 + - **extra-light**: 200 + - **light**: 300 + - **regular**: 400 (**default**) + - **medium**: 500 + - **semi-bold**: 600 + - **bold**: 700 + - **extra-bold**: 800 + - **black**: 900 + + - **italic** (*Optional*, boolean): Whether the font should be italic. + + **Local Fonts**: + + - **path** (**Required**, string): The path (relative to where the .yaml file is) of the TrueType font file. + - **id** (**Required**, :ref:`config-id`): The ID with which you will be able to reference the font later in your display code. - **size** (*Optional*, int): The size of the font in pt (not pixel!). @@ -190,8 +221,10 @@ Configuration variables: to install it using ``pip install pillow``. +Drawing Static Text +******************* -Then, in your display code just reference the font like so: +In your display code, you can render static text by referencing the font and just entering your string: .. code-block:: yaml diff --git a/components/display/lcd_display.rst b/components/display/lcd_display.rst index ad54d07d4..ba6440a70 100644 --- a/components/display/lcd_display.rst +++ b/components/display/lcd_display.rst @@ -203,6 +203,45 @@ turns off 90 seconds after the last activation of the sensor. - lambda: |- id(mydisplay).no_backlight(); +User Defined Characters +----------------------- + +The LCD display has the possibility to define up to eight user defined characters occupying the characters +``0`` to ``7`` and mirrored at ``8`` to ``15`` (i.e. ``\x08`` can be used instead of the ``\0`` that can +be problematic in strings). Each character has eight lines of five bits, with the first line on the top +and the most significant bit on the left, meaning that ``0b10000`` followed by six zeros and a ``0b00001`` +defines a dot at the upper left and lower right of the character. + +.. code-block:: yaml + + display: + - platform: lcd_pcf8574 + id: mydisplay + # ... + user_characters: + - position: 0 + data: + - 0b00000 + - 0b01010 + - 0b00000 + - 0b00100 + - 0b00100 + - 0b10001 + - 0b01110 + - 0b00000 + - position: 7 + data: + - 0b00000 + - 0b01010 + - 0b00000 + - 0b00100 + - 0b00100 + - 0b00000 + - 0b01110 + - 0b10001 + lambda: |- + it.print("Hello, world \x08 \x07!"); + See Also -------- diff --git a/components/display/tm1637.rst b/components/display/tm1637.rst index 79b0b4d24..502508671 100644 --- a/components/display/tm1637.rst +++ b/components/display/tm1637.rst @@ -48,6 +48,37 @@ Configuration variables: .. _display-tm1637_lambda: +Binary Sensor +------------- + +The TM1637 LED display controller also includes a special circuit with keyboard scan interface and enhanced identification circuit with anti-interference keys. +This circuit uses the 8 segment lines that also drive the LED display. But combined with the K1 and K2 pins we can add 16 keys that can be used as binary sensors in esphome. + +.. figure:: images/tm1637_key_connections.png + :align: center + :width: 50.0% + + TM1637 display keyboard connections + +.. code-block:: yaml + + binary_sensor: + - platform: tm1637 + id: key0 + name: key1-00 + tm1637_id: tm1637_display + key: 0 + +Configuration variables: +************************ + +- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor. +- **name** (*Optional*, string): The name for the binary sensor. +- **tm1637_id** (*Optional*, ::ref:`config-id`): The id of the tm1637 that should be used to scan the keys in case you are using multiple devices. +- **key** (**Required**, integer): The keycode for the connected key (Seg0 = 0, Seg1 = 1 etc,). Range is from + 0 to 15. +- All other options from :ref:`Binary Sensor `. + Rendering Lambda ---------------- @@ -125,6 +156,25 @@ The following example creates a typical digital clock with the ``:`` colon flash else it.strftime("%H%M", id(homeassistant_time).now()); +Connect multiple displays +------------------------- + +To connect multiple TM1636 displays you need as many control lines as you have displays. This is achived by sharing control-lines for clk and dio between displays. + +.. figure:: images/tm1637_2devices.png + :align: center + :width: 50.0% + + Two TM1637 displays on only 2 control lines + +When using more than 2 devices like 3 or more you add a control-line for the Dio pin and share this with the next display Clk pin. +The last displays Dio pin shares the Clk pin of the first display. + +.. figure:: images/tm1637_3plus_devices.png + :align: center + :width: 50.0% + + Three TM1637 displays on 3 control lines See Also -------- diff --git a/components/light/images/sonoff_d1.jpg b/components/light/images/sonoff_d1.jpg new file mode 100644 index 000000000..547588ac1 Binary files /dev/null and b/components/light/images/sonoff_d1.jpg differ diff --git a/components/light/images/sonoff_d1_gpio0.jpg b/components/light/images/sonoff_d1_gpio0.jpg new file mode 100644 index 000000000..6e11cb1b9 Binary files /dev/null and b/components/light/images/sonoff_d1_gpio0.jpg differ diff --git a/components/light/images/sonoff_d1_serial.jpg b/components/light/images/sonoff_d1_serial.jpg new file mode 100644 index 000000000..a87a42786 Binary files /dev/null and b/components/light/images/sonoff_d1_serial.jpg differ diff --git a/components/light/shelly_dimmer.rst b/components/light/shelly_dimmer.rst new file mode 100644 index 000000000..8313290fe --- /dev/null +++ b/components/light/shelly_dimmer.rst @@ -0,0 +1,99 @@ +Shelly Dimmer +============= + +.. seo:: + :description: Instructions for setting up a Shelly Dimmer 2. + :image: shellydimmer2.jpg + +The ``shelly_dimmer`` component adds support for the dimming and power-metering functionality that can be found the `Shelly Dimmer 2 `_. The interaction with mains is done via an STM32 microcontroller that is flashed with an `open source firmware `_. +A detailed analysis of the Shelly Dimmer 2 hardware is given `here `_. + +.. figure:: ../../images/shellydimmer2.jpg + :align: center + :width: 40.0% + + +An example of a configuration of this component: + +.. code-block:: yaml + + logger: + baud_rate: 0 + + uart: + tx_pin: 1 + rx_pin: 3 + baud_rate: 115200 + sensor: + + light: + - platform: shelly_dimmer + name: Shelly Dimmer 2 Light + id: thislight + power: + name: Shelly Dimmer 2 Light Power + voltage: + name: Shelly Dimmer 2 Light Voltage + current: + name: Shelly Dimmer 2 Light Current + max_brightness: 500 + firmware: + version: "51.6" + update: true + + +Configuration variables: +------------------------ + +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- **uart_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the UART hub. + +.. note:: + + Currently, only the first hardware UART of the ESP is supported, which has to be configured like this: + + .. code-block:: yaml + + uart: + tx_pin: 1 + rx_pin: 3 + baud_rate: 115200 + + +- **name** (**Required**, string): The name of the light. +- **leading_edge** (**Optional**, boolean): `Dimming mode `_: "true" means leading edge, "false" (default) is trailing edge. +- **min_brightness** (**Optional**, int): Minimum brightness value on a scale from 0..1000, the default is 0. +- **max_brightness** (**Optional**, int): Maximum brightness value on a scale from 0..1000, the default is 1000. +- **warmup_brightness** (**Optional**, int): Brightness threshold below which the dimmer switches on later in mains current cycle. `This might help with dimming LEDs `_. The value is from 0..1000 with an default of 0. +- **nrst_pin** (**Optional**, :ref:`config-pin`): Pin connected with "NRST" of STM32. The default is "GPIO5". +- **boot0_pin** (**Optional**, :ref:`config-pin`): Pin connected with "BOOT0" of STM32. The default is "GPIO4". +- **current** (**Optional**): Sensor of the current in Amperes. All options from + :ref:`Sensor `. +- **voltage** (**Optional**): Sensor of the voltage in Volts. Only accurate if neutral is connected. All options from :ref:`Sensor `. +- **power** (**Optional**): Sensor of the active power in Watts. Only accurate if neutral is connected. All options from :ref:`Sensor `. +- **firmware** (**Optional**): + - **version** (**Optional**): Version string of the `firmware `_ that will be expected on the microcontroller. The default is "51.6", another known-good firmware is "51.5". + - **url** (**Optional**): An URL to download the firmware from. Defaults to github for known firmware versions. + - **sha256** (**Optional**): A hash to compare the downloaded firmware against. Defaults a proper hash of known firmware versions. + - **update** (**Optional**): Should the firmware of the STM be updated if necessary? The default is false. + +.. note:: + + When flashing Shelly Dimmer with esphome for the first time, flashing the STM firmware is necessary too for the dimmer to work: + + .. code-block:: yaml + + firmware: + version: "51.6" #<-- set version here + update: true + + +- All other options from :ref:`Light `. + + +See Also +-------- + +- :doc:`/components/light/index` +- :apiref:`shelly_dimmer/light/shelly_dimmer.h` +- :ghedit:`Edit` diff --git a/components/light/sonoff_d1.rst b/components/light/sonoff_d1.rst new file mode 100644 index 000000000..75c4bc6ed --- /dev/null +++ b/components/light/sonoff_d1.rst @@ -0,0 +1,124 @@ +Sonoff D1 Dimmer +================ + +.. seo:: + :description: Instructions for setting up a Sonoff D1 dimmer switch. + :image: brightness-medium.svg + +The ``sonoff_d1`` light platform creates a simple brightness-only light for the +hardware found in `Sonoff D1 dimmer `__. Installations with Sonoff RM433 433MHz radio +remotes are also supported. Use this component to integrate Sonoff D1 dimmer into +ESPHome / Home Assistant ecosystem. + +.. figure:: images/sonoff_d1.jpg + :align: center + :width: 100.0% + + Sonoff D1 dimmer front and back view. Image by `ITEAD `__. + +Sonoff D1 uses another MCU for light dimming and handling of radio commands. +It's hooked up to ESP8266 via UART bus with default RX / TX pins being used on +ESP8266 side. Bi-directional symmetric request / response protocol is implemented +between ESP8266 and MCU. ``sonoff_d1`` component implements this protocol and +translates between HA light commands and serial messages. + +For detailed instructions on how to replace the stock firmware with ESPHome see :doc:`/devices/sonoff_s20`. +You will need to locate GPIO0 pin and serial port. Photos below should help. + +.. figure:: images/sonoff_d1_gpio0.jpg + :align: center + :width: 100.0% + + Photo of GPIO 0, images by `klotzma `__. +.. figure:: images/sonoff_d1_serial.jpg + :align: center + :width: 100.0% + + Photo of serial port pins, images by `klotzma `__. + +Before using this components make sure: + +- board is configured to ``esp8285`` +- :ref:`UART bus ` is configured with default RX / TX pins and 9600 baud rate +- :doc:`logger ` to the serial port is disabled by setting ``baud_rate`` to ``0`` +- in case you need light state restoration on power up, make sure ``restore_from_flash`` is set to ``true`` in the :doc:`ESP8266 platform ` + + +This component is useless for devices other than Sonoff D1 dimmer. + +.. code-block:: yaml + + + # Example configuration entry + esphome: + name: my-d1-dimmer + + # Restore from flash if you want to keep the last state at power up + esp8266: + board: esp8285 + restore_from_flash: true + + # Make sure your WiFi will connect + wifi: + ssid: "ssid" + password: "password" + + # Make sure logging is not using the serial port + logger: + baud_rate: 0 + + # Enable Home Assistant API + api: + + # Make sure you can upload new firmware OTA + ota: + + # D1 dimmer uses hardware serial port on the default pins @ 9600 bps + uart: + rx_pin: RX + tx_pin: TX + baud_rate: 9600 + + # And finally the light component + # gamma correction equal to zero gives linear scale, + # exactly what's needed for this device + light: + - platform: sonoff_d1 + use_rm433_remote: False + name: Sonoff D1 Dimmer + restore_mode: RESTORE_DEFAULT_OFF + gamma_correct: 0.0 + default_transition_length: 1s + + +Configuration variables +----------------------- + +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- **name** (**Required**, string): The name of the light. +- **use_rm433_remote** (*Optional*, boolean): Set to ``True`` if your setup uses Sonoff RM433 + or any other radio remote control. Properly setting this parameter allows the platform to + identify what to do with incoming UART commands. RF chip is known to catch random commands + if not paired with a real remote (so called ghost commands). This problem is observed even + with the stock firmware and most probably is a bug in the MCU firmware or in the RF chip + firmware. Setting this to ``False`` instructs the platform to properly ignore such commands + and thus prevent unexpected switches or light intensity changes. +- **min_value** (*Optional*, int): The lowest dimmer value allowed. Acceptable value for your + setup will depend on actual light bulbs installed and number of them. Start with the default + value and check what will be the minimal brightness bulbs can render. Pay attention that for + some dimmable LED lamps minimal turn-on brightness will be higher that the minimal achievable + brightness if you just decrease it when lamp is already turned on. Defaults to 0. +- **max_value** (*Optional*, int): The highest dimmer value allowed. Use this to hard-limit light + intensity for your setup. For some bulbs this parameter might be also useful to prevent + flickering at high brightness values. Defaults to 100. +- All other options from :ref:`Light `. + + +See Also +-------- + +- :doc:`/components/light/index` +- :doc:`/components/uart` +- :doc:`/components/logger` +- :doc:`/components/esp8266` +- :ghedit:`Edit` diff --git a/components/mqtt.rst b/components/mqtt.rst index 3d9a75344..042dac909 100644 --- a/components/mqtt.rst +++ b/components/mqtt.rst @@ -24,6 +24,12 @@ in which case this is not needed. username: livingroom password: !secret mqtt_password + +.. note:: + + Support for esp-idf is still experminental. Please report issues you have with mqtt using the esp-idf framework. + + Configuration variables: ------------------------ @@ -71,8 +77,13 @@ Configuration variables: - **shutdown_message** (*Optional*, :ref:`mqtt-message`): The message to send when the node shuts down and the connection is closed cleanly. See :ref:`mqtt-last_will_birth` for more information. - **ssl_fingerprints** (*Optional*, list): Only on ESP8266. A list of SHA1 hashes used - for verifying SSL connections. See :ref:`mqtt-ssl_fingerprints` + for verifying SSL connections. See :ref:`mqtt-ssl_fingerprints`. for more information. +- **certificate_authority** *(Optional*, string): Only with `esp-idf`. CA certificate in PEM format. See :ref:`mqtt-tls-idf` for more information +- **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`. Default is false. If true publishing the message happens from the internal mqtt task. The client only enqueues the message. + 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. - **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 @@ -262,6 +273,56 @@ then run the ``mqtt-fingerprint`` script of ESPHome to get the certificate: .. _config-mqtt-component: + +.. _mqtt-tls-idf: + +TLS with esp-idf (esp32) +------------------------ + +If used with the esp-idf framework a TLS connection to a mqtt broker can be established. +The servers CA certificate is required to validate the connection. + +You have to download the server CA certficiate in PEM format and add it to ``certificate_authority``. +Usually these are .crt files and you can open them with any text editor. +Also make sure to change the ``port`` of the mqtt broker. Most brokers use port 8883 for TLS connections. + +.. code-block:: yaml + + mqtt: + broker: test.mymqtt.local + port: 8883 + discovery: true + discovery_prefix: ${mqtt_prefix}/homeassistant + log_topic: ${mqtt_prefix}/logs + skip_cert_cn_check: true + idf_send_async: false + certificate_authority: | + -----BEGIN CERTIFICATE----- + MIIEAzCCAuugAwIBAgIUBY1hlCGvdj4NhBXkZ/uLUZNILAwwDQYJKoZIhvcNAQEL + BQAwgZAxCzAJBgNVBAYTAkdCMRcwFQYDVQQIDA5Vbml0ZWQgS2luZ2RvbTEOMAwG + A1UEBwwFRGVyYnkxEjAQBgNVBAoMCU1vc3F1aXR0bzELMAkGA1UECwwCQ0ExFjAU + BgNVBAMMDW1vc3F1aXR0by5vcmcxHzAdBgkqhkiG9w0BCQEWEHJvZ2VyQGF0Y2hv + by5vcmcwHhcNMjAwNjA5MTEwNjM5WhcNMzAwNjA3MTEwNjM5WjCBkDELMAkGA1UE + BhMCR0IxFzAVBgNVBAgMDlVuaXRlZCBLaW5nZG9tMQ4wDAYDVQQHDAVEZXJieTES + MBAGA1UECgwJTW9zcXVpdHRvMQswCQYDVQQLDAJDQTEWMBQGA1UEAwwNbW9zcXVp + dHRvLm9yZzEfMB0GCSqGSIb3DQEJARYQcm9nZXJAYXRjaG9vLm9yZzCCASIwDQYJ + KoZIhvcNAQEBBQADggEPADCCAQoCggEBAME0HKmIzfTOwkKLT3THHe+ObdizamPg + UZmD64Tf3zJdNeYGYn4CEXbyP6fy3tWc8S2boW6dzrH8SdFf9uo320GJA9B7U1FW + Te3xda/Lm3JFfaHjkWw7jBwcauQZjpGINHapHRlpiCZsquAthOgxW9SgDgYlGzEA + s06pkEFiMw+qDfLo/sxFKB6vQlFekMeCymjLCbNwPJyqyhFmPWwio/PDMruBTzPH + 3cioBnrJWKXc3OjXdLGFJOfj7pP0j/dr2LH72eSvv3PQQFl90CZPFhrCUcRHSSxo + E6yjGOdnz7f6PveLIB574kQORwt8ePn0yidrTC1ictikED3nHYhMUOUCAwEAAaNT + MFEwHQYDVR0OBBYEFPVV6xBUFPiGKDyo5V3+Hbh4N9YSMB8GA1UdIwQYMBaAFPVV + 6xBUFPiGKDyo5V3+Hbh4N9YSMA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQEL + BQADggEBAGa9kS21N70ThM6/Hj9D7mbVxKLBjVWe2TPsGfbl3rEDfZ+OKRZ2j6AC + 6r7jb4TZO3dzF2p6dgbrlU71Y/4K0TdzIjRj3cQ3KSm41JvUQ0hZ/c04iGDg/xWf + +pp58nfPAYwuerruPNWmlStWAXf0UTqRtg4hQDWBuUFDJTuWuuBvEXudz74eh/wK + sMwfu1HFvjy5Z0iMDU8PUDepjVolOCue9ashlS4EB5IECdSR2TItnAIiIwimx839 + LdUdRudafMu5T5Xma182OC0/u/xRlEm+tvKGGmfFcN0piqVl8OrSPBgIlb+1IKJE + m/XriWr/Cq4h/JfB7NTsezVslgkBaoU= + -----END CERTIFICATE----- + + MQTT Component Base Configuration --------------------------------- diff --git a/components/remote_receiver.rst b/components/remote_receiver.rst index 69b2f44cc..84521c65c 100644 --- a/components/remote_receiver.rst +++ b/components/remote_receiver.rst @@ -40,7 +40,8 @@ Configuration variables: - **nexa**: Decode and dump Nexa (RF) codes. - **panasonic**: Decode and dump Panasonic infrared codes. - **pioneer**: Decode and dump Pioneer infrared codes. - - **raw**: Print all remote codes in their raw form. Useful for using arbitrary protocols. + - **pronto**: Print remote code in Pronto form. Useful for using arbitrary protocols. + - **raw**: Print all remote codes in their raw form. Also useful for using arbitrary protocols. - **rc5**: Decode and dump RC5 IR codes. - **rc_switch**: Decode and dump RCSwitch RF codes. - **samsung**: Decode and dump Samsung infrared codes. @@ -101,6 +102,9 @@ Automations: - **on_pioneer** (*Optional*, :ref:`Automation `): An automation to perform when a pioneer remote code has been decoded. A variable ``x`` of type :apistruct:`remote_base::PioneerData` is passed to the automation for use in lambdas. +- **on_pronto** (*Optional*, :ref:`Automation `): An automation to perform when a + Pronto remote code has been decoded. A variable ``x`` of type ``std::string`` + is passed to the automation for use in lambdas. - **on_raw** (*Optional*, :ref:`Automation `): An automation to perform when a raw remote code has been decoded. A variable ``x`` of type ``std::vector`` is passed to the automation for use in lambdas. @@ -213,6 +217,11 @@ Remote code selection (exactly one of these has to be included): - **rc_code_1** (**Required**, int): The remote control code to trigger on, see dumper output for more details. +- **pronto**: Trigger on a Pronto remote code with the given code. + + - **data** (**Required**, string): The code to listen for, see :ref:`remote_transmitter-transmit_raw` + for more info. Usually you only need to copy this directly from the dumper output. + - **raw**: Trigger on a raw remote code with the given code. - **code** (**Required**, list): The code to listen for, see :ref:`remote_transmitter-transmit_raw` diff --git a/components/sensor/growatt_solar.rst b/components/sensor/growatt_solar.rst index 84898cf17..f6f5c8855 100644 --- a/components/sensor/growatt_solar.rst +++ b/components/sensor/growatt_solar.rst @@ -34,6 +34,7 @@ to some pins on your board and the baud rate set to 9600. sensor: - platform: growatt_solar update_interval: 10s + protocol_version: RTU inverter_status: name: "Growatt Status Code" @@ -102,6 +103,9 @@ Configuration variables: - **inverter_status** (*Optional*): Status code of the inverter (0: waiting, 1: normal, 3:fault) +- **protocol_version** (*Optional*): Version of the protocol used by your inverter. + Old inverters use RTU (default). Newer ones use RTU2 (e.g. MIC, MIN, MAX series) + - **phase_a** (*Optional*): The group of exposed sensors for Phase A/1. - **current** (*Optional*): Use the current value of the sensor in amperes. All options from diff --git a/components/sensor/hydreon_rgxx.rst b/components/sensor/hydreon_rgxx.rst new file mode 100644 index 000000000..aea638d5d --- /dev/null +++ b/components/sensor/hydreon_rgxx.rst @@ -0,0 +1,114 @@ +Hydreon Rain Sensor +=================== + +.. seo:: + :description: Instructions for setting up Hydreon rain sensors + :image: hydreon_rg9.jpg + :keywords: hydreon + +The ``hydreon_rgxx`` sensor platform allows you to use rain sensors by Hydreon. Currently supported are the RG-9 and RG-15 (`rainsensors `_) sensors. +These optical rain sensors use a UART connection at 3.3V. The :ref:`UART ` is +required to be set up in your configuration for this sensor to work. + + +.. figure:: images/hydreon_rg9_full.jpg + :align: center + :width: 50.0% + + Hydreon RG-9 Rain Sensor. Image by `Hydreon `_. + +.. code-block:: yaml + + # Example RG-9 entry + + uart: + rx_pin: GPIO16 + tx_pin: GPIO17 + baud_rate: 9600 + + sensor: + - platform: hydreon_rgxx + model: "RG_9" + update_interval: 60s + moisture: + name: "rain" + expire_after: 120s + + binary_sensor: + - platform: hydreon_rgxx + too_cold: + name: "too cold" + +.. code-block:: yaml + + # Example RG-15 entry + + uart: + rx_pin: GPIO16 + tx_pin: GPIO17 + baud_rate: 9600 + + sensor: + - platform: hydreon_rgxx + model: "RG_15" + update_interval: 60s + acc: + name: "rain" + event_acc: + name: "rain event" + total_acc: + name: "rain total" + r_int: + name: "rain intensity" + +Configuration variables: +------------------------ + +- **model**: (**Required**, int): Specify which rain sensor you have connected. Must be either ``RG_9`` or ``RG_15``. + +- **uart_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`UART Component ` if you want + to use multiple UART buses. + +- **moisture** (*Optional*): Rain intensity level from 0-7. Only on RG-9. + + - **name** (**Required**, string): The name for the voltage sensor. + - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. + - All other options from :ref:`Sensor `. + +- **acc** (*Optional*): Amount of rain since last message (see `update_interval`), in `mm`. Only on RG-15. + + - **name** (**Required**, string): The name for the voltage sensor. + - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. + - All other options from :ref:`Sensor `. + +- **event_acc** (*Optional*): Amount of rain for this event (i.e. since it last stopped raining), in `mm`. Only on RG-15. + + - **name** (**Required**, string): The name for the voltage sensor. + - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. + - All other options from :ref:`Sensor `. + +- **total_acc** (*Optional*): Total amount of rain this sensor has ever measured, in `mm`. Only on RG-15. + + - **name** (**Required**, string): The name for the voltage sensor. + - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. + - All other options from :ref:`Sensor `. + +- **r_int** (*Optional*): Current rain intensity in `mm/h`. Only on RG-15. + + - **name** (**Required**, string): The name for the voltage sensor. + - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. + - All other options from :ref:`Sensor `. + +- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. + + +See Also +-------- + +- :ref:`sensor-filters` +- :doc:`../binary_sensor/hydreon_rgxx` +- `Hydreon RG-9 `__ +- `Hydreon RG-15 `__ +- `RG-15 V1.000 manual `__ +- `RG-9 V1.000 manual `__ +- :ghedit:`Edit` diff --git a/components/sensor/images/hydreon_rg9_full.jpg b/components/sensor/images/hydreon_rg9_full.jpg new file mode 100644 index 000000000..a3d774c45 Binary files /dev/null and b/components/sensor/images/hydreon_rg9_full.jpg differ diff --git a/components/sensor/images/xiaomi_rtcgq02lm.jpg b/components/sensor/images/xiaomi_rtcgq02lm.jpg new file mode 100644 index 000000000..f52af5019 Binary files /dev/null and b/components/sensor/images/xiaomi_rtcgq02lm.jpg differ diff --git a/components/sensor/mcp3204.rst b/components/sensor/mcp3204.rst index e38ffedd5..b8239a977 100644 --- a/components/sensor/mcp3204.rst +++ b/components/sensor/mcp3204.rst @@ -1,14 +1,15 @@ -MCP3204 4-Channel 12-Bit A/D Converter -====================================== +MCP3204 & MCP3208 12-Bit A/D Converters +======================================= .. seo:: - :description: Instructions for setting up MCP3204 12-Bit Analog to Digital Converter in ESPHome. - :keywords: MCP3204 + :description: Instructions for setting up MCP3204 & MCP3208 12-Bit Analog to Digital Converter in ESPHome. + :keywords: MCP3204 MCP3208 :image: mcp3204.jpg -The Microchip Technology Inc. MCP3204 +The Microchip Technology Inc. MCP3204 & MCP3208 devices are successive approximation 12-bit Analog-to-Digital (A/D) converters with on-board sample and -hold circuitry. +hold circuitry. This integration is common for both device types. +configure both devices as MCP3204 and observe the maximum number of channels as per variant used. .. figure:: images/mcp3204.jpg :align: center @@ -19,17 +20,18 @@ hold circuitry. Component/Hub ------------- -The MCP3204 component allows you to use MCP3204 4-Channel 12-Bit A/D Converter +The MCP3204 component allows you to use MCP3204 or MCP3208 12-Bit A/D Converter (`datasheet `__) in ESPHome. +The MCP3204 is a 4-channel and MCP3208 is an 8-channel device. It uses the :ref:`SPI Bus ` for communication. -Once configured, you can use any of the 4 pins as +Once configured, you can use any of the 4 or 8 pins (depending on device variant) as sensors for your projects. Each pin will respond with a voltage calculated off of the ``reference_voltage`` (default is 3.3V). It calculates the voltage by multiplying the ``reference_voltage * value`` on the pin (basically the percentage of VREF) -Most configurations will set the ``reference_voltage`` = VREF (pin 13 on the chip) +Most configurations will set the ``reference_voltage`` = VREF pin .. code-block:: yaml @@ -47,6 +49,12 @@ Most configurations will set the ``reference_voltage`` = VREF (pin 13 on the chi id: solar_voltage number: 0 # MCP3204 pin number + # In case MCP3208 is used. you can specify pin number > 4 + - platform: mcp3204 # Attached to pin 7 of the MCP3208. + update_interval: 1s + id: supply_voltage + number: 7 # MCP3208 pin number + Configuration variables: ************************ @@ -59,8 +67,8 @@ Configuration variables: Sensor ------ -The ``mcp3204`` sensor allows you to use your MCP3204 12-Bit A/D Converter sensors with ESPHome. -First, setup a :ref:`MCP3204 Hub ` for your MCP3204 sensor and then use this +The ``mcp3204`` sensor allows you to use your MCP3204 or MCP3208 12-Bit A/D Converter sensors with ESPHome. +First, setup a :ref:`MCP3204 Hub ` for your MCP3204/8 sensor and then use this sensor platform to create individual sensors that will report the voltage to Home Assistant. Configuration variables: diff --git a/components/sensor/qmp6988.rst b/components/sensor/qmp6988.rst new file mode 100644 index 000000000..8d777dfb4 --- /dev/null +++ b/components/sensor/qmp6988.rst @@ -0,0 +1,86 @@ +QMP6988 Temperature+Pressure Sensor +=================================== + +.. seo:: + :description: Instructions for setting up QMP6988 temperature and pressure sensors with ESPHome + :keywords: QMP6988 + +The ``qmp6988`` sensor platform allows you to use your QMP6988 +(`datasheet `__, +`M5Stack`_) temperature and pressure sensors with ESPHome. The :ref:`I²C ` is +required to be set up in your configuration for this sensor to work. + +.. figure:: ../../images/qmp6988_env3.png + :align: center + :width: 40.0% + + QMP6988 Temperature and Pressure Sensor. + +.. _M5Stack: https://docs.m5stack.com/en/unit/envIII + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: qmp6988 + temperature: + name: "Living Room Temperature" + oversampling: 16x + pressure: + name: "Living Room Pressure" + oversampling: 16x + address: 0x70 + update_interval: 60s + iir_filter: 2x + +Configuration variables: +------------------------ + +- **temperature** (*Optional*): The information for the temperature sensor + + - **name** (**Required**, string): The name for the temperature + sensor. + - **oversampling** (*Optional*): The oversampling parameter for the temperature sensor. + See :ref:`Oversampling Options `. + - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. + - All other options from :ref:`Sensor `. + +- **pressure** (*Optional*): The information for the pressure sensor. + + - **name** (**Required**, string): The name for the pressure sensor. + - **oversampling** (*Optional*): The oversampling parameter for the temperature sensor. + See :ref:`Oversampling Options `. + - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. + - All other options from :ref:`Sensor `. + +- **address** (*Optional*, int): Manually specify the I²C address of + the sensor. Defaults to ``0x70``. ``0x56`` is also configurable - see datasheet. +- **iir_filter** (*Optional*): Set up an Infinite Impulse Response filter to increase accuracy. One of + ``OFF``, ``2x``, ``4x``, ``8x``, ``16x``, ``32x``. Defaults to ``OFF``. +- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the + sensor. Defaults to ``60s``. + +.. _qmp6988-oversampling: + +Oversampling Options +-------------------- + +By default, the QMP6988 sensor has been configured to measure each value 8 times when requesting a new value. You can, however, +configure this amount. Possible oversampling values: + +- ``NONE`` (value is skipped) +- ``1x`` +- ``2x`` +- ``4x`` +- ``8x`` (default) +- ``16x`` +- ``32x`` +- ``64x`` + +See Also +-------- + +- :ref:`sensor-filters` +- :apiref:`qmp6988/qmp6988.h` +- `QMP6988 Library `__ by `M5Stack `__ +- :ghedit:`Edit` diff --git a/components/sensor/xiaomi_ble.rst b/components/sensor/xiaomi_ble.rst index f02a380a1..507113881 100644 --- a/components/sensor/xiaomi_ble.rst +++ b/components/sensor/xiaomi_ble.rst @@ -485,6 +485,43 @@ Configuration example: illuminance: name: "CGPR1 Illuminance" +RTCGQ02LM - Mi Motion Sensor 2 +****************************** + +Motion & ambient light sensor. Broadcasts motion detection, light/dark and battery status. Also has a button that broadcasts when pressed. +Requires a bindkey in order to decrypt the received data (see :ref:`obtaining_the_bindkey`). + +.. figure:: images/xiaomi_rtcgq02lm.jpg + :align: center + :width: 30.0% + +Configuration example: + +.. code-block:: yaml + + xiaomi_rtcgq02lm: + - id: motion_one + mac_address: 01:23:45:67:89:AB + bindkey: fe39106baeedb7c801e3d63c4396f97e + + binary_sensor: + - platform: xiaomi_rtcgq02lm + id: motion_one + motion: + name: "Mi Motion" + light: + name: "Mi Motion Sensor Light" + button: + name: "Mi Motion Sensor Button" + + sensor: + - platform: xiaomi_rtcgq02lm + id: motion_one + battery_level: + name: "Mi Motion Sensor Battery Level" + + + Setting Up Devices ------------------ diff --git a/conf.py b/conf.py index 8e23562a8..20e99eb77 100644 --- a/conf.py +++ b/conf.py @@ -66,9 +66,9 @@ author = "ESPHome" # built documents. # # The short X.Y version. -version = "2022.3" +version = "2022.4" # The full version, including alpha/beta/rc tags. -release = "2022.3.2" +release = "2022.4.0" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/guides/supporters.rst b/guides/supporters.rst index cc4fbf424..fc4195778 100644 --- a/guides/supporters.rst +++ b/guides/supporters.rst @@ -55,10 +55,12 @@ Contributors - `alva (@alva-seal) `__ - `Amish Vishwakarma (@amishv) `__ - `Jason Nader (@ammgws) `__ +- `Branden Cash (@ammmze) `__ - `anatoly-savchenkov (@anatoly-savchenkov) `__ - `andig (@andig) `__ - `András Bíró (@andrasbiro) `__ - `Andreas Hergert (@andreashergert1984) `__ +- `Andrew J.Swan (@andrewjswan) `__ - `andrewpc (@andrewpc) `__ - `Andrzej (@andriej) `__ - `Andreas (@anduchs) `__ @@ -115,6 +117,7 @@ Contributors - `buddydvd (@buddydvd) `__ - `buxtronix (@buxtronix) `__ - `bvansambeek (@bvansambeek) `__ +- `calco88 (@calco88) `__ - `Carlos Gustavo Sarmiento (@carlos-sarmiento) `__ - `Carlos Garcia Saura (@CarlosGS) `__ - `Carlos Ruiz (@CarlosRDomin) `__ @@ -190,6 +193,7 @@ Contributors - `Mark (@Diramu) `__ - `Dirk Heinke (@DirkHeinke) `__ - `Dirk Jahnke (@dirkj) `__ +- `djwlindenaar (@djwlindenaar) `__ - `Marcos Pérez Ferro (@djwmarcx) `__ - `Dan Mannock (@dmannock) `__ - `Dmitriy Lopatko (@dmitriy5181) `__ @@ -210,6 +214,7 @@ Contributors - `Sergey V. DUDANOV (@dudanov) `__ - `Duncan Findlay (@duncf) `__ - `dyarkovoy (@dyarkovoy) `__ +- `Janez Troha (@dz0ny) `__ - `Dimitris Zervas (@dzervas) `__ - `Dan Jackson (@e28eta) `__ - `Ermanno Baschiera (@ebaschiera) `__ @@ -272,6 +277,7 @@ Contributors - `Gabe Cook (@gabe565) `__ - `Gareth Cooper (@gaco79) `__ - `GeekVisit (@GeekVisit) `__ +- `Ian Reinhart Geiser (@geiseri) `__ - `R Huish (@genestealer) `__ - `Geoff Davis (@geoffdavis) `__ - `Geoffrey Van Landeghem (@geoffrey-vl) `__ @@ -325,6 +331,7 @@ Contributors - `igg (@igg) `__ - `Petko Bordjukov (@ignisf) `__ - `ikatkov (@ikatkov) `__ +- `Tim Smeets (@ikilledmypc) `__ - `imgbot[bot] (@imgbot[bot]) `__ - `ImSorryButWho (@ImSorryButWho) `__ - `Lorenzo Ortiz (@Infinitte) `__ @@ -336,6 +343,7 @@ Contributors - `Jan Harkes (@jaharkes) `__ - `Jakob Reiter (@jakommo) `__ - `James Braid (@jamesbraid) `__ +- `James Duke (@jamesduke) `__ - `James Gao (@jamesgao) `__ - `János Rusiczki (@janosrusiczki) `__ - `Jan Pieper (@janpieper) `__ @@ -345,6 +353,7 @@ Contributors - `Jas Strong (@jasstrong) `__ - `Jonas Bergler (@jbergler) `__ - `JbLb (@jblb) `__ +- `Jonathan Burns (@jburns20) `__ - `James Callaghan (@jcallaghan) `__ - `Josh Willox (@jcwillox) `__ - `jddonovan (@jddonovan) `__ @@ -357,6 +366,7 @@ Contributors - `Jérôme Laban (@jeromelaban) `__ - `Jesse Hills (@jesserockz) `__ - `Yuval Brik (@jhamhader) `__ +- `Joe (@jhansche) `__ - `Jim Bauwens (@jimbauwens) `__ - `Jérémy JOURDIN (@JJK801) `__ - `Jonathan Jefferies (@jjok) `__ @@ -471,6 +481,7 @@ Contributors - `matt123p (@matt123p) `__ - `Matteo Franceschini (@matteofranceschini) `__ - `Matthew Mazzanti (@matthewmazzanti) `__ +- `matthias882 (@matthias882) `__ - `Maurice Schleußinger (@maurice-schleussinger) `__ - `mbo18 (@mbo18) `__ - `mckaymatthew (@mckaymatthew) `__ @@ -514,6 +525,7 @@ Contributors - `MrZetor (@MrZetor) `__ - `mtl010957 (@mtl010957) `__ - `Murilo (@murilobaliego) `__ +- `Michel van de Wetering (@mvdwetering) `__ - `Michiel van Turnhout (@mvturnho) `__ - `Martin Weinelt (@mweinelt) `__ - `myhomeiot (@myhomeiot) `__ @@ -573,6 +585,7 @@ Contributors - `Pablo Clemente Maseda (@paclema) `__ - `Derrick Lyndon Pallas (@pallas) `__ - `Panuruj Khambanonda (PK) (@panuruj) `__ +- `parats15 (@parats15) `__ - `Pasi Suominen (@pasiz) `__ - `Patrick Felstead (@patfelst) `__ - `Paul Deen (@PaulAntonDeen) `__ @@ -613,6 +626,7 @@ Contributors - `Richard Miles (@r89m) `__ - `Pär Stålberg (@rabbadab) `__ - `Aaron Zhang (@rabbit-aaron) `__ +- `RadekHvizdos (@RadekHvizdos) `__ - `Radim Karniš (@radimkarnis) `__ - `Florian Ragwitz (@rafl) `__ - `Rai-Rai (@Rai-Rai) `__ @@ -648,6 +662,7 @@ Contributors - `Robbie Page (@rorpage) `__ - `rotarykite (@rotarykite) `__ - `rradar (@rradar) `__ +- `rrooggiieerr (@rrooggiieerr) `__ - `rspaargaren (@rspaargaren) `__ - `rsumner (@rsumner) `__ - `Rubén G. (@rubengargar) `__ @@ -715,10 +730,8 @@ Contributors - `TBobsin (@TBobsin) `__ - `Team Super Panda (@teamsuperpanda) `__ - `Ryan Hoffman (@tekmaven) `__ -- `Tempura San (@tempura-san) `__ - `testbughub (@testbughub) `__ - `Greg Lincoln (@tetious) `__ -- `Thane Gill (@thanegill) `__ - `Nejc (@thedexboy) `__ - `Thomas Eckerstorfer (@TheEggi) `__ - `TheGroundZero (@TheGroundZero) `__ @@ -749,8 +762,8 @@ Contributors - `Tom Price (@tomtom5152) `__ - `tony (@tony-fav) `__ - `David Kiliani (@torfbolt) `__ -- `Teemu Simola (@tpssim) `__ - `Felix Eckhofer (@tribut) `__ +- `Trick van Staveren (@trickv) `__ - `Tobias (@tripplet) `__ - `Troon (@Troon) `__ - `Tyler Bules (@Troublebrewing) `__ @@ -770,6 +783,7 @@ Contributors - `Nad (@valordk) `__ - `André Lademann (@vergissberlin) `__ - `Víctor Ferrer García (@vicfergar) `__ +- `Vincèn (@vincegre) `__ - `VitaliyKurokhtin (@VitaliyKurokhtin) `__ - `voibit (@voibit) `__ - `Xuming Feng (@voicevon) `__ @@ -808,4 +822,4 @@ Contributors - `Michael Labuschke (@zigman79) `__ - `Christian Zufferey (@zuzu59) `__ -*This page was last updated March 30, 2022.* +*This page was last updated April 20, 2022.* diff --git a/images/hydreon_rg9.jpg b/images/hydreon_rg9.jpg new file mode 100644 index 000000000..a4ba0b0e8 Binary files /dev/null and b/images/hydreon_rg9.jpg differ diff --git a/images/qmp6988_env3.png b/images/qmp6988_env3.png new file mode 100644 index 000000000..71869828f Binary files /dev/null and b/images/qmp6988_env3.png differ diff --git a/images/shellydimmer2.jpg b/images/shellydimmer2.jpg new file mode 100644 index 000000000..0d9186234 Binary files /dev/null and b/images/shellydimmer2.jpg differ diff --git a/images/sonoff_d1.jpg b/images/sonoff_d1.jpg new file mode 100644 index 000000000..7597689ec Binary files /dev/null and b/images/sonoff_d1.jpg differ diff --git a/images/xiaomi_rtcgq02lm.jpg b/images/xiaomi_rtcgq02lm.jpg new file mode 100644 index 000000000..48d0cdbe9 Binary files /dev/null and b/images/xiaomi_rtcgq02lm.jpg differ diff --git a/index.rst b/index.rst index caf1bc993..c75a4cb58 100644 --- a/index.rst +++ b/index.rst @@ -209,7 +209,7 @@ Analogue ADS1115, components/sensor/ads1115, ads1115.jpg, 4-channel ADC CD74HC4067, components/sensor/cd74hc4067, cd74hc4067.jpg, 16-channel analog multiplexer MCP3008, components/sensor/mcp3008, mcp3008.jpg, 8-channel ADC - MCP3204, components/sensor/mcp3204, mcp3204.jpg, 4-channel ADC + MCP3204/MCP3208, components/sensor/mcp3204, mcp3204.jpg, 4-channel ADC Resistance, components/sensor/resistance, omega.svg @@ -295,11 +295,13 @@ Environmental HDC1080, components/sensor/hdc1080, hdc1080.jpg, Temperature & Humidity Honeywell ABP, components/sensor/honeywellabp, honeywellabp.jpg, Pressure & Temperature HTU21D / Si7021 / SHT21, components/sensor/htu21d, htu21d.jpg, Temperature & Humidity + Hydreon Rain Sensor, components/sensor/hydreon_rgxx, hydreon_rg9.jpg, Rain Inkbird IBS-TH1 Mini, components/sensor/inkbird_ibsth1_mini, inkbird_isbth1_mini.jpg, Temperature & Humidity MCP9808, components/sensor/mcp9808, mcp9808.jpg, Temperature MH-Z19, components/sensor/mhz19, mhz19.jpg, CO2 & Temperature MS5611, components/sensor/ms5611, ms5611.jpg, Pressure NTC Thermistor, components/sensor/ntc, ntc.jpg, Temperature + QMP6988, components/sensor/qmp6988, qmp6988_env3.png, Temperature & Pressure RadonEye BLE, components/sensor/radon_eye_ble, radon_eye_logo.png, Radon RuuviTag, components/sensor/ruuvitag, ruuvitag.jpg, Temperature & Humidity & Accelerometer SCD30, components/sensor/scd30, scd30.jpg, CO2 & Temperature & Humidity @@ -400,6 +402,7 @@ Binary Sensor Components Analog Threshold, components/binary_sensor/analog_threshold, analog_threshold.svg ESP32 BLE Presence, components/binary_sensor/ble_presence, bluetooth.svg 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 @@ -462,9 +465,11 @@ Light Components Light Partition, components/light/partition, color_lens.svg Tuya Dimmer, components/light/tuya, tuya.png + Shelly Dimmer, components/light/shelly_dimmer, shellydimmer2.jpg Custom Light, components/light/custom, language-cpp.svg H-bridge Light, components/light/hbridge, brightness-medium.svg + Sonoff D1 Dimmer, components/light/sonoff_d1, sonoff_d1.jpg Looking for WS2811 and similar individually addressable lights? Have a look at the :doc:`FastLED Light `.