Introduction

Welcome to the qt-test documentation. This guide provides comprehensive information for developers working with SitePoint GPS devices and the qt-test application.

Project Overview

qt-test is a Qt/QML desktop application for real-time GPS positioning with RTK (Real-Time Kinematic) corrections via Bluetooth Low Energy (BLE).

The application serves as both a functional GPS positioning tool and a reference implementation for developers building applications that communicate with SitePoint GPS receivers.

Key Features

  • Real-time GPS data acquisition via Bluetooth Low Energy

  • RTK correction data streaming via NTRIP protocol

  • Interactive map visualization with OpenStreetMap integration

  • Device configuration management for SitePoint GPS receivers

  • Cross-platform support for Windows, Linux, and macOS

  • Comprehensive API for integrating SitePoint devices into custom applications

Technology Stack

  • Qt Framework 6.5+ - Application framework

  • Qt Bluetooth - BLE communication

  • Qt Network - NTRIP client implementation

  • Qt Quick/QML - User interface

  • SQSP Protocol - SitePoint data structures

  • SQTP Protocol - SitePoint transport protocol

SitePoint Protocol Overview

SitePoint GPS devices communicate using proprietary protocols optimized for real-time positioning and correction data transmission.

SQSP (SitePoint Structures Protocol)

SQSP defines the data structures used to exchange information between the GPS receiver and host application. Key structures include:

SqspLla_t - Position Data

Contains latitude, longitude, altitude, and accuracy information. Updated at 8-10 Hz from the GPS receiver.

Key fields:

  • latitude (double) - Latitude in degrees (-90 to +90)

  • longitude (double) - Longitude in degrees (-180 to +180)

  • height (double) - Height above WGS84 ellipsoid in meters

  • hMSL (double) - Height above mean sea level in meters

  • hAcc (float) - Horizontal accuracy in meters

  • vAcc (float) - Vertical accuracy in meters

  • solutionType (uint8_t) - Solution quality indicator

SqspStatus_t - Device Status

Provides real-time information about GPS receiver state, satellite tracking, and correction status. Updated at 8-10 Hz.

Key fields:

  • numSatellites (uint8_t) - Number of satellites tracked

  • hdop (float) - Horizontal dilution of precision

  • vdop (float) - Vertical dilution of precision

  • correctionAge (uint32_t) - Age of correction data in milliseconds

  • aidingBins (uint32_t) - Aiding data availability bitmap

  • deviceState (uint8_t) - Current operational state

SqspLbConfig_t - Configuration Data

Contains device configuration including base station position for RTK operations. Uses double precision for all position values.

Key fields:

  • longitude (double) - Base station longitude

  • latitude (double) - Base station latitude

  • height (double) - Base station height

  • hMSL (double) - Base station height MSL

  • duration (int32_t) - Survey duration in seconds

SQTP (SitePoint Transport Protocol)

SQTP is a lightweight transport protocol for reliable data exchange over BLE. It provides:

  • Frame-based transmission with headers and CRC protection

  • Subframe identification for different data types

  • Bidirectional communication for commands and data

  • Efficient packing optimized for BLE MTU constraints

SQTP Frame Structure:

+----------+-------------+----------+----------+-------+
| Header   | Subframe ID | Length   | Payload  | CRC   |
| (2 bytes)| (2 bytes)   | (2 bytes)| (N bytes)| (2 B) |
+----------+-------------+----------+----------+-------+

Common Subframe IDs:

  • SQTP_ID_SITEPOINT_LLA (0x1244) - Position data

  • SQTP_ID_SITEPOINT_STATUS (0x1243) - Status data

  • SQTP_ID_SITEPOINT_LOCAL_BASE_CONFIG (0x1245) - Configuration and mode changes

  • SQTP_ID_RTCM (0x00D3) - RTCM correction messages (legacy)

NTRIP and RTCM Overview

RTK positioning requires correction data from a base station or network service. The application uses NTRIP (Networked Transport of RTCM via Internet Protocol) to receive correction data and RTCM (Radio Technical Commission for Maritime Services) messages to transmit corrections to the GPS receiver.

NTRIP (Networked Transport of RTCM)

NTRIP is an HTTP-based protocol for streaming RTCM correction data from a caster server to GPS clients.

Key Concepts:

  • Caster - Server that distributes correction data

  • Mountpoint - Specific correction stream identifier

  • Source Table - List of available correction streams

  • Credentials - Username/password for authentication

Typical NTRIP Connection:

Client                  NTRIP Caster              Base Station
  |                           |                          |
  |--- HTTP GET Request ----->|                          |
  |<-- 200 OK + Stream -------|<------ RTCM Data --------|
  |                           |                          |
  |--- RTCM Data Stream ----->|                          |

RTCM (Correction Data Format)

RTCM v3 messages contain differential GPS corrections in binary format. Common message types used for RTK:

  • 1005 - Stationary RTK reference station position

  • 1077/1087/1097 - MSM7 high-precision observations (GPS/GLONASS/Galileo)

  • 1074/1084/1094 - MSM4 medium-precision observations

  • 1230 - GLONASS code-phase biases

Message Structure:

+----------+-------------+----------+-------+
| Preamble | Reserved    | Message  | CRC   |
| (8 bits) | (6 bits)    | (N bits) | (24b) |
+----------+-------------+----------+-------+

Transmission via BLE:

RTCM messages are queued and transmitted to the SitePoint device via BLE characteristic 0x0102 using the RTCM transmission FSM (see BLE Communication with SitePoint GPS Devices).

Data Update Rates

Understanding data update rates is critical for application performance:

GPS Position Data (LLA):

  • Update rate: 8-10 Hz

  • Latency: < 20 ms typical

  • Change detection: Applied to prevent UI thrashing

GPS Status Data:

  • Update rate: 8-10 Hz

  • Contains real-time satellite and correction status

Configuration Data:

  • Update rate: On change only

  • Typically updated when device mode changes

NTRIP Correction Data:

  • Update rate: 1 Hz typical (varies by caster)

  • Message size: 100-800 bytes typical

  • Latency: Network-dependent (50-500 ms typical)

BLE Transmission:

  • Connection interval: 7.5-15 ms typical

  • MTU: 23-527 bytes (negotiated at connection)

  • Throughput: ~16-32 KB/s effective

Aiding Data

The aidingBins field in SqspStatus_t indicates availability of various aiding data sources that improve GPS performance:

Aiding Types (bitmap flags):

  • Bit 0: Ephemeris - Satellite orbit data

  • Bit 1: Almanac - Approximate satellite positions

  • Bit 2: UTC Model - Time correction parameters

  • Bit 3: Ionosphere Model - Atmospheric correction

  • Bit 4: RTCM Corrections - RTK correction data active

Interpreting aidingBins:

#define AIDING_EPHEMERIS    (1 << 0)
#define AIDING_ALMANAC      (1 << 1)
#define AIDING_UTC          (1 << 2)
#define AIDING_IONO         (1 << 3)
#define AIDING_RTCM         (1 << 4)

// Check if RTCM corrections are active
if (status.aidingBins & AIDING_RTCM) {
    qDebug() << "RTK corrections active";
}

Application Architecture

The application follows a manager-based architecture:

  • BLEManager - Handles all Bluetooth communication

  • NTRIPManager - NTRIP client for correction data

  • DataManager - Formats data for UI presentation

  • MapManager - Manages map display and position updates

See BLE Communication with SitePoint GPS Devices for detailed information on the BLE communication subsystem.

Target Audience

This documentation is designed for:

External Developers:

Software developers integrating SitePoint GPS devices into their applications. Covers protocols, APIs, and usage patterns.

Internal Developers:

SignalQuest developers working on the application. Includes internal tools and deployment documentation (see Internal Tools in internal build).

Document Organization