diff --git a/docs/customization.md b/docs/customization.md index 4201f2e..0ef9824 100644 --- a/docs/customization.md +++ b/docs/customization.md @@ -27,6 +27,7 @@ Table of contents: - [Framework `arduino`](#framework-arduino) - [Framework `esp-idf`](#framework-esp-idf) - [Bluetooth proxy](#bluetooth-proxy) + - [BLE tracker](#ble-tracker) - [Logger via UART](#logger-via-uart) - [Climate custom presets](#climate-custom-presets) - [Push button / Momentary switch](#push-button--momentary-switch) @@ -566,20 +567,85 @@ esp32: > [!IMPORTANT] > The [ESP32 Platform](#framework-esp-idf) component should be configured to use the `esp-idf` framework, -> as the `arduino` framework uses significantly more memory and performs poorly with the Bluetooth proxy enabled. +> as the `arduino` framework uses significantly more memory and performs poorly with the Bluetooth stack enabled. -> [!NOTE] -> The Bluetooth proxy component significantly reduces device RAM, leaving less than 10k RAM free. +> [!IMPORTANT] +> The Bluetooth stack significantly reduces device RAM. > Enabling this with additional customizations/components may lead to crashes due to low memory. > HTTPS connections might be erratic, and local TFT flashing could fail due to insufficient RAM. > > Solutions include: -> 1. Flash the device (remove Bluetooth proxy) while updating TFT. -> 2. Flash from a local (HTTP) source at a low baud rate (9600 or lower) to avoid memory crashes. This method is slower, taking over 10 minutes. +> 1. Flash the device (remove Bluetooth components) while updating TFT. +> 2. Flash from a local (HTTP) source at a low baud rate (9600 or lower) to avoid memory crashes. This method is slower. ```yaml # Enable Bluetooth proxy bluetooth_proxy: + id: ble_proxy + +# Give an id for the BLE Tracker (which is part of BT proxy) +esp32_ble_tracker: + id: ble_tracker + +# Modify upload tft engine to stop BLE scan while uploading +script: + - id: !extend upload_tft + then: + - lambda: |- + static const char *const TAG = "CUSTOM.script.upload_tft"; + ble_tracker->dump_config(); + ESP_LOGD(TAG, "Stopping BLE Tracker scan..."); + ble_tracker->stop_scan(); + ESP_LOGD(TAG, "Disabling BLE Tracker scan..."); + ble_tracker->set_scan_active(false); + ESP_LOGD(TAG, "State: %s", id(ble_proxy)->has_active() ? "Active" : "Passive"); + while (ble_proxy->get_bluetooth_connections_limit() != ble_proxy->get_bluetooth_connections_free()) { + ESP_LOGD(TAG, "Connections: %i of %i", int(ble_proxy->get_bluetooth_connections_limit() - ble_proxy->get_bluetooth_connections_free()), int(ble_proxy->get_bluetooth_connections_limit())); + if (id(ble_proxy)->has_active()) { + ESP_LOGD(TAG, "Setting passive mode..."); + ble_proxy->set_active(false); + } + vTaskDelay(pdMS_TO_TICKS(1000)); + App.feed_wdt(); + } + +# Set Wi-Fi power save mode to "LIGHT" as required for Bluetooth on ESP32 +wifi: + power_save_mode: LIGHT +``` + +### BLE Tracker + +> [!IMPORTANT] +> The [ESP32 Platform](#framework-esp-idf) component should be configured to use the `esp-idf` framework, +> as the `arduino` framework uses significantly more memory and performs poorly with the Bluetooth stack enabled. + +> [!IMPORTANT] +> The Bluetooth stack significantly reduces device RAM. +> Enabling this with additional customizations/components may lead to crashes due to low memory. +> HTTPS connections might be erratic, and local TFT flashing could fail due to insufficient RAM. +> +> Solutions include: +> 1. Flash the device (remove Bluetooth components) while updating TFT. +> 2. Flash from a local (HTTP) source at a low baud rate (9600 or lower) to avoid memory crashes. This method is slower. + +```yaml +# Enable Bluetooth tracker +esp32_ble_tracker: + id: ble_tracker + +# Modify upload tft engine to stop BLE tracker while uploading +script: + - id: !extend upload_tft + then: + - lambda: |- + static const char *const TAG = "CUSTOM.script.upload_tft"; + ble_tracker->dump_config(); + ESP_LOGI(TAG, "Stopping BLE Tracker scan..."); + ble_tracker->stop_scan(); + ESP_LOGI(TAG, "Disabling BLE Tracker scan..."); + ble_tracker->set_scan_active(false); + # Set Wi-Fi power save mode to "LIGHT" as required for Bluetooth on ESP32 wifi: power_save_mode: LIGHT