GRX Developer Guide

This guide provides documentation and examples for using the GRX receiver API by SeRo Systems. It covers all public APIs, protocol definitions, and step-by-step instructions for Python, Java, and C++.

Overview

The GRX receiver API is built on gRPC and Protocol Buffers, two widely adopted frameworks (used by Google, Netflix, Docker, and many others) for building language-agnostic, high-performance APIs. Over 20 programming languages are supported, including Python, Java, C++, Go, C#, and Ruby.

Note

If you are developing an application that runs directly on the device, the API is always available via the loopback interface – even if the external API is not enabled in the device’s configuration.

API Overview

The GRX API is split into five services, each running on its own TCP port:

Service	Port	Description
Receiver API	5303	Received signals (Mode S, Mode 1/2/3/A/C, UAT, DME/TACAN, etc.), tracking data, radio front-end status, I/Q samples per detection
Monitoring API	5305	System health, GNSS position and timing, CPU/memory/network usage
Spectrum API	5306	FFT spectrum data, waterfall charts, channel power measurements
Sample Streaming API	5308	Continuous raw I/Q sample streaming (SDR-like)
Tunable Channel API	5309	Configuration of tunable radio front-ends (frequency, bandwidth, gain)

Note

Which data and APIs are available depends on the radio front-end(s) installed in your GRX. For example, a GRX1090 only receives on 1090 MHz, while a GRX3X can monitor up to three frequency bands simultaneously. The Tunable Channel API is only available on receivers equipped with a tunable SDR-like daughterboard. The Sample Streaming API is only available on the GRX3X.

Getting Started

To use the API from your application:

1. Download the .proto files (see Protocol Buffer Definitions)

2. Generate language-specific bindings using the Protocol Buffer compiler protoc

3. Connect to the GRX receiver using gRPC and call the desired methods

Language-specific setup instructions are provided for Python, Java, and C++.

Tip

New to programming? An AI assistant such as Claude, Codex, or ChatGPT can guide you from installing the required tools to running a GRX application. Download the starter files, ask the assistant to read the included AGENTS.md, and describe what you need.

API Reference

• Receiver API
  • Service Methods
  • Tracked Targets (State Vectors)
  • Radio Front-End Status
  • Streaming Signal Data
  • Multiple Radio Front-Ends
  • Protocol Buffer Definition
• Monitoring API
  • Service Methods
  • GNSS Position and Timing
  • System Health
  • Protocol Buffer Definition
• Spectrum API
  • Service Methods
  • How It Works
  • Waterfall Charts
  • Channel Power
  • Multiple Radio Front-Ends
  • Protocol Buffer Definition
• Sample Streaming API
  • Service Methods
  • Stream Properties
  • Starting a Stream
  • Identifying Radio Channels
  • Protocol Buffer Definition
• Tunable Channel API
  • Service Methods
  • Discovering Tunable Channels
  • Configuring a Channel
  • Typical Workflow
  • Protocol Buffer Definition

Protocol Definitions

• gRPC and Protocol Buffers
  • How gRPC Works
  • Generating Language Bindings
  • Protocol Buffer Definitions

Language Guides

• Python Guide
  • Prerequisites
  • Step 1: Set Up a Virtual Environment
  • Step 2: Install Dependencies
  • Step 3: Generate Python Bindings
  • Step 4: Connect and Use the API
  • Examples
• Java Guide
  • Prerequisites
  • Step 1: Create a Maven Project
  • Step 2: Configure Protobuf Compilation
  • Step 3: Build
  • Step 4: Connect and Use the API
  • Examples
• C++ Guide
  • Prerequisites
  • Step 1: Project Structure
  • Step 2: CMakeLists.txt
  • Step 3: Examples
  • Step 4: Build and Run
  • Cross-Platform Notes
• Use an AI Assistant to Build a GRX Application
  • Before You Start
  • 1. Give the Assistant This First Message
  • 2. Follow the Instructions One Step at a Time
  • 3. Run and Extend Your Application
  • Helpful Follow-up Prompts
  • Choosing a Language
  • Safety and Troubleshooting