Update the docs for ESP32-C3 devices

[grigi]

Hi, thanks for this project! It's great that I can re-use my many ESPHome devices for location tracking :smiley:

This issue is just some documentation-related suggestions.

WIKI update

The documentation in the wiki https://github.com/agittins/bermuda/wiki/ESPHome-Configurations#esp32-c3-modules should be updated with some minor corrections.

Firstly, the API connect/disconnect logic is not great in that when restarting home assistant (in case of a hard reset) the order of connection signals are:

• connect old-HA
• HARD REBOOT (cause plug was accidentally pulled)
• connect new-HA
• disconnect old-HA (after a timeout)

Also when connecting to see the logs, closing the view will trigger a disconnect api signal. Any disconnect will disable scanning.

Please update the example block for increased robustness:

api:
  # Only enable BLE tracking when wifi is up and api is connected
  # Gives the single-core ESP32C3 devices time to manage wifi and authenticating 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:

I have also tested with various different frameworks and the options, and the suggested settings of:

esp32:
  board: esp32-c3-devkitm-1
  framework:
    type: esp-idf
    sdkconfig_options:
      CONFIG_BT_BLE_50_FEATURES_SUPPORTED: y
      CONFIG_BT_BLE_42_FEATURES_SUPPORTED: y
      # If device spends more than 10 seconds "doing stuff" it will reboot.
      CONFIG_ESP_TASK_WDT_TIMEOUT_S: "10"

is noticeably more responsive when moving around versus using arduino or not specifying the config options. I would reccomend that for C3 boards you'd need both and to try and not load them with too much work. On the one board that has a lot of sensors and doing PWM, I got better stability by reducing the window to 280ms.

Sample config

On a different, but related topic. It would be helpful to have example config files as reference-points for various board types: I had a lot of Seeed XIAO ESP32-C3 boards lying around so used them for BT beacons, and they now work very reliably.

For example, a reasonably good starting point for ESP32-C3 boards is:

substitutions:
  name: "esp32-c3-sample"
  friendly_name: "BTScanner-ESP32C3"

esphome:
  name: ${name}
  friendly_name: ${friendly_name}
  min_version: 2024.6.0
  name_add_mac_suffix: false

esp32:
  board: esp32-c3-devkitm-1
  framework:
    type: esp-idf
    sdkconfig_options:
      CONFIG_BT_BLE_50_FEATURES_SUPPORTED: y
      CONFIG_BT_BLE_42_FEATURES_SUPPORTED: y
      # If device spends more than 10 seconds "doing stuff" it will reboot.
      CONFIG_ESP_TASK_WDT_TIMEOUT_S: "10"

# Enable logging, but disable serial logging to free some CPU
logger:
  baud_rate: 0

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

# Allow Over-The-Air updates
ota:
- platform: esphome

api:
  # encryption:
  #   key: "set this super secret key please"

  # Only enable BLE tracking when wifi is up and api is connected
  # Gives the single-core ESP32C3 devices time to manage wifi and authenticating 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.
    continuous: False

    # Whether to send scan-request packets to devices to gather more info (like devicename)
    active: True
    # Listen on BLE for 300ms out of ever 320ms interval
    # If the device is failing to keep up, reduce the window to give it more time to do stuff
    interval: 320ms # suggested 211ms # default 320ms
    window:   300ms # suggested 120ms # default 30ms    

bluetooth_proxy:
  active: true

sensor:
  - platform: uptime
    name: "Uptime Sensor"
    update_interval: 60s

It might be worth it to add sample configs for standard/S3/C3 variants that are mentioned in the wiki. Maybe put them in an example_config/ folder on the repo?

[agittins]

@grigi thanks for putting all this together, it's fantastic!

It might be worth it to add sample configs

Yes, I've been keen to do this, perhaps as a package that people can easily import / adopt into their esphome dashboard.

At any rate, I'll definitely integrate this into the wiki, thanks so much for taking the time to work through the options to test and document it all!

[nebulous]

For the Xiao boards, any reason to use esp32-c3-devkitm-1 vs the more-specific seeed_xiao_esp32c3 board definition?

https://docs.platformio.org/en/latest/boards/espressif32/seeed_xiao_esp32c3.html

[grigi]

Other than that I didn't even know that was an option, no. The esp32-c3-devkitm-1 works perfectly for all my projects. I think I have about 7 of those board deployed around the place doing various sensor stuff right now.

[agittins]

I've just updated the wiki to incorporate your findings. I plan to create some package configs though as you suggest that will allow us to simplify the process for people a lot. I'll keep this open until I get that done, I think.

[EFH52]

Here is a use case that seems to be working on an Apollo MTR-1 using the notes above (mostly from the wiki as they've been added). I have departures bouncing between rooms yet, but am following the exploration in other issues for that yet.

substitutions:
  name: lr_mtr
  friendly_name: Living Room MTR

packages:
  ApolloAutomation.MTR-1: github://ApolloAutomation/MTR-1/Integrations/ESPHome/MTR-1.yaml

esphome:
  name: ${name}
  name_add_mac_suffix: false
  friendly_name: ${friendly_name}

api:
  encryption:
    key: !secret api_encryption_key_lr_mtr
  #added below from Bermuda Wiki
  on_client_connected:
    - esp32_ble_tracker.start_scan:
        continuous: true
  on_client_disconnected:
    if:
      condition:
        not:
          api.connected:
      then:
        - esp32_ble_tracker.stop_scan:

esp32:
  framework:
    type: esp-idf #redundant to core .yml, but left in for clarity
    sdkconfig_options: 
      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"

esp32_ble_tracker:
  scan_parameters:
    continuous: False
    active: True
    interval: 320ms
    window: 290ms

bluetooth_proxy:
  active: true

logger:
  level: INFO
  baud_rate: 0

wifi:
  power_save_mode: LIGHT #replaced the NONE in core .yml as it is required for BLE and Wifi to cooperate
  ssid: !secret wifi_ssid
  password: !secret wifi_password