bt-sensors-plugin-sk 1.1.0-beta.2.2.1.4 → 1.1.0-beta.2.2.1.5

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bt-sensors-plugin-sk",
-  "version": "1.1.0-beta.2.2.1.4",
-  "description": "Bluetooth Sensors for Signalk -- support for Victron devices, RuuviTag, Xiaomi, ATC and Inkbird, Ultrasonic wind meters, Mopeka tank readers, Renogy Battery and Solar Controllers (new), Aranet4 environment sensors, and Govee GVH51xx temp sensors",
+  "version": "1.1.0-beta.2.2.1.5",
+  "description": "Bluetooth Sensors for Signalk -- support for Victron devices, RuuviTag, Xiaomi, ATC and Inkbird, Ultrasonic wind meters, Mopeka tank readers, Renogy Battery and Solar Controllers, Aranet4 environment sensors, SwitchBot temp and humidity sensors, KilovaultHLXPlus smart batteries, and Govee GVH51xx temp sensors",
   "main": "index.js",
   "dependencies": {
     "dbus-next": "^0.10.2",

package/sensor_classes/KilovaultHLXPlus.js

@@ -0,0 +1,207 @@
+/*
+    Sensor class for monitoring Kilovault HLX+ batteries.
+
+    Status from the battery is collected via the BLE notify method.  A complete status
+    message consists of several fragments, which must be pieced back together.  The
+    format of the status message is described below.  All data fields are hexidecimal
+    character strings in little-endian order (e.g. "0F34" is four characters, not just two
+    bytes, and represents 0x340F (13327 decimal)).
+
+	Index   Length  Description
+	  0     1       indicator (0xb0) for start of message
+	  1     4       Voltage, in millivolts
+	  5     4       ???
+	  9     8       Current (milliamps), two's complement for negative values
+	 17     8       Energy Capacity (milliwatt-hours)
+	 25     4       Number of charge cycles
+	 29     4       State of Charge (SOC) (%)
+	 33     4       Temperature * 10 (deci-°K)
+	 37     4       status ???
+	 41     4       AFE status ???
+	 45     4       Cell 1 Voltage (millivolts)
+	 49     4       Cell 2 Voltage (millivolts)
+	 53     4       Cell 3 Voltage (millivolts)
+	 57     4       Cell 4 Voltage (millivolts)
+	 61     16      all zeroes
+	 77     16      all zeroes
+	 93     16      all zeroes
+	109     4       16-bit CRC of bytes 1 - 108, represented in big-endian order
+	113     8       eight 'R's; i.e. 'RRRRRRRR'
+
+	The format was derived from:  
+	  https://github.com/fancygaphtrn/esphome/tree/master/my_components/kilovault_bms_ble
+
+ */
+
+const BTSensor = require("../BTSensor");
+class KilovaultHLXPlus extends BTSensor{
+    constructor(device, config, gattConfig) {
+        super(device, config, gattConfig)
+        this.accumulated_buffer = Buffer.alloc(0)
+    }
+
+    static async identify(device){
+        const regex = /^\d\d\-(12|24|36)00HLX\+\d{4}/
+	// This regex will match factory-assigned names (e.g. "21-2400HLX+0013").
+	// If you have renamed the battery, you will need to manually select the sensor
+	// type during configuration.
+
+        const name = await this.getDeviceProp(device,'Name')
+        if (name && name.match(regex))
+            return this 
+        else
+            return null
+    }
+
+    hasGATT(){
+        return true
+    }
+    emitGATT(){
+        // Nothing to do here.  HLX+ only reports via BLE notify, not BLE read
+    }
+
+    async init(){
+        await super.init()
+
+        this.addMetadatum("voltage","V","Battery Voltage",
+            (buffer)=>{return Number(buffer.readInt16LE(0)) / 1000})
+        this.addMetadatum("current","A","Battery Current",
+            (buffer)=>{return buffer.readInt32LE(4) / 1000})
+        this.addMetadatum("energy","AHr","Battery Capacity",
+            (buffer)=>{return buffer.readInt32LE(8) / 1000})
+        this.addMetadatum("cycles","","Number of Charge Cycles",
+            (buffer)=>{return buffer.readInt16LE(12)})
+        this.addMetadatum("soc","ratio","Battery State of Charge",
+            (buffer)=>{return buffer.readInt16LE(14)})
+        this.addMetadatum("temperature","K","Battery Temperature",
+            (buffer)=>{return buffer.readInt16LE(16)/10 })
+
+        this.addMetadatum("status","","Battery Status",
+            (buffer)=>{return buffer.readInt16LE(18) })
+        this.addMetadatum("AFEStatus","","Battery AFE Status",
+            (buffer)=>{return buffer.readInt16LE(20) })
+
+        this.addMetadatum("cell1_voltage","V","Cell 1 Voltage",
+            (buffer)=>{return buffer.readInt16LE(22) / 1000})
+        this.addMetadatum("cell2_voltage","V","Cell 2 Voltage",
+            (buffer)=>{return buffer.readInt16LE(24) / 1000})
+        this.addMetadatum("cell3_voltage","V","Cell 3 Voltage",
+            (buffer)=>{return buffer.readInt16LE(26) / 1000})
+        this.addMetadatum("cell4_voltage","V","Cell 4 Voltage",
+            (buffer)=>{return buffer.readInt16LE(28) / 1000})
+    }
+
+    // Concatentate chunks received by notification into a complete message.
+    // A message begins with 0xb0, is 121 bytes long, and ends with eight 'R's.
+    // Preceding the string of eight 'R's, is a 16-bit CRC, calculated using
+    // bytes 1 - 108.
+    //
+    reassemble(chunk) {
+      try {
+        if (this.accumulated_buffer.length > 121) {
+          // If no complete message by now, we must have accumulated some garbage,
+          // so start over.
+          this.accumulated_buffer = Buffer.alloc(0)
+        }
+
+        // Add the new chunk to the end of the buffer.
+        this.accumulated_buffer = Buffer.concat([this.accumulated_buffer, chunk])
+      } 
+      catch (err) {
+        console.log("buffer error: ", err)
+      }
+
+      try {
+        // Discard contents of buffer before the first 0xb0.  
+        const startByte = this.accumulated_buffer.indexOf(0xb0)
+        if (startByte == -1) return
+        this.accumulated_buffer = this.accumulated_buffer.subarray(startByte)
+
+        // At this point, the buffer begins with 0xb0, which could be the start of
+        // a message, or, if something was lost, part of the CRC.  If part of the CRC,
+        // this (partial) message will eventually be discarded.
+      }
+      catch (err) {
+        console.log("buffer error: ", err)
+      }
+
+      try {
+        // Look for 'RRRRRRRR' (eight 'R's), marking the end of the message.
+	const firstR = this.accumulated_buffer.indexOf('RRRRRRRR')
+        if (firstR == -1) return	// haven't received end of message yet
+
+        // Copy the message to <message>, ignoring the 0xb0 at the beginning and
+        // the 'R's at the end.
+        const msg_buffer = this.accumulated_buffer.subarray(1, firstR)
+
+        // Remove the message from the buffer.
+        this.accumulated_buffer = this.accumulated_buffer.subarray(firstR+8)
+
+        // We might now have a complete message.  The actual message is in bytes 0-107, 
+        // and the CRC is in bytes 108-111.  
+        if (msg_buffer.length != 112) return
+
+        const rcvd_crc = Buffer.from(msg_buffer.subarray(108).toString(), 'hex').readUInt16BE()
+        const message = Buffer.from(msg_buffer.subarray(0, 108).toString(), 'hex')
+
+        // Calculate and Verify the CRC.
+        let calc_crc = 0
+        for (const byte of message) {
+          calc_crc += byte
+        }
+        calc_crc = calc_crc & 0xffff
+
+        if (rcvd_crc != calc_crc) throw new Error("invalid CRC, buffer:" + msg_buffer.toString())
+
+        // Parse the message and emit the values.
+        this.emitData("voltage", message)
+        this.emitData("current", message)
+        this.emitData("cycles", message)
+        this.emitData("soc", message)
+        this.emitData("temperature", message)
+        this.emitData("energy", message)
+
+        this.emitData("status", message)
+        this.emitData("AFEStatus", message)
+
+        this.emitData("cell1_voltage", message)
+        this.emitData("cell2_voltage", message)
+        this.emitData("cell3_voltage", message)
+        this.emitData("cell4_voltage", message)
+      }
+      catch (err) {
+        console.log("buffer error: ", err)
+      }
+    }
+
+    initGATTConnection(){ 
+        return new Promise((resolve,reject )=>{ this.device.connect().then(async ()=>{ 
+            if (!this.gattServer) { 
+                this.gattServer = await this.device.gatt() 
+                this.battService = await this.gattServer.getPrimaryService("0000ffe0-0000-1000-8000-00805f9b34fb") 
+                this.battCharacteristic = await this.battService.getCharacteristic("0000ffe4-0000-1000-8000-00805f9b34fb")
+                }
+                resolve(this)
+             }) .catch((e)=>{ reject(e.message) }) }) 
+    }
+
+    initGATTNotifications() { 
+        Promise.resolve(this.battCharacteristic.startNotifications().then(()=>{    
+            this.battCharacteristic.on('valuechanged', buffer => {
+                this.reassemble(buffer)
+            })
+        }))
+    }
+  
+    async stopListening(){
+        super.stopListening()
+        if (this.battCharacteristic  && await this.battCharacteristic.isNotifying()) {
+            await this.battCharacteristic.stopNotifications()
+            this.battCharacteristic=null
+        }
+        if (await this.device.isConnected()){
+               await this.device.disconnect()
+        }
+    }
+}
+module.exports=KilovaultHLXPlus