Merge dev into main for v1.5.3 release

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: DerekSeaman

ESPHome Devices/README.md

@@ -4,6 +4,30 @@ This directory contains the ESPHome YAML configuration files for the IRK Capture
 
 ## Files
 
+### irk-capture-device-remote.yaml
+
+Remote Device Configuration (Recommended)
+
+This is the simplest configuration option. It pulls both the YAML package and IRK Capture component directly from GitHub at build time. No need to download or copy any files to your Home Assistant filesystem.
+
+**Usage:**
+
+- Use this as a template for your own device configuration
+- Replace all substitution values with your device-specific settings
+- Tip: Create a dummy device in ESPHome Device Builder, grab the API/OTA keys, then use this YAML template
+
+**Required substitutions:**
+
+- `device_name` - Unique device name (lowercase, hyphens only)
+- `friendly_name` - Human-readable name shown in Home Assistant
+- `api_key` - ESPHome API encryption key
+- `ota_password` - OTA update password
+- `esp32_variant` - Your ESP32 variant (esp32, esp32c3, esp32c6, esp32s3, etc.)
+- `esp32_board` - Your board type (see ESPHome board list)
+- `ble_name` - BLE advertising name shown in Bluetooth settings
+
+---
+
 ### irk-capture-base.yaml
 
 Generic ESP32 IRK Capture Package
@@ -59,7 +83,7 @@ This is a single-file configuration that merges the base package and device sett
 
 Example Secrets File
 
-This is an example secrets file showing the required Wi-Fi credentials. ESPHome Device Builder typically manages this file automatically. Make sure these substituations are in the secrets file.
+This is an example secrets file showing the required Wi-Fi credentials. ESPHome Device Builder typically manages this file automatically. Make sure these substituations are in the secrets file. The ESPHome device builder secrets can be accessed directly via the UI.
 
 **Required secrets:**
 
@@ -71,19 +95,26 @@ This is an example secrets file showing the required Wi-Fi credentials. ESPHome
 
 ## Which Configuration Should I Use
 
-### Use the Package Approach (base + device) if
+### Use the Remote Configuration (Recommended) if
+
+- You want the simplest setup with no local file management
+- You want automatic updates when the component is updated on GitHub
+- You don't need to modify the base package
+- You're new to ESPHome
+
+### Use the Local Package Approach (base + device) if
 
 - You have multiple ESP32 devices running IRK Capture
 - You want to maintain consistency across devices
 - You prefer separation between base functionality and device settings
-- You're comfortable with the ESPHome package system
+- You need to customize the base package
 
 ### Use the Standalone Configuration (full) if
 
 - You have a single ESP32 device
 - You prefer everything in one file
 - You want simplicity over modularity
-- You're new to ESPHome packages
+- You want an offline copy of the YAML configuration. However, the IRK Capture component is still pulled from GitHub at build time.
 
 ---
 
@@ -97,12 +128,3 @@ When using the package approach, your ESPHome directory should look like this:
 │   └── irk-capture-base.yaml
 └── my-irk-capture.yaml (your device file)
 ```
-
-## Directory Structure for Standalone Approach
-
-When using the standalone approach:
-
-```text
-/config/esphome/
-└── irk-capture-full.yaml (renamed to your preference)
-```

ESPHome Devices/irk-capture-base.yaml

@@ -32,7 +32,7 @@ esphome:
   friendly_name: ${friendly_name}
   project:
     name: "derekseaman.irk-capture"
-    version: "1.5.2"
+    version: "1.5.3"
 
 # IMPORTANT: Do NOT include esp32_ble:, esp32_ble_tracker:, or bluetooth_proxy: here.
 # The irk_capture component fully initializes and manages NimBLE itself.

ESPHome Devices/irk-capture-device-remote.yaml

@@ -0,0 +1,15 @@
+---
+substitutions:
+  device_name: esphome-irk-capture
+  friendly_name: IRK Capture
+  api_key: "ZmFrZWFwaWtleWZha2VleGFtcGxlZmFrZWtleQ=="
+  ota_password: "ChangeMe!2025"
+  esp32_variant: esp32          # Any ESP32 variant (esp32, esp32c3, esp32c6, esp32s3, etc.)
+  esp32_board: featheresp32     # Set to your board ID (e.g., featheresp32, esp32dev)
+  ble_name: "IRK Capture"
+
+packages:
+  device:
+    url: https://github.com/DerekSeaman/irk-capture
+    ref: main
+    file: ESPHome Devices/irk-capture-base.yaml

ESPHome Devices/irk-capture-full.yaml

@@ -43,7 +43,7 @@ esphome:
   friendly_name: ${friendly_name}
   project:
     name: "derekseaman.irk-capture"
-    version: "1.5.2"
+    version: "1.5.3"
 
 # IMPORTANT: Do NOT include esp32_ble:, esp32_ble_tracker:, or bluetooth_proxy: here.
 # The irk_capture component fully initializes and manages NimBLE itself.

README.md

@@ -53,11 +53,37 @@ When your Apple or Android device pairs with the ESP32:
 
 ## Installation
 
-I cover two methods for deploying your ESPHome device. First, you can use an ESPHome package which has a device independent YAML configuration file, plus a tiny device-specific YAML file. Second, you can use a single standalone YAML file that has all of the configuration details. Both accomplish the same end result. Personally I use the package method, as I have various ESP32 device types.
+I cover three methods for deploying your ESPHome device:
+
+- **Option 1 - Remote (Recommended):** Pulls the YAML and IRK Capture components directly from GitHub. Simplest method with no local file downloads required. This is the recommended option, as it will always pull the latest version at build time.
+- **Option 2 - Local Package:** Uses a base YAML file plus a device-specific YAML file. Best for managing multiple ESP32 device types. Requires accessing the Home Assistant filesystem to manually copy files into the esphome directory tree.
+- **Option 3 - Local Standalone:** A single self-contained YAML file with all configuration details. Only pulls the IRK Capture component from GitHub at build time.
 
 If you use either the Seeed ESP32-C3 or Seeed ESP32-C6, I've built dedicated IRK capture YAML files. You can find those IRK YAML files in my repos: [ESPHome-Seeed-Xiao-ESP32-c3-Config](https://github.com/DerekSeaman/ESPHome-Seeed-Xiao-ESP32-c3-Config) and [ESPHome-Seeed-Xiao-ESP32-C6-Config](https://github.com/DerekSeaman/ESPHome-Seeed-Xiao-ESP32-C6-Config).
 
-### Using ESPHome Device Builder Packages (Option 1)
+### Using ESPHome Device Builder Package - Remote (Option 1)
+
+This is the simplest installation method. It pulls the component directly from GitHub without requiring any local file downloads.
+
+1. Create a new dummy device in ESPHome, and save the unique API and OTA keys.
+2. Delete all of the pre-populated YAML from the dummy device.
+3. **Create your device YAML** using [irk-capture-device-remote.yaml](ESPHome%20Devices/irk-capture-device-remote.yaml) as a template and replace the OTA and API keys with the ones ESPHome generated.
+   - Modify the YAML parameters `esp32_variant` and `esp32_board` as needed to match your ESP32 device and board type
+   - Change the `device_name` and `friendly_name` as desired.
+
+4. **Secrets File (managed by ESPHome device builder UI):**
+
+   ```yaml
+   wifi_ssid: "Your WiFi Network"
+   wifi_password: "your_wifi_password"
+   wifi_captive: "fallback_password"
+   ```
+
+5. **Flash to your ESP32:**
+   - In ESPHome, click "Install" and choose your connection method
+   - IMPORTANT: After the flashing is complete, either power cycle your ESP32 or do a 'Restart Device' from the ESPHome interface. This will randomize the BLE MAC address.
+
+### Using ESPHome Device Builder Package - Local (Option 2)
 
 1. **In the Home Assistant filesystem create the 'common' directory under esphome, if not already present:**
 
@@ -91,7 +117,7 @@ If you use either the Seeed ESP32-C3 or Seeed ESP32-C6, I've built dedicated IRK
      ble_name: "IRK Capture"                   # Change: BLE advertising name (max 12 characters, shown in Bluetooth settings)
    ```
 
-4. **Secrets File** (managed by ESPHome device builder):
+4. **Secrets File (managed by ESPHome device builder UI):**
    - Modify the Wi-Fi secrets as needed
 
    ```yaml
@@ -104,7 +130,7 @@ If you use either the Seeed ESP32-C3 or Seeed ESP32-C6, I've built dedicated IRK
    - In ESPHome Device Builder, click "Install" and choose your connection method
    - IMPORTANT: After the flashing is complete, either power cycle your ESP32 or do a 'Restart Device' from the ESPHome interface. This will randomize the BLE MAC address.
 
-### Using a Standalone ESPHome Device (Option 2)
+### Using a Standalone ESPHome Device - Local (Option 3)
 
 1. Create a new dummy device in ESPHome, and save the unique API and OTA keys.
 2. Delete all of the pre-populated YAML from the dummy device.
@@ -124,7 +150,7 @@ If you use either the Seeed ESP32-C3 or Seeed ESP32-C6, I've built dedicated IRK
      ble_name: "IRK Capture"                   # Change: BLE advertising name (max 12 characters, shown in Bluetooth settings)
    ```
 
-7. **Secrets File** (managed by ESPHome device builder):
+7. **Secrets File (managed by ESPHome device builder UI):**
    - Modify the Wi-Fi secrets as needed
 
    ```yaml

components/irk_capture/irk_capture.cpp

@@ -23,7 +23,7 @@ namespace esphome {
 namespace irk_capture {
 
 static const char* const TAG = "irk_capture";
-static constexpr char VERSION[] = "1.5.2";
+static constexpr char VERSION[] = "1.5.3";
 static constexpr char HEX[] = "0123456789abcdef";
 
 //======================== NAMING CONVENTIONS ========================