diff options
| -rw-r--r-- | Doxyfile | 1 | ||||
| -rw-r--r-- | docs/doxygen-layout.xml | 62 | ||||
| -rw-r--r-- | lib/pbdrv/pb-route.h | 4 | ||||
| -rw-r--r-- | main/i2c.c | 11 | ||||
| -rw-r--r-- | main/i2c.h | 1 | ||||
| -rw-r--r-- | main/index.dox | 7 | ||||
| -rw-r--r-- | readme.md | 75 |
7 files changed, 119 insertions, 42 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/lib/pbdrv/pb-route.h b/lib/pbdrv/pb-route.h index b80e4ec..2a28c0b 100644 --- a/lib/pbdrv/pb-route.h +++ b/lib/pbdrv/pb-route.h @@ -98,6 +98,7 @@ void pb_route_cmd_state_req(pb_msg_t * msg); * controller handles this type of command. */ void pb_route_cmd_state_res(pb_msg_t * msg); +// TODO: add link to pb_route_cmd_state_res handler in main/i2c.c /** * \brief Handle a \ref PB_CMD_STATE "STATE" message with action \ref * PB_ACTION_SET "SET" @@ -122,7 +123,8 @@ void pb_route_cmd_magic_req(pb_msg_t * msg); * PB_ACTION_RES "RES" * * The default implementation of this function is empty, as only the main - * controller handles this type of command. + * controller handles this type of command. (\ref main_route_cmd_magic_res + * "link") */ void pb_route_cmd_magic_res(pb_msg_t * msg); @@ -41,6 +41,17 @@ void bus_task() { } } +/** + * \ingroup main_pb_override + * \anchor main_route_cmd_magic_res + * + * This function registers the I2C address of the puzzle module that replied to + * the \c MAGIC \c REQ command into a list of "known puzzle modules", which are + * then periodically updated during gameplay. + * + * \note Up to \ref CFG_PB_MOD_MAX puzzle modules can be registered + * simultaniously. + */ void pb_route_cmd_magic_res(pb_msg_t * msg) { if (modules_size == CFG_PB_MOD_MAX) return; modules[modules_size++] = msg->sender; @@ -15,3 +15,4 @@ void bus_task(); /// \} + diff --git a/main/index.dox b/main/index.dox index aa2d07a..0fee58a 100644 --- a/main/index.dox +++ b/main/index.dox @@ -4,3 +4,10 @@ \defgroup main_tasks tasks \brief Tasks */ + +/** +\ingroup main +\defgroup main_pb_override overrides +\brief Override functions from \ref pbdrv-mod +*/ + @@ -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 |