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

Want to get started quickly? Use an LLM (Claude, ChatGPT, etc.) to generate client code for you. Download our LLM context file containing the full API definitions and examples, paste it into a chat, and describe what you need. This works with any programming language – not just the ones documented here.

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
• Using LLMs to Generate GRX Client Code
  • LLM Context File
  • Recommended First Prompt
  • Example Prompts
  • Tips for Best Results
  • Obtaining Proto Files