-
Notifications
You must be signed in to change notification settings - Fork 167
Development UAVTalk Protocol
UAVTalk is a highly efficient, extremely flexible and completely open binary protocol designed specifically for communication with UAVs.
The UAVTalk Protocol uses the concept of telemetry objects. The object based design allows the protocol to be optimized for low speed telemetry channels but conversely can also be configured for rapid update times and large object payloads for high bandwidth links. Each object is 243 bytes or less (so as to keep the total frame size under 256 bytes) and identified by a unique 32 bit object ID, and corresponds to a specific type of information relating to flight operations: gyro values, range information, GPS coordinates, etc.
Information may be configuration objects set by the ground station, used internally by the flight controller and additionally downlinked as telemetry, or purely informational in nature. Metaobjects are used to configure whether flight or ground station can update specific data units and at what rate they should be telemetered.
The protocol is channel independent since it is used over a wide variety of channels: USB HID, TCP networks, logs, local serial, wireless modems, etc.
To support a variety of data objects, the low level protocol is not aware of the structure of the data transmitted. Packing, unpacking and interpretation of the data is handled by the upper layers. The diagram below shows the structure of the protocol and it is described in more detail in the following sections.
The UAVTalk protocol implements the low level communication between the GCS and the autopilot. It simply provides the transport of the data structures defined by the UAVObjects. To make the addition of UAVObjects easier, the UAVTalk protocol does not need to know the details of the data structure as this is handled by the UAVObject instead. UAVTalk is only responsible of sending byte arrays and routing received byte arrays to the correct object for unpacking.
The packet format is shown below.
| Field | Length (bytes) | Value |
| Sync Val | 1 | 0x3C |
| Message type | 1 | The most significant bit of this field specifies that this frame contains a timestamp. (Only for logs). The next three bits specify a protocol version (presently 2).The least significant 4 bits specify a message type: Object (OBJ): 0 Object request (OBJ_REQ): 1 Object with acknowledge request (OBJ_ACK): 2 Acknowledgement (ACK): 3 Negative-Acknowledgement (NACK) : 4 |
| Length | 1 | Length of header and data, not including the final CRC byte. |
| Reserved | 1 | Reserved byte- must be all zeroes |
| Object ID | 4 | Unique object ID (generated by UAV object parser) |
| Instance ID (optional) | 2 | Unique object instance ID. Only present in UAVObjects that are NOT of type 'single instance' |
| Timestamp (optional) | 2 | For packet types with the timestamp flag (MSB set) this field will contain a two byte timestamp in milliseconds |
| Data | 0-255 | Serialized (packed) object. |
| Checksum | 1 | CRC-8 checksum |
There are currently a total of three different type of transactions, each one is described below.
The data field is packed with values stored as little endian. This is consistent with x86, and ARM in the default little endian mode, but requires translation for big endian processors.
Bits 7 to 4 of the message type field are used to indicate the UAVTalk version used in the message. Packets with unrecognised protocol versions should be ignored.
The object message is a simple one way update of an object. Once this message is received the unpack function of the corresponding object is invoked and the object fields are updated. No response is sent on OBJ messages and they are typically used on periodic updates (see below).
Object requests are sent whenever the latest value of an object is required by the sender. The OBJ_REQ message has no payload (length field is zero) and the recipient immediately responds by packing the object data and sending an OBJ message.
In case the ObjectID requested is not found, the receiver will answer with a NACK message, instead of the OBJ message (see description of NACK below).
The OBJ_ACK message is similar to a regular OBJ message but this time an acknowledgment shall be sent back to the sender to confirm that the object was received by the remote end. The acknowledgement is in the form of an ACK message with no payload. It does have the instance ID in the case of a multiple instance object.
NACK is a message with no payload except an optional Instance ID based on the object type (none for a single instance object)
NACK is sent in response to a OBJ_REQ message, whenever the requested ObjectID does not exist on the remote side. The non-existent requested objectID is sent back with the NACK message so that the sender can take into account the absence of this ObjectID on the remote side, and act accordingly.
A NACK message shall be sent in case the receiver receives an Acknowledged Object message (OBJ_ACK) and does not recognize the ObjectID of that object.
The object ID is a unique 32-bit integer identifying the object the message data represent. The UAVTalk layer routes all received payloads to the appropriate object for unpacking. The object ID is automatically generated by the parser by applying a hash on the XML definition of the object. This has two advantages, first the ID is unique (very small probability of collision exists but it is insignificant) so there is no need for a centralized database of IDs, objects can be added without worrying about choosing a unique ID. Second each time the object definition is changed the ID will also change, this is a convenient way to make sure that UAVObjects on the GCS and autopilot have the same definition (i.e. have the same version).
The message type and object ID fields (first 5 bytes) also serve as framing bytes and used to detect the start of a packet. There are only a very small set of values out of all possible combinations of the first 5 bytes that are used for actual messages. In other words, the probability that the first five bytes randomly form a valid object header is very small and therefore they can be used for framing.
The UAVTalk layer is also responsible for periodic object updates. Each registered object has a timer associated with it, when the timer expires an OBJ message is sent. The timer values can be dynamically updated.
Telemetry between Copter Control and GCS over a serial link is established by a sequence of changes in the Status field of the FlightTelemetryStatus and GCSTelemetryStatus UAVObjects. The sequence passes through Status values DISCONNECTED = 0, HANDSHAKEREQ = 1, HANDSHAKEACK = 2, and CONNECTED = 3 as in this example from the Feb 1, 2012 release.
UAVObjects are the actual object containers and are the main interface to the plugins and core application for both the GCS and autopilot. Normally the UAVTalk layer is only used through the UAVObjects and not directly by the application. The UAVObjects maintain a number of data fields and provide the packing and unpacking functions to the UAVTalk layer. The actual code for the UAVObject is generated by the parser based on an XML definition of the object and its fields. The parser will then generate the necessary autopilot and GCS code of the UAVObject. There will be multiple UAVObjects one for each object defined in the XML. It is expected that each plugin will have its own XML and set of UAVObjects. In addition the parser will generate the functions required for generic access to the data, this will be used by parts of the GCS that does not need to know the actual object type (e.g. the GCS plotting feature).
The parser will also generate the fields required to remotely configure the period of the automatic object updates.
This is a fairly straight forward example, the fields of the navigation object will be defined in an XML and the parser will generate the necessary UAVObject for the GCS and autopilot. The autopilot will use the generated UAVObject for sharing the navigation data internally (with plugins for example) and with the GCS. At a configurable interval the object will be packed and sent to the GCS.
The airframe configuration can be easily represented by an UAVObject, the different configuration fields and their type will be defined in a XML file. The parser will generate the UAVObject code for the GCS and autopilot. On power-up the autopilot will load the airframe configuration and initialize the object fields. Every time a field needs to be updated the GCS application will simply update the corresponding field in the GCS UAVObject and through the UAVTalk layer the update will be propagated to the autopilot.
Log recording can also easily achieved by the UAVTalk layer. On configurable intervals the objects will be packed and stored with a time stamp. The same log can then be replayed in the GCS by feeding the recorded objects in the UAVTalk layer, the UAVObjects and application will not be aware that the updates are coming from a recorded log. A similar approach can be used for plotting the data from a log or exporting them to a text file.