signalk-nightswimming-battery-guard

Lightweight SignalK plugin for the sailing yacht Nightswimming (Italia Yachts 13.98 / Cerbo GX / Victron MultiPlus). Replaces the Node-RED battery management flows with a single compiled TypeScript plugin, saving ~100 MB heap on the Cerbo GX.

Rules

Rule 1 — Solar MPPT protection (relay-gated)

Active only while Cerbo internal relay 2 is ON. Monitors electrical.solar.278.modeNumber and electrical.solar.279.modeNumber and flips them via SignalK PUT:

| Condition | Action | |-----------|--------| | Relay ON + SOC > solarDisableThreshold + MPPTs currently enabled | PUT modeNumber=4 (Off) on both MPPTs | | Relay ON + SOC < solarEnableThreshold + MPPTs currently disabled | PUT modeNumber=1 (On) on both MPPTs | | Relay OFF + MPPTs disabled by this plugin | PUT modeNumber=1 (On) on both MPPTs, then reset internal state | | Relay OFF + MPPTs not disabled by this plugin | No action |

Relay OFF restore (v0.2.0): when the relay transitions from ON to OFF while the plugin had previously disabled the MPPTs, the plugin restores them to ON. This handles the scenario where a user turns the relay off while the MPPTs were suppressed. After the restore PUTs, the internal solarEnabled flag is reset to null (unknown) — it will re-initialize from the next MPPT delta, so the plugin never assumes hardware state it didn't set.

Rule 2 — Inverter safety cutoff (always active)

Always active, independent of relay state.

| Condition | Action | |-----------|--------| | SOC < inverterCutoffThreshold | PUT modeNumber=4 (Off) on MultiPlus | | SOC > inverterCutoffThreshold + 5% (re-arm margin) | Rule re-arms for next trigger |

Configuration

| Field | Default | Description | |-------|---------|-------------| | solarDisableThreshold | 0.70 | Disable MPPTs when SOC exceeds this ratio (0–1). Set to 1.0 or above to effectively disable this rule (logged at startup). | | solarEnableThreshold | 0.55 | Re-enable MPPTs when SOC drops below this ratio (0–1). | | inverterCutoffThreshold | 0.20 | Cut MultiPlus inverter when SOC drops below this ratio (0–1). | | signalkPort | 3000 | Local SignalK server port (default on Cerbo GX). | | signalkToken | "" | Bearer token for PUT requests — leave empty if SignalK auth is not configured. | | signalkProtocol | https | Protocol used to reach the local SignalK server (http or https). The Cerbo GX is HTTPS-only. | | rejectUnauthorized | false | Only applies with https. Leave false to accept the Cerbo GX self-signed cert (CN=venus.local); set true to enforce CA-verified certificates. |

Disabling the solar rule

Set solarDisableThreshold to 1.0 or above. Since SOC can never exceed 1.0 (100%), the disable condition (soc > threshold) will never be true. The plugin logs "solar disable rule effectively disabled (threshold >= 1.0)" at startup.

There is no hard cap on solarDisableThreshold or solarEnableThreshold in the schema — the UI will accept any value ≥ 0.

SignalK paths

| Path | Role | |------|------| | electrical.batteries.277.capacity.stateOfCharge | SOC input (0–1) | | electrical.switches.gx.gxInternalRelay2.state | Relay 2 gate for solar rule | | electrical.solar.278.modeNumber | MPPT 278 — read (init) + PUT | | electrical.solar.279.modeNumber | MPPT 279 — read (init) + PUT | | electrical.chargers.276.modeNumber | MultiPlus — PUT only |

modeNumber values confirmed on Cerbo GX with supportsPut: true:

• MPPT: 1 = On, 4 = Off
• MultiPlus: 2 = Inverter only, 3 = On (charge+invert), 4 = Off

Installation

Copy the plugin directory to your SignalK node_modules or publish via npm. After restarting SignalK, configure the thresholds in the plugin settings panel.

npm run build   # compile TypeScript → dist/
npm test        # run unit tests (vitest)

Changelog

See CHANGELOG.md.