Merge pull request #168 from semuconsulting/RC-1.5.0

Rc 1.5.0

.vscode/settings.json

@@ -4,6 +4,6 @@
     "editor.formatOnSave": true,
     "modulename": "pygpsclient",
     "distname": "pygpsclient",
-    "moduleversion": "1.4.27",
+    "moduleversion": "1.5.0",
     "python.defaultInterpreterPath": "python3",
 }

CUSTOM_MAPS.md

@@ -0,0 +1,24 @@
+# How to create a custom offline map for PyGPSClient's Map and GPX Viewers
+
+### We use and recommend the free, open-source [QGIS software](https://qgis.org/download/), which is available for most platforms including Windows, MacOS and Linux.
+
+1. Download and install QGIS. The latest LTR version at time of writing is 3.34. It's a relatively large package and the install may take a minute or so. **NB**: If you're installing on MacOS Sequoia or newer, note the "Tips for first launch".
+1. Open QGIS and select from the top menu bar **Project..Properties..CRS** (*Coordinate Reference System*). Search for, select and apply CRS "**EPSG:4326 WGS84**". This will display map extent as latitude and longitude rather than the default meters (*other suitable CRSs are available but this is the de facto standard used by PyGPSClient*).
+
+   ![QGIS CRS Selection](/images/QGIS_crs.png?raw=true)
+
+1. Navigate to the left hand browser and select **XYZ Tiles..OpenStreetMap** (*OpenStreetMap is available as standard in recent versions of QGIS - previously it was available as an optional plugin*). Please note that OpenStreetMap is open data, licensed under the [Open Data Commons Open Database License](https://opendatacommons.org/licenses/odbl/) (ODbL) by the [OpenStreetMap Foundation](https://osmfoundation.org/) (OSMF). If you have imported your own XYZ data source, you can also use this.
+1. Shift and zoom into the area of interest. Toggle the '**Coordinate/Extents**' display in the bottommost status bar to show the current map extent.
+
+   ![QGIS Screenshot](/images/QGIS_screenshot.png?raw=true)
+
+1. When you reach the desired extent, select from the top menu bar **Project..Import/Export..Export Map to Image...**.
+1. Accept all the defaults in the "Save Map as Image" pop-up box. **Ensure the "Append Georeference Information" option is ticked**. If necessary, make a note of the map extent.
+
+   ![QGIS Save Map Popup](/images/QGIS_savemap.png?raw=true)
+
+1. Save the map as a geoTIFF (*.tif) file.
+
+You can now import the saved image into PyGPSClient using **Options..Import Custom Map**. If the Python `rasterio` library is installed, the map extent will be extracted automatically - otherwise, it must be entered manually.
+
+**FYI:** Installing QGIS using the default settings also installs the GDAL (*Geospatial Data Abstraction Library*) package, which is a dependency for the `rasterio` library (*though it can also be installed separately*).

README.md

@@ -54,6 +54,20 @@ This is an independent project and we have no affiliation whatsoever with u-blox
 ---
 ## <a name="installation">Installation</a>
 
+## The Quick Version
+
+If you have an [official Python]([Python.org](https://www.python.org/downloads/)) >=3.9 with tkinter >=8.6 installed and the Python [binaries](#binaries) folder is in your PATH, you can install PyGPSClient using pip:
+```shell
+python3 -m pip install --upgrade pygpsclient
+```
+
+and then run it by typing:
+```shell
+pygpsclient
+```
+
+## The Longer Version
+
 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](#binaries) 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*).
 
 ### Platform Dependencies
@@ -225,9 +239,10 @@ You will need to logout and login for the launcher to take effect.
 1. 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 [UBX Configuration Dialog](#ubxconfig)).
 1. Position Format and Units - Change the displayed position (D.DD / D.M.S / D.M.MM / ECEF) and unit (metric/imperial) formats.
 1. Map Type - Select from "world", "map", "sat" or "custom". "map" and "sat" types require an Internet connection and free [Mapquest API Key](#mapquestapi). "custom" offline map images can be imported and georeferenced using the [Menu..Options..Import Custom Map](#custommap) facility.
+1. Show Track - Tick to show track in map view. Map track will only be recorded while this checkbox is ticked.
 1. 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.
 1. 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.
-1. 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.
+1. GPX Track - Turn track recording (in GPX format) on or off. You will be prompted to select the directory into which timestamped GPX track files are saved.
 1. 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.
 1. To load a saved configuration file, go to File..Load Configuration. The default configuration file location is `$HOME/pygpsclient.json`. **NB** Any active serial or RTK connection must be stopped before loading a new configuration.
 
@@ -244,14 +259,14 @@ You will need to logout and login for the launcher to take effect.
 | User-selectable 'widgets' | To show or hide the various widgets, go to Menu..View and click on the relevant hide/show option. |
 |---------------------------|---------------------------------------------------------------------------------------------------|
 |![banner widget](https://github.com/semuconsulting/PyGPSClient/blob/master/images/banner_widget.png?raw=true)| 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 ![expand icon](https://github.com/semuconsulting/PyGPSClient/blob/master/src/pygpsclient/resources/iconmonstr-arrow-80-16.png?raw=true)/![expand icon](https://github.com/semuconsulting/PyGPSClient/blob/master/src/pygpsclient/resources/iconmonstr-triangle-1-16.png?raw=true) 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_SAT |
-|![console widget](https://github.com/semuconsulting/PyGPSClient/blob/master/images/console_widget.png?raw=true)| Configurable serial console widget showing incoming GNSS, NTRIP and SPARTN data streams in either parsed, binary or tabular hexadecimal formats. Double-click to copy contents of console to clipboard. 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.|
+|![console widget](https://github.com/semuconsulting/PyGPSClient/blob/master/images/console_widget.png?raw=true)| Configurable serial console widget showing all incoming data streams (both GNSS and RTK) in either parsed, binary or tabular hexadecimal formats. Double-click to copy contents of console to clipboard. The scroll behaviour and number of lines retained in the console can be configured via the settings panel. 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). If color is set to "HALT", streaming will halt on any match and a warning displayed. NB: color tagging does impose a small performance overhead - turning it off will improve console response times at very high transaction rates.|
 |![skyview widget](https://github.com/semuconsulting/PyGPSClient/blob/master/images/skyview_widget.png?raw=true)| 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](https://github.com/semuconsulting/PyGPSClient/blob/master/images/graphview_widget.png?raw=true)| Graphview widget showing current satellite reception (carrier-to-noise ratio or cnr). Double-click to toggle legend. |
 |![static map](https://github.com/semuconsulting/PyGPSClient/blob/master/images/staticmap.png?raw=true)| Map widget with various modes of display. Map Type = 'world': a static offline Mercator world map showing current global location.
 |![webmap widget](https://github.com/semuconsulting/PyGPSClient/blob/master/images/webmap_widget.png?raw=true)| Map Type = 'map' or 'sat': Dynamic, online web map or satellite image via MapQuest API (*requires an Internet connection and free [Mapquest API Key](#mapquestapi)*). 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, but **NB** the facility is not intended to be used for real-time navigation. Double-click anywhere in the map to immediately refresh. |
-|![custom map](https://github.com/semuconsulting/PyGPSClient/blob/master/images/custommap.png?raw=true)| Map Type = 'custom': One or more user-defined custom offline maps can be imported using the Menu..Options..Import Custom Map facility, or by manually setting the `usermaps_l` field in the json configuration file. The `usermaps_l` setting 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]] - see [example configuration file](https://github.com/semuconsulting/PyGPSClient/blob/master/pygpsclient.json). Map images must be a [supported format](https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html) and use a standard WGS84 Web Mercator projection e.g. EPSG:4326.|
-|![import custom map](https://github.com/semuconsulting/PyGPSClient/blob/master/images/importcustommap.png?raw=true)| <a name="custommap">Import Custom Map dialog</a>. Click ![load icon](https://github.com/semuconsulting/PyGPSClient/blob/master/src/pygpsclient/resources/iconmonstr-folder-18-24.png?raw=true) to open the custom map image location (*the default file suffix is `*.gif` - select Show Options to select any file suffix `*.*`*). If the `rasterio` library is installed and the image is georeferenced (e.g. using [QGIS](https://qgis.org/)), the bounding box will be automatically extracted - otherwise it must be entered manually. Import the custom map path and bounding box settings by clicking ![play icon](https://github.com/semuconsulting/PyGPSClient/blob/master/src/pygpsclient/resources/iconmonstr-arrow-12-24.png?raw=true).|
-|![spectrum widget](https://github.com/semuconsulting/PyGPSClient/blob/master/images/spectrum_widget.png?raw=true)| 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. **NB:** Some receivers (e.g. NEO-F10N) will not output the requisite MON-SPAN messages unless the port baud rate is at least 57,600. |
+|![custom map](https://github.com/semuconsulting/PyGPSClient/blob/master/images/custommap.png?raw=true)| Map Type = 'custom': One or more user-defined custom offline maps can be imported using the Menu..Options..Import Custom Map facility, or by manually setting the `usermaps_l` field in the json configuration file. The `usermaps_l` setting represents a list of map paths and bounding boxes in the format ["path to map image", [minlat, minlon, maxlat, maxlon]] - see [example configuration file](https://github.com/semuconsulting/PyGPSClient/blob/master/pygpsclient.json). Map images must be a [supported format](https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html) and use a standard WGS84 Web Mercator projection e.g. EPSG:4326.|
+|![import custom map](https://github.com/semuconsulting/PyGPSClient/blob/master/images/importcustommap.png?raw=true)| <a name="custommap">Import Custom Map dialog</a>. Click ![load icon](https://github.com/semuconsulting/PyGPSClient/blob/master/src/pygpsclient/resources/iconmonstr-folder-18-24.png?raw=true) to open the custom map image location (*the default file suffix is `*.gif` - select Show Options to select any file suffix `*.*`*). If the `rasterio` library is installed and the image is georeferenced (e.g. using [QGIS](https://qgis.org/)), the map extent will be automatically extracted - otherwise it must be entered manually. Import the custom map path anad extent settings by clicking ![play icon](https://github.com/semuconsulting/PyGPSClient/blob/master/src/pygpsclient/resources/iconmonstr-arrow-12-24.png?raw=true). See [CUSTOM_MAPS](https://github.com/semuconsulting/PyGPSClient/blob/master/CUSTOM_MAPS.md) for tips on how to create a suitable georeferenced map image.|
+|![spectrum widget](https://github.com/semuconsulting/PyGPSClient/blob/master/images/spectrum_widget.png?raw=true)| 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. Right-click anywhere in the chart to capture a snapshot of the spectrum data, which will then be superimposed on the live data. Double-right-click to clear snapshot. **NB:** Some receivers (e.g. NEO-F10N) will not output the requisite MON-SPAN messages unless the port baud rate is at least 57,600. |
 |![sysmon widget](https://github.com/semuconsulting/PyGPSClient/blob/master/images/sysmon_widget.png?raw=true)| 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](https://github.com/semuconsulting/PyGPSClient/blob/master/images/scatterplot_widget.png?raw=true)| Scatterplot widget showing variability in position reporting over time. (Optional) Enter fixed reference position. Select Average to center plot on dynamic average position (*displayed at top left*), or Fixed to center on fixed reference position (*if entered*). Check Autorange to set plot range automatically. Set the update interval (e.g. 4 = every 4th navigation solution). Use the range slider or mouse wheel to adjust plot range. Right-click to set fixed reference point to the current mouse cursor position. Double-click clear existing plot. The default center mode, autorange, update increment, scale index and fixed reference position settings can be stored in the json configuration file as `scattercenter_s`/`scatterautorange_b`/`scatterinterval_n`/`scatterscale_n`/`scatterlat_f`/`scatterlon_f`. |
 |![rover widget](https://github.com/semuconsulting/PyGPSClient/blob/master/images/rover_widget.png?raw=true) | Rover widget plots the relative 2D position, track and status information for the roving receiver in a fixed or moving base / rover RTK configuration. Can also display relative position of NTRIP mountpoint and receiver in a static RTK configuration. Double-click to clear existing plot. (*GNSS rover receiver must be capable of outputting UBX NAV-RELPOSNED messages.*) |
@@ -463,7 +478,7 @@ By default, the server/caster binds to the host address '0.0.0.0' (IPv4) or '::'
 
 *GPX Track Viewer screenshot*
 
-The GPX Track Viewer can display any valid GPX file containing trackpoints (`<trkpt>..</trkpt>` elements). The map display requires a free [MapQuest API key](#mapquestapi). The Y axis scales will reflect the current choice of units (metric or imperial). Click ![refresh icon](https://github.com/semuconsulting/PyGPSClient/blob/master/src/pygpsclient/resources/iconmonstr-refresh-lined-24.png?raw=true) to refresh the display after any changes (e.g. resizing, zooming or change of units).
+The GPX Track Viewer can display any valid GPX file containing trackpoints (`<trkpt>..</trkpt>` elements) against either an ["custom" offline map image](#custommap), or an online MapQuest "map" or "sat" view. The "map" and "sat" options require a free [MapQuest API key](#mapquestapi). The Y axis scales will reflect the current choice of units (metric or imperial). Click ![refresh icon](https://github.com/semuconsulting/PyGPSClient/blob/master/src/pygpsclient/resources/iconmonstr-refresh-lined-24.png?raw=true) to refresh the display after any changes (e.g. resizing, zooming or change of units). In "custom" view, zoom is not functional, and mouse right-click will show the position at the mouse cursor.
 
 ---
 ## <a name="mapquestapi">MapQuest API Key</a>

RELEASE_NOTES.md

@@ -1,5 +1,24 @@
 # PyGPSClient Release Notes
 
+### RELEASE 1.5.0
+
+FIXES:
+
+1. Fix NAV-SVINFO TypeError in ubx_hnadler.
+
+ENHANCEMENTS:
+
+1. Enhancements to spectrum widget:
+   - Add snapshot facilty. Right-click anywhere in spectrum plot to capture current spectrum data, which will then be superimposed on the live spectrum data in a different color. Double-right-click to clear the snapshot. Intention is to help compare RF reception at different times and/or with different antenna configurations.
+   - Add pgaoffset option. If selected, adds receiver PGA (programmable gain amplifier) gain to spectrum db axis.
+   - vertical (db) axis range is now fixed - fixes previous vertical axis 'jumping'.
+1. Enhance console color tagging.
+1. Add baseline (where available) to banner dgps display.
+1. Selected receiver serial port now included in saved json configuration file (NB: obviously won't work if the saved device is no longer available on the same port).
+1. Minor interval enhancments to SPARTM data stream handling to reflect pyspartn>=1.05
+
+
+
 ### RELEASE 1.4.27
 
 ENHANCEMENTS:

docs/conf.py

@@ -57,9 +57,6 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 # html_static_path = ["_static"]
 html_last_updated_fmt = "%b %d %Y"
-html_theme_options = {
-    "display_version": True,
-}
 
 autodoc_default_options = {
     "members": True,