Message Format
==============

## Data type

The datatype consists of 4-bit (nibble) 2 parts: the most significant nibble is the syntax, while the least significant nibble is the sematics. 

| 7 . 6 | 5 . 4| 3. 2. 1. 0 |
|-|-|-|
| angular | linear | semantics |

When the Data type is 0x00, this indicates that a second byte will follow which defines further syntax options. Currently, this has not been defined yet, but can be used to define high-resolution angles using 2 bytes per dimension.


### Syntax

The syntax defines the format of the data sent and makes it possible to parse or skip parts of the message. Every value can consist of two parts: the angular and linear part, each represented by 2 bits.


| Angular part | |
|-|-|
| 00 (0x0) | No angle | 
| 01 (0x4) | 1-byte, 1D angle |
| 10 (0x8) | 2-byte, 2D angle |
| 11 (0xC) | 3-byte, 3D angle |

| Linear part | |
|-|-|
| 00 (0x0) | No magnitude |
| 01 (0x1) | 1 byte magnitude |
| 10 (0x2) | 2 byte magnitude |
| 11 (0x3) | 4 byte magnitude |

Note that these values do not actually say how the angular and linear values are encoded. A 4-byte magnitude may be a 32-bit unsigned int or a single precision float for example. This depends on the semantics.

When the angular and linear parts are combined, the size of the message can be determined. A few examples:

| Data type | Size | Description |
|-|-|-|
| 0001 (0x1) | 1 byte | A single byte of linear data, like an intensity value |
| 0100 (0x4) | 1 byte | An angle, like an angle between 0 and 360 degrees |
| 0101 (0x5) | 2 bytes | An angle with a distance, like a polar coordinate |
| 1101 (0xD) | 4 bytes | For example a quaternion, where the x,y,z = angular and w = linear part |
| 0002 (0x2) | 2 bytes | A 16-bit value, like a single short int |
| 1011 (0xB) | 6 bytes | 2D angles and a 32-bit distance, for example a spherical coordinate |

### Semantics

The semantics defines how the data should be interpreted. The following are defined:

| Semantics | |
|-|-|
| 0b0001 (0x1) | Position |
| 0b0010 (0x2) | Linear velocity |
| 0b0011 (0x3) | Linear acceleration |
| 0b0101 (0x5) | Orientation or rotation |
| ob0110 (0x6) | Angular velocity |
| 0b0111 (0x7) | Angular acceleration |
| 0b1000 (0x8) | Direction |

## Currently implemented data types

| Data type | Message |
|-|-|
| 0x62 | Polar velocity with 2-byte distance |

## Typical data types

| Data type | Interpretation |
| 0x48 | A direction in 2D space, represented by an angle. |
| 0x88 | A direction in 3D space, represented by 2 angles. |
| 0x83 | A position in 3D space, using Spherical coordinates |
| 0xD4 | An orientation represented by a quaternion |
| 0xE5 | Angular verlocity, represented in Angle-axis format |
| 0xF5 | Angular verlocity, represented in Angle-axis format using a float for the magnitude |

Note that a 2D or 3D vector is not directly supported. In alignment to the coordinate sytem of Roboid controle, these need to be converted to Polar or Spherical coordinates before they can be sent.