Source code

The final weeks of project OCAP have started and we've begun to add the source code of the project to a Github repository (https://github.com/aschweiz/project-ocap).

Even though we're still performing real-world flight tests with our partners and have planned to perform code clean-up and performance optimizations during this time, we think that the structure and integration pattern of the code won't change much during this time.

This blog post explains how device manufacturers may integrate the source code into their application.

Structure of the code

The code consists of two program libraries, libocap and libadsl.

The latter, libadsl, implements creating and decoding I-Conspicuity packets as specified in the EASA ADS-L radio protocol (currently version 1, but will be updated as versions 2 and 3 become available).

The former, libocap, implements the collision warning algorithm. Technically, libocap is independent of the underlying protocol, but as ADS-L as an open standard by EASA is the obvious choice.

If a device vendor needs only the TX part, i.e. wants to make the device visible to other aircraft but doesn't want to perform collision warning for the own aircraft, for example for a simple beacon for paragliders, it's sufficient to integrate libadsl. Otherwise, both libraries need to be integrated.

Sequence diagrams

This section shows the interaction of the device vendor's applicaton code with libadsl and libocap.

Creating and transmitting an I-Conspicuity packet

To make the own aircraft visible to surrounding aircraft and to ground receivers, a device needs to broadcast an ADS-L I-Conspicuity packet, typically once per second. libadsl provdes functionality to create the packet based on GPS data and data about the aircraft.

For the grey boxes, the source code is available in the source code repository.

Sequence diagram for creating and transmitting ADS-L I-Conspicuity packets.

In a first step, the application calls createAdslPacket with GPS and aircraft information as input data. libadsl then constructs an I-Conspicuity packet from this information and returns it.

In a second step, the application calls adslEncodeIConspicuity with the ADS-L packet from the first step. This function creates the byte sequence, calculates the checksum and performs the XXTEA srambling.

In the third and last step, the application forwards the data bytes from step 2 to the radio transmitter.

Receiving and decoding I-Conspicuity packets from surrounding aircraft

Devices which should support collision warning need to implement the RX process, as shown in the following sequence diagram.

Sequence diagram for receiving ADS-L packets from surrounding aircraft.

For each received packet, the application forwards the raw bytes from the radio module to the adslDecodeIConspicuity function. This function de-scrambles, verifies and decodes the received packet and constructs an ADS-L packet structure. This packet structure contains the information about the other aircraft such as position, velocity, unique ID etc.

In the second step, the application forwards each decoded I-Conspicuity packet to the calculateOtherData function. This function processes the packet so that it is available for the collision warning algorithm.

Flight path prediction and collision warning calculation

Once per second, at the end of the RX time window, devices run the collision warning process, as shown in the following sequence diagram.

Sequence diagram for performing flight path prediction and calculating collision warnings.

First, the application needs to provide information on the own aircraft to libocap by calling the calculateOwnDataFromGpsInfo function.

Second, the application calls predictionCalculateAlarmState. This function extrapolates the flight path of the own aircraft and of surrounding aircraft for a specified amount (typically 30 seconds) into the future. It then checks the distance between the own aircraft and all surrounding aircraft. Using the warning criterion described in an earlier blog post (see https://www.project-ocap.net/post/revised-warning-criterion), the algorithm generates and stores collision warnings for the surrounding aircraft.

Third, the application checks the generated collision warnings with alarmStateListGetCount and alarmStateListGetAtIndex (0 <= i < count) and provides them to the pilot of the own aircraft. It's up to the device vendor how the warnings are presented (optically, acoustically). Warnings include an alarm level (low, medium, high), a time to collision (seconds) and a pointer to the affected aircraft. If desired, the application can call the helper function flightObjectOrientationCalculate to calculate the distance in meters and relative orientation in degrees of the affected aircraft, for example for graphically displaying the data on a screen.

Feedback and support

We're interested in feedback and can provide certain support for device vendors who would like to integrate libadsl and libocap into their device software. Please contact us at info@project-ocap.net.