Python Guide

This guide shows how to set up a Python project to use the GRX API, generate the required gRPC bindings, and run the provided examples.

Prerequisites

Python 3.8 or later (3.11 or later for the examples that use pyModeS)
pip package manager

Step 1: Set Up a Virtual Environment

We recommend using a virtual environment to isolate dependencies:

Linux / macOS:

python3 -m venv venv
source venv/bin/activate

Windows (Command Prompt):

python -m venv venv
venv\Scripts\activate.bat

Windows (PowerShell):

python -m venv venv
.\venv\Scripts\Activate.ps1

Step 2: Install Dependencies

Install the gRPC and Protocol Buffers libraries:

pip install grpcio grpcio-tools

For the example scripts that decode or visualize data, you may also need:

# Mode S / ADS-B decoding (pyModeS 3 requires Python 3.11+)
pip install "pyModeS>=3"

# Image display (for waterfall charts)
pip install Pillow

Step 3: Generate Python Bindings

Download the .proto files (see Protocol Buffer Definitions) into one directory. The command below assumes that directory is named protos/ and that you want the generated Python files in your current working directory:

python -m grpc_tools.protoc \
    -I./protos \
    --python_out=. \
    --grpc_python_out=. \
    ./protos/Common.proto \
    ./protos/Receiverd.proto \
    ./protos/Monitord.proto \
    ./protos/Spectrumd.proto \
    ./protos/Samplestreamingd.proto \
    ./protos/TunableChanneld.proto

This generates *_pb2.py (message classes) and *_pb2_grpc.py (service stubs) files in the current directory. Run your script from that same directory, or add the generated output directory to PYTHONPATH.

Note

In this repository, a convenience script gen_pb.sh is provided in the python/ directory. From the repository root, run cd python and then bash gen_pb.sh. The provided Python examples should then be run from the python/ directory so they can import the generated modules.

Step 4: Connect and Use the API

Here is a minimal example that connects to a GRX and retrieves tracked aircraft:

import grpc
from google.protobuf.empty_pb2 import Empty
import Receiverd_pb2_grpc

# Connect to the Receiver API (port 5303)
channel = grpc.insecure_channel("YOUR_GRX_IP:5303")
receiverd = Receiverd_pb2_grpc.ReceiverdStub(channel)

# Get all tracked aircraft
state_vectors = receiverd.GetStateVectors(Empty())

for ac in state_vectors.state_vectors:
    print(f"ICAO: {ac.qualified_address.address:06x}, "
          f"Signal: {ac.average_signal_level_directly_received:.1f} dBm")

channel.close()

For streaming data (e.g., Mode S frames):

import Receiverd_pb2 as receiverd_pb2

# Subscribe to DF11 and DF17 Mode S frames
request = receiverd_pb2.GetModeSDownlinkFramesRequest(
    downlink_formats=[11, 17]
)
stream = receiverd.GetModeSDownlinkFrames(request)

for reply in stream:
    print(reply.frame.payload.hex())

# To stop: stream.cancel()

Examples

The following examples are provided in the python/ directory. Each is a self-contained script that can be run with:

cd python
bash gen_pb.sh
python <script_name>.py [GRX_HOST]

Replace YOUR_GRX_IP in the script with your receiver’s IP address, or pass it as a command-line argument.

Receiver API Examples

device_status.py – Radio Front-End Status

Queries the radio front-end hardware status, including gain settings, noise levels, and antenna information.

Download device_status.py

tracked_aircraft.py – List Tracked Aircraft

Retrieves and displays all currently tracked aircraft with ICAO address, callsign, position, altitude, and signal level.

Download tracked_aircraft.py

modes_downlink.py – Stream Mode S Downlink Frames

Subscribes to Mode S downlink frames (DF11/DF17) and prints each frame with signal metadata. Uses pyModeS for decoding. Demonstrates format filtering.

Download modes_downlink.py

Additional dependency: pip install "pyModeS>=3"

modes_iq_samples.py – Mode S with I/Q Samples

Subscribes to Mode S downlink with I/Q sample collection enabled. Shows how to configure SampleEnableRule filters and parse raw I/Q data.

Download modes_iq_samples.py

Additional dependency: pip install "pyModeS>=3"

mode_ac.py – Mode 1/2/3/A/C Downlink Replies

Streams Mode 1/2/3/A/C replies with binning (grouped receptions of the same code). Demonstrates low-level gRPC API usage and GPS timestamp conversion.

Download mode_ac.py

Monitoring API Examples

gnss_info.py – GNSS/GPS Information

Retrieves the device’s GNSS status including position, fix type, timing accuracy, and hardware monitoring data.

Download gnss_info.py

Spectrum API Examples

spectrum_waterfall.py – Waterfall Chart

Queries FFT parameters and captures a waterfall JPEG image. Displays the result using the system image viewer.

Download spectrum_waterfall.py

Additional dependency: pip install Pillow

Sample Streaming API Examples

sample_streaming.py – Continuous I/Q Streaming

Streams continuous raw I/Q sample blocks from a radio channel. Shows how to query stream properties and parse the sample data.

Download sample_streaming.py

Tunable Channel API Examples

tunable_channel.py – Query/Configure Tunable Channels

Lists available tunable channels and queries their current settings (frequency, bandwidth, sample rate, gain, RX ports). Includes commented-out code showing how to tune to a new frequency.

Download tunable_channel.py