Improv via Serial

The improv_serial component in ESPHome implements the open Improv standard for configuring Wi-Fi on an ESPHome device by using a serial connection to the device, eg. USB.

The improv_serial component requires the logger component. By default Improv shares the logger’s serial port. When uart_id is set, Improv runs on a dedicated UART bus instead and the logger’s serial settings are unused, so serial logging can be disabled with baud_rate: 0.

The improv_serial component will use the project name and version instead of ESPHomes version whenever it’s available.

# Example configuration entry
wifi:
  # ...

improv_serial:

Configuration variables

next_url (Optional, url): A URL that can be used to forward the user to after setting credentials with improv.
uart_id (Optional, ID): Run Improv on this UART bus instead of the logger’s serial port. The bus needs both tx_pin and rx_pin.

Next URL

Substitutions can be inserted into the URL, such as project name and version and there are some special substitutions that can be performed by ESPHome when wrapped in double braces {{ }} :

device_name: This will substitute the device name including the mac address suffix.
ip_address: This will substitute the IP address of the device.
esphome_version: This will substitute the version of ESPHome that is running on the device.

# Example next_url
improv_serial:
  next_url: http://example.com/?device_name={{device_name}}&ip_address={{ip_address}}&esphome_version={{esphome_version}}

Dedicated UART

Improv normally shares the serial port used for logging. To run it on its own port instead, point uart_id at a UART bus with both pins configured:

uart:
  - id: improv_uart
    tx_pin: GPIOXX
    rx_pin: GPIOXX
    baud_rate: 115200

improv_serial:
  uart_id: improv_uart

Improv via Serial

Configuration variables

Next URL

Dedicated UART

See Also