OBD2 to Signal K

odb2-to-signalk is a Signal K server plugin for ELM327-compatible OBD-II adapters. It can connect over a local serial device (including an RFCOMM device created from a paired Bluetooth adapter) or TCP, decode a focused set of Mode 01 PIDs, convert values to Signal K SI units, and publish them as deltas. Its runtime plugin ID remains obd2-signalk for compatibility with existing Signal K configuration and API routes.

The 2.x line modernizes the original plugin for current Signal K plugin-registry expectations: safe default activation, a JSON Schema with defaults, standards-aligned propulsion paths, deterministic lifecycle cleanup, dependency-free tests using node:test, AppStore metadata, release notes, screenshots, and CI guidance.

Quick start

1. Install the plugin from the Signal K AppStore or link it into a development server.
2. Open Server → Plugin Config → OBD2 to Signal K.
3. Select Enable OBD-II connection.
4. Choose serial or tcp and enter the adapter settings.
5. Save the configuration and inspect the Data Browser under propulsion.<engineId>.

The plugin is intentionally idle with its default configuration. This lets the Signal K server and plugin registry load, activate, stop, and restart it safely when no OBD-II hardware is present.

Supported data

The plugin currently decodes vehicle speed, engine RPM, coolant temperature, fuel-system state, calculated engine load, intake manifold absolute pressure, intake air temperature, throttle position, distance travelled with MIL active, engine runtime, ambient air temperature, fuel type, and fuel level. Only values with an appropriate Signal K mapping are publishable. Each mappable PID can be enabled/disabled independently and mapped to either its canonical default Signal K path or a user-defined path.

See docs/getting_started.md for installation and commissioning, docs/signalk_paths.md for units and paths, and docs/architecture.md for implementation details.

Per-PID mapping configuration

Every mappable OBD-II PID has independent configuration controls in the Signal K plugin settings: Activate PID, Use default Signal K mapping, and Custom Signal K path. Turn off the default-mapping switch to use a custom destination. Turn it back on at any time to restore the plugin's canonical Signal K mapping; the retained custom path is then ignored. Instance placeholders {engineId}, {fuelTankId}, and {batteryId} are supported in custom paths.

PID 0D vehicle speed and PID A6 odometer remain disabled by default because their automotive semantics can differ from marine speedThroughWater and navigation.log.

Development

Requires Node.js 20 or later.

npm install --ignore-scripts
npm test
npm run coverage
npm run lint
npm pack --dry-run
npm audit

Before publishing, verify the package contains the AppStore icon and screenshots and that the Signal K plugin CI workflow is green.

License

ISC. See LICENSE.

OBD-II coverage

Version 2.2.0 covers the standardized Mode 01 measurements that have a defensible mapping into the standard Signal K vessel schema, including propulsion, fuel, environment, electrical battery, tank and navigation-log values. It also derives boost pressure correctly from manifold absolute and barometric pressure. Diagnostic-only/emissions-control values are not mislabeled as vessel measurements. See docs/signalk_paths.md for the complete mapping matrix and the deliberate exclusions.

Companion WebApp

Version 2.3.0 includes a read-only WebApp that visualizes the live OBD-II decoding and Signal K mapping pipeline. It shows connection state, enabled and dependency-polled PIDs, raw adapter responses, decoded values, default/custom mapping selection, effective Signal K paths, mapped values, and last-seen times. Open it from the Signal K WebApps page after installation. See docs/webapp.md for details.