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 --- docs/handover.adoc | 47 ++++++++++++++++++++++++++++++----------------- 1 file changed, 30 insertions(+), 17 deletions(-) (limited to 'docs') 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 -- 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(-) (limited to 'docs') 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 (limited to 'docs') 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(-) (limited to 'docs') 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 67f076b151d35a36800734cb31a403fac92ffb6d Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Fri, 21 Jun 2024 13:22:18 +0200 Subject: WIP more design document + add TODOs --- docs/design.adoc | 332 +++++++++++++++++------------- docs/handover.adoc | 3 +- docs/img/.gitignore | 2 + docs/img/sequence-puzzle-module-init.puml | 17 ++ docs/img/sequence-puzzle-module-init.svg | 3 - docs/img/style.ipuml | 1 + docs/makefile | 1 + lib/pbdrv/pb.h | 19 +- 8 files changed, 222 insertions(+), 156 deletions(-) create mode 100644 docs/img/sequence-puzzle-module-init.puml delete mode 100644 docs/img/sequence-puzzle-module-init.svg (limited to 'docs') 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(-) (limited to 'docs') 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(+) (limited to 'docs') 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(-) (limited to 'docs') 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(-) (limited to 'docs') 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(-) (limited to 'docs') 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(-) (limited to 'docs') 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 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(-) (limited to 'docs') 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 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(-) (limited to 'docs') 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 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 (limited to 'docs') 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 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 (limited to 'docs') 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 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(-) (limited to 'docs') 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 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(-) (limited to 'docs') 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(-) (limited to 'docs') 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(-) (limited to 'docs') 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(-) (limited to 'docs') 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