SBRL-Archive/PixelHub
Archived
1
0
Fork 0
Code Issues 1 Pull requests Activity

Work more on the PixelHub Protocol

Browse source
This commit is contained in:
Starbeamrainbowlabs 2017-02-13 20:52:30 +00:00
parent 0b95857a60
commit 84888f149b
1 changed files with 116 additions and 13 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

129
PixelHub Protocol.md
View file

@ -3,6 +3,7 @@
The _PixelHub Protocol_ is a communication protocol for WiFi-capable [Hull PixelBots](http://hullpixelbot.com/hullpixelbot/2017/02/01/welcome-to-hullpixelbot.html) to communicate with and be controlled by a remote server. While the protocol is binary, it is designed to be fairly easy to parse and implement.
## Basic Information
The PixelHub Protocol is conducted over a single TCP connection. Obtaining these details can be done automatically by listening to the UDP multicast beacon set up by the server.
@ -10,6 +11,7 @@ In this specification document, when referring to bytes, The C++ notation will b
Each PixelHub message is terminated by a null byte (`0b00000000`).
## Conversation Flow
- [ Hub -> Bot ]: Send instruction
@ -17,22 +19,123 @@ Each PixelHub message is terminated by a null byte (`0b00000000`).
- [ Bot ]: Execute command
- [ Bot -> Hub ]: Notify about instruction completion
## Message Struture
### Basic Message
### Basic Message Structure
This is the basic structure of a PixelHub Protocol message. The labels are explained below:
```
+--------+--------+--------+--------+
| Byte 1 | Byte 2 | Byte 3 | Byte 4 |
+--------+--------+--------+--------+
| Message Type |
+--------+--------+--------+--------+
| Message Id |
+--------+--------+--------+--------+
| Message Contents |
+--------+--------+--------+--------+
| Null |
| Byte |
+--------+
+------------+------------+------------+------------+
| Byte 1 | Byte 2 | Byte 3 | Byte 4 |
+------------+------------+------------+------------+
| ushort Protocol Version | ushort Message Type |
+-------------------------+-------------------------+
| uint Message Id |
+---------------------------------------------------+
| uint Message Length |
+---------------------------------------------------+
| byte[] Message Contents |
+---------------------------------------------------+
| byte null |
+------------+
```
- `ushort` Protocol Version - The pixelhub protocol version, as an unsigned short, that is being spoken. Either the server _or_ the client reserve the right to kill any connections (and optionally send an incorrect protocol version packet) to any parties not speaking their protocol version.
- `ushort` Message Type - The type of message, as an unsigned short, of message that is being sent. The values for this may be mapped into an enum.
- `uint` Message Id - The message id, as an unsigned integer. Should be randomly generated. Message replies must contain instead the id to of the message they are replying to.
- `uint` Message Length - The length of the following message contents, in 8 bit bytes.
- `byte[]` Message Contents - The content of the message that has been sent. Once the message itself has been parsed, the body can be extracted and passedto the appropriate handler for parsing.
- `byte` null - A single null byte (`0b00000000`). This signifiest he end o the message. Even though it's technically not needed because of the _Message Length_ included above, it's been added anyway to simplify initial parsing and message end detection.
### Error: When bots complain
This message doesn't have a body, but is a direct response to a message that the sending party recieved that it didn't like.
### HandshakeRequest: Beginning a handshake
In the PixelHub protocol, handshakes are initiated by the client, and completed by the server. The server may close a connection if it hasn't received a handshake within a given length of time (the server can decide on this, but it shouldn't be less than 5 seconds).
```
+------------+------------+------------+------------+
| Byte 1 | Byte 2 | Byte 3 | Byte 4 |
+------------+------------+------------+------------+
| char* PixelBot Type |
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
```
- `char*` PixelBot Type - The type of pixelbot sending the handshake request. This should be an array of characters, terminated by a null character. It shouldn't be more than 32 characters in length.
### HandshakeResponse: Completing a handshake
The counterpart to the above is the `HandshakeResponse` message. It's a direct response to a `HandshakeRequest` message, and is documented below:
```
+------------+------------+------------+------------+
| Byte 1 | Byte 2 | Byte 3 | Byte 4 |
+------------+------------+------------+------------+
| uint Id |
+---------------------------------------------------+
```
- `uint` Id - The id that the PixelHub server is assigning to the PixelBot.
### Move: Asking a PixelBot to move
From here on only the _Message Content_ will be displayed in the diagrams. It must be wrapped in the [Basic Message](#Basic Message) structure described above.
Asking a PixelBot to move is done quite simply. A pixelbot can either move forward or backwards, or turn left or right on the spot. This is evident in the movement command syntax, shown below:
Message Type: `20`
```
+------------+------------+------------+------------+
| Byte 1 | Byte 2 | Byte 3 | Byte 4 |
+------------+------------+------------+------------+
| byte | |
| Movement | ushort Tick Count |
| Type | |
+------------+-------------------------+
```
- `byte` Movement Type - The type of movement that should be made. See the [Movement Types](#Movement Types) table below.
- `ushort` Tick Count - The number of ticks that the movement should be made for.
#### Movement Types
Type | Name | Description
-------:|-----------|-------------
0 | Stop | No movement at all.
1 | Forwards | Moving forwards.
2 | Backwards | Moving backwards.
3 | Left | Turning left.
4 | Right | Turning right.
### CommandOk: When the PixelBot is ok with a command
This message doesn't have a body, but it is sent by a PixelBot to say that it is going to perform the command that was sent previously.
This message is a direct response to a `Move` command.
### CommandComplete: When a PixelBot completes a command
This message doesn't have a body, but is sent by a PixelBot when it finished executing a `Move` command. It should be in direct response the commandd sent by the server.
## Message Types
Message types, as briefly described in the [Basic Message Structure](#Basic Message Structure), are represented as an unsigned short number. All the possible message types are documented below:
Type | Name | Description
-------:|-------------------|-------------
0 | Reset | Hard-resets the PixelBot. Useful if something has gone wrong, or to reset it's internal state.
1 | Error | May be sent by either party. Indicates that one or the other doesn't like a message that was sent by the other party.
1 | HandshakeRequest | Sent by a PixelBot upon connection.
2 | HandshakeResponse | Sent by the server in response to a `HandshakeRequest`.
11 | Move | Instructs a PixelBot to perform a movement.
12 | CommandOk | Sent by a pixelbot to indicate that the command sent by the server is ok, and that it will proceed to execute it.
13 | CommandComplete | Sent by a pixelbot to indicate that it has completed executing the command sent previously.
14 | CommandFailed | Sent by a pixelbot to indicate that it has failed to complete the execution of a command it received previously.
20 | InfoRequest | Sent by the server to request information from a PixelBot. This could be from sensors, configuration, statistics, etc.
21 | InfoResponse | Sent by a PixelBot in response to an `InfoRequest` message.
Note that a status message isn't actually contained in this protocol. This is becaue it is rather awkward to respond to network messages in the middle of a movement, so it will always be something along the lines of 'idle'.