homebridge-navilink 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+All notable changes to this project are documented here. This file is generated by
+[release-please](https://github.com/googleapis/release-please) from Conventional Commit
+messages; do not edit it by hand. See [RELEASING.md](RELEASING.md).

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

@@ -0,0 +1,161 @@
+# homebridge-navilink
+
+[![Tests](https://github.com/tbaur/homebridge-navilink/actions/workflows/test.yml/badge.svg)](https://github.com/tbaur/homebridge-navilink/actions/workflows/test.yml) [![npm version](https://img.shields.io/npm/v/homebridge-navilink?style=flat-square)](https://www.npmjs.com/package/homebridge-navilink) [![npm downloads](https://img.shields.io/npm/dt/homebridge-navilink?label=downloads&style=flat-square)](https://www.npmjs.com/package/homebridge-navilink) [![Node.js](https://img.shields.io/badge/node-22%20%7C%7C%2024%20%7C%7C%2026-green)](https://nodejs.org) [![Homebridge](https://img.shields.io/badge/homebridge-2.x-purple)](https://homebridge.io) [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+
+**Navien combi boilers and water heaters in Apple HomeKit.** Hot water and space-heating thermostats, recirculation, faults and temperature probes, with changes arriving as they happen rather than on a polling loop. Verified against an NCB-240E (firmware 4352).
+
+Scheduling, weekly programmes and commissioning stay in the NaviLink app, which does them properly. This plugin adds the tile, the scene, the automation and the spoken command. It also adds a fault sensor that tells you the boiler has stopped before the shower does.
+
+> **This plugin talks to Navien's cloud, not to your boiler.** There is no local API on a NaviLink gateway. It needs your NaviLink account. See [Supported devices](#supported-devices) and [Security](#security) before you install it.
+
+## Features
+
+### Per appliance
+
+- **Hot water thermostat:** the domestic hot water setpoint, reading the actual outlet temperature. Respects the range your installer set
+- **Heating thermostat:** the space-heating flow temperature. This is the boiler's water temperature, not a room thermostat. Your room thermostat still decides when heat is called for
+- **Power switch:** on and off, with switching *off* refused by default because it stops central heating too
+- **Recirculation switch:** starts the on-demand pump, so hot water reaches the tap without running it first. Only offered where a pump is fitted. The appliance runs the pump for a fixed period and then stops; the tile turns itself off when that happens
+- **Fault sensor:** a contact sensor that opens on an error code, so HomeKit can notify you. The code goes to the log
+- **Temperature sensors:** hot water in and out, heating flow and return, and the outdoor probe if one is fitted. Each disables itself if the appliance does not report it
+
+### Reliability
+
+- **Push, not polling.** The gateway sends changes as they happen, so a setpoint changed at the wall controller or in the NaviLink app reaches HomeKit in about a second. The poll is only a backstop
+- **A rejected password is never retried.** Repeating a wrong password at a cloud is how an account gets locked. The plugin stops, says so once, and waits for you
+- **Credentials are renewed on a clock,** a few minutes before they expire, so the connection is not already dead in the middle of the night
+- **A connected socket is not a live appliance.** Readings carry the time they were taken, and a stale one becomes No Response instead of yesterday's setpoint
+- **Honest state:** No Response until the appliance has actually been read, never a value it cannot confirm
+- **Never loses your rooms:** a broken config disables the platform without unregistering anything
+
+### Quality
+
+- **Strict TypeScript,** with `noUncheckedIndexedAccess` and type-aware lint
+- **Tested:** a behavioural Jest suite against fixtures recorded from real hardware, with a guard that fails the build if anything identifying reaches them
+- **No analytics:** nothing is sent anywhere except Navien's own service
+- **One runtime dependency,** Homebridge's own UI helper. The MQTT client is a small in-repo codec, not a `mqtt.js` dependency tree
+
+Every accessory, field and log line is documented in [Detailed documentation](docs/README-DETAILED.md).
+
+## Quick Start
+
+### 1. Install
+
+**Homebridge UI** (recommended): Plugins → Search `homebridge-navilink` → Install
+
+```bash
+npm install -g homebridge-navilink
+```
+
+### 2. Prepare your appliance
+
+Your NaviLink gateway must be connected and showing as online in the NaviLink app. Nothing needs enabling: the plugin uses the same service the app does. If the app cannot see the appliance, neither can this.
+
+### 3. Configure
+
+**Homebridge UI** (recommended): open the plugin settings, enter your NaviLink email and password, and press **Sign in**. Every appliance on the account is listed, along with the accessories it can actually support. A recirculation switch is only offered where a pump is fitted. Tick what you want and press the Homebridge Save button.
+
+Or in `config.json`:
+
+```json
+{
+  "platforms": [
+    {
+      "platform": "NaviLink",
+      "name": "NaviLink",
+      "email": "you@example.com",
+      "password": "your-navilink-password",
+      "devices": [
+        {
+          "id": "a1b2c3d4e5f6:1",
+          "name": "Boiler",
+          "dhw": true,
+          "heating": true,
+          "fault": true
+        }
+      ]
+    }
+  ]
+}
+```
+
+The `id` is your gateway's MAC address and the channel. The settings page writes it for you; finding it by hand is not worth the effort.
+
+See the [full configuration reference](docs/README-DETAILED.md#full-configuration-reference) for every option.
+
+### 4. Restart Homebridge
+
+Accessories appear in the Home app after restart, showing No Response for the few seconds it takes to sign in and read the first status frame.
+
+## Supported Devices
+
+Any Navien appliance that the NaviLink app controls. The cloud interface is the same for all of them; what differs is which capabilities an appliance reports.
+
+| Verified against | Notes |
+|---|---|
+| **NCB-240E (NG)** | Combi: hot water and space heating, firmware 4352 |
+
+Other families are decoded from the same table the NaviLink app uses and are expected to work, but nobody has confirmed them here:
+
+| Family | Expected |
+|---|---|
+| **NPE, NPE2, NPN** | Tankless water heaters. Hot water only; the heating thermostat disables itself |
+| **NCB-H** | Combi with a buffer tank |
+| **NHB** | Boiler. Space heating only |
+| **NFB, NFC** | Boilers with hot water and space heating |
+| **NVW** | Water heater with a tank |
+
+If yours is not listed, it will most likely work. Please open an issue with the output of `node scripts/capture-fixture.js --redact` either way, so the table can say so with confidence.
+
+## Configuration Options
+
+Only one `NaviLink` platform block is supported. It can hold as many appliances as the account owns.
+
+| Option | Required to run | Description |
+|---|:-:|---|
+| `name` | ✓ | Plugin instance name shown in Homebridge logs |
+| `email` | ✓ | Your NaviLink account address. Needed before the plugin signs in |
+| `password` | ✓ | Your NaviLink password. Needed before the plugin signs in |
+| `devices` | ✓ | List of appliances. Needed before the plugin signs in |
+| `options.statusIntervalSec` | | Backstop refresh, 30–3600 seconds (default 120) |
+| `options.readOnly` | | Report everything, change nothing (default false) |
+| `options.allowPowerOff` | | Let HomeKit switch the appliance off (default false) |
+
+Each entry in `devices[]` takes `id` and `name`, plus an optional `channel` and one flag per accessory: `dhw`, `heating`, `power`, `recirculation`, `fault`, `temperatureSensors` and `outdoorSensor`. The [detailed documentation](docs/README-DETAILED.md#devices-entries) describes each one.
+
+## Not Working?
+
+1. **"NaviLink rejected the email address or password."** Sign in to the NaviLink app with the same credentials. The plugin has stopped trying on purpose, so fix the password and restart Homebridge
+2. **Everything shows No Response.** Check the log for `the NaviLink platform is disabled`, which means the configuration could not be read
+3. **The heating thermostat says it has no loop.** Your appliance reports no space-heating circuit. Turn the accessory off in the settings
+4. **A recirculation switch that is not offered.** No pump is fitted, or it is not commissioned. Check the NaviLink app
+5. **"The appliance refused a command for arriving too soon."** The cloud rate-limits control. The plugin pauses and retries on your next press
+
+The [full troubleshooting list](docs/README-DETAILED.md#troubleshooting) covers more, including what Off on the hot water tile does once you allow power-off.
+
+## Security
+
+This plugin needs your NaviLink password, stores it in the Homebridge configuration file as every Homebridge credential is stored, and sends it to Navien to sign in. It is never written to the Homebridge log, never put into an accessory's cache, and redacted from anything the plugin prints. That is the honest summary; [SECURITY.md](SECURITY.md) has the detail, including what a capture contains and why the fixtures in this repository are pseudonymised.
+
+## Requirements
+
+- Homebridge 2.x
+- Node.js 22, 24 or 26, matching what Homebridge 2.x itself supports
+- A North American NaviLink account (`nlus`). Other Navien regions use different hosts and will look like a rejected password
+- A NaviLink account with at least one gateway online
+- A working internet connection
+
+## More Info
+
+- [Detailed documentation](docs/README-DETAILED.md)
+- [Features](docs/FEATURES.md)
+- [Protocol reference](docs/PROTOCOL.md): what the NaviLink cloud actually does
+- [Development](DEVELOPMENT.md)
+- [Report Issues](https://github.com/tbaur/homebridge-navilink/issues)
+- [Changelog](CHANGELOG.md)
+
+## License
+
+Copyright 2026 tbaur
+
+Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) file for details.

package/SECURITY.md

@@ -0,0 +1,73 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.x.x   | ✅ Active support  |
+
+## Reporting a Vulnerability
+
+Do not open a public issue. Use GitHub's [private vulnerability reporting](https://github.com/tbaur/homebridge-navilink/security/advisories/new), and include a description, how to reproduce it, and the impact.
+
+## The honest summary
+
+**This plugin needs your NaviLink password and stores it in plain text in the Homebridge configuration file.** That is how every Homebridge plugin that talks to a cloud service works, because Homebridge offers no secret store. It deserves saying plainly.
+
+What follows from that:
+
+- Anyone who can read your Homebridge config can sign in to your NaviLink account, which controls your boiler.
+- The plugin uses an interface Navien has never published. Navien can change or withdraw it at any time, without notice, and would be within their rights to.
+- There is no local fallback. A NaviLink gateway has no LAN interface, so this stops working when your internet does.
+
+If those are not acceptable, this plugin is not for you, and that is a reasonable conclusion.
+
+## Security Measures
+
+- **Credentials in one place.** The password is read from configuration, used to sign in, and held only in memory. It is never written to a log, never placed in an accessory's cache, never sent anywhere except Navien's sign-in endpoint over HTTPS, and never passed to a script as a command-line argument.
+- **Redaction by shape, not by name.** `src/utils/redact.ts` matches JWTs, AWS key ids, signed-URL parameters and credential-shaped JSON fields by their *form*. A field name list would miss a token in a response shape nobody anticipated; this does not.
+- **Masked identifiers in the log.** The account address appears as `s…e@example.com` and a gateway MAC as `…E5F6`. Both identify you, and a Homebridge log gets pasted into issues.
+- **The accessory cache holds identity, not credentials.** Homebridge persists `{mac}:{channel}` as `deviceId` so a restart adopts the same tile. That file is plain JSON and is included in diagnostic bundles, so it must never hold the password, a token or a signed AWS URL. The MAC is the appliance's address in every MQTT topic. HomeKit serial numbers are opaque generated values, not the MAC.
+- **HomeKit serial numbers are opaque generated values,** not the gateway MAC. The Home app displays them, so they reach screenshots.
+- **Input validation.** Config is checked at startup. A missing account, or a `devices` value that is not a list, disables the platform without unregistering accessories. A bad appliance entry is skipped. Names are stripped of control characters and length-capped before they reach a log line or a characteristic.
+- **Bounded I/O.** Separate connect and total timeouts on every request, a capped HTTP response size, and a capped MQTT packet size, so a hostile or broken response cannot exhaust memory.
+- **A rejected credential stops the session.** Retrying a wrong password is how an account gets locked; the plugin declines to do it.
+- **Minimal dependencies.** One at runtime: Homebridge's own UI helper. The MQTT client is in this repository, for a protocol reason ([PROTOCOL.md](docs/PROTOCOL.md)) that also reduces supply-chain surface.
+- **Dependencies audited.** CI runs `npm audit` on the runtime tree and OSV-Scanner on the full tree.
+- **A CI step rejects credential-shaped strings** in the published docs, fixtures, schema and issue templates, so a token cannot be committed by accident. Unit tests that hold fake JWTs are outside that scan on purpose.
+
+## The settings page
+
+The configuration UI runs in its own short-lived process and is the one place that handles a typed password.
+
+- The password is used for the sign-in of the request that carried it. It is not cached between requests and not written to a file by that process.
+- Nothing from a sign-in response reaches the browser. The page receives appliances; the tokens and AWS credentials stay in the UI process and die with the request.
+- Diagnostic output handed back on failure is the plugin's own redacted log, filtered a second time on the way out, because a line that reaches a browser can end up in a screenshot in a public issue.
+
+## Captures and fixtures
+
+A raw frame from the NaviLink cloud carries your gateway's MAC address and your account's sequence numbers. The `device/info` endpoint also returns your installation's **street address and coordinates**, which is why the plugin reads only the firmware version from it and nothing else is available to callers.
+
+- Raw captures go to `tests/fixtures/raw/`, which is git-ignored.
+- `scripts/pseudonymise.js` rewrites them and then audits its own output. It reports every identifier that remains. It does not trust a list of field names. A MAC appears twice in two spellings in these frames, and a name-driven rewrite misses the second.
+- `tests/unit/fixtures.test.ts` fails the build if a MAC, email address, JWT or AWS key that is not the documented example appears in `tests/fixtures/`.
+- `scripts/capture-fixture.js --redact` is the form to paste into a bug report. Read it before you paste it: the redaction is good, and it is not a promise.
+
+## Best Practices for Users
+
+1. Keep Homebridge and this plugin updated.
+2. Run Homebridge with minimal privileges, and do not expose it to the internet.
+3. Protect the Homebridge configuration file and any backup of it as you would a password file, because it contains one.
+4. Use `options.readOnly` if you want the readings without the plugin being able to change anything.
+5. Leave `options.allowPowerOff` off unless you have thought about what "turn everything off" means in February.
+6. Consider a NaviLink account used only for this, if you would rather not have your primary one in a config file.
+
+## Response Timeline
+
+- **Acknowledgment**: Within 48 hours
+- **Initial assessment**: Within 1 week
+- **Fix timeline**: Depends on severity
+  - Critical: 24-48 hours
+  - High: 1 week
+  - Medium: 2 weeks
+  - Low: Next release

package/config.schema.json

@@ -0,0 +1,138 @@
+{
+  "pluginAlias": "NaviLink",
+  "pluginType": "platform",
+  "singular": true,
+  "customUi": true,
+  "customUiPath": "./homebridge-ui",
+  "headerDisplay": "Exposes Navien combi boilers and water heaters to HomeKit through the North American NaviLink cloud (`nlus`): hot water and space-heating thermostats, a power switch, recirculation, a fault sensor and temperature probes. Verified on an NCB-240E. Press **Sign in** to list the appliances on your account; every field below can also be edited by hand.",
+  "footerDisplay": "Your NaviLink password is stored in the Homebridge configuration file, because the plugin has to sign in again after a restart and Navien offers no other credential. See the [documentation](https://github.com/tbaur/homebridge-navilink#readme) for what this plugin does and does not do.",
+  "schema": {
+    "type": "object",
+    "required": ["name"],
+    "properties": {
+      "name": {
+        "title": "Platform Name",
+        "type": "string",
+        "default": "NaviLink",
+        "description": "Shown in the Homebridge log."
+      },
+      "email": {
+        "title": "NaviLink Email",
+        "type": "string",
+        "format": "email",
+        "maxLength": 254,
+        "description": "The email address for your NaviLink account, the same one you use in the NaviLink app."
+      },
+      "password": {
+        "title": "NaviLink Password",
+        "type": "string",
+        "maxLength": 256,
+        "x-schema-form": { "type": "password" },
+        "description": "Stored in plain text in the Homebridge configuration file, as every Homebridge credential is. It is never written to the Homebridge log."
+      },
+      "options": {
+        "title": "Options",
+        "type": "object",
+        "properties": {
+          "statusIntervalSec": {
+            "title": "Status Refresh (seconds)",
+            "type": "integer",
+            "default": 120,
+            "minimum": 30,
+            "maximum": 3600,
+            "description": "A floor on how stale a reading can be. The appliance pushes changes as they happen, so this is not how state normally arrives; it is the backstop for a push that was missed."
+          },
+          "readOnly": {
+            "title": "Read-only",
+            "type": "boolean",
+            "default": false,
+            "description": "Report everything, change nothing. Every accessory still shows state, and a HomeKit write is declined with one explanatory line in the log."
+          },
+          "allowPowerOff": {
+            "title": "Allow HomeKit to Switch the Appliance Off",
+            "type": "boolean",
+            "default": false,
+            "description": "Off by default, and worth leaving off. On a combi appliance the power state governs central heating as well as hot water, so \"turn off the water heater\" said to Siri, or a scene that turns everything off, would stop the heating in a house that may be empty and freezing. With this off, a power-off request is declined and explained instead of obeyed."
+          }
+        }
+      },
+      "devices": {
+        "title": "Appliances",
+        "type": "array",
+        "items": {
+          "type": "object",
+          "title": "Appliance",
+          "required": ["id", "name"],
+          "properties": {
+            "id": {
+              "title": "Identity",
+              "type": "string",
+              "minLength": 3,
+              "maxLength": 20,
+              "pattern": "^[0-9a-fA-F]{12}:([1-9]|[12][0-9]|3[0-2])$",
+              "examples": ["a1b2c3d4e5f6:1"],
+              "description": "Stable identity: twelve hex digits and the channel, as the settings page writes it (lowercase, no separators). Changing it detaches the accessories from their HomeKit rooms and automations."
+            },
+            "name": {
+              "title": "Name",
+              "type": "string",
+              "maxLength": 64,
+              "examples": ["Zone One"],
+              "description": "The appliance's name. Accessories are named from it: \"Boiler\" gives \"Boiler Hot Water\", \"Boiler Heating\", \"Boiler Fault\" and so on."
+            },
+            "channel": {
+              "title": "Channel",
+              "type": "integer",
+              "default": 1,
+              "minimum": 1,
+              "maximum": 32,
+              "description": "1 for a single appliance. A cascade of several appliances behind one gateway uses a channel each."
+            },
+            "dhw": {
+              "title": "Hot Water Thermostat",
+              "type": "boolean",
+              "default": true,
+              "description": "The domestic hot water setpoint, as a HomeKit thermostat. Reads the outlet temperature. Switching it off does not switch the appliance off unless you also allow that above."
+            },
+            "heating": {
+              "title": "Heating Thermostat",
+              "type": "boolean",
+              "default": false,
+              "description": "The space-heating water setpoint, as a HomeKit thermostat. This is the boiler's flow temperature, not a room thermostat: it sets how hot the water going to your radiators is, and your existing room thermostat still decides when heat is called for. Only useful on a combi; an appliance with no heating loop disables it and says so in the log."
+            },
+            "power": {
+              "title": "Power Switch",
+              "type": "boolean",
+              "default": false,
+              "description": "A switch for the appliance's power state. Switching it off is refused unless \"Allow HomeKit to switch the appliance off\" is on."
+            },
+            "recirculation": {
+              "title": "Recirculation Switch",
+              "type": "boolean",
+              "default": false,
+              "description": "Starts the on-demand hot water recirculation pump, so hot water reaches the tap without running it first. The appliance runs the pump for a fixed period and then stops; the switch turns itself off when that happens. Only for appliances with a pump fitted and commissioned."
+            },
+            "fault": {
+              "title": "Fault Sensor",
+              "type": "boolean",
+              "default": false,
+              "description": "A contact sensor that opens when the appliance reports an error code, so HomeKit can notify you. The code itself is written to the log."
+            },
+            "temperatureSensors": {
+              "title": "Temperature Sensors",
+              "type": "boolean",
+              "default": false,
+              "description": "Four read-only sensors: hot water in and out, and heating flow and return. Each one disables itself if the appliance turns out not to report it."
+            },
+            "outdoorSensor": {
+              "title": "Outdoor Temperature",
+              "type": "boolean",
+              "default": false,
+              "description": "The outdoor probe, on an installation that has one fitted for weather compensation. Most do not."
+            }
+          }
+        }
+      }
+    }
+  }
+}