@rhizomatics/signalk-bluetti-plugin 1.0.1-alpha

package/.claude/settings.local.json

@@ -0,0 +1,14 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python3 -c \"import json,sys; d=json.load\\(sys.stdin\\); print\\('engines' in d, 'signalk' in d\\)\")",
+      "Bash(node -e \"const p = require\\('/Users/jey/Code/sailing/signalk-bluetti-plugin/package.json'\\); console.log\\(JSON.stringify\\(p, null, 2\\)\\)\")",
+      "Read(//usr/local/lib/**)",
+      "Bash(npm ls *)",
+      "Bash(mkdir -p /Users/jey/Code/sailing/signalk-bluetti-plugin/registers)"
+    ],
+    "additionalDirectories": [
+      "/Users/jey/Code/sailing/signalk-bluetti-plugin"
+    ]
+  }
+}

package/index.js

@@ -0,0 +1,300 @@
+'use strict';
+
+const os   = require('os');
+const path = require('path');
+const fs   = require('fs');
+
+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'];
+
+// 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.
+function findBluettiEncryptionCsvInHome() {
+  try {
+    const homeDir = os.homedir();
+    const matches = fs.readdirSync(homeDir).filter(f => {
+      if (!f.toLowerCase().endsWith('.csv')) return false;
+      const stem = f.slice(0, -4).toUpperCase();
+      return BLUETTI_PREFIXES.some(p => stem.startsWith(p));
+    });
+    return matches.length === 1 ? path.join(os.homedir(), matches[0]) : '';
+  } catch (_) {
+    return '';
+  }
+}
+
+function builtinModelNames() {
+  try {
+    return fs.readdirSync(REGISTERS_DIR)
+      .filter(f => f.endsWith('.csv'))
+      .map(f => f.replace(/\.csv$/, ''))
+      .sort();
+  } catch (_) {
+    return [];
+  }
+}
+
+module.exports = function (app) {
+  const log = (msg) => app.debug(msg);
+
+  let scanner       = null;
+  let activeDevices = [];
+  let scanResultCache = [];
+
+  const builtins = builtinModelNames();
+
+  // ── Plugin metadata ────────────────────────────────────────────────────
+
+  const plugin = {
+    id:          PLUGIN_ID,
+    name:        'Bluetti Power Station (BLE)',
+    description: 'Monitors Bluetti power devices via Bluetooth LE and publishes to electrical.* paths',
+  };
+
+  // ── Config schema ──────────────────────────────────────────────────────
+
+  plugin.schema = {
+    type: 'object',
+    required: [],
+    properties: {
+      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.',
+        default: true,
+      },
+      devices: {
+        type: 'array',
+        title: 'Devices',
+        description: 'One entry per Bluetti device you want to monitor.',
+        items: {
+          type: 'object',
+          required: ['address', 'name'],
+          properties: {
+            enabled: {
+              type: 'boolean',
+              title: 'Enabled',
+              default: true,
+            },
+            address: {
+              type: 'string',
+              title: 'BLE MAC address',
+              description: 'e.g. aa:bb:cc:dd:ee:ff  — run a scan to find this',
+            },
+            name: {
+              type: 'string',
+              title: 'Device name (used in SignalK path)',
+              description: 'e.g. "house" → electrical.batteries.house.voltage',
+            },
+            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',
+            },
+            csvPath: {
+              type: 'string',
+              title: 'Custom register map CSV path',
+              description: 'Absolute path to a register definition CSV. Only used when "custom" is selected above.',
+              default: '',
+            },
+            encryptionCsvPath: {
+              type: 'string',
+              title: 'Bluetti encryption CSV path (optional)',
+              description: 'Path to the encrypted CSV file provided by Bluetti for your device. Leave blank for unencrypted devices.',
+              default: findBluettiEncryptionCsvInHome(),
+            },
+            pollIntervalSeconds: {
+              type: 'number',
+              title: 'Poll interval (seconds)',
+              default: 10,
+              minimum: 2,
+            },
+          },
+        },
+        default: [],
+      },
+    },
+  };
+
+  plugin.uiSchema = {
+    devices: {
+      items: {
+        address:           { 'ui:placeholder': 'aa:bb:cc:dd:ee:ff' },
+        name:              { 'ui:placeholder': 'house' },
+        csvPath:           { 'ui:placeholder': '/home/pi/my-device-registers.csv' },
+        encryptionCsvPath: { 'ui:placeholder': '/home/pi/19e1646709e0421b755fa9dda74.csv' },
+      },
+    },
+  };
+
+  // ── Start ──────────────────────────────────────────────────────────────
+
+  plugin.start = function (options) {
+    let Scanner, BluettiDevice, loadCsv, buildDelta, readEncryptionKey;
+    try {
+      Scanner              = require('./lib/scanner');
+      BluettiDevice        = require('./lib/device');
+      ({ loadCsv }         = require('./lib/csv-loader'));
+      ({ buildDelta }      = require('./lib/path-mapper'));
+      ({ readEncryptionKey } = require('./lib/encryption'));
+    } catch (err) {
+      app.setPluginError(`Dependency load failed: ${err.message}. Run: npm install inside the plugin directory.`);
+      return;
+    }
+
+    scanner = new Scanner(log);
+
+    const devices = (options.devices || []).filter(d => d.enabled !== false);
+
+    if (devices.length === 0) {
+      // Discovery-only mode: log anything Bluetti-shaped that appears
+      scanner.on('discovered', ({ address, name }) => {
+        scanResultCache.push({ address, name });
+        app.setPluginStatus(`Discovered: ${name} [${address}] — copy address into plugin config`);
+      });
+      scanner.on('scanComplete', (found) => {
+        if (found.length === 0) app.setPluginStatus('Scan complete — no Bluetti devices found nearby.');
+      });
+      if (options.scanOnStart !== false) {
+        app.setPluginStatus('No devices configured — scanning for Bluetti devices …');
+        scanner.startScan(15000);
+      } else {
+        app.setPluginStatus('No devices configured. Add a device in plugin settings.');
+      }
+      return;
+    }
+
+    // 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 };
+
+    scanner.on('discovered', ({ address, name, peripheral }) => {
+      scanResultCache.push({ address, name });
+      const cfg = pending.get(normalise(address));
+      if (cfg) {
+        pending.delete(normalise(address));
+        app.setPluginStatus(`Found ${name} [${address}] — connecting …`);
+        startDevice(cfg, peripheral, name, deps);
+      } else {
+        log(`Discovered unconfigured Bluetti device: ${name} [${address}]`);
+      }
+    });
+
+    scanner.on('scanComplete', () => {
+      if (pending.size > 0) {
+        const missing = [...pending.values()].map(c => `${c.name} [${c.address}]`).join(', ');
+        app.setPluginStatus(`Waiting for device(s): ${missing} — rescanning …`);
+        setTimeout(() => {
+          if (pending.size > 0 && scanner) scanner.startScan(30000);
+        }, 5000);
+      }
+    });
+
+    app.setPluginStatus(`Scanning for ${devices.length} configured device(s) …`);
+    scanner.startScan(30000);
+  };
+
+  // Search $HOME for a file named <bleName>.csv (case-insensitive).
+  function findEncryptionCsvInHome(bleName) {
+    const homeDir = os.homedir();
+    const target  = `${bleName.toLowerCase()}.csv`;
+    try {
+      const match = fs.readdirSync(homeDir).find(f => f.toLowerCase() === target);
+      return match ? path.join(homeDir, match) : null;
+    } catch (_) {
+      return null;
+    }
+  }
+
+  function resolveRegisterMapPath(cfg) {
+    const { builtinModel, csvPath } = 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;
+    }
+    return path.join(REGISTERS_DIR, `${builtinModel}.csv`);
+  }
+
+  function startDevice(cfg, peripheral, bleName, { BluettiDevice, loadCsv, buildDelta, readEncryptionKey }) {
+    const { address, name, encryptionCsvPath = '', pollIntervalSeconds = 10 } = cfg;
+
+    let registerPath;
+    try {
+      registerPath = resolveRegisterMapPath(cfg);
+    } catch (err) {
+      app.setPluginError(`[${name}] ${err.message}`);
+      return;
+    }
+
+    let fields;
+    try {
+      fields = loadCsv(registerPath);
+      log(`[${name}] Loaded ${fields.length} registers from ${registerPath}`);
+    } catch (err) {
+      app.setPluginError(`[${name}] Failed to load register map "${registerPath}": ${err.message}`);
+      return;
+    }
+
+    let effectiveEncryptionPath = encryptionCsvPath;
+    if (!effectiveEncryptionPath && bleName) {
+      const autoPath = findEncryptionCsvInHome(bleName);
+      if (autoPath) {
+        effectiveEncryptionPath = autoPath;
+        log(`[${name}] Auto-detected encryption CSV for ${bleName}: ${autoPath}`);
+      }
+    }
+
+    let xorKey = null;
+    if (effectiveEncryptionPath) {
+      try {
+        xorKey = readEncryptionKey(effectiveEncryptionPath);
+        log(`[${name}] Loaded encryption key from ${effectiveEncryptionPath}`);
+      } catch (err) {
+        app.setPluginError(`[${name}] Failed to read encryption key: ${err.message}`);
+        return;
+      }
+    }
+
+    const device = new BluettiDevice({
+      address,
+      name,
+      peripheral,
+      fields,
+      pollIntervalMs: pollIntervalSeconds * 1000,
+      xorKey,
+      log,
+    });
+
+    device.on('connected', () => {
+      app.setPluginStatus(`Connected to ${name} [${address}]`);
+    });
+
+    device.on('registers', (registers) => {
+      const delta = buildDelta(registers, fields, name, PLUGIN_ID);
+      if (delta) app.handleMessage(PLUGIN_ID, delta);
+    });
+
+    device.start();
+    activeDevices.push(device);
+  }
+
+  // ── Stop ───────────────────────────────────────────────────────────────
+
+  plugin.stop = function () {
+    activeDevices.forEach(d => d.stop());
+    activeDevices = [];
+    if (scanner) {
+      scanner.stopAll();
+      scanner = null;
+    }
+    scanResultCache = [];
+  };
+
+  return plugin;
+};

package/lib/csv-loader.js

@@ -0,0 +1,136 @@
+'use strict';
+
+const fs = require('fs');
+const { parse } = require('csv-parse/sync');
+
+// Column name aliases — Bluetti CSVs have been seen in English and Chinese headers.
+// Maps our internal key → list of possible header strings (case-insensitive match).
+const COL_ALIASES = {
+  field_name:       ['field_name', 'fieldname', 'name', '字段名', 'field'],
+  register_address: ['register_address', 'register', 'address', 'addr', 'reg', 'no', 'no.', '寄存器', '地址'],
+  data_type:        ['data_type', 'datatype', 'type', '数据type', '数据类型'],
+  scale:            ['scale', '倍率', 'factor', 'multiplier'],
+  offset:           ['offset', '偏移'],
+  unit:             ['unit', 'units', '单位'],
+  signalk_path:     ['signalk_path', 'signalk', 'sk_path', 'path'],
+  register_count:   ['register_count', 'count', 'length', 'bytes', '数据长度'],
+};
+
+function resolveColumn(headers, key) {
+  const aliases = COL_ALIASES[key];
+  for (const alias of aliases) {
+    const found = headers.find(h => h.trim().toLowerCase() === alias.toLowerCase());
+    if (found) return found;
+  }
+  return null;
+}
+
+// Parse the CSV and return an array of field descriptors.
+// Each descriptor: { fieldName, register, count, dataType, scale, offset, unit, signalkPath }
+function loadCsv(filePath) {
+  const raw = fs.readFileSync(filePath, 'utf8');
+
+  // Strip BOM if present
+  const content = raw.charCodeAt(0) === 0xFEFF ? raw.slice(1) : raw;
+
+  const records = parse(content, {
+    columns: true,
+    skip_empty_lines: true,
+    trim: true,
+    comment: '#',
+  });
+
+  if (records.length === 0) throw new Error(`CSV file ${filePath} has no data rows`);
+
+  const headers = Object.keys(records[0]);
+
+  const col = {};
+  for (const key of Object.keys(COL_ALIASES)) {
+    col[key] = resolveColumn(headers, key);
+  }
+
+  if (!col.register_address) throw new Error('CSV must have a register address column');
+  if (!col.field_name)       throw new Error('CSV must have a field name column');
+
+  const fields = [];
+  for (const row of records) {
+    const registerRaw = row[col.register_address];
+    const register = parseInt(registerRaw, 10);
+    if (isNaN(register)) continue;  // skip header-like rows embedded in data
+
+    const dataType = col.data_type ? (row[col.data_type] || 'uint16').toLowerCase().trim() : 'uint16';
+    const scale    = col.scale     ? parseFloat(row[col.scale])  || 1   : 1;
+    const offset   = col.offset    ? parseFloat(row[col.offset]) || 0   : 0;
+    const unit     = col.unit      ? (row[col.unit]  || '').trim()      : '';
+
+    // register_count: for multi-register types (int32, uint32, float32 = 2 regs; int64 = 4 regs)
+    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 });
+  }
+
+  if (fields.length === 0) throw new Error(`No valid register rows found in ${filePath}`);
+  return fields;
+}
+
+function registersForType(dataType) {
+  switch (dataType) {
+    case 'int32':
+    case 'uint32':
+    case 'float32': return 2;
+    case 'int64':
+    case 'uint64': return 4;
+    default: return 1;  // uint16, int16, bool, enum
+  }
+}
+
+// Decode a raw register value (or pair of registers for 32-bit types) into a number.
+// rawRegs: Map<addr, uint16>, startAddr: the register address for this field
+function decodeValue(field, rawRegs) {
+  const { register, count, dataType, scale, offset } = field;
+
+  let raw;
+  if (count === 1) {
+    raw = rawRegs.get(register);
+    if (raw === undefined) return null;
+  } else if (count === 2) {
+    const hi = rawRegs.get(register);
+    const lo = rawRegs.get(register + 1);
+    if (hi === undefined || lo === undefined) return null;
+    raw = (hi << 16) | lo;
+  } else {
+    return null;
+  }
+
+  let value;
+  switch (dataType) {
+    case 'int16':
+      value = raw > 0x7FFF ? raw - 0x10000 : raw;
+      break;
+    case 'int32': {
+      const signed = raw > 0x7FFFFFFF ? raw - 0x100000000 : raw;
+      value = signed;
+      break;
+    }
+    case 'float32': {
+      const tmpBuf = Buffer.alloc(4);
+      tmpBuf.writeUInt32BE(raw, 0);
+      value = tmpBuf.readFloatBE(0);
+      break;
+    }
+    case 'bool':
+      return raw !== 0 ? 1 : 0;
+    default:
+      value = raw;
+  }
+
+  return value * scale + offset;
+}
+
+module.exports = { loadCsv, decodeValue };

package/lib/device.js

@@ -0,0 +1,195 @@
+'use strict';
+
+const EventEmitter = require('events');
+const { buildReadRequest, completeFrameLength, parseReadResponse, applyXor, groupRegisters } = require('./protocol');
+
+// UUIDs used by most Bluetti devices (short form — noble strips dashes and lowercases)
+const SERVICE_UUID  = 'ff00';
+const NOTIFY_UUID   = 'ff01';
+const WRITE_UUID    = 'ff02';
+
+// Fallback UUIDs seen on some older/alternate firmwares
+const ALT_SERVICE_UUID = 'ffe0';
+const ALT_CHAR_UUID    = 'ffe1';
+
+const RECONNECT_DELAYS = [5000, 10000, 20000, 30000, 60000];  // ms, capped at last value
+
+class BluettiDevice extends EventEmitter {
+  constructor({ address, name, peripheral, fields, pollIntervalMs = 10000, xorKey = null, log }) {
+    super();
+    this._address       = address;
+    this._name          = name;
+    this._peripheral    = peripheral;
+    this._fields        = fields;
+    this._pollIntervalMs = pollIntervalMs;
+    this._xorKey        = xorKey ? Buffer.from(xorKey, 'hex') : null;
+    this._log           = log;
+
+    this._connected     = false;
+    this._notifyChar    = null;
+    this._writeChar     = null;
+    this._rxBuf         = Buffer.alloc(0);
+    this._currentBatch  = null;   // { start, count } being awaited
+    this._batchQueue    = [];
+    this._pollTimer     = null;
+    this._reconnectAttempt = 0;
+    this._stopped       = false;
+
+    // Pre-compute register poll batches from field list
+    const addrs = [...new Set(fields.flatMap(f => Array.from({ length: f.count }, (_, i) => f.register + i)))];
+    this._batches = groupRegisters(addrs);
+    this._log(`[${name}] Poll plan: ${this._batches.length} batch(es) covering ${addrs.length} registers`);
+  }
+
+  start() {
+    this._stopped = false;
+    this._connect();
+  }
+
+  stop() {
+    this._stopped = true;
+    this._stopPolling();
+    if (this._peripheral && this._connected) {
+      try { this._peripheral.disconnect(); } catch (_) {}
+    }
+  }
+
+  // ── Connection lifecycle ─────────────────────────────────────────────────
+
+  _connect() {
+    if (this._stopped) return;
+    this._log(`[${this._name}] Connecting to ${this._address} …`);
+
+    this._peripheral.connect((err) => {
+      if (err) {
+        this._log(`[${this._name}] Connect error: ${err.message}`);
+        this._scheduleReconnect();
+        return;
+      }
+      this._log(`[${this._name}] Connected`);
+      this._reconnectAttempt = 0;
+      this._discoverServices();
+    });
+
+    this._peripheral.once('disconnect', () => {
+      if (this._stopped) return;
+      this._connected = false;
+      this._notifyChar = null;
+      this._writeChar  = null;
+      this._log(`[${this._name}] Disconnected`);
+      this._stopPolling();
+      this._scheduleReconnect();
+    });
+  }
+
+  _discoverServices() {
+    this._peripheral.discoverAllServicesAndCharacteristics((err, _services, chars) => {
+      if (err) {
+        this._log(`[${this._name}] Service discovery error: ${err.message}`);
+        this._scheduleReconnect();
+        return;
+      }
+
+      const notifyChar = chars.find(c => c.uuid === NOTIFY_UUID) ||
+                         chars.find(c => c.uuid === ALT_CHAR_UUID);
+      const writeChar  = chars.find(c => c.uuid === WRITE_UUID)  ||
+                         chars.find(c => c.uuid === ALT_CHAR_UUID);
+
+      if (!notifyChar || !writeChar) {
+        const uuids = chars.map(c => c.uuid).join(', ');
+        this._log(`[${this._name}] Could not find required characteristics. Found: ${uuids}`);
+        this._scheduleReconnect();
+        return;
+      }
+
+      this._notifyChar = notifyChar;
+      this._writeChar  = writeChar;
+
+      notifyChar.subscribe((err) => {
+        if (err) {
+          this._log(`[${this._name}] Subscribe error: ${err.message}`);
+          this._scheduleReconnect();
+          return;
+        }
+        notifyChar.on('data', (data) => this._onData(data));
+        this._connected = true;
+        this.emit('connected');
+        this._startPolling();
+      });
+    });
+  }
+
+  _scheduleReconnect() {
+    if (this._stopped) return;
+    const delay = RECONNECT_DELAYS[Math.min(this._reconnectAttempt, RECONNECT_DELAYS.length - 1)];
+    this._reconnectAttempt++;
+    this._log(`[${this._name}] Reconnecting in ${delay / 1000}s (attempt ${this._reconnectAttempt})`);
+    setTimeout(() => {
+      if (!this._stopped) this._connect();
+    }, delay);
+  }
+
+  // ── Polling ──────────────────────────────────────────────────────────────
+
+  _startPolling() {
+    this._stopPolling();
+    this._poll();
+    this._pollTimer = setInterval(() => this._poll(), this._pollIntervalMs);
+  }
+
+  _stopPolling() {
+    if (this._pollTimer) {
+      clearInterval(this._pollTimer);
+      this._pollTimer = null;
+    }
+    this._batchQueue = [];
+    this._currentBatch = null;
+  }
+
+  _poll() {
+    if (!this._connected || this._batches.length === 0) return;
+    // Queue all batches; they'll be sent one at a time as responses arrive
+    this._batchQueue = [...this._batches];
+    this._rxBuf = Buffer.alloc(0);
+    this._sendNextBatch();
+  }
+
+  _sendNextBatch() {
+    if (!this._connected || this._batchQueue.length === 0) return;
+    this._currentBatch = this._batchQueue.shift();
+    const { start, count } = this._currentBatch;
+    let frame = buildReadRequest(start, count);
+    if (this._xorKey) frame = applyXor(frame, this._xorKey);
+    this._rxBuf = Buffer.alloc(0);
+    this._writeChar.write(frame, false, (err) => {
+      if (err) this._log(`[${this._name}] Write error: ${err.message}`);
+    });
+  }
+
+  // ── Receive ──────────────────────────────────────────────────────────────
+
+  _onData(data) {
+    // Undo XOR on incoming data if encryption is in use
+    const chunk = this._xorKey ? applyXor(data, this._xorKey) : data;
+    this._rxBuf = Buffer.concat([this._rxBuf, chunk]);
+
+    const frameLen = completeFrameLength(this._rxBuf);
+    if (frameLen === 0) return;  // waiting for more BLE packets
+
+    const frame = this._rxBuf.slice(0, frameLen);
+    this._rxBuf = this._rxBuf.slice(frameLen);
+
+    if (!this._currentBatch) return;
+    const result = parseReadResponse(frame, this._currentBatch.start);
+    if (result) {
+      this.emit('registers', result.registers);
+    } else {
+      this._log(`[${this._name}] CRC error or unexpected frame, skipping batch`);
+    }
+
+    // Move to next batch
+    this._sendNextBatch();
+  }
+}
+
+module.exports = BluettiDevice;

package/lib/encryption.js

@@ -0,0 +1,19 @@
+'use strict';
+
+const fs = require('fs');
+
+// Parse the Bluetti-provided encryption CSV file and return the XOR key hex string.
+// Format: line 1 = "bluetti", line 2 = device timestamp, line 3 = short ID, line 4 = key.
+function readEncryptionKey(csvPath) {
+  const lines = fs.readFileSync(csvPath, 'utf8')
+    .split('\n')
+    .map(l => l.trim())
+    .filter(Boolean);
+
+  if (lines[0] !== 'bluetti') throw new Error(`Not a Bluetti encryption file: ${csvPath}`);
+  if (lines.length < 4) throw new Error(`Encryption file missing key line: ${csvPath}`);
+
+  return lines[3];
+}
+
+module.exports = { readEncryptionKey };

package/lib/path-mapper.js

@@ -0,0 +1,103 @@
+'use strict';
+
+const { decodeValue } = require('./csv-loader');
+
+// SignalK requires specific SI units. These conversions handle the most common
+// cases found in Bluetti register maps. The CSV's `unit` column drives the choice.
+const UNIT_CONVERSIONS = {
+  // temperature: Bluetti reports in °C or 0.1°C (handled by scale), SignalK wants K
+  'c':   (v) => v + 273.15,
+  '°c':  (v) => v + 273.15,
+  'degc':(v) => v + 273.15,
+
+  // energy: Bluetti reports Wh, SignalK wants J
+  'wh':  (v) => v * 3600,
+  'kwh': (v) => v * 3600000,
+
+  // state of charge: Bluetti is 0–100, SignalK wants 0.0–1.0
+  '%':   (v) => v / 100,
+  'pct': (v) => v / 100,
+  'soc': (v) => v / 100,
+
+  // everything else (V, A, W, Ah, Hz, min, s) is already SI — pass through
+};
+
+function convertUnits(value, unit) {
+  if (unit === null || unit === undefined) 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.
+function resolvePath(field, deviceName) {
+  if (field.signalkPath) {
+    return field.signalkPath.replace(/\{name\}/gi, 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.
+function autoPath(fieldName, name) {
+  const f = fieldName.toLowerCase();
+  if (f.includes('battery') || f.includes('batt') || f.includes('soc')) {
+    if (f.includes('voltage') || f.includes('volt')) return `electrical.batteries.${name}.voltage`;
+    if (f.includes('current') || f.includes('curr')) return `electrical.batteries.${name}.current`;
+    if (f.includes('percent') || f.includes('soc') || f.includes('capacity')) return `electrical.batteries.${name}.stateOfCharge`;
+    if (f.includes('temp'))   return `electrical.batteries.${name}.temperature`;
+    if (f.includes('power'))  return `electrical.batteries.${name}.power`;
+    if (f.includes('remain')) return `electrical.batteries.${name}.capacity.remaining`;
+    return `electrical.batteries.${name}.${fieldName}`;
+  }
+  if (f.includes('dc_input') || f.includes('solar') || f.includes('pv')) {
+    if (f.includes('power'))   return `electrical.solar.${name}.panelPower`;
+    if (f.includes('voltage')) return `electrical.solar.${name}.panelVoltage`;
+    if (f.includes('current')) return `electrical.solar.${name}.panelCurrent`;
+    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('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}`;
+  }
+  // Catch-all
+  return `electrical.${name}.${fieldName}`;
+}
+
+// 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) {
+  const values = [];
+
+  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);
+
+    values.push({ path, value: converted });
+  }
+
+  if (values.length === 0) return null;
+
+  return {
+    updates: [{
+      source: { label: source },
+      timestamp: new Date().toISOString(),
+      values,
+    }],
+  };
+}
+
+module.exports = { buildDelta, resolvePath, convertUnits };

package/lib/protocol.js

@@ -0,0 +1,101 @@
+'use strict';
+
+// Modbus CRC16 (standard table-driven implementation)
+function crc16(buf) {
+  let crc = 0xFFFF;
+  for (let i = 0; i < buf.length; i++) {
+    crc ^= buf[i];
+    for (let j = 0; j < 8; j++) {
+      crc = (crc & 0x0001) ? (crc >> 1) ^ 0xA001 : crc >> 1;
+    }
+  }
+  return crc;
+}
+
+// Build a Modbus RTU "read holding registers" request (function code 0x03)
+function buildReadRequest(startRegister, count) {
+  const buf = Buffer.alloc(8);
+  buf[0] = 0x01;                          // device address (Bluetti uses 0x01)
+  buf[1] = 0x03;                          // FC: read holding registers
+  buf.writeUInt16BE(startRegister, 2);
+  buf.writeUInt16BE(count, 4);
+  const crc = crc16(buf.slice(0, 6));
+  buf[6] = crc & 0xFF;
+  buf[7] = (crc >> 8) & 0xFF;
+  return buf;
+}
+
+// Check if an accumulated buffer contains a complete Modbus response.
+// Returns byte length of the complete frame, or 0 if incomplete.
+function completeFrameLength(buf) {
+  if (buf.length < 5) return 0;
+  if (buf[0] !== 0x01) return 0;
+  if (buf[1] === 0x03) {
+    const expected = 3 + buf[2] + 2;     // hdr(3) + data + crc(2)
+    return buf.length >= expected ? expected : 0;
+  }
+  // Error response: FC | 0x80, error code, 2-byte CRC = 5 bytes
+  if ((buf[1] & 0x80) !== 0) return buf.length >= 5 ? 5 : 0;
+  return 0;
+}
+
+// Parse a complete Modbus RTU read-response frame.
+// Returns { registers: Map<addr, uint16>, startRegister } or null on CRC error.
+function parseReadResponse(buf, startRegister) {
+  const frameLen = completeFrameLength(buf);
+  if (frameLen === 0) return null;
+
+  // CRC check
+  const receivedCrc = buf[frameLen - 2] | (buf[frameLen - 1] << 8);
+  const computedCrc = crc16(buf.slice(0, frameLen - 2));
+  if (receivedCrc !== computedCrc) return null;
+
+  // Error frame
+  if ((buf[1] & 0x80) !== 0) return null;
+
+  const byteCount = buf[2];
+  const registers = new Map();
+  for (let i = 0; i < byteCount / 2; i++) {
+    const addr = startRegister + i;
+    const val = buf.readUInt16BE(3 + i * 2);
+    registers.set(addr, val);
+  }
+  return { registers, startRegister };
+}
+
+// Apply the optional XOR-based frame scrambling used by some Bluetti models.
+// key is a Buffer. If key is null/empty, returns buf unchanged.
+function applyXor(buf, key) {
+  if (!key || key.length === 0) return buf;
+  const out = Buffer.from(buf);
+  for (let i = 0; i < out.length; i++) {
+    out[i] ^= key[i % key.length];
+  }
+  return out;
+}
+
+// Group a sorted list of register addresses into contiguous batches for polling.
+// maxGap: if two adjacent addresses are more than this apart, start a new batch.
+// maxCount: max registers per request.
+function groupRegisters(addresses, maxGap = 10, maxCount = 50) {
+  if (addresses.length === 0) return [];
+  const sorted = [...addresses].sort((a, b) => a - b);
+  const batches = [];
+  let start = sorted[0];
+  let end = sorted[0];
+
+  for (let i = 1; i < sorted.length; i++) {
+    const addr = sorted[i];
+    if (addr - end <= maxGap && addr - start < maxCount) {
+      end = addr;
+    } else {
+      batches.push({ start, count: end - start + 1 });
+      start = addr;
+      end = addr;
+    }
+  }
+  batches.push({ start, count: end - start + 1 });
+  return batches;
+}
+
+module.exports = { crc16, buildReadRequest, completeFrameLength, parseReadResponse, applyXor, groupRegisters };

package/lib/scanner.js

@@ -0,0 +1,108 @@
+'use strict';
+
+const EventEmitter = require('events');
+
+// Bluetti devices advertise with names matching these prefixes.
+// BT-TH-XXXXXXXXXX is the most common; some models use BLUETTI or model names directly.
+const BLUETTI_NAME_PREFIXES = ['BT-TH-', 'BLUETTI', 'AC', 'EP', 'EB', 'EL'];
+
+function isBluettiDevice(peripheral) {
+  const name = (peripheral.advertisement && peripheral.advertisement.localName) || '';
+  return BLUETTI_NAME_PREFIXES.some(p => name.toUpperCase().startsWith(p.toUpperCase()));
+}
+
+class Scanner extends EventEmitter {
+  constructor(log) {
+    super();
+    this._log = log;
+    this._noble = null;
+    this._scanning = false;
+    this._found = new Map();   // address → peripheral
+  }
+
+  // Returns a promise that resolves once noble is powered on.
+  _initNoble() {
+    if (this._noble) return Promise.resolve();
+
+    return new Promise((resolve, reject) => {
+      let noble;
+      try {
+        noble = require('@abandonware/noble');
+      } catch (e) {
+        return reject(new Error('@abandonware/noble not installed — run: npm install'));
+      }
+
+      this._noble = noble;
+
+      noble.on('discover', (peripheral) => {
+        if (!isBluettiDevice(peripheral)) return;
+        const addr = peripheral.address || peripheral.id;
+        const name = (peripheral.advertisement.localName || 'unknown').trim();
+        if (!this._found.has(addr)) {
+          this._found.set(addr, peripheral);
+          this._log(`Discovered Bluetti device: ${name} [${addr}]`);
+          this.emit('discovered', { address: addr, name, peripheral });
+        }
+      });
+
+      noble.on('stateChange', (state) => {
+        this._log(`BLE adapter state: ${state}`);
+        if (state === 'poweredOn') {
+          resolve();
+        } else if (state === 'poweredOff' || state === 'unsupported') {
+          reject(new Error(`BLE adapter state: ${state}`));
+        }
+      });
+
+      // Already powered on (noble initialised before our listener)
+      if (noble.state === 'poweredOn') resolve();
+    });
+  }
+
+  async startScan(durationMs = 15000) {
+    if (this._scanning) return;
+    await this._initNoble();
+    this._found.clear();
+    this._scanning = true;
+    this._log(`Scanning for Bluetti devices for ${durationMs / 1000}s …`);
+    this._noble.startScanning([], false);
+    this._scanTimer = setTimeout(() => this.stopScan(), durationMs);
+  }
+
+  stopScan() {
+    if (!this._scanning) return;
+    clearTimeout(this._scanTimer);
+    this._scanning = false;
+    if (this._noble) this._noble.stopScanning();
+    this._log(`Scan complete. Found ${this._found.size} Bluetti device(s).`);
+    this.emit('scanComplete', [...this._found.values()].map(p => ({
+      address: p.address || p.id,
+      name: (p.advertisement.localName || 'unknown').trim(),
+    })));
+  }
+
+  // Retrieve a previously-discovered peripheral by address (for reconnect).
+  getPeripheral(address) {
+    return this._found.get(address) || null;
+  }
+
+  // Start a persistent background scan (noble keeps discovering; don't auto-stop).
+  startPassiveScan() {
+    this._initNoble().then(() => {
+      this._scanning = true;
+      this._noble.startScanning([], true);   // allowDuplicates=true so we see RSSI updates
+    }).catch(err => {
+      this._log(`BLE init failed: ${err.message}`);
+      this.emit('error', err);
+    });
+  }
+
+  stopAll() {
+    this.stopScan();
+    if (this._noble) {
+      try { this._noble.stopScanning(); } catch (_) {}
+    }
+  }
+}
+
+module.exports = Scanner;

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@rhizomatics/signalk-bluetti-plugin",
+  "version": "1.0.1-alpha",
+  "signalk": {
+    "displayName": "Bluetti Monitoring"
+  },
+  "description": "SignalK plugin for Bluetti power station monitoring via Bluetooth LE. ",
+  "main": "index.js",
+  "license": "Apache-2.0",
+  "keywords": [
+    "signalk-node-server-plugin",
+    "signalk-node-plugin",
+    "bluetti",
+    "battery",
+    "electrical",
+    "bluetooth",
+    "ble",
+    "marine"
+  ],
+  "engines": {
+    "signalk-server": "*"
+  },
+  "signalk-plugin-enabled-by-default": false,
+  "scripts": {
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "@abandonware/noble": "^1.9.2-15",
+    "csv-parse": "^5.5.6"
+  }
+}

package/registers/ac200p.csv

@@ -0,0 +1,39 @@
+# 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)
+#   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
+#
+field_name,register_address,register_count,data_type,scale,offset,unit,signalk_path
+# ── Battery ────────────────────────────────────────────────────────────────
+battery_percent,100,1,uint16,1,0,%,electrical.batteries.{name}.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
+# ── 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
+# ── 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 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
+# ── Internal temperature ────────────────────────────────────────────────────
+internal_temperature,118,1,uint16,0.1,0,°C,electrical.batteries.{name}.controllerTemperature
+# ── Estimated time remaining ────────────────────────────────────────────────
+time_remaining_minutes,119,1,uint16,1,0,min,electrical.batteries.{name}.capacity.timeRemaining

package/registers/el100v2.csv

@@ -0,0 +1,13 @@
+# Bluetti Elite 100 V2 (EL100V2) register map
+# Source: https://github.com/Patrick762/bluetti-bt-lib
+# BaseDeviceV2 fields: BATTERY_SOC (102)
+# 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,0.01,0,%,electrical.batteries.{name}.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

package/registers-example.csv

@@ -0,0 +1,39 @@
+# 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)
+#   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
+#
+field_name,register_address,register_count,data_type,scale,offset,unit,signalk_path
+# ── Battery ────────────────────────────────────────────────────────────────
+battery_percent,100,1,uint16,1,0,%,electrical.batteries.{name}.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
+# ── 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
+# ── 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 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
+# ── Internal temperature ────────────────────────────────────────────────────
+internal_temperature,118,1,uint16,0.1,0,°C,electrical.batteries.{name}.controllerTemperature
+# ── Estimated time remaining ────────────────────────────────────────────────
+time_remaining_minutes,119,1,uint16,1,0,min,electrical.batteries.{name}.capacity.timeRemaining