Introducing "Add-on: Bluetooth Proxy"

Supports:
- #1983
- #1946
- #1815

docs/README.md

@@ -12,7 +12,8 @@
 
 ## Advanced settings
 - [Customization](customization.md)
-- [Add-on climate](addon_climate.md)
+- [Add-on Bluetooth Proxy](addon_bluetooth_proxy.md)
+- [Add-on Climate](addon_climate.md)
 - [Alarm Control Panel](alarm.md)
 - [API](api.md)
 - [Using Different Versions of This Project](different_version.md)

docs/addon_bluetooth_proxy.md

@@ -0,0 +1,50 @@
+# Add-on: Bluetooth Proxy
+
+## Description
+
+This add-on allows your panel's relays to function as a Bluetooth proxy (BLE only) by utilizing the internal Bluetooth radio
+along with the [ESPHome Bluetooth Proxy component](https://esphome.io/components/bluetooth_proxy.html).
+
+> [!IMPORTANT]
+>  Ensure you configure the Bluetooth Proxy using this add-on as it will enable better memory management by releasing the Bluetooth stack before a TFT update.
+
+## Installation
+
+To install, add the reference to `nspanel_esphome_addon_bluetooth_proxy` in your ESPHome settings under the `packages` section
+following the `remote_package` entry, as illustrated below:
+
+> [!WARNING]
+> While the `esp-idf` framework is the default and recommended for the [ESP32 Platform](#framework-esp-idf) when Bluetooth features are enabled,
+> ensure it is not switched to the `arduino` framework. The `arduino` framework significantly increases memory usage, which may prevent installation on your panel.
+
+```yaml
+substitutions:
+  # Settings - Editable values
+  device_name: "YOUR_NSPANEL_NAME"
+  friendly_name: "Your panel's friendly name"
+  wifi_ssid: !secret wifi_ssid
+  wifi_password: !secret wifi_password
+
+  # Add-on configuration (if needed)
+  ## Add-on climate
+  # heater_relay: "1"  # Possible values: "1" or "2"
+
+# Customization area
+##### My customization - Start #####
+##### My customization - End #####
+
+# Basic and optional configurations
+packages:
+  remote_package:
+    url: https://github.com/Blackymas/NSPanel_HA_Blueprint
+    ref: main
+    refresh: 300s
+    files:
+      - nspanel_esphome.yaml # Basic package
+      # Optional advanced and add-on configurations
+      # - esphome/nspanel_esphome_advanced.yaml
+      - esphome/nspanel_esphome_addon_bluetooth_proxy.yaml
+      # - esphome/nspanel_esphome_addon_climate_cool.yaml
+      # - esphome/nspanel_esphome_addon_climate_heat.yaml
+      # - esphome/nspanel_esphome_addon_climate_dual.yaml
+```

docs/addon_climate.md

@@ -46,14 +46,15 @@ packages:
   remote_package:
     url: https://github.com/Blackymas/NSPanel_HA_Blueprint
     ref: main
+    refresh: 300s
     files:
       - nspanel_esphome.yaml # Basic package
       # Optional advanced and add-on configurations
       # - esphome/nspanel_esphome_advanced.yaml
-      # - nspanel_esphome_addon_climate_cool.yaml
+      # - esphome/nspanel_esphome_addon_bluetooth_proxy.yaml
-      - nspanel_esphome_addon_climate_heat.yaml
+      # - esphome/nspanel_esphome_addon_climate_cool.yaml
-      # - nspanel_esphome_addon_climate_dual.yaml
+      - esphome/nspanel_esphome_addon_climate_heat.yaml
-    refresh: 300s
+      # - esphome/nspanel_esphome_addon_climate_dual.yaml
 ```
 
 ## Configuration
@@ -116,14 +117,15 @@ packages:
   remote_package:
     url: https://github.com/Blackymas/NSPanel_HA_Blueprint
     ref: main
+    refresh: 300s
     files:
       - nspanel_esphome.yaml # Basic package
       # Optional advanced and add-on configurations
       # - esphome/nspanel_esphome_advanced.yaml
-      - nspanel_esphome_addon_climate_cool.yaml
+      # - esphome/nspanel_esphome_addon_bluetooth_proxy.yaml
-      # - nspanel_esphome_addon_climate_heat.yaml
+      - esphome/nspanel_esphome_addon_climate_cool.yaml
-      # - nspanel_esphome_addon_climate_dual.yaml
+      # - esphome/nspanel_esphome_addon_climate_heat.yaml
-    refresh: 300s
+      # - esphome/nspanel_esphome_addon_climate_dual.yaml
 ```
 
 ### Heater
@@ -155,16 +157,18 @@ packages:
   remote_package:
     url: https://github.com/Blackymas/NSPanel_HA_Blueprint
     ref: main
+    refresh: 300s
     files:
       - nspanel_esphome.yaml # Basic package
       # Optional advanced and add-on configurations
       # - esphome/nspanel_esphome_advanced.yaml
-      # - nspanel_esphome_addon_climate_cool.yaml
+      # - esphome/nspanel_esphome_addon_bluetooth_proxy.yaml
-      - nspanel_esphome_addon_climate_heat.yaml
+      # - esphome/nspanel_esphome_addon_climate_cool.yaml
-      # - nspanel_esphome_addon_climate_dual.yaml
+      - esphome/nspanel_esphome_addon_climate_heat.yaml
-    refresh: 300s
+      # - esphome/nspanel_esphome_addon_climate_dual.yaml
 ```
 
+
 ### Dual
 
 ```yaml
@@ -197,14 +201,15 @@ packages:
   remote_package:
     url: https://github.com/Blackymas/NSPanel_HA_Blueprint
     ref: main
+    refresh: 300s
     files:
       - nspanel_esphome.yaml # Basic package
       # Optional advanced and add-on configurations
       # - esphome/nspanel_esphome_advanced.yaml
-      # - nspanel_esphome_addon_climate_cool.yaml
+      # - esphome/nspanel_esphome_addon_bluetooth_proxy.yaml
-      # - nspanel_esphome_addon_climate_heat.yaml
+      # - esphome/nspanel_esphome_addon_climate_cool.yaml
-      - nspanel_esphome_addon_climate_dual.yaml
+      # - esphome/nspanel_esphome_addon_climate_heat.yaml
-    refresh: 300s
+      - esphome/nspanel_esphome_addon_climate_dual.yaml
 ```
 
 ### Real Use Case Example: Water Underfloor Heating with NSPanel

docs/customization.md

@@ -90,14 +90,15 @@ packages:
   remote_package:
     url: https://github.com/Blackymas/NSPanel_HA_Blueprint
     ref: main
+    refresh: 300s
     files:
       - nspanel_esphome.yaml # Basic package
       # Optional advanced and add-on configurations
       # - esphome/nspanel_esphome_advanced.yaml
-      # - nspanel_esphome_addon_climate_cool.yaml
+      # - esphome/nspanel_esphome_addon_bluetooth_proxy.yaml
-      - nspanel_esphome_addon_climate_heat.yaml
+      # - esphome/nspanel_esphome_addon_climate_cool.yaml
-      # - nspanel_esphome_addon_climate_dual.yaml
+      # - esphome/nspanel_esphome_addon_climate_heat.yaml
-    refresh: 300s
+      # - esphome/nspanel_esphome_addon_climate_dual.yaml
 ```
 
 ## Memory Management
@@ -572,84 +573,11 @@ esp32:
     type: esp-idf
 ```
 
-### Bluetooth proxy
+### Bluetooth Proxy
-<!-- markdownlint-disable MD028 -->
+Please refer to the "[Add-on: Bluetooth Proxy](addon_bluetooth_proxy.md)" guide.
-> [!IMPORTANT]
-> **Problem Overview:**
-> Enabling Bluetooth consumes a significant amount of your device's memory (RAM), leading to potential issues:
-> - **Device Crashes:** Adding extra features on top of Bluetooth may overload the memory capacity, causing crashes.
-> - **Unstable HTTPS Connections:** There may be difficulties establishing or maintaining secure internet connections.
-> - **Failed TFT Screen Updates:** Insufficient RAM can cause screen update processes (TFT flashing) to fail.
->
-> **Solution:**
-> **Freeing Up Memory:**
-> To prevent these problems, remove the Bluetooth components to free up memory:
-> 1. **Flash the Device:** Apply a fresh installation of the software without the Bluetooth features to increase available RAM.
-> 2. **During TFT Update:** Perform this step specifically when updating the TFT screen to ensure enough RAM is available for the process.
-
-> [!IMPORTANT]
-> **Framework Recommendation:**
-> Utilize the [ESP32 Platform](#framework-esp-idf) with the `esp-idf` framework for optimal performance, especially when the Bluetooth feature is enabled.
-> The `arduino` framework is not recommended as it significantly increases memory usage and reduces system stability with Bluetooth.
-
-> [!WARNING]
-> **Correct Component IDs:**
-> It's crucial to use specific IDs for Bluetooth components (`ble_proxy` and `ble_tracker`). These IDs allow the system to properly manage Bluetooth services,
-> stopping them temporarily during the TFT update to free up RAM, thus enhancing the update's success rate.
->
-> Even if using only the `bluetooth_proxy`, you must define `esp32_ble_tracker` with the specified ID as shown below.
-> This setup is necessary for system compatibility and does not affect the firmware size but ensures proper functionality.
-
-```yaml
-# Configuration for Bluetooth Proxy
-bluetooth_proxy:
-  id: ble_proxy
-
-# Configuration for the BLE Tracker (required as part of the Bluetooth Proxy)
-esp32_ble_tracker:
-  id: ble_tracker
-
-# Wi-Fi settings adjusted for Bluetooth compatibility on ESP32
-wifi:
-  power_save_mode: LIGHT  # Required for Bluetooth
-```
 
 ### BLE Tracker
-<!-- markdownlint-disable MD028 -->
+Please refer to the "[Add-on: Bluetooth Proxy](addon_bluetooth_proxy.md)" guide.
-> [!IMPORTANT]
-> **Problem Overview:**
-> Enabling the BLE Tracker consumes a significant amount of your device's memory (RAM), which can lead to potential issues:
-> - **Device Crashes:** Running additional features along with the BLE Tracker may exceed the memory limits, causing the device to crash.
-> - **Unstable HTTPS Connections:** Secure internet connections might become unreliable.
-> - **Failed TFT Screen Updates:** A lack of sufficient RAM can disrupt the screen updating process (TFT flashing).
->
-> **Solution:**
-> **Freeing Up Memory:**
-> To mitigate these issues, simplify the device's configuration to increase available memory:
-> 1. **Flash the Device:** Reinstall the software with minimal features to maximize available RAM.
-> 2. **During TFT Update:** Specifically clear memory-consuming processes when updating the TFT screen to prevent update failures.
-
-> [!IMPORTANT]
-> **Framework Recommendation:**
-> For best performance, especially when using BLE features, it's advised to employ the [ESP32 Platform](#framework-esp-idf) with the `esp-idf` framework.
-> The `arduino` framework is less efficient as it consumes more memory and can compromise the stability of BLE functionalities.
-
-> [!WARNING]
-> **Component ID Usage:**
-> The `esp32_ble_tracker` must be configured with the specific ID `ble_tracker` to correctly manage BLE operations.
-> This ID setup is critical for system performance and stability during intensive operations like TFT updates.
->
-> Defining the `esp32_ble_tracker` with `ble_tracker` as the ID does not increase the firmware's size but is vital for operational success and system compatibility.
-
-```yaml
-# Configuration for the BLE Tracker
-esp32_ble_tracker:
-  id: ble_tracker
-
-# Wi-Fi settings optimized for BLE functionality on ESP32
-wifi:
-  power_save_mode: LIGHT  # Required for Bluetooth
-```
 
 ### Logger via UART
 

docs/install.md

@@ -129,9 +129,10 @@ Follow these steps to add a new device in the ESPHome Dashboard:
          - nspanel_esphome.yaml # Basic package
          # Optional advanced and add-on configurations
          # - esphome/nspanel_esphome_advanced.yaml
-         # - nspanel_esphome_addon_climate_cool.yaml
+         # - esphome/nspanel_esphome_addon_bluetooth_proxy.yaml
-         # - nspanel_esphome_addon_climate_heat.yaml
+         # - esphome/nspanel_esphome_addon_climate_cool.yaml
-         # - nspanel_esphome_addon_climate_dual.yaml
+         - esphome/nspanel_esphome_addon_climate_heat.yaml
+         # - esphome/nspanel_esphome_addon_climate_dual.yaml
    ```
 
    ![YAML Code](pics/ha_esphome_dashboard_new_device_06.png)

esphome/nspanel_esphome_addon_bluetooth_proxy.yaml

@@ -0,0 +1,43 @@
+#####################################################################################################
+##### NSPANEL ESPHOME created by Blackymas - https://github.com/Blackymas/NSPanel_HA_Blueprint  #####
+##### ESPHome Add-on for Bluetooth proxy                                                        #####
+##### PLEASE only make changes if it is necessary and also the required knowledge is available. #####
+##### For normal use with the Blueprint, no changes are necessary.                              #####
+#####################################################################################################
+##### ATTENTION: This will add climate elements to the core system and requires the core part.  #####
+#####################################################################################################
+---
+
+bluetooth_proxy:
+  id: ble_proxy
+
+# Enable Bluetooth tracker
+esp32_ble_tracker:
+  id: ble_tracker
+
+esphome:
+  platformio_options:
+    build_flags:
+      - -D NSPANEL_HA_BLUEPRINT_ADDON_BLUETOOTH_PROXY
+
+script:
+  - id: !extend dump_config
+    then:
+      - lambda: |-
+          // Check if this is installed with Arduino
+          #ifdef USE_ARDUINO
+            #error "Invalid settings for add-on Bluetooth Proxy. Arduino framework is not supported when using Bluetooth in this project."
+          #endif
+          if (!id(is_uploading_tft)) {
+            static const char *const TAG = "nspanel_ha_blueprint";
+            ESP_LOGCONFIG(TAG, "Add-on Bluetooth Proxy:");
+            ESP_LOGCONFIG(TAG, "  Mode:        %s", ble_proxy->has_active() ? "Active" : "Passive");
+            ESP_LOGCONFIG(TAG, "  Connections: %i", int(ble_proxy->get_bluetooth_connections_limit() -
+                                                        ble_proxy->get_bluetooth_connections_free()));
+            ESP_LOGCONFIG(TAG, "  Limit:       %i", int(ble_proxy->get_bluetooth_connections_limit()));
+          }
+
+# Set Wi-Fi power save mode to "LIGHT" as required for Bluetooth on ESP32
+wifi:
+  power_save_mode: LIGHT
+...

esphome/nspanel_esphome_advanced.yaml

@@ -33,6 +33,7 @@ button:
       - script.execute: exit_reparse
 
 captive_portal:
+  id: ap_captive_portal
 
 script:
   - id: exit_reparse
@@ -76,9 +77,9 @@ sensor:
 
 text_sensor:
   ##### ESPhome version used to compile the app #####
-  - name: ESPhome Version
+  - name: ESPhome Compiler
     platform: version
-    disabled_by_default: false
+    disabled_by_default: true
     internal: false
     icon: mdi:tag-text-outline
 

esphome/nspanel_esphome_core.yaml

@@ -2274,6 +2274,9 @@ script:
             #ifdef NSPANEL_HA_BLUEPRINT_ADVANCED
             ESP_LOGCONFIG(TAG, "  - Advanced");
             #endif
+            #ifdef NSPANEL_HA_BLUEPRINT_ADDON_BLUETOOTH_PROXY
+            ESP_LOGCONFIG(TAG, "  - Bluetooth Proxy");
+            #endif
             #ifdef NSPANEL_HA_BLUEPRINT_ADDON_UPLOAD_TFT
             ESP_LOGCONFIG(TAG, "  - Upload TFT");
             #endif
@@ -2296,10 +2299,7 @@ script:
             ESP_LOGCONFIG(TAG, "  - Pre-built (Wall Display)");
             #endif
             #if defined(USE_BLUETOOTH_PROXY) || defined(USE_WEBSERVER) || defined(USE_CAPTIVE_PORTAL)
-            ESP_LOGCONFIG(TAG, "Non-standard components:");
+            ESP_LOGCONFIG(TAG, "Components:");
-            #ifdef USE_CAPTIVE_PORTAL
-            ESP_LOGCONFIG(TAG, "  - Captive portal");
-            #endif
             #ifdef USE_ESP32_BLE_SERVER
             ESP_LOGCONFIG(TAG, "  - BLE server");
             #endif
@@ -2309,6 +2309,9 @@ script:
             #ifdef USE_BLUETOOTH_PROXY
             ESP_LOGCONFIG(TAG, "  - Bluetooth proxy");
             #endif
+            #ifdef USE_CAPTIVE_PORTAL
+            ESP_LOGCONFIG(TAG, "  - Captive portal");
+            #endif
             #ifdef USE_IMPROV
             ESP_LOGCONFIG(TAG, "  - Improv (BLE)");
             #endif
@@ -2533,6 +2536,9 @@ script:
           disp1->set_component_font("home.wifi_icon", id(home_chip_font_id));
           disp1->set_component_font_color("home.chip_relay1", id(home_relay1_icon_color));
           disp1->set_component_font_color("home.chip_relay2", id(home_relay2_icon_color));
+          #if defined(USE_ESP32_BLE_SERVER) || defined(USE_ESP32_BLE_CLIENT) || defined(USE_BLUETOOTH_PROXY) || defined(USE_IMPROV)
+          disp1->set_component_text("home.bt_icon", "\uE0AE");
+          #endif
           boot_progress->execute(8);
       - wait_until:
           condition:

hmi/dev/nspanel_eu_code/boot.txt

@@ -96,8 +96,8 @@ Text tft_version
         Dragging           : 0
         Send Component ID  : on press and release
         Associated Keyboard: none
-        Text               : 4.3.4
+        Text               : 4.3.5.dev1
-        Max. Text Size     : 9
+        Max. Text Size     : 10
     
 Text esph_version
     Attributes

hmi/dev/nspanel_eu_code/home.txt

@@ -643,6 +643,23 @@ Text value03
         Text               : 
         Max. Text Size     : 30
     
+Text bt_icon
+    Attributes
+        ID                 : 48
+        Scope              : global
+        Dragging           : 0
+        Send Component ID  : on press and release
+        Associated Keyboard: none
+        Text               : 
+        Max. Text Size     : 5
+    
+    Events
+        Touch Press Event
+            settings_timer.en=1
+        
+        Touch Release Event
+            settings_timer.en=0
+        
 Picture weather
     Attributes
         ID               : 7

hmi/dev/nspanel_us_code/boot.txt

@@ -96,8 +96,8 @@ Text tft_version
         Dragging           : 0
         Send Component ID  : on press and release
         Associated Keyboard: none
-        Text               : 4.3.4
+        Text               : 4.3.5.dev1
-        Max. Text Size     : 9
+        Max. Text Size     : 10
     
     Events
         Touch Release Event

hmi/dev/nspanel_us_code/home.txt

@@ -643,6 +643,23 @@ Text value04
         Text               : 
         Max. Text Size     : 30
     
+Text bt_icon
+    Attributes
+        ID                 : 48
+        Scope              : global
+        Dragging           : 0
+        Send Component ID  : on press and release
+        Associated Keyboard: none
+        Text               : 
+        Max. Text Size     : 5
+    
+    Events
+        Touch Press Event
+            settings_timer.en=1
+        
+        Touch Release Event
+            settings_timer.en=0
+        
 Picture weather
     Attributes
         ID               : 7

hmi/dev/nspanel_us_land_code/boot.txt

@@ -96,8 +96,8 @@ Text tft_version
         Dragging           : 0
         Send Component ID  : on press and release
         Associated Keyboard: none
-        Text               : 4.3.4
+        Text               : 4.3.5.dev1
-        Max. Text Size     : 9
+        Max. Text Size     : 10
     
 Text esph_version
     Attributes

hmi/dev/nspanel_us_land_code/home.txt

@@ -643,6 +643,23 @@ Text value03
         Text               : 
         Max. Text Size     : 30
     
+Text bt_icon
+    Attributes
+        ID                 : 48
+        Scope              : global
+        Dragging           : 0
+        Send Component ID  : on press and release
+        Associated Keyboard: none
+        Text               : 
+        Max. Text Size     : 5
+    
+    Events
+        Touch Press Event
+            settings_timer.en=1
+        
+        Touch Release Event
+            settings_timer.en=0
+        
 Picture weather
     Attributes
         ID               : 7

prebuilt/nspanel_esphome_prebuilt.yaml

@@ -124,7 +124,6 @@ text:
         - lambda: |-
             ESP_LOGD("text.fw_url", "New Firmware URL set: %s", x.c_str());
 
-
 wifi:
   networks: !remove
   ap: {}