Merge pull request #26 from athombv/master

MMIP

Author: nozols

.github/workflows/build.yml

@@ -16,10 +16,10 @@ jobs:
     runs-on: buildjet-2vcpu-ubuntu-2204-arm
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e
         with:
           node-version-file: '.nvmrc'
           registry-url: 'https://npm.pkg.github.com'

.github/workflows/lint.yml

@@ -13,5 +13,20 @@ on:
 jobs:
   lint:
     name: Lint
-    uses: athombv/athom-github-workflow/.github/workflows/lint.yml@master
-    secrets: inherit
+    runs-on: buildjet-2vcpu-ubuntu-2204-arm
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+
+      - name: Setup Node.js
+        uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e
+        with:
+          node-version-file: '.nvmrc'
+          registry-url: 'https://npm.pkg.github.com'
+
+      - name: Lint
+        run: |
+          npm ci --ignore-scripts --audit=false
+          npm run lint
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.HOMEY_GITHUB_ACTIONS_BOT_PERSONAL_ACCESS_TOKEN }}

.github/workflows/npm-version.yml

@@ -38,10 +38,10 @@ jobs:
           exit 1
 
       - name: Checkout git repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e
         with:
           node-version-file: '.nvmrc'
           registry-url: 'https://npm.pkg.github.com'

.github/workflows/release.yml

@@ -12,10 +12,10 @@ jobs:
     runs-on: buildjet-2vcpu-ubuntu-2204-arm
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e
         with:
           node-version-file: '.nvmrc'
           registry-url: 'https://npm.pkg.github.com'
@@ -55,7 +55,7 @@ jobs:
         # Post a Slack notification on success/failure
       - name: Slack notify
         if: always()
-        uses: innocarpe/actions-slack@v1
+        uses: innocarpe/actions-slack@b2f50d9d8037ef8a1f77fa4659767747120124e4
         with:
           status: ${{ job.status }}
           success_text: '${{github.repository}} - Published ${{ env.package_name }}@${{ env.package_version }} to GitHub Packages Registry 🚀'

.github/workflows/test.yml

@@ -13,5 +13,23 @@ on:
 jobs:
   test:
     name: Test
-    uses: athombv/athom-github-workflow/.github/workflows/test.yml@master
-    secrets: inherit
+    runs-on: buildjet-2vcpu-ubuntu-2204-arm
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+
+      - name: Setup Node.js
+        uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e
+        with:
+          node-version-file: '.nvmrc'
+          registry-url: 'https://npm.pkg.github.com'
+
+      - name: Build
+        run: |
+          npm ci --audit=false
+          npm run build
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.HOMEY_GITHUB_ACTIONS_BOT_PERSONAL_ACCESS_TOKEN }}
+
+      - name: Test
+        run: npm run test

.gitignore

@@ -1,2 +1,3 @@
 /node_modules
-/dist
+/dist
+/private

README.md

@@ -1,5 +1,8 @@
 # DSMR Parser
 
+[![Test](https://github.com/athombv/node-dsmr-parser/actions/workflows/test.yml/badge.svg)](https://github.com/athombv/node-dsmr-parser/actions/workflows/test.yml)
+[![Build](https://github.com/athombv/node-dsmr-parser/actions/workflows/build.yml/badge.svg)](https://github.com/athombv/node-dsmr-parser/actions/workflows/build.yml)
+
 This module can parse Dutch Smart Meter Requirements (DSMR) messages, and return their contents as JavaScript Objects.
 
 ## Installation
@@ -109,7 +112,7 @@ Result: {
 }
 ```
 
-### Using Homey Energy Dongle
+### Connecting Homey Energy Dongle using USB
 
 When you connect a PC to Homey Energy Dongle, you can read the raw data from the meter from Homey Energy Dongle's USB port. An example
 script of how to do this is located in [`examples/homey-energy-dongle-usb.js`](./examples/homey-energy-dongle-usb.js). To run this example you need to:
@@ -143,3 +146,34 @@ If the data from your meter is encrypted, you'll need to provide the decryption
 ```sh
 node examples/homey-energy-dongle-usb.js /dev/tty.usbmodem101 1234567890123456
 ```
+
+### Connection Homey Energy Dongle using WebSocket
+
+Homey Energy Dongle has a Local WebSocket API. An example script of how to use this Local API is located in [`examples/homey-energy-dongle-ws.js`](./examples/homey-energy-dongle-ws.js).
+To run this example, you need to:
+
+1. Have NodeJS and git installed on your system
+2. Open a terminal window
+3. Clone this repository
+
+```sh
+git clone https://github.com/athombv/node-dsmr-parser
+```
+
+4. Install the dependencies and build the project
+
+```sh
+cd node-dsmr-parser
+npm ci
+npm run build
+```
+
+5. Connect Homey Energy Dongle to a Smart Meter
+6. Set up Homey Energy Dongle in the Homey app
+7. Enable the Local API in Homey Energy Dongle's settings in Homey
+   - You can also find Homey Energy Dongle's IP address here
+8. Run the example script:
+
+```sh
+node examples/homey-energy-dongle-ws.js <ip> <decryption key (optional)>
+```

examples/homey-energy-dongle-usb.js

@@ -81,7 +81,7 @@ const parser = DSMR.createStreamParser({
       console.log(result.raw);
       console.log('Parsed telegram:');
       delete result.raw;
-      console.log(result);
+      console.dir(result, { depth: Infinity });
     }
   },
 });

examples/homey-energy-dongle-ws.js

@@ -0,0 +1,142 @@
+/*
+ * This is an example of how to parse Smart Meter data when connected to the WebSocket server of a
+ * Homey Energy Dongle. Homey Energy Dongle will output the raw data from the connected Smart Meter
+ * over its WebSocket server. This data can be parsed using the DSMR parser library.
+ *
+ * To get started, first make sure to enable the local API in the device settings of the Homey app.
+ * There you can find the IP address of the Homey Energy Dongle as well. Then run this script as
+ * follows:
+ *
+ * node examples/homey-energy-dongle-ws.js <ip> <decryption key (optional)>
+ *
+ * The script will automatically connect to the Homey Energy Dongle and start parsing data from your
+ * Smart Meter!
+ */
+
+import WebSocket, { createWebSocketStream } from 'ws';
+import { DSMRError, DSMR } from '@athombv/dsmr-parser';
+
+const ENERGY_DONGLE_IP = process.argv[2];
+const DECRYPTION_KEY = process.argv[3];
+
+if (!ENERGY_DONGLE_IP) {
+  console.log('Usage: node examples/homey-energy-dongle-ws.js <ip> <decryption key (optional)>');
+  console.log('No IP address provided.');
+  process.exit(1);
+}
+
+if (DECRYPTION_KEY) {
+  console.log(`Decryption key: ${DECRYPTION_KEY}`);
+}
+
+/** @type {WebSocket | undefined} */
+let ws;
+
+process.on('SIGINT', () => {
+  console.log('Shutting down...');
+  if (ws) {
+    ws.terminate();
+    ws.close();
+    console.log('Connection closed');
+  }
+
+  console.log('Goodbye!');
+  process.exit(0);
+});
+
+// You can obtain the address of Homey Energy Dongle by using mDNS discovery.
+// Homey Energy Dongle can be found on the _energydongle._tcp service. This service contains
+// the "p" (short for path) and "v" (short for version) TXT records.
+// If the websocket server is not enabled, the "p" record will not be set.
+// The "p" record contains the path to the websocket server.
+const address = `ws://${ENERGY_DONGLE_IP}:80/ws`;
+
+while (true) {
+  console.log(`Connecting to ${address}`);
+
+  // Use the ws package to handle the WebSocket connection to the Homey Energy Dongle.
+  ws = new WebSocket(address);
+  let interval;
+  let receivedPong = false;
+
+  // If the connection fails, log the error and terminate the connection.
+  ws.on('error', (error) => {
+    console.log('WS Error:', error);
+    ws.terminate();
+  });
+
+  // If the connection is opened, log the event and start the ping interval.
+  // The ping interval makes sure the connection is still alive by sending a ping every so often.
+  ws.on('open', () => {
+    console.log(`Connected to ${address}`);
+
+    interval = setInterval(() => {
+      if (!receivedPong) {
+        console.log('No pong received, closing connection');
+        ws.close();
+        ws.terminate();
+        return;
+      }
+
+      receivedPong = false;
+      ws.ping();
+    }, 10_000);
+
+    ws.ping();
+  });
+
+  // Set a flag when a pong is received.
+  ws.on('pong', () => {
+    receivedPong = true;
+  });
+
+  // Stream all messages from the WebSocket connection.
+  // The DSMR library will parse incoming data from the websocket,
+  const stream = createWebSocketStream(ws);
+
+  stream.on('data', (data) => {
+    console.log('Stream data:', data.toString());
+  });
+
+  // If the stream encounters an error, log the error and terminate the connection.
+  stream.on('error', (error) => {
+    console.log('Stream error:', error);
+    ws.terminate();
+  });
+
+  // Create a DSMR parser that listens to the stream.
+  const parser = DSMR.createStreamParser({
+    stream,
+    decryptionKey: DECRYPTION_KEY,
+    detectEncryption: true,
+    callback: (error, result) => {
+      if (error instanceof DSMRError) {
+        console.error('Error parsing DSMR data:', error.message);
+        console.error('Raw data:', error.rawTelegram?.toString('hex'));
+      } else if (error) {
+        console.error('Error:', error);
+      } else {
+        // Not very useful to log the raw telegram here as it is already logged by the data listener on the stream.
+        delete result.raw;
+        console.log('Parsed telegram:');
+        console.dir(result, { depth: Infinity });
+      }
+    },
+  });
+
+  // Don't continue the loop until the connection is closed.
+  await new Promise((resolve) => {
+    ws.on('close', (code, reason) => {
+      // Homey Energy Dongle only allows two clients to connect to the web socket at the same time.
+      // If you get the error code 1008, with reason "Connection limit reached" there are already two clients connected.
+      // If you get the error code 1008, with reason "Local API disabled" the local API is disabled and should be activated in the Homey app.
+      console.log('WS disconnected:', code, reason.toString());
+      clearInterval(interval);
+      parser.destroy();
+      resolve();
+    });
+  });
+
+  // Some delay before reconnecting.
+  await new Promise((resolve) => setTimeout(resolve, 5000));
+}

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@athombv/dsmr-parser",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "DSMR Parser for Smart Meters",
   "type": "module",
   "main": "dist/index.js",
@@ -18,7 +18,9 @@
     "prettier": "prettier . --write",
     "prettier:check": "prettier . --check",
     "tool:parse-telegram": "tsx ./tools/parse-telegram.ts",
-    "tool:update-test-telegrams": "tsx ./tools/update-test-telegrams.ts"
+    "tool:update-test-telegrams": "tsx ./tools/update-test-telegrams.ts",
+    "tool:decrypt-telegram": "tsx ./tools/decrypt-telegram.ts",
+    "tool:encrypt-telegram": "tsx ./tools/encrypt-telegram.ts"
   },
   "repository": {
     "type": "git",
@@ -42,6 +44,7 @@
     "serialport": "^12.0.0",
     "tsx": "^4.16.2",
     "typescript": "^5.5.3",
-    "typescript-eslint": "^8.0.0"
+    "typescript-eslint": "^8.0.0",
+    "ws": "^8.18.1"
   }
 }