Provision New Microcontroller

Provisioning a new microcontroller is always the first step in an ESPHome project: it turns a generic microcontroller into a fully managed ESPHome device. The provisioning procedure uploads ESPHome firmware to the microcontroller.

Once done, the microcontroller can receive firmware updates wirelessly (no need for USB cables, tools, and awkward button presses) and is fully manageable by your ESPHome instance.

Supported Microcontrollers

Any microcontroller that is supported by ESPHome can be provisioned:

• Espressif: ESP8266, ESP32 including newer family members like S2, S3, C3. The latter are still under active development, so expect a few quirks and issues.
• Raspberry: RP2040
• Beken and Realtec: Beken BK72xx and Realtec RTL87xx are often found in commercial smart devices such as sensors, lamps, or plugs and can be converted to ESPHome devices, effectively freeing them from proprietary vendor clouds and turning them into locally controlled devices.

In practice, this is not always trivial since commercial devices typically have neither USB ports nor UART chips to upload new firmware.

esphome:
  name: esp32-c6
  friendly_name: esp32 c6

esp32:
  board: esp32-c6-devkitc-1
  flash_size: 8MB
  variant: esp32c6
  framework:
    type: esp-idf
    version: "5.2.1"
    platform_version: 6.6.0
    sdkconfig_options:
      CONFIG_OPENTHREAD_ENABLED: n
      CONFIG_ENABLE_WIFI_STATION: y
      CONFIG_USE_MINIMAL_MDNS: y
      CONFIG_ESPTOOLPY_FLASHSIZE_8MB: y

# fix for logger from luar123
external_components:
    - source: github://luar123/esphome@fix_logger
      components: [ logger ]
      refresh: never

# Enable logging
logger:

# Enable Home Assistant API
api:
  encryption:
    key: "..."

ota:
  - platform: esphome
    password: "..."

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

  # Enable fallback hotspot (captive portal) in case wifi connection fails
  ap:
    ssid: "Esp32-C6 Fallback Hotspot"
    password: "..."

captive_portal:

Provisioning Strategies

There are two ways of provisioning a microcontroller for use with ESPHome:

• Basic provisioning: only requires a web browser. After provisioning, the microcontroller can be used *at any time - now or later - for a specific project.
• Integrated provisioning: occurs automatically when you create a ESPHome configuration and design a particular ESPHome device.

Basic Provisioning

Below steps perform a basic provisioning for a fresh microcontroller, for example if you just received a bunch of new microcontrollers that you would like to prepare for use with ESPHome at a later time.

Provisioning also serves as a quick test whether your new microcontrollers work correctly.

No specific prerequisites are needed for this step. In fact, you do not even need ESPHome for it. A compatible web browser (i.e. Chrome) is all you need.

Should the procedure below not work for your particular microcontroller (board), then try alternate ways, i.e. to provision ESP32 S2 Mini and similar boards that are notorious for using incompatible USB/UART designs.

Check WiFi Antenna

Most ESPxx microcontrollers come with a built-in WiFi PCB antenna and are simple to use.

Some ESP32 modules have an auxiliary IPEX connector to attach an external antenna in case you need more reach. They still also have a visible PCB antenna which is active by default. The IPEX connector is not used until you take a soldering iron and actively change the antenna connection.

Finally, some ESP32 modules have an IPEX connector but no built-in PCB antenna. This saves space in cases where you always want to use an external antenna.

The downside is that you now must attach an external WiFi antenna before you can power on the microcontroller. If you operate it without antenna, this can damage its RF unit. While it typically does not cause harm to run such a microcontroller for just the few seconds it takes to provision it, you shouldn’t take this risk and attach an external antenna before proceeding with the provisioning.

Operating a microcontroller without WiFi antenna is not just hurting its RF unit, it also severely limits reception. During provisioning you will only be able to connect to very strong WiFi signals.

Upload Generic ESPHome Firmware

In this first step, you upload generic ESPHome firmware to your microcontroller:

1. Connect the microcontroller via USB cable to your computer. Place the microcontroller in firmware update mode: hold its boot button while you shortly press its reset button. A new usb device discovered sound should heard from your PC.

2. In a browser (Chrome, Edge), navigate to web.esphome.io, and click CONNECT.

   

3. In supported browsers (i.e. Chrome, Edge), you now see the microcontroller board that is connected to your USB port. Select it, and click Connect:

   

   If the list is empty and your microcontroller is not recognized, close all programs and reboot your computer.

4. You are presented with a menu. Click Prepare for first use:

   

5. A dialog explains that you are about to upload the basic ESPHome firmware to your microcontroller. Click INSTALL.

   

6. The ESPHome default firmware is copied to your microcontroller which takes a few seconds.

   

   If you just see a spinning wheel for more than a few seconds, keep the boot button on the microcontroller pressed until the firmware upload starts.

7. Once the installation is complete, you are greeted with a success message. Click CLOSE.

   

8. Press the reset button on the microcontroller board to make sure it boots from the new firmware.

The device is now provisioned, however it is not yet connected to any specific WiFi. To actually use it in ESPHome, it needs to connect to the WiFi that ESPHome is connected to (see next step).

Whether you provision the WiFi access now or postpone it to later. You can perform the WiFi configuration (below) at any time. If you plan to use the microcontroller in your own home or lab environment, it is recommended to fully complete the provisioning process and add the WiFi credentials now (as shown below).

Connecting To WiFi

The provisioning process automatically re-connects the device and shows this dialog:

If you do not want to configure WiFi at this point, click CLOSE.

If you instead see the dialog below, click CLOSE, then click the three dot menu, and choose Configure Wi-Fi.

You can always return to this point by connecting the microcontroller via USB cable, and opening ESPHome Web Tool in your browser. Once the browser has connected to the microcontroller, click the three-dot menu to configure WiFi access.

To complete provisioning and enable the device to automatically connect to your WiFi, click CONNECT TO WI-FI.

In a drop-down list, select the WiFi SSID you want to connect to, and provide the WiFi password. The connection is then tested, and provisioning is successfully completed.

What’s Next

When you supply power to a microcontroller that has been fully provisioned before, it automatically boots with its ESPHome firmware and connects to your WiFi.

Once it is online, it is automatically detected by ESPHome and appears as a newly discovered device that can be adopted it.

During adoption, it receives its own individual configuration file and now is no longer adoptable by any ESPHome instance.

You can now edit its configuration and add specific logic to it as required.

Comments

Please do leave comments below. I am using utteran.ce, an open-source and ad-free light-weight commenting system.

  Show on Github    Submit Issue

^{_{(content created Jun 01, 2024 - last updated Jul 12, 2024)}}