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 --- lib/pbdrv/pb-mod.h | 36 ++++++++++++++++++++++++++++++++++-- 1 file changed, 34 insertions(+), 2 deletions(-) (limited to 'lib') diff --git a/lib/pbdrv/pb-mod.h b/lib/pbdrv/pb-mod.h index ae36d22..c4629a6 100644 --- a/lib/pbdrv/pb-mod.h +++ b/lib/pbdrv/pb-mod.h @@ -3,8 +3,8 @@ /** * \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 + * 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. @@ -21,10 +21,42 @@ extern const char * PB_MOD_NAME; //! puzzle module bus address (required) extern const i2c_addr_t PB_MOD_ADDR; +/** + * \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. + * + * \param buf pointer to message content + * \param sz size of \p buf + * + * \note This function should not be directly called from an ISR. Please use + * FreeRTOS's \c xTimerPendFunctionCallFromISR() or a similar scheduler-based + * deferred function call mechanism instead. + */ void pb_i2c_recv(const uint8_t * buf, size_t sz); +/** + * \brief send a message in master-mode on the I2C bus (puzzle bus) + * + * This function sends an I2C message to the address specified by \p i2c_addr. + * + * \param i2c_addr address of slave controller + * \param buf pointer to message content + * \param sz size of \p buf + */ void pb_i2c_send(i2c_addr_t i2c_addr, const uint8_t * buf, size_t sz); +/** + * \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); /** -- cgit v1.2.3 From 9425826203e1c954491a6a29ae84daf1a5edda2c Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Thu, 20 Jun 2024 17:53:58 +0200 Subject: more documentation (WIP design.adoc) --- docs/design.adoc | 96 ++++---- docs/figs.drawio | 396 ++++++++------------------------ docs/img/.gitignore | 1 + docs/img/main-controller-state.svg | 2 +- docs/img/main-controller-top.svg | 2 +- docs/img/power-supply-top.svg | 2 +- docs/img/puzzle-module-common-state.svg | 2 +- docs/img/puzzle-module-top.svg | 2 +- docs/img/software-components.puml | 37 +++ docs/img/style.ipuml | 3 + docs/img/system-bus.svg | 2 +- docs/img/system-top.svg | 2 +- docs/makefile | 5 + lib/pbdrv/pb-types.h | 43 +++- 14 files changed, 232 insertions(+), 363 deletions(-) create mode 100644 docs/img/.gitignore create mode 100644 docs/img/software-components.puml create mode 100644 docs/img/style.ipuml (limited to 'lib') diff --git a/docs/design.adoc b/docs/design.adoc index 5ebbb15..e54c970 100644 --- a/docs/design.adoc +++ b/docs/design.adoc @@ -117,7 +117,7 @@ the following: ** Aggregating game state for all installed puzzle modules. ** Reading and writing game state for all installed puzzle modules. ** Broadcasting updates internally. -* Serve TCP socket connections for— +* Serve a TCP socket for— ** Sending state updates ** Manually updating game state ** Integration with the bomb @@ -146,6 +146,7 @@ The criteria for the main controller are: The requirements document compares various microcontrollers that fit these criteria. After this comparison, the decision was made to utilize the Raspberry Pi Pico W as main controller during development. +// TODO: this was a bad choice [[fig:main-controller-top]] .Main controller top-level block diagram @@ -165,9 +166,22 @@ peripherals is handled through a central I^2^C bus referred to as the 'puzzle bus'. This design was again carried over from the hardware design from the 21-22 group cite:[2122_design]. -The only notable difference made this year was the removal of the -"HarwareInterrupt" line1{empty}footnote:[This is not a typo], which was -connected but not utilized cite:[research]. +The previously specified "HarwareInterrupt" line1{empty}footnote:[This is not a +typo] has been removed this year, as it was connected but not utilized +cite:[research]. + +To optimize for flexibility and extensibility, the puzzle bus should ideally +function as a network (similar to the CAN bus), to allow puzzle modules to send +responses asynchronously. I^2^C was initially chosen for the puzzle bus due to +its widespread availability on microcontrollers and in peripherals, but does +not provide any network-like capabilities. + +To archive network-like capabilities, the puzzle bus is specified to be a +multi-master I^2^C bus, and all puzzle modules are specified to be I^2^C +multi-master controllers that are slave-addressible. The multi-master part is +required to prevent I^2^C transmissions from being corrupted in the event of a +bus collision, and the slave-addressible part is required to both send and +receive messages on the same controller. Address definitions and protocol specifications are further detailed in <>. @@ -202,15 +216,15 @@ image::img/system-bus.svg[] [[sec:lv2]] == Modules -This section elaborates on the top-level specifications from <> with -additional hardware specifications and software design decisions. +This section elaborates on the top-level (hardware) specifications from +<> with software design decisions. === Puzzle Module Framework This subsection defines aspects of the 'puzzle framework' and the interface that allows puzzle modules to integrate with this framework. All communication described within this subsection refers to 'internal' communication between the -main controller and puzzle module. +main controller and puzzle modules on the puzzle bus. The puzzle framework is the foundation of the puzzle box software, and is designed to facilitate the following: @@ -226,56 +240,52 @@ designed to facilitate the following: ==== State All puzzle modules implement the same state machine shown in -<>. Note that the arrows indicate state -transitions that a puzzle module may take on its own. The main controller also -allows the game operator to manually set the current state as one of the states -on the right half of <>, which can be used to -skip a puzzle if a player is stuck (<>) or -reset a game if it is malfunctioning (<>). - -Puzzle modules start in the 'uninitialized' state, where they repeatedly send -messages to the main controller (see <>). The state transition -from 'uninitialized' to 'reset' is forced by the main controller upon -initialization. States on the right half of <> -are used during gameplay. +<>. Note that solid arrows indicate state +transitions that a puzzle module may take on its own, while dashed arrows +indicate state transitions forced by the main controller. The main controller +also allows the game operator to manually set the current state as one of the +states on the right half of <>, which can be +used to skip a puzzle if a player is stuck (<>) +or reset a game if it is malfunctioning (<>). + +Puzzle modules start in the 'uninitialized' state, where they wait until the +main controller sends a SET STATE command. Receiving this command indicates to +the puzzle module that it was successfully registered by the main controller, +and that it may transition from the 'uninitialized' state to the 'reset' state. [[fig:puzzle-module-common-state]] .Global puzzle module state machine image::img/puzzle-module-common-state.svg[] The state machine described in <> is referred -to as the global state. Puzzle modules may also declare and define custom state -variables, which is referred to as auxiliary state. These auxiliary state -variables contain game-specific variables; e.g. the binary state of each button -on the Neotrellis puzzle module, or the last passcode entered on the vault -puzzle module. +to as the global state. Puzzle modules may also declare and define custom +variables, which are referred to as properties. These properties may contain +game-specific variables; e.g. the binary state of each button on the Neotrellis +puzzle module, or the last passcode entered on the vault puzzle module. -Separating the auxiliary state from the generic state allows the main -controller to handle the auxiliary state as an arbitrary blob, which allows for -future expansion without modification of the main controller software. +Separating properties from the global state allows the main controller to +handle these property values as an arbitrary blob, which allows for future +expansion without modification of the main controller software. ==== Commands -The puzzle module framework describes the following commands: +The puzzle module framework describes the following command *types*: + +* ``PROP``: property +* ``MAGIC``: handshake +* ``STATE``: global state -* Read state -* Write state -* Update +Each command also has a specific *action*: -The 'read' and 'write' commands are used to communicate both types of state -defined in <>. +* ``REQ``: request +* ``RES``: response +* ``SET``: (over)write -To avoid issues caused by state synchronization memory consumption on the main -controller and puzzle modules, auxiliary state is only stored on each -respective puzzle module's controller. Only global state is cached on the main -controller to reduce the number of back-and-forth messages required for state -updates. +Not all commands define behavior for all actions (e.g. there is no MAGIC SET +command). -These commands are sufficient to realize the puzzle box, but this means that -the puzzle box would rely heavily on polling-based updates internally. To solve -this, the 'update' command was created. This command is utilized for various -kinds of updates, including registering new puzzle modules and updating global -state. +The Doxygen-generated pages for these command types explain their usage, and +will not be repeated here. === Main Controller diff --git a/docs/figs.drawio b/docs/figs.drawio index 042ce15..d898390 100644 --- a/docs/figs.drawio +++ b/docs/figs.drawio @@ -1,4 +1,4 @@ - + @@ -354,20 +354,20 @@ - + - - + + - + - + @@ -381,28 +381,28 @@ - + - - + + - + - - + + - - + + @@ -415,21 +415,21 @@ - + - - + + - + - - + + @@ -437,465 +437,249 @@ - + - + + + + - + - - + + - + - - + + - - + + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + - - - - - - - - - - + + - - - - - - - - - - + + - + - - + + - - + - - + + + - - + - + + + - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + diff --git a/docs/img/.gitignore b/docs/img/.gitignore new file mode 100644 index 0000000..afafe8d --- /dev/null +++ b/docs/img/.gitignore @@ -0,0 +1 @@ +software-components.svg diff --git a/docs/img/main-controller-state.svg b/docs/img/main-controller-state.svg index 6e0333b..f82a8c0 100644 --- a/docs/img/main-controller-state.svg +++ b/docs/img/main-controller-state.svg @@ -1,3 +1,3 @@ -
Reset
Playing
Solved
 \ No newline at end of file +
idle
playing
solved
 \ No newline at end of file diff --git a/docs/img/main-controller-top.svg b/docs/img/main-controller-top.svg index 5bb7cda..601b402 100644 --- a/docs/img/main-controller-top.svg +++ b/docs/img/main-controller-top.svg @@ -1,3 +1,3 @@ -
Main controller
Puzzle bus
Wi-Fi
 \ No newline at end of file +
main controller
puzzle bus
Wi-Fi
 \ No newline at end of file diff --git a/docs/img/power-supply-top.svg b/docs/img/power-supply-top.svg index 89107a6..1ba4c14 100644 --- a/docs/img/power-supply-top.svg +++ b/docs/img/power-supply-top.svg @@ -1,3 +1,3 @@ -
Power supply
Puzzle bus
Charger
 \ No newline at end of file +
power supply
puzzle bus
charger
 \ No newline at end of file diff --git a/docs/img/puzzle-module-common-state.svg b/docs/img/puzzle-module-common-state.svg index b5688ef..4b1e1fd 100644 --- a/docs/img/puzzle-module-common-state.svg +++ b/docs/img/puzzle-module-common-state.svg @@ -1,3 +1,3 @@ -
Uninitialized
Reset
Playing
Solved
 \ No newline at end of file +
uninitialized
idle
playing
solved
 \ No newline at end of file diff --git a/docs/img/puzzle-module-top.svg b/docs/img/puzzle-module-top.svg index 79c16ed..bc65730 100644 --- a/docs/img/puzzle-module-top.svg +++ b/docs/img/puzzle-module-top.svg @@ -1,3 +1,3 @@ -
Puzzle module
Puzzle bus
Puzzle outputs
Puzzle inputs
 \ No newline at end of file +
puzzle module
puzzle bus
puzzle outputs
puzzle inputs
 \ No newline at end of file diff --git a/docs/img/software-components.puml b/docs/img/software-components.puml new file mode 100644 index 0000000..3803334 --- /dev/null +++ b/docs/img/software-components.puml @@ -0,0 +1,37 @@ +@startuml +!include style.ipuml + +component [arduino-sdk] as "Arduino SDK" + +component pbdrv-mod as "Puzzle bus module driver\n(pbdrv-mod)" { + component pbdrv as "Puzzle bus driver\n(pbdrv)" +} + +[freertos] as "FreeRTOS" +[mpack] as "mpack" + +[pico-sdk] as "RPI Pico SDK\n(pico-sdk)" +[i2ctcp] as "i2c over tcp bridge\n(i2ctcp)" + +node pbc as "puzzle box client\n(pbc)" +node main as "main controller software" +node pm as "puzzle module" + +pm ---> [pbdrv-mod] +pm ----> [freertos] +pm ----> [arduino-sdk] + +main ---> [pbdrv-mod] +main ----> [freertos] +main ----> [pico-sdk] +main ---> [i2ctcp] + +pbc ---> [pbdrv] +pbc ---> [i2ctcp] + +[pbdrv] --> [mpack] + +[i2ctcp] --> [mpack] + +@enduml + diff --git a/docs/img/style.ipuml b/docs/img/style.ipuml new file mode 100644 index 0000000..25bb6d7 --- /dev/null +++ b/docs/img/style.ipuml @@ -0,0 +1,3 @@ +!theme plain +skinparam RoundCorner 0 + diff --git a/docs/img/system-bus.svg b/docs/img/system-bus.svg index 440227a..1b04940 100644 --- a/docs/img/system-bus.svg +++ b/docs/img/system-bus.svg @@ -1,3 +1,3 @@ -
Puzzle bus
(I²C + power)
Main controller
Puzzle module 3
(neotrellis)
Puzzle module 4
(safe)
Puzzle module 1
(software)
Puzzle module 2
(hardware)
Power supply
(battery pack)
 \ No newline at end of file +
puzzle bus
(I²C + power)
main controller
neotrellis puzzle module
vault puzzle module
software puzzle module
hardware puzzle module
power supply
(battery pack)
 \ No newline at end of file diff --git a/docs/img/system-top.svg b/docs/img/system-top.svg index 0a9e8c0..902fa07 100644 --- a/docs/img/system-top.svg +++ b/docs/img/system-top.svg @@ -1,3 +1,3 @@ -
Puzzle outputs
Puzzle box
Puzzle inputs
Player(s)
Charger
Wi-Fi
Bomb
 \ No newline at end of file +
puzzle outputs
puzzle box
puzzle inputs
player(s)
charger
Wi-Fi
bomb
 \ No newline at end of file diff --git a/docs/makefile b/docs/makefile index eb54a80..15ea3a4 100644 --- a/docs/makefile +++ b/docs/makefile @@ -20,3 +20,8 @@ ASCIIDOCTOR_ARGS += --backend pdf %.pdf: %.adoc $(PDFDEPS) bundle exec asciidoctor $(ASCIIDOCTOR_ARGS) $< +%.svg: %.puml + plantuml -tsvg $< + +design.pdf: img/software-components.svg + diff --git a/lib/pbdrv/pb-types.h b/lib/pbdrv/pb-types.h index 4d085f9..f5fbb74 100644 --- a/lib/pbdrv/pb-types.h +++ b/lib/pbdrv/pb-types.h @@ -21,9 +21,17 @@ typedef uint16_t i2c_addr_t; //! puzzle bus command types enum pb_cmd_id { - PB_CMD_PROP, //!< puzzle module property - PB_CMD_STATE, //!< global state - PB_CMD_MAGIC, //!< magic (handshake) + /** \brief puzzle module property (REQ, RES, SET) */ + PB_CMD_PROP, + /** \brief puzzle module global state variable (REQ, RES, SET) */ + PB_CMD_STATE, + /** + * \brief magic (handshake) (REQ, RES) + * + * This message is used to distinguish between puzzle modules and regular I2C + * slaves on the puzzle bus. + */ + PB_CMD_MAGIC, }; typedef enum pb_cmd_id pb_cmd_id_t; @@ -51,10 +59,31 @@ static const char pb_cmd_magic_res[] = { 0x67, 0x61, 0x6d, 0x69, 0x6e, 0x67 }; //! puzzle bus message header (shared by all commands) typedef struct { - pb_cmd_id_t type; //!< command type - pb_action_t action; //!< command action - i2c_addr_t sender; //!< i2c address of sender - void * cmd; //!< command data (type dependant) + /** + * \brief command type + * + * This is used to identify what the message is about. + */ + pb_cmd_id_t type; + /** + * \brief command action + * + * This is used to specify what should happen as a result of this message. + */ + pb_action_t action; + /** + * \brief I2C address of sender + * + * This is used to facilitate the 'network' features, as the sender of an I2C + * write is unknown. + */ + i2c_addr_t sender; + /** + * \brief command data (type dependent) + * + * Struct containing command type-specific data. + */ + void * cmd; } pb_msg_t; //! PB_CMD_PROP data -- cgit v1.2.3 From d57d0cdb11451283fffbc3ac4b4deaacf188e94a Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Fri, 21 Jun 2024 10:51:19 +0200 Subject: add puzzle module init hook + weak implementation --- lib/pbdrv/pb-route.c | 9 ++++++++- lib/pbdrv/pb-route.h | 1 + 2 files changed, 9 insertions(+), 1 deletion(-) (limited to 'lib') diff --git a/lib/pbdrv/pb-route.c b/lib/pbdrv/pb-route.c index ee47700..df00cd3 100644 --- a/lib/pbdrv/pb-route.c +++ b/lib/pbdrv/pb-route.c @@ -56,8 +56,12 @@ __weak void pb_route_cmd_prop_req(pb_msg_t * msg) {} __weak void pb_route_cmd_prop_res(pb_msg_t * msg) {} __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() { + pb_hook_mod_state_write(PB_GS_IDLE); +} __weak void pb_route_cmd_state_req(pb_msg_t * msg) { pb_global_state_t own_state = pb_hook_mod_state_read(); pb_buf_t buf = pb_send_state_res(own_state); @@ -66,8 +70,11 @@ __weak void pb_route_cmd_state_req(pb_msg_t * msg) { // notify of new global state variable pb_cmd_state_t * cmd = msg->cmd; - if (cmd->state != _main_state) + 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); + } _main_state = cmd->state; } diff --git a/lib/pbdrv/pb-route.h b/lib/pbdrv/pb-route.h index 41c009a..967c4a9 100644 --- a/lib/pbdrv/pb-route.h +++ b/lib/pbdrv/pb-route.h @@ -27,6 +27,7 @@ void pb_route_cmd_state_res(pb_msg_t * msg); void pb_route_cmd_state_set(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); -- cgit v1.2.3 From 6da66e5356eb367e4b766484eab3a94cb009fb9c Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Fri, 21 Jun 2024 10:56:20 +0200 Subject: fix dumb mistake in pbdrv --- lib/pbdrv/pb-route.c | 7 ++++--- lib/pbdrv/pb-send.c | 4 ++-- lib/pbdrv/pb-send.h | 2 +- 3 files changed, 7 insertions(+), 6 deletions(-) (limited to 'lib') diff --git a/lib/pbdrv/pb-route.c b/lib/pbdrv/pb-route.c index df00cd3..709fb7f 100644 --- a/lib/pbdrv/pb-route.c +++ b/lib/pbdrv/pb-route.c @@ -64,9 +64,6 @@ __weak void pb_hook_module_init() { } __weak void pb_route_cmd_state_req(pb_msg_t * msg) { pb_global_state_t own_state = pb_hook_mod_state_read(); - pb_buf_t buf = pb_send_state_res(own_state); - pb_send_reply(msg, &buf); - pb_buf_free(&buf); // notify of new global state variable pb_cmd_state_t * cmd = msg->cmd; @@ -76,6 +73,10 @@ __weak void pb_route_cmd_state_req(pb_msg_t * msg) { pb_hook_main_state_update(cmd->state); } _main_state = cmd->state; + + pb_buf_t buf = pb_send_state_res(); + pb_send_reply(msg, &buf); + pb_buf_free(&buf); } __weak void pb_route_cmd_state_res(pb_msg_t * msg) {} diff --git a/lib/pbdrv/pb-send.c b/lib/pbdrv/pb-send.c index 66c43c1..29d81ed 100644 --- a/lib/pbdrv/pb-send.c +++ b/lib/pbdrv/pb-send.c @@ -64,9 +64,9 @@ pb_buf_t pb_send_state_req() { return pb_msg_write(&msg); } -pb_buf_t pb_send_state_res(pb_global_state_t state) { +pb_buf_t pb_send_state_res() { pb_cmd_state_t cmd = { - .state = state, + .state = pb_hook_mod_state_read(), }; pb_msg_t msg = { .type = PB_CMD_STATE, diff --git a/lib/pbdrv/pb-send.h b/lib/pbdrv/pb-send.h index 2f8be1e..679df29 100644 --- a/lib/pbdrv/pb-send.h +++ b/lib/pbdrv/pb-send.h @@ -13,7 +13,7 @@ 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); pb_buf_t pb_send_state_req(); -pb_buf_t pb_send_state_res(pb_global_state_t state); +pb_buf_t pb_send_state_res(); pb_buf_t pb_send_state_set(pb_global_state_t state); pb_buf_t pb_send_magic_req(); pb_buf_t pb_send_magic_res(); -- cgit v1.2.3 From 67f076b151d35a36800734cb31a403fac92ffb6d Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Fri, 21 Jun 2024 13:22:18 +0200 Subject: WIP more design document + add TODOs --- docs/design.adoc | 332 +++++++++++++++++------------- docs/handover.adoc | 3 +- docs/img/.gitignore | 2 + docs/img/sequence-puzzle-module-init.puml | 17 ++ docs/img/sequence-puzzle-module-init.svg | 3 - docs/img/style.ipuml | 1 + docs/makefile | 1 + lib/pbdrv/pb.h | 19 +- 8 files changed, 222 insertions(+), 156 deletions(-) create mode 100644 docs/img/sequence-puzzle-module-init.puml delete mode 100644 docs/img/sequence-puzzle-module-init.svg (limited to 'lib') diff --git a/docs/design.adoc b/docs/design.adoc index e54c970..7d9759a 100644 --- a/docs/design.adoc +++ b/docs/design.adoc @@ -219,12 +219,36 @@ image::img/system-bus.svg[] This section elaborates on the top-level (hardware) specifications from <> with software design decisions. -=== Puzzle Module Framework +=== Software module separation -This subsection defines aspects of the 'puzzle framework' and the interface -that allows puzzle modules to integrate with this framework. All communication -described within this subsection refers to 'internal' communication between the -main controller and puzzle modules on the puzzle bus. +[[fig:software-component]] +.Software library components +image::img/software-components.svg[] + +<> shows a software component diagram with an example +Arduino-based puzzle module, the main controller and the puzzle box client. +Notable properties of this architecture include: + +* The Arduino SDK, FreeRTOS, mpack, and RPI Pico SDK are external libraries, + and with the exception of mpack, these have not been modified. +* The puzzle bus driver is split into a (portable) standalone library and a + module-specific driver. +* There is a separate library for (de)serializing I^2^C commands for + transmission over TCP. + +The specific decision to split the puzzle bus driver and create a separate +I^2^C over TCP library was made to avoid writing a command set separate from +internal puzzle bus commands (i.e. one specific to TCP connections). This +architecture allows the puzzle box client to not only control the main +controller, but also directly inspect puzzle bus messages for debugging and +development of future puzzle modules (<>). + +=== Puzzle module framework + +This subsection defines aspects of the 'puzzle framework': the interface that +allows puzzle modules to integrate with the puzzle bus main controller. All +communication described within this subsection refers to 'internal' +communication between the main controller and puzzle modules on the puzzle bus. The puzzle framework is the foundation of the puzzle box software, and is designed to facilitate the following: @@ -240,18 +264,18 @@ designed to facilitate the following: ==== State All puzzle modules implement the same state machine shown in -<>. Note that solid arrows indicate state +<>. Note that continuous arrows indicate state transitions that a puzzle module may take on its own, while dashed arrows indicate state transitions forced by the main controller. The main controller -also allows the game operator to manually set the current state as one of the -states on the right half of <>, which can be -used to skip a puzzle if a player is stuck (<>) -or reset a game if it is malfunctioning (<>). +also allows the game operator to manually set a module''s global state to one of +these states, which can be used to skip a puzzle if a player is stuck +(<>) or reset a game if it is malfunctioning +(<>). Puzzle modules start in the 'uninitialized' state, where they wait until the main controller sends a SET STATE command. Receiving this command indicates to the puzzle module that it was successfully registered by the main controller, -and that it may transition from the 'uninitialized' state to the 'reset' state. +and that it may transition from the 'uninitialized' state to the 'idle' state. [[fig:puzzle-module-common-state]] .Global puzzle module state machine @@ -269,70 +293,124 @@ expansion without modification of the main controller software. ==== Commands -The puzzle module framework describes the following command *types*: +// TODO: cleanup + +All messages sent over the puzzle bus have a similar format. This format is +shown in Table 2. Notable details include: + +The 'subject' field does not have to match the I^2^C address of the message +sender or recipient + +Property 0x00 stores a module's global state + +.Puzzle bus message format +[%autowidth] +|=== +| Field | Content + +| Command | Enum: read, write, update +| Subject | I^2^C address (7-bit) +| Property | Address (8-bit) +| Value | Byte string (variable length) +|=== + +The messages described in Table 2 are (de)serialized using Google's protocol +buffer library. This choice was made after considering various alternative +options for sending structured messages cite:[research]. + +<> shows an example of how messages are +exchanged for the initialization of a puzzle module. + +<> shows an example exchange where the last puzzle +module (A) is solved while (B) is already solved. + +. First, module A sets it's own state to 'solved' and subsequently informs the + main controller of this change. +. As a result of this update notification, the main controller queries puzzle + module A for its new global state. +. Once the main controller has received and confirmed that all puzzle module + global states are set to 'solved', the main controller sets its own state to + 'solved', and broadcasts an update message to all puzzle modules. +. As a result of the update message from the main controller, module B requests + the main controller's new global state, and is able to verify that all puzzle + modules have been solved. + +In this example, module B could be the vault puzzle module, which displays a +code when the entire puzzle box is solved. + +[[fig:sequence-puzzle-finish]] +.Puzzle box finish sequence diagram +image::img/sequence-puzzle-finish.svg[] + +The puzzle module framework describes the following command _types_: * ``PROP``: property * ``MAGIC``: handshake * ``STATE``: global state -Each command also has a specific *action*: +Each command also has a specific _action_: * ``REQ``: request * ``RES``: response * ``SET``: (over)write -Not all commands define behavior for all actions (e.g. there is no MAGIC SET -command). +- Not all commands define behavior for all actions (e.g. there is no MAGIC SET + command). +- A REQ command is always answered by a RES command. +- A SET command does not have a reply. +- All commands are sent as I^2^C writes. The Doxygen-generated pages for these command types explain their usage, and -will not be repeated here. +will not be restated in this document. === Main Controller This subsection defines the function and state of the main controller. +==== Initializing puzzle modules + +The main controller sends a MAGIC REQ command to every I^2^C address on +startup. The MAGIC command effectively serves as a 'secret handshake' (using a +_magic_ value) which is used to distinguish between puzzle modules and +unrelated I^2^C devices. Puzzle modules start in the 'uninitialized' state (see +<>), in which they do nothing. Puzzle modules +in this state are still able to reply to requests, including MAGIC REQ +commands. When the main controller receives a MAGIC RES command, the I^2^C +address of the sender is added to an internal list for puzzle modules. + +After the initial handshake request 'wave' (bus scan), all puzzle modules are +repeatedly asked for their global state using a STATE REQ command. This request +also includes the global state of the requesting puzzle module, which is always +the main controller (under normal circumstances). Upon receiving the first +STATE REQ command, a puzzle module knows it has been registered successfully by +the main controller, and may transition into the 'idle' state. + +[[fig:sequence-puzzle-module-init]] +.Puzzle module initialization sequence diagram +image::img/sequence-puzzle-module-init.svg[] + +(Activated lifeline indicates the module is no longer in 'uninitialized' state) + ==== State -The global state of the main controller is an aggregated version of all -installed puzzle modules and is defined by the state machine shown in +The global state of the main controller is an aggregation of all installed +puzzle modules and is defined by the state machine shown in <>. [[fig:main-controller-state]] .Main controller global state machine image::img/main-controller-state.svg[] -The following list describes when each state is active: +The main controller global state is determined using the following rules: -* If all puzzle modules are in the 'reset' state, the main controller is also - in the 'reset' state. +* If all puzzle modules are in the 'idle' state, the main controller is also in + the 'idle' state. * If all puzzle modules are in the 'solved' state, the main controller is also - in the 'solved' state. + in the 'solved' state. * Else, the main controller is in the 'playing' state. -Because the main controller's state is only dependent on the installed puzzle -modules' state, it is only updated when a puzzle module sends an update -notification. When the global state of the main module changes, an update -broadcast is sent to all puzzle modules. - -To simplify the commands used to control the puzzle box, the list of installed -puzzle modules is stored as an auxiliary state variable of the main controller. - -==== Initializing Puzzle Modules - -Puzzle modules start in the 'uninitialized' state (see -<>). In this state, the puzzle module -repeatedly sends an update command to the main controller. The main controller -responds to this message by sending a 'set state' command with the target state -as 'reset' as reply. Before this response is sent, the main controller -internally adds the bus address of the puzzle module requesting to be -initialized to the list of installed puzzle modules. From the main controller's -point of view, this reply marks the moment the initialization is complete. - -[[fig:sequence-puzzle-module-init]] -.Puzzle module initialization sequence diagram -image::img/sequence-puzzle-module-init.svg[] - -(Activated lifeline indicates the module is no longer in 'uninitialized' state) +Due to the repeated STATE REQ commands, this effectively informs the puzzle +modules when the puzzle box is completely solved. [[sec:main-bridge]] ==== Bridge @@ -343,99 +421,83 @@ The Raspberry Pi 3B+ used as main controller during the 21-22 run of the project set up a Wi-Fi Mesh network cite:[2122_design] to communicate with the puzzle box. This year's main controller (Raspberry Pi Pico W cite:[research]) uses a standard 802.11b/g/n access point instead -(<>). +(<>) as it is a simpler solution. + +On this network, the main controller hosts a server that serves a TCP socket +connection. This socket is used to directly forward all internal messages sent +on the puzzle bus to the puzzle box client bidirectionally (on behalf of the +main controller). + +Due to the separation of the puzzle bus driver code into a standalone library +for reading/writing puzzle bus commands, and a puzzle module-specific code, the +puzzle box client is able to read/write raw I^2^C commands directly. A separate +library was made for serializing I^2^C messages so they can be sent over the +TCP connection. -On this network, the main controller hosts a server that serves TCP socket -connections. These sockets directly forward all internal messages sent to the -main controller bidirectionally (i.e. on behalf of the main controller). Detailed specifications on the TCP socket server are in <>. -==== Operating System +==== Operating system + +TODO -The research document cite:[research] contains a detailed comparison of various -operating systems that are suitable to realize the functionality described in -this section. After this comparison, the decision was made to utilize FreeRTOS -as the operating system on the Rasberry Pi Pico W. +- main controller does tcp and i2c at the same time +- simple scheduler is needed +- curriculum only has FreeRTOS and Zephyr +- Zephyr is overkill +- FreeRTOS it is + +- due to RP2040 limitations, delays are used +- most SDKs I2C drivers directly call I2C message handlers from ISR +- puzzle bus driver functions can no longer be called directly from ISR handlers due to the delay +- FreeRTOS is also used in puzzle modules, though this can likely be removed in the future [[sec:lv2-bus]] -=== Puzzle Bus +=== Puzzle bus This section describes the addresses and communication protocol used on the puzzle bus. These specifications only apply to messages sent internally in the puzzle box, as messages forwarded by the bridge (see <>) are sent on behalf of the main controller. -==== Addresses - -The I^2^C addresses remain mostly unchanged from the 20-21 group's -implementation cite:[2021_design]. Addresses that were modified since the 20-21 -implementation are marked with an asterisk. Table 1 lists these addresses for -reference. These addresses are also used to identify specific puzzle modules. - -.I^2^C address reference -[%autowidth] -|=== -| Peripheral | Address - -| Main controller | 0x10* -| Neotrellis puzzle controller | 0x11* -| Neotrellis button matrix | 0x12* -| Software puzzle controller | 0x03 -| Hardware puzzle controller | 0x04 -| Vault puzzle controller | 0x06 -|=== - -==== Messages - -All messages sent over the puzzle bus have a similar format. This format is -shown in Table 2. Notable details include: - -The 'subject' field does not have to match the I^2^C address of the message -sender or recipient - -Property 0x00 stores a module's global state +==== Guidelines -.Puzzle bus message format -[%autowidth] -|=== -| Field | Content +The following assumptions are made about puzzle modules: -| Command | Enum: read, write, update -| Subject | I^2^C address (7-bit) -| Property | Address (8-bit) -| Value | Byte string (variable length) -|=== +* Puzzle modules do not take initiative to send REQ or SET commands. They only + respond to requests from the main controller. +* Puzzle modules can be distinguished from unrelated I^2^C peripherals using + the MAGIC command. +* Puzzle modules are I^2^C multi-master controllers that are slave-addressable + in master mode. +* The main controller is a puzzle module, but with the following differences: +** The main controller is allowed to initiate REQ and SET commands. +** The main controller's global state is an aggregation of all other puzzle + modules, and ignores STATE SET commands. -The messages described in Table 2 are (de)serialized using Google's protocol -buffer library. This choice was made after considering various alternative -options for sending structured messages cite:[research]. +These guidelines allow the following simplifications: -<> shows an example of how messages are -exchanged for the initialization of a puzzle module. +* Puzzle modules may assume they are always being addressed by the main + controller (this simplifies the message architecture). +* The puzzle bus may be shared with regular I^2^C peripherals without causing + issues. -<> shows an example exchange where the last puzzle -module (A) is solved while (B) is already solved. +==== Addresses -. First, module A sets it's own state to 'solved' and subsequently informs the - main controller of this change. -. As a result of this update notification, the main controller queries puzzle - module A for its new global state. -. Once the main controller has received and confirmed that all puzzle module - global states are set to 'solved', the main controller sets its own state to - 'solved', and broadcasts an update message to all puzzle modules. -. As a result of the update message from the main controller, module B requests - the main controller's new global state, and is able to verify that all puzzle - modules have been solved. +The RPI Pico SDK prohibits the use of I^2^C addresses reserved by the I^2^C +specification. This means different addresses from previous years are used. +These addresses are indexed in the code under a shared header (see +``lib/pbdrv/pb.h``). -In this example, module B could be the vault puzzle module, which displays a -code when the entire puzzle box is solved. +The same I^2^C address may be used by two different puzzle modules, but this +will make it impossible for them to be used simultaniously. -[[fig:sequence-puzzle-finish]] -.Puzzle box finish sequence diagram -image::img/sequence-puzzle-finish.svg[] +The I^2^C addresses are also used to determine the puzzle sequence (i.e. the +order in which puzzle modules are set to the 'playing' state). The sequence is +determined by the main controller on startup, and consists of the connected +puzzle modules' addresses in descending order (i.e. highest address first). -=== NeoTrellis Puzzle +=== NeoTrellis puzzle This subsection defines aspects of the 'NeoTrellis puzzle' module and gives a summary of how the puzzle is meant to be solved. This module will be created to @@ -462,7 +524,7 @@ diagram has been shown in <>. .NeoTrellis puzzle in-out image::img/neotrellis-io.png[] -=== Software Puzzle +=== Software puzzle This subsection defines aspects of the 'software puzzle' module and gives a summary of how the puzzle is meant to be solved. This module will be created to @@ -502,9 +564,9 @@ code. This is shown in <>. .Software puzzle in-out image::img/software-io.png[] -=== Hardware Puzzle +=== Hardware puzzle -==== Hardware Puzzle gameplay +==== Hardware puzzle gameplay The hardware puzzle has a logic gate puzzle engraved on the front plate of the puzzle box. To solve the puzzle, the user must set the toggle switches to the @@ -522,7 +584,7 @@ The inputs and outputs of this puzzle have been taken from the design document of the previous group which worked on this project (21-22). This input and output diagram has been shown in Figure ??. -=== Vault Puzzle +=== Vault puzzle ==== Vault puzzle gameplay @@ -539,35 +601,9 @@ clicked the vault resets and they need to start over from the beginning. .Vault puzzle in-out image::img/vault-io.png[] -=== Bomb device - -==== Bomb device connection - -The bomb connects to a WiFi-network using the 802.11x standard. The hub hosts -an interface that can be used to identify all the devices including the bomb -and also pair it to a puzzlebox. After that the game can be set-up and a given -countdown time and start time will be communicated to the bomb over a TCP -socket connection. The hub generates a code that will be send to both the -puzzlebox and bomb so that both devices know what would be or can be expected. - -The bomb can also use the WiFi connection to sync. the time. - -==== Device inputs & outputs - -[[fig:bomb-io]] -.Bomb device in-out -image::img/bomb-io.png[] - == Components [[sec:lv3-remote-control]] -=== Remote Control -==== Socket Server -==== Socket Commands -=== Neotrellis Puzzle -=== Game state diagrams, activity diagrams (if applicable) -=== Software Puzzle -=== Hardware Puzzle -=== Vault Puzzle +=== Remote control [appendix] == NeoTrellis puzzle example diff --git a/docs/handover.adoc b/docs/handover.adoc index 0e8af5a..6918256 100644 --- a/docs/handover.adoc +++ b/docs/handover.adoc @@ -109,7 +109,8 @@ Our project documentation was originally written in Microsoft Word, but we later transferred all documentation to AsciiDoc because of issues where OneDrive would roll back changes. If possible, use a documentation system or format that allows using an external version control system like Git to avoid -losing content. +losing content. This is also the reason why our documents may contain +formatting/style errors. === Misconceptions diff --git a/docs/img/.gitignore b/docs/img/.gitignore index afafe8d..529fbaa 100644 --- a/docs/img/.gitignore +++ b/docs/img/.gitignore @@ -1 +1,3 @@ software-components.svg +sequence-puzzle-module-init.svg +sequence-puzzle-finish.svg diff --git a/docs/img/sequence-puzzle-module-init.puml b/docs/img/sequence-puzzle-module-init.puml new file mode 100644 index 0000000..3d2fa56 --- /dev/null +++ b/docs/img/sequence-puzzle-module-init.puml @@ -0,0 +1,17 @@ +@startuml +!include style.ipuml + +participant "main controller" as main +participant "puzzle module" as mod + +activate main + +main -> mod : MAGIC REQ +mod -> main : MAGIC RES + +||| + +main -> mod ++: STATE REQ +mod -> main : STATE RES + +@enduml diff --git a/docs/img/sequence-puzzle-module-init.svg b/docs/img/sequence-puzzle-module-init.svg deleted file mode 100644 index 2e8db4f..0000000 --- a/docs/img/sequence-puzzle-module-init.svg +++ /dev/null @@ -1,3 +0,0 @@ - - -
Main
update
A
state := reset
state := reset
power on
update
 \ No newline at end of file diff --git a/docs/img/style.ipuml b/docs/img/style.ipuml index 25bb6d7..9ea5170 100644 --- a/docs/img/style.ipuml +++ b/docs/img/style.ipuml @@ -1,3 +1,4 @@ !theme plain skinparam RoundCorner 0 +hide footbox diff --git a/docs/makefile b/docs/makefile index 15ea3a4..d180398 100644 --- a/docs/makefile +++ b/docs/makefile @@ -24,4 +24,5 @@ ASCIIDOCTOR_ARGS += --backend pdf plantuml -tsvg $< design.pdf: img/software-components.svg +design.pdf: img/sequence-puzzle-module-init.svg diff --git a/lib/pbdrv/pb.h b/lib/pbdrv/pb.h index 0f2e9d1..e8037ae 100644 --- a/lib/pbdrv/pb.h +++ b/lib/pbdrv/pb.h @@ -1,23 +1,34 @@ #pragma once +//! I2C bus speed in hertz (100 KHz) #define PB_CLOCK_SPEED_HZ 100000 +//! I2C bus timeout delay in milliseconds #define PB_TIMEOUT_MS 10 +//! I2C bus timeout delay in microseconds #define PB_TIMEOUT_US (1e3 * PB_TIMEOUT_MS) -// Adafruit NeoTrellis modules +//! Adafruit NeoTrellis module 1 I2C address #define PB_ADDR_ADA_NEO_1 0x2E +//! Adafruit NeoTrellis module 2 I2C address #define PB_ADDR_ADA_NEO_2 0x2F +//! Adafruit NeoTrellis module 3 I2C address #define PB_ADDR_ADA_NEO_3 0x30 +//! Adafruit NeoTrellis module 4 I2C address #define PB_ADDR_ADA_NEO_4 0x32 -// Main controller +//! Main controller I2C address #define PB_ADDR_MOD_MAIN 0x08 -// Puzzle modules +//! NeoTrellis puzzle module I2C address #define PB_ADDR_MOD_NEOTRELLIS 0x21 +//! Software puzzle module I2C address #define PB_ADDR_MOD_SOFTWARE 0x22 +//! Hardware puzzle module I2C address #define PB_ADDR_MOD_HARDWARE 0x23 +//! Vault puzzle module I2C address #define PB_ADDR_MOD_VAULT 0x24 -// #define BUSADDR_MOD_AUTOMATION 0x25 +//! Automation puzzle module I2C address +#define BUSADDR_MOD_AUTOMATION 0x25 +//! Dummy puzzle module I2C address #define PB_ADDR_MOD_DUMMY 0x69 -- 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 'lib') 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 'lib') 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 'lib') 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 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 --- lib/pbdrv/drv/arduino/index.dox | 19 ++++++++++ lib/pbdrv/drv/arduino/mod.cpp | 20 ++++++----- lib/pbdrv/drv/index.dox | 32 +++++++++++++++++ lib/pbdrv/ext/freertos/index.dox | 6 ++++ lib/pbdrv/ext/freertos/pb-mem.c | 5 +++ lib/pbdrv/ext/freertos/pb-mod.c | 1 + lib/pbdrv/ext/index.dox | 24 +++++++++++++ lib/pbdrv/ext/stdlib/index.dox | 6 ++++ lib/pbdrv/ext/stdlib/pb-mem.c | 5 +++ lib/pbdrv/index.dox | 64 +++++++++++++++++++++++++-------- lib/pbdrv/pb-mod.h | 13 ++----- lib/pbdrv/pb-msg.h | 3 ++ lib/pbdrv/pb-serial.h | 76 ++++++++++++++++++++++++++++++++++------ main/pbdrv.h | 56 +++++++++++++++++------------ 14 files changed, 262 insertions(+), 68 deletions(-) create mode 100644 lib/pbdrv/drv/arduino/index.dox create mode 100644 lib/pbdrv/drv/index.dox create mode 100644 lib/pbdrv/ext/freertos/index.dox create mode 100644 lib/pbdrv/ext/index.dox create mode 100644 lib/pbdrv/ext/stdlib/index.dox (limited to 'lib') diff --git a/lib/pbdrv/drv/arduino/index.dox b/lib/pbdrv/drv/arduino/index.dox new file mode 100644 index 0000000..4c74222 --- /dev/null +++ b/lib/pbdrv/drv/arduino/index.dox @@ -0,0 +1,19 @@ +// vim:ft=doxygen +/** +\ingroup pb_drv +\defgroup pb_drv_arduino Arduino +\brief Arduino (Arduino-CMake-Toolchain) driver + +This driver is automatically enabled if the variable \c ARDUINO is defined in +your CMakeLists.txt (it is by default when using Arduino-CMake-Toolchain). + +\note This driver automatically includes the +\ref pb_ext_freertos "FreeRTOS extension" for deferring calls to \c +pb_i2c_recv() from the I2C ISR. + +This driver is known to work with the following MCUs: +- ATmega328P (Arduino Uno) +- ATmega2560 (Arduino Mega) + +*/ + diff --git a/lib/pbdrv/drv/arduino/mod.cpp b/lib/pbdrv/drv/arduino/mod.cpp index 9130334..2eef8d5 100644 --- a/lib/pbdrv/drv/arduino/mod.cpp +++ b/lib/pbdrv/drv/arduino/mod.cpp @@ -42,6 +42,7 @@ static void pb_setup() { Wire.onReceive(recv_event); } +/// \ingroup pb_drv_arduino __weak void pb_i2c_send(i2c_addr_t addr, const uint8_t * buf, size_t sz) { Wire.beginTransmission((int) addr); Wire.write(buf, sz); @@ -64,7 +65,16 @@ void loop_task() { } } -//! Application entrypoint +/** + * \ingroup pb_drv_arduino + * \brief Application entrypoint + * + * \note I should really be able to use Arduino's initVariant function for + * this, but I can't seem to get it to link properly using the CMake setup in + * this repository. Overriding the main() function seems to work, and the + * USBCON thing in the default Arduino main() function isn't needed because + * puzzle modules are likely not using USB. + */ int main(void) { init(); // call arduino internal setup setup(); // call regular arduino setup @@ -74,11 +84,3 @@ int main(void) { return 0; } -/** - * \note I should really be able to use Arduino's initVariant function for - * this, but I can't seem to get it to link properly using the CMake setup in - * this repository. Overriding the main() function seems to work, and the - * USBCON thing in the default Arduino main() function isn't needed because - * puzzle modules are likely not using USB. - */ - diff --git a/lib/pbdrv/drv/index.dox b/lib/pbdrv/drv/index.dox new file mode 100644 index 0000000..1fe09e2 --- /dev/null +++ b/lib/pbdrv/drv/index.dox @@ -0,0 +1,32 @@ +// vim:ft=doxygen +/** +\ingroup pbdrv-mod +\defgroup pb_drv Drivers +\brief Platform-specific \ref pbdrv-mod implementations + +Like \ref pb_ext "extensions", drivers provide platform-specific +implementations for various functions used in \ref pbdrv-mod. + +Drivers are automatically included based on your build configuration, and you +only need to ensure \c pbdrv-mod is linked with your final executable in order +to use one of the available drivers: + +```cmake +# include pbdrv +add_subdirectory(lib/pbdrv) + +# link pbdrv-mod +target_link_libraries(main pbdrv-mod) + +``` + +If there is no existing driver for your target, you may implement the following +in order to use \ref pbdrv-mod: + +- 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 + +*/ + diff --git a/lib/pbdrv/ext/freertos/index.dox b/lib/pbdrv/ext/freertos/index.dox new file mode 100644 index 0000000..dfa45ff --- /dev/null +++ b/lib/pbdrv/ext/freertos/index.dox @@ -0,0 +1,6 @@ +// vim:ft=doxygen +/** +\ingroup pb_ext +\defgroup pb_ext_freertos FreeRTOS +\brief FreeRTOS memory management and scheduler-based delay +*/ diff --git a/lib/pbdrv/ext/freertos/pb-mem.c b/lib/pbdrv/ext/freertos/pb-mem.c index b18d79f..6647f05 100644 --- a/lib/pbdrv/ext/freertos/pb-mem.c +++ b/lib/pbdrv/ext/freertos/pb-mem.c @@ -3,24 +3,29 @@ #include "../../pb-mem.h" #include "../../pb-types.h" +/// \ingroup pb_ext_freertos inline void * pb_malloc(size_t sz) { return pvPortMalloc(sz); } +/// \ingroup pb_ext_freertos inline void pb_free(void * ptr) { vPortFree(ptr); } +/// \ingroup pb_ext_freertos __weak inline void * pb_realloc(void * ptr, size_t sz) { return NULL; // shit out of luck (don't use mpack_writer_init_growable) } +/// \ingroup pb_ext_freertos __weak void * pb_memcpy(void * dest, const void * src, size_t sz) { for (size_t offset = 0; offset < sz; offset++) *((char*) dest + offset) = *((char*) src + offset); return dest; } +/// \ingroup pb_ext_freertos __weak int pb_memcmp(const void * a, const void * b, size_t sz) { for (size_t offset = 0; offset < sz; offset++) { int diff = *((char*) a + offset) - *((char*) b + offset); diff --git a/lib/pbdrv/ext/freertos/pb-mod.c b/lib/pbdrv/ext/freertos/pb-mod.c index 75495be..5c0aa36 100644 --- a/lib/pbdrv/ext/freertos/pb-mod.c +++ b/lib/pbdrv/ext/freertos/pb-mod.c @@ -3,6 +3,7 @@ #include "../../pb-types.h" +/// \ingroup pb_ext_freertos __weak void pb_mod_blocking_delay_ms(unsigned long ms) { vTaskDelay(ms / portTICK_PERIOD_MS); } diff --git a/lib/pbdrv/ext/index.dox b/lib/pbdrv/ext/index.dox new file mode 100644 index 0000000..f7d2bc6 --- /dev/null +++ b/lib/pbdrv/ext/index.dox @@ -0,0 +1,24 @@ +// vim:ft=doxygen +/** +\ingroup pbdrv +\ingroup pbdrv-mod +\defgroup pb_ext Extensions +\brief Platform-specific \ref pbdrv implementations + +Extensions provide platform-specific implementations for various functions used +in \ref pbdrv, and allows \ref pbdrv to remain completely portable. Extensions +are used in both \ref pbdrv and \ref pbdrv-mod. + +In order to use an extension, include the appropriate CMake lists file for your +target platform after the \ref pbdrv include: + +```cmake +# include pbdrv +add_subdirectory(lib/pbdrv) + +# use stdlib extension (for use with C standard library) +include(lib/pbdrv/ext/stdlib/include.cmake) + +``` + +*/ diff --git a/lib/pbdrv/ext/stdlib/index.dox b/lib/pbdrv/ext/stdlib/index.dox new file mode 100644 index 0000000..756af1e --- /dev/null +++ b/lib/pbdrv/ext/stdlib/index.dox @@ -0,0 +1,6 @@ +// vim:ft=doxygen +/** +\ingroup pb_ext +\defgroup pb_ext_stdlib stdlib +\brief C stdlib memory management +*/ diff --git a/lib/pbdrv/ext/stdlib/pb-mem.c b/lib/pbdrv/ext/stdlib/pb-mem.c index b260c2c..328efbb 100644 --- a/lib/pbdrv/ext/stdlib/pb-mem.c +++ b/lib/pbdrv/ext/stdlib/pb-mem.c @@ -3,22 +3,27 @@ #include "../../pb-mem.h" +/// \ingroup pb_ext_stdlib inline void * pb_malloc(size_t sz) { return malloc(sz); } +/// \ingroup pb_ext_stdlib inline void pb_free(void * ptr) { free(ptr); } +/// \ingroup pb_ext_stdlib inline void * pb_realloc(void * ptr, size_t sz) { return realloc(ptr, sz); } +/// \ingroup pb_ext_stdlib void * pb_memcpy(void * dest, const void * src, size_t sz) { return memcpy(dest, src, sz); } +/// \ingroup pb_ext_stdlib int pb_memcmp(const void * a, const void * b, size_t sz) { return memcmp(a, b, sz); } diff --git a/lib/pbdrv/index.dox b/lib/pbdrv/index.dox index e4a6c5f..eb0fd63 100644 --- a/lib/pbdrv/index.dox +++ b/lib/pbdrv/index.dox @@ -4,28 +4,62 @@ \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. +\ref pbdrv is a standalone portable static library for handling (i.e. +(de)serialization) of puzzle bus messages. \ref pbdrv is meant for use within +applications that handle puzzle bus messages, but are not puzzle modules +themselves. For a complete puzzle module driver, please see \ref pbdrv-mod. -\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. +If you order to use \ref pbdrv, you need to include this folder in your +CMakeLists.txt file, include the \ref pb_ext "extension" for your target +platform, and link the \c pbdrv library with your executable: + +```cmake +# include pbdrv +add_subdirectory(lib/pbdrv) + +# + +# link with executable +target_link_libraries(main pbdrv) +``` -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. +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. + +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. A notable +difference with \ref pbdrv-mod is that you do not need to include an extension. +\ref pb_ext "Extensions" are still used by \ref pbdrv-mod, but they are +included automatically by the target platform's \ref pb_drv "driver". The +appropriate \ref pb_drv "driver" to load is also automatically detected. + +Example: + +```cmake +# include pbdrv +add_subdirectory(lib/pbdrv) + +# link with executable +target_link_libraries(main pbdrv-mod) +``` + +\note In most cases, the \ref pb_hook "hooks" should be sufficient to realize +extensions or custom behavior not provided by \ref pbdrv-mod. + +\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. -\copydetails pbdrv +\see pbdrv \{ @@ -35,7 +69,7 @@ driver, or (partially) implementing the driver functions. 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. +pbdrv-mod. \} diff --git a/lib/pbdrv/pb-mod.h b/lib/pbdrv/pb-mod.h index 75fcbec..3869e55 100644 --- a/lib/pbdrv/pb-mod.h +++ b/lib/pbdrv/pb-mod.h @@ -39,20 +39,11 @@ void pb_mod_blocking_delay_ms(unsigned long ms); * \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) + * \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. @@ -67,7 +58,7 @@ void pb_mod_blocking_delay_ms(unsigned long ms); */ void pb_i2c_recv(const uint8_t * buf, size_t sz); /** - * \brief send a message in master-mode on the I2C bus (puzzle bus) + * \brief Send a message in master-mode on the I2C bus (puzzle bus) * * This function sends an I2C message to the address specified by \p i2c_addr. * diff --git a/lib/pbdrv/pb-msg.h b/lib/pbdrv/pb-msg.h index 33b697a..ff5bcde 100644 --- a/lib/pbdrv/pb-msg.h +++ b/lib/pbdrv/pb-msg.h @@ -46,6 +46,9 @@ pb_buf_t pb_msg_write(const pb_msg_t * msg); pb_msg_t * pb_msg_read(const pb_buf_t * buf); /** * \brief Recursively free fields of a \c pb_msg_t + * + * \note The \p msg pointer itself is also free'd by this function. You should + * set it to NULL afterwards to avoid confusion. */ void pb_msg_free(pb_msg_t * msg); diff --git a/lib/pbdrv/pb-serial.h b/lib/pbdrv/pb-serial.h index d3d0007..79f08d7 100644 --- a/lib/pbdrv/pb-serial.h +++ b/lib/pbdrv/pb-serial.h @@ -8,23 +8,77 @@ extern "C" { #endif -#define __pb_cmd(name) \ - pb_ser_r_t pb_ser_r_##name; \ - pb_ser_w_t pb_ser_w_##name; \ - pb_ser_free_t pb_ser_free_##name; +/** + * \ingroup pbdrv + * \ingroup pbdrv-mod + * \defgroup pb_ser Serial + * \internal + * \brief Internal (de)serialization functions using mpack + * + * \{ + */ +/** + * \brief Write (serialize) message fields using mpack + * + * \param writer Pointer to \c mpack_writer_t instance + * \param msg Pointer to message struct to read from + */ typedef void pb_ser_w_t(mpack_writer_t * writer, const pb_msg_t * msg); -pb_ser_w_t pb_ser_w; - +/** + * \brief Read (deserialize) message fields using mpack + * + * \param reader Pointer to \c mpack_reader_t instance + * \param msg Pointer to message struct to write to + */ typedef void pb_ser_r_t(mpack_reader_t * reader, pb_msg_t * msg); -pb_ser_r_t pb_ser_r; - +/** + * \brief Recursively free message struct fields + * + * \param msg Pointer to message struct to free + */ typedef void pb_ser_free_t(pb_msg_t * msg); + +/** + * \brief Write the \ref pb_msg_t header fields and call another function for + * \p msg->cmd. + * \see pb_ser_w_t + */ +pb_ser_w_t pb_ser_w; +/** + * \brief Read the \ref pb_msg_t header fields and call another function for \p + * msg->cmd. + * \see pb_ser_r_t + */ +pb_ser_r_t pb_ser_r; +/** + * \brief Call another function for \p msg->cmd. + * \see pb_ser_free_t + */ pb_ser_free_t pb_ser_free; -__pb_cmd(cmd_prop) -__pb_cmd(cmd_state) -__pb_cmd(cmd_magic) +//! Write the \ref pb_cmd_prop_t fields \see pb_ser_w_t +pb_ser_w_t pb_ser_w_cmd_prop; +//! Read the \ref pb_cmd_prop_t fields \see pb_ser_r_t +pb_ser_r_t pb_ser_r_cmd_prop; +//! Free the \ref pb_cmd_prop_t fields \see pb_ser_free_t +pb_ser_free_t pb_ser_free_cmd_prop; + +//! Write the \ref pb_cmd_state_t fields \see pb_ser_w_t +pb_ser_w_t pb_ser_w_cmd_state; +//! Read the \ref pb_cmd_state_t fields \see pb_ser_r_t +pb_ser_r_t pb_ser_r_cmd_state; +//! Free the \ref pb_cmd_state_t fields \see pb_ser_free_t +pb_ser_free_t pb_ser_free_cmd_state; + +//! Write the \ref pb_cmd_magic_t fields \see pb_ser_w_t +pb_ser_w_t pb_ser_w_cmd_magic; +//! Read the \ref pb_cmd_magic_t fields \see pb_ser_r_t +pb_ser_r_t pb_ser_r_cmd_magic; +//! Free the \ref pb_cmd_magic_t fields \see pb_ser_free_t +pb_ser_free_t pb_ser_free_cmd_magic; + +/// \} #ifdef __cplusplus } 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 5113ffd3b0b3c761681456fae5ed554c2b35cc8d Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Sat, 22 Jun 2024 13:44:06 +0200 Subject: add i2ctcp to doxygen --- lib/i2ctcp/i2ctcpv1.h | 64 ++++++++++++++++++++++++++++++++++++--------------- lib/i2ctcp/readme.md | 25 -------------------- 2 files changed, 45 insertions(+), 44 deletions(-) delete mode 100644 lib/i2ctcp/readme.md (limited to 'lib') diff --git a/lib/i2ctcp/i2ctcpv1.h b/lib/i2ctcp/i2ctcpv1.h index 799b668..d7bb29e 100644 --- a/lib/i2ctcp/i2ctcpv1.h +++ b/lib/i2ctcp/i2ctcpv1.h @@ -2,43 +2,69 @@ #include #include +#include #ifdef __cplusplus extern "C" { #endif -/** \brief I2C over TCP message (v1) */ -struct i2ctcp_msg { - uint16_t addr; //!< I^2^C address +/** + * \defgroup i2ctcp i2ctcp + * \brief I2C over TCP + * + * This library includes protocol (de)serialization functions for sending and + * receiving I2C messages over TCP. These functions are used by the \ref main + * "main controller" and the \ref pbc "puzzle box client (pbc)". This library + * does not include any puzzle bus specific code. + * + * mpack is used for the actual (de)serialization, and the functions in this + * library act as helpers for parsing from chunked data streams. + * + * To use these functions, include the following statement in your + * CMakeLists.txt: + * + * ```cmake + * # include pbdrv + * add_subdirectory(lib/i2ctcp) + * + * # link with executable + * target_link_libraries(main i2ctcp) + * ``` + * + * \{ + */ + +//! I2C over TCP message (v1) +typedef struct { + uint16_t addr; //!< I2C address char * data; //!< message content size_t length; //!< message size size_t _rdata; //!< \private remaining bytes to read until message is complete -}; -typedef struct i2ctcp_msg i2ctcp_msg_t; +} i2ctcp_msg_t; /** * \brief Read chunk of input stream, and store resulting message in \p target * * This function is called for each chunk of data from an input stream, and * will parse the next puzzle bus message into \p target. The input stream is - * assumed to only contain messages encoded by \p i2ctcp_write() + * assumed to only contain messages encoded by \c i2ctcp_write() * - * \param target pointer to struct that will contain the finished message data - * \param buf pointer to input stream data chunk - * \param buf_sz size of \p buf + * \param target Pointer to struct that will contain the finished message data + * \param buf Pointer to input stream data chunk + * \param buf_sz Size of \p buf * * \returns Integer representing amount of bytes required to finish message, or * -1 if the message header could not be read. If this function returns 0, the * message in \p target is complete. * - * \note target->data will automatically be allocated by this function, even if - * the message is not fully parsed. This variable must be `free()`d by the + * \note \p target->data will automatically be allocated by this function, even + * if the message is not fully parsed. This variable must be free'd by the * caller after each complete message to prevent memory leaks. */ int i2ctcp_read(i2ctcp_msg_t * target, const char * buf, size_t buf_sz); /** - * \brief reset the remaining message data counter + * \brief Reset the remaining message data counter * * Calling this function has the effect of forcing \c i2ctcp_read() to parse * the next buffer chunk as the start of a new message. This function may be @@ -52,16 +78,16 @@ void i2ctcp_read_reset(i2ctcp_msg_t * target); * * This function allocates a buffer large enough to fit the message specified * in \p target, and encodes the data in \p target in a format that can be - * decoded later using \p i2ctcp_read() + * decoded later using \c i2ctcp_read(). * - * \param target pointer to struct that contains the message data - * \param buf pointer to \c char* that will contain the formatted message - * \param buf_sz pointer to \c size_t that will represent the final size of \p buf + * \param target Pointer to struct that contains the message data + * \param buf Pointer to \c char* that will contain the formatted message + * \param buf_sz Pointer to \c size_t that will represent the final size of \p buf * - * \returns boolean true if a the message could be encoded successfully, false - * if there was some kind of error + * \returns Boolean \c true if a the message could be encoded successfully, \c + * false if there was some kind of error * - * \note the pointer stored in \p buf must be `free()`d by the caller afterwards + * \note The pointer stored in \p buf must be free'd by the caller afterwards */ bool i2ctcp_write(const i2ctcp_msg_t * target, char ** buf, size_t * buf_sz); diff --git a/lib/i2ctcp/readme.md b/lib/i2ctcp/readme.md deleted file mode 100644 index d5bfe6d..0000000 --- a/lib/i2ctcp/readme.md +++ /dev/null @@ -1,25 +0,0 @@ -# i2ctcp (I2C over TCP) - -This folder includes protocol (de)serialization functions for sending and -receiving I2C messages over TCP. These functions are used by the -[main controller](../main) and the [puzzle box client (pbc)](../client). This -folder does not include any puzzle bus specific code, and the headers for -puzbus are in the [shared](../shared) folder instead. - -[MessagePack][msgpack] (specifically the [mpack][mpack] implementation) is used -for the actual serialization/deserializtion, and the functions in this folder -act as helpers for parsing from chunked data streams. - -To use these functions, include the following statement in your CMakeLists.txt: -```cmake -include(../i2ctcp/include.cmake) -``` - -The functions are available by `#include`ing the `i2ctcpv1.h` header, and are -extensively documented using Doxygen-style comments. - -[msgpack]: https://msgpack.org/ -[mpack]: https://github.com/ludocode/mpack/ - - - -- 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 'lib') 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 9c255363bb578ada6bb53d15e5ca12fa8b39986b Mon Sep 17 00:00:00 2001 From: Elwin Date: Sat, 22 Jun 2024 17:40:40 +0200 Subject: Freertos support --- .gitmodules | 2 +- lib/Arduino-CMake-Toolchain | 2 +- puzzle/vault/CMakeLists.txt | 49 ++++++ puzzle/vault/FreeRTOSConfig.h | 52 +++++++ .../arduino-vaultpuzzle/arduino-vaultpuzzle.ino | 150 ------------------- puzzle/vault/console-vaultpuzzle/vault.cpp | 130 ---------------- puzzle/vault/lib | 1 + puzzle/vault/main.cpp | 165 +++++++++++++++++++++ puzzle/vault/makefile | 20 +++ puzzle/vault/mod.c | 6 + 10 files changed, 295 insertions(+), 282 deletions(-) create mode 100644 puzzle/vault/CMakeLists.txt create mode 100644 puzzle/vault/FreeRTOSConfig.h delete mode 100644 puzzle/vault/arduino-vaultpuzzle/arduino-vaultpuzzle.ino delete mode 100644 puzzle/vault/console-vaultpuzzle/vault.cpp create mode 120000 puzzle/vault/lib create mode 100644 puzzle/vault/main.cpp create mode 100644 puzzle/vault/makefile create mode 100644 puzzle/vault/mod.c (limited to 'lib') diff --git a/.gitmodules b/.gitmodules index 9ff7e96..37a53dd 100644 --- a/.gitmodules +++ b/.gitmodules @@ -21,6 +21,6 @@ [submodule "lib/Arduino-CMake-Toolchain"] path = lib/Arduino-CMake-Toolchain url = https://github.com/a9183756-gh/Arduino-CMake-Toolchain - branch = e745a9bed3c3fb83442d55bf05630f31574674f2 + branch = release-1.1-dev shallow = true diff --git a/lib/Arduino-CMake-Toolchain b/lib/Arduino-CMake-Toolchain index e745a9b..953b2e6 160000 --- a/lib/Arduino-CMake-Toolchain +++ b/lib/Arduino-CMake-Toolchain @@ -1 +1 @@ -Subproject commit e745a9bed3c3fb83442d55bf05630f31574674f2 +Subproject commit 953b2e63ddf434868bfba60244fb714262fce5f4 diff --git a/puzzle/vault/CMakeLists.txt b/puzzle/vault/CMakeLists.txt new file mode 100644 index 0000000..b0f05f2 --- /dev/null +++ b/puzzle/vault/CMakeLists.txt @@ -0,0 +1,49 @@ +cmake_minimum_required(VERSION 3.29) + +set(CMAKE_C_STANDARD 11) +set(CMAKE_CXX_STANDARD 17) +set(CMAKE_EXPORT_COMPILE_COMMANDS 1) + +# enable debug features +set(CMAKE_BUILD_TYPE Debug) +add_compile_definitions(DEBUG) +# add_compile_options(-O0) # no optimizations + +# arduino +set(CMAKE_TOOLCHAIN_FILE ${CMAKE_SOURCE_DIR}/lib/Arduino-CMake-Toolchain/Arduino-toolchain.cmake) +# set(ARDUINO_BOARD "Arduino Uno [avr.uno]") +set(ARDUINO_BOARD "Arduino Mega or Mega 2560 [avr.mega]") + +# freertos +add_library(freertos_config INTERFACE) +target_include_directories(freertos_config SYSTEM INTERFACE .) +# set(FREERTOS_PORT GCC_ATMEGA) # Arduino Uno +set(FREERTOS_PORT GCC_ATMEGA) # Arduino Uno +set(FREERTOS_HEAP 4) + +# used for testing +# set(ARDUINO_BOARD "Raspberry Pi Pico W [rp2040.rpipicow]") +# add_compile_definitions(USE_TINYUSB) +# include_directories(/home/loek/.arduino15/packages/rp2040/hardware/rp2040/3.9.2/libraries/Adafruit_TinyUSB_Arduino/src/arduino) + +project(pb_mod_dummy C CXX) + +add_subdirectory(lib/pbdrv) +add_subdirectory(lib/FreeRTOS-Kernel) + +add_executable(main + main.cpp + mod.c + ) + +target_link_libraries(main PUBLIC + pbdrv-mod + ) +target_link_arduino_libraries(main PUBLIC + core + Wire + TM1637 + ) + +target_enable_arduino_upload(main) + diff --git a/puzzle/vault/FreeRTOSConfig.h b/puzzle/vault/FreeRTOSConfig.h new file mode 100644 index 0000000..c0acc49 --- /dev/null +++ b/puzzle/vault/FreeRTOSConfig.h @@ -0,0 +1,52 @@ +#pragma once + +#define configUSE_PREEMPTION 1 +#define configUSE_IDLE_HOOK 0 +#define configUSE_TICK_HOOK 0 +#define configMAX_PRIORITIES 32 +#define configMINIMAL_STACK_SIZE ((configSTACK_DEPTH_TYPE) 192) +#define configUSE_16_BIT_TICKS 1 +#define configIDLE_SHOULD_YIELD 1 +#define configUSE_MUTEXES 1 +#define configUSE_RECURSIVE_MUTEXES 1 +#define configUSE_APPLICATION_TASK_TAG 0 +#define configUSE_COUNTING_SEMAPHORES 1 +#define configQUEUE_REGISTRY_SIZE 8 +#define configUSE_QUEUE_SETS 0 +#define configUSE_TIME_SLICING 1 +#define configSTACK_DEPTH_TYPE uint16_t +#define configSUPPORT_STATIC_ALLOCATION 0 +#define configSUPPORT_DYNAMIC_ALLOCATION 1 +// #define configTOTAL_HEAP_SIZE (1024) +#define configTOTAL_HEAP_SIZE (5 * 1024) +#define configCHECK_FOR_STACK_OVERFLOW 0 +#define configUSE_MALLOC_FAILED_HOOK 0 +#define configUSE_DAEMON_TASK_STARTUP_HOOK 0 +#define configGENERATE_RUN_TIME_STATS 0 +#define configUSE_TRACE_FACILITY 0 +#define configUSE_STATS_FORMATTING_FUNCTIONS 0 +#define configUSE_TIMERS 1 +#define configTIMER_TASK_PRIORITY (configMAX_PRIORITIES - 1) +#define configTIMER_QUEUE_LENGTH 10 +#define configTIMER_TASK_STACK_DEPTH 92 + +#include +#define configASSERT(x) assert(x) + +#define INCLUDE_vTaskPrioritySet 1 +#define INCLUDE_uxTaskPriorityGet 1 +#define INCLUDE_vTaskDelete 1 +#define INCLUDE_vTaskSuspend 1 +#define INCLUDE_vTaskDelayUntil 1 +#define INCLUDE_vTaskDelay 1 +#define INCLUDE_xTaskGetSchedulerState 1 +#define INCLUDE_xTaskGetCurrentTaskHandle 1 +#define INCLUDE_uxTaskGetStackHighWaterMark 1 +#define INCLUDE_xTaskGetIdleTaskHandle 1 +#define INCLUDE_eTaskGetState 1 +#define INCLUDE_xTimerPendFunctionCall 1 +#define INCLUDE_xTaskAbortDelay 1 +#define INCLUDE_xTaskGetHandle 1 +#define INCLUDE_xTaskResumeFromISR 1 +#define INCLUDE_xQueueGetMutexHolder 1 + diff --git a/puzzle/vault/arduino-vaultpuzzle/arduino-vaultpuzzle.ino b/puzzle/vault/arduino-vaultpuzzle/arduino-vaultpuzzle.ino deleted file mode 100644 index 4dd8ac8..0000000 --- a/puzzle/vault/arduino-vaultpuzzle/arduino-vaultpuzzle.ino +++ /dev/null @@ -1,150 +0,0 @@ -#include -#include - -// Definitions for GPIO numbers, change these according to your hardware setup -#define TOTAL_LEVELS 5 -#define TAG "VaultPuzzle" - -// Key Matrix Pin Configuration -#define ROWS 4 -#define COLS 3 - -// Module connection pins (Digital Pins for TM1637) -#define CLK 2 -#define DIO 3 - -// Pin to indicate puzzle solved state -#define SOLVED_PIN 53 - -// Initialize the TM1637 display -TM1637Display display(CLK, DIO); - -//TODO Update these pin numbers based on your Arduino setup -const int ROW_PINS[ROWS] = {7, 6, 5, 4}; -const int COL_PINS[COLS] = {10, 9, 8}; - -typedef enum { - STATE_UNINITIALIZED = 0x00, - STATE_RESET = 0x01, - STATE_PLAYING = 0x02, - STATE_SOLVED = 0x03, - STATE_ERROR = 0x04 -} PuzzleState; - -const char* validButtons[TOTAL_LEVELS] = {"A2", "B1", "D3", "C2", "C1"}; -PuzzleState puzzleState = STATE_UNINITIALIZED; -int currentLevel = 0; - -// Function prototypes -void display_code(int level); -void initialize_system(); -void check_button_press(); -void update_state_after_button_press(bool validPress); -void play_error_sound(); -void blink_display(); - -void setup() { - Serial.begin(115200); // Initialize default Serial for debug messages - pinMode(SOLVED_PIN, OUTPUT); // Initialize the solved indicator pin - digitalWrite(SOLVED_PIN, LOW); // Start with the solved pin LOW - - display.setBrightness(0x0f); // Set the brightness of the TM1637 display - initialize_system(); - Serial.println("GPIO and display initialized."); - - // Test to light up all segments - uint8_t allOn[] = {0xFF, 0xFF, 0xFF, 0xFF}; // All segments on - display.setSegments(allOn); - delay(2000); // Keep it on for 2 seconds before proceeding - - // Initialize the game - if (true) { // Simulating isVaultClosed - puzzleState = STATE_RESET; - currentLevel = 0; - display_code(currentLevel); - } else { - Serial.println("Vault door is open. Please close the door to start the puzzle."); - } -} - -void initialize_system() { - // Configure the rows as input with pull-up - for (int i = 0; i < ROWS; i++) { - pinMode(ROW_PINS[i], INPUT_PULLUP); - } - - // Configure the columns as output - for (int i = 0; i < COLS; i++) { - pinMode(COL_PINS[i], OUTPUT); - digitalWrite(COL_PINS[i], HIGH); - } -} - -void loop() { - while (puzzleState != STATE_SOLVED) { - check_button_press(); - delay(100); // Non-blocking delay - } - // When puzzle is solved, you might want to display a final message and set the solved pin high - if (puzzleState == STATE_SOLVED) { - digitalWrite(SOLVED_PIN, HIGH); // Set the solved pin high - display.showNumberDec(currentLevel, true); // Show final level or a special message - Serial.println("Final display shown. Puzzle complete."); - while (1) { delay(1000); } // Hold on the final display - } -} - -void display_code(int level) { - Serial.print("Displaying code for level "); Serial.println(level); - // Display the level on the TM1637 4-digit 7-segment display - display.showNumberDec(level, true); // True to show leading zeros - Serial.print("Code for level "); Serial.print(level); Serial.println(" displayed successfully."); -} - -void check_button_press() { - char keyPress[3] = {0}; - for (int col = 0; col < COLS; col++) { - digitalWrite(COL_PINS[col], LOW); // Activate column - for (int row = 0; row < ROWS; row++) { - if (digitalRead(ROW_PINS[row]) == LOW) { // Detect if any row is activated - delay(50); // Debounce delay - if (digitalRead(ROW_PINS[row]) == LOW) { // Confirm the button is still pressed - keyPress[0] = 'A' + row; - keyPress[1] = '1' + col; - keyPress[2] = '\0'; - Serial.print("Keypress detected: "); Serial.println(keyPress); - if (strcmp(keyPress, validButtons[currentLevel]) == 0) { - currentLevel++; - if (currentLevel >= TOTAL_LEVELS) { - puzzleState = STATE_SOLVED; - Serial.println("Puzzle solved!"); - display.showNumberDec(currentLevel + 1, true); // Display the final level - digitalWrite(SOLVED_PIN, HIGH); // Set the solved pin high - } else { - puzzleState = STATE_PLAYING; - display_code(currentLevel); - } - } else { - play_error_sound(); - blink_display(); - puzzleState = STATE_ERROR; - currentLevel = 0; - display_code(currentLevel); - } - while (digitalRead(ROW_PINS[row]) == LOW) {} // Wait for release - } - } - } - digitalWrite(COL_PINS[col], HIGH); // Deactivate column - } -} - -void play_error_sound() { - // Simulate error sound - connect a buzzer to play actual sound - Serial.println("Playing error sound."); -} - -void blink_display() { - // Simulate blinking the display - use LEDs or other methods to show visual feedback - Serial.println("7-segment display is blinking to indicate an error."); -} diff --git a/puzzle/vault/console-vaultpuzzle/vault.cpp b/puzzle/vault/console-vaultpuzzle/vault.cpp deleted file mode 100644 index 3566b3e..0000000 --- a/puzzle/vault/console-vaultpuzzle/vault.cpp +++ /dev/null @@ -1,130 +0,0 @@ -#include -#include -#include - -// Definitions for puzzle requirements -constexpr int TOTAL_LEVELS = 5; - -// Enumeration for the states of the puzzle -enum PuzzleState { - STATE_UNINITIALIZED, - STATE_RESET, - STATE_PLAYING, - STATE_SOLVED, - STATE_ERROR -}; - -// This array maps each level to the correct button press -const std::array validButtons = {"A3", "F1", "U4", "C2", "L1"}; - -PuzzleState puzzleState = STATE_UNINITIALIZED; -int currentLevel = 0; - -// Function prototypes -void displayCode(int level); -void sendI2CUpdate(PuzzleState state); - -// Simulate sending an I2C update -void sendI2CUpdate(PuzzleState state) { - std::cout << "Sending state " << state << " to main controller via I2C.\n"; -} - -// Simulate checking if the vault door is closed -bool isVaultClosed() { - return true; // Return true if the door sensor indicates closed -} - -// Function to display a code on the 7-segment display -void displayCode(int level) { - std::cout << "Displaying code for level " << level << " on the 7-segment display.\n"; -} - -// Function to initialize the puzzle -void initializePuzzle() { - if (isVaultClosed()) { - puzzleState = STATE_RESET; - currentLevel = 1; // Start at level 1 - std::cout << "Puzzle initialized. Starting at level " << currentLevel << ".\n"; - displayCode(currentLevel); // Show the first code - } else { - std::cout << "Vault door is open. Please close the door to start the puzzle.\n"; - } -} - -// Function to lock the vault -void lockVault() { - std::cout << "Vault locked.\n"; -} - -// Function to unlock the vault -void unlockVault() { - std::cout << "Vault unlocked!\n"; -} - -// Function to simulate the buzzer sound -void playErrorSound() { - std::cout << "Playing error sound.\n"; -} - -// Function to simulate blinking the 7-segment display -void blinkDisplay() { - std::cout << "7-segment display is blinking to indicate an error.\n"; -} - -// Validate the button press for the current level -bool isValidButtonPress(const std::string& button, int level) { - return button == validButtons[level - 1]; -} - -// Function to update the state of the puzzle based on the current level -void updateStateAfterButtonPress(bool validPress) { - if (validPress) { - if (currentLevel >= TOTAL_LEVELS) { - puzzleState = STATE_SOLVED; - unlockVault(); - } else { - puzzleState = STATE_PLAYING; - displayCode(currentLevel); - } - } else { - puzzleState = STATE_ERROR; - playErrorSound(); - blinkDisplay(); - lockVault(); - currentLevel = 1; // Reset to level 1 - displayCode(currentLevel); - } - sendI2CUpdate(puzzleState); // Notify main controller of the state change -} - -int main() { - initializePuzzle(); - - std::string buttonInput; - - while (puzzleState != STATE_SOLVED) { - std::cout << "Enter the button pressed for level " << currentLevel << " (format Xn, e.g., A3): "; - std::getline(std::cin, buttonInput); - - if (!buttonInput.empty() && isValidButtonPress(buttonInput, currentLevel)) { - currentLevel++; - if (currentLevel > TOTAL_LEVELS) { - puzzleState = STATE_SOLVED; - unlockVault(); - std::cout << "The puzzle is solved and the vault is open!\n"; - } else { - displayCode(currentLevel); - } - } else { - playErrorSound(); - blinkDisplay(); - lockVault(); - puzzleState = STATE_RESET; - currentLevel = 1; - displayCode(currentLevel); - } - sendI2CUpdate(puzzleState); - } - - return 0; -} diff --git a/puzzle/vault/lib b/puzzle/vault/lib new file mode 120000 index 0000000..58677dd --- /dev/null +++ b/puzzle/vault/lib @@ -0,0 +1 @@ +../../lib \ No newline at end of file diff --git a/puzzle/vault/main.cpp b/puzzle/vault/main.cpp new file mode 100644 index 0000000..76e5f65 --- /dev/null +++ b/puzzle/vault/main.cpp @@ -0,0 +1,165 @@ +#include +#include +#include + +#define TOTAL_LEVELS 5 +#define ROWS 4 +#define COLS 3 +#define CLK 2 +#define DIO 3 +#define SOLVED_PIN 53 +#define I2C_MODULE_ADDRESS 0x08 // Address of the puzzle module +#define HANDSHAKE_RECEIVED {0x70, 0x75, 0x7a, 0x62, 0x75, 0x73} // Magic command for the handshake +#define HANDSHAKE_SEND {0x67, 0x61, 0x6d, 0x69, 0x6e, 0x67} // Magic command for the handshake +#define REQUEST_STATE_CMD 0x53 // 'S' to request the game state + +const int ROW_PINS[ROWS] = {7, 6, 5, 4}; +const int COL_PINS[COLS] = {10, 9, 8}; +const char* validButtons[TOTAL_LEVELS] = {"A2", "B1", "D3", "C2", "C3"}; +const char bombCode[] = "1234"; + +TM1637Display display(CLK, DIO); + +typedef enum { + STATE_UNINITIALIZED = 0x00, + STATE_RESET = 0x01, + STATE_PLAYING = 0x02, + STATE_SOLVED = 0x03, + STATE_ERROR = 0x04 +} PuzzleState; + +PuzzleState puzzleState = STATE_UNINITIALIZED; +int currentLevel = 0; + +void requestEvent() { + if (puzzleState == STATE_PLAYING) { + uint8_t responseData[] = HANDSHAKE_SEND; + Wire.write(responseData, sizeof(responseData)); + Serial.println("Handshake response sent."); + } +} + +void blink_display(char num) { + while(puzzleState == STATE_UNINITIALIZED || puzzleState == STATE_ERROR) { + display.showNumberDecEx(0, 0b11111111, true); // Display "0000" with all digits on + delay(500); + display.clear(); + delay(500); + } +} + +void display_final_code(const char* code) { + uint8_t segs[4] = {0, 0, 0, 0}; + int numDigits = strlen(code); + numDigits = numDigits > 4 ? 4 : numDigits; + + for (int i = 0; i < numDigits; i++) { + segs[i] = display.encodeDigit(code[i] - '0'); + } + + display.setSegments(segs, numDigits, 0); +} + +void check_button_press() { + for (int col = 0; col < COLS; col++) { + digitalWrite(COL_PINS[col], LOW); + for (int row = 0; row < ROWS; row++) { + if (digitalRead(ROW_PINS[row]) == LOW) { + delay(50); + if (digitalRead(ROW_PINS[row]) == LOW) { + char keyPress[3] = {'A' + row, '1' + col, '\0'}; + Serial.print("Keypress detected: "); + Serial.println(keyPress); + if (strcmp(keyPress, validButtons[currentLevel]) == 0) { + currentLevel++; + if (currentLevel >= TOTAL_LEVELS) { + puzzleState = STATE_SOLVED; + Serial.println("Puzzle solved!"); + display.showNumberDec(currentLevel + 1, true); + digitalWrite(SOLVED_PIN, HIGH); + } else { + puzzleState = STATE_PLAYING; + } + } else { + currentLevel = 0; + } + while (digitalRead(ROW_PINS[row]) == LOW) {} // Ensure button release + } + } + } + digitalWrite(COL_PINS[col], HIGH); + } +} + +void initialize_system() { + for (int i = 0; i < ROWS; i++) { + pinMode(ROW_PINS[i], INPUT_PULLUP); + } + for (int i = 0; i < COLS; i++) { + pinMode(COL_PINS[i], OUTPUT); + digitalWrite(COL_PINS[i], HIGH); + } + Serial.println("GPIO and display initialized."); +} + +void receiveEvent(int howMany) { + if (howMany == 6) { + uint8_t expectedBytes[] = HANDSHAKE_RECEIVED; + uint8_t receivedBytes[6]; + bool match = true; + + for (int i = 0; i < 6; i++) { + receivedBytes[i] = Wire.read(); + if (receivedBytes[i] != expectedBytes[i]) { + match = false; + break; + } + } + + if (match) { + Serial.println("Correct handshake data received."); + puzzleState = STATE_PLAYING; + initialize_system(); + } else { + Serial.println("Incorrect handshake data received."); + puzzleState = STATE_ERROR; + } + } else { + Serial.print("Received wrong number of bytes: "); + Serial.println(howMany); + puzzleState = STATE_ERROR; + } +} + + +void setup() { + Serial.begin(115200); + pinMode(SOLVED_PIN, OUTPUT); + digitalWrite(SOLVED_PIN, LOW); + display.setBrightness(0x0f); + + Wire.begin(I2C_MODULE_ADDRESS); + Wire.onRequest(requestEvent); + Wire.onReceive(receiveEvent); + + // Initialize display with blinking zeros to indicate no connection or initialization state + blink_display('0'); +} + +void loop() { + switch(puzzleState) { + case STATE_PLAYING: + check_button_press(); + delay(100); + break; + case STATE_SOLVED: + display_final_code(bombCode); + digitalWrite(SOLVED_PIN, HIGH); + Serial.println("Final display shown. Puzzle complete."); + break; + case STATE_ERROR: + case STATE_UNINITIALIZED: + blink_display('0'); + break; + } +} \ No newline at end of file diff --git a/puzzle/vault/makefile b/puzzle/vault/makefile new file mode 100644 index 0000000..509d8e3 --- /dev/null +++ b/puzzle/vault/makefile @@ -0,0 +1,20 @@ +TARGET = $(BUILD_DIR)/main.elf + +include ../../lazy.mk + +export SERIAL_PORT ?= /dev/ttyACM0 +flash: upload-main; +upload-main: $(TARGET) + +test: test_a test_b; + +test_a: + $(MAKE) -C . clean + $(MAKE) -E CMFLAGS+=-D\ CMAKE_CXX_FLAGS=-DTEST_A -C . + $(MAKE) -E SERIAL_PORT=/dev/ttyACM0 -C . flash + +test_b: + $(MAKE) -C . clean + $(MAKE) -E CMFLAGS+=-D\ CMAKE_CXX_FLAGS=-DTEST_B -C . + $(MAKE) -E SERIAL_PORT=/dev/ttyACM1 -C . flash + diff --git a/puzzle/vault/mod.c b/puzzle/vault/mod.c new file mode 100644 index 0000000..058a585 --- /dev/null +++ b/puzzle/vault/mod.c @@ -0,0 +1,6 @@ +#include "pb.h" +#include "pb-mod.h" + +const char * PB_MOD_NAME = "dummy"; +const i2c_addr_t PB_MOD_ADDR = PB_ADDR_MOD_DUMMY; + -- cgit v1.2.3