Merge branch 'master' into prot/vault-puzzle (merge #5)

1 files changed, 568 insertions, 0 deletions

diff --git a/docs/design.adoc b/docs/design.adoc
new file mode 100644
index 0000000..5ebbb15
--- /dev/null
+++ b/docs/design.adoc
@@ -0,0 +1,568 @@
+: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.
+
+[[sec:lv1]]
+== Top-Level
+
+This section of the design document establishes the development target
+hardware. It also specifies the modules that are elaborated further in
+<<sec:lv2>>.
+
+<<fig:system-top>> 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.
+
+[[fig:system-top]]
+.Context block diagram
+image::img/system-top.svg[]
+
+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 (<<reqs.adoc#req:pm-i2c-ctrl>>).
+* Should have enough I/O ports to directly control moderately complex puzzles
+  (<<reqs.adoc#req:pm-gpio>>).
+* Should be power efficient (<<reqs.adoc#req:pm-pwr-efficient>>).
+
+The research document cite:[research] compares various microcontrollers
+matching these criteria. As a result of this research, the Microchip
+PIC16F15276 was selected as the recommended microcontroller for future puzzle
+modules. The current development hardware utilizes an ESP32-PICO-D4 module, so
+the puzzle module software is written with portability in mind.
+
+[[fig:puzzle-module-top]]
+.Generic puzzle module top-level block diagram
+image::img/puzzle-module-top.svg[]
+
+<<fig:puzzle-module-top>> shows a block diagram of how most puzzle modules are
+implemented. Since the internal components of the puzzle module block from
+<<fig:puzzle-module-top>> differ for each puzzle, they are left out in this
+section. <<sec:lv2>> includes the next detail level for all of the implemented
+puzzles this year. The puzzle bus is detailed further in
+<<sec:lv1-communication>>.
+
+=== 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 cite:[research], 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
+cite:[2122_handover]. 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 (<<reqs.adoc#req:main-i2c-ctrl>>).
+* Must be able to connect to a standard 802.11b/g/n access point
+  (<<reqs.adoc#req:main-802-11-ap>>).
+* Must be able to serve TCP socket connection(s)
+  (<<reqs.adoc#req:main-tcp-socket>>).
+* Should be power efficient (<<reqs.adoc#req:main-pwr-efficient>>).
+
+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.
+
+[[fig:main-controller-top]]
+.Main controller top-level block diagram
+image::img/main-controller-top.svg[]
+
+<<fig:main-controller-top>> 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 <<sec:lv1-communication>>.
+
+[[sec:lv1-communication]]
+=== 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 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].
+
+Address definitions and protocol specifications are further detailed in
+<<sec:lv2-bus>>.
+
+=== Power supply
+
+One of the user requirements is that the puzzle box runs on battery power
+(<<reqs.adoc#req:pwr-battery>>). 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.
+
+[[fig:power-supply-top]]
+.Power supply module top-level block diagram
+image::img/power-supply-top.svg[]
+
+<<fig:puzzle-module-top>> 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
+
+<<fig:system-bus>> is the resulting combination of the modules from
+<<fig:puzzle-module-top>>, <<fig:main-controller-top>> and
+<<fig:power-supply-top>>.
+
+[[fig:system-bus]]
+.Hardware component overview
+image::img/system-bus.svg[]
+
+[[sec:lv2]]
+== Modules
+
+This section elaborates on the top-level specifications from <<sec:lv1>> 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
+  (<<reqs.adoc#req:pm-swap>>).
+* Simplify the development process and integration of new puzzle modules
+  (<<reqs.adoc#req:main-static>>).
+* Provide abstracted interfaces to allow for easy integration of the puzzle box
+  as part of a larger whole (<<reqs.adoc#req:main-interface>>).
+
+[[sec:framework-state]]
+==== State
+
+All puzzle modules implement the same state machine shown in
+<<fig:puzzle-module-common-state>>. 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 <<fig:puzzle-module-common-state>>, which can be used to
+skip a puzzle if a player is stuck (<<reqs.adoc#req:edge-skip-puzzle>>) or
+reset a game if it is malfunctioning (<<reqs.adoc#req:edge-manual-reset>>).
+
+Puzzle modules start in the 'uninitialized' state, where they repeatedly send
+messages to the main controller (see <<sec:main-bridge>>). The state transition
+from 'uninitialized' to 'reset' is forced by the main controller upon
+initialization. States on the right half of <<fig:puzzle-module-common-state>>
+are used during gameplay.
+
+[[fig:puzzle-module-common-state]]
+.Global puzzle module state machine
+image::img/puzzle-module-common-state.svg[]
+
+The state machine described in <<fig:puzzle-module-common-state>> 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 <<sec:framework-state>>.
+
+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
+<<fig:main-controller-state>>.
+
+[[fig:main-controller-state]]
+.Main controller global state machine
+image::img/main-controller-state.svg[]
+
+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
+<<fig:puzzle-module-common-state>>). 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)
+
+[[sec:main-bridge]]
+==== 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 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
+(<<reqs.adoc#req:main-802-11-ap>>).
+
+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
+<<sec:lv3-remote-control>>.
+
+==== Operating System
+
+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.
+
+[[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 <<sec:main-bridge>>) 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
+
+.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].
+
+<<fig:sequence-puzzle-module-init>> shows an example of how messages are
+exchanged for the initialization of a puzzle module.
+
+<<fig:sequence-puzzle-finish>> 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[]
+
+=== 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 <<fig:neotrellis-io>>.
+
+[[fig:neotrellis-io]]
+.NeoTrellis puzzle in-out
+image::img/neotrellis-io.png[]
+
+=== 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.
+
+[[sec:software-gameplay]]
+==== 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 <<sec:software-gameplay>> 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 <<fig:software-io>>.
+
+[[fig:software-io]]
+.Software puzzle in-out
+image::img/software-io.png[]
+
+=== 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
+
+[[fig:vault-io]]
+.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
+
+[appendix]
+== NeoTrellis puzzle example
+
+[appendix]
+== Software puzzle example
+
+include::share/footer.adoc[]