@mschaeffler/node-red-bthome 0.1.2 → 0.1.3

package/README.md

@@ -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
 
 ```
@@ -64,14 +68,14 @@ There are two output ports:
 
 |msg.    | type   | description                       |
 |:-------|:-------|:----------------------------------|
-|topic   | string | State-Prefix + name of the device|
+|topic   | string | `State-Prefix` + name of the device|
 |payload | object | decoded state data|
 
 ### Events
 
 |msg.    | type   | description                       |
 |:-------|:-------|:----------------------------------|
-|topic   | string | Event-Prefix + name of the device|
+|topic   | string | `Event-Prefix` + name of the device|
 |payload | object | data of the decoded event|
 
 ## Parameters
@@ -105,6 +109,26 @@ An example for such a config from the unit tests:
 
 ### 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
 
 [example flow](https://github.com/m-schaeffler/node-red-my-nodes/raw/main/node-red-bthome/examples/bthome.json)

package/bthome.html

@@ -74,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/package.json

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