signalk-rec-bms 1.1.7 → 2.0.2

package/README.md

@@ -4,19 +4,19 @@
 
 ## Features
 
-- Reads all avabile data streams from BMS and publishes to SignalK
-- Supports Websocket connection from the REC WiFi module with firmare >= SW164_2
+- Reads all available data streams from BMS and publishes to SignalK
+- Supports WebSocket connection from the REC WiFi module with firmware >= SW164_2
 - Supports serial connection directly from BMS
 - Can set BMS settings when using serial connection
-- Live status & settings page within SignalK 
+- Live status & settings page within SignalK
 
 ## Notes
 
-Tested with the 4 cell ABMS model only
+Tested with the 4 cell ABMS model only. Multi-unit series configurations are detected automatically but have not been tested beyond a single unit — proceed with caution if running multiple ABMS units in series.
 
 ## Requirements
 
-#### Websocket connection (WiFi):
+#### WebSocket connection (WiFi):
 
 - A REC WiFi module with firmware >= SW164_2, which enables websockets  
 
@@ -32,7 +32,7 @@ Tested with the 4 cell ABMS model only
 
 ## Dependencies
 
-- npm package: [websocket](https://www.npmjs.com/package/websocket)
+- npm package: [ws](https://www.npmjs.com/package/ws)
 - npm package: [serialport](https://www.npmjs.com/package/serialport)
 - npm package: [crc](https://www.npmjs.com/package/crc)
 
@@ -45,14 +45,36 @@ Run the following command:
    npm install signalk-rec-bms
    ```
 
+## SignalK Paths
+
+All data is published under `electrical.batteries.bms.*` by default. The base path is configurable via the `deltaPrefix` plugin setting. Key paths include:
+
+| Path | Description |
+|---|---|
+| `electrical.batteries.bms.voltage` | Pack voltage |
+| `electrical.batteries.bms.current` | Pack current |
+| `electrical.batteries.bms.power` | Instantaneous power |
+| `electrical.batteries.bms.capacity.stateOfCharge` | State of charge (0–1) |
+| `electrical.batteries.bms.capacity.stateOfHealth` | State of health (0–1) |
+| `electrical.batteries.bms.capacity.nominal` | Configured capacity (Ah) |
+| `electrical.batteries.bms.capacity.remaining` | Estimated remaining (Ah) |
+| `electrical.batteries.bms.cellVoltage{N}` | Individual cell voltages |
+| `electrical.batteries.bms.cellTemperature{N}` | Cell temperatures (K) |
+| `electrical.batteries.bms.cellResistance{N}` | Cell internal resistance (Ohm) |
+| `electrical.batteries.bms.bmsTemperature` | BMS board temperature (K) |
+| `electrical.batteries.bms.minCellVoltage` | Minimum cell voltage |
+| `electrical.batteries.bms.maxCellVoltage` | Maximum cell voltage |
+
+Temperature values are published in Kelvin in compliance with the SignalK specification. Instrument displays that respect SK unit preferences will convert automatically to °C or °F.
+
 ## Victron Cerbo GX / Venus OS
 
-VenusOS claims all serial devices by default and attempts to pair them with a pre-defined service. This script works by telling VenusOS to ignore your usb to serial device & allowing you to use it with SignalK. 
+VenusOS claims all USB serial devices by default via its `serial-starter` service, which cycles through Victron protocols and prevents SignalK from accessing the port. The setup script creates a udev rule that instructs VenusOS to ignore your specific RS485 adapter, leaving it available exclusively for SignalK. The rule uses a `zz-` prefix to ensure it overrides Victron's default rules regardless of load order.
 
 ```bash
 curl -o /home/root/signalk-rec-bms-venusOS.sh https://raw.githubusercontent.com/ofernander/signalk-rec-bms/main/venus-os/signalk-rec-bms-venusOS.sh && bash /home/root/signalk-rec-bms-venusOS.sh
 ```
 
-The script will list your connected USB serial devices, you select which one is the usb to serial converter for your REC-BMS. Once complete, unplug and replug your RS485 adapter, then reboot the Cerbo device. 
+The script will list your connected USB serial devices, you select which one is the usb to serial converter for your REC-BMS. Once complete, unplug and replug your RS485 adapter, then reboot the Cerbo device.
 
-To uninstall: `bash /home/root/signalk-rec-bms-venusOS.sh --uninstall` or select the last option in the script menu. 
+To uninstall: `bash /home/root/signalk-rec-bms-venusOS.sh --uninstall` or select the last option in the script menu.

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "signalk-rec-bms",
-  "version": "1.1.7",
+  "version": "2.0.2",
   "description": "SignalK plugin for REC-BMS",
   "main": "plugin/index.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node --test test/parsers.test.js"
   },
   "keywords": [
     "signalk-webapp",
@@ -29,7 +29,7 @@
     "node": ">=10"
   },
   "signalk": {
-    "appIcon": "./assets/icons/rec_ball-72x72.png",
+    "appIcon": "./assets/icons/signalk-rec-bms-icon_72x72.png",
     "displayName": "SignalK-REC-BMS"
   }
 }

package/plugin/index.js

@@ -2,10 +2,13 @@
 
 const schema = require('./lib/schema');
 const connection = require('./lib/connection');
+const HistoryBuffer = require('./lib/history');
 
 module.exports = function(app) {
   let conn;
   let pluginOptions;
+  let historyBuffer;
+  let historyRouteRegistered = false;
 
   function publishMeta(options) {
     const p = options.deltaPrefix || "electrical.batteries.bms";
@@ -94,10 +97,13 @@ module.exports = function(app) {
   }
 
   function publishDelta(delta) {
+    if (historyBuffer) historyBuffer.record(delta);
+
     const precision = 5;
     const factor = Math.pow(10, precision);
 
     delta.updates.forEach(update => {
+      update.$source = "signalk-rec-bms";
       update.values.forEach(item => {
         if (typeof item.value === "number") {
           item.value = Math.round(item.value * factor) / factor;
@@ -122,15 +128,31 @@ module.exports = function(app) {
       pluginOptions = options;
       app.debug(`[INDEX] START invoked with options: ${JSON.stringify(options)}`);
       app.setPluginStatus("Connecting to BMS…");
+
+      const prefix = options.deltaPrefix || "electrical.batteries.bms";
+      const dataDir = typeof app.getDataDirPath === 'function' ? app.getDataDirPath() : null;
+      historyBuffer = new HistoryBuffer(prefix, dataDir);
+
+      if (!historyRouteRegistered) {
+        historyRouteRegistered = true;
+        app.get('/signalk/v1/bms/history', (req, res) => {
+          if (!historyBuffer) return res.status(503).json({ error: "Buffer not ready" });
+          const hours = req.query.hours || 1;
+          res.json(historyBuffer.getHistory(hours));
+        });
+      }
+
       publishMeta(options);
       conn = connection(options, app, publishDelta);
       conn.start(options);
     },
     stop: function() {
+      if (historyBuffer) historyBuffer.stop();
       if (conn) {
         conn.stop();
         conn = null;
       }
+      historyBuffer = null;
       app.debug("[INDEX] Plugin stopped");
       app.setPluginStatus("Stopped");
     },

package/plugin/lib/history.js

@@ -0,0 +1,163 @@
+"use strict";
+
+const fs = require('fs');
+const path = require('path');
+
+const FLUSH_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+
+module.exports = function HistoryBuffer(prefix, dataDir) {
+  const persistPath = dataDir
+    ? path.join(dataDir, 'bms-history.json')
+    : null;
+
+  // Three-tier storage per metric
+  // Each entry: { t: timestamp_ms, v: value }
+  const store = {
+    voltage: { fine: [], medium: [], coarse: [] },
+    current: { fine: [], medium: [], coarse: [] },
+    power:   { fine: [], medium: [], coarse: [] },
+    soc:     { fine: [], medium: [], coarse: [] }
+  };
+
+  // Tier boundaries and max retention
+  const FINE_RESOLUTION_MS   = 10 * 1000;       // 10s — keep for 1 hour
+  const MEDIUM_RESOLUTION_MS = 60 * 1000;       // 1m  — keep for 6 hours
+  const COARSE_RESOLUTION_MS = 5 * 60 * 1000;   // 5m  — keep for 24 hours
+
+  const FINE_MAX_AGE_MS   = 1 * 60 * 60 * 1000;   // 1 hour
+  const MEDIUM_MAX_AGE_MS = 6 * 60 * 60 * 1000;   // 6 hours
+  const COARSE_MAX_AGE_MS = 24 * 60 * 60 * 1000;  // 24 hours
+
+  // Last recorded timestamp per metric per tier, for resolution gating
+  const lastRecorded = {
+    voltage: { fine: 0, medium: 0, coarse: 0 },
+    current: { fine: 0, medium: 0, coarse: 0 },
+    power:   { fine: 0, medium: 0, coarse: 0 },
+    soc:     { fine: 0, medium: 0, coarse: 0 }
+  };
+
+  // Load persisted data on startup
+  if (persistPath) {
+    try {
+      const raw = fs.readFileSync(persistPath, 'utf8');
+      const saved = JSON.parse(raw);
+      const now = Date.now();
+
+      for (const metric of ['voltage', 'current', 'power', 'soc']) {
+        if (saved[metric]) {
+          store[metric].fine   = (saved[metric].fine   || []).filter(p => p.t >= now - FINE_MAX_AGE_MS);
+          store[metric].medium = (saved[metric].medium || []).filter(p => p.t >= now - MEDIUM_MAX_AGE_MS);
+          store[metric].coarse = (saved[metric].coarse || []).filter(p => p.t >= now - COARSE_MAX_AGE_MS);
+        }
+      }
+
+      // Restore lastRecorded from last entry in each tier so we don't duplicate points
+      for (const metric of ['voltage', 'current', 'power', 'soc']) {
+        for (const tier of ['fine', 'medium', 'coarse']) {
+          const arr = store[metric][tier];
+          if (arr.length > 0) lastRecorded[metric][tier] = arr[arr.length - 1].t;
+        }
+      }
+    } catch (e) {
+      // Missing or corrupt file — start fresh silently
+    }
+  }
+
+  const pathMap = {
+    [`${prefix}.voltage`]:                'voltage',
+    [`${prefix}.current`]:                'current',
+    [`${prefix}.power`]:                  'power',
+    [`${prefix}.capacity.stateOfCharge`]: 'soc'
+  };
+
+  function record(delta) {
+    if (!delta.updates) return;
+    const now = Date.now();
+
+    delta.updates.forEach(update => {
+      if (!update.values) return;
+      update.values.forEach(({ path, value }) => {
+        const metric = pathMap[path];
+        if (!metric || typeof value !== 'number') return;
+        push(metric, now, value);
+      });
+    });
+  }
+
+  function push(metric, now, value) {
+    const tiers = store[metric];
+    const last = lastRecorded[metric];
+
+    if (now - last.fine >= FINE_RESOLUTION_MS) {
+      tiers.fine.push({ t: now, v: value });
+      last.fine = now;
+    }
+
+    if (now - last.medium >= MEDIUM_RESOLUTION_MS) {
+      tiers.medium.push({ t: now, v: value });
+      last.medium = now;
+    }
+
+    if (now - last.coarse >= COARSE_RESOLUTION_MS) {
+      tiers.coarse.push({ t: now, v: value });
+      last.coarse = now;
+    }
+
+    prune(tiers.fine,   now - FINE_MAX_AGE_MS);
+    prune(tiers.medium, now - MEDIUM_MAX_AGE_MS);
+    prune(tiers.coarse, now - COARSE_MAX_AGE_MS);
+  }
+
+  function prune(arr, cutoff) {
+    while (arr.length > 0 && arr[0].t < cutoff) arr.shift();
+  }
+
+  function flush() {
+    if (!persistPath) return;
+    try {
+      const data = {};
+      for (const metric of ['voltage', 'current', 'power', 'soc']) {
+        data[metric] = {
+          fine:   store[metric].fine,
+          medium: store[metric].medium,
+          coarse: store[metric].coarse
+        };
+      }
+      fs.writeFileSync(persistPath, JSON.stringify(data), 'utf8');
+    } catch (e) {
+      // Write failure — non-fatal, will retry on next interval
+    }
+  }
+
+  // Periodic flush to disk
+  let flushTimer = null;
+  if (persistPath) {
+    flushTimer = setInterval(() => flush(), FLUSH_INTERVAL_MS);
+  }
+
+  function getHistory(hours) {
+    const h = Math.min(Math.max(parseFloat(hours) || 1, 0.25), 24);
+    const now = Date.now();
+    const cutoff = now - h * 60 * 60 * 1000;
+
+    let tier;
+    if (h <= 1)       tier = 'fine';
+    else if (h <= 6)  tier = 'medium';
+    else              tier = 'coarse';
+
+    const result = {};
+    for (const metric of ['voltage', 'current', 'power', 'soc']) {
+      result[metric] = store[metric][tier]
+        .filter(p => p.t >= cutoff)
+        .map(p => ({ t: p.t, v: p.v }));
+    }
+    return { hours: h, tier, generated: now, data: result };
+  }
+
+  function stop() {
+    if (flushTimer) clearInterval(flushTimer);
+    flush(); // flush on stop so shutdown data is preserved
+  }
+
+  return { record, getHistory, stop };
+};

package/plugin/lib/serial/Layer2.js

@@ -5,8 +5,6 @@ class Layer2 {
 	constructor() {
 		this.buffer = [];
 		this.stats = {
-			tx: 0,
-			txBytes: 0,
 			rx: 0,
 			rxBytes: 0,
 			badCRC: 0
@@ -66,4 +64,4 @@ class Layer2 {
 	}
 }
 
-module.exports = Layer2;
+module.exports = Layer2;

package/plugin/lib/serial/atlas.json

@@ -490,16 +490,6 @@
     "description": "SERI? returns ABMS serial number",
     "module": "abms"
   },
-  {
-    "tag": "SERI2",
-    "command": "SERI?",
-    "expectedPackets": 1,
-    "payloadSizes": [null],
-    "parser": "parseSERIResponse",
-    "timeout": 1000,
-    "description": "SERI2? returns ABMS serial number (hidden duplicate)",
-    "module": "abms"
-  },
   {
     "tag": "SWVR",
     "command": "SWVR?",
@@ -549,5 +539,5 @@
     "timeout": 1000,
     "description": "WCBI? returns balancing cell number",
     "module": "abms"
-  } 
+  }
 ]

package/plugin/lib/serial/engine.js

@@ -1,6 +1,4 @@
 "use strict";
-const fs = require('fs');
-const path = require('path');
 const EventEmitter = require('events');
 const hexer = require('./hexer');
 const atlas = require('./atlas.json');
@@ -18,9 +16,14 @@ class CommandEngine extends EventEmitter {
 
   sendCommand(tag, targetAddress, rawCommandStr = null, options = {}) {
     return new Promise((resolve, reject) => {
+      // If a command is already in flight, reject unless caller explicitly forces
+      if (this.activeCommand && !options.force) {
+        return reject(new Error(`[ENGINE] Busy — command ${this.activeCommand.tag} in flight, dropping ${tag}`));
+      }
+
       let commandStr;
       let expectedPackets = 1;
-      let timeoutMs = 3000; 
+      let timeoutMs = 3000;
       let config = atlasMapping[tag];
 
       if (rawCommandStr) {
@@ -64,6 +67,7 @@ class CommandEngine extends EventEmitter {
         currentCommand.timeout = setTimeout(() => {
           const errMsg = `${tag} response timed out after ${timeoutMs} ms`;
           if (currentCommand && typeof currentCommand.reject === "function") {
+            this.activeCommand = null;
             currentCommand.reject(new Error(errMsg));
           }
         }, timeoutMs);

package/plugin/lib/serial/modules/array.js

@@ -70,6 +70,9 @@ function parseLCD3Response(input) {
 
 function parseIDNResponse(input) {
   const packet = Array.isArray(input) ? input[0] : input;
+  if (!packet) {
+    return null;
+  }
   const payload = packet.slice(4, packet.length - 3).toString('utf8');
   const result = {
     type: "IDN",
@@ -390,10 +393,6 @@ function getDelta(parsed, options, app) {
   return delta;
 }
 
-/* ============================================================================
-   4. EXPORTS
-   Export functions for building commands, parsing responses, and building deltas.
-   ============================================================================ */
 module.exports = {
   buildCommand,
   getDelta,

package/plugin/lib/serial/modules/derived.js

@@ -12,6 +12,8 @@ module.exports = function Derived(app, sendDeltaCallback, config) {
   // 'capacity' is stored internally in Ah (as received from capacity.nominal).
   // 'ampHourUsed' is stored internally in Ah (converted from Coulombs off the stream).
 
+  const subscriptions = [];
+
   function computeAndSendDeltas() {
     if ([voltage, current, ampHourUsed, capacity].every(v => typeof v === 'number')) {
       const power = voltage * current;
@@ -43,20 +45,20 @@ module.exports = function Derived(app, sendDeltaCallback, config) {
     }
   }
 
-  app.streambundle.getSelfStream(prefix + 'voltage').forEach(v => {
+  subscriptions.push(app.streambundle.getSelfStream(prefix + 'voltage').forEach(v => {
     if (typeof v === 'number') { voltage = v; computeAndSendDeltas(); }
-  });
-  app.streambundle.getSelfStream(prefix + 'current').forEach(v => {
+  }));
+  subscriptions.push(app.streambundle.getSelfStream(prefix + 'current').forEach(v => {
     if (typeof v === 'number') { current = v; computeAndSendDeltas(); }
-  });
-  app.streambundle.getSelfStream(prefix + 'capacity.dischargeSinceFull').forEach(v => {
+  }));
+  subscriptions.push(app.streambundle.getSelfStream(prefix + 'capacity.dischargeSinceFull').forEach(v => {
     // value on stream is Coulombs; convert to Ah for internal arithmetic
     if (typeof v === 'number') { ampHourUsed = v / 3600; computeAndSendDeltas(); }
-  });
-  app.streambundle.getSelfStream(prefix + 'capacity.nominal').forEach(v => {
+  }));
+  subscriptions.push(app.streambundle.getSelfStream(prefix + 'capacity.nominal').forEach(v => {
     // value on stream is Ah
     if (typeof v === 'number') { capacity = v; computeAndSendDeltas(); }
-  });
+  }));
 
   // ---- Cell diff logic ----
   let totalCells = 0;
@@ -73,7 +75,7 @@ module.exports = function Derived(app, sendDeltaCallback, config) {
   const CELL_DIFF_RETRY_MS = 200;
   const CELL_DIFF_MAX_WAIT_MS = 8000;
 
-  app.streambundle.getSelfStream(prefix + 'numBMSUnits').forEach(units => {
+  subscriptions.push(app.streambundle.getSelfStream(prefix + 'numBMSUnits').forEach(units => {
     if (typeof units === 'number' && units > 0) {
       // If units changes (or first time), reset expectations and cached values
       if (units !== unitsExpected) {
@@ -95,13 +97,13 @@ module.exports = function Derived(app, sendDeltaCallback, config) {
 
         subscribedCells.add(i);
         const cellPath = prefix + 'cellVoltage' + i;
-        app.streambundle.getSelfStream(cellPath).forEach(val => {
+        subscriptions.push(app.streambundle.getSelfStream(cellPath).forEach(val => {
           if (typeof val === 'number' && Number.isFinite(val)) {
             if (!firstCellSeenAtMs) firstCellSeenAtMs = Date.now();
             cellVoltages[i] = val;
             trySendCellDiff();
           }
-        });
+        }));
       }
 
       subscribedCellStreams = true;
@@ -109,7 +111,7 @@ module.exports = function Derived(app, sendDeltaCallback, config) {
       // Attempt immediately in case we already have cached values after restart
       trySendCellDiff();
     }
-  });
+  }));
 
   function scheduleCellDiffRetry() {
     if (pendingCellDiffTimer) return;
@@ -173,6 +175,8 @@ module.exports = function Derived(app, sendDeltaCallback, config) {
   return {
     stop: () => {
       app.debug("[DERIVED] Stopping derived module");
+      if (pendingCellDiffTimer) clearTimeout(pendingCellDiffTimer);
+      subscriptions.forEach(unsub => { if (typeof unsub === 'function') unsub(); });
     }
   };
 };

package/plugin/lib/serial/serial.js

@@ -31,6 +31,8 @@ const moduleMapping = {
 module.exports = function(app, publishDelta) {
   let port, parser, engine;
   let derivedModule;
+  let pollingInterval;
+  let routeRegistered = false;
 
   function start(options) {
     app.debug("[SERIAL] start() called with options: " + JSON.stringify(options));
@@ -69,7 +71,7 @@ module.exports = function(app, publishDelta) {
       const commandList = atlas.map(entry => entry.tag);
       let currentIndex = 0;
 
-      setInterval(() => {
+      pollingInterval = setInterval(() => {
         const tag = commandList[currentIndex];
         currentIndex = (currentIndex + 1) % commandList.length;
 
@@ -86,58 +88,67 @@ module.exports = function(app, publishDelta) {
               if (moduleDelta) publishDelta(moduleDelta);
             }
           })
-          .catch(err => app.debug("[SERIAL] Error: " + err.message));
+          .catch(err => {
+            if (err.message.startsWith('[ENGINE] Busy')) {
+              app.debug("[SERIAL] Skipping " + tag + " — engine busy");
+            } else {
+              app.debug("[SERIAL] Error: " + err.message);
+            }
+          });
       }, 100);
 
-      // command endpoint 
-      app.post('/signalk/v1/bms/command', (req, res) => {
-        const { command } = req.body;
-        if (!command) return res.status(400).json({ error: "Missing command" });
-
-        const parts = command.trim().split(/\s+/);
-        let tag = parts[0];
-        const raw = command.trim();
-        const isQuery = tag.endsWith("?");
+      if (!routeRegistered) {
+        routeRegistered = true;
+        app.post('/signalk/v1/bms/command', (req, res) => {
+          const { command } = req.body;
+          if (!command) return res.status(400).json({ error: "Missing command" });
 
-        if (isQuery) {
-          tag = tag.slice(0, -1);
-        }
+          const parts = command.trim().split(/\s+/);
+          let tag = parts[0];
+          const raw = command.trim();
+          const isQuery = tag.endsWith("?");
 
-        const config = atlas.find(entry => entry.tag === tag);
+          if (isQuery) {
+            tag = tag.slice(0, -1);
+          }
 
-        if (config && config.module && moduleMapping[config.module]) {
-          const commandModule = moduleMapping[config.module];
-          const expectResponse = isQuery;
-
-          engine.sendCommand(tag, options.serial.targetAddress, raw, { expectResponse })
-            .then(packets => {
-              if (expectResponse) {
-                const parsed = commandModule[config.parser]?.(packets);
-                res.json({
-                  command,
-                  response: parsed,
-                  rawPackets: packets.map(p => p.toString('hex'))
-                });
-              } else {
-                res.json({
-                  command,
-                  response: { status: "sent (no response expected)" }
-                });
-              }
-            })
-            .catch(err => {
-              res.status(500).json({ error: err.message, command });
-            });
-        } else {
-          res.status(400).json({ error: "Unknown or unsupported command" });
-        }
-      });
+          const config = atlas.find(entry => entry.tag === tag);
+
+          if (config && config.module && moduleMapping[config.module]) {
+            const commandModule = moduleMapping[config.module];
+            const expectResponse = isQuery;
+
+            engine.sendCommand(tag, options.serial.targetAddress, raw, { expectResponse, force: true })
+              .then(packets => {
+                if (expectResponse) {
+                  const parsed = commandModule[config.parser]?.(packets);
+                  res.json({
+                    command,
+                    response: parsed,
+                    rawPackets: packets.map(p => p.toString('hex'))
+                  });
+                } else {
+                  res.json({
+                    command,
+                    response: { status: "sent (no response expected)" }
+                  });
+                }
+              })
+              .catch(err => {
+                res.status(500).json({ error: err.message, command });
+              });
+          } else {
+            res.status(400).json({ error: "Unknown or unsupported command" });
+          }
+        });
+      }
     });
 
     port.on('error', (err) => app.debug("[SERIAL] Error: " + err.message));
   }
 
   function stop() {
+    clearInterval(pollingInterval);
     if (port) port.close();
     if (derivedModule && typeof derivedModule.stop === 'function') derivedModule.stop();
   }
@@ -152,7 +163,7 @@ module.exports = function(app, publishDelta) {
         throw new Error("Unknown or unsupported command");
       }
       const commandModule = moduleMapping[config.module];
-      return engine.sendCommand(tag, targetAddress)
+      return engine.sendCommand(tag, targetAddress, null, { force: true })
         .then(packets => ({
           packets,
           parsed: commandModule[config.parser]?.(packets)