From c89d8caccdccc5c1ceb299addc1adc63bfb2d156 Mon Sep 17 00:00:00 2001 From: lonkaars Date: Tue, 17 Jan 2023 20:56:18 +0100 Subject: WIP design --- docs/design.md | 36 +++++++++++++++++++++++++++++------- docs/fig.drawio | 2 +- docs/img/fig-protocol.svg | 3 +++ 3 files changed, 33 insertions(+), 8 deletions(-) create mode 100644 docs/img/fig-protocol.svg 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: + +![Example exchange between the client (QT) and server (border +router)](img/fig-protocol.svg) + +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
|Library|Version| -|-------|-------| +|:------|------:| |Git|2.39.0| |GCC|12.2.0| |Qt|6.0.0| diff --git a/docs/fig.drawio b/docs/fig.drawio index 0c6aa41..19a86e6 100644 --- a/docs/fig.drawio +++ b/docs/fig.drawio @@ -1 +1 @@ -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 \ No newline at end of file +5VnRcps4FP0az7QPyYAA4zzGjpNtJztN683s9lGAjFUL5BUitvv1K4EAgzAhMWnq2Twk0pUQ0rnn3ntERtYs2t0xuFn9SQNERsAIdiPrZgSA49ritzTsc4PtuLkhZDjITWZlWOCfSBkNZU1xgJLaRE4p4XhTN/o0jpHPazbIGN3Wpy0pqb91A0OkGRY+JLr1bxzwVW6dOEZl/wPhcFW82TTUSASLycqQrGBAtwcmaz6yZoxSnrei3QwRiV2BS/7c7ZHRcmMMxbzPA5sr98f3zfzT3Hc8tv3yiL7N+YU5yZd5giRVJ/ZES0Asdi8OgRL5J0Z8S9lanYPvC3AYTeMAyfXNkTXdrjBHiw305ehWsEHYVjwiahgSHMaiTdBS7HdKoIfIA00wx1SafXEMxMTAE2IcCwfcNyZ4lHMaHUy4VgtyKt+0xITMKKFiiZuYxmIP04QzukaFcQQsI/sRI1TsEnNJSVd2IfMV84Atu15CScrRdWmW+w9gsirPKjsPkIsdx5kFGNKqu0R5SW4Z7Q5MykV3iEaIs72YUowqtuzr3W3FPTBWttUB78TZFOcV38Ny5YoSoqFY8QKGWK7GkOlfJTUahECBCB7VpYyvaEhjSOaVdVpRJvNDOeeeSi9m2P5AnO8V8DDltE4jFAfXMq4rNwvLLZaHypZExMsGC5Y0Pdft+qMeTGjKfNSB01glJ8hCxDvmKTglUp18YIhAjp/qaWhw744158Yig3cEutEj0PtE0wChAhqhMtFjxTRbYsV5q1AxdTR/61DpiouWMBosVNyeoWL2DBXFhwvj0gYT5YPe4aOWe6BYHKNcy3YaabjBmXzv6qGKNgJuuD+YtpETkuOvceuvcY0GB/P1Gs8Wi9PlMkF81GRtCczriayn/PPNCsZ7ZwVga2jOaLzEYcpgJm2AkXJMZOyBMZHSyGOiFcrWh2xYCOC1FDlS5UYbARr7eJoUe732KkQcy4E7osUavm6W3HeUV2DSgx5WCz1KzgxfNY4Em8YF8WZgeJQFwlUiwdH/LxFatH52kin012EGQDEaoCVMMyAHII/p1MkDeqYWrXoMxx3nXXTFDvN/5OOXjup9L8S3aN/sDjv7ovOMFhlMXNg9xQXoKS5eJiReKgDKe1vxeaRDAQxV3fV6RDKunkd5b1yQW0S/3RKCb3c91sD0UpEi4/NA0xz/XmgCvRZ+u3XAZLc7TzwtHc+rX4mnqdNTLxhaZj4Aro7yqxL/s/VosNRvDZz6D7zmdNwYTrxqmpPxJajfA8cNPuQn126bejWxx5fjwx+rtmxTwg50iS1TRGsNe+H0k0veBJnh02IWfTUmrvk1/PenPbtqKXmPi6mkFGIYknfRUM/ooROiwNHDoBWUwRXQaYXU0XxUeMfYCIDz22+UxuKWkV+bz6EglOm+CMGWD/pv9jmi1ev6ddNvfI24e/x0puC6PcEdot62gmudbSrpyhC//i51khN0Efn54h7H65H8kualYSi/n5wjv1vU5FD0Ft3qP9F51a3+nW/N/wM=3VdNb9swDP01Pm7wB+Jm1yZZd8iAARnQ7ajarK1VMT1Fju3++tERHUc10DVLh6Q9WXymaOrxiZK9aLZubrQo86+YgvJCP228aO6FYRCFMT06pLXI1Gcg0zJlpwFYyUdg0Ge0kilsHEeDqIwsXTDBooDEOJjQGmvX7R6V+9VSZDACVolQY/RWpiZnNIg/DS++gMxy/vQ0vLIv1qJ35pVscpFifQBFCy+aaURjR+tmBqojr+clb33h423xezkN7rKrx/q7ePhgg30+Zsp+CRoK87qhpzb0VqiK+eK1mrYnEFLik03UJscMC6EWA3qtsSpS6D7jkzX4LBFLAgMCf4ExLYtDVAYJys1a8Vtalm5/dPM/TnrzJ4fbGfPGsVq2bK5dgk9q/Rei2G+DlU7gGT8mwwidwXPxor0aaBsBroGSpHkalDBy6yYnWM/Z3m8/9RtKSjv0ee9NWHe88YKp70awafGkofA0OMhigHZyOEZ1wXml4Ahh0MWFSyE+UQpOFY8tWTjazXPYEvAgSSGxoryv7zSNsm40U7KjZoSvammSfFx7pahldzWuc2lgVYodXzWdGm4Fxaa0ffxeNp0SuDRb0AaafyjOmMz6oI/7vCnygxa+B1+d4OgYglegadFjfLnL9IL55YZDh7+Ncz6+g4s6joIz96DJW+hBvWjOVLLAu6hj46UlO/UGcVLJJuOuhkVGhXlHZwZHCWP3UnUBPS5+Mftv9kB5Sv7/IJvM4VfM3oGHH9po8Qc=5ZjRbtowFIafJtJ2UWQnBMIlsHabtknVqmmXk0tOE68mjhzTwp5+J9ghCYZRWIG14wLZv+1j55yP34AXjKfz94rl6RcZg/B8Es+94J3n+91+hO+lsDBCEFEjJIrHRmoIN/wXWJFYdcZjKFoTtZRC87wtTmSWwUS3NKaUfGxPu5OivWvOEnCEmwkTrvqdxzo1ahSSWv8APEmrnSmxI1NWTbZCkbJYPjak4NILxkpKbVrT+RhEmbsqL2bd1ZbR1cEUZPopC35ItUjVR7j61LuIZPiteODhhY3ywMTMPvBY8DKgObJeVHnA0+dlczYVn/kdCJ5hb5SD4lPQoHBEWPm61kZYFc1QK8fpsi8Eywt+uwxLUFEwmamCP8BXKEzxl6qcZTHEtrfK3LKjlbxf1aIMatf55ah9HFAa5lvzRFfZR2pB4mHVAqc81vXt2ZqljdIGVWWZRSpZLa2zjg2b+D2K4DtFuAGFz/A/FqFa0LfJPltRAqcoXjjqeSG2iIIil1kB2HyTAX5YyE/JM8/HnYi8f+vUrUwFR08ZCp5kKN1KreUUMwVZPCxNCjWZAw6NYlaky5xTM2wdMdpdAbMrxI6freUcTyZnagK7gdRMJaB3uYdbQwWCaaSpbcYbCmSXXmPydF37MDQr7I3hB7QzaL7a8cwhbYim/a1Fxbj7hDU5csJitdiiMS0vJxTbn4V2SXvXfsuksWEi1pyu8ng4ut1N6PoG3SauB1B6K+Tk/qQsVpf+Lhb9U7AYkQ5pvCg9DTT+CaAJN0HTLaEZ+96Q5DxLXggxZ3avQWeA3w/7tGveu22C6PqFtYUZ17+CQWdHqC1WuDd+vTZ+p7Cs3ib6iHvbGgxfyz17Zm/7M6n+E/F6AqlOqCMZ5eAEpPY3kUoNqcnycs3wN/ALscp/G0D6bFbphHouq1wDsOoflcBoE4Gh65VNGl+LY573bj/8Dj7W14S9gQ3XgP27yx279R9YZnr9L2Bw+Rs= \ No newline at end of file diff --git a/docs/img/fig-protocol.svg b/docs/img/fig-protocol.svg new file mode 100644 index 0000000..485656e --- /dev/null +++ b/docs/img/fig-protocol.svg @@ -0,0 +1,3 @@ + + +ClientServer[6] response (net join, ok)[2] net join[4] ping[0] response (ping, ok)[1] get node[5] response (get node, ok) \ No newline at end of file -- cgit v1.2.3