Installation

Updated on Aug 29, 2026

Build the library from source on Raspberry Pi or another Linux system with the packages needed for the features you want. The default upstream configuration builds the shared library and CLI tools. Python bindings, examples, tests, and NTRIP TLS support are enabled with extra CMake flags.

Dependencies

Install the recommended base dependencies:

sudo apt-get update
sudo apt-get install build-essential cmake libgpiod-dev libtoml11-dev

Add optional packages as needed:

Package	Needed for
`python3-dev`	Python bindings (`BUILD_PYTHON=ON`)
`libssl-dev`	TLS for NTRIP (`NTRIP_TLS_SUPPORT=ON`)
`libgtest-dev`	Unit tests (`BUILD_TESTS=ON`)

Note
BUILD_TOOLS is enabled by default in the upstream project, so libtoml11-dev is part of the recommended install even for a basic native build. If you only need the shared library, you can disable the tools with -DBUILD_TOOLS=OFF.

Build & Install

Clone and build the project:

git clone https://github.com/jimmypaputto/gnsshat.git
cd gnsshat
mkdir -p build && cd build
cmake .. -DBUILD_PYTHON=ON -DBUILD_EXAMPLES=ON
make
sudo make install

Installation Complete
The install step places the shared library, headers, pkg-config metadata, and CMake package files under /usr/local. Optional components such as Python bindings, examples, and CLI tools are installed when you enable them.

Common CMake Options

Option	Default	Description
`BUILD_PYTHON`	`OFF`	Build and install the Python CPython extension module
`BUILD_EXAMPLES`	`OFF`	Build C and C++ examples. Convenience symlinks are created in `examples/bin/`
`BUILD_TOOLS`	`ON`	Build `gnsshat-info`, `gnsshat-probe`, and `gnsshat-rtk-base`
`BUILD_TESTS`	`OFF`	Build unit tests; run them with `ctest`
`NTRIP_TLS_SUPPORT`	`OFF`	Enable OpenSSL/TLS support for NTRIP features
`GNSSHAT_PLATFORM`	`auto`	Target platform: `auto`, `generic`, `rpi4`, or `rpi5`

Note
On Raspberry Pi 4 and Pi 5, GNSSHAT_PLATFORM=auto detects the board and selects the correct GPIO chip automatically. Override it only when cross-compiling or forcing a non-default target.

Python Module Standalone Build

The Python module can also be built separately after the C/C++ library is already installed:

cd gnsshat/python
mkdir -p build && cd build
cmake .. 
make
sudo make install

This installs into the system Python platform-library path under /usr, for example /usr/lib/python3/dist-packages/jimmypaputto/ on Debian-based systems.

Troubleshooting

Missing toml11

If CMake fails while configuring the CLI tools, install libtoml11-dev or rebuild with -DBUILD_TOOLS=OFF.

libgpiod Detection

Current upstream CMake auto-detects whether your system has libgpiod v1 or v2. If configuration fails after changing system packages, delete the build/ directory and configure again so detection runs fresh.

UART Configuration

If you see:

[UART] Failed to open UART device: No such file or directory
[UART] Cannot init epoll - UART not initialized

enable the UART interface (for example via raspi-config):

sudo raspi-config

Navigate to Interface Options → Serial Port and enable the serial hardware interface. A reboot is required.

Important
Only the L1/L5 TIME HAT (NEO-F10T) and the L1/L5 RTK HAT (NEO-F9P) require UART. The L1 GNSS HAT (NEO-M9N) uses SPI only.