pyubxutils package

Submodules

pyubxutils.exceptions module

UBX Custom Exception Types

Created on 27 Sep 2020

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

exception pyubxutils.exceptions.ParameterError[source]

Bases: Exception

Parameter Error Class.

exception pyubxutils.exceptions.GNSSStreamError[source]

Bases: Exception

Generic Stream Error Class.

pyubxutils.globals module

Global variables for pyubxutils.

Created on 26 May 2022

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

pyubxutils.globals.EARTH_RADIUS = 6371: Earth radius in km

pyubxutils.globals.EPILOG = '© 2022 SEMU Consulting BSD 3-Clause license - https://github.com/semuconsulting/pyubxutils/': CLI argument parser epilog

pyubxutils.globals.VERBOSITY_CRITICAL = -1: Verbosity critical

pyubxutils.globals.VERBOSITY_LOW = 0: Verbosity error

pyubxutils.globals.VERBOSITY_MEDIUM = 1: Verbosity warning

pyubxutils.globals.VERBOSITY_HIGH = 2: Verbosity info

pyubxutils.globals.VERBOSITY_DEBUG = 3: Verbosity debug

pyubxutils.globals.LOGFORMAT = '{asctime}.{msecs:.0f} - {levelname} - {name} - {message}': Logging format

pyubxutils.globals.LOGLIMIT = 10485760: Logfile limit

pyubxutils.globals.UBXSIMULATOR = 'UBXSIMULATOR': UBX simulator

pyubxutils.helpers module

Collection of GNSS related helper methods.

Created on 26 May 2022

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

pyubxutils.helpers.parse_config(configfile: str) → dict[source]

Parse config file.

Parameters:: configfile (str) – fully qualified path to config file
Returns:: config as kwargs, or None if file not found
Return type:: dict
Raises:: FileNotFoundError
Raises:: ValueError

pyubxutils.helpers.set_common_args(name: str, ap: ArgumentParser, logname: str = 'pyubxutils', logdefault: int = 1) → dict[source]

Set common argument parser and logging args.

Parameters:

name (str) – name of CLI utility e.g. “gnssstreamer”
ArgumentParserap – argument parser instance
logname (str) – logger name
logdefault (int) – default logger verbosity level

Returns:

parsed arguments as kwargs

Return type:

dict

pyubxutils.helpers.set_logging(logger: Logger, verbosity: int = 1, logtofile: str = '', logform: str = '{asctime}.{msecs:.0f} - {levelname} - {name} - {message}', limit: int = 10485760)[source]

Set logging format and level.

Parameters:

logger (logging.Logger) – module log handler
verbosity (int) – verbosity level -1,0,1,2,3 (2 - MEDIUM)
logtofile (str) – fully qualified log file name (“”)
logform (str) – logging format (datetime - level - name)
limit (int) – maximum logfile size in bytes (10MB)

pyubxutils.helpers.progbar(i: int, lim: int, inc: int = 50)[source]: Display progress bar on console.

pyubxutils.helpers.h2sphp(val: float) → tuple[source]

Split height in cm into standard (cm) and high (mm * 10) precision components.

e.g. 123456.78 -> 123456, 78

Parameters:: val – decimal lat/lon value
Returns:: tuple of integers
Return type:: tuple

pyubxutils.helpers.ll2sphp(val: float) → tuple[source]

Split lat/lon into standard (1-7 dp) and high (8-9 dp) precision components.

e.g. 51.123456789 -> 511234567, 89

Parameters:: val – decimal height value in cm
Returns:: tuple of integers
Return type:: tuple

pyubxutils.ubxbase module

ubxbase.py

NB: ONLY FOR GENERATION 9+ UBX RTK DEVICES e.g. ZED-F9n

This command line utility configures an RTK-compatible u-blox GNSS receiver to operate in Base Station mode.

RTCM 1006 (Antenna Reference Data) is only output if the base station is active, so receipt of this message type is used as a configuration success criterion.

Created on 06 Jan 2023

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

class pyubxutils.ubxbase.UBXBase(stream: object, **kwargs)[source]

Bases: object

UBX Base Station Configuration Class.

__init__(stream: object, **kwargs)[source]

Constructor.

Parameters:

file (object) – input file
stream (object) – output serial stream

run()[source]: Run configuration load routines.

pyubxutils.ubxbase.main()[source]

CLI Entry point.

Param:: as per UBXBase constructor.

pyubxutils.ubxcompare module

ubxcompare.py

Parse and compare contents of two or more u-blox config files. Can accept either *.txt (text) or *.ubx (binary) formatted input files - the default is *.txt.

Usage:

ubxcompare –infiles “config1.txt, config2.txt” –format 0 –diffsonly 1

Outputs dictionary of config keys and their values for each file e.g.

CFG_RATE_MEAS (None): {1: ‘1000’, 2: ‘1000’} signifies both files have same value
CFG_RATE_MEAS (DIFFS!): {1: ‘1000’, 2: ‘100’} signifies differences between values
CFG_RATE_MEAS (DIFFS!): {1: ‘1000’} signifies the value was missing from the second or subsequent file(s)

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

class pyubxutils.ubxcompare.UBXCompare(infiles: str, form: int = 0, diffsonly: bool = True)[source]

Bases: object

UBX Compare Configuration Class.

__init__(infiles: str, form: int = 0, diffsonly: bool = True)[source]

Constructor.

Parameters:

infiles (str) – comma-separated list of fully-qualified filenames
format (int) – 0 = text, 1 = binary (0)
diffsonly (bool) – True = show diffs only, False = show entire config (True)

parse_line(line: str) → UBXMessage[source]

Parse individual config line from txt file.

Any messages other than CFG-MSG, CFG-PRT or CFG-VALGET are discarded. The CFG-VALGET messages are converted into CFG-VALSET.

Parameters:: line (str) – config line
Returns:: parsed config line as UBXMessage
Return type:: UBXMessage

get_attrs(cfgdict: dict, parsed: str, fileno: int)[source]

Get individual config keys and values from parsed line.

Parameters:

cfgdict (dict) – dictionary of all config keys and values
parsed (UBXMessage) – parsed config line
fileno (int) – file number

parse_file(cfgdict: dict, filename: str, fileno: int, form: int)[source]

Load u-center format text configuration file.

Parameters:

cfgdict (dict) – dictionary of all config keys and values
filename (str) – fully qualified input file name
fileno (int) – file number
form (int) – 0 = TXT (text), 1 = UBX (binary)

pyubxutils.ubxcompare.main()[source]

CLI Entry point.

Param:: as per UBXLoader constructor.

pyubxutils.ubxload module

ubxload.py

NB: ONLY FOR GENERATION 9+ UBX DEVICES e.g. NEO-M9N, ZED-F9P

This command line utility reads UBX configuration data from a binary file and loads this into a compatible UBX device via its serial port. It then confirms that the data has been successfully acknowledged by the device, or reports any errors.

The binary file is created using the ubxsave utility and contains a series of CFG-VALSET messages representing the complete configuration of the source device.

Created on 06 Jan 2023

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

class pyubxutils.ubxload.UBXLoader(stream: object, **kwargs)[source]

Bases: object

UBX Configuration Loader Class.

__init__(stream: object, **kwargs)[source]

Constructor.

Parameters:

file (object) – input file
stream (object) – output serial stream

run()[source]: Run configuration load routines.

pyubxutils.ubxload.main()[source]

CLI Entry point.

Param:: as per UBXLoader constructor.

pyubxutils.ubxsave module

ubxsave.py

NB: ONLY FOR GENERATION 9+ UBX DEVICES e.g. NEO-M9N, ZED-F9P

CLI utility which saves Generation 9+ UBX device configuration data to a file. ubxsave polls configuration data via the device’s serial port using a series of CFG-VALGET poll messages. It parses the responses to these polls, converts them to CFG-VALSET command messages and saves these to a binary file. This binary file can then be loaded into any compatible UBX device (e.g. via the ubxload utility) to restore the saved configuration.

The CFG-VALSET commands are stored as a single transaction, so if one or more fails on reload, the entire set will be rejected.

NB: The utility relies on receiving a complete set of poll responses within a specified waittime. If the device is exceptionally busy or the transmit buffer is full, poll responses may be delayed or dropped altogether. If the utility reports errors, try increasing the waittime and/or baudrate or temporarily reducing periodic message rates.

Usage (all kwargs are optional):

> ubxsave –port /dev/ttyACM1 –baud 9600 –timeout 0.02 –outfile ubxconfig.ubx –verbosity 1

Created on 06 Jan 2023

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

class pyubxutils.ubxsave.UBXSaver(file: object, stream: object, **kwargs)[source]

Bases: object

UBX Configuration Saver Class.

__init__(file: object, stream: object, **kwargs)[source]: Constructor.

run()[source]: Main save routine.

pyubxutils.ubxsave.main()[source]

CLI Entry Point.

Param:: as per UBXSaver constructor.

pyubxutils.ubxsetrate module

ubxsetrate.py

Simple command line utility, installed with PyPi library pyubxutils, to configure message rates on a UBX GNSS receiver connected to a local serial port via the UBX CFG-MSG command.

Usage:

ubxsetrate –port dev/tty.usbmodem1301 –baudrate 38400 –timeout 5: –msgClass 0xf1 –msgID 0x00 –rate 1 –verbosity 1

or (to turn off all NMEA messages):

ubxsetrate –port /dev/tty.usbmodem1301 –msgClass allnmea –rate 0

Created on 12 Dec 2022

author:: semuadmin
license:: BSD 3-Clause

class pyubxutils.ubxsetrate.UBXSetRate(**kwargs)[source]

Bases: object

UBX Set Rate Class.

Supports basic enable/disable message configuration for UBX GNSS devices connected to a local serial port

__init__(**kwargs)[source]

Constructor.

Parameters:

port (str) – (kwarg) serial port name
baudrate (int) – (kwarg) serial baud rate (9600)
timeout (int) – (kwarg) serial timeout in seconds (3)
msgClass (str) – (kwarg) message class from pyubx2.UBX_CLASSES OR
msgClass – (kwarg) special values “allubx”, ‘minubx”, “allnmea” or “minnmea”
msgID (int) – (kwarg) message ID from pyubx2.UBX_MSGIDS[1:]
rate (int) – (kwarg) message rate per navigation solution (1)

Raises:

ParameterError

apply()[source]: Creates UBX CFG-MSG command(s) and sends them to receiver.

pyubxutils.ubxsetrate.main()[source]

CLI Entry point.

Param:: as per UBXSetRate constructor.
Raises:: ParameterError if parameters are invalid

pyubxutils.ubxsimulator module

ubxsimulator.py

* EXPERIMENTAL *

Simple UBX GNSS serial device simulator.

Simulates a GNSS serial stream by generating synthetic UBX or NMEA messages based on parameters defined in a json configuration file. Can simulate a motion vector based on a specified course over ground and speed.

Example usage:

from pyubxutils import UBXSimulator from pyubx2 import UBXReader

with UBXSimulator(configfile=”/home/myuser/ubxsimulator.json”, interval=1, timeout=3) as stream:
ubr = UBXReader(stream) for raw, parsed in ubr:

print(parsed)

Generates mock acknowledgements (ACK-ACK) for valid incoming UBX commands and polls.

See sample ubxsimulator.json configuration file in the \examples folder.

NB: Principally intended for testing Python GNSS application functionality. There is currently no attempt to simulate real-world satellite geodetics, though this could be done using e.g. the Python skyfield library and the relevant satellite TLE (orbital elements) files. I may look into adding such functionality as and when time permits. Contributions welcome.

Created on 3 Feb 2024

author:: semuadmin
license:: BSD 3-Clause

class pyubxutils.ubxsimulator.UBXSimulator(app=None, **kwargs)[source]

Bases: object

Simple dummy GNSS UBX serial stream class.

__init__(app=None, **kwargs)[source]

Constructor.

Parameters:

interval (float) – (kwarg) simulated navigation interval in seconds
timeout (float) – (kwarg) simulated serial read timeout in seconds
configfile (str) – (kwarg) fully qualified path to json config file

start()[source]: Start streaming.

stop()[source]: Stop streaming.

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

Read n bytes from buffer.

Parameters:: val (int) – num of bytes to read (1)
Returns:: bytes
Raises:: TimeoutError

readline() → bytes[source]

Read line from buffer.

Returns:: bytes

write(data: bytes)[source]

Simulated write to receiver.

Parameters:: data (bytes) – UBX data

close()[source]: Close dummy serial stream.

property is_open: bool

Return status.

Returns:: true or false
Return type:: bool

property in_waiting: int

Return number of bytes in buffer.

Returns:: buffer length
Return type:: int

pyubxutils.ubxsimulator_cli module

ubxsimulator_cli.py

CLI wrapper for UBXSimulator class.

Created on 24 Jul 2024

author:: semuadmin
license:: BSD 3-Clause

pyubxutils.ubxsimulator_cli.main()[source]: CLI Entry point.

Module contents

Created on 27 Sep 2020

author:: semuadmin
license:: BSD 3-Clause