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 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