@rhizomatics/signalk-bluetti-plugin 1.5.0 → 1.5.1

package/CHANGELOG.md

@@ -2,9 +2,15 @@
 
 All notable changes to this plugin are documented here. Format loosely follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [1.5.1]
+
+- Simplify the custom device configuration override
+- 'Register Map' is now 'Device Configuration'
+- Bundled register maps moved from `registers/` to `devices/`
+
 ## [1.5.0]
 
-- Expanded Bluetti model support
+- Expanded Bluetti model support, over 20 now with register mappings
 - Configuration moved from CSV to YAML
 - Configurable directory to add YAML files for unsupported Bluetti models
 - CLI `models` command lists supported register maps with field/constant counts

package/README.md

@@ -73,7 +73,7 @@ node cli.js dump aa:bb:cc:dd:ee:ff --timeout 30   # discovery timeout if device
 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/*.yaml for available models)
+# Decode live registers using a bundled device configuration (see devices/*.yaml 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
 
@@ -86,7 +86,7 @@ node cli.js info aa:bb:cc:dd:ee:ff --registers ac200p --timeout 30   # discovery
 
 ### `models`
 
-List every register map the CLI (and the plugin) can find — bundled ones plus anything dropped into the custom directory (`~/.signalk/bluetti` by default) — with a field and constant count per model. No device connection needed.
+List every device configuration the CLI (and the plugin) can find — bundled ones plus anything dropped into the custom directory (`~/.signalk/bluetti` by default) — with a field and constant count per model. No device connection needed.
 
 ```bash
 node cli.js models
@@ -140,9 +140,9 @@ This tells systemd to start `bluetoothd` first and wait for it before starting S
 
 ### My station isn't supported
 
-Additional products can be added using a YAML file mapping modbus registers and providing static values — see [`docs/examples/model_definition.yaml`](docs/examples/model_definition.yaml) in the repo for an annotated template, and `registers/*.yaml` for real examples.
+Additional products can be added using a YAML file mapping modbus registers and providing static values — see [`docs/examples/model_definition.yaml`](docs/examples/model_definition.yaml) in the repo for an annotated template, and `devices/*.yaml` for real examples.
 
-Drop your file into the plugin's **Custom register maps directory** (a plugin setting, defaulting to `~/.signalk/bluetti`) and it'll appear in the **Register map** dropdown for a device, named after the file (without `.yaml`). A file there takes priority over a bundled one of the same name, so it also doubles as a way to override a built-in map. If you'd rather not touch plugin settings, point a device's **Custom register map YAML path** at the file directly instead — either way works, use whichever is more convenient.
+Drop your file into the plugin's **Custom Device Configuration Directory** (a plugin setting, defaulting to `~/.signalk/bluetti`) and it'll appear in the **Device Configuration** dropdown for a device, named after the file (without `.yaml`). A file there takes priority over a bundled one of the same name, so it also doubles as a way to override a built-in map.
 
 Check one of these projects to see if some of the mapping work has been done:
 

package/cli.js

@@ -5,11 +5,11 @@ const fs = require("fs");
 const os = require("os");
 const path = require("path");
 
-const REGISTERS_DIR = path.join(__dirname, "registers");
+const DEVICES_DIR = path.join(__dirname, "devices");
 // Same default the plugin itself uses when running under a real SignalK
 // server (see index.js) — lets a user's custom register maps be found by the
 // CLI too, without needing to pass --registers-dir.
-const DEFAULT_USER_REGISTERS_DIR = path.join(os.homedir(), ".signalk", "bluetti");
+const DEFAULT_USER_DEVICES_DIR = path.join(os.homedir(), ".signalk", "bluetti");
 
 function listModels(dir) {
   try {
@@ -24,7 +24,7 @@ function listModels(dir) {
 }
 
 function listBuiltinModels() {
-  return [...new Set([...listModels(REGISTERS_DIR), ...listModels(DEFAULT_USER_REGISTERS_DIR)])].sort((a, b) => a.localeCompare(b));
+  return [...new Set([...listModels(DEVICES_DIR), ...listModels(DEFAULT_USER_DEVICES_DIR)])].sort((a, b) => a.localeCompare(b));
 }
 
 // One row per model, checking the custom directory before the bundled one so
@@ -35,8 +35,8 @@ function listModelDetails() {
 
   return listBuiltinModels().map((model) => {
     for (const [dir, source] of [
-      [DEFAULT_USER_REGISTERS_DIR, "custom"],
-      [REGISTERS_DIR, "built-in"],
+      [DEFAULT_USER_DEVICES_DIR, "custom"],
+      [DEVICES_DIR, "built-in"],
     ]) {
       for (const ext of [".yaml", ".yml"]) {
         const p = path.join(dir, `${model}${ext}`);
@@ -79,12 +79,12 @@ Commands:
                                 Bluetti device found.
     --registers <model|path>     Built-in model (${builtins.join(", ") || "none bundled"}) or a register map
                                   YAML path (required). Also checks
-                                  ${DEFAULT_USER_REGISTERS_DIR} for custom models.
+                                  ${DEFAULT_USER_DEVICES_DIR} for custom models.
     --encryption-key <path>      Path to the Bluetti-provided encryption CSV
                                   (only needed for legacy XOR-scrambled models)
     --timeout <seconds>          Discovery/scan timeout if not already known (default: 20)
 
-  models                       List supported register maps, with a field and
+  models                       List supported device configurations, with a field and
                                 constant count per model
 
   help                         Show this help
@@ -180,7 +180,7 @@ async function findDevice(adapter, mac, timeoutMs) {
 }
 
 function resolveRegistersArg(value) {
-  for (const dir of [DEFAULT_USER_REGISTERS_DIR, REGISTERS_DIR]) {
+  for (const dir of [DEFAULT_USER_DEVICES_DIR, DEVICES_DIR]) {
     for (const ext of [".yaml", ".yml"]) {
       const p = path.join(dir, `${value}${ext}`);
       if (fs.existsSync(p)) return p;
@@ -188,7 +188,7 @@ function resolveRegistersArg(value) {
   }
   if (fs.existsSync(value)) return value;
   const builtins = listBuiltinModels();
-  throw new Error(`Register map not found: "${value}" (not a built-in model [${builtins.join(", ")}] or an existing file path)`);
+  throw new Error(`Device configuration not found: "${value}" (not a built-in model [${builtins.join(", ")}] or an existing file path)`);
 }
 
 async function printDeviceSummary(bleDevice, mac) {
@@ -406,7 +406,7 @@ async function cmdInfo(args) {
 function cmdModels() {
   const rows = listModelDetails();
   if (rows.length === 0) {
-    console.log(`No register maps found (checked ${REGISTERS_DIR} and ${DEFAULT_USER_REGISTERS_DIR}).`);
+    console.log(`No device configurations found (checked ${DEVICES_DIR} and ${DEFAULT_USER_DEVICES_DIR}).`);
     return;
   }
   printTable(rows, ["model", "fields", "constants", "source"]);

package/index.js

@@ -5,7 +5,7 @@ const path = require("path");
 const fs = require("fs");
 
 const PLUGIN_ID = "signalk-bluetti-plugin";
-const REGISTERS_DIR = path.join(__dirname, "registers");
+const DEVICES_DIR = path.join(__dirname, "devices");
 
 // Bluetti device BLE name prefixes (mirrors scanner.js).
 const BLUETTI_PREFIXES = ["BT-TH-", "BLUETTI", "AC", "EP", "EB", "EL", "PR", "AP"];
@@ -38,7 +38,7 @@ function yamlModelNames(dir) {
   }
 }
 
-// The directory a user can drop their own register map YAML files into,
+// The directory a user can drop their own device configuration YAML files into,
 // without needing to fork/publish the plugin — defaults to a `bluetti`
 // subdirectory of the SignalK home directory (e.g. ~/.signalk/bluetti).
 // `app.config.configPath` isn't part of the documented plugin API but is the
@@ -57,7 +57,7 @@ module.exports = function (app) {
   let waitingStatusTimer = null;
 
   const defaultUserDir = defaultUserRegistersDir(app);
-  const builtins = yamlModelNames(REGISTERS_DIR);
+  const builtins = yamlModelNames(DEVICES_DIR);
   // Models available for the dropdown at schema-render time — bundled plus
   // whatever's already sitting in the default user directory. If `registersDir`
   // is overridden away from the default, models unique to that directory won't
@@ -83,13 +83,13 @@ module.exports = function (app) {
       scanOnStart: {
         type: "boolean",
         title: "Scan for new devices on plugin start",
-        description: "Runs a 15-second BLE scan and logs discovered Bluetti devices. Useful for finding device addresses.",
+        description: "Runs a short BLE scan and logs discovered Bluetti devices. Useful for finding device addresses.",
         default: true,
       },
       registersDir: {
         type: "string",
-        title: "Custom register maps directory",
-        description: `Directory to scan for your own register map YAML files (e.g. for a model this plugin doesn't bundle yet), in addition to the ones built in. Leave blank to use the default: ${defaultUserDir || "<SignalK home>/bluetti"}.`,
+        title: "Custom Device Configuration Directory",
+        description: `Directory to scan for your own device configuration YAML files (e.g. for a model this plugin doesn't bundle yet), in addition to the ones built in. Leave blank to use the default: ${defaultUserDir || "<SignalK home>/bluetti"}.`,
         default: "",
       },
       devices: {
@@ -117,17 +117,11 @@ module.exports = function (app) {
             },
             builtinModel: {
               type: "string",
-              title: "Register map",
+              title: "Device Configuration",
               description:
-                'Select a register map for your device model — bundled with the plugin, or dropped into the custom register maps directory above — or "custom" to supply an explicit YAML file path below.',
-              enum: ["custom", ...allModels],
-              default: allModels.length > 0 ? allModels[0] : "custom",
-            },
-            registerMapPath: {
-              type: "string",
-              title: "Custom register map YAML path",
-              description: 'Absolute path to a register map YAML file. Only used when "custom" is selected above.',
-              default: "",
+                "Select a device configuration for your model — bundled with the plugin, or dropped into the custom device configuration directory above.",
+              enum: allModels,
+              default: allModels.length > 0 ? allModels[0] : "",
             },
             encryptionCsvPath: {
               type: "string",
@@ -154,7 +148,6 @@ module.exports = function (app) {
       items: {
         address: { "ui:placeholder": "aa:bb:cc:dd:ee:ff" },
         name: { "ui:placeholder": "house" },
-        registerMapPath: { "ui:placeholder": "e.g. /path/to/my-device-registers.yaml" },
         encryptionCsvPath: { "ui:placeholder": "e.g. /path/to/19e1646709e0421b755fa9dda74.csv" },
       },
     },
@@ -180,7 +173,7 @@ module.exports = function (app) {
       try {
         fs.mkdirSync(userRegistersDir, { recursive: true });
       } catch (err) {
-        log(`Could not create custom register maps directory "${userRegistersDir}": ${err.message}`);
+        log(`Could not create custom device configuration directory "${userRegistersDir}": ${err.message}`);
       }
     }
 
@@ -298,7 +291,7 @@ module.exports = function (app) {
   // Finds <model>.yaml (or .yml), checking the custom directory before the
   // bundled one so a user's own file can override a built-in of the same name.
   function findModelFile(model, userRegistersDir) {
-    const dirs = [userRegistersDir, REGISTERS_DIR].filter(Boolean);
+    const dirs = [userRegistersDir, DEVICES_DIR].filter(Boolean);
     for (const dir of dirs) {
       for (const ext of [".yaml", ".yml"]) {
         const p = path.join(dir, `${model}${ext}`);
@@ -309,15 +302,12 @@ module.exports = function (app) {
   }
 
   function resolveRegisterMapPath(cfg, userRegistersDir) {
-    const { builtinModel, registerMapPath } = cfg;
-    if (!builtinModel || builtinModel === "custom") {
-      if (!registerMapPath) throw new Error("No register map: select a model or provide a custom YAML path");
-      return registerMapPath;
-    }
+    const { builtinModel } = cfg;
+    if (!builtinModel) throw new Error("No device configuration: select a model");
     const found = findModelFile(builtinModel, userRegistersDir);
     if (!found)
       throw new Error(
-        `Register map "${builtinModel}" not found (checked ${userRegistersDir ? `${userRegistersDir} and ` : ""}${REGISTERS_DIR})`,
+        `Device configuration "${builtinModel}" not found (checked ${userRegistersDir ? `${userRegistersDir} and ` : ""}${DEVICES_DIR})`,
       );
     return found;
   }
@@ -339,7 +329,7 @@ module.exports = function (app) {
       fields = loadRegisters(registerPath);
       log(`[${name}] Loaded ${fields.length} registers from ${registerPath}`);
     } catch (err) {
-      app.setPluginError(`[${name}] Failed to load register map "${registerPath}": ${err.message}`);
+      app.setPluginError(`[${name}] Failed to load device configuration "${registerPath}": ${err.message}`);
       return;
     }
 

package/lib/path-mapper.js

@@ -216,7 +216,7 @@ function buildDelta(registers, fields, deviceName, source, opts = {}) {
 
   // 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/*.yaml)
+  // on every model; deriving it from a fixed nominal spec (see devices/*.yaml)
   // 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")) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhizomatics/signalk-bluetti-plugin",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "SignalK plugin for Bluetti power station monitoring via Bluetooth LE. Comes with configuration for 20+ models.",
   "keywords": [
     "battery",
@@ -35,7 +35,7 @@
     "lib/",
     "docs/assets/",
     "docs/examples/",
-    "registers/",
+    "devices/",
     "README.md",
     "CHANGELOG.md"
   ],