pygnssutils

Current Status | Installation | gnssreader | gnssstreamer CLI | gnssserver CLI | gnssntripclient CLI | gnssmqttclient CLI | socketserver | RTK Demonstration | Troubleshooting | Graphical Client | Author & License

pygnssutils is an original series of Python GNSS utility classes and CLI tools built around the following core libraries from the same stable:

• pyubx2 - UBX parsing and generation library (u-blox binary data output & configuration)
• pysbf2 - SBF parsing and generation library (Septentrio binary data output)
• pyunigps - UNI parsing and generation library (Unicore binary data output)
• pyqgc - QGC parsing and generation library (Quectel binary data output & configuration)
• pynmeagps - NMEA parsing and generation library (generic data output and Quectel configuration)
• pyrtcm - RTCM3 parsing library
• pyspartn - SPARTN parsing library

Originally developed in support of the PyGPSClient GUI GNSS application, the utilities provided by pygnssutils can also be used in their own right:

1. GNSSReader class. This is essentially an amalgamation of the *Reader classes in all the subsidiary parsers listed above, allowing the user to seamlessly stream any of NMEA, UBX, SBF, UNI, QGC, RTCM3 and SPARTN message protocols concurrently from a single stream.
2. GNSSStreamer class and its associated gnssstreamer (formerly gnssdump) CLI utility. This is essentially a configurable bidirectional input/output wrapper around the GNSSReader class with flexible message formatting, filtering and output handling options for NMEA, UBX, SBF, UNI, QGC and RTCM3 protocols.
3. GNSSSocketServer class and its associated gnssserver CLI utility. This implements a TCP Socket Server for GNSS data streams which is also capable of being run as a simple NTRIP Server/Caster.
4. GNSSNTRIPClient class and its associated gnssntripclient CLI utility. This implements a simple NTRIP Client which receives RTCM3 or SPARTN correction data from an NTRIP Server and (optionally) sends this to a designated output stream.
5. GNSSMQTTClient class and its associated gnssmqttclient CLI utility. This implements a simple SPARTN IP (MQTT) Client which receives SPARTN correction data from an SPARTN IP location service and (optionally) sends this to a designated output stream.
6. SocketServer class based on the native Python ThreadingTCPServer. Capable of operating in two modes - Socket Server or NTRIP Caster. Provides two alternate client request handler classes - ClientHandler (HTTP) or ClientHandlerTLS (HTTPS).

The pygnssutils homepage is located at https://github.com/semuconsulting/pygnssutils.

<a name="currentstatus">Current Status</a>

Sphinx API Documentation in HTML format is available at https://www.semuconsulting.com/pygnssutils.

Contributions welcome - please refer to CONTRIBUTING.MD.

Bug reports and Feature requests - please use the templates provided. For general queries and advice, post a message to one of the pygnssutils Discussions channels.

---

<a name="installation">Installation</a>

pygnssutils is compatible with Python>=3.10.

In the following, python3 & pip refer to the Python 3 executables. You may need to substitute python for python3, depending on your particular environment (on Windows it's generally python). It is strongly recommended that the Python 3 binaries (\Scripts or /bin) and site_packages directories are included in your PATH (most standard Python 3 installation packages will do this automatically if you select the 'Add to PATH' option during installation).

The recommended way to install the latest version of pygnssutils is with pip:

python3 -m pip install --upgrade pygnssutils

If required, pygnssutils can also be installed into a virtual environment, e.g.:

python3 -m venv env
source env/bin/activate # (or env\Scripts\activate on Windows)
python3 -m pip install --upgrade pygnssutils

For Conda users, pygnssutils is also available from conda forge:

conda install -c conda-forge pygnssutils

---

<a name="gnssreader">GNSSReader class</a>

class pygnssutils.gnssreader.GNSSReader(**kwargs)

GNSSReader is an amalgamation of the individual *Reader classes from the parser libraries listed above, utilising the same input arguments (protfilter, quitonerror, etc). It allows the user to seamlessly stream any of NMEA, UBX, SBF, UNI, QGC, RTCM3 and SPARTN message protocols concurrently from a single GNSS binary data stream.

Refer to the Sphinx API documentation for further details.

---

<a name="gnssstreamer">GNSSStreamer and gnssstreamer CLI (formerly gnssdump)</a>

class pygnssutils.gnssstreamer.GNSSStreamer(**kwargs)

gnssstreamer (formerly gnssdump) is a command line utility for concurrent bidirectional communication with a GNSS datastream - typically a GNSS receiver. It supports NMEA, UBX, SBF, UNI, QGC, RTCM3, SPARTN, NTRIP and MQTT protocols - individual protocols can be filtered via the protfilter arguments.

• The CLI utility can acquire data from any one of the following sources:

  • port: serial port e.g. COM3 or /dev/ttyACM1 (can specify --baudrate and --timeout)
  • filename: fully qualified path to binary input file e.g. /logs/logfile.bin
  • socket: socket e.g. 192.168.0.72:50007 (port must be specified)
  • stream: any other instance of a stream class which implements a read(n) -> bytes method

• It offers a variety of data filtering options based on message protocol, identity and periodicity via the --protfilter and --msgfilter arguments e.g. --protfilter 2 --msgfilter NAV-PVT(10) will filter output to the UBX protocol and NAV-PVT message type and will limit NAV-PVT periodicity to 1 every 10 seconds.

• It can format the filtered data via the --format argument:

  • 1 = parsed as object (e.g. NMEAMessage, UBXMessage) (default)
  • 2 = raw binary
  • 4 = hexadecimal string
  • 8 = tabulated hexadecimal
  • 16 = parsed as string
  • 32 = JSON

  or any OR'd combination thereof - e.g. --format 9 outputs the parsed version of a UBX message alongside its tabular hexadecimal representation.

• It can output the formatted and filtered data to a variety of output channels via the --clioutput and --output arguments:

  • 0 = stdout (terminal) (default)
  • 1 = file
  • 2 = serial
  • 3 = TCP socket server
  • 4 = Python lambda expression (which could, for example, be used to format the output into a user-defined f-string).

• It can also support a variety of concurrent input data sources via the --cliinput and --input arguments:

  • 0 = none (default)
  • 1 = RTK NTRIP RTCM caster
  • 2 = RTK NTRIP SPARTN caster
  • 3 = RTK MQTT SPARTN source (see gnssmqttclient for MQTT client configuration details)
  • 4 = serial port
  • 5 = binary file.

  Data from these sources will be uploaded to the GNSS datastream provided this datastream supports write() operations. A principal use case for this input facility is to monitor a GNSS receiver's output while processing incoming RTK correction data via pygnssutil's in-built NTRIP or MQTT (SPARTN IP) clients