This repository contains the source code for the puzzle framework designed and 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.

The software in this repository should be easily portable to various other microcontrollers, and a recommendation is made in the design document. Please see the handover document first for more details.

Libraries

Libraries are stored in the 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 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: 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 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

If you are viewing this page from Doxygen, please take a look at the components tab for a comprehensive list of components within this project.

Project documentation is available in the docs folder, and all code is documented using Doxygen. To generate HTML docs, run

$ make doxygen

and open the generated HTML files in a browser. A rendered copy of this documentation is also hosted unofficially at pipeframe.

Tidyness

Please keep this repository tidy by being aware of the following conventions:

An .editorconfig file is provided in this repository. Please install the EditorConfig plugin for your text editor of choice to automatically use these.
There are also .clang-tidy and .clang-format files which define specific code style attributes. These can be enforced by running

$ make format