node-red-contrib-shelly

# 02 · Structural Design ## Source tree ``` shelly/ ├── 99-shelly.js Node-RED entry; registers all 6 node types + admin routes ├── 99-shelly.html Admin-UI definitions for the editor (forms, dropdowns) ├── config/ │ └── config.json Single source of truth for the device catalog ├── lib/ │ ├── shelly.js Shared HTTP transport, auth, polling lifecycle │ ├── configuration.js Catalog lookups (model → type, gen → device list) │ └── utils.js Small helpers (payload validity, trim, replace) ├── nodes/ │ ├── gen1-node.js } │ ├── gen1-server-node.js } paired: device node + fastify-listener config │ ├── gen2-node.js } │ ├── gen2-server-node.js } │ ├── cloud-node.js } │ └── cloud-server-node.js} ├── scripts/ Device-side JS, runs on Shelly's mJS runtime (not Node) │ ├── callback.js Forwards events from gen2+ device to Node-RED listener │ └── ble-shelly-blu.js BLU scanner for gen2+ gateway devices (vendored, Apache 2.0) └── icons/ Three PNG icons used in the Node-RED palette ``` ``` examples/ 28 importable Node-RED flow JSONs (one per device family) .github/workflows/ CI (lint matrix) + npm-publish (on release) .husky/ Pre-commit lint gate doc/architecture/ This documentation ``` ## Module dependency graph ``` ┌──────────────────┐ │ 99-shelly.js │ (entry, registers all node types) └────────┬─────────┘ │ requires ┌─────────────────┼─────────────────────────┐ ▼ ▼ ▼ ┌──────────────┐ ┌───────────────────┐ ┌────────────────────┐ │ lib/utils │ │ lib/shelly │ │ lib/configuration │ │ (helpers) │ │ (HTTP, auth, │ │ (model→type maps, │ │ │ │ polling loop) │ │ gen catalogs) │ └────────▲─────┘ └────────▲──────────┘ └────────▲───────────┘ │ │ │ │ │ (used by all node types) │ │ │ └────────┬────────┴───────────────────────┘ │ ┌──────────────┼──────────────┬──────────────┐ ▼ ▼ ▼ ▼ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────────────────┐ │ gen1- │ │ gen2- │ │ cloud- │ │ *-server-node.js │ │ node.js │ │ node.js │ │ node.js │ │ (fastify listener │ └─────────┘ └─────────┘ └─────────┘ │ or cloud creds) │ └──────────────────┘ ``` **Key observations:** - `lib/` is the only horizontal layer. Everything else above it is a "leaf" that depends on `lib/` but not on its sibling. - There are **no cycles** in the require graph. - The three protocol paths (gen1 / gen2 / cloud) are siblings. They share `lib/utils` and `lib/configuration`; gen1 and gen2 also share `lib/shelly` (cloud uses its own axios + rate-limiter and skips the shared transport). - Cloud is the most isolated branch — its only `lib/` dependency is `utils`. ## Per-file roles ### Entry and registration [`99-shelly.js`](../../shelly/99-shelly.js) (104 LOC) is the Node-RED entry, declared under `node-red.nodes` in [package.json](../../package.json). It does three things: 1. **Logs the package version** at load time (`pkg.version`). 2. **Mounts four HTTP admin routes** used by the config editor to populate dropdowns: `getidevicetypesgen1`, `getidevicetypesgen2` (which actually concatenates gen 2, 3, 4), `getipaddresses`, `getshellyinfo`. 3. **Registers the six node types** with their credential schemas (gen 1/2 have username/password; servers have a `token`; cloud-server has `serveruri` + `authkey`). [`99-shelly.html`](../../shelly/99-shelly.html) (~1300 LOC) holds the editor-side UI for those six types — form definitions, the dropdown population script, the field validators. ### Shared library [`lib/shelly.js`](../../shelly/lib/shelly.js) (430 LOC) is the HTTP transport layer for gen1 and gen2+. Notable members: - `shellyRequestAsync` — generic axios wrapper; transparent retry on 401 with HTTP Digest auth (gen2+); error enrichment with the device's response body (since 11.10.1). - `getDigestAuthorization` — RFC 7616-flavour digest builder; consumes the `www-authenticate` challenge and builds the next `Authorization` header. - `shellyPing` / `tryCheckDeviceType` — reachability check + device-type assertion (used at init and on every poll tick). - `start` / `startAsync` — polling loop; sets up the `setInterval` and emits `msg.error` on transitions to offline. - `getIPAddresses`, `getShellyInfo` — used by admin routes only. [`lib/configuration.js`](../../shelly/lib/configuration.js) (172 LOC) is the catalog-lookup module. It reads [`config/config.json`](../../shelly/config/config.json) once at load and exposes: - `getDeviceTypeInfos(gen)` — flat list of `{deviceType, description}` for the editor dropdown. - `getDeviceType(model)` / `getDevice(model)` — model → type / model → full entry. - `getDeviceTypes1` / `getDeviceTypes2` — given a device-family ("Relay", "Dimmer", "Sensor", "BluGateway", …), return the model-number prefixes to match. - `isExactTypeGen1` / `isExactTypeGen2` — does this token name a family or a concrete model? [`lib/utils.js`](../../shelly/lib/utils.js) (51 LOC) holds small helpers: `isMsgPayloadValid`, `isMsgPayloadValidOrArray`, `isEmpty`, `trim`, `replace`. No state, no I/O. ### Nodes [`nodes/gen1-node.js`](../../shelly/nodes/gen1-node.js) (1342 LOC, the largest file in the codebase) is the gen 1 device implementation. Its size comes from carrying **eight per-device-family input parsers** (Relay, Measure, Roller, Dimmer, Thermostat, Sensor, Button, RGBW), each translating `msg.payload` into a REST query string like `/relay/0?turn=on&timer=5`. It also owns: - `tryInstallWebhook1Async` / `tryUninstallWebhook1Async` — gen 1 callback support via the device's built-in `/settings/actions` webhooks. - `applySettings1Async` — generic `/settings/...` path for arbitrary device settings. - `convertStatus1` — extracts the interesting fields from `/status` into a slimmer object surfaced as `msg.payload`. - `getInitializer1` / `getInputParser1` — function-table dispatch on device family. - The `ShellyGen1Node` constructor. [`nodes/gen2-node.js`](../../shelly/nodes/gen2-node.js) (703 LOC) is the gen 2/3/4 device implementation. Smaller than gen 1 because the JSON-RPC envelope is uniform — `inputParserGeneric2` handles every command type with a single shape. The bulk of the file is **script / webhook lifecycle**: `tryInstallScriptAsync`, `tryUninstallScriptAsync`, `tryInstallWebhook2Async`, `tryUninstallWebhook2Async`, plus four `initializer*` variants (`polling`, `Callback`, `BluCallback`, `Webhook`) wired by `getInitializer2`. Same `ShellyGen2Node` constructor pattern as gen 1. [`nodes/cloud-node.js`](../../shelly/nodes/cloud-node.js) (164 LOC) is by far the smallest device implementation — it's a thin REST wrapper around the Shelly Cloud control API. Uses [`axios-rate-limit`](https://github.com/aishek/axios-rate-limit) capped at 1 request per second (the cloud's hard rate limit). The three `*-server-node.js` files are config-node skeletons: - [`gen1-server-node.js`](../../shelly/nodes/gen1-server-node.js) (55 LOC) and [`gen2-server-node.js`](../../shelly/nodes/gen2-server-node.js) (58 LOC) spawn a [fastify](https://www.fastify.io/) listener on a user-configured port and emit a `callback` event whenever the device hits them. gen1 wires the `/webhook` route; gen2 wires both `/callback` (script-driven) and `/webhook` (gen2-style webhooks for sensors). - [`cloud-server-node.js`](../../shelly/nodes/cloud-server-node.js) (25 LOC) just stores the cloud URI + auth key. No listener. ### Device-side scripts The two files in `shelly/scripts/` (345 LOC combined) are **not Node.js code**. They run on Shelly's embedded mJS interpreter — a JavaScript subset with no `require`, no Node modules, only the device's built-in `Shelly.*` API. The lint config explicitly excludes this directory (`--ignore-pattern scripts`). - [`callback.js`](../../shelly/scripts/callback.js) — uploaded onto every gen2+ device in callback mode. Subscribes to device events (input clicks, switch state changes, BLU advertisements forwarded by the BLU scanner) and POSTs them to the Node-RED fastify listener. - [`ble-shelly-blu.js`](../../shelly/scripts/ble-shelly-blu.js) — vendored verbatim from [`ALLTERCO/shelly-script-examples`](https://github.com/ALLTERCO/shelly-script-examples). Scans for BTHomeV2-formatted Bluetooth advertisements and emits them as events the callback script picks up. ## Device catalog as a data layer [`config/config.json`](../../shelly/config/config.json) (30 KB, 123 device entries) is the single source of truth for which devices the package supports. Its top-level shape: ```jsonc { "gen1DeviceTypes": [ // family → model-number prefixes (for matching) ["Relay", ["SHSW-", "SHPLG-", "SHUNI-", "SHEM", "SHPLG2-"]], ... ], "gen2DeviceTypes": [ // same, covering gen 2/3/4 ["Relay", ["SNSW-", "SPSW-", "SPSH-", ...]], ... ], "devices": [ // every concrete model { "gen": "1", "name": "Shelly 1", "model": "SHSW-1", "type": "Relay", "helpLink": "...", "supported": "true" }, ... ] } ``` The current breakdown by generation: | Generation | Models in catalog | |---|---:| | Gen 1 | 34 | | Gen 2 | 52 | | Gen 3 | 24 | | Gen 4 | 13 | | **Total** | **123** | **This is the key architectural lever for extensibility:** adding a new Shelly model is almost always _just_ adding an entry here. New code is only needed when the device introduces a fundamentally new behaviour family (e.g. when "BluGateway" was added). ## Boundaries - **Node-RED runtime ↔ this package:** through the [Node-RED node API](https://nodered.org/docs/creating-nodes/) — `RED.nodes.registerType`, `RED.httpAdmin.get`, `node.on('input'/'close')`, `node.send`, `node.status`, `node.warn`/`error`. No other contact points. - **Package ↔ Shelly device (local):** HTTP (gen1 REST, gen2 JSON-RPC). HTTPS is not used for local LAN access — Shelly devices on LAN do not present TLS certs. - **Package ↔ Shelly cloud:** HTTPS to a user-supplied `serverUri` with `auth_key=...` in the body, rate-limited. - **Device ↔ package (callback direction):** outbound HTTP from device to a fastify listener inside Node-RED. Requires that the device can reach Node-RED — when Node-RED is in Docker / bridged net, the server config node has a hostname/IP override. - **Package ↔ npm registry:** only at install time (no runtime fetches).