signalk-czone 0.3.0-beta.13 → 0.3.0-beta.15

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.3.0-beta.15
+
+- Preserves plugin settings when uploading a ZCF or selecting a network configuration (#32).
+- Publishes switch-input states for Signal Interface, COI and Control X PLUS modules (#30).
+- Adds the Navico chartplotter touch layout, drag scrolling and reduced redraw cost (#31).
+- Updates the canonical ZCF parser to 0.1.0-beta.2 for newer Configuration Tool layouts and corrected tank settings.
+
+## 0.3.0-beta.14
+
+- Adds bidirectional CZone links to Shelly Gen2+ switches and Victron GX outputs, with startup, confirmation and relay-function safeguards.
+- Restores Navico chartplotter compatibility with Chromium 69 syntax and flex-spacing fallbacks.
+
 ## 0.3.0-beta.13
 
 - Adds a fullscreen icon beside the CZone / Boat Systems branding, with expand/collapse states and accessible labels.

package/README.md

@@ -57,6 +57,28 @@ The existing electrical-monitoring definition endpoint remains:
 GET /plugins/signalk-czone/monitoring
 ```
 
+## Switch inputs
+
+Each switch input in the ZCF (a switch, float switch or signal wired to a CZone module) is published as `electrical.czone.inputs.<input name>.state`, `true` when the input is on. The name is cleaned the same way as circuit names; a repeated name gets `2`, `3` and so on. A value is published when the plugin first hears the module and then only on change.
+
+Where an input's state is read depends on the kind of module (its type in the ZCF):
+
+| Module | Message read | Input `i` is at |
+| --- | --- | --- |
+| Signal Interface | 65284 status and 65308 input message | bit `2i+1` |
+| COI | 65308 input message only (its 65284 is its outputs) | bit `2(i-16)+1` |
+| Control X PLUS | 65284 status only | bit `i`, or `i+1` when wired to switch to negative |
+
+Inputs on other kinds of module are listed but not given a state. Checked on a Signal Interface on a test bench, COIs on SugarShack and a Control X PLUS on Compass Rose (Anchor Up, Ignition, High Bilge Water Alarm). Only one Control X PLUS input wired to negative has been seen.
+
+```text
+GET /plugins/signalk-czone/inputs
+```
+
+lists each input with its module, input number, wiring, module type, state and when it last changed.
+
+The input table needs `signalk-czone-zcf` with `signalInputs` (the newer Configuration Tool layout included).
+
 ## Design
 
 The plugin does **not** modify Signal K Server, canboatjs, n2k-signalk, or any global PGN definitions.
@@ -195,9 +217,27 @@ Full detail is written on change (plus the last unchanged sample before a change
 - `GET /plugins/signalk-czone/trend?path=<Signal K path>&range=1h|24h|7d|31d|90d|1y`, or `&from=<ms>&to=<ms>` for a custom period. Answers `{ available, tier, start, end, gapMs, data, latest }`, where `data` rows are `[t, value]` (full detail) or `[t, avg, min, max]` (summaries, or full detail reduced to about 400 points), and `latest` is the live value while the circuit is reporting.
 - `GET /plugins/signalk-czone/trend/status` answers where trends are going, free space, and how many circuits are being recorded, or the reason trends are off.
 
+## Third-party switches
+
+Switch something that is not on the CZone network from a CZone display or keypad, with no switchbank: a Shelly, a GX relay, or any output in the Victron switch pane.
+
+1. In the CZone Configuration Tool, add a **virtual circuit** for it and put it on the display. Write the configuration and upload the new ZCF to the plugin.
+2. In the configuration panel, under **Third-party switches**, choose that circuit and link it to:
+   - **a Victron output (through the GX):** anything Venus OS lists as a switchable output: a Shelly added to the GX, the GX's own relays, a Node-RED virtual switch. Needs the plugin running on the GX (D-Bus; `dbus-native` is an optional dependency). A GX relay is offered only when its function is **Manual**; one used as an alarm relay, for a generator, a tank pump or temperature is listed greyed out with the reason and never switched. Set-points and dimmers are not offered as on/off switches.
+   - **a Shelly (directly, by IP address):** Shelly Gen2 or later, no password, through its local RPC API (`/rpc/Switch.Set`, `/rpc/Switch.GetStatus`). No GX needed. **Test** asks the Shelly for its state.
+
+The switch follows the CZone circuit, and the circuit follows the switch when it is switched from anywhere else (its app, the Victron pane, VRM); that needs **Enable CZone read/write control**. Rules, so the two never fight:
+
+- a side is acted on only when it changes, and only if the other side differs; the plugin's own change coming back is recognised;
+- **nothing is switched when the plugin starts**: if the two differ (a GX relay comes back off after a reboot), the link shows *out of step* until one side is switched;
+- a circuit set to **confirm before turning off (on)** is never turned off (on) by a link, unless other apps are allowed to; the link says why and does not retry;
+- a change one side could not take (unreachable, refused, sending disabled) is retried every 15 s; a switch that accepts a command but does not change is reported after 6 s.
+
+The switch is read every 2 s; a CZone change is acted on as its status message arrives. `GET /plugins/signalk-czone/bridge/status` shows each link; `/bridge/outputs` lists the GX's outputs; `/bridge/shelly?host=&channel=` asks a Shelly. Tested on a bench (Shelly PM1 both ways) and on a boat (GX relay 2 switched from a CZone display; the alarm relay refused).
+
 ## Installation
 
-The plugin installs the pinned `signalk-czone-zcf@0.1.0-beta.1` npm dependency automatically. No separate parser installation or Git checkout is required.
+The plugin installs the pinned `signalk-czone-zcf@0.1.0-beta.2` npm dependency automatically. No separate parser installation or Git checkout is required.
 
 ### Signal K App Store
 
@@ -221,11 +261,11 @@ npm install signalk-czone@latest --omit=dev --ignore-scripts
 
 Restart Signal K and follow the configuration steps above. For Docker or appliance installations, use the corresponding container/configuration directory and restart method.
 
-For installation from a maintainer-provided npm tarball, run `npm install /path/to/signalk-czone-0.3.0-beta.9.tgz --omit=dev --ignore-scripts` from the same configuration directory. Its pinned parser dependency must already be published to npm. Do not simply extract the plugin into `node_modules`: that does not install dependencies.
+For installation from a maintainer-provided npm tarball, run `npm install /path/to/signalk-czone-0.3.0-beta.15.tgz --omit=dev --ignore-scripts` from the same configuration directory. Its pinned parser dependency must already be published to npm. Do not simply extract the plugin into `node_modules`: that does not install dependencies.
 
 ### Publishing (maintainers)
 
-Publish `signalk-czone-zcf@0.1.0-beta.1` first. Then run `npm install`, `npm test`, and `npm pack --dry-run` in this repository, verify the runtime files and App Store assets, and run `npm publish --tag latest` after npm authentication.
+Publish `signalk-czone-zcf@0.1.0-beta.2` first. Then run `npm install`, `npm test`, and `npm pack --dry-run` in this repository, verify the runtime files and App Store assets, and run `npm publish --tag latest` after npm authentication.
 
 The package defaults to `latest`, including versions named `-beta.N`. The GitHub publishing workflow runs when `package.json` or the workflow changes on `main`: it tests and packs the release, publishes it if the version is new, and sets and verifies the `latest` tag. If the version already exists, the workflow promotes that existing version without republishing its contents.
 
@@ -424,6 +464,15 @@ Only the installed path is stored in plugin configuration; the binary ZCF is not
 
 The beta is intended for extended real-world testing before a stable `0.3.0` release.
 
+## On a Navico chartplotter (B&G, Simrad, Lowrance)
+
+A Navico plotter shows the webapp in its own browser (Chromium 69), driven by a touch screen whose touches arrive as mouse events. The page recognises the plotter from the parameters the plotter adds to the address (`mfd_name`, `mfd_model_detail`, `brand`), or from the login token left by `signalk-navico-embedder`, and switches to a touch layout. `?layout=mfd` shows it in a desktop browser for testing. Nothing changes anywhere else.
+
+- **Touch layout:** larger rows, buttons and navigation; no banner, overview or category chips; drawn icons in place of emoji and symbol characters the plotter's fonts lack; no shadows, gradients, blur or transitions, which are slow to draw there.
+- **Scrolling:** a drag scrolls the list or the left column instead of selecting text, applied once per frame, and the tap that ends a drag is not taken as a press. Redraws caused by live data wait while a finger is down.
+- **Updates:** the plotter keeps showing the page it first loaded. Once a minute the page checks whether its script has changed on the server and reloads once if so.
+- **Diagnosis:** five taps on the connection line show the last input events, the frame time and the time to redraw the list.
+
 ## Fullscreen and tablet home-screen launch
 
 Open `/signalk-czone/` directly in your browser. The **fullscreen icon** beside

package/index.js

@@ -3,12 +3,16 @@
 const path = require('path')
 const fs = require('fs')
 const zcf = require('./lib/zcf')
+const inputs = require('./lib/inputs')
 const czone = require('./lib/czone')
 const nmea = require('./lib/nmea2000')
 const monitoring = require('./lib/monitoring')
 const { createTrends } = require('./lib/trends')
 const signalk = require('./lib/signalk')
 const confirmOffLib = require('./lib/confirm-off')
+const { createBridge, bridgeEntries } = require('./lib/bridge')
+const { createShellyDriver } = require('./lib/bridge/shelly')
+const { createVictronDriver } = require('./lib/bridge/victron')
 
 const MAX_UPLOAD_BYTES = 1024 * 1024
 const CZONE_CONFIG_BLOCK_HEADER = 23
@@ -104,6 +108,49 @@ module.exports = function (app) {
   let nmeaReadyAt = null
   let lastNmeaOutput = null
   let runtimeState = new Map()
+
+  // Third-party switches (lib/bridge): a CZone circuit, normally a virtual
+  // circuit added for the purpose, linked to a switch that is not on the CZone
+  // network: a Victron switchable output on the GX's D-Bus (a Shelly added to
+  // the GX, a GX relay set to Manual, a Node-RED virtual switch) or a Shelly
+  // reached directly by IP. lib/bridge holds the linking rules and the drivers
+  // and has no CZone or Signal K code in it.
+  let bridgeBus = null
+  function getBridgeBus () {
+    if (bridgeBus) return bridgeBus
+    let dbus
+    try { dbus = require('dbus-native') } catch (_) { throw new Error('D-Bus support is not installed (only available on a Victron GX)') }
+    bridgeBus = dbus.systemBus()
+    if (bridgeBus && bridgeBus.connection && typeof bridgeBus.connection.on === 'function') {
+      bridgeBus.connection.on('error', err => { log(`Bridge D-Bus: ${err.message}`); closeBridgeBus() })
+    }
+    return bridgeBus
+  }
+  function closeBridgeBus () {
+    if (!bridgeBus) return
+    try { if (bridgeBus.connection && typeof bridgeBus.connection.end === 'function') bridgeBus.connection.end() } catch (_) {}
+    bridgeBus = null
+  }
+  const bridgeDrivers = { victron: createVictronDriver({ getBus: getBridgeBus }), shelly: createShellyDriver() }
+  const bridge = createBridge({
+    log: m => log(m),
+    readCircuit: name => {
+      const st = runtimeState.get(name)
+      return st && st.statusObserved && (st.state === 'ON' || st.state === 'OFF') ? st.state === 'ON' : undefined
+    },
+    writeCircuit: (name, on) => {
+      const c = mapping && mapping.circuits.find(x => x.name === name)
+      if (!c) throw new Error(`no circuit "${name}" in the CZone configuration`)
+      // A link cannot ask "are you sure?": a circuit nominated to confirm is
+      // never switched that way by a link, unless other apps are allowed to.
+      // Refused for good (not retried); the link shows why.
+      const refuse = text => { const err = new Error(text); err.permanent = true; throw err }
+      if (!on && confirmOff.has(c.name) && settings.confirmOffAllowElsewhere !== true) refuse('not switched off: this circuit asks before turning off')
+      if (on && confirmOn.has(c.name) && settings.confirmOnAllowElsewhere !== true) refuse('not switched on: this circuit asks before turning on')
+      sendCircuitState(c, on)
+    },
+    drivers: bridgeDrivers
+  })
   let monitoringRuntime = null
   // Trend recording of circuit current (see lib/trends).
   let trends = null
@@ -125,6 +172,10 @@ module.exports = function (app) {
   // Circuits nominated to confirm before switching, by circuit name.
   let confirmOff = new Set()
   let confirmOn = new Set()
+  // Switch inputs of the loaded configuration (lib/inputs) and their last
+  // decoded state, by Signal K path.
+  let switchInputs = []
+  let inputState = new Map()
 
   const configRoot = app.config && app.config.configPath
     ? path.join(app.config.configPath, 'plugin-config-data')
@@ -167,12 +218,16 @@ module.exports = function (app) {
   function loadConfiguredZcf () {
     if (!fs.existsSync(zcfPath())) {
       mapping = null
+      switchInputs = []
+      inputState = new Map()
       return null
     }
     mapping = zcf.load(zcfPath())
     mapping.commandDeviceId = selectCommandDeviceId(mapping)
     publishedCircuitValues.clear()
     monitoringRuntime = monitoring.createRuntime(mapping.meters || [])
+    switchInputs = inputs.switchInputs(mapping)
+    inputState = new Map(switchInputs.map(i => [i.path, { state: null, since: null }]))
     runtimeState = new Map(mapping.circuits.map(c => [c.name, {
       state: null,
       percent: null,
@@ -718,6 +773,13 @@ module.exports = function (app) {
   // bitmap. The runtime module/bit mapping is decoded from the ZCF status
   // table; it is intentionally not inferred from the primary ZCF
   // module/channel identity.
+  function startBridge () {
+    const entries = bridgeEntries(settings.bridges)
+    const known = entries.filter(e => mapping && mapping.circuits.some(c => c.name === e.circuit))
+    for (const e of entries) if (!known.includes(e)) log(`Third-party switch: circuit "${e.circuit}" is not in the CZone configuration; link ignored`)
+    bridge.start(known)
+  }
+
   function decodeCzoneCircuitStatus (frame) {
     if (!frame || frame.pgn !== 65284 || !frame.data || frame.data.length !== 8) return
     const data = frame.data
@@ -763,6 +825,7 @@ module.exports = function (app) {
         }
       }
 
+      bridge.onCircuit(circuit.name, enabled) // a linked switch follows at once
       const stateSource = signalk.nmea2000Source(frame.source, frame.pgn)
       const observedState = enabled ? 'ON' : 'OFF'
       log(`CZone STATE: ${circuit.name} -> ${observedState} (runtime ${Number(circuit.statusModule).toString(16).padStart(2, '0')}:${Number(circuit.statusMask).toString(16).padStart(8, '0')}, src=${frame.source})`)
@@ -838,6 +901,25 @@ module.exports = function (app) {
     }
   }
 
+  // Switch inputs: PGN 65284 (module status) and 65308 (input message), each
+  // input read only from the message its kind of module carries it in.
+  function decodeSwitchInputs (frame) {
+    if (!switchInputs.length) return
+    const decoded = inputs.decodeFrame(frame.data)
+    if (!decoded) return
+    for (const input of switchInputs) {
+      if (input.module !== decoded.module) continue
+      const on = inputs.inputState(input.moduleKind, decoded.bitmap, input.input, frame.pgn, input.wiring)
+      if (on === undefined) continue
+      const entry = inputState.get(input.path)
+      if (entry.state === on) continue
+      entry.state = on
+      entry.since = new Date().toISOString()
+      log(`CZone INPUT: ${input.name} ${on ? 'ON' : 'OFF'} (PGN ${frame.pgn} module=0x${decoded.module.toString(16).padStart(2, '0')} bitmap=0x${decoded.bitmap.toString(16).padStart(8, '0')})`)
+      publishDelta(input.path, on)
+    }
+  }
+
   function handleRawFrame (line) {
     const frame = nmea.parseRawLine(line)
     if (!frame) return
@@ -847,7 +929,12 @@ module.exports = function (app) {
       handleConfigFastPacket(frame)
       return
     }
+    if (frame.pgn === inputs.INPUT_PGN) {
+      decodeSwitchInputs(frame)
+      return
+    }
     if (frame.pgn === 65284) {
+      decodeSwitchInputs(frame)
       decodeCzoneCircuitStatus(frame)
       return
     }
@@ -1221,6 +1308,23 @@ module.exports = function (app) {
           title: 'Let other apps turn those circuits off',
           default: false,
           description: 'Other Signal K apps switch with a PUT and cannot ask "are you sure?". Unticked, an off from them is refused with a message; the circuit can still be turned off from the webapp or a CZone keypad.'
+        },
+        bridges: {
+          type: 'array',
+          title: 'Third-party switches',
+          description: 'CZone circuits (normally virtual circuits added for the purpose) linked to a switch that is not on the CZone network. Set up in the configuration panel.',
+          default: [],
+          items: {
+            type: 'object',
+            properties: {
+              circuit: { type: 'string', title: 'CZone circuit' },
+              target: { type: 'string', title: 'Linked to', enum: ['victron', 'shelly'], enumNames: ['A Victron output (through the GX)', 'A Shelly (directly, by IP address)'] },
+              output: { type: 'string', title: 'Victron output (service#id)' },
+              label: { type: 'string', title: 'Name' },
+              host: { type: 'string', title: 'Shelly IP address' },
+              channel: { type: 'number', title: 'Shelly channel', default: 0 }
+            }
+          }
         }
       }
     }),
@@ -1245,6 +1349,7 @@ module.exports = function (app) {
         log
       })
       trends.start()
+      startBridge()
 
       const ready = (reason = 'nmea2000OutAvailable event') => {
         nmeaReady = true
@@ -1320,6 +1425,8 @@ module.exports = function (app) {
       monitoringRuntime = null
       if (trends) trends.stop()
       trends = null
+      bridge.stop()
+      closeBridgeBus()
       reassembler = null
       configFastPacket = null
       clearConfigTransfer()
@@ -1327,6 +1434,8 @@ module.exports = function (app) {
       mapping = null
       runtimeState.clear()
       publishedCircuitValues.clear()
+      switchInputs = []
+      inputState = new Map()
       // Signal K removes PUT handlers when the plugin stops. The plugin
       // factory can be reused on a subsequent enable, so allow start() to
       // register the handlers again instead of treating the stale paths as
@@ -1335,6 +1444,22 @@ module.exports = function (app) {
     },
 
     registerWithRouter: router => {
+      router.get('/inputs', (_req, res) => {
+        res.json({
+          inputs: switchInputs.map(i => ({
+            name: i.name,
+            path: i.path,
+            module: i.module,
+            input: i.input,
+            wiring: i.wiring || null,
+            moduleType: i.decoded ? inputs.LAYOUT[i.moduleKind].name : null,
+            decoded: i.decoded,
+            state: inputState.get(i.path).state,
+            since: inputState.get(i.path).since
+          }))
+        })
+      })
+
       router.get('/status', (_req, res) => {
         res.json({
           sendingEnabled: settings.allowCzoneWrite === true,
@@ -1417,6 +1542,21 @@ module.exports = function (app) {
         })
       })
 
+      // Third-party switches: link status, the GX's outputs, a Shelly test.
+      router.get('/bridge/status', (_req, res) => res.json({ links: bridge.status() }))
+      router.get('/bridge/outputs', (_req, res) => {
+        bridgeDrivers.victron.list()
+          .then(outputs => res.json({ available: true, outputs }))
+          .catch(err => res.json({ available: false, outputs: [], detail: `No Victron GX found (${err.message})` }))
+      })
+      router.get('/bridge/shelly', (req, res) => {
+        const host = String((req.query && req.query.host) || '').trim()
+        if (!/^[\w.-]+(:\d{1,5})?$/.test(host)) return res.status(400).json({ ok: false, detail: 'Give the Shelly\'s IP address' })
+        bridgeDrivers.shelly.status({ host, channel: Number(req.query.channel) || 0 })
+          .then(st => res.json({ ok: typeof st.output === 'boolean', output: st.output, power: st.apower, voltage: st.voltage }))
+          .catch(err => res.json({ ok: false, detail: err.message }))
+      })
+
       router.get('/configuration', (_req, res) => {
         res.json({
           source: settings.configurationSource || 'installedZcf',
@@ -1427,7 +1567,10 @@ module.exports = function (app) {
           networkRead: lastNetworkConfig ? { ...lastNetworkConfig, blocks: undefined } : null,
           nmeaReady,
           // The circuits offered under "Confirm before turning off".
-          circuitNames: confirmOffLib.choices({}, mapping ? mapping.circuits : []).map(n => n.value)
+          circuitNames: confirmOffLib.choices({}, mapping ? mapping.circuits : []).map(n => n.value),
+          // Every circuit, for linking a third-party switch (a virtual circuit
+          // added for one may not be listed in the webapp).
+          allCircuitNames: mapping ? mapping.circuits.map(c => c.name).sort((a, b) => a.localeCompare(b)) : []
         })
       })
 
@@ -1455,11 +1598,9 @@ module.exports = function (app) {
           fs.copyFileSync(source, temp)
           const next = zcf.load(temp)
           try { fs.unlinkSync(temp) } catch (_) {}
-          const newSettings = {
-            allowCzoneWrite: settings.allowCzoneWrite === true,
-            configurationSource: 'networkCache',
-            networkConfigFile: filename
-          }
+          // Only the configuration source changes; every other setting (confirm
+          // before on/off, trends, third-party switches, …) is kept.
+          const newSettings = { ...settings, configurationSource: 'networkCache', networkConfigFile: filename }
           const restartResult = await saveAndRestart(newSettings)
           res.json({ ok: true, file: filename, bytes: next.fileSize, vesselName: next.vesselName || null, configuration: newSettings, restartRequested: restartResult.restartRequested })
         } catch (err) { res.status(400).json({ ok: false, error: err.message }) }
@@ -1487,11 +1628,9 @@ module.exports = function (app) {
                 savedAt: new Date().toISOString()
               }, null, 2))
             } catch (_) {}
-            const newSettings = {
-              allowCzoneWrite: settings.allowCzoneWrite === true,
-              configurationSource: 'installedZcf',
-              networkConfigFile: ''
-            }
+            // Only the configuration source changes; every other setting (confirm
+            // before on/off, trends, third-party switches, …) is kept.
+            const newSettings = { ...settings, configurationSource: 'installedZcf', networkConfigFile: '' }
             const restartResult = await saveAndRestart(newSettings)
             res.json({
               ok: true,
@@ -1592,5 +1731,7 @@ module.exports = function (app) {
     }
   }
 
+  // For tests: run one bridge poll now instead of waiting for its timer.
+  Object.defineProperty(plugin, '_bridgePoll', { value: () => bridge.poll(), enumerable: false })
   return plugin
 }

package/lib/bridge/index.js

@@ -0,0 +1,226 @@
+'use strict'
+
+// Third-party switches driven from CZone.
+//
+// A CZone circuit (normally a virtual circuit added in the CZone configuration
+// for the purpose, with no output of its own) is linked to a switch that is not
+// on the CZone network: a Victron switchable output (a Shelly added to the GX,
+// a GX relay, ...) or a Shelly reached directly on the network.
+//
+//   CZone circuit changes (display, keypad, webapp)  -> the switch follows
+//   the switch changes (Victron pane, VRM, its app)  -> the CZone circuit follows
+//
+// The CZone side needs nothing new: a virtual circuit is held by a CZone module
+// like any other circuit (on the bench, the Output Interface reports it as
+// channel 6 in its status message), and the plugin already reads that state and
+// can send it. Only the switch side differs, in a driver:
+//
+//   driver.read(entry)  -> Promise<true|false>
+//   driver.write(entry, on) -> Promise
+//
+// Rules, so the two sides never fight:
+//   - a side is only acted on when it changes, and only if the other side
+//     differs;
+//   - our own change coming back is recognised and not passed on again;
+//   - at start (or when a side is first seen) nothing is switched: if the two
+//     sides differ the link says "out of step" and waits for the next real
+//     change on either side. (It used to take the switch as right, but a GX
+//     relay comes back off after a reboot, and a link to Instruments then
+//     turned Instruments off: Compass Rose, 15 Oct 2026.);
+//   - a change the host refuses for good (err.permanent: a circuit that asks
+//     before turning off) is reported and not tried again;
+//   - a change one side could not take (switch unreachable or refusing,
+//     NMEA 2000 sending off or not ready yet) is kept and retried every
+//     RETRY_MS until it is taken or that side is changed some other way.
+//
+// Self-contained (no CZone or Signal K code here) so it can move to another
+// plugin as it is: give it readCircuit/writeCircuit and the drivers.
+
+const POLL_MS = 2000
+const SETTLE_MS = 6000
+const RETRY_MS = 15000
+const OUT_OF_STEP = 'Out of step at start: nothing switched; the next change on either side brings them together'
+
+function createBridge ({
+  log = () => {},
+  readCircuit = () => undefined, // name -> true | false | undefined (not known yet)
+  writeCircuit = () => { throw new Error('No CZone writer') }, // (name, on)
+  drivers = {},
+  now = () => Date.now(),
+  pollMs = POLL_MS,
+  settleMs = SETTLE_MS,
+  retryMs = RETRY_MS
+} = {}) {
+  let links = []
+  let timer = null
+  let polling = false
+
+  function describe (entry) {
+    const d = drivers[entry.target]
+    return d && typeof d.describe === 'function' ? d.describe(entry) : `${entry.target}`
+  }
+
+  function start (entries = []) {
+    stop()
+    links = entries
+      .filter(e => e && e.circuit && drivers[e.target])
+      .map(entry => ({ entry, driver: drivers[entry.target], cz: undefined, dev: undefined, want: undefined, wantCz: undefined, retryAt: 0, pending: null, error: null, last: null, at: null }))
+    if (!links.length) return
+    log(`Bridge: ${links.map(l => `"${l.entry.circuit}" <-> ${describe(l.entry)}`).join('; ')}`)
+    timer = setInterval(() => { poll().catch(() => {}) }, pollMs)
+    if (timer.unref) timer.unref()
+    poll().catch(() => {})
+  }
+
+  function stop () {
+    if (timer) clearInterval(timer)
+    timer = null
+    links = []
+  }
+
+  function note (link, text) {
+    link.last = text
+    link.at = now()
+    log(`Bridge "${link.entry.circuit}": ${text}`)
+  }
+
+  async function toDevice (link, on, why) {
+    link.pending = { side: 'device', value: on, until: now() + settleMs }
+    note(link, `${why}: switching ${describe(link.entry)} ${on ? 'ON' : 'OFF'}`)
+    try {
+      await link.driver.write(link.entry, on)
+      link.error = null
+    } catch (err) {
+      link.pending = null
+      link.retryAt = now() + retryMs // link.want is kept: tried again later
+      link.error = `Could not switch ${describe(link.entry)}: ${err.message}`
+      log(`Bridge "${link.entry.circuit}": ${link.error}`)
+    }
+  }
+
+  function toCzone (link, on, why) {
+    link.pending = { side: 'czone', value: on, until: now() + settleMs }
+    note(link, `${why}: switching CZone circuit ${on ? 'ON' : 'OFF'}`)
+    try {
+      writeCircuit(link.entry.circuit, on)
+      link.error = null
+    } catch (err) {
+      link.pending = null
+      link.wantCz = err && err.permanent ? undefined : on
+      link.retryAt = now() + retryMs
+      link.error = `Could not switch the CZone circuit: ${err.message}`
+      log(`Bridge "${link.entry.circuit}": ${link.error}`)
+    }
+  }
+
+  function seeCircuit (link, on) {
+    if (on !== true && on !== false) return
+    const before = link.cz
+    link.cz = on
+    if (before === undefined) {
+      if (link.dev !== undefined && link.dev !== on && link.want === undefined) note(link, OUT_OF_STEP)
+      return
+    }
+    if (before === on) return
+    if (link.pending && link.pending.side === 'czone' && link.pending.value === on) { link.pending = null; link.wantCz = undefined; return } // our own change
+    link.wantCz = undefined
+    link.want = on
+    link.retryAt = 0
+    if (link.dev === on) link.want = undefined
+    else if (link.dev !== undefined) toDevice(link, on, 'CZone circuit switched')
+    // switch not seen yet: taken when it is (see poll)
+  }
+
+  function seeDevice (link, on) {
+    if (on !== true && on !== false) return
+    const before = link.dev
+    link.dev = on
+    if (before === undefined) {
+      if (link.want === undefined && link.cz !== undefined && link.cz !== on) note(link, OUT_OF_STEP)
+      return
+    }
+    if (before === on) return
+    if (link.pending && link.pending.side === 'device' && link.pending.value === on) { link.pending = null; link.want = undefined; return } // our own change
+    link.want = undefined
+    if (link.cz !== undefined && link.cz !== on) toCzone(link, on, 'Switch changed elsewhere')
+  }
+
+  // From the plugin's CZone state decoding: called as each status arrives, so
+  // a display press reaches the switch without waiting for the next poll.
+  function onCircuit (name, on) {
+    for (const link of links) if (link.entry.circuit === name) seeCircuit(link, on)
+  }
+
+  async function poll () {
+    if (polling) return
+    polling = true
+    try {
+      for (const link of links) {
+        if (link.pending && now() > link.pending.until) {
+          note(link, `No confirmation from the ${link.pending.side === 'czone' ? 'CZone circuit' : 'switch'}`)
+          link.pending = null
+          link.retryAt = now() + retryMs // anything still wanted waits its turn
+        }
+        seeCircuit(link, readCircuit(link.entry.circuit))
+        // A switch change the CZone circuit has not taken yet.
+        if (link.wantCz !== undefined && !link.pending) {
+          if (link.cz === link.wantCz) link.wantCz = undefined
+          else if (now() >= link.retryAt) toCzone(link, link.wantCz, 'Switch changed (trying the CZone circuit again)')
+        }
+        try {
+          const on = await link.driver.read(link.entry)
+          if (link.error && /^Not reachable/.test(link.error)) link.error = null
+          seeDevice(link, on)
+          // A CZone change the switch has not taken yet.
+          if (link.want !== undefined && !link.pending) {
+            if (link.dev === link.want) link.want = undefined
+            else if (now() >= link.retryAt) await toDevice(link, link.want, 'CZone circuit switched (trying again)')
+          }
+        } catch (err) {
+          if (!link.error || /^Not reachable/.test(link.error)) link.error = `Not reachable: ${err.message}`
+        }
+      }
+    } finally {
+      polling = false
+    }
+  }
+
+  function status () {
+    return links.map(l => ({
+      circuit: l.entry.circuit,
+      target: describe(l.entry),
+      czone: l.cz === undefined ? null : l.cz,
+      device: l.dev === undefined ? null : l.dev,
+      inStep: l.cz !== undefined && l.dev !== undefined ? l.cz === l.dev : null,
+      pending: l.pending ? { side: l.pending.side, value: l.pending.value } : null,
+      error: l.error,
+      last: l.last,
+      at: l.at
+    }))
+  }
+
+  const circuits = () => new Set(links.map(l => l.entry.circuit))
+
+  return { start, stop, onCircuit, poll, status, circuits }
+}
+
+// Saved settings -> bridge entries. Bad or incomplete rows are dropped.
+//   { circuit, target: 'victron', output: '<service>#<id>' }
+//   { circuit, target: 'shelly', host: '192.168.1.204', channel: 0 }
+function bridgeEntries (list) {
+  const out = []
+  for (const row of Array.isArray(list) ? list : []) {
+    if (!row || typeof row.circuit !== 'string' || !row.circuit.trim()) continue
+    const circuit = row.circuit.trim()
+    if (row.target === 'victron' && typeof row.output === 'string' && /^com\.victronenergy\.[\w.]+#[\w-]+$/.test(row.output)) {
+      const [service, id] = row.output.split('#')
+      out.push({ circuit, target: 'victron', service, output: id, label: row.label || '' })
+    } else if (row.target === 'shelly' && typeof row.host === 'string' && /^[\w.-]+(:\d{1,5})?$/.test(row.host.trim())) {
+      const channel = Number.isInteger(Number(row.channel)) && Number(row.channel) >= 0 ? Number(row.channel) : 0
+      out.push({ circuit, target: 'shelly', host: row.host.trim(), channel, label: row.label || '' })
+    }
+  }
+  return out
+}
+
+module.exports = { createBridge, bridgeEntries, POLL_MS, SETTLE_MS, RETRY_MS }