diff options
| -rw-r--r-- | client/cmd.h | 15 | ||||
| -rw-r--r-- | client/readme.md | 20 | ||||
| -rw-r--r-- | lib/pbdrv/index.dox | 7 | ||||
| -rw-r--r-- | main/readme.md | 17 | ||||
| -rw-r--r-- | puzzle/readme.md | 11 | ||||
| -rw-r--r-- | readme.md | 87 |
6 files changed, 102 insertions, 55 deletions
diff --git a/client/cmd.h b/client/cmd.h index eac9834..7fee700 100644 --- a/client/cmd.h +++ b/client/cmd.h @@ -61,6 +61,9 @@ cmd_handle_t cmd_exit; /** * \brief \c test command * + * \note This command is only available in builds of \c pbc compiled with the + * \c DEBUG flag + * * ``` * (pbc) test * ``` @@ -96,6 +99,9 @@ cmd_handle_t cmd_reset; /** * \brief \c send command * + * \note This command is only available in builds of \c pbc compiled with the + * \c DEBUG flag + * * ``` * (pbc) send <addr> <data> * ``` @@ -178,6 +184,15 @@ cmd_handle_t cmd_send; cmd_handle_t cmd_skip; /** * \brief \c dump command + * + * \note This command is only available in builds of \c pbc compiled with the + * \c DEBUG flag + * + * ``` + * (pbc) dump <none|send|recv|both> + * ``` + * + * Show raw I2C messages being sent to/from the main controller. */ cmd_handle_t cmd_dump; diff --git a/client/readme.md b/client/readme.md index d99991f..375e8c1 100644 --- a/client/readme.md +++ b/client/readme.md @@ -10,20 +10,24 @@ 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. +> [!NOTE] +> The client depends on the [GNU readline][readline] library, which is not +> included as a submodule because it is installed on most Linux distributions +> by default. Please ensure you have the readline development headers installed +> for your distribution of choice. + ## 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 +- Individually reset puzzle modules +- Individually skip puzzle modules - Debug: send arbitrary messages ## Usage -See \ref pbc_cmd_usage "command usage" for individual command usage. +See [command usage](#pbc_cmd_usage) -## WIP TODO +## Bugs -- add enum to string functions in CLIENT ONLY -- bug: tab completion for `dump` seems to print garbage sometimes +- tab completion for the `dump` command seems to print garbage (sometimes) +[readline]: https://www.gnu.org/software/readline diff --git a/lib/pbdrv/index.dox b/lib/pbdrv/index.dox index 0be5f33..03a17b5 100644 --- a/lib/pbdrv/index.dox +++ b/lib/pbdrv/index.dox @@ -30,10 +30,9 @@ target_link_libraries(main pbdrv) pbdrv-mod is a superset of \ref pbdrv, and includes functions specific to puzzle bus modules. \ref pbdrv-mod compiles to an object file instead of a -static library because it may depend on functions that rely on external -libraries. \ref pbdrv-mod is still considered standalone, but requires either -using an existing \ref pb_drv "driver", or (partially) implementing the driver -functions. +static library because it may depend on functions from external libraries. \ref +pbdrv-mod is still considered standalone, but requires either using an existing +\ref pb_drv "driver", or (partially) implementing the driver functions. Like \ref pbdrv, \ref pbdrv-mod can be used by including this folder in your CMakeLists.txt file and linking the library with your executable. Please see diff --git a/main/readme.md b/main/readme.md index 97150eb..2a50fd1 100644 --- a/main/readme.md +++ b/main/readme.md @@ -4,17 +4,18 @@ # main controller firmware This directory contains the software for the main controller of the Puzzle Box. +The main controller target is a Raspberry Pi Pico W. -## building +## Building -1. make sure the submodules are initialized -2. create a `config.h` file (see \ref main_config "config") -3. use CMake to build +1. Create a `config.h` file (see [config](#main_config)) +2. Use CMake to build -## flashing +## Flashing -1. build -2. hold the BOOTSEL button while resetting the pico (by power cycling or +1. Hold the BOOTSEL button while resetting the Pico (by power cycling or pulling pin 30 (RUN) to GND) -3. `picotool load build/main.uf2` +2. ``` + $ picotool load build/main.uf2 + ``` diff --git a/puzzle/readme.md b/puzzle/readme.md index 1b572ba..833723e 100644 --- a/puzzle/readme.md +++ b/puzzle/readme.md @@ -15,7 +15,15 @@ sure you have done the following: - Open "Tools" > "Board" > "Board manager" - Install the "Arduino AVR Boards" package (1.8.6 works at the time of writing) -[arduino-cmake]: https://github.com/a9183756-gh/Arduino-CMake-Toolchain +Some puzzle modules also require installing libraries through the Arduino +library manager. Dependencies for specific puzzle modules are detailed on their +Doxygen pages. + +### Flashing + +``` +$ ninja -C build upload +``` <!-- @@ -33,3 +41,4 @@ sure you have done the following: --> +[arduino-cmake]: https://github.com/a9183756-gh/Arduino-CMake-Toolchain @@ -10,14 +10,58 @@ 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. +## Libraries + +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. + +> [!NOTE] +> Please note that symbolic links may not work correctly if you clone the +> repository under a filesystem or operating system that does not support +> these. MinGW/Windows are known to have issues with symlinks, so please verify +> symlinks are recognised as such before attempting to build or initialize the +> submodules. + +TL;DR: If something is complaining about missing files + +``` +git submodule update --init --recursive --depth 1 +``` + +until your problems go away. + +## Building + +All subfolders/modules/libraries use CMake, and build in roughly the same way. +All documentation assumes CMake is used in combination with Ninja, though other +generators may also work. The following commands can be used inside each +subfolder to compile (make sure you have initialized the submodules before +compiling): + +``` +$ cmake -B build -G Ninja +$ ninja -C build +``` + +Target-specific flashing/uploading commands are detailed in the respective +folder's README. + > [!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. -> -> Please note that most subfolders use symbolic links to the [lib](lib/) -> folder, which may not work correctly if you clone the repository under a -> filesystem or operating system that does not support these. +> Cross-platform compilation should be supported, though this has not been +> verified. Most of this project was developed on Linux, and Windows +> compatibility has not been verified. + +### lazy\.mk + +[`lazy.mk`](./lazy.mk) is a file made by Loek, and includes some rules for +forwarding `make` calls to `cmake` and `ninja`. **This is purely for +convenience, and should not become an essential part of the build system**. +This file should be included at the end of a regular makefile. Any targets +defined in a makefile can be used as-is, while targets that would otherwise be +unknown will be forwarded to Ninja. ## Documentation @@ -43,35 +87,10 @@ Please keep this repository tidy by being aware of the following conventions: - 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 +- There are also `.clang-tidy` and `.clang-format` files which define specific + code style attributes. These can be enforced by running ``` $ make format ``` -## Libraries - -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. - -TL;DR: If something is complaining about missing files - -``` -git submodule update --init --recursive --depth 1 -``` - -until your problems go away. - -## lazy\.mk - -[`lazy.mk`](./lazy.mk) is a file made by Loek, and includes some rules for -forwarding `make` calls to `cmake` and `ninja`. **This is purely for -convenience, and should not become an essential part of the build system**. -This file should be included at the end of a regular makefile. Any targets -defined in a makefile can be used as-is, while targets that would otherwise be -unknown will be forwarded to Ninja. - |