Skip to content

ESPHome Configurations

Jump to bottom
Ashley Gittins edited this page Sep 24, 2024 · 4 revisions

Compatibility of ESP32 Chips

Chip Compat Notes
ESP32 Good Original esp32 chip, such as the ESP-WROOM-32 etc. BT4.2
ESP32-S2 NO Has no Bluetooth, single core.
ESP32-S3 Good? BT5, Dual-core. No integrated Ethernet MAC
ESP32-C2 ?? Single-core RISC-V
ESP32-C3 Good, see below Single core RISC-V, BT5
ESP32-C6 ?? Dual-core RISC-V, BT5.3, Thread, Zigbee
ESP32-H2 ?? Single-core RISC-V, BT5.3, NO WIFI
ESP32-C5 ?? Single-core RISC-V, BT5, WIFI6 (2.4GHz + 5GHz)
ESP32-P4 NO Triple-core RISC-V, NO WIFI OR BT
  • Please let me know if you have first-hand experience of bluetooth-proxy working on any of the above where I don't have "Good" noted. The "??" entries don't mean "it doesn't work well" it literally means that I, personally, aren't sure - probably because I've been too lazy to check properly. Corrections welcomed!

General configuration

  • Use the esp-idf framework, as the arduino framework is less memory-efficient and doesn't seem to perform as well.
esp32:
  board: wemos_d1_mini32  # Make sure you choose *your* board here!
  framework:
    type: esp-idf
  • I turn off serial logging because I think it uses more memory and cpu time. I don't know if that's entirely true or not. With this setting you still get debug logging via wireless connection.
logger:
  baud_rate: 0  # disable serial uart logging
  #level: VERBOSE
  • Try flashing your proxy via USB or Serial just once. This is because esphome changed the flash format/layout not too long ago in order to improve the Bluetooth performance and stability, but esphome will only apply that change when the board is flashed via USB or Serial - it won't do it when flashing OTA. (todo: find version where flash partition layout changed - early 2024?)

BLE Tracker settings

The default ESPHome setup works "ok" but it is fairly conservative with the advert listening, which works for most use-cases but we want the esp32 to be hearing every possible advert.

The default setup listens for advertisements for 30ms every 320ms. This means that for 90% of the time, it isn't receiving adverts!

The BLE advert protocol is designed to handle this by adding random delays in various places, so that users can usually "find" the devices they want to connect to, but for our purposes we want to see every advert we can.

This is worth experimenting with, but my current suggestion is to use the following:

esp32_ble_tracker:
  scan_parameters:
    active: True # Whether to send scan-request packets to devices to gather more info (like devicename)
    interval: 320ms # suggested 211ms # default 320ms
    window:   300ms # suggested 120ms # default 30ms

Other interval/window timings to try are 1000/900. You can experiment with these, but bear in mind:

  • the difference between invterval and window is where esphome gets to do everything else it needs to do, including managing the wifi connection and actually sending data back to Home Assistant.
  • If the interval and window values are too close together, your esp will crash, the wifi will drop, timeouts with HA etc.
  • A BLE device will typically send an advertisement on each of the three advertising channels, in rapid succession, wait for its own interval time, then repeat.
  • setting active: False might give better performance, I am not sure. The downside with active mode is that the esp will be spending some of its time sending requests to devices to discover their names. This might impact receive performance, I am not sure. The up-side of active mode is that you are more likely to get the name of devices showing up in Bermuda when configuring things, but this isn't hugely useful since you can simply name your entities however you like anyway.
  • If, and ONLY IF you have an esp32 connected via Ethernet, you could use interval/window timings of 1:1 (so, 1000 and 1000, say).

ESP32-C3 Modules

The C3 variant of the ESP32 has a single cpu, rather than two cores per the other variants. This seems to result in there being more cases where the sharing of bluetooth and wifi between the one radio causes more difficulties with the software.

  • Any time the firmware is doing "bluetooth stuff" it can't do any "wifi stuff". So if the interval is too long wifi things will time out.
  • If window is too close to interval then it won't have enough time to perform the wifi (or other) things it needs to do.

A solid config for C3 devices is provided below. Thanks to @grigi's report for pulling this together and providing additional testing. Particularly important are the esp32, api and scan_paramaters parts.

The suggested ESP32-C3 config:

esp32:
  board: esp32-c3-devkitm-1  # Feel free to use a more specific board if that's what you have
  framework:
    type: esp-idf  # This is important: the default "arduino" framework does not perform well.
    sdkconfig_options:
      # @grigi found in testing that these options resulted in better responsiveness.
      # BLE 4.2 is supported by ALL ESP32 boards that have bluetooth, the original and derivatives.
      CONFIG_BT_BLE_42_FEATURES_SUPPORTED: y
      # Also enable this on any derivative boards (S2, C3 etc) but not the original ESP32.
      CONFIG_BT_BLE_50_FEATURES_SUPPORTED: y
      # Extend the watchdog timeout, so the device reboots if the device appears locked up for over 10 seconds.
      CONFIG_ESP_TASK_WDT_TIMEOUT_S: "10"

logger:
  baud_rate: 0  # 0 Enables logging, but disables serial-port logging to free CPU and memory

ota:
  platform: esphome

api:

  # Only enable BLE tracking when wifi is up and api is connected
  # Gives single-core ESP32-C3 devices time to manage wifi and authenticate with api
  on_client_connected:
     - esp32_ble_tracker.start_scan:
        continuous: true
  # Disable BLE tracking when there are no api connections live
  on_client_disconnected:
    if:
      condition:
        not:
          api.connected:
      then:
        - esp32_ble_tracker.stop_scan:

esp32_ble_tracker:
  scan_parameters:
    # Don't auto start BLE scanning, we control it in the `api` block's automation.
    continuous: False
    
    active: True  # send scan-request packets to gather more info, like device name for some devices.

    interval: 320ms  # default 320ms - how long to spend on each advert channel
    window:   300ms  # default 30ms - how long to actually "listen" in each interval. Reduce this if device is unstable.
    # If the device cannot keep up or becomes unstable, reduce the "window" setting. This may be
    # required if your device is controlling other sensors or doing PWM for lights etc.

bluetooth_proxy:
  active: true  # allows outbound connections from HA to devices.

sensor:
  - platform: uptime
    # The uptime sensor is extremely helpful to know if your device is rebooting
    # when it shouldn't be. This might indicate your interval-to-window timing is
    # too tight, and the window needs to be reduced.
    name: "Uptime Sensor"
    update_interval: 60s

Sources:

Clone this wiki locally