Java Guide

This guide shows how to set up a Java project to use the GRX API with Maven, compile the Protocol Buffer definitions, and run the provided examples.

Prerequisites

• Java 17 or later (JDK)

• Maven 3.6 or later

Step 1: Create a Maven Project

Add the following dependencies to your pom.xml:

<properties>
    <protobuf.version>4.34.0</protobuf.version>
    <grpc.version>1.79.0</grpc.version>
</properties>

<dependencies>
    <dependency>
        <groupId>com.google.protobuf</groupId>
        <artifactId>protobuf-java</artifactId>
        <version>${protobuf.version}</version>
    </dependency>
    <dependency>
        <groupId>io.grpc</groupId>
        <artifactId>grpc-netty</artifactId>
        <version>${grpc.version}</version>
    </dependency>
    <dependency>
        <groupId>io.grpc</groupId>
        <artifactId>grpc-protobuf</artifactId>
        <version>${grpc.version}</version>
    </dependency>
    <dependency>
        <groupId>io.grpc</groupId>
        <artifactId>grpc-stub</artifactId>
        <version>${grpc.version}</version>
    </dependency>
    <dependency>
        <groupId>javax.annotation</groupId>
        <artifactId>javax.annotation-api</artifactId>
        <version>1.3.2</version>
    </dependency>
</dependencies>

Step 2: Configure Protobuf Compilation

Add the protobuf Maven plugin to automatically compile .proto files during the build:

<build>
    <extensions>
        <extension>
            <groupId>kr.motd.maven</groupId>
            <artifactId>os-maven-plugin</artifactId>
            <version>1.7.0</version>
        </extension>
    </extensions>
    <plugins>
        <plugin>
            <groupId>org.xolstice.maven.plugins</groupId>
            <artifactId>protobuf-maven-plugin</artifactId>
            <version>0.6.1</version>
            <configuration>
                <protocArtifact>
                    com.google.protobuf:protoc:${protobuf.version}:exe:${os.detected.classifier}
                </protocArtifact>
                <pluginId>grpc-java</pluginId>
                <pluginArtifact>
                    io.grpc:protoc-gen-grpc-java:${grpc.version}:exe:${os.detected.classifier}
                </pluginArtifact>
            </configuration>
            <executions>
                <execution>
                    <goals>
                        <goal>compile</goal>
                        <goal>compile-custom</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Place the downloaded .proto files in src/main/proto/.

Note

In this repository, the java/src/main/proto/ directory already contains symlinks to the public v3 proto files. If you create a new Maven project, copy or download all six public proto files into your project’s src/main/proto/ directory before running Maven.

Step 3: Build

mvn clean compile

This compiles the .proto files into Java classes under target/generated-sources/protobuf/.

Step 4: Connect and Use the API

Here is a minimal example:

import com.google.protobuf.Empty;
import de.serosystems.proto.v3.grx.receiverd.*;
import io.grpc.ManagedChannel;
import io.grpc.ManagedChannelBuilder;

public class QuickStart {
    public static void main(String[] args) {
        // Connect to the Receiver API (port 5303)
        ManagedChannel channel = ManagedChannelBuilder
            .forAddress("YOUR_GRX_IP", 5303)
            .usePlaintext()
            .build();

        ReceiverdGrpc.ReceiverdBlockingStub stub =
            ReceiverdGrpc.newBlockingStub(channel);

        // Get all tracked aircraft
        ReceiverDProto.StateVectorList sv =
            stub.getStateVectors(Empty.getDefaultInstance());

        System.out.println("Tracking " + sv.getStateVectorsCount()
            + " aircraft");

        channel.shutdownNow();
    }
}

Examples

The following examples are provided in the java/ directory. Each is a self-contained class with a main method.

To build and run all examples:

# from the repository root
cd java/
mvn clean package
java -cp target/grx-client-*.jar de.serosystems.grx.example.TrackedAircraft [HOST]

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

Receiver API Examples

DeviceStatus.java – Radio Front-End Status

Queries radio front-end hardware status including gains, noise levels, antenna ports, and antenna switches.

Download DeviceStatus.java

TrackedAircraft.java – List Tracked Aircraft

Retrieves and displays all currently tracked aircraft with ICAO address, callsign, position, altitude, speed, and track.

Download TrackedAircraft.java

BlockingModeSDownlink.java – Blocking Mode S Stream

Subscribes to Mode S downlink frames (DF11/DF17) using a blocking iterator. Collects 10 frames and prints hex payload and signal level.

Download BlockingModeSDownlink.java

AsyncModeSDownlink.java – Asynchronous Mode S Stream

Subscribes to Mode S downlink frames using a StreamObserver for asynchronous processing. Runs for 5 seconds.

Download AsyncModeSDownlink.java

IQSamples.java – Mode S with I/Q Samples

Subscribes to DF17 with I/Q sample collection. Parses the S16I_S16Q sample format into separate I and Q arrays.

Download IQSamples.java

Monitoring API Examples

GNSSStatus.java – GNSS/GPS Information

Retrieves GNSS status including position, fix type, UTC time, satellite count, and accuracy metrics.

Download GNSSStatus.java

Spectrum API Examples

SpecShot.java – Waterfall Chart

Queries FFT parameters and captures a waterfall JPEG image. Displays the result in a Swing window.

Download SpecShot.java

Sample Streaming API Examples

SampleStreaming.java – Continuous I/Q Streaming

Queries stream properties and receives I/Q sample blocks from a radio channel.

Download SampleStreaming.java

Tunable Channel API Examples

TunableChannel.java – Query/Configure Tunable Channels

Lists available tunable channels and queries their current center frequency, bandwidth, sample rate, gain, and RX ports.

Download TunableChannel.java