@rhizomatics/signalk-bluetti-plugin 1.4.1 → 1.5.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this plugin are documented here. Format loosely follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [1.5.0]
+
+- Expanded Bluetti model support
+- 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
+
 ## [1.4.1]
 
 - Basic test suite

package/README.md

@@ -6,7 +6,7 @@
 ![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
+A SignalK plugin to display data from Bluetti power stations over a Bluetooth Low Energy (BLE) connection. Supports 20+ stations, extensible by configuration. Also offers a CLI for easier exploring and debugging.
 
 ![Example Data](docs/assets/screenshots/bluetti_data.png)
 
@@ -73,19 +73,44 @@ 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/*.csv for available models)
+# Decode live registers using a bundled register map (see registers/*.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
 
-# Or a custom CSV, plus an encryption key file for legacy models that XOR-scramble frames
+# Or a custom YAML, 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)
-node cli.js info aa:bb:cc:dd:ee:ff --registers ./my-device-registers.csv --encryption-key ~/19e1646709e0421b755fa9dda74.csv
+node cli.js info aa:bb:cc:dd:ee:ff --registers ./my-device-registers.yaml --encryption-key ~/19e1646709e0421b755fa9dda74.csv
 
 node cli.js info aa:bb:cc:dd:ee:ff --registers ac200p --timeout 30   # discovery timeout if device isn't already known to BlueZ (default: 20)
 ```
 
+### `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.
+
+```bash
+node cli.js models
+```
+
 ## FAQ
 
+### Capacity figures show in Joules, how do I make it useful?
+
+SignalK stores all data in SI units rather than any customary units used anywhere, for example temperatures are all held in Kelvin and unit preferences allow them to be converted in the display to C or F.
+
+Unfortunately the default sets of preset unit preferences don't include the `energy` category used for capacity and more unfortunately as of SignalK v2.30.0 there's no easy way to override individual paths.
+
+The fiddly way to do it should be as below (however there's a current [misconfiguration](https://github.com/SignalK/signalk-server/issues/2878) in the SignalK code which gets in the way):
+
+1. Download your preferred set of unit preferences from the [SignalK repo](https://github.com/SignalK/signalk-server/tree/ac368c548fba923db0acf8a314cbdc6552b2b8cf/unitpreferences/presets)
+2. Edit the downloaded file
+
+- Change the `targetUnit` of `energy` category to `Wh`
+- Change the `name` at the top of the file to reflect the change, for example `"Nautical (Metric, Wh capacity)"`
+
+3. Go to the _Unit Preferences_ section of the _Data_ menu in SignalK
+4. Use the _Upload_ button to upload your amended preferences preset and select it in the preset dropdown
+
 ### SignalK starts before the Bluetooth daemon — does the plugin need `bluetoothd` running at boot?
 
 The plugin retries BLE adapter initialisation with backoff (starting at 2s, capping at 30s) if `bluetoothd`/D-Bus isn't up yet when the plugin starts, so a slow-starting Bluetooth stack on boot will no longer strand it — it keeps retrying until the adapter appears rather than failing once and giving up. You'll see `BLE adapter not ready … — retrying in Ns …` in the SignalK logs in the meantime.
@@ -112,3 +137,14 @@ sudo systemctl restart signalk
 ```
 
 This tells systemd to start `bluetoothd` first and wait for it before starting SignalK, rather than relying on both racing to start in parallel at boot.
+
+### 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.
+
+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.
+
+Check one of these projects to see if some of the mapping work has been done:
+
+- https://github.com/Patrick762/bluetti-bt-lib
+- https://github.com/warhammerkid/bluetti_mqtt

package/cli.js

@@ -2,22 +2,58 @@
 "use strict";
 
 const fs = require("fs");
+const os = require("os");
 const path = require("path");
 
 const REGISTERS_DIR = path.join(__dirname, "registers");
+// 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");
 
-function listBuiltinModels() {
+function listModels(dir) {
   try {
     return fs
-      .readdirSync(REGISTERS_DIR)
-      .filter((f) => f.endsWith(".csv"))
-      .map((f) => f.replace(/\.csv$/, ""))
+      .readdirSync(dir)
+      .filter((f) => /\.ya?ml$/.test(f))
+      .map((f) => f.replace(/\.ya?ml$/, ""))
       .sort();
   } catch {
     return [];
   }
 }
 
+function listBuiltinModels() {
+  return [...new Set([...listModels(REGISTERS_DIR), ...listModels(DEFAULT_USER_REGISTERS_DIR)])].sort((a, b) => a.localeCompare(b));
+}
+
+// One row per model, checking the custom directory before the bundled one so
+// a user's own file overriding a built-in shows up as "custom" — same
+// resolution order as resolveRegistersArg()/the plugin itself.
+function listModelDetails() {
+  const { loadRegisters } = require("./lib/register-loader");
+
+  return listBuiltinModels().map((model) => {
+    for (const [dir, source] of [
+      [DEFAULT_USER_REGISTERS_DIR, "custom"],
+      [REGISTERS_DIR, "built-in"],
+    ]) {
+      for (const ext of [".yaml", ".yml"]) {
+        const p = path.join(dir, `${model}${ext}`);
+        if (!fs.existsSync(p)) continue;
+        try {
+          const fields = loadRegisters(p);
+          const constants = fields.filter((f) => f.dataType === "const").length;
+          return { model, fields: fields.length - constants, constants, source, path: p };
+        } catch (err) {
+          return { model, fields: "?", constants: "?", source, path: `${p} (failed to load: ${err.message})` };
+        }
+      }
+    }
+    return { model, fields: "?", constants: "?", source: "?", path: "" };
+  });
+}
+
 function usage() {
   const builtins = listBuiltinModels();
   console.log(`
@@ -41,11 +77,16 @@ Commands:
                                 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)
+    --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.
     --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
+                                constant count per model
+
   help                         Show this help
 
 Examples:
@@ -55,6 +96,7 @@ Examples:
   bluetti-cli dump
   bluetti-cli info aa:bb:cc:dd:ee:ff --registers ac200p
   bluetti-cli info --registers ac200p
+  bluetti-cli models
 `);
 }
 
@@ -138,8 +180,12 @@ async function findDevice(adapter, mac, timeoutMs) {
 }
 
 function resolveRegistersArg(value) {
-  const builtinPath = path.join(REGISTERS_DIR, `${value}.csv`);
-  if (fs.existsSync(builtinPath)) return builtinPath;
+  for (const dir of [DEFAULT_USER_REGISTERS_DIR, REGISTERS_DIR]) {
+    for (const ext of [".yaml", ".yml"]) {
+      const p = path.join(dir, `${value}${ext}`);
+      if (fs.existsSync(p)) return p;
+    }
+  }
   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)`);
@@ -212,14 +258,14 @@ async function printGattTree(bleDevice) {
 }
 
 async function printRegisterValues(bleDevice, mac, args) {
-  const { loadCsv, decodeValue } = require("./lib/csv-loader");
+  const { loadRegisters, decodeValue } = require("./lib/register-loader");
   const { resolvePath, convertUnits } = require("./lib/path-mapper");
   const { readEncryptionKey } = require("./lib/encryption");
   const { groupRegisters } = require("./lib/protocol");
   const BluettiDevice = require("./lib/device");
 
   const registerPath = resolveRegistersArg(args.registers);
-  const fields = loadCsv(registerPath);
+  const fields = loadRegisters(registerPath);
   console.log(`\nLoaded ${fields.length} register field(s) from ${registerPath}`);
 
   const addrs = [...new Set(fields.flatMap((f) => Array.from({ length: f.count }, (_, i) => f.register + i)))];
@@ -355,6 +401,17 @@ async function cmdInfo(args) {
   );
 }
 
+// ── models ───────────────────────────────────────────────────────────────
+
+function cmdModels() {
+  const rows = listModelDetails();
+  if (rows.length === 0) {
+    console.log(`No register maps found (checked ${REGISTERS_DIR} and ${DEFAULT_USER_REGISTERS_DIR}).`);
+    return;
+  }
+  printTable(rows, ["model", "fields", "constants", "source"]);
+}
+
 // ── main ─────────────────────────────────────────────────────────────────
 
 async function main() {
@@ -371,6 +428,9 @@ async function main() {
     case "info":
       await cmdInfo(args);
       break;
+    case "models":
+      cmdModels();
+      break;
     case "help":
     case "--help":
     case "-h":

package/docs/assets/icon.svg

@@ -0,0 +1,36 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" width="256" height="256">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#0f4c5c"/>
+      <stop offset="1" stop-color="#093542"/>
+    </linearGradient>
+    <linearGradient id="body" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#f4f6f7"/>
+      <stop offset="1" stop-color="#d7dde0"/>
+    </linearGradient>
+  </defs>
+
+  <!-- app icon background -->
+  <rect x="0" y="0" width="256" height="256" rx="48" fill="url(#bg)"/>
+
+  <!-- power station body -->
+  <rect x="56" y="58" width="144" height="132" rx="14" fill="url(#body)" stroke="#093542" stroke-width="4"/>
+
+  <!-- display -->
+  <rect x="74" y="74" width="56" height="34" rx="6" fill="#0f4c5c"/>
+  <!-- battery glyph inside display -->
+  <rect x="82" y="85" width="30" height="12" rx="2" fill="none" stroke="#7fd8c4" stroke-width="2.5"/>
+  <rect x="113" y="88.5" width="4" height="5" fill="#7fd8c4"/>
+  <rect x="85" y="88" width="18" height="6" fill="#7fd8c4"/>
+
+  <!-- lightning bolt -->
+  <path d="M156 72 L138 104 h14 l-6 30 26 -38 h-15 z" fill="#f4a340" stroke="#093542" stroke-width="3" stroke-linejoin="round"/>
+
+  <!-- ports along the bottom edge -->
+  <circle cx="80" cy="166" r="10" fill="none" stroke="#093542" stroke-width="4"/>
+  <circle cx="80" cy="166" r="3.5" fill="#093542"/>
+  <rect x="106" y="158" width="20" height="16" rx="3" fill="none" stroke="#093542" stroke-width="4"/>
+  <rect x="142" y="156" width="26" height="20" rx="3" fill="none" stroke="#093542" stroke-width="4"/>
+  <rect x="150" y="162" width="3.5" height="8" fill="#093542"/>
+  <rect x="157" y="162" width="3.5" height="8" fill="#093542"/>
+</svg>

package/docs/examples/model_definition.yaml

@@ -0,0 +1,112 @@
+# Example register map for a Bluetti device this plugin doesn't bundle yet.
+#
+# Drop a copy of this file (renamed, e.g. my-device.yaml) into your custom
+# register maps directory — see the plugin's "Custom register maps directory"
+# setting, which defaults to <SignalK home>/bluetti (e.g. ~/.signalk/bluetti)
+# — and it'll show up in the "Register map" dropdown for a device, keyed by
+# its filename (without .yaml).
+#
+# Two top-level keys:
+#
+#   fields:    one entry per live Modbus holding register on the device.
+#              The key is the field name; standard names (see lib/path-mapper.js's
+#              STANDARD_FIELD_PATHS) are resolved to a SignalK path automatically —
+#              use whichever of these match what your device actually reports.
+#              Any other name gets a best-effort guess, or set `path:` explicitly.
+#
+#     <field_name>:
+#       register: <number>     # Modbus holding register address (required)
+#       type: uint16            # uint16 (default) | int16 | uint32 | int32 | float32 | bool
+#       count: <number>         # registers this field spans; inferred from `type` if omitted
+#       scale: <number>         # multiply the raw value by this (default 1)
+#       offset: <number>        # add after scaling (default 0)
+#       unit: V                 # V | A | W | Wh | kWh | % | °C | Hz | min — drives SignalK unit conversion
+#       path: electrical.batteries.{name}.voltage   # optional override; {name} is the per-device name from config
+#
+#   constants: fixed, non-register facts about this model — a bare scalar
+#              (string or number) or, for a number that needs unit conversion
+#              (e.g. a capacity in Wh), an expanded { value, unit } form.
+#
+# Standard field names worth knowing: battery_soc, battery_voltage,
+# battery_current, battery_power, battery_temperature, dc_input_power/voltage/current
+# (solar), ac_output_power/voltage/current/frequency (inverter), ac_input_power/
+# voltage/current/frequency (mains charger), time_remaining_minutes,
+# total_capacity, battery_chemistry, battery_manufacturer_name, battery_manufacturer_model.
+
+fields:
+  battery_percent:
+    register: 100
+    unit: "%"
+  battery_voltage:
+    register: 101
+    scale: 0.1
+    unit: V
+  battery_current:
+    register: 102
+    type: int16
+    scale: 0.1
+    unit: A
+  battery_power:
+    register: 103
+    type: int16
+    unit: W
+  battery_temperature:
+    register: 104
+    scale: 0.1
+    unit: "°C"
+  dc_input_power:
+    register: 107
+    unit: W
+  dc_input_voltage:
+    register: 108
+    scale: 0.1
+    unit: V
+  dc_input_current:
+    register: 109
+    scale: 0.1
+    unit: A
+  ac_output_power:
+    register: 110
+    unit: W
+  ac_output_voltage:
+    register: 111
+    scale: 0.1
+    unit: V
+  ac_output_current:
+    register: 112
+    scale: 0.1
+    unit: A
+  ac_output_frequency:
+    register: 113
+    scale: 0.1
+    unit: Hz
+  ac_input_power:
+    register: 114
+    unit: W
+  ac_input_voltage:
+    register: 115
+    scale: 0.1
+    unit: V
+  ac_input_current:
+    register: 116
+    scale: 0.1
+    unit: A
+  ac_input_frequency:
+    register: 117
+    scale: 0.1
+    unit: Hz
+  internal_temperature:
+    register: 118
+    scale: 0.1
+    unit: "°C"
+  time_remaining_minutes:
+    register: 119
+    unit: min
+
+constants:
+  battery_chemistry: LiFePO4
+  battery_manufacturer_name: Bluetti
+  battery_manufacturer_model: My Device
+  total_capacity:
+    value: 2000
+    unit: Wh

package/index.js

@@ -8,7 +8,7 @@ const PLUGIN_ID = "signalk-bluetti-plugin";
 const REGISTERS_DIR = path.join(__dirname, "registers");
 
 // Bluetti device BLE name prefixes (mirrors scanner.js).
-const BLUETTI_PREFIXES = ["BT-TH-", "BLUETTI", "AC", "EP", "EB", "EL"];
+const BLUETTI_PREFIXES = ["BT-TH-", "BLUETTI", "AC", "EP", "EB", "EL", "PR", "AP"];
 
 // Search $HOME for exactly one CSV whose stem looks like a Bluetti device ID.
 // Returns the full path if exactly one match, empty string otherwise.
@@ -26,18 +26,28 @@ function findBluettiEncryptionCsvInHome() {
   }
 }
 
-function builtinModelNames() {
+function yamlModelNames(dir) {
   try {
     return fs
-      .readdirSync(REGISTERS_DIR)
-      .filter((f) => f.endsWith(".csv"))
-      .map((f) => f.replace(/\.csv$/, ""))
+      .readdirSync(dir)
+      .filter((f) => /\.ya?ml$/.test(f))
+      .map((f) => f.replace(/\.ya?ml$/, ""))
       .sort();
   } catch {
     return [];
   }
 }
 
+// The directory a user can drop their own register map 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
+// long-established way plugins locate the SignalK home directory.
+function defaultUserRegistersDir(app) {
+  const home = app && app.config && app.config.configPath;
+  return home ? path.join(home, "bluetti") : null;
+}
+
 module.exports = function (app) {
   const log = (msg) => app.debug(msg);
 
@@ -46,7 +56,15 @@ module.exports = function (app) {
   let scanResultCache = [];
   let waitingStatusTimer = null;
 
-  const builtins = builtinModelNames();
+  const defaultUserDir = defaultUserRegistersDir(app);
+  const builtins = yamlModelNames(REGISTERS_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
+  // appear here until the plugin restarts with the new setting saved.
+  const allModels = [...new Set([...builtins, ...(defaultUserDir ? yamlModelNames(defaultUserDir) : [])])].sort((a, b) =>
+    a.localeCompare(b),
+  );
 
   // ── Plugin metadata ────────────────────────────────────────────────────
 
@@ -68,6 +86,12 @@ module.exports = function (app) {
         description: "Runs a 15-second 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"}.`,
+        default: "",
+      },
       devices: {
         type: "array",
         title: "Devices",
@@ -93,15 +117,16 @@ module.exports = function (app) {
             },
             builtinModel: {
               type: "string",
-              title: "Built-in register map",
-              description: 'Select a bundled register map for your device model, or "custom" to supply your own CSV path below.',
-              enum: ["custom", ...builtins],
-              default: builtins.length > 0 ? builtins[0] : "custom",
+              title: "Register map",
+              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",
             },
-            csvPath: {
+            registerMapPath: {
               type: "string",
-              title: "Custom register map CSV path",
-              description: 'Absolute path to a register definition CSV. Only used when "custom" is selected above.',
+              title: "Custom register map YAML path",
+              description: 'Absolute path to a register map YAML file. Only used when "custom" is selected above.',
               default: "",
             },
             encryptionCsvPath: {
@@ -124,11 +149,12 @@ module.exports = function (app) {
   };
 
   plugin.uiSchema = {
+    registersDir: { "ui:placeholder": defaultUserDir || "e.g. /home/pi/.signalk/bluetti" },
     devices: {
       items: {
         address: { "ui:placeholder": "aa:bb:cc:dd:ee:ff" },
         name: { "ui:placeholder": "house" },
-        csvPath: { "ui:placeholder": "e.g. /path/to/my-device-registers.csv" },
+        registerMapPath: { "ui:placeholder": "e.g. /path/to/my-device-registers.yaml" },
         encryptionCsvPath: { "ui:placeholder": "e.g. /path/to/19e1646709e0421b755fa9dda74.csv" },
       },
     },
@@ -137,11 +163,11 @@ module.exports = function (app) {
   // ── Start ──────────────────────────────────────────────────────────────
 
   plugin.start = function (options) {
-    let Scanner, BluettiDevice, loadCsv, buildDelta, readEncryptionKey;
+    let Scanner, BluettiDevice, loadRegisters, buildDelta, readEncryptionKey;
     try {
       Scanner = require("./lib/scanner");
       BluettiDevice = require("./lib/device");
-      ({ loadCsv } = require("./lib/csv-loader"));
+      ({ loadRegisters } = require("./lib/register-loader"));
       ({ buildDelta } = require("./lib/path-mapper"));
       ({ readEncryptionKey } = require("./lib/encryption"));
     } catch (err) {
@@ -149,6 +175,15 @@ module.exports = function (app) {
       return;
     }
 
+    const userRegistersDir = options.registersDir || defaultUserDir;
+    if (userRegistersDir) {
+      try {
+        fs.mkdirSync(userRegistersDir, { recursive: true });
+      } catch (err) {
+        log(`Could not create custom register maps directory "${userRegistersDir}": ${err.message}`);
+      }
+    }
+
     scanner = new Scanner(log);
 
     const devices = (options.devices || []).filter((d) => d.enabled !== false);
@@ -185,7 +220,7 @@ module.exports = function (app) {
     // Build address → cfg lookup (normalise to lowercase, no colons)
     const normalise = (addr) => addr.toLowerCase().replace(/:/g, "");
     const pending = new Map(devices.map((cfg) => [normalise(cfg.address), cfg]));
-    const deps = { BluettiDevice, loadCsv, buildDelta, readEncryptionKey };
+    const deps = { BluettiDevice, loadRegisters, buildDelta, readEncryptionKey, userRegistersDir };
 
     scanner.on("discovered", ({ address, name, device: bleDevice }) => {
       scanResultCache.push({ address, name });
@@ -260,22 +295,40 @@ module.exports = function (app) {
     return null;
   }
 
-  function resolveRegisterMapPath(cfg) {
-    const { builtinModel, csvPath } = cfg;
+  // 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);
+    for (const dir of dirs) {
+      for (const ext of [".yaml", ".yml"]) {
+        const p = path.join(dir, `${model}${ext}`);
+        if (fs.existsSync(p)) return p;
+      }
+    }
+    return null;
+  }
+
+  function resolveRegisterMapPath(cfg, userRegistersDir) {
+    const { builtinModel, registerMapPath } = cfg;
     if (!builtinModel || builtinModel === "custom") {
-      if (!csvPath) throw new Error("No register map: select a built-in model or provide a custom CSV path");
-      return csvPath;
+      if (!registerMapPath) throw new Error("No register map: select a model or provide a custom YAML path");
+      return registerMapPath;
     }
-    return path.join(REGISTERS_DIR, `${builtinModel}.csv`);
+    const found = findModelFile(builtinModel, userRegistersDir);
+    if (!found)
+      throw new Error(
+        `Register map "${builtinModel}" not found (checked ${userRegistersDir ? `${userRegistersDir} and ` : ""}${REGISTERS_DIR})`,
+      );
+    return found;
   }
 
-  function startDevice(cfg, bleDevice, bleName, { BluettiDevice, loadCsv, buildDelta, readEncryptionKey }) {
+  function startDevice(cfg, bleDevice, bleName, { BluettiDevice, loadRegisters, buildDelta, readEncryptionKey, userRegistersDir }) {
     const { address, name, encryptionCsvPath = "", pollIntervalSeconds = 10 } = cfg;
     const registerCache = new Map(); // last-known value per field_name, across polls — see buildDelta
 
     let registerPath;
     try {
-      registerPath = resolveRegisterMapPath(cfg);
+      registerPath = resolveRegisterMapPath(cfg, userRegistersDir);
     } catch (err) {
       app.setPluginError(`[${name}] ${err.message}`);
       return;
@@ -283,7 +336,7 @@ module.exports = function (app) {
 
     let fields;
     try {
-      fields = loadCsv(registerPath);
+      fields = loadRegisters(registerPath);
       log(`[${name}] Loaded ${fields.length} registers from ${registerPath}`);
     } catch (err) {
       app.setPluginError(`[${name}] Failed to load register map "${registerPath}": ${err.message}`);