bt-sensors-plugin-sk 1.3.7 → 1.3.8-beta10

package/AI-DEV.md

@@ -1,784 +1,197 @@
-# AI-Assisted Development Guide for Bluetooth Battery Sensors
+# Working on bt-sensors-plugin-sk with Claude Code
 
-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.
+This file describes how the maintainers and contributors use Claude Code on this codebase. It is opinionated about *this* codebase, not about Claude Code in general; the patterns here have been validated by real PRs (see #142, #143, #144, #145).
 
-## Overview
+Two workflows are covered:
 
-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.
+1. **Adding a new sensor class.** Building support for a new Bluetooth device.
+2. **Cross-cutting review and cleanup.** Finding latent bugs, leaks, and hygiene issues across many existing sensors at once.
 
-## Prerequisites
+Both assume Claude Code (or another agent-based AI coding tool with comparable capabilities). Some sections reference specific Claude Code features such as skills (`/simplify`), sub-agents, and agent teams.
 
-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.)
+## Workflow 1: adding a new sensor class
 
-### 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)
+The plugin is a collection of sensor classes under `sensor_classes/`, each one extending `BTSensor` and handling one device family. New classes follow well-established patterns, so Claude's main job is recognizing the right pattern and copying it carefully, not designing something new.
 
-### 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
+### Capture real device traffic first
 
-## Critical First Step: Capture Real Bluetooth Data
+This is the single most important step. Without real packets, you and Claude are both guessing.
 
-### Using Android Bluetooth HCI Snoop Log (ESSENTIAL)
+- **Android HCI snoop log + vendor app** is the gold standard. Enable Developer Options on Android, turn on "Bluetooth HCI snoop log," use the vendor's app for 30 to 60 seconds pressing every button, then `adb pull /sdcard/Android/data/btsnoop_hci.log` and open in Wireshark. Filter on `bluetooth.addr == XX:XX:XX:XX:XX:XX`. Look for `ATT Write Request` (commands), `ATT Handle Value Notification` (push data), `ATT Read Response` (pull data), and `Advertising Data` (broadcast). Note what the vendor app displays at the moment each packet appears: that is the ground truth your decoder must match.
+- **nRF Connect** is the fallback if there is no vendor app. Scan, connect, walk every service and characteristic, read each readable one, enable notifications on each notifiable one, screenshot hex with the matching device-display reading.
 
-**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.
+Keep the captures around. You will use them again to validate the decoder before touching real hardware.
 
-**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
+### Have Claude pick a pattern from existing classes
 
-**Step-by-step process:**
+Three reference implementations cover most of the design space:
 
-1. **Enable Developer Options on Android:**
-   - Go to Settings → About Phone
-   - Tap "Build Number" 7 times
-   - Go back to Settings → Developer Options
+- `sensor_classes/VictronSmartLithium.js`: advertising data with AES-CTR encryption.
+- `sensor_classes/JBDBMS.js`: GATT with command/response protocol.
+- `sensor_classes/RenogyBattery.js`: GATT with Modbus-style register reads and polling.
 
-2. **Enable Bluetooth HCI Snoop Log:**
-   - In Developer Options, enable "Bluetooth HCI snoop log"
-   - This captures ALL Bluetooth traffic to a file
+A useful prompt: *"I'm adding a new sensor class for `<device>`. It uses `<advertising | GATT notifications | GATT polling>`. Read the three reference classes, summarize the pattern that fits best, and use it as the template."* Claude will read the actual files and report back, which is much better than improvising a structure from scratch.
 
-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
+### Implementation order
 
-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
-   ```
+1. **Skeleton class.** Extends `BTSensor`, sets `static Domain`, `static Manufacturer`, `static Description`, `static ImageFile`. Empty `initSchema()`.
+2. **`identify(device)`.** For advertising devices, match on manufacturer ID plus any disambiguating bytes. For GATT, match on advertised service UUID. Verify by running the plugin and confirming the device shows up under the right class.
+3. **Schema.** In `initSchema()`, call `addDefaultPath()` for standard SignalK paths (voltage, current, SoC, temperature), `addMetadatum()` for device-specific paths, and `addDefaultParam()` for configurable parameters like `batteryID`. Each path's `.read` function takes a `Buffer` and returns the decoded value.
+4. **Decoders.** Implement the `.read` functions using `buffer.readInt16LE`, `readUInt16BE`, etc. Match endianness to what your captured packets show.
+5. **GATT lifecycle (if applicable).** `hasGATT()` returns true, `usingGATT()` returns the configured flag, `initGATTConnection()` discovers services and characteristics, `initGATTNotifications()` or `initGATTInterval()` sets up the data flow, `emitGATT()` parses incoming buffers and calls `emitValuesFrom(buffer)`. Implement `deactivateGATT()` for cleanup.
+6. **Register the class.** Add to `classLoader.js` so it loads at startup.
 
-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
+### Verify against captured packets before touching hardware
 
-**What to look for in Wireshark:**
+`BTSensor` provides `_test()` for feeding a captured hex packet into the decoder and printing the parsed values. Confirm the output matches what the vendor app showed at the moment the packet was captured. Mismatches almost always come down to one of:
 
-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
+- wrong endianness (off by 256x or byte-swapped),
+- wrong sign (UInt vs Int),
+- wrong scale factor,
+- wrong byte offset.
 
-For Advertising devices:
-- `Advertising Data` packets
-- Manufacturer Data field with ID and hex bytes
-- Service Data field with UUID and hex bytes
+A passing `_test()` is necessary but not sufficient: it does not catch reconnect bugs, lifecycle leaks, or characteristic-discovery edge cases. Real-device verification is the only way to be sure.
 
-**Real Example - HSC14F Battery:**
+### Run `/simplify` before opening the PR
 
-```
-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)
-```
+Before pushing, ask Claude Code to run `/simplify` on the diff. It looks for reuse opportunities (someone else already wrote a similar decoder), tightens overengineered code, and catches issues introduced during the change itself. Cheap and worth doing every time.
 
-**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:
+## Workflow 2: cross-cutting review and cleanup
 
-[FOR GATT DEVICES:]
-Service UUID: 0000ffe0-0000-1000-8000-00805f9b34fb
-Characteristic UUID: 0000ffe1-0000-1000-8000-00805f9b34fb
+The codebase has 100+ sensor classes, mostly contributed device-by-device, so the same kinds of bugs tend to recur across many files: comma-expressions where function calls were meant, missing `await`s, `for` loops with the condition and update slots swapped, listeners that compound across reconnects. A targeted multi-agent pass catches a lot of these in one go.
 
-Write Request to device:
-A5 5A 00 FF 01 03
+### The pattern (recently used for PRs #142, #143, #144, #145)
 
-Notification Response:
-A5 5A 00 01 01 0C E4 10 0E 55 19 00 01 02 [...]
+1. **Spawn an agent team with non-overlapping lenses.** Each teammate gets one bug class to look for. Useful lenses for this codebase:
+   - **Silent value-corruption.** Decoders that return wrong numbers without throwing: comma-expression bugs, missing `return` in arrow function bodies, wrong scale factors, bitwise-vs-arithmetic operator confusion (`^` instead of `**`).
+   - **Latent runtime crashes.** Bare `varName` instead of `this.varName`, missing `await`, `buffer.size` (does not exist on Node `Buffer`) instead of `buffer.length`, copy-paste typos that throw `ReferenceError` on first invocation.
+   - **Connection-lifecycle and resource leaks.** `setInterval` cleared with `clearTimeout`, listeners that compound across reconnects, command sequences that overlap on a single characteristic, retry loops with broken exit conditions.
+   - **Security and hygiene.** `eval`, `debugger`, dead code, unused imports, implicit globals, duplicate declarations.
 
-When this packet arrived, the vendor app displayed:
-- Voltage: 13.2V
-- Current: 10.5A
-- SOC: 85%
-- Temperature: 25°C
+   Agent teams beat single sub-agents because teammates can challenge each other's findings via the team mailbox before reporting up to you. False positives drop dramatically. Set `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in `~/.claude/settings.json` and spawn three teammates with distinct lenses in a single turn so they run concurrently.
 
-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
+2. **Triage and group.** Have the agents pool every finding, dedupe overlap, and rank by blast radius and confidence. **Drop anything that cannot be verified from the code alone.** Byte-offset claims that need hardware to validate, claims about files on a live in-flight branch, decoder behavior that depends on what a real device actually emits: skip those rather than guess. Better to miss a real bug than to merge a wrong "fix."
 
-[FOR ADVERTISING DEVICES:]
-Advertising Data shows:
-Manufacturer Data (0x1234): AB CD 0C E4 10 0E 55 01 F4
+3. **Group findings into themed PRs, not one big PR.** Different bug classes are different review burdens for the maintainer. PR #142 (silent value bugs) and PR #143 (runtime crashes) need different mental models from a reviewer; mixing them makes both harder to evaluate. Aim for roughly 5 to 10 fixes per PR with a coherent theme.
 
-When this was captured, device display showed:
-- Voltage: 13.2V
-- Current: 10.5A
-- SOC: 85%
+4. **`/simplify` pass per PR.** Same as in workflow 1: run before opening each PR. It often catches an over-engineered patch and trims it down before it leaves your machine.
 
-Please decode this packet format.
-```
+5. **Per-PR test plan tied to real hardware.** End every PR description with a checklist of things to verify on the actual devices. The maintainer is the one with the hardware; the test plan is the merge bar, not filler. PRs without a test plan put all the verification cost on the maintainer, and most maintainers will deprioritize them.
 
-### Alternative: Using nRF Connect (If No Vendor App Available)
+6. **Manual review before push.** Read every diff yourself. Hold back changes that look plausible to the agents but feel off on a second read. "Claude Code was involved" can mean very different things depending on whether a human looked at the diff before pushing.
 
-If there's no vendor app:
+### What this workflow does NOT do well
 
-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
+- **Architectural changes.** Agent teams find local bugs. Refactors and design shifts should be brainstormed with a human first, not handed to an agent team. Use the `brainstorming` skill for that.
+- **Behavior changes that need hardware verification.** If a fix's correctness depends on what the device actually emits, the agents' confidence is meaningless. Either verify on hardware before opening the PR or skip the change.
+- **Anything on an active feature branch.** Run this against `main` only. Running it across in-flight branches creates merge nightmares and steps on the contributor's work.
 
-**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
+## Appendix: tactical patterns
 
-Battery label shows: 13.2V, 10.5A, 85%
+### Buffer reading
 
-How do I decode this to get those values?
+```js
+buffer.readUInt16LE(offset)   // unsigned 16-bit little-endian
+buffer.readInt16LE(offset)    // signed
+buffer.readUInt16BE(offset)   // big-endian
+buffer.readUInt8(offset)      // single byte
+buffer.readInt8(offset)
+buffer.readUInt32LE(offset)
 ```
 
-## Step-by-Step AI-Assisted Development Process
+Common decoder shapes:
 
-### Step 1: Analyze Existing Similar Implementations
+```js
+// Voltage: 0.01V units, unsigned LE
+.read = (buffer) => buffer.readUInt16LE(2) / 100
 
-**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
-```
+// Current: 0.01A units, signed LE (positive = charging)
+.read = (buffer) => buffer.readInt16LE(4) / 100
 
-**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
+// Temperature: 0.1°C, signed, returned as Kelvin
+.read = (buffer) => buffer.readInt16LE(7) / 10 + 273.15
 
-### 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
-```
+// SoC: percent as ratio
+.read = (buffer) => buffer.readUInt8(6) / 100
 
-**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
+// "Not available" sentinel handling
+.read = (buffer) => {
+  const v = buffer.readInt16LE(8)
+  return v === 0x7FFF ? NaN : v / 10
 }
 ```
 
-### 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
+### SignalK paths
 
-**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)
-   ...
-   */
+Standard battery paths (units in parentheses):
 
-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":
-
+electrical.batteries.{id}.voltage                    (V)
+electrical.batteries.{id}.current                    (A, +ve = charging)
+electrical.batteries.{id}.temperature                (K)
+electrical.batteries.{id}.capacity.stateOfCharge     (ratio 0-1)
+electrical.batteries.{id}.capacity.remaining         (C, coulombs)
+electrical.batteries.{id}.capacity.actual            (C, total)
+electrical.batteries.{id}.cycles                     (count)
+electrical.batteries.{id}.lifetimeDischarge          (C)
+electrical.batteries.{id}.lifetimeRecharge           (C)
 ```
-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)
+Per-cell paths use `electrical.batteries.{id}.cell[N].voltage`.
 
-AI: [Fixes current sign interpretation]
+### Common gotchas
 
-User: Perfect! Now add the image reference and register it.
+| Symptom | Likely cause |
+|---------|--------------|
+| Values 256x off | Wrong endianness |
+| Negative when charging | UInt vs Int, or signed value being read unsigned |
+| Always the same constant | Wrong byte offset, OR a `(x, y)` comma-expression where a function call was intended |
+| `undefined` from a decoder | Arrow function body uses `{ ... }` but is missing `return` |
+| `Cannot read properties of null` after disconnect | GATT handle accessed without checking that `_gattConnection` is still non-null |
+| Listener count grows over time | Override missing `super.propertiesChanged()` call, or a reconnect path that re-adds listeners without removing the old ones |
 
-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]
-```
+### Capturing HCI logs (quick reference)
 
-### 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
+# Android: enable in Developer Options, then
+adb pull /sdcard/Android/data/btsnoop_hci.log
+# Or, on newer Android:
+adb bugreport
+# then extract: FS/data/misc/bluetooth/logs/btsnoop_hci.log
+
+# Wireshark filter:
+bluetooth.addr == XX:XX:XX:XX:XX:XX
+# look at: ATT Write Request, ATT Handle Value Notification,
+#          ATT Read Response, Advertising Data
+
+# tshark for batch extraction:
 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)
+### bluetoothctl quick scan
 
-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.
+```bash
+bluetoothctl
+scan on
+# wait for the device to appear
+info XX:XX:XX:XX:XX:XX
+# look for: ManufacturerData, ServiceData, UUIDs
 ```
 
-## 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! 🔋⚡
+- [SignalK specification](http://signalk.org/specification/latest/doc/vesselsBranch.html)
+- [Bluetooth GATT specifications](https://www.bluetooth.com/specifications/specs/)
+- [Node.js Buffer API](https://nodejs.org/api/buffer.html)
+- `README.md`: plugin overview
+- `BTSensor.js`: base class for all sensor implementations
+- `sensor_classes/DEVELOPMENT.md`: older device-style guide; some overlap with this file