Introducing "Add-on: Bluetooth Proxy"

Supports: - #1983 - #1946 - #1815
2024-04-18 18:34:49 +02:00
parent c9be4d2422
commit 544b2bc9cf
21 changed files with 198 additions and 113 deletions
--- a/docs/README.md
+++ b/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)
--- a/docs/addon_bluetooth_proxy.md
+++ b/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
+```
--- a/docs/addon_climate.md
+++ b/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
-      - nspanel_esphome_addon_climate_heat.yaml
-      # - nspanel_esphome_addon_climate_dual.yaml
-    refresh: 300s
+      # - 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
 ```

 ## 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
-      # - nspanel_esphome_addon_climate_heat.yaml
-      # - nspanel_esphome_addon_climate_dual.yaml
-    refresh: 300s
+      # - 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
 ```

 ### 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
-      - nspanel_esphome_addon_climate_heat.yaml
-      # - nspanel_esphome_addon_climate_dual.yaml
-    refresh: 300s
+      # - 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
 ```

+
 ### 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
-      # - nspanel_esphome_addon_climate_heat.yaml
-      - nspanel_esphome_addon_climate_dual.yaml
-    refresh: 300s
+      # - 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
 ```

 ### Real Use Case Example: Water Underfloor Heating with NSPanel
--- a/docs/customization.md
+++ b/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
-      - nspanel_esphome_addon_climate_heat.yaml
-      # - nspanel_esphome_addon_climate_dual.yaml
-    refresh: 300s
+      # - 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
 ```

 ## Memory Management
@@ -572,84 +573,11 @@ esp32:
    type: esp-idf
 ```

-### Bluetooth proxy
-<!-- markdownlint-disable MD028 -->
-> [!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
-```
+### Bluetooth Proxy
+Please refer to the "[Add-on: Bluetooth Proxy](addon_bluetooth_proxy.md)" guide.

 ### BLE Tracker
-<!-- markdownlint-disable MD028 -->
-> [!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
-```
+Please refer to the "[Add-on: Bluetooth Proxy](addon_bluetooth_proxy.md)" guide.

 ### Logger via UART

--- a/docs/install.md
+++ b/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
-         # - nspanel_esphome_addon_climate_heat.yaml
-         # - nspanel_esphome_addon_climate_dual.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
   ```

   ![YAML Code](pics/ha_esphome_dashboard_new_device_06.png)