esp32_improv.rst

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 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.

# 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 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

The ESP32 Improv component provides various :ref:`automations <automation>` that can be used to provide feedback during the Improv provisioning process.

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.

esp32_improv:
  on_start:
    then:
      - logger.log: "Improv awaiting authorization/authorized"

on_provisioned

This automation will be triggered when provisioning has completed.

esp32_improv:
  on_provisioned:
    then:
      - logger.log: "Improv provisioned"

on_provisioning

This automation will be triggered when provisioning begins.

esp32_improv:
  on_provisioning:
    then:
      - logger.log: "Improv provisioning"

on_stop

This automation will be triggered when Improv has stopped.

esp32_improv:
  on_stop:
    then:
      - logger.log: "Improv stopped"

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

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
• :apiref:`esp32_improv/esp32_improv_component.h`
• :ghedit:`Edit`