-
Notifications
You must be signed in to change notification settings - Fork 0
Packet Format and Packet Types
As SpyGlass itself is just an application to display something, it obviously needs a source of data where it gets the information from what can or must be displayed. This information comes from the SpyGlass packets, which are syntactically well-defined data packets. That means, that they must be formatted according to one of the five packet types described below.
All SpyGlass packets consist of a header and a payload, where the header format is equal for all packet types. A header must always have a length of exactly 19 bytes and contain the information shown in the table below. Note, that the numbering of the bytes of a packet starts with 0.
| Byte No. | Type | Content | Comment |
|---|---|---|---|
| 0, 1 | uint16 | packet length (header + payload) | |
| 2 | uint8 | version | currently fixed to 2 |
| 3 | uint8 | syntax type | 0 = std 1 = uint8_list 2 = uint16_list 3 = int16_list 4 = uint32_list 5 = int 6 = float_list 7 = variable |
| 4 | uint8 | semantic type | |
| 5, 6 | uint16 | sender ID | |
| 7, 8, 9, 10 | uint32 | current time in seconds | |
| 11, 12 | uint16 | milliseconds of current time | |
| 13, 14 | int16 | x-coordinate of senders position | |
| 15, 16 | int16 | y-coordinate of senders position | |
| 17, 18 | int16 | z-coordinate of senders position |
A packets' payload is built according to a fixed syntax (see the syntax type field in the packet header) and correspond to one of the following packet types:
The payload of a Neighborhood-Packet contains a list of uint16 values which represents a list of node IDs. Its syntax type is uint16_list. The list must neither contain a node ID twice, nor the node ID of the sender itself.
| Byte No. | Content | Type |
|---|---|---|
| 19, 20 | Node ID | uint16 |
| 21, 22 | Node ID | uint16 |
| ... | ... | ... |
A Coordinates-List-Packet-2 contains a payload, which consists of a list of 2-dimensional coordinates. Each coordinate is represented by an int16 value. Thus a 2-dimensional position needs two values and consequently the payload must have a length of a multiple of four bytes. Its syntax type is int16_list.
| Byte No. | Content | Type |
|---|---|---|
| 19, 20 | x-coordinate of position 1 | int16 |
| 21, 22 | y-coordinate of position 1 | int16 |
| 23, 24 | x-coordinate of position 2 | int16 |
| 25, 26 | y-coordinate of position 2 | int16 |
| ... | ... | ... |
A Coordinates-List-Packet-3 is very similar to a Coordinates-List-Packet-2. The only difference is the dimensionality, because this packet contains positions with three dimensions instead of 2. As each coordinate is represented by an int16 value and a 3-dimensional position needs three values, the payload must have a length of a multiple of six bytes. The syntax type is int16_list.
| Byte No. | Content | Type |
|---|---|---|
| 19, 20 | x-coordinate of position 1 | int16 |
| 21, 22 | y-coordinate of position 1 | int16 |
| 23, 24 | z-coordinate of position 1 | int16 |
| 25, 26 | x-coordinate of position 2 | int16 |
| 27, 28 | y-coordinate of position 2 | int16 |
| 29, 30 | z-coordinate of position 2 | int16 |
| ... | ... | ... |
The payload of Trajectory-Packet-2 represents the way of an object via several 2-dimensional positions and the time it needs to come from one position to the next. So the payload contains a list of tuples, where the first two elements of each tuple represents a position. The third element represents the time in seconds, that the object spends between the position given before and the next position. Although the syntax type is int16_list and all elements are of type int16, the time element must not contain negative values. Since the last position specifies the ending point, the last tuple is incomplete. It contains only the two elements representing the position.
| Byte No. | Content | Type |
|---|---|---|
| 19, 20 | x-coordinate of position 1 | int16 |
| 21, 22 | y-coordinate of position 1 | int16 |
| 23, 24 | duration of moving between position 1 and position 2 | int16 |
| 25, 26 | x-coordinate of position 2 | int16 |
| 27, 28 | y-coordinate of position 2 | int16 |
| 29, 30 | duration of moving between position 2 and position 3 | int16 |
| ... | ... | ... |
| 19 + 6(n-1), 20 + 6(n-1) | x-coordinate of position n | int16 |
| 21 + 6(n-1), 22 + 6(n-1) | y-coordinate of position n | int16 |
The payload of a Trajectory-Packet-3 is very similar to a Trajectory-Packet-2. The only difference is, that the positions are not given in 2D but in 3D. Thus each position consists of three coordinates. Between two positions the payload contains the duration, the objects needs to pass the way from one position to the next. The syntax type is int16_list. The duration value must be given in seconds and must not contain a negative number even though it is an int16 field.
| Byte No. | Content | Type |
|---|---|---|
| 19, 20 | x-coordinate of position 1 | int16 |
| 21, 22 | y-coordinate of position 1 | int16 |
| 23, 24 | z-coordinate of position 1 | int16 |
| 25, 26 | duration of moving between position 1 and position 2 | int16 |
| 27, 28 | x-coordinate of position 2 | int16 |
| 29, 30 | y-coordinate of position 2 | int16 |
| 31, 32 | z-coordinate of position 2 | int16 |
| 33, 34 | duration of moving between position 2 and position 3 | int16 |
| ... | ... | ... |
| 19 + 8(n-1), 20 + 8(n-1) | x-coordinate of position n | int16 |
| 21 + 8(n-1), 22 + 8(n-1) | y-coordinate of position n | int16 |
| 23 + 8(n-1), 24 + 8(n-1) | z-coordinate of position n | int16 |
A Data-Packets payload contains arbitrary data. Its syntax type is flexible but must be defined in the header of the packet. The possible syntax types are uint8_list, uint16_list, int16_list, uint32_list, int64_list and float_list. The length of the payload depends on the syntax type.