CANboat version v9.2.0 2009-2026, Kees Verruijt, Harlingen, The Netherlands. For more information see https://github.com/canboat/canboat This file is part of CANboat. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. The outer container has the historic name PGNDefinitions. Historic, because it now also contains other complex types that are referred to from the PGNs. Wherever possible we use a straight sequence, which guarantees that the children elements are always in the same order. This has as children some basic string elements followed by the different complex types that we use to define the PGNs: Physical Quantities, Field Types, and five types of enumerations: Missing, Lookup, LookupIndirect, LookupBit and LookupFieldtype. The last element is the list of PGNs themselves. This is the version of the schema that the XML instance document uses. The version of the schema is found in the version attribute in the xs:schema top-level element. The protocol on the CAN bus these PGNs are carried on. NMEA 2000 (docs/canboat.xml) and SAE J1939 (docs/canboat-j1939.xml) share the ISO 11783 frame header, address claim and transport protocol but define different PGNs, and only NMEA 2000 has fast-packet framing. Quick PCS (docs/canboat-quick.xml) has 11-bit CAN identifiers instead: there the PGN is the identifier, a message type, with no priority, source or destination. Absent in documents older than schema 2.7.0, which are all NMEA 2000. pseudo (docs/canboat-pseudo.xml, since schema 2.8.0) is not a bus: it holds canboat's pseudo-PGNs, 0x40000 and up, which no other document has. They are records of a gateway (Actisense BEM messages, an NMEA 2000 gateway's network status) and of canboat itself. They never appear on a bus, but they do in canboat's output streams, whatever the protocol. The LookupEnumeration is a list of EnumPair elements with a name. This allows the PGN field to refer to this when it contains a lookup field, for instance 0 = No, 1 = Yes. The special null-like values for Unknown and Error are not placed in this list. The LookupEnumeration is a list of EnumTriplet elements with a name. This allows the PGN field to refer to this when it contains a lookup field. Indirect enumerations use two values to define a specific name. The first value is taken from another field. The second value is the value for this field. The special null-like values for Unknown and Error are not placed in this list. The LookupBitEnumeration is a list of BitPair elements with a name. This allows the PGN field to refer to this when it contains a lookup field, for instance bit 0 = Too Hot, bit 1 = Too Cold. LookupBitEnumeration fields do not have special null-like values. When the FieldType is LOOKUP, the field value has meaning derived from the lookup table mentioned here. When the FieldType is INDIRECT_LOOKUP, the field value has meaning derived from the lookup table mentioned here. It requires an additional first value derived from the field indicated by LookupIndirectEnumerationField.. When the FieldType is INDIRECT_LOOKUP, the field value has meaning that also depends on the value of the field mentioned by order in this element. When the FieldType is BITLOOKUP, the field value has to be interpreted as a number of bits, with each bit forming a flag whose meaning is given in the lookup table. The LookupFieldTypeEnumeration is a list of EnumFieldType elements with a name. This allows the PGN field to refer to this when it contains a lookup field, for instance 0 = No, 1 = Yes. The special null-like values for Unknown and Error are not placed in this list. This is different from a LookupEnumeration in that it also defines a set of field attributes for a following variable field. To explain numeric types more easily the concept of a PhysicalQuantity is introduced. Given the few public snippets of the NMEA PGN definitions it looks as if they do not explicitly have such a concept, but it seems a nice way of grouping similar fields. If a field represents a value with a particular unit, like 'A' for Ampere, this refers to the concept of ELECTRICAL_CURRENT -- at least that is how we see it. The PhysicalQuantity is mostly used for 'explanation', it is not fundamental to interpreting the PGN field values. There are only a few, really basic, field types. In the C code of the CANBoat analyzer, these map perfectly onto C functions that extract the bits from the PGN and emit them in "human" or "JSON" form. Explanation of how the field type is encoded. field type. Optional external reference explaining the encoding of this field type. The number of bits that this field takes up in the PGN, if this is fixed for all fields. Present in the FieldType when it has a typical unit. Present in the FieldType when all fields have a guaranteed sign. True if the fields of this FieldType all have a variable length in bits. How a field of this type signals "data not available" (and, for integers, out-of-range and reserved). One of: TopOfRange - the top 1 to 3 raw integer values are reserved as Unknown (most positive), OutOfRange (max-1) and Reserved (max-2); the count depends on the bit width, so the actual reserved values are given per field as UnknownValue, OutOfRangeValue and ReservedValue. For LOOKUP fields a value that the enumeration names explicitly is a real value and is not reserved, lowering the count. EmptyString - an empty string (after trimming end-of-string bytes such as 0xff, 0x00 and '@') marks the field as unavailable. NaN - the IEEE-754 Not-a-Number value. Variable - the convention depends on the data type that is resolved at run time through the companion DYNAMIC_FIELD_KEY field. None - the field has no unavailable encoding (an identifier such as PGN or MMSI, filler such as RESERVED, or a structured field). The Field is the core definition, as a PGN is usually just a bunch of fields in sequence. The sequence in which the field is ordered within the PGN. Starts at 1. In theory there could be 233 * 8 fields, but in practice there are no more than 29. A generated string representing the field name; e.g. with spaces removed and in camelCase. The field name. An extra explanation. SAE J1939 only: the Suspect Parameter Number J1939-71 gives this value. It identifies the value itself, whichever PGN carries it, and is what J1939 documentation and diagnostic trouble codes (DM1) refer to. Absent on NMEA 2000 fields. The Id of an earlier field in the same record (and the same repeating set) whose value this field continues: this field's bits are that value's high bits, above the earlier field's own BitLength. The field keeps its own place in the layout. J1939-73 splits a trouble code's 19-bit SPN this way, around the FMI. A decoder that does not know this element sees two plain numbers; one that does shows the earlier field with the joined value (and its lookup name), and this field not at all. Only on a DECIMAL field, together with TrailingZeroIsDigitValue: the Order of an earlier unsigned integer field without resolution or offset, at a fixed position (nothing of variable length, no proprietary field and no repeating set before it), so its raw value is compared. A DECIMAL with an odd number of digits is sent with a 0 added at the end, which a decoder drops: a DSC call sends a 9-digit MMSI as ten digits. When the field with this Order holds TrailingZeroIsDigitValue, that last digit is part of the value instead and must be kept. PGN 129808's DSC Message Address is ten digits of geographical area when the DSC Format is 102. The raw value of the field named by TrailingZeroIsDigitField for which this DECIMAL keeps its last digit. This is present, and true, if the field has a variable length. For instance, most types of strings. These will then have a minimum length defined by how the string length is determined, but that is type dependent. The field may also have a different field that specifies how long this field is, in that case BitLengthField will be present. If present, the field is variable length and the number of bits is contained in the field whose order is indicated here. Until now the only known occurrences have the property that the length field immediately precedes the variable length field. If present, the field has a fixed length and this element gives the number of bits that the field is long. If present, the field is preceded by no other fields or only fixed length fields and the offset from the start of the PGN data can be pre-determined, and this element says how many bits from the start that this field is located. Some fields are not byte-aligned, and will contain a non-zero value for BitStart, indicating at which bit in the byte the field starts. Note that fields can span multiple bytes. In practice we have not seen fields that start at a non-zero BitStart and span more than 2 bytes. When a field contains this element, this field may or may not appear in the PGN depending on the condition. At this moment the only possible condition is if the early field in the same PGN named 'PGN' is manufacturer proprietary. Manufacturer proprietary PGNs do not have to have a unique PGN number, as each manufacturer is free to use all PGNs in the manufacturer proprietary ranges. To distinguish which PGN definition is the appropriate one, some PGNs contain Match values that must all match before this PGN definition is considered the right one. The unit that the PGN is defined in; these are generally, but not always, SI or SI like. Some manufacturer PGNs define angles in degrees instead of in radians, and some standardized fields use kWh instead of J. All number-y fields have a resolution, which tells you how the binary value must be interpreted vis-a-vis the physical quantity. For instance, angles are generally stored as 0.0001 radian, so a binary value of 0 means 0 radians, 1 means 0.0001 radian, 2 means 0.0002 radian, etc. All number-y fields have this element, and it reports whether the fields contains a signed or an unsigned value. Unsigned values are always in standard binary format, with the LSB representing the value 1, the 2nd bit the value 2, the 3rd bit the value 4, etc. Signed values are either in 2s complement, or in Excess K offset notation. If the latter, the Offset element is present. When the value is signed, but not in 2s complement, the value is in Excess K format and this element contains the (negative) offset that must be added to the unsigned binary number to end up with the appropriate signed value. It is in the field's own units, so it can have a fraction (J1939's -62.5 L fluid level deviation). An unsigned value can have an offset too: J1939's 8-bit temperature starts at -40 deg C, which is an Offset of 233.15 K. For a DYNAMIC_FIELD_LENGTH field: the number of non-value header bytes (for example a class byte and a data-type id) that sit between this length field and the value and are counted in this length. A decoder must subtract this from the length to obtain the byte count of the following DYNAMIC_FIELD_VALUE field. The minimal value that the field can represent, after conversion to a floating point value -- e.g. after the sign and offset and resolution have been applied. The minimal value that the field can represent, after conversion to a floating point value -- e.g. after the sign and offset and resolution have been applied. Note that this reserves space for the special values that can be present. For integer number fields: the raw (unscaled) value that signals "data not available". This is the most positive value the field can hold. For integer number fields of 4 bits and larger: the raw (unscaled) value that signals "out of range" (the most positive value minus one). For integer number fields of 8 bits and larger: the raw (unscaled) value that the NMEA 2000 standard reserves (the most positive value minus two). Fields always contain a field type. Character set to read this field's bytes as when they are not well-formed UTF-8. Only present on 8-bit string fields whose device is known to put some other charset on the wire; absent means Latin-1, which is what every string field uses by default. A reader should still try UTF-8 first and consult this only when that fails. RDS2 carries text as UTF-8, so a device that gains it will start sending valid UTF-8 in the same field and must keep decoding without a database change. RDS_G0 is the Basic RDS character set: IEC 62106 table E.1, published identically as the "Complete EBU Latin based repertoire" in ETSI TS 101 756 V1.6.1 (2014-05) annex C. Take it from V1.6.1, not from the V1.8.1 (2015-12) revision of that annex, and not from a third-party copy. V1.8.1 reassigns 36 of the 224 positions - the whole 0xA0..0xBF block, 0x24, and backslash, brace and bar - as a DAB-only extension that never reached RDS. The two agree on every accented letter common in a station name, so the mistake does not show up in casual testing. Fields that represent a physical quantity refer to one of the PhysicalQuantities. If Unit is present, so is PhysicalQuantity. When the FieldType is LOOKUP, the field value has meaning derived from the lookup table mentioned here. When the FieldType is INDIRECT_LOOKUP, the field value has meaning derived from the lookup table mentioned here. It requires an additional first value derived from the field indicated by LookupIndirectEnumerationField.. When the FieldType is INDIRECT_LOOKUP, the field value has meaning that also depends on the value of the field mentioned by order in this element. When the FieldType is BITLOOKUP, the field value has to be interpreted as a number of bits, with each bit forming a flag whose meaning is given in the lookup table. When the FieldType is LOOKUP_FIELDTYPE, the field value has meaning derived from the lookup table mentioned here. It also defines the field type of a following variable field. If present and set to true, this field serves as a component of the primary key for the PGN. It uniquely identifies records in conjunction with other key fields. Pure simplistic analyzers or software that just passes this data on can ignore this field. Software that stores data organised by source can store data indexed by all primary key fields. In other words: if a PGN repeats but it contains a different value in the primary key fields, it is for a different object. The prime example is AIS, where a different source MMSI means it is from a different ship. Documents the things that we do not know about this PGN yet. Whether the PGN is a Single frame or a Fast packet set of frames. When present and true, the PGN has been reverse engineered to such a level that we believe it is nearly complete; e.g. in all practical ways the PGN is usable in producing proper results. If this is not present, there will be a Missing element that explains what we think we don't know. When present and true, the PGN is a 'virtual' PGN used as a fallback mechanism to print unknown PGNs. The element will either be missing or contain true. Gives a list of MissingAttribute that we think we don't know. The length in bytes of the shortest payload that still decodes as this PGN. On a variable-length PGN (one with a repeating field set, or a field whose width is not known in advance) this is the only length published: the actual length depends on how often the set repeats. On a fixed-length PGN it appears next to Length, and then documents that shorter payloads occur on the wire: the trailing fields were added by a later NMEA 2000 version and devices built against the earlier layout still omit them. Such a payload ends on a field boundary, so every field it does contain decodes normally and the fields past MinLength are simply absent. The length in bytes of a complete payload, present only when the PGN has a fixed length. See MinLength for the shortest form that is still accepted. Some fields may repeat, either until the data is exhausted or a particular field says how often the fields repeat. There can be two sets of repeating fields. If present, this element documents how many fields are in the first set of repeating fields. If not present, there are no repeating fields. Some fields may repeat, either until the data is exhausted or a particular field says how often the fields repeat. There can be two sets of repeating fields. This element documents at which field (e.g. its 'Order') the first set starts. Some fields may repeat, either until the data is exhausted or a particular field says how often the fields repeat. There can be two sets of repeating fields. This element documents which earlier field indicates how often the first set repeats. If RepeatingFieldSet1StartField is present but RepeatingFieldSet1CountField is not, the set repeats until the data is exhausted. Some fields may repeat, either until the data is exhausted or a particular field says how often the fields repeat. There can be two sets of repeating fields. If present, this element documents how many fields are in the second set of repeating fields. If not present, there is no repeating second set. Some fields may repeat, either until the data is exhausted or a particular field says how often the fields repeat. There can be two sets of repeating fields. This element documents at which field (e.g. its 'Order') the second set starts. Some fields may repeat, either until the data is exhausted or a particular field says how often the fields repeat. There can be two sets of repeating fields. This element documents which earlier field indicates how often the second set repeats. If RepeatingFieldSet2StartField is present but RepeatingFieldSet2CountField is not, the set repeats until the data is exhausted. When present, it reports the typical interval, in milliseconds, that the PGN repeats. When present, and true, the PGN is only transmitted when something happens (like an error condition), when a button is pressed, or when some other devices sends a request for the device to send this PGN.