New Add-on: BLE Tracker

Solves #1946
Helps with #1983

.github/workflows/validate_esphome.yml

@@ -148,7 +148,30 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@main
 
-      - name: Advanced Firmware
+      - name: Build Advanced Firmware
+        uses: barndawgie/build-action@v1.9.0
+        with:
+          yaml_file: ${{ matrix.yaml_file }}
+
+  build_ble_tracker:
+    name: BLE Tracker
+    needs: build_cores
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - id: idf_v4
+            base: idf_v4
+            yaml_file: ".test/esphome_idf_ble_tracker.yaml"
+          - id: idf_v5
+            base: idf_v5
+            yaml_file: ".test/esphome_idf5_ble_tracker.yaml"
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@main
+
+      - name: Build BLE Tracker Firmware
         uses: barndawgie/build-action@v1.9.0
         with:
           yaml_file: ${{ matrix.yaml_file }}
@@ -171,7 +194,7 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@main
 
-      - name: Bluetooth Proxy Firmware
+      - name: Build Bluetooth Proxy Firmware
         uses: barndawgie/build-action@v1.9.0
         with:
           yaml_file: ${{ matrix.yaml_file }}
@@ -197,7 +220,7 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@main
 
-      - name: Climate Cool Firmware
+      - name: Build Climate Cool Firmware
         uses: barndawgie/build-action@v1.9.0
         with:
           yaml_file: ${{ matrix.yaml_file }}
@@ -223,7 +246,7 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@main
 
-      - name: Climate Heat Firmware
+      - name: Build Climate Heat Firmware
         uses: barndawgie/build-action@v1.9.0
         with:
           yaml_file: ${{ matrix.yaml_file }}
@@ -249,7 +272,7 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@main
 
-      - name: Climate Dial Firmware
+      - name: Build Climate Dial Firmware
         uses: barndawgie/build-action@v1.9.0
         with:
           yaml_file: ${{ matrix.yaml_file }}
@@ -274,7 +297,7 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@main
 
-      - name: Customizations Firmware
+      - name: Build Customizations Firmware
         uses: barndawgie/build-action@v1.9.0
         with:
           yaml_file: ${{ matrix.yaml_file }}
@@ -296,7 +319,7 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@main
 
-      - name: Customizations Firmware
+      - name: Build Customizations Firmware
         uses: barndawgie/build-action@v1.9.0
         with:
           yaml_file: ${{ matrix.yaml_file }}
@@ -309,7 +332,7 @@ jobs:
     steps:
       - uses: actions/checkout@main
 
-      - name: ESPHome Prebuilt Firmware
+      - name: Build ESPHome Prebuilt Firmware
         uses: barndawgie/build-action@v1.9.0
         with:
           yaml_file: prebuilt/nspanel_esphome_prebuilt.yaml
@@ -320,7 +343,7 @@ jobs:
           cp prebuilt/.esphome/build/nspanel/.pioenvs/nspanel/firmware.bin prebuilt/nspanel_esphome_prebuilt.bin || true
           cp prebuilt/.esphome/build/nspanel/.pioenvs/nspanel/firmware-factory.bin prebuilt/nspanel_esphome_prebuilt-factory.bin || true
 
-      - name: ESPHome Prebuilt Wall Display Firmware
+      - name: Build ESPHome Prebuilt Wall Display Firmware
         uses: barndawgie/build-action@v1.9.0
         with:
           yaml_file: prebuilt/wall_display.yaml

.test/esphome_idf5_ble_tracker.yaml

@@ -0,0 +1,17 @@
+---
+substitutions:
+  device_name: nspanel
+  wifi_ssid: "nspanel"
+  wifi_password: "NSPanel_HA_Blueprint"
+  nextion_update_url: "https://github.com/Blackymas/NSPanel_HA_Blueprint/dummy"
+
+packages:
+  basic_package: !include ../nspanel_esphome.yaml  # Core package
+  addon_ble_tracker: !include ../esphome/nspanel_esphome_addon_ble_tracker.yaml
+
+esp32:
+  framework:
+    type: esp-idf
+    version: 5.0.2
+    platform_version: 6.3.2
+...

.test/esphome_idf_ble_tracker.yaml

@@ -0,0 +1,11 @@
+---
+substitutions:
+  device_name: nspanel
+  wifi_ssid: "nspanel"
+  wifi_password: "NSPanel_HA_Blueprint"
+  nextion_update_url: "https://github.com/Blackymas/NSPanel_HA_Blueprint/dummy"
+
+packages:
+  basic_package: !include ../nspanel_esphome.yaml  # Core package
+  addon_ble_tracker: !include ../esphome/nspanel_esphome_addon_ble_tracker.yaml
+...

docs/addon_ble_tracker.md

@@ -0,0 +1,60 @@
+# Add-on: BLE Tracker
+
+## Description
+This add-on enables your NSPanel to use its internal Bluetooth module to track nearby Bluetooth Low Energy (BLE) devices using the [ESPHome BLE Tracker component](https://esphome.io/components/esp32_ble_tracker.html).
+
+> [!IMPORTANT]
+> Configuring the BLE Tracker on your NSPanel is crucial for enabling device discovery and presence detection functionalities efficiently. This component should be managed with careful consideration of ESP32's memory capabilities, especially when other Bluetooth components are used concurrently.
+
+## Prerequisites
+- The `esp-idf` framework is recommended for the [ESP32 Platform](customization.md#framework-esp-idf) to ensure optimal operation and compatibility when using BLE features. The `arduino` framework is not advised as it may increase memory usage and impact the performance negatively.
+
+> [!WARNING]
+> Using the `arduino` framework can lead to high memory consumption which might interfere with the stability of BLE operations on the NSPanel. It is crucial to use the `esp-idf` framework to avoid such issues.
+
+## Configuration Steps
+1. **Edit Your ESPHome YAML File**: Incorporate the BLE Tracker component into your NSPanel's configuration by adding the necessary entries under the `esp32_ble_tracker:` section as shown below:
+```yaml
+substitutions:
+  device_name: "YOUR_NSPANEL_NAME"        # Set your NSPanel's device name
+  friendly_name: "Your Friendly Name"     # Set a friendly display name
+  wifi_ssid: !secret wifi_ssid            # Your Wi-Fi SSID
+  wifi_password: !secret wifi_password    # Your Wi-Fi password
+
+# Optional configurations (uncomment if needed)
+## Add-on for specific tracked devices or automation triggers
+# sensor:
+#   - platform: ble_rssi
+#     mac_address: MAC_ADDRESS_OF_DEVICE
+#     name: "BLE Device RSSI"
+
+## If you wanna set non-standard parameters to your BLE tracker, just add like this:
+# esp32_ble_tracker:
+#   scan_parameters:
+#     interval: 1100ms
+#     window: 1100ms
+#     active: true
+
+# Package Configuration
+packages:
+  remote_package:
+    url: https://github.com/Blackymas/NSPanel_HA_Blueprint
+    ref: main
+    refresh: 300s
+    files:
+      - nspanel_esphome.yaml # Basic NSPanel package
+      # Optional packages for advanced features and other add-ons
+      - esphome/nspanel_esphome_addon_ble_tracker.yaml # BLE Tracker add-on package
+      # - 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
+```
+2. **Update Substitutions**: Customize `"YOUR_NSPANEL_NAME"` and `"Your Friendly Name"` to appropriate identifiers for your device and its Bluetooth functionality.
+3. **Save and Upload**: After making the necessary changes, save your configuration file and upload it to your NSPanel via the ESPHome dashboard.
+> [!NOTE]
+> The first time this component is enabled for an ESP32, the code partition needs to be resized.
+> Please flash the ESP32 via USB when adding this to your configuration. After that, you can use OTA updates again.
+
+
+This configuration allows your NSPanel to efficiently manage Bluetooth connections, acting as a proxy for various BLE operations.

docs/addon_bluetooth_proxy.md

@@ -1,50 +1,64 @@
 # Add-on: Bluetooth Proxy
 
 ## Description
-
+This add-on enables your NSPanel to function as a Bluetooth Low Energy (BLE) proxy utilizing its internal Bluetooth module
-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.
+> It is crucial to configure the Bluetooth Proxy using this add-on for optimal memory management, which involves releasing the Bluetooth stack prior to any TFT updates.
 
-## Installation
+### Prerequisites
-
+- Ensure the `esp-idf` framework is utilized for the [ESP32 Platform](customization.md#framework-esp-idf) when enabling Bluetooth features.
-To install, add the reference to `nspanel_esphome_addon_bluetooth_proxy` in your ESPHome settings under the `packages` section
+Avoid switching to the `arduino` framework as it significantly increases memory usage, potentially causing installation failures on your panel.
-following the `remote_package` entry, as illustrated below:
 
 > [!WARNING]
-> While the `esp-idf` framework is the default and recommended for the [ESP32 Platform](customization.md#framework-esp-idf) when Bluetooth features are enabled,
+> The `arduino` framework, while compatible, should not be used for Bluetooth-intensive applications on the NSPanel due to its higher memory consumption.
-> ensure it is not switched to the `arduino` framework. The `arduino` framework significantly increases memory usage, which may prevent installation on your panel.
 
+### Configuration Steps
+1. **Edit Your ESPHome YAML File**: Add the Bluetooth Proxy add-on to your configuration by including the `remote_package` entry under the `packages` section as illustrated below:
 ```yaml
 substitutions:
-  # Settings - Editable values
+  device_name: "YOUR_NSPANEL_NAME"          # Set your NSPanel's device name
-  device_name: "YOUR_NSPANEL_NAME"
+  friendly_name: "Your Friendly Name"       # Set a friendly display name
-  friendly_name: "Your panel's friendly name"
+  wifi_ssid: !secret wifi_ssid              # Your Wi-Fi SSID
-  wifi_ssid: !secret wifi_ssid
+  wifi_password: !secret wifi_password      # Your Wi-Fi password
-  wifi_password: !secret wifi_password
 
-  # Add-on configuration (if needed)
+# Optional configurations (uncomment if needed)
-  ## Add-on climate
+## Add-on for climate control
-  # heater_relay: "1"  # Possible values: "1" or "2"
+# heater_relay: "1"  # Options: "1" or "2"
 
-# Customization area
+# Begin Customization Section
-##### My customization - Start #####
+##### Customization - Start #####
-##### My customization - End #####
+## If you wanna set non-standard parameters to your Bluetooth proxy just add like this:
+# esp32_ble_tracker:
+#   scan_parameters:
+#     interval: 1100ms
+#     window: 1100ms
+#     active: true
+#
+# bluetooth_proxy:
+#   active: true
+##### Customization - End #####
 
-# Basic and optional configurations
+# Package Configuration
 packages:
   remote_package:
     url: https://github.com/Blackymas/NSPanel_HA_Blueprint
     ref: main
     refresh: 300s
     files:
-      - nspanel_esphome.yaml # Basic package
+      - nspanel_esphome.yaml # Basic NSPanel package
-      # Optional advanced and add-on configurations
+      # Optional packages for advanced features and other add-ons
-      # - esphome/nspanel_esphome_advanced.yaml
+      # - esphome/nspanel_esphome_addon_ble_tracker.yaml
-      - esphome/nspanel_esphome_addon_bluetooth_proxy.yaml
+      - esphome/nspanel_esphome_addon_bluetooth_proxy.yaml # Bluetooth Proxy add-on package
       # - esphome/nspanel_esphome_addon_climate_cool.yaml
       # - esphome/nspanel_esphome_addon_climate_heat.yaml
       # - esphome/nspanel_esphome_addon_climate_dual.yaml
 ```
+2. **Update Substitutions**: Customize `"YOUR_NSPANEL_NAME"` and `"Your Friendly Name"` to appropriate identifiers for your device and its Bluetooth functionality.
+3. **Save and Upload**: After making the necessary changes, save your configuration file and upload it to your NSPanel via the ESPHome dashboard.
+> [!NOTE]
+> The first time this component is enabled for an ESP32, the code partition needs to be resized.
+> Please flash the ESP32 via USB when adding this to your configuration. After that, you can use OTA updates again.
+
+This configuration allows your NSPanel to efficiently manage Bluetooth connections, acting as a proxy for various BLE operations.

docs/addon_climate.md

@@ -51,6 +51,7 @@ packages:
       - nspanel_esphome.yaml # Basic package
       # Optional advanced and add-on configurations
       # - esphome/nspanel_esphome_advanced.yaml
+      # - esphome/nspanel_esphome_addon_ble_tracker.yaml
       # - esphome/nspanel_esphome_addon_bluetooth_proxy.yaml
       # - esphome/nspanel_esphome_addon_climate_cool.yaml
       - esphome/nspanel_esphome_addon_climate_heat.yaml
@@ -122,6 +123,7 @@ packages:
       - nspanel_esphome.yaml # Basic package
       # Optional advanced and add-on configurations
       # - esphome/nspanel_esphome_advanced.yaml
+      # - esphome/nspanel_esphome_addon_ble_tracker.yaml
       # - esphome/nspanel_esphome_addon_bluetooth_proxy.yaml
       - esphome/nspanel_esphome_addon_climate_cool.yaml
       # - esphome/nspanel_esphome_addon_climate_heat.yaml
@@ -162,6 +164,7 @@ packages:
       - nspanel_esphome.yaml # Basic package
       # Optional advanced and add-on configurations
       # - esphome/nspanel_esphome_advanced.yaml
+      # - esphome/nspanel_esphome_addon_ble_tracker.yaml
       # - esphome/nspanel_esphome_addon_bluetooth_proxy.yaml
       # - esphome/nspanel_esphome_addon_climate_cool.yaml
       - esphome/nspanel_esphome_addon_climate_heat.yaml
@@ -206,6 +209,7 @@ packages:
       - nspanel_esphome.yaml # Basic package
       # Optional advanced and add-on configurations
       # - esphome/nspanel_esphome_advanced.yaml
+      # - esphome/nspanel_esphome_addon_ble_tracker.yaml
       # - esphome/nspanel_esphome_addon_bluetooth_proxy.yaml
       # - esphome/nspanel_esphome_addon_climate_cool.yaml
       # - esphome/nspanel_esphome_addon_climate_heat.yaml

docs/customization.md

@@ -95,6 +95,7 @@ packages:
       - nspanel_esphome.yaml # Basic package
       # Optional advanced and add-on configurations
       # - esphome/nspanel_esphome_advanced.yaml
+      # - esphome/nspanel_esphome_addon_ble_tracker.yaml
       # - esphome/nspanel_esphome_addon_bluetooth_proxy.yaml
       # - esphome/nspanel_esphome_addon_climate_cool.yaml
       # - esphome/nspanel_esphome_addon_climate_heat.yaml
@@ -577,7 +578,7 @@ esp32:
 Please refer to the "[Add-on: Bluetooth Proxy](addon_bluetooth_proxy.md)" guide.
 
 ### BLE Tracker
-Please refer to the "[Add-on: Bluetooth Proxy](addon_bluetooth_proxy.md)" guide.
+Please refer to the "[Add-on: BLE Tracker Proxy](addon_ble_tracker.md)" guide.
 
 ### Logger via UART
 

docs/install.md

@@ -129,6 +129,7 @@ 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
+         # - esphome/nspanel_esphome_addon_ble_tracker.yaml
          # - esphome/nspanel_esphome_addon_bluetooth_proxy.yaml
          # - esphome/nspanel_esphome_addon_climate_cool.yaml
          - esphome/nspanel_esphome_addon_climate_heat.yaml