@bitpoolos/edge-bacnet 1.5.3 → 1.6.1

package/CHANGELOG.md

@@ -1,27 +1,172 @@
 # Changelog
 
+## [1.6.1] - 14-04-2025
+
+Bug fixes: 
+  - Inspector stats were calculating incorrectly in certain scenarios
+  - Inspector downloaded HTML files had incorrect stat percentages
+  - Inspector Last_Polled_Time stat was always "UNKNOWN", now shows correct date time.
+
+Minor updates: 
+  - Inspector BACnet main stats now output on msg.type = getBacnetStats inject. Can be set on a scheduled inject. 
+  - Updated Examples with Inspector
+
+
+## [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;
+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. 
+- 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) {
@@ -578,25 +592,6 @@ 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);
@@ -931,32 +926,8 @@ 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 {
-      // let readOptions = {
-      //   maxSegments: device.getMaxSe,
-      //   maxApdu: that.readPropertyMultipleOptions.maxApdu,
-      // };
-
       const results = await this._readObjectWithRequestArray(device, points, this.readPropertyMultipleOptions);
       return results;
     } catch (error) {
@@ -980,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);
@@ -1855,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 };
@@ -1865,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) {
@@ -1934,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:
@@ -2000,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_gateway.html

@@ -106,6 +106,16 @@
         body: JSON.stringify({ d: device }),
       }).then((res) => res.json());
     }
+    updatePoint(device, pointKey) {
+      return fetch(RED.settings.httpNodeRoot + "bitpool-bacnet-data/updatePoint", {
+        method: "POST",
+        headers: {
+          Accept: "application/json",
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ d: device, k: pointKey }),
+      }).then((res) => res.json());
+    }
     setDeviceDisplayName(device, displayName) {
       return fetch(RED.settings.httpNodeRoot + "bitpool-bacnet-data/setDeviceDisplayName", {
         method: "POST",
@@ -143,6 +153,7 @@
     defaults: {
       name: { value: "" },
       local_device_address: { value: "", required: true },
+      local_interface_name: { value: "", required: false },
       apduTimeout: { value: 6000 },
       roundDecimal: { value: 2 },
       local_device_port: { value: 47808, required: true },
@@ -241,6 +252,13 @@
         });
       }
 
+      //sets name of network adapter
+      document.getElementById("node-input-local_device_address").addEventListener("change", function () {
+        let selectedText = this.options[this.selectedIndex].innerText;
+        let nicName = selectedText.split(":")[0];
+        node.local_interface_name = nicName;
+      });
+
       queryAdapters();
 
       window.confirmDialogExists = window.confirmDialogExists || false;
@@ -338,7 +356,6 @@
       vueapp.use(primevue.confirmationservice);
       node.vm1 = vueapp.mount("#serverParent");
 
-
       // Import Device List
       $("#file-upload").on("change", function (event) {
         const input = event.target.files[0];
@@ -356,7 +373,7 @@
             contentType: "application/json",
             data: JSON.stringify(jsonPayload),
             success: function (result) { },
-            timeout: 15000,
+            timeout: 0,
           });
         };
 
@@ -374,7 +391,7 @@
             aEle.setAttribute("download", "bitpool-bacnet-devices.json");
             aEle.click();
           },
-          timeout: 10000,
+          timeout: 0,
         });
       });
 
@@ -395,7 +412,7 @@
             contentType: "application/json",
             data: JSON.stringify(jsonPayload),
             success: function (result) { },
-            timeout: 15000,
+            timeout: 0,
           });
         };
 
@@ -413,7 +430,7 @@
             aEle.setAttribute("download", "edge-bacnet-datastore.json");
             aEle.click();
           },
-          timeout: 10000,
+          timeout: 0,
         });
       });
 
@@ -796,7 +813,6 @@
       font-weight: bold;
       font-size: 16px;
       width: auto !important;
-      
     }
     .database-file-label-div {
       padding-top: 15px;