Software Overview

Warning - Resource Requirements

When choosing a SBC, please be aware of any resource requirements.

For example, the mosaic-X GNSS Flex module provides an internal web server, which can be utilized to change its configuration settings. On platforms such as the Raspberry Pi, using the latest Raspberry Pi OS (Bookworm, at the time of writing), the Chromium web browser requires a good amount of RAM to run smoothly. Therefore, some of the older Raspberry Pi models become extremely sluggish to work with.

Supported Platforms

There are dozens of single board computers (SBCs) to choose from; we have tested this hardware with the Raspberry Pi and Nvidia platforms using their latest OS distributions (Bookworm and JetPack 6.2). To use the SparkFun GNSS Flex pHAT on other platforms, the SBC must have a compatible 40-pin GPIO header that follows Raspberry Pi's standardized pin layout.

Tip - Hardware Recommendations

We highly recommend using the Raspberry Pi 4B/5 and latest Nvidia Jetson Orin Nano. While users are free to use other boards or platforms, we cannot guarantee the functionality of our recommended software for those instances.

Jetson Orin Nano (super) - Tested and verified
Jetson Nano (4GB) - Tested and verified
Pi 5 - Tested and verified with 4GB version
Pi 4B - Tested and verified with 2GB and 4GB versions; would recommend avoiding the 1GB version due to the web browser requirements
Pi Zero 2W - Tested and verified; would recommend avoiding due to the web browser requirements
Pi 3A+ - Tested and verified; would recommend avoiding due to the web browser requirements
Pi 3B+ - Tested and verified
Pi 3B - Tested and verified; would recommend avoiding due to limitations in processing power
Pi Zero/Zero W - Avoid

PyGPSClient

The PyGPSClient software that we recommend below, provides a nice graphical user interface for the GNSS Flex modules. However, as with any GUI, it requires a decent amount of computational resources to run smoothly.

Users can try using the Pi Zero 2W, but just be aware that we noticed a small degree of lag in the GUI.
Just avoid using the Pi 3B (or older) and Pi Zero/Zero W models.

mosaic-X5 Web Server

The mosaic-X GNSS Flex module provides an internal web server, which can be utilized to change its configuration settings. However, when using the latest Raspberry Pi OS (Bookworm), the Chromium browser requires a decent amount of RAM to function. For this reason, we recommend using any Pi 4B or later model, with at least 2GB of RAM.

Save yourself the trouble and just avoid using the following Raspberry Pi boards:

Users can try using the Pi 3B+ model, but it will require a significant amount of patience waiting for a web page to load. The web page needs to reload each time users change a setting; and again, to save the settings.
Just avoid using the Pi 3B/A+ (or older) and Pi Zero/Zero W/Zero 2W models

Getting Started with your SBC

For users unfamiliar with the following platforms, we have linked additional resources below:

Raspberry Pi OS
Nvidia JetPack SDK
- JetPack SDK
  - NVIDIA SDK Manager Documentation
- Getting Started with Jetson Developer Kits
  - Jetson Orin Nano Super Developer Kit
    - User Guide
    - Getting Started Guide
  - Jetson AGX Orin Developer Kit
    - User Guide
    - Getting Started Guide
- Support

Update Software

Once users have got their SBC up and running, ensure that it is utilizing the latest software. Run the following commands to update and upgrade any installed packages:

sudo apt update
sudo apt full-upgrade
sudo apt autoremove --purge && sudo apt clean

Info

Advanced Package Tool (APT) is the recommended way to install, update, and remove software in Raspberry Pi OS. Users can access APT through the apt CLI.

Enable Serial Interface

Depending on the SBC platform, users may need to enable access to the serial interface from the 40-pin GPIO header for the operating system.

Configuration Settings

In the Raspberry Pi OS, users can enable access to the serial interface through the raspi-config configuration tool. The tool can be utilized through either the CLI or desktop GUI. To change the configuration settings, users will need to navigate through the Interface options > Serial port menus and enable the serial port.

Note

Not all of the advanced configuration options from the CLI are available in the Raspberry Pi Configuration GUI.

Disabling the Linux Serial Console

On the Pi 3/4/5/Zero 2W, users should keep access to the shell disabled from the serial interface.

Is PyGPSClient disconnecting?

If PyGPSClient disconnects from the serial port after a few seconds, you probably still have the Login Shell enabled. Use raspi-config to ensure: the serial port hardware is enabled; and that the login shell is not accessible.

Additional UARTs

The GNSS Flex pHAT supports up to four hardware UART connections. On Raspberry Pi, it may be necessary to enable the three additional UARTs manually. On Raspberry Pi 5, the additional ports usually appear as /dev/ttyAMA2, /dev/ttyAMA3 and /dev/ttyAMA4. In a Terminal Window, type ls /dev/tty* to list all the available ports. If the ports are not enabled, you can enable them by editing /boot/firmware/config.txt:

Edit /boot/firmware/config.txt
```
sudo nano /boot/firmware/config.txt
```

Add these three lines to the end of the file

dtoverlay=uart2
dtoverlay=uart3
dtoverlay=uart4

Save the file using crtl-X and select Save
Reboot the Pi with sudo reboot

UART Numbering

Please note that the UART numbers (UART1 - UART4) listed in the GNSS Flex Module hardware documentation refer to the GNSS UART numbering scheme. The mosaic-X5 supports four hardware UARTs (COM1 - COM4). The LG290P supports only three (UART1 - UART3).

Please also note that the UART numbers on Raspberry Pi will be different, as will the /dev/ttyAMA device names. There is not a 1:1 mapping between the Flex UART numbers and the Raspberry Pi UART numbers. The Raspberry Pi UART numbers also vary from model to model; the Pi 5 and Pi 4 numbering is different for example. On Pi 4, it is necessary to enable UART3 - UART5.

User Privileges

To access the serial port on most Linux platforms, users will need to be a member of the tty and/or dialout groups. This can be configured with either the adduser or usermod utilities.

adduser Utility
```
sudo adduser <username> <groupname>
```

usermod Utility

sudo usermod -aG <groupname> <username>

PyGPSClient

PyGPSClient is a free, open-source graphical interface for GNSS receiver testing and evaluation. We recommend the software for the Raspberry Pi and other SBCs because it is supported on multiple operating systems. It works very well on desktop machines too - if you have Python installed.

System Requirements

The installation requires an internet connection to download the Python package from PyPI. Additionally, users will also need administrative privileges (or root access sudo) for the installation and access the hardware connections. Other than this, no special privileges are required.

Installation

There are a variety of installation methods detailed in the GitHub repository's README.md file. However, we recommend utilizing either the pip installation method or installation shell script.

Shell Script

Installation instructions for the example shell scripts are detailed in the GitHub repository's README.md file.

Example Installation Script

pygpsclient_debian_install.sh

#!/bin/bash

# Bash shell script to install PyGPSClient on 64-bit Debian-based
# Linux environments, including Raspberry Pi and Ubuntu.
#
# Change shebang /bin/bash to /bin/zsh if running from zsh shell.
# NB: NOT for use on Windows or MacOS!
#
# Remember to run chmod +x pygpsclient_debian_install.sh to make this script executable.
#
# Full installation instructions:
# https://github.com/semuconsulting/PyGPSClient
#
# Created by semuadmin on 20 Sep 2023.
# 
# exit on error
set -e

PYVER="$(python3 -c 'import sys; print(".".join(map(str, sys.version_info[:2])))')"

echo "Installed Python version is $PYVER"

echo "PyGPSClient will be installed at $HOME/pygpsclient/bin"

echo "Installing dependencies..."
sudo apt install python3-pip python3-tk python3-pil python3-pil.imagetk \
     libjpeg-dev zlib1g-dev tk-dev python3-rasterio

echo "Setting user permissions..."
sudo usermod -a -G tty $USER

echo "Creating virtual environment..."
cd $HOME
python3 -m venv pygpsclient
source pygpsclient/bin/activate
python3 -m pip install --upgrade pip pygpsclient
deactivate

echo "Adding desktop launch icon..."
cat > $HOME/.local/share/applications/pygpsclient.desktop <<EOF
[Desktop Entry]
Type=Application
Terminal=false
Name=PyGPSClient
Icon=$HOME/pygpsclient/lib/python$PYVER/site-packages/pygpsclient/resources/pygpsclient.ico
Exec=$HOME/pygpsclient/bin/pygpsclient
EOF

echo "Adding directory to PATH..."
BASHPROF1=$HOME/.profile
BASHPROF2=$HOME/.bash_rc
ZSHPROF1=$HOME/.zprofile
ZSHPROF2=$HOME/.zshrc
if test -f $BASHPROF1
then
PROF=$BASHPROF1
elif test -f $BASHPROF2
then
PROF=$BASHPROF2
fi
if test -f $ZSHPROF1
then
PROF=$ZSHPROF1
elif test -f $ZSHPROF2
then
PROF=$ZSHPROF2
fi
sed -i '$a# Path to PyGPSClient executable\nexport PATH="$HOME/pygpsclient/bin:$PATH"' $PROF
source $PROF # this will throw an error if running as bash script in zsh shell

echo "Installation complete"

`pip` Installation

Installation instructions for the pip installation method are detailed in the GitHub repository's README.md file. Depending on how Python is installed on the computer, one of the following commands should allow users to install the software:

Jetson - Install pip

For the Jetson Orin Nano development kit, users will need to install pip before following the installation steps below.

sudo apt install python3-pip

Pi OS - Bookworm

Starting with Raspberry Pi OS Bookworm, users can no longer install Python packages, via pip, directly into the system version of Python. Instead, Python packages must be installed into a Python virtual environment (venv); a container where third-party modules can be safely installed without interfering with the system version of Python.

python3 -m pip install pygpsclient

pip3 install pygpsclient

Virtual Environment

With the latest version of the Raspberry Pi OS, Bookworm, users will need to follow to the instructions for utilizing a virtual environment.

Warning

Due to the nature of utilizing a virtual environment, these instructions will not function as a system wide installation. (i.e. You'll only be able to access the application with the <user>, used to install the application in their virtual environment.)

Create a Virtual Environment

To create a virtual environment, in a specific <directory>:

python3 -m venv <directory>

Example

Creating a virtual environment in the env directory:

python3 -m venv env

Activate the Virtual Environment

To activate the virtual environment that was created in the <directory>:

source <directory>/bin/activate

Install the Application in the Virtual Environment

Once inside the virtual environment, users can install the Python package with the normal pip installation command:
```
python3 -m pip install pygpsclient
```
Run the Application in the Virtual Environment

To run the application in the virtual environment:
```
pygpsclient
```

Example

To install and run the the Python package inside the env virtual environment:

source env/bin/activate
python3 -m pip install pygpsclient
pygpsclient

Deactivate the Virtual Environment

To deactivate the virtual environment:

deactivate

Once deactivated, the virtual environment can be reactivated with the activation command:
```
source <directory>/bin/activate
```

To reactivate and run the Python package in the virtual environment:

source <directory>/bin/activate
pygpsclient

Example

source env/bin/activate
pygpsclient

Enable User Port

In certain circumstances, users may need to manually configure the serial port for the application to function.

Pi 3/4/Zero 2W:

sudo pygpsclient ---userport /dev/ttyS0

Pi 5:

sudo pygpsclient ---userport /dev/ttyAMA0

Launch Options

While not required to operate the PyGPSClient software, user have additional options for how the Python package is executed.

To operate the software outside of a virtual environment, users can add the directory of the software's binaries to the PATH variable.
To utilize the software without an open terminal to be open, users can create a desktop application launcher.

Locate Relevant Binaries

The location of the relevant binaries folder can usually be found by executing one of the following commands:

If the package was installed in the virtual environment, activate it:
```
source <directory>/bin/activate
```
For a global installation, execute the following command:
```
python3 -c "import os,sysconfig;print(sysconfig.get_path('scripts'))"
```
The system should return the following directory for the relevant binaries, in a virtual environment:
```
/home/<user>/<directory>/bin
```
Deactivate, if inside a virtual environment:
```
deactivate
```

Example

For a virtual environment, to find the directory of the relevant binaries execute the following commands:

source env/bin/activate
python3 -c "import os,sysconfig;print(sysconfig.get_path('scripts'))"
deactivate

Add to `PATH` Variable

To make the Python package accessible outside of the virtual environment, the directory of the relevant binaries need to be added to the PATH variable:

export PATH="$PATH:<directory to relevant binaries>"
source ~/.profile

Example

export PATH="$PATH:/home/pi/env/bin"
source ~/.profile

Once added, the application should now be available outside of the virtual environment:

pygpsclient

Application Launcher

In addition to the previous sections, users can follow these instructions to create an application launcher.

Create a text file named pygpsclient.desktop with the following content and save it in the /home/<user>/.local/share/applications directory.

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

Example

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

Tip

Users can also validate the file, with the following command:

desktop-file-validate <file_name>.desktop

Logout and back in for the changes to take effect.

NTRIP Client

NTRIP server configurations — Configuration settings for connecting to an NTRIP client.

To receive and process NTRIP RTK correction data from an NTRIP server in the PyGPSClient software, users can follow these instructions:

Click on the icon, labeled NTRIP Client.
Enter the information for the network and mount point.
- For an NTRIP server hosted by the PyGPSClient software:
  - Server: IP address of Pi
  - Port: 2101
  - Mountpoint: pygnssutils
  - User: anon
  - Password: password
Click on the icon to connect to the server.

NTRIP Server

If their GNSS receiver is supported by NTRIP sever feature of the PyGPSClient software, users can follow these instructions to setup their Raspberry Pi to operate as an NTRIP sever:

In the settings console, scroll to the bottom and select NTRIP CASTER from the Mode drop-down menu.
Select the box for Configure Base Station and select the GNSS receiver from the drop-down menu.
Select a mode of operation for the base station and provide the necessary information.
Select the box for Socket Server/NTRIP Caster.

mosaic-X5 - Internet Access

In order to receive or cast RTK corrections to/from a RTK network, such as NTRIP, the mosaic-X5 GNSS receiver will need access to the internet through the USB interface.

Users will need to use the web interface to enable the Outgoing Internet Access Over USB from the Communication > USB drop-down menu of the navigation tabs.
This also requires users to configure a network bridge on the Raspberry Pi.

Editing the network connections to create a network bridge.
1. Open the network connections menu by opening the network manager (i.e. ↑↓ or icon on taskbar) and selecting Advanced Options > Edit Connections.
  
  Editing the connections through the Raspberry Pi's Network Manager.
2. Check the wired connections under Ethernet to locate the connection that lists Device: usb0 .... in its properties.
  
  Check the connections listed under Ethernet.
3. For that network connection, select the IP v4 Settings tab and select Shared to other computers from the Method drop-down menu.
4. Click Save to apply the changes.
5. Reboot the Raspberry Pi.
6. To determine the new IP address assigned to the mosaic-X5, click on network manager and select Advanced Options > Connection Information. Locate the IP address listed for the same wired connection.
  New IP Address
  
  Once a network bridge is enabled, the receiver will receive its IP address from the computer's DHCP server. Depending on the routing table, the module may no longer be reachable at its default IP address (192.168.3.1).
  
  If users need to determine the subnet address of the network connection, they need to install a tool called nmap.
```
sudo apt install nmap -y
```
  In a terminal enter the following command to determine IP address.
```
nmap <IP Address>/24
```
  - With the */24 option, the program will scan all the Class C subnet addresses (i.e. from A.B.C.x through A.B.C.255)
  Tip
  
  If the mosaic is still not connecting, try resetting it. The assigned IP should not change after it has booted.

Software Overview

Supported Platforms

Getting Started with your SBC

Raspberry Pi OS

Nvidia JetPack SDK

Update Software

Enable Serial Interface

Configuration Settings

Additional UARTs

User Privileges

PyGPSClient

Installation

Shell Script

pip Installation

Virtual Environment

Create a Virtual Environment

Activate the Virtual Environment

Deactivate the Virtual Environment

Enable User Port

Launch Options

Locate Relevant Binaries

Add to PATH Variable

Application Launcher

NTRIP Client

NTRIP Server

mosaic-X5 - Internet Access

`pip` Installation

Add to `PATH` Variable