node-red-contrib-surface-dial 1.0.0

package/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

package/README.md

@@ -0,0 +1,2 @@
+# node-surface-dial
+A NodeRED module for the Microsoft Surface Dial

package/example-flows/OnkyoVolumeControl.json

@@ -0,0 +1,198 @@
+[
+    {
+        "id": "525341509fb3d38a",
+        "type": "tab",
+        "label": "Flow 1",
+        "disabled": false,
+        "info": "",
+        "env": []
+    },
+    {
+        "id": "346aa6a9bcdd187a",
+        "type": "change",
+        "z": "525341509fb3d38a",
+        "name": "Toggle Mute",
+        "rules": [
+            {
+                "t": "set",
+                "p": "payload",
+                "pt": "msg",
+                "to": "AMTTG",
+                "tot": "str"
+            }
+        ],
+        "action": "",
+        "property": "",
+        "from": "",
+        "to": "",
+        "reg": false,
+        "x": 570,
+        "y": 300,
+        "wires": [
+            [
+                "fdc88824dc09574d"
+            ]
+        ]
+    },
+    {
+        "id": "3d6fc401573ee75d",
+        "type": "change",
+        "z": "525341509fb3d38a",
+        "name": "Volume Up",
+        "rules": [
+            {
+                "t": "set",
+                "p": "payload",
+                "pt": "msg",
+                "to": "MVLUP",
+                "tot": "str"
+            }
+        ],
+        "action": "",
+        "property": "",
+        "from": "",
+        "to": "",
+        "reg": false,
+        "x": 570,
+        "y": 180,
+        "wires": [
+            [
+                "fdc88824dc09574d"
+            ]
+        ]
+    },
+    {
+        "id": "1a7aa7895b7cf865",
+        "type": "change",
+        "z": "525341509fb3d38a",
+        "name": "Volume Down",
+        "rules": [
+            {
+                "t": "set",
+                "p": "payload",
+                "pt": "msg",
+                "to": "MVLDOWN",
+                "tot": "str"
+            }
+        ],
+        "action": "",
+        "property": "",
+        "from": "",
+        "to": "",
+        "reg": false,
+        "x": 580,
+        "y": 240,
+        "wires": [
+            [
+                "fdc88824dc09574d"
+            ]
+        ]
+    },
+    {
+        "id": "fdc88824dc09574d",
+        "type": "function",
+        "z": "525341509fb3d38a",
+        "name": "Onkyo EISCP",
+        "func": "function buildEiscpPacket(command) {\n    // Payload: !1<COMMAND>\\r\n    const payload = Buffer.from(`!1${command}\\r`, \"ascii\");\n\n    const header = Buffer.alloc(16);\n\n    // \"ISCP\"\n    header.write(\"ISCP\", 0, 4, \"ascii\");\n\n    // Header size = 16\n    header.writeUInt32BE(16, 4);\n\n    // Data size = payload length\n    header.writeUInt32BE(payload.length, 8);\n\n    // Version = 1\n    header[12] = 0x01;\n    // bytes 13–15 stay 0\n\n    return Buffer.concat([header, payload]);\n}\n\n\nmsg.payload = buildEiscpPacket(msg.payload)\nreturn msg",
+        "outputs": 1,
+        "timeout": 0,
+        "noerr": 0,
+        "initialize": "",
+        "finalize": "",
+        "libs": [],
+        "x": 820,
+        "y": 240,
+        "wires": [
+            [
+                "2738e6759d4a0f23"
+            ]
+        ]
+    },
+    {
+        "id": "2738e6759d4a0f23",
+        "type": "tcp request",
+        "z": "525341509fb3d38a",
+        "name": "",
+        "server": "192.168.60.187",
+        "port": "60128",
+        "out": "sit",
+        "ret": "buffer",
+        "splitc": " ",
+        "newline": "",
+        "trim": false,
+        "tls": "",
+        "x": 1060,
+        "y": 240,
+        "wires": [
+            []
+        ]
+    },
+    {
+        "id": "d32a4762b7f63361",
+        "type": "surface-dial",
+        "z": "525341509fb3d38a",
+        "name": "",
+        "x": 170,
+        "y": 240,
+        "wires": [
+            [
+                "b2c18fde179a4291"
+            ]
+        ]
+    },
+    {
+        "id": "b2c18fde179a4291",
+        "type": "switch",
+        "z": "525341509fb3d38a",
+        "name": "Event Type",
+        "property": "payload",
+        "propertyType": "msg",
+        "rules": [
+            {
+                "t": "eq",
+                "v": "clockwise",
+                "vt": "str"
+            },
+            {
+                "t": "eq",
+                "v": "counter-clockwise",
+                "vt": "str"
+            },
+            {
+                "t": "eq",
+                "v": "pressed",
+                "vt": "str"
+            },
+            {
+                "t": "eq",
+                "v": "released",
+                "vt": "str"
+            }
+        ],
+        "checkall": "true",
+        "repair": false,
+        "outputs": 4,
+        "x": 350,
+        "y": 240,
+        "wires": [
+            [
+                "3d6fc401573ee75d"
+            ],
+            [
+                "1a7aa7895b7cf865"
+            ],
+            [
+                "346aa6a9bcdd187a"
+            ],
+            []
+        ]
+    },
+    {
+        "id": "5702f84b15c52c98",
+        "type": "global-config",
+        "env": [],
+        "modules": {
+            "node-red-contrib-surface-dial": "1.0.0"
+        }
+    }
+]

package/nodes/surface-dial.html

@@ -0,0 +1,41 @@
+<script type="text/javascript">
+    RED.nodes.registerType('surface-dial', {
+        category: 'input',
+        color: '#0078D4',
+        defaults: {
+            name: { value: "" }
+        },
+        inputs: 0,
+        outputs: 1,
+        icon: "font-awesome/fa-circle-o-notch",
+        label: function() {
+            return this.name || "surface-dial";
+        },
+        paletteLabel: "surface-dial"
+    });
+</script>
+
+<script type="text/html" data-template-name="surface-dial">
+    <div class="form-row">
+        <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+        <input type="text" id="node-input-name" placeholder="Name">
+    </div>
+</script>
+
+<script type="text/html" data-help-name="surface-dial">
+    <p>Discovers a local Microsoft Surface Dial, connects to it, and emits button and rotation events.</p>
+
+    <h3>Outputs</h3>
+    <dl class="message-properties">
+        <dt>topic <span class="property-type">string</span></dt>
+        <dd><code>"button"</code> or <code>"rotation"</code></dd>
+        <dt>payload <span class="property-type">string</span></dt>
+        <dd>
+            <code>"pressed"</code> / <code>"released"</code> for button events<br>
+            <code>"clockwise"</code> / <code>"counter-clockwise"</code> for rotation events
+        </dd>
+    </dl>
+
+    <h3>Details</h3>
+    <p>Auto-connects to the Surface Dial on deploy and reconnects if disconnected.</p>
+</script>

package/nodes/surface-dial.js

@@ -0,0 +1,180 @@
+module.exports = function(RED) {
+    const HID = require('node-hid');
+
+    // Surface Dial constants
+    const VENDOR_ID = 0x045E;  // Microsoft
+    const PRODUCT_ID = 0x091B; // Surface Dial
+    const RECONNECT_POLL_INTERVAL = 50; // ms
+
+    function SurfaceDialNode(config) {
+        RED.nodes.createNode(this, config);
+        const node = this;
+
+        let device = null;
+        let pollTimer = null;
+        let prevButtonState = false;
+        let closing = false;
+
+        // Attempt to find and open the Surface Dial
+        // Returns the device handle or null if not found
+        function connectDevice() {
+            try {
+                const devices = HID.devices(VENDOR_ID, PRODUCT_ID);
+                if (devices.length === 0) {
+                    return null;
+                }
+
+                const deviceInfo = devices[0];
+                const dev = new HID.HID(deviceInfo.path);
+
+                node.log(`Found Surface Dial: ${deviceInfo.product || 'Unknown'} at ${deviceInfo.path}`);
+                return dev;
+            } catch (err) {
+                node.log(`Failed to connect: ${err.message}`);
+                return null;
+            }
+        }
+
+        // Parse HID report data
+        function parseReport(data) {
+            if (data.length < 4) {
+                return;
+            }
+
+            // Check Report ID (must be 1)
+            const reportID = data[0];
+            if (reportID !== 1) {
+                return;
+            }
+
+            // Parse button state (byte 1, bit 0)
+            const buttonPressed = (data[1] & 0x01) !== 0;
+
+            // Detect button state transitions
+            if (buttonPressed !== prevButtonState) {
+                const state = buttonPressed ? "pressed" : "released";
+                node.send({
+                    payload: state,
+                    topic: "button"
+                });
+                prevButtonState = buttonPressed;
+            }
+
+            // Parse rotation value (bytes 2-3, little-endian signed int16)
+            let rotation = data[2] | (data[3] << 8);
+            // Convert to signed int16
+            if (rotation > 32767) {
+                rotation -= 65536;
+            }
+
+            if (rotation !== 0) {
+                const direction = rotation > 0 ? "clockwise" : "counter-clockwise";
+                node.send({
+                    payload: direction,
+                    topic: "rotation"
+                });
+            }
+        }
+
+        // Start listening for device events
+        function startEventLoop() {
+            if (!device || closing) {
+                return;
+            }
+
+            device.on('data', (data) => {
+                parseReport(data);
+            });
+
+            device.on('error', (err) => {
+                if (closing) {
+                    return;
+                }
+                node.log(`Device error: ${err.message}`);
+                handleDisconnect();
+            });
+        }
+
+        // Handle device disconnection
+        function handleDisconnect() {
+            if (closing) {
+                return;
+            }
+
+            if (device) {
+                try {
+                    device.close();
+                } catch (e) {
+                    // Ignore close errors
+                }
+                device = null;
+            }
+
+            prevButtonState = false;
+            node.status({ fill: "red", shape: "ring", text: "disconnected" });
+
+            // Start polling for reconnection
+            waitForDevice();
+        }
+
+        // Poll for device until available or node is closed
+        function waitForDevice() {
+            if (closing) {
+                return;
+            }
+
+            // Try immediate connection first
+            device = connectDevice();
+            if (device) {
+                node.status({ fill: "green", shape: "dot", text: "connected" });
+                startEventLoop();
+                return;
+            }
+
+            // Start polling
+            node.status({ fill: "grey", shape: "ring", text: "waiting..." });
+
+            pollTimer = setInterval(() => {
+                if (closing) {
+                    clearInterval(pollTimer);
+                    pollTimer = null;
+                    return;
+                }
+
+                device = connectDevice();
+                if (device) {
+                    clearInterval(pollTimer);
+                    pollTimer = null;
+                    node.status({ fill: "green", shape: "dot", text: "connected" });
+                    startEventLoop();
+                }
+            }, RECONNECT_POLL_INTERVAL);
+        }
+
+        // Start connection loop on deploy
+        waitForDevice();
+
+        // Cleanup on node close
+        node.on('close', (done) => {
+            closing = true;
+
+            if (pollTimer) {
+                clearInterval(pollTimer);
+                pollTimer = null;
+            }
+
+            if (device) {
+                try {
+                    device.close();
+                } catch (e) {
+                    // Ignore close errors
+                }
+                device = null;
+            }
+
+            done();
+        });
+    }
+
+    RED.nodes.registerType("surface-dial", SurfaceDialNode);
+};

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "node-red-contrib-surface-dial",
+  "version": "1.0.0",
+  "description": "Node-RED node for Microsoft Surface Dial",
+  "keywords": [
+    "node-red",
+    "surface-dial",
+    "microsoft",
+    "hid"
+  ],
+  "author": "",
+  "license": "MIT",
+  "node-red": {
+    "version": ">=2.0.0",
+    "nodes": {
+      "surface-dial": "nodes/surface-dial.js"
+    }
+  },
+  "dependencies": {
+    "node-hid": "^3.1.0"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}