pygpsclient 1.3.8

PyGPSClient GNSS/GPS Graphical Client

PyGPSClient

Current Status | Features | How to Use | UBX Configuration | NTRIP Client | Socket Server / NTRIP Caster | Installation | Mapquest API Key | User-defined Presets | Known Issues | Glossary of Terms | License | Author Information

PyGPSClient is a multi-platform graphical GNSS/GPS testing, diagnostic and UBX © (u-blox ™) device configuration application written entirely in Python and tkinter.

Screenshot showing mixed-protocol stream from u-blox ZED-F9P receiver, using PyGPSClient's NTRIP Client to achieve >= 1cm accuracy

The application can be installed using the standard pip Python package manager - see installation instructions below.

---

Current Status

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

Contributions welcome - please refer to CONTRIBUTING.MD.

Bug reports and Feature requests - please use the templates provided.

This is an independent project and we have no affiliation whatsoever with u-blox.

---

Features

1. Runs on any platform which supports a Python 3 interpreter (>=3.7) and tkinter (>=8.6) GUI framework, including Windows, MacOS, Linux and Raspberry Pi OS.
2. Supports NMEA, UBX, RTCM3 and NTRIP protocols.
3. Capable of reading from a variety of GNSS data streams: Serial (USB / UART), Socket (TCP / UDP) and binary datalog file.
4. Configurable GUI with selectable and resizeable widgets.
5. Expandable banner widget showing key navigation information.
6. Serial console widget showing data stream in either parsed, binary or hexadecimal format.
7. User-configurable color tagging of selected console entries.
8. Skyview widget showing current satellite visibility and position (elevation / azimuth). Satellite icon borders are colour-coded to distinguish between different GNSS constellations.
9. Graphview widget showing current satellite reception (signal-to-noise ratio).
10. Mapview widget with location marker, showing either a static Mercator world map, or an optional dynamic web-based map downloaded via a MapQuest API (requires an Internet connection and free MapQuest API Key).
11. Data logging in parsed, binary, hexadecimal string and tabulated hexadecimal formats (NB. only binary datalogs can be re-read by PyGPSClient's parser).
12. Track recording in GPX format.
13. UBX Configuration Dialog, with the ability to send a variety of UBX CFG configuration commands to u-blox GNSS devices. This includes the facility to add user-defined commands or command sequences - see instructions under user-defined presets below. While not intended to be a direct replacement, the application supports much of the UBX configuration functionality in u-blox's Windows-only u-center © tool.
14. NTRIP Client (differential GPS enhancement) facility with the ability to connect to a specified NTRIP server (caster), parse the incoming RTCM3 data and feed this data to a compatible GNSS device (requires an Internet connection and access to a suitable NTRIP caster).
15. Socket Server / NTRIP Caster with two modes of operation: (a) open, unauthenticated Socket Server or (b) NTRIP Caster.

---

How to Use

• To connect to a listed serial device, select the device from the listbox, set the appropriate serial connection parameters and click . The application will endeavour to pre-select a recognised GNSS/GPS device but this is platform and device dependent. Press the button to refresh the list of connected devices at any point. Rate bps is typically the only setting that might need adjusting, but tweaking the timeout setting may improve performance on certain platforms.
• To connect to a TCP or UDP socket, enter the server URL and port, select the protocol (defaults to TCP) and click .
• To stream from a previously-saved binary datalog file, click and select the file. PyGPSClient datalog files will be named e.g. pygpsdata-20220427114802.log, but any binary dump of an GNSS receiver output is acceptable.
• To disconnect from the data stream, click .
• To display the UBX Configuration Dialog (only functional when connected to a UBX GNSS device via serial port), click , or go to Menu..Options.
• To display the NTRIP Client Configuration Dialog (requires internet connection), click , or go to Menu..Options.
• To expand or collapse the banner or serial port configuration widgets, click the / buttons.
• To show or hide the various widgets, go to Menu..View and click on the relevant hide/show option.
• Protocols Shown - Select which protocols to display; NMEA, UBX and/or RTCM3 (NB: this only changes the displayed protocols - to change the actual protocols output by the receiver, use the CFG-PRT command).
• Console Display - Select from parsed, binary or hexadecimal formats.
• Tags - Turn console color tagging on or off. User-configurable color tags are loaded from a file "colortags" (lower case, no extension) in the user's home directory - see example provided. NB: color tagging does impose a small performance overhead - turning it off will improve console response times at very high transaction rates.
• Degrees Format and Units - Change the displayed degree and unit formats.
• Zoom - Change the web map scale (any change will take effect at the next map refresh, indicated by a small timer icon at the top left of the panel).
• Show Legend - Turn the graph legend on or off.
• Show Unused Satellites - Include or exclude satellites that are not used in the navigation solution (e.g. because their signal level is too low) from the graph and sky view panels.
• DataLogging - Turn Data logging in the selected format on or off. You will be prompted to select the directory into which timestamped log files are saved (NB. only binary datalogs can be re-read by PyGPSClient's parser).
• GPX Track - Turn track recording (in GPX format) on or off. You will be prompted to select the directory into which timestamped track files are saved.
• Socket / NTRIP Server - Turn Socket / NTRIP Server on or off.
• UBX Configuration - Opens UBX configuration panel (only functional with u-blox devices).
• NTRIP Client Configuration - Opens NTRIP Client configuration panel.

---

UBX Configuration Facilities

The UBX Configuration Dialog currently supports the following UBX configuration panels:

1. Version panel shows current device hardware/firmware versions (via MON-VER and MON-HW polls).
2. Protocol Configuration panel (CFG-PRT) sets baud rate and inbound/outbound protocols across all available ports.
3. Solution Rate panel (CFG-RATE) sets navigation solution interval in ms (e.g. 1000 = 1/second) and measurement ratio (ratio between the number of measurements and the number of navigation solutions, e.g. 5 = five measurements per navigation solution).
4. For each of the panels above, clicking anywhere in the widget background will refresh the displayed information with the current configuration.
5. Message Rate panel (CFG-MSG) sets message rates per port for UBX and NMEA messages. Message rate is relative to navigation solution frequency e.g. a message rate of '4' means 'every 4th navigation solution'.
6. Other configuration panel (CFG-*) providing structured updates for a range of legacy CFG- configuration commands for pre-Generation 9+ devices. Note: 'X' (byte) type attributes can be entered as integers or hexadecimal strings e.g. 522125312 or 0x1f1f0000.
7. Configuration Interface widget (CFG-VALSET, CFG-VALDEL and CFG-VALGET) queries and sets configuration for Generation 9+ devices e.g. NEO-M9, ZED-F9P, etc.
8. Preset Commands widget supports a variety of preset and user-defined commands - see user defined presets

An icon to the right of each 'SEND' button indicates the confirmation status of the configuration command; (pending i.e. awaiting confirmation , confirmed , warning or unknown i.e. no confirmation available ).

Note:

• Poll and Acknowledgement responses can take several seconds at high message transmission rates, or be discarded altogether if the device's transmit buffer is full (txbuff-alloc error). To ensure timely responses, try increasing the baud rate and/or temporarily reducing transmitted message rates using the configuration commands provided.
• A warning icon (typically accompanied by an ACK-NAK response) is usually an indication that one or more of the commands sent is not supported by your receiver.

---

NTRIP Client Facilities

To use:

1. Enter the required NTRIP server URL (or IP address) and port (defaults to 2101). For services which require authorisation, enter your login username and password.
2. To retrieve the sourcetable, leave the mountpoint field blank and click connect (response may take a few seconds). The required mountpoint may then be selected from the list, or entered manually. Where possible, PyGPSClient will automatically identify the closest mountpoint to the current location.
3. For NTRIP services which require client position data via NMEA GGA sentences, select the appropriate sentence transmission interval in seconds. The default is 'None' (no GGA sentences sent). A value of 10 or 60 seconds is typical.
4. If GGA sentence transmission is enabled, GGA sentences can either be populated from live navigation data (assuming a receiver is connected and outputting valid position data) or from manual settings entered in the NTRIP configuration panel (latitude, longitude, elevation and separation - all four manual settings must be provided).
5. To connect to the NTRIP server, click . To disconnect, click .
6. If NTRIP data is being successfully received, the banner 'dgps:' status indicator should change to 'YES' and indicate the age and reference station of the correction data (where available) . Note that DGPS status is typically maintained for up to 60 seconds after loss of correction signal.
7. Some NTRIP services may output RTCM3 correction messages at a high rate, flooding the GUI console display. To suppress these messages in the console, de-select the 'RTCM' option in 'Protocols Shown' - the RTCM3 messages will continue to be processed in the background.

Below is a illustrative NTRIP DGPS data log, showing:

• Outgoing NMEA GPGGA (client position) sentence.
• Incoming RTCM3 correction messages; in this case - 1006 (Ref station ARP (DF003=2690) with antenna height), 1008 (Antenna descriptor), 1033 (Receiver descriptor), 1075 (GPS MSM5), 1085 (GLONASS MSM5), 1095 (Galileo MSM5), 1125 (BeiDou MSM5) and 1230 (GLONASS Code-Phase Biases)
• Corresponding UBX RXM-RTCM acknowledgements generated by the u-blox ZED-F9P receiver, confirming message type, valid checksum (crcFailed=0), successful use (msgUsed=2) and reference station ARP (refStation=2690).

NB: Please respect the terms and conditions of any remote NTRIP service used with this facility. For testing or evaluation purposes, consider deploying a local SNIP LITE server. Inappropriate use of an NTRIP service may result in your account being blocked.

---

Socket Server / NTRIP Caster Facilities

The Socket Server / NTRIP Caster facility is capable of operating in either of two modes;

1. SOCKET SERVER - an open, unauthenticated TCP socket server available to any socket client including, for example, another instance of PyGPSClient or gnssdump (CLI utility installed with pygnssutils) running on another machine. In this mode it will broadcast the host's currently connected GNSS data stream (NMEA, UBX, RTCM3). The default port is 50010.
2. NTRIP CASTER - a simple implementation of an authenticated NTRIP caster available to any NTRIP client including, for example, the PyGPSClient NTRIP Client facility or gnssntripclient (CLI utility installed with pygnssutils). Login credentials for the NTRIP caster are set via host environment variables PYGPSCLIENT_USER and PYGPSCLIENT_PASSWORD. The default port is 2101. See prerequisites below.

The server/caster binds to the host address '0.0.0.0' i.e. all available IP addresses on the host machine. It may be necessary to add a firewall rule on the host and/or client machine to allow remote traffic on the specified port.

A label on the settings panel indicates the number of connected clients, and the server/caster status is indicated in the topmost banner: closed: , open with no clients: , open with clients: .

NB: Running in NTRIP caster mode is predicated on the host being connected to an RTK-compatible GNSS receiver operating in Base Station mode (either SURVEY_IN or FIXED) and outputting the requisite RTCM3 message types (1005, 1077, 1087, 1097, 1127 and 1230). In the case of the u-blox ZED-F9P receiver, for example, this is set using the CFG-TMODE* and CFG-MSGOUT-RTCM* configuration interface parameters available via the UBX Configuration panel - refer to the Integration Manual and Interface Specification for further details. PyGPSClient does not configure the receiver automatically, though an example configuration script for the u-blox ZED-F9P receiver may be found at /examples/f9p_basestation.py. This script can also be used to generate user-defined preset command strings suitable for copying and pasting into a ubxpresets file (see User Defined Presets below).

---

Installation

In the following, python3 & pip refer to the Python 3 executables. You may need to type python or pip3, depending on your particular environment. It is also recommended that the Python 3 scripts (bin) and site_packages directories are included in your PATH (many standard Python 3 installation packages will do this automatically).

Platform Dependencies

On Windows and MacOS, pip, tkinter and the necessary imaging libraries are generally packaged with Python 3. On some Linux distributions like Ubuntu 18+ and Raspberry Pi OS, they may need to be installed separately, e.g.:

sudo apt install python3-pip python3-tk python3-pil python3-pil.imagetk

NB: If you're compiling the latest version of Python 3 from source, you may also need to install tk-dev (or a similarly named package e.g. tk-devel) first. Refer to http://wiki.python.org/moin/TkInter for further details.

sudo apt install tk-dev

Ideally the platform screen resolution will be at least 1400 x 900, though the main application window is resizeable.

User Privileges

To access the serial port on most Linux platforms, you will need to be a member of the tty and/or dialout groups. Other than this, no special privileges are required.

usermod -a -G tty myuser

1. Install using pip

The easiest way to install the latest version of PyGPSClient is with pip:

python3 -m pip install --upgrade PyGPSClient

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

python3 -m pip install --user --upgrade virtualenv
python3 -m virtualenv env
source env/bin/activate (or env\Scripts\activate on Windows)
(env) python3 -m pip install --upgrade PyGPSClient
...
deactivate

To run the application, if the Python 3 scripts (bin) directory is in your PATH, simply type (all lowercase):

pygpsclient

If desired, you can add a shortcut to this command to your desktop or favourites menu.

Alternatively, if the Python 3 site_packages are in your PATH, you can type (all lowercase):

python3 -m pygpsclient

NB: If the Python 3 scripts (bin) or site_packages directories are not in your PATH, you will need to add the fully-qualified path to pygpsclient in the commands above.

Tip: to find the site_packages location, type:

python3 -m pip show PyGPSClient

and look for the Location: entry in the response, e.g.

• Linux: Location: /home/username/.local/lib/python3.9/site-packages
• MacOS: Location: /Library/Frameworks/Python.framework/Versions/3.9/lib/python3.9/site-packages
• Windows: Location: c:\users\username\appdata\roaming\python\python39\lib\site-packages

Tip: To create an application launcher for linux distributions like Ubuntu, create a text file named pygpsclient.desktop with the following content (edited for your particular environment) and copy this to the /home/user/.local/share/applications folder, e.g.

[Desktop Entry]
Type=Application
Terminal=false
Name=PyGPSClient
Icon=/home/user/.local/lib/python3.9/site-packages/pygpsclient/resources/pygpsclient.ico
Exec=/home/user/.local/bin/pygpsclient

2. Manual installation

See requirements.txt.

The following Python libraries are required (these will be installed automatically if using pip to install PyGPSClient):

python3 -m pip install --upgrade pygnssutils pyserial Pillow requests

To install PyGPSClient manually, download and unzip this repository and run:

python3 -m /path_to_folder/foldername/pygpsclient

e.g. if you downloaded and unzipped to a folder named PyGPSClient-1.3.4, run:

python3 -m /path_to_folder/PyGPSClient-1.3.4/pygpsclient

---

MapQuest API Key

To use the optional dynamic web-based mapview facility, you need to request and install a MapQuest API key. The free edition of this API allows for up to 15,000 transactions/month (roughly 500/day) on a non-commercial basis. For this reason, the map refresh rate is intentionally limited to 1/minute* to avoid exceeding the free transaction limit under normal use. NB: this facility is not intended to be used for real time navigational purposes.

Once you have received the API key (a 32-character alphanumeric string), you can either:

1. create an environment variable named MQAPIKEY (all upper case) and set this to the API key value. It is recommended that this is a User variable rather than a System/Global variable.
2. copy it to a file named mqapikey (lower case, no extension) and place this file in the user's home directory.

*The web map refresh rate can be amended if required by changing the MAP_UPDATE_INTERVAL constant in globals.py.

---

User Defined Presets

The UBX Configuration Dialog includes the facility to send user-defined UBX configuration messages or message sequences to the receiver. These can be set up by adding appropriate comma-delimited message descriptions and payload definitions to a file named ubxpresets (lower case, no extension), and then placing this file in the user's home directory. The message definition comprises a free-format text description (avoid embedded commas) followed by one or more pyubx2 UBXMessage constructors, i.e.

1. message class as a string e.g. CFG (must be a valid class from pyubx2.UBX_CLASSES)
2. message id as a string e.g. CFG-MSG (must be a valid id from pyubx2.UBX_MSGIDS)
3. payload as a hexadecimal string e.g. f004010100010100 (leave blank for null payloads e.g. most POLL messages)
4. mode as an integer (1 = SET, 2 = POLL)

(payload as hex string can be obtained from a UBXMessage created using the pyubx2 library thus: msg.payload.hex())

Multiple commands can be concatenated on a single line. Illustrative examples are shown below:

Stop GNSS, CFG, CFG-RST, 00000800, 1
Start GNSS, CFG, CFG-RST, 00000900, 1
Enable NMEA UBX00 & UBX03 sentences, CFG, CFG-MSG, f100010100010100, 1, CFG, CFG-MSG, f103010100010100, 1
Poll NEO-9 UART1/2 baud rates, CFG, CFG-VALGET, 000000000100524001005340, 2
Poll NEO-9 Message Rates, CFG, CFG-VALGET, 00000000ffff9120, 2, CFG, CFG-VALGET, 00004000ffff9120, 2, CFG, CFG-VALGET, 00008000ffff9120, 2
Set ZED-F9P to Base Station Survey-In Mode (1m accuracy), CFG, CFG-VALSET, 000100008b00912001c002912001cf02912001d4029120011b03912001d902912001060391200111000340e8030000100003405a0000000100032001, 1
Set ZED-F9P to Base Station Survey-In Mode (1cm accuracy), CFG, CFG-VALSET, 000100008b00912001c002912001cf02912001d4029120011b03912001d9029120010603912001110003400a000000100003405a0000000100032001, 1
Poll Receiver Software Version, MON, MON-VER, , 2
Poll Datum, CFG, CFG-DAT, , 2
Poll GNSS config, CFG, CFG-GNSS, , 2
Poll NMEA config, CFG, CFG-NMEA, , 2
Poll Satellite-based Augmentation, CFG, CFG-SBAS, , 2
Poll Receiver Management, CFG, CFG-RXM, , 2
Poll Navigation Mode, CFG, CFG-NAV5, , 2
Poll Expert Navigation mode, CFG, CFG-NAVX5, , 2
Poll Geofencing, CFG, CFG-GEOFENCE, , 2
Poll Timepulse, CFG, CFG-TP5, , 2
Set NEO-M8T Timepulse to 1 Hz, CFG, CFG-TP5, 000100003200000001000000010000003200000032000000000000006f000000, 1
Set NEO-M8T Timepulse to 8 MHz, CFG, CFG-TP5, 000100003200000000127a0000127a003200000032000000000000006f000000, 1
Limit NMEA GNSS to GPS only, CFG, CFG-NMEA, 0040000276000000000000010000000000000000, 1
Limit NMEA GNSS to GLONASS only, CFG, CFG-NMEA, 0040000257000000000000010000000000000000, 1
Set NMEA GNSS to ALL, CFG, CFG-NMEA, 0040000200000000000000010000000000000000, 1
Limit UBX GNSS to GPS only, CFG, CFG-GNSS, 0020200700081000010001010101030000000101020408000000010103081000000001010400080000000103050003000000010506080E0000000101, 1
Limit UBX GNSS to GLONASS only, CFG, CFG-GNSS, 0020200700081000000001010101030000000101020408000000010103081000000001010400080000000103050003000000010506080E0001000101, 1
Set UBX GNSS to ALL, CFG, CFG-GNSS, 0020200700081000010001010101030001000101020408000000010103081000000001010400080000000103050003000100010506080E0001000101, 1
FORCE COLD RESTART !*** Expect ClearCommError ***!, CFG, CFG-RST, ffff0100, 1

---

Known Issues

As at May 2022, tkinter performance is noticeably slower on MacOS Monterey platforms (particularly M1/M2) than on Windows or Linux, though internal streamlining in PyGPSClient v1.3.2 went some way to mitigating the impact. The application is fully functional on MacOS but you may find some dialog load operations are relatively slow, particularly at high message rates. This may be resolved in a subsequent MacOS update, but in the meantime the impact can be minimised by:

1. Opening and closing the UBX or NTRIP configuration dialogs while the serial connection is closed.
2. Minimising incoming message rates while using the configuration facilities. The UBX Configuration facility offers presets for 'minimum NMEA messages' or 'minimum UBX messages'.
3. Temporarily disabling the console display of certain message protocols using the 'Protocols Shown' checkboxes.
4. Turning off color tagging.

---

Glossary of Terms

See also GNSS Positioning - A Reviser

• ACC - accuracy of location in real units (hacc - horizontal, vacc - vertical). Note that location accuracy is not directly provided via the standard NMEA message set, but is available from UBX messages e.g. NAV-POSLLH, NAV-PVT and some proprietary NMEA messages e.g. UBX00.
• BEI - BeiDou Navigation Satellite System.
• DOP - dilution of precision (pdop - overall position, hdop - horizontal, vdop - vertical).
• GAL - Galileo Satellite Navigation.
• GLO - GLONASS, Global Navigation Satellite System.
• GNSS - global navigation satellite system.
• GPS - Global Positioning System.
• IME - IMES, Indoor MEssaging System
• NTRIP - Networked Transport of RTCM via Internet Protocol
• PRN - pseudo-random noise number (code that each satellite transmits to differentiate itself from other satellites in the active constellation).
• QZS - QZSS, Quasi-Zenith Satellite System.
• RTCM(3) - RTCM 10403.n Differential GNSS Services standard.
• SBA - SBAS, Satellite-based Augmentation System.
• SIP - satellites used in position solution.
• SIV - satellites in view.
• SV(N) - space vehicle number (serial number assigned to each satellite).
• UTC - coordinated universal time.

---

License

BSD 3-Clause License

Copyright © 2020, SEMU Consulting All rights reserved.

Application icons from iconmonstr ©.

---

Author Information

[e-mail]

PyGPSClient is maintained entirely by unpaid volunteers. It receives no funding from advertising or corporate sponsorship. If you find the utility useful, a small donation would be greatly appreciated!