diff options
| -rw-r--r-- | Doxyfile | 1 | ||||
| -rw-r--r-- | docs/doxygen-layout.xml | 62 | ||||
| -rw-r--r-- | docs/research.adoc | 111 | ||||
| -rw-r--r-- | docs/share/refs.bib | 19 | ||||
| -rw-r--r-- | readme.md | 75 |
5 files changed, 227 insertions, 41 deletions
@@ -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}, +} @@ -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 |