Merge branch 'wip/docs' into wip/rp2040-good-ending

5 files changed, 227 insertions, 41 deletions

diff --git a/Doxyfile b/Doxyfile
index af362dd..3dd7951 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -2,6 +2,7 @@
 DOXYFILE_ENCODING = UTF-8
 PROJECT_NAME = "puzzlebox"
 OUTPUT_DIRECTORY = doxygen
+LAYOUT_FILE = docs/doxygen-layout.xml
 
 INPUT += readme.md
 INPUT += lib/mpack
diff --git a/docs/doxygen-layout.xml b/docs/doxygen-layout.xml
new file mode 100644
index 0000000..9ac2aaa
--- /dev/null
+++ b/docs/doxygen-layout.xml
@@ -0,0 +1,62 @@
+<!--
+  This file is largely based off /templates/general/layout_default.xml from
+	<https://github.com/doxygen/doxygen>. The official documentation for this
+	XML file is at <https://www.doxygen.nl/manual/customize.html>.
+-->
+<doxygenlayout version="1.0">
+	<navindex>
+		<tab type="mainpage" visible="yes" title="Index"/>
+		<tab type="topics" visible="yes" title="Components"/>
+	</navindex>
+	<group>
+		<briefdescription visible="yes"/>
+		<detaileddescription visible="yes"/>
+		<groupgraph visible="yes"/>
+		<memberdecl>
+			<nestedgroups visible="yes" title="Components"/>
+			<modules visible="yes"/>
+			<dirs visible="yes"/>
+			<files visible="yes"/>
+			<namespaces visible="yes"/>
+			<concepts visible="yes"/>
+			<classes visible="yes"/>
+			<defines/>
+			<typedefs/>
+			<sequences/>
+			<dictionaries/>
+			<enums/>
+			<enumvalues/>
+			<functions/>
+			<variables/>
+			<signals/>
+			<publicslots/>
+			<protectedslots/>
+			<privateslots/>
+			<events/>
+			<properties/>
+			<friends/>
+			<membergroups visible="yes"/>
+		</memberdecl>
+		<memberdef>
+			<pagedocs/>
+			<inlineclasses/>
+			<defines/>
+			<typedefs/>
+			<sequences/>
+			<dictionaries/>
+			<enums/>
+			<enumvalues/>
+			<functions/>
+			<variables/>
+			<signals/>
+			<publicslots/>
+			<protectedslots/>
+			<privateslots/>
+			<events/>
+			<properties/>
+			<friends/>
+		</memberdef>
+		<authorsection visible="yes"/>
+	</group>
+</doxygenlayout>
+
diff --git a/docs/research.adoc b/docs/research.adoc
index acab4ab..7a9d56c 100644
--- a/docs/research.adoc
+++ b/docs/research.adoc
@@ -411,6 +411,117 @@ testing. Including mocking tests, a large amount of assertions, multiple test
 with different input support, and lastly being supported in the newest
 non-experimental version of {cpp}. 
 
+== I^2^C (Thomas)
+
+=== Research question
+
+How can we use I^2^C for the puzzle module detection and communication?
+
+=== Puzzle Module and Main Controller Communication
+
+Research from project group 21/22 shows that the I^2^C protocol is the best 
+option for communication between the puzzle modules and the main controller. 
+This research section extends the previous section about which MCU is suitable 
+for the puzzle bus, as we have found vital I^2^C limitations with the 
+controller we had chosen. See the handover document for the found limitations.
+
+// TODO: REFERENCES
+// TODO: Find synonym for 'vital'
+
+==== MCUs Supporting Master Addressable as Slave
+
+===== Atmega328p
+
+The Atmega328p has multi-master support, where the MCU is addressable as a 
+slave while being in master mode. This has been confirmed using the Arduino 
+wire library on both the Arduino Mega and the Arduino Uno.
+
+===== PIC16F15276 & ESP32
+
+Both the PIC16F15276 and the ESP32 MCUs show possibilities to be addressable as a slave while being in master mode. However, at the moment of writing this 
+has yet to be tested.
+
+// TODO: Add the following reference:
+// PIC16F15276 - 25.2.4.3
+// https://ww1.microchip.com/downloads/aemDocuments/documents/MCU08/ProductDocuments/DataSheets/PIC16F15256-74-75-76-Microcontroller-Data-Sheet-40002305.pdf
+
+// TODO: Add the following reference:
+// https://docs.espressif.com/projects/esp-idf/en/v4.3/esp32/api-reference/peripherals/i2c.html
+// https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf#i2c
+// https://www.bitsandparts.nl/documentation/482/ESP32_Specifications_EN_v1.pdf
+
+==== Alternatives
+
+===== PIC16F15276 Registers
+
+In the case of the PIC16F15276 not support master addressable as slave the 
+following approach would most likely work. As the PIC16F15276 uses specific 
+registers for its master receive functions, namely the RCEN register, it can 
+be manually set to receive data from the I^2^C bus. However, this also has 
+yet to be tested.
+
+// TODO: Add the following reference:
+// PIC16F15276 - 25.2.4.3
+// https://ww1.microchip.com/downloads/aemDocuments/documents/MCU08/ProductDocuments/DataSheets/PIC16F15256-74-75-76-Microcontroller-Data-Sheet-40002305.pdf
+
+===== Multiple I^2^C Peripherals
+
+==== ESP32 & RP2040
+
+The ESP32 and the RP2040 both have multiple peripherals for I^2^C 
+communication, while also supporting simultaneous configuration. This allows 
+both two I^2^C peripherals to be active, one being configured as a master and 
+the other being configured as a slave. This enables the controller to send and 
+receive data to the I^2^C bus without much difficulty. This does introduce 
+increased code complexity but is a valid option if it is succesful in testing.
+
+// TODO: Add the following reference:
+// https://docs.espressif.com/projects/esp-idf/en/v4.3/esp32/api-reference/peripherals/i2c.html
+// https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf#i2c
+// https://www.bitsandparts.nl/documentation/482/ESP32_Specifications_EN_v1.pdf
+
+=== Puzzle Module Detection
+
+Puzzle module detection is vital to the puzzelbox, as this allows changing the 
+puzzles without much software or hardware configuration needed. An option will 
+be given for the choice of main controller (RP2040); namely to scan the full 
+I^2^C bus for responsive slaves. The RPI Pico SDK has an API for I^2^C which 
+also supports functions create a bus scanning function. An example of this 
+bus scan function, according to the API examples, can be found in the pseudo 
+code below.
+
+[source, c]
+----
+#include <stdio.h>
+#include "pico/stdlib.h"
+#include "hardware/i2c.h"
+
+void bus_scan() {
+    int ret;
+    uint8_t rxdata;
+    
+    for (int addr = 0; addr < (1 << 7); ++addr) {
+        ret = i2c_read_blocking(i2c_default, addr, &rxdata, 1, false);
+        printf(ret < 0 ? "." : "@");
+        printf(addr % 16 == 15 ? "\n" : "  ");
+    }
+    printf("Done.\n");
+}
+----
+
+The bus scan function tries to read data from all possible I^2^C addresses, 
+and prints a table which shows what the addresses are from found I^2^C 
+slaves. This is possible due to the i2c_read_blocking function, which returns 
+the length of the read data if the slave address is in use (in this case 1) or 
+a number below 0 if the slave address is not in use. The puzzelbox, however, 
+has the 'Neotrellis' puzzle which also uses I^2^C to function. The bus scan 
+function would also see the 'Neotrellis' rgb matrix as a puzzle module (slave) 
+using this implementation. This can easily be fixed using a handshake between 
+puzzle modules and the main controller, as the 'Neotrellis' rgb matrix cannot 
+answer this handshake and is therefor not recognized as a puzzle module.
+
+// TODO: references (API) & code block naming?
+
 == Original Puzzle Box Functionality Research (Thomas)
 
 === Research question
diff --git a/docs/share/refs.bib b/docs/share/refs.bib
index 1c37465..481d4d1 100644
--- a/docs/share/refs.bib
+++ b/docs/share/refs.bib
@@ -200,3 +200,22 @@
 	publisher = {Avans University of Applied Sciences},
 	year = {2022},
 }
+
+@online{Joh21,
+	author = {Johnston, P.},
+	title = {Embedded systems testing resources},
+	url = {https://embeddedartistry.com/blog/2018/10/18/embedded-systems-testing-resources/},
+	month = jun,
+	msbib-day = {10},
+	msbib-accessed = {2024-02-25},
+	year = {2021},
+}
+
+@online{RPI23,
+	title = {Hardware APIs - Hardware I2C},
+	url = {https://www.raspberrypi.com/documentation/pico-sdk/hardware.html#hardware_i2c},
+	month = jun,
+	msbib-day = {14},
+	year = {2023},
+	msbib-accessed = {2024-05-11},
+}
diff --git a/readme.md b/readme.md
index a6365c0..da96575 100644
--- a/readme.md
+++ b/readme.md
@@ -5,63 +5,56 @@ implemented during the 2023-2024 run of the Puzzlebox project. This year's run
 of the project consists of only software students, and was developed using the
 hardware from the 21-22 run of the project.
 
-Improved hardware was designed but not realised during the 22-23 run of the
-project. This hardware is recommended for future groups participating in the
-project. The software in this repository should be easily portable to various
-other microcontrollers, and a recommendation is made in the [design
-document](docs/design.adoc).
+The software in this repository should be easily portable to various other
+microcontrollers, and a recommendation is made in the [design
+document](docs/design.adoc). Please see the [handover
+document](docs/handover.adoc) first for more details.
+
+> [!NOTE]
+> This project was mostly developed on Linux. All subfolders/modules/libraries
+> use CMake, and *should* build cross-platform when using CMake+Ninja. This has
+> not yet been verified.
 
 ## Documentation
 
-This project is documented using Doxygen. To generate HTML docs, run
+If you are viewing this page from Doxygen, please take a look at the
+[components](topics.html) tab for a comprehensive list of components within
+this project.
+
+Project documentation is available in the [docs](docs/) folder, and all code is
+documented using Doxygen. To generate HTML docs, run
 
 ```
 $ make doxygen
 ```
 
-and open <doxygen/html/index.html> in a browser.
-
-If you are viewing this page from Doxygen, please take a look at
-[topics](/topics.html) for a comprehensive list of components within this
-project.
+and open [the generated HTML files](doxygen/html/index.html) in a browser. A
+rendered copy of this documentation is also hosted unofficially at
+[pipeframe](https://media.pipeframe.xyz/puzzlebox/23-24/doxygen).
 
 ## Tidyness
 
-Please keep this repository tidy by being aware of the following conventions!
+Please keep this repository tidy by being aware of the following conventions:
 
-### Folder structure
-
-```
-/client           desktop PC application for controlling the puzzle box
-/docs             project documentation in AsciiDoc(tor) format
-/lib              custom libraries and submodules
-├───/i2ctcp       I2C over TCP protocol functions (used by main and client)
-├───/mpack        MsgPack CMake configuration and extension
-└───/pbdrv        puzzle bus driver (module driver + (de)serializing functions)
-/main             main controller (RPi pico) software
-/puzzle/<name>    puzzle sources, each puzzle has its own subdirectory
-/shared           (unused) shared code
-/test             unit tests
-```
+- An `.editorconfig` file is provided in this repository. Please install the
+  [EditorConfig](https://editorconfig.org/) plugin for your text editor of
+  choice to automatically use these.
+- There are also `.clang-tidy` and `.clang-format` files, which can be enforced
+  by running
 
-### Code style
-
-An `.editorconfig` file is provided in this repository. Please install the
-[EditorConfig](https://editorconfig.org/) plugin for your text editor of choice
-to automatically use these.
-
-There are also `.clang-tidy` and `.clang-format` files, which can be enforced
-by running
-
-```
-$ make format
-```
+  ```
+  $ make format
+  ```
 
-## Submodules
+## Libraries
 
-This repository tracks (most) dependencies via git submodules.
+Libraries are stored in the [lib](lib/) folder, and this folder is symlinked to
+from each subfolder in the project for convenience (allows CMake to include
+out-of-tree modules). The lib folder contains a mix of direct Git submodules
+and custom libraries specific to this project. (Most) external dependencies are
+tracked as git submodules, exceptions are in the [puzzle](puzzle/) folder.
 
-If something is complaining about missing files
+TL;DR: If something is complaining about missing files
 
 ```
 git submodule update --init --recursive --depth 1