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 +++++++++++++++++++++++++++++++------------------------- 1 file changed, 53 insertions(+), 43 deletions(-) (limited to 'docs/design.adoc') 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 -- 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/design.adoc') 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/design.adoc') 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/design.adoc') 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/design.adoc') 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