bt-sensors-plugin-sk 1.3.3 → 1.3.4

package/AI-DEV.md

@@ -0,0 +1,784 @@
+# AI-Assisted Development Guide for Bluetooth Battery Sensors
+
+This guide documents the AI-assisted development process used to create Bluetooth battery sensor implementations for the SignalK bt-sensors-plugin-sk. Follow this process to add support for new Bluetooth battery devices.
+
+## Overview
+
+This plugin architecture allows adding new Bluetooth battery sensors by creating sensor class files that inherit from [`BTSensor.js`](BTSensor.js:1). Each sensor class handles device-specific Bluetooth communication and data parsing, then maps the data to SignalK paths.
+
+## Prerequisites
+
+Before starting, gather the following information about your Bluetooth battery:
+
+### 1. Device Documentation
+- Manufacturer's name and device model
+- Bluetooth specifications (BLE services, characteristics, UUIDs)
+- Data packet format and protocol documentation
+- Available metrics (voltage, current, SOC, temperature, etc.)
+
+### 2. Development Tools
+- Access to the physical device for testing
+- **Android device with Bluetooth debugging enabled** (CRITICAL - see section below)
+- Bluetooth scanning tools (`bluetoothctl`, nRF Connect app, etc.)
+- **Vendor's mobile app** for the battery (if available)
+- Sample data packets (advertising data, characteristic reads)
+
+### 3. Technical Details
+- Service UUIDs the device advertises
+- Characteristic UUIDs for reading data
+- Data encoding format (byte order, scaling factors, units)
+- Any CRC/checksum algorithms used
+- Whether device uses advertising data or GATT connection
+
+## Critical First Step: Capture Real Bluetooth Data
+
+### Using Android Bluetooth HCI Snoop Log (ESSENTIAL)
+
+**This is the most important step** - Before writing any code, you need to capture actual Bluetooth communication from the device. The most effective method is using Android's built-in Bluetooth debugging with the vendor's app.
+
+**Why this matters:**
+- Reveals the exact protocol the device uses
+- Shows actual commands and responses
+- Eliminates guesswork about byte layouts
+- Provides test data for validation
+
+**Step-by-step process:**
+
+1. **Enable Developer Options on Android:**
+   - Go to Settings → About Phone
+   - Tap "Build Number" 7 times
+   - Go back to Settings → Developer Options
+
+2. **Enable Bluetooth HCI Snoop Log:**
+   - In Developer Options, enable "Bluetooth HCI snoop log"
+   - This captures ALL Bluetooth traffic to a file
+
+3. **Use the Vendor's App:**
+   - Install the battery manufacturer's official app
+   - Connect to your battery
+   - Navigate through all screens showing battery data
+   - Trigger all functions (refresh, settings, etc.)
+   - Let it run for 30-60 seconds
+
+4. **Extract the Log File:**
+   ```bash
+   # Pull the Bluetooth log from Android device via ADB
+   adb pull /sdcard/Android/data/btsnoop_hci.log
+   
+   # Or from newer Android versions:
+   adb bugreport
+   # Then extract: FS/data/misc/bluetooth/logs/btsnoop_hci.log
+   ```
+
+5. **Analyze with Wireshark:**
+   - Open btsnoop_hci.log in Wireshark
+   - Filter for your device's MAC address: `bluetooth.addr == XX:XX:XX:XX:XX:XX`
+   - Look for:
+     - **ATT (Attribute Protocol) packets** - GATT read/write/notify operations
+     - **Advertising packets** - Manufacturer/Service data broadcasts
+     - **Command/response patterns** - Protocol structure
+
+**What to look for in Wireshark:**
+
+For GATT devices:
+- `ATT Write Request` - Commands sent by app to device
+- `ATT Handle Value Notification` - Data pushed from device
+- `ATT Read Response` - Data read from characteristics
+- Note the characteristic handles (0x00XX) and UUIDs
+
+For Advertising devices:
+- `Advertising Data` packets
+- Manufacturer Data field with ID and hex bytes
+- Service Data field with UUID and hex bytes
+
+**Real Example - HSC14F Battery:**
+
+```
+Wireshark Filter: bluetooth.addr == AA:BB:CC:DD:EE:FF
+
+Frame 142: ATT Write Request, Handle: 0x000e
+Data: A5 5A 00 FF 01 03
+(This is the "read battery info" command)
+
+Frame 145: ATT Handle Value Notification, Handle: 0x000b
+Data: A5 5A 00 01 01 0C E4 10 0E 55 19 [...]
+(Device's response with battery data)
+
+Vendor app displayed at this moment:
+- Voltage: 13.2V (bytes 6-7: 0x0CE4 = 3300 * 0.01 / 2 cells)
+- Current: 10.5A (bytes 8-9: 0x100E = 4110 * 0.01 / 4)
+- SOC: 85% (byte 10: 0x55 = 85)
+```
+
+**Prompt to AI after capturing:**
+
+```
+I've captured Bluetooth HCI snoop log from my [DEVICE_NAME] using the vendor's
+Android app. Here's what Wireshark shows:
+
+[FOR GATT DEVICES:]
+Service UUID: 0000ffe0-0000-1000-8000-00805f9b34fb
+Characteristic UUID: 0000ffe1-0000-1000-8000-00805f9b34fb
+
+Write Request to device:
+A5 5A 00 FF 01 03
+
+Notification Response:
+A5 5A 00 01 01 0C E4 10 0E 55 19 00 01 02 [...]
+
+When this packet arrived, the vendor app displayed:
+- Voltage: 13.2V
+- Current: 10.5A
+- SOC: 85%
+- Temperature: 25°C
+
+Please help me:
+1. Understand the protocol structure
+2. Map hex bytes to displayed values
+3. Determine byte positions, endianness, and scaling
+4. Create the sensor class implementation
+
+[FOR ADVERTISING DEVICES:]
+Advertising Data shows:
+Manufacturer Data (0x1234): AB CD 0C E4 10 0E 55 01 F4
+
+When this was captured, device display showed:
+- Voltage: 13.2V
+- Current: 10.5A
+- SOC: 85%
+
+Please decode this packet format.
+```
+
+### Alternative: Using nRF Connect (If No Vendor App Available)
+
+If there's no vendor app:
+
+1. **Install nRF Connect** (Nordic Semiconductor app for Android/iOS)
+2. **Scan and connect** to your battery
+3. **Explore all services and characteristics**
+4. **Read values** from readable characteristics
+5. **Enable notifications** on notifiable characteristics
+6. **Screenshot hex values** and note what they represent
+
+**Prompt to AI:**
+```
+Using nRF Connect, I found on [DEVICE_NAME]:
+
+Service: 0000ffe0-0000-1000-8000-00805f9b34fb
+Characteristics:
+- 0000ffe1-... (Read, Notify)
+  Current value: A5 5A 00 01 01 0C E4 10 0E 55
+
+Battery label shows: 13.2V, 10.5A, 85%
+
+How do I decode this to get those values?
+```
+
+## Step-by-Step AI-Assisted Development Process
+
+### Step 1: Analyze Existing Similar Implementations
+
+**Prompt to AI:**
+```
+I want to add support for a [DEVICE_NAME] Bluetooth battery to the bt-sensors-plugin-sk.
+Please review the sensor_classes directory and identify existing battery sensor 
+implementations that are similar. Show me the key patterns used for:
+- Device identification (matchManufacturerData or identify methods)
+- Bluetooth service/characteristic UUIDs
+- Data packet parsing
+- SignalK path mapping
+- GATT vs advertising data approaches
+
+Focus on these example files:
+- sensor_classes/VictronSmartLithium.js
+- sensor_classes/JBDBMS.js
+- sensor_classes/RenogyBattery.js
+```
+
+**What AI should examine:**
+- [`VictronSmartLithium.js`](sensor_classes/VictronSmartLithium.js:1) - Advertising data approach with encryption
+- [`JBDBMS.js`](sensor_classes/JBDBMS.js:1) - GATT connection with command/response protocol
+- [`RenogyBattery.js`](sensor_classes/RenogyBattery.js:1) - GATT with Modbus-style registers
+- [`BTSensor.js`](BTSensor.js:1) - Base class showing required methods
+
+### Step 2: Determine Communication Method
+
+**Prompt to AI:**
+```
+My device [DOES/DOES NOT] require a GATT connection. It provides data via:
+- [X] Advertising packets (manufacturer data or service data)
+- [ ] GATT characteristic notifications
+- [ ] GATT characteristic reads (polling)
+
+Here's the Bluetooth scan data I captured:
+[Paste output from bluetoothctl or nRF Connect]
+
+Which approach should I use: advertising-based like VictronSmartLithium, 
+or GATT-based like JBDBMS or RenogyBattery?
+```
+
+### Step 3: Create Initial Sensor Class File
+
+**Prompt to AI:**
+```
+Create a new sensor class file for [DEVICE_NAME] based on the following specifications:
+
+Device: [DEVICE_NAME]
+Manufacturer: [MANUFACTURER]
+Communication method: [Advertising/GATT]
+
+[IF ADVERTISING:]
+Manufacturer ID: [0xXXXX]
+The device advertises data in manufacturer data with this format:
+[Describe byte layout]
+
+[IF GATT:]
+Service UUID: [UUID]
+Characteristics:
+- Read: [UUID] - [description]
+- Notify: [UUID] - [description]
+- Write: [UUID] - [description if applicable]
+
+The device provides these metrics:
+- Voltage (range: X-Y V)
+- Current (range: -X to +Y A)
+- State of Charge (0-100%)
+- Temperature (range: X-Y °C)
+- [Other metrics...]
+
+Please create sensor_classes/[DeviceName].js following the pattern used in
+[VictronSmartLithium.js/JBDBMS.js/RenogyBattery.js], including:
+1. Class definition extending BTSensor
+2. Static Domain property set to BTSensor.SensorDomains.electrical
+3. Static identify() method for device identification
+4. Static ImageFile property
+5. initSchema() method with metadata
+6. Data parsing methods
+7. SignalK path defaults
+```
+
+**Expected AI actions:**
+- Creates new file in `sensor_classes/`
+- Implements basic class structure
+- Sets up UUID constants (if GATT)
+- Defines device identification logic
+- Creates default SignalK path mappings
+
+### Step 4: Implement Device Identification
+
+**For Advertising-based Devices:**
+
+**Prompt to AI:**
+```
+I have Bluetooth advertising data from [DEVICE_NAME]:
+Manufacturer Data: [paste hex dump, e.g., "AB CD 01 02 03 04..."]
+or
+Service Data (UUID [UUID]): [paste hex dump]
+
+The manufacturer ID should be: [0xXXXX]
+
+Please implement the static identify(device) method to correctly identify this device.
+Use the pattern from VictronSensor.js which checks manufacturer ID and additional
+identifying bytes if needed.
+```
+
+**For GATT Devices:**
+
+**Prompt to AI:**
+```
+My GATT device advertises the service UUID: [UUID]
+
+Please implement the static identify(device) method that:
+1. Checks if the device advertises this service UUID
+2. Returns the class if matched, null otherwise
+
+Use this pattern:
+static async identify(device){
+    const serviceUUIDs = await BTSensor.getDeviceProp(device, 'UUIDs')
+    if (serviceUUIDs && serviceUUIDs.includes('[UUID]'))
+        return this
+    return null
+}
+```
+
+### Step 5: Implement Data Parsing (Advertising Method)
+
+**Prompt to AI:**
+```
+The [DEVICE_NAME] sends data in manufacturer data packets with this format:
+
+Byte 0-1: Manufacturer ID (0xXXXX, little-endian)
+Byte 2-3: Voltage (0.01V units, unsigned 16-bit LE)
+Byte 4-5: Current (0.01A units, signed 16-bit LE, positive=charging)
+Byte 6: State of Charge (%, unsigned 8-bit, 0-100)
+Byte 7-8: Temperature (0.1°C units, signed 16-bit LE)
+[Continue for all fields...]
+
+Sample packet: [provide actual hex dump, e.g., "CD AB 10 0D E8 03 64 5A 01"]
+
+Please implement the propertiesChanged() method that:
+1. Calls super.propertiesChanged(props) first
+2. Extracts manufacturer data
+3. Parses the buffer using the read functions defined in initSchema()
+4. Calls emitValuesFrom(buffer) to emit all values
+
+Also update initSchema() with the correct read functions for each path using:
+.read = (buffer) => { return buffer.readUInt16LE(2) / 100 } // for voltage at byte 2
+```
+
+**Common Buffer Reading Methods:**
+- `buffer.readUInt16LE(offset)` - Unsigned 16-bit little-endian
+- `buffer.readInt16LE(offset)` - Signed 16-bit little-endian
+- `buffer.readUInt8(offset)` - Unsigned 8-bit
+- `buffer.readInt8(offset)` - Signed 8-bit
+- `buffer.readUInt32LE(offset)` - Unsigned 32-bit little-endian
+- Use `BE` suffix for big-endian variants
+
+### Step 6: Implement GATT Communication (GATT Method)
+
+**Prompt to AI:**
+```
+My GATT device uses this protocol:
+Service UUID: [UUID]
+Notify Characteristic: [UUID] - Sends battery data
+Write Characteristic: [UUID] - Accepts commands
+Read Characteristic: [UUID] - Returns data on request
+
+Command format: [describe, e.g., "0xDD 0xA5 CMD 0x00 0xFF CHECKSUM 0x77"]
+Response format: [describe structure]
+
+Please implement:
+1. initSchema() that connects to the device and sets up characteristics
+2. initGATTConnection() override if needed
+3. initGATTNotifications() or initGATTInterval() depending on polling vs notifications
+4. emitGATT() method that requests data and parses responses
+5. Helper methods like sendReadFunctionRequest() if needed
+
+Follow the pattern from JBDBMS.js which uses command/response protocol.
+```
+
+**For devices that need polling:**
+
+**Prompt to AI:**
+```
+Add GATT parameters to support polling:
+- In initSchema(), call this.addGATTParameter() for pollFreq
+- Set hasGATT() to return true
+- Set usingGATT() to return this.useGATT
+- Implement initGATTInterval() to poll at specified frequency
+- Implement emitGATT() to read and emit all values
+```
+
+### Step 7: Define SignalK Path Mappings
+
+**Prompt to AI:**
+```
+Please implement proper SignalK path defaults in initSchema() for this battery.
+Map the parsed values to these SignalK paths:
+
+Use addDefaultPath() for standard paths:
+- Voltage → electrical.batteries.voltage
+- Current → electrical.batteries.current  
+- SOC → electrical.batteries.capacity.stateOfCharge
+- Temperature → electrical.batteries.temperature
+- Remaining capacity → electrical.batteries.capacity.remaining
+- Cycles → electrical.batteries.cycles
+
+Use addMetadatum() for device-specific paths:
+- Cell voltages → electrical.batteries.{batteryID}.cell[N].voltage
+- Protection status → electrical.batteries.{batteryID}.protectionStatus
+- [Other custom metrics]
+
+Add parameter for battery ID:
+this.addDefaultParam("batteryID").default="house"
+
+Ensure all paths use proper template variables like {batteryID} where appropriate.
+```
+
+**SignalK Path Reference:**
+```
+electrical.batteries.{id}.voltage          // V
+electrical.batteries.{id}.current          // A (positive = charging)
+electrical.batteries.{id}.temperature      // K (Kelvin)
+electrical.batteries.{id}.capacity.stateOfCharge      // ratio (0-1)
+electrical.batteries.{id}.capacity.remaining          // C (coulombs/amp-hours)
+electrical.batteries.{id}.capacity.actual             // C (total capacity)
+electrical.batteries.{id}.cycles                      // count
+electrical.batteries.{id}.lifetimeDischarge           // C
+electrical.batteries.{id}.lifetimeRecharge            // C
+```
+
+### Step 8: Add Device Image and Description
+
+**Prompt to AI:**
+```
+I have an image for [DEVICE_NAME] saved as: public/images/[DeviceName].webp
+
+Please update the sensor class to include:
+1. static ImageFile = "[DeviceName].webp"
+2. static Description = "[Brief description of device]"
+3. static Manufacturer = "[Manufacturer Name]"
+
+Follow the pattern from other sensor classes.
+```
+
+### Step 9: Register the Sensor Class
+
+**Prompt to AI:**
+```
+Please help me register the new [DeviceName] sensor class in the plugin:
+1. Check classLoader.js to see the pattern for importing and registering classes
+2. Add the appropriate require() statement
+3. Add it to the class map
+4. Ensure it's in the correct order for identification
+
+Show me the exact changes needed to classLoader.js.
+```
+
+### Step 10: Test with Real Device
+
+**Prompt to AI:**
+```
+I'm testing with the actual [DEVICE_NAME] device. Here's what I'm seeing:
+
+Debug output:
+[Paste logs, errors, or unexpected behavior]
+
+Expected values from device display:
+- Voltage: [X]V
+- Current: [X]A  
+- SOC: [X]%
+- Temperature: [X]°C
+
+Actual parsed values:
+- Voltage: [Y]V
+- Current: [Y]A
+- SOC: [Y]%  
+- Temperature: [Y]°C
+
+Please help debug:
+1. Are the byte offsets correct?
+2. Is the byte order (endianness) correct?
+3. Are scaling factors correct?
+4. Are signed vs unsigned interpretations correct?
+```
+
+**Common Issues & Fixes:**
+- **Values 256x too large/small**: Wrong endianness (LE vs BE)
+- **Negative values where shouldn't be**: Using UInt instead of Int
+- **Values in wrong range**: Incorrect scaling factor
+- **Values always same**: Wrong byte offset or not updating
+
+### Step 11: Add Error Handling
+
+**Prompt to AI:**
+```
+Please add robust error handling to the [DeviceName] class for:
+
+For advertising-based devices:
+1. Check manufacturer data exists before parsing
+2. Validate buffer length before reading
+3. Handle out-of-range values gracefully
+4. Add try-catch in propertiesChanged()
+
+For GATT devices:
+1. Add timeouts for response waits
+2. Validate checksums if protocol uses them
+3. Handle disconnections gracefully
+4. Add retry logic for failed reads
+5. Implement deactivateGATT() cleanup
+
+Follow the error handling patterns in JBDBMS.js and BTSensor.js.
+```
+
+### Step 12: Documentation and Testing
+
+**Prompt to AI:**
+```
+Please add comprehensive documentation to the [DeviceName] class:
+
+1. Add JSDoc comments for all methods explaining:
+   - Parameters and return values
+   - Protocol details
+   - Data format specifics
+
+2. Add a comment block at the top documenting the data format:
+   /*
+   [DeviceName] Data Format
+   Byte X-Y: [Field] (units, format, range)
+   ...
+   */
+
+3. Create a _test() usage example showing how to test parsing with sample data
+
+4. Document any device-specific quirks or limitations
+```
+
+## Complete Example Workflow
+
+Here's a condensed example conversation for adding an "AcmeBattery BT-100":
+
+```
+User: I want to add support for the Acme BT-100 Bluetooth battery. It uses 
+advertising data with manufacturer ID 0x1234. Here's a sample packet:
+34 12 10 0D E8 03 64 5A 01
+
+AI: [Analyzes structure, creates initial class file]
+
+User: The packet format is:
+Bytes 0-1: Manufacturer ID (0x1234)
+Bytes 2-3: Voltage in 0.01V (little-endian, so 0x0D10 = 3344 = 33.44V)
+Bytes 4-5: Current in 0.01A (signed LE, 0x03E8 = 1000 = 10.00A)
+Byte 6: SOC (0x64 = 100 = 100%)
+Bytes 7-8: Temp in 0.1°C (signed LE, 0x015A = 346 = 34.6°C)
+
+AI: [Implements propertiesChanged() and read functions with correct parsing]
+
+User: Testing shows voltage correct but current is backwards (negative when charging)
+
+AI: [Fixes current sign interpretation]
+
+User: Perfect! Now add the image reference and register it.
+
+AI: [Updates ImageFile, modifies classLoader.js]
+```
+
+## Bluetooth Scanning Commands
+
+### Using bluetoothctl
+```bash
+# Start scanning
+bluetoothctl
+scan on
+
+# Wait for device to appear, then:
+info [MAC_ADDRESS]
+
+# Look for:
+# - ManufacturerData: key [ID] value [hex bytes]
+# - ServiceData: key [UUID] value [hex bytes]
+# - UUIDs: [list of service UUIDs]
+```
+
+### Using hcitool/hcidump
+```bash
+# Terminal 1: Start scan
+sudo hcitool lescan
+
+# Terminal 2: Capture advertising data
+sudo hcidump --raw
+```
+
+## Testing Your Implementation
+
+### Static Testing (No Device Required)
+```javascript
+const MyBattery = require('./sensor_classes/MyBattery.js')
+
+// Test with sample packet
+const sampleData = "34 12 10 0D E8 03 64 5A 01"
+MyBattery._test(sampleData)
+
+// Should output:
+// voltage=33.44
+// current=10.00
+// SOC=1.00
+// temperature=307.75
+```
+
+### Live Testing Checklist
+- [ ] Device correctly identified during scan
+- [ ] Connection establishes (if GATT)
+- [ ] All metrics parse with correct values
+- [ ] **Values match vendor app exactly** (critical!)
+- [ ] **Parsed values match HCI snoop captured data**
+- [ ] Values also match device's physical display (if available)
+- [ ] Reconnection works after going out of range
+- [ ] SignalK paths appear in data browser
+- [ ] Units are correct (Kelvin for temp, etc.)
+- [ ] No memory leaks over extended operation
+
+### Validating Against Captured HCI Data
+
+After implementing your sensor class, verify it parses the same packets you captured:
+
+**Extract specific packets from your capture:**
+```bash
+# Use tshark to extract hex data from your captured log
+tshark -r btsnoop_hci.log -Y "btatt && bluetooth.addr == XX:XX:XX:XX:XX:XX" \
+  -T fields -e btatt.value
+```
+
+**Test with captured data:**
+```javascript
+const MyBattery = require('./sensor_classes/MyBattery.js')
+
+// Use actual packet from your HCI capture
+const capturedPacket = "A5 5A 00 01 01 0C E4 10 0E 55 19 00 01 02"
+MyBattery._test(capturedPacket)
+
+// Output should match what vendor app showed:
+// voltage=13.2
+// current=10.5
+// SOC=0.85
+// temperature=298.15
+```
+
+**Prompt to AI if values don't match:**
+```
+My implementation parses this HCI-captured packet:
+A5 5A 00 01 01 0C E4 10 0E 55
+
+And produces:
+- voltage=33.0V (WRONG)
+- current=10.5A (CORRECT)
+
+But the vendor app showed voltage=13.2V when this packet was sent.
+
+Bytes 6-7 are: 0C E4 (hex)
+0x0CE4 = 3300 decimal
+
+The device is a 2-cell battery. Help me debug the voltage parsing.
+```
+
+**AI will likely identify:** You need to divide by number of cells, or the scaling factor is different, or byte order is reversed.
+
+## Common Data Parsing Patterns
+
+### Temperature Conversions
+```javascript
+// Celsius to Kelvin
+.read = (buffer) => { return buffer.readInt16LE(offset) / 10 + 273.15 }
+
+// Handle "not available" values  
+.read = (buffer) => { 
+    const val = buffer.readInt8(offset)
+    return val === 0x7F ? NaN : val + 273.15 
+}
+```
+
+### Current Direction
+```javascript
+// Positive = charging, negative = discharging
+.read = (buffer) => { return buffer.readInt16LE(offset) / 100 }
+```
+
+### State of Charge
+```javascript
+// Percent to ratio (0-1)
+.read = (buffer) => { return buffer.readUInt8(offset) / 100 }
+```
+
+### Bit Flags
+```javascript
+.read = (buffer) => {
+    const byte = buffer.readUInt8(offset)
+    return {
+        charging: (byte & 0x01) !== 0,
+        discharging: (byte & 0x02) !== 0,
+        balancing: (byte & 0x04) !== 0,
+        fault: (byte & 0x80) !== 0
+    }
+}
+```
+
+## Advanced Topics
+
+### Encryption
+Some devices (like Victron) encrypt advertising data. If your device uses encryption:
+
+**Prompt to AI:**
+```
+My device uses AES-CTR encryption with a 128-bit key. The encrypted data starts
+at byte 8 of the manufacturer data. The nonce/counter is in bytes 0-7.
+
+Please implement:
+1. A decrypt() method using Node.js crypto module
+2. Update propertiesChanged() to decrypt before parsing
+3. Add encryptionKey parameter to configuration
+
+Follow the pattern from VictronSensor.js.
+```
+
+### Multiple Cell Voltages
+For batteries with multiple cells:
+
+**Prompt to AI:**
+```
+The battery has [N] cells. Cell voltages are packed into the data:
+- Starting at byte X
+- Each cell is 2 bytes, little-endian
+- Values are in millivolts (1mV = 0.001V)
+
+Please:
+1. Add a loop in initSchema() to create cell voltage paths dynamically
+2. Create read functions for each cell
+3. Use template {batteryID} in paths like:
+   electrical.batteries.{batteryID}.cell[N].voltage
+```
+
+### Checksum Validation
+For protocols with checksums:
+
+**Prompt to AI:**
+```
+The protocol includes a checksum at bytes [X-Y]:
+- Type: [CRC-16/sum/XOR]
+- Calculated over bytes [A-B]
+- [Describe algorithm]
+
+Please implement a validateChecksum() function and call it before parsing data.
+Reject invalid packets with this.debug() message.
+
+See JBDBMS.js checkSum() function as reference.
+```
+
+## Troubleshooting Guide
+
+| Problem | Likely Cause | Solution Prompt |
+|---------|-------------|-----------------|
+| Device not appearing in scan | UUID filter, not advertising | "Check if identify() method is correct. Show me how to debug device detection." |
+| Values are NaN | Wrong byte offsets, invalid data | "Values showing NaN. Help me verify byte offsets and add validation." |
+| Connection fails | Wrong service UUID, device busy | "GATT connection failing with error: [error]. What should I check?" |
+| Values incorrect magnitude | Wrong scaling factor | "Values are 100x too large. Check my scaling factors." |
+| Negative when should be positive | Unsigned vs signed | "Current showing negative when charging. Fix my Int/UInt usage." |
+| Updates stop after a while | Memory leak, no cleanup | "Device stops updating after 5 minutes. Check my cleanup in stopListening()." |
+
+## Resources
+
+- [SignalK Specification](http://signalk.org/specification/latest/doc/vesselsBranch.html)
+- [Bluetooth GATT Specifications](https://www.bluetooth.com/specifications/specs/)
+- [Node.js Buffer Documentation](https://nodejs.org/api/buffer.html)
+- Plugin README: [`README.md`](README.md:1)
+- Development Guide: [`sensor_classes/DEVELOPMENT.md`](sensor_classes/DEVELOPMENT.md:1)
+- Base Sensor Class: [`BTSensor.js`](BTSensor.js:1)
+
+## Summary
+
+The AI-assisted development process follows this pattern:
+
+1. **Research** - Analyze similar implementations
+2. **Identify** - Determine communication method (advertising vs GATT)
+3. **Create** - Generate skeleton sensor class
+4. **Implement** - Add device identification logic
+5. **Parse** - Implement data parsing with correct byte operations
+6. **Map** - Create SignalK path mappings with defaults
+7. **Register** - Add to classLoader.js
+8. **Test** - Verify with real hardware
+9. **Debug** - Fix scaling, offsets, byte order issues
+10. **Refine** - Add error handling and documentation
+11. **Complete** - Test thoroughly and contribute back
+
+By providing clear, specific prompts with actual device data (hex dumps, protocol specs, test results), AI can effectively assist in creating robust, maintainable sensor implementations that follow the established patterns in this codebase.
+
+## Key Success Factors
+
+1. **Have real device data** - Actual advertising packets or GATT responses
+2. **Know the protocol** - Byte layout, scaling factors, data types
+3. **Test iteratively** - Make small changes, test each one
+4. **Compare values** - Match against device's own display
+5. **Use existing patterns** - Don't reinvent, follow proven implementations
+6. **Document thoroughly** - Help the next developer
+
+Good luck adding your Bluetooth battery! 🔋⚡

package/README.md

@@ -2,11 +2,17 @@
 
 ## WHAT'S NEW  
 
+
+# Version 1.3.4 
+
+- Inactivity timeout configuration option. If > 0 and there's been no contact with any Bluetooth device, the plugin will power cycle the bluetooth adapter.
+- Exclude non-active devices that are Out of Range from Last Error and Status on SignalK Dashboard
+ 
 # Version 1.3.3 
 
 - Support for additional Xiaomi environmental sensors
 - Out Of Range device automatic retry
-- Pairing guide
+- [Device pairing guide](./pairing.md)
 
 # Version 1.3.2-1
 

package/index.js

@@ -178,6 +178,11 @@ module.exports =   function (app) {
 				minimum: 10,
 				maximum: 3600 
 			},
+			inactivityTimeout: {title: "Inactivity timeout in seconds -- set to 0 to disable. (If no contact with any sensors for this period, the plugin will attempt to power cycle the Bluetooth adapter.)", 
+				type: "integer", default: 0,
+				minimum: 0,
+				maximum: 3600 
+			},
 			discoveryInterval: {title: "Scan for new devices interval (in seconds-- 0 for no new device scanning)", 
 				type: "integer", 
 				default: 10,
@@ -323,7 +328,8 @@ module.exports =   function (app) {
 						transport: options.transport,
 						duplicateData: options.duplicateData,
 						discoveryTimeout: options.discoveryTimeout,
-						discoveryInterval: options.discoveryInterval
+						discoveryInterval: options.discoveryInterval,
+						inactivityTimeout: options.inactivityTimeout
 					}
 					}
 				);
@@ -498,6 +504,10 @@ module.exports =   function (app) {
 						s.listen()
 						if (config.active)
 							await s.activate(config, plugin)
+						else {
+							s.unsetError()
+							s.setState("DORMANT")
+						}
 						removeSensorFromList(s)
 						addSensorToList(s)
 					})
@@ -510,7 +520,8 @@ module.exports =   function (app) {
 					{
 						s.setError(errorTxt)
 					} else {
-						plugin.setError(errorTxt)
+						if (config.active)
+							plugin.setError(errorTxt)
 					}
 					plugin.debug(e)
 
@@ -753,15 +764,27 @@ module.exports =   function (app) {
 		}
 		const minTimeout=Math.min(...deviceConfigs.map((dc)=>dc?.discoveryTimeout??options.discoveryTimeout))
 		const intervalTimeout = ((minTimeout==Infinity)?(options?.discoveryTimeout??plugin.schema.properties.discoveryTimeout.default):minTimeout)*1000
-		deviceHealthID = setInterval( ()=> {
+
+		deviceHealthID = setInterval( async ()=> {
+			let lastContactDelta=Infinity
 			sensorMap.forEach((sensor)=>{
 				const config = getDeviceConfig(sensor.getMacAddress())
 				const dt = config?.discoveryTimeout??options.discoveryTimeout
 				const lc=sensor.elapsedTimeSinceLastContact()
+				if (lc<lastContactDelta) //get min last contact delta
+					lastContactDelta=lc
 				if (lc > dt) { 
 					updateSensor(sensor)
 				}
 			})
+			if (sensorMap.size && options.inactivityTimeout && lastContactDelta > options.inactivityTimeout)
+			{
+				
+				plugin.debug(`No contact with any sensors for ${lastContactDelta} seconds. Recycling Bluetooth adapter.`)	
+				await adapter.setPowered(false)
+				await adapter.setPowered(true)
+			}
+
 		}, intervalTimeout)
 		
 		if (!options.hasOwnProperty("discoveryInterval" )) //no config -- first run
@@ -789,6 +812,11 @@ module.exports =   function (app) {
 			progressTimeoutID=null
 		}
 
+		if (deviceHealthID) {
+			clearTimeout(deviceHealthID)
+			deviceHealthID=null
+		}
+
 		if ((sensorMap)){
 				for await (const sensorEntry of sensorMap.entries()) {
 				try{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bt-sensors-plugin-sk",
-  "version": "1.3.3",
+  "version": "1.3.4",
   "description": "Bluetooth Sensors for Signalk - see https://www.npmjs.com/package/bt-sensors-plugin-sk#supported-sensors for a list of supported sensors",
   "main": "index.js",
   "dependencies": {
@@ -13,7 +13,7 @@
     "@jellybrick/dbus-next": "^0.10.3",
     "int24": "^0.0.1",
     "kaitai-struct": "^0.10.0",
-    "@naugehyde/node-ble":"^1.13.4",
+    "@naugehyde/node-ble":"^1.13.5",
     "semver": "^7.7.1",
     "lru-cache": "^11.1.0"
   },

package/sensor_classes/HumsienkBMS.js

@@ -0,0 +1,385 @@
+const BTSensor = require("../BTSensor");
+
+/**
+ * HSC14F Battery Management System Sensor Class
+ * 
+ * Manufacturer: BMC (HumsiENK branded)
+ * Protocol: Custom BLE protocol using AA prefix commands
+ * 
+ * Discovered protocol details:
+ * - TX Handle: 0x000c (write commands to battery)
+ * - RX Handle: 0x000e (receive notifications from battery)
+ * - Command format: aa [CMD] 00 [CMD] 00
+ * - Multi-part responses (some commands send 2-3 notifications)
+ * 
+ * Key Commands:
+ * - 0x00: Handshake
+ * - 0x21: Real-time battery data (voltage, current, SOC, temps) - PRIMARY
+ * - 0x22: Individual cell voltages
+ * - 0x23: Battery status/warnings
+ * - 0x20: Configuration data
+ * - 0x10: Manufacturer name
+ * - 0x11: Model number
+ */
+
+class HumsienkBMS extends BTSensor {
+  static Domain = BTSensor.SensorDomains.electrical;
+
+  // Discovered actual UUIDs from device
+  static TX_RX_SERVICE = "00000001-0000-1000-8000-00805f9b34fb";
+  static WRITE_CHAR_UUID = "00000002-0000-1000-8000-00805f9b34fb";
+  static NOTIFY_CHAR_UUID = "00000003-0000-1000-8000-00805f9b34fb";
+
+  static identify(device) {
+    // HSC14F batteries advertise with this service UUID
+    // Further identification would require GATT connection to read manufacturer/model
+    return null;
+  }
+
+  static ImageFile = "JBDBMS.webp"; // Using similar BMS image for now
+  static Manufacturer = "BMC (HumsiENK)";
+  static Description = "HSC14F LiFePO4 Battery Management System";
+
+  /**
+   * Create HSC14F command
+   * Format: aa [CMD] 00 [CMD] 00
+   */
+  hsc14fCommand(command) {
+    return [0xaa, command, 0x00, command, 0x00];
+  }
+
+  /**
+   * Send command to battery
+   * HSC14F requires Write Request (0x12) not Write Command (0x52)
+   */
+  async sendCommand(command) {
+    this.debug(`Sending command 0x${command.toString(16)} to ${this.getName()}`);
+    return await this.txChar.writeValue(
+      Buffer.from(this.hsc14fCommand(command))
+    );
+  }
+
+  async initSchema() {
+    super.initSchema();
+    this.addDefaultParam("batteryID");
+
+    // Number of cells parameter - configurable (default 4 for LiFePO4)
+    if (this.numberOfCells === undefined) {
+      this.numberOfCells = 4;
+    }
+
+    this.addParameter("numberOfCells", {
+      title: "Number of cells",
+      description: "Number of cells in the battery (typically 4 for 12V LiFePO4)",
+      type: "number",
+      isRequired: true,
+      default: this.numberOfCells,
+      minimum: 1,
+      maximum: 16,
+      multipleOf: 1
+    });
+
+    // Voltage
+    this.addDefaultPath("voltage", "electrical.batteries.voltage").read = (
+      buffer
+    ) => {
+      // Bytes 3-4: voltage in mV, little-endian
+      return buffer.readUInt16LE(3) / 1000;
+    };
+
+    // Current - CORRECTED based on buffer analysis
+    this.addDefaultPath("current", "electrical.batteries.current").read = (
+      buffer
+    ) => {
+      // Bytes 7-8: current in milliamps, signed little-endian
+      // Negative = charging, Positive = discharging
+      return buffer.readInt16LE(7) / 1000;
+    };
+
+    // State of Charge
+    this.addDefaultPath(
+      "SOC",
+      "electrical.batteries.capacity.stateOfCharge"
+    ).read = (buffer) => {
+      // Byte 11: SOC percentage (0-100)
+      return buffer.readUInt8(11) / 100;
+    };
+
+    // Temperature 1 (ENV temperature) - CORRECTED byte position
+    this.addMetadatum("temp1", "K", "Battery Environment Temperature", (buffer) => {
+      // Byte 27: Environment temperature in °C
+      const tempC = buffer.readUInt8(27);
+      return 273.15 + tempC; // Convert to Kelvin
+    }).default = "electrical.batteries.{batteryID}.temperature";
+
+    // Temperature 2 (MOS temperature) - CORRECTED byte position
+    this.addMetadatum("temp2", "K", "Battery MOS Temperature", (buffer) => {
+      // Byte 28: MOS (MOSFET) temperature in °C
+      const tempC = buffer.readUInt8(28);
+      return 273.15 + tempC;
+    }).default = "electrical.batteries.{batteryID}.mosfetTemperature";
+
+    // Temperature 3 (Sensor) - CORRECTED byte position
+    this.addMetadatum("temp3", "K", "Battery Sensor Temperature", (buffer) => {
+      // Byte 29: Additional temperature sensor in °C
+      const tempC = buffer.readUInt8(29);
+      return 273.15 + tempC;
+    }).default = "electrical.batteries.{batteryID}.sensorTemperature";
+
+    // Manufacturer (from command 0x10)
+    this.addMetadatum(
+      "manufacturer",
+      "",
+      "Battery Manufacturer",
+      (buffer) => {
+        // Response: aa 10 03 42 4d 43 ...
+        // ASCII bytes starting at position 3
+        const len = buffer.readUInt8(2);
+        return buffer.toString("ascii", 3, 3 + len);
+      }
+    ).default = "electrical.batteries.{batteryID}.manufacturer";
+
+    // Model (from command 0x11)
+    this.addMetadatum("model", "", "Battery Model", (buffer) => {
+      // Response: aa 11 0a 42 4d 43 2d 30 34 53 30 30 31 ...
+      const len = buffer.readUInt8(2);
+      return buffer.toString("ascii", 3, 3 + len);
+    }).default = "electrical.batteries.{batteryID}.model";
+
+    // Cell voltages (from command 0x22)
+    // Number of cells is configurable via numberOfCells parameter
+    for (let i = 0; i < this.numberOfCells; i++) {
+      this.addMetadatum(
+        `cell${i}Voltage`,
+        "V",
+        `Cell ${i + 1} voltage`,
+        (buffer) => {
+          // Cell voltages: aa 22 30 6a 0d 58 0d 8f 0d 34 0d ...
+          // Starting at byte 3, each cell is 2 bytes little-endian in mV
+          return buffer.readUInt16LE(3 + i * 2) / 1000;
+        }
+      ).default = `electrical.batteries.{batteryID}.cell${i}.voltage`;
+    }
+  }
+
+  hasGATT() {
+    return true;
+  }
+
+  usingGATT() {
+    return true;
+  }
+
+  async initGATTNotifications() {
+    // Don't use notifications for polling mode
+    // The parent class initGATTInterval will handle periodic connections
+  }
+
+  async emitGATT() {
+    try {
+      await this.getAndEmitBatteryInfo();
+    } catch (e) {
+      this.debug(`Failed to emit battery info for ${this.getName()}: ${e}`);
+      throw e; // Re-throw so parent can handle reconnection
+    }
+
+    // Get cell voltages after a short delay
+    await new Promise(resolve => setTimeout(resolve, 2000));
+    
+    try {
+      await this.getAndEmitCellVoltages();
+    } catch (e) {
+      this.debug(`Failed to emit cell voltages for ${this.getName()}: ${e}`);
+      throw e; // Re-throw so parent can handle reconnection
+    }
+  }
+
+  /**
+   * Get buffer response from battery command
+   * HSC14F sends multi-part responses for some commands
+   */
+  async getBuffer(command) {
+    let result = Buffer.alloc(256);
+    let offset = 0;
+    let lastPacketTime = Date.now();
+
+    // Set up listener first
+    const responsePromise = new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        clearTimeout(timer);
+        if (completionTimer) clearTimeout(completionTimer);
+        this.rxChar.removeAllListeners("valuechanged");
+        reject(
+          new Error(
+            `Response timed out (+10s) from HSC14F device ${this.getName()}.`
+          )
+        );
+      }, 10000);
+
+      let completionTimer = null;
+
+      const valChanged = (buffer) => {
+        // HSC14F responses start with 0xaa followed by command byte
+        if (offset === 0 && (buffer[0] !== 0xaa || buffer[1] !== command)) {
+          this.debug(
+            `Invalid buffer from ${this.getName()}, expected command 0x${command.toString(
+              16
+            )}, got 0x${buffer[0].toString(16)} 0x${buffer[1].toString(16)}`
+          );
+          return;
+        }
+
+        buffer.copy(result, offset);
+        offset += buffer.length;
+        lastPacketTime = Date.now();
+
+        // Clear any existing completion timer
+        if (completionTimer) clearTimeout(completionTimer);
+
+        // Wait 200ms after last packet to consider response complete
+        // This allows multi-packet responses to assemble properly
+        completionTimer = setTimeout(() => {
+          result = Uint8Array.prototype.slice.call(result, 0, offset);
+          this.rxChar.removeAllListeners("valuechanged");
+          clearTimeout(timer);
+          resolve(result);
+        }, 200);
+      };
+
+      // Set up listener BEFORE sending command
+      this.rxChar.on("valuechanged", valChanged);
+    });
+
+    // Small delay to ensure listener is attached
+    await new Promise(r => setTimeout(r, 100));
+    
+    // Send the command
+    try {
+      await this.sendCommand(command);
+    } catch (err) {
+      this.rxChar.removeAllListeners("valuechanged");
+      throw err;
+    }
+
+    // Wait for response
+    return responsePromise;
+  }
+
+  async initGATTConnection(isReconnecting = false) {
+    await super.initGATTConnection(isReconnecting);
+    
+    // Set up GATT characteristics
+    const gattServer = await this.device.gatt();
+    const txRxService = await gattServer.getPrimaryService(
+      this.constructor.TX_RX_SERVICE
+    );
+    this.rxChar = await txRxService.getCharacteristic(
+      this.constructor.NOTIFY_CHAR_UUID
+    );
+    this.txChar = await txRxService.getCharacteristic(
+      this.constructor.WRITE_CHAR_UUID
+    );
+    await this.rxChar.startNotifications();
+    
+    return this;
+  }
+
+  /**
+   * Get and emit main battery data (voltage, current, SOC, temp)
+   * Uses command 0x21
+   */
+  async getAndEmitBatteryInfo() {
+    return this.getBuffer(0x21).then((buffer) => {
+      // Debug logging to verify buffer received
+      this.debug(`Command 0x21 response: ${buffer.length} bytes, hex: ${buffer.slice(0, 30).toString('hex')}`);
+      
+      ["voltage", "current", "SOC", "temp1", "temp2", "temp3"].forEach((tag) => {
+        this.emitData(tag, buffer);
+      });
+    });
+  }
+
+  /**
+   * Get and emit individual cell voltages
+   * Uses command 0x22
+   */
+  async getAndEmitCellVoltages() {
+    return this.getBuffer(0x22).then((buffer) => {
+      // Debug logging to verify buffer received
+      this.debug(`Command 0x22 response: ${buffer.length} bytes, hex: ${buffer.slice(0, 30).toString('hex')}`);
+      
+      for (let i = 0; i < this.numberOfCells; i++) {
+        this.emitData(`cell${i}Voltage`, buffer);
+      }
+    });
+  }
+
+  async initGATTInterval() {
+    // Get static info once (manufacturer, model) at first connection
+    try {
+      const mfgBuffer = await this.getBuffer(0x10);
+      this.emitData("manufacturer", mfgBuffer);
+      
+      const modelBuffer = await this.getBuffer(0x11);
+      this.emitData("model", modelBuffer);
+    } catch (e) {
+      this.debug(`Failed to get device info: ${e.message}`);
+    }
+
+    // Get first poll data before disconnecting
+    try {
+      await this.emitGATT();
+    } catch (error) {
+      this.debug(`Initial poll failed: ${error.message}`);
+    }
+
+    // Disconnect after initial data collection
+    await this.deactivateGATT().catch((e) => {
+      this.debug(`Error deactivating GATT Connection: ${e.message}`);
+    });
+    this.setState("WAITING");
+
+    // Set up polling interval - reconnect, poll, disconnect
+    this.intervalID = setInterval(async () => {
+      try {
+        this.setState("CONNECTING");
+        await this.initGATTConnection(true);
+        await this.emitGATT();
+      } catch (error) {
+        // Check if device has been removed from BlueZ cache
+        if (error.message && error.message.includes("interface not found in proxy object")) {
+          this.debug(`Device removed from BlueZ cache. Clearing stale connection state.`);
+          this.setError(`Device out of range or removed from Bluetooth cache. Waiting for rediscovery...`);
+          
+          // Clear the interval to stop futile reconnection attempts
+          if (this.intervalID) {
+            clearInterval(this.intervalID);
+            this.intervalID = null;
+          }
+          
+          // Set state to indicate waiting for rediscovery
+          this.setState("OUT_OF_RANGE");
+          return;
+        }
+        
+        this.debug(error);
+        this.setError(`Unable to emit values for device: ${error.message}`);
+      } finally {
+        await this.deactivateGATT().catch((e) => {
+          // Suppress errors when device is already removed from BlueZ
+          if (!e.message || !e.message.includes("interface not found")) {
+            this.debug(`Error deactivating GATT Connection: ${e.message}`);
+          }
+        });
+        this.setState("WAITING");
+      }
+    }, this.pollFreq * 1000);
+  }
+
+  async deactivateGATT() {
+    await this.stopGATTNotifications(this.rxChar);
+    await super.deactivateGATT();
+  }
+}
+
+module.exports = HumsienkBMS;