175 lines
5.5 KiB
ReStructuredText
175 lines
5.5 KiB
ReStructuredText
Improv via BLE
|
|
==============
|
|
|
|
.. seo::
|
|
:description: Instructions for setting up Improv via BLE in ESPHome.
|
|
:image: improv-social.png
|
|
|
|
The ``esp32_improv`` component in ESPHome implements the open `Improv standard <https://www.improv-wifi.com/>`__
|
|
for configuring Wi-Fi on an ESP32 device by using Bluetooth Low Energy (BLE) to receive the credentials.
|
|
|
|
The ``esp32_improv`` component will automatically set up the :doc:`BLE Server <esp32_ble>`.
|
|
|
|
.. warning::
|
|
|
|
The BLE software stack on the ESP32 consumes a significant amount of RAM on the device.
|
|
|
|
**Crashes are likely to occur** if you include too many additional components in your device's
|
|
configuration. Memory-intensive components such as :doc:`/components/voice_assistant` and other
|
|
audio components are most likely to cause issues.
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration entry
|
|
wifi:
|
|
# ...
|
|
|
|
esp32_improv:
|
|
authorizer: binary_sensor_id
|
|
|
|
|
|
Configuration variables:
|
|
------------------------
|
|
|
|
- **authorizer** (**Required**, :ref:`config-id`): A :doc:`binary sensor <binary_sensor/index>` to authorize with.
|
|
Also accepts ``none``/``false`` to skip authorization.
|
|
- **authorized_duration** (*Optional*, :ref:`config-time`): The amount of time until authorization times out and needs
|
|
to be re-authorized. Defaults to ``1min``.
|
|
- **status_indicator** (*Optional*, :ref:`config-id`): An :doc:`output <output/index>` to display feedback to the user.
|
|
- **identify_duration** (*Optional*, :ref:`config-time`): The amount of time to identify for. Defaults to ``10s``.
|
|
- **wifi_timeout** (*Optional*, :ref:`config-time`): The amount of time to wait before starting the Improv service
|
|
after Wi-Fi is no longer connected. Defaults to ``1min``.
|
|
- **on_start** (*Optional*, :ref:`Automation<automation>`): An action to be performed when Improv is waiting for
|
|
authorization and/or upon authorization. See :ref:`improv-on_start`.
|
|
- **on_provisioned** (*Optional*, :ref:`Automation<automation>`): An action to be performed when provisioning has
|
|
completed. See :ref:`improv-on_provisioned`.
|
|
- **on_provisioning** (*Optional*, :ref:`Automation<automation>`): An action to be performed when the device begins the
|
|
provisioning process. See :ref:`improv-on_provisioning`.
|
|
- **on_stop** (*Optional*, :ref:`Automation<automation>`): An action to be performed when Improv has stopped.
|
|
See :ref:`improv-on_stop`.
|
|
- **on_state** (*Optional*, :ref:`Automation<automation>`): An action to be performed when an Improv state change
|
|
happens. See :ref:`improv-on_state`.
|
|
|
|
.. _improv-automations:
|
|
|
|
Improv Automations
|
|
------------------
|
|
|
|
The ESP32 Improv component provides various :ref:`automations <automation>` that can be used to provide feedback during
|
|
the Improv provisioning process.
|
|
|
|
.. _improv-on_start:
|
|
|
|
``on_start``
|
|
************
|
|
|
|
This automation will be triggered when the device is waiting for authorization (usually by pressing a button on the
|
|
device, if configured -- see ``authorizer`` above) and/or upon authorization.
|
|
|
|
.. code-block:: yaml
|
|
|
|
esp32_improv:
|
|
on_start:
|
|
then:
|
|
- logger.log: "Improv awaiting authorization/authorized"
|
|
|
|
.. _improv-on_provisioned:
|
|
|
|
``on_provisioned``
|
|
******************
|
|
|
|
This automation will be triggered when provisioning has completed.
|
|
|
|
.. code-block:: yaml
|
|
|
|
esp32_improv:
|
|
on_provisioned:
|
|
then:
|
|
- logger.log: "Improv provisioned"
|
|
|
|
.. _improv-on_provisioning:
|
|
|
|
``on_provisioning``
|
|
*******************
|
|
|
|
This automation will be triggered when provisioning begins.
|
|
|
|
.. code-block:: yaml
|
|
|
|
esp32_improv:
|
|
on_provisioning:
|
|
then:
|
|
- logger.log: "Improv provisioning"
|
|
|
|
.. _improv-on_stop:
|
|
|
|
``on_stop``
|
|
***********
|
|
|
|
This automation will be triggered when Improv has stopped.
|
|
|
|
.. code-block:: yaml
|
|
|
|
esp32_improv:
|
|
on_stop:
|
|
then:
|
|
- logger.log: "Improv stopped"
|
|
|
|
.. _improv-on_state:
|
|
|
|
``on_state``
|
|
************
|
|
|
|
This automation will be triggered on every state change.
|
|
|
|
Two variables are available for use in :ref:`lambdas<config-lambda>` within this automation. They are:
|
|
|
|
- ``state``, an ``enum`` named ``improv::State``, having one of the following values:
|
|
|
|
- ``improv::STATE_STOPPED``
|
|
- ``improv::STATE_AWAITING_AUTHORIZATION``
|
|
- ``improv::STATE_AUTHORIZED``
|
|
- ``improv::STATE_PROVISIONING``
|
|
- ``improv::STATE_PROVISIONED``
|
|
|
|
- ``error``, an ``enum`` named ``improv::Error``, having one of the following values:
|
|
|
|
- ``improv::ERROR_NONE``
|
|
- ``improv::ERROR_INVALID_RPC``
|
|
- ``improv::ERROR_UNKNOWN_RPC``
|
|
- ``improv::ERROR_UNABLE_TO_CONNECT``
|
|
- ``improv::ERROR_NOT_AUTHORIZED``
|
|
- ``improv::ERROR_UNKNOWN``
|
|
|
|
.. code-block:: yaml
|
|
|
|
esp32_improv:
|
|
on_state:
|
|
then:
|
|
- if:
|
|
condition:
|
|
lambda: return state == improv::STATE_AUTHORIZED;
|
|
then:
|
|
- logger.log: "Improv state is STATE_AUTHORIZED"
|
|
|
|
Status Indicator
|
|
----------------
|
|
|
|
The ``status_indicator`` has the following patterns:
|
|
|
|
- solid: The improv service is active and waiting to be authorized.
|
|
- blinking once per second: The improv service is awaiting credentials.
|
|
- blinking 3 times per second with a break in between: The identify command has been used by the client.
|
|
- blinking 5 times per second: Credentials are being verified and saved to the device.
|
|
- off: The improv service is not running.
|
|
|
|
See Also
|
|
--------
|
|
|
|
- :doc:`wifi`
|
|
- :doc:`improv_serial`
|
|
- :doc:`captive_portal`
|
|
- `Improv Wi-Fi <https://www.improv-wifi.com/>`__
|
|
- :apiref:`esp32_improv/esp32_improv_component.h`
|
|
- :ghedit:`Edit`
|