pyubx2 package

Submodules

pyubx2.exceptions module

UBX Custom Exception Types

Created on 27 Sep 2020

author:: semuadmin
copyright:: SEMU Consulting © 2020
license:: BSD 3-Clause

exception pyubx2.exceptions.ParameterError[source]

Bases: Exception

Parameter Error Class.

exception pyubx2.exceptions.GNSSStreamError[source]

Bases: Exception

Generic Stream Error Class.

exception pyubx2.exceptions.UBXParseError[source]

Bases: Exception

UBX Parsing error.

exception pyubx2.exceptions.UBXStreamError[source]

Bases: Exception

UBX Streaming error.

exception pyubx2.exceptions.UBXMessageError[source]

Bases: Exception

UBX Undefined message class/id. Essentially a prompt to add missing payload types to UBX_PAYLOADS.

exception pyubx2.exceptions.UBXTypeError[source]

Bases: Exception

UBX Undefined payload attribute type. Essentially a prompt to fix incorrect payload definitions to UBX_PAYLOADS.

pyubx2.socket_stream module

socket_stream class.

A skeleton socket wrapper which provides basic stream-like read(bytes) and readline() methods.

NB: this will read from a socket indefinitely. It is the responsibility of the calling application to monitor data returned and implement appropriate socket error, timeout or inactivity procedures.

Created on 4 Apr 2022

author:: semuadmin
copyright:: SEMU Consulting © 2022
license:: BSD 3-Clause

class pyubx2.socket_stream.SocketStream(sock: socket, **kwargs)[source]

Bases: object

socket stream class.

__init__(sock: socket, **kwargs)[source]

Constructor.

Parameters:

socket (sock) – socket object
bufsize (int) – (kwarg) internal buffer size (4096)

property buffer: bytearray

Getter for buffer.

Returns:: buffer
Return type:: bytearray

read(num: int) → bytes[source]

Read specified number of bytes from buffer. NB: always check length of return data.

Parameters:: num (int) – number of bytes to read
Returns:: bytes read (which may be less than num)
Return type:: bytes

readline() → bytes[source]

Read bytes from buffer until LF reached. NB: always check that return data terminator is LF.

Returns:: bytes
Return type:: bytes

write(data: bytes, **kwargs)[source]

Write bytes to socket.

Parameters:: data (bytes) – data
Returns:: None if successful
Return type:: Nonetype

pyubx2.ubxhelpers module

Collection of UBX helper methods which can be used outside the UBXMessage or UBXReader classes

Created on 15 Dec 2020

author:: semuadmin
copyright:: SEMU Consulting © 2020
license:: BSD 3-Clause

pyubx2.ubxhelpers.att2idx(att: str) → int[source]

Get integer index corresponding to grouped attribute.

e.g. svid_06 -> 6; gnssId_103 -> 103

Parameters:: att (str) – grouped attribute name e.g. svid_01
Returns:: index as integer, or 0 if not grouped
Return type:: int

pyubx2.ubxhelpers.att2name(att: str) → str[source]

Get name of grouped attribute.

e.g. svid_06 -> svid; gnssId_103 -> gnssId

Parameters:: att (str) – grouped attribute name e.g. svid_01
Returns:: name without index e.g. DF406
Return type:: str

pyubx2.ubxhelpers.calc_checksum(content: bytes) → bytes[source]

Calculate checksum using 8-bit Fletcher’s algorithm.

Parameters:: content (bytes) – message content, excluding header and checksum bytes
Returns:: checksum
Return type:: bytes

pyubx2.ubxhelpers.isvalid_checksum(message: bytes) → bool[source]

Validate message checksum.

Parameters:: message (bytes) – message including header and checksum bytes
Returns:: checksum valid flag
Return type:: bool

pyubx2.ubxhelpers.atttyp(att: str) → str[source]

Helper function to return attribute type as string.

Parameters:: str – attribute type e.g. ‘U002’
Returns:: type of attribute as string e.g. ‘U’
Return type:: str

pyubx2.ubxhelpers.attsiz(att: str) → int[source]

Helper function to return attribute size in bytes.

Parameters:: str – attribute type e.g. ‘U002’
Returns:: size of attribute in bytes
Return type:: int

pyubx2.ubxhelpers.itow2utc(itow: int) → time[source]

Convert GPS Time Of Week to UTC time

Parameters:: itow (int) – GPS Time Of Week in milliseconds
Returns:: UTC time hh.mm.ss
Return type:: datetime.time

pyubx2.ubxhelpers.utc2itow(utc: datetime) → tuple[source]

Convert UTC datetime to GPS Week Number, Time Of Week

Parameters:: utc (datetime) – datetime
Returns:: GPS Week Number, Time of Week in milliseconds
Return type:: tuple

pyubx2.ubxhelpers.gpsfix2str(fix: int) → str[source]

Convert GPS fix integer to descriptive string.

Parameters:: fix (int) – GPS fix type (0-5)
Returns:: GPS fix type as string
Return type:: str

pyubx2.ubxhelpers.dop2str(dop: float) → str[source]

Convert Dilution of Precision float to descriptive string.

Parameters:: dop (float) – dilution of precision as float
Returns:: dilution of precision as string
Return type:: str

pyubx2.ubxhelpers.gnss2str(gnss_id: int) → str[source]

Convert GNSS ID to descriptive string (‘GPS’, ‘GLONASS’, etc.).

Parameters:: gnss_id (int) – GNSS identifier as integer (0-6)
Returns:: GNSS identifier as string
Return type:: str

pyubx2.ubxhelpers.key_from_val(dictionary: dict, value) → str[source]

Helper method - get dictionary key corresponding to (unique) value.

Parameters:

dictionary (dict) – dictionary
value (object) – unique dictionary value

Returns:

dictionary key

Return type:

str

Raises:

KeyError: if no key found for value

pyubx2.ubxhelpers.get_bits(bitfield: bytes, bitmask: int) → int[source]

Get integer value of specified (masked) bit(s) in a UBX bitfield (attribute type ‘X’)

e.g. to get value of bits 6,7 in bitfield b’\x89’ (binary 0b10001001):

get_bits(b'\x89', 0b11000000) = get_bits(b'\x89', 192) = 2

Parameters:

bitfield (bytes) – bitfield byte(s)
bitmask (int) – bitmask as integer (= Σ(2**n), where n is the number of the bit)

Returns:

value of masked bit(s)

Return type:

int

pyubx2.ubxhelpers.val2bytes(val, att: str) → bytes[source]

Convert value to bytes for given UBX attribute type.

Parameters:

val (object) – attribute value e.g. 25
att (str) – attribute type e.g. ‘U004’

Returns:

attribute value as bytes

Return type:

bytes

Raises:

UBXTypeError

pyubx2.ubxhelpers.bytes2val(valb: bytes, att: str) → object[source]

Convert bytes to value for given UBX attribute type.

Parameters:

valb (bytes) – attribute value in byte format e.g. b’\x19\x00\x00\x00’
att (str) – attribute type e.g. ‘U004’

Returns:

attribute value as int, float, str or bytes

Return type:

object

Raises:

UBXTypeError

pyubx2.ubxhelpers.nomval(att: str) → object[source]

Get nominal value for given UBX attribute type.

Parameters:: att (str) – attribute type e.g. ‘U004’
Returns:: attribute value as int, float, str or bytes
Return type:: object
Raises:: UBXTypeError

pyubx2.ubxhelpers.msgclass2bytes(msgClass: int, msgID: int) → bytes[source]

Convert message class/id integers to bytes.

Parameters:

msgClass (int) – message class as integer e.g. 6
msgID (int) – message ID as integer e.g. 1

Returns:

message class as bytes e.g. b’/x06/x01’

Return type:

bytes

pyubx2.ubxhelpers.msgstr2bytes(msgClass: str, msgID: str) → bytes[source]

Convert plain text UBX message class to bytes.

Parameters:

msgClass (str) – message class as str e.g. ‘CFG’
msgID (str) – message ID as str e.g. ‘CFG-MSG’

Returns:

message class as bytes e.g. b’/x06/x01’

Return type:

bytes

Raises:

UBXMessageError

pyubx2.ubxhelpers.cfgname2key(name: str) → tuple[source]

Return hexadecimal key and data type for given configuration database key name.

Parameters:: name (str) – config key as string e.g. “CFG_NMEA_PROTVER”
Returns:: tuple of (key, type)
Return type:: tuple: (int, str)
Raises:: UBXMessageError

pyubx2.ubxhelpers.cfgkey2name(keyID: int) → tuple[source]

Return key name and data type for given configuration database hexadecimal key.

Parameters:: keyID (int) – config key as integer e.g. 0x20930001
Returns:: tuple of (keyname, type)
Return type:: tuple: (str, str)
Raises:: UBXMessageError

pyubx2.ubxhelpers.protocol(raw: bytes) → int[source]

Gets protocol of raw message.

Parameters:: raw (bytes) – raw (binary) message
Returns:: protocol type (1 = NMEA, 2 = UBX, 4 = RTCM3, 0 = unknown)
Return type:: int

pyubx2.ubxhelpers.hextable(raw: bytes, cols: int = 8) → str[source]

Formats raw (binary) message in tabular hexadecimal format e.g.

000: 2447 4e47 5341 2c41 2c33 2c33 342c 3233 | b’$GNGSA,A,3,34,23’ |

Parameters:

raw (bytes) – raw (binary) data
cols (int) – number of columns in hex table (8)

Returns:

table of hex data

Return type:

str

pyubx2.ubxhelpers.cel2cart(elevation: float, azimuth: float) → tuple[source]

Convert celestial coordinates (degrees) to Cartesian coordinates.

Parameters:

elevation (float) – elevation
azimuth (float) – azimuth

Returns:

cartesian x,y coordinates

Return type:

tuple

pyubx2.ubxhelpers.escapeall(val: bytes) → str[source]

Escape all byte characters e.g. b’\x73’ rather than b`s`

Parameters:: val (bytes) – bytes
Returns:: string of escaped bytes
Return type:: str

pyubx2.ubxhelpers.val2sphp(val: float, scale: float = 1e-07) → tuple[source]

Convert a float value into separate standard and high precisions components, multiplied by a scaling factor to render them as integers, as required by some CFG and NAV messages.

e.g. 48.123456789 becomes (481234567, 89)

Parameters:

val (float) – value as float
scale (float) – scaling factor e.g. 1e-7

Returns:

tuple of (standard precision, high precision)

Return type:

tuple

pyubx2.ubxhelpers.getinputmode(data: bytes) → int[source]

Return input message mode (SET or POLL).

Parameters:: data (bytes) – raw UBX input message
Returns:: message mode (1 = SET, 2 = POLL)
Return type:: int

pyubx2.ubxmessage module

Main UBX Message Protocol Class.

Created on 26 Sep 2020

author:: semuadmin
copyright:: SEMU Consulting © 2020
license:: BSD 3-Clause

class pyubx2.ubxmessage.UBXMessage(ubxClass, ubxID, msgmode: int, parsebitfield: bool = True, scaling: bool = True, **kwargs)[source]

Bases: object

UBX Message Class.

__init__(ubxClass, ubxID, msgmode: int, parsebitfield: bool = True, scaling: bool = True, **kwargs)[source]

Constructor.

If no keyword parms are passed, the payload is taken to be empty.

If ‘payload’ is passed as a keyword parm, this is taken to contain the complete payload as a sequence of bytes; any other keyword parms are ignored.

Otherwise, any named attributes will be assigned the value given, all others will be assigned a nominal value according to type.

Parameters:

msgClass (object) – message class as str, int or byte
msgID (object) – message ID as str, int or byte
msgmode (int) – message mode (0=GET, 1=SET, 2=POLL)
parsebitfield (bool) – parse bitfields (‘X’ type attributes) Y/N
scaling (bool) – apply scale factors Y/N
kwargs – optional payload keyword arguments

Raises:

UBXMessageError

serialize() → bytes[source]

Serialize message.

Returns:: serialized output
Return type:: bytes

property identity: str

Returns message identity in plain text form.

If the message is unrecognised, the message is parsed to a nominal payload definition UBX-NOMINAL and the term ‘NOMINAL’ is appended to the identity.

Returns:: message identity e.g. ‘CFG-MSG’
Return type:: str

property msg_cls: bytes

Class id getter.

Returns:: message class as bytes
Return type:: bytes

property msg_id: bytes

Message id getter.

Returns:: message id as bytes
Return type:: bytes

property length: int

Payload length getter.

Returns:: payload length as integer
Return type:: int

property payload: bytes

Payload getter - returns the raw payload bytes.

Returns:: raw payload as bytes
Return type:: bytes

property msgmode: int

Message mode getter.

Returns:: msgmode as integer
Return type:: int

static config_set(layers: int, transaction: int, cfgData: list) → object[source]

Construct CFG-VALSET message from an array of configuration database (key, value) tuples. Keys can be in int (keyID) or str (keyname) format.

Parameters:

layers (int) – memory layer(s) (1=RAM, 2=BBR, 4=Flash)
transaction (int) – 0=no txn, 1=start txn, 2=continue txn, 3=apply txn
cfgData (list) – list of up to 64 tuples (key, value)

Returns:

UBXMessage CFG-VALSET

Return type:

UBXMessage

Raises:

UBXMessageError

static config_del(layers: int, transaction: int, keys: list) → object[source]

Construct CFG-VALDEL message from an array of configuration database keys, which can be in int (keyID) or str (keyname) format.

Parameters:

layers (int) – memory layer(s) (2=BBR, 4=Flash)
transaction (int) – 0=no txn, 1=start txn, 2=continue txn, 3=apply txn
keys (list) – array of up to 64 keys as int (keyID) or string (keyname)

Returns:

UBXMessage CFG-VALDEL

Return type:

UBXMessage

Raises:

UBXMessageError

static config_poll(layer: int, position: int, keys: list) → object[source]

Construct CFG-VALGET message from an array of configuration database keys, which can be in int (keyID) or str (keyname) format.

Parameters:

layer (int) – memory layer (0=RAM, 1=BBR, 2=Flash, 7 = Default)
position (int) – number of keys to skip before returning result
keys (list) – array of up to 64 keys as int (keyID) or str (keyname)

Returns:

UBXMessage CFG-VALGET

Return type:

UBXMessage

Raises:

UBXMessageError

pyubx2.ubxreader module

UBXReader class.

Reads and parses individual UBX, NMEA or RTCM3 messages from any stream which supports a read(n) -> bytes method.

Returns both the raw binary data (as bytes) and the parsed data (as a UBXMessage, NMEAMessage or RTCMMessage object).

‘protfilter’ governs which protocols (NMEA, UBX or RTCM3) are processed ‘quitonerror’ governs how errors are handled ‘msgmode’ indicates the type of UBX datastream (output GET, input SET, query POLL)

If msgmode set to SETPOLL, input mode will be automatically detected by parser.

Created on 2 Oct 2020

author:: semuadmin
license:: BSD 3-Clause

class pyubx2.ubxreader.UBXReader(datastream, msgmode: int = 0, validate: int = 1, protfilter: int = 3, quitonerror: int = 1, parsebitfield: bool = True, scaling: bool = True, labelmsm: bool = True, bufsize: int = 4096, parsing: bool = True, errorhandler: object = None)[source]

Bases: object

UBXReader class.

__init__(datastream, msgmode: int = 0, validate: int = 1, protfilter: int = 3, quitonerror: int = 1, parsebitfield: bool = True, scaling: bool = True, labelmsm: bool = True, bufsize: int = 4096, parsing: bool = True, errorhandler: object = None)[source]

Constructor.

Parameters:

stream (datastream) – input data stream
msgmode (int) – 0=GET, 1=SET, 2=POLL, 3=SETPOLL (0)
validate (int) – 0 = ignore invalid checksum, 1 = validate checksum (1)
protfilter (int) – protocol filter 1 = NMEA, 2 = UBX, 4 = RTCM3 (3)
quitonerror (int) – 0 = ignore errors, 1 = log continue, 2 = (re)raise (1)
parsebitfield (bool) – 1 = parse bitfields, 0 = leave as bytes (1)
scaling (bool) – 1 = apply scale factors, 0 = do not apply (1)
labelmsm (bool) – whether to label RTCM3 MSM NSAT and NCELL attributes (1)
bufsize (int) – socket recv buffer size (4096)
parsing (bool) – True = parse data, False = don’t parse data (output raw only) (True)
errorhandler (int) – error handling object or function (None)

Raises:

UBXStreamError (if mode is invalid)

read() → tuple[source]

Read a single NMEA, UBX or RTCM3 message from the stream buffer and return both raw and parsed data.

‘protfilter’ determines which protocols are parsed. ‘quitonerror’ determines whether to raise, log or ignore parsing errors.

Returns:: tuple of (raw_data as bytes, parsed_data as UBXMessage, NMEAMessage or RTCMMessage)
Return type:: tuple
Raises:: UBXStreamError (if unrecognised protocol in data stream)

property datastream: object

Getter for stream.

Returns:: data stream
Return type:: object

static parse(message: bytes, msgmode: int = 0, validate: int = 1, quitonerror: int = 1, parsebitfield: bool = True, scaling: bool = True) → object[source]

Parse UBX byte stream to UBXMessage object.

Includes option to validate incoming payload length and checksum (the UBXMessage constructor can calculate and assign its own values anyway).

Parameters:

message (bytes) – binary message to parse
quitonerror (int) – 0 = ignore errors, 1 = log continue, 2 = (re)raise (1)
validate (int) – validate cksum (VALCKSUM (1)=True (default), VALNONE (0)=False)
msgmode (int) – message mode (0=GET (default), 1=SET, 2=POLL)
parsebitfield (bool) – 1 = parse bitfields, 0 = leave as bytes (1)
scaling (bool) – 1 = apply scale factors, 0 = do not apply (1)

Returns:

UBXMessage object

Return type:

UBXMessage

Raises:

UBXParseError (if data stream contains invalid data or unknown message type)

pyubx2.ubxtypes_configdb module

UBX Protocol Configuration Database Keys

Used by CFG_VALGET, CFG_VALSET and CFG_VALDEL message types

Format: “keyname”: (keyID, “type”)

Created on 30 Nov 2020

author:: semuadmin

pyubx2.ubxtypes_core module

UBX Protocol core globals and constants

Created on 27 Sep 2020

author:: semuadmin

pyubx2.ubxtypes_decodes module

UBX Protocol attribute value decode constants.

Created on 26 Aug 2023

author:: semuadmin

pyubx2.ubxtypes_get module

UBX Protocol Output payload definitions

THESE ARE THE PAYLOAD DEFINITIONS FOR _GET_ MESSAGES _FROM_ THE RECEIVER (e.g. Periodic Navigation Data; Poll Responses; Info messages)

Created on 27 Sep 2020

author:: semuadmin

pyubx2.ubxtypes_poll module

UBX Protocol Polling payload definitions

THESE ARE THE PAYLOAD DEFINITIONS FOR _POLL_ MESSAGES _TO_ THE RECEIVER (e.g. query configuration; request monitoring, receiver management, logging or sensor fusion status) Response payloads are defined in UBX_PAYLOADS_GET

NB: Attribute names must be unique within each message class/id

Created on 27 Sep 2020

author:: semuadmin

pyubx2.ubxtypes_set module

UBX Protocol Input payload definitions

THESE ARE THE PAYLOAD DEFINITIONS FOR _SET_ MESSAGES _TO_ THE RECEIVER (e.g. configuration and calibration commands; AssistNow payloads)

Created on 27 Sep 2020

author:: semuadmin

Module contents

Created on 27 Sep 2020

author:: semuadmin
license:: BSD 3-Clause