From 92a184fbf8c2b5671032cfcad8ae2f1c9ee39ca7 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Thu, 20 Jun 2024 12:27:48 +0200 Subject: WIP more documentation --- Doxyfile | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 Doxyfile (limited to 'Doxyfile') diff --git a/Doxyfile b/Doxyfile new file mode 100644 index 0000000..c3623cc --- /dev/null +++ b/Doxyfile @@ -0,0 +1,21 @@ +# Doxyfile 1.11.0 +DOXYFILE_ENCODING = UTF-8 +PROJECT_NAME = "puzzlebox" +OUTPUT_DIRECTORY = doxygen + +INPUT += client +INPUT += lib/mpack +INPUT += lib/i2ctcp +INPUT += lib/pbdrv +INPUT += main +INPUT += puzzle/dummy + +EXCLUDE = lib/mpack/src +EXCLUDE_PATTERNS = **/build +EXCLUDE_SYMLINKS = YES + +FILE_PATTERNS = *.c *.cpp *.h *.hpp *.md +RECURSIVE = YES + +GENERATE_LATEX = NO + -- cgit v1.2.3 From 8a80226e9dce394573e95d68fc9fe04592ad5907 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Fri, 21 Jun 2024 19:29:44 +0200 Subject: more doxygen documentationg --- Doxyfile | 8 +++- lib/pbdrv/index.dox | 39 +++++++++++++++ lib/pbdrv/pb-buf.h | 16 +++++++ lib/pbdrv/pb-mem.h | 55 +++++++++++++++++++++ lib/pbdrv/pb-mod.h | 83 ++++++++++++++++++++++++-------- lib/pbdrv/pb-msg.h | 40 ++++++++++++++++ lib/pbdrv/pb-route.h | 27 +++++++---- lib/pbdrv/pb.h | 9 ++++ lib/pbdrv/spec.adoc | 133 --------------------------------------------------- 9 files changed, 248 insertions(+), 162 deletions(-) create mode 100644 lib/pbdrv/index.dox delete mode 100644 lib/pbdrv/spec.adoc (limited to 'Doxyfile') diff --git a/Doxyfile b/Doxyfile index c3623cc..53e75c2 100644 --- a/Doxyfile +++ b/Doxyfile @@ -3,6 +3,7 @@ DOXYFILE_ENCODING = UTF-8 PROJECT_NAME = "puzzlebox" OUTPUT_DIRECTORY = doxygen +INPUT += readme.md INPUT += client INPUT += lib/mpack INPUT += lib/i2ctcp @@ -14,8 +15,13 @@ EXCLUDE = lib/mpack/src EXCLUDE_PATTERNS = **/build EXCLUDE_SYMLINKS = YES -FILE_PATTERNS = *.c *.cpp *.h *.hpp *.md +FILE_PATTERNS = *.c *.cpp *.h *.hpp *.md *.dox RECURSIVE = YES GENERATE_LATEX = NO +ALIASES += I2C="I²C" +INPUT_FILTER = "sed -e 's/\\|\2<\/sup>C\>/\\I2C/g'" + +USE_MDFILE_AS_MAINPAGE = readme.md + diff --git a/lib/pbdrv/index.dox b/lib/pbdrv/index.dox new file mode 100644 index 0000000..ad05078 --- /dev/null +++ b/lib/pbdrv/index.dox @@ -0,0 +1,39 @@ +// vim:ft=doxygen +/** + +\defgroup pbdrv pbdrv +\brief Standalone puzzle bus driver + +pbdrv is a standalone portable static library for handling (i.e. +(de)serialization) of puzzle bus messages. + +\defgroup pbdrv-mod pbdrv-mod +\brief Puzzle module driver (superset of \ref pbdrv) + +pbdrv-mod is a superset of pbdrv, and includes functions specific to puzzle bus +modules. pbdrv-mod compiles to an object file instead of a static library +because it may depend on functions that rely on external libraries. pbdrv-mod +is still considered standalone, but requires either using an existing driver, +or (partially) implementing the driver functions. + +\note Most \c pb_* functions have a weak implementation, which may be +overwritten by a custom implementation. This allows you to use the default +implementation where possible, and only implement extensions required for your +puzzle module. + +TODO: where to find drivers +TODO: what are extensions +TODO: what to do if there is no driver / extension + +\{ + +\defgroup hook +\brief Functions for (partially) overriding default behavior + +Hooks are functions with a default (weak) implementation in pbdrv. These +functions can be overwritten by the user to implement custom behavior, without +needing to understand the internals of pbdrv. + +\} + +*/ diff --git a/lib/pbdrv/pb-buf.h b/lib/pbdrv/pb-buf.h index 78ee380..049f516 100644 --- a/lib/pbdrv/pb-buf.h +++ b/lib/pbdrv/pb-buf.h @@ -6,14 +6,30 @@ extern "C" { #endif +/** + * \ingroup pbdrv + * \ingroup pbdrv-mod + * \defgroup pb_buf Buffer + * \brief Binary data buffer type used in pbdrv + * \{ + */ + //! binary buffer struct typedef struct { char * data; //! pointer to data size_t size; //! size of data } pb_buf_t; +/** + * \brief free a \c pb_buf_t + * + * This function calls \c pb_free() on the \c data member of a \c pb_buf_t + * struct if it is not equal to \c NULL. + */ void pb_buf_free(pb_buf_t * buf); +/// \} + #ifdef __cplusplus } #endif diff --git a/lib/pbdrv/pb-mem.h b/lib/pbdrv/pb-mem.h index 72be214..4d0f995 100644 --- a/lib/pbdrv/pb-mem.h +++ b/lib/pbdrv/pb-mem.h @@ -6,13 +6,68 @@ extern "C" { #endif +/** + * \ingroup pbdrv + * \ingroup pbdrv-mod + * \defgroup pb_mem Memory + * \brief Platform-specific memory management functions + * + * \note This header only declares the memory management functions, and it is + * up to \ref pb_ext "extensions" to implement the underlying memory management + * functions. + * + * TODO: ref to extensions + * + * \{ + */ + +/** + * \brief Allocate a contiguous chunk of memory + * \param sz Requested size of memory area + * \return Pointer to memory area, or \c NULL on failure + * \note The allocated memory must be free'd again using \c pb_free() + */ void * pb_malloc(size_t sz); +/** + * \brief Free a chunk of memory previously allocated with \c pb_malloc() + * \param ptr Pointer to memory area + */ void pb_free(void * ptr); +/** + * \brief Resize the memory area \c ptr to size \c sz + * \param ptr Pointer to allocated memory area + * \param sz Requested new size of memory area + * \return Pointer to memory area, or \c NULL on failure + * \warning This function is not available on FreeRTOS, and should be avoided + * if possible. MPack's \c mpack_writer_init_growable() is known to use \c + * realloc(), and should not be used for this reason. + */ void * pb_realloc(void * ptr, size_t sz); +/** + * \brief copy a memory region + * \param dest Pointer to destination memory + * \param src Pointer to source memory + * \param sz Number of bytes to copy + * \return Pointer to \c dest + * + * This function has a portable implementation, and is always available. + */ void * pb_memcpy(void * dest, const void * src, size_t sz); +/** + * \brief compare two memory regions + * \param a Pointer to first memory region + * \param b Pointer to second memory region + * \param sz Number of bytes to compare + * \return 0 if the memory regions are identical, or the difference between the + * first non-matching byte + * + * This function has a portable implementation, and is always available. + */ int pb_memcmp(const void * a, const void * b, size_t sz); +/// \} + #ifdef __cplusplus } #endif diff --git a/lib/pbdrv/pb-mod.h b/lib/pbdrv/pb-mod.h index c4629a6..2ff1908 100644 --- a/lib/pbdrv/pb-mod.h +++ b/lib/pbdrv/pb-mod.h @@ -1,31 +1,63 @@ #pragma once -/** - * \file puzzle bus driver implementation - * - * Most \c pb_* functions have a weak implementation, which may be overwritten - * by a custom implementation. This allows you to use the default - * implementation where possible, and only implement extensions required for - * your puzzle module. Please see spec.adoc for more information about how to - * use the puzzle bus driver library. - */ - #include "pb-types.h" #ifdef __cplusplus extern "C" { #endif -//! puzzle module name (optional, default = "???") +/** + * \ingroup pbdrv-mod + * \defgroup pb_mod Module + * \brief Metadata and auxiliary utility functions + * \{ + */ + +/** + * \brief Puzzle module name + * + * Optional to define, default value is "???" + */ extern const char * PB_MOD_NAME; -//! puzzle module bus address (required) +/** + * \brief Puzzle module bus address + * + * **Required** to define + */ extern const i2c_addr_t PB_MOD_ADDR; +/** + * \brief Platform-specific blocking delay function + * + * FIXME: this should be removed (see handover: RP2040 I2C limitations) + */ +void pb_mod_blocking_delay_ms(unsigned long ms); + +/// \} + +/** + * \ingroup pbdrv-mod + * \defgroup pb_i2c I2C + * \brief I2C send/receive handlers + * + * If there is no existing \ref pb_drv "driver" for the microcontroller on + * which you want to use the puzzle bus driver, you may implement the following + * in order to use pbdrv: + * + * - The \c pb_i2c_recv() function must be **called** for every received I2C + * message + * - The \c pb_i2c_send() function must be **implemented** using the + * platform/device-specific I2C write function + * + * \{ + */ + /** * \brief handle a received message from the I2C bus (puzzle bus) * * This function attempts to parse an I2C message as a puzzle bus message, and * calls the appropriate handler for the message if it is considered valid. + * Invalid messages are silently ignored. * * \param buf pointer to message content * \param sz size of \p buf @@ -46,25 +78,36 @@ void pb_i2c_recv(const uint8_t * buf, size_t sz); */ void pb_i2c_send(i2c_addr_t i2c_addr, const uint8_t * buf, size_t sz); +/// \} + +/// \ingroup hook +/// \{ + +/** + * \defgroup pb_hook_mod_state State + * \brief Provide your own global state variable + * + * If your puzzle module defines its own global \c pb_global_state_t, you can + * tell the driver to use it by implementing these functions. These functions + * are also used internally by the driver when creating \c STATE \c REQ and \c + * STATE \c RES commands. + * + * \{ + */ + /** * \brief global state read hook - * \ingroup hook * \return current value of global state enum */ pb_global_state_t pb_hook_mod_state_read(); /** * \brief global state write hook - * \ingroup hook * \param state new value of global state enum */ void pb_hook_mod_state_write(pb_global_state_t state); -/** - * \brief platform-specific blocking delay function - * - * FIXME: this should be removed (see handover: RP2040 I2C limitations) - */ -void pb_mod_blocking_delay_ms(unsigned long ms); +/// \} +/// \} #ifdef __cplusplus } diff --git a/lib/pbdrv/pb-msg.h b/lib/pbdrv/pb-msg.h index f27d4c4..33b697a 100644 --- a/lib/pbdrv/pb-msg.h +++ b/lib/pbdrv/pb-msg.h @@ -7,10 +7,50 @@ extern "C" { #endif +/** + * \ingroup pbdrv + * \ingroup pbdrv-mod + * \defgroup pb_msg Message + * \brief Message (de)serialization + * \{ + */ + +/** + * \brief Serialize a message into a binary buffer + * + * \note This function allocates a \c pb_buf_t that should be free'd using \c + * pb_buf_free() + * + * \param msg Message to serialize + * + * \warning The type of \c msg->cmd is inferred from \c msg->type. If the + * message is not correctly formatted, this function may cause undefined + * behavior. If possible, use functions from \ref pb_send instead. + * + * \return \c pb_buf_t containing the serialized message, or an empty struct if + * serialization failed + */ pb_buf_t pb_msg_write(const pb_msg_t * msg); +/** + * \brief Read a binary buffer and attempt to deserialize it as a puzzle bus + * message + * + * \note This function allocates a \c pb_msg_t pointer that should be free'd + * using \c pb_msg_free() + * + * \param buf Binary data to interpret as puzzle bus message + * + * \return \c pb_msg_t pointer containing the deserialized message, or NULL if + * serialization failed + */ pb_msg_t * pb_msg_read(const pb_buf_t * buf); +/** + * \brief Recursively free fields of a \c pb_msg_t + */ void pb_msg_free(pb_msg_t * msg); +/// \} + #ifdef __cplusplus } #endif diff --git a/lib/pbdrv/pb-route.h b/lib/pbdrv/pb-route.h index 967c4a9..233a087 100644 --- a/lib/pbdrv/pb-route.h +++ b/lib/pbdrv/pb-route.h @@ -8,16 +8,10 @@ extern "C" { void pb_route_msg(pb_msg_t * msg); -bool pb_hook_route_msg(pb_msg_t * msg); - void pb_route_cmd_prop(pb_msg_t * msg); void pb_route_cmd_state(pb_msg_t * msg); void pb_route_cmd_magic(pb_msg_t * msg); -bool pb_hook_route_cmd_prop(pb_msg_t * msg); -bool pb_hook_route_cmd_state(pb_msg_t * msg); -bool pb_hook_route_cmd_magic(pb_msg_t * msg); - void pb_route_cmd_prop_req(pb_msg_t * msg); void pb_route_cmd_prop_res(pb_msg_t * msg); void pb_route_cmd_prop_set(pb_msg_t * msg); @@ -26,11 +20,28 @@ void pb_route_cmd_state_req(pb_msg_t * msg); void pb_route_cmd_state_res(pb_msg_t * msg); void pb_route_cmd_state_set(pb_msg_t * msg); +void pb_route_cmd_magic_req(pb_msg_t * msg); +void pb_route_cmd_magic_res(pb_msg_t * msg); + +/// \ingroup hook +/// \{ + +/// \defgroup hook_route Routing +/// \brief Use a custom message handler +/// \{ + +bool pb_hook_route_msg(pb_msg_t * msg); + +bool pb_hook_route_cmd_prop(pb_msg_t * msg); +bool pb_hook_route_cmd_state(pb_msg_t * msg); +bool pb_hook_route_cmd_magic(pb_msg_t * msg); + +/// \} + void pb_hook_main_state_update(pb_global_state_t state); void pb_hook_module_init(); -void pb_route_cmd_magic_req(pb_msg_t * msg); -void pb_route_cmd_magic_res(pb_msg_t * msg); +/// \} #ifdef __cplusplus } diff --git a/lib/pbdrv/pb.h b/lib/pbdrv/pb.h index e8037ae..cef04d8 100644 --- a/lib/pbdrv/pb.h +++ b/lib/pbdrv/pb.h @@ -1,5 +1,13 @@ #pragma once +/** + * \ingroup pbdrv + * \ingroup pbdrv-mod + * \defgroup pb Bus + * \brief Constants for the puzzle bus hardware + * \{ + */ + //! I2C bus speed in hertz (100 KHz) #define PB_CLOCK_SPEED_HZ 100000 //! I2C bus timeout delay in milliseconds @@ -32,3 +40,4 @@ //! Dummy puzzle module I2C address #define PB_ADDR_MOD_DUMMY 0x69 +/// \} diff --git a/lib/pbdrv/spec.adoc b/lib/pbdrv/spec.adoc deleted file mode 100644 index 3172e84..0000000 --- a/lib/pbdrv/spec.adoc +++ /dev/null @@ -1,133 +0,0 @@ -= Puzzle module specification - -This folder contains an implementation of the puzzle bus protocol -specification, and is targeted at puzzle module developers. This document -describes the required implementation steps for integrating a new game into the -puzzle module framework. - -== The bus - -The puzzle bus carries data over a standard I^2^C bus. Additional details about -this bus can be found in the link:../../docs/design.adoc[Design document]. - -The following details are important to puzzle module developers, as they may -cause unexpected behavior: - -- *Addresses influence the puzzle box's behavior*. The order of puzzles is - determined by the puzzle module address. Two puzzle modules may use the same - address, but this will mean that they cannot be used simultaniously in the - same puzzle box. Known addresses are documented in link:bus.h[]. -- *The read/write bit of an I^2^C frame determines how it's handled*. I^2^C - *read* frames are treated as requests, while *write* frames are treated as - responses. - -== Puzzle bus driver (pbdrv) - -The library in this folder is a partial implementation of the puzzle bus -specification *for puzzle modules*. Most functions in the driver are marked -with the 'weak' attribute, which allows you to override them by providing an -implementation. - -In order to utilize this driver, the following must be done: - -- The ``pbdrv_i2c_recv`` function must be *called* for every received *I^2^C - read* frame -- The ``pbdrv_i2c_send`` function must be *implemented* with the - platform-specific *I^2^C write* function - -This is enough to get the puzzle module registered. You may also want to -implement some of the following integrations: - -- If your game uses the global state variable, you should implement the - <> to point the driver to your own - global state variable, and be notified of reads/writes to it. -- If you want to expose additional game state variables over the puzzle bus, - you should implement the <>. -- If you want to implement custom puzzle bus commands, you can implement the - <>. - -All other kinds of integrations/hooks can likely be realized by overriding the -default implementations, but this is discouraged. - -[[sec:state-global]] -== Global state - -If your puzzle module defines its own global ``enum pb_state``, you can tell -the driver to use it by implementing the ``pbdrv_hook_state_read`` and -``pbdrv_hook_state_write`` functions. These functions are also used by the -default implementation of the read/write commands to address 0 (global state). - -Example: - -```c -pb_state_t global_state = PB_GS_NOINIT; - -pb_state_t pbdrv_hook_mod_state_read() { - return global_state; -} - -void pbdrv_hook_mod_state_write(pb_state_t state) { - global_state = state; -} -``` - -[[sec:state-aux]] -== Auxiliary state - -You can expose additional state variables by implementing the -``pbdrv_hook_read`` and ``pbdrv_hook_write`` functions. These functions should -return ``true`` for state addresses you want to override. - -Example: - -```c -#define CUSTOM_VAR_ADDR 0x01 -uint8_t my_custom_variable = 10; - -bool pbdrv_hook_read(uint16_t i2c_addr, uint8_t addr) { - switch (addr) { - case CUSTOM_VAR_ADDR: { - char res[] = { PB_CMD_READ, addr, my_custom_variable }; - pbdrv_i2c_send(i2c_addr, res, sizeof(res)); - break; - } - default: return false; - } - - return true; -} - -bool pbdrv_hook_write(uint16_t i2c_addr, uint8_t addr, const char * buf, size_t sz) { - switch (addr) { - case CUSTOM_VAR_ADDR: { - if (sz != 1) return false; - my_custom_variable = buf[0]; - break; - } - default: return false; - } - - return true; -} -``` - -[[sec:cmd]] -== Custom commands - -Similar to the auxiliary state, custom commands can be added by implementing -the ``pbdrv_hook_cmd`` function, which should return ``true`` for the -command(s) that you want to overwrite. - -Example: - -```c -bool pbdrv_hook_cmd(uint16_t i2c_addr, enum pb_cmd cmd, const char * buf, size_t sz) { - if (cmd == 0x54) { - printf("custom command received!\n"); - return true; - } - - return false; -} -``` - -- cgit v1.2.3 From 2187c3d6196f2a25bc0b74365358c9874dde3a46 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Sat, 22 Jun 2024 10:39:01 +0200 Subject: more code documentation --- Doxyfile | 2 + lib/pbdrv/index.dox | 29 +++++----- lib/pbdrv/pb-buf.h | 2 +- lib/pbdrv/pb-mod.h | 11 +++- lib/pbdrv/pb-route.c | 8 +-- lib/pbdrv/pb-route.h | 161 ++++++++++++++++++++++++++++++++++++++++++++++++--- lib/pbdrv/pb-types.h | 58 ++++++++++++++----- 7 files changed, 228 insertions(+), 43 deletions(-) (limited to 'Doxyfile') diff --git a/Doxyfile b/Doxyfile index 53e75c2..ea9692a 100644 --- a/Doxyfile +++ b/Doxyfile @@ -25,3 +25,5 @@ INPUT_FILTER = "sed -e 's/\\|\2<\/sup>C\>/\\I2C/g'" USE_MDFILE_AS_MAINPAGE = readme.md +INTERNAL_DOCS = YES + diff --git a/lib/pbdrv/index.dox b/lib/pbdrv/index.dox index ad05078..e4a6c5f 100644 --- a/lib/pbdrv/index.dox +++ b/lib/pbdrv/index.dox @@ -7,15 +7,6 @@ pbdrv is a standalone portable static library for handling (i.e. (de)serialization) of puzzle bus messages. -\defgroup pbdrv-mod pbdrv-mod -\brief Puzzle module driver (superset of \ref pbdrv) - -pbdrv-mod is a superset of pbdrv, and includes functions specific to puzzle bus -modules. pbdrv-mod compiles to an object file instead of a static library -because it may depend on functions that rely on external libraries. pbdrv-mod -is still considered standalone, but requires either using an existing driver, -or (partially) implementing the driver functions. - \note Most \c pb_* functions have a weak implementation, which may be overwritten by a custom implementation. This allows you to use the default implementation where possible, and only implement extensions required for your @@ -25,14 +16,26 @@ TODO: where to find drivers TODO: what are extensions TODO: what to do if there is no driver / extension +\defgroup pbdrv-mod pbdrv-mod +\brief Puzzle module driver (superset of \ref pbdrv) + +pbdrv-mod is a superset of \ref pbdrv, and includes functions specific to +puzzle bus modules. pbdrv-mod compiles to an object file instead of a static +library because it may depend on functions that rely on external libraries. +pbdrv-mod is still considered standalone, but requires either using an existing +driver, or (partially) implementing the driver functions. + +\copydetails pbdrv + \{ -\defgroup hook +\defgroup pb_hook Hook \brief Functions for (partially) overriding default behavior -Hooks are functions with a default (weak) implementation in pbdrv. These -functions can be overwritten by the user to implement custom behavior, without -needing to understand the internals of pbdrv. +Hooks are functions that allow the user to implement custom behavior (i.e. +extend or conditionally replace the default handlers), without needing to +completely overwrite the built-in handlers or understand the internals of \ref +pbdrv. \} diff --git a/lib/pbdrv/pb-buf.h b/lib/pbdrv/pb-buf.h index 049f516..9ff53fe 100644 --- a/lib/pbdrv/pb-buf.h +++ b/lib/pbdrv/pb-buf.h @@ -10,7 +10,7 @@ extern "C" { * \ingroup pbdrv * \ingroup pbdrv-mod * \defgroup pb_buf Buffer - * \brief Binary data buffer type used in pbdrv + * \brief Binary data buffer type used in \ref pbdrv * \{ */ diff --git a/lib/pbdrv/pb-mod.h b/lib/pbdrv/pb-mod.h index 2ff1908..ef2cd77 100644 --- a/lib/pbdrv/pb-mod.h +++ b/lib/pbdrv/pb-mod.h @@ -80,7 +80,7 @@ void pb_i2c_send(i2c_addr_t i2c_addr, const uint8_t * buf, size_t sz); /// \} -/// \ingroup hook +/// \ingroup pb_hook /// \{ /** @@ -89,8 +89,7 @@ void pb_i2c_send(i2c_addr_t i2c_addr, const uint8_t * buf, size_t sz); * * If your puzzle module defines its own global \c pb_global_state_t, you can * tell the driver to use it by implementing these functions. These functions - * are also used internally by the driver when creating \c STATE \c REQ and \c - * STATE \c RES commands. + * are also used internally by the driver. * * \{ */ @@ -98,11 +97,17 @@ void pb_i2c_send(i2c_addr_t i2c_addr, const uint8_t * buf, size_t sz); /** * \brief global state read hook * \return current value of global state enum + * + * The default implementation of this function uses an internal global state + * variable in \ref pbdrv. */ pb_global_state_t pb_hook_mod_state_read(); /** * \brief global state write hook * \param state new value of global state enum + * + * The default implementation of this function uses an internal global state + * variable in \ref pbdrv. */ void pb_hook_mod_state_write(pb_global_state_t state); diff --git a/lib/pbdrv/pb-route.c b/lib/pbdrv/pb-route.c index 709fb7f..f5c32d6 100644 --- a/lib/pbdrv/pb-route.c +++ b/lib/pbdrv/pb-route.c @@ -58,8 +58,8 @@ __weak void pb_route_cmd_prop_set(pb_msg_t * msg) {} //! last known global state of last STATE REQ sender (i.e. main controller) static pb_global_state_t _main_state = PB_GS_NOINIT; -__weak void pb_hook_main_state_update(pb_global_state_t state) {} -__weak void pb_hook_module_init() { +__weak void pb_hook_ev_main_state_update(pb_global_state_t state) {} +__weak void pb_hook_ev_module_init() { pb_hook_mod_state_write(PB_GS_IDLE); } __weak void pb_route_cmd_state_req(pb_msg_t * msg) { @@ -69,8 +69,8 @@ __weak void pb_route_cmd_state_req(pb_msg_t * msg) { pb_cmd_state_t * cmd = msg->cmd; if (cmd->state != _main_state) { // first STATE REQ = module init OK - if (_main_state == PB_GS_NOINIT) pb_hook_module_init(); - pb_hook_main_state_update(cmd->state); + if (_main_state == PB_GS_NOINIT) pb_hook_ev_module_init(); + pb_hook_ev_main_state_update(cmd->state); } _main_state = cmd->state; diff --git a/lib/pbdrv/pb-route.h b/lib/pbdrv/pb-route.h index 233a087..b80e4ec 100644 --- a/lib/pbdrv/pb-route.h +++ b/lib/pbdrv/pb-route.h @@ -6,40 +6,185 @@ extern "C" { #endif +/** + * \ingroup pbdrv-mod + * \defgroup pb_route Routing + * \internal + * \brief Parsed message handler routing + * + * These functions form a tree-shaped call graph, and are used to handle + * specific commands received from \c pb_i2c_recv(). + * + * \{ + */ + +/** + * \brief Handle a message with type {\ref PB_CMD_PROP "PROP", \ref + * PB_CMD_STATE "STATE", \ref PB_CMD_MAGIC "MAGIC"} + * + * Calls the next handler depending on \c msg->type. + */ void pb_route_msg(pb_msg_t * msg); +/** + * \brief Handle a \ref PB_CMD_PROP "PROP" message with action {\ref + * pb_route_cmd_prop_req "REQ", \ref pb_route_cmd_prop_res "RES", \ref + * pb_route_cmd_prop_set "SET"} + * + * Calls the next handler depending on \c msg->action. + */ void pb_route_cmd_prop(pb_msg_t * msg); +/** + * \brief Handle a \ref PB_CMD_STATE "STATE" message with action {\ref + * pb_route_cmd_state_req "REQ", \ref pb_route_cmd_state_res "RES", \ref + * pb_route_cmd_state_set "SET"} + * + * Calls the next handler depending on \c msg->action. + */ void pb_route_cmd_state(pb_msg_t * msg); +/** + * \brief Handle a \ref PB_CMD_MAGIC "MAGIC" message with action {\ref + * pb_route_cmd_magic_req "REQ", \ref pb_route_cmd_magic_res "RES"} + * + * Calls the next handler depending on \c msg->action. + * + * \note Messages with type \c MAGIC and action \c SET will be silently + * ignored, as there is no such command. + */ void pb_route_cmd_magic(pb_msg_t * msg); +/** + * \brief Handle a \ref PB_CMD_PROP "PROP" message with action \ref + * PB_ACTION_REQ "REQ" + * + * The default implementation of this function is empty, as puzzle module + * properties are user-defined. + */ void pb_route_cmd_prop_req(pb_msg_t * msg); +/** + * \brief Handle a \ref PB_CMD_PROP "PROP" message with action \ref + * PB_ACTION_RES "RES" + * + * The default implementation of this function is empty, as puzzle module + * properties are user-defined. + */ void pb_route_cmd_prop_res(pb_msg_t * msg); +/** + * \brief Handle a \ref PB_CMD_PROP "PROP" message with action \ref + * PB_ACTION_SET "SET" + * + * The default implementation of this function is empty, as puzzle module + * properties are user-defined. + */ void pb_route_cmd_prop_set(pb_msg_t * msg); +/** + * \brief Handle a \ref PB_CMD_STATE "STATE" message with action \ref + * PB_ACTION_REQ "REQ" + * + * The default implementation of this function does the following: + * - Call \c pb_hook_ev_module_init() if this is the first received \c STATE \c + * REQ command. + * - Call \c pb_hook_ev_main_state_update() if the main controller state has + * changed. + * - Reply with a \c STATE \c RES message. + */ void pb_route_cmd_state_req(pb_msg_t * msg); +/** + * \brief Handle a \ref PB_CMD_STATE "STATE" message with action \ref + * PB_ACTION_RES "RES" + * + * The default implementation of this function is empty, as only the main + * controller handles this type of command. + */ void pb_route_cmd_state_res(pb_msg_t * msg); +/** + * \brief Handle a \ref PB_CMD_STATE "STATE" message with action \ref + * PB_ACTION_SET "SET" + * + * The default implementation of this function does the following: + * - Write the global state variable using \c pb_hook_mod_state_write(). + */ void pb_route_cmd_state_set(pb_msg_t * msg); +/** + * \brief Handle a \ref PB_CMD_MAGIC "MAGIC" message with action \ref + * PB_ACTION_REQ "REQ" + * + * The default implementation of this function does the following: + * - Verify the size of the magic string + * - Verify the content of the magic string + * - Reply with a \c MAGIC \c RES message. + */ void pb_route_cmd_magic_req(pb_msg_t * msg); +/** + * \brief Handle a \ref PB_CMD_MAGIC "MAGIC" message with action \ref + * PB_ACTION_RES "RES" + * + * The default implementation of this function is empty, as only the main + * controller handles this type of command. + */ void pb_route_cmd_magic_res(pb_msg_t * msg); -/// \ingroup hook -/// \{ - -/// \defgroup hook_route Routing -/// \brief Use a custom message handler -/// \{ +/// \} +/** + * \ingroup pb_hook + * \defgroup pb_hook_route Routing + * \brief Conditionally use substitute or extend the built-in message handlers + * \{ + */ + +/** + * \brief \c pb_route_msg() hook + * + * The default implementation of this function immediately returns false. + * + * \return \c true if execution should continue to the default handler, or \c + * false if it should stop (i.e. the message was handled). + */ bool pb_hook_route_msg(pb_msg_t * msg); +//! \c pb_route_cmd_prop() hook \copydetails pb_hook_route_msg bool pb_hook_route_cmd_prop(pb_msg_t * msg); +//! \c pb_route_cmd_state() hook \copydetails pb_hook_route_msg bool pb_hook_route_cmd_state(pb_msg_t * msg); +//! \c pb_route_cmd_magic() hook \copydetails pb_hook_route_msg bool pb_hook_route_cmd_magic(pb_msg_t * msg); /// \} -void pb_hook_main_state_update(pb_global_state_t state); -void pb_hook_module_init(); +/** + * \ingroup pb_hook + * \defgroup pb_hook_ev Events + * \brief Functions called on puzzle bus-related events + * \{ + */ + +/** + * \brief Main controller state update hook + * + * The default implementation of this function is empty. + * + * \param state New state of main controller + * + * \note This function is also called when the first \c STATE \c REQ command is + * received, as the main controller state variable used to check if the state + * actually changed is initialized to \ref PB_GS_NOINIT. In this case, this + * function is called *after* \c pb_hook_ev_module_init(). + */ +void pb_hook_ev_main_state_update(pb_global_state_t state); +/** + * \brief Module initialized hook + * + * The default implementation of this function calls \c + * pb_hook_mod_state_write() with \ref PB_GS_IDLE. + * + * This function is called when the first \c STATE \c REQ command is received, + * indicating this puzzle module has been registered successfully by the main + * controller, and is now part of an active play session. + */ +void pb_hook_ev_module_init(); /// \} diff --git a/lib/pbdrv/pb-types.h b/lib/pbdrv/pb-types.h index f5fbb74..dfd5da9 100644 --- a/lib/pbdrv/pb-types.h +++ b/lib/pbdrv/pb-types.h @@ -8,7 +8,17 @@ extern "C" { #endif +/** + * \ingroup pbdrv + * \ingroup pbdrv-mod + * \defgroup pb_types Types + * \brief Datatypes used within \ref pbdrv + * + * \{ + */ + #ifdef __GNUC__ +//! Mark function as weak (allow user to override implementation) #define __weak __attribute__((weak)) #endif #ifndef __weak @@ -21,15 +31,33 @@ typedef uint16_t i2c_addr_t; //! puzzle bus command types enum pb_cmd_id { - /** \brief puzzle module property (REQ, RES, SET) */ + /** + * \brief puzzle module property (\ref pb_route_cmd_prop_req "REQ", \ref + * pb_route_cmd_prop_res "RES", \ref pb_route_cmd_prop_set "SET") + * + * The \c PROP command type is used for exchanging arbitrary data between + * puzzle modules and/or the puzzle box client (pbc) over the TCP bridge. + * These properties are not used by the puzzle framework. + */ PB_CMD_PROP, - /** \brief puzzle module global state variable (REQ, RES, SET) */ + /** + * \brief puzzle module global state variable (\ref pb_route_cmd_state_req + * "REQ", \ref pb_route_cmd_state_res "RES", \ref pb_route_cmd_state_set + * "SET") + * + * The \c STATE command is used by puzzle modules to inform the main + * controller about their global state. The main controller aggregates the + * states of all connected puzzle modules and exchanges this aggregated state + * with the puzzle modules to indicate when the entire puzzle box is solved. + */ PB_CMD_STATE, /** - * \brief magic (handshake) (REQ, RES) + * \brief magic (handshake) (\ref pb_route_cmd_magic_req "REQ", \ref + * pb_route_cmd_magic_res "RES") * - * This message is used to distinguish between puzzle modules and regular I2C - * slaves on the puzzle bus. + * The \c MAGIC command effectively serves as a 'secret handshake' (using a + * _magic_ value) which is used to distinguish between puzzle modules and + * unrelated I2C devices. */ PB_CMD_MAGIC, }; @@ -57,16 +85,16 @@ static const char pb_cmd_magic_req[] = { 0x70, 0x75, 0x7a, 0x62, 0x75, 0x73 }; //! magic reply from puzzle module back to main controller static const char pb_cmd_magic_res[] = { 0x67, 0x61, 0x6d, 0x69, 0x6e, 0x67 }; -//! puzzle bus message header (shared by all commands) +//! puzzle bus message header / container (shared by all commands) typedef struct { /** - * \brief command type + * \brief Command type (see \ref pb_cmd_id_t) * * This is used to identify what the message is about. */ pb_cmd_id_t type; /** - * \brief command action + * \brief Command action (see \ref pb_action_t) * * This is used to specify what should happen as a result of this message. */ @@ -79,31 +107,33 @@ typedef struct { */ i2c_addr_t sender; /** - * \brief command data (type dependent) + * \brief Command data (dependent on \p type) * * Struct containing command type-specific data. */ void * cmd; } pb_msg_t; -//! PB_CMD_PROP data +//! \ref PB_CMD_PROP data typedef struct { uint8_t propid; //!< id of state property uint8_t * value; //!< new or current value - size_t _value_size; //!< [META] size of \p value + size_t _value_size; //!< size of \p value } pb_cmd_prop_t; -//! PB_CMD_STATE data +//! \ref PB_CMD_STATE data typedef struct { pb_global_state_t state; //!< global state } pb_cmd_state_t; -//! PB_CMD_MAGIC data +//! \ref PB_CMD_MAGIC data typedef struct { char * magic; //!< magic value - size_t _magic_size; //!< [META] size of \p magic + size_t _magic_size; //!< size of \p magic } pb_cmd_magic_t; +/// \} + #ifdef __cplusplus } #endif -- cgit v1.2.3 From bad32f876ab99fe0820fd310a4826378d0b11fe7 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Sat, 22 Jun 2024 11:27:48 +0200 Subject: more docs --- Doxyfile | 1 + lib/pbdrv/pb-buf.h | 4 +- lib/pbdrv/pb-mod.h | 11 +++-- lib/pbdrv/pb-send.c | 10 ++--- lib/pbdrv/pb-send.h | 115 +++++++++++++++++++++++++++++++++++++++++++++++++-- lib/pbdrv/pb-types.h | 35 +++++++++------- 6 files changed, 145 insertions(+), 31 deletions(-) (limited to 'Doxyfile') diff --git a/Doxyfile b/Doxyfile index ea9692a..2d600e7 100644 --- a/Doxyfile +++ b/Doxyfile @@ -26,4 +26,5 @@ INPUT_FILTER = "sed -e 's/\\|\2<\/sup>C\>/\\I2C/g'" USE_MDFILE_AS_MAINPAGE = readme.md INTERNAL_DOCS = YES +EXTRACT_STATIC = YES diff --git a/lib/pbdrv/pb-buf.h b/lib/pbdrv/pb-buf.h index 9ff53fe..8b4bb10 100644 --- a/lib/pbdrv/pb-buf.h +++ b/lib/pbdrv/pb-buf.h @@ -16,8 +16,8 @@ extern "C" { //! binary buffer struct typedef struct { - char * data; //! pointer to data - size_t size; //! size of data + char * data; //!< pointer to data + size_t size; //!< size of data } pb_buf_t; /** diff --git a/lib/pbdrv/pb-mod.h b/lib/pbdrv/pb-mod.h index ef2cd77..75fcbec 100644 --- a/lib/pbdrv/pb-mod.h +++ b/lib/pbdrv/pb-mod.h @@ -9,27 +9,26 @@ extern "C" { /** * \ingroup pbdrv-mod * \defgroup pb_mod Module - * \brief Metadata and auxiliary utility functions + * \brief Puzzle module metadata and auxiliary utility functions * \{ */ /** * \brief Puzzle module name - * - * Optional to define, default value is "???" + * \note This constant is optional to define, its default value is "???" */ extern const char * PB_MOD_NAME; /** * \brief Puzzle module bus address - * - * **Required** to define + * \warning This variable **must** be defined by the user */ extern const i2c_addr_t PB_MOD_ADDR; /** * \brief Platform-specific blocking delay function * - * FIXME: this should be removed (see handover: RP2040 I2C limitations) + * FIXME: this entire function should be removed (see handover: RP2040 I2C + * limitations) */ void pb_mod_blocking_delay_ms(unsigned long ms); diff --git a/lib/pbdrv/pb-send.c b/lib/pbdrv/pb-send.c index 29d81ed..dc34c44 100644 --- a/lib/pbdrv/pb-send.c +++ b/lib/pbdrv/pb-send.c @@ -2,7 +2,7 @@ #include "pb-mod.h" #include "pb-msg.h" -__weak void pb_send_reply(pb_msg_t * msg, pb_buf_t * reply) { +__weak void pb_send_reply(const pb_msg_t * msg, const pb_buf_t * reply) { return pb_i2c_send(msg->sender, (uint8_t *) reply->data, reply->size); } @@ -21,10 +21,10 @@ pb_buf_t pb_send_read_req(uint8_t propid) { return pb_msg_write(&msg); } -pb_buf_t pb_send_read_res(uint8_t propid, uint8_t * value, size_t size) { +pb_buf_t pb_send_read_res(uint8_t propid, const uint8_t * value, size_t size) { pb_cmd_prop_t cmd = { .propid = propid, - .value = value, + .value = (uint8_t *) value, ._value_size = size, }; pb_msg_t msg = { @@ -36,10 +36,10 @@ pb_buf_t pb_send_read_res(uint8_t propid, uint8_t * value, size_t size) { return pb_msg_write(&msg); } -pb_buf_t pb_send_write_req(uint8_t propid, uint8_t * value, size_t size) { +pb_buf_t pb_send_write_req(uint8_t propid, const uint8_t * value, size_t size) { pb_cmd_prop_t cmd = { .propid = propid, - .value = value, + .value = (uint8_t *) value, ._value_size = size, }; pb_msg_t msg = { diff --git a/lib/pbdrv/pb-send.h b/lib/pbdrv/pb-send.h index 679df29..7e21eda 100644 --- a/lib/pbdrv/pb-send.h +++ b/lib/pbdrv/pb-send.h @@ -7,17 +7,126 @@ extern "C" { #endif -void pb_send_reply(pb_msg_t * msg, pb_buf_t * reply); +/** + * \ingroup pbdrv-mod + * \defgroup pb_send Send + * \brief Functions for directly creating serialized message buffers + * \{ + */ +/** + * \brief Utility function for replying to a message + * + * \param msg Message to reply to + * \param reply Data to send as reply + * + * This function uses \c pb_i2c_send() to send \p reply to \p msg->sender. + */ +void pb_send_reply(const pb_msg_t * msg, const pb_buf_t * reply); + +/** + * \brief Create a serialized \ref PB_CMD_PROP "PROP" \ref PB_ACTION_REQ "REQ" + * message + * + * \param propid Property ID to request + * + * \return Message buffer + * + * \note The buffer returned by this function must be free'd with \c + * pb_buf_free(). + */ pb_buf_t pb_send_read_req(uint8_t propid); -pb_buf_t pb_send_read_res(uint8_t propid, uint8_t * value, size_t size); -pb_buf_t pb_send_write_req(uint8_t propid, uint8_t * value, size_t size); +/** + * \brief Create a serialized \ref PB_CMD_PROP "PROP" \ref PB_ACTION_RES "RES" + * message + * + * \param propid Requested property ID + * \param value Pointer to structured data in property + * \param size Size of \p value + * + * \return Message buffer + * + * \note The buffer returned by this function must be free'd with \c + * pb_buf_free(). + */ +pb_buf_t pb_send_read_res(uint8_t propid, const uint8_t * value, size_t size); +/** + * \brief Create a serialized \ref PB_CMD_PROP "PROP" \ref PB_ACTION_SET "SET" + * message + * + * \param propid Property ID to write + * \param value Pointer to data to write to property + * \param size Size of \p value + * + * \return Message buffer + * + * \note The buffer returned by this function must be free'd with \c + * pb_buf_free(). + */ +pb_buf_t pb_send_write_req(uint8_t propid, const uint8_t * value, size_t size); +/** + * \brief Create a serialized \ref PB_CMD_STATE "STATE" \ref PB_ACTION_REQ + * "REQ" message + * + * The current module's state is obtained using \c pb_hook_mod_state_read(). + * + * \return Message buffer + * + * \note The buffer returned by this function must be free'd with \c + * pb_buf_free(). + */ pb_buf_t pb_send_state_req(); +/** + * \brief Create a serialized \ref PB_CMD_STATE "STATE" \ref PB_ACTION_RES + * "RES" message + * + * The current module's state is obtained using \c pb_hook_mod_state_read(). + * + * \return Message buffer + * + * \note The buffer returned by this function must be free'd with \c + * pb_buf_free(). + */ pb_buf_t pb_send_state_res(); +/** + * \brief Create a serialized \ref PB_CMD_STATE "STATE" \ref PB_ACTION_SET + * "SET" message + * + * \param state Requested new state + * + * \return Message buffer + * + * \note The buffer returned by this function must be free'd with \c + * pb_buf_free(). + */ pb_buf_t pb_send_state_set(pb_global_state_t state); +/** + * \brief Create a serialized \ref PB_CMD_MAGIC "MAGIC" \ref PB_ACTION_REQ + * "REQ" message + * + * The magic string is equal to \ref pb_cmd_magic_req. + * + * \return Message buffer + * + * \note The buffer returned by this function must be free'd with \c + * pb_buf_free(). + */ pb_buf_t pb_send_magic_req(); +/** + * \brief Create a serialized \ref PB_CMD_MAGIC "MAGIC" \ref PB_ACTION_RES + * "RES" message + * + * The magic string is equal to \ref pb_cmd_magic_res. + * + * \return Message buffer + * + * \note The buffer returned by this function must be free'd with \c + * pb_buf_free(). + */ pb_buf_t pb_send_magic_res(); +/// \} + #ifdef __cplusplus } #endif diff --git a/lib/pbdrv/pb-types.h b/lib/pbdrv/pb-types.h index dfd5da9..ef3df54 100644 --- a/lib/pbdrv/pb-types.h +++ b/lib/pbdrv/pb-types.h @@ -18,19 +18,19 @@ extern "C" { */ #ifdef __GNUC__ -//! Mark function as weak (allow user to override implementation) #define __weak __attribute__((weak)) #endif #ifndef __weak #error Could not determine weak attribute for current compiler +//! Mark function as weak (allow user to override implementation) #define __weak #endif //! I2C address (10 or 7 bit) typedef uint16_t i2c_addr_t; -//! puzzle bus command types -enum pb_cmd_id { +//! Puzzle bus command types +typedef enum { /** * \brief puzzle module property (\ref pb_route_cmd_prop_req "REQ", \ref * pb_route_cmd_prop_res "RES", \ref pb_route_cmd_prop_set "SET") @@ -60,29 +60,34 @@ enum pb_cmd_id { * unrelated I2C devices. */ PB_CMD_MAGIC, -}; -typedef enum pb_cmd_id pb_cmd_id_t; +} pb_cmd_id_t; -//! puzzle bus command action types -enum pb_action { +//! Puzzle bus command action types +typedef enum { PB_ACTION_REQ, //!< request PB_ACTION_RES, //!< response PB_ACTION_SET, //!< (over)write -}; -typedef enum pb_action pb_action_t; +} pb_action_t; -//! puzzle bus global states -enum pb_global_state { +//! Puzzle module global states +typedef enum { PB_GS_NOINIT, //!< uninitialized (only used by puzzle modules) PB_GS_IDLE, //!< puzzle not started yet PB_GS_PLAYING, //!< puzzle actively being solved PB_GS_SOLVED, //!< puzzle completed -}; -typedef enum pb_global_state pb_global_state_t; +} pb_global_state_t; -//! magic sent from main controller to puzzle module +/** + * \brief Magic sent from main controller to puzzle module (="puzbus") + * + * The size of this array can be obtained by \c sizeof(pb_cmd_magic_req). + */ static const char pb_cmd_magic_req[] = { 0x70, 0x75, 0x7a, 0x62, 0x75, 0x73 }; -//! magic reply from puzzle module back to main controller +/** + * \brief Magic reply from puzzle module back to main controller (="gaming") + * + * The size of this array can be obtained by \c sizeof(pb_cmd_magic_res). + */ static const char pb_cmd_magic_res[] = { 0x67, 0x61, 0x6d, 0x69, 0x6e, 0x67 }; //! puzzle bus message header / container (shared by all commands) -- 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 'Doxyfile') 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 f4e7a23309797c56baf6be3a9e99e74596223474 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Sun, 23 Jun 2024 13:32:18 +0200 Subject: tweak doxygen output --- Doxyfile | 1 + docs/doxygen-layout.xml | 62 ++++++++++++++++++++++++++++++++++++++++ readme.md | 75 ++++++++++++++++++++++--------------------------- 3 files changed, 97 insertions(+), 41 deletions(-) create mode 100644 docs/doxygen-layout.xml (limited to 'Doxyfile') 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 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 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/ 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 -- cgit v1.2.3