Package: pygpsclient
PyGPSClientCurrent Status|Installation|Instructions|UBX Configuration|NTRIP Client|SPARTN Client|Socket Server / NTRIP Caster|GPX Track Viewer|Mapquest API Key|User-defined Presets|CLI Utilities|License|Author InformationPyGPSClient is a free, open-source, multi-platform graphical GNSS/GPS testing, diagnostic and UBX © (u-blox ™) device configuration application written entirely in Python and tkinter.Runs on any platform which supports a Python 3 interpreter (>=3.8) and tkinter (>=8.6) GUI framework, including Windows, MacOS, Linux and Raspberry Pi OS.Supports NMEA, UBX, RTCM3, NTRIP and SPARTN protocols.Capable of reading from a variety of GNSS data streams: Serial (USB / UART), Socket (TCP / UDP), binary data stream (terminal or file capture) and u-center (*.ubx) recording.ProvidesNTRIPandSPARTNclient facilities.Can serve as anNTRIP base stationwith a compatible receiver (e.g. ZED-F9P).While not intended to be a direct replacement, the application supports most of the UBX configuration functionality in u-blox's Windows-onlyu-center ©tool (only public-domain features are supported).Screenshot showing mixed-protocol stream from u-blox ZED-F9P receiver, using PyGPSClient'sNTRIP Clientwith a base station 26km to the west to achieve better than 2cm accuracyThe application can be installed using the standardpipPython package manager - seeinstallation instructionsbelow.Current StatusThe PyGPSClient home page is atPyGPSClient. For a general overview of GNSS, DGPS, RTK, NTRIP and SPARTN technologies and terminology, refer toGNSS Positioning - A Reviser.Sphinx API Documentation in HTML format is available athttps://www.semuconsulting.com/pygpsclient.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 thePyGPSClient Discussionschannels.This is an independent project and we have no affiliation whatsoever with u-blox.InstructionsTo connect to a GNSS receiver via USB or UART port, 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 thebutton to refresh the list of connected devices at any point.Rate bps(baud rate) is typically the only setting that might need adjusting, but tweaking thetimeoutsetting may improve performance on certain platforms. TheMsg Modeparameter defaults toGETi.e., periodic or poll response messagesfroma receiver. If you wish to parse streams of command or poll messages being senttoa receiver, set theMsg ModetoSETorPOLL. An optional serial or socket stream inactivity timeout can also be set (in seconds; 0 = no timeout).A custom user-defined serial port can also be passed via the json configuration file setting"userport_s":, via environment variablePYGPSCLIENT_USERPORTor as a command line argument--userport. A special userport value of "ubxsimulator" invokes the experimentalpygnssutils.UBXSimulatorutility to emulate a GNSS NMEA/UBX serial stream.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-savedbinary datalog file, clickand select the file type (*.log, *.ubx, *.*) and path. PyGPSClient datalog files will be named e.g.pygpsdata-20220427114802.log, but any binary dump of an GNSS receiver output is acceptable, including*.ubxfiles produced by u-center.To disconnect from the data stream, click.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 theUBX Configuration Dialog).Position Format and Units - Change the displayed position (D.DD / D.M.S / D.M.MM / ECEF) and unit (metric/imperial) formats.Map Type - Select from "world", "map" or "sat" ("map" and "sat" types require an Internet connection and freeMapquest API Key).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.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.To save the current configuration to a file, go to File..Save Configuration.NB:NTRIP and SPARTN client settings must be uploaded to the client handler (by clicking connect) before saving.To load a saved configuration file, go to File..Load Configuration. The default configuration file location is$HOME/pygpsclient.json.NBAny active serial or RTK connection must be stopped before loading a new configuration.Socket Server / NTRIP Casterfacility with two modes of operation: (a) open, unauthenticated Socket Server or (b) NTRIP Caster (mountpoint =pygnssutils).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 adduser-defined commands or command sequences- see instructions underuser-defined presetsbelow. To display the UBX Configuration Dialog (only functional when connected to a UBX GNSS device via serial port), click, or go to Menu..Options..UBX Configuration Dialog.NTRIP Clientfacility with the ability to connect to a specified NTRIP caster, parse the incoming RTCM3 data and feed this data to a compatible GNSS receiver (requires an Internet connection and access to an NTRIP caster and local mountpoint). To display the NTRIP Client Configuration Dialog, click, or go to Menu..Options..NTRIP Configuration Dialog.SPARTN Clientfacility with the ability to configure an IP or L-Band SPARTN Correction source and SPARTN-compatible GNSS receiver (e.g. ZED-F9P) and pass the incoming correction data to the GNSS receiver (requires an Internet connection and access to a SPARTN location service). To display the SPARTN Client Configuration Dialog, click, or go to Menu..Options..SPARTN Configuration Dialog.GPX Track Viewerutility with elevation and speed profiles and track metadata (requires an Internet connection and freeMapQuest API Key). To display the GPX Track viewer, go to Menu..Options..GPX Track Viewer.User-selectable 'widgets'To show or hide the various widgets, go to Menu..View and click on the relevant hide/show option.Expandable banner showing key navigation status information based on messages received from receiver. To expand or collapse the banner or serial port configuration widgets, click the/buttons.NB: some fields (e.g. hdop/vdop, hacc/vacc) are only available from proprietary NMEA or UBX messages and may not be output by default. The minimum messages required to populate all available fields are: NMEA: GGA, GSA, GSV, RMC, UBX00 (proprietary); UBX: NAV-DOP, NAV-PVT, NAV_SATConfigurable serial console widget showing incoming GNSS, NTRIP and SPARTN data streams in either parsed, binary or tabular hexadecimal formats. Supports user-configurable color tagging of selected strings for easy identification. Color tags are loaded from the"colortag_b":value (0= disable,1= enable) and"colortags_l":list ([string, color]pairs) in your json configuration file (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.Skyview widget showing current satellite visibility and position (elevation / azimuth). Satellite icon borders are colour-coded to distinguish between different GNSS constellations. For consistency between NMEA and UBX data sources, will display GLONASS NMEA SVID (65-96) rather than slot (1-24).Graphview widget showing current satellite reception (carrier-to-noise ratio or cnr). Double-click to toggle legend.Map widget with various modes of display. Map Type = 'world': a static offline Mercator world map showing current global location.Map Type = 'custom': one or more user-defined custom offline maps can be imported by setting theusermaps_lfield in the json configuration file. Theusermaps_lsetting represents a list of map paths and bounding boxes in the format ["path to map image", [top left lat, top left lon, bottom right lat, bottom right lon]] - seeexample configuration file. Map images must be asupported formatand use a standard WGS84 Web Mercator projection e.g. EPSG:4326. A utilitygeoref.pyis provided in the \examples folder which automatically generates the necessary calibration settings for one or more georeferenced image files e.g. geoTIFF.Map Type = 'map' or 'sat': Dynamic, online web map or satellite image via MapQuest API (requires an Internet connection and freeMapquest API Key). Left Click +/- to zoom in or out. Right click +/- to zoom in or out to maximum extent. By default, the web map will automatically refresh every 60 seconds (indicated by a small timer icon at the top left). The default refresh rate can be amended by changing the"mapupdateinterval_n":value in your json configuration file, butNBthe facility is not intended to be used for real-time navigation. Double-click anywhere in the map to immediately refresh.Spectrum widget showing a spectrum analysis chart (GNSS receiver must be capable of outputting UBX MON-SPAN messages). Clicking anywhere in the spectrum chart will display the frequency and decibel reading at that point. Double-clicking anywhere in the chart will toggle the GNSS frequency band markers (L1, G2, etc.) on or off.System Monitor widget showing device cpu, memory and I/O utilisation (GNSS receiver must be capable of outputting UBX MON-SYS and/or MON-COMMS messages). Tick checkbox to toggle between actual (cumulative) I/O stats and pending I/O.Scatterplot widget showing variability in position reporting over time. Uses a haversine great circle formula at scales greater than 50m, and a planar approximation formula for smaller scales. Double-click to clear existing plot.Rover widget plots the relative 2D position, track and status information for the roving receiver in a fixed or moving base / rover RTK configuration. Double-click to clear existing plot. (GNSS rover receiver must be capable of outputting UBX NAV-RELPOSNED messages.)UBX Configuration FacilitiesPre-Requisites:u-blox GNSS receiver e.g. u-blox NEO-M8S, ZED-F9P, etc. connected to the workstation via USB or UART port.Instructions:The UBX Configuration Dialog currently provides the following UBX configuration panels:Version panel shows current device hardware/firmware versions (via MON-VER and MON-HW polls).CFG Configuration Load/Save/Record facility. This allows users to recorda sequence of UBX CFG configuration commands, and to savethis recording to a file (as binary CFG-* messages). Saved files can be reloadedand the configuration commands replayed. This provides a means to easily reproduce a given sequence of configuration commands, or copy a saved configuration between compatible devices. The Configuration Load/Save/Record facility can accept configuration files in either binary UBX format (*.ubx) or u-center text format (*.txt). Files saved using theubxsaveCLI utility (installed via thepygnssutilslibrary) can also be reloaded and replayed.Tip:The contents of a binary config file can be reviewed using PyGPSClient'sfile streaming facility,BUTremember to set theMsg Modein the Settings panel toSETrather than the defaultGET.Protocol Configuration panel (CFG-PRT) sets baud rate and inbound/outbound protocols across all available ports.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).For each of the panels above, clicking anywhere in the panel background will refresh the displayed information with the current configuration.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' (higher = less frequent).Generic 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.Configuration Interface widget (CFG-VALSET, CFG-VALDEL and CFG-VALGET) queries and sets configuration forGeneration 9+ devicese.g. NEO-M9, ZED-F9P, etc.Preset Commands widget supports a variety of preset and user-defined commands - seeuser defined presetsAn icon to the right of each 'SEND'button indicates the confirmation status of the configuration command;
(pending i.e. awaiting confirmation,
confirmedor
warning).Note:The UBX protocol does not support synchronous command acknowledgement or unique confirmation IDs. Asynchronous command and poll acknowledgements and 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.For presets that invoke a CFG-MSG command to set message rates, the port(s) to which the rate applies can be set via thedefaultport_sconfiguration setting, which supports a comma-separated list of ports e.g. "USB", "USB,UART1" or "USB,I2C".NTRIP Client FacilitiesThe NTRIP Configuration utility allows users to receive and process NTRIP RTK Correction data from an NTRIP caster to achieve cm level location accuracy. The facility can be accessed by clickingor selecting Menu..Options..NTRIP Configuration Dialog.Pre-Requisites:NTRIP-compatible GNSS receiver e.g. u-blox ZED-F9PInternet accessURL of NTRIP casterLogin credentials for the NTRIP caster (where required)Name of local MOUNTPOINT (if not using PyGPSClient's automatic mountpoint locator)Instructions: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.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,PyGPSClientwill automatically identify the closest mountpoint to the current location.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.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 fixed reference settings entered in the NTRIP configuration panel (latitude, longitude, elevation and geoid separation - all four reference settings must be provided).To connect to the NTRIP server, click. To disconnect, click.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.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 localSNIP LITEserver.Inappropriate use of an NTRIP service may result in your account being blocked.SPARTN Client FacilitiesThe SPARTN Configuration utility allows users to receive and process SPARTN RTK Correction data from an IP or L-Band source to achieve cm level location accuracy. It provides three independent configuration sections, one for IP Correction (MQTT), one for L-Band Correction (e.g. NEO-D9S) and a third for the GNSS receiver (e.g. ZED-F9P).The facility can be accessed by clickingor selecting Menu..Options..SPARTN Configuration Dialog.FYI:the SPARTN client utilises a newpyspartnlibrary. Thepyspartn.SPARTNReaderclass will parse individual SPARTN messages from any binary stream containingsolelySPARTN data e.g. an MQTT/pp/iptopic. Thepyspartn.SPARTNMessageclass is in Alpha and does not currently perform a full decode of all SPARTN protocol messages; it basically decodes just enough information to identify message type/subtype, payload length and other key metadata.Pre-Requisites:IP Correction (MQTT Client):Internet accessSubscription to a suitable MQTT SPARTN location service e.g. u-blox / Thingstream PointPerfect IP or L-band, which should provide the following details:Server URL e.g.pp.services.u-blox.comClient ID (which can be stored in the"mqttclientid_s":json configuration file setting or via environment variableMQTTCLIENTID)Encryption certificate (*.crt) and key (*.pem) files required to access the SPARTN service via an encrypted HTTPS connection. If these are placed in the user's HOME directory using the location service's standard naming convention, PyGPSClient will find them automatically.Region code - select fromus,eu,jp,krorau.Source - select from eitherIPorL-Band(NB: the 'L-Band' MQTT mode provides decryption keys, Assist Now data and L-Band frequency information, but the correction data itself arrives via the L-Band receiver below).A list of published topics. These typically include:/pp/ip/region- binary SPARTN correction data (SPARTN-1X-HPAC* / OCB* / GAD*) for the selected region, for IP sources only./pp/ubx/mga- UBX MGA AssistNow ephemera data for each constellation./pp/ubx/0236/ipor/pp/ubx/0236/Lb- UBX RXM-SPARTNKEY messages containing the IP or L-band decryption keys to be uploaded to the GNSS receiver./pp/frequencies/Lb- json message containing each region's L-band transmission frequency - currentlyusoreu(this is automatically enabled whenL-Bandis selected).L-BAND Correction (D9* Receiver):SPARTN L-Band correction receiver e.g. u-blox NEO-D9S.Suitable Inmarsat L-band antennaand good satellite reception on regional frequency (NB: standard GNSS antenna may not be suitable).Subscription to L-Band location service e.g. u-blox / Thingstream PointPerfect, which should provide the following details:L-Band frequency (also available via/pp/frequencies/LbMQTT topic)Search windowUse Service ID?Use Descrambling?Use Prescrambling?Service IDData RateDescrambler InitUnique WordGNSS Receiver:SPARTN-compatible GNSS receiver e.g. u-blox ZED-F9PSubscription to either IP and/or L-Band location service(s) e.g. e.g. u-blox / Thingstream PointPerfect, which should provide the following details:Current and Next IP or L-band decryption Keys in hexadecimal format. These allow the receiver to decrypt the SPARTN message payloads.Valid From dates in YYYYMMDD format (keys normally valid for 4 week period).Instructions:IP Correction Configuration (MQTT)Enter your MQTT Client ID (or set it up beforehand as *.json configuration setting"mqttclientid_s":or via environment variableMQTTCLIENTID).Select the path to the MQTT*.crtand*.pemfiles provided by the location service (PyGPSClient will use the user's HOME directory by default).Select the required region and subscription mode (IPorL-Band).Select the required topics:IP - this is the raw SPARTN correction data as SPARTN-1X-HPAC* / OCB* / GAD* messages (required for IP; must be unchecked for L-Band).Assist - this is Assist Now data as UBX MGA-* messages.Key - this is the SPARTN IP or L-band decryption keys as a UBX RXM-SPARTNKEY message.To connect to the MQTT server, click. To disconnect, click.L-Band Correction Configuration (D9*)To connect to the Correction receiver, select the receiver's port from the SPARTN dialog's Serial Port listbox and click. To disconnect, click.Select the required Output Port - this is the port used to connect the Correction receiver to the GNSS receiver e.g. UART2 or I2C.If both Correction and GNSS receivers are connected to the same PyGPSClient workstation (e.g. via separate USB ports), it is possible to run the utility in Output Port = 'Passthough' mode, whereby the output data from the Correction receiver (UBXRXM-PMPmessages) will be automatically passed through to the GNSS receiver by PyGPSClient, without the need to connect the two externally.To enable INF-DEBUG messages, which give diagnostic information about current L-Band reception, click 'Enable Debug?'.To save the configuration to the device's persistent storage (Battery-backed RAM, Flash or EEPROM), click 'Save Config?'. This only has to be done once for a given region.Once connected, clickto upload the configuration. The utility will send the relevant configuration command(s) to the Correction receiver and poll for an acknowledgement.GNSS Receiver Configuration (F9*)Connect to the GNSS receiver first by clickingon the main PyGPSClient settings panel.If you are subscribing to the MQTT SPARTNKEY (/pp/ubx/0236/ipor/pp/ubx/0236/Lb) topic, the decryption key and validity date details will be entered automatically on receipt of a UBX RXM-SPARTNKEY message (which may take a few seconds after connecting). Alternatively, they can be uploaded from the service provider's JSON file, or entered manually as follows:Enter the current and next decryption keys in hexadecimal format e.g.0102030405060708090a0b0c0d0e0f10. The keys are normally 16 bytes long, or 32 hexadecimal characters.Enter the supplied Valid From dates inYYYYMMDDformat.NB:These areValid Fromdates rather thanExpirydates. If the location service provides Expiry dates, subtract 4 weeks from these to get the Valid From dates.Select 'DGPS Timeout', 'Upload keys', 'Configure receiver' and 'Disable NMEA' options as required.Select the SPARTN correction source - eitherIPorL-Band.To reduce traffic volumes, you can choose to disable NMEA messages from the receiver. A minimal set of UBX NAV messages will be enabled in their place.Clickto upload the configuration. The utility will send the relevant configuration command(s) to the receiver and poll for an acknowledgement.Below is a illustrative SPARTN DGPS data log, showing:Incoming SPARTN correction messages (SPARTN-1X-HPAC* high-precision atmosphere corrections; SPARTN-OCB* orbit / clock / bias corrections; SPARTN-1X-GAD geographic area definitions).Outgoing UBX RXM-COR confirmation messages from receiver showing that the SPARTN data has been received and decrypted OK.Socket Server / NTRIP Caster FacilitiesThe Socket Server / NTRIP Caster facility is capable of operating in either of two modes;SOCKET SERVER - an open, unauthenticated TCP socket server available to any socket client including, for example, another instance of PyGPSClient or thegnssdumpCLI utility. In this mode it will broadcast the host's currently connected GNSS data stream (NMEA, UBX, RTCM3). The default port is 50012.NTRIP CASTER - a simple implementation of an authenticated NTRIP caster available to any NTRIP client including, for example, the PyGPSClient NTRIP Client facility or thegnssntripclientCLI utility. Login credentials for the NTRIP caster are set via the"ntripcasteruser_s":and"ntripcasterpassword_s":settings in the *.json confirmation file (they can also be set via PyGPSClient command line arguments--ntripcasteruser,--ntripcasterpassword, or by setting environment variablesNTRIPCASTER_USER,NTRIPCASTER_PASSWORD). Default settings are as follows: bind address: 0.0.0.0, port: 2101, mountpoint: pygnssutils, user: anon, password: password.By default, the server/caster binds to the host address '0.0.0.0' (IPv4) or '::' (IPv6) i.e. all available IP addresses on the host machine. This can be overridden via the settings panel or a host environment variablePYGPSCLIENT_BINDADDRESS. A label on the settings panel indicates the number of connected clients, and the server/caster status is indicated in the topmost banner: running with no clients:, running with clients:.Pre-Requisites:Running in NTRIP CASTER mode is predicated on the host being connected to an RTK-compatible GNSS receiver (e.g. u-blox ZED-F9P)operating in Base Station mode(eitherFIXEDorSURVEY_IN) and outputting the requisite RTCM3 message types (1005, 1077, 1087, 1097, 1127 and 1230).It may be necessary to add a firewall rule and/or enable port-forwarding on the host machine or router to allow remote traffic on the specified address:port.Instructions:SOCKET SERVER MODESelect SOCKET SERVER mode and (if necessary) enter the host IP address and port.Check the Socket Server/NTRIP Caster checkbox to activate the server.To stop the server, uncheck the checkbox.NTRIP CASTER MODESelect NTRIP CASTER mode and (if necessary) enter the host IP address and port.An additional expandable panel is made available to allow the user to configure a connected RTK-compatible u-blox receiver (e.g. ZED-F9P) to operate in eitherFIXEDorSURVEY-INBase Station mode (NB: parameters can only be amended while the caster is stopped). If 'Configure Base Station' is checked, the selected configuration will be applied to the connected receiver once the caster is activated.NMEA messages can be suppressed by checking 'Disable NMEA'. A minimum set of UBX messages will be output in their place.NTRIP client login credentials are set via the user and password fields.Check the Socket Server/NTRIP Caster checkbox to activate the caster.To stop the caster, uncheck the checkbox.Base Station ConfigurationConfiguration SettingsBase Station ModeFIXED. In this mode, the known base station coordinates (Antenna Reference Point or ARP) are specified in either LLH or ECEF (X,Y,Z) format. The coordinates are pre-populated with the receiver's current navigation solution (if available), but these can (and normally should) be overridden with accurately surveyed values. If the coordinates are accepted, the UBX Fix status will change toTIME ONLYand the receiver will start outputting RTCM1005(ARP location) messages.SURVEY-IN. In this mode, the base station coordinates are derived from the receiver's current navigation solution, provided the prescribed level of accuracy is met within the specified survey duration. If the survey is successful, the UBX NAV-SVIN monitoring message will indicatevalid=1, active=0, the UBX Fix status will change toTIME ONLYand the receiver will start outputting RTCM1005(ARP location) messages.DISABLED. Disable base station operation.NB:To operate effectively as an RTK Base Station, antenna positioning is of paramount importance. Refer to the following links for advice:u-blox GNSS Antennas PaperArdusimple GNSS Antenna Installation GuideGPX Track ViewerGPX Track Viewer screenshotThe GPX Track Viewer can display any valid GPX file containing trackpoints (<trkpt>..</trkpt>elements). The map display requires a freeMapQuest API key. The Y axis scales will reflect the current choice of units (metric or imperial). Clickto refresh the display after any changes (e.g. resizing, zooming or change of units).InstallationIn the following,python3&piprefer to the Python 3 executables. You may need to typepythonorpip3, depending on your particular environment. It is recommended that
the Python 3 scripts (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).NB: if you're installing onto a 32-bit Linux platform (e.g. Raspberry Pi OS 32), there may be additional installation steps - see note⁵below.Platform DependenciesPython >= 3.8¹Tk (tkinter) >= 8.6²Screen resolution >= 800 x 600; Ideally >= 1920 x 1080, though the main application window is resizeable and reconfigurable.All platforms¹It is highly recommended to use the latest officialPython.orginstallation package for your platform, rather than any pre-installed version.Windows 10 or later:Normally installs without any additional steps.MacOS 11 or later:²The version of Python supplied with most Apple MacOS platforms includes adeprecated version of tkinter(8.5). Use an officialPython.orginstallation package instead.Linux (including Raspberry Pi OS):³Some Linux distributions may not include the necessary pip, tkinter or Pillow imaging libraries by default. They may need to be installed separately, e.g.:sudoaptinstallpython3-pippython3-tkpython3-pilpython3-pil.imagetklibjpeg-devzlib1g-dev⁴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 tohttp://wiki.python.org/moin/TkInterfor further details:sudoaptinstalltk-dev⁵On some 32-bit Linux platforms (e.g. Raspberry Pi OS 32), it may be necessary toinstall Rust compiler supportand someadditional build dependenciesin order to install thecryptographylibrary which PyGPSClient depends on to decrypt SPARTN messages (seeDiscussionand alsopyspartn cryptography installation notes):curl--proto'=https'--tlsv1.2-sSfhttps://sh.rustup.rs|sh
sudoapt-getinstallbuild-essentiallibssl-devlibffi-devpython3-devpkg-configUser PrivilegesTo access the serial port on most Linux platforms, you will need to be a member of thettyand/ordialoutgroups. Other than this, no special privileges are required.usermod-a-Gttymyuser1. Install using pipThe easiest way to install the latest version ofPyGPSClientis withpip:python3-mpipinstall--upgradepygpsclientIf required,PyGPSClientcan also be installed into a virtual environment, e.g.:python3-mpipinstall--user--upgradevirtualenv
python3-mvirtualenvenvsourceenv/bin/activate(orenv\Scripts\activateonWindows)(env)python3-mpipinstall--upgradepygpsclient(env)./env/bin/pygpsclient
...
deactivateTo run the application, if the Python 3 scripts (bin) directory is in your PATH, simply type (all lowercase):pygpsclientpygpsclientalso accepts optional command line arguments for a variety of configurable parameters. These will override any saved configuration file settings. Type the following for help:pygpsclient-hIf 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-mpygpsclientNB:If the Python 3 scripts (bin) or site_packages directories arenotin your PATH, you will need to add the fully-qualified path topygpsclientin the commands above.Tip:to find the site_packages location, type:python3-mpipshowpygpsclientand look for theLocation:entry in the response, e.g.Linux:Location: /home/username/.local/lib/python3.11/site-packagesMacOS:Location: /Library/Frameworks/Python.framework/Versions/3.11/lib/python3.11/site-packagesWindows:Location: c:\users\username\appdata\roaming\python\python311\lib\site-packagesTip:To create an application launcher for Linux distributions like Ubuntu, create a text file namedpygpsclient.desktopwith the following content (edited for your particular environment) and copy this to the/home/user/.local/share/applicationsfolder, e.g.[Desktop Entry]
Type=Application
Terminal=false
Name=PyGPSClient
Icon=/home/user/.local/lib/python3.11/site-packages/pygpsclient/resources/pygpsclient.ico
Exec=/home/user/.local/bin/pygpsclientTip:To create an application launcher for MacOS, use MacOS's Automator tool to create a "Run Shell Script" application and save this asPyGPSClient.app, e.g.Shell: /bin/zsh/Library/Frameworks/Python.framework/Versions/3.11/bin/pygpsclientTo assign an icon to this application, right-click on thePyGPSCliententry in the Applications folder, select "Get Info" and drag-and-drop the pygpsclient.ico image file from the site-packages folder (e.g. "/Library/Frameworks/Python.framework/Versions/3.11/lib/python3.11/site-packages/pygpsclient/resources/pygpsclient.ico") to the default application icon at the top left.2. Manual installationThe following Python libraries are required (these will be installed automatically if using pip to install PyGPSClient):python3-mpipinstall--upgradePillowpygnssutilspyserialpyspartnrequestsTo install PyGPSClient manually, download and unzip this repository and run:python3-m/path_to_folder/foldername/pygpscliente.g. if you downloaded and unzipped to a folder namedPyGPSClient-1.3.26, run:python3-m/path_to_folder/PyGPSClient-1.3.26/pygpsclientMapQuest API KeyPre-Requisites:To use the optional dynamic web-based mapview or GPX Track Viewer facilities, you need to request and install aMapQuest API key.Note that, from January 15th 2024, MapQuest require payment card details for the use of this API, but the
first 15,000 transactions/month remain free. Usage above 15,000 transactions/month is charged at $.0045 per transaction. SeeFAQfor further information.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 isnotintended to be used for real time navigational purposes.Instructions:Once you have received the API key (a 32-character alphanumeric string), you can (in order of precedence):Copy it to the"mqapikey_s":value in your json configuration file (see example provided).Create an environment variable namedMQAPIKEY(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.Pass it via command line argument--mqapikey.*The web map refresh rate can be amended if required by changing themapupdateinterval_n:value in your json configuration file.User Defined PresetsThe 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 the"ubxpresets_l":list in your json configuration file (see example provided). The message definition comprises a free-format text description (avoid embedded commas)
followed by one or morepyubx2 UBXMessage constructors, i.e.message class as a string e.g.CFG(must be a valid class from pyubx2.UBX_CLASSES)message id as a string e.g.CFG-MSG(must be a valid id from pyubx2.UBX_MSGIDS)payload as a hexadecimal string e.g.f004010100010100(leave blank for null payloads e.g. most POLL messages)mode as an integer (1= SET,2= POLL)(payload as hex string can be obtained from aUBXMessagecreated using thepyubx2 librarythus:msg.payload.hex())Multiple commands can be concatenated on a single line. Illustrative examples are shown below:"ubxpresets_l": [
		"Force HOT Reset (!!! Will require reconnection !!!), CFG, CFG-RST, 00000000, 1",
		"Force WARM Reset (!!! Will require reconnection !!!), CFG, CFG-RST, 00010000, 1",
		"Force COLD Reset (!!! Will require reconnection !!!), CFG, CFG-RST, ffff0000, 1",
		"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 RTCM3 MSGOUT Basestation, CFG, CFG-VALSET, 00010000c002912001cf02912001d4029120011b03912001d902912001060391200101039120018403912001, 1",
		"Set ZED-F9P to Survey-In Timing Mode Basestation, CFG, CFG-VALSET, 0001000001000320011100034070110100100003405a0000008b00912001, 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 RXM-SPARTN-KEY, RXM, RXM-SPARTN-KEY, , 2",
		"Poll RXM-COR, RXM, RXM-COR, , 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 8 MHz, CFG, CFG-TP5, 000100003200000000127a0000127a003200000032000000000000006f000000, 1",
	]Command Line UtilitiesThepygnssutilslibrary which underpins many of the functions inPyGPSClientalso incorporates command line versions of these functions:gnssdumpCLI 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.gnssserverCLI utility. This implements a TCP Socket Server for GNSS data streams which is also capable of being run as a simple NTRIP Server.gnssntripclientCLI 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.gnssmqttclientCLI utility. This implements a simple SPARTN IP (MQTT) Client which receives SPARTN and UBX correction data from a SPARTN IP location service (e.g. u-blox / Thingstream PointPerfect) and (optionally) 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.For further details, refer to thepygnssutilshomepage athttps://github.com/semuconsulting/pygnssutils.LicenseBSD 3-Clause LicenseCopyright © 2020, SEMU Consulting
All rights reserved.Application icons fromiconmonstr©.Author Informationsemuadmin@semuconsulting.comPyGPSClientis 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!