|
15 | 15 | [Mapquest API Key](#mapquestapi) | |
16 | 16 | [User-defined Presets](#userdefined) | |
17 | 17 | [CLI Utilities](#cli) | |
18 | | -[Troubleshooting](#troubleshoot) | |
| 18 | +[Troubleshooting & Known Issues](#troubleshoot) | |
19 | 19 | [License](#license) | |
20 | 20 | [Author Information](#author) |
21 | 21 |
|
@@ -59,7 +59,7 @@ This is an independent project and we have no affiliation whatsoever with any GN |
59 | 59 |
|
60 | 60 | The PyGPSClient home page is at [PyGPSClient](https://github.com/semuconsulting/PyGPSClient). |
61 | 61 |
|
62 | | -Contributions from human beings welcome - please refer to [CONTRIBUTING.MD](https://github.com/semuconsulting/PyGPSClient/blob/master/CONTRIBUTING.md). |
| 62 | +Contributions **_from human beings_** welcome - please refer to [CONTRIBUTING.MD](https://github.com/semuconsulting/PyGPSClient/blob/master/CONTRIBUTING.md). |
63 | 63 |
|
64 | 64 | For [Bug reports](https://github.com/semuconsulting/PyGPSClient/blob/master/.github/ISSUE_TEMPLATE/bug_report.md), please use the template provided. For feature requests and general queries and advice, post a message to one of the [PyGPSClient Discussions](https://github.com/semuconsulting/PyGPSClient/discussions) channels in the first instance. |
65 | 65 |
|
@@ -91,7 +91,8 @@ To install into a virtual environment (*which may be necessary if you have an [` |
91 | 91 | python3 -m venv pygpsclient |
92 | 92 | source pygpsclient/bin/activate # (or .\pygpsclient\Scripts\activate on Windows) |
93 | 93 | python3 -m pip install --upgrade pygpsclient |
94 | | -deactivate |
| 94 | +pygpsclient |
| 95 | +deactivate # to deactivate virtual environment when finished |
95 | 96 | ``` |
96 | 97 |
|
97 | 98 | Quick [installation shell scripts](https://github.com/semuconsulting/PyGPSClient/blob/master/INSTALLATION.md#script) are available for Linux and MacOS platforms. |
@@ -149,6 +150,7 @@ For more comprehensive installation instructions, please refer to [INSTALLATION. |
149 | 150 | gnssstreamer --port /dev/ttyACM0 --baudrate 115200 --timeout 3 --format 2 --clioutput 1 --output pygpsdata.log --verbosity 2 |
150 | 151 | ``` |
151 | 152 |
|
| 153 | + Datalogs will include both receiver output and (_if the relevant protocol is enabled in settings_) any incoming NTRIP RTK data stream. |
152 | 154 | 18. GPX Track - Turn track recording (in GPX format) on or off. On first selection, you will be prompted to select the directory into which timestamped GPX track files are saved. See also [GPX Track Viewer](#gpxviewer). |
153 | 155 | 19. Database - Turn spatialite database recording (*where available*) on or off. On first selection, you will be prompted to select the directory into which the `pygpsclient.sqlite` database is saved. *Note that, when first created, the database's spatial metadata may take up to a minute or so to initialise*. |
154 | 156 | - Database logging is dependent on your Python environment supporting the requisite [sqlite3 `mod_spatialite` extension](https://www.gaia-gis.it/fossil/libspatialite/index) - see [INSTALLATION.md](https://github.com/semuconsulting/PyGPSClient/blob/master/INSTALLATION.md#prereqs) for further details. If not supported, the option will be greyed out. Check the Menu..Help..About dialog for an indication of the current spatialite support status - `no-ext` means the spatialite extension is not supported; `no-ms` means spatialite *is* supported but the necessary `mod_spatialite` extension module cannot be found in the PATH; a numeric version number like `3.51.2` indicates spatialite is fully supported. |
@@ -508,17 +510,19 @@ The `pygnssutils` and `pyubxutils` libraries which underpin many of the function |
508 | 510 | For further details, refer to the `pygnssutils` homepage at [https://github.com/semuconsulting/pygnssutils](https://github.com/semuconsulting/pygnssutils) or `pyubxutils` homepage at [https://github.com/semuconsulting/pyubxutils](https://github.com/semuconsulting/pyubxutils). |
509 | 511 |
|
510 | 512 | --- |
511 | | -## <a name="troubleshoot">Troubleshooting</a> |
| 513 | +## <a name="troubleshoot">Troubleshooting and Known Issues</a> |
| 514 | +
|
| 515 | +1. There is a known issue with PyGPSClient GUI refreshes becoming progressively slower on certain platforms if the app is left unattended (_i.e. no user interaction_) for an extended period - typically 30 minutes or more. The issue is more pronounced on low-end SBC platforms like the Raspberry Pi. **Underlying processing (including message parsing and datalogging) is unaffected**, and the GUI can generally be 'woken up' within a few seconds via a simple user interaction e.g. resizing the main panel. The root cause of this issue is under investigation, but as a workaround, users can try a) increasing the `guiupdateinterval_f` setting in the json configuration file, or b) hiding some or all user-selectable widgets until needed. |
512 | 516 |
|
513 | | -1. **NB:** The latest version of Python for MacOS (>=3.14.5) comes with a new version of tkinter (9.0). There appear to be fairly serious performance issues with this version on MacOS Tahoe which render the PyGPSClient UI somewhat sluggish. For the time being, it is recommended that users use >=3.14.4. This issue does *not* affect other operating systems or Python apps not using tkinter. |
| 517 | +2. **NB:** The latest version of Python for MacOS (>=3.14.5) comes with a new version of tkinter (9.0). There appear to be fairly serious performance issues with this version on MacOS Tahoe which render the PyGPSClient GUI somewhat sluggish. For the time being, it is recommended that users use >=3.14.4. This issue does *not* affect other operating systems or Python apps not using tkinter. |
514 | 518 |
|
515 | | -2. If you encounter persistent `WARNING>>Error parsing data stream Serial stream terminated unexpectedly` messages in the console, this may be indicative of insufficient serial port bandwidth (baudrate or timeout) for the current output message cohort (*particularly if this includes Ephemera or Observation data*). Try increasing the baudrate in the first instance. |
| 519 | +3. If you encounter persistent `WARNING>>Error parsing data stream Serial stream terminated unexpectedly` messages in the console, this may be indicative of insufficient serial port bandwidth (baudrate or timeout) for the current output message cohort (*particularly if this includes raw Ephemerides or Observation data*). Try increasing the baudrate in the first instance. |
516 | 520 |
|
517 | | -3. Most [budget USB-UART adapters](https://www.amazon.co.uk/DSD-TECH-adapter-FT232RL-Compatible/dp/B07BBPX8B8?ref_=ast_sto_dp) (e.g. FT232, CH345, CP2102, *including those embedded on development boards*) have a bandwidth limit of around 3Mbps (≈ 375000 baud) and may not work reliably above 230600 baud, even if the receiver supports higher baud rates. If you're using an adapter and notice significant message corruption (e.g. frequent `WARNING>>..invalid checksum` messages), try reducing the baud rate to a maximum 230600. |
| 521 | +4. Most [budget USB-UART adapters](https://www.amazon.co.uk/DSD-TECH-adapter-FT232RL-Compatible/dp/B07BBPX8B8?ref_=ast_sto_dp) (e.g. FT232, CH345, CP2102, *including those embedded on development boards*) have a bandwidth limit of around 3Mbps (≈ 375000 baud) and may not work reliably above 230600 baud, even if the receiver supports higher baud rates. If you're using an adapter and notice significant message corruption (e.g. frequent `WARNING>>..invalid checksum` messages), try reducing the baud rate to a maximum 230600. |
518 | 522 |
|
519 | | -4. Some Linux Wayland platforms appear to require Toplevel dialog windows to be non-transient (`transient_dialog_b: 0`) for the window 'maximise' icon to work properly. |
| 523 | +5. Some Linux Wayland platforms appear to require Toplevel dialog windows to be non-transient (`transient_dialog_b: 0`) for the window 'maximise' icon to work properly. |
520 | 524 |
|
521 | | -5. Some Homebrew-installed Python environments on MacOS can give rise to critical segmentation errors (*illegal memory access*) when shell subprocesses are invoked, due to the way permissions are implemented. This may, for example, affect About..Update functionality; the workaround is to update via a standard CLI `pip install --upgrade` command. |
| 525 | +6. Some Homebrew-installed Python environments on MacOS can give rise to critical segmentation errors (*illegal memory access*) when shell subprocesses are invoked, due to the way permissions are implemented. For this reason, application updates via the About..Update button are disabled on Homebrew environments; use the CLI `python3 -m pip install --upgrade pygpsclient` command instead. |
522 | 526 |
|
523 | 527 | --- |
524 | 528 | ## <a name="license">License</a> |
|
0 commit comments