Work more on the PixelHub Protocol

PixelHub Protocol.md

@@ -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 |
+|   Byte 1   |   Byte 2   |   Byte 3   |   Byte 4   |
-+--------+--------+--------+--------+
++------------+------------+------------+------------+
-| Message Type    | 
+| ushort Protocol Version | ushort Message Type     |
-+--------+--------+--------+--------+
++-------------------------+-------------------------+
-| Message Id                        |
+| uint Message Id                                   |
-+--------+--------+--------+--------+
++---------------------------------------------------+
-| Message Contents                  |
+| uint Message Length                               |
-+--------+--------+--------+--------+
++---------------------------------------------------+
-| Null   |
+| byte[] Message Contents                           |
-| Byte   |
++---------------------------------------------------+
-+--------+
+| 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'.