Document the J1939 to NMEA 2000 to Signal K engine chain - #683
Open
dirkwa wants to merge 2 commits into
Open
Conversation
added 2 commits
August 6, 2026 17:31
Marine engines from Volvo Penta, Yanmar, Cummins and others speak SAE J1939 rather than NMEA 2000, and reach Signal K through a gateway that translates a subset of J1939 parameters into the NMEA 2000 engine PGNs. Which J1939 parameter becomes which NMEA 2000 field is not recorded anywhere in the specification, so implementers keep rediscovering it. Adds an appendix covering that chain: the SPN to NMEA 2000 to Signal K path table for the parameters that survive a gateway, the resolution changes across the boundary, the engine alarm bit mapping, and the parameters that have no NMEA 2000 equivalent and are therefore reachable only by a server reading J1939 directly. Two practical traps are called out. Engine hours is transmitted in 0.05 hour steps, so second-level changes in runTime behind a gateway are conversion artefacts rather than measurements; and percent torque carries a -125 % offset that, if missed, reads as full load on an idling engine. This is reference material only - no schema change. Tested: npm test (207 passing); verified every Signal K path named in the appendix exists in schemas/groups/propulsion.json, and every NMEA 2000 resolution quoted against the canboat PGN database.
Verification against the J1939DA parameter registry corrected three transmission parameter names: SPN 123 is Transmission Clutch 1 Pressure, 127 is Transmission 1 Oil Pressure and 177 is Transmission 1 Oil Temperature 1. Also documents the gear offset, which belongs alongside the percent torque trap already covered. SPN 523 carries the same -125 offset, and after biasing the value is the gear number directly - reverse negative, 0 neutral. Missing it makes every gear read as roughly 125. The selected and current range fields travel as two-character ASCII (D, N, R) and are usually the more useful value on a marine transmission with no multi-speed gearbox. Tested: npm test (207 passing).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Marine engines from Volvo Penta, Yanmar, Cummins, Scania and others do not speak NMEA 2000 natively — they speak SAE J1939, and reach Signal K through a gateway that translates a subset of J1939 parameters into the NMEA 2000 engine PGNs. Which J1939 parameter becomes which NMEA 2000 field is written down nowhere in this specification, so implementers keep rediscovering it.
This adds an appendix covering that chain end to end:
propulsion.<id>.*table for the parameters that survive a gatewayTwo traps are worth calling out here because they produce plausible-looking wrong data rather than obvious errors. Engine hours is transmitted in 0.05 hour steps — three minutes — so a
runTimevalue that changes by one second behind a gateway is reporting a conversion artefact, not a measurement; consumers computing rates from it should not assume second-level truth. And percent torque carries a -125 % offset that, if missed, reads as full load on an idling engine.The appendix also notes that some SPNs collapse onto a single NMEA 2000 field — SPN 167, 168 and 158 all land in
alternatorVoltage— so that value is not guaranteed to be alternator output on every installation.This is reference material only. No schema change, no new keys. Where a J1939 parameter has real value and no Signal K path yet, the text points at the normal proposal route rather than inventing a private key.
Follows on from #682, which added
propulsion.<id>.diagnosticsfor the structured DM1 fault codes; this documents the measurement side of the same chain. Related: the open J1939 PGN database in canboat/canboat#822.Tested:
npm test(207 passing). Verified every Signal K path named in the appendix exists inschemas/groups/propulsion.json, and every NMEA 2000 resolution quoted against the canboat PGN database — one figure was corrected in the process (oil temperature is 0.1 K in NMEA 2000, coarser than J1939's 0.03125 K, not finer as I first wrote).