Development / Protocol


The NGCTRL2 UAV Communication Protocol

{i} This is work in progress! Please post in the forum when you find errors or mistakes!

General overview

The NGCTRL2 protocol is a simple asynchronous serial protocol used between NGOS and it's client implementation in libng (available in the source code release). Essentially it's a packet driven, eg. each message has a message type and messages may arrive asynchronously and out of order.

The client library libng implements everything needed to open a connection to NGOS, request data packets with arbitrary intervals and default parsers for all available packet types. A client application opens a NGCTRL2 connection, requests packet types and intervals and specifies the parser function to process received packets.

There are several parser functions implemented in libng allowing you to process the received data:

{i} It's also easily possible to implement your own parser function and use that.

Usage of the NGCTRL2 protocol in the NGOS shell

The NGOS shell has shell commands which allow you to inspect and manipulate the NGCTRL2 packet dumping.

Make sure to enable the API mode, so that the special API shell commands are available to you:

You can inspect the available packet types with the command api ngctrl-v2-list-types.

You can also inspect the NGCTRL2 packet dumping tables. In this case we are dumping 5 packet types in intervals of 500ms on UART0:

It's also possible to request packet dumping with a shell command. To start dumping packet type 4 (motors 5-8) in an interval of 500ms use the following commands:

Now, NGCTRL2 is active on UART0 and sends packet type 4 all 500ms. To switch it off again, use the following shell commands:

The command line tool NGCTRL2

ngctrl2, the command line tool, uses the parsers described on this page to implement simple command and data query access to NGOS.

It's arguments are quite simple:

In essence you tell it what communication port to use (--device, --baud, --flowctrl), then you tell it what to request (--request) and choose if you want to print it to your screen (--log) or to a file (--log-to-file).

A sample usage where we request packets of type 2 (attitude) with a 500ms interval:

As you can see the argument to --request is <packet-type>:<intervall>.

Besides requesting certain packet types, ngctrl2 will also display out-of-order packets received. An out-of-order packet is a packet, which you did not request but which gets sent to you automatically when an event happens.

A sample of an out-of-order packet can be seen here:

As you can see above, we receive a packet of type DUMP_PKG_FLIGHTSTATE, whenever NGOS changes it's flight state.

Out-of-order packets can be ignored, or they can be handled by the client application.

Simple NGCTRL2 communications

Available NGCTRL2 packet types

The following are the available packet types in the NGCTRL2 protocol (defined in ngos/src/fc/ctrl/dump.h):

These are the packet types you may request together with an interval specifying how often you want to receive that data packet. Please note that packets may arrive out of order.

NGCTRL2 functions in library libng

The following functions are implemented in libng and are defined in ng.h:

The NGCTRL2 protocol packet definition

NGCTRL2 dispatches NGCTRL2 packets between NGOS and PC (or better libng). Each packet may contain an arbitrary count of data-sets. All data-sets sent out within one cycle will be queued up inside a single NGCTRL2 packet and sent out together as one packet.

These packets are COBS (Constant Overhead Byte Stuffing) encoded, which makes sure that no zero byte will show up inside the packet. The NGCTRL2 packet is framed with a zero byte. Each packet contains a simple one byte checksum at the end of the packet.

{i} The COBS algorithm has a constant worst case overhead of 1 byte per 255 bytes - whereas normal byte stuffing algorithms have a non-constant worst case of up to 200% of packet size - making sure our packets will not grow madly with deformed packet data content.

A NGCTRL2 packet consists of a arbitrary length series of data-sets, a checksum and a framing bytes. Each data-set consists of a type byte, specifying the data-set data content and size, and the payload with the implicit size given by the data-set type. These arbitrary count of data-sets are followed by a one byte XOR checksum. The whole packet gets COBS encoded and framed with a zero byte.

Concluding one can specify a NGCTRL2 packet like this:

There are a lot of different data-set types available in NGOS.

Here is a non conclusive list of the available data-set types:

Each of the above data-set types can be requested by a client application, either continiously with a arbitrary interval time or just once, for a snapshot of the current state.

The NGCTRL2 packet parsers

The NGCTRL2 printf parser

Requesting data from your NG and output it using the printf parser is a simple thing consisting of a handful lines of code.

{i} Make sure to link the resulting object file with the NG client library

The NGCTRL2 fprintf parser

Requesting data from your NG and output it using the fprintf parser is very similar to using the printf parser. The only difference is that you have to open a file before hand using a special file descriptor exported by libng.

{i} Make sure to link the resulting object file with the NG client library

Your own NGCTRL2 packet parser

A NGCTRL2 packet parser is nothing more than a function with defined arguments and return value.

Having defined a parser function like the one above, you can now specify it when you setup the packet dispatcher:

{i} Make sure to link the resulting object file with the NG client library

Development/Protocol/NGCTRL2 (last edited 2011-12-12 10:09:48 by TaarekGuindehi)