diff options
| -rw-r--r-- | Doxyfile | 6 | ||||
| -rw-r--r-- | client/readme.md | 32 | ||||
| -rw-r--r-- | lib/i2ctcp/i2ctcpv1.h | 2 | ||||
| -rw-r--r-- | lib/mpack/mpack.h | 31 | ||||
| -rw-r--r-- | main/readme.md | 3 | ||||
| -rw-r--r-- | makefile | 9 | ||||
| -rw-r--r-- | puzzle/dummy/index.dox | 9 | ||||
| -rw-r--r-- | puzzle/neo/index.dox | 6 | ||||
| -rw-r--r-- | puzzle/readme.md | 17 | ||||
| -rw-r--r-- | puzzle/vault/index.dox | 6 | ||||
| -rw-r--r-- | readme.md | 22 |
11 files changed, 109 insertions, 34 deletions
@@ -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/\<I2C\>\|\<I<sup>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. @@ -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 +*/ @@ -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 <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. + ## 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 |