WIP initial import of software design document from word

3 files changed, 518 insertions, 0 deletions

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