@bitpoolos/edge-bacnet 1.5.2 → 1.6.0

package/CHANGELOG.md

@@ -1,10 +1,160 @@
 # Changelog
 
+## [1.6.0] - 09-04-2025
+
+New features:
+
+- New node - Inspector version 1:
+
+  - Link the outputs of all of your Read nodes and Gateway node into the inspector node for a more detailed analysis of that current state of your site.
+  - There is a custom UI which can be viewed once the node is placed and deployed, via the open webpage link in the node properties view.
+  - Basic point status statistics can be output in MQTT format via an injection of msg.type = "sendMqttStats" directly into the inspector node. This can be done with a node-red inject node or a bitpool-inject node.
+  - The custom UI shows a data table with rich meta data, that can be filtered.
+  - The inspector node comes with a variety of API routes that can be used for analysis and engineering
+  - API routes available:
+
+    - /inspector
+      - view UI in web browser
+
+    - /inspector-downloadhtml
+      - downloads the html of the inspector in its current state
+
+    - /inspector-downloadhtml?filter=tableKey&value=value1,value2
+      - downloads the html of the inspector, but with a applied filter to the table. 
+      - tableKey in the above example can be any of the table columns, only 1 tableKey may be filtered on: 
+        deviceID, objectType, objectInstance, presentValue, dataModelStatus, pointName, discoveredBACnetPointName, displayName, deviceName, ipAddress, area, key, topic, lastSeen, error
+      - value=value1,value2 etc can be any value that the tableKey can contain. This parameter can accept many comma separated values
+      - an example filter request may look like: 
+        /inspector-downloadhtml?filter=dataModelStatus&value=error,missing
+
+    - /getModelStats
+      - returns JSON data with analysis of the BACnet model
+      - contains point status, metrics, and detailed information
+
+    - /pointstoread
+      - downloads CSV file with all points in the read list
+      - format: [siteName]_PointsToRead_[timestamp].csv
+
+    - /getpointerrors
+      - downloads CSV file with all points that have errors
+      - format: [siteName]_PointErrors_[timestamp].csv
+      
+    - /getmodelstatscsv
+      - downloads CSV file with all model stats data in CSV format
+      - format: [siteName]_ModelStats_[timestamp].csv
+      
+    - /publishedpointslist
+      - downloads CSV file with all published points and their current values
+      - format: [siteName]_PublishedPointsList_[timestamp].csv
+      - outputs mqtt topic and payloads with statistics about the current state of the bacnet network
+      - output topics:
+          EDGE_DEVICE_{IP_ID}/STATUS/LAST_POINT_PUSHED_TIME
+          payload: Timestamp of when the last point was pushed (ISO string)
+          EDGE_DEVICE_{IP_ID}/STATUS/LAST_STAT_CALC_TIME
+          payload: Current timestamp (ISO string)
+          EDGE_DEVICE_{IP_ID}/STATUS/UPTIME
+          payload: System uptime formatted as string (e.g., "Uptime: 3 days, 5 hours, 12 minutes, 45 seconds")
+          EDGE_DEVICE_{IP_ID}/STATUS/ONLINE_POINTS
+          payload: Number of online points
+          EDGE_DEVICE_{IP_ID}/STATUS/OFFLINE_POINTS
+          payload: Number of offline points
+          EDGE_DEVICE_{IP_ID}/STATUS/TOTAL_POLLED_POINTS
+          payload: Total number of polled points
+          EDGE_DEVICE_{IP_ID}/STATUS/AVERAGE_TIME_SINCE_COV_IN_SECONDS
+          payload: Average time since last change of value in seconds
+          EDGE_DEVICE_{IP_ID}/STATUS/TOTAL_POINTS_TO_READ
+          payload: Total number of points to read
+          EDGE_DEVICE_{IP_ID}/STATUS/DISCOVERED_POINT_COUNT
+          payload: Number of discovered points
+          EDGE_DEVICE_{IP_ID}/STATUS/DISCOVERED_DEVICE_COUNT
+          payload: Number of discovered devices
+
+          where {IP_ID} is the IP address of the device with periods removed (e.g., 192.168.1.100 becomes 192168110).
+          each of these topics includes the site name as a tag in the message metadata with format geoAddr={siteName}.
+
+  - Additional input options: 
+    - reset - resets the complete data model used for all of the inspector analytics
+      - msg input format: msg.reset = true
+
+    - sendMqttStats - outputs additional mqtt statistics
+      - msg input format:  msg.type = sendMqttStats
+      - output topics: 
+        EDGE_DEVICE_{siteName}/BACNETSTATS/ok
+        payload: Number of points with OK status
+        EDGE_DEVICE_{siteName}/BACNETSTATS/error
+        payload: Number of points with error status
+        EDGE_DEVICE_{siteName}/BACNETSTATS/missing
+        payload: Number of missing points
+        EDGE_DEVICE_{siteName}/BACNETSTATS/warnings
+        payload: Number of points with warnings
+        EDGE_DEVICE_{siteName}/BACNETSTATS/moved
+        payload: Number of points that have moved (e.g changed object instance)
+        EDGE_DEVICE_{siteName}/BACNETSTATS/deviceIdChange
+        payload: Number of points with changed device IDs
+        EDGE_DEVICE_{siteName}/BACNETSTATS/deviceIdConflict
+        payload: Number of points with conflicting device IDs
+        EDGE_DEVICE_{siteName}/BACNETSTATS/unmapped
+        payload: Number of unmapped points
+        EDGE_DEVICE_{siteName}/BACNETSTATS/offlinePercentage
+        payload: Percentage of points that are offline
+
+        where {siteName} is the site name configured in the inspector node.
+
+
+- Right click -> Update Point on a individual point in the device tree. (Read node UI)
+
+- Added programmatic reinitialize/clear points on BACnet server via injecting { msg.reinitializeBacnetServer: true } into the gateway node. Optionally can include a msg.responseTopic string to get a confrimation published to that topic output from the gateway node on sucessfull reinitialize.
+  - Example workflow:
+    -inject into gateway node:
+    ```javascript
+    msg = {
+      reinitializeBacnetServer: true,
+      responseTopic: "/mqtt/subscriber/topic",
+    };
+    ```
+    -upon sucessfull reinitialize, gateway outputs:
+    ```javascript
+    {
+      topic: "/mqtt/subscriber/topic";
+      payload: "Server successfully reinitialized";
+    }
+    ```
+
+Refactor:
+
+- Reading and Writing to the cache file of the datamodel.
+  - write operations are now locked to 1 operation at a time
+  - a rolling secondary backup file is now created, which can be used in case of corruption of the primary file
+
+- Ported more of the project to async / await program flow vs Promise.then
+
+Bug fixes:
+
+- timeouts removed from import and export database file, as they can be very large.
+
+## [1.5.3] - 23-01-2025
+
+New feature:
+
+- import / export buttons added to new tab in gateway node, used to manage the complete data model for backup or restore
+- associated API end points for programatic backing up or restoring - /bitpool-bacnet-data/getDataModel; /bitpool-bacnet-data/updateDataModel;
+
+Further async / await refactoring
+
+Bug fixes:
+
+- incorrect device name in read list export
+- read command indexing unhandled scenario
+- duplicating points in read list after pressing refresh tree button
+- Multi State Values and other state text based points not being handled correctly in large volume scenarios
+
+NOTE:
+New importing and exporting feature handles a .json file instead of the .cfg file used in the back end. This is due to browsers flagging .cfg files as malicious. The contents of the file are unchanged.
+
 ## [1.5.2] - 10-01-2025
 
 Mismatched network request hot fix
 
-
 ## [1.5.1] - 13-11-2024
 
 ### Summary

package/bacnet_client.js

@@ -4,13 +4,13 @@
 
 const bacnet = require("./resources/node-bacstack-ts/dist/index.js");
 const baEnum = bacnet.enum;
-const bacnetIdMax = baEnum.ASN1_MAX_PROPERTY_ID;
 const { EventEmitter } = require("events");
 const {
   getUnit,
   roundDecimalPlaces,
   parseBacnetError,
   getBacnetErrorString,
+  Read_Config_Async,
   Read_Config_Sync,
   isNumber,
   decodeBitArray,
@@ -41,20 +41,6 @@ class BacnetClient extends EventEmitter {
     that.portRangeMatrix = config.portRangeMatrix;
 
     try {
-      if (that.config.cacheFileEnabled) {
-        let cachedData = JSON.parse(Read_Config_Sync());
-        if (cachedData && typeof cachedData == "object") {
-          if (cachedData.renderList) that.renderList = cachedData.renderList;
-          if (cachedData.deviceList) {
-            cachedData.deviceList.forEach(function (device) {
-              let newBacnetDevice = new BacnetDevice(true, device);
-              that.deviceList.push(newBacnetDevice);
-            });
-          }
-          if (cachedData.pointList) that.networkTree = cachedData.pointList;
-          if (cachedData.renderListCount) that.renderListCount = cachedData.renderListCount;
-        }
-      }
 
       that.roundDecimal = config.roundDecimal;
       that.apduSize = config.apduSize;
@@ -73,6 +59,8 @@ class BacnetClient extends EventEmitter {
       };
 
       try {
+        that.readCachedFile();
+
         that.client = new bacnet.Client({
           apduTimeout: config.apduTimeout,
           interface: config.localIpAdrress,
@@ -115,22 +103,48 @@ class BacnetClient extends EventEmitter {
 
         that.scheduler.addSimpleIntervalJob(buildNetworkTreeJob);
 
-        that.globalWhoIs();
-
         setTimeout(() => {
-          that.queryDevices();
-          that.buildJsonTree();
+          that.globalWhoIs();
+          setTimeout(() => {
+            that.queryDevices();
+            that.buildJsonTree();
+          }, "4000");
         }, "5000");
+
       } catch (e) {
         that.logOut("Issue initializing client: ", e);
       }
 
-      //who is callback
-      that.client.on("iAm", (device) => {
-        if (device.address !== that.config.localIpAdrress) {
-          if (that.scanMatrix.length > 0) {
-            let matrixMap = that.scanMatrix.filter((ele) => device.deviceId >= ele.start && device.deviceId <= ele.end);
-            if (matrixMap.length > 0) {
+      try {
+
+        //who is callback
+        that.client.on("iAm", (device) => {
+          if (device.address !== that.config.localIpAdrress) {
+            if (that.scanMatrix.length > 0) {
+              let matrixMap = that.scanMatrix.filter((ele) => device.deviceId >= ele.start && device.deviceId <= ele.end);
+              if (matrixMap.length > 0) {
+                //only add unique device to array
+                let foundIndex = that.deviceList.findIndex((ele) => ele.getDeviceId() == device.deviceId);
+                if (foundIndex == -1) {
+                  let newBacnetDevice = new BacnetDevice(false, device);
+                  newBacnetDevice.setLastSeen(Date.now());
+                  if (newBacnetDevice.getIsMstpDevice()) {
+                    that.addToParentMstpNetwork(newBacnetDevice);
+                  }
+                  that.deviceList.push(newBacnetDevice);
+                  that.addToNetworkTree(newBacnetDevice);
+                } else if (foundIndex !== -1) {
+                  that.deviceList[foundIndex].updateDeviceConfig(device);
+                  that.deviceList[foundIndex].setLastSeen(Date.now());
+                  if (that.deviceList[foundIndex].getIsMstpDevice()) {
+                    that.addToParentMstpNetwork(that.deviceList[foundIndex]);
+                  }
+                  that.addToNetworkTree(that.deviceList[foundIndex]);
+                }
+                //emit event for node-red to log
+                that.emit("deviceFound", device);
+              }
+            } else {
               //only add unique device to array
               let foundIndex = that.deviceList.findIndex((ele) => ele.getDeviceId() == device.deviceId);
               if (foundIndex == -1) {
@@ -149,49 +163,49 @@ class BacnetClient extends EventEmitter {
                 }
                 that.addToNetworkTree(that.deviceList[foundIndex]);
               }
+
               //emit event for node-red to log
               that.emit("deviceFound", device);
             }
-          } else {
-            //only add unique device to array
-            let foundIndex = that.deviceList.findIndex((ele) => ele.getDeviceId() == device.deviceId);
-            if (foundIndex == -1) {
-              let newBacnetDevice = new BacnetDevice(false, device);
-              newBacnetDevice.setLastSeen(Date.now());
-              if (newBacnetDevice.getIsMstpDevice()) {
-                that.addToParentMstpNetwork(newBacnetDevice);
-              }
-              that.deviceList.push(newBacnetDevice);
-              that.addToNetworkTree(newBacnetDevice);
-            } else if (foundIndex !== -1) {
-              that.deviceList[foundIndex].updateDeviceConfig(device);
-              that.deviceList[foundIndex].setLastSeen(Date.now());
-              if (that.deviceList[foundIndex].getIsMstpDevice()) {
-                that.addToParentMstpNetwork(that.deviceList[foundIndex]);
-              }
-              that.addToNetworkTree(that.deviceList[foundIndex]);
-            }
-
-            //emit event for node-red to log
-            that.emit("deviceFound", device);
           }
+        });
+      } catch (e) {
+        that.logOut("Issue with creating bacnet client, see error:  ", e);
+      }
+
+      that.client.on("error", (err) => {
+        that.logOut("Error occurred: ", err);
+
+        if (err.errno == -4090) {
+          that.logOut("Invalid Client information or incorrect IP address provided");
+        } else if (err.errno == -49) {
+          that.logOut("Invalid IP address provided");
+        } else {
+          that.reinitializeClient(that.config);
         }
       });
     } catch (e) {
-      that.logOut("Issue with creating bacnet client, see error:  ", e);
+      console.log("BACnet Client client binder error: ", e);
     }
+  }
 
-    that.client.on("error", (err) => {
-      that.logOut("Error occurred: ", err);
-
-      if (err.errno == -4090) {
-        that.logOut("Invalid Client information or incorrect IP address provided");
-      } else if (err.errno == -49) {
-        that.logOut("Invalid IP address provided");
-      } else {
-        that.reinitializeClient(that.config);
+  async readCachedFile() {
+    let that = this;
+    if (that.config.cacheFileEnabled) {
+      const cachedData = await Read_Config_Async();
+      const parsedData = JSON.parse(cachedData);
+      if (parsedData && typeof parsedData == "object") {
+        if (parsedData.renderList) that.renderList = parsedData.renderList;
+        if (parsedData.deviceList) {
+          parsedData.deviceList.forEach(function (device) {
+            let newBacnetDevice = new BacnetDevice(true, device);
+            that.deviceList.push(newBacnetDevice);
+          });
+        }
+        if (parsedData.pointList) that.networkTree = parsedData.pointList;
+        if (parsedData.renderListCount) that.renderListCount = parsedData.renderListCount;
       }
-    });
+    }
   }
 
   testFunction(address, port, type, instance, property) {
@@ -534,7 +548,6 @@ class BacnetClient extends EventEmitter {
               }
             }
             try {
-
               await that.updateDeviceName(device);
 
               if (device.getSegmentation() !== 3) {
@@ -579,23 +592,16 @@ class BacnetClient extends EventEmitter {
     }
   }
 
-  updateDeviceName(device) {
-    let that = this;
-    return new Promise((resolve, reject) => {
-      that
-        ._getDeviceName(device)
-        .then(function (deviceObject) {
-          if (typeof deviceObject.name == "string") {
-            device.setDeviceName(deviceObject.name + " " + device.getDeviceId());
-            device.setPointsList(deviceObject.devicePointEntry);
-          }
-          resolve();
-        })
-        .catch(function (e) {
-          that.logOut("updateDeviceName error: ", e);
-          resolve();
-        });
-    });
+  async updateDeviceName(device) {
+    try {
+      const deviceObject = await this._getDeviceName(device);
+      if (typeof deviceObject?.name === "string") {
+        device.setDeviceName(deviceObject.name + " " + device.getDeviceId());
+        device.setPointsList(deviceObject.devicePointEntry);
+      }
+    } catch (e) {
+      this.logOut("updateDeviceName error: ", e);
+    }
   }
 
   reinitializeClient(config) {
@@ -729,15 +735,15 @@ class BacnetClient extends EventEmitter {
         // Process points for the current device
         const pointsToRead = readConfig.pointsToRead[key];
         const pointNames = Object.keys(pointsToRead);
-        let totalPoints = pointNames.length;
+        let totalPoints = pointNames.length - 1;
         let requestArray = [];
         let processedPoints = 0; // Counter for processed points
 
         // Process each point for the device in batches
         for (let i = 0; i < pointNames.length; i++) {
+
           const pointName = pointNames[i];
           if (pointName === "deviceName") {
-            totalPoints = totalPoints - 1;
             continue;
           }
 
@@ -758,8 +764,7 @@ class BacnetClient extends EventEmitter {
           }
 
           // Process the batch when the request array is full or the last point is reached
-          if (requestArray.length === maxObjectCount || i === pointNames.length - 1) {
-
+          if (requestArray.length === maxObjectCount) {
             if (device.getProtocolServiceSupport("ReadPropertyMultiple") == true) {
               await that.processBatch(device, requestArray, deviceName, bacnetResults, that, roundDecimal);
             } else {
@@ -769,6 +774,16 @@ class BacnetClient extends EventEmitter {
             requestArray = [];
             // Increment the processed points counter
             processedPoints += maxObjectCount;
+          } else if (i === pointNames.length - 1) {
+            if (device.getProtocolServiceSupport("ReadPropertyMultiple") == true) {
+              await that.processBatch(device, requestArray, deviceName, bacnetResults, that, roundDecimal);
+            } else {
+              await that.processIndividualPoints(device, requestArray, deviceName, bacnetResults, that, roundDecimal);
+            }
+
+            requestArray = [];
+            // Increment the processed points counter
+            processedPoints += i;
           }
 
           // Check if all points for the device have been processed
@@ -870,17 +885,23 @@ class BacnetClient extends EventEmitter {
       const { objectId, pointRef, pointName } = request;
       try {
 
-
         const result = await that.updatePoint(device, pointRef);
 
-        //const result = await that.updatePointWithRetry(device, pointRef, 1);
-
-
         if (result.objectId.type == objectId.type && result.objectId.instance == objectId.instance) {
           const val = result.values[0].value;
 
           if (isNumber(val)) {
             pointRef.presentValue = roundDecimalPlaces(val, roundDecimal);
+
+            if (pointRef.meta.objectId.type == 19 || pointRef.meta.objectId.type == 13 || pointRef.meta.objectId.type == 14) {
+              if (pointRef.stateTextArray && typeof pointRef.stateTextArray[0].value !== "object") {
+                if (val != 0) {
+                  pointRef.presentValue = pointRef.stateTextArray[val - 1].value;
+                } else {
+                  pointRef.presentValue = pointRef.stateTextArray[val].value;
+                }
+              }
+            }
           } else {
             pointRef.presentValue = val;
           }
@@ -905,24 +926,13 @@ class BacnetClient extends EventEmitter {
     }
   }
 
-  updateManyPoints(device, points) {
-    let that = this;
-    return new Promise((resolve, reject) => {
-
-      // let readOptions = {
-      //   maxSegments: device.getMaxSe,
-      //   maxApdu: that.readPropertyMultipleOptions.maxApdu,
-      // };
-
-      that
-        ._readObjectWithRequestArray(device, points, that.readPropertyMultipleOptions)
-        .then(function (results) {
-          resolve(results);
-        })
-        .catch(function (err) {
-          reject(err);
-        });
-    });
+  async updateManyPoints(device, points) {
+    try {
+      const results = await this._readObjectWithRequestArray(device, points, this.readPropertyMultipleOptions);
+      return results;
+    } catch (error) {
+      throw error;
+    }
   }
 
   updatePointWithRetry(device, point, retryCount = 1) {
@@ -941,18 +951,63 @@ class BacnetClient extends EventEmitter {
     return tryUpdate(retryCount);
   }
 
+  //used for manual point updates in the UI tree
+  async updateIndividualPoint(deviceKey, pointKey) {
+    let that = this;
+    try {
+      let device = that.deviceList.find((ele) => ele.getDeviceId() == deviceKey.split("-")[1]);
+      const pointType = parseInt(pointKey.split(":")[0]);
+      const pointInstance = parseInt(pointKey.split(":")[1]);
+      const promiseArray = [];
+      const result = await that._readObjectFull(device, pointType, pointInstance);
+
+      if (!result.error) {
+        device.setLastSeen(Date.now());
+        if (result.length > 0 && Array.isArray(result)) {
+          promiseArray.push(...result);
+        } else {
+          promiseArray.push(result);
+        }
+      }
+
+      await that.buildNetworkModel(promiseArray, device);
+
+      return true;
+    } catch (e) {
+      throw e
+    }
+  }
+
+  //used in the doRead querying work flow
   updatePoint(device, point) {
     let that = this;
     let addressObject = {
       address: device.getAddress(),
       port: device.getPort(),
     };
+
+    let maxSegments = that.readPropertyMultipleOptions.maxSegments;
+    let maxApdu = that.readPropertyMultipleOptions.maxApdu;
+
+    if (device.getSegmentation() == 3) {
+      maxSegments = 0;
+    }
+
+    if (device.getMaxApdu() == 480) {
+      maxApdu = 3;
+    }
+
+    let settings = {
+      maxSegments: maxSegments,
+      maxApdu: maxApdu,
+    }
+
     return new Promise((resolve, reject) => {
       that.client.readProperty(
         addressObject,
         { type: point.meta.objectId.type, instance: point.meta.objectId.instance },
         baEnum.PropertyIdentifier.PRESENT_VALUE,
-        that.readPropertyMultipleOptions,
+        settings,
         (err, value) => {
           if (err) {
             reject(err);
@@ -1552,6 +1607,22 @@ class BacnetClient extends EventEmitter {
     });
   }
 
+  getDataModel() {
+    let that = this;
+    return new Promise(async function (resolve, reject) {
+      try {
+        resolve({
+          renderList: that.renderList,
+          deviceList: that.deviceList,
+          pointList: that.networkTree,
+          renderListCount: that.renderListCount,
+        });
+      } catch (e) {
+        reject(e);
+      }
+    });
+  }
+
   updatePointsList(json) {
     let that = this;
     json.deviceList.forEach(function (updatedDevice) {
@@ -1587,6 +1658,29 @@ class BacnetClient extends EventEmitter {
     });
   }
 
+  updateDataModel(json) {
+    let that = this;
+    return new Promise(async function (resolve, reject) {
+      try {
+        if (json.body.renderList) {
+          that.renderList = json.body.renderList;
+        }
+        if (json.body.deviceList) {
+          await that.updateDeviceList(json);
+        }
+        if (json.body.pointList) {
+          that.networkTree = json.body.pointList;
+        }
+        if (json.body.renderListCount) {
+          that.renderListCount = json.body.renderListCount;
+        }
+        resolve();
+      } catch (e) {
+        reject(e);
+      }
+    });
+  }
+
   sortDevices(a, b) {
     if (a.deviceId < b.deviceId) {
       return -1;
@@ -1777,7 +1871,7 @@ class BacnetClient extends EventEmitter {
         requestMutex.release();
       }
 
-      await this.buildResponse(promiseArray, device);
+      await this.buildNetworkModel(promiseArray, device);
       this.lastNetworkPoll = Date.now();
 
       return { deviceList: this.deviceList, pointList: this.networkTree };
@@ -1787,8 +1881,8 @@ class BacnetClient extends EventEmitter {
     }
   }
 
-  // Builds response object for a fully qualified
-  buildResponse(fullObjects, device) {
+  // Builds the data rich bacnet network model
+  buildNetworkModel(fullObjects, device) {
     let that = this;
     const reg = /[$#\/\\+,]/gi;
     return new Promise(function (resolve, reject) {
@@ -1856,7 +1950,7 @@ class BacnetClient extends EventEmitter {
                             }
                             values[objectId].meta.arrayIndex = object.index;
                           } catch (e) {
-                            that.logOut("buildResponse PRESENT_VALUE error: ", e);
+                            that.logOut("buildNetworkModel PRESENT_VALUE error: ", e);
                           }
                           break;
                         case baEnum.PropertyIdentifier.DESCRIPTION:
@@ -1922,7 +2016,7 @@ class BacnetClient extends EventEmitter {
                               }
                             }
                           } catch (e) {
-                            that.logOut("buildResponse STATE_TEXT error: ", e);
+                            that.logOut("buildNetworkModel STATE_TEXT error: ", e);
                           }
                           break;
                         case baEnum.PropertyIdentifier.VENDOR_NAME:

package/bacnet_device.js

@@ -88,7 +88,9 @@ class BacnetDevice {
     }
 
     setDisplayName(displayName) {
-        this.displayName = displayName;
+        if (typeof displayName == "string") {
+            this.displayName = displayName;
+        }
     }
 
     getDisplayName() {