diff --git a/Doxygen b/Doxygen index 31fa5d55d..5f634dfbd 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 = 1.17.2 +PROJECT_NUMBER = 1.18.0b1 # 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 06150d7ba..672b9e0ad 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,5 @@ ESPHOME_PATH = ../esphome -ESPHOME_REF = v1.17.2 +ESPHOME_REF = v1.18.0b1 .PHONY: html html-strict cleanhtml deploy help webserver Makefile netlify netlify-api api netlify-dependencies svg2png copy-svg2png diff --git a/_static/version b/_static/version index 0e1f39b86..e4e8fab72 100644 --- a/_static/version +++ b/_static/version @@ -1 +1 @@ -1.17.2 \ No newline at end of file +1.18.0b1 \ No newline at end of file diff --git a/changelog/index.rst b/changelog/index.rst index 8dd643894..bcd2faef6 100644 --- a/changelog/index.rst +++ b/changelog/index.rst @@ -2,7 +2,7 @@ Changelog ========= .. redirect:: - :url: /changelog/v1.17.0.html + :url: /changelog/v1.18.0.html .. toctree:: :glob: diff --git a/changelog/v1.18.0.rst b/changelog/v1.18.0.rst new file mode 100644 index 000000000..401c91140 --- /dev/null +++ b/changelog/v1.18.0.rst @@ -0,0 +1,105 @@ +Changelog - Version 1.18.0 - TBD +=============================================== + +.. seo:: + :description: Changelog for ESPHome version 1.18.0. + :image: /_static/changelog-1.18.0.png + :author: ESPHome + :author_twitter: @esphome_ + +.. imgtable:: + :columns: 5 + + BME680 via BSEC, components/sensor/bme680_bsec, bme680.jpg + b-parasite, components/sensor/b_parasite, b_parasite.jpg + SGP40, components/sensor/sgp40, sgp40.jpg + SHT4X, components/sensor/sht4x, sht4x.jpg + TCA9548A I²C Multiplexer, components/tca9548a, tca9548a.jpg + + Grow Fingerprint Reader, components/fingerprint_grow, fingerprint.svg + TOF10120, components/sensor/tof10120, tof10120.jpg + ESP32 BLE Client, components/ble_client, bluetooth.svg + External Components, components/external_components, external_components.svg + + +New Integrations +---------------- + +- esphome: Add I2CMultiplexer in general and the TCA9548A in special :esphomepr:`1410` by :ghuser:`andreashergert1984` (new-integration) +- esphome: Add BME680 via BSEC integration :esphomepr:`1313` by :ghuser:`trvrnrth` (new-integration) +- esphome: Adds support for b-parasite soil moisture sensor :esphomepr:`1666` by :ghuser:`rbaron` (new-integration) +- esphome: Sgp40 :esphomepr:`1513` by :ghuser:`SenexCrenshaw` (new-integration) +- esphome: Add support for SHT4X :esphomepr:`1512` by :ghuser:`sjtrny` (new-integration) +- esphome: Add Grow Fingerprint Reader :esphomepr:`1356` by :ghuser:`loongyh` (new-integration) +- esphome: Support for TOF10120 distance sensor :esphomepr:`1375` by :ghuser:`wstrzalka` (new-integration) +- esphome: BLE client support on ESP32 :esphomepr:`1177` by :ghuser:`buxtronix` (new-integration) +- esphome: Implement external custom components installing from YAML :esphomepr:`1630` (new-integration) + +Breaking Changes +---------------- + +- esphome: Raise minimum python version to 3.7 :esphomepr:`1673` (breaking-change) +- esphome: Change wifi signal strength unit to dBm :esphomepr:`1734` by :ghuser:`mbo18` (breaking-change) + +All changes +----------- + +- esphome: Add I2CMultiplexer in generel and the TCA9548A in special :esphomepr:`1410` by :ghuser:`andreashergert1984` (new-integration) +- docs: Add i2c multiplexer :docspr:`897` by :ghuser:`andreashergert1984` +- esphome: Add the display.is_displaying_page condition :esphomepr:`1646` by :ghuser:`numo68` +- docs: Add documentation for the display.is_displaying_page condition :docspr:`1079` by :ghuser:`numo68` +- esphome: Add BME680 via BSEC integration :esphomepr:`1313` by :ghuser:`trvrnrth` (new-integration) +- docs: Add BME680 BSEC docs :docspr:`793` by :ghuser:`trvrnrth` +- esphome: Fixed CustomComponentConstructor::get_component() :esphomepr:`1653` by :ghuser:`dataway` +- esphome: Bump pytest from 6.2.2 to 6.2.3 :esphomepr:`1663` by :ghuser:`dependabot[bot]` +- esphome: Bump protobuf from 3.15.6 to 3.15.7 :esphomepr:`1662` by :ghuser:`dependabot[bot]` +- esphome: Rewrite sun component calculations :esphomepr:`1661` +- esphome: Raise minimum python version to 3.7 :esphomepr:`1673` (breaking-change) +- esphome: Adds support for b-parasite soil moisture sensor :esphomepr:`1666` by :ghuser:`rbaron` (new-integration) +- docs: Adds docs for the b-parasite soil moisture sensor :docspr:`1086` by :ghuser:`rbaron` +- esphome: mqtt_client: Added MQTTClientComponent::unsubscribe() :esphomepr:`1672` by :ghuser:`dataway` +- esphome: Disallow _ in node name :esphomepr:`1632` by :ghuser:`pkuehne` +- esphome: Receive long MQTT payload :esphomepr:`1590` by :ghuser:`gaco79` +- esphome: Daylight Saving Time spelling fix :esphomepr:`1677` by :ghuser:`dashdrum` +- esphome: Support custom build_flags for bme680_bsec :esphomepr:`1678` by :ghuser:`SenexCrenshaw` +- esphome: Add Arduino ESP32 version mapping :esphomepr:`1679` +- esphome: Automate building and publishing of esphome-lint docker image :esphomepr:`1680` +- esphome: Sgp40 :esphomepr:`1513` by :ghuser:`SenexCrenshaw` (new-integration) +- docs: sgp40 :docspr:`985` by :ghuser:`SenexCrenshaw` +- esphome: Bump protobuf from 3.15.7 to 3.15.8 :esphomepr:`1682` by :ghuser:`dependabot[bot]` +- esphome: Implementing the remainder of GPS data for the GPS component. :esphomepr:`1676` by :ghuser:`coogle` +- docs: Updating docs for the gps component. :docspr:`1094` by :ghuser:`coogle` +- esphome: Bump AsyncTCP-esphome to 1.2.1. :esphomepr:`1693` by :ghuser:`mmakaay` +- esphome: Revert "Bump AsyncTCP-esphome to 1.2.1." :esphomepr:`1709` by :ghuser:`glmnet` +- esphome: Fix name_add_mac_suffix using _ instead of - :esphomepr:`1702` by :ghuser:`glmnet` +- docs: Update name_add_mac_suffix use dash :docspr:`1111` by :ghuser:`glmnet` +- esphome: Add monochromatic effects: Pulse, Random :esphomepr:`1616` by :ghuser:`ferbar` +- docs: Add 'pulse' effect doc :docspr:`1067` by :ghuser:`ferbar` +- esphome: Add support for SHT4X :esphomepr:`1512` by :ghuser:`sjtrny` (new-integration) +- docs: Add docs for SHT4X :docspr:`1002` by :ghuser:`sjtrny` +- esphome: Addition of forward and reverse active energy counters to ATM90E32 sensor component :esphomepr:`1271` by :ghuser:`elyorkhakimov` +- docs: Add Atm90e32 energy docs :docspr:`1120` by :ghuser:`jesserockz` +- esphome: Add Grow Fingerprint Reader :esphomepr:`1356` by :ghuser:`loongyh` (new-integration) +- docs: Add Grow fingerprint reader docs :docspr:`835` by :ghuser:`loongyh` +- esphome: Support for TOF10120 distance sensor :esphomepr:`1375` by :ghuser:`wstrzalka` (new-integration) +- docs: Documentation for TOF10120 support :docspr:`846` by :ghuser:`wstrzalka` +- esphome: Swap fan and swing fields for Fujitu ACs :esphomepr:`1635` by :ghuser:`alex-richards` +- esphome: BLE client support on ESP32 :esphomepr:`1177` by :ghuser:`buxtronix` (new-integration) +- docs: Ble client docs :docspr:`702` by :ghuser:`buxtronix` +- esphome: Update email addresses :esphomepr:`1733` by :ghuser:`jesserockz` +- esphome: Ble client fixes :esphomepr:`1739` by :ghuser:`buxtronix` +- esphome: Fix #1940: Implement speed_count in TuyaFan :esphomepr:`1654` by :ghuser:`0x0a11c0de` +- docs: Add speed_count to tuya fan :docspr:`1080` by :ghuser:`0x0a11c0de` +- docs: Fix mcp3008 reference :docspr:`1131` by :ghuser:`jesserockz` +- esphome: Add Hyperion Support :esphomepr:`1339` by :ghuser:`d-two` +- docs: Add note about hyperion classic udp port :docspr:`1135` by :ghuser:`jesserockz` +- esphome: Call ``Stepper::should_step_`` every loop iteration :esphomepr:`1373` by :ghuser:`akonradi` +- esphome: Add support for controlling Tuya fan direction :esphomepr:`1409` by :ghuser:`rmounce` +- docs: Document Tuya fan direction datapoint :docspr:`877` by :ghuser:`rmounce` +- esphome: Change wifi signal strength unit to dBm :esphomepr:`1734` by :ghuser:`mbo18` (breaking-change) +- docs: Change wifi signal strength unit to dBm :docspr:`1125` by :ghuser:`mbo18` +- esphome: Added an option to disable mDNS :esphomepr:`1716` by :ghuser:`dnetguru` +- docs: Added docs for enable_mdns option :docspr:`1118` by :ghuser:`dnetguru` +- docs: add External components docs :docspr:`1107` by :ghuser:`glmnet` +- esphome: Implement external custom components installing from YAML :esphomepr:`1630` (new-integration) +- esphome: Update copyright year :esphomepr:`1760` by :ghuser:`bonanitech` diff --git a/components/ble_client.rst b/components/ble_client.rst new file mode 100644 index 000000000..452342c8c --- /dev/null +++ b/components/ble_client.rst @@ -0,0 +1,214 @@ +BLE Client +========== + +.. seo:: + :description: Configuration of the BLE client on ESP32. + :image: bluetooth.svg + +The ``ble_client`` component enables connections to Bluetooth +Low Energy devices in order to query and control them. This +component does not expose any sensors or output components itself, +but merely manages connections to them for use by other components. + +.. note:: + + The BLE software stack on the ESP32 consumes a significant + amount of RAM on the device. As such, you may experience + frequent crashes due to out-of-memory if you enable many + other components. + + A maximum of three devices is supported due to limitations in the + ESP32 BLE stack. If you wish to connect more devices, use additional + ESP32 boards. + + This component does not (yet) support devices that require + security settings (eg connecting with a PIN). + + Currently, devices connected with the client cannot be + supported by other components based on :doc:`/components/esp32_ble_tracker` + as they listen to advertisements which are only sent by devices + without an active connection. + +Despite the last point above, the ``ble_client`` component requires +the ``esp32_ble_tracker`` component in order to discover available +client devices. + +.. code-block:: yaml + + esp32_ble_tracker: + + ble_client: + - mac_address: FF:FF:20:00:0F:15 + id: itag_black + +Configuration variables: +------------------------ + +- **mac_address** (*Required*, MAC Address): The MAC address of the BLE device to connect to. +- **id** (*Required*, :ref:`config-id`): The ID to use for code generation, and for reference by dependent components. + +Automations: + +- **on_connect** (*Optional*, :ref:`Automation `): An automation to perform + when the client connects to a device. See :ref:`ble_client-on_connect`. +- **on_disconnect** (*Optional*, :ref:`Automation `): An automation to perform + when the client disconnects from a device. See :ref:`ble_client-on_disconnect`. + +BLE Client Automation +--------------------- + +.. _ble_client-on_connect: + +``on_connect`` +************** + +This automation is triggered when the client connects to the BLE device. + +.. code-block:: yaml + + ble_client: + - mac_address: 11:22:33:44:55:66 + id: ble_itag + on_connect: + then: + - lambda: |- + ESP_LOGD("ble_client_lambda", "Connected to BLE device"); + +.. _ble_client-on_disconnect: + +``on_disconnect`` +***************** + +This automation is triggered when the client disconnects from a BLE device. + +.. code-block:: yaml + + ble_client: + - mac_address: 11:22:33:44:55:66 + id: ble_itag + on_disconnect: + then: + - lambda: |- + ESP_LOGD("ble_client_lambda", "Disconnected from BLE device"); + +BLE Overview +------------ +This section gives a brief overview of the Bluetooth LE architecture +to help with understanding this and the related components. There are +plenty of more detailed references online. + +BLE uses the concept of a *server* and a *client*. In simple terms, +the server is implemented on the device providing services, usually +these are the devices such as heart monitors, tags, weather stations, +etc. The client connects to the server and makes use of its services. +The client will often be an app on a phone, or in the case of ESPHome, +it's the ESP32 device. + +When a client connects to a server, the client queries for *services* +provided by the server. Services expose categories of functionality +on the server. These might be well defined and supported services, +such as the Battery Level service, Device Information or Heart Rate. +Or they might be custom services designed just for that device. For +example the button on cheap iTags uses a custom service. + +Each service then defines one or more *characteristics* which are +typically the discrete values of that service. For example for the +Environmental Sensor service characteristics exposed include the +Wind Speed, Humidity and Rainfall. Each of these may be read-only +or read-write, depending on their functionality. + +A characteristic may also expose one or more *descriptors*, which carry +further information about the characteristic. This could be things +like the units, the valid ranges, and whether notifications (see below) +are enabled. + +BLE also supports *notifications*. A client continuously polling for +updates could consume a lot of power, which is undesirable for a +protocol that's designed to be low energy. Instead, a server can push +updates to the client only when they change. Depending on their purpose +and design, a characteristic may allow for notifications to be sent. The +client can then enable notifications by setting the configuration +descriptor for the characteristic. + +Each service, characteristic, and descriptor is identified by a +unique identifier (UUID) that may be between 16 and 128 bits long. +A client will typically identify a device's capabilities based on +the UUIDs. + +Once the connection is established, referencing each +service/characteristic/descriptor by the full UUID would take a +considerable portion of the small (~23 byte) packet. So the +characteristics and descriptors also provide a small 2-byte +*handle* (alias) to maximise available data space. + +Setting Up Devices +------------------ + +Whilst the component can connect to most BLE devices (that do not +require authentication/pin), useful functionality is only obtained +through dependent components, such as :doc:`/components/sensor/ble_sensor`. +See the documentation for these components for details on setting up +specific devices. + +In order to use the ``ble_client`` component, you need to enable the +:doc:`/components/esp32_ble_tracker` component. This will also allow you to discover +the MAC address of the device. + +When you have discovered the MAC address of the device, you can add it +to the ``ble_client`` stanza. + +If you then build and upload this configuration, the ESP will listen for +the device and attempt to connect to it when it is discovered. The component +will then query the device for all available services and characteristics and +display them in the log: + +.. code-block:: text + + [18:24:56][D][ble_client:043]: Found device at MAC address [FC:58:FA:B1:F8:93] + [18:24:56][I][ble_client:072]: Attempting BLE connection to fc:58:fa:b1:f8:93 + [18:24:56][I][ble_client:097]: [fc:58:fa:b1:f8:93] ESP_GATTC_OPEN_EVT + [18:24:57][I][ble_client:143]: Service UUID: 0x1800 + [18:24:57][I][ble_client:144]: start_handle: 0x1 end_handle: 0x5 + [18:24:57][I][ble_client:305]: characteristic 0x2A00, handle 0x3, properties 0x2 + [18:24:57][I][ble_client:305]: characteristic 0x2A01, handle 0x5, properties 0x2 + [18:24:57][I][ble_client:143]: Service UUID: 0x1801 + [18:24:57][I][ble_client:144]: start_handle: 0x6 end_handle: 0x6 + [18:24:57][I][ble_client:143]: Service UUID: 0x180A + [18:24:57][I][ble_client:144]: start_handle: 0x7 end_handle: 0x19 + [18:24:57][I][ble_client:305]: characteristic 0x2A29, handle 0x9, properties 0x2 + [18:24:57][I][ble_client:305]: characteristic 0x2A24, handle 0xb, properties 0x2 + [18:24:57][I][ble_client:305]: characteristic 0x2A25, handle 0xd, properties 0x2 + [18:24:57][I][ble_client:305]: characteristic 0x2A27, handle 0xf, properties 0x2 + [18:24:57][I][ble_client:305]: characteristic 0x2A26, handle 0x11, properties 0x2 + [18:24:57][I][ble_client:305]: characteristic 0x2A28, handle 0x13, properties 0x2 + [18:24:57][I][ble_client:305]: characteristic 0x2A23, handle 0x15, properties 0x2 + [18:24:57][I][ble_client:305]: characteristic 0x2A2A, handle 0x17, properties 0x2 + [18:24:57][I][ble_client:305]: characteristic 0x2A50, handle 0x19, properties 0x2 + [18:24:57][I][ble_client:143]: Service UUID: F000FFC0045140-00B0-0000-0000-000000 + [18:24:57][I][ble_client:144]: start_handle: 0x1a end_handle: 0x22 + [18:24:57][I][ble_client:305]: characteristic F000FFC1045140-00B0-0000-0000-000000, handle 0x1c, properties 0x1c + [18:24:57][I][ble_client:343]: descriptor 0x2902, handle 0x1d + [18:24:57][I][ble_client:343]: descriptor 0x2901, handle 0x1e + [18:24:57][I][ble_client:305]: characteristic F000FFC2045140-00B0-0000-0000-000000, handle 0x20, properties 0x1c + [18:24:57][I][ble_client:343]: descriptor 0x2902, handle 0x21 + [18:24:57][I][ble_client:343]: descriptor 0x2901, handle 0x22 + [18:24:57][I][ble_client:143]: Service UUID: 0xFFE0 + [18:24:57][I][ble_client:144]: start_handle: 0x23 end_handle: 0x26 + [18:24:57][I][ble_client:305]: characteristic 0xFFE1, handle 0x25, properties 0x10 + [18:24:57][I][ble_client:343]: descriptor 0x2902, handle 0x26 + [18:24:57][I][ble_client:143]: Service UUID: 0x1802 + [18:24:57][I][ble_client:144]: start_handle: 0x27 end_handle: 0x29 + [18:24:57][I][ble_client:305]: characteristic 0x2A06, handle 0x29, properties 0x4 + + +The discovered services can then be used to enable and configure other +ESPHome components, for example Service UUID 0xFFE0 is used for iTag style +keychain button events, used by the :doc:`/components/sensor/ble_sensor` component. + +See Also +-------- + +- :doc:`/components/sensor/ble_sensor` +- :ref:`Automation ` +- :apiref:`ble_client/ble_client.h` +- :ghedit:`Edit` diff --git a/components/display/index.rst b/components/display/index.rst index a8aa8fdb1..b3e1ff07e 100644 --- a/components/display/index.rst +++ b/components/display/index.rst @@ -549,6 +549,27 @@ You can then switch between these with three different actions: - display.page.show_next: my_display - component.update: my_display +.. _display-is_displaying_page-condition: + +**display.is_displaying_page**: This condition returns true while the specified page is being shown. + +.. code-block:: yaml + + # In some trigger: + on_...: + - if: + condition: + display.is_displaying_page: page1 + then: + ... + - if: + condition: + display.is_displaying_page: + id: my_display + page_id: page2 + then: + ... + See Also -------- diff --git a/components/esphome.rst b/components/esphome.rst index 0247c7e3f..66c94e886 100644 --- a/components/esphome.rst +++ b/components/esphome.rst @@ -49,8 +49,8 @@ Advanced options: - **libraries** (*Optional*, list of libraries): A list of `platformio libraries `__ to include in the project. See `platformio lib install `__. - **comment** (*Optional*, string): Additional text information about this node. Only for display in UI. -- **name_add_mac_suffix** (*Optional*, boolean): Appends the last 6 bytes of the mac address of the device to - the name in the form `_aabbcc`. Defaults to ``False``. +- **name_add_mac_suffix** (*Optional*, boolean): Appends the last 6 bytes of the mac address of the device to + the name in the form `-aabbcc`. Defaults to ``False``. See :ref:`esphome-mac_suffix`. ESP8266 Options: diff --git a/components/ethernet.rst b/components/ethernet.rst index 0d6b68bdf..791b763fb 100644 --- a/components/ethernet.rst +++ b/components/ethernet.rst @@ -54,6 +54,7 @@ Configuration variables: - **dns1** (*Optional*, IPv4 address): The main DNS server to use. - **dns2** (*Optional*, IPv4 address): The backup DNS server to use. +- **enable_mdns** (*Optional*, boolean): Controls if your node should advertise its presense and services using mDNS. When set to ``false`` you won't be able to access your node using its hostname which can break certain functionalities. Please see :ref:`notes on disabling mDNS `. Defaults to ``true``. - **domain** (*Optional*, string): Set the domain of the node hostname used for uploading. For example, if it's set to ``.local``, all uploads will be sent to ``.local``. Defaults to ``.local``. diff --git a/components/external_components.rst b/components/external_components.rst new file mode 100644 index 000000000..828bf0e0e --- /dev/null +++ b/components/external_components.rst @@ -0,0 +1,166 @@ +External Components +=================== + +.. seo:: + :description: Instructions for setting up ESPHome External Components. + :keywords: External, Custom, Components, ESPHome + +You can easily import community components using the external components feature. Bundled components +can be overridden using this feature. + +.. code-block:: yaml + + external_components: + # use rtttl and dfplayer from ESPHome's dev branch in GitHub + - source: + type: git + url: https://github.com/esphome/esphome + ref: dev + components: [ rtttl, dfplayer ] + + # equivalent shorthand for GitHub + - source: github://esphome/esphome@dev + components: [ rtttl ] + +Configuration variables: + +- **source**: The location of the components you want to retrieve. See :ref:`external-components_local` + and :ref:`external-components_git`. + + - **type** (**Required**): Repository type. One of ``local``, ``git``. + + git options: + + - **url** (**Required**, url): Http git repository url. See :ref:`external-components_git`. + - **ref** (*Optional*, string): Git ref (branch or tag). If not specified the default branch is used. + + local options: + + - **path** (**Required**): Path to use when using local components. See :ref:`external-components_local`. + +- **components** (*Optional*, list): The list of components to retrieve from the external source. + Defaults to ``all``. + +- **refresh** (*Optional*, :ref:`time `): The interval the source will be checked. Has no + effect on ``local``. See :ref:`external-components_refresh`. for more info. Defaults to ``1day``. + + +.. _external-components_local: + +Local +----- + +You can specify a local path for the external components, this is most useful if you want to manually +control the origin of the files. + +.. code-block:: yaml + + external_components: + source: + path: /copied_components + + # shorthand + external_components: + source: my_components + + +Notice that relative paths are supported, so you can enter ``my_components`` as the source path and then +ESPHome will load components from a ``my_components`` folder in the same folder where your YAML configuration +is. + + +.. _external-components_git: + +Git +--- + +Retrieving components from git is the easiest way to use components not included in ESPHome by default. +The source components should be inside a ``components`` folder or inside an ``esphome/components`` +folder. The latter makes sharing a component from a forked ESPHome repository easier. + +Example of git repositories +*************************** + +For repositories where you share one or a few components: + +.. code-block:: text + + components +   ├── my_component1 +   │   ├── __init__.py +   │   ├── component1.cpp +   │   ├── component1.h +   │   └── sensor.py +   └── my_component2 +      ├── __init__.py +      ├── component2.cpp +      ├── component2.h +      └── switch.py + example_component1.yaml <- not required but recommended + README.md + + +or, this structure is also supported, which makes handy to share components from a **forked** ESPHome +repository: + +.. code-block:: text + + esphome + ├── components + │   ├── my_component1 + │   │   ├── __init__.py + │   │   ├── component1.cpp + │   │   ├── component1.h + │   │   └── sensor.py + │   ├── my_component2 + │   │   ├── __init__.py + │   │   ├── component2.cpp + │   │   ├── component2.h + │   │   └── switch.py + │  ... + ... + +Http git repositories in general are supported with this configuration: + +.. code-block:: yaml + + external_components: + source: + type: git + url: http://repository_url/ + ref: branch_or_tag + +The source fields accepts a short hand **github://** resource: + +.. code-block:: yaml + + external_components: + # shorthand + source: github:///[@] + +Under the hood, during validation, ESPHome will clone the git repository into the hidden ``.esphome`` +folder and components will then be loaded from this local copy. The local path of the cloned repository +varies per repository name and ref name, so repositories with different refs are considered different +repositories and updated independently. + +.. _external-components_refresh: + +Refresh +******* + +Components are initially cloned into a cache directory, then the repository is checked for updates +(via *git pull*) after the ``refresh:`` time passes since last check. + +You can make ESPHome check the repository every time by setting this option to ``0s``, however since +ESPHome is validating the configuration continuously while using the dashboard or the vscode extension, +it is not recommended to set this value to less than a few minutes to avoid validation slow down and +excessive repository checks. + +Likewise, you can set this setting to ``never`` and ESPHome will never +**update** the repository, useful e.g. when ``ref`` points to a **tag**. + + +See Also +-------- + +- :ghedit:`Edit` diff --git a/components/fan/tuya.rst b/components/fan/tuya.rst index 8fb4e8299..9d0a06657 100644 --- a/components/fan/tuya.rst +++ b/components/fan/tuya.rst @@ -55,6 +55,9 @@ Configuration variables: - **switch_datapoint** (**Required**, int): The datapoint id number of the fan switch. - **oscillation_datapoint** (*Optional*, int): The datapoint id number of the oscillation switch. Probably not supported on any Tuya controllers currently, but it's there if need be. +- **direction_datapoint** (**Optional**, int): The datapoint id number of the direction + switch. Supported by some ceiling fans. +- **speed_count** (*Optional*, int): Set the number of supported discrete speed levels. Defaults to ``3``. - All other options from :ref:`Fan `. .. note:: diff --git a/components/fingerprint_grow.rst b/components/fingerprint_grow.rst new file mode 100644 index 000000000..9b5c3339b --- /dev/null +++ b/components/fingerprint_grow.rst @@ -0,0 +1,530 @@ +Grow Fingerprint Reader +======================= + +.. seo:: + :description: Instructions for setting up Grow Fingerprint Reader integration in ESPHome. + :image: fingerprint.png + +The ``fingerprint_grow`` component allows you to use your R307, R503, ZFM-20, ... fingerprint sensors with ESPHome. + +.. figure:: images/r307-full.jpg + :align: center + :width: 50.0% + + R307/ZFM-20 Optical Fingerprint Reader (`datasheet `__, `Adafruit `__). Image by `Adafruit `__. + +.. figure:: images/r503-full.jpg + :align: center + :width: 50.0% + + R503 Capacitive Fingerprint Reader with Bi-Color Aura LED (`datasheet `__, `Adafruit `__). Image by `Adafruit `__. + +Overview +-------- + +The reader can be powered by the 3.3V output of an NodeMCU. As the communication with the reader is done using UART (default baud rate is 57600), you need to have an :ref:`UART bus ` in your configuration with the ``rx_pin`` connected to the reader's ``TX`` and the ``tx_pin`` connected to the reader's ``RX``. + +If available on your reader model, it's recommended to connect 3.3VT (touch induction power supply) to 3.3V; WAKEUP (finger detection signal) to a free GPIO pin and define it with the ``sensing_pin`` option to allow the polling function to quickly return when there's no finger on the reader. + +.. code-block:: yaml + + # Example configuration entry + uart: + rx_pin: GPIO13 + tx_pin: GPIO15 + baud_rate: 57600 + + # Declare Grow Fingerprint Reader + fingerprint_grow: + sensing_pin: GPIO12 + on_finger_scan_matched: + - text_sensor.template.publish: + id: fingerprint_state + state: "Authorized finger" + - switch.turn_on: gate + - delay: 500ms + - switch.turn_off: gate + on_finger_scan_unmatched: + - text_sensor.template.publish: + id: fingerprint_state + state: "Unauthorized finger" + on_enrollment_scan: + - text_sensor.template.publish: + id: fingerprint_state + state: "Finger scanned" + on_enrollment_done: + - text_sensor.template.publish: + id: fingerprint_state + state: "Enrolled fingerprint" + on_enrollment_failed: + - text_sensor.template.publish: + id: fingerprint_state + state: "Failed to enroll fingerprint" + + # Optional template text sensor for visual feedback + text_sensor: + - platform: template + id: fingerprint_state + name: "Fingerprint State" + + # Optional component (GPIO switch, lock etc.) to control in on_finger_scan_matched trigger + switch: + - platform: gpio + pin: GPIO14 + id: gate + + # Optional sensors + binary_sensor: + - platform: fingerprint_grow + id: fingerprint_enrolling + name: "Fingerprint Enrolling" + + sensor: + - platform: fingerprint_grow + fingerprint_count: + name: "Fingerprint Count" + last_finger_id: + name: "Fingerprint Last Finger ID" + last_confidence: + name: "Fingerprint Last Confidence" + status: + name: "Fingerprint Status" + capacity: + name: "Fingerprint Capacity" + security_level: + name: "Fingerprint Security Level" + + +Configuration variables: +------------------------ + +The configuration is made up of three parts: The central component, optional individual sensors, and the optional enrolling binary sensor. + +Base Configuration: + +- **uart_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the UART hub. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- **sensing_pin** (*Optional*, :ref:`Pin Schema `): Pin connected to the reader's finger detection signal (WAKEUP) output. +- **password** (*Optional*, int): Password to use for authentication. Defaults to ``0x00``. +- **set_password** (*Optional*, int): Sets a new password to use for authentication. See :ref:`fingerprint_grow-set_new_password` for more information. +- **on_finger_scan_matched** (*Optional*, :ref:`Automation `): An action to be performed when an enrolled fingerprint is scanned. See :ref:`fingerprint_grow-on_finger_scan_matched`. +- **on_finger_scan_unmatched** (*Optional*, :ref:`Automation `): An action to be performed when an unknown fingerprint is scanned. See :ref:`fingerprint_grow-on_finger_scan_unmatched`. +- **on_enrollment_scan** (*Optional*, :ref:`Automation `): An action to be performed when a fingerprint is scanned during enrollment. See :ref:`fingerprint_grow-on_enrollment_scan`. +- **on_enrollment_done** (*Optional*, :ref:`Automation `): An action to be performed when a fingerprint is enrolled. See :ref:`fingerprint_grow-on_enrollment_done`. +- **on_enrollment_failed** (*Optional*, :ref:`Automation `): An action to be performed when a fingerprint enrollment failed. See :ref:`fingerprint_grow-on_enrollment_failed`. + +Optional Binary Sensor Configuration: + +- **name** (**Required**, string): The name for the enrolling binary sensor. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- All other options from :ref:`Binary Sensor `. + +Optional Sensor Configuration: + +Available sensors: + +- **fingerprint_count**: The number of enrolled fingerprints stored on the reader. + + - **name** (**Required**, string): The name for the sensor. + - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. + - All other options from :ref:`Sensor `. + +- **last_finger_id**: The last matched enrolled fingerprint as set by :ref:`fingerprint_grow-on_finger_scan_matched`. + + - **name** (**Required**, string): The name for the sensor. + - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. + - All other options from :ref:`Sensor `. + +- **last_confidence**: The last matched confidence as set by :ref:`fingerprint_grow-on_finger_scan_matched`. + + - **name** (**Required**, string): The name for the sensor. + - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. + - All other options from :ref:`Sensor `. + +- **status**: The integer representation of the internal status register of the reader. + + - **name** (**Required**, string): The name for the sensor. + - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. + - All other options from :ref:`Sensor `. + +- **capacity**: The fingerprint storage capacity of the reader. + + - **name** (**Required**, string): The name for the sensor. + - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. + - All other options from :ref:`Sensor `. + +- **security_level**: The integer representation of the currently configured security level of the reader. Higher security levels reduce the false acceptance rate (FAR) at the expense of increasing the false rejection rate (FRR). Range is 1 (lowest) to 5 (highest). + + - **name** (**Required**, string): The name for the sensor. + - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. + - All other options from :ref:`Sensor `. + + +.. _fingerprint_grow-set_new_password: + +Setting a New Password +---------------------- + +.. warning:: + + Forgetting the password will render your fingerprint reader unusable! + +You can set a new password for your fingerprint reader using the ``set_password:`` configuration option. The password is defined as a 32-bit unsigned integer. + +.. code-block:: yaml + + fingerprint_grow: + password: 0x275FE3D2 # Existing password, can be omitted if it's the default of 0x00 + set_password: 0x72AB96CD # New password + +The ``set_password:`` configuration option is meant to be compiled, flashed to the ESP device and run once, after which it's removed and the new password is defined in the ``password:`` configuration option to be compiled and flashed again. + +.. code-block:: yaml + + fingerprint_grow: + password: 0x72AB96CD # Update the existing password with the new one + + +.. _fingerprint_grow-on_finger_scan_matched: + +``on_finger_scan_matched`` Trigger +---------------------------------- + +With this configuration option you can write complex automations whenever a finger scan is matched to an enrolled fingerprint. +To use the variables, use a :ref:`lambda ` template, the matched slot number and the confidence are available inside that lambda under the variables named ``finger_id`` and ``confidence``. + +.. code-block:: yaml + + on_finger_scan_matched: + - text_sensor.template.publish: + id: fingerprint_state + state: !lambda 'return "Authorized finger " + to_string(finger_id) + ", confidence " + tostring(confidence);' + # Pushing a tag_scanned event based on finger_id only if confidence is greater than 50 + - if: + condition: + lambda: 'return confidence > 50;' + then: + - homeassistant.tag_scanned: !lambda |- + switch (finger_id) { + case 0: + return "person_a"; + case 1: + return "person_b"; + ... + default: + return "person_unknown"; + } + +.. _fingerprint_grow-on_finger_scan_unmatched: + +``on_finger_scan_unmatched`` Trigger +------------------------------------ + +With this configuration option you can write complex automations whenever an unknown fingerprint is scanned. + +.. code-block:: yaml + + on_finger_scan_unmatched: + - text_sensor.template.publish: + id: fingerprint_state + state: "Unauthorized finger" + +.. _fingerprint_grow-on_enrollment_scan: + +``on_enrollment_scan`` Trigger +------------------------------ + +With this configuration option you can write complex automations whenever a finger is scanned during enrollment. +To use the variables, use a :ref:`lambda ` template, the scan number and the slot number to be enrolled into are available inside that lambda under the variables named ``scan_num`` and ``finger_id``. + +.. code-block:: yaml + + on_enrollment_scan: + - text_sensor.template.publish: + id: fingerprint_state + state: !lambda 'return "Enrolling into slot " + to_string(finger_id) + ", scanned " + to_string(scan_num) + " time(s)";' + +.. _fingerprint_grow-on_enrollment_done: + +``on_enrollment_done`` Trigger +------------------------------ + +With this configuration option you can write complex automations whenever a finger is successfully enrolled. +To use the variables, use a :ref:`lambda ` template, the slot number enrolled into is available inside that lambda under the variable named ``finger_id``. + +.. code-block:: yaml + + on_enrollment_done: + - text_sensor.template.publish: + id: fingerprint_state + state: !lambda 'return "Enrolled into slot " + to_string(finger_id);' + +.. _fingerprint_grow-on_enrollment_failed: + +``on_enrollment_failed`` Trigger +-------------------------------- + +With this configuration option you can write complex automations whenever a finger failed to be enrolled. +To use the variables, use a :ref:`lambda ` template, the slot number that failed to be enrolled into is available inside that lambda under the variable named ``finger_id``. + +.. code-block:: yaml + + on_enrollment_failed: + - text_sensor.template.publish: + id: fingerprint_state + state: !lambda 'return "Failed to enroll into slot " + to_string(finger_id);' + # Retry enrollment into the same slot + - delay: 3s + - text_sensor.template.publish: + id: fingerprint_state + state: !lambda 'return "Retrying enrollment into slot " + to_string(finger_id) + " in 3 seconds...";' + - delay: 3s + - fingerprint_grow.enroll: !lambda 'return finger_id;' + + +``fingerprint_grow.enroll`` Action +---------------------------------- + +Starts the fingerprint enrollment process on the slot number defined. + +.. code-block:: yaml + + on_...: + then: + - fingerprint_grow.enroll: + finger_id: 0 + num_scans: 2 + # Shorthand + - fingerprint_grow.enroll: 0 + # Update the template text sensor for visual feedback + - text_sensor.template.publish: + id: fingerprint_state + state: "Place a finger on the reader" + +Configuration options: + +- **finger_id** (**Required**, int, :ref:`templatable `): The slot number to enroll the new fingerprint into. Limited to the fingerprint capacity available on the reader. +- **num_scans** (*Optional*, int, :ref:`templatable `): Number of times to scan the finger to be enrolled. Limited to the number of character buffers available on the reader. Defaults to 2. + +``fingerprint_grow.cancel_enroll`` Action +----------------------------------------- + +Cancels the current fingerprint enrollment process. Triggers the ``on_enrollment_failed`` trigger. + +.. code-block:: yaml + + on_...: + then: + - fingerprint_grow.cancel_enroll: + +``fingerprint_grow.delete`` Action +---------------------------------- + +Removes the enrolled fingerprint from the slot number defined. + +.. code-block:: yaml + + on_...: + then: + - fingerprint_grow.delete: + finger_id: 0 + # Shorthand + - fingerprint_grow.delete: 0 + +Configuration options: + +- **finger_id** (**Required**, int, :ref:`templatable `): The slot number of the enrolled fingerprint to delete. + +``fingerprint_grow.delete_all`` Action +-------------------------------------- + +Removes all enrolled fingerprints. + +.. code-block:: yaml + + on_...: + then: + - fingerprint_grow.delete_all: + +``fingerprint_grow.led_control`` Action +--------------------------------------- + +Turns on or off the LED on the reader. Only available on select models. If you have the R503 use :ref:`fingerprint_grow-aura_led_control` instead. + +.. code-block:: yaml + + on_...: + then: + - fingerprint_grow.led_control: + state: ON + # Shorthand + - fingerprint_grow.led_control: ON + +Configuration options: + +- **state** (**Required**, boolean, :ref:`templatable `): The state to set the LED. + +.. _fingerprint_grow-aura_led_control: + +``fingerprint_grow.aura_led_control`` Action +-------------------------------------------- + +Controls the Aura LED on the reader. Only available on select models. + +.. code-block:: yaml + + on_...: + then: + - fingerprint_grow.aura_led_control: + state: BREATHING + speed: 100 + color: BLUE + count: 2 + # Sample Aura LED config for all reader triggers + fingerprint_grow: + on_finger_scan_matched: + - fingerprint_grow.aura_led_control: + state: BREATHING + speed: 200 + color: BLUE + count: 1 + on_finger_scan_unmatched: + - fingerprint_grow.aura_led_control: + state: FLASHING + speed: 25 + color: RED + count: 2 + on_enrollment_scan: + - fingerprint_grow.aura_led_control: + state: FLASHING + speed: 25 + color: BLUE + count: 2 + - fingerprint_grow.aura_led_control: + state: ALWAYS_ON + speed: 0 + color: PURPLE + count: 0 + on_enrollment_done: + - fingerprint_grow.aura_led_control: + state: BREATHING + speed: 100 + color: BLUE + count: 2 + on_enrollment_failed: + - fingerprint_grow.aura_led_control: + state: FLASHING + speed: 25 + color: RED + count: 4 + on...: + then: + - fingerprint_grow.enroll: ... + - fingerprint_grow.aura_led_control: + state: ALWAYS_ON + speed: 0 + color: PURPLE + count: 0 + +Configuration options: + +- **state** (**Required**, string, :ref:`templatable `): The state to set the LED. One of ``BREATHING``, ``FLASHING``, ``ALWAYS_ON``, ``ALWAYS_OFF``, ``GRADUAL_ON`` and ``GRADUAL_OFF``. +- **speed** (**Required**, int, :ref:`templatable `): The duration each cycle lasts, a factor of 10ms. Only relevant for ``BREATHING``, ``FLASHING``, ``GRADUAL_ON`` and ``GRADUAL_OFF`` states. The total duration is defined by 10ms * speed * count. Range is 0 to 255. +- **color** (**Required**, string, :ref:`templatable `): The LED color to activate. One of ``RED``, ``BLUE`` and ``PURPLE``. +- **count** (**Required**, int, :ref:`templatable `): How many times to repeat the pattern. Only relevant for ``BREATHING`` and ``FLASHING`` states. 0 for infinite, or 1 to 255. + +All actions +----------- + +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID of the Grow fingerprint reader if you have multiple components. + + +Test setup +---------- + +With the following code you can quickly setup a node and use Home Assistant's service in the developer tools. +E.g. for calling ``fingerprint_grow.enroll`` select the service ``esphome.test_node_enroll`` and in service data enter + +.. code-block:: json + + { "finger_id": 0, "num_scans": 2 } + +Sample code +*********** + +.. code-block:: yaml + + esphome: + name: test_node + platform: ESP8266 + board: nodemcu + + wifi: + ssid: !secret wifi_ssid + password: !secret wifi_pass + + logger: + + uart: + rx_pin: GPIO13 + tx_pin: GPIO15 + baud_rate: 57600 + + fingerprint_grow: + sensing_pin: GPIO12 + on_finger_scan_matched: + - homeassistant.event: + event: esphome.test_node_finger_scan_matched + data: + finger_id: !lambda 'return finger_id;' + confidence: !lambda 'return confidence;' + on_finger_scan_unmatched: + - homeassistant.event: + event: esphome.test_node_finger_scan_unmatched + on_enrollment_scan: + - homeassistant.event: + event: esphome.test_node_enrollment_scan + data: + finger_id: !lambda 'return finger_id;' + scan_num: !lambda 'return scan_num;' + on_enrollment_done: + - homeassistant.event: + event: esphome.test_node_enrollment_done + data: + finger_id: !lambda 'return finger_id;' + on_enrollment_failed: + - homeassistant.event: + event: esphome.test_node_enrollment_failed + data: + finger_id: !lambda 'return finger_id;' + + api: + services: + - service: enroll + variables: + finger_id: int + num_scans: int + then: + - fingerprint_grow.enroll: + finger_id: !lambda 'return finger_id;' + num_scans: !lambda 'return num_scans;' + - service: cancel_enroll + then: + - fingerprint_grow.cancel_enroll: + - service: delete + variables: + finger_id: int + then: + - fingerprint_grow.delete: + finger_id: !lambda 'return finger_id;' + - service: delete_all + then: + - fingerprint_grow.delete_all: + +See Also +-------- + +- :apiref:`fingerprint_grow/fingerprint_grow.h` +- `Tutorial from Adafruit `__ +- `Adafruit Fingerprint Sensor Library `__ by `Adafruit `__ +- :ghedit:`Edit` diff --git a/components/gps.rst b/components/gps.rst index 6207e3ac5..648080349 100644 --- a/components/gps.rst +++ b/components/gps.rst @@ -23,26 +23,69 @@ in your configuration - only the RX pin should be necessary. # Example configuration entry uart: - rx_pin: D0 + rx_pin: D7 baud_rate: 9600 # Declare GPS module gps: + latitude: + name: "Latitude" + longitude: + name: "Longitude" + altitude: + name: "Altitude" # GPS as time source time: - platform: gps -The component is split up in platforms. No configuration variables. +The component is split up in platforms, by defining the GPS module +(as seen above). -First you need to define a global GPS module hub (as seen above). - -Currently, the only data that can be extracted from GPS is the current time. -GPS can be used as a time platform to get the current date and time via the -very accurate GPS clocks that are also independent of any network connection. +In addition to retrieving GPS position data, the module can also be used as a +time platform to get the current date and time via the very accurate GPS clocks +without a network connection. See :doc:`time` for config options for the GPS time source. +Configuration variables: +------------------------ +- **latitude** (*Optional*): Include the Latitude as a sensor + + - **name** (**Required**, string): The name to give the latitude sensor + - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. + - All other options from :ref:`Sensor `. + +- **longitude** (*Optional*): Include the Longitude as a sensor + + - **name** (**Required**, string): The name to give the latitude 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 + - **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 + - **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 + - **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 + - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. + - All other options from :ref:`Sensor `. + See Also -------- diff --git a/components/i2c.rst b/components/i2c.rst index 57043320f..5d426bad2 100644 --- a/components/i2c.rst +++ b/components/i2c.rst @@ -61,6 +61,13 @@ Configuration variables: address: 0x76 # ... + # If a I²C multiplexer is used all I²C devices can be additionally configured like: + - platform: bmp280 + multiplexer: + id: multiplex0 + channel: 0 + # ... + See Also -------- diff --git a/components/images/r307-full.jpg b/components/images/r307-full.jpg new file mode 100644 index 000000000..2f88e9b5b Binary files /dev/null and b/components/images/r307-full.jpg differ diff --git a/components/images/r503-full.jpg b/components/images/r503-full.jpg new file mode 100644 index 000000000..d7383e0ca Binary files /dev/null and b/components/images/r503-full.jpg differ diff --git a/components/images/tca9548a.jpg b/components/images/tca9548a.jpg new file mode 100644 index 000000000..b241b0ec0 Binary files /dev/null and b/components/images/tca9548a.jpg differ diff --git a/components/images/tof10120.jpg b/components/images/tof10120.jpg new file mode 100644 index 000000000..c638fbc75 Binary files /dev/null and b/components/images/tof10120.jpg differ diff --git a/components/light/index.rst b/components/light/index.rst index 5f0eadd68..fa3de18bd 100644 --- a/components/light/index.rst +++ b/components/light/index.rst @@ -370,6 +370,34 @@ entries with each having a unique name like so: transition_length: 4s update_interval: 5s +Pulse Effect +************ + +This effect makes a pulsating light. The period can be defined by ``update_interval``, the transition length with ``transition_length``. ``transition_length`` should be set to less than ``update_interval``, setting ``transition_length`` to ``1s`` and ``update_interval`` to ``2s`` will result in a transition from 0% to 100% lasting 1 second, 1 second full light, a transition from 100% to 0% for 1 second and off for 1 second. + +.. code-block:: yaml + + light: + - platform: ... + # ... + effects: + - pulse: + - pulse: + name: "Fast Puse" + transition_length: 0.5s + update_interval: 0.5s + - pulse: + name: "Slow Puse" + # transition_length: 1s # defaults to 1s + update_interval: 2s + +Configuration variables: + +- **name** (*Optional*, string): The name of the effect. Defaults to ``Pulse``. +- **transition_length** (*Optional*, :ref:`config-time`): The duration of each transition. Defaults to ``1s``. +- **update_interval** (*Optional*, :ref:`config-time`): The interval when the new transistion is started. Defaults to ``1s``. + + Random Effect ************* @@ -718,8 +746,8 @@ This effect allows you to access each LED individually in a custom light effect. Available variables in the lambda: - **it** - :apiclass:`AddressableLight ` instance (see API reference for more info). -- **current_color** - :apistruct:`Color ` instance (see API reference for more info). -- **initial_run** - A bool which is true on the first execution of the lambda. Useful to reset static variables when restarting a effect. +- **current_color** - :apistruct:`ESPColor ` instance (see API reference for more info). +- **initial_run** - A bool which is true on the first execution of the lambda. Useful to reset static variables when restarting an effect. .. note:: @@ -872,6 +900,10 @@ Configuration variables: - **method** (*Optional*): Listening method, one of ``multicast`` or ``unicast``. Defaults to ``multicast``. +<<<<<<< HEAD +The udp port esphome is listening on is 5568. +======= +>>>>>>> current .. _E1.31: https://www.doityourselfchristmas.com/wiki/index.php?title=E1.31_(Streaming-ACN)_Protocol .. _JINX: http://www.live-leds.de/jinx-v1-3-with-resizable-mainwindow-real-dmx-and-sacne1-31/ @@ -939,6 +971,11 @@ Configuration variables: - **port** (*Optional*, integer): The port to run the UDP server on. Defaults to ``21324``. +.. note:: + + You can also set the ``port`` to ``19446`` for compatability with Hyperion Classic using a + UDP device with protocol 0. + Currently the following realtime protocols are supported: WARLS, DRGB, DRGBW, DNRGB and WLED Notifier. diff --git a/components/sensor/atm90e32.rst b/components/sensor/atm90e32.rst index 09bd3002e..2d9d4c27e 100644 --- a/components/sensor/atm90e32.rst +++ b/components/sensor/atm90e32.rst @@ -7,7 +7,7 @@ ATM90E32 Power Sensor :keywords: ATM90E32, CircuitSetup, Split Single Phase Real Time Whole House Energy Meter, Expandable 6 Channel ESP32 Energy Meter Main Board The ``atm90e32`` sensor platform allows you to use your ATM90E32 voltage/current and power sensors -(`datasheet `__) sensors with +(`datasheet `__) with ESPHome. This sensor is commonly found in CircuitSetup 2 and 6 channel energy meters. Communication with the device is done via an :ref:`SPI bus `, so you need to have an ``spi:`` entry in your configuration @@ -46,20 +46,24 @@ Configuration variables: :ref:`Sensor `. - **power** (*Optional*): Use the power value on this phase in watts. All options from :ref:`Sensor `. - - **reactive_power** (*Optional*): Use the reactive power value on this phase. All options from + - **reactive_power** (*Optional*): Use the reactive power value on this phase. All options from :ref:`Sensor `. - - **power_factor** (*Optional*): Use the power factor value on this phase. All options from + - **power_factor** (*Optional*): Use the power factor value on this phase. All options from :ref:`Sensor `. - **gain_voltage** (*Optional*, int): Voltage gain to scale the low voltage AC power pack to household mains feed. Defaults to ``7305``. - **gain_ct** (*Optional*, int): CT clamp calibration for this phase. Defaults to ``27961``. + - **forward_active_energy** (*Optional*): Use the forward active energy value on this phase in watt-hours. + All options from :ref:`Sensor `. + - **reverse_active_energy** (*Optional*): Use the reverse active energy value on this phase in watt-hours. + All options from :ref:`Sensor `. - **phase_b** (*Optional*): The configuration options for the 2nd phase. Same options as 1st phase. - **phase_c** (*Optional*): The configuration options for the 3rd phase. Same options as 1st phase. -- **frequency** (*Optional*): Use the frequenycy value calculated by the meter. All options from +- **frequency** (*Optional*): Use the frequenycy value calculated by the meter. All options from :ref:`Sensor `. -- **chip_temperature** (*Optional*): Use the chip temperature value. All options from +- **chip_temperature** (*Optional*): Use the chip temperature value. All options from :ref:`Sensor `. - **gain_pga** (*Optional*, string): The gain for the CT clamp, ``2X`` for 100A, ``4X`` for 100A - 200A. One of ``1X``, ``2X``, ``4X``. Defaults to ``2X`` which is suitable for the popular SCT-013-000 clamp. @@ -80,7 +84,7 @@ A load which uses a known amount of current can be used to calibrate. For for a Voltage ^^^^^^^ -Use the expected mains voltage for your region 110V/230V or plug in the Kill-A-Watt and select voltage. See what +Use the expected mains voltage for your region 110V/230V or plug in the Kill-A-Watt and select voltage. See what value the ATM90E32 sensor reports for voltage. To adjust the sensor use the calculation: ``New gain_voltage = (your voltage reading / ESPHome voltage reading) * existing gain_voltage value`` @@ -135,6 +139,37 @@ Here are common current calibrations for the **Expandable 6 Channel Energy Meter - 100A/50ma SCT-013-000: 27961 - 120A/40mA: SCT-016: 41880 +Active Energy +^^^^^^^^^^^^^ + +The ATM90E32 chip has a high-precision built-in ability to count the amount of consumed energy on a per-phase basis. +For each phase both the Forward and Reverse active energy is counted in watt-hours. +Forward Active Energy is used to count consumed energy, whereas Reverse Active Energy is used to count exported energy +(e.g. with solar pv installations). +The counters are reset every time a given active energy value is read from the ATM90E32 chip. + +Current implementation targets users who retrieve the energy values with a regular interval and store them in +a time-series-database, e.g. InfluxDB. + +**Example:** + +.. code-block:: yaml + + sensor: + #IC1 Main + - platform: atm90e32 + cs_pin: 5 + phase_a: + forward_active_energy: + name: ${disp_name} ct1 FAWattHours + id: ct1FAWattHours + state_topic: ${disp_name}/ct1/forward_active_energy + reverse_active_energy: + name: ${disp_name} ct1 RAWattHours + id: ct1RAWattHours + state_topic: ${disp_name}/ct1/reverse_active_energy + + Additional Examples ------------------- @@ -156,7 +191,7 @@ Additional Examples name: "EMON CT1 Current" power: name: "EMON Active Power CT1" - reactive_power: + reactive_power: name: "EMON Reactive Power CT1" power_factor: name: "EMON Power Factor CT1" @@ -167,7 +202,7 @@ Additional Examples name: "EMON CT2 Current" power: name: "EMON Active Power CT2" - reactive_power: + reactive_power: name: "EMON Reactive Power CT2" power_factor: name: "EMON Power Factor CT2" @@ -248,18 +283,18 @@ Additional Examples current_phases: 3 gain_pga: 1X update_interval: 60s - + .. code-block:: yaml # Example CircuitSetup 6-channel without jumpers jp9-jp11 joined or < meter v1.4 # power is calculated in a template - + substitutions: disp_name: 6C update_time: 10s current_cal: '27961' - + spi: clk_pin: 18 miso_pin: 19 @@ -321,7 +356,7 @@ Additional Examples current_phases: 3 gain_pga: 1X update_interval: ${update_time} - + #Watts per channel - platform: template name: ${disp_name} CT1 Watts @@ -330,7 +365,7 @@ Additional Examples accuracy_decimals: 0 unit_of_measurement: W icon: "mdi:flash-circle" - update_interval: ${update_time} + update_interval: ${update_time} - platform: template name: ${disp_name} CT2 Watts id: ct2Watts @@ -338,7 +373,7 @@ Additional Examples accuracy_decimals: 0 unit_of_measurement: W icon: "mdi:flash-circle" - update_interval: ${update_time} + update_interval: ${update_time} - platform: template name: ${disp_name} CT3 Watts id: ct3Watts @@ -346,7 +381,7 @@ Additional Examples accuracy_decimals: 0 unit_of_measurement: W icon: "mdi:flash-circle" - update_interval: ${update_time} + update_interval: ${update_time} - platform: template name: ${disp_name} CT4 Watts id: ct4Watts @@ -354,7 +389,7 @@ Additional Examples accuracy_decimals: 0 unit_of_measurement: W icon: "mdi:flash-circle" - update_interval: ${update_time} + update_interval: ${update_time} - platform: template name: ${disp_name} CT5 Watts id: ct5Watts @@ -362,7 +397,7 @@ Additional Examples accuracy_decimals: 0 unit_of_measurement: W icon: "mdi:flash-circle" - update_interval: ${update_time} + update_interval: ${update_time} - platform: template name: ${disp_name} CT6 Watts id: ct6Watts @@ -370,8 +405,8 @@ Additional Examples accuracy_decimals: 0 unit_of_measurement: W icon: "mdi:flash-circle" - update_interval: ${update_time} - #Total Amps + update_interval: ${update_time} + #Total Amps - platform: template name: ${disp_name} Total Amps id: totalAmps @@ -379,7 +414,7 @@ Additional Examples accuracy_decimals: 2 unit_of_measurement: A icon: "mdi:flash" - update_interval: ${update_time} + update_interval: ${update_time} #Total Watts - platform: template name: ${disp_name} Total Watts diff --git a/components/sensor/b_parasite.rst b/components/sensor/b_parasite.rst new file mode 100644 index 000000000..3faff4609 --- /dev/null +++ b/components/sensor/b_parasite.rst @@ -0,0 +1,63 @@ +b-parasite +========== + +.. seo:: + :description: Instructions for setting up the b-parasite soil moisture sensor in ESPHome. + :image: b_parasite.jpg + :keywords: b-parasite, parasite, BLE, Bluetooth, soil moisture + + +`b-parasite `__ is an open source soil moisture and ambient temperature/humidity sensor. + +The ``b_parasite`` sensor platform tracks b-parasite's Bluetooth Low Energy (BLE) advertisement packets. These packets contains soil moisture, air temperature/humidity and baterry voltage data. + +.. figure:: images/b_parasite.jpg + :align: center + :width: 80.0% + +.. code-block:: yaml + + # Example configuration. + + # Required. + esp32_ble_tracker: + + sensor: + - platform: b_parasite + mac_address: F0:CA:F0:CA:01:01 + humidity: + name: 'b-parasite Air Humidity' + temperature: + name: 'b-parasite Air Temperature' + moisture: + name: 'b-parasite Soil Moisture' + battery_voltage: + name: 'b-parasite Battery Voltage' + +Configuration variables +----------------------- + +- **mac_address** (**Required**): The MAC address of the device. +- **temperature** (*Optional*): Air temperature in Celcius. + + - **name** (**Required**): Sensor name. + - All other options from :ref:`Sensor `. +- **humidity** (*Optional*): Relative air humidity in %. + + - **name** (**Required**): Sensor name. + - All other options from :ref:`Sensor `. +- **moisture** (*Optional*): Soil moisture in %. + + - **name** (**Required**): Sensor name. + - All other options from :ref:`Sensor `. +- **battery_voltage** (*Optional*): Battery voltage in volts. + + - **name** (**Required**): Sensor name. + - All other options from :ref:`Sensor `. + +See Also +-------- + +- `b-parasite on GitHub `__ +- :doc:`/components/esp32_ble_tracker` +- :ghedit:`Edit` diff --git a/components/sensor/ble_sensor.rst b/components/sensor/ble_sensor.rst new file mode 100644 index 000000000..bc57cbb92 --- /dev/null +++ b/components/sensor/ble_sensor.rst @@ -0,0 +1,85 @@ +BLE Sensor +========== + +.. seo:: + :description: Fetch numeric values from BLE devices. + :image: bluetooth.svg + +The ``ble_sensor`` component is a sensor platform that can +query BLE devices for specific values of service characteristics. + +For more information on BLE services and characteristics, see +:doc:`/components/ble_client`. + +.. code-block:: yaml + + esp32_ble_tracker: + + ble_client: + - mac_address: FF:FF:20:00:0F:15 + id: itag_black + + sensor: + - platform: ble_client + ble_client_id: itag_black + name: "iTag battery level" + service_uuid: '180f' + characteristic_uuid: '2a19' + icon: 'mdi:battery' + unit_of_measurement: '%' + +Configuration variables: +------------------------ + +- **ble_client_id** (**Required**, :ref:`config-id`): ID of the associated BLE client. +- **service_uuid** (**Required**, UUID): UUID of the service on the device. +- **characteristic_uuid** (**Required**, UUID): UUID of the service's characteristic to query. +- **descriptor_uuid** (*Optional*, UUID): UUID of the characteristic's descriptor to query. +- **id** (*Optional*, :ref:`config-id`): The ID to use for code generation, and for reference by dependent components. +- **notify** (*Optional*, boolean): Instruct the server to send notifications for this + characteristic. +- **update_interval** (*Optional*, :ref:`config-time`): The interval to poll the device. +- All other options from :ref:`Sensor `. + +Automations: + +- **on_notify** (*Optional*, :ref:`Automation `): An automation to + perform when a notify message is received from the device. See :ref:`ble_sensor-on_notify`. + +BLE Sensor Automation +--------------------- + +.. _ble_sensor-on_notify: + +``on_notify`` +************* + +This automation is triggered when the device/server sends a notify message for +a characteristic. The config variable *notify* must be true or this will have +no effect. +A variable ``x`` of type ``float`` is passed to the automation for use in lambdas. + +Example UUIDs +------------- +The UUIDs available on a device are dependent on the type of +device and the functionality made available. Check the ESPHome +device logs for those that are found on the device. + +Some common ones: + ++----------+------------------+-----------------------+ +| Service | Characteristic | Description | ++==========+==================+=======================+ +| 180F | 2A19 | Battery level | ++----------+------------------+-----------------------+ +| 181A | 2A6F | Humidity | ++----------+------------------+-----------------------+ + + +See Also +-------- + +- :doc:`/components/ble_client` +- :ref:`sensor-filters` +- :apiref:`ble_sensor/ble_sensor.h` +- :ghedit:`Edit` diff --git a/components/sensor/bme680_bsec.rst b/components/sensor/bme680_bsec.rst new file mode 100644 index 000000000..511020632 --- /dev/null +++ b/components/sensor/bme680_bsec.rst @@ -0,0 +1,269 @@ +BME680 Temperature+Pressure+Humidity+Gas Sensor via BSEC +======================================================== + +.. seo:: + :description: Instructions for setting up BME680 temperature, humidity, pressure and gas sensors via BSEC. + :image: bme680.jpg + :keywords: BME680 + +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. + +.. note:: + + The Bosch 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. + +The :ref:`I²C ` is required to be set up in your configuration for this sensor to work. + +.. figure:: images/bme680-full.jpg + :align: center + :width: 50.0% + + BME680 Temperature, Pressure, Humidity & Gas Sensor. + +.. _BSEC license agreement: https://www.bosch-sensortec.com/media/boschsensortec/downloads/bsec/2017-07-17_clickthrough_license_terms_environmentalib_sw_clean.pdf + +.. _Adafruit: https://www.adafruit.com/product/3660 + +.. code-block:: yaml + + # Minimal example configuration with common sensors + i2c: + + bme680_bsec: + + sensor: + - platform: bme680_bsec + temperature: + name: "BME680 Temperature" + pressure: + name: "BME680 Pressure" + humidity: + name: "BME680 Humidity" + iaq: + name: "BME680 IAQ" + co2_equivalent: + name: "BME680 CO2 Equivalent" + breath_voc_equivalent: + name: "BME680 Breath VOC Equivalent" + + text_sensor: + - platform: bme680_bsec + iaq_accuracy: + name: "BME680 IAQ Accuracy" + +Configuration variables: +------------------------ + +The configuration is made up of three parts: The central hub, individual sensors, and accuracy text sensor. + +Hub Configuration: + +- **address** (*Optional*, int): Manually specify the I^2C 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. + Defaults to ``0``. + +- **iaq_mode** (*Optional*, string): IAQ calculation mode. Default is ``static`` for static applications (e.g. fixed indoor devices). + 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. + +- **state_save_interval** (*Optional*, :ref:`config-time`): The minimum interval at which to save calibrated BSEC algorithm state to + flash so that calibration does have to start from zero on device restart. Defaults to ``6h``. + +Sensor Configuration: + +- **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. + - 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. + - 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. + - All other options from :ref:`Sensor `. + +- **gas_resistance** (*Optional*): The information for the gas sensor. + + - **name** (**Required**, string): The name for the gas resistance sensor. + - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. + - All other options from :ref:`Sensor `. + +- **iaq** (*Optional*): The information for the IAQ sensor. + + - **name** (**Required**, string): The name for the IAQ sensor. + - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. + - All other options from :ref:`Sensor `. + +- **iaq_accuracy** (*Optional*): The information for the numeric IAQ accuracy sensor. + + - **name** (**Required**, string): The name for the IAQ accuracy sensor. + - **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. + + - **name** (**Required**, string): The name for the CO2 equivalent sensor. + - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. + - All other options from :ref:`Sensor `. + +- **breath_voc_equivalent** (*Optional*): The information for the Breath VOC equivalent humidity sensor. + + - **name** (**Required**, string): The name for the Breath VOC equivalent sensor. + - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. + - All other options from :ref:`Sensor `. + +Text Sensor Configuration: + +- **iaq_accuracy** (*Optional*): The information for the IAQ accuracy sensor. + + - **name** (**Required**, string): The name for the IAQ accuracy sensor. + - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. + - All other options from :ref:`TextSensor `. + +.. figure:: images/bme680-bsec-ui.png + :align: center + :width: 80.0% + +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. + +.. code-block:: yaml + + bme680_bsec: + # i2c address + # ----------- + # Common values are: + # - 0x76 + # - 0x77 + # Default: 0x76 + address: 0x76 + + # Temperature offset + # ------------------ + # Useful if device is in enclosure and reads too high + # Default: 0 + temperature_offset: 0 + + # IAQ calculation mode + # -------------------- + # Available options: + # - static (for fixed position devices) + # - mobile (for on person or other moveable devices) + # Default: static + iaq_mode: static + + # Sample rate + # ----------- + # Available options: + # - lp (low power - samples every 3 seconds) + # - ulp (ultra low power - samples every 5 minutes) + # Default: lp + sample_rate: lp + + # Interval at which to save BSEC state + # ------------------------------------ + # Default: 6h + state_save_interval: 6h + + sensor: + - platform: bme680_bsec + temperature: + # Temperature in °C + name: "BME680 Temperature" + filters: + - median + pressure: + # Pressure in hPa + name: "BME680 Pressure" + filters: + - median + humidity: + # Relative humidity % + name: "BME680 Humidity" + filters: + - median + gas_resistance: + # Gas resistance in Ω + name: "BME680 Gas Resistance" + filters: + - median + iaq: + # Indoor air quality value + name: "BME680 IAQ" + filters: + - median + iaq_accuracy: + # IAQ accuracy as a numeric value of 0, 1, 2, 3 + name: "BME680 Numeric IAQ Accuracy" + co2_equivalent: + # CO2 equivalent estimate in ppm + name: "BME680 CO2 Equivalent" + filters: + - median + breath_voc_equivalent: + # Volatile organic compounds equivalent estimate in ppm + name: "BME680 Breath VOC Equivalent" + filters: + - median + + text_sensor: + - platform: bme680_bsec + iaq_accuracy: + # IAQ accuracy as a text value of Stabilizing, Uncertain, Calibrating, Calibrated + name: "BME680 IAQ Accuracy" + + +Indoor Air Quality (IAQ) Measurement +------------------------------------ + +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: + +- ``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 + stable for BSEC to clearly define its reference. +- ``Calibrating``: BSEC found new calibration data and is currently calibrating. +- ``Calibrated``: BSEC calibrated successfully. + +Every ``state_save_interval``, or as soon thereafter as full calibration is reached, the current algorithm state is saved to flash +so that the process does not have to start from zero on device restart. + +See Also +-------- + +- :ref:`sensor-filters` +- :doc:`bme680` +- :apiref:`bme680_bsec/bme680_bsec.h` +- `BSEC Arduino Library `__ by `Bosch Sensortec `__ +- `Bosch Sensortec Community `__ +- :ghedit:`Edit` diff --git a/components/sensor/images/b_parasite.jpg b/components/sensor/images/b_parasite.jpg new file mode 100644 index 000000000..22ff8e097 Binary files /dev/null and b/components/sensor/images/b_parasite.jpg differ diff --git a/components/sensor/images/bme680-bsec-ui.png b/components/sensor/images/bme680-bsec-ui.png new file mode 100644 index 000000000..f85dea8fd Binary files /dev/null and b/components/sensor/images/bme680-bsec-ui.png differ diff --git a/components/sensor/images/sgp40.jpg b/components/sensor/images/sgp40.jpg new file mode 100644 index 000000000..947b7d251 Binary files /dev/null and b/components/sensor/images/sgp40.jpg differ diff --git a/components/sensor/images/sht4x-full.jpg b/components/sensor/images/sht4x-full.jpg new file mode 100644 index 000000000..50a3834a6 Binary files /dev/null and b/components/sensor/images/sht4x-full.jpg differ diff --git a/components/sensor/images/tof10120-full.jpg b/components/sensor/images/tof10120-full.jpg new file mode 100644 index 000000000..66329b8c4 Binary files /dev/null and b/components/sensor/images/tof10120-full.jpg differ diff --git a/components/sensor/images/tof10120-ui.png b/components/sensor/images/tof10120-ui.png new file mode 100644 index 000000000..caf511d95 Binary files /dev/null and b/components/sensor/images/tof10120-ui.png differ diff --git a/components/sensor/images/wifi_signal-ui.png b/components/sensor/images/wifi_signal-ui.png index 2a351fb7a..9a016fafd 100644 Binary files a/components/sensor/images/wifi_signal-ui.png and b/components/sensor/images/wifi_signal-ui.png differ diff --git a/components/sensor/mcp3008.rst b/components/sensor/mcp3008.rst index fe14d9bcf..871944550 100644 --- a/components/sensor/mcp3008.rst +++ b/components/sensor/mcp3008.rst @@ -7,14 +7,13 @@ MCP3008 I/O Expander :image: images/mcp3008.jpg The Microchip Technology Inc. MCP3008 -devices are successive approximation 10-bit Analogto-Digital (A/D) converters with on-board sample and +devices are successive approximation 10-bit Analog-to-Digital (A/D) converters with on-board sample and hold circuitry. .. figure:: images/mcp3008.jpg :align: center :width: 50.0% - .. _mcp3008-component: Component/Hub diff --git a/components/sensor/sgp40.rst b/components/sensor/sgp40.rst new file mode 100644 index 000000000..3551cc87d --- /dev/null +++ b/components/sensor/sgp40.rst @@ -0,0 +1,65 @@ +SGP40 Volatile Organic Compound Sensor +====================================== + +.. seo:: + :description: Instructions for setting up SGP40 Volatile Organic Compound sensor + :image: sgp40.jpg + +The ``sgp40`` sensor platform allows you to use your Sensiron SGP40 VOC sensor +(`datasheet `__) with ESPHome. +The :ref:`I²C Bus ` is required to be set up in your configuration for this sensor to work. + +.. figure:: images/sgp40.jpg + :align: center + :width: 80.0% + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: sgp40 + name: "Workshop VOC" + + +Configuration variables: +------------------------ + +- **name** (**Required**, string): The name for the CO₂eq sensor. +- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. +- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s`` +- **store_baseline** (*Optional*, boolean ): Stores and retrieves the baseline infortmation for quicker startups. Defaults to ``True`` + +- **compensation** (*Optional*): The block containing sensors used for compensation. If not set defaults will be used. + + - **temperature_source** (*Optional*, :ref:`config-id`): Give an external temperature sensor ID + here. This can improve the sensor's internal calculations. Defaults to ``25`` + + - **humidity_source** (*Optional*, :ref:`config-id`): Give an external humidity sensor ID + here. This can improve the sensor's internal calculations. Defaults to ``50`` + +- All other options from :ref:`Sensor `. + +Example With Compensation +------------------------- +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: sgp40 + name: "Workshop VOC" + update_interval: 5s + compensation: + humidity_source: dht1_temp + temperature_source: dht1_hum + +See Also +-------- + +- :ref:`sensor-filters` +- :doc:`dht` +- :doc:`dht12` +- :doc:`hdc1080` +- :doc:`htu21d` +- :doc:`sht3xd` +- :apiref:`sgp40/sgp40.h` +- :ghedit:`Edit` diff --git a/components/sensor/sht4x.rst b/components/sensor/sht4x.rst new file mode 100644 index 000000000..048d026e0 --- /dev/null +++ b/components/sensor/sht4x.rst @@ -0,0 +1,62 @@ +SHT4X Temperature and Humidity Sensor +================================================== + +.. seo:: + :description: Instructions for setting up SHT4X temperature and humidity sensor + :image: images/sht4x-full.jpg + +The ``sht4x`` sensor platform allows you to use your SHT4X temperature and humidity 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/sht4x-full.jpg + :align: center + :width: 80.0% + +.. _Adafruit: https://www.adafruit.com/product/4885 + +.. code-block:: yaml + + sensor: + - platform: sht4x + temperature: + name: "Temperature" + humidity: + name: "Relative Humidity" + +Configuration variables: +------------------------ + +- **temperature** (**Optional**): Temperature. All other options from :ref:`Sensor `. +- **humidity** (**Optional**): Relative Humidity. All other options from :ref:`Sensor `. + +- **precision** (**Optional**, string): The measurement precision, either ``"High"``, ``"Med"`` or ``"Low"``. Default is ``"High"``. +- **heater_max_duty** (**Optional**, float): The maximum duty cycle of the heater (limited to ``0.05``). Default is ``0.0`` i.e. heater off. +- **heater_power** (**Optional**, string): The heater power, either ``"High"``, ``"Med"`` or ``"Low"``. Default is ``"High"``. +- **heater_time** (**Optional**, string): The length of time to run the heater, either ``"Long"`` (``1000ms``) or ``"Short"`` (``100ms``). Default is ``"Long"``. +- **address** (**Optional**, int): Manually specify the I²C address of the sensor. Default is ``0x44``. +- **update_interval** (**Optional**, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. + +Heater Configuration: +--------------------- + +The SHT4X includes an on-chip heater which is intended to remove condensation from the sensor that +has been sprayed onto the sensor or in high humidity environments. This can help +maintain accurate humidity measurements. + +The heater can be enabled by setting ``heater_max_duty`` up to a maximum duty cycle +of ``5%`` (``0.05``). This runs the heater on a regular interval. While the heater +is in operation the sensor disables measurements so no updates will be published. + +See the (`datasheet `__) +for more information about heater operation. + +See Also +-------- + +- :doc:`/components/sensor/sht3xd` +- :doc:`/components/sensor/shtcx` +- :ref:`sensor-filters` +- :apiref:`sht4x/sht4x.h` +- :ghedit:`Edit` diff --git a/components/sensor/tof10120.rst b/components/sensor/tof10120.rst new file mode 100644 index 000000000..8badc342b --- /dev/null +++ b/components/sensor/tof10120.rst @@ -0,0 +1,52 @@ +TOF10120 Time Of Flight Distance Sensor +======================================= + +.. seo:: + :description: Instructions for setting up TOF10120 distance sensors in ESPHome. + :image: tof10120.jpg + :keywords: TOF10120 + +The ``tof10120`` sensor platform allows you to use TOF10120 optical time of flight sensor (`datasheet `__) +with ESPHome to measure distances. The sensor works optically by emitting short infrared pulses +and measuring the time it takes the light to be reflected back. + +The sensor can measure distances in range 10-180 centimeters, though that figure depends significantly +on several conditions like surface reflectance, field of view, temperature etc. . + +The :ref:`I²C Bus ` is +required to be set up in your configuration for this sensor to work. + +.. figure:: images/tof10120-full.jpg + :align: center + :width: 50.0% + + TOF10120 Time Of Flight Distance Sensor. + +.. figure:: images/tof10120-ui.png + :align: center + :width: 80.0% + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: tof10120 + name: "TOF10120 Distance" + update_interval: 5s + +Configuration variables: +------------------------ + +- **name** (**Required**, string): The name of the sensor. +- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the + sensor. Defaults to ``60s``. +- **address** (*Optional*, int): Manually specify the I^2C address of the sensor. Defaults to ``0x52``. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- All other options from :ref:`Sensor `. + +See Also +-------- + +- :ref:`sensor-filters` +- :apiref:`tof10120/tof10120_sensor.h` +- :ghedit:`Edit` diff --git a/components/sensor/wifi_signal.rst b/components/sensor/wifi_signal.rst index 966877dd7..f2a5b57f5 100644 --- a/components/sensor/wifi_signal.rst +++ b/components/sensor/wifi_signal.rst @@ -9,7 +9,7 @@ The ``wifi_signal`` sensor platform allows you to read the signal strength of the currently connected :doc:`WiFi Access Point `. The sensor value is the `"Received signal strength indication" `__ -measured in decibels. These values are always negative and the closer they are to zero, the better the signal is. +measured in decibel-milliwatts (dBm). These values are always negative and the closer they are to zero, the better the signal is. .. figure:: images/wifi_signal-ui.png :align: center diff --git a/components/switch/ble.rst b/components/switch/ble.rst new file mode 100644 index 000000000..eaf225736 --- /dev/null +++ b/components/switch/ble.rst @@ -0,0 +1,41 @@ +BLE Switch +========== + +.. seo:: + :description: Control the state of BLE clients. + :image: bluetooth.svg + +The ``ble_switch`` component is a switch platform that is used to enable +and disable a ``ble_client``. This has several uses, such as minimising +battery usage or for allowing other clients (Eg phone apps) to connect to +the device. + +For more information on BLE services and characteristics, see +:doc:`/components/ble_client`. + +.. code-block:: yaml + + esp32_ble_tracker: + + ble_client: + - mac_address: FF:FF:20:00:0F:15 + id: itag_black + + switch: + - platform: ble_client + ble_client_id: itag_black + name: "Enable iTag" + +Configuration variables: +------------------------ + +- **ble_client_id** (**Required**, :ref:`config-id`): ID of the associated BLE client. +- **id** (**Optional**, :ref:`config-id`): The ID to use for code generation, and for reference by dependent components. +- All other options from :ref:`Switch `. + +See Also +-------- + +- :doc:`/components/ble_client` +- :apiref:`ble_client/switch/ble_switch.h` +- :ghedit:`Edit` diff --git a/components/tca9548a.rst b/components/tca9548a.rst new file mode 100644 index 000000000..502c08d54 --- /dev/null +++ b/components/tca9548a.rst @@ -0,0 +1,54 @@ +TCA9548A I²C Multiplexer +======================== + +.. seo:: + :description: Instructions for setting up TCA9548A I²C multiplexer in ESPHome. + :image: tca9548a.jpg + +The TCA9548A component allows you to use TCA9548A as a I²C multiplexer +(`datasheet `__, +`AdaFruit`_) in ESPHome. It uses :ref:`I²C Bus ` for communication. + +Once configured, you can use any of the 8 channels (TCA9548A) as seperated channels for your projects. + + +.. figure:: images/tca9548a.jpg + :align: center + :width: 80.0% + + tca9548a I2C Multiplexer. + +.. _AdaFruit: https://learn.adafruit.com/adafruit-tca9548a-1-to-8-i2c-multiplexer-breakout + +.. code-block:: yaml + + # Example configuration entry + tca9548a: + - address: 0x70 + id: multiplex0 + i2c_id: i2c0 + scan: True + + # Individual I2C Devices + sensor: + - platform: bmp280 + multiplexer: + id: multiplex0 + channel: 0 + ... + +Configuration variables: +~~~~~~~~~~~~~~~~~~~~~~~~ + +- **id** (**Required**, :ref:`config-id`): The id to use for this TCA9548A component. +- **address** (*Optional*, int): The I²C address of the Multiplexer. + Defaults to ``0x70``. +- **i2c_id** (*Optional*): The I²C Bus ID +- **scan** (*Optional*, bool): if the channel should be scanned + Defaults to ``false`` + +See Also +-------- + +- :ref:`i2c` +- :ghedit:`Edit` diff --git a/components/wifi.rst b/components/wifi.rst index 4a3a9b083..32181a1c2 100644 --- a/components/wifi.rst +++ b/components/wifi.rst @@ -26,6 +26,8 @@ dramatically improve connection times. gateway: 10.0.0.1 subnet: 255.255.255.0 +.. _wifi-configuration_variables: + Configuration variables: ------------------------ @@ -59,6 +61,7 @@ Configuration variables: - **ap_timeout** (*Optional*, :ref:`time `): The time after which to enable the configured fallback hotspot. Defaults to ``1min``. +- **enable_mdns** (*Optional*, boolean): Controls if your node should advertise its presense and services using mDNS. When set to ``false`` you won't be able to access your node using its hostname which can break certain functionalities. Please see :ref:`notes on disabling mDNS `. Defaults to ``true``. - **domain** (*Optional*, string): Set the domain of the node hostname used for uploading. For example, if it's set to ``.local``, all uploads will be sent to ``.local``. Defaults to ``.local``. diff --git a/conf.py b/conf.py index f08845187..880d76804 100644 --- a/conf.py +++ b/conf.py @@ -67,9 +67,9 @@ author = "Otto Winter" # built documents. # # The short X.Y version. -version = "1.17" +version = "1.18" # The full version, including alpha/beta/rc tags. -release = "1.17.2" +release = "1.18.0b1" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/cookbook/ble_itag.rst b/cookbook/ble_itag.rst new file mode 100644 index 000000000..463dc0483 --- /dev/null +++ b/cookbook/ble_itag.rst @@ -0,0 +1,114 @@ +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 + ble_client_id: itag_black + name: "Black iTag btn" + service_uuid: 'ffe0' + char_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 frontent. + - platform: ble_client + ble_client_id: itag_black + name: "Black iTag Battery" + service_uuid: '180f' + char_uuid: '2a19' + icon: 'mdi:battery' + unit_of_measurement: '%' + +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_sensor` +- :ghedit:`Edit` diff --git a/cookbook/iaq_board.rst b/cookbook/iaq_board.rst index 84f849134..cedaa11d1 100644 --- a/cookbook/iaq_board.rst +++ b/cookbook/iaq_board.rst @@ -53,6 +53,7 @@ See Also - :doc:`/components/sensor/pmsx003` - :doc:`/components/sensor/mhz19` - :doc:`/components/sensor/sgp30` +- :doc:`/components/sensor/sgp40` - :doc:`/components/sensor/tsl2561` - :doc:`/components/binary_sensor/gpio` - :doc:`/components/sensor/template` diff --git a/cookbook/images/esp32_ble_itag.png b/cookbook/images/esp32_ble_itag.png new file mode 100644 index 000000000..cb3051f0e Binary files /dev/null and b/cookbook/images/esp32_ble_itag.png differ diff --git a/guides/automations.rst b/guides/automations.rst index 1418b1608..af7ea872b 100644 --- a/guides/automations.rst +++ b/guides/automations.rst @@ -394,6 +394,7 @@ All Conditions - :ref:`sun.is_above_horizon / sun.is_below_horizon ` - :ref:`text_sensor.state ` - :ref:`light.is_on ` / :ref:`light.is_off ` +- :ref:`display.is_displaying_page ` All Lambda Calls ---------------- diff --git a/guides/contributing.rst b/guides/contributing.rst index 8cf95b127..c1db3d796 100644 --- a/guides/contributing.rst +++ b/guides/contributing.rst @@ -414,10 +414,11 @@ by the integration developer. .. note:: - Additionally, ESPHome has a ``custom_components`` mechanism like - `Home Assistant does `__. - So for testing you can also create a new ``custom_components`` folder inside of your ESPHome - config folder and create new integrations in there. + For testing you can use :doc:`/components/external_components`. + + ESPHome also has a ``custom_components`` mechanism like `Home Assistant does + `__. However this is + discouraged in favor of :doc:`/components/external_components`. 2. Config Validation ******************** @@ -543,7 +544,8 @@ loader. These are: - ``DEPENDENCIES``: Mark the component to depend on other components. If the user hasn't explicitly added these components in their configuration, a validation error will be generated. - ``AUTO_LOAD``: Automatically load an integration if the user hasn't added it manually. -- ``MULTI_CONF``: Mark this component to accept an array of configurations. +- ``MULTI_CONF``: Mark this component to accept an array of configurations. If this is an + integer instead of a boolean, validation will only permit the given number of entries. - ``CONFLICTS_WITH``: Mark a list of components as conflicting with this integration. If the user has one of them in the config, a validation error will be generated. diff --git a/guides/faq.rst b/guides/faq.rst index 89d356b2c..a2c29bd2b 100644 --- a/guides/faq.rst +++ b/guides/faq.rst @@ -282,9 +282,10 @@ And a docker compose file looks like this: network_mode: host restart: always +.. _docker-reference-notes: .. note:: - ESPHome uses mDNS to show online/offline state in the dashboard view. So for that feature + By default ESPHome uses mDNS to show online/offline state in the dashboard view. So for that feature to work you need to enable host networking mode On MacOS the networking mode ("-net=host" option) doesn't work as expected. You have to use @@ -302,6 +303,19 @@ And a docker compose file looks like this: Alternatively, you can make esphome use ICMP pings to check the status of the device with the Hass.io Addon ``"status_use_ping": true,`` option or with docker ``-e ESPHOME_DASHBOARD_USE_PING=true`` See also https://github.com/esphome/issues/issues/641#issuecomment-534156628. + +.. _faq-notes_on_disabling_mdns: + +Notes on disabling mDNS +------------------------------------------------------------------------------ +Some of ESPHome's functionalities rely on mDNS, so naturally :ref:`disabling ` it will cause these features to stop working. +Generally speaking, disabling mDNS without setting a :ref:`static IP address ` (or a static DHCP lease) is bound to cause problems. This is due to the fact that mDNS is used to find the IP address of each ESPHome nodes. + +- You will not be able to use the node's hostname to ping, find it's IP address or connect to it. + +- Automatic discovery in Home Assistant when using :doc:`native API ` relies on mDNS broadcast messages to detect presence of new ESPHome nodes. If you need to use the native API with mDNS disabled, then you will have to use a static IP address and manually add the ESPHome integration with the fixed IP address. + +- Online status detection in ESPHome's dashboard by default uses mDNS, so disabling mDNS will cause the ESPHome dashboard to show the status of the nodes created without mDNS support to be always offline. Currently, this does not affect any functionality, however if you want to see the online/offline status you could configure ESPHome to ping each node instead. See the :ref:`notes in the Docker Reference section ` for more information. Can Configuration Files Be Recovered From The Device? ----------------------------------------------------- diff --git a/guides/supporters.rst b/guides/supporters.rst index cc302280d..de2560017 100644 --- a/guides/supporters.rst +++ b/guides/supporters.rst @@ -17,6 +17,7 @@ Contributors (in alphabetical order) - `0hax (@0hax) `__ +- `Nikola (@0nikola1) `__ - `0x0a11c0de (@0x0a11c0de) `__ - `2016for (@2016for) `__ - `Pavel Golovin (@31337Ghost) `__ @@ -529,4 +530,4 @@ Contributors - `San (@zhujunsan) `__ - `Christian Zufferey (@zuzu59) `__ -*This page was last updated May 9, 2021.* +*This page was last updated May 10, 2021.* diff --git a/images/b_parasite.jpg b/images/b_parasite.jpg new file mode 100644 index 000000000..46e395c50 Binary files /dev/null and b/images/b_parasite.jpg differ diff --git a/images/esp32_ble_itag.jpg b/images/esp32_ble_itag.jpg new file mode 100644 index 000000000..34ece0dc0 Binary files /dev/null and b/images/esp32_ble_itag.jpg differ diff --git a/images/external_components.svg b/images/external_components.svg new file mode 100644 index 000000000..b366dda6c --- /dev/null +++ b/images/external_components.svg @@ -0,0 +1 @@ + diff --git a/images/fingerprint.svg b/images/fingerprint.svg new file mode 100644 index 000000000..3bfef9230 --- /dev/null +++ b/images/fingerprint.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/images/sgp40.jpg b/images/sgp40.jpg new file mode 100644 index 000000000..947b7d251 Binary files /dev/null and b/images/sgp40.jpg differ diff --git a/images/sht4x.jpg b/images/sht4x.jpg new file mode 100644 index 000000000..950ee411a Binary files /dev/null and b/images/sht4x.jpg differ diff --git a/images/tca9548a.jpg b/images/tca9548a.jpg new file mode 100644 index 000000000..b241b0ec0 Binary files /dev/null and b/images/tca9548a.jpg differ diff --git a/images/tof10120.jpg b/images/tof10120.jpg new file mode 100644 index 000000000..c638fbc75 Binary files /dev/null and b/images/tof10120.jpg differ diff --git a/index.rst b/index.rst index 8f8ede82d..309249633 100644 --- a/index.rst +++ b/index.rst @@ -85,6 +85,7 @@ Core Components Native API, components/api, server-network.svg Power Supply, components/power_supply, power.svg Deep Sleep, components/deep_sleep, hotel.svg + External Components, components/external_components, external_components.svg Sensor Components ----------------- @@ -103,10 +104,13 @@ Sensor Components BH1750, components/sensor/bh1750, bh1750.jpg Binary Sensor Map, components/sensor/binary_sensor_map, binary_sensor_map.jpg BLE RSSI, components/sensor/ble_rssi, bluetooth.svg + BLE Sensor, components/sensor/ble_sensor, bluetooth.svg BME280, components/sensor/bme280, bme280.jpg BME680, components/sensor/bme680, bme680.jpg + BME680 via BSEC, components/sensor/bme680_bsec, bme680.jpg BMP085, components/sensor/bmp085, bmp180.jpg BMP280, components/sensor/bmp280, bmp280.jpg + b-parasite, components/sensor/b_parasite, b_parasite.jpg CCS811, components/sensor/ccs811, ccs811.jpg CSE7766, components/sensor/cse7766, cse7766.svg CT Clamp, components/sensor/ct_clamp, ct_clamp.jpg @@ -155,15 +159,18 @@ Sensor Components SCD30, components/sensor/scd30, scd30.jpg SHTCx, components/sensor/shtcx, shtc3.jpg SHT3X-D, components/sensor/sht3xd, sht3xd.jpg + SHT4X, components/sensor/sht4x, sht4x.jpg SM300D2, components/sensor/sm300d2, sm300d2.jpg SPS30, components/sensor/sps30, sps30.jpg STS3X, components/sensor/sts3x, sts3x.jpg SGP30, components/sensor/sgp30, sgp30.jpg + SGP40, components/sensor/sgp40, sgp40.jpg TCS34725, components/sensor/tcs34725, tcs34725.jpg Teleinfo, components/sensor/teleinfo, teleinfo.jpg Template Sensor, components/sensor/template, description.svg TMP102, components/sensor/tmp102, tmp102.jpg TMP117, components/sensor/tmp117, tmp117.jpg + TOF10120, components/sensor/tof10120, tof10120.jpg Total Daily Energy, components/sensor/total_daily_energy, sigma.svg TSL2561, components/sensor/tsl2561, tsl2561.jpg Tuya Sensor, components/sensor/tuya, tuya.png @@ -264,6 +271,7 @@ Switch Components UART Switch, components/switch/uart, uart.svg Custom Switch, components/switch/custom, language-cpp.svg Tuya Switch, components/switch/tuya, tuya.png + BLE Switch, components/switch/ble, bluetooth.svg Fan Components -------------- @@ -353,6 +361,7 @@ Misc Components Sun, components/sun, weather-sunny.svg GPS, components/gps, crosshairs-gps.svg + ESP32 BLE Client, components/ble_client, bluetooth.svg ESP32 BLE Tracker, components/esp32_ble_tracker, bluetooth.svg ESP32 BLE Beacon, components/esp32_ble_beacon, bluetooth.svg ESP32 Ethernet, components/ethernet, ethernet.svg @@ -363,6 +372,7 @@ Misc Components PCF8574 I/O Expander, components/pcf8574, pcf8574.jpg MCP230XX I/O Expander - I²C Bus, components/mcp230xx, mcp230xx.svg + TCA9548A I²C Multiplexer, components/tca9548a, tca9548a.jpg MCP23SXX I/O Expander - SPI Bus, components/mcp23Sxx, mcp230xx.svg SX1509 I/O Expander, components/sx1509, sx1509.jpg SN74HC595 I/O Expander, components/sn74hc595, sn74hc595.jpg @@ -376,6 +386,7 @@ Misc Components Exposure Notifications, components/exposure_notifications, exposure_notifications.png RTTTL Buzzer, components/rtttl, buzzer.jpg Prometheus, components/prometheus, prometheus.svg + Grow Fingerprint Reader, components/fingerprint_grow, fingerprint.svg Additional Custom Components ---------------------------- @@ -415,6 +426,7 @@ Cookbook 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 Custom UART Text Sensor, cookbook/uart_text_sensor, language-cpp.svg IWOOLE Table Lamp, cookbook/iwoole_rgbw_table_lamp, iwoole_rgbw_table_lamp.png