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 --- .gitignore | 1 + Doxyfile | 21 +++++++++++++++++++++ docs/handover.adoc | 47 ++++++++++++++++++++++++++++++----------------- lib/pbdrv/pb-mod.h | 36 ++++++++++++++++++++++++++++++++++-- makefile | 5 +++++ 5 files changed, 91 insertions(+), 19 deletions(-) create mode 100644 Doxyfile create mode 100644 makefile diff --git a/.gitignore b/.gitignore index 19dc4f4..6064624 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ build .vscode/** .cache +doxygen diff --git a/Doxyfile b/Doxyfile new file mode 100644 index 0000000..c3623cc --- /dev/null +++ b/Doxyfile @@ -0,0 +1,21 @@ +# Doxyfile 1.11.0 +DOXYFILE_ENCODING = UTF-8 +PROJECT_NAME = "puzzlebox" +OUTPUT_DIRECTORY = doxygen + +INPUT += client +INPUT += lib/mpack +INPUT += lib/i2ctcp +INPUT += lib/pbdrv +INPUT += main +INPUT += puzzle/dummy + +EXCLUDE = lib/mpack/src +EXCLUDE_PATTERNS = **/build +EXCLUDE_SYMLINKS = YES + +FILE_PATTERNS = *.c *.cpp *.h *.hpp *.md +RECURSIVE = YES + +GENERATE_LATEX = NO + diff --git a/docs/handover.adoc b/docs/handover.adoc index 7bc52b3..c948b7b 100644 --- a/docs/handover.adoc +++ b/docs/handover.adoc @@ -120,11 +120,14 @@ which connects with the main controller to monitor/edit the game state. And the software for the puzzle modules 'Vault' and 'Neotrellis' is in the prototype state. == Incidents -There were a multitude of different challenges we had to face before getting to a -working product. The majority of these have been documented here, and it is highly -recommended to have a look at this before development. + +During this year's run of the project, we encountered several difficuties we +feel need to be addressed. We recommend that these incidents are analyzed by +future project groups and incorporated into the risk analysis section of future +project plan documents. === Misconceptions + Make sure to know what you are developing and do some research beforehand, to make sure you have the complete picture about what you are using. Sounds stupid, but it happened for multiple project attempts, and caused time loss. This also includes @@ -133,6 +136,7 @@ and verify it on the lowest possible level for the same reason as previously mentioned. === I^2^C + I^2^C is easy to implement but also easy to underestimate, this project requires a multi-master structure as communication is otherwise too complicated compared to other means of communication. @@ -149,24 +153,24 @@ been implemented to be able to continue using the RPI Pico W. To simplify; a controller is needed which supports multi-master while being able to be addressed as a slave. -=== Available Hardware/SDKs -When choosing or using specific chips/SDKs make sure it is available for (at least) -a few years. This makes it easier for the next project team to use the same chips/SDKs -instead of having to find new ones. This also includes having enough development boards -for multiple people to program using the same setup, e.g. the RPI Pico W requires -another RPI Pico W to be debugged. Effectively requiring the project team to have at -least 4 RPI Pico Ws to be able to develop in the same environment (if there are 2 -software students). +=== Development hardware availability -=== Arduino -Allocating memory using 'realloc' on Arduino is not possible, which makes it impossible -to use the 'mpack_writer_init_growable'. +When choosing or using specific chips or development boards, make sure to +include research on the product lifecycle. Choosing boards/chips that have +planned long term support makes it easier for the next project team to order +and use the same chips/boards instead of having to find new ones. -=== Garbage workarounds +This also includes having enough development boards for multiple people to +program using the same setup, e.g. the RPI Pico W requires another RPI Pico W +to be debugged, effectively requiring the project team to have at least 4 RPI +Pico Ws to be able to develop in the same environment (if there are 2 software +students). + +=== Auxiliary workarounds and technical limitations This section details unelegant workarounds that should be removed from the -code. All workarounds are marked with ``FIXME:`` comments referring to one of -the workarounds mentioned in this section. +code. Workarounds that should be removed are marked with ``FIXME:`` comments +referring to one of the workarounds mentioned in this section. RP2040 I^2^C limitations:: - All puzzle module drivers have a hard-coded 2 second delay between receiving @@ -174,6 +178,15 @@ RP2040 I^2^C limitations:: was done to ensure responses are not ignored by the RP2040 (main controller) while it is still in I^2^C master mode. +Memory management on Arduino:: +The Arduino's built-in memory management functions do not seem to work +properly. The FreeRTOS heap 4 memory management functions are used on the +puzzle modules instead. FreeRTOS does not have an implementation of the +``realloc()`` function. +- mpack's writer API cannot be used with a writer initialized using the + ``mpack_writer_init_growable`` function on Arduino-based puzzle modules. The + ``mpack_writer_init`` function is used with a static size buffer instead. + == Recommendations === Imperatives 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); /** diff --git a/makefile b/makefile new file mode 100644 index 0000000..5f5340b --- /dev/null +++ b/makefile @@ -0,0 +1,5 @@ +all: doxygen + +doxygen: Doxyfile + doxygen + -- cgit v1.2.3 From 35db69be891919ecb2a5a3eb13c5cc166aca9d6b Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Thu, 20 Jun 2024 14:34:16 +0200 Subject: WIP handover edits --- docs/.gitignore | 1 + docs/figs.drawio | 58 ++++++------ docs/handover.adoc | 253 ++++++++++++++++++++++++++++------------------------- 3 files changed, 164 insertions(+), 148 deletions(-) diff --git a/docs/.gitignore b/docs/.gitignore index a2f45c2..da49ef2 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,5 +1,6 @@ *.pdf res +.$*.bkp # i know this is bad Gemfile.lock diff --git a/docs/figs.drawio b/docs/figs.drawio index a40503b..042ce15 100644 --- a/docs/figs.drawio +++ b/docs/figs.drawio @@ -1,4 +1,4 @@ - + @@ -213,11 +213,11 @@ - + - + @@ -228,7 +228,7 @@ - + @@ -239,7 +239,7 @@ - + @@ -250,7 +250,7 @@ - + @@ -261,7 +261,7 @@ - + @@ -272,7 +272,7 @@ - + @@ -283,19 +283,19 @@ - + - + - - + + @@ -311,10 +311,10 @@ - + - + @@ -325,10 +325,10 @@ - + - + @@ -342,18 +342,18 @@ - + - + - + @@ -362,7 +362,7 @@ - + @@ -376,11 +376,11 @@ - + - + @@ -389,17 +389,17 @@ - + - + - + @@ -410,11 +410,11 @@ - + - + @@ -423,10 +423,10 @@ - + - + diff --git a/docs/handover.adoc b/docs/handover.adoc index c948b7b..0e8af5a 100644 --- a/docs/handover.adoc +++ b/docs/handover.adoc @@ -1,13 +1,19 @@ :document: Handover Report include::share/meta.adoc[] -== A Note Before Reading -The team of year 2023-2024 consisted of only software students, meaning no -hardware was developed in this year. We were tasked with simplifying the -software to the point where it would only have to be ported into the new hardware, -which was designed in the year 2022-2023. The goal of this year is to create -a software framework which can be used to implement new puzzles and to make the -development process of these puzzles easier. +== Introduction + +This is an (at times slightly informal) document that summarizes how the 23-24 +run of this project went. We found the previous handover documents to be +unhelpful when determining the 'actual' state of the project in the first few +weeks, and felt they did not address the pitfalls of this project. + +The team of year 2023-2024 consisted of only software students (see +<>), meaning no hardware was developed in this year. The goal of +this year is to create a software framework which can be used to implement new +puzzles and to make the development process of these puzzles easier, and allow +the entire software stack to be ported to the the hardware designed by the +22-23 group. Previous years' groups have put their predecessor's documents inside their own project folder, which has resulted in what we called the 'Russian doll folder @@ -19,35 +25,20 @@ require credentials to log in. Please note that this is very much unofficial, and is not managed or endorsed by Avans. <> is the contact for removal or transfer of these files. -== Introduction - -This is an informal document that summarizes how the 23-24 run of this project -went. We found the previous handover documents to be unhelpful when determining -the 'actual' state of the project in the first few weeks, and felt they did not -address the pitfalls of this project. +== Group history -== Group History - -=== 19-20 - -.19-20 group composition -[%autowidth] +[[tab:proj-comp]] +.Project group composition |=== -| Name | Study path +| Year | Name | Study path +.4+| 19-20 | Daniël Janssen | Software | Dion Legierse | Software | Jop van Laanen | Hardware | Max van den Heijkant | Software -|=== - -=== 20-21 - -.20-21 group composition -[%autowidth] -|=== -| Name | Study path +.4+| 20-21 | Joost van Wiechen | Hardware | Justin Maas | Software | [[pn:creemers,Merel Creemers]]Merel Creemers | Hardware{empty}footnote:[The @@ -59,40 +50,19 @@ may indicate that they were removed from the project group. I am unsure if they were a hardware student that worked on the PCBs or a CMD student working on the puzzle box chassis.] | Vincent Lengowski | Hardware -|=== - -=== 21-22 - -.21-22 group composition -[%autowidth] -|=== -| Name | Study path +.5+| 21-22 | Alex van Kuijk | Hardware | Jef Baars | Software | Julian de Bruin | Software | Lucas van Gastel | Software | Toon Rockx | Hardware -|=== - -=== 22-23 - -.22-23 group composition -[%autowidth] -|=== -| Name | Study path +.2+| 22-23 | Frank Bekema | Hardware | Jasper Gense | Hardware -|=== - -=== 23-24 (current) - -.23-24 group composition -[%autowidth] -|=== -| Name | Study path +.4+| 23-24 | Elwin Hammer | Software | [[pn:faase,Lars Faase]]Lars Faase{empty}footnote:[<> was removed from the project group on 2024-06-03 following complaints about the lack of @@ -101,57 +71,79 @@ communication, and lack of motivation] | Software | Thomas in 't Anker | Software |=== -== Project State -The current project state is as follows: No new hardware has been designed -or developed this year. The software was completely revised, now consisting of a -a puzzle bus driver, a main controller, a simple CLI application, and two puzzle -modules. Namely the puzzle modules 'Vault' and 'Neotrellis', both using an Arduino -as the controller. The main controller (a RPI Pico W) can interact with the -different puzzle modules using an I^2^C bus. The I^2^C bus has been configured to -be a multi-master I^2^C bus, allowing the puzzle modules and the main controller -to initiate a I^2^C transmission. The main controller is able to find -new puzzle modules on startup, and does not check for new modules afterwards. A -simple CLI application has been developed, which can communicate with the main -controller through a TCP connection and simple commands. - -In short: A puzzle bus driver has been implemented to allow for communication -between the main controller and the puzzle modules. A CLI application was developed -which connects with the main controller to monitor/edit the game state. And the -software for the puzzle modules 'Vault' and 'Neotrellis' is in the prototype state. +== Project state + +The current project state is as follows: + +* No new hardware has been designed or developed this year +* The software was completely revised, now consisting of +** a puzzle bus driver (``pbdrv``) +** a main controller +** a simple CLI application +** two puzzle modules ('Vault' and 'NeoTrellis') integrated using the puzzle + bus driver + +* The main controller (a RPI Pico W) can interact with the different puzzle + modules using a central shared I^2^C bus (referred to as the 'puzzle bus') +* The main controller is able to find new puzzle modules on startup, and does + not check for new modules afterwards. +* A simple CLI application has been developed, which can communicate with the + main controller through a TCP connection and allows control over various + aspects of the puzzle box using simple commands. == Incidents During this year's run of the project, we encountered several difficuties we -feel need to be addressed. We recommend that these incidents are analyzed by -future project groups and incorporated into the risk analysis section of future -project plan documents. +feel need to be addressed in order to be mitigated in future runs of the +project. We recommend that these incidents are analyzed by future project +groups and incorporated into the risk analysis section of future project plan +documents. -=== Misconceptions +=== Documentation -Make sure to know what you are developing and do some research beforehand, to make -sure you have the complete picture about what you are using. Sounds stupid, but it -happened for multiple project attempts, and caused time loss. This also includes -when you want to use documentation of previous years: go through the documentation -and verify it on the lowest possible level for the same reason as previously -mentioned. +We spent too much time working on documentation at the start of the project. +Make sure you set clear deadlines for documentation, and try not to spend too +much time on review procedures, as these cost a lot of time. -=== I^2^C +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. + +=== Misconceptions -I^2^C is easy to implement but also easy to underestimate, this project requires a -multi-master structure as communication is otherwise too complicated compared to -other means of communication. +Make sure to know what you are developing and do some research beforehand, to +make sure you have a complete picture about what you are using. Sounds stupid, +but it happened for multiple project attempts, and caused time loss. This also +includes when you want to use documentation of previous years: go through the +documentation and verify it on the lowest possible level for the same reason as +previously mentioned. -For I^2^C on hardware level: make sure to use pull-up resistors as it is otherwise -impossible to use I^2^C due to incorrect messages. This is also required for -controllers which are connected to the I^2^C bus. Make sure to use I^2^C devices -that support arbitration when using it as a multi-master. +=== I^2^C -The RPI Pico W (RP2040) does supports multi-master to the point of being able to -receive messages from other multi-masters as a slave while being configured as master. -Everything else about the I^2^C bus works, but due to this limitation a workaround has -been implemented to be able to continue using the RPI Pico W. -To simplify; a controller is needed which supports multi-master -while being able to be addressed as a slave. +I^2^C is used because it is widely available and easy to implement. We strongly +recommend 3rd year software students to refresh their knowledge on I^2^C before +making major design decisions that rely on their conception of how to I^2^C bus +works. + +Please note the following differences between I^2^C devices: + +- Regular I^2^C slave peripherals are allowed on the puzzle bus, and can be + connected to the puzzle bus as long as they do not cause issues with + addressing. +- I^2^C master controllers must have hardware support for a multi-master + hardware configuration (i.e. support bus arbitration on a hardware level). + Arbitration support is required to prevent message corruption or electrical + shorts in a multi-master setup. Multi-master controllers may also be + connected to the puzzle bus, but only as long as they only interact with + regular I^2^C slave devices. +- I^2^C multi-master controllers that are slave-addressable in master mode are + the only kind of I^2^C controller suitable for use in puzzle modules. + +The RP2040 supports multi-master, but is not addressable as a slave in master +mode. Due to time constraints, this was mitigated using a workaround (see +<>). === Development hardware availability @@ -160,19 +152,22 @@ include research on the product lifecycle. Choosing boards/chips that have planned long term support makes it easier for the next project team to order and use the same chips/boards instead of having to find new ones. -This also includes having enough development boards for multiple people to -program using the same setup, e.g. the RPI Pico W requires another RPI Pico W -to be debugged, effectively requiring the project team to have at least 4 RPI -Pico Ws to be able to develop in the same environment (if there are 2 software -students). +Due to a lack of foresight, only 2 Picos were ordered this year, which caused +unoptimal workload spread during the last weeks of the project. Because of +this, we also strongly recommend making enough development boards available for +multiple people to develop using the same setup. Note that the RPI Pico is a +special case, as it requires another Pico for debugging, effectively requiring +double the amount of hardware to support developers. === Auxiliary workarounds and technical limitations -This section details unelegant workarounds that should be removed from the -code. Workarounds that should be removed are marked with ``FIXME:`` comments -referring to one of the workarounds mentioned in this section. +This section details workarounds that were implemented instead of being fixed +due to time constraints or project scope. Workarounds that should be removed +are marked with ``FIXME:`` comments referring to one of the workarounds +mentioned in this section. -RP2040 I^2^C limitations:: +[[fixme:rp2040-i2c,RP2040 I^2^C limitations]] +<>:: - All puzzle module drivers have a hard-coded 2 second delay between receiving the MAGIC handshake request and the MAGIC handshake response handler. This was done to ensure responses are not ignored by the RP2040 (main controller) @@ -189,23 +184,43 @@ puzzle modules instead. FreeRTOS does not have an implementation of the == Recommendations +This section details our recommendations on course of action for future project +groups. + === Imperatives -* The 22-23 design document already mentions that the application of the I^2^C -bus is in a multi-master configuration, but does not mention that this only -works when pull-up resistors are used on the SCL and SDA lines. The pull-up -resistors are required, as omitting them makes the bus arbitration process -very inconsistent which causes frames to be dropped entirely. -* Start creating prototypes as fast as possible; this benefits the project in the long run, -as you have already shown that certain parts of the project are already working and "only" -need to be integrated. -* The Atmega328P chip is sufficient for the puzzle modules as it has enough I/O, mutli-master -hardware support, and the ability to be addressed as a slave while being in master mode. -* The hardware design can be taken from the year 22-23, and the game rules are taken from -the year 20-21. - -// TODO: rename this bitch -=== Loose imperatives -* The RPI Pico W has programmable IO modules, making it possible to create an I^2^C driver -that allows multi-master communication while still being addressable as a slave. + +The following points must not be dismissed by future project groups, as they +are critical for project success: + +- The 22-23 design document already mentions that the application of the I^2^C + bus is in a multi-master configuration, but does not mention that this only + works when pull-up resistors are used on the SCL and SDA lines. The pull-up + resistors are required, as omitting them makes the bus arbitration process + very inconsistent which causes frames to be dropped entirely. +- Start creating prototypes as early as possible; this benefits the project in + the long run, as you have already shown that certain parts of the project are + already working and "only" need to be integrated. +- The Atmega328P and ATmega2560 MCUs are both sufficient for the puzzle modules + as they have enough I/O, mutli-master hardware support, and the ability to be + addressed as a slave while being in master mode. +- The RPI Pico (and Pico W)'s I^2^C peripheral supports multi-master, but does + not support being addressed as a slave while in master mode. This is required + for puzzle bus integration, and was mitigated using a workaround (see + <>). A replacement controller should be used instead. + +=== Other suggestions + +These points are suggestions for future project groups. While we do not think +these are critical to project success, we still think they are important to +mention. + +- Implement the hardware design from the year 22-23. +- The original game rules are described in a separate document from the year + 20-21. +- The RPI Pico W has programmable I/O modules. Due to time constraints, we did + not research if these modules can be used to create a custom I^2^C peripheral + (and driver) that allows multi-master communication while still being + addressable as a slave. If this is possible, the RPI Pico W can still be used + as main controller without the use of workarounds. include::share/footer.adoc[] -- 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 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 3238485b246731990c8f073234ff202fb0fedc88 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Thu, 20 Jun 2024 18:44:04 +0200 Subject: add names to research document --- docs/research.adoc | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/research.adoc b/docs/research.adoc index a6ef255..753206c 100644 --- a/docs/research.adoc +++ b/docs/research.adoc @@ -1,7 +1,7 @@ :document: Research include::share/meta.adoc[] -== Microcontrollers used in the current state. +== Microcontrollers used in the current state (Elwin) === Research @@ -39,7 +39,7 @@ see <>. The other custom-made PCB's do not have any microcontroller installed but seem to be made to be used by a ESP32-PICO-KIT V4/V4.1. -=== Summery +=== Summary There seems to be four games implemented where of only one may work because of its integrated ESP32, the other three also may work if the missing ESP32's are @@ -87,7 +87,7 @@ Issues . Button row 4, col 1 for the safe side needs to be replaced (missing a pin) . LED strips for the software and hardware sides only work for 50%. -==== (Appendix Loek) +==== Appendix (Loek) The puzzle bus connector (see <>) appears to have 10 conductors in total. The hardware schematics from 21-22 reveal the pinout of @@ -112,7 +112,7 @@ Source: cite:[2122_design] + (Connector key is next to pin 5) ==== -== Controllers +== Controllers (Loek) To mitigate power consumption issues discovered by the 21-22 group, new controllers were chosen for this year's (23-24) run of the puzzle box project. @@ -205,7 +205,7 @@ the Raspberry Pi RP2040 on the Raspberry Pi Pico W. The recommended MCU for new puzzle modules is the Microchip PIC16F15276. The existing puzzle modules still utilize the ESP32 development kits chosen by the 21-22 group. -== Main Controller OS +== Main Controller OS (Loek) Because the hardware produced by the 21-22 group uses a Raspberry Pi 3B+ as main controller, the usage of this specific board was turned into a @@ -522,7 +522,7 @@ The way these puzzles are solved has been summarized in this research document, but the most complete versions of how to solve these puzzles are given in the group's respective design document. -== Research of hardware designs of previous groups (21-22 and 22-23) +== Research of hardware designs of previous groups (21-22 and 22-23) (Lars) This part of the research looks at the hardware designs of the previous groups that did this project. These are compared with each other and finally the -- 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(-) 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 349db1098e7a7d6f08352dcb7dc5207aae49257c Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Fri, 21 Jun 2024 10:51:30 +0200 Subject: update linter rules --- .clang-format | 2 +- .clang-tidy | 7 ------- 2 files changed, 1 insertion(+), 8 deletions(-) diff --git a/.clang-format b/.clang-format index 3266955..f180135 100644 --- a/.clang-format +++ b/.clang-format @@ -16,4 +16,4 @@ TabWidth: 4 UseTab: Always ... -# vim: ft=yaml \ No newline at end of file +# vim: ft=yaml diff --git a/.clang-tidy b/.clang-tidy index 7a8470a..b242e3f 100644 --- a/.clang-tidy +++ b/.clang-tidy @@ -1,25 +1,18 @@ Checks: '-*,readability-identifier-naming' CheckOptions: - { key: readability-identifier-naming.EnumCase, value: lower_case } - - { key: readability-identifier-naming.EnumPrefix, value: hh_e_ } - { key: readability-identifier-naming.GlobalFunctionCase, value: lower_case } - - { key: readability-identifier-naming.GlobalFunctionPrefix, value: hh_ } - { key: readability-identifier-naming.ClassCase, value: CamelCase } - - { key: readability-identifier-naming.ClassPrefix, value: hh } - { key: readability-identifier-naming.ClassMethodCase, value: lower_case } - { key: readability-identifier-naming.ClassMethodPrefix, value: '' } - { key: readability-identifier-naming.ClassMemberCase, value: lower_case } - { key: readability-identifier-naming.ClassMemberPrefix, value: '' } - { key: readability-identifier-naming.GlobalConstantCase, value: UPPER_CASE } - { key: readability-identifier-naming.GlobalConstantIgnoredRegexp, value: _.* } - - { key: readability-identifier-naming.GlobalConstantPrefix, value: HH_ } - { key: readability-identifier-naming.GlobalVariableCase, value: lower_case } - { key: readability-identifier-naming.GlobalVariableIgnoredRegexp, value: _.* } - - { key: readability-identifier-naming.GlobalVariablePrefix, value: g_hh_ } - { key: readability-identifier-naming.MacroDefinitionCase, value: UPPER_CASE } - { key: readability-identifier-naming.MacroDefinitionIgnoredRegexp, value: _.* } - - { key: readability-identifier-naming.MacroDefinitionPrefix, value: HH_ } - { key: readability-identifier-naming.StructCase, value: lower_case } - - { key: readability-identifier-naming.StructPrefix, value: hh_s_ } # vim: ft=yaml -- 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(-) 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 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 358bd57295bdda494e11619e2e95bdbe271c0231 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Fri, 21 Jun 2024 14:17:16 +0200 Subject: merge puzzle module framework and puzzle bus sections --- docs/design.adoc | 252 +++++++++++++++++++++++++++---------------------------- 1 file changed, 124 insertions(+), 128 deletions(-) diff --git a/docs/design.adoc b/docs/design.adoc index 7d9759a..6a52b38 100644 --- a/docs/design.adoc +++ b/docs/design.adoc @@ -181,10 +181,11 @@ 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. +receive messages on the same controller. This is the only hardware-level +specification made this year. -Address definitions and protocol specifications are further detailed in -<>. +More details on the messages sent over the puzzle bus are described in +<>. === Power supply @@ -260,6 +261,103 @@ designed to facilitate the following: * Provide abstracted interfaces to allow for easy integration of the puzzle box as part of a larger whole (<>). +==== Guidelines + +The following assumptions are made about puzzle modules: + +* Puzzle modules do not take initiative to send REQ or SET commands. They only + respond to requests from the main controller. +* 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. + +These guidelines allow the following simplifications: + +* 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. + +[[sec:lv3-pb-messages]] +==== Messages + +Puzzle bus messages consist of a simple header and variable data. This format +is shown in <>. The messages are (de)serialized using mpack. +This choice was made after considering various alternative options for sending +structured messages cite:[research]. Note that all messages are sent as I^2^C +writes. Due to this, the I^2^C address of a message sender is included in the +header. + +[[tab:pb-msg-fmt]] +.Puzzle bus message format +[%autowidth] +|=== +| Field | Content + +| type | Command type (see <>) +| action | Command action (see <>) +| sender | I^2^C address of sender +| cmd | Command data (dependent on ``type``) +|=== + +<> lists the different command types. + +[[tab:pb-msg-types]] +.Puzzle bus command types +[cols="10,~"] +|=== +| Type | Description + +| ``MAGIC`` +| 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. + +| ``STATE`` +| The STATE command is used by puzzle modules to inform the main controller about +their global state (see <>). 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. + +| ``PROP`` +| The PROP command type is used for exchanging arbitrary data between puzzle +modules and/or the puzzle box client (pbc) over the <>. These properties are not used by the puzzle framework. +|=== + +<> lists the different command actions. + +[[tab:pb-msg-actions]] +.Puzzle bus command actions +[cols="10,~"] +|=== +| ``REQ`` +| Mark the command as a request. The receiver of this message is expected to +return a message of the same type, but with a RES action. + +| ``RES`` +| Mark the command as a response to a REQ message. All REQ messages should be +followed by a RES message. + +| ``SET`` +| Request a change / write. The SET command is never followed by a RES. +|=== + +Please note that not all commands define behavior for all actions (e.g. there +is no MAGIC SET command). + +Only the MAGIC and STATE commands are required for the puzzle box to function. +The PROP command was created to allow future expansion without modifying the +main controller firmware (<>). + +The specific format of the 'cmd' field from <> is different for +each command type, and is for this reason only documented in-code using +Doxygen. + [[sec:framework-state]] ==== State @@ -267,20 +365,21 @@ All puzzle modules implement the same state machine shown in <>. 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 a module''s global state to one of +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 'idle' state. - [[fig:puzzle-module-common-state]] .Global puzzle module state machine image::img/puzzle-module-common-state.svg[] +Puzzle modules start in the 'uninitialized' state, where they wait until the +main controller sends a REQ 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 'idle' state. +This process is also shown in <>. + The state machine described in <> is referred to as the global state. Puzzle modules may also declare and define custom variables, which are referred to as properties. These properties may contain @@ -289,79 +388,23 @@ puzzle module, or the last passcode entered on the vault puzzle module. 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 - -// 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. +expansion without modification of the main controller software +(<>). -In this example, module B could be the vault puzzle module, which displays a -code when the entire puzzle box is solved. +==== I^2^C addresses -[[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_: - -* ``REQ``: request -* ``RES``: response -* ``SET``: (over)write +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``). -- 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 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. -The Doxygen-generated pages for these command types explain their usage, and -will not be restated in this document. +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). === Main Controller @@ -370,11 +413,9 @@ 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 +startup. Puzzle modules start in the 'uninitialized' state (see +<>), during 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. @@ -452,51 +493,6 @@ TODO - 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 - -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. - -==== Guidelines - -The following assumptions are made about puzzle modules: - -* 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. - -These guidelines allow the following simplifications: - -* 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. - -==== Addresses - -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``). - -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. - -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 This subsection defines aspects of the 'NeoTrellis puzzle' module and gives a -- cgit v1.2.3 From d38d1f7abd1b91b216172f1d356cec2124e62fac Mon Sep 17 00:00:00 2001 From: ThomasintAnker Date: Fri, 21 Jun 2024 15:03:06 +0200 Subject: WIP Added puzzle module i2c research --- docs/research.adoc | 43 +++++++++++++++++++++++++++++++++++++++++++ docs/share/refs.bib | 19 +++++++++++++++++++ 2 files changed, 62 insertions(+) diff --git a/docs/research.adoc b/docs/research.adoc index a6ef255..4f64538 100644 --- a/docs/research.adoc +++ b/docs/research.adoc @@ -522,6 +522,49 @@ The way these puzzles are solved has been summarized in this research document, but the most complete versions of how to solve these puzzles are given in the group's respective design document. +== I^2^C (Thomas) + +=== Research question + +How can we use I^2^C for the internal communication between puzzle modules +and the main controller, and how can we detect new puzzle modules using I^2^C? + +=== Puzzle Module Detection + +Puzzle module detection is vital to the puzzelbox, as this allows changing the +puzzles without much software or hardware configuration needed. An option will +be given for the choice of main controller (RP2040); namely to scan the full +I^2^C bus for responsive slaves. The RPI Pico SDK has an API for I^2^C which +also supports functions create a bus scanning function. An example of just the +bus scan function according to the API examples can be found in the code block +below. + +[source, c] +---- +#include +#include "pico/stdlib.h" +#include "hardware/i2c.h" + +void bus_scan() { + int ret; + uint8_t rxdata; + + for (int addr = 0; addr < (1 << 7); ++addr) { + ret = i2c_read_blocking(i2c_default, addr, &rxdata, 1, false); + printf(ret < 0 ? "." : "@"); + printf(addr % 16 == 15 ? "\n" : " "); + } + printf("Done.\n"); +} + +---- + +// TODO: references (API) & code block naming? + +=== Arduino + + + == Research of hardware designs of previous groups (21-22 and 22-23) This part of the research looks at the hardware designs of the previous groups diff --git a/docs/share/refs.bib b/docs/share/refs.bib index b6fe625..0af5f94 100644 --- a/docs/share/refs.bib +++ b/docs/share/refs.bib @@ -192,3 +192,22 @@ publisher = {Avans University of Applied Sciences}, year = {2022}, } + +@online{Joh21, + author = {Johnston, P.}, + title = {Embedded systems testing resources}, + url = {https://embeddedartistry.com/blog/2018/10/18/embedded-systems-testing-resources/}, + month = jun, + msbib-day = {10}, + msbib-accessed = {2024-02-25}, + year = {2021}, +} + +@online{RPI23, + title = {Hardware APIs - Hardware I2C}, + url = {https://www.raspberrypi.com/documentation/pico-sdk/hardware.html#hardware_i2c}, + month = jun, + msbib-day = {14}, + year = {2023}, + msbib-accessed = {2024-05-11}, +} -- cgit v1.2.3 From 454032718251eac7788c4d1b45767c18c0aa11ed Mon Sep 17 00:00:00 2001 From: ThomasintAnker Date: Fri, 21 Jun 2024 15:23:24 +0200 Subject: Changed order of researcg --- docs/research.adoc | 25 +++++++++++++++---------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/docs/research.adoc b/docs/research.adoc index 4f64538..65cc68b 100644 --- a/docs/research.adoc +++ b/docs/research.adoc @@ -526,8 +526,7 @@ group's respective design document. === Research question -How can we use I^2^C for the internal communication between puzzle modules -and the main controller, and how can we detect new puzzle modules using I^2^C? +How can we use I^2^C for the puzzle module detection? === Puzzle Module Detection @@ -535,9 +534,9 @@ Puzzle module detection is vital to the puzzelbox, as this allows changing the puzzles without much software or hardware configuration needed. An option will be given for the choice of main controller (RP2040); namely to scan the full I^2^C bus for responsive slaves. The RPI Pico SDK has an API for I^2^C which -also supports functions create a bus scanning function. An example of just the -bus scan function according to the API examples can be found in the code block -below. +also supports functions create a bus scanning function. An example of this +bus scan function, according to the API examples, can be found in the pseudo +code below. [source, c] ---- @@ -556,14 +555,20 @@ void bus_scan() { } printf("Done.\n"); } - ---- -// TODO: references (API) & code block naming? - -=== Arduino - +The bus scan function tries to read data from all possible I^2^C addresses, +and prints a table which shows what the addresses are from found I^2^C +slaves. This is possible due to the i2c_read_blocking function, which returns +the length of the read data if the slave address is in use (in this case 1) or +a number below 0 if the slave address is not in use. The puzzelbox, however, +has the 'Neotrellis' puzzle which also uses I^2^C to function. The bus scan +function would also see the 'Neotrellis' rgb matrix as a puzzle module (slave) +using this implementation. This can easily be fixed using a handshake between +puzzle modules and the main controller, as the 'Neotrellis' rgb matrix cannot +answer this handshake and is therefor not recognized as a puzzle module. +// TODO: references (API) & code block naming? == Research of hardware designs of previous groups (21-22 and 22-23) -- cgit v1.2.3 From a536385ba46e9f55414593a1c47683e2f9abe628 Mon Sep 17 00:00:00 2001 From: ThomasintAnker Date: Fri, 21 Jun 2024 15:24:28 +0200 Subject: WIP --- docs/research.adoc | 100 ++++++++++++++++++++++++++++------------------------- 1 file changed, 52 insertions(+), 48 deletions(-) diff --git a/docs/research.adoc b/docs/research.adoc index 65cc68b..88e43a7 100644 --- a/docs/research.adoc +++ b/docs/research.adoc @@ -400,6 +400,58 @@ testing. Including mocking tests, a large amount of assertions, multiple test with different input support, and lastly being supported in the newest non-experimental version of {cpp}. +== I^2^C (Thomas) + +=== Research question + +How can we use I^2^C for the puzzle module detection? + +=== Puzzle Module Detection + +Puzzle module detection is vital to the puzzelbox, as this allows changing the +puzzles without much software or hardware configuration needed. An option will +be given for the choice of main controller (RP2040); namely to scan the full +I^2^C bus for responsive slaves. The RPI Pico SDK has an API for I^2^C which +also supports functions create a bus scanning function. An example of this +bus scan function, according to the API examples, can be found in the pseudo +code below. + +[source, c] +---- +#include +#include "pico/stdlib.h" +#include "hardware/i2c.h" + +void bus_scan() { + int ret; + uint8_t rxdata; + + for (int addr = 0; addr < (1 << 7); ++addr) { + ret = i2c_read_blocking(i2c_default, addr, &rxdata, 1, false); + printf(ret < 0 ? "." : "@"); + printf(addr % 16 == 15 ? "\n" : " "); + } + printf("Done.\n"); +} +---- + +The bus scan function tries to read data from all possible I^2^C addresses, +and prints a table which shows what the addresses are from found I^2^C +slaves. This is possible due to the i2c_read_blocking function, which returns +the length of the read data if the slave address is in use (in this case 1) or +a number below 0 if the slave address is not in use. The puzzelbox, however, +has the 'Neotrellis' puzzle which also uses I^2^C to function. The bus scan +function would also see the 'Neotrellis' rgb matrix as a puzzle module (slave) +using this implementation. This can easily be fixed using a handshake between +puzzle modules and the main controller, as the 'Neotrellis' rgb matrix cannot +answer this handshake and is therefor not recognized as a puzzle module. + +// TODO: references (API) & code block naming? + +=== Welke microcontroller famillies zijn slave addresseerbaar while in master die ook multimaster vriendelijk zijn. + +=== multi master == standaard? + == Original Puzzle Box Functionality Research (Thomas) === Research question @@ -522,54 +574,6 @@ The way these puzzles are solved has been summarized in this research document, but the most complete versions of how to solve these puzzles are given in the group's respective design document. -== I^2^C (Thomas) - -=== Research question - -How can we use I^2^C for the puzzle module detection? - -=== Puzzle Module Detection - -Puzzle module detection is vital to the puzzelbox, as this allows changing the -puzzles without much software or hardware configuration needed. An option will -be given for the choice of main controller (RP2040); namely to scan the full -I^2^C bus for responsive slaves. The RPI Pico SDK has an API for I^2^C which -also supports functions create a bus scanning function. An example of this -bus scan function, according to the API examples, can be found in the pseudo -code below. - -[source, c] ----- -#include -#include "pico/stdlib.h" -#include "hardware/i2c.h" - -void bus_scan() { - int ret; - uint8_t rxdata; - - for (int addr = 0; addr < (1 << 7); ++addr) { - ret = i2c_read_blocking(i2c_default, addr, &rxdata, 1, false); - printf(ret < 0 ? "." : "@"); - printf(addr % 16 == 15 ? "\n" : " "); - } - printf("Done.\n"); -} ----- - -The bus scan function tries to read data from all possible I^2^C addresses, -and prints a table which shows what the addresses are from found I^2^C -slaves. This is possible due to the i2c_read_blocking function, which returns -the length of the read data if the slave address is in use (in this case 1) or -a number below 0 if the slave address is not in use. The puzzelbox, however, -has the 'Neotrellis' puzzle which also uses I^2^C to function. The bus scan -function would also see the 'Neotrellis' rgb matrix as a puzzle module (slave) -using this implementation. This can easily be fixed using a handshake between -puzzle modules and the main controller, as the 'Neotrellis' rgb matrix cannot -answer this handshake and is therefor not recognized as a puzzle module. - -// TODO: references (API) & code block naming? - == Research of hardware designs of previous groups (21-22 and 22-23) This part of the research looks at the hardware designs of the previous groups -- cgit v1.2.3 From 8bd40843cbaafd82e11d897fe210c0975b5bd73c Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Fri, 21 Jun 2024 15:43:00 +0200 Subject: add disclaimers --- .editorconfig | 2 +- docs/design.adoc | 8 +++++++- docs/handover.adoc | 11 ++++++----- docs/reqs.adoc | 40 ++++++++++++++++++++-------------------- docs/research.adoc | 19 +++++++++++++++---- docs/share/refs.bib | 8 ++++++++ docs/theme.yml | 8 ++++++++ 7 files changed, 65 insertions(+), 31 deletions(-) diff --git a/.editorconfig b/.editorconfig index cd37156..bd1f474 100644 --- a/.editorconfig +++ b/.editorconfig @@ -5,7 +5,7 @@ indent_style = tab end_of_line = lf insert_final_newline = true -[*.md] +[*.{md,yml}] indent_style = space indent_size = 2 diff --git a/docs/design.adoc b/docs/design.adoc index 6a52b38..06cd100 100644 --- a/docs/design.adoc +++ b/docs/design.adoc @@ -146,7 +146,13 @@ 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 + +NOTE: This was written while we did not know the puzzle bus specifically +requires slave-addressible I^2^C multi-master controllers to function properly. +While the research concludes the RP2040 is a suitable microcontroller for the +main controller, it is not. The RP2040 was still used, but has required +implementing workarounds. Please see the handover report for more details on +how this impacted the project cite:[handover]. [[fig:main-controller-top]] .Main controller top-level block diagram diff --git a/docs/handover.adoc b/docs/handover.adoc index 6918256..77d5da0 100644 --- a/docs/handover.adoc +++ b/docs/handover.adoc @@ -29,16 +29,17 @@ removal or transfer of these files. [[tab:proj-comp]] .Project group composition +[cols="15,35,20",width=55%] |=== | Year | Name | Study path -.4+| 19-20 +.4+h| 19-20 | Daniël Janssen | Software | Dion Legierse | Software | Jop van Laanen | Hardware | Max van den Heijkant | Software -.4+| 20-21 +.4+h| 20-21 | Joost van Wiechen | Hardware | Justin Maas | Software | [[pn:creemers,Merel Creemers]]Merel Creemers | Hardware{empty}footnote:[The @@ -51,18 +52,18 @@ were a hardware student that worked on the PCBs or a CMD student working on the puzzle box chassis.] | Vincent Lengowski | Hardware -.5+| 21-22 +.5+h| 21-22 | Alex van Kuijk | Hardware | Jef Baars | Software | Julian de Bruin | Software | Lucas van Gastel | Software | Toon Rockx | Hardware -.2+| 22-23 +.2+h| 22-23 | Frank Bekema | Hardware | Jasper Gense | Hardware -.4+| 23-24 +.4+h| 23-24 | Elwin Hammer | Software | [[pn:faase,Lars Faase]]Lars Faase{empty}footnote:[<> was removed from the project group on 2024-06-03 following complaints about the lack of diff --git a/docs/reqs.adoc b/docs/reqs.adoc index 8ad24a8..611c8f3 100644 --- a/docs/reqs.adoc +++ b/docs/reqs.adoc @@ -108,7 +108,7 @@ describes all functional requirements of the puzzle box. === The puzzle box .Puzzle box specifications -[cols="8h,5h,~"] +[cols="9h,6h,~"] |=== | ID | <> | Specification @@ -165,7 +165,7 @@ describes all functional requirements of the puzzle box. === The bomb .Bomb specifications -[cols="8h,5h,~"] +[cols="9h,6h,~"] |=== | ID | <> | Specification @@ -198,7 +198,7 @@ describes all functional requirements of the puzzle box. === The game .General game specifications -[cols="8h,5h,~"] +[cols="9h,6h,~"] |=== | ID | <> | Specification @@ -239,7 +239,7 @@ describes all functional requirements of the puzzle box. ==== NeoTrellis puzzle .NeoTrellis puzzle requirements -[cols="8h,5h,~"] +[cols="9h,6h,~"] |=== | ID | <> | Specification @@ -262,7 +262,7 @@ describes all functional requirements of the puzzle box. ==== Software puzzle .Software puzzle requirements -[cols="8h,5h,~"] +[cols="9h,6h,~"] |=== | ID | <> | Specification @@ -297,7 +297,7 @@ The specific details for this puzzle are not present in the previous documentation. Due to time constraints, the section will be left empty. .Automation puzzle requirements -[cols="8h,5h,~"] +[cols="9h,6h,~"] |=== | ID | <> | Specification @@ -308,7 +308,7 @@ documentation. Due to time constraints, the section will be left empty. ==== Hardware puzzle .Hardware puzzle requirements -[cols="8h,5h,~"] +[cols="9h,6h,~"] |=== | ID | <> | Specification @@ -397,7 +397,7 @@ documentation. Due to time constraints, the section will be left empty. ==== Vault puzzle .Vault puzzle requirements -[cols="8h,5h,~"] +[cols="9h,6h,~"] |=== | ID | <> | Specification @@ -447,7 +447,7 @@ documentation. Due to time constraints, the section will be left empty. === Battery .Battery requirements -[cols="8h,5h,~"] +[cols="9h,6h,~"] |=== | ID | <> | Specification @@ -464,7 +464,7 @@ documentation. Due to time constraints, the section will be left empty. === Network Communication .Communication requirements -[cols="8h,5h,~"] +[cols="9h,6h,~"] |=== | ID | <> | Specification @@ -477,7 +477,7 @@ documentation. Due to time constraints, the section will be left empty. === Framework -[cols="8h,5h,~"] +[cols="9h,6h,~"] |=== | ID | <> | Specification @@ -497,7 +497,7 @@ documentation. Due to time constraints, the section will be left empty. === Puzzle box hub .Puzzle box hub general requirements -[cols="8h,5h,~"] +[cols="9h,6h,~"] |=== | ID | <> | Specification @@ -516,7 +516,7 @@ technical specifications of the puzzle box. === Wireless communication .Wireless communication requirements -[cols="8h,5h,~"] +[cols="9h,6h,~"] |=== | ID | <> | Specification @@ -527,7 +527,7 @@ technical specifications of the puzzle box. === Framework .Development framework requirements -[cols="8h,5h,~"] +[cols="9h,6h,~"] |=== | ID | <> | Specification @@ -550,7 +550,7 @@ technical specifications of the puzzle box. === Main controller .Main controller requirements -[cols="8h,5h,~"] +[cols="9h,6h,~"] |=== | ID | <> | Specification @@ -575,7 +575,7 @@ technical specifications of the puzzle box. === Puzzle module controller -[cols="8h,5h,~"] +[cols="9h,6h,~"] |=== | ID | <> | Specification @@ -601,7 +601,7 @@ technical specifications of the puzzle box. === Vault puzzle .Vault puzzle requirements -[cols="8h,5h,~"] +[cols="9h,6h,~"] |=== | ID | <> | Specification @@ -627,7 +627,7 @@ technical specifications of the puzzle box. === Bomb .Bomb requirements -[cols="8h,5h,~"] +[cols="9h,6h,~"] |=== | ID | <> | Specification @@ -650,7 +650,7 @@ This section describes the aspects of the project which have been set as preconditions and cannot be changed. .Preconditions -[cols="8h,~"] +[cols="9h,~"] |=== | ID | Precondition @@ -666,7 +666,7 @@ preconditions and cannot be changed. This section lists requirements that apply to documentation produced during this project. -[cols="8h,5h,~"] +[cols="9h,6h,~"] |=== | ID | <> | Specification diff --git a/docs/research.adoc b/docs/research.adoc index 753206c..acab4ab 100644 --- a/docs/research.adoc +++ b/docs/research.adoc @@ -143,6 +143,13 @@ than the other options. It also happens to be less expensive than all other options. Due to these reasons, the RP2040 was chosen as main controller MCU. The Raspberry Pi Pico W board is utilized during development. +NOTE: This was written while we did not know the puzzle bus specifically +requires slave-addressible I^2^C multi-master controllers to function properly. +While the research concludes the RP2040 is a suitable microcontroller for the +main controller, it is not. The RP2040 was still used, but has required +implementing workarounds. Please see the handover report for more details on +how this impacted the project cite:[handover]. + [[tab:main-mcu]] .Main controller MCU candidates [%autowidth] @@ -173,10 +180,10 @@ manufacturers: Atmel, STMicroelectronics, Raspberry Pi. All the MCUs listed in <> support some version of a low-power mode. The RP2040 is again included and appears here because it supports clock speed -configuration and has a clock gate for each peripheral [2], which may make it a -feasible option with regards to power consumption. Choosing the RP2040 may also -simplify the development process as only a single MCU toolchain needs to be -maintained. +configuration and has a clock gate for each peripheral cite:[rp2040ds], which +may make it a feasible option with regards to power consumption. Choosing the +RP2040 may also simplify the development process as only a single MCU toolchain +needs to be maintained. The Microchip PIC16F15276 is the most power efficient on this list and is the recommended MCU for puzzle modules. It supports both extreme underclocking and @@ -187,6 +194,10 @@ Because this year's run of this project was carried out by a team consisting only of software students, this choice remains as a recommendation. The puzzle box hardware may still use the ESP32 development kits from the 21-22 group. +NOTE: This was written while we did not know the puzzle bus specifically +requires slave-addressible I^2^C multi-master controllers to function properly. +We have not verified if the PIC16F15276 supports this feature. + [[tab:pm-mcu]] .Puzzle module controller MCU candidates [%autowidth] diff --git a/docs/share/refs.bib b/docs/share/refs.bib index b6fe625..1c37465 100644 --- a/docs/share/refs.bib +++ b/docs/share/refs.bib @@ -166,6 +166,14 @@ year = {2024}, } +@techreport{handover, + author = {Blansch, Loek Le and Hammer, Elwin and Faase, Lars and in 't Anker, Thomas}, + title = {Handover Report}, + location = {'s-Hertogenbosch}, + publisher = {Avans University of Applied Sciences}, + year = {2024}, +} + @techreport{2021_design, author = {Creemers, Merel and van Wiechen, Joost and Lengowski, Vincent and Maas, Justin}, title = {Ontwerpdocument}, diff --git a/docs/theme.yml b/docs/theme.yml index b26ad75..49f729f 100644 --- a/docs/theme.yml +++ b/docs/theme.yml @@ -61,6 +61,7 @@ toc: caption: align: center end: bottom + margin_inside: 6pt image: align: center @@ -98,3 +99,10 @@ footer: center: content: '{page-number}' +admonition: + column_rule_color: '#000000' + column_rule_width: 1pt + padding: [3pt, 6pt, 3pt, 6pt] + label: + font_style: bold + -- cgit v1.2.3 From 79e60b430143b2acc4b93f62e23770e6bcbd7861 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Fri, 21 Jun 2024 16:31:43 +0200 Subject: design doc TODOs done --- docs/design.adoc | 26 ++++++++++++++------------ docs/reqs.adoc | 5 ++++- 2 files changed, 18 insertions(+), 13 deletions(-) diff --git a/docs/design.adoc b/docs/design.adoc index 06cd100..9e48fd4 100644 --- a/docs/design.adoc +++ b/docs/design.adoc @@ -486,18 +486,20 @@ Detailed specifications on the TCP socket server are in ==== Operating system -TODO - -- 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 +Because the main controller needs to asynchronously handle state exchanges with +puzzle modules while serving a TCP socket connection, the decision to use a +task scheduler was made. Due to the requirement that most software should be +covered by the standard curriculum (<>), this +choice was between FreeRTOS and Zephyr. FreeRTOS was chosen because it is the +simplest solution, and because the features Zephyr offers over FreeRTOS are +already present in the Raspberry Pi Pico SDK. + +NOTE: Due to the issues with the RP2040 that were later discovered +cite:[handover], delays are used within the puzzle bus driver's message +handling logic. This means that due to the use of the RP2040, *all puzzle +modules* are required to use a task scheduler or similar mechanism for +deferring calls to the puzzle bus driver from the I^2^C interrupt service +routine (ISR). === NeoTrellis puzzle diff --git a/docs/reqs.adoc b/docs/reqs.adoc index 611c8f3..a221173 100644 --- a/docs/reqs.adoc +++ b/docs/reqs.adoc @@ -543,8 +543,11 @@ technical specifications of the puzzle box. | <> | <> | [[req:135,R-135]] Puzzle modules are initialized by the main controller module. -| <> | <> | +| <> | <> | [[req:165,R-165]] Puzzle modules repeatedly send 'update' messages to the main controller while their global state is 'uninitialized' + +| <> | <> | +[[req:curriculum-cov,R-169]] External software and libraries that are covered in the standard curriculum should be used where possible |=== === Main controller -- 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 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(-) 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(-) 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 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 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 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 3667d9a9955face0d4a147319cc902cbf8c95299 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Sat, 22 Jun 2024 17:00:51 +0200 Subject: more client docs --- client/cmd.h | 50 +++++++++++++++++++++++++++++++++++++++++--------- client/i2c.cpp | 4 ++-- client/i2c.h | 29 ++++++++++++++++++++++++++++- client/parse.h | 14 ++++++++++++++ client/rl.cpp | 15 ++++++++------- client/rl.h | 43 ++++++++++++++++++++++++++++++++++++++++++- client/sock.h | 43 +++++++++++++++++++++++++++++++++++++++++++ client/xxd.h | 9 +++++++++ 8 files changed, 187 insertions(+), 20 deletions(-) diff --git a/client/cmd.h b/client/cmd.h index 961ef89..a3cc44a 100644 --- a/client/cmd.h +++ b/client/cmd.h @@ -1,17 +1,44 @@ #pragma once +/** + * \ingroup pbc + * \defgroup pbc_cmd cmd + * \brief Commands within \ref pbc + * \{ + */ + #include -typedef void cmd_handle_t(char *); -typedef char** cmd_complete_t(const char*, int, int); +/** + * \internal + * \brief Command handler function + * + * \param line Remaining text after command name on command line + */ +typedef void cmd_handle_t(char * line); +/** + * \internal + * \brief Command completion function + * + * \param text Current word to complete + * \param start Index in \c rl_line_buffer of cursor position + * \param end End index of \p text in \c rl_line_buffer + * + * \return Array of \c char* with suggestions. The array is terminated by a + * NULL pointer. + */ +typedef char** cmd_complete_t(const char* text, int start, int end); -struct cmd { - cmd_handle_t * handle; - const char* name; - const char* info; - cmd_complete_t * complete; -}; -typedef struct cmd cmd_t; +/** + * \internal + * \brief Command definition struct + */ +typedef struct { + cmd_handle_t * handle; //!< Handler function (required) + const char* name; //!< Command name (required) + const char* info; //!< Command info (shown in help command) (optional = NULL) + cmd_complete_t * complete; //!< Completion function (optional = NULL) +} cmd_t; cmd_handle_t cmd_exit; cmd_handle_t cmd_test; @@ -23,6 +50,7 @@ cmd_handle_t cmd_skip; cmd_handle_t cmd_dump; cmd_complete_t cmd_dump_complete; +//! Commands static const cmd_t cmds[] = { { .handle = cmd_exit, @@ -68,5 +96,9 @@ static const cmd_t cmds[] = { }, #endif }; + +//! Number of commands defined in \c cmds static const size_t cmds_length = sizeof(cmds) / sizeof(cmds[0]); +/// \} + diff --git a/client/i2c.cpp b/client/i2c.cpp index 78e5585..3655191 100644 --- a/client/i2c.cpp +++ b/client/i2c.cpp @@ -35,9 +35,9 @@ void i2c_send(uint16_t addr, const char * data, size_t data_size) { static void i2c_handle_cmd_read(uint16_t, const char *, size_t); -void i2c_recv(uint16_t addr, const char * data, size_t data_size) { +void i2c_recv(const char * data, size_t data_size) { if (i2c_dump_recv) { - printf("[%s] addr(0x%02x) data(0x%02lx):\n", __FUNCTION__, addr, data_size); + printf("[%s] data(0x%02lx):\n", __FUNCTION__, data_size); xxd(data, data_size); } } diff --git a/client/i2c.h b/client/i2c.h index f9f58f9..87f33c9 100644 --- a/client/i2c.h +++ b/client/i2c.h @@ -3,6 +3,33 @@ #include #include +/** + * \ingroup pbc + * \defgroup pbc_i2c i2c + * \brief I2C abstraction functions + * \{ + */ + +/** + * \brief Fake I2C send function + * + * This function sends an I2C message to the main controller over TCP using + * \ref i2ctcp. + * + * \param addr I2C address + * \param data Data to send + * \param data_size size of \p data + */ void i2c_send(uint16_t addr, const char * data, size_t data_size); -void i2c_recv(uint16_t addr, const char * data, size_t data_size); +/** + * \brief Fake I2C receive handler + * + * This function is called for I2C messages received by the main controller and + * forwarded to \ref pbc. + * + * \param data Received data + * \param data_size size of \p data + */ +void i2c_recv(const char * data, size_t data_size); +/// \} diff --git a/client/parse.h b/client/parse.h index 94afe70..8b7d235 100644 --- a/client/parse.h +++ b/client/parse.h @@ -2,11 +2,23 @@ #include +/** + * \ingroup pbc + * \defgroup pbc_parse parse + * \brief Debug send command parser utilities + * \{ + */ + +//! Internal field separator (i.e. whitespace delimiter) #define IFS " \t\n" +//! Octal digit character set #define SET_OCT "01234567" +//! Decimal digit character set #define SET_DEC "0123456789" +//! Hexadecimal digit character set #define SET_HEX SET_DEC"abcdefABCDEF" +//! (Hexadecimal) byte string character set #define SET_HEX_STR SET_HEX":" /** @@ -40,3 +52,5 @@ char* consume_token(char * token, const char * ifs); */ int strtodata(const char * str, char ** data, size_t * size); +/// \} + diff --git a/client/rl.cpp b/client/rl.cpp index fa44bf4..f839d96 100644 --- a/client/rl.cpp +++ b/client/rl.cpp @@ -119,24 +119,25 @@ int rl_word(const char * line, int cursor) { return word; } +/// \internal typedef struct { const char * word; - const char ** suggestions; + const char ** options; } __rl_complete_list_data_t; -char** rl_complete_list(const char * word, const char ** suggestions) { +char** rl_complete_list(const char * word, const char ** options) { __rl_complete_list_data_t data = { .word = word, - .suggestions = suggestions, + .options = options, }; return rl_completion_matches((char *) &data, [](const char * text, int state) -> char * { __rl_complete_list_data_t data = *(__rl_complete_list_data_t *) text; static size_t i = 0; if (state == 0) i = 0; - while (data.suggestions[i] != NULL) { - const char * suggestion = data.suggestions[i++]; - if (strncmp(data.word, suggestion, strlen(data.word)) == 0) - return strdup(suggestion); + while (data.options[i] != NULL) { + const char * option = data.options[i++]; + if (strncmp(data.word, option, strlen(data.word)) == 0) + return strdup(option); } return NULL; }); diff --git a/client/rl.h b/client/rl.h index ab31ddb..d2f8612 100644 --- a/client/rl.h +++ b/client/rl.h @@ -1,12 +1,53 @@ #pragma once +/** + * \ingroup pbc + * \defgroup pbc_rl rl + * \brief GNU Readline related functions + * \{ + */ + +//! Reset color (ANSI sequence) #define COLOR_OFF "\x1b[0m" +//! Set font to bold (ANSI sequence) #define COLOR_BOLD "\x1b[1m" +//! Prompt text #define CLI_PROMPT "(" COLOR_BOLD "pbc" COLOR_OFF ") " +//! CLI entrypoint int cli_main(); + +/** + * \brief Print format string to stdout without disturbing the readline prompt + * + * This function saves and restores the current readline prompt before/after + * calling printf. This function is not required for commands that print output + * synchronously, as the prompt is only shown after a command handler + * completes. + */ void rl_printf(const char * fmt, ...); +/** + * \brief Get the index of the word currently under the cursor + * + * \param line Command line contents + * \param cursor Index of cursor position + * + * This function returns the index of the word from an array made by splitting + * \p line on consecutive occurrences of \c IFS. + * + * \return Index of word + */ int rl_word(const char * line, int cursor); -char ** rl_complete_list(const char * word, const char * suggestions[]); +/** + * \brief Create a completion suggestion string array for readline + * + * \param word Word to complete + * \param options List of possible choices (NULL terminated array of strings) + * + * \return Suggestions matching \p word + */ +char ** rl_complete_list(const char * word, const char * options[]); + +/// \} diff --git a/client/sock.h b/client/sock.h index 0dee09e..c124e45 100644 --- a/client/sock.h +++ b/client/sock.h @@ -3,29 +3,72 @@ #include #include +/** + * \ingroup pbc + * \defgroup pbc_sock sock + * \brief TCP socket handling + * \{ + */ + +/** + * \brief Asynchronous puzzle box socket connection + * \note Once connected, this class will call \c i2c_recv() when a complete I2C + * message has been received + */ class PBSocket { public: PBSocket(); PBSocket(const char * addr, uint16_t port); virtual ~PBSocket(); + //! Configure target server void set_server(const char * addr, uint16_t port); + //! Attempt to connect to server and start \c sock_task() in a thread void sock_connect(); + /** + * \brief Send data over the TCP connection + * + * \param buf Data to send + * \param buf_sz Size of \p buf in bytes + */ void send(const char * buf, size_t buf_sz); private: + /** + * \brief Continously read from the TCP socket and read \ref i2ctcp messages + * using \c i2ctcp_read(). + * + * Once a complete message has been parsed, \c i2c_recv() is called with the + * complete message. This message is automatically free'd after \c i2c_recv() + * returns. + * + * \note This function is run in a separate thread + */ void sock_task(); + //! Close the socket void sock_close(); + //! Pointer to thread running \c sock_task() std::thread* _thread = nullptr; + /** + * \brief IP address of server to connect to + * + * \note This member must contain an IP address, as no hostname resolution is + * done in pbc. + */ const char * _addr = NULL; + //! Port number of server to connect to uint16_t _port = 0; + //! Unix file descriptor of opened socket int _fd = -1; }; +//! Singleton \c PBSocket instance extern PBSocket* sock; +/// \} + diff --git a/client/xxd.h b/client/xxd.h index fb28bb1..ede9fff 100644 --- a/client/xxd.h +++ b/client/xxd.h @@ -6,11 +6,20 @@ extern "C" { #endif +/** + * \ingroup pbc + * \defgroup pbc_xxd xxd + * \brief Utility hexdump + * \{ + */ + /** * \brief utility function that prints hexdump of data */ void xxd(const char * data, size_t size); +/// \} + #ifdef __cplusplus } #endif -- cgit v1.2.3 From 3c2f4422e4dd90826a549c87d9d042c592806cb8 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Sat, 22 Jun 2024 17:26:17 +0200 Subject: docs done --- main/blink.h | 12 ++++++++++++ main/config.def.h | 54 ++++++++++++++++++++++++++++++++++++------------------ main/i2c.h | 14 +++++++++++++- main/index.dox | 6 ++++++ main/init.h | 12 +++++++++--- main/sock.h | 15 ++++++++++++--- main/tasks.h | 9 +++++++++ 7 files changed, 97 insertions(+), 25 deletions(-) create mode 100644 main/index.dox diff --git a/main/blink.h b/main/blink.h index 51c5f32..f8262d0 100644 --- a/main/blink.h +++ b/main/blink.h @@ -1,4 +1,16 @@ #pragma once +/** + * \ingroup main_tasks + * \{ + */ + +/** + * \brief Status LED blink task + * + * This task is started after initialization is complete, and blinks the + * on-board LED to indicate the Pico has completed initialization successfully. + */ void blink_task(); +/// \} diff --git a/main/config.def.h b/main/config.def.h index e9503ed..0dae608 100644 --- a/main/config.def.h +++ b/main/config.def.h @@ -2,32 +2,45 @@ #include #include +/** + * \ingroup main + * \defgroup main_config config + * \brief Configuration options + * \{ + */ + /** * \name Network (Wi-Fi) configuration * \{ */ #ifndef CFG_NET_SSID -//! network name (SSID) +/** + * \brief Network name (SSID) + * \note Not defining \c CFG_NET_SSID will implicitly enable \c CFG_NET_DISABLE + */ #define CFG_NET_SSID "" #ifndef CFG_NET_DISABLE -//! disable network communication +/** + * \brief Disable network communication completely + * \note Enabling this option will implicitly enable \c CFG_SRV_DISABLE + */ #define CFG_NET_DISABLE #warning No SSID defined! Disabling network communication! #endif #endif #ifndef CFG_NET_PASS -//! network password +//! Network password #define CFG_NET_PASS "" #endif #ifndef CFG_NET_AUTH -//! network security type +//! Network security type #define CFG_NET_AUTH CYW43_AUTH_OPEN #endif #ifndef CFG_NET_CONN_TIMEOUT -//! max duration (milliseconds) for establishing wifi connection +//! Max duration (milliseconds) for establishing Wi-Fi connection #define CFG_NET_CONN_TIMEOUT 10e3 #endif @@ -36,47 +49,52 @@ #define CFG_NET_COUNTRY CYW43_COUNTRY_WORLDWIDE #endif #ifndef CFG_NET_COUNTRY -//! radio communications country +//! Radio communications country #define CFG_NET_COUNTRY CYW43_COUNTRY_NETHERLANDS #endif -/** \} */ +/// \} /** - * \name i2ctcp server configuration + * \name TCP server configuration * \{ */ #ifndef CFG_SRV_PORT -//! i2ctcp server port +//! TCP server port #define CFG_SRV_PORT 9191 #endif - #ifdef CFG_NET_DISABLE -//! disable the i2ctcp server +//! Disable the TCP server #define CFG_SRV_DISABLE #endif -/** \} */ +/// \} /** * \name I2C configuration * \{ */ #ifndef CFG_SDA_PIN -//! I^2^C SDA pin +//! I2C SDA pin #define CFG_SDA_PIN 16 #endif #ifndef CFG_SCL_PIN -//! I^2^C SCL pin +//! I2C SCL pin #define CFG_SCL_PIN 17 #endif -/** \} */ +/// \} +/** + * \name Auxiliary options + * \{ + */ #ifndef CFG_LED_PIN -//! status LED pin +//! Status LED pin #define CFG_LED_PIN CYW43_WL_GPIO_LED_PIN #endif - #ifndef CFG_PB_MOD_MAX -//! maximum number of simultaniously connected puzzle modules +//! Maximum number of simultaniously connected puzzle modules #define CFG_PB_MOD_MAX 8 #endif +/// \} + +/// \} diff --git a/main/i2c.h b/main/i2c.h index d1173c8..107a04d 100644 --- a/main/i2c.h +++ b/main/i2c.h @@ -1,5 +1,17 @@ #pragma once -//! looking for slave addresses and requesting updates +/** + * \ingroup main_tasks + * \{ + */ + +/** + * \brief I2C bus activity task + * + * This function does an initial bus scan for puzzle modules, and then goes + * into an infinite loop that periodically polls all puzzle modules for their + * global state. + */ void bus_task(); +/// \} diff --git a/main/index.dox b/main/index.dox new file mode 100644 index 0000000..aa2d07a --- /dev/null +++ b/main/index.dox @@ -0,0 +1,6 @@ +// vim:ft=doxygen +/** +\ingroup main +\defgroup main_tasks tasks +\brief Tasks +*/ diff --git a/main/init.h b/main/init.h index 73d2773..a24977d 100644 --- a/main/init.h +++ b/main/init.h @@ -1,11 +1,17 @@ #pragma once /** - * \brief initialize the main controller + * \ingroup main + * \{ + */ + +/** + * \brief Initialize the main controller * * This function only synchronously initializes the standard input/output (used - * for `printf` and `panic`), and queues all other types of initialization in - * the `init` task using FreeRTOS. + * for \c printf() and \c panic()), and queues all other types of + * initialization in the \c async_init() task using FreeRTOS. */ void init(); +/// \} diff --git a/main/sock.h b/main/sock.h index 38fca01..a151973 100644 --- a/main/sock.h +++ b/main/sock.h @@ -1,8 +1,17 @@ #pragma once -#include -#include +/** + * \ingroup main_tasks + * \{ + */ -//! start listening for TCP socket requests +/** + * \brief Listen for TCP socket messages + * + * This task starts a TCP server that listens for messages using \ref i2ctcp, + * and sends any received I2C messages (also using \ref i2ctcp). + */ void serve_task(); +/// \} + diff --git a/main/tasks.h b/main/tasks.h index 002f830..ac77a9e 100644 --- a/main/tasks.h +++ b/main/tasks.h @@ -1,4 +1,13 @@ #pragma once +/** + * \ingroup main + * \{ + */ + +/** + * \brief Register \ref main_tasks "all tasks" in FreeRTOS + */ void init_tasks(); +/// \} -- 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 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 From 9a24fe708770d717ecb8cbe45fe24922d21b5838 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Sat, 22 Jun 2024 17:40:40 +0200 Subject: tweak clang format settings --- .clang-format | 10 ++++++++-- makefile | 3 ++- 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.clang-format b/.clang-format index f180135..064fa96 100644 --- a/.clang-format +++ b/.clang-format @@ -1,11 +1,10 @@ --- AccessModifierOffset: -4 -AlignConsecutiveAssignments: true AllowShortIfStatementsOnASingleLine: AllIfsAndElse AllowShortLoopsOnASingleLine: true BasedOnStyle: LLVM BreakBeforeBraces: Attach -ColumnLimit: 180 +ColumnLimit: 80 EmptyLineBeforeAccessModifier: Always IndentAccessModifiers: false IndentCaseLabels: true @@ -14,6 +13,13 @@ Language: Cpp Standard: Cpp11 TabWidth: 4 UseTab: Always +PointerAlignment: Middle +SpaceAfterCStyleCast: true +AlignConsecutiveAssignments: + Enabled: false +AlignTrailingComments: + Kind: Leave +ReflowComments: false ... # vim: ft=yaml diff --git a/makefile b/makefile index 090877e..2ea1c3d 100644 --- a/makefile +++ b/makefile @@ -8,5 +8,6 @@ doxygen: Doxyfile FORCE FMT += $(shell git ls-files '*.h' '*.c' '*.cpp') format: FORCE clang-format -i $(FMT) - clang-tidy --fix-errors $(FMT) +# clang tidy doesn't work that well :/ +# clang-tidy --fix-errors $(FMT) -- cgit v1.2.3 From ccdcf5001c47820c41e9b962d8498602870289b5 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Sat, 22 Jun 2024 18:32:06 +0200 Subject: WIP RP2040 I2C workaround code --- lib/pbdrv/pb-route.c | 3 --- main/config.def.h | 20 ++++++++++++++------ main/i2c.c | 16 ++++++++++++---- main/init.c | 12 ++++++++---- main/pbdrv.c | 36 +++++++++++------------------------- main/pbdrv.h | 15 --------------- 6 files changed, 45 insertions(+), 57 deletions(-) diff --git a/lib/pbdrv/pb-route.c b/lib/pbdrv/pb-route.c index f5c32d6..5a7bd67 100644 --- a/lib/pbdrv/pb-route.c +++ b/lib/pbdrv/pb-route.c @@ -93,9 +93,6 @@ __weak void pb_route_cmd_magic_req(pb_msg_t * msg) { // // return early if magic doesn't match if (pb_memcmp(cmd->magic, pb_cmd_magic_req, sizeof(pb_cmd_magic_req)) != 0) return; - // FIXME: this should be removed (see handover: RP2040 I2C limitations) - pb_mod_blocking_delay_ms(2000); - pb_buf_t buf = pb_send_magic_res(); pb_send_reply(msg, &buf); pb_buf_free(&buf); diff --git a/main/config.def.h b/main/config.def.h index 0dae608..b3be5ed 100644 --- a/main/config.def.h +++ b/main/config.def.h @@ -72,13 +72,21 @@ * \name I2C configuration * \{ */ -#ifndef CFG_SDA_PIN -//! I2C SDA pin -#define CFG_SDA_PIN 16 +#ifndef CFG_SDA0_PIN +//! I2C 0 SDA pin +#define CFG_SDA0_PIN 16 #endif -#ifndef CFG_SCL_PIN -//! I2C SCL pin -#define CFG_SCL_PIN 17 +#ifndef CFG_SCL0_PIN +//! I2C 0 SCL pin +#define CFG_SCL0_PIN 17 +#endif +#ifndef CFG_SDA1_PIN +//! I2C 1 SDA pin +#define CFG_SDA1_PIN 18 +#endif +#ifndef CFG_SCL1_PIN +//! I2C 1 SCL pin +#define CFG_SCL1_PIN 19 #endif /// \} diff --git a/main/i2c.c b/main/i2c.c index 2503560..0f23a13 100644 --- a/main/i2c.c +++ b/main/i2c.c @@ -16,6 +16,18 @@ i2c_addr_t modules[CFG_PB_MOD_MAX]; size_t modules_size = 0; +static void bus_scan() { + pb_buf_t buf = pb_send_magic_req(); + + // check for all 7-bit addresses + uint16_t addr_max = 1 << 7; + for (uint16_t addr = 0x00; addr < addr_max; addr++) { + pb_i2c_send(addr, (uint8_t *) buf.data, buf.size); + } + + pb_buf_free(&buf); +} + static void state_exchange() { for (size_t i = 0; i < modules_size; i++) { pb_buf_t buf = pb_send_state_req(); @@ -28,10 +40,6 @@ void bus_task() { // do a scan of the bus bus_scan(); - // FIXME: this should be removed (see handover: RP2040 I2C limitations) - // wait for 5 seconds until all handshake responses are received - pb_mod_blocking_delay_ms(5e3); - while(1) { // send my state to all puzzle modules state_exchange(); diff --git a/main/init.c b/main/init.c index 6d29d19..d85c94d 100644 --- a/main/init.c +++ b/main/init.c @@ -29,11 +29,15 @@ static void init_wifi() { } static void init_i2c() { - gpio_set_function(CFG_SDA_PIN, GPIO_FUNC_I2C); - gpio_set_function(CFG_SCL_PIN, GPIO_FUNC_I2C); + gpio_set_function(CFG_SDA0_PIN, GPIO_FUNC_I2C); + gpio_set_function(CFG_SCL0_PIN, GPIO_FUNC_I2C); + gpio_set_function(CFG_SDA1_PIN, GPIO_FUNC_I2C); + gpio_set_function(CFG_SCL1_PIN, GPIO_FUNC_I2C); - gpio_pull_up(CFG_SDA_PIN); - gpio_pull_up(CFG_SCL_PIN); + gpio_pull_up(CFG_SDA0_PIN); + gpio_pull_up(CFG_SCL0_PIN); + gpio_pull_up(CFG_SDA1_PIN); + gpio_pull_up(CFG_SCL1_PIN); pb_setup(); } diff --git a/main/pbdrv.c b/main/pbdrv.c index 0624897..6a89253 100644 --- a/main/pbdrv.c +++ b/main/pbdrv.c @@ -14,7 +14,9 @@ #include #include -#define PB_I2C i2c0 +#define PB_I2C_S i2c0 +#define PB_I2C_M i2c1 + #define BUF_SIZE 256 #define MSGS_MAX 4 @@ -32,6 +34,8 @@ static void async_pb_i2c_recv(void * _msg, uint32_t _) { } static void msg_complete(i2c_msg_buf_t * msg) { + return pb_i2c_recv(msg->data, msg->size); + // defer pb_i2c_recv call to FreeRTOS scheduler as pb_i2c_recv takes // too long to return from an ISR xTimerPendFunctionCallFromISR(async_pb_i2c_recv, msg, 0, NULL); @@ -48,7 +52,7 @@ static void recv_event(i2c_inst_t *i2c, i2c_slave_event_t event) { switch (event) { case I2C_SLAVE_RECEIVE: { if (msg->size == BUF_SIZE) return; - msg->data[msg->size++] = i2c_read_byte_raw(PB_I2C); + msg->data[msg->size++] = i2c_read_byte_raw(PB_I2C_S); break; } case I2C_SLAVE_FINISH: { @@ -60,33 +64,15 @@ static void recv_event(i2c_inst_t *i2c, i2c_slave_event_t event) { } void pb_setup() { - i2c_init(PB_I2C, PB_CLOCK_SPEED_HZ); - i2c_slave_init(PB_I2C, PB_MOD_ADDR, &recv_event); + i2c_init(PB_I2C_S, PB_CLOCK_SPEED_HZ); + i2c_init(PB_I2C_M, PB_CLOCK_SPEED_HZ); + + i2c_slave_init(PB_I2C_S, PB_MOD_ADDR, &recv_event); } __weak void pb_i2c_send(i2c_addr_t addr, const uint8_t * buf, size_t sz) { - i2c_set_slave_mode(PB_I2C, false, PB_MOD_ADDR); - // false to write stop condition to i2c bus - i2c_write_timeout_us(PB_I2C, addr, buf, sz, false, PB_TIMEOUT_US); - - i2c_set_slave_mode(PB_I2C, true, PB_MOD_ADDR); -} - -void bus_scan() { - i2c_set_slave_mode(PB_I2C, false, PB_MOD_ADDR); - - pb_buf_t buf = pb_send_magic_req(); - - // check for all 7-bit addresses - uint16_t addr_max = 1 << 7; - for (uint16_t addr = 0x00; addr < addr_max; addr++) { - i2c_write_timeout_us(PB_I2C, addr, (uint8_t *) buf.data, buf.size, false, PB_TIMEOUT_US); - } - - pb_buf_free(&buf); - - i2c_set_slave_mode(PB_I2C, true, PB_MOD_ADDR); + i2c_write_timeout_us(PB_I2C_M, addr, buf, sz, false, PB_TIMEOUT_US); } void pb_mod_blocking_delay_ms(unsigned long ms) { diff --git a/main/pbdrv.h b/main/pbdrv.h index 9496aa9..89a4870 100644 --- a/main/pbdrv.h +++ b/main/pbdrv.h @@ -41,21 +41,6 @@ void pb_setup(); */ 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. - * - * \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 -- cgit v1.2.3 From 99dc241919bf6ea3cd3c06b77c7d8ad04c7d1fdf Mon Sep 17 00:00:00 2001 From: ThomasintAnker Date: Sat, 22 Jun 2024 20:11:26 +0200 Subject: Added i2c mcu research --- docs/research.adoc | 53 ++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 48 insertions(+), 5 deletions(-) diff --git a/docs/research.adoc b/docs/research.adoc index 88e43a7..80e32f2 100644 --- a/docs/research.adoc +++ b/docs/research.adoc @@ -404,7 +404,54 @@ non-experimental version of {cpp}. === Research question -How can we use I^2^C for the puzzle module detection? +How can we use I^2^C for the puzzle module detection and communication? + +=== Puzzle Module and Main Controller Communication + +Research from project group 21/22 shows that the I^2^C protocol is the best +option for communication between the puzzle modules and the main controller. +This research section extends the previous section about which MCU is suitable +for the puzzle bus, as we have found vital I^2^C limitations with the +controller we had chosen. See the handover document for the found limitations. + +// TODO: REFERENCES + +==== PIC16F15276 + +The PIC16F15276 MCU shows possibilities to be addressable as a slave while +being in master mode. However, this can not be confirmed without physical +testing due to the datasheet not mentioning whether it can or can not support +this function. It is possible to use this MCU without the aforementioned +functionality by manually changing the RCEN register to manually set the +MCU to 'receiving' I^2^C instructions, however this also requires a degree of +testing. + +// TODO: Add the following reference: +// PIC16F15276 - 25.2.4.3 +// https://ww1.microchip.com/downloads/aemDocuments/documents/MCU08/ProductDocuments/DataSheets/PIC16F15256-74-75-76-Microcontroller-Data-Sheet-40002305.pdf + +==== ESP32 + +The ESP32, like the PIC16F15276, shows possibilities to be addressable as a +slave while being in master mode, this also requires testing however. In the +case of the ESP32 it is possible to use the two I^2^C peripherals to achieve +roughly the same goal. This can be done by having one of the two peripherals +be initiated in master mode while the other peripheral is initiated in slave +mode. Allowing the MCU to send and recieve data to the I^2^C bus. This does +introduce increased code complexity but is a valid option if it goes through +testing. + +// TODO: Add the following reference: +// https://docs.espressif.com/projects/esp-idf/en/v4.3/esp32/api-reference/peripherals/i2c.html +// https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf#i2c +// https://www.bitsandparts.nl/documentation/482/ESP32_Specifications_EN_v1.pdf + +==== RP2040 + +As written in the handover document, the RP2040 does not support being +addressed as a slave while being in master mode. It does however, just like +the ESP32 have two I^2^C peripherals. Meaning the same theory can be applied +on this MCU. === Puzzle Module Detection @@ -448,10 +495,6 @@ answer this handshake and is therefor not recognized as a puzzle module. // TODO: references (API) & code block naming? -=== Welke microcontroller famillies zijn slave addresseerbaar while in master die ook multimaster vriendelijk zijn. - -=== multi master == standaard? - == Original Puzzle Box Functionality Research (Thomas) === Research question -- cgit v1.2.3 From c48d92585f59e5e8c55b62b7d1d2540a151688f8 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Sun, 23 Jun 2024 09:02:26 +0200 Subject: Arduino Uno dummy sketch restored + fixed --- puzzle/dummy/CMakeLists.txt | 11 +++++------ puzzle/dummy/FreeRTOSConfig.h | 4 ++-- 2 files changed, 7 insertions(+), 8 deletions(-) diff --git a/puzzle/dummy/CMakeLists.txt b/puzzle/dummy/CMakeLists.txt index 6acc4c8..1a228e0 100644 --- a/puzzle/dummy/CMakeLists.txt +++ b/puzzle/dummy/CMakeLists.txt @@ -11,14 +11,13 @@ add_compile_definitions(DEBUG) # 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]") +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_PORT GCC_ATMEGA) set(FREERTOS_HEAP 4) # used for testing @@ -36,10 +35,10 @@ add_executable(main mod.c ) -target_link_libraries(main +target_link_libraries(main PUBLIC pbdrv-mod ) -target_link_arduino_libraries(main + target_link_arduino_libraries(main PUBLIC core Wire ) diff --git a/puzzle/dummy/FreeRTOSConfig.h b/puzzle/dummy/FreeRTOSConfig.h index 1cfdd71..1d98f78 100644 --- a/puzzle/dummy/FreeRTOSConfig.h +++ b/puzzle/dummy/FreeRTOSConfig.h @@ -17,8 +17,8 @@ #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 (7 * 1024) +#define configTOTAL_HEAP_SIZE (1024) +// #define configTOTAL_HEAP_SIZE (7 * 1024) #define configCHECK_FOR_STACK_OVERFLOW 0 #define configUSE_MALLOC_FAILED_HOOK 0 #define configUSE_DAEMON_TASK_STARTUP_HOOK 0 -- cgit v1.2.3 From 381c80d765628f5d85b58b3b97e5a6bf3a0d1eb7 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Sun, 23 Jun 2024 09:22:50 +0200 Subject: clean up build files --- puzzle/dummy/CMakeLists.txt | 2 +- puzzle/dummy/makefile | 12 ------------ 2 files changed, 1 insertion(+), 13 deletions(-) diff --git a/puzzle/dummy/CMakeLists.txt b/puzzle/dummy/CMakeLists.txt index 1a228e0..c2633a1 100644 --- a/puzzle/dummy/CMakeLists.txt +++ b/puzzle/dummy/CMakeLists.txt @@ -38,7 +38,7 @@ add_executable(main target_link_libraries(main PUBLIC pbdrv-mod ) - target_link_arduino_libraries(main PUBLIC +target_link_arduino_libraries(main PUBLIC core Wire ) diff --git a/puzzle/dummy/makefile b/puzzle/dummy/makefile index 509d8e3..26e9157 100644 --- a/puzzle/dummy/makefile +++ b/puzzle/dummy/makefile @@ -6,15 +6,3 @@ 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 - -- cgit v1.2.3 From 4eec490cdfdcf6ea4283c2d069ef147fe2365d2b Mon Sep 17 00:00:00 2001 From: ThomasintAnker Date: Sun, 23 Jun 2024 10:15:55 +0200 Subject: Improved i2c researcg --- docs/research.adoc | 64 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 40 insertions(+), 24 deletions(-) diff --git a/docs/research.adoc b/docs/research.adoc index 80e32f2..9da6303 100644 --- a/docs/research.adoc +++ b/docs/research.adoc @@ -415,43 +415,59 @@ for the puzzle bus, as we have found vital I^2^C limitations with the controller we had chosen. See the handover document for the found limitations. // TODO: REFERENCES +// TODO: Find synonym for 'vital' -==== PIC16F15276 +==== MCUs Supporting Master Addressable as Slave -The PIC16F15276 MCU shows possibilities to be addressable as a slave while -being in master mode. However, this can not be confirmed without physical -testing due to the datasheet not mentioning whether it can or can not support -this function. It is possible to use this MCU without the aforementioned -functionality by manually changing the RCEN register to manually set the -MCU to 'receiving' I^2^C instructions, however this also requires a degree of -testing. +===== Atmega328p + +The Atmega328p has multi-master support, where the MCU is addressable as a +slave while being in master mode. This has been confirmed using the Arduino +wire library on both the Arduino Mega and the Arduino Uno. + +===== PIC16F15276 & ESP32 + +Both the PIC16F15276 and the ESP32 MCUs show possibilities to be addressable as a slave while being in master mode. However, at the moment of writing this +has yet to be tested. // TODO: Add the following reference: // PIC16F15276 - 25.2.4.3 // https://ww1.microchip.com/downloads/aemDocuments/documents/MCU08/ProductDocuments/DataSheets/PIC16F15256-74-75-76-Microcontroller-Data-Sheet-40002305.pdf -==== ESP32 - -The ESP32, like the PIC16F15276, shows possibilities to be addressable as a -slave while being in master mode, this also requires testing however. In the -case of the ESP32 it is possible to use the two I^2^C peripherals to achieve -roughly the same goal. This can be done by having one of the two peripherals -be initiated in master mode while the other peripheral is initiated in slave -mode. Allowing the MCU to send and recieve data to the I^2^C bus. This does -introduce increased code complexity but is a valid option if it goes through -testing. - // TODO: Add the following reference: // https://docs.espressif.com/projects/esp-idf/en/v4.3/esp32/api-reference/peripherals/i2c.html // https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf#i2c // https://www.bitsandparts.nl/documentation/482/ESP32_Specifications_EN_v1.pdf -==== RP2040 +==== Alternatives + +===== PIC16F15276 Registers + +In the case of the PIC16F15276 not support master addressable as slave the +following approach would most likely work. As the PIC16F15276 uses specific +registers for its master receive functions, namely the RCEN register, it can +be manually set to receive data from the I^2^C bus. However, this also has +yet to be tested. + +// TODO: Add the following reference: +// PIC16F15276 - 25.2.4.3 +// https://ww1.microchip.com/downloads/aemDocuments/documents/MCU08/ProductDocuments/DataSheets/PIC16F15256-74-75-76-Microcontroller-Data-Sheet-40002305.pdf + +===== Multiple I^2^C Peripherals + +==== ESP32 & RP2040 + +The ESP32 and the RP2040 both have multiple peripherals for I^2^C +communication, while also supporting simultaneous configuration. This allows +both two I^2^C peripherals to be active, one being configured as a master and +the other being configured as a slave. This enables the controller to send and +receive data to the I^2^C bus without much difficulty. This does introduce +increased code complexity but is a valid option if it is succesful in testing. -As written in the handover document, the RP2040 does not support being -addressed as a slave while being in master mode. It does however, just like -the ESP32 have two I^2^C peripherals. Meaning the same theory can be applied -on this MCU. +// TODO: Add the following reference: +// https://docs.espressif.com/projects/esp-idf/en/v4.3/esp32/api-reference/peripherals/i2c.html +// https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf#i2c +// https://www.bitsandparts.nl/documentation/482/ESP32_Specifications_EN_v1.pdf === Puzzle Module Detection -- cgit v1.2.3 From 9664deb3e817b616dd1e8f73a89c0703a0771464 Mon Sep 17 00:00:00 2001 From: Elwin Date: Sun, 23 Jun 2024 11:31:15 +0200 Subject: Neotrellis Freertos support --- puzzle/dummy/CMakeLists.txt | 4 +- puzzle/neo/CMakeLists.txt | 52 +++++++++++ puzzle/neo/FreeRTOSConfig.h | 52 +++++++++++ puzzle/neo/arduino-neopuzzle/arduino-neopuzzle.ino | 95 -------------------- puzzle/neo/console-neopuzzle/neo.cpp | 100 --------------------- puzzle/neo/lib | 1 + puzzle/neo/main.cpp | 98 ++++++++++++++++++++ puzzle/neo/makefile | 20 +++++ puzzle/neo/mod.c | 6 ++ puzzle/readme.md | 2 + 10 files changed, 233 insertions(+), 197 deletions(-) create mode 100644 puzzle/neo/CMakeLists.txt create mode 100644 puzzle/neo/FreeRTOSConfig.h delete mode 100644 puzzle/neo/arduino-neopuzzle/arduino-neopuzzle.ino delete mode 100644 puzzle/neo/console-neopuzzle/neo.cpp create mode 120000 puzzle/neo/lib create mode 100644 puzzle/neo/main.cpp create mode 100644 puzzle/neo/makefile create mode 100644 puzzle/neo/mod.c diff --git a/puzzle/dummy/CMakeLists.txt b/puzzle/dummy/CMakeLists.txt index 6acc4c8..0d508ae 100644 --- a/puzzle/dummy/CMakeLists.txt +++ b/puzzle/dummy/CMakeLists.txt @@ -36,10 +36,10 @@ add_executable(main mod.c ) -target_link_libraries(main +target_link_libraries(main PUBLIC pbdrv-mod ) -target_link_arduino_libraries(main +target_link_arduino_libraries(main PUBLIC core Wire ) diff --git a/puzzle/neo/CMakeLists.txt b/puzzle/neo/CMakeLists.txt new file mode 100644 index 0000000..db3aadc --- /dev/null +++ b/puzzle/neo/CMakeLists.txt @@ -0,0 +1,52 @@ +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 + Adafruit_seesaw + ) + +#Adafruit workarround +target_link_arduino_libraries(_arduino_lib_Adafruit_seesaw_Library PUBLIC "Adafruit BusIO") + +target_enable_arduino_upload(main) + diff --git a/puzzle/neo/FreeRTOSConfig.h b/puzzle/neo/FreeRTOSConfig.h new file mode 100644 index 0000000..c0acc49 --- /dev/null +++ b/puzzle/neo/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/neo/arduino-neopuzzle/arduino-neopuzzle.ino b/puzzle/neo/arduino-neopuzzle/arduino-neopuzzle.ino deleted file mode 100644 index b334677..0000000 --- a/puzzle/neo/arduino-neopuzzle/arduino-neopuzzle.ino +++ /dev/null @@ -1,95 +0,0 @@ -#include -#include - -#define MATRIX_SIZE 8 -#define LED_COLOR_ON 0xFFFFFF // Color of the LEDs in ON state -#define LED_COLOR_OFF 0x000000 // Color of the LEDs in OFF state - -Adafruit_NeoTrellis t_array[MATRIX_SIZE / 4][MATRIX_SIZE / 4] = { - {Adafruit_NeoTrellis(0x2E), Adafruit_NeoTrellis(0x2F)}, - {Adafruit_NeoTrellis(0x30), Adafruit_NeoTrellis(0x32)} -}; - -Adafruit_MultiTrellis trellis((Adafruit_NeoTrellis *)t_array, MATRIX_SIZE / 4, MATRIX_SIZE / 4); - -bool neoMatrix[MATRIX_SIZE][MATRIX_SIZE]; // To track state of each pixel - -enum NeoState { - NEO_UNINITIALIZED, - NEO_PLAYING, - NEO_SOLVED -}; - -NeoState neoState = NEO_UNINITIALIZED; - -void setup() { - Serial.begin(115200); - while (!Serial); // Wait for Serial to be ready - - if (!trellis.begin()) { - Serial.println("Failed to initialize NeoTrellis"); - while (1) delay(1); - } - - // Initialize the matrix with a checkerboard pattern - bool toggle = false; - for (int i = 0; i < MATRIX_SIZE; i++) { - for (int j = 0; j < MATRIX_SIZE; j++) { - neoMatrix[i][j] = toggle; - toggle = !toggle; - trellis.setPixelColor(i * MATRIX_SIZE + j, neoMatrix[i][j] ? LED_COLOR_ON : LED_COLOR_OFF); - } - toggle = !toggle; - } - trellis.show(); - neoState = NEO_PLAYING; - - // Register the callback for each key - for (int i = 0; i < MATRIX_SIZE * MATRIX_SIZE; i++) { - trellis.activateKey(i, SEESAW_KEYPAD_EDGE_RISING, true); - trellis.activateKey(i, SEESAW_KEYPAD_EDGE_FALLING, true); - trellis.registerCallback(i, buttonCallback); - } -} - -void loop() { - trellis.read(); // Process button events - delay(20); -} - -TrellisCallback buttonCallback(keyEvent evt) { - int x = evt.bit.NUM / MATRIX_SIZE; - int y = evt.bit.NUM % MATRIX_SIZE; - - if (evt.bit.EDGE == SEESAW_KEYPAD_EDGE_RISING) { - toggleAdjacentLEDs(x, y); - trellis.show(); - if (isNeoPuzzleSolved()) { - neoState = NEO_SOLVED; - Serial.println("The NeoTrellis puzzle is solved!"); - } - } - return 0; -} - -void toggleAdjacentLEDs(int x, int y) { - for (int dx = -1; dx <= 1; ++dx) { - for (int dy = -1; dy <= 1; ++dy) { - if (dx == 0 && dy == 0) continue; // Skip the center button itself - int nx = x + dx, ny = y + dy; - if (nx >= 0 && nx < MATRIX_SIZE && ny >= 0 && ny < MATRIX_SIZE) { - neoMatrix[nx][ny] = !neoMatrix[nx][ny]; - trellis.setPixelColor(nx * MATRIX_SIZE + ny, neoMatrix[nx][ny] ? LED_COLOR_ON : LED_COLOR_OFF); - } - } - } -} - -bool isNeoPuzzleSolved() { - for (int i = 0; i < MATRIX_SIZE; i++) { - for (int j = 0; j < MATRIX_SIZE; j++) { - if (neoMatrix[i][j]) return false; // If any LED is on, puzzle is not solved - } - } - return true; -} diff --git a/puzzle/neo/console-neopuzzle/neo.cpp b/puzzle/neo/console-neopuzzle/neo.cpp deleted file mode 100644 index 56d90f7..0000000 --- a/puzzle/neo/console-neopuzzle/neo.cpp +++ /dev/null @@ -1,100 +0,0 @@ -#include -#include - -#define MATRIX_SIZE 8 - -enum NeoState { - NEO_UNINITIALIZED, - NEO_PLAYING, - NEO_SOLVED -}; - -// Simulate the 8x8 LED matrix with a 2D array -std::array, MATRIX_SIZE> neoMatrix; - -NeoState neoState = NEO_UNINITIALIZED; - -// Helper function to toggle LEDs if within bounds -void toggleIfValid(int x, int y) { - if (x >= 0 && x < MATRIX_SIZE && y >= 0 && y < MATRIX_SIZE) { - neoMatrix[x][y] = !neoMatrix[x][y]; - } -} - -void initializeNeoMatrix() { - // The initial pattern from the Appendix A example (assuming red is 'true'/on and white is 'false'/off) - std::array, MATRIX_SIZE> initialPattern = {{ - {false, true, false, true, false, true, false, true}, - {true, false, true, false, true, false, true, false}, - {false, true, false, true, false, true, false, true}, - {true, false, true, false, true, false, true, false}, - {false, true, false, true, false, true, false, true}, - {true, false, true, false, true, false, true, false}, - {false, true, false, true, false, true, false, true}, - {true, false, true, false, true, false, true, false} - }}; - - for (int i = 0; i < MATRIX_SIZE; i++) { - for (int j = 0; j < MATRIX_SIZE; j++) { - neoMatrix[i][j] = initialPattern[i][j]; - } - } - - neoState = NEO_PLAYING; -} - - -void printNeoMatrix() { - // Print the matrix state to the console - for (int i = 0; i < MATRIX_SIZE; i++) { - for (int j = 0; j < MATRIX_SIZE; j++) { - std::cout << (neoMatrix[i][j] ? 1 : 0) << " "; - } - std::cout << std::endl; - } -} - -void toggleAdjacentLEDs(int x, int y) { - // Toggle the LED at (x, y) and adjacent LEDs - toggleIfValid(x, y); // Center - toggleIfValid(x - 1, y); // Up - toggleIfValid(x + 1, y); // Down - toggleIfValid(x, y - 1); // Left - toggleIfValid(x, y + 1); // Right -} - - -bool isNeoPuzzleSolved() { - for (int i = 0; i < MATRIX_SIZE; i++) { - for (int j = 0; j < MATRIX_SIZE; j++) { - if (neoMatrix[i][j]) return false; // If any LED is on, puzzle is not solved - } - } - return true; -} - -/// Integration needed -int main() { - initializeNeoMatrix(); - printNeoMatrix(); - - while (neoState != NEO_SOLVED) { - int x, y; - std::cout << "Enter the coordinates of the button pressed (x y): "; - std::cin >> x >> y; - - if (x >= 0 && x < MATRIX_SIZE && y >= 0 && y < MATRIX_SIZE) { - toggleAdjacentLEDs(x, y); - printNeoMatrix(); - - if (isNeoPuzzleSolved()) { - neoState = NEO_SOLVED; - std::cout << "The NeoTrellis puzzle is solved!\n"; - } - } else { - std::cout << "Invalid coordinates. Please enter values between 0 and " << MATRIX_SIZE - 1 << ".\n"; - } - } - - return 0; -} diff --git a/puzzle/neo/lib b/puzzle/neo/lib new file mode 120000 index 0000000..58677dd --- /dev/null +++ b/puzzle/neo/lib @@ -0,0 +1 @@ +../../lib \ No newline at end of file diff --git a/puzzle/neo/main.cpp b/puzzle/neo/main.cpp new file mode 100644 index 0000000..13a6859 --- /dev/null +++ b/puzzle/neo/main.cpp @@ -0,0 +1,98 @@ +#include +#include +#include + +#define MATRIX_SIZE 8 +#define LED_COLOR_ON 0xFFFFFF // Color of the LEDs in ON state +#define LED_COLOR_OFF 0x000000 // Color of the LEDs in OFF state + +Adafruit_NeoTrellis t_array[MATRIX_SIZE / 4][MATRIX_SIZE / 4] = { + {Adafruit_NeoTrellis(0x2E), Adafruit_NeoTrellis(0x2F)}, + {Adafruit_NeoTrellis(0x30), Adafruit_NeoTrellis(0x32)} +}; + +Adafruit_MultiTrellis trellis((Adafruit_NeoTrellis *)t_array, MATRIX_SIZE / 4, MATRIX_SIZE / 4); + +bool neoMatrix[MATRIX_SIZE][MATRIX_SIZE]; // To track state of each pixel + +enum NeoState { + NEO_UNINITIALIZED, + NEO_PLAYING, + NEO_SOLVED +}; + +NeoState neoState = NEO_UNINITIALIZED; + +void toggleAdjacentLEDs(int x, int y) { + for (int dx = -1; dx <= 1; ++dx) { + for (int dy = -1; dy <= 1; ++dy) { + if (dx == 0 && dy == 0) continue; // Skip the center button itself + int nx = x + dx, ny = y + dy; + if (nx >= 0 && nx < MATRIX_SIZE && ny >= 0 && ny < MATRIX_SIZE) { + neoMatrix[nx][ny] = !neoMatrix[nx][ny]; + trellis.setPixelColor(nx * MATRIX_SIZE + ny, neoMatrix[nx][ny] ? LED_COLOR_ON : LED_COLOR_OFF); + } + } + } +} + + +bool isNeoPuzzleSolved() { + for (int i = 0; i < MATRIX_SIZE; i++) { + for (int j = 0; j < MATRIX_SIZE; j++) { + if (neoMatrix[i][j]) return false; // If any LED is on, puzzle is not solved + } + } + return true; +} + +TrellisCallback buttonCallback(keyEvent evt) { + int x = evt.bit.NUM / MATRIX_SIZE; + int y = evt.bit.NUM % MATRIX_SIZE; + + if (evt.bit.EDGE == SEESAW_KEYPAD_EDGE_RISING) { + toggleAdjacentLEDs(x, y); + trellis.show(); + if (isNeoPuzzleSolved()) { + neoState = NEO_SOLVED; + Serial.println("The NeoTrellis puzzle is solved!"); + } + } + return 0; +} + + +void setup() { + Serial.begin(115200); + while (!Serial); // Wait for Serial to be ready + + if (!trellis.begin()) { + Serial.println("Failed to initialize NeoTrellis"); + while (1) delay(1); + } + + // Initialize the matrix with a checkerboard pattern + bool toggle = false; + for (int i = 0; i < MATRIX_SIZE; i++) { + for (int j = 0; j < MATRIX_SIZE; j++) { + neoMatrix[i][j] = toggle; + toggle = !toggle; + trellis.setPixelColor(i * MATRIX_SIZE + j, neoMatrix[i][j] ? LED_COLOR_ON : LED_COLOR_OFF); + } + toggle = !toggle; + } + trellis.show(); + neoState = NEO_PLAYING; + + // Register the callback for each key + for (int i = 0; i < MATRIX_SIZE * MATRIX_SIZE; i++) { + trellis.activateKey(i, SEESAW_KEYPAD_EDGE_RISING, true); + trellis.activateKey(i, SEESAW_KEYPAD_EDGE_FALLING, true); + trellis.registerCallback(i, buttonCallback); + } +} + +void loop() { + trellis.read(); // Process button events + delay(20); +} \ No newline at end of file diff --git a/puzzle/neo/makefile b/puzzle/neo/makefile new file mode 100644 index 0000000..509d8e3 --- /dev/null +++ b/puzzle/neo/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/neo/mod.c b/puzzle/neo/mod.c new file mode 100644 index 0000000..058a585 --- /dev/null +++ b/puzzle/neo/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; + diff --git a/puzzle/readme.md b/puzzle/readme.md index 959c506..21cddd3 100644 --- a/puzzle/readme.md +++ b/puzzle/readme.md @@ -19,6 +19,8 @@ of these subfolders, make sure you have done the following: - Install the official Arduino IDE - Open "Tools" > "Board" > "Board manager" - Install the "Arduino AVR Boards" package (1.8.6 works at the time of writing) +- Install the Adafruit seesaw library and dependicies (for the neotrellis puzzle) +- Install the TM1637 library from Avishay Orpaz [arduino-cmake]: https://github.com/a9183756-gh/Arduino-CMake-Toolchain -- cgit v1.2.3 From 15b0af2a1378d2a1fbd68affd96d0cb3f6badf89 Mon Sep 17 00:00:00 2001 From: Elwin Hammer Date: Sun, 23 Jun 2024 12:19:40 +0200 Subject: Updated FAT document --- docs/fat.adoc | 289 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 289 insertions(+) create mode 100644 docs/fat.adoc diff --git a/docs/fat.adoc b/docs/fat.adoc new file mode 100644 index 0000000..29622e2 --- /dev/null +++ b/docs/fat.adoc @@ -0,0 +1,289 @@ +:document: Factory Acceptance Test +include::share/meta.adoc[] + +== Introduction +// TODO: Make an intro + +=== Compatibility matrix +[cols="1,9*^", options="header"] +|=== +| Requirement \\ Test | T-01 | T-02 | T-03 | T-04 | T-05 | T-06 | T-07 | T-08 | T-09 + +| xref:reqs.adoc#R-001[R-001] | xref:#Test-01[✓] | | | | | | | | +| xref:reqs.adoc#R-002[R-002] | xref:#Test-01[✓] | | | | | | | | +| xref:reqs.adoc#R-003[R-003] | xref:#Test-01[✓] | | | | | | | | +| xref:reqs.adoc#R-004[R-004] | xref:#Test-01[✓] | | | | | | | | +| xref:reqs.adoc#R-005[R-005] | xref:#Test-01[✓] | | | | | | | | +| xref:reqs.adoc#R-034[R-034] | xref:#Test-01[✓] | | | | | | | | +| xref:reqs.adoc#R-036[R-036] | | xref:#Test-02[✓] | | | | | | | +| xref:reqs.adoc#R-037[R-037] | | xref:#Test-02[✓] | | | | | | | +| xref:reqs.adoc#R-038[R-038] | | xref:#Test-02[✓] | | | | | | | +| xref:reqs.adoc#R-166[R-166] | | xref:#Test-02[✓] | | | | | | | +| xref:reqs.adoc#R-169[R-169] | | xref:#Test-02[✓] | | | | | | | +| xref:reqs.adoc#R-075[R-075] | | | xref:#Test-03[✓] | | | | | | +| xref:reqs.adoc#R-076[R-076] | | | xref:#Test-03[✓] | | | | | | +| xref:reqs.adoc#R-081[R-081] | | | xref:#Test-03[✓] | | | | | | +| xref:reqs.adoc#R-085[R-085] | | | | xref:#Test-04[✓] | | | | | +| xref:reqs.adoc#R-087[R-087] | | | | xref:#Test-04[✓] | | | | | +| xref:reqs.adoc#R-150[R-150] | | | | | xref:#Test-05[✓] | | | | +| xref:reqs.adoc#R-082[R-082] | | | | | xref:#Test-05[✓] | | | | +| xref:reqs.adoc#R-083[R-083] | | | | | xref:#Test-05[✓] | | | | +| xref:reqs.adoc#R-084[R-084] | | | | | xref:#Test-05[✓] | | | | +| xref:reqs.adoc#R-167[R-167] | | | | | | xref:#Test-06[✓] | | | +| xref:reqs.adoc#R-168[R-168] | | | | | | xref:#Test-06[✓] | | | +| xref:reqs.adoc#R-027[R-027] | | | | | | | xref:#Test-07[✓] | | +| xref:reqs.adoc#R-048[R-048] | | | | | | | | xref:#Test-08[✓] | +| xref:reqs.adoc#R-049[R-049] | | | | | | | | xref:#Test-08[✓] | +| xref:reqs.adoc#R-050[R-050] | | | | | | | | xref:#Test-08[✓] | +| xref:reqs.adoc#R-051[R-051] | | | | | | | | xref:#Test-08[✓] | +| xref:reqs.adoc#R-052[R-052] | | | | | | | | xref:#Test-08[✓] | +| xref:reqs.adoc#R-053[R-053] | | | | | | | | xref:#Test-08[✓] | +| xref:reqs.adoc#R-089[R-089] | | | | | | | | | xref:#Test-09[✓] +| xref:reqs.adoc#R-090[R-090] | | | | | | | | | xref:#Test-09[✓] +| xref:reqs.adoc#R-091[R-091] | | | | | | | | | xref:#Test-09[✓] +| xref:reqs.adoc#R-127[R-127] | | | | | | | | | xref:#Test-09[✓] +| xref:reqs.adoc#R-128[R-128] | | | | | | | | | xref:#Test-09[✓] +| xref:reqs.adoc#R-129[R-129] | | | | | | | | | xref:#Test-09[✓] +| xref:reqs.adoc#R-134[R-134] | | | | | | | | | xref:#Test-09[✓] +| xref:reqs.adoc#R-135[R-135] | | | | | | | | | xref:#Test-09[✓] +| xref:reqs.adoc#R-165[R-165] | | | | | | | | | xref:#Test-09[✓] +|=== + +=== Neotrellis-puzzle + +[#Test-01] +==== Test 01 + +===== Covered requirements +* Technical requirements +** xref:reqs.adoc#R-034[R-034] (neotrellis function & Arduino init.) +* Functional requirements +** *None* + +===== Additional setup +*None* + +===== Test +. Turn both the Arduino and the neotrellis modules on + +===== Result +* [ ] Verify that the neotrellis modules emit light in different colors (init. state). + +[#Test-02] +==== Test 02 + +===== Covered requirements +* Technical requirements +** xref:reqs.adoc#R-166[R-166] (Arduino & RPI Pico I²C communication) +** xref:reqs.adoc#R-169[R-169] (Arduino & neotrellis I²C communication) +* Functional requirements +** xref:reqs.adoc#R-036[R-036] (game logic) +** xref:reqs.adoc#R-037[R-037] (neotrellis led color) +** xref:reqs.adoc#R-038[R-038] (game d.o.d.) + +===== Additional setup +* [ ] Connect the Arduino to the maincontroller (RPI Pico) using the I²C interface, pull-up resistors and a common ground. + +===== Test +. Turn both the Arduino and the neotrellis modules on. +. Wait for a few seconds. +. Turn the RPI Pico on. +. Wait for another few seconds. +. Play the game until you have succeeded. + +===== Result +* [ ] Verify that the puzzle module tries to communicate with the maincontroller. +* [ ] Verify that a light should be blinking on one of the neotrellis modules. +* [ ] Press one of the emitting buttons and check if the buttons surrounding it will light +* [ ] Play the game until no buttons emit light anymore and check if the main controllers wants to load the next puzzle. + +=== Vault-puzzle + +[#Test-03] +==== Test 03 + +===== Covered requirements +* Technical requirements +** xref:reqs.adoc#R-151[R-151] (4x 7-seg. type & connection) +* Functional requirements +** xref:reqs.adoc#R-075[R-075] (4x 7-seg. availability) +** xref:reqs.adoc#R-076[R-076] (ventilation) +** xref:reqs.adoc#R-081[R-081] (4x 7-seg. operation) + +===== Additional setup +* [ ] Connect the Arduino to the maincontroller (RPI Pico) using the I²C interface, pull-up resistors and a common ground. + +===== Test +. Turn the Arduino on. +. Wait for a few seconds. +. Turn the RPI Pico on. +. Wait until the Arduino is in its init. state. + +===== Result +* [ ] Verify that there is a 4x 7-seg. display and working. +* [ ] Verify that the puzzle module tries to communicate with the maincontroller +* [ ] Check if after the unit. state (blinking zero's) there is a letter and number displayed on the 4x 7 seg. display. + +[#Test-04] +==== Test 04 + +===== Covered requirements +* Technical requirements +** *None* +* Functional requirements +** xref:reqs.adoc#R-085[R-085] (4x 7-seg. operation by passing the game) +** xref:reqs.adoc#R-087[R-087] (4x 7-seg. operation by failing the game) + +===== Additional setup +*None* + +===== Test +. Turn the Arduino on. +. Wait for a few seconds. +. Turn the RPI Pico on. +. Play the game correctly for 2 levels. +. Play one level incorrectly. + +===== Result +* [ ] Verify a new code is generated each time you level-up +* [ ] Verify that an older code is presented each time you level-down + +[#Test-05] +==== Test 05 + +===== Covered requirements +* Technical requirements +** xref:reqs.adoc#R-150[R-150] (button matrix) +* Functional requirements +** xref:reqs.adoc#R-082[R-082] (game logic: leveling) +** xref:reqs.adoc#R-083[R-083] (game logic: level) +** xref:reqs.adoc#R-084[R-084] (game logic: succeeding level) + +===== Additional setup +* Connect the vault solenoid valve to the Arduino using a MOSFET or other type of driver. + +===== Test +. Turn the Arduino on. +. Wait for a few seconds. +. Turn the RPI Pico on. +. Play the game correctly until you reach the end of the game. + +===== Result +* [ ] Verify that at the last level a code should be displayed that can be used to disarm the "bomb". +* [ ] Check if the vault itself will unlock and lock again after the game is reset. + +=== Puzzle Box Requirements + +[#Test-06] +==== Puzzle Box Basic Setup and Verification + +===== Covered requirements +* Functional requirements +** xref:reqs.adoc#R-1[R-1] (Puzzle box dimensions) +** xref:reqs.adoc#R-2[R-2] (Extension on the sides and top) +** xref:reqs.adoc#R-3[R-3] (Flat bottom) +** xref:reqs.adoc#R-4[R-4] (Key switch at the bottom of the NeoTrellis puzzle) +** xref:reqs.adoc#R-5[R-5] (Indicator LED at the bottom of the NeoTrellis puzzle) + +===== Additional setup +* [ ] Measure the dimensions of the puzzle box to ensure compliance with R-1. +* [ ] Inspect the physical structure for extensions beyond specified limits. +* [ ] Confirm flatness of the bottom surface. +* [ ] Locate and identify the key switch and indicator LED as per design specifications. + +===== Test +. Measure and record the dimensions of the puzzle box. +. Examine the extensions, if any, on the sides and top of the box. +. Test the flatness of the bottom of the box. +. Verify the functionality of the key switch. +. Check the initial state of the indicator LED when power is supplied to the puzzle box. + +===== Result +* [ ] Puzzle box dimensions are within the specified range of 30x30x30 cm ± 5%. +* [ ] No excess extension beyond 5 cm on any side or the top. +* [ ] The bottom of the puzzle box is confirmed flat. +* [ ] The key switch operates as intended. +* [ ] The indicator LED functions correctly and is visible. + +=== Game Functional Requirements Testing + +[#Test-07] +==== Puzzle Module Control Tests + +===== Covered requirements +* Functional requirements +** xref:reqs.adoc#R-167[R-167] (Manual reset capability of a puzzle module) +** xref:reqs.adoc#R-168[R-168] (Manual solve capability of a puzzle module) + +===== Additional setup +* [ ] Ensure access to the game operator controls for manual reset and solve. + +===== Test +. Perform a manual reset of a puzzle module during gameplay to verify it resets correctly. +. Manually set a puzzle module as solved and observe if the system acknowledges the solve appropriately. + +===== Result +* [ ] Puzzle module resets correctly when manually triggered. +* [ ] Puzzle module is recognized as solved when set manually. + +[#Test-08] +==== Puzzle Difficulty Verification + +===== Covered requirements +* Functional requirements +** xref:reqs.adoc#R-27[R-27] (Puzzle solvability without prior knowledge) + +===== Test +. Invite testers unfamiliar with the game to solve the puzzles. +. Record the ease or difficulty encountered by the testers in solving the puzzles. + +===== Result +* [ ] Testers without prior knowledge are able to solve the puzzles, indicating appropriate difficulty levels. + +=== Hardware Puzzle Module Testing + +[#Test-09] +==== Initial Setup Verification + +===== Covered requirements +* Functional requirements +** xref:reqs.adoc#R-58[R-58] (Game operator initial switch position) +** xref:reqs.adoc#R-59[R-59] (Game operator initial potentiometer position) + +===== Additional setup +* [ ] Access to hardware puzzle board controls for switches and potentiometers. + +===== Test +. Manually set all switches on the hardware puzzle board to the down position. +. Turn all potentiometers fully to the left to their zero position. + +===== Result +* [ ] All switches are confirmed to be in the down position at the start of the game. +* [ ] All potentiometers are set to zero at the beginning of the game, indicating correct initial setup. + +[#Test-10] +==== Hardware Component Functionality + +===== Covered requirements +* Functional requirements +** xref:reqs.adoc#R-48[R-48] (Presence of eight switches) +** xref:reqs.adoc#R-49[R-49] (Combinatorial circuit functionality) +** xref:reqs.adoc#R-50[R-50] (7-segment 4-digit display presence and functionality) +** xref:reqs.adoc#R-51[R-51] (Four potentiometers) +** xref:reqs.adoc#R-52[R-52] (Blue LED displaying Morse code) +** xref:reqs.adoc#R-53[R-53] (Green LED indicating solved state) + +===== Additional setup +* [ ] Ensure all hardware components are installed as per the design specifications. + +===== Test +. Verify the presence and functionality of eight switches linked to the combinatorial circuit. +. Confirm that the combinatorial circuit operates as depicted in the provided diagram. +. Check the 7-segment display and potentiometers for correct operation. +. Observe the blue LED for Morse code display and green LED for indicating the puzzle is solved. + +===== Result +* [ ] Eight switches are operational and affect the combinatorial circuit as expected. +* [ ] The combinatorial circuit correctly processes inputs to produce the expected output. +* [ ] The 7-segment display and potentiometers function correctly, displaying values as manipulated. +* [ ] Blue LED successfully displays Morse code, and green LED lights up when the puzzle is solved. -- cgit v1.2.3 From 648d87ea98ec39d5745d36a0b5c5078cd9491211 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Sun, 23 Jun 2024 13:31:49 +0200 Subject: place rp2040 back in pbdrv --- lib/pbdrv/CMakeLists.txt | 6 +-- lib/pbdrv/drv/arduino/include.cmake | 6 +-- lib/pbdrv/drv/arduino/index.dox | 20 +++++---- lib/pbdrv/drv/arduino/mod.cpp | 42 ++++++------------- lib/pbdrv/drv/index.dox | 13 ------ lib/pbdrv/drv/rp2040/include.cmake | 11 +++++ lib/pbdrv/drv/rp2040/index.dox | 31 ++++++++++++++ lib/pbdrv/drv/rp2040/mod.c | 49 ++++++++++++++++++++++ lib/pbdrv/drv/rp2040/pb-mod.h | 21 ++++++++++ lib/pbdrv/ext/freertos/include.cmake | 2 +- lib/pbdrv/index.dox | 13 +++--- main/CMakeLists.txt | 4 +- main/i2c.c | 1 - main/init.c | 2 +- main/mod.c | 7 ++++ main/pbdrv.c | 81 ------------------------------------ main/pbdrv.h | 49 ---------------------- puzzle/dummy/CMakeLists.txt | 3 +- 18 files changed, 157 insertions(+), 204 deletions(-) create mode 100644 lib/pbdrv/drv/rp2040/include.cmake create mode 100644 lib/pbdrv/drv/rp2040/index.dox create mode 100644 lib/pbdrv/drv/rp2040/mod.c create mode 100644 lib/pbdrv/drv/rp2040/pb-mod.h delete mode 100644 main/pbdrv.c delete mode 100644 main/pbdrv.h diff --git a/lib/pbdrv/CMakeLists.txt b/lib/pbdrv/CMakeLists.txt index 998ed4d..903a3b4 100644 --- a/lib/pbdrv/CMakeLists.txt +++ b/lib/pbdrv/CMakeLists.txt @@ -23,7 +23,7 @@ add_library(pbdrv STATIC pb-buf.c ) target_include_directories(pbdrv SYSTEM INTERFACE .) -target_link_libraries(pbdrv mpack) +target_link_libraries(pbdrv PRIVATE mpack) # puzzle bus *module* specific code add_library(pbdrv-mod OBJECT @@ -32,9 +32,9 @@ add_library(pbdrv-mod OBJECT pb-route.c ) target_include_directories(pbdrv-mod SYSTEM INTERFACE .) -target_link_libraries(pbdrv-mod pbdrv) +target_link_libraries(pbdrv-mod PUBLIC pbdrv) # puzzle bus drivers include(drv/arduino/include.cmake) -# include(drv/rp2040/include.cmake) # please see /main/pbdrv.h +include(drv/rp2040/include.cmake) diff --git a/lib/pbdrv/drv/arduino/include.cmake b/lib/pbdrv/drv/arduino/include.cmake index 1e2ff08..520bfc1 100644 --- a/lib/pbdrv/drv/arduino/include.cmake +++ b/lib/pbdrv/drv/arduino/include.cmake @@ -3,9 +3,5 @@ if(NOT DEFINED ARDUINO) endif() target_sources(pbdrv-mod PRIVATE "${CMAKE_CURRENT_LIST_DIR}/mod.cpp") -target_link_arduino_libraries(pbdrv-mod core Wire) - -# freertos is used to defer the handling of i2c messages outside the receive -# interrupt service routine -include("${CMAKE_CURRENT_LIST_DIR}/../../ext/freertos/include.cmake") +target_link_arduino_libraries(pbdrv-mod PRIVATE core Wire) diff --git a/lib/pbdrv/drv/arduino/index.dox b/lib/pbdrv/drv/arduino/index.dox index 4c74222..1856918 100644 --- a/lib/pbdrv/drv/arduino/index.dox +++ b/lib/pbdrv/drv/arduino/index.dox @@ -2,18 +2,22 @@ /** \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. +\brief Arduino ATmega (w/ Arduino-CMake-Toolchain) driver This driver is known to work with the following MCUs: - ATmega328P (Arduino Uno) - ATmega2560 (Arduino Mega) +\par Usage +- Link the \c pbdrv-mod library with your main executable +- Load an \ref pb_ext "extension" + +\note 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). + +A complete example for this driver is available in the \ref puzzle/dummy +folder. + */ diff --git a/lib/pbdrv/drv/arduino/mod.cpp b/lib/pbdrv/drv/arduino/mod.cpp index 2eef8d5..d2a6402 100644 --- a/lib/pbdrv/drv/arduino/mod.cpp +++ b/lib/pbdrv/drv/arduino/mod.cpp @@ -6,32 +6,17 @@ #include #include -#include -#include -#include - #include "../../pb.h" #include "../../pb-mod.h" #include "../../pb-types.h" -#include "../../pb-buf.h" -#include "../../pb-mem.h" - -static void async_pb_i2c_recv(void * _msg, uint32_t _) { - pb_buf_t * msg = (pb_buf_t *) _msg; - pb_i2c_recv((uint8_t *) msg->data, msg->size); - pb_buf_free(msg); - pb_free(msg); -} static void recv_event(int bytes) { - pb_buf_t * msg = (pb_buf_t *) pb_malloc(sizeof(pb_buf_t)); - msg->data = (char *) pb_malloc(bytes); - msg->size = 0; + uint8_t data[bytes]; + size_t sz = 0; while (Wire.available()) - msg->data[msg->size++] = Wire.read(); + data[sz++] = Wire.read(); - // defer pb_i2c_recv call - xTimerPendFunctionCallFromISR(async_pb_i2c_recv, msg, 0, NULL); + pb_i2c_recv(data, sz); } static void pb_setup() { @@ -42,7 +27,6 @@ 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); @@ -57,18 +41,14 @@ extern void loop(void); //! Arduino internal initialization void init(void); -//! FreeRTOS loop task -void loop_task() { - for(;;) { - loop(); - if (serialEventRun) serialEventRun(); - } -} - /** * \ingroup pb_drv_arduino * \brief Application entrypoint * + * This function overrides the default (weak) implementation of the \c main() + * function in the Arduino framework. No additional setup is required to use + * this driver. + * * \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 @@ -79,8 +59,10 @@ int main(void) { init(); // call arduino internal setup setup(); // call regular arduino setup pb_setup(); // call pbdrv-mod setup - xTaskCreate((TaskFunction_t) loop_task, "loop", configMINIMAL_STACK_SIZE, NULL, tskIDLE_PRIORITY + 1, NULL); - vTaskStartScheduler(); // start freertos scheduler + for(;;) { + loop(); + if (serialEventRun) serialEventRun(); + } return 0; } diff --git a/lib/pbdrv/drv/index.dox b/lib/pbdrv/drv/index.dox index 1fe09e2..89b9247 100644 --- a/lib/pbdrv/drv/index.dox +++ b/lib/pbdrv/drv/index.dox @@ -7,19 +7,6 @@ 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: diff --git a/lib/pbdrv/drv/rp2040/include.cmake b/lib/pbdrv/drv/rp2040/include.cmake new file mode 100644 index 0000000..6d25e96 --- /dev/null +++ b/lib/pbdrv/drv/rp2040/include.cmake @@ -0,0 +1,11 @@ +if(NOT PICO_PLATFORM STREQUAL "rp2040") + return() +endif() + +target_sources(pbdrv-mod PRIVATE "${CMAKE_CURRENT_LIST_DIR}/mod.c") +target_link_libraries(pbdrv-mod PRIVATE hardware_i2c_headers pico_i2c_slave_headers) +target_include_directories(pbdrv-mod INTERFACE "${CMAKE_CURRENT_LIST_DIR}") + +# pico-stdlib is compatible with C stdlib +include("${CMAKE_CURRENT_LIST_DIR}/../../ext/stdlib/include.cmake") + diff --git a/lib/pbdrv/drv/rp2040/index.dox b/lib/pbdrv/drv/rp2040/index.dox new file mode 100644 index 0000000..eb01d15 --- /dev/null +++ b/lib/pbdrv/drv/rp2040/index.dox @@ -0,0 +1,31 @@ +// vim:ft=doxygen +/** +\ingroup pb_drv +\defgroup pb_drv_rp2040 RP2040 +\brief Raspberry Pi Pico and Pico W driver + +This driver is known to work with the following MCUs: +- Raspberry Pi Pico W + +\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. + +\note This driver includes a workaround that uses both I2C peripherals on the +RP2040. To use this driver, make sure you initialize both I2C peripherals, and +connect their respective SDA and SCL pins to the same I2C bus. + +\par Usage +- Link the \c pbdrv-mod library with your main executable +- Call the \c pb_setup() function (from \c ) during setup + +\note This driver is automatically enabled if the variable \c PICO_PLATFORM is +equal to \c "rp2040" in your CMakeLists.txt (it is by default when using the +pico-sdk CMake library). + +\note This driver automatically includes the \ref pb_ext_stdlib +"stdlib extension" as the pico-sdk implements the C standard library. + +*/ + diff --git a/lib/pbdrv/drv/rp2040/mod.c b/lib/pbdrv/drv/rp2040/mod.c new file mode 100644 index 0000000..1535da9 --- /dev/null +++ b/lib/pbdrv/drv/rp2040/mod.c @@ -0,0 +1,49 @@ +#include "pb.h" + +#include "pb.h" +#include "pb-types.h" +#include "pb-mod.h" +#include "pb-send.h" +#include "pb-buf.h" + +#include +#include +#include + +#define PB_I2C_S i2c0 +#define PB_I2C_M i2c1 + +#define BUF_SIZE 256 + +uint8_t i2c_msg_buf[BUF_SIZE]; +size_t i2c_msg_buf_sz = 0; + +// This function is called from the I2C ISR +static void recv_event(i2c_inst_t *i2c, i2c_slave_event_t event) { + switch (event) { + case I2C_SLAVE_RECEIVE: { + if (i2c_msg_buf_sz == BUF_SIZE) return; + i2c_msg_buf[i2c_msg_buf_sz++] = i2c_read_byte_raw(PB_I2C_S); + break; + } + case I2C_SLAVE_FINISH: { + pb_i2c_recv(i2c_msg_buf, i2c_msg_buf_sz); + i2c_msg_buf_sz = 0; + break; + } + default: break; + } +} + +void pb_setup() { + i2c_init(PB_I2C_S, PB_CLOCK_SPEED_HZ); + i2c_init(PB_I2C_M, PB_CLOCK_SPEED_HZ); + + i2c_slave_init(PB_I2C_S, PB_MOD_ADDR, &recv_event); +} + +__weak void pb_i2c_send(i2c_addr_t addr, const uint8_t * buf, size_t sz) { + // false to write stop condition to i2c bus + i2c_write_timeout_us(PB_I2C_M, addr, buf, sz, false, PB_TIMEOUT_US); +} + diff --git a/lib/pbdrv/drv/rp2040/pb-mod.h b/lib/pbdrv/drv/rp2040/pb-mod.h new file mode 100644 index 0000000..96edc70 --- /dev/null +++ b/lib/pbdrv/drv/rp2040/pb-mod.h @@ -0,0 +1,21 @@ +#pragma once + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * \ingroup pb_drv_rp2040 + * \brief Puzzle bus driver setup + * + * This function must be called from a setup/init function to initialize the + * I2C peripherals used by this driver. + */ +void pb_setup(); + +#ifdef __cplusplus +} +#endif + +#include "../../pb-mod.h" + diff --git a/lib/pbdrv/ext/freertos/include.cmake b/lib/pbdrv/ext/freertos/include.cmake index e7ab7fd..70ed090 100644 --- a/lib/pbdrv/ext/freertos/include.cmake +++ b/lib/pbdrv/ext/freertos/include.cmake @@ -1,5 +1,5 @@ target_sources(pbdrv PRIVATE "${CMAKE_CURRENT_LIST_DIR}/pb-mem.c") -target_link_libraries(pbdrv +target_link_libraries(pbdrv PUBLIC freertos_kernel freertos_kernel_include freertos_config diff --git a/lib/pbdrv/index.dox b/lib/pbdrv/index.dox index eb0fd63..8ddcb6a 100644 --- a/lib/pbdrv/index.dox +++ b/lib/pbdrv/index.dox @@ -11,8 +11,9 @@ themselves. For a complete puzzle module driver, please see \ref pbdrv-mod. 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: +platform, and link the \c pbdrv library with your executable. +\par Example ```cmake # include pbdrv add_subdirectory(lib/pbdrv) @@ -35,14 +36,10 @@ 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: +CMakeLists.txt file and linking the library with your executable. Please see +the \ref pb_drv "drivers" page for target-specific usage instructions. +\par Example ```cmake # include pbdrv add_subdirectory(lib/pbdrv) diff --git a/main/CMakeLists.txt b/main/CMakeLists.txt index d6cbf33..76b1244 100644 --- a/main/CMakeLists.txt +++ b/main/CMakeLists.txt @@ -10,7 +10,6 @@ include(lib/FreeRTOS-Kernel/portable/ThirdParty/GCC/RP2040/FreeRTOS_Kernel_impor add_subdirectory(lib/mpack) add_subdirectory(lib/i2ctcp) add_subdirectory(lib/pbdrv) -include(lib/pbdrv/ext/stdlib/include.cmake) # pico-stdlib is compatible with C stdlib project(puzzlebox_main C CXX ASM) @@ -24,7 +23,6 @@ add_executable(main mod.c tasks.c blink.c - pbdrv.c ) pico_enable_stdio_usb(main 1) @@ -34,7 +32,7 @@ pico_add_extra_outputs(main) # include_directories(lib/pico-sdk/lib/lwip/contrib/ports/freertos/include) target_include_directories(main PRIVATE .) -target_link_libraries(main +target_link_libraries(main PUBLIC pico_cyw43_arch_lwip_sys_freertos pico_stdlib pico_i2c_slave diff --git a/main/i2c.c b/main/i2c.c index 0f23a13..db859d8 100644 --- a/main/i2c.c +++ b/main/i2c.c @@ -8,7 +8,6 @@ #include "i2c.h" #include "pb-mod.h" -#include "pbdrv.h" #include "config.h" #include "pb-buf.h" #include "pb-send.h" diff --git a/main/init.c b/main/init.c index d85c94d..25fa5e3 100644 --- a/main/init.c +++ b/main/init.c @@ -7,7 +7,7 @@ #include "config.h" #include "init.h" #include "tasks.h" -#include "pbdrv.h" +#include "pb-mod.h" static void init_stdio() { stdio_init_all(); diff --git a/main/mod.c b/main/mod.c index 11a1bb7..ac9107d 100644 --- a/main/mod.c +++ b/main/mod.c @@ -1,6 +1,13 @@ +#include +#include + #include "pb.h" #include "pb-mod.h" const char * PB_MOD_NAME = "main controller"; const i2c_addr_t PB_MOD_ADDR = PB_ADDR_MOD_MAIN; +void pb_mod_blocking_delay_ms(unsigned long ms) { + vTaskDelay(ms / portTICK_PERIOD_MS); +} + diff --git a/main/pbdrv.c b/main/pbdrv.c deleted file mode 100644 index 6a89253..0000000 --- a/main/pbdrv.c +++ /dev/null @@ -1,81 +0,0 @@ -#include "pb.h" - -#include "pb.h" -#include "pb-types.h" -#include "pb-mod.h" -#include "pb-send.h" - -#include -#include -#include -#include - -#include -#include -#include - -#define PB_I2C_S i2c0 -#define PB_I2C_M i2c1 - -#define BUF_SIZE 256 -#define MSGS_MAX 4 - -typedef struct { - uint8_t data[BUF_SIZE]; - size_t size; -} i2c_msg_buf_t; - -static i2c_msg_buf_t msgs[MSGS_MAX]; -static size_t msg_index = 0; - -static void async_pb_i2c_recv(void * _msg, uint32_t _) { - i2c_msg_buf_t * msg = _msg; - pb_i2c_recv(msg->data, msg->size); -} - -static void msg_complete(i2c_msg_buf_t * msg) { - return pb_i2c_recv(msg->data, msg->size); - - // defer pb_i2c_recv call to FreeRTOS scheduler as pb_i2c_recv takes - // too long to return from an ISR - xTimerPendFunctionCallFromISR(async_pb_i2c_recv, msg, 0, NULL); - - // prepare next message for use - msg_index = (msg_index + 1) % MSGS_MAX; - msgs[msg_index].size = 0; -} - -// This function is called from the I2C ISR -static void recv_event(i2c_inst_t *i2c, i2c_slave_event_t event) { - i2c_msg_buf_t * msg = &msgs[msg_index]; - - switch (event) { - case I2C_SLAVE_RECEIVE: { - if (msg->size == BUF_SIZE) return; - msg->data[msg->size++] = i2c_read_byte_raw(PB_I2C_S); - break; - } - case I2C_SLAVE_FINISH: { - msg_complete(msg); - break; - } - default: break; - } -} - -void pb_setup() { - i2c_init(PB_I2C_S, PB_CLOCK_SPEED_HZ); - i2c_init(PB_I2C_M, PB_CLOCK_SPEED_HZ); - - i2c_slave_init(PB_I2C_S, PB_MOD_ADDR, &recv_event); -} - -__weak void pb_i2c_send(i2c_addr_t addr, const uint8_t * buf, size_t sz) { - // false to write stop condition to i2c bus - i2c_write_timeout_us(PB_I2C_M, addr, buf, sz, false, PB_TIMEOUT_US); -} - -void pb_mod_blocking_delay_ms(unsigned long ms) { - vTaskDelay(ms / portTICK_PERIOD_MS); -} - diff --git a/main/pbdrv.h b/main/pbdrv.h deleted file mode 100644 index 89a4870..0000000 --- a/main/pbdrv.h +++ /dev/null @@ -1,49 +0,0 @@ -#pragma once - -#include "pb-types.h" - -/** - * \ingroup pb_drv - * \defgroup pb_drv_rp2040 RP2040 - * \brief Raspberry Pi Pico and Pico W driver - * - * \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 -void pb_setup(); - -/** - * \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. - * - * \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); - -/// \} - -#ifdef __cplusplus -} -#endif - diff --git a/puzzle/dummy/CMakeLists.txt b/puzzle/dummy/CMakeLists.txt index c2633a1..7edce2b 100644 --- a/puzzle/dummy/CMakeLists.txt +++ b/puzzle/dummy/CMakeLists.txt @@ -14,7 +14,7 @@ set(CMAKE_TOOLCHAIN_FILE ${CMAKE_SOURCE_DIR}/lib/Arduino-CMake-Toolchain/Arduino set(ARDUINO_BOARD "Arduino Uno [avr.uno]") # set(ARDUINO_BOARD "Arduino Mega or Mega 2560 [avr.mega]") -# freertos +# freertos (used for memory management only) add_library(freertos_config INTERFACE) target_include_directories(freertos_config SYSTEM INTERFACE .) set(FREERTOS_PORT GCC_ATMEGA) @@ -28,6 +28,7 @@ set(FREERTOS_HEAP 4) project(pb_mod_dummy C CXX) add_subdirectory(lib/pbdrv) +include(lib/pbdrv/ext/freertos/include.cmake) add_subdirectory(lib/FreeRTOS-Kernel) add_executable(main -- cgit v1.2.3 From f4e7a23309797c56baf6be3a9e99e74596223474 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Sun, 23 Jun 2024 13:32:18 +0200 Subject: tweak doxygen output --- Doxyfile | 1 + docs/doxygen-layout.xml | 62 ++++++++++++++++++++++++++++++++++++++++ readme.md | 75 ++++++++++++++++++++++--------------------------- 3 files changed, 97 insertions(+), 41 deletions(-) create mode 100644 docs/doxygen-layout.xml diff --git a/Doxyfile b/Doxyfile index af362dd..3dd7951 100644 --- a/Doxyfile +++ b/Doxyfile @@ -2,6 +2,7 @@ DOXYFILE_ENCODING = UTF-8 PROJECT_NAME = "puzzlebox" OUTPUT_DIRECTORY = doxygen +LAYOUT_FILE = docs/doxygen-layout.xml INPUT += readme.md INPUT += lib/mpack diff --git a/docs/doxygen-layout.xml b/docs/doxygen-layout.xml new file mode 100644 index 0000000..9ac2aaa --- /dev/null +++ b/docs/doxygen-layout.xml @@ -0,0 +1,62 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/readme.md b/readme.md index a6365c0..da96575 100644 --- a/readme.md +++ b/readme.md @@ -5,63 +5,56 @@ implemented during the 2023-2024 run of the Puzzlebox project. This year's run of the project consists of only software students, and was developed using the hardware from the 21-22 run of the project. -Improved hardware was designed but not realised during the 22-23 run of the -project. This hardware is recommended for future groups participating in the -project. The software in this repository should be easily portable to various -other microcontrollers, and a recommendation is made in the [design -document](docs/design.adoc). +The software in this repository should be easily portable to various other +microcontrollers, and a recommendation is made in the [design +document](docs/design.adoc). Please see the [handover +document](docs/handover.adoc) first for more details. + +> [!NOTE] +> This project was mostly developed on Linux. All subfolders/modules/libraries +> use CMake, and *should* build cross-platform when using CMake+Ninja. This has +> not yet been verified. ## Documentation -This project is documented using Doxygen. To generate HTML docs, run +If you are viewing this page from Doxygen, please take a look at the +[components](topics.html) tab for a comprehensive list of components within +this project. + +Project documentation is available in the [docs](docs/) folder, and all code is +documented using Doxygen. To generate HTML docs, run ``` $ make doxygen ``` -and open in a browser. - -If you are viewing this page from Doxygen, please take a look at -[topics](/topics.html) for a comprehensive list of components within this -project. +and open [the generated HTML files](doxygen/html/index.html) in a browser. A +rendered copy of this documentation is also hosted unofficially at +[pipeframe](https://media.pipeframe.xyz/puzzlebox/23-24/doxygen). ## Tidyness -Please keep this repository tidy by being aware of the following conventions! +Please keep this repository tidy by being aware of the following conventions: -### Folder structure - -``` -/client desktop PC application for controlling the puzzle box -/docs project documentation in AsciiDoc(tor) format -/lib custom libraries and submodules -├───/i2ctcp I2C over TCP protocol functions (used by main and client) -├───/mpack MsgPack CMake configuration and extension -└───/pbdrv puzzle bus driver (module driver + (de)serializing functions) -/main main controller (RPi pico) software -/puzzle/ puzzle sources, each puzzle has its own subdirectory -/shared (unused) shared code -/test unit tests -``` +- An `.editorconfig` file is provided in this repository. Please install the + [EditorConfig](https://editorconfig.org/) plugin for your text editor of + choice to automatically use these. +- There are also `.clang-tidy` and `.clang-format` files, which can be enforced + by running -### Code style - -An `.editorconfig` file is provided in this repository. Please install the -[EditorConfig](https://editorconfig.org/) plugin for your text editor of choice -to automatically use these. - -There are also `.clang-tidy` and `.clang-format` files, which can be enforced -by running - -``` -$ make format -``` + ``` + $ make format + ``` -## Submodules +## Libraries -This repository tracks (most) dependencies via git submodules. +Libraries are stored in the [lib](lib/) folder, and this folder is symlinked to +from each subfolder in the project for convenience (allows CMake to include +out-of-tree modules). The lib folder contains a mix of direct Git submodules +and custom libraries specific to this project. (Most) external dependencies are +tracked as git submodules, exceptions are in the [puzzle](puzzle/) folder. -If something is complaining about missing files +TL;DR: If something is complaining about missing files ``` git submodule update --init --recursive --depth 1 -- cgit v1.2.3 From 46eb2370e53c3a1c7eb593ca99c07944c81ec695 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Sun, 23 Jun 2024 13:37:17 +0200 Subject: remove delay function from pbdrv --- lib/pbdrv/ext/freertos/include.cmake | 2 -- lib/pbdrv/ext/freertos/index.dox | 2 +- lib/pbdrv/ext/freertos/pb-mod.c | 10 ---------- lib/pbdrv/pb-mod.h | 8 -------- main/i2c.c | 2 +- main/mod.c | 4 ---- 6 files changed, 2 insertions(+), 26 deletions(-) delete mode 100644 lib/pbdrv/ext/freertos/pb-mod.c diff --git a/lib/pbdrv/ext/freertos/include.cmake b/lib/pbdrv/ext/freertos/include.cmake index 70ed090..e205c8f 100644 --- a/lib/pbdrv/ext/freertos/include.cmake +++ b/lib/pbdrv/ext/freertos/include.cmake @@ -5,5 +5,3 @@ target_link_libraries(pbdrv PUBLIC freertos_config ) -target_sources(pbdrv-mod PRIVATE "${CMAKE_CURRENT_LIST_DIR}/pb-mod.c") - diff --git a/lib/pbdrv/ext/freertos/index.dox b/lib/pbdrv/ext/freertos/index.dox index dfa45ff..7d72918 100644 --- a/lib/pbdrv/ext/freertos/index.dox +++ b/lib/pbdrv/ext/freertos/index.dox @@ -2,5 +2,5 @@ /** \ingroup pb_ext \defgroup pb_ext_freertos FreeRTOS -\brief FreeRTOS memory management and scheduler-based delay +\brief FreeRTOS memory management */ diff --git a/lib/pbdrv/ext/freertos/pb-mod.c b/lib/pbdrv/ext/freertos/pb-mod.c deleted file mode 100644 index 5c0aa36..0000000 --- a/lib/pbdrv/ext/freertos/pb-mod.c +++ /dev/null @@ -1,10 +0,0 @@ -#include -#include - -#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/pb-mod.h b/lib/pbdrv/pb-mod.h index 3869e55..91e1d1f 100644 --- a/lib/pbdrv/pb-mod.h +++ b/lib/pbdrv/pb-mod.h @@ -24,14 +24,6 @@ extern const char * PB_MOD_NAME; */ extern const i2c_addr_t PB_MOD_ADDR; -/** - * \brief Platform-specific blocking delay function - * - * FIXME: this entire function should be removed (see handover: RP2040 I2C - * limitations) - */ -void pb_mod_blocking_delay_ms(unsigned long ms); - /// \} /** diff --git a/main/i2c.c b/main/i2c.c index db859d8..93b64db 100644 --- a/main/i2c.c +++ b/main/i2c.c @@ -44,7 +44,7 @@ void bus_task() { state_exchange(); // wait 1 second - pb_mod_blocking_delay_ms(1e3); + vTaskDelay(1e3 / portTICK_PERIOD_MS); } } diff --git a/main/mod.c b/main/mod.c index ac9107d..8650861 100644 --- a/main/mod.c +++ b/main/mod.c @@ -7,7 +7,3 @@ const char * PB_MOD_NAME = "main controller"; const i2c_addr_t PB_MOD_ADDR = PB_ADDR_MOD_MAIN; -void pb_mod_blocking_delay_ms(unsigned long ms) { - vTaskDelay(ms / portTICK_PERIOD_MS); -} - -- cgit v1.2.3 From 3fd5c9e58f2d4ce3cdea41a3f37235ef0de57d39 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Sun, 23 Jun 2024 13:39:16 +0200 Subject: fix client compile errors --- client/cmd.cpp | 2 +- client/rl.cpp | 2 +- client/sock.cpp | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/client/cmd.cpp b/client/cmd.cpp index 10d53e3..062fefa 100644 --- a/client/cmd.cpp +++ b/client/cmd.cpp @@ -28,7 +28,7 @@ void cmd_test(char*) { void cmd_help(char*) { printf("List of available commands:\n"); for (size_t i = 0; i < cmds_length; i++) { - struct cmd cmd = cmds[i]; + cmd_t cmd = cmds[i]; printf(" %-*s", 10, cmd.name); if (cmd.info != NULL) printf(" %s", cmd.info); diff --git a/client/rl.cpp b/client/rl.cpp index f839d96..2e74e5f 100644 --- a/client/rl.cpp +++ b/client/rl.cpp @@ -57,7 +57,7 @@ static char* rl_completion_entries(const char *text, int state) { if (state == 0) i = 0; while (i < cmds_length) { - struct cmd cmd = cmds[i]; + cmd_t cmd = cmds[i]; i++; if (strncmp(text, cmd.name, strlen(text)) == 0) { return strdup(cmd.name); diff --git a/client/sock.cpp b/client/sock.cpp index 3490586..e33a3dc 100644 --- a/client/sock.cpp +++ b/client/sock.cpp @@ -101,7 +101,7 @@ void PBSocket::sock_task() { if (ret > 0) continue; // message read completely! - i2c_recv(input.addr, input.data, input.length); + i2c_recv(input.data, input.length); free(input.data); } -- cgit v1.2.3 From bfa85b6c313a725afe98bbe6ccb60978de3187a9 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Sun, 23 Jun 2024 13:54:02 +0200 Subject: add cross-reference for overwritten pbdrv handlers in main controller software --- lib/pbdrv/pb-route.h | 4 +++- main/i2c.c | 11 +++++++++++ main/i2c.h | 1 + main/index.dox | 7 +++++++ 4 files changed, 22 insertions(+), 1 deletion(-) diff --git a/lib/pbdrv/pb-route.h b/lib/pbdrv/pb-route.h index b80e4ec..2a28c0b 100644 --- a/lib/pbdrv/pb-route.h +++ b/lib/pbdrv/pb-route.h @@ -98,6 +98,7 @@ void pb_route_cmd_state_req(pb_msg_t * msg); * controller handles this type of command. */ void pb_route_cmd_state_res(pb_msg_t * msg); +// TODO: add link to pb_route_cmd_state_res handler in main/i2c.c /** * \brief Handle a \ref PB_CMD_STATE "STATE" message with action \ref * PB_ACTION_SET "SET" @@ -122,7 +123,8 @@ void pb_route_cmd_magic_req(pb_msg_t * msg); * PB_ACTION_RES "RES" * * The default implementation of this function is empty, as only the main - * controller handles this type of command. + * controller handles this type of command. (\ref main_route_cmd_magic_res + * "link") */ void pb_route_cmd_magic_res(pb_msg_t * msg); diff --git a/main/i2c.c b/main/i2c.c index 2503560..f366793 100644 --- a/main/i2c.c +++ b/main/i2c.c @@ -41,6 +41,17 @@ void bus_task() { } } +/** + * \ingroup main_pb_override + * \anchor main_route_cmd_magic_res + * + * This function registers the I2C address of the puzzle module that replied to + * the \c MAGIC \c REQ command into a list of "known puzzle modules", which are + * then periodically updated during gameplay. + * + * \note Up to \ref CFG_PB_MOD_MAX puzzle modules can be registered + * simultaniously. + */ void pb_route_cmd_magic_res(pb_msg_t * msg) { if (modules_size == CFG_PB_MOD_MAX) return; modules[modules_size++] = msg->sender; diff --git a/main/i2c.h b/main/i2c.h index 107a04d..27c0b02 100644 --- a/main/i2c.h +++ b/main/i2c.h @@ -15,3 +15,4 @@ void bus_task(); /// \} + diff --git a/main/index.dox b/main/index.dox index aa2d07a..0fee58a 100644 --- a/main/index.dox +++ b/main/index.dox @@ -4,3 +4,10 @@ \defgroup main_tasks tasks \brief Tasks */ + +/** +\ingroup main +\defgroup main_pb_override overrides +\brief Override functions from \ref pbdrv-mod +*/ + -- cgit v1.2.3 From 77aba570a3a94cdcf78e82dc0ebbff0c3dde41d1 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Sun, 23 Jun 2024 14:16:41 +0200 Subject: clean up documentation for puzzle modules --- puzzle/dummy/CMakeLists.txt | 3 +-- puzzle/dummy/makefile | 12 ------------ puzzle/neo/CMakeLists.txt | 14 +++----------- puzzle/neo/index.dox | 8 ++++++++ puzzle/neo/makefile | 12 ------------ puzzle/neo/mod.c | 4 ++-- puzzle/readme.md | 17 +++++++---------- puzzle/vault/CMakeLists.txt | 12 ++---------- puzzle/vault/index.dox | 5 +++++ puzzle/vault/makefile | 12 ------------ puzzle/vault/mod.c | 4 ++-- 11 files changed, 30 insertions(+), 73 deletions(-) diff --git a/puzzle/dummy/CMakeLists.txt b/puzzle/dummy/CMakeLists.txt index 0d508ae..63c4449 100644 --- a/puzzle/dummy/CMakeLists.txt +++ b/puzzle/dummy/CMakeLists.txt @@ -17,8 +17,7 @@ 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_PORT GCC_ATMEGA) set(FREERTOS_HEAP 4) # used for testing diff --git a/puzzle/dummy/makefile b/puzzle/dummy/makefile index 509d8e3..26e9157 100644 --- a/puzzle/dummy/makefile +++ b/puzzle/dummy/makefile @@ -6,15 +6,3 @@ 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/neo/CMakeLists.txt b/puzzle/neo/CMakeLists.txt index db3aadc..6c45f13 100644 --- a/puzzle/neo/CMakeLists.txt +++ b/puzzle/neo/CMakeLists.txt @@ -7,26 +7,18 @@ 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_PORT GCC_ATMEGA) 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) +project(pb_mod_neo C CXX) add_subdirectory(lib/pbdrv) add_subdirectory(lib/FreeRTOS-Kernel) @@ -45,7 +37,7 @@ target_link_arduino_libraries(main PUBLIC Adafruit_seesaw ) -#Adafruit workarround +# fugly workaround target_link_arduino_libraries(_arduino_lib_Adafruit_seesaw_Library PUBLIC "Adafruit BusIO") target_enable_arduino_upload(main) diff --git a/puzzle/neo/index.dox b/puzzle/neo/index.dox index 14cefdc..87822e0 100644 --- a/puzzle/neo/index.dox +++ b/puzzle/neo/index.dox @@ -3,4 +3,12 @@ \ingroup puz \defgroup puz_neo Neo \brief NeoTrellis puzzle module + +\par Setup +- Use the Arduino IDE library manager to install the "Adafruit seesaw Library" + library and its dependencies + +\warning There is another library named "Adafruit NeoTrellis M4 Library", this +is not the right library. + */ diff --git a/puzzle/neo/makefile b/puzzle/neo/makefile index 509d8e3..26e9157 100644 --- a/puzzle/neo/makefile +++ b/puzzle/neo/makefile @@ -6,15 +6,3 @@ 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/neo/mod.c b/puzzle/neo/mod.c index 058a585..7157d22 100644 --- a/puzzle/neo/mod.c +++ b/puzzle/neo/mod.c @@ -1,6 +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; +const char * PB_MOD_NAME = "neotrellis"; +const i2c_addr_t PB_MOD_ADDR = PB_ADDR_MOD_NEOTRELLIS; diff --git a/puzzle/readme.md b/puzzle/readme.md index 21cddd3..1b572ba 100644 --- a/puzzle/readme.md +++ b/puzzle/readme.md @@ -1,29 +1,24 @@ \defgroup puz puzzle \brief Puzzle modules -# puzzles - -This folder contains the source code for all puzzle modules. - ## Arduino-based puzzle modules > [!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: +The Arduino based puzzle modules also use CMake with the +[Arduino-CMake-Toolchain][arduino-cmake]. To build any of these puzzles, make +sure you have done the following: - Install the official Arduino IDE - Open "Tools" > "Board" > "Board manager" - Install the "Arduino AVR Boards" package (1.8.6 works at the time of writing) -- Install the Adafruit seesaw library and dependicies (for the neotrellis puzzle) -- Install the TM1637 library from Avishay Orpaz [arduino-cmake]: https://github.com/a9183756-gh/Arduino-CMake-Toolchain + + diff --git a/puzzle/vault/CMakeLists.txt b/puzzle/vault/CMakeLists.txt index b0f05f2..bc13c8c 100644 --- a/puzzle/vault/CMakeLists.txt +++ b/puzzle/vault/CMakeLists.txt @@ -7,26 +7,18 @@ 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_PORT GCC_ATMEGA) 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) +project(pb_mod_vault C CXX) add_subdirectory(lib/pbdrv) add_subdirectory(lib/FreeRTOS-Kernel) diff --git a/puzzle/vault/index.dox b/puzzle/vault/index.dox index b14e616..15eae1f 100644 --- a/puzzle/vault/index.dox +++ b/puzzle/vault/index.dox @@ -3,4 +3,9 @@ \ingroup puz \defgroup puz_vault Vault \brief Vault puzzle module + +\par Setup +- Use the Arduino IDE library manager to install the "TM1637" library (by + Avishay Orpaz) and its dependencies + */ diff --git a/puzzle/vault/makefile b/puzzle/vault/makefile index 509d8e3..26e9157 100644 --- a/puzzle/vault/makefile +++ b/puzzle/vault/makefile @@ -6,15 +6,3 @@ 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 index 058a585..bae8a3d 100644 --- a/puzzle/vault/mod.c +++ b/puzzle/vault/mod.c @@ -1,6 +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; +const char * PB_MOD_NAME = "vault"; +const i2c_addr_t PB_MOD_ADDR = PB_ADDR_MOD_VAULT; -- cgit v1.2.3 From 807e1499a683209f7ca310e65a6a268772e0409d Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Sun, 23 Jun 2024 15:40:50 +0200 Subject: final documentation check --- docs/design.adoc | 79 ++++++++++++++++++++++------------------------------- docs/handover.adoc | 33 +++++++++++++++------- docs/research.adoc | 7 ++--- docs/share/refs.bib | 8 ++++++ 4 files changed, 67 insertions(+), 60 deletions(-) diff --git a/docs/design.adoc b/docs/design.adoc index 9e48fd4..6df83b6 100644 --- a/docs/design.adoc +++ b/docs/design.adoc @@ -13,7 +13,7 @@ structure, and has three levels of design 'depth': Only design details deemed relevant by the document authors are documented here. Low-level implementation details such as API interfaces, code paths and -workarounds are documented inside the source code repository. +workarounds are documented with Doxygen cite:[pbdox]. [[sec:lv1]] == Top-Level @@ -34,8 +34,9 @@ main controller and multiple puzzle modules. Other notable details include: time of writing (2024-03-11), and this project only describes the interface between the puzzle box and the bomb. * The puzzle box is capable of bidirectional communication over Wi-Fi. This - connection is used to configure the puzzle box before gameplay or modify its - state during gameplay. + connection is used to configure the puzzle box before gameplay or modify its + state during gameplay (<>, + <>). [[fig:system-top]] .Context block diagram @@ -92,8 +93,11 @@ The criteria for a puzzle module controller are: The research document cite:[research] compares various microcontrollers matching these criteria. As a result of this research, the Microchip PIC16F15276 was selected as the recommended microcontroller for future puzzle -modules. The current development hardware utilizes an ESP32-PICO-D4 module, so -the puzzle module software is written with portability in mind. +modules. + +NOTE: The current development hardware still utilizes an ESP32-PICO-D4 module, +but due to a misunderstanding cite:[handover], Arduino boards were used to +implement the puzzle modules. [[fig:puzzle-module-top]] .Generic puzzle module top-level block diagram @@ -149,10 +153,9 @@ Pi Pico W as main controller during development. NOTE: This was written while we did not know the puzzle bus specifically requires slave-addressible I^2^C multi-master controllers to function properly. -While the research concludes the RP2040 is a suitable microcontroller for the -main controller, it is not. The RP2040 was still used, but has required -implementing workarounds. Please see the handover report for more details on -how this impacted the project cite:[handover]. +The RP2040 was still used, but has required implementing workarounds. Please +see the handover report for more details on how this impacted the project +cite:[handover]. [[fig:main-controller-top]] .Main controller top-level block diagram @@ -187,8 +190,10 @@ 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. This is the only hardware-level -specification made this year. +receive messages on the same controller. This can also be achieved by using 2 +I^2^C peripherals on the same bus simultaniously, which is what the RP2040 +currently uses. This has required changes to the wiring, and is the only +hardware-level specification made this year. More details on the messages sent over the puzzle bus are described in <>. @@ -253,7 +258,7 @@ 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 +allows puzzle modules to integrate with the puzzle bus and main controller. All communication described within this subsection refers to 'internal' communication between the main controller and puzzle modules on the puzzle bus. @@ -295,7 +300,7 @@ is shown in <>. The messages are (de)serialized using mpack. This choice was made after considering various alternative options for sending structured messages cite:[research]. Note that all messages are sent as I^2^C writes. Due to this, the I^2^C address of a message sender is included in the -header. +header to facilitate network-like features over I^2^C. [[tab:pb-msg-fmt]] .Puzzle bus message format @@ -332,7 +337,8 @@ is solved. | ``PROP`` | The PROP command type is used for exchanging arbitrary data between puzzle modules and/or the puzzle box client (pbc) over the <>. These properties are not used by the puzzle framework. +bridge>>. These properties are not used by the puzzle framework, and serve as +an extensible interface for puzzle module developers to use. |=== <> lists the different command actions. @@ -362,7 +368,7 @@ main controller firmware (<>). The specific format of the 'cmd' field from <> is different for each command type, and is for this reason only documented in-code using -Doxygen. +Doxygen cite:[pbdox]. [[sec:framework-state]] ==== State @@ -401,16 +407,15 @@ expansion without modification of the main controller software 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``). - -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. +These addresses are indexed in the code in a header exposed by the puzzle bus +driver cite:[pbdox]. 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). +Note that 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. === Main Controller @@ -423,14 +428,15 @@ startup. Puzzle modules start in the 'uninitialized' state (see <>), during 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. +address of the sender is added to an internal list of I^2^C devices that are +considered 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. +the main controller, and transitions into the 'idle' state. [[fig:sequence-puzzle-module-init]] .Puzzle module initialization sequence diagram @@ -479,10 +485,7 @@ 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. - -Detailed specifications on the TCP socket server are in -<>. +TCP connection. This library is documented in detail using Doxygen cite:[pbdox]. ==== Operating system @@ -494,13 +497,6 @@ choice was between FreeRTOS and Zephyr. FreeRTOS was chosen because it is the simplest solution, and because the features Zephyr offers over FreeRTOS are already present in the Raspberry Pi Pico SDK. -NOTE: Due to the issues with the RP2040 that were later discovered -cite:[handover], delays are used within the puzzle bus driver's message -handling logic. This means that due to the use of the RP2040, *all puzzle -modules* are required to use a task scheduler or similar mechanism for -deferring calls to the puzzle bus driver from the I^2^C interrupt service -routine (ISR). - === NeoTrellis puzzle This subsection defines aspects of the 'NeoTrellis puzzle' module and gives a @@ -515,8 +511,8 @@ button. The way to solve this puzzle is by dimming every Neopixel in the 8x8 matrix. This is done by clicking on a button, which switches the state of the Neopixel underneath the pixel and the Neopixels in each cardinal direction from the pressed button. This means that if a Neopixel was on and the button was -pressed it will turn off and vice-versa. A visual example can be found in -Appendix B. +pressed it will turn off and vice-versa. +// A visual example can be found in Appendix B. ==== Puzzle inputs & outputs @@ -544,7 +540,8 @@ have their own logical circuit engraved in the box, and the 6 input ports on the right side of the puzzle have a letter (A through F) engraved in the box. The way to solve the puzzle is by connecting the banana plug cable from an input port on the left side of the puzzle to the corresponding input port on -the right side of the puzzle. An example of this can be found in Appendix C. +the right side of the puzzle. +// An example of this can be found in Appendix C. When the puzzle starts, the participants of the game will have 6 code-fragments written on paper, corresponding to the logical circuits on the puzzle box. The @@ -605,14 +602,4 @@ clicked the vault resets and they need to start over from the beginning. .Vault puzzle in-out image::img/vault-io.png[] -== Components -[[sec:lv3-remote-control]] -=== Remote control - -[appendix] -== NeoTrellis puzzle example - -[appendix] -== Software puzzle example - include::share/footer.adoc[] diff --git a/docs/handover.adoc b/docs/handover.adoc index 77d5da0..efeec00 100644 --- a/docs/handover.adoc +++ b/docs/handover.adoc @@ -84,6 +84,8 @@ The current project state is as follows: ** two puzzle modules ('Vault' and 'NeoTrellis') integrated using the puzzle bus driver +Functionality: + * The main controller (a RPI Pico W) can interact with the different puzzle modules using a central shared I^2^C bus (referred to as the 'puzzle bus') * The main controller is able to find new puzzle modules on startup, and does @@ -92,6 +94,11 @@ The current project state is as follows: main controller through a TCP connection and allows control over various aspects of the puzzle box using simple commands. +Documentation: + +* These project documents +* Detailed usage and API documentation for all software modules cite:[pbdox] + == Incidents During this year's run of the project, we encountered several difficuties we @@ -142,10 +149,11 @@ Please note the following differences between I^2^C devices: regular I^2^C slave devices. - I^2^C multi-master controllers that are slave-addressable in master mode are the only kind of I^2^C controller suitable for use in puzzle modules. + Microcontrollers with 2 I^2^C peripherals on the same bus (one in master + mode, one in slave mode) can also be used to achieve the same effect. The RP2040 supports multi-master, but is not addressable as a slave in master -mode. Due to time constraints, this was mitigated using a workaround (see -<>). +mode. This was mitigated using a workaround (see <>). === Development hardware availability @@ -161,6 +169,12 @@ multiple people to develop using the same setup. Note that the RPI Pico is a special case, as it requires another Pico for debugging, effectively requiring double the amount of hardware to support developers. +Due to a misunderstanding, we also thought our development boards went missing +somewhere during week 13. Double-checking if project materials were actually +stolen, or making clear where the materials are stored by sending an image of +its location could have easily avoided this from happening; make sure to do +either. + === Auxiliary workarounds and technical limitations This section details workarounds that were implemented instead of being fixed @@ -170,10 +184,9 @@ mentioned in this section. [[fixme:rp2040-i2c,RP2040 I^2^C limitations]] <>:: -- All puzzle module drivers have a hard-coded 2 second delay between receiving - the MAGIC handshake request and the MAGIC handshake response handler. This - was done to ensure responses are not ignored by the RP2040 (main controller) - while it is still in I^2^C master mode. +- The RP2040 is not slave-addressable while in master mode. A workaround that + uses both I^2^C peripherals simultaniously was written to work around this + issue. Memory management on Arduino:: The Arduino's built-in memory management functions do not seem to work @@ -208,7 +221,7 @@ are critical for project success: - The RPI Pico (and Pico W)'s I^2^C peripheral supports multi-master, but does not support being addressed as a slave while in master mode. This is required for puzzle bus integration, and was mitigated using a workaround (see - <>). A replacement controller should be used instead. + <>). === Other suggestions @@ -216,13 +229,13 @@ These points are suggestions for future project groups. While we do not think these are critical to project success, we still think they are important to mention. -- Implement the hardware design from the year 22-23. +- The hardware design from the year 22-23 should be implemented. - The original game rules are described in a separate document from the year 20-21. - The RPI Pico W has programmable I/O modules. Due to time constraints, we did not research if these modules can be used to create a custom I^2^C peripheral (and driver) that allows multi-master communication while still being - addressable as a slave. If this is possible, the RPI Pico W can still be used - as main controller without the use of workarounds. + addressable as a slave. If this is possible, the RPI Pico W could be used + without the use of workarounds. include::share/footer.adoc[] diff --git a/docs/research.adoc b/docs/research.adoc index 7a9d56c..6f9b494 100644 --- a/docs/research.adoc +++ b/docs/research.adoc @@ -145,10 +145,9 @@ The Raspberry Pi Pico W board is utilized during development. NOTE: This was written while we did not know the puzzle bus specifically requires slave-addressible I^2^C multi-master controllers to function properly. -While the research concludes the RP2040 is a suitable microcontroller for the -main controller, it is not. The RP2040 was still used, but has required -implementing workarounds. Please see the handover report for more details on -how this impacted the project cite:[handover]. +The RP2040 was still used, but has required implementing workarounds. Please +see the handover report for more details on how this impacted the project +cite:[handover]. [[tab:main-mcu]] .Main controller MCU candidates diff --git a/docs/share/refs.bib b/docs/share/refs.bib index 481d4d1..299d621 100644 --- a/docs/share/refs.bib +++ b/docs/share/refs.bib @@ -219,3 +219,11 @@ year = {2023}, msbib-accessed = {2024-05-11}, } + +@techreport{pbdox, + title = {puzzlebox Doxygen documentation}, + author = {Blansch, Loek Le and Hammer, Elwin and Faase, Lars and in 't Anker, Thomas}, + url = {https://media.pipeframe.xyz/puzzlebox/23-24/doxygen}, + year = {2024}, +} + -- cgit v1.2.3 From 55c9222110375b50a7c6aca5ff9c9c661f84a932 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Sun, 23 Jun 2024 19:37:05 +0200 Subject: add note about symlinks to OS warning --- readme.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/readme.md b/readme.md index da96575..5f71788 100644 --- a/readme.md +++ b/readme.md @@ -14,6 +14,10 @@ document](docs/handover.adoc) first for more details. > This project was mostly developed on Linux. All subfolders/modules/libraries > use CMake, and *should* build cross-platform when using CMake+Ninja. This has > not yet been verified. +> +> Please note that most subfolders use symbolic links to the [lib](lib/) +> folder, which may not work correctly if you clone the repository under a +> filesystem or operating system that does not support these. ## Documentation -- cgit v1.2.3 From fc22aec1eef1872c25a624672d31f57db5c7bb26 Mon Sep 17 00:00:00 2001 From: ThomasintAnker Date: Sun, 23 Jun 2024 19:37:44 +0200 Subject: Added references --- docs/research.adoc | 23 ++++++++++------------- docs/share/refs.bib | 27 +++++++++++++++++++++++++++ 2 files changed, 37 insertions(+), 13 deletions(-) diff --git a/docs/research.adoc b/docs/research.adoc index 6f9b494..e1fbfb8 100644 --- a/docs/research.adoc +++ b/docs/research.adoc @@ -437,7 +437,7 @@ wire library on both the Arduino Mega and the Arduino Uno. ===== PIC16F15276 & ESP32 -Both the PIC16F15276 and the ESP32 MCUs show possibilities to be addressable as a slave while being in master mode. However, at the moment of writing this +Both the PIC16F15276 cite:[PICData] and the ESP32 MCUs show possibilities to be addressable as a slave while being in master mode. However, at the moment of writing this has yet to be tested. // TODO: Add the following reference: @@ -453,26 +453,23 @@ has yet to be tested. ===== PIC16F15276 Registers -In the case of the PIC16F15276 not support master addressable as slave the +In the case of the PIC16F15276 cite:[PICData] not support master addressable as slave the following approach would most likely work. As the PIC16F15276 uses specific registers for its master receive functions, namely the RCEN register, it can be manually set to receive data from the I^2^C bus. However, this also has -yet to be tested. - -// TODO: Add the following reference: -// PIC16F15276 - 25.2.4.3 -// https://ww1.microchip.com/downloads/aemDocuments/documents/MCU08/ProductDocuments/DataSheets/PIC16F15256-74-75-76-Microcontroller-Data-Sheet-40002305.pdf +yet to be tested. ===== Multiple I^2^C Peripherals ==== ESP32 & RP2040 -The ESP32 and the RP2040 both have multiple peripherals for I^2^C -communication, while also supporting simultaneous configuration. This allows -both two I^2^C peripherals to be active, one being configured as a master and -the other being configured as a slave. This enables the controller to send and -receive data to the I^2^C bus without much difficulty. This does introduce -increased code complexity but is a valid option if it is succesful in testing. +The ESP32 cite:[I2CESPAPI] cite:[I2CESPTECH] cite:[ESPSPECS] and the RP2040 both +have multiple peripherals for I^2^C communication, while also supporting +simultaneous configuration. This allows both two I^2^C peripherals to be active, +one being configured as a master and the other being configured as a slave. This +enables the controller to send and receive data to the I^2^C bus without much +difficulty. This does introduce increased code complexity but is a valid option +if it is succesful in testing. // TODO: Add the following reference: // https://docs.espressif.com/projects/esp-idf/en/v4.3/esp32/api-reference/peripherals/i2c.html diff --git a/docs/share/refs.bib b/docs/share/refs.bib index 299d621..138ca57 100644 --- a/docs/share/refs.bib +++ b/docs/share/refs.bib @@ -227,3 +227,30 @@ year = {2024}, } +@online{PICData + title = {PIC16F15276 - 25.2.4.3}, + url = {https://ww1.microchip.com/downloads/aemDocuments/documents/MCU08/ProductDocuments/DataSheets/PIC16F15256-74-75-76-Microcontroller-Data-Sheet-40002305.pdf}, + author = {Microchip}, + year = {2022}, +} + +@online{I2CESPAPI + title = {I2C Driver - ESP32}, + url = {https://docs.espressif.com/projects/esp-idf/en/v4.3/esp32/api-reference/peripherals/i2c.html}, + author = {Espressif Systems}, + year = {2021}, +} + +@online{I2CESPTECH + title = {ESP32 Technical Reference Manual}, + url = {https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf#i2c}, + author = {Espressif Systems}, + year = {2024}, +} + +@online{ESPSPECS + title = {ESP32 Specifications}, + url = {https://www.bitsandparts.nl/documentation/482/ESP32_Specifications_EN_v1.pdf}, + author = {Espressif Systems}, + year = {2015}, +} -- cgit v1.2.3 From 84f729a8ff5c82bd7cf512d2a8a0dbe1433f7e0d Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Sun, 23 Jun 2024 19:40:46 +0200 Subject: protect corporate authors in bibtex file --- docs/share/refs.bib | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/share/refs.bib b/docs/share/refs.bib index 138ca57..7c8e511 100644 --- a/docs/share/refs.bib +++ b/docs/share/refs.bib @@ -230,27 +230,27 @@ @online{PICData title = {PIC16F15276 - 25.2.4.3}, url = {https://ww1.microchip.com/downloads/aemDocuments/documents/MCU08/ProductDocuments/DataSheets/PIC16F15256-74-75-76-Microcontroller-Data-Sheet-40002305.pdf}, - author = {Microchip}, + author = {{Microchip}}, year = {2022}, } @online{I2CESPAPI title = {I2C Driver - ESP32}, url = {https://docs.espressif.com/projects/esp-idf/en/v4.3/esp32/api-reference/peripherals/i2c.html}, - author = {Espressif Systems}, + author = {{Espressif Systems}}, year = {2021}, } @online{I2CESPTECH title = {ESP32 Technical Reference Manual}, url = {https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf#i2c}, - author = {Espressif Systems}, + author = {{Espressif Systems}}, year = {2024}, } @online{ESPSPECS title = {ESP32 Specifications}, url = {https://www.bitsandparts.nl/documentation/482/ESP32_Specifications_EN_v1.pdf}, - author = {Espressif Systems}, + author = {{Espressif Systems}}, year = {2015}, } -- cgit v1.2.3 From b0c5e2f2bd1f9116f09803cf841d45e82c0212c0 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Sun, 23 Jun 2024 19:42:22 +0200 Subject: fix bibtex file --- docs/share/refs.bib | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/share/refs.bib b/docs/share/refs.bib index 7c8e511..6386fec 100644 --- a/docs/share/refs.bib +++ b/docs/share/refs.bib @@ -227,28 +227,28 @@ year = {2024}, } -@online{PICData +@online{PICData, title = {PIC16F15276 - 25.2.4.3}, url = {https://ww1.microchip.com/downloads/aemDocuments/documents/MCU08/ProductDocuments/DataSheets/PIC16F15256-74-75-76-Microcontroller-Data-Sheet-40002305.pdf}, author = {{Microchip}}, year = {2022}, } -@online{I2CESPAPI +@online{I2CESPAPI, title = {I2C Driver - ESP32}, url = {https://docs.espressif.com/projects/esp-idf/en/v4.3/esp32/api-reference/peripherals/i2c.html}, author = {{Espressif Systems}}, year = {2021}, } -@online{I2CESPTECH +@online{I2CESPTECH, title = {ESP32 Technical Reference Manual}, url = {https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf#i2c}, author = {{Espressif Systems}}, year = {2024}, } -@online{ESPSPECS +@online{ESPSPECS, title = {ESP32 Specifications}, url = {https://www.bitsandparts.nl/documentation/482/ESP32_Specifications_EN_v1.pdf}, author = {{Espressif Systems}}, -- cgit v1.2.3 From 7830fb636853564560df5ba330b23791655e4161 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Sun, 23 Jun 2024 19:50:53 +0200 Subject: remove old OS research --- docs/research.adoc | 65 ------------------------------------------------------ 1 file changed, 65 deletions(-) diff --git a/docs/research.adoc b/docs/research.adoc index e1fbfb8..1cd6150 100644 --- a/docs/research.adoc +++ b/docs/research.adoc @@ -215,71 +215,6 @@ the Raspberry Pi RP2040 on the Raspberry Pi Pico W. The recommended MCU for new puzzle modules is the Microchip PIC16F15276. The existing puzzle modules still utilize the ESP32 development kits chosen by the 21-22 group. -== Main Controller OS (Loek) - -Because the hardware produced by the 21-22 group uses a Raspberry Pi 3B+ as -main controller, the usage of this specific board was turned into a -prerequisite for this project (??). The Raspberry Pi 3B+ uses the Broadcom -BCM2837 chipset, which supports the aarch64 instruction set cite:[rpicpu]. -Because the puzzle box should be able to run on battery power (??), the CPU -should be under as little load as possible to preserve power. Choosing the -right operating system is crucial to ensure maximum control over which -processes consume CPU resources. This section indexes the available operating -systems that support the aarch64 instruction set to support the decision for -main controller OS in the design document [??]. - -Each operating system is evaluated on the following criteria: - -* Number of 'base' software packages (pre-installed software) -* Size of base installation (base disk utilization) -* Time required to get set-up -* Software iteration time (amount of work required to complete a - compile-upload-run cycle) -* Whether it is covered by the standard curriculum at Avans University of - Applied Sciences - -All of these factors (except for curriculum coverage) should be low. This means -that operating systems that are minimalistic by default are preferred. - -=== Raspberry Pi OS Lite (Debian) - -The manufacturer of the Raspberry Pi boards publishes a modified version of the -Debian Linux distribution which is aimed at general-purpose users [??]. It -comes with an easy-to-use installer, and is the only OS officially supported by -the manufacturer of this board. All the required drivers come pre-installed, -which means this OS has very little setup time. - -Raspberry Pi OS comes in 3 different varieties [??], the 'Light' variant of -which is the most minimalistic. This variant comes with the least number of -pre-installed software packages and has a base image size of 2.6 GiB after -extracting the archive from the official download page [??]. - -This exact OS is not covered in the normal curriculum, but other derivative -distributions of Debian are, so this OS is be considered familiar. - -=== Void Linux - -=== Linux From Scratch - -=== Bare-metal Firmware - -=== Conclusions - -<> summarizes the considered operating systems based on the -criteria outlined at the start of this section. - -[[tab:main-os]] -.Main controller OS comparison -[%autowidth] -|=== -| | Packages | Size | Set-up time | Iteration time | Covered - -| Raspberry Pi OS Lite | 592 | 2.6 GiB | Medium | Short | Yes -| Void Linux | 126 | 334 MiB | Short | Short | No -| Linux from scratch | n/a | 25+ MiB | Long | Long | Yes -| Bare-metal firmware | n/a | n/a | Long | Long | No -|=== - == Unit Testing Framework Research (Thomas) === Research question -- cgit v1.2.3 From 2528775b34f9c0033027931385a4de866ab2749d Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Mon, 24 Jun 2024 08:31:35 +0200 Subject: add more documentation --- client/cmd.h | 7 ++++++- client/i2c.h | 2 +- client/parse.h | 4 ++-- client/sock.h | 2 +- main/config.def.h | 27 ++++++++++++++++++++++++++- main/index.dox | 6 +++--- main/readme.md | 12 +----------- 7 files changed, 40 insertions(+), 20 deletions(-) diff --git a/client/cmd.h b/client/cmd.h index a3cc44a..4f77d50 100644 --- a/client/cmd.h +++ b/client/cmd.h @@ -2,8 +2,13 @@ /** * \ingroup pbc - * \defgroup pbc_cmd cmd + * \defgroup pbc_cmd Commands * \brief Commands within \ref pbc + * + * \note A manpage is available containing end-user usage instructions inside + * the \ref client folder in the source code repository. This page contains the + * internal code documentation for the commands defined in \c pbc. + * * \{ */ diff --git a/client/i2c.h b/client/i2c.h index 87f33c9..d2cfa9a 100644 --- a/client/i2c.h +++ b/client/i2c.h @@ -5,7 +5,7 @@ /** * \ingroup pbc - * \defgroup pbc_i2c i2c + * \defgroup pbc_i2c I2C * \brief I2C abstraction functions * \{ */ diff --git a/client/parse.h b/client/parse.h index 8b7d235..1beb714 100644 --- a/client/parse.h +++ b/client/parse.h @@ -4,8 +4,8 @@ /** * \ingroup pbc - * \defgroup pbc_parse parse - * \brief Debug send command parser utilities + * \defgroup pbc_parse Parse + * \brief Debug \c send command parser utilities * \{ */ diff --git a/client/sock.h b/client/sock.h index c124e45..792123e 100644 --- a/client/sock.h +++ b/client/sock.h @@ -5,7 +5,7 @@ /** * \ingroup pbc - * \defgroup pbc_sock sock + * \defgroup pbc_sock Socket * \brief TCP socket handling * \{ */ diff --git a/main/config.def.h b/main/config.def.h index b3be5ed..cb6e8b4 100644 --- a/main/config.def.h +++ b/main/config.def.h @@ -4,8 +4,33 @@ /** * \ingroup main - * \defgroup main_config config + * \defgroup main_config Config * \brief Configuration options + * + * The main controller firmware is configured statically (i.e. through + * compile-time defined options). Because the configuration is likely to + * contain Wi-Fi credentials, this file is not tracked under version control. + * + * Before compiling the main controller fimrware, a file (`config.h`) must be + * created by the user with the following format: + * + * ```c + * #pragma once + * + * // define non-default options here + * + * #include "config.def.h" + * ``` + * + * \note `config.def.h` contains preprocessor logic that tries to ensure a + * correct configuration. The default configuration has the following settings: + * - Wi-Fi is disabled (prints a warning during compilation because it was not + * explicitly disabled by the user) + * - The TCP server is disabled (due to Wi-Fi being disabled) + * + * \note The exact default values of each configuration option, and all + * available options are listed below. + * * \{ */ diff --git a/main/index.dox b/main/index.dox index 0fee58a..54c5b15 100644 --- a/main/index.dox +++ b/main/index.dox @@ -1,13 +1,13 @@ // vim:ft=doxygen /** \ingroup main -\defgroup main_tasks tasks -\brief Tasks +\defgroup main_tasks Tasks +\brief FreeRTOS tasks */ /** \ingroup main -\defgroup main_pb_override overrides +\defgroup main_pb_override Overrides \brief Override functions from \ref pbdrv-mod */ diff --git a/main/readme.md b/main/readme.md index 85a3fca..97150eb 100644 --- a/main/readme.md +++ b/main/readme.md @@ -8,17 +8,7 @@ This directory contains the software for the main controller of the Puzzle Box. ## building 1. make sure the submodules are initialized -2. create a `config.h` file and define some options (see `config.def.h` for all - options): - ```c - #pragma once - - #define CFG_NET_SSID "network name" - #define CFG_NET_PASS "network password" - #define CFG_NET_AUTH CYW43_AUTH_WPA2_AES_PSK - - #include "config.def.h" - ``` +2. create a `config.h` file (see \ref main_config "config") 3. use CMake to build ## flashing -- cgit v1.2.3 From 3e7765dd54706eb927b653d1ed8fa03a1f288c88 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Mon, 24 Jun 2024 09:45:15 +0200 Subject: ignore some addresses in bus scan --- main/i2c.c | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/main/i2c.c b/main/i2c.c index 87c8161..2237b4d 100644 --- a/main/i2c.c +++ b/main/i2c.c @@ -12,6 +12,9 @@ #include "pb-buf.h" #include "pb-send.h" +// stolen from lib/pico-sdk/src/rp2_common/hardware_i2c/i2c.c +#define i2c_reserved_addr(addr) (((addr) & 0x78) == 0 || ((addr) & 0x78) == 0x78) + i2c_addr_t modules[CFG_PB_MOD_MAX]; size_t modules_size = 0; @@ -21,6 +24,9 @@ static void bus_scan() { // check for all 7-bit addresses uint16_t addr_max = 1 << 7; for (uint16_t addr = 0x00; addr < addr_max; addr++) { + if (i2c_reserved_addr(addr)) continue; + if (addr == PB_MOD_ADDR) continue; + pb_i2c_send(addr, (uint8_t *) buf.data, buf.size); } -- cgit v1.2.3 From 668e4ce82b2d490a83cb45ef79cab6a328f06638 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Mon, 24 Jun 2024 09:57:57 +0200 Subject: fix make flash --- puzzle/dummy/makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/puzzle/dummy/makefile b/puzzle/dummy/makefile index 26e9157..e22f546 100644 --- a/puzzle/dummy/makefile +++ b/puzzle/dummy/makefile @@ -3,6 +3,6 @@ TARGET = $(BUILD_DIR)/main.elf include ../../lazy.mk export SERIAL_PORT ?= /dev/ttyACM0 -flash: upload-main; +flash: upload; upload-main: $(TARGET) -- cgit v1.2.3 From f6f79683d6ffcc8542652e2eb11a1148d2a94288 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Mon, 24 Jun 2024 11:10:52 +0200 Subject: fix makefile (for real this time) --- puzzle/dummy/makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/puzzle/dummy/makefile b/puzzle/dummy/makefile index e22f546..6b8341b 100644 --- a/puzzle/dummy/makefile +++ b/puzzle/dummy/makefile @@ -4,5 +4,5 @@ include ../../lazy.mk export SERIAL_PORT ?= /dev/ttyACM0 flash: upload; -upload-main: $(TARGET) +upload: $(TARGET) -- cgit v1.2.3 From ac40ddb49eb3a65cf928b1dd48e79802f2414c2e Mon Sep 17 00:00:00 2001 From: Elwin Date: Mon, 24 Jun 2024 11:33:05 +0200 Subject: cmake change and pbdrv implementation --- puzzle/vault/main.cpp | 79 ++++++++++++++------------------------------------- puzzle/vault/makefile | 2 +- 2 files changed, 23 insertions(+), 58 deletions(-) diff --git a/puzzle/vault/main.cpp b/puzzle/vault/main.cpp index 76e5f65..a553c97 100644 --- a/puzzle/vault/main.cpp +++ b/puzzle/vault/main.cpp @@ -1,6 +1,7 @@ #include -#include #include +#include "lib/pbdrv/pb-types.h" +#include "lib/pbdrv/pb-mod.h" #define TOTAL_LEVELS 5 #define ROWS 4 @@ -18,29 +19,16 @@ 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; +// Puzzle state +pb_global_state_t puzzleState = PB_GS_NOINIT; -PuzzleState puzzleState = STATE_UNINITIALIZED; -int currentLevel = 0; +TM1637Display display(CLK, DIO); -void requestEvent() { - if (puzzleState == STATE_PLAYING) { - uint8_t responseData[] = HANDSHAKE_SEND; - Wire.write(responseData, sizeof(responseData)); - Serial.println("Handshake response sent."); - } -} +int currentLevel = 0; void blink_display(char num) { - while(puzzleState == STATE_UNINITIALIZED || puzzleState == STATE_ERROR) { + while(puzzleState == PB_GS_NOINIT) { display.showNumberDecEx(0, 0b11111111, true); // Display "0000" with all digits on delay(500); display.clear(); @@ -73,12 +61,12 @@ void check_button_press() { if (strcmp(keyPress, validButtons[currentLevel]) == 0) { currentLevel++; if (currentLevel >= TOTAL_LEVELS) { - puzzleState = STATE_SOLVED; + puzzleState = PB_GS_SOLVED; Serial.println("Puzzle solved!"); display.showNumberDec(currentLevel + 1, true); digitalWrite(SOLVED_PIN, HIGH); } else { - puzzleState = STATE_PLAYING; + puzzleState = PB_GS_PLAYING; } } else { currentLevel = 0; @@ -102,35 +90,6 @@ void initialize_system() { 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); @@ -138,9 +97,12 @@ void setup() { digitalWrite(SOLVED_PIN, LOW); display.setBrightness(0x0f); - Wire.begin(I2C_MODULE_ADDRESS); - Wire.onRequest(requestEvent); - Wire.onReceive(receiveEvent); + //puzzelState = pb_hook_mod_state_read(); + + + ///// TEST + puzzleState = PB_GS_IDLE; + initialize_system(); // Initialize display with blinking zeros to indicate no connection or initialization state blink_display('0'); @@ -148,18 +110,21 @@ void setup() { void loop() { switch(puzzleState) { - case STATE_PLAYING: + case PB_GS_PLAYING: check_button_press(); delay(100); break; - case STATE_SOLVED: + case PB_GS_SOLVED: display_final_code(bombCode); digitalWrite(SOLVED_PIN, HIGH); Serial.println("Final display shown. Puzzle complete."); break; - case STATE_ERROR: - case STATE_UNINITIALIZED: + case PB_GS_NOINIT: blink_display('0'); break; + case PB_GS_IDLE: + blink_display('1'); + break; } + //puzzelState = pb_hook_mod_state_read(); } \ No newline at end of file diff --git a/puzzle/vault/makefile b/puzzle/vault/makefile index 26e9157..e22f546 100644 --- a/puzzle/vault/makefile +++ b/puzzle/vault/makefile @@ -3,6 +3,6 @@ TARGET = $(BUILD_DIR)/main.elf include ../../lazy.mk export SERIAL_PORT ?= /dev/ttyACM0 -flash: upload-main; +flash: upload; upload-main: $(TARGET) -- cgit v1.2.3 From 8f1fd935e69c5e303466b2be80bff77f556dead5 Mon Sep 17 00:00:00 2001 From: Elwin Date: Mon, 24 Jun 2024 13:17:55 +0200 Subject: Cmake fix and working vault code with pbdrv impl. --- puzzle/vault/main.cpp | 89 +++++++++++++++++++++++++++++++++++++++++---------- puzzle/vault/makefile | 4 +-- 2 files changed, 74 insertions(+), 19 deletions(-) diff --git a/puzzle/vault/main.cpp b/puzzle/vault/main.cpp index a553c97..1a70076 100644 --- a/puzzle/vault/main.cpp +++ b/puzzle/vault/main.cpp @@ -18,6 +18,28 @@ 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"; +const uint8_t SEGMENT_MAP[] = { + 0b00111111, // 0 + 0b00000110, // 1 + 0b01011011, // 2 + 0b01001111, // 3 + 0b01100110, // 4 + 0b01101101, // 5 + 0b01111101, // 6 + 0b00000111, // 7 + 0b01111111, // 8 + 0b01101111, // 9 + 0b01110111, // A + 0b01111100, // B + 0b00111001, // C + 0b01011110, // D + 0b01111001, // E + 0b01110001 // F + // Add other letters if needed +}; + +// This array of level codes matches the codes you might display per level. +const char* levelCodes[TOTAL_LEVELS] = {"A1", "B2", "D1", "C3", "A2"}; // Puzzle state @@ -27,15 +49,20 @@ TM1637Display display(CLK, DIO); int currentLevel = 0; -void blink_display(char num) { - while(puzzleState == PB_GS_NOINIT) { - display.showNumberDecEx(0, 0b11111111, true); // Display "0000" with all digits on - delay(500); - display.clear(); - delay(500); +void blink_display(int num) { + if (num == 1) { + // Display "1111" with leading zeros shown if necessary + display.showNumberDecEx(1111, 0b11111111, true); + } else if (num == 0) { + // Display "0000" with leading zeros shown if necessary + display.showNumberDecEx(0, 0b11111111, true); } + 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); @@ -90,6 +117,37 @@ void initialize_system() { Serial.println("GPIO and display initialized."); } +void display_code_for_level(int level) { + char code[3] = {0}; // Temp storage for level code + strncpy(code, levelCodes[level], 2); // Copy the level-specific code + + uint8_t segs[4] = {0}; // Segments to send to the display + + // Check if the first character is a letter and map it + if (isalpha(code[0])) { + if (code[0] >= 'A' && code[0] <= 'F') { + segs[0] = SEGMENT_MAP[code[0] - 'A' + 10]; // Maps A-F to their segment patterns + } else { + // Handle unexpected characters or extend SEGMENT_MAP for more letters + segs[0] = 0; // Display nothing for undefined letters + } + } else { + // Assume it's a number and map directly + segs[0] = SEGMENT_MAP[code[0] - '0']; + } + + // Check if the second character is a digit and map it + if (isdigit(code[1])) { + segs[1] = SEGMENT_MAP[code[1] - '0']; + } else { + // Handle unexpected characters + segs[1] = 0; // Display nothing for undefined digits + } + + // Set only the first two segments, leave others blank + display.setSegments(segs, 2, 0); // Display on leftmost two digits +} + void setup() { Serial.begin(115200); @@ -97,34 +155,31 @@ void setup() { digitalWrite(SOLVED_PIN, LOW); display.setBrightness(0x0f); - //puzzelState = pb_hook_mod_state_read(); + puzzleState = pb_hook_mod_state_read(); - - ///// TEST - puzzleState = PB_GS_IDLE; initialize_system(); - - // Initialize display with blinking zeros to indicate no connection or initialization state - blink_display('0'); } void loop() { switch(puzzleState) { case PB_GS_PLAYING: + display_code_for_level(currentLevel); check_button_press(); delay(100); break; case PB_GS_SOLVED: + Serial.println("STATE = PB_GS_SOLVED"); display_final_code(bombCode); digitalWrite(SOLVED_PIN, HIGH); - Serial.println("Final display shown. Puzzle complete."); break; case PB_GS_NOINIT: - blink_display('0'); + Serial.println("STATE = PB_GS_NOINIT"); + blink_display(0); break; case PB_GS_IDLE: - blink_display('1'); + Serial.println("STATE = PB_GS_IDLE"); + blink_display(1); break; } - //puzzelState = pb_hook_mod_state_read(); + puzzleState = pb_hook_mod_state_read(); } \ No newline at end of file diff --git a/puzzle/vault/makefile b/puzzle/vault/makefile index e22f546..f33ca7e 100644 --- a/puzzle/vault/makefile +++ b/puzzle/vault/makefile @@ -2,7 +2,7 @@ TARGET = $(BUILD_DIR)/main.elf include ../../lazy.mk -export SERIAL_PORT ?= /dev/ttyACM0 +export SERIAL_PORT ?= /dev/ttyUSB0 flash: upload; -upload-main: $(TARGET) +upload: $(TARGET) -- cgit v1.2.3 From 07e49bbbd3790a95511d68b94d47bf107a5e24a1 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Mon, 24 Jun 2024 14:04:06 +0200 Subject: re-implement deferred I2C handlers for the Arduino pbdrv drv --- lib/pbdrv/drv/arduino/include.cmake | 4 +++ lib/pbdrv/drv/arduino/index.dox | 4 ++- lib/pbdrv/drv/arduino/mod.cpp | 51 ++++++++++++++++++++++++++++--------- 3 files changed, 46 insertions(+), 13 deletions(-) diff --git a/lib/pbdrv/drv/arduino/include.cmake b/lib/pbdrv/drv/arduino/include.cmake index 520bfc1..5ec1124 100644 --- a/lib/pbdrv/drv/arduino/include.cmake +++ b/lib/pbdrv/drv/arduino/include.cmake @@ -5,3 +5,7 @@ endif() target_sources(pbdrv-mod PRIVATE "${CMAKE_CURRENT_LIST_DIR}/mod.cpp") target_link_arduino_libraries(pbdrv-mod PRIVATE core Wire) +# freertos is used to defer the handling of i2c messages outside the receive +# interrupt service routine +include("${CMAKE_CURRENT_LIST_DIR}/../../ext/freertos/include.cmake") + diff --git a/lib/pbdrv/drv/arduino/index.dox b/lib/pbdrv/drv/arduino/index.dox index 1856918..03510dd 100644 --- a/lib/pbdrv/drv/arduino/index.dox +++ b/lib/pbdrv/drv/arduino/index.dox @@ -10,12 +10,14 @@ This driver is known to work with the following MCUs: \par Usage - Link the \c pbdrv-mod library with your main executable -- Load an \ref pb_ext "extension" \note 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. + A complete example for this driver is available in the \ref puzzle/dummy folder. diff --git a/lib/pbdrv/drv/arduino/mod.cpp b/lib/pbdrv/drv/arduino/mod.cpp index d2a6402..c381077 100644 --- a/lib/pbdrv/drv/arduino/mod.cpp +++ b/lib/pbdrv/drv/arduino/mod.cpp @@ -1,22 +1,33 @@ -#ifndef ARDUINO -#error This driver only works on the Arduino platform! -#endif - #include #include #include +#include +#include +#include + #include "../../pb.h" #include "../../pb-mod.h" #include "../../pb-types.h" +#include "../../pb-buf.h" +#include "../../pb-mem.h" + +static void async_pb_i2c_recv(void * _msg, uint32_t _) { + pb_buf_t * msg = (pb_buf_t *) _msg; + pb_i2c_recv((uint8_t *) msg->data, msg->size); + pb_buf_free(msg); + pb_free(msg); +} static void recv_event(int bytes) { - uint8_t data[bytes]; - size_t sz = 0; + pb_buf_t * msg = (pb_buf_t *) pb_malloc(sizeof(pb_buf_t)); + msg->data = (char *) pb_malloc(bytes); + msg->size = 0; while (Wire.available()) - data[sz++] = Wire.read(); + msg->data[msg->size++] = Wire.read(); - pb_i2c_recv(data, sz); + // defer pb_i2c_recv call + xTimerPendFunctionCallFromISR(async_pb_i2c_recv, msg, 0, NULL); } static void pb_setup() { @@ -27,7 +38,17 @@ static void pb_setup() { Wire.onReceive(recv_event); } +/** + * \ingroup pb_drv_arduino + * \warning This function includes a hard-coded 10ms delay before sending. This + * is to work around a weird issue where the Arduino pulls both SDA and SCL low + * while attempting to initiate an I2C transmission. We were able to verify + * that the Arduino correctly handles bus arbitration under a test scenario + * with 2 Uno's, but ran into issues while integrating the Arduino's with the + * RP2040. + */ __weak void pb_i2c_send(i2c_addr_t addr, const uint8_t * buf, size_t sz) { + vTaskDelay(10 / portTICK_PERIOD_MS); // prevent bus collisions Wire.beginTransmission((int) addr); Wire.write(buf, sz); Wire.endTransmission(true); @@ -41,6 +62,14 @@ extern void loop(void); //! Arduino internal initialization void init(void); +//! FreeRTOS loop task +void loop_task() { + for(;;) { + loop(); + if (serialEventRun) serialEventRun(); + } +} + /** * \ingroup pb_drv_arduino * \brief Application entrypoint @@ -59,10 +88,8 @@ int main(void) { init(); // call arduino internal setup setup(); // call regular arduino setup pb_setup(); // call pbdrv-mod setup - for(;;) { - loop(); - if (serialEventRun) serialEventRun(); - } + xTaskCreate((TaskFunction_t) loop_task, "loop", configMINIMAL_STACK_SIZE, NULL, tskIDLE_PRIORITY + 1, NULL); + vTaskStartScheduler(); // start freertos scheduler return 0; } -- cgit v1.2.3 From 0624733a1b4a5c79763a1a0b2f3c53e94fe486be Mon Sep 17 00:00:00 2001 From: Elwin Date: Mon, 24 Jun 2024 14:15:14 +0200 Subject: Corrected pbdrv impl. --- puzzle/vault/main.cpp | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/puzzle/vault/main.cpp b/puzzle/vault/main.cpp index 1a70076..2e4cafc 100644 --- a/puzzle/vault/main.cpp +++ b/puzzle/vault/main.cpp @@ -88,12 +88,10 @@ void check_button_press() { if (strcmp(keyPress, validButtons[currentLevel]) == 0) { currentLevel++; if (currentLevel >= TOTAL_LEVELS) { - puzzleState = PB_GS_SOLVED; + pb_hook_mod_state_write(PB_GS_SOLVED); Serial.println("Puzzle solved!"); display.showNumberDec(currentLevel + 1, true); digitalWrite(SOLVED_PIN, HIGH); - } else { - puzzleState = PB_GS_PLAYING; } } else { currentLevel = 0; @@ -149,14 +147,19 @@ void display_code_for_level(int level) { } +pb_global_state_t pb_hook_mod_state_read() { + return puzzleState; +} + +void pb_hook_mod_state_write(pb_global_state_t state) { + puzzleState = state; +} + void setup() { Serial.begin(115200); pinMode(SOLVED_PIN, OUTPUT); digitalWrite(SOLVED_PIN, LOW); - display.setBrightness(0x0f); - - puzzleState = pb_hook_mod_state_read(); - + display.setBrightness(0x0f); initialize_system(); } @@ -181,5 +184,4 @@ void loop() { blink_display(1); break; } - puzzleState = pb_hook_mod_state_read(); } \ No newline at end of file -- cgit v1.2.3