@bldgblocks/node-red-contrib-quietcool 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BldgBlocks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,135 @@
+# node-red-contrib-quietcool
+
+Node-RED nodes for controlling QuietCool whole house fans over BLE.
+
+## Requirements
+
+- Raspberry Pi (or Linux with BLE)
+- Python 3.9+
+- BlueZ (pre-installed on Raspberry Pi OS)
+- A QuietCool fan with BLE (AFG SMT ES-3.0 or similar)
+
+## Installation
+
+```bash
+cd ~/.node-red
+npm install /path/to/quietcool-ble/node-red-contrib-quietcool
+```
+
+The `postinstall` script automatically creates a Python virtual environment and installs the `bleak` BLE library.
+
+Restart Node-RED after installation:
+
+```bash
+node-red-restart
+```
+
+## Setup
+
+### Quick Setup (recommended)
+
+No phone app or HCI snoop needed — pair directly from Node-RED:
+
+1. Drag a **fan control** or **fan sensor** node onto the canvas
+2. Double-click and create a new fan configuration
+3. Click **Scan** to find your fan — select it from the dropdown
+4. Click **New** to generate a Phone ID
+5. On the fan controller, hold the **Pair** button for ~5 seconds until the LED blinks
+6. Click **Pair with Fan** in the editor
+7. Save and deploy — you're done!
+
+### Alternative: Extract Phone ID from existing app pairing
+
+If you've already paired with the QuietCool mobile app, you can extract the Phone ID:
+
+1. Enable *Bluetooth HCI snoop log* in Android Developer Options
+2. Open the QuietCool app and connect to the fan
+3. Pull the log: `adb bugreport bugreport.zip`
+4. Extract and parse `btsnoop_hci.log` to find the `PhoneID` in a `Login` command
+
+### Manual fan discovery
+
+If the Scan button doesn't work, find the address manually:
+
+```bash
+bluetoothctl scan on
+```
+
+Look for a device named `ATTICFAN_*`. Note the MAC address (e.g., `XX:XX:XX:XX:XX:XX`).
+
+## Nodes
+
+### fan control (`quietcool-control`)
+
+Send commands to the fan. Available actions:
+
+| Action | Description |
+|--------|-------------|
+| Turn Off | Sets fan to Idle mode |
+| Smart Mode (TH) | Temperature/humidity auto mode |
+| Run High | Continuous run at high speed |
+| Run Low | Continuous run at low speed |
+| Timer | Run for a set duration |
+| Apply Preset | Apply a named profile (Summer, Winter, etc.) |
+| Set Thresholds | Set custom temp/humidity thresholds |
+| Pair | Pair with fan (must be in pairing mode) |
+| Raw | Send any raw API command |
+
+Actions can be overridden via `msg.payload`:
+
+```json
+{
+  "action": "preset",
+  "args": { "name": "Summer" }
+}
+```
+
+```json
+{
+  "action": "timer",
+  "args": { "hours": 2, "minutes": 0, "speed": "HIGH" }
+}
+```
+
+### fan sensor (`quietcool-sensor`)
+
+Read data from the fan. Available queries:
+
+| Query | Returns |
+|-------|---------|
+| State | Mode, speed, temperature (°F), humidity (%) |
+| Full Status | Complete status with fan info, firmware, presets |
+| Fan Info | Name, model, serial number |
+| Firmware | Firmware and hardware version |
+| Parameters | Current temp/humidity thresholds |
+| Presets | List of preset profiles |
+| Timer Remaining | Time left on active timer |
+
+For State and Full Status queries, convenience fields are added:
+- `msg.temperature` — Temperature in °F
+- `msg.humidity` — Humidity %
+- `msg.mode` — Current mode (Idle, Timer, TH)
+- `msg.range` — Current speed (LOW, HIGH, CLOSE)
+
+Optional **polling**: set a poll interval (seconds) to auto-query without input triggers.
+
+## Architecture
+
+The Node-RED nodes communicate with the fan through a Python bridge process:
+
+```
+Node-RED → stdin JSON → bridge.py → BLE/bleak → QuietCool Fan
+Node-RED ← stdout JSON ← bridge.py ← BLE/bleak ← QuietCool Fan
+```
+
+The bridge maintains a persistent BLE connection, avoiding the ~3 second reconnect overhead for each command. It spawns automatically when nodes are deployed and shuts down when they're removed.
+
+## Protocol
+
+QuietCool fans use plain JSON over BLE GATT. All communication goes through a single characteristic (`0000ff01`) on service `000000ff`. The protocol requires a `Login` with a `PhoneID` before any commands are accepted.
+
+Tested with firmware `IT-BLT-ATTICFAN_V2.6`.
+
+## License
+
+MIT

package/nodes/quietcool-config.html

@@ -0,0 +1,144 @@
+<script type="text/html" data-template-name="quietcool-config">
+    <div class="form-row">
+        <label for="node-config-input-name"><i class="fa fa-tag"></i> Name</label>
+        <input type="text" id="node-config-input-name" placeholder="My Fan">
+    </div>
+    <div class="form-row">
+        <label for="node-config-input-address"><i class="fa fa-bluetooth"></i> BLE Address</label>
+        <div style="display:flex; gap:4px;">
+            <input type="text" id="node-config-input-address" placeholder="XX:XX:XX:XX:XX:XX" style="flex:1;">
+            <button type="button" id="quietcool-scan-btn" class="red-ui-button" title="Scan for fans"><i class="fa fa-search"></i> Scan</button>
+        </div>
+    </div>
+    <div id="quietcool-scan-results" style="display:none; margin-bottom:10px;">
+        <label>&nbsp;</label>
+        <select id="quietcool-fan-select" style="width:70%;"></select>
+    </div>
+    <div class="form-row">
+        <label for="node-config-input-phoneId"><i class="fa fa-key"></i> Phone ID</label>
+        <div style="display:flex; gap:4px;">
+            <input type="text" id="node-config-input-phoneId" placeholder="16-char hex string">
+            <button type="button" id="quietcool-genid-btn" class="red-ui-button" title="Generate random ID"><i class="fa fa-random"></i> New</button>
+        </div>
+    </div>
+    <div class="form-row">
+        <label>&nbsp;</label>
+        <button type="button" id="quietcool-pair-btn" class="red-ui-button" style="width:auto;">
+            <i class="fa fa-link"></i> Pair with Fan
+        </button>
+        <span id="quietcool-pair-status" style="margin-left:8px;"></span>
+    </div>
+    <div class="form-row">
+        <label>&nbsp;</label>
+        <input type="checkbox" id="node-config-input-autoConnect" style="width:auto; vertical-align:top;">
+        <label for="node-config-input-autoConnect" style="width:auto;"> Auto-connect on deploy</label>
+    </div>
+    <div class="form-tips">
+        <p><b>Quick Setup:</b></p>
+        <ol>
+            <li>Click <b>Scan</b> to find your fan and select it</li>
+            <li>Click <b>New</b> to generate a Phone ID</li>
+            <li>Put the fan in pairing mode: hold the <b>Pair</b> button on the controller for ~5 seconds until the LED blinks</li>
+            <li>Click <b>Pair with Fan</b></li>
+            <li>Save the config — you're done!</li>
+        </ol>
+        <p><b>Already paired from the app?</b> You can extract the Phone ID from
+        a Bluetooth HCI snoop log instead. See the README for details.</p>
+    </div>
+</script>
+
+<script type="text/html" data-help-name="quietcool-config">
+    <p>Configuration for a QuietCool whole house fan BLE connection.</p>
+    <p>Each fan needs its own config node with the BLE MAC address and Phone ID.</p>
+    <p>The config node manages a Python bridge process that maintains the BLE
+    connection to the fan. It starts automatically when nodes using this config
+    are deployed, and stops when they are removed.</p>
+</script>
+
+<script type="text/javascript">
+    RED.nodes.registerType("quietcool-config", {
+        category: "config",
+        defaults: {
+            name: { value: "" },
+            address: { value: "", required: true },
+            phoneId: { value: "", required: true },
+            autoConnect: { value: true },
+        },
+        label: function () {
+            return this.name || this.address || "QuietCool Fan";
+        },
+        oneditprepare: function () {
+            // Scan button
+            $("#quietcool-scan-btn").on("click", function () {
+                var btn = $(this);
+                btn.prop("disabled", true).find("i").removeClass("fa-search").addClass("fa-spinner fa-spin");
+                $.getJSON("quietcool/scan", function (data) {
+                    btn.prop("disabled", false).find("i").removeClass("fa-spinner fa-spin").addClass("fa-search");
+                    if (data.fans && data.fans.length > 0) {
+                        var select = $("#quietcool-fan-select").empty();
+                        data.fans.forEach(function (f) {
+                            select.append($("<option>").val(f.address).text(f.name + " (" + f.address + ") RSSI: " + f.rssi));
+                        });
+                        $("#quietcool-scan-results").show();
+                        select.off("change").on("change", function () {
+                            $("#node-config-input-address").val($(this).val());
+                        });
+                        $("#node-config-input-address").val(data.fans[0].address);
+                    } else {
+                        RED.notify("No QuietCool fans found. Make sure Bluetooth is on and the fan is powered.", "warning");
+                    }
+                }).fail(function () {
+                    btn.prop("disabled", false).find("i").removeClass("fa-spinner fa-spin").addClass("fa-search");
+                    RED.notify("Scan failed. Check that Bluetooth is enabled.", "error");
+                });
+            });
+
+            // Generate ID button
+            $("#quietcool-genid-btn").on("click", function () {
+                $.getJSON("quietcool/generate-id", function (data) {
+                    if (data.phone_id) {
+                        $("#node-config-input-phoneId").val(data.phone_id);
+                    }
+                });
+            });
+
+            // Pair button
+            $("#quietcool-pair-btn").on("click", function () {
+                var address = $("#node-config-input-address").val();
+                var phoneId = $("#node-config-input-phoneId").val();
+                if (!address || !phoneId) {
+                    RED.notify("Fill in BLE Address and Phone ID first.", "warning");
+                    return;
+                }
+                var btn = $(this);
+                var status = $("#quietcool-pair-status");
+                btn.prop("disabled", true);
+                status.text("Connecting...").css("color", "#666");
+
+                $.ajax({
+                    url: "quietcool/pair",
+                    type: "POST",
+                    contentType: "application/json",
+                    data: JSON.stringify({ address: address, phoneId: phoneId }),
+                    success: function (data) {
+                        btn.prop("disabled", false);
+                        if (data.paired) {
+                            status.text("\u2713 " + (data.message || "Paired!")).css("color", "green");
+                            if (data.phone_id) {
+                                $("#node-config-input-phoneId").val(data.phone_id);
+                            }
+                        } else {
+                            status.text("\u2717 " + (data.message || data.error || "Failed")).css("color", "red");
+                        }
+                    },
+                    error: function (xhr) {
+                        btn.prop("disabled", false);
+                        var msg = "Pair failed";
+                        try { msg = JSON.parse(xhr.responseText).error || msg; } catch (e) {}
+                        status.text("\u2717 " + msg).css("color", "red");
+                    },
+                });
+            });
+        },
+    });
+</script>

package/nodes/quietcool-config.js

@@ -0,0 +1,300 @@
+/**
+ * QuietCool BLE config node — manages the Python bridge process lifecycle.
+ */
+
+const { spawn } = require("child_process");
+const path = require("path");
+const readline = require("readline");
+
+// Path to Python bridge (module scope — used by both config node and HTTP admin endpoints)
+const pythonDir = path.join(__dirname, "..", "python");
+const venvPython = path.join(pythonDir, ".venv", "bin", "python3");
+const bridgeScript = path.join(pythonDir, "bridge.py");
+
+module.exports = function (RED) {
+    function QuietCoolConfigNode(config) {
+        RED.nodes.createNode(this, config);
+        const node = this;
+
+        node.address = config.address;
+        node.phoneId = config.phoneId;
+        node.autoConnect = config.autoConnect !== false;
+        node.bridge = null;
+        node.bridgeReady = false;
+        node.connected = false;
+        node.pendingCallbacks = {};
+        node.msgCounter = 0;
+        node.users = new Set();
+
+        node.startBridge = function () {
+            if (node.bridge) return;
+
+            node.log(`Starting BLE bridge for ${node.address}`);
+
+            node.bridge = spawn(venvPython, [bridgeScript], {
+                cwd: pythonDir,
+                stdio: ["pipe", "pipe", "pipe"],
+                env: {
+                    ...process.env,
+                    QUIETCOOL_LOG_LEVEL: "WARNING",
+                },
+            });
+
+            // Read JSON responses from stdout
+            const rl = readline.createInterface({ input: node.bridge.stdout });
+            rl.on("line", (line) => {
+                try {
+                    const msg = JSON.parse(line);
+
+                    if (msg.type === "status") {
+                        node.connected = msg.connected;
+                        node.bridgeReady = true;
+                        node.updateStatus();
+
+                        if (
+                            msg.detail === "bridge_ready" &&
+                            node.autoConnect &&
+                            node.address &&
+                            node.phoneId
+                        ) {
+                            node.sendBridgeCommand("connect", {
+                                address: node.address,
+                                phone_id: node.phoneId,
+                            });
+                        }
+                        return;
+                    }
+
+                    // Route response to waiting callback
+                    const cb = node.pendingCallbacks[msg.id];
+                    if (cb) {
+                        delete node.pendingCallbacks[msg.id];
+                        cb(msg);
+                    }
+                } catch (e) {
+                    node.warn(`Bridge parse error: ${e.message} - ${line}`);
+                }
+            });
+
+            // Log bridge stderr
+            const stderrRl = readline.createInterface({
+                input: node.bridge.stderr,
+            });
+            stderrRl.on("line", (line) => {
+                node.trace(`Bridge: ${line}`);
+            });
+
+            node.bridge.on("exit", (code, signal) => {
+                node.warn(`Bridge exited: code=${code} signal=${signal}`);
+                node.bridge = null;
+                node.bridgeReady = false;
+                node.connected = false;
+                node.updateStatus();
+
+                // Reject all pending callbacks
+                for (const id of Object.keys(node.pendingCallbacks)) {
+                    node.pendingCallbacks[id]({
+                        ok: false,
+                        error: "Bridge process exited",
+                    });
+                }
+                node.pendingCallbacks = {};
+
+                // Auto-restart after 5s if we still have users
+                if (node.users.size > 0) {
+                    setTimeout(() => node.startBridge(), 5000);
+                }
+            });
+
+            node.bridge.on("error", (err) => {
+                node.error(`Bridge spawn error: ${err.message}`);
+            });
+        };
+
+        node.stopBridge = function () {
+            if (node.bridge) {
+                node.log("Stopping BLE bridge");
+                node.bridge.kill("SIGTERM");
+                node.bridge = null;
+                node.bridgeReady = false;
+                node.connected = false;
+            }
+        };
+
+        node.sendBridgeCommand = function (cmd, args, callback) {
+            if (!node.bridge || !node.bridgeReady) {
+                if (callback) {
+                    callback({ ok: false, error: "Bridge not ready" });
+                }
+                return;
+            }
+
+            const id = `msg_${++node.msgCounter}`;
+            const msg = JSON.stringify({ id, cmd, args: args || {} }) + "\n";
+
+            if (callback) {
+                node.pendingCallbacks[id] = callback;
+                // Timeout after 15s
+                setTimeout(() => {
+                    if (node.pendingCallbacks[id]) {
+                        delete node.pendingCallbacks[id];
+                        callback({ ok: false, error: "Command timeout" });
+                    }
+                }, 15000);
+            }
+
+            node.bridge.stdin.write(msg);
+        };
+
+        node.registerUser = function (userNode) {
+            node.users.add(userNode.id);
+            if (!node.bridge) {
+                node.startBridge();
+            }
+        };
+
+        node.deregisterUser = function (userNode) {
+            node.users.delete(userNode.id);
+            if (node.users.size === 0) {
+                node.stopBridge();
+            }
+        };
+
+        node.updateStatus = function () {
+            for (const userId of node.users) {
+                const userNode = RED.nodes.getNode(userId);
+                if (userNode && userNode.updateNodeStatus) {
+                    userNode.updateNodeStatus(node.connected);
+                }
+            }
+        };
+
+        node.on("close", function (done) {
+            node.stopBridge();
+            done();
+        });
+    }
+
+    RED.nodes.registerType("quietcool-config", QuietCoolConfigNode);
+
+    // ================================================================
+    // HTTP Admin Endpoints for editor UI (scan, pair, generate ID)
+    // ================================================================
+
+    // Scan for QuietCool fans
+    RED.httpAdmin.get(
+        "/quietcool/scan",
+        RED.auth.needsPermission("quietcool-config.write"),
+        function (req, res) {
+            const proc = spawn(venvPython, [bridgeScript], {
+                cwd: pythonDir,
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+
+            let responded = false;
+            const rl = readline.createInterface({ input: proc.stdout });
+
+            rl.on("line", (line) => {
+                try {
+                    const msg = JSON.parse(line);
+                    if (msg.type === "status" && msg.detail === "bridge_ready") {
+                        proc.stdin.write(
+                            JSON.stringify({ id: "scan", cmd: "scan", args: { timeout: 8 } }) + "\n"
+                        );
+                    } else if (msg.id === "scan" && !responded) {
+                        responded = true;
+                        res.json(msg.ok ? msg.data : { error: msg.error });
+                        proc.kill("SIGTERM");
+                    }
+                } catch (e) {
+                    /* ignore parse errors */
+                }
+            });
+
+            proc.on("error", (err) => {
+                if (!responded) {
+                    responded = true;
+                    res.status(500).json({ error: err.message });
+                }
+            });
+
+            setTimeout(() => {
+                if (!responded) {
+                    responded = true;
+                    res.status(504).json({ error: "Scan timeout" });
+                    proc.kill("SIGTERM");
+                }
+            }, 15000);
+        }
+    );
+
+    // Generate a new Phone ID
+    RED.httpAdmin.get(
+        "/quietcool/generate-id",
+        RED.auth.needsPermission("quietcool-config.write"),
+        function (req, res) {
+            const crypto = require("crypto");
+            const id = crypto.randomBytes(8).toString("hex");
+            res.json({ phone_id: id });
+        }
+    );
+
+    // Pair with a fan
+    RED.httpAdmin.post(
+        "/quietcool/pair",
+        RED.auth.needsPermission("quietcool-config.write"),
+        function (req, res) {
+            const address = req.body.address;
+            const phoneId = req.body.phoneId;
+
+            if (!address || !phoneId) {
+                res.status(400).json({ error: "address and phoneId required" });
+                return;
+            }
+
+            const proc = spawn(venvPython, [bridgeScript], {
+                cwd: pythonDir,
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+
+            let responded = false;
+            const rl = readline.createInterface({ input: proc.stdout });
+
+            rl.on("line", (line) => {
+                try {
+                    const msg = JSON.parse(line);
+                    if (msg.type === "status" && msg.detail === "bridge_ready") {
+                        proc.stdin.write(
+                            JSON.stringify({
+                                id: "pair",
+                                cmd: "pair",
+                                args: { address, phone_id: phoneId },
+                            }) + "\n"
+                        );
+                    } else if (msg.id === "pair" && !responded) {
+                        responded = true;
+                        res.json(msg.ok ? msg.data : { error: msg.error });
+                        proc.kill("SIGTERM");
+                    }
+                } catch (e) {
+                    /* ignore */
+                }
+            });
+
+            proc.on("error", (err) => {
+                if (!responded) {
+                    responded = true;
+                    res.status(500).json({ error: err.message });
+                }
+            });
+
+            setTimeout(() => {
+                if (!responded) {
+                    responded = true;
+                    res.status(504).json({ error: "Pair timeout" });
+                    proc.kill("SIGTERM");
+                }
+            }, 30000);
+        }
+    );
+};