From 9baf7a839fa79db145ffce8ce807807e4055a1a0 Mon Sep 17 00:00:00 2001 From: lonkaars Date: Sat, 20 Apr 2024 16:42:00 +0200 Subject: WIP initial import of software design document from word --- docs/design.adoc | 515 +++++++++++++++++++++++++++++++++++++++++++++++ docs/readme.md | 2 + docs/share/glossary.adoc | 1 + 3 files changed, 518 insertions(+) diff --git a/docs/design.adoc b/docs/design.adoc index b653633..2bac6b3 100644 --- a/docs/design.adoc +++ b/docs/design.adoc @@ -1,5 +1,520 @@ :document: Software Design include::share/meta.adoc[] +== Introduction + +This document contains all the design considerations made for the separate +software components that make up the puzzle box. This document has a top-down +structure, and has three levels of design 'depth': + +. Top-level (hardware diagrams, OSes, communication buses, etc.) +. Module-level (puzzle inputs/outputs, top-level software diagram, etc.) +. Component-level (software dependencies, game state, etc.) + +Only design details deemed relevant by the document authors are documented +here. Low-level implementation details such as API interfaces, code paths and +workarounds are documented inside the source code repository. + +== Top-Level + +This section of the design document establishes the development target +hardware. It also specifies the modules that are elaborated further in §3. + +Figure 1 shows a block diagram that describes the context in which the puzzle +box is used. The puzzle box in this diagram internally consists of a main +controller and multiple puzzle modules. Other notable details include: + +* The charger is removable, and the puzzle box is intended to be used as a + battery-powered device (i.e. not while tethered). +* Puzzle outputs are used to complete a feedback loop (gameplay) with the + players, as well as eventually provide a solution to diffuse a bomb. This + bomb is part of a standalone project that has already been finished at the + time of writing (2024-03-11), and this project only describes the interface + between the puzzle box and the bomb. +* The puzzle box is capable of bidirectional communication over Wi-Fi. This + connection is used to configure the puzzle box before gameplay or modify its + state during gameplay. + +.Context block diagram + +The rest of this section details the internal hardware modules and the +separation of functionality of these modules. + +=== Puzzle Modules + +The puzzle box hardware produced by the 21-22 group consists of 6 sides, 4 of +which are utilized by puzzle modules. This section defines the properties of a +puzzle module. + +Puzzle modules can occupy one or more physical sides of the puzzle box to +implement the physical interface required for a puzzle or game. In order to +realize a complete game, each of these puzzle modules must have the ability to +control game inputs and outputs. Two approaches for this were considered: + +. Let the main controller handle game state and logic for all puzzle modules. ++ +This approach has the main benefit of allowing puzzle module controllers to be +substituted for I^2^C I/O expanders that draw less power than a complete MCU. ++ +The major drawback of this approach is that the main controller's software +needs to be configured for each different hardware configuration, which makes +the main controller software more complicated. + +. Design an abstract 'game interface' and give each puzzle module its own MCU. ++ +This approach provides the most flexibility, as the main controller's software +is no longer dependent on the physically installed hardware. This approach is +also favorable with regards to testability, as each puzzle module can run +standalone. ++ +The main drawback of this approach is the possible increase in power +consumption, as each puzzle module now must have its own MCU for managing game +state and communication with the main controller. + +The current hardware (developed by the 21-22 group) uses the second approach, +though with MCUs that were not designed for power efficiency. This year +(23-24), the hardware produced by the 21-22 group was utilized due to the 23-24 +group not including students from the hardware study path. Minimizing power +draw for each puzzle module is still a priority, so a different microcontroller +was selected. + +The criteria for a puzzle module controller are: + +* Must have an I^2^C peripheral (R#141). +* Should have enough I/O ports to directly control moderately complex puzzles + (R#142). +* Should be power efficient (R#143). + +The research document [1] compares various microcontrollers matching these +criteria. As a result of this research, the Microchip PIC16F15276 was selected +as the recommended microcontroller for future puzzle modules. The current +development hardware utilizes an ESP32-PICO-D4 module, so the puzzle module +software is written with portability in mind. + +.Generic puzzle module top-level block diagram + +Figure 2 shows a block diagram of how most puzzle modules are implemented. +Since the internal components of the puzzle module block from Figure 2 differ +for each puzzle, they are left out in this section. Section 3 includes the next +detail level for all of the implemented puzzles this year. The puzzle bus is +detailed further in §2.3. + +=== Main Controller + +This section describes the responsibilities of the main controller inside the +puzzle box. The main controller is a central processor that is responsible for +the following: + +* Integrate installed puzzle modules to form a cohesive experience by— +** Detecting and initializing installed puzzle modules. +** 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— +** Sending state updates +** Manually updating game state +** Integration with the bomb + +The specific requirement of being able to serve TCP socket connections was +created so this year's puzzle box could keep compatibility with the software +produced by the 21-22 group. + +As mentioned in the research document [1], the 21-22 group produced the +hardware that is used as development target for this year's (23-24) run of the +puzzle box project. The existing hardware utilizes a Raspberry Pi 3B+ as main +controller, but this controller caused issues with power consumption [2]. +Choosing a different controller during development requires significant +refactoring, so a different main controller has been selected at the start of +this year's run of the puzzle box project. + +The criteria for the main controller are: + +* Must have an I^2^C peripheral (R#136). +* Must be able to connect to a standard 802.11b/g/n access point (R#137). +* Must be able to serve TCP socket connection(s) (R#138). +* Should be power efficient (R#166). + +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. + +.Main controller top-level block diagram + +Figure 3 shows a block diagram of the main controller and its inputs and +outputs. The main controller is the only module in the puzzle box that is able +to communicate over Wi-Fi and is therefore responsible for all communication +between the puzzle box and game operator. The puzzle bus is detailed further in +§2.3. + +=== Communication + +Communication between puzzle modules, the main controller and other auxiliary +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 [3]. + +The only notable difference made this year was the removal of the +"HarwareInterrupt" line1, which was connected but not utilized [1]. + +Address definitions and protocol specifications are further detailed in §3.3. + +=== Power supply + +One of the user requirements is that the puzzle box runs on battery power +(R#89). Due to the team composition of this year's (23-24) run of the puzzle +box project, a new power supply was not chosen, even though the current power +supply was determined insufficient by the 21-22 group. This year, additional +requirements were specified for the power supply, which were used when +selecting MCUs suitable for battery-powered applications. + +.Power supply module top-level block diagram + +Figure 2 shows a block diagram of how most puzzle modules are implemented. +Besides the additional requirements, the power supply remains the same, and +will not be elaborated further on in this document. + +=== Overview + +Figure 5 is the resulting combination of the modules from Figures 3, 2 and 4. + +.Hardware component overview + +== Modules + +This section elaborates on the top-level specifications from §2 with additional +hardware specifications and 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. + +The puzzle framework is the foundation of the puzzle box software, and is +designed to facilitate the following: + +* Allow puzzle modules to be swapped with minimal downtime or maintenance + (R#132). +* Simplify the development process and integration of new puzzle modules + (R#130). +* Provide abstracted interfaces to allow for easy integration of the puzzle box + as part of a larger whole (R#133). + +==== State + +All puzzle modules implement the same state machine shown in Figure 6. 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 Figure 6, which can be +used to skip a puzzle if a player is stuck (R#168) or reset a game if it is +malfunctioning (R#167). + +Puzzle modules start in the 'uninitialized' state, where they repeatedly send +messages to the main controller (see §3.2.3). The state transition from +'uninitialized' to 'reset' is forced by the main controller upon +initialization. States on the right half of Figure 6 are used during gameplay. + +.Global puzzle module state machine + +The state machine described in Figure 6 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. + +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. + +==== Commands + +The puzzle module framework describes the following commands: + +* Read state +* Write state +* Update + +The 'read' and 'write' commands are used to communicate both types of state +defined in §3.1.1. + +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. + +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. + +=== Main Controller + +This subsection defines the function and state of the main controller. + +==== 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 Figure 7. + +.Main controller global state machine + +The following list describes when each state is active: + +* 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 'solved' state, the main controller is also + 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 Figure 6). 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. + +.Puzzle module initialization sequence diagram + +(Activated lifeline indicates the module is no longer in 'uninitialized' state) + +==== Bridge + +The bridge is used to remotely access and control the puzzle box. + +The Raspberry Pi 3B+ used as main controller during the 21-22 run of the +project set up a Wi-Fi Mesh network [3] to communicate with the puzzle box. +This year's main controller (Raspberry Pi Pico W [1]) uses a standard +802.11b/g/n access point instead (R#137). + +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 §4.1. + +==== Operating System + +The research document [1] 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. + +=== 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 §3.2.3) are sent on behalf +of the main controller. + +==== Addresses + +The I^2^C addresses remain mostly unchanged from the 20-21 group's +implementation [4]. 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 + +.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 [1]. + +Figure 8 shows an example of how messages are exchanged for the initialization +of a puzzle module. + +Figure 9 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. + +.Puzzle box finish sequence diagram + +=== 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 +facilitate the NeoTrellis puzzle game logic and communication with the main +controller about the puzzle state. + +==== NeoTrellis puzzle gameplay + +The NeoTrellis puzzle is an 8x8 button matrix with Neopixels underneath each +button. The way to solve this puzzle is by dimming every Neopixel in the 8x8 +matrix. This is done by clicking on a button, which switches the state of the +Neopixel underneath the pixel and the Neopixels in each cardinal direction from +the pressed button. This means that if a Neopixel was on and the button was +pressed it will turn off and vice-versa. A visual example can be found in +Appendix B. + +==== Puzzle inputs & outputs + +The inputs and outputs of this puzzle have been taken from the design document +of the previous group which worked on this project (??). This input and output +diagram has been shown in Figure 10. + +.NeoTrellis puzzle in-out + +=== 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 +facilitate the software puzzle game logic and communication with the main +controller about the software puzzle state. + +==== Software puzzle gameplay + +The software puzzle consists of 12 input ports which can be connected using a +banana plug connector. The 6 input ports on the left side of the puzzle each +have their own logical circuit engraved in the box, and the 6 input ports on +the right side of the puzzle have a letter (A through F) engraved in the box. +The way to solve the puzzle is by connecting the banana plug cable from an +input port on the left side of the puzzle to the corresponding input port on +the right side of the puzzle. An example of this can be found in Appendix C. + +When the puzzle starts, the participants of the game will have 6 code-fragments +written on paper, corresponding to the logical circuits on the puzzle box. The +bomb participants will have description of the C-code fragments, while the +puzzle box participants only have the logical circuits on the puzzle box. The +participants must communicate with each other to figure out which a fragment of +C code corresponds with a logical circuit engraved on the puzzle box. Once this +has been done the puzzle box participants can use a banana plug cable to +connect the input and output to each other. Once the correct combination of +logical gates with the correct letter is made, the puzzle is solved (shown by +an LED lighting up above the puzzle). Allowing the participants to both see a +binary code using 16 LEDs above the puzzle, and to continue to the next puzzle. + +==== Puzzle inputs & outputs + +As stated in §3.5.1 the puzzle has 12 inputs, as well as an LED which shows +whether the puzzle has been solved and 16 LEDs showing a binary code. This is +shown in Figure 11. + +.Software puzzle in-out + +=== Hardware Puzzle + +==== 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 +correct position. To solve the puzzle, a truth table is used. + +The second part of the puzzle is unlocked after solving the logic gate puzzle, +the user has to listen to a Morse code from which a four-digit code follows. +The user then turns potentiometers to change this code on the display. The +puzzle is solved when the user has put the correct code on the display. Once +successful, the indicator LED will light up. + +==== Puzzle inputs / outputs + +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 gameplay + +The vault puzzle is a puzzle created to test the communication skills of the +student. It shows a code on the puzzle box, which then needs to be given to +students with the game manual, who communicates this to the students at the +puzzle box the button they must click. This needs to be done 5 times before the +vault opens and the last code is given to defuse the bomb if a wrong button is +clicked the vault resets and they need to start over from the beginning. + +==== Puzzle inputs & outputs + +.Vault puzzle in-out + +=== 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 + +.Bomb device in-out + +== Components +=== Remote Control +==== Socket Server +==== Socket Commands +=== Neotrellis Puzzle +=== Game state diagrams, activity diagrams (if applicable) +=== Software Puzzle +=== Hardware Puzzle +=== Vault Puzzle + +[appendix] +== NeoTrellis puzzle example + +[appendix] +== Software puzzle example include::share/footer.adoc[] diff --git a/docs/readme.md b/docs/readme.md index c5067b5..32814dc 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -18,7 +18,9 @@ makefile is provided for convenience. - [x] project plan - [x] requirements - [x] research + - [ ] footnotes - [ ] software design + - [ ] footnotes - xrefs for-- - [x] tables - [x] figures diff --git a/docs/share/glossary.adoc b/docs/share/glossary.adoc index 8cc19f5..871a8e9 100644 --- a/docs/share/glossary.adoc +++ b/docs/share/glossary.adoc @@ -6,4 +6,5 @@ RPI:: Raspberry Pi Main board:: The main board is the PCB on the bottom of the puzzle box, this communicates with the puzzles and the bomb Puzzle box hub:: The puzzle box hub communicates with the puzzle box and the bomb, as well as helps with configuring them SID:: security identifiers +game operator:: person who organizes a puzzle box play session -- cgit v1.2.3