@rhizomatics/signalk-bluetti-plugin 1.3.2 → 1.4.1

package/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+All notable changes to this plugin are documented here. Format loosely follows [Keep a Changelog](https://keepachangelog.com/).
+
+## [1.4.1]
+
+- Basic test suite
+
+## [1.4.0]
+
+- Normalize and extend paths for SignalK
+  - Elite 100 v2 now publishes 12 paths, the AC200P 22
+- Metadata update for package, including git repo transfer
+- README and CHANGELOG now included in package
+- CLI commands now guess MAC address if one not provided
+- CSV files now can provide static defaults, e.g. for DC output voltage, where the unit itself does not expose this over BLE
+
+## [1.3.2]
+
+- Correct SignalK paths so state of charge shows as a percentage
+  - From `electrical.batteries.<id>.stateOfCharge` to `electrical.batteries.<id>.capacity.stateOfCharge`
+
+## [1.3.1]
+
+- Back off if bluetooth daemon not available at startup
+- Fix scaling of current state of charge value
+
+## [1.3.0]
+
+- Fix handling of node-ble 128-bit UUIDs
+- Fix encrypted reads for Elite v2 BLE
+  - Confirmed successful values read from an Elite 100 V2
+- CLI now has separate `dump` and `info` commands for raw and interpreted data
+
+## [1.2.0]
+
+- Stop scanner going into continuous scan loop if configured device not found
+- Add discovery timeout
+- Added CLI to scan and inspect devices
+- Build tools added oxfmt and oxlint to improve cod quality
+- Fix upstream EventEmitter leak in `@naugehyde/node-ble`
+
+## [1.1.2-alpha]
+
+- Fix crash on scan completion
+
+## [1.1.1-alpha]
+
+- Add timeout handling for BLE connect/polling
+
+## [1.1.0-alpha]
+
+- Switch BLE backend from `@stoprocent/noble` to `@naugehyde/node-ble` (BlueZ D-Bus), so connections persist across disconnects without needing a rescan
+
+## [1.0.8-alpha]
+
+- Improve connect/reconnect behaviour
+
+## [1.0.7-alpha]
+
+- Validate the encryption key file; stop scanning once a device connection starts
+
+## [1.0.6-alpha] and earlier
+
+- Initial register map support, BLE scanning, and encryption-key auto-detection, plus assorted fixes leading up to the first alpha releases
+
+## [1.0.0]
+
+- Initial release

package/README.md

@@ -2,12 +2,14 @@
 
 [![npm version](https://img.shields.io/npm/v/@rhizomatics/signalk-bluetti-plugin.svg)](https://www.npmjs.com/package/@rhizomatics/signalk-bluetti-plugin)
 [![npm downloads](https://img.shields.io/npm/dm/@rhizomatics/signalk-bluetti-plugin.svg)](https://www.npmjs.com/package/@rhizomatics/signalk-bluetti-plugin)
-[![SignalK Plugin CI](https://github.com/jeyrb/signalk-bluetti-plugin/actions/workflows/signalk-ci.yml/badge.svg)](https://github.com/jeyrb/signalk-bluetti-plugin/actions/workflows/signalk-ci.yml)
+[![SignalK Plugin CI](https://github.com/rhizomatics/signalk-bluetti-plugin/actions/workflows/signalk-ci.yml/badge.svg)](https://github.com/rhizomatics/signalk-bluetti-plugin/actions/workflows/signalk-ci.yml)
 ![code style: oxfmt](https://img.shields.io/badge/code_style-oxfmt-blue.svg)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/rhizomatics/signalk-bluetti-plugin/blob/main/LICENSE)
 
 A SignalK plugin to display data from Bluetti power stations over a Bluetooth Low Energy (BLE) connection. BETA status
 
+![Example Data](docs/assets/screenshots/bluetti_data.png)
+
 ## Pre-requisites
 
 The requirements below are only to make SignalK work with Bluetooth Low Energy, which is good thing to have anyway, since vendors like Victron, Switchbot, Ruuvi and others have BLE enabled hardware that's useful to have on a boat. Ignore if BLE already being used. [Direct BLE support](https://github.com/SignalK/signalk-server/issues/2411) in SignalK is being planned in 2026 and this plugin will support that when it comes.
@@ -56,22 +58,24 @@ node cli.js scan --all              # show every BLE device, not just Bluetti-ma
 node cli.js scan --timeout 30       # scan duration in seconds (default: 15)
 ```
 
-### `dump <mac>`
+### `dump [mac]`
 
-Connect to a single device by MAC address and print low-level details: name, alias, RSSI, pairing state, manufacturer data, and its raw GATT services/characteristics. Useful for figuring out a new/unknown device's UUIDs before wiring up a register map.
+Connect to a single device by MAC address and print low-level details: name, alias, RSSI, pairing state, manufacturer data, and its raw GATT services/characteristics — including each characteristic's flags (read/write/notify/…) and, for readable ones, its current value as hex. Useful for figuring out a new/unknown device's UUIDs before wiring up a register map. If `mac` is omitted, scans and connects to the first Bluetti-matching device found.
 
 ```bash
 node cli.js dump aa:bb:cc:dd:ee:ff
+node cli.js dump                                   # scan and use the first Bluetti device found
 node cli.js dump aa:bb:cc:dd:ee:ff --timeout 30   # discovery timeout if device isn't already known to BlueZ (default: 20)
 ```
 
-### `info <mac>`
+### `info [mac]`
 
-Connect to a device and decode its live register values the same way the plugin itself does — same GATT UUIDs, same encryption handshake (including the AES/ECDH handshake used by "V2"-protocol models like the EL100V2), same register parsing. Requires `--registers`.
+Connect to a device and decode its live register values the same way the plugin itself does — same GATT UUIDs, same encryption handshake (including the AES/ECDH handshake used by "V2"-protocol models like the EL100V2), same register parsing. Requires `--registers`. If `mac` is omitted, scans and connects to the first Bluetti-matching device found.
 
 ```bash
 # Decode live registers using a bundled register map (see registers/*.csv for available models)
 node cli.js info aa:bb:cc:dd:ee:ff --registers ac200p
+node cli.js info --registers ac200p                # scan and use the first Bluetti device found
 
 # Or a custom CSV, plus an encryption key file for legacy models that XOR-scramble frames
 # (not needed for V2-protocol models — those are auto-detected and handshake automatically)

package/cli.js

@@ -30,16 +30,21 @@ Commands:
     --all                       Also show non-Bluetti BLE devices
     --timeout <seconds>          Scan duration (default: 15)
 
-  dump <mac>                   Connect to a device and print its raw GATT
-                                services/characteristics (low-level inspection)
-    --timeout <seconds>          Discovery timeout if not already known (default: 20)
-
-  info <mac>                   Connect and decode live registers the same way
+  dump [mac]                   Connect to a device and print its raw GATT
+                                services/characteristics, with flags and
+                                readable values (low-level inspection)
+                                If mac is omitted, scans and uses the first
+                                Bluetti device found.
+    --timeout <seconds>          Discovery/scan timeout if not already known (default: 20)
+
+  info [mac]                   Connect and decode live registers the same way
                                 the plugin does
+                                If mac is omitted, scans and uses the first
+                                Bluetti device found.
     --registers <model|path>     Built-in model (${builtins.join(", ") || "none bundled"}) or a CSV path (required)
     --encryption-key <path>      Path to the Bluetti-provided encryption CSV
                                   (only needed for legacy XOR-scrambled models)
-    --timeout <seconds>          Discovery timeout if not already known (default: 20)
+    --timeout <seconds>          Discovery/scan timeout if not already known (default: 20)
 
   help                         Show this help
 
@@ -47,7 +52,9 @@ Examples:
   bluetti-cli scan
   bluetti-cli scan --all --timeout 30
   bluetti-cli dump aa:bb:cc:dd:ee:ff
+  bluetti-cli dump
   bluetti-cli info aa:bb:cc:dd:ee:ff --registers ac200p
+  bluetti-cli info --registers ac200p
 `);
 }
 
@@ -183,7 +190,21 @@ async function printGattTree(bleDevice) {
       console.log(`Service ${uuid}`);
       const service = await gatt.getPrimaryService(uuid);
       const charUuids = await service.characteristics();
-      for (const cUuid of charUuids) console.log(`  Characteristic ${cUuid}`);
+      for (const cUuid of charUuids) {
+        const characteristic = await service.getCharacteristic(cUuid);
+        const flags = await characteristic.getFlags().catch(() => []);
+
+        let valueStr = "";
+        if (flags.includes("read")) {
+          try {
+            const value = await characteristic.readValue();
+            valueStr = ` = ${value.length ? value.toString("hex") : "(empty)"}`;
+          } catch (err) {
+            valueStr = ` = (read failed: ${err.message})`;
+          }
+        }
+        console.log(`  Characteristic ${cUuid} [${flags.join(", ") || "?"}]${valueStr}`);
+      }
     }
   } finally {
     if (!alreadyConnected) await bleDevice.disconnect().catch(() => {});
@@ -261,17 +282,45 @@ async function printRegisterValues(bleDevice, mac, args) {
   }
 }
 
+// Scans for the first Bluetti-matching device and resolves its address, or
+// null if none turned up before durationMs. Used to default `[mac]` CLI
+// arguments when the user doesn't already know the address.
+async function findFirstBluettiAddress(durationMs, log) {
+  const Scanner = require("./lib/scanner");
+  const scanner = new Scanner(log, { includeAll: false });
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      scanner.stopAll();
+      resolve(result);
+    };
+    scanner.once("discovered", ({ address, name }) => finish({ address, name }));
+    scanner.once("scanComplete", () => finish(null));
+    scanner.once("error", () => finish(null));
+    void scanner.startScan(durationMs);
+  });
+}
+
 async function withConnectedDevice(args, usageLine, body) {
-  const mac = args._[0];
+  let mac = args._[0];
+  const timeoutMs = (args.timeout ? parseFloat(args.timeout) : 20) * 1000;
+
   if (!mac) {
-    console.error(`Error: MAC address required. Usage: ${usageLine}`);
-    process.exitCode = 1;
-    return;
+    console.error(`No MAC address given — scanning for a Bluetti device (up to ${timeoutMs / 1000}s)…`);
+    const found = await findFirstBluettiAddress(timeoutMs, (msg) => console.error(`[scan] ${msg}`));
+    if (!found) {
+      console.error(`No Bluetti device found. Usage: ${usageLine}`);
+      process.exitCode = 1;
+      return;
+    }
+    mac = found.address;
+    console.error(`Found ${found.name || "(unnamed)"} [${mac}]`);
   }
 
   const { createBluetooth } = require("@naugehyde/node-ble");
   const bt = createBluetooth();
-  const timeoutMs = (args.timeout ? parseFloat(args.timeout) : 20) * 1000;
 
   try {
     const adapter = await bt.bluetooth.defaultAdapter();
@@ -292,16 +341,16 @@ async function withConnectedDevice(args, usageLine, body) {
 }
 
 async function cmdDump(args) {
-  await withConnectedDevice(args, "bluetti-cli dump <mac>", (bleDevice) => printGattTree(bleDevice));
+  await withConnectedDevice(args, "bluetti-cli dump [mac]", (bleDevice) => printGattTree(bleDevice));
 }
 
 async function cmdInfo(args) {
   if (!args.registers) {
-    console.error("Error: --registers <model|path> is required. Usage: bluetti-cli info <mac> --registers <model|path>");
+    console.error("Error: --registers <model|path> is required. Usage: bluetti-cli info [mac] --registers <model|path>");
     process.exitCode = 1;
     return;
   }
-  await withConnectedDevice(args, "bluetti-cli info <mac> --registers <model|path>", (bleDevice, mac) =>
+  await withConnectedDevice(args, "bluetti-cli info [mac] --registers <model|path>", (bleDevice, mac) =>
     printRegisterValues(bleDevice, mac, args),
   );
 }

package/index.js

@@ -271,6 +271,7 @@ module.exports = function (app) {
 
   function startDevice(cfg, bleDevice, bleName, { BluettiDevice, loadCsv, buildDelta, readEncryptionKey }) {
     const { address, name, encryptionCsvPath = "", pollIntervalSeconds = 10 } = cfg;
+    const registerCache = new Map(); // last-known value per field_name, across polls — see buildDelta
 
     let registerPath;
     try {
@@ -324,7 +325,7 @@ module.exports = function (app) {
     });
 
     device.on("registers", (registers) => {
-      const delta = buildDelta(registers, fields, name, PLUGIN_ID);
+      const delta = buildDelta(registers, fields, name, PLUGIN_ID, { cache: registerCache });
       if (delta) app.handleMessage(PLUGIN_ID, delta);
     });
 

package/lib/csv-loader.js

@@ -14,6 +14,7 @@ const COL_ALIASES = {
   unit: ["unit", "units", "单位"],
   signalk_path: ["signalk_path", "signalk", "sk_path", "path"],
   register_count: ["register_count", "count", "length", "bytes", "数据长度"],
+  constant_value: ["constant_value", "constant", "const", "fixed_value", "static_value"],
 };
 
 function resolveColumn(headers, key) {
@@ -26,7 +27,8 @@ function resolveColumn(headers, key) {
 }
 
 // Parse the CSV and return an array of field descriptors.
-// Each descriptor: { fieldName, register, count, dataType, scale, offset, unit, signalkPath }
+// Each descriptor is either register-backed: { fieldName, register, count, dataType, scale, offset, unit, signalkPath }
+// or a fixed constant (register_address left blank): { fieldName, register: null, count: 0, dataType: "const", ..., constantValue }
 function loadCsv(filePath) {
   const raw = fs.readFileSync(filePath, "utf8");
 
@@ -38,6 +40,7 @@ function loadCsv(filePath) {
     skip_empty_lines: true,
     trim: true,
     comment: "#",
+    relax_column_count: true,
   });
 
   if (records.length === 0) throw new Error(`CSV file ${filePath} has no data rows`);
@@ -54,9 +57,30 @@ function loadCsv(filePath) {
 
   const fields = [];
   for (const row of records) {
+    const fieldName = (row[col.field_name] || "").trim();
+    if (!fieldName) continue;
+
+    const signalkPath = col.signalk_path ? (row[col.signalk_path] || "").trim() : "";
+    const constantRaw = col.constant_value ? (row[col.constant_value] || "").trim() : "";
+
     const registerRaw = row[col.register_address];
     const register = parseInt(registerRaw, 10);
-    if (isNaN(register)) continue; // skip header-like rows embedded in data
+
+    if (isNaN(register)) {
+      // No register address — only valid if this row instead supplies a fixed
+      // constant (e.g. a model's nominal battery capacity or chemistry, which
+      // isn't a live register on every device). Otherwise it's a header-like
+      // row embedded in the data and gets skipped.
+      if (!constantRaw) continue;
+      // Numeric constants (e.g. a nominal capacity in Wh) need to go through
+      // the same unit conversion as register-backed fields; text constants
+      // (chemistry, manufacturer name) are left as-is.
+      const asNumber = Number(constantRaw);
+      const constantValue = Number.isNaN(asNumber) ? constantRaw : asNumber;
+      const unit = col.unit ? (row[col.unit] || "").trim() : "";
+      fields.push({ fieldName, register: null, count: 0, dataType: "const", scale: 1, offset: 0, unit, signalkPath, constantValue });
+      continue;
+    }
 
     const dataType = col.data_type ? (row[col.data_type] || "uint16").toLowerCase().trim() : "uint16";
     const scale = col.scale ? parseFloat(row[col.scale]) || 1 : 1;
@@ -67,11 +91,6 @@ function loadCsv(filePath) {
     let count = col.register_count ? parseInt(row[col.register_count], 10) : NaN;
     if (isNaN(count)) count = registersForType(dataType);
 
-    const signalkPath = col.signalk_path ? (row[col.signalk_path] || "").trim() : "";
-    const fieldName = (row[col.field_name] || "").trim();
-
-    if (!fieldName) continue;
-
     fields.push({ fieldName, register, count, dataType, scale, offset, unit, signalkPath });
   }
 
@@ -98,6 +117,8 @@ function registersForType(dataType) {
 function decodeValue(field, rawRegs) {
   const { register, count, dataType, scale, offset } = field;
 
+  if (dataType === "const") return field.constantValue;
+
   let raw;
   if (count === 1) {
     raw = rawRegs.get(register);

package/lib/path-mapper.js

@@ -23,23 +23,72 @@ const UNIT_CONVERSIONS = {
 };
 
 function convertUnits(value, unit) {
-  if (unit === null || unit === undefined) return value;
+  if (unit === null || unit === undefined || typeof value !== "number") return value;
   const key = unit.toLowerCase().trim();
   const fn = UNIT_CONVERSIONS[key];
   return fn ? fn(value) : value;
 }
 
-// Build a SignalK path for a field, substituting {name} with the device name.
-// Falls back to auto-generating from fieldName if signalkPath is not set in CSV.
+// Canonical field_name → SignalK path for the register names Bluetti's own
+// documentation and the bundled CSVs use. A CSV's `signalk_path` column is an
+// override on top of this — only needed for a register the code doesn't know
+// about — so bundled/well-known CSVs can leave it blank and just list
+// field_name + register info.
+//
+// ac_input_power, ac_input_voltage, and dc_output_power are intentionally
+// absent here — they don't have a direct standard path of their own, they're
+// only ever consumed as inputs to the derived charger/battery current in
+// buildDelta() below.
+const STANDARD_FIELD_PATHS = {
+  // Battery
+  battery_soc: "electrical.batteries.{name}.capacity.stateOfCharge",
+  battery_percent: "electrical.batteries.{name}.capacity.stateOfCharge",
+  battery_voltage: "electrical.batteries.{name}.voltage",
+  battery_current: "electrical.batteries.{name}.current",
+  battery_power: "electrical.batteries.{name}.power",
+  battery_temperature: "electrical.batteries.{name}.temperature",
+  battery_chemistry: "electrical.batteries.{name}.chemistry",
+  battery_manufacturer_name: "electrical.batteries.{name}.manufacturer.name",
+  battery_manufacturer_model: "electrical.batteries.{name}.manufacturer.model",
+  total_capacity: "electrical.batteries.{name}.capacity.nominal",
+  time_remaining_minutes: "electrical.batteries.{name}.capacity.timeRemaining",
+  internal_temperature: "electrical.batteries.{name}.controllerTemperature",
+
+  // Solar / DC input
+  dc_input_power: "electrical.solar.{name}.panelPower",
+  dc_input_voltage: "electrical.solar.{name}.panelVoltage",
+  dc_input_current: "electrical.solar.{name}.panelCurrent",
+
+  // AC output (inverter)
+  ac_output_power: "electrical.inverters.{name}.ac.realPower",
+  ac_output_voltage: "electrical.inverters.{name}.ac.voltage",
+  ac_output_current: "electrical.inverters.{name}.ac.current",
+  ac_output_frequency: "electrical.inverters.{name}.ac.frequency",
+
+  // AC input (charger) — current/frequency map directly when a device has real
+  // registers for them; if not, current is derived (see buildDelta below).
+  ac_input_current: "electrical.chargers.{name}.current",
+  ac_input_frequency: "electrical.chargers.{name}.frequency",
+};
+
+// Fields that feed a derived computation in buildDelta() rather than being
+// published under their own path directly.
+const DERIVED_SOURCE_FIELDS = new Set(["ac_input_power", "ac_input_voltage", "dc_output_power", "dc_output_voltage"]);
+
+// Build a SignalK path for a field: explicit CSV override first, then the
+// standard field_name registry above, then a best-effort keyword guess.
 function resolvePath(field, deviceName) {
   if (field.signalkPath) {
     return field.signalkPath.replace(/\{name\}/gi, deviceName);
   }
+  const standard = STANDARD_FIELD_PATHS[field.fieldName.toLowerCase()];
+  if (standard) return standard.replace(/\{name\}/g, deviceName);
   return autoPath(field.fieldName, deviceName);
 }
 
 // Best-effort automatic path generation for common Bluetti field names.
-// Users with a properly-annotated CSV will never hit this; it's a safety net.
+// Only reached for fields not in STANDARD_FIELD_PATHS above — i.e. a custom
+// CSV using field names the code doesn't recognise and no explicit override.
 function autoPath(fieldName, name) {
   const f = fieldName.toLowerCase();
   if (f.includes("battery") || f.includes("batt") || f.includes("soc")) {
@@ -58,17 +107,17 @@ function autoPath(fieldName, name) {
     return `electrical.solar.${name}.${fieldName}`;
   }
   if (f.includes("ac_output") || f.includes("inverter") || f.includes("ac_out")) {
-    if (f.includes("power")) return `electrical.inverters.${name}.ac.power`;
+    if (f.includes("power")) return `electrical.inverters.${name}.ac.realPower`;
     if (f.includes("voltage")) return `electrical.inverters.${name}.ac.voltage`;
     if (f.includes("current")) return `electrical.inverters.${name}.ac.current`;
     if (f.includes("freq")) return `electrical.inverters.${name}.ac.frequency`;
     return `electrical.inverters.${name}.ac.${fieldName}`;
   }
   if (f.includes("ac_input") || f.includes("mains") || f.includes("grid") || f.includes("charger")) {
-    if (f.includes("power")) return `electrical.chargers.${name}.input.power`;
-    if (f.includes("voltage")) return `electrical.chargers.${name}.input.voltage`;
-    if (f.includes("current")) return `electrical.chargers.${name}.input.current`;
-    return `electrical.chargers.${name}.input.${fieldName}`;
+    if (f.includes("power")) return `electrical.chargers.${name}.power`;
+    if (f.includes("voltage")) return `electrical.chargers.${name}.voltage`;
+    if (f.includes("current")) return `electrical.chargers.${name}.current`;
+    return `electrical.chargers.${name}.${fieldName}`;
   }
   // Catch-all
   return `electrical.${name}.${fieldName}`;
@@ -76,17 +125,60 @@ function autoPath(fieldName, name) {
 
 // Given a Map of register→uint16 values and the full field list,
 // produce a SignalK delta values array ready for app.handleMessage().
-function buildDelta(registers, fields, deviceName, source) {
+//
+// opts.cache: a Map the caller keeps alive for the lifetime of the device,
+// used to remember the last-known value of every field across polls. This is
+// needed because a single call here only ever sees one batch's worth of
+// registers (see groupRegisters in protocol.js) — e.g. ac_input_power and
+// ac_input_voltage typically land in different batches, so deriving current
+// from their ratio requires remembering whichever arrived most recently.
+function buildDelta(registers, fields, deviceName, source, opts = {}) {
+  const { cache = new Map() } = opts;
   const values = [];
+  const hasRawAcInputCurrent = fields.some((f) => f.fieldName.toLowerCase() === "ac_input_current");
 
   for (const field of fields) {
     const raw = decodeValue(field, registers);
     if (raw === null) continue;
 
     const converted = convertUnits(raw, field.unit);
-    const path = resolvePath(field, deviceName);
+    const key = field.fieldName.toLowerCase();
+    cache.set(key, converted);
+
+    if (!field.signalkPath && DERIVED_SOURCE_FIELDS.has(key)) continue; // published below instead
+
+    values.push({ path: resolvePath(field, deviceName), value: converted });
+  }
+
+  // AC mains charger: Bluetti reports power+voltage on this input, not
+  // current — SignalK's electrical.chargers.<id> wants voltage/current, so
+  // derive it (unless the device has a real current register — see above).
+  if (cache.has("ac_input_voltage")) {
+    values.push({ path: `electrical.chargers.${deviceName}.voltage`, value: cache.get("ac_input_voltage") });
+  }
+  if (!hasRawAcInputCurrent && cache.has("ac_input_power") && cache.has("ac_input_voltage")) {
+    const voltage = cache.get("ac_input_voltage");
+    const power = cache.get("ac_input_power");
+    values.push({ path: `electrical.chargers.${deviceName}.current`, value: voltage ? power / voltage : 0 });
+  }
+
+  // DC output port (e.g. a 12V accessory socket): Bluetti reports power only,
+  // at a fixed nominal voltage that isn't itself a register — the CSV supplies
+  // it as a constant (dc_output_voltage), and current is derived from that.
+  if (cache.has("dc_output_power") && cache.has("dc_output_voltage")) {
+    const power = cache.get("dc_output_power");
+    const voltage = cache.get("dc_output_voltage");
+    values.push({ path: `electrical.batteries.${deviceName}.voltage`, value: voltage });
+    values.push({ path: `electrical.batteries.${deviceName}.current`, value: voltage ? power / voltage : 0 });
+  }
 
-    values.push({ path, value: converted });
+  // Remaining capacity = nominal capacity × state of charge. Bluetti's own
+  // "remaining capacity" register drifts with cell aging and isn't available
+  // on every model; deriving it from a fixed nominal spec (see registers/*.csv)
+  // plus the reported SoC is simpler and consistent across models.
+  const soc = cache.has("battery_soc") ? cache.get("battery_soc") : cache.has("battery_percent") ? cache.get("battery_percent") : null;
+  if (soc !== null && cache.has("total_capacity")) {
+    values.push({ path: `electrical.batteries.${deviceName}.capacity.remaining`, value: cache.get("total_capacity") * soc });
   }
 
   if (values.length === 0) return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhizomatics/signalk-bluetti-plugin",
-  "version": "1.3.2",
+  "version": "1.4.1",
   "description": "SignalK plugin for Bluetti power station monitoring via Bluetooth LE. Beta, use with caution.",
   "keywords": [
     "battery",
@@ -12,7 +12,16 @@
     "signalk-node-plugin",
     "signalk-node-server-plugin"
   ],
-  "license": "Apache-2.0",
+  "homepage": "https://github.com/rhizomatics/signalk-bluetti-plugin.git",
+  "bugs": {
+    "url": "https://github.com/rhizomatics/signalk-bluetti-plugin/issues"
+  },
+  "license": "APACHE-2.0",
+  "author": "jey burrows",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rhizomatics/signalk-bluetti-plugin.git"
+  },
   "bin": {
     "bluetti-cli": "cli.js"
   },
@@ -20,7 +29,9 @@
     "index.js",
     "cli.js",
     "lib/",
-    "registers/"
+    "registers/",
+    "README.md",
+    "CHANGELOG.md"
   ],
   "main": "index.js",
   "scripts": {
@@ -28,7 +39,9 @@
     "cli": "node cli.js",
     "fmt": "oxfmt",
     "fmt:check": "oxfmt --check",
-    "lint": "oxlint"
+    "lint": "oxlint",
+    "test": "node --test",
+    "test:coverage": "node --experimental-test-coverage --test-coverage-include=\"lib/**/*.js\" --test-coverage-exclude=\"lib/device.js\" --test-coverage-exclude=\"lib/scanner.js\" --test-coverage-lines=80 --test-coverage-branches=80 --test-coverage-functions=80 --test"
   },
   "dependencies": {
     "@naugehyde/node-ble": "^1.13.5",
@@ -44,7 +57,13 @@
     "signalk-server": "*"
   },
   "signalk": {
-    "displayName": "Bluetti Monitoring"
+    "displayName": "Bluetti Monitoring",
+    "recommends": [
+      "@rhizomatics/signalk-einklabel-plugin"
+    ],
+    "screenshots": [
+      "docs/assets/screenshots/bluetti_data.png"
+    ]
   },
   "signalk-plugin-enabled-by-default": false
 }

package/registers/ac200p.csv

@@ -1,39 +1,47 @@
 # Bluetti register map example — based on AC200P / AC200MAX community reverse-engineering.
 # Replace with your device's actual CSV. Columns the plugin recognises:
 #
-#   field_name       — internal identifier (no spaces)
-#   register_address — Modbus holding register number (decimal)
+#   field_name       — a standard Bluetti register name (see lib/path-mapper.js
+#                       for the ones the code already maps to a SignalK path),
+#                       or any identifier you like if you're supplying signalk_path
+#   register_address — Modbus holding register number (decimal); leave blank
+#                       for a fixed constant_value row instead (e.g. model specs)
 #   register_count   — number of 16-bit registers this field spans (1 for uint16/int16, 2 for int32/float32)
 #   data_type        — uint16 | int16 | uint32 | int32 | float32 | bool
 #   scale            — multiply raw value by this to get physical value
 #   offset           — add after scale (usually 0)
 #   unit             — V | A | W | Wh | % | °C | Hz | min — drives SignalK unit conversion
-#   signalk_path     — full SignalK path; use {name} where the device name goes
+#   signalk_path     — override; only needed for a register the code doesn't
+#                       recognise by field_name. Use {name} where the device name goes
+#   constant_value   — fixed value for a non-register row (register_address blank)
 #
-field_name,register_address,register_count,data_type,scale,offset,unit,signalk_path
+field_name,register_address,register_count,data_type,scale,offset,unit,signalk_path,constant_value
 # ── Battery ────────────────────────────────────────────────────────────────
-battery_percent,100,1,uint16,1,0,%,electrical.batteries.{name}.capacity.stateOfCharge
-battery_voltage,101,1,uint16,0.1,0,V,electrical.batteries.{name}.voltage
-battery_current,102,1,int16,0.1,0,A,electrical.batteries.{name}.current
-battery_power,103,1,int16,1,0,W,electrical.batteries.{name}.power
-battery_temperature,104,1,uint16,0.1,0,°C,electrical.batteries.{name}.temperature
-total_capacity,105,1,uint16,1,0,Wh,electrical.batteries.{name}.capacity.nominal
-remaining_capacity,106,1,uint16,1,0,Wh,electrical.batteries.{name}.capacity.remaining
+battery_percent,100,1,uint16,1,0,%,,
+battery_voltage,101,1,uint16,0.1,0,V,,
+battery_current,102,1,int16,0.1,0,A,,
+battery_power,103,1,int16,1,0,W,,
+battery_temperature,104,1,uint16,0.1,0,°C,,
 # ── DC / Solar input ────────────────────────────────────────────────────────
-dc_input_power,107,1,uint16,1,0,W,electrical.solar.{name}.panelPower
-dc_input_voltage,108,1,uint16,0.1,0,V,electrical.solar.{name}.panelVoltage
-dc_input_current,109,1,uint16,0.1,0,A,electrical.solar.{name}.panelCurrent
+dc_input_power,107,1,uint16,1,0,W,,
+dc_input_voltage,108,1,uint16,0.1,0,V,,
+dc_input_current,109,1,uint16,0.1,0,A,,
 # ── AC output (inverter) ────────────────────────────────────────────────────
-ac_output_power,110,1,uint16,1,0,W,electrical.inverters.{name}.ac.power
-ac_output_voltage,111,1,uint16,0.1,0,V,electrical.inverters.{name}.ac.voltage
-ac_output_current,112,1,uint16,0.1,0,A,electrical.inverters.{name}.ac.current
-ac_output_frequency,113,1,uint16,0.1,0,Hz,electrical.inverters.{name}.ac.frequency
+ac_output_power,110,1,uint16,1,0,W,,
+ac_output_voltage,111,1,uint16,0.1,0,V,,
+ac_output_current,112,1,uint16,0.1,0,A,,
+ac_output_frequency,113,1,uint16,0.1,0,Hz,,
 # ── AC input (charger / mains) ──────────────────────────────────────────────
-ac_input_power,114,1,uint16,1,0,W,electrical.chargers.{name}.input.power
-ac_input_voltage,115,1,uint16,0.1,0,V,electrical.chargers.{name}.input.voltage
-ac_input_current,116,1,uint16,0.1,0,A,electrical.chargers.{name}.input.current
-ac_input_frequency,117,1,uint16,0.1,0,Hz,electrical.chargers.{name}.input.frequency
+ac_input_power,114,1,uint16,1,0,W,,
+ac_input_voltage,115,1,uint16,0.1,0,V,,
+ac_input_current,116,1,uint16,0.1,0,A,,
+ac_input_frequency,117,1,uint16,0.1,0,Hz,,
 # ── Internal temperature ────────────────────────────────────────────────────
-internal_temperature,118,1,uint16,0.1,0,°C,electrical.batteries.{name}.controllerTemperature
+internal_temperature,118,1,uint16,0.1,0,°C,,
 # ── Estimated time remaining ────────────────────────────────────────────────
-time_remaining_minutes,119,1,uint16,1,0,min,electrical.batteries.{name}.capacity.timeRemaining
+time_remaining_minutes,119,1,uint16,1,0,min,,
+# ── Fixed model facts ────────────────────────────────────────────────────────
+battery_chemistry,,,,,,,,LiFePO4
+total_capacity,,,,,,Wh,,2000
+battery_manufacturer_name,,,,,,,,Bluetti
+battery_manufacturer_model,,,,,,,,AC200P

package/registers/el100v2.csv

@@ -4,10 +4,24 @@
 # EL100V2-specific fields: 140, 142, 144, 146, 1314
 # Note: DEVICE_TYPE (110) and DEVICE_SN (116) are string/serial fields — omitted.
 #
-field_name,register_address,register_count,data_type,scale,offset,unit,signalk_path
-battery_soc,102,1,uint16,1,0,%,electrical.batteries.{name}.capacity.stateOfCharge
-dc_output_power,140,1,uint16,1,0,W,electrical.dc.{name}.power
-ac_output_power,142,1,uint16,1,0,W,electrical.inverters.{name}.ac.power
-dc_input_power,144,1,uint16,1,0,W,electrical.solar.{name}.panelPower
-ac_input_power,146,1,uint16,1,0,W,electrical.chargers.{name}.input.power
-ac_input_voltage,1314,1,uint16,0.1,0,V,electrical.chargers.{name}.input.voltage
+# field_name is a standard Bluetti register name — the code maps these to
+# SignalK paths on its own (see lib/path-mapper.js). signalk_path is an
+# override, only needed if you're exposing a register the code doesn't
+# recognise. constant_value is for fixed, non-register facts about this model
+# (register_address left blank for those rows).
+#
+field_name,register_address,register_count,data_type,scale,offset,unit,signalk_path,constant_value
+battery_soc,102,1,uint16,1,0,%,,
+dc_output_power,140,1,uint16,1,0,W,,
+ac_output_power,142,1,uint16,1,0,W,,
+dc_input_power,144,1,uint16,1,0,W,,
+ac_input_power,146,1,uint16,1,0,W,,
+ac_input_voltage,1314,1,uint16,0.1,0,V,,
+# ── Fixed model facts ────────────────────────────────────────────────────────
+battery_chemistry,,,,,,,,LiFePO4
+total_capacity,,,,,,Wh,,1024
+battery_manufacturer_name,,,,,,,,Bluetti
+battery_manufacturer_model,,,,,,,,Elite 100 V2
+# dc_output_power (140) only reports power, not current — this fixed nominal
+# voltage (12V accessory port) is what lib/path-mapper.js derives current from.
+dc_output_voltage,,,,,,V,,12