Subscribing to OGN data using Java

Subscribing to OGN data

A simple Java API is available allowing to subscribe to the OGN beacons (aircraft positioning updates as well as base stations beacons).
The source code is available on GitHub and can easily be built with Apache Maven.

Projects

ogn-commons-java

This project provides classes and interfaces describing aircraft and receiver beacons (OgnBeacon and its specializations: AircraftBeacon & ReceiverBeacon), classes implementing parsing mechanisms for OGN APRS sentences, utility classes for serialization and deserialization of OGN beacons to and from JSON, aircraft descriptors, handling FlarmNet database, etc.
This module is to be shared across other java modules or applications and should be easily compilable on different platforms (including Android), therefore it is kept simple, with absolute minimum 3rd party dependencies needed.

For detailed API description, please look into the JavaDoc

Beacons interfaces

class or interface description additional info
OgnBeacon parent beacon interface with properties common to all beacons regardless of their type
AircraftBeacon interface of the aircraft beacon
ReceiverBeacon interface of the ground receiver beacon
AircraftDescriptor static aircraft descriptive information when subscribed to aircraft beacons, AircraftDescritor is given in a callback (see: ogn-client's AircraftBeaconListener for details)
AircraftDescriptorProvider interface which all aircraft descriptor providers must implement

AircraftType and AddressType

class or interface description additional info
AircraftType defines all possible aircraft types handled by the system. The definitions are taken from FLARM spec.
AddressType defines types of hardware addresses supported by OGN if type is "OGN", it means a packet originates from a OGN tracker

Aircraft Descriptor providers

The "core" aircraft beacons do not carry any "descriptive" information about an aircraft, such as e.g. it's registration or competition number. By using descriptor providers you can easily get link these static information to each aircraft beacon received.

class or interface description additional info
FileDbDescriptorProvider This AircraftDescriptorProvider resolves AircraftDescriptors from different file databases, e.g. FlarmNetdepricated or OGN db for an example of how different types of descriptor providers (ONG, FlarmNet..) are created and used, refer to OgnDemoAircraftBeaconsClient2

Other classes

class or interface description additional info
IgcLogger The Igc logger creates IGC logs. It can work in sync or async (non-blocking) mode
FlarmNetDb Handles FlarmNet db. Flarmnet data can be loaded remotely (e.g. directly from flarmnet) or from a local flarmnet db. file and is kept in the internal cache. Every time refresh() is called the cache is updated. This class is thread-safe! Depricated: Please use OgnDb instead
OgnDb Handles OGN db. OGN data can be loaded remotely (e.g. directly from ogn server) or from a local db file. file and is kept in the internal cache. Every time refresh() is called the cache is updated. This class is thread-safe!

Utility classes

class or interface description additional info
AprsUtils utility methods handy when decoding OGN APRS messages
JsonUtils serialization/deserialization to/from JSON
StringUtils utility methods converting ASCII to HEX (and vice verca), generating md5 hashes etc..
Version conversion of version strings in X.Y.Z format to numeric representation and vice versa

ogn-client-java

This project provides classes and interfaces allowing subscription to OGN beacons. It provides factory for creating OGN client objects, handling subscriptions, defines beacon listeners, etc..
This library can be used by any Java application which needs to subscribe to OGN data.

depends-on: ogn-commons

For detailed API description, please look into the JavaDoc

Main classes and interfaces

class or interface description additional info
AircraftBeaconListener
ReceiverBeaconListener
OgnClient When connecting, you can pass APRS filter as an argument to Client's connect() method.
OgnClientFactory To be used to create OGN client instances can be used with or without AircraftDescriptorProviders (see 2 examples below)

Demo client programs

Subscribing to aircraft beacons
Simplest subscription

The example below shows how to use OGN client to subscribe to AircraftBeacons. No aircraft descriptor providers are used, therefore the client will receive bear beacons, with no static information describing an aircraft.

OgnDemoAircraftBeaconsClient
Program Output

Using descriptor providers

In most cases, you want to know what is the aircraft you get a positioning update for. You can configure OGN client to use so-called AircraftDescriptorProviders which will be resolving this information for you automatically. OGN commons library includes FileDbDescriptorProvider which can be used together with FlarmNetDb or OgnDb. The OGN database is the default source of the aircraft descriptive information, however if needed, you are free to implement your own, custom providers.

The example below demonstrates how to use OGN client to subscribe to AircraftBeacons, using aircraft descriptor providers to resolve static information describing aircraft.

Please note that one can register more than one aircraft descriptor providers at a time. In such case they will be queried in the order of declaration, until a successful descriptor is found, or none.

OgnDemoAircraftBeaconsClient2
Program Output

Creating multiple client instances

Sometimes you may need to create several instances of OGN client (e.g. you may want them to subscribe with different filters or to different servers, on different ports etc..)
OgnDemoAircraftBeaconsClient3 demonstrates how to do it.

Subscribing to receiver beacons

The example below demonstrates how to use OGN client to subscribe to ReceiverBeacons.

OgnDemoReceiverBeaconsClient
Program Output

ogn-gateway-java

The gateway is a standalone application and its main purpose is logging traffic passing through the OGN infrastructure and relaying OGN beacons to different systems (namely live.glidernet.org, FR24,…). In addition some computing plugins are implemented (e.g. the "stats" plugin), which process information extracted from the beacons (aircraft and receiver).
The so-called for "forwarders" are implemented as plugins and once deployed to the expected plugin folder are automatically registered and start working. No need to restart ogn-gateway for that!
OGN gateway also logs all packets into IGC files (can be enabled/disabled) and it is configurable.

A plugin receives notifications on its interface ( respectively AircraftBeacon or ReceiverBeacons ) and can do with it whatever it needs ( forward, compute some information etc.)

Please refer here for the detailed information concerning the OGN gateway.

depends-on: ogn-commons, ogn-client

howto build

To build modules, you will need JDK 7+ and Maven to be installed in your system. This is not the place to introduce Maven in details, most Java developers are familiar with the tool anyway. If you are developing under Eclipse, it will be convenient for you to install m2e plugin.

Please mind the dependency between the modules. If you are building from command line, you must build the modules in the following order:

cd ogn-commons-java
mvn install

cd ..
cd ogn-client-java
mvn install
cd ogn-gateway-java
mvn package

quick maven installation under ubuntu

Follow this simple procedure

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License