matterbridge-dynalite 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0 — unreleased
+
+First version.
+
+- Lights: each channel as a dimmable or on/off light, or an area as one light switched by its presets.
+- Heating: thermostat areas as Matter heating thermostats, with temperature and setpoint.
+- Live updates from the gateway's DyNet TCP port (DyNet 1 and DyNet2), with a read-back after fades.
+- Commands and reads over the gateway's HTTP API, one request at a time.
+- Several gateways; devices identified by gateway name, area and channel.
+- Two devices with the same name (a room's light and its thermostat) are told apart, as Matterbridge refuses the second.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,147 @@
-# Temporary Holding Version
+# matterbridge-dynalite
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A [Matterbridge](https://github.com/Luligu/matterbridge) plugin for **Signify Dynalite** (formerly Philips Dynalite). It puts your Dynalite lights and heating into Apple Home, Google Home, Alexa, SmartThings, Home Assistant or any other Matter controller. The plugin talks straight to the Dynalite Ethernet gateway, with nothing in between.
+
+- **Lights.** Each channel can be its own Matter light: dimmable, or on/off for a relay. An area can also be shown as one light that is switched by its presets.
+- **Heating.** A thermostat area becomes a Matter heating thermostat, with the room temperature and a setpoint you can change.
+- **Live updates.** With the gateway's DyNet TCP port set up, the plugin reads the bus as it happens. A wall panel press, a timer, a fade, a temperature or a setpoint changed at the thermostat shows in Matter at once. Both DyNet 1 and DyNet2 are read.
+- **Commands** use the gateway's own HTTP API, the same one its web pages use. The plugin never writes to the bus directly.
+- **Several gateways**, one per site or one per house.
+
+> **Status:** early, but in use. The DyNet2 decoding comes from traffic captured on a PDEG and checked against Dynalite's own monitor (see [docs/DYNET.md](docs/DYNET.md)). Reports from other gateways and installations are very welcome.
+
+## How it works
+
+```
+ Matter controller ⇄ Matterbridge ⇄ matterbridge-dynalite ─ HTTP (commands, reads) ─┐
+                                                           └─ TCP (DyNet, live) ─────┴─ Dynalite Ethernet gateway ─ DyNet bus
+```
+
+- **At start-up,** every configured area is read over HTTP (`GetDyNet.cgi`).
+- **With a DyNet port,** the plugin keeps a TCP connection open and decodes every packet. It updates the devices it knows and ignores the rest. When a preset or a fade changes channel levels, it reads the area again once the fade is done, so Matter shows where the lights ended up.
+- **Commands** from Matter go to `SetDyNet.cgi`: a channel level with a fade, a preset, or a setpoint.
+- **Every area is read again** every *pollMinutes*. With live updates this is a check (60 minutes by default). Without them it is the only source of state (5 minutes by default).
+
+## Requirements
+
+- Matterbridge 3.3.0 or later, on Node.js 20, 22 or 24.
+- A Dynalite Ethernet gateway whose web server can be reached from Matterbridge (PDEG, DDNG and similar, with `GetDyNet.cgi` / `SetDyNet.cgi`).
+- For live updates, a TCP server port set up on the gateway in its own configuration tool (e.g. System Builder/EnvisionProject): **Mode** Server, **Protocol** TCP, **Connection** *Trunk*, **Port type** DyNet or DyNet2, and a port number, e.g. 50000. A gateway can have several such ports. If another program already listens on one, give this plugin its own.
+  - **A new port needs routes.** In the gateway's routing table, route at least *Comm Port 1* (the DyNet bus), *Internal Messages* and the *Web Socket* port **to** the new port. Without them the port connects but sends only its own heartbeat. Copy the routes the gateway's existing trunk port has. No routes **from** the new port are needed: the plugin only listens.
+
+## Installation
+
+Once published on npm, install it from the Matterbridge frontend (*Install plugin* → `matterbridge-dynalite`) or from a shell on the Matterbridge host:
+
+```bash
+matterbridge -add matterbridge-dynalite
+```
+
+Until then, build it from this repository on the Matterbridge host:
+
+```bash
+git clone https://github.com/jonaskul/matterbridge-dynalite.git
+cd matterbridge-dynalite
+npm install && npm link matterbridge && npm run build
+matterbridge -add "$PWD"
+```
+
+Restart Matterbridge, open the plugin's settings and add your gateway(s).
+
+## Configuration
+
+Everything is set in the plugin's settings in the Matterbridge frontend, and saved as `matterbridge-dynalite.config.json`:
+
+```json
+{
+  "name": "matterbridge-dynalite",
+  "type": "DynamicPlatform",
+  "gateways": [
+    {
+      "name": "Home",
+      "host": "192.168.1.50",
+      "dynetPort": 50000,
+      "fadeSeconds": 2,
+      "areas": [
+        { "area": 9, "name": "Stairs", "type": "light", "channels": [{ "channel": 1 }] },
+        {
+          "area": 10,
+          "name": "Kitchen",
+          "type": "light",
+          "channels": [
+            { "channel": 1, "name": "Kitchen ceiling" },
+            { "channel": 2, "name": "Kitchen worktop" },
+            { "channel": 3, "name": "Kitchen sockets", "dimmable": false }
+          ]
+        },
+        { "area": 24, "name": "Garden", "type": "light", "onPreset": 1, "offPreset": 4 },
+        { "area": 18, "name": "Bedroom", "type": "thermostat", "minSetpoint": 10, "maxSetpoint": 25 }
+      ]
+    }
+  ]
+}
+```
+
+| Gateway setting | | Default |
+|---|---|---|
+| `name` | Short and unique. It is part of every device's identity, so keep it once set. | |
+| `host` | The gateway's IP or host name, with `:port` only if its web server is not on 80/443. Not the DyNet port. | |
+| `https`, `allowSelfSigned` | HTTPS, and whether to accept the gateway's self-signed certificate. | off |
+| `username`, `password` | Only if the gateway asks for HTTP authentication. | |
+| `dynetPort` | The gateway's DyNet TCP port for live updates. Leave it empty to poll only. | none |
+| `pollMinutes` | How often every area is read over HTTP. | 60 with live, 5 without |
+| `fadeSeconds` | The fade for commands from Matter that don't give one. | 2 |
+
+| Area setting | | Default |
+|---|---|---|
+| `area` | The DyNet area number (1–65535). | |
+| `name` | The name shown in your controller. If a light and a thermostat share a name, the second gets " thermostat" or " light" added. | |
+| `type` | `light` or `thermostat`. | `light` |
+| `channels` | For lights: `channel`, `name` and `dimmable` (false for a relay). Leave it out to show the area as one light switched by presets. | |
+| `onPreset`, `offPreset` | For an area light without channels: the presets that switch it. | 1, 4 |
+| `minSetpoint`, `maxSetpoint` | For thermostats: the range offered, °C. Setpoints are sent in half degrees. | 5, 30 |
+
+Matterbridge's usual `whiteList`, `blackList`, `debug` and `unregisterOnShutdown` settings work as in other plugins.
+
+### Finding area and channel numbers
+
+They are in your Dynalite configuration (System Builder or EnvisionProject). You can also watch the bus: with a DyNet port set and `debug` on, the plugin logs what it receives. Press a panel and look for `area N ch M`.
+
+Or watch the port from a shell on the Matterbridge host, without Matterbridge (also a quick check that the port is set up right):
+
+```bash
+node /path/to/matterbridge-dynalite/dist/listen.js 192.168.1.50 50000   # add --all for heartbeats and bytes
+```
+
+## Notes and limits
+
+- **Setpoints and temperatures** are taken from what the thermostats send. Only temperatures above 0 °C have been seen so far, so how a negative temperature is sent is not known yet.
+- **Presets.** Matter has no scenes for bridged lights, so presets aren't exposed as such. An area without channels can be switched on and off through two of them.
+- **The gateway answers one HTTP request at a time.** If other software (a dashboard, Home Assistant) also polls it, keep the poll intervals reasonable.
+
+## Development
+
+Matterbridge is linked, not installed. This follows Matterbridge's rule that plugins never depend on it:
+
+```bash
+npm install -g matterbridge
+npm install
+npm link matterbridge
+npm run build
+npm test
+```
+
+The tests cover the DyNet decoding (with packets captured from real gateways), the HTTP client and the TCP connection against local fakes, and the platform inside a real matter.js server with Matterbridge's test harness.
+
+To try a local build in Matterbridge, run `matterbridge -add /path/to/matterbridge-dynalite` and restart it.
+
+### Releasing
+
+1. Set the new version in `package.json` (and in `CHANGELOG.md`), and push it.
+2. Make a GitHub release with the tag `v<version>`, e.g. `v0.1.0`.
+
+The *Publish* workflow then tests it and publishes it to npm with provenance, through npm's trusted publishing (no token in the repository). A release marked as a pre-release goes out under the `next` tag, so Matterbridge keeps offering the last full release.
+
+## Licence
+
+Apache-2.0. Dynalite, DyNet, Signify and Philips are trademarks of their respective owners. This project is not affiliated with or endorsed by Signify.

package/dist/bridge.d.ts

@@ -0,0 +1,87 @@
+/**
+ * One gateway: its areas as devices, kept up to date from the bus and from
+ * reads, and driven by commands. Knows nothing of Matter — it reports through
+ * a DeviceSink and acts through a GatewayApi — so it can be tested on its own.
+ */
+import { type Area, type Gateway } from './config.js';
+import { type DynetEvent } from './dynet.js';
+/** What the gateway can be asked and told (GatewayHttp, or a stand-in in tests). */
+export interface GatewayApi {
+    getPreset(area: number): Promise<number | undefined>;
+    getLevel(area: number, channel: number): Promise<number | undefined>;
+    getTemperature(area: number): Promise<number | undefined>;
+    getSetpoint(area: number): Promise<number | undefined>;
+    setPreset(area: number, preset: number, fadeMs?: number): Promise<void>;
+    setLevel(area: number, channel: number, percent: number, fadeMs?: number): Promise<void>;
+    setSetpoint(area: number, setpoint: number): Promise<void>;
+}
+/** Where state goes: the Matter side, or a recorder in tests. Levels in percent, temperatures in °C. */
+export interface DeviceSink {
+    light(id: string, state: {
+        on: boolean;
+        level?: number;
+    }): void;
+    thermostat(id: string, state: {
+        temperature?: number;
+        setpoint?: number;
+    }): void;
+}
+export interface Logger {
+    info(message: string): void;
+    warn(message: string): void;
+    debug(message: string): void;
+}
+export type DeviceKind = 'dimmable' | 'onoff' | 'thermostat';
+export interface Device {
+    id: string;
+    kind: DeviceKind;
+    name: string;
+    area: number;
+    /** The channel, for a channel light; none for an area switched by preset, or a thermostat. */
+    channel?: number;
+    config: Area;
+}
+/** After a change on the bus, an area is read back once its fade is done, plus this (ms). */
+export declare const READ_AFTER_MS = 1500;
+/** Between areas when reading them all, so the gateway is not swamped (ms). */
+export declare const STAGGER_MS = 500;
+export declare class GatewayBridge {
+    readonly gateway: Gateway;
+    private readonly api;
+    private readonly sink;
+    private readonly log;
+    private readonly timing;
+    readonly devices: Device[];
+    private readonly byId;
+    private readonly byArea;
+    /** The level a channel light was last on at, to go back to when switched on. */
+    private readonly lastLevel;
+    private readonly reads;
+    private pollTimer?;
+    private live?;
+    private stopped;
+    constructor(gateway: Gateway, api: GatewayApi, sink: DeviceSink, log?: Logger, timing?: {
+        readAfterMs: number;
+        staggerMs: number;
+    });
+    get liveConnected(): boolean;
+    /** Read every area now, then listen to the bus (if a port is set) and read again every pollMinutes. */
+    start(): Promise<void>;
+    stop(): void;
+    handleEvent(event: DynetEvent): void;
+    /** Read one area again after *fadeSeconds* (plus a little); a newer change puts it off. */
+    readArea(area: number, fadeSeconds?: number): void;
+    refreshAll(): Promise<void>;
+    refreshArea(area: number): Promise<void>;
+    private showLevel;
+    lightOn(id: string, fadeMs?: number): Promise<void>;
+    lightOff(id: string, fadeMs?: number): Promise<void>;
+    /** A channel to a level in percent; 0 switches it off. */
+    lightLevel(id: string, percent: number, fadeMs?: number): Promise<void>;
+    /** A thermostat's setpoint, within its limits. Returns what was sent. */
+    setSetpoint(id: string, celsius: number): Promise<number>;
+    private get fadeMs();
+    /** With the bus heard, its echo brings the state back; without it, read the area once the fade is done. */
+    private afterCommand;
+    private device;
+}