custom protocol design + architecture done

1 files changed, 11 insertions, 2 deletions

diff --git a/docs/design.md b/docs/design.md
index e7321b6..5d231fc 100644
--- a/docs/design.md
+++ b/docs/design.md
@@ -37,8 +37,12 @@ binary messages with comments are provided in the source folder
 
 When messages are sent out by either side, they are prefixed with a single
 `0xff` byte to identify the start of a message. If a message contains a literal
-`0xff` byte, it will be escaped by the send function by sending the `0xff` byte
-twice.
+`0xff` byte, it will be escaped by sending the `0xff` byte twice. When the
+parser is done receiving a message, it goes into "idle mode". In this mode, all
+data is ignored (including double `0xff` bytes), until a single `0xff` byte
+followed by any other byte is received, which will cause the parser to parse
+incoming data normally again. This approach of a "idle" and "normal" mode was
+chosen to make the parser more resilient to serial noise.
 
 All data that is sent starts with an opcode to represent the message type, and
 a message id to uniquely identify each message for the purpose of replying to a
@@ -66,6 +70,11 @@ Other important details:
 - Messages are buffered until complete, so this protocol should be used over
   unbuffered serial connections only.
 
+A complete list of commands and the additional data they send is located in the
+`shared/protocol.h` source file, and is well documented using Doxygen comments.
+The protocol implementation is written in portable C, and is used by both the
+client and server side to send and receive data.
+
 # Asynchronous QT Serial port
 
 The serial data communication is done in an asynchronous manner, which allows the program to efficiently handle data that is arriving on a serial port.