signalk-venus-engine-state

A Signal K server plugin that converts Victron Venus OS (Cerbo GX) digital inputs — configured as type Alarm and published by signalk-venus-plugin as electrical.venus-input.<name>.state with values Open / Close — into standard propulsion state paths:

propulsion.<id>.state = "started" | "stopped"

Optionally, it can also accumulate engine run time in propulsion.<id>.runTime (seconds), persisted across server restarts.

Why

Many boats wire an engine's oil-pressure switch (or an alternator W-terminal, tachometer relay, etc.) into a Cerbo GX digital input. Venus OS reports the raw contact state (Open/Close) but there is no built-in translation to Signal K's standard propulsion.*.state path used by instruments, autopilots, and logging plugins. This plugin bridges that gap with a simple, per-engine mapping.

Installation

From the Signal K App Store (recommended)

1. Open your Signal K server admin UI.
2. Go to Appstore.
3. Search for signalk-venus-engine-state and click Install.

From npm

cd ~/.signalk
npm install signalk-venus-engine-state

Then restart your Signal K server.

Requirements

• A running signalk-venus-plugin connection to a Venus OS device (Cerbo GX, etc.).
• One or more Venus digital inputs configured as type Alarm, wired to a source that reflects whether the engine is running.

Configuration

In the Signal K admin UI, open the plugin configuration page and add one entry per engine under Digital input -> engine mappings:

| Field | Description | Example | |---|---|---| | Source path | The Venus digital input path to watch | electrical.venus-input.portEngine.state | | Target path | The propulsion state path to write | propulsion.port.state | | Contact value when running | The raw value (Open, Close/Closed) that means the engine is running. Check the actual value in the Data Browser, since it depends on wiring and Venus' "invert" setting | Close | | Track run time | Also accumulate propulsion.<id>.runTime (in seconds), published every 60 s and persisted to disk | false | | Initial run time | Starting value for the run-time counter, in seconds (useful to seed an existing engine-hours count) | 0 |

The engine identifier used for runTime (propulsion.<id>.runTime) is derived from the second segment of the target path (e.g. propulsion.port.state -> propulsion.port.runTime).

Example configuration

{
  "mappings": [
    {
      "source": "electrical.venus-input.portEngine.state",
      "target": "propulsion.port.state",
      "runningValue": "Close",
      "trackRunTime": true,
      "initialRunTime": 0
    },
    {
      "source": "electrical.venus-input.stbdEngine.state",
      "target": "propulsion.stbd.state",
      "runningValue": "Close",
      "trackRunTime": true,
      "initialRunTime": 0
    }
  ]
}

Output

For each mapping, the plugin emits Signal K deltas:

• propulsion.<id>.state — "started" or "stopped", updated on every change of the source input.
• propulsion.<id>.runTime — cumulative seconds of run time, updated every 60 seconds while the engine is running (only if Track run time is enabled).

Web app

The plugin ships a small web app showing each engine's current state and run time (in hours), and letting you correct the run time (hour meter) — for example after replacing an engine. It's available at:

http://<your-server>/signalk-venus-engine-state/

and should also appear in the Signal K admin UI's Webapps list.

It's a standalone page (opening it navigates away from the admin UI), not an "embedded" webapp like signalk-logbook. Signal K's embedded-webapp mechanism (signalk-embeddable-webapp keyword) requires a React component built with Webpack Module Federation, which would mean adding React/Webpack/Babel as dependencies and a build step — at odds with this plugin's zero-dependency, zero-build-step design (see CLAUDE.md). The page does link back to /admin/ for convenience.

License

MIT © Cedric RICARD