diff options
Diffstat (limited to 'docs/design.md')
| -rw-r--r-- | docs/design.md | 36 |
1 files changed, 29 insertions, 7 deletions
diff --git a/docs/design.md b/docs/design.md index e63dff2..e7321b6 100644 --- a/docs/design.md +++ b/docs/design.md @@ -30,19 +30,41 @@ interface, over which our custom protocol is used to send and receive formatted data. The protocol itself is in a binary format to save on bandwidth and memory -consumption on the node side. Messages consist of a single starting byte -(0xff), and following data which is derived from packed structs (a struct of -which each field is adjacent in memory, without padding). +consumption on the node side. The message data is derived from packed structs +(a struct of which each field is adjacent in memory, without padding). Example +binary messages with comments are provided in the source folder +`shared/protocol-tests`. + +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. 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 -specific message or request. Most messages are fixed-length, but messages that +specific message request. Most messages are fixed-length, but messages that have variable-length fields have extra logic in the parser module to handle memory allocation. All message types implement their own handler function which decodes the message back into a regular struct. -Exact specifications of the protocol can be found in the source tree in -markdown format, with included client and parser libaries. +The following is an example in which the server notices that the client is +connected, and the client requests a node to be provisioned into the network: + + + +The following details should be noted in this diagram: + +- Messages are numbered sequentially and independently by each side +- Each message has a separate type +- Response messages include the type of their 'parent' message +- Response messages include a status + +Other important details: + +- 16-bit and 32-bit numbers are sent with network (big) endianness. +- Messages are buffered until complete, so this protocol should be used over + unbuffered serial connections only. # Asynchronous QT Serial port @@ -76,7 +98,7 @@ For now, there are two semaphores created in the provisioner software. The first <figure> |Library|Version| -|-------|-------| +|:------|------:| |Git|2.39.0| |GCC|12.2.0| |Qt|6.0.0| |