Consultation on a change to NMEA2000 decoding/encoding

[antipole2]

The NMEA2000 object has the ability to decode NMEA2000 binary data into a JavaScript object.
It can also encode a JavaScript object into NMEA2000 binary.

Now I have gained experience with this, I am having second thoughts about how this process handles Enums.
I am considering changing this in a way that would change some JavaScript objects.

Background

Some fields in NMEA2000 data are codes rather than measured values.
Examples:

• Type of fix
• Wind angle type
• Manufacturer code

The PGN descriptors mostly contain look-up tables and when decoding, I look up the given numeric code and then return the enumerated value.
Some PGNs do not contain the look-up table, and you need to consult elsewhere to interpret it e.g. manufacturer codes.

As it now is

Consider PGN 130306 Wind.
The fourth field is the wind reference type, and its look-up table is:

"EnumValues": [
        {
					"name": "True (ground referenced to North)",
					"value": 0
				},
				{
					"name": "Magnetic (ground referenced to Magnetic North)",
					"value": 1
				},
				{
					"name": "Apparent",
					"value": 2
				},
				{
					"name": "True (boat referenced)",
					"value": 3
				},
				{
					"name": "True (water referenced)",
					"value": 4
				}

A typical JavaScript object for PGN 130306 might be

{
	"PGN": 130306,
	"id": "windData",
	"description": "Wind Data",
	"timestamp": 320367580,
	"priority": 255,
	"desination": 255,
	"origin": 255,
	"windSpeed": "15.0000000",
	"windAngle": "3.1420000",
	"reference": "True (boat referenced)"
}

The reference has been converted from 3 to its name.

For PGNs for which there is no look-up table, reference is set to its numeric value.

When encoding a JavaScript object into binary data, the method accepts either a numeric value or a string. A string must exactly match a name in the table.

It is when the object is used that this is unwieldy.
Consider the converter to NMEA0182 function in VDR2

angle = obj.windAngle * 57.29578;	// angle from radians to degrees
speed = obj.windSpeed * 1.943844;	// speed from m/s to knots
switch (obj.reference){
	case "Apparent":
		ref = "R"; break;
	case "True (boat referenced)":
		ref = "T"; break;
	default: throw("PGN130306 has unsupported reference " + obj.reference + " please report this");
		}
sentence = "$" + sender +"MWV," +angle.toFixed(2) + "," + ref + "," + speed.toFixed(2) + ",K,A";

Proposed change

I could simply return the value, but that is not meaningful in itself and would require the user to look up its meaning elsewhere or write code to extract the name from the descriptor.

More elegantly, I could return a structure containing both the value and its name (when available). So the example above becomes

{
	"PGN": 130306,
	"id": "windData",
	"description": "Wind Data",
	"timestamp": 320367580,
	"priority": 255,
	"desination": 255,
	"origin": 255,
	"windSpeed": "15.0000000",
	"windAngle": "3.1420000",
	"reference": {
		"value": 3,
		"name": "True (boat referenced)"
		}
}

For encoding, just the value would be used as encoding from the name could give errors if there is not a perfect match.

I regard the NMEA2000 object as at beta status and subject to change.
I am consulting here as this change will require adjustment of scripts using enumerated data.

The change to implement this proposal is small and already proven.
A replacement file could be installed on your system without a plugin update.
It would be incorporated in the next plugin update, which, unless necessary earlier, will not be before the autumn 2024 after my sailing season.

Any opinions? Preferred solutions? Poll remains open until 19th April.

[rgleason]

Tony, I haven't used it enough to comment intelligently. Sorry. Too busy with the manual.

[antipole2]

As no one is commenting on this proposal, I am taking the decision now to adopt this change and implement in the plugin v3.0.2.