npm - @mschaeffler/node-red-bthome - Versions diffs - 0.1.1 → 0.1.3 - Mend

@mschaeffler/node-red-bthome 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md CHANGED Viewed

@@ -8,10 +8,10 @@ At the moment these sensors are implemented and tested:
 - Shelly BLU Door/Window
 - Shelly BLU H&T
 - Shelly BLU Button 1
-- Shelly BLU Button Tough 1
+- Shelly BLU Button Tough 1
 - Shelly BLU RC Button 4
 - Shelly BLU Wall Switch 4
-- Shelly BLU Motion
+- Shelly BLU Motion
 ## Capture of Raw Frames
@@ -19,6 +19,10 @@ The raw data frames are captured by Shelly devices with Bluetooth (Gen2 up to Ge
 [This is the script to be used.](https://raw.githubusercontent.com/m-schaeffler/ShellyScripts/refs/heads/main/ShellyBlu.js)
+## Encryption
+is at the moment not supported, an update will follow shortly.
 ## Install
 ```
@@ -29,21 +33,101 @@ $ npm install @mschaeffler/node-red-bthome
 |msg.    | type   | description                       |
 |:-------|:-------|:----------------------------------|
-|topic   | string | topic for the output message|
-|payload |        | payload for the output message |
+|payload | object | data from Shelly script|
+### msg.payload
+Only the first two values are needed, the others are optional.
+|msg.payload| type   | description                       |
+|:----------|:-------|:----------------------------------|
+|addr       | string |mac of the BT-Home device (needed) |
+|data       | array of bytes|raw BT-Home message (needed) |
+|rssi       | number |signal strength |
+|time       | number |Javscript timestamp of the reception |
+|gateway    | string |name of the geteway |
+This is an example of such a message payload:
+```
+{
+    "addr":    "11:22:33:44:55:66",
+    "rssi":    -85,
+    "time":    1745395033113,
+    "gateway": "Shelly Gateway",
+    "data":    [68,0,164,1,100,46,56,69,43,255]
+}
+```
+## Outputs
+There are two output ports:
+1. one for meassurement values (states)
+2. one for actions done with the devices (events)
+### State
+|msg.    | type   | description                       |
+|:-------|:-------|:----------------------------------|
+|topic   | string | `State-Prefix` + name of the device|
+|payload | object | decoded state data|
-## Output
+### Events
 |msg.    | type   | description                       |
 |:-------|:-------|:----------------------------------|
-|topic   | string | same is in corresponding input message|
-|payload |        | same is in corresponding input message|
+|topic   | string | `Event-Prefix` + name of the device|
+|payload | object | data of the decoded event|
 ## Parameters
-|config| type   | description                       |
-|:-----|:-------|:----------------------------------|
-|interval | number | the intervall between two resends |
+|config       | type   | description                       |
+|:------------|:-------|:----------------------------------|
+|Devices      | JSON   | configuration of the BT-Home devices |
+|Status-Prefix| string | prefix for the topic for state output |
+|Event-Prefix | string | prefix for the topic for event output |
+|Context-Variable| string | name of the variable in flow context storage |
+|Contextstore | string | context store to be used |
+### Device-Configuration
+With this JSON string the installed [BT-Home](https://bthome.io) devices are configured:
+```
+{
+    "<mac address of the device>": { "topic": "<name of the device>", "key": "<encryption key, if device is encrypted>" }
+}
+```
+An example for such a config from the unit tests:
+```
+{
+    "11:22:33:44:55:66": { "topic": "dev_unencrypted_1" },
+    "00:01:02:03:04:05": { "topic": "dev_unencrypted_2" },
+    "00:10:20:30:40:50": { "topic": "dev_encrypted_1", "key": "00112233445566778899AABBCCDDEEFF" },
+    "00:00:00:00:00:00": { "topic": "dev_encrypted_2", "key": [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16] }
+}
+```
+### Context storage
+All recorded data can be stored in a flow context variable for
+- initialisation
+- statistics
+- visualisation
+Example:
+```
+{
+    "dev_unencrypted_1":
+    {
+        "pid":       164,
+        "time":      1745395033113,
+        "encrypted": false,
+        "battery":   100,
+        "gw":        { "Shelly Gateway": { "time": 1745395033113, "rssi":-85 } },
+        data":       { "humidity":56, "temperature":-21.3 }
+    }
+}
+```
 ## Example Flow

package/bthome.html CHANGED Viewed

@@ -7,20 +7,21 @@
             devices:{value:"[]",required:true},
             statusPrefix:{value:""},
             eventPrefix:{value:""},
+            contextVar:{value:"bthome",required:true},
             contextStore:{value:"",required:true}
         },
         inputs:1,
-        outputs:1,
+        outputs:2,
         icon: "bthome.png",
         label: function() {
-            return this.name||"bthome";
+            return this.name||"BT-Home";
         },
         labelStyle: function() {
             return this.name?"node_label_italic":"";
         },
         paletteLabel: "bthome",
-        inputLabels: 'bthome frame',
-        outputLabels: 'decoded frame',
+        inputLabels: 'raw bthome frame',
+        outputLabels: ['state output','event output'],
         oneditprepare: function() {
             const node = this;
             $("#node-input-devices").typedInput({
@@ -61,6 +62,10 @@
         <label for="node-input-eventPrefix"><i class="fa fa-star-o"></i> Event-Prefix</label>
         <input type="text" id="node-input-eventPrefix"></input>
     </div>
+    <div class="form-row">
+        <label for="node-input-contextVar"><i class="fa fa-database"></i> Context-Variable</label>
+        <input type="text" id="node-input-contextVar"></input>
+    </div>
     <div class="form-row">
         <label for="node-input-contextStore"><i class="fa fa-database"></i> Contextstore</label>
         <select type="text" id="node-input-contextStore"></select>
@@ -69,30 +74,126 @@
 <script type="text/x-red" data-help-name="bthome">
-    <p>A Node Red node to decrypt and decode bthome frames.</p>
+    <p>A Node Red node to decrypt and decode raw data frames from <a href="https://bthome.io">BT-Home</a> sensors.</p>
-    <p>.</p>
+    <p>At the moment these sensors are implemented and tested:</p>
+    <ul>
+    <li>Shelly BLU Door/Window</li>
+    <li>Shelly BLU H&T</li>
+    <li>Shelly BLU Button 1</li>
+    <li>Shelly BLU Button Tough 1</li>
+    <li>Shelly BLU RC Button 4</li>
+    <li>Shelly BLU Wall Switch 4</li>
+    <li>Shelly BLU Motion</li>
+    </ul>
+    <h3>Capture of Raw Frames</h3>
+    <p>The raw data frames are captured by Shelly devices with Bluetooth (Gen2 up to Gen4) and then sent via MQTT to Node-Red.</p>
+    <a href="https://raw.githubusercontent.com/m-schaeffler/ShellyScripts/refs/heads/main/ShellyBlu.js">This is the script to be used.</a>
+    <h3>Encryption</h3>
+    <p>is at the moment not supported, an update will follow shortly.</p>
     <h3>Input</h3>
+    <dl class="message-properties">
+        <dt>payload <span class="property-type">object</span></dt>
+        <dd> data from Shelly script</dd>
+    </dl>
+    <h4>msg.payload</h4>
+    <p>Only the first two values are needed, the others are optional.</p>
+    <dl class="message-properties">
+        <dt>payload.addr <span class="property-type">string</span></dt>
+        <dd> mac of the BT-Home device (needed)</dd>
+        <dt>payload.data <span class="property-type">array of bytes</span></dt>
+        <dd> raw BT-Home message (needed)</dd>
+        <dt>payload.rssi <span class="property-type">number</span></dt>
+        <dd> signal strength</dd>
+        <dt>payload.time <span class="property-type">number</span></dt>
+        <dd> Javscript timestamp of the reception</dd>
+        <dt>payload.gateway <span class="property-type">string</span></dt>
+        <dd> name of the geteway</dd>
+    </dl>
+    <p>This is an example of such a message payload:</p>
+    <code>{<br>
+    "addr":    "11:22:33:44:55:66",<br>
+    "rssi":    -85,<br>
+    "time":    1745395033113,<br>
+    "gateway": "Shelly Gateway",<br>
+    "data":    [68,0,164,1,100,46,56,69,43,255]<br>
+}</code>
+    <h3>Outputs</h3>
+    <p>There are two output ports:</p>
+    <ol>
+      <li>one for meassurement values (states)</li>
+      <li>one for actions done with the devices (events)</li>
+    </ol>
+    <h4>State</h4>
     <dl class="message-properties">
         <dt>topic <span class="property-type">string</span></dt>
-        <dd> topic for the output message</dd>
+        <dd> <code>State-Prefix</code> + name of the device</dd>
         <dt>payload <span class="property-type"></span></dt>
-        <dd> payload for the output message</dd>
+        <dd> decoded state data</dd>
     </dl>
-    <h3>Outputs</h3>
+    </h4>Events</h4>
     <dl class="message-properties">
         <dt>topic <span class="property-type">string</span></dt>
-        <dd> same is in corresponding input message</dd>
+        <dd> <code>Event-Prefix</code> + name of the device</dd>
         <dt>payload <span class="property-type"></span></dt>
-        <dd> same is in corresponding input message</dd>
+        <dd> data of the decoded event</dd>
     </dl>
     <h3>Parameters</h3>
     <dl class="message-properties">
-        <dt>devices <span class="property-type">JSON</span></dt>
-        <dd> data of the connected BT-Home devices.</dd>
+        <dt>Devices <span class="property-type">JSON</span></dt>
+        <dd> configuration of the BT-Home devices.</dd>
+        <dt>Status-Prefix <span class="property-type">string</span></dt>
+        <dd> prefix for the topic for state output.</dd>
+        <dt>Event-Prefix <span class="property-type">string</span></dt>
+        <dd> prefix for the topic for event output.</dd>
+        <dt>Context-Variable <span class="property-type">string</span></dt>
+        <dd> name of the variable in flow context storage.</dd>
+        <dt>Contextstore <span class="property-type">string</span></dt>
+        <dd>  context store to be used.</dd>
     </dl>
+    <h4>Device-Configuration</h4>
+    <p>With this JSON string the installed <a href="https://bthome.io">BT-Home</a> devices are configured:</p>
+    <code>{<br>
+    "<mac address of the device>": { "topic": "<name of the device>", "key": "<encryption key, if device is encrypted>" }<br>
+}</code>
+    <p>An example for such a config from the unit tests:</p>
+    <code>{<br>
+    "11:22:33:44:55:66": { "topic": "dev_unencrypted_1" },<br>
+    "00:01:02:03:04:05": { "topic": "dev_unencrypted_2" },<br>
+    "00:10:20:30:40:50": { "topic": "dev_encrypted_1", "key": "00112233445566778899AABBCCDDEEFF" },<br>
+    "00:00:00:00:00:00": { "topic": "dev_encrypted_2", "key": [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16] }<br>
+}</code>
+    <h4>Context storage</h4>
+    <p>All recorded data can be stored in a flow context variable for</p>
+    <ul>
+      <li>initialisation</li>
+      <li>statistics</li>
+      <li>visualisation</li>
+    </ul>
+    <p>Example:</p>
+    <code>{<br>
+    "dev_unencrypted_1":<br>
+    {<br>
+        "pid":       164,<br>
+        "time":      1745395033113,<br>
+        "encrypted": false,<br>
+        "battery":   100,<br>
+        "gw":        { "Shelly Gateway": { "time": 1745395033113, "rssi":-85 } },<br>
+        data":       { "humidity":56, "temperature":-21.3 }<br>
+    }
+}<code>
 </script>

package/bthome.js CHANGED Viewed

@@ -216,7 +216,7 @@ module.exports = function(RED) {
             {
                 if( encrypted )
                 {
-                    decyrptMsg();
+                    decryptMsg();
                     done();return;
                 }
                 if( item == undefined )

package/examples/bthome.json CHANGED Viewed

@@ -0,0 +1,137 @@
+[
+    {
+        "id": "3a9fcdbd98993dbc",
+        "type": "mqtt in",
+        "z": "8e0e9a167c607864",
+        "name": "",
+        "topic": "node-red/bleraw",
+        "qos": "0",
+        "datatype": "json",
+        "broker": "66b8b47e.0f87bc",
+        "nl": false,
+        "rap": true,
+        "rh": 0,
+        "inputs": 0,
+        "x": 140,
+        "y": 1460,
+        "wires": [
+            [
+                "c4df490573c18fc4"
+            ]
+        ]
+    },
+    {
+        "id": "c4df490573c18fc4",
+        "type": "bthome",
+        "z": "8e0e9a167c607864",
+        "name": "",
+        "devices": "{\"11:22:33:44:55:66\":{\"topic\":\"dev_unencrypted_1\"},\"00:01:02:03:04:05\":{\"topic\":\"dev_unencrypted_2\"},\"00:10:20:30:40:50\":{\"topic\":\"dev_encrypted_1\",\"key\":\"00112233445566778899AABBCCDDEEFF\"},\"00:00:00:00:00:00\":{\"topic\":\"dev_encrypted_2\",\"key\":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16]}}",
+        "statusPrefix": "Status",
+        "eventPrefix": "Event",
+        "contextVar": "bt-home",
+        "contextStore": "memoryOnly",
+        "x": 340,
+        "y": 1440,
+        "wires": [
+            [
+                "3c9fee837ed43fc0"
+            ],
+            [
+                "26ebe1833f97c4d4"
+            ]
+        ]
+    },
+    {
+        "id": "3c9fee837ed43fc0",
+        "type": "debug",
+        "z": "8e0e9a167c607864",
+        "name": "debug 9",
+        "active": true,
+        "tosidebar": true,
+        "console": false,
+        "tostatus": false,
+        "complete": "false",
+        "statusVal": "",
+        "statusType": "auto",
+        "x": 520,
+        "y": 1420,
+        "wires": []
+    },
+    {
+        "id": "26ebe1833f97c4d4",
+        "type": "debug",
+        "z": "8e0e9a167c607864",
+        "name": "debug 10",
+        "active": true,
+        "tosidebar": true,
+        "console": false,
+        "tostatus": false,
+        "complete": "false",
+        "statusVal": "",
+        "statusType": "auto",
+        "x": 520,
+        "y": 1460,
+        "wires": []
+    },
+    {
+        "id": "e3ad83be53fa3fe3",
+        "type": "inject",
+        "z": "8e0e9a167c607864",
+        "name": "",
+        "props": [
+            {
+                "p": "payload"
+            },
+            {
+                "p": "topic",
+                "vt": "str"
+            }
+        ],
+        "repeat": "",
+        "crontab": "",
+        "once": false,
+        "onceDelay": 0.1,
+        "topic": "",
+        "payload": "{\"addr\":\"11:22:33:44:55:66\",\"rssi\":-85,\"time\":1745395033113,\"gateway\":\"Shelly Gateway\",\"data\":[68,0,164,1,100,46,56,69,43,255]}",
+        "payloadType": "json",
+        "x": 170,
+        "y": 1420,
+        "wires": [
+            [
+                "c4df490573c18fc4"
+            ]
+        ]
+    },
+    {
+        "id": "66b8b47e.0f87bc",
+        "type": "mqtt-broker",
+        "name": "mqtt.lan",
+        "broker": "mqtt.lan",
+        "port": "1883",
+        "clientid": "node-red",
+        "autoConnect": false,
+        "usetls": false,
+        "compatmode": false,
+        "protocolVersion": "4",
+        "keepalive": "60",
+        "cleansession": true,
+        "autoUnsubscribe": true,
+        "birthTopic": "node-red/online",
+        "birthQos": "1",
+        "birthRetain": "true",
+        "birthPayload": "true",
+        "birthMsg": {},
+        "closeTopic": "node-red/online",
+        "closeQos": "1",
+        "closeRetain": "true",
+        "closePayload": "false",
+        "closeMsg": {},
+        "willTopic": "node-red/online",
+        "willQos": "1",
+        "willRetain": "true",
+        "willPayload": "false",
+        "willMsg": {},
+        "userProps": "",
+        "sessionExpiry": ""
+    }
+]

package/examples/bthome.png CHANGED Viewed

Binary file

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
     "name": "@mschaeffler/node-red-bthome",
-    "version": "0.1.1",
+    "version": "0.1.3",
     "description": "A Node Red node to decrypt and decode BT-Home frames",
     "author": {
         "name": "Mathias Schäffler",