From 706f5ab73fedd5f2cc17a849c8ccef6b4d226a8f Mon Sep 17 00:00:00 2001 From: lonkaars Date: Wed, 14 Dec 2022 20:50:00 +0100 Subject: add design ramblings --- docs/design.md | 62 ++++++++++++++++++++++++++++++++++++++++--- docs/fig.drawio | 1 + docs/gen/doc.m4 | 1 + docs/gen/style.css | 1 + docs/img/fig-architecture.svg | 3 +++ docs/makefile | 2 +- 6 files changed, 66 insertions(+), 4 deletions(-) create mode 100644 docs/fig.drawio create mode 100644 docs/img/fig-architecture.svg (limited to 'docs') diff --git a/docs/design.md b/docs/design.md index d2a3144..1eb7c09 100644 --- a/docs/design.md +++ b/docs/design.md @@ -1,6 +1,62 @@ # QT Serial port communication (joshua) -# General system architecture (loek) -# Custom serial protocol (loek) +# General system architecture + +![System architecture](img/fig-architecture.svg) + +Above is a diagram that shows the component layout of the end product. Notable +details are: + +- The use of bluetooth mesh to establish connections between nodes in the + network. + + Bluetooth mesh was chosen because it provides an abstraction layer between + the node behaviour and low-level bluetooth protocol routines. +- The use of a J-Link debugger for connecting the border router node to a + desktop computer running the configuration utility. + + The use of the J-Link debugger was chosen because it requires no additional + USB controller setup on the node side to communicate. + + Because the network should continue functioning even without the + configuration utility connected to the border router, all network + configuration (which buttons control which lights) is stored on the border + router. The configuration utility is only a 'viewer' for the network with + features to edit the configuration and node state, but all action handling is + happening on the nodes. + +# Custom serial protocol + +The border router node communicates with the QT application using a USART +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). + +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 +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. + # Multitasking on nodes (niels) -# Used software and library versions () +# Used software and library versions + +
+|Library|Version| +|-------|-------| +|Git|2.39.0| +|GCC|12.2.0| +|Qt|6.0.0| +|Zephyr|3.1| +|nRF SDK|2.1.2| +
Software and library functions
+
+ diff --git a/docs/fig.drawio b/docs/fig.drawio new file mode 100644 index 0000000..0c6aa41 --- /dev/null +++ b/docs/fig.drawio @@ -0,0 +1 @@ +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 \ No newline at end of file diff --git a/docs/gen/doc.m4 b/docs/gen/doc.m4 index d25fdc9..3b1c0e4 100644 --- a/docs/gen/doc.m4 +++ b/docs/gen/doc.m4 @@ -2,6 +2,7 @@ define(`docname', ifelse(NAME, `pva', `Plan van aanpak', NAME, `pve', `Pakket van eisen', NAME, `research', `Research document', + NAME, `design', `Design document', `UNKNOWN???'))dnl diff --git a/docs/gen/style.css b/docs/gen/style.css index eb47f5e..7179ded 100644 --- a/docs/gen/style.css +++ b/docs/gen/style.css @@ -53,6 +53,7 @@ border-style: solid; border-width: 0.7pt 0; border-color: black; + margin: 1rem auto; } th, td { diff --git a/docs/img/fig-architecture.svg b/docs/img/fig-architecture.svg new file mode 100644 index 0000000..8b65f9f --- /dev/null +++ b/docs/img/fig-architecture.svg @@ -0,0 +1,3 @@ + + +
bluetooth mesh network
bluetooth mesh network
BT mesh
BT mesh
node
node
BT mesh
BT mesh
node
node
Configuration utility
(on desktop computer)
Configuration utility...
node
(as border router)
node...
light
light
button
button
nRF528xx
nRF528xx
USB serial
USB serial
serial port communication
serial port commun...
configuration GUI
configuration GUI
J-Link debugger
J-Link debuggerText is not SVG - cannot display \ No newline at end of file diff --git a/docs/makefile b/docs/makefile index 78a931a..55aa9ab 100644 --- a/docs/makefile +++ b/docs/makefile @@ -11,7 +11,7 @@ PDF_T = $(SRCS:.md=.pdf) .PRECIOUS: %.toc %.con -all: $(PDF_T) +all: $(HTML_T) gen/paged.polyfill.js: $(CURL) -Ls https://unpkg.com/pagedjs/dist/paged.polyfill.js > $@ -- cgit v1.2.3