Package: pygnssutils
pygnssutilsCurrent Status|Installation|gnssdump CLI|gnssserver CLI|gnssntripclient CLI|gnssmqttclient CLI|ubxsetrate CLI|Graphical Client|Author & Licensepygnssutils is an original series of GNSS CLI utilities and Python classes built around the following core libraries from the same stable:pyubx2- UBX parsing and generation library, which in turn utilises:pynmeagps- NMEA parsing and generation librarypyrtcm- RTCM3 parsing librarypyspartn- SPARTN parsing libraryThe utilities provided by pygnssutils comprise:GNSSStreamerclass and its associatedgnssdumpCLI utility. This is essentially a configurable input/output wrapper around thepyubx2.UBXReaderclass with flexible message formatting and filtering options for NMEA, UBX and RTCM3 protocols.GNSSSocketServerclass and its associatedgnssserverCLI utility. This implements a TCP Socket Server for GNSS data streams which is also capable of being run as a simple NTRIP Server.GNSSNTRIPClientclass and its associatedgnssntripclientCLI utility. This implements
a simple NTRIP Client which receives RTCM3 correction data from an NTRIP Server and (optionally) sends this to a
designated output stream.GNSSMQTTClientclass and its associatedgnssmqttclientCLI utility. This implements
a simple SPARTN IP (MQTT) Client which receives SPARTN correction data from an SPARTN IP location service sends this to a
designated output stream.ubxsaveCLI utility. This saves a complete set of configuration data from any Generation 9+ u-blox device (e.g. NEO-M9N or ZED-F9P) to a file. The file can then be reloaded to any compatible device using theubxloadutility.ubxloadCLI utility. This reads a file containing binary configuration data and loads it into any compatible Generation 9+ u-blox device (e.g. NEO-M9N or ZED-F9P).ubxsetrateCLI utility. A simple utility which sets NMEA or UBX message rates on u-blox GNSS receivers.The pygnssutils homepage is located athttps://github.com/semuconsulting/pygnssutils.Current StatusSphinx API Documentation in HTML format is available athttps://www.semuconsulting.com/pygnssutils.Contributions welcome - please refer toCONTRIBUTING.MD.Bug reportsandFeature requests- please use the templates provided. For general queries and advice, post a message to one of thepygnssutils Discussionschannels.Installationpygnssutilsis compatible with Python >=3.8. It is recommended that the Python 3 scripts (bin) folder is in your PATH.In the following,python3&piprefer to the Python 3 executables. You may need to typepythonorpip3, depending on your particular environment.The recommended way to install the latest version ofpygnssutilsis withpip:python3-mpipinstall--upgradepygnssutilsIf required,pygnssutilscan also be installed into a virtual environment, e.g.:python3-mpipinstall--user--upgradevirtualenv
python3-mvirtualenvenvsourceenv/bin/activate(orenv\Scripts\activateonWindows)(env)python3-mpipinstall--upgradepygnssutils
...
deactivateForCondausers,pygnssutilsis also available fromconda forge:condainstall-cconda-forgepygnssutilsGNSSStreamer and gnssdump CLIclass pygnssutils.gnssdump.GNSSStreamer(**kwargs)GNSSStreameris essentially a configurable input/output wrapper around thepyubx2.UBXReaderclass. It supports a variety of input streams (including serial, file and socket) and outputs either to stdout (terminal), to an output file or to a custom output handler. The custom output handler can be a writeable output medium (serial, file, socket or queue) or an evaluable Python expression (e.g. lambda function).The utility can output data in a variety of formats; parsed (1), raw binary (2), hexadecimal string (4), tabulated hexadecimal (8), parsed as string (16), JSON (32), or any combination thereof. You could, for example, output the parsed version of a UBX message alongside its tabular hexadecimal representation.Any one of the following data stream specifiers must be provided:port: serial port e.g.COM3or/dev/ttyACM1filename: fully qualified path to binary input file e.g./logs/logfile.binsocket: 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 methodFor help and full list of optional arguments, type:>gnssdump-hRefer to theSphinx API documentationfor further details.CLI Usage:Assuming the Python 3 scripts (bin) directory is in your PATH, the CLI utility may be invoked from the shell thus:Serial input example (with simple external output handler):>gnssdump--port/dev/ttyACM1--baudrate9600--timeout5--quitonerror1--protfilter2--msgfilterNAV-PVT--outputhandler"lambda msg: print(f'lat: {msg.lat}, lon: {msg.lon}')"2022-06-2319:23:12.052109:ParsingGNSSdatastreamfromserial:Serial<id=0x10fe8f100,open=True>(port='/dev/ttyACM1',baudrate=9600,bytesize=8,parity='N',stopbits=1,timeout=5,xonxoff=False,rtscts=False,dsrdtr=False)...

lat:51.352179,lon:-2.130762
lat:51.352155,lon:-2.130751File input example (in parsed and tabulated hexadecimal formats):>gnssdump--filenamepygpsdata.log--quitonerror2--format92022-07-0110:47:28.097706:ParsingGNSSdatastreamfromfile:<_io.BufferedReadername='pygpsdata.log'>...

<UBX(NAV-STATUS,iTOW=09:47:37,gpsFix=3,gpsFixOk=1,diffSoln=0,wknSet=1,towSet=1,diffCorr=0,carrSolnValid=1,mapMatching=0,psmState=0,spoofDetState=1,carrSoln=0,ttff=33377,msss=1912382)>000:b56201031000f80cda1b03dd02086182|b'\xb5b\x01\x03\x10\x00\xf8\x0c\xda\x1b\x03\xdd\x02\x08a\x82'|016:00003e2e1d00633d|b'\x00\x00>.\x1d\x00c='|<UBX(NAV-DOP,iTOW=09:47:37,gDOP=1.55,pDOP=1.32,tDOP=0.8,vDOP=1.11,hDOP=0.72,nDOP=0.59,eDOP=0.42)>000:b56201041200f80cda1b9b0084005000|b'\xb5b\x01\x04\x12\x00\xf8\x0c\xda\x1b\x9b\x00\x84\x00P\x00'|016:6f0048003b002a009b75|b'o\x00H\x00;\x00*\x00\x9bu'|<UBX(NAV-TIMEGPS,iTOW=09:47:37,fTOW=422082,week=2216,leapS=18,towValid=1,weekValid=1,leapSValid=1,tAcc=10)>000:b56201201000f80cda1bc2700600a808|b'\xb5b\x01 \x10\x00\xf8\x0c\xda\x1b\xc2p\x06\x00\xa8\x08'|016:12070a0000003566|b'\x12\x07\n\x00\x00\x005f'|Socket input example (in JSON format):>gnssdump--socket192.168.0.20:50010--format32--msgfilter10872022-06-2319:27:10.103332:ParsingGNSSdatastreamfrom:<socket.socketfd=3,family=AddressFamily.AF_INET,type=SocketKind.SOCK_STREAM,proto=0,laddr=('127.0.0.1',57399),raddr=('127.0.0.1',50010)>...{"GNSS_Messages: [{"class": "<class'pyrtcm.rtcmmessage.RTCMMessage'>", "identity": "1087", "payload": {"DF002": 1087, "DF003": 0, "GNSSEpoch": 738154640, "DF393": 1, "DF409": 0, "DF001_7": 0, "DF411": 0, "DF412": 0, "DF417": 0, "DF418": 0, "DF394": 1152921504606846976, "NSat": 1, "DF395": 1073741824, "NSig": 1, "DF396": 1, "DF405_01": 0.00050994, "DF406_01": 0.00194752, "DF407_01": 102, "DF420_01": 0, "DF408_01": 0, "DF404_01": 0.5118}},...]}Output file example (this filters unwanted UBX config & debug messages from a u-center .ubx file):>gnssdump--filenameCOM6__9600_220623_093412.ubx--protfilter1--format2--verbosity0--outfileCOM6__9600_220623_093412_filtered.ubxGNSSSocketServer and gnssserver CLIclass pygnssutils.gnssserver.GNSSSocketServer(**kwargs)GNSSSocketServeris essentially a wrapper around theGNSSStreamerandSocketServerclasses (the latter based on the native PythonThreadingTCPServerframework) which uses queues to transport data between the two classes.CLI Usage - Default Mode:In its default configuration (ntripmode=0)gnssserveracts as an open, unauthenticated CLI TCP socket server, reading the binary data stream from a host-connected GNSS receiver and broadcasting the data to any local or remote TCP socket client capable of parsing binary GNSS data.It supports most ofgnssdump's formatting capabilities and could be configured to output a variety of non-binary formats (including, for example, JSON or hexadecimal), but the client software would need to be capable of parsing data in such formats.Assuming the Python 3 scripts (bin) directory is in your PATH, the CLI utility may be invoked from the shell thus:>gnssserver--inport"/dev/tty.usbmodem14301"--baudrate115200--hostip192.168.0.20--outport6000Startingserver(typeCTRL-Ctostop)...
Startinginputthread,readingfrom/dev/tty.usbmodem141301...

ParsingGNSSdatastreamfrom:Serial<id=0x1063647f0,open=True>(port='/dev/tty.usbmodem141301',baudrate=115200,bytesize=8,parity='N',stopbits=1,timeout=3,xonxoff=False,rtscts=False,dsrdtr=False)...

Startingoutputthread,broadcastingon192.168.0.20:6000...
Client('192.168.0.56',59565)hasconnected.Totalclients:1Client('192.168.0.34',59566)hasconnected.Totalclients:2Client('192.168.0.41',59567)hasconnected.Totalclients:3Client('192.168.0.56',59565)hasdisconnected.Totalclients:2gnssservercan be run as a daemon process (or even a service) but note that abrupt termination (i.e. without invoking the internalserver.shutdown()method) may result in the designated TCP socket port being unavailable for a short period - this is operating system dependant.For help and full list of optional arguments, type:>gnssserver-hRefer to theSphinx API documentationfor further details.CLI Usage - NTRIP Mode:gnssservercan also be configured to act as a single-mountpoint NTRIP Server/Caster (ntripmode=1), broadcasting RTCM3 RTK correction data to any authenticated NTRIP client on the standard 2101 port using the mountpoint namepygnssutils(NB: to use with standard NTRIP clients, output format must be set to binary (2) - this is the default, so the argument can be omitted):>gnssserver--inport"/dev/tty.usbmodem14101"--hostip192.168.0.20--outport2101--ntripmode1--protfilter4--format2--ntripusermyuser--ntrippasswordmypasswordNOTE THATthis configuration is predicated on the host-connected receiver being an RTK-capable device (e.g. the u-blox ZED-F9P) operating in 'Base Station' mode (either 'SURVEY_IN' or 'FIXED') and outputting the requisite RTCM3 RTK correction messages (1005, 1077, 1087, 1097, 1127, 1230). NTRIP server login credentials are set via command line arguments or environment variablesPYGPSCLIENT_USERandPYGPSCLIENT_PASSWORD.Clientsgnssserverwill work with any client capable of parsing binary GNSS data from a TCP socket. Suitable clients include,but are not limited to:pygnssutils'sgnssdumpcli utility invoked thus:>gnssdump--sockethostip:outport(in NTRIP mode) pygnssutil'sgnssntripclientcli utility invoked thus:>gnssntripclient-Shostip-P2101-Mpygnssutils--ntripusermyuser--ntrippasswordmypasswordThe PyGPSClient GUI application.GNSSNTRIPClient and gnssntripclient CLIclass pygnssutils.gnssntripclient.GNSSNTRIPClient(app=None, **kwargs)TheGNSSNTRIPClientclass provides a basic NTRIP Client capability and forms the basis of agnssntripclientCLI utility. It receives RTCM3 correction data from an NTRIP server and (optionally) sends this to a designated output stream. NTRIP server login credentials are set via command line arguments or environment variablesPYGPSCLIENT_USERandPYGPSCLIENT_PASSWORD.CLI Usage:Assuming the Python 3 scripts (bin) directory is in your PATH, the CLI utility may be invoked from the shell thus:To retrieve the sourcetable and determine the closest available mountpoint to the reference lat/lon, leave the mountpoint argument blank (the port defaults to 2101):>gnssntripclient--serverrtk2go.com--ggamode1--reflat37.23--reflon115.81--ntripusermyuser--ntrippasswordmypassword2022-06-0320:15:54.510294:Closestmountpointtoreferencelocation37.23,-115.81=WW6RY,351.51km

Completesourcetablefollows...['AGSSIAAP','Acheres','RTCM 3.0','1004(1),1006(13),1012(1),1033(31)','2','GPS+GLO','SNIP','FRA','48.97','2.17','1','0','sNTRIP','none','N','N','2540','']...To retrieve correction data from a designated mountpoint (this will send NMEA GGA position sentences to the server at intervals of 60 seconds, based on the supplied reference lat/lon):>gnssntripclient--serverrtk2go.com--ggamode1--reflat37.23--reflon-115.81--mountpointUFOSRUS--ggainterval60--ntripusermyuser--ntrippasswordmypassword2022-06-0311:55:10.305870:<RTCM(1077,DF002=1077,DF003=0,GNSSEpoch=471328000,DF393=1,...For help and full list of optional arguments, type:>gnssntripclient-hRefer to theSphinx API documentationfor further details.GNSSMQTTClient and gnssmqttclient CLIclass pygnssutils.gnssmqttclient.GNSSMQTTClient(app=None, **kwargs)TheGNSSMQTTClientclass provides a basic SPARTN IP (MQTT) Client capability and forms the basis of agnssmqttclientCLI utility. It receives RTK correction data from a SPARTN IP (MQTT) location service (e.g. the u-blox / Thingstream PointPerfect service) and (optionally) sends this to a designated output stream.CLI Usage:Theclientidprovided by the location service may be set as environment variableMQTTCLIENTID. If this environment variable is set and the TLS certificate (*.crt) and key (*.pem) files provided by the location service are placed in the user'sHOMEdirectory, the utility can use these as default settings and may be invoked without any arguments.Assuming the Python 3 scripts (bin) directory is in your PATH, the CLI utility may be invoked from the shell thus (press CTRL-C to terminate):>gnssmqttclient2023-02-2318:40:41.552070:StartingMQTTclientwitharguments{'server':'pp.services.u-blox.com','port':8883,'clientid':'{your-client-id}','region':'eu','topic_ip':1,'topic_mga':1,'topic_key':1,'tlscrt':'/Users/{your-user}/device-{your-clientid}-pp-cert.crt','tlskey':'/Users/{your-user}/device-{your-client-id}-pp-key.pem'},outputNone.
<UBX(RXM-SPARTN-KEY,version=1,numKeys=2,...)>
<UBX(MGA-INI-TIME-UTC,type=16,etc...)>
<UBX(MGA-GPS-EPH,type=1,version=0,...)>
...
<SPARTN(SPARTN-1X-GAD,msgType=2,nData=191...)>
<SPARTN(SPARTN-1X-OCB-GPS,msgType=0,nData=44...)>
...For help and full list of optional arguments, type:>gnssmqttclient-hubxsave CLIGENERATION 9+ DEVICES ONLY (e.g. NEO-M9N or ZED-F9P)class pygnssutils.ubxconfig.UBXSaver(file, stream, **kwargs)CLI utility which saves Generation 9+ UBX device configuration data to a file.ubxsavepolls 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 theubxloadutility) to restore the saved configuration.The CFG-VALSET commands are stored as a single transaction. 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 specifiedwaittime. 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.CLI Usage:>ubxsave--port/dev/ttyACM1--baudrate9600--timeout0.02--outfileubxconfig.ubx--verbosity1For help and full list of optional arguments, type:>ubxsave-hubxload CLIGENERATION 9+ DEVICES ONLY (e.g. NEO-M9N or ZED-F9P)class pygnssutils.ubxconfig.UBXLoader(file, stream, **kwargs)CLI utility which loads UBX configuration (CFG-VALSET) data from a binary file (e.g. one created by theubxsaveutility) and loads it into the volatile memory (RAM) of a compatible Generation 9+ UBX device via its serial port. It then awaits acknowledgements to this data and reports any errors.CLI Usage:>ubxload--port/dev/ttyACM1--baudrate9600--timeout0.05--infileubxconfig.ubx--verbosity1For help and full list of optional arguments, type:>ubxload-hubxsetrate CLIclass pygnssutils.ubxconfig.UBXSetRate(**kwargs)A simple CLI utility to set NMEA or UBX message rates on u-blox receivers via a serial port.CLI Usage:Assuming the Python 3 scripts (bin) directory is in your PATH, the CLI utility may be invoked from the shell thus:This example sets the UBX NAV-HPPOSLLH message rate to 1:>ubxsetrate--port/dev/ttyACM0--baudrate38400--msgClass0x01--msgID0x14--rate1Openingserialport/dev/ttyACM0@38400baud...

Sendingconfigurationmessage<UBX(CFG-MSG,msgClass=NAV,msgID=NAV-HPPOSLLH,rateDDC=1,rateUART1=1,rateUART2=1,rateUSB=1,rateSPI=1,reserved=0)>...

Configurationmessagesent.Refer topyubx2 documentationfor availablemsgClassandmsgIDvalues.msgClassandmsgIDcan be specified in either integer or hexadecimal formats.Alternatively, themsgClasskeyword can be set to one of the following group values (in which case themsgIDkeyword can be omitted):"allubx" - set rate for all available UBX NAV messages"minubx" - set rate for a minimum set of UBX NAV messages (NAV-PVT, NAV-SAT)"allnmea" - set rate for all available NMEA messages"minnmea" - set rate for a minimum set of NMEA messages (GGA, GSA, GSV, RMC, VTG)For help and full list of optional arguments, type:>ubxsetrate-hGraphical ClientA python/tkinter graphical GPS client which utilises thepygnssutilslibrary and supports NMEA, UBX, RTCM3 and NTRIP protocols is available at:https://github.com/semuconsulting/PyGPSClientAuthor & License Informationsemuadmin@semuconsulting.compygnssutilsis maintained entirely by unpaid volunteers. It receives no funding from advertising or corporate sponsorship. If you find the library useful, a small donation would be greatly appreciated!