Skip to main content

UbxMsgParser

Latest Version: 2.0.0

This library provides a parser for UBX binary messages. For information about UBX messages, please see the u-blox protocol specification.

Electric Imp offers two libraries to support the u-blox NEO-M8N module: this message parser and a device-side driver class

The parser is implemented as a table, so command-parsing functions can be added and existing ones easily customized. A small number of messages have been selected as a base. These commands are detailed in the Class Methods section below.

You can view the library’s source code on GitHub. Click here to see information on other versions of this library.

To include this library in your project, add #require "UbxMsgParser.lib.nut:2.0.0" at the top of your agent and/or device code.

Class Usage

No initialization is needed to use the parser, which is implemented as a table that is accessed via the global variable UbxMsgParser.

There is one helper method available to convert the integer latitude and longitude values returned by UBX methods to a decimal degree string, a more common format for this data.

The remaining slots in the parser table are identified by 16-bit integers: the UBX class message ID. For example, to parse the payload of a UBX message of type NAV_PVT, you would call:

local result = UbxMsgParser[0x0107](payload);

where payload is the message data and result is the parsed information, returned as a table.

The value of each slot is the relevant parsing function. Each parsing function takes the UBX message payload and returns a table. The parsed tables will always contain error and payload slots. If no error was encountered when parsing the payload, the error slot will be null and additional slots will be included in the table. Users should always check the error value before accessing the other slots.

Note Squirrel only supports signed 32-bit integers. If the payload contains a 32-bit unsigned integer, the parsed table will contain a four-byte blob with the payload values. These values will be in the same order as received by the M8N (little endian).

Class Methods

toDecimalDegreeString(UBXdegrees)

This method converts an integer UBX latitude or longitude value into a decimal degree string, eg. "37.3955323" or "-122.1023164".

Parameters

Parameter Type Required Description
UBXdegrees Integer Yes Latitude or Longitude integer from a parsed UBX message

Returns

String — the decimal degree latitude or longitude.

0x0107(payload)

This method parses 0x0107 (NAV_PVT) UBX message payloads.

Parameters

Parameter Type Required Description
payload Blob Yes 100-byte NAV_PVT message payload

Returns

Table — contains the following keys:

Key Type Description
error String or null Error message if a parsing error was encountered, or null
payload Blob The unparsed payload
iTOW Blob GPS time of week of the navigation epoch in ms (four-byte unsigned integer)
year Integer Year (UTC)
month Integer Month in range 1-12 (UTC)
day Integer Day of month in range 1-31 (UTC)
hour Integer Hour of day in range 0-23 (UTC)
min Integer Minute of hour in range 0-59 (UTC)
sec Integer Seconds of minute in range 0-60 (UTC)
valid Table Validity flags (see below)
tAcc Integer Time accuracy estimate in ns (UTC)
nano Integer Fraction of second (ns) in range -1e9 to +1e9 (UTC)
fixType Integer GNSSfix Type:
0 = No fix
1 = Dead reckoning only
2 = 2D fix
3 = 3D fix
4 = GNSS plus dead reckoning combined
5 = Time-only fix
fixStatusFlags Table Fix status flags (see below)
numSV Integer Number of satellites used
lon Integer Longitude in degrees
lat Integer Latitude in degrees
height Integer Height above ellipsoid in mm
hMSL Integer Height above mean sea level mm
hAcc Blob Horizontal accuracy estimate in mm (four-byte unsigned integer)
vAcc Blob Vertical accuracy estimate in mm (four-byte unsigned integer)
velN Integer NED north velocity in mm/s
velE Integer NED east velocity in mm/s
velD Integer NED down velocity in mm/s
gSpeed Integer Ground Speed (2D) in mm/s
headMot Integer Heading of motion (2D) in degrees
sAcc Blob Speed accuracy estimate in mm/s (four-byte unsigned integer)
headAcc Blob Heading accuracy estimate (both motion and vehicle) in mm/s (four-byte unsigned integer)
pDOP Integer Position DOP
headVeh Integer Heading of vehicle (2D) in degrees
magDec Integer Magnetic declination in degrees
magAcc Integer Magnetic declination accuracy in degrees

Validity Flags

Key Type Description
validDate Bool UTC date valid?
validTime Bool UTC time of day valid?
fullyResolved Bool UTC time of day has been fully resolved? (no seconds uncertainty)
validMag Bool Magnetic declination valid?

Fix Status Flags

Key Type Description
gnssFixOK Integer 1 = Valid fix (ie. within DOP & accuracy masks)
diffSoln Integer 1 = Differential corrections were applied
psmState Integer Power Save Mode state:
0 = PSM is not active
1 = Enabled (an intermediate state before acquisition)
2 = Acquisition
3 = Tracking
4 = Power-optimized tracking
5 = Inactive
headVehValid Integer 1 = heading of vehicle is valid
carrSoln Integer Carrier phase range solution status (not supported in protocol versions less than 20):
0 = No carrier phase range solution
1 = Float solution (no fixed integer carrier phase measurements have been used to calculate the solution)
2 = Fixed solution (one or more fixed integer carrier phase range measurements have been used to calculate the solution)
confirmedAvai Integer 1 = Information about UTC Date and Time of Day validity confirmation is available (Not supported in all versions)
confirmedDate Integer 1 = UTC date validity could be confirmed
confirmedTime Integer 1 = UTC time of day could be confirmed

0x0135(payload)

This method parses 0x0135 (NAV_SAT) UBX message payloads.

Parameters

Parameter Type Required Description
payload Blob Yes 8 + 12 * n bytes of NAV_SAT message payload

Returns

Table — contains the following keys:

Key Type Description
error String or null Error message if a parsing error was encountered, or null
payload Blob The unparsed payload
iTOW Blob GPS time of week of the navigation epoch in ms (four-byte unsigned integer)
version Integer Message version (1 for this version)
numSvs Integer Number of satellites
satInfo Array of tables Satellite details (see below)

Satellite Info Table Keys

Key Type Description
error String or null Error message if a parsing error was encountered, or null
payload Blob The unparsed payload
gnssId Integer GNSS identifier
svId Integer Satellite identifier
cno Integer Carrier to noise ratio (signal strength) in dBHz
elev Integer Elevation (range ±90), unknown if out of range, in degrees
azim Integer Azimuth (range 0-360), unknown if elevation is out of range, in degrees
prRes Integer Pseudorange residual in m
flags Table Set of flags (see below)

Satellite Info Flags

Key Type Description
error String or null Error message if a parsing error was encountered, or null
payload Blob The unparsed payload
qualityInd Integer Signal quality indicator:
0 = No signal
1 = Searching for signal
2 = Signal acquired
3 = Signal detected but unusable
4 = Code locked and time synchronized
5, 6, 7 = Code and carrier locked and time synchronized
svUsed Integer 1 = Signal in the subset specified in signal identifiers is currently being used for navigation
health Integer Signal health flag:
0 = Unknown
1 = Healthy
2 = Unhealthy
diffCorr Integer 1 = Differential correction data is available for this SV
smoothed Integer 1 = Carrier smoothed pseudorange used
orbitSource Integer Orbit source:
0 = No orbit information is available for this SV
1 = Ephemeris is used
2 = Almanac is used
3 = AssistNow offline orbit is used
4 = AssistNow autonomous orbit is used
5, 6, 7 = Other orbit information is used
ephAvail Integer 1 = Ephemeris is available for this SV
almAvail Integer 1 = Almanac is available for this SV
anoAvail Integer 1 = AssistNow offline data is available for this SV
aopAvail Integer 1 = AssistNow autonomous data is available for this SV
sbasCorrUsed Integer 1 = SBAS corrections have been used for a signal
rtcmCorrUsed Integer 1 = RTCM corrections have been used
slasCorrUsed Integer 1 = QZSS SLAS corrections have been used
prCorrUsed Integer 1 = Pseudorange corrections have been used
crCorrUsed Integer 1 = Carrier range corrections have been used
doCorrUsed Integer 1 = Range rate (Doppler) corrections have been used

0x0501(payload)

This method parses 0x0501 (ACK_ACK) UBX message payloads.

Parameters

Parameter Type Required Description
payload Blob Yes A two-byte ACK_ACK message payload

Returns

Table — contains the following keys:

Key Type Description
error string or null Error message if a parsing error was encountered, or null
payload Blob The unparsed payload
ackMsgClassId Integer The two-byte message class and ID of the ACK’d message

0x0500(payload)

This method parses 0x0500 (ACK_NAK) UBX message payloads.

Parameters

Parameter Type Required Description
payload Blob Yes A two-byte ACK_NAK message payload

Returns

Table — contains the following keys:

Key Type Description
error String or null Error message if a parsing error was encountered, or null
payload Bblob The unparsed payload
nakMsgClassId Integer The two-byte message class and ID of the NAK’d message

0x0A04(payload)

This method parses 0x0a04 (MON_VER) UBX message payloads.

Parameters

Parameter Type Required Description
payload Blob Yes 40 + 30 * n bytes of MON_VER message payload

Returns

Table — contains the following keys:

Key Type Description
error String or null Error message if a parsing error was encountered, or null
payload Blob The unparsed payload
swVersion String The software Version
hwVersion Sting The hardware Version
exSwInfo Array of strings Extended software information strings, if any

0x0A09(payload)

This method parses 0x0a09 (MON_HW) UBX message payloads.

Parameters

Parameter Type Required Description
payload Blob Yes A 60-byte MON_HW message payload

Returns

Table — contains the following keys:

Key Type Description
error String or null Error message if a parsing error was encountered, or null
payload Blob The unparsed payload
pinSel Blob Mask of pins set as Peripheral/PIO
pinBank Blob Mask of pins set as Bank A/B
pinDir Blob Mask of pins set as Input/Output
pinVal Blob Mask of pins of value Low/High
noisePerMS Integer Noise level as measured by the GPS core
agcCnt Integer AGC Monitor (counts SIGHI xor SIGLO, range 0 to 8191)
aStatus Integer The status of the antenna supervisor state machine:
0 = Initializing
1 = Unknown
2 = OK
3 = Short
4 = Open
aPower Integer The current power status of the antenna:
0 = Off
1 = On
2 = Unknown
flags Table Table of flags (see below)
usedMask Blob Mask of pins that are used by the Virtual Pin Manager
vp blob Array of pin mappings for each of the 17 physical pins
jamInd Integer CW Jamming indicator, scaled from 0 (no CW jamming) to 255 (strong CW jamming)
pinIrq Blob Mask of pins using the PIO IRQ
pullH Blob Mask of pins using the PIO Pull High Resistor
pullL Blob Mask of pins using the PIO Pull Low Resistor

Flags Table

Key Type Description
rtcCalib Integer RTC is calibrated
safeBoot Integer Safe boot mode:
0 = Inactive
1 = Active
jammingState Integer Output from the Jamming/Interference Monitor:
0 = Unknown or feature disabled
1 = OK — no significant jamming
2 = Warning — interference visible but fix OK
3 = Critical — interference visible and no fix
xtalAbsent integer RTC crystal has been determined to be absent. Note Not supported in protocol versions less than 18

Release History

The Electric Imp Dev Center documents the latest version of the library. For past versions, please see the Electric Imp public GitHub repos listed below.

Version Source Code Notes
1.0.0 GitHub Initial release
2.0.0 GitHub Removed Assist Now ACK from parser; added checks and errors for methods that would cause conflicts with Assist Now )

License

This library is licensed under the MIT License.