This folder contains a C++17 standard version of the IASDK. The SDK C++ API provides an object-based interface for controlling/configuring the radar and for processing incoming data.

This C++17 implementation additionally includes the source code of a peak finding function to operate on a single azimuth of raw radar data: the same functionality that is implemented within the radar firmware to enable Navigation Mode .

This version of the SDK was developed on Ubuntu 20.04. The Preferred compiler for building is Clang V10 but GCC 9.3.x should work.

Building the SDK

Prerequisites

Building using CMAKE

This assumes that the SDK has been cloned into ~/iasdk. To simplify the (arcane) CMake syntax, a simple batch script has been written to automate the build process. The script creates a folder, output, which holds the build. The script will create a subfolder - debug/release - depending on the option chosen at the commend line.

Unless otherwise specified, the default build type isdebug.

The output executables are placed in thr directory bin, below the build-type folder. For example:

Building from VS Code

The project is configured to work with the Microsoft CMake Tools. If the CMake Tools are installed, opening the project in VSCode should detect the make files and configure the project accordingly. The first time a build is selected you will need to select a compiler kit. This will present a list of possible compiler configurations.

Open VS Code in the project folder

VS Code can be launched directly from wsl and it will pick up the project configurations directly.

(As previously, assume the SDK has been installed in ~/iasdk)

Using the VS Code build task

The .vscode folder contains a build task configuration for invoking CMake. To build: * hit ctrl-shift-b * select Build

The following options are available:

Example projects

The SDK comes with three example projects.

colossus_client

This project gives an example of how to create a radar client and connect up free-function handlers for processing various message types. In this case, the radar client requests, and receives, FFT data from the radar. The FFT data itself is not processed, but statistics about the data are presented - packet rate, packet size and packet time.

Note, when a client connects to a radar a configuration message is always sent. The radar client must process this message, before requesting any other types.

The colossus_client program has two command-line options, as follows:

If an option is not provided, its default value will be used.

navigation_client

The navigation_client project is a sample application that will peak search and report back upto ten targets per azimuth.

The class Peak_finder can be used to process FFT data and search for peaks. The algorithm will sub-resolve within radar bins and return a power at a distance in metres on the azmith being checked.

The algorithm implemented here will slide a window over the FFT data moving forwards by the size of the window, when the FFT has risen and then fallen, the peak resolving algorithm is run to sub-resolve the distance.

See Peak_finder.h for the data structure that is generated per azimuth

• threshold - Threshold in dB

• bins_to_operate_on - Radar bins window size to search for peaks in

• start_bin - Start Bin

• buffer_mode - Buffer mode should only be used with a staring radar

• buffer_length - Buffer length

• max_peaks_per_azimuth - Maximum number of peaks to find in a single azimuth

The navigation_client program has two command-line options, as follows:

If an option is not provided, its default value will be used.

Connection_tester

The Connection tester project is a utility to stress-test the stability of the server. The program creates a radar client that randomly connects and disconnects from a server. On each connection, the radar client requests FFT data.

The Connection_tester object runs in its own thread-of-control and can therefore be run in parallel. Up to three Connection_tester objects can be run, all connecting/disconnecting to the same radar. More than three Connection_tester objects can be running, but a server will only allow a maximum of three connections at any one time.

The connection_tester program has three command-line options, as follows:

If an option is not provided, its default value will be used.

NOTE: The connection tester can be terminated with ctrl-c. This will send an asynchronous message to each Connection_tester object. The Connection_tester will only act upon this signal once it has completed its current connect/disconnect sequence. This means it may take several seconds for the program to end, and you may see additional connect/disconnects after the ctrl-c.

cat240_client

The cat240_client can connect to an ASTERIX CAT-240 source (for example, the cat240_server project) and will receive video messages. This project does not perform any significant processing on incoming video messages. NOTE: The cat240_client will not (currently) re-form video message packets that may have been split (by the server).

The cat240_server program has two command-line options:

nmea_client

This project gives a simple example for receiving NMEA messages over a UDP connection. At present, only the following NMEA messages can be handled:

• GPGGA

• GPRMC

• GPHDT

• PASHR

The messaging classes are currently simplistic and only perform basic message processsing (validation, conversion to string/vector, etc.) The nmea_client program has two command-line options:

nmea_server

This project gives a simple example for sending NMEA messages over a UDP connection. At present, only the following NMEA messages can be handled:

• GPGGA

• GPRMC

• GPHDT

• PASHR

The messaging classes allow construction of NMEA messages from strings or from vectors of std::uint8_t. There are currently no facilities for appending/removing message clauses. The nmea_server program has two command-line options:

If the IP address supplied falls into the range of multicast addresses (224.0.0.1 - 239.255.255.255) the server will be configured to multicast its NMEA messages.

colossus_protocol_tester

The colossus_protocol_tester application tests the Colossus messaging protocol between the radar and a client. It verifies that the radar is responding to commands and emitting data correctly. The program runs through a sequence of test cases, and presents the results. Some tests may run for several seconds (for example, if messages are sent at periodic intervals).

The colossuse_protocol_tester program has three command-line options:

For example:

Messaging protocol types

The SDK contains a minimum viable set of network messages for communicating to/from a radar. Currently the following protocols are supported: * Colossus, * Cambridge Pixel * ASTERIX CAT-240 * NMEA (limited capability).

All of the protocols follow a similar idiom for how they are sent, received and accessed. The protocols are designed to be extensible. Please see the /network/protocol/README.md file for a detailed overview of how the Colossus protocol code works, how it used, and how it can be extended.

Utilities

The SDK comes with a library of utilities classes and functions, designed to make programming easier. The utilities are used throughout the code. Notable examples include:

Time utilites (Time_utils.h)

The time utilities library provides an alternative to the C++ std::chrono library. The Time Utilities support both real-time and monotonic clocks. The main classes are: * Durations - A Duration represents a period of time. Durations have nanosecond resolution * Observations - An Observation represents a point in time; as a Duration from their clock's epoch.

Durations and Observations are designed to be compared manipulated in intuitive ways - for example, subtracting two Observations will yield the Duration between them. Durations and Observations also support expressive streaming options, meaning displaying/streaming time objects is simple.

Active classes (Active.h)

The Active class provides a high-level abstraction from OS threading and support for asynchronous messaging. See the Active.h header for more information on how to use the Active class.

Object lifetime managerment (pointer_types.h)

The code uses aliasing directives to make object lifetime management - ownership - as explicit as possible. Raw pointers for dynamically-allocated objects is discouraged. There is a distinct separation between object-to-object association (the "uses-a" relationship) and lifetime management of an object. owner_of and shared_owner types must never be used for association.

Under the hood: * owner_of is an alias of std::unique_ptr; * shared_owner is an alias of std::shared_ptr; * association_to wraps 'raw' pointers

Please see Utility/pointer_types.h for a more detailed explanation.

Networking utilities

The SDK contains a library of types for supporting networking. These include:

Programming with the SDK

Connection to a radar is handled through a Client object. A Client provides two basic interfaces:

• Setting up callbacks for incoming Colossus messages

• Sending Colossus messages (to the radar)

Constructing the Client

The Client must be constructed with the IP address and port number of the server:

In the above code we are using the user-defined literal _ipv4 to construct an IP_address object from a string literal.

Creating a callback

Incoming messages are dispatched to an appropriate callback, which must be provided by the client. The callback can be any C++ Callable type - that is, a function, a member function or a lambda expression - that satisfies the function signature:

Note, the callback has two parameters, the (incoming) message, and a reference to the (calling) Client. This reference allows the callback to access the API of the Client without resorting to static (global) Client objects. An example of how this may be exploited is shown below.

In this simple example, we'll use a free function to process the incoming configuration.

We must register the handler with the Client and associate it with a particular message type.

Next, we must set the Client running, so that it can connect to the radar and begin processing messages. The Client runs in its own thread. Callbacks are executed in the context of the Client (more specifically, in the context of the Client's Dispatcher thread). It is your responsibility to protect against race conditions if your callback functions interact with other threads-of-control.

For this example, we will simply let the Client run for a period of time, before stopping.

Handling incoming messages

The Colossus_protocol::Message type encapsulates a buffer with a basic interface for accessing data. For more details on the Message type, please read /network/protocol/README.md, which explains the concept behind the Colossus messaging classes.

To access the radar data in a message, the simplest way (and our recommended way) is to perform a memory overlay onto the message data. The Message class provides an interface for this. Once the overlay has been done, the specific message's API can be accessed to read from the message buffer. The API has been constructed to hide any endianess issues, scaling or conversion that may be required to get from 'raw' message bytes to usable radar information.

In the example above we are using the logging utility, stdout_log. This utility extends C++ console output, whilst maintaining a similar interface (all the IO manipulators available to std::ostream are also available to stdout_log, for example).

Handling protocol buffer from a message

If the incoming message contains a protocol buffer, this data can be extracted into a protobuf object and then accessed through the normal protobuf API.

Sending a message

The full details of sending Colossus messages is beyond the scope of this 'getting started' overview. For full details of how to construct and send Colossus messages, please read /network/protocol/README.md.

In the case of a radar client, typically only simple messages are sent to the radar, to enable/disable features such as FFT data, or radar health.

Remember - if you enable data transmission from the radar you must have a handler for it, otherwise you will receive an error each time a message arrives!

Sending a message within a callback

Commonly, you will want to send a message from within a callback. Since the callback has the Client as an argument, you can directly send a message.

Note, in the case of simple messages (with no header or payload), the send() method can construct the Colossus_protocol::Message object implicitly as part of the call.