.. |br| raw:: html
.. _ubx:
UBX Parser
==========
The UBX parser makes it easy to receive and decode messages in the u-blox propietary protocol. |br|
.. note:: To follow this section we suggest to download `u-blox ZED-F9P Interface Description document `_ to use it as a reference.
Methods
-------
.. class:: ubx.Parser(cb=None, raw_payload=False, verbose=0)
The ``ubx.Parser`` class is used to create an object that can access the UART1 port of the GPS/GNSS receivers mounted on the SBC.
The class needs to be initialized with the following parameters:
.. csv-table::
:header: Parameter name, Value, Description
:widths: 10, 10, 10
``cb``, "Any function. |br| Default value is None.", Callback function to be called when a |br| UBX message is parsed. |br| Callback function argument is a variable |br| containing the UBX message fields in an array.
``raw_payload``, "True, False. |br| Default value is False.", "If set to False, the ``parse`` method will return a |br|
message array with all the parsed message fields. |br| If set to True, the ``parse`` method will return a |br| message array with:
1. Message class identifier
2. Message Ide identifier
3. Message payload (raw)
4. Message payload length
*See examples below to understand better*"
``verbose``, "0, 1, default value is 0", If set to 1 parser will print in the terminal a |br| *CRC failed* message if the parsed message |br| is not valid
.. method:: parse(buf):
Parse UBX message
Args:
``buf``: Variable containing one or many UBX messages. This variable may contain messages in other procotols, which will be ignored by the UBX parser.
Return:
Array of UBX messages contained in ``buf``.
Example to parse a UBX NAV-PVT message with and without the ``raw_payload`` enabled:
>>> import sbc
>>> ubx_parser = sbc.ubx.Parser(raw_payload=False)
>>> ubx_msg = bytes([0xB5, 0x62, 0x01, 0x07, 0x5C, 0x00, 0xB8, 0x39, 0x92, 0x17, 0xE5, 0x07, 0x03, 0x12, 0x0D, 0x32, 0x29, 0x37, 0x19, 0x00, 0x00, 0x00, 0xB9, 0xE9, 0xFC, 0xFF, 0x03, 0x03, 0xEA, 0x19, 0x1E, 0x59, 0x5D, 0x00, 0x46, 0xFB, 0xCC, 0x18, 0x8F, 0xDE, 0x03, 0x00, 0xFF, 0x1B, 0x03, 0x00, 0xD8, 0x05, 0x00, 0x00, 0xD5, 0x06, 0x00, 0x00, 0xEF, 0xFF, 0xFF, 0xFF, 0x00, 0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x11, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xA5, 0x00, 0x00, 0x00, 0x80, 0xA8, 0x12, 0x01, 0x5F, 0x00, 0x00, 0x00, 0x6C, 0x18, 0x42, 0x3E, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xE2, 0x62])
>>> msg = ubx_parser.parse(ubx_msg)
>>> print(msg)
[NavPvt {'lat': 416086854, 'vAcc': 1749, 'itow': 395459000, 'height': 253583, 'year': 2021, 'sAcc': 165, 'flags': 3, 'headVeh': 0, 'hAcc': 1496, 'reserved3': 1044519020, 'reserved2': 0, 'magDec': 0, 'magAcc': 0, 'hour': 13, 'day': 18, 'valid': 55, 'min': 50, 'headingAcc': 18000000, 'name': 'NavPvt', 'tAcc': 25, 'numSV': 25, 'velN': -17, 'flags3': 0, 'hMSL': 203775, 'sec': 41, 'gSpeed': 17, 'month': 3, 'fixType': 3, 'nano': -202311, 'flags2': 234, 'heading': 0, 'velD': 7, 'velE': 0, 'pDop': 95, 'lon': 6117662}]
>>> print('Received UBX message is: ', msg[0].name,', latitude value is: ', msg[0].lat)
Received UBX message is: NavPvt , latitude value is: 416086854
>>> ubx_parser = sbc.ubx.Parser(raw_payload=True)
>>> msg = ubx_parser.parse(ubx_msg)
>>> print(msg)
[(1, 7, bytearray(b'\xb89\x92\x17\xe5\x07\x03\x12\r2)7\x19\x00\x00\x00\xb9\xe9\xfc\xff\x03\x03\xea\x19\x1eY]\x00F\xfb\xcc\x18\x8f\xde\x03\x00\xff\x1b\x03\x00\xd8\x05\x00\x00\xd5\x06\x00\x00\xef\xff\xff\xff\x00\x00\x00\x00\x07\x00\x00\x00\x11\x00\x00\x00\x00\x00\x00\x00\xa5\x00\x00\x00\x80\xa8\x12\x01_\x00\x00\x00l\x18B>\x00\x00\x00\x00\x00\x00\x00\x00'), 92)]
>>> print('UBX message class is: ', msg[0][0], ', message ide is: ', msg[0][1], ', message payload length is: ', msg[0][3], ', message payload is: ', msg[0][2])
UBX message class is: 1 , message ide is: 7 , message payload length is: 92 , message payload is: bytearray(b'\xb89\x92\x17\xe5\x07\x03\x12\r2)7\x19\x00\x00\x00\xb9\xe9\xfc\xff\x03\x03\xea\x19\x1eY]\x00F\xfb\xcc\x18\x8f\xde\x03\x00\xff\x1b\x03\x00\xd8\x05\x00\x00\xd5\x06\x00\x00\xef\xff\xff\xff\x00\x00\x00\x00\x07\x00\x00\x00\x11\x00\x00\x00\x00\x00\x00\x00\xa5\x00\x00\x00\x80\xa8\x12\x01_\x00\x00\x00l\x18B>\x00\x00\x00\x00\x00\x00\x00\x00')
Example to use a callback to print a message everytime a UBX-NAV-PVT message is received:
>>> import sbc
>>> import time
>>> def ubx_callback(msg):
>>> if msg.name == 'NavPvt':
>>> print('NavPvt message received at GPS iTOW: ', msg.itow)
>>> gps1 = sbc.Gps(1, uart_baudrate = 38400)
>>> ubx_parser = sbc.ubx.Parser(cb = ubx_callback)
>>> time.sleep(1)
>>> while True:
>>> ubx_parser.parse(gps1.read())
NavPvt message received at GPS iTOW: 396758000
NavPvt message received at GPS iTOW: 396759000
NavPvt message received at GPS iTOW: 396760000
NavPvt message received at GPS iTOW: 396761000
NavPvt message received at GPS iTOW: 396762000
NavPvt message received at GPS iTOW: 396763000
NavPvt message received at GPS iTOW: 396764000
...
.. method:: ubx.request(gps,parser,msg_name,timeout_ms=1000):
Request (poll) a specific UBX message to the GPS/GNSS receiver
Args:
``gps``: Gps object. |br|
``parser``: ubx.Parser object. **The parser used must have** ``raw_payload`` **set to False**. |br|
``msg_name``: name of the UBX message to be polled. |br|
``timeout_ms``: maximum time in milliseconds to wait for a response from the GPS/GNSS receiver. Default value is 1000ms. |br|
Return:
Requested UBX message or None if the GPS/GNSS receiver does not answer.
Example to poll UBX NAV-RELPOSNED message:
>>> import sbc
>>> gps1 = sbc.Gps(1, uart_baudrate = 38400)
>>> ubx_parser = sbc.ubx.Parser()
>>> msg = sbc.ubx.request(gps1, ubx_parser, "NavRelposned")
>>> print(msg)
NavRelposned {'relPosHeading': 0, 'refStationId': 0, 'reserved1': 0, 'reserved0': 0, 'relPosLength': 0, 'accN': 0, 'itow': 465463000, 'relPosD': 0, 'relPosHPN': 0, 'relPosE': 0, 'reserved2': 0, 'name': 'NavRelposned', 'flags': 3, 'relPosN': 0, 'relPosHPD': 0, 'relPosHPE': 0, 'accE': 0, 'relPosHPLength': 0, 'version': 1, 'accD': 0, 'accLength': 0, 'accHeading': 0}
>>> print('Message name is:',msg.name,'which was received at iTOW:',msg.itow)
Message name is: NavRelposned which was received at iTOW: 465463000
.. method:: ubx.request_from_cls_ide(gps,parser,cls,ide,timeout_ms=1000):
Request (poll) a specific UBX message (by Class and Message Ide) to the GPS/GNSS receiver
Args:
``gps``: Gps object. |br|
``parser``: ubx.Parser object. **The parser used must have** ``raw_payload`` **set to True**. |br|
``cls``: UBX message Class to be polled. |br|
``ide``: UBX message Id to be polled. |br|
``timeout_ms``: maximum time in milliseconds to wait for a response from the GPS/GNSS receiver. Default value is 1000ms. |br|
Return:
Requested UBX message or None if the GPS/GNSS receiver does not answer.
Example to poll UBX NAV-RELPOSNED message, which Class is 0x01 and Id is 0x3C:
>>> import sbc
>>> gps1 = sbc.Gps(1, uart_baudrate = 38400)
>>> ubx_parser = sbc.ubx.Parser(raw_payload=True)
>>> msg = sbc.ubx.request_from_cls_ide(gps1, ubx_parser, 0x01, 0x3C)
>>> print(msg)
(1, 60, bytearray(b'\x01\x00\x00\x00(7P\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00'), 64)
.. method:: ubx.build(msg):
Builds a UBX binary message from a SBC readable msg.
Args:
``msg``: UBX message in SBC readable format. |br|
Return:
Binary UBX message, including headers and CRC.
Example to generate UBX NAV-PVT message:
>>> import sbc
>>> gps1 = sbc.Gps(1, uart_baudrate = 38400)
>>> ubx_parser = sbc.ubx.Parser()
>>> msg = sbc.ubx.request(gps1, ubx_parser, "NavPvt")
>>> print(msg)
NavPvt {'lat': 425083600, 'vAcc': 5564, 'itow': 293472000, 'height': 1069380, 'year': 2022, 'sAcc': 412, 'flags': 3, 'headVeh': 0, 'hAcc': 3019, 'reserved3': 860200482, 'reserved2': 0, 'magDec': 0, 'magAcc': 0, 'hour': 9, 'day': 2, 'valid': 55, 'min': 30, 'headingAcc': 18000000, 'name': 'NavPvt', 'tAcc': 33, 'numSV': 14, 'velN': -9, 'flags3': 0, 'hMSL': 1020343, 'sec': 54, 'gSpeed': 10, 'month': 2, 'fixType': 3, 'nano': 347857, 'flags2': 234, 'heading': 0, 'velD': -39, 'velE': -6, 'pDop': 216, 'lon': 15306910}
>>> msg_binary = sbc.ubx.build(msg)
>>> print(msg_binary)
b'\xb5b\x01\x07\\\x000\xf9~\x11\xe6\x07\x02\x02\t\x1f87"\x00\x00\x00\x0bP\x04\x00\x03\x03\xea\x0e\x07\x8f\xe9\x00\x95CV\x19\xcaP\x10\x00=\x91\x0f\x00>\x0c\x00\x00]\x16\x00\x00\xf6\xff\xff\xff\xf2\xff\xff\xff\x1b\x00\x00\x00\x11\x00\x00\x00\x00\x00\x00\x00Y\x01\x00\x00\x80\xa8\x12\x01\xa6\x00\x00\x00"\x9eE3\x00\x00\x00\x00\x00\x00\x00\x00.\xba'
.. method:: ubx.build_from_cls_ide(cls, ide, payload):
Builds a UBX binary message from the message inputs.
Args:
``cls``: UBX message Class. |br|
``ide``: UBX message Id. |br|
``payload``: UBX message payload. |br|
Return:
Binary UBX message, including headers and CRC.
Example to generate UBX message bring your GPS/GNSS receiver to its default configuration:
>>> import sbc
>>> payload = bytes([0xFF, 0xFF, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xFF, 0xFF, 0x00, 0x00, 0x03])
>>> ubx_parser = sbc.ubx.Parser()
>>> print(sbc.ubx.build_from_cls_ide(0x06, 0x09, payload))
b'\xb5b\x06\t\r\x00\xff\xff\x00\x00\x00\x00\x00\x00\xff\xff\x00\x00\x03\x1b\x9a'
.. method:: ubx.config_from_cls_ide(gps,parser,cls,ide,payload,timeout_ms=1000):
Send UBX configuration message to the GPS/GNSS receiver
Args:
``gps``: Gps object. |br|
``parser``: ubx.Parser object. |br|
``cls``: UBX message Class to be configured. |br|
``ide``: UBX message Id to be configured. |br|
``payload``: UBX message configuration payload. |br|
``timeout_ms``: maximum time in milliseconds to wait for a response from the GPS/GNSS receiver. Default value is 1000ms. |br|
Return:
True or False if config message is acknowledged/not-acknowledged by the GPS/GNSS receiver.
Example to bring your GPS/GNSS receiver to its default configuration :
>>> import sbc
>>> payload = bytes([0xFF, 0xFF, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xFF, 0xFF, 0x00, 0x00, 0x03])
>>> gps1 = sbc.Gps(1, uart_baudrate = 38400)
>>> ubx_parser = sbc.ubx.Parser()
>>> print(sbc.ubx.config_from_cls_ide(gps1, ubx_parser, 0x06, 0x09, payload))
True
Supported messages
------------------
.. note:: To understand better the meaning of the fields, units, ... we suggest to download `u-blox ZED-F9P Interface Description document `_ . |br|
:ref:`Contact us ` if the message you need is not on the list and we will add it :)
.. csv-table::
:header: Name, Class, Id, Fields
``AckAck``,0x05,0x01,"clsId, msgId"
``AckNak``,0x05,0x00,"clsId, msgId"
``MonMsgpp``,0x0A,0x06,"msg1, msg2, msg3, msg4, msg5, msg6"
``MonVer``,0x0A,0x04 ,"swVersion, hwVersion, numExtensions, extensions"
``NavEoe``,0x01,0x61,"itow"
``NavHpposecef``,0x01,0x13,"version, reserved1, itow, ecefX, ecefY, |br| ecefZ, ecefXHp, ecefYHp, ecefZHp, flags, pAcc"
``NavHpposllh``,0x01,0x14,"version, reserved1, flags, itow, lon, lat, height, hMSL, lonHp, |br| latHp, heigthHp, hMSLHp, hAcc, vAcc"
``NavPvt``,0x01,0x07,"itow, year, month, day, hour, min, sec, valid, tAcc, nano, fixType, |br| flags, flags2, numSV, lon, lat, height, hMSL, hAcc, vAcc, velN, |br| velE, velD, gSpeed, heading, sAcc, headingAcc, pDop, flags3, |br| reserved2, reserved3, headVeh, magDec, magAcc"
``NavRelposned``,0x01,0x3C,"version, reserved0, refStationId, itow, relPosN, relPosE, relPosD, |br| relPosLength, relPosHeading, reserved1, relPosHPN, relPosHPE, |br| relPosHPD, relPosHPLength, accN, accE, accD, accLength, |br| accHeading, reserved2, flags"
``NavSat``,0x01,0x35,"itow, version, numSvs, reserved1, Svs"
``NavSig``,0x01,0x43,"itow, version, numSvs, reserved0, Sigs"
``NavStatus``,0x01,0x03,"itow, gpsFix, flags, fixStat, flags2, ttff, msss"
``NavSvin``,0x01,0x3B,"version, reserved1, itow, dur, meanX, meanY, meanZ, meanXHP, |br| meanYHP, meanZHP, reserved2, meanAcc, obs, valid, active, |br| reserved3"
``NavTimegps``,0x01,0x20,"itow, ftow, weeks, leapS, valid, tAcc"
``NavTimeutc``,0x01,0x21,"itow, tAcc, nano, year, month, day, hour, min, sec, valid"
``NavVelecef``,0x01,0x11,"itow, ecefVX, ecefVY, ecefVZ, sAcc"
``NavVelned``,0x01,0x12,"itow, velN, velE, velD, speed, gSpeed, heading, sAcc, cAcc"
``RxmRawx``,0x02,0x15,"week, leapS, numMeas, recStat, version, reserved1, Meas"
``RxmRtcm``,0x02,0x32,"version, flags, subType, refStation, msgType"
``RxmSfrbx``,0x02,0x13,"gnssId, svid, reserved1, freqId, numWords, chn, version, |br| reserved3, Words"
``TimTm2``,0x0D,0x03,"ch, flags, count, wnR, wnF, towMsR, towSubMsR, towMsF, |br| towSubMsF, accEst"