From bb63040692c94ffa662b0af7eb14f3c5951aa6e6 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Sat, 22 Jun 2024 13:01:42 +0200 Subject: even more doxygen documentation --- main/pbdrv.h | 56 ++++++++++++++++++++++++++++++++++---------------------- 1 file changed, 34 insertions(+), 22 deletions(-) (limited to 'main') diff --git a/main/pbdrv.h b/main/pbdrv.h index a751000..9496aa9 100644 --- a/main/pbdrv.h +++ b/main/pbdrv.h @@ -3,35 +3,41 @@ #include "pb-types.h" /** - * This is the RP2040 puzzle bus driver. This file is no longer inside - * lib/pb//rp2040 as it is tightly coupled to both the pico-sdk and - * freertos functions. I have tried to get FreeRTOS to play nicely with the - * CMake subproject layout, but the pico-sdk and the rp2040 port of freertos - * both rely on CMake's import() functionality, which makes using FreeRTOS in a - * libary context extremely messy. + * \ingroup pb_drv + * \defgroup pb_drv_rp2040 RP2040 + * \brief Raspberry Pi Pico and Pico W driver * - * The workaround implemented in this driver was already kind of messy, and a - * different microcontroller should be used for the main controller instead. + * \note This file is no longer inside `lib/pbdrv/drv/rp2040` as it is tightly + * coupled to both the pico-sdk and FreeRTOS functions. I have tried to get + * FreeRTOS to play nicely with the CMake subproject layout, but the pico-sdk + * and the RP2040 port of FreeRTOS both rely on CMake's import() functionality, + * which makes using FreeRTOS in a libary context extremely messy. + * + * \warning The workaround implemented in this driver was already kind of + * messy, and **a different microcontroller should be used for the main + * controller instead**. Please see the handover document for more details. + * + * \{ */ #ifdef __cplusplus extern "C" { #endif -//! puzzle bus driver setup +//! Puzzle bus driver setup void pb_setup(); /** - * While the RP2040's datasheet claims it supports multi-master configurations - * by implementing bus arbitration, it does not natively support a mode where - * it is configured as a (multi-)master with a slave address, such that it can - * be addressed by other multi-masters. This function includes a hacky - * workaround that teporarily sets the RP2040 to I2C master mode to send a - * message, and then restores it back to slave mode. + * \note While the RP2040's datasheet claims it supports multi-master + * configurations by implementing bus arbitration, it does not natively support + * a mode where it is configured as a (multi-)master with a slave address, such + * that it can be addressed by other multi-masters. This function includes a + * hacky workaround that teporarily sets the RP2040 to I2C master mode to send + * a message, and then restores it back to slave mode. * - * This approach results in some received frames being (partially) dropped in - * the time period between the invocation of this function and the bus becoming - * idle (and the message is sent). + * \warning This approach results in some received frames being (partially) + * dropped in the time period between the invocation of this function and the + * bus becoming idle (and the message is sent). */ void pb_i2c_send(i2c_addr_t addr, const uint8_t * buf, size_t sz); @@ -39,13 +45,19 @@ void pb_i2c_send(i2c_addr_t addr, const uint8_t * buf, size_t sz); * \brief Scan the bus for I2C slaves, and send handshake messages to ACK-ing * slaves. * - * As a result of the RP2040 hardware limitations detailed at the top of this - * file, this function is also implemented in this file, even through it does - * not belong to the puzzle bus driver. In order to not miss any handshake - * responses, the bus should remain busy during the entire scan. + * \note As a result of the RP2040 hardware limitations, this function is also + * implemented in this file, even though it does not belong to the puzzle bus + * driver. + * + * \warning In order to not miss any handshake responses, the bus should remain + * busy during the entire scan. The \c nostop parameter of the \c + * i2c_write_timeout_us() function from the pico-sdk does not seem to keep the + * bus busy. */ void bus_scan(); +/// \} + #ifdef __cplusplus } #endif -- cgit v1.2.3 From 33d17dbab86c1277a1327273fb9753b2c98b7b03 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Sat, 22 Jun 2024 14:32:19 +0200 Subject: more documentation --- Doxyfile | 6 ++++-- client/readme.md | 32 ++++++++++++++------------------ lib/i2ctcp/i2ctcpv1.h | 2 ++ lib/mpack/mpack.h | 31 ++++++++++++++++++++++++++----- main/readme.md | 3 +++ makefile | 9 ++++++++- puzzle/dummy/index.dox | 9 +++++++++ puzzle/neo/index.dox | 6 ++++++ puzzle/readme.md | 17 +++++++++++------ puzzle/vault/index.dox | 6 ++++++ readme.md | 22 ++++++++++++++++++++-- 11 files changed, 109 insertions(+), 34 deletions(-) create mode 100644 puzzle/dummy/index.dox create mode 100644 puzzle/neo/index.dox create mode 100644 puzzle/vault/index.dox (limited to 'main') diff --git a/Doxyfile b/Doxyfile index 2d600e7..af362dd 100644 --- a/Doxyfile +++ b/Doxyfile @@ -4,12 +4,12 @@ PROJECT_NAME = "puzzlebox" OUTPUT_DIRECTORY = doxygen INPUT += readme.md -INPUT += client INPUT += lib/mpack INPUT += lib/i2ctcp INPUT += lib/pbdrv +INPUT += client INPUT += main -INPUT += puzzle/dummy +INPUT += puzzle EXCLUDE = lib/mpack/src EXCLUDE_PATTERNS = **/build @@ -24,6 +24,8 @@ ALIASES += I2C="I²C" INPUT_FILTER = "sed -e 's/\\|\2<\/sup>C\>/\\I2C/g'" USE_MDFILE_AS_MAINPAGE = readme.md +HTML_INDEX_NUM_ENTRIES = 1 # collapse trees by default +REPEAT_BRIEF = NO INTERNAL_DOCS = YES EXTRACT_STATIC = YES diff --git a/client/readme.md b/client/readme.md index fcde40d..b9e0b09 100644 --- a/client/readme.md +++ b/client/readme.md @@ -1,3 +1,6 @@ +\defgroup pbc pbc +\brief Puzzle box client + # puzzle box client This folder contains the source code for the puzzle box client (pbc). This is a @@ -7,30 +10,21 @@ game operator to control and monitor the state of a puzzle box, but is also a useful debugging tool when developing puzzle modules, as it allows you to send arbitrary data over the puzzle bus. -## WIP TODO - -- cleanup - - separate ../shared/pb/moddrv.c into a puzzle module specific and 'common' bit - - use the common bit in i2c.cpp instead - - cast to structs in ../shared/pb/moddrv.c -- functionality - - print pretty tree of connected puzzle modules - - add enum to string functions in CLIENT ONLY - ## Features - List detected puzzle modules - Reset puzzle modules (individually or all to reset the box) - Skip puzzle modules (individually or all) - Request puzzle box state - -Debug only: -- Send arbitrary messages +- Debug: send arbitrary messages ## Building -PBC is a standard CMake project, but a [makefile](./makefile) is provided for -convenience (still requires CMake and Ninja are installed). +PBC is a standard CMake project. + +## Using + +See ./pbc.1 for usage. ## Send data @@ -45,8 +39,10 @@ send 0x39 68:65:6c:6c:6f 44 0x20 'world' 33 The data is concatenated, and may contain mixed types of literals -## known bugs (TODO) -- tab completion for `dump` seems to print garbage sometimes -- the send command with an address but no data causes a segmentation fault +## WIP TODO + +- add enum to string functions in CLIENT ONLY +- bug: tab completion for `dump` seems to print garbage sometimes +- bug: the send command with an address but no data causes a segmentation fault diff --git a/lib/i2ctcp/i2ctcpv1.h b/lib/i2ctcp/i2ctcpv1.h index d7bb29e..e9bc0d9 100644 --- a/lib/i2ctcp/i2ctcpv1.h +++ b/lib/i2ctcp/i2ctcpv1.h @@ -91,6 +91,8 @@ void i2ctcp_read_reset(i2ctcp_msg_t * target); */ bool i2ctcp_write(const i2ctcp_msg_t * target, char ** buf, size_t * buf_sz); +/// \} + #ifdef __cplusplus } #endif diff --git a/lib/mpack/mpack.h b/lib/mpack/mpack.h index 7c0c089..33521c4 100644 --- a/lib/mpack/mpack.h +++ b/lib/mpack/mpack.h @@ -2,18 +2,39 @@ #include "src/src/mpack/mpack.h" +#ifdef __cplusplus +extern "C" { +#endif + +/** + * \defgroup mpack mpack + * \brief Mpack extensions specific to this project + * + * The mpack folder under `lib/` contains a CMakeLists.txt for integrating the + * mapck library with CMake, and includes an extension in the form of an + * additional utility function. + * + * \{ + */ + /** - * \brief read remaining bytes in reader without opening a tag first + * \brief Read remaining bytes in reader without opening a tag first * - * \param reader pointer to mpack reader object - * \param p pointer to write data to - * \param count maximum number of bytes to read + * \param reader Pointer to mpack reader object + * \param p Pointer to write data to + * \param count Maximum number of bytes to read * * This function reads *up to* the amount of bytes specified in \p count, or * less if there is less remaining data in the buffer. If \p count is equal to * 0, all remaining data in the buffer is read. * - * \return amount of bytes read + * \return Amount of bytes read */ size_t mpack_read_remaining_bytes(mpack_reader_t * reader, char * p, size_t count); +/// \} + +#ifdef __cplusplus +} +#endif + diff --git a/main/readme.md b/main/readme.md index 28fcfad..85a3fca 100644 --- a/main/readme.md +++ b/main/readme.md @@ -1,3 +1,6 @@ +\defgroup main main +\brief Main controller software + # main controller firmware This directory contains the software for the main controller of the Puzzle Box. diff --git a/makefile b/makefile index 5f5340b..090877e 100644 --- a/makefile +++ b/makefile @@ -1,5 +1,12 @@ all: doxygen -doxygen: Doxyfile +.PHONY: FORCE + +doxygen: Doxyfile FORCE doxygen +FMT += $(shell git ls-files '*.h' '*.c' '*.cpp') +format: FORCE + clang-format -i $(FMT) + clang-tidy --fix-errors $(FMT) + diff --git a/puzzle/dummy/index.dox b/puzzle/dummy/index.dox new file mode 100644 index 0000000..918bf7f --- /dev/null +++ b/puzzle/dummy/index.dox @@ -0,0 +1,9 @@ +// vim:ft=doxygen +/** +\ingroup puz +\defgroup puz_dummy Dummy +\brief Demo puzzle module + +The dummy puzzle module consists of an empty Arduino sketch, and can be used as +a starting point for developing new puzzle modules. +*/ diff --git a/puzzle/neo/index.dox b/puzzle/neo/index.dox new file mode 100644 index 0000000..14cefdc --- /dev/null +++ b/puzzle/neo/index.dox @@ -0,0 +1,6 @@ +// vim:ft=doxygen +/** +\ingroup puz +\defgroup puz_neo Neo +\brief NeoTrellis puzzle module +*/ diff --git a/puzzle/readme.md b/puzzle/readme.md index 59c10b1..959c506 100644 --- a/puzzle/readme.md +++ b/puzzle/readme.md @@ -1,15 +1,20 @@ +\defgroup puz puzzle +\brief Puzzle modules + # puzzles This folder contains the source code for all puzzle modules. ## Arduino-based puzzle modules -Because of the poorly designed hardware (21-22) used during development -(23-24), some puzzle modules ended up being developed using Arduino boards. All -libraries in this repository use CMake for building (for consistency), which -also means the Arduino based puzzle modules use CMake. The CMakeLists.txt of -some puzzles uses the [Arduino-CMake-Toolchain][arduino-cmake]. To build any of -these subfolders, make sure you have done the following: +> [!NOTE] +> Because of the poorly designed hardware (21-22) used during development +> (23-24), all puzzle modules ended up being developed using Arduino boards. + +All libraries in this repository use CMake for building (for consistency), +which also means the Arduino based puzzle modules use CMake. The CMakeLists.txt +of some puzzles uses the [Arduino-CMake-Toolchain][arduino-cmake]. To build any +of these subfolders, make sure you have done the following: - Install the official Arduino IDE - Open "Tools" > "Board" > "Board manager" diff --git a/puzzle/vault/index.dox b/puzzle/vault/index.dox new file mode 100644 index 0000000..b14e616 --- /dev/null +++ b/puzzle/vault/index.dox @@ -0,0 +1,6 @@ +// vim:ft=doxygen +/** +\ingroup puz +\defgroup puz_vault Vault +\brief Vault puzzle module +*/ diff --git a/readme.md b/readme.md index 457ffaa..a6365c0 100644 --- a/readme.md +++ b/readme.md @@ -11,6 +11,20 @@ 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). +## Documentation + +This project is documented using Doxygen. To generate HTML docs, run + +``` +$ make doxygen +``` + +and open 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. + ## Tidyness Please keep this repository tidy by being aware of the following conventions! @@ -36,8 +50,12 @@ 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. -Currently, no linter/formatter is configured for maintaining consistent code -style. +There are also `.clang-tidy` and `.clang-format` files, which can be enforced +by running + +``` +$ make format +``` ## Submodules -- cgit v1.2.3 From 3c2f4422e4dd90826a549c87d9d042c592806cb8 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Sat, 22 Jun 2024 17:26:17 +0200 Subject: docs done --- main/blink.h | 12 ++++++++++++ main/config.def.h | 54 ++++++++++++++++++++++++++++++++++++------------------ main/i2c.h | 14 +++++++++++++- main/index.dox | 6 ++++++ main/init.h | 12 +++++++++--- main/sock.h | 15 ++++++++++++--- main/tasks.h | 9 +++++++++ 7 files changed, 97 insertions(+), 25 deletions(-) create mode 100644 main/index.dox (limited to 'main') diff --git a/main/blink.h b/main/blink.h index 51c5f32..f8262d0 100644 --- a/main/blink.h +++ b/main/blink.h @@ -1,4 +1,16 @@ #pragma once +/** + * \ingroup main_tasks + * \{ + */ + +/** + * \brief Status LED blink task + * + * This task is started after initialization is complete, and blinks the + * on-board LED to indicate the Pico has completed initialization successfully. + */ void blink_task(); +/// \} diff --git a/main/config.def.h b/main/config.def.h index e9503ed..0dae608 100644 --- a/main/config.def.h +++ b/main/config.def.h @@ -2,32 +2,45 @@ #include #include +/** + * \ingroup main + * \defgroup main_config config + * \brief Configuration options + * \{ + */ + /** * \name Network (Wi-Fi) configuration * \{ */ #ifndef CFG_NET_SSID -//! network name (SSID) +/** + * \brief Network name (SSID) + * \note Not defining \c CFG_NET_SSID will implicitly enable \c CFG_NET_DISABLE + */ #define CFG_NET_SSID "" #ifndef CFG_NET_DISABLE -//! disable network communication +/** + * \brief Disable network communication completely + * \note Enabling this option will implicitly enable \c CFG_SRV_DISABLE + */ #define CFG_NET_DISABLE #warning No SSID defined! Disabling network communication! #endif #endif #ifndef CFG_NET_PASS -//! network password +//! Network password #define CFG_NET_PASS "" #endif #ifndef CFG_NET_AUTH -//! network security type +//! Network security type #define CFG_NET_AUTH CYW43_AUTH_OPEN #endif #ifndef CFG_NET_CONN_TIMEOUT -//! max duration (milliseconds) for establishing wifi connection +//! Max duration (milliseconds) for establishing Wi-Fi connection #define CFG_NET_CONN_TIMEOUT 10e3 #endif @@ -36,47 +49,52 @@ #define CFG_NET_COUNTRY CYW43_COUNTRY_WORLDWIDE #endif #ifndef CFG_NET_COUNTRY -//! radio communications country +//! Radio communications country #define CFG_NET_COUNTRY CYW43_COUNTRY_NETHERLANDS #endif -/** \} */ +/// \} /** - * \name i2ctcp server configuration + * \name TCP server configuration * \{ */ #ifndef CFG_SRV_PORT -//! i2ctcp server port +//! TCP server port #define CFG_SRV_PORT 9191 #endif - #ifdef CFG_NET_DISABLE -//! disable the i2ctcp server +//! Disable the TCP server #define CFG_SRV_DISABLE #endif -/** \} */ +/// \} /** * \name I2C configuration * \{ */ #ifndef CFG_SDA_PIN -//! I^2^C SDA pin +//! I2C SDA pin #define CFG_SDA_PIN 16 #endif #ifndef CFG_SCL_PIN -//! I^2^C SCL pin +//! I2C SCL pin #define CFG_SCL_PIN 17 #endif -/** \} */ +/// \} +/** + * \name Auxiliary options + * \{ + */ #ifndef CFG_LED_PIN -//! status LED pin +//! Status LED pin #define CFG_LED_PIN CYW43_WL_GPIO_LED_PIN #endif - #ifndef CFG_PB_MOD_MAX -//! maximum number of simultaniously connected puzzle modules +//! Maximum number of simultaniously connected puzzle modules #define CFG_PB_MOD_MAX 8 #endif +/// \} + +/// \} diff --git a/main/i2c.h b/main/i2c.h index d1173c8..107a04d 100644 --- a/main/i2c.h +++ b/main/i2c.h @@ -1,5 +1,17 @@ #pragma once -//! looking for slave addresses and requesting updates +/** + * \ingroup main_tasks + * \{ + */ + +/** + * \brief I2C bus activity task + * + * This function does an initial bus scan for puzzle modules, and then goes + * into an infinite loop that periodically polls all puzzle modules for their + * global state. + */ void bus_task(); +/// \} diff --git a/main/index.dox b/main/index.dox new file mode 100644 index 0000000..aa2d07a --- /dev/null +++ b/main/index.dox @@ -0,0 +1,6 @@ +// vim:ft=doxygen +/** +\ingroup main +\defgroup main_tasks tasks +\brief Tasks +*/ diff --git a/main/init.h b/main/init.h index 73d2773..a24977d 100644 --- a/main/init.h +++ b/main/init.h @@ -1,11 +1,17 @@ #pragma once /** - * \brief initialize the main controller + * \ingroup main + * \{ + */ + +/** + * \brief Initialize the main controller * * This function only synchronously initializes the standard input/output (used - * for `printf` and `panic`), and queues all other types of initialization in - * the `init` task using FreeRTOS. + * for \c printf() and \c panic()), and queues all other types of + * initialization in the \c async_init() task using FreeRTOS. */ void init(); +/// \} diff --git a/main/sock.h b/main/sock.h index 38fca01..a151973 100644 --- a/main/sock.h +++ b/main/sock.h @@ -1,8 +1,17 @@ #pragma once -#include -#include +/** + * \ingroup main_tasks + * \{ + */ -//! start listening for TCP socket requests +/** + * \brief Listen for TCP socket messages + * + * This task starts a TCP server that listens for messages using \ref i2ctcp, + * and sends any received I2C messages (also using \ref i2ctcp). + */ void serve_task(); +/// \} + diff --git a/main/tasks.h b/main/tasks.h index 002f830..ac77a9e 100644 --- a/main/tasks.h +++ b/main/tasks.h @@ -1,4 +1,13 @@ #pragma once +/** + * \ingroup main + * \{ + */ + +/** + * \brief Register \ref main_tasks "all tasks" in FreeRTOS + */ void init_tasks(); +/// \} -- cgit v1.2.3