diff --git a/MessageFormat.md b/MessageFormat.md new file mode 100644 index 0000000..1cc4ce7 --- /dev/null +++ b/MessageFormat.md @@ -0,0 +1,78 @@ + +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. \ No newline at end of file