:document: Project Requirements include::share/meta.adoc[] == Introduction In this document, the specifications are described prior to the investigation of the Puzzle Box project. These specifications are partly derived from the previously established requirements and are further supplemented and modified. The priority of specifications is indicated using the MoSCoW method, see <>. [[tab:moscow]] .MoSCoW Method cite:[Wik22] [cols="20h,~"] |=== | Priority | Description | [[must,M]]<> | Represents essential system requirements. Without these, the system will not function. | [[should,S]]<> | Denotes desirable system features. The system can work without these, but it lacks necessary elements. | [[could,C]]<> | Refers to additional functionalities that can be implemented if there is extra time. | [[wont,W]]<> | Specifies requirements that will not be implemented in the current version but may be considered in a future release. |=== This specification document covers hardware, software, and game-specific details. The focus in this project year for the Puzzle Box is to thoroughly document the system and create a software framework for future groups. == Context This chapter describes how the user will interact with the system. This is done in the form of a user story. This user story covers hardware, software, and game specifications. From this narrative, many specifications can be derived for both functional and non-functional requirements (<> and <>). The game administrator picks up the puzzle box and places it on a flat surface. By using the key switch, the puzzle box is turned on, and the green indicator LED lights up. Through the mesh network established by the external puzzle box hub, the corresponding web panel can be accessed. The web panel provides instructions for configuring the puzzle box, including linking it to any bomb. The instructions issue a warning if any of the start conditions are not properly set. If a criterion is incorrectly configured, it is highlighted for resolution. Additionally, a warning is given if the battery capacity is insufficient for one game duration, causing the indicator LED on the puzzle box to turn red. In such cases, the battery should be charged using the USB-C cable. While the puzzle box is charging, the indicator LED is blue. Once there are no warnings and the puzzle box is adequately charged, the game can be started in the web panel. The puzzle box begins with the NeoTrellis game. In this game, players must turn off all LEDs on an 8x8 button LED matrix. When any button is pressed, the directly adjacent LEDs toggle. If a lit LED is toggled, it turns off; if an unlit LED is toggled, it turns on. Once all LEDs are turned off, the game is solved, and the software puzzle begins. On the software puzzle, there are 6 banana plug connectors on both the left and right sides. The ones on the left are labeled with various logical gates, while the ones on the right are labeled from A to F. Participants in the bomb game have 6 pieces of C-code written on paper, corresponding to the logical gates on the puzzle box. The bomb participants must provide a description of the C-code to the puzzle box participants, allowing them to correctly connect the appropriate logical gate to the corresponding letter. Once the correct combination of logical gates with the correct letter is made, the game is solved. Subsequently, the automation puzzle is initiated. Since there is no concept available for the automation puzzle yet, the hardware puzzle is started directly. The hardware puzzle is played in two distinct phases. In Phase 1, the objective is to solve a combinatorial circuit such that its output becomes '1'. There are 8 inputs for this circuit, each controlled by an on/off switch. Once the combinatorial circuit evaluates to '1', the LED at the output lights up, indicating the completion of the first phase. In Phase 2, another LED blinks, consistently repeating a pattern. This pattern represents a randomly generated Morse code, corresponding to a number from 0 to 9999. Participants use a Morse code table to decipher the correct number. Using four potentiometers, the participants can set a number on a 7-segment display. When this number matches the randomly generated one, the hardware puzzle is solved. Subsequently, the vault puzzle is initiated. In the vault puzzle, a 7-segment display shows a random combination of a letter and a digit. Participants have access to a list containing the correct button combination for the corresponding letter and digit. The vault puzzle consists of 5 levels, each displaying a unique button combination from the list. When participants correctly press the button on the keypad, the level advances, and a new value is shown. Pressing the wrong button restarts the game at level 1. Once all 5 levels are completed, the vault door unlocks, allowing access to the inside of the puzzle box. On the mainboard, there is a 7-segment display showing a code. This code must be relayed to the participants of the bomb game. Once the bomb team receives the code, the puzzle box is considered solved. [[sec:functional]] == Functional Requirements The functional requirements describe the things which are important to the client. This is mainly about the way the product is going to be used, what it is going to look like, and how the product reacts to interaction. This chapter describes all functional requirements of the puzzle box. === The puzzle box .Puzzle box specifications [cols="9h,6h,~"] |=== | ID | <> | Specification | <> | <> | [[req:1,R-001]] The dimensions of the puzzle box are 30×30×30cm ± 5% (Length × Width × Height). | <> | <> | [[req:2,R-002]] The puzzle box extends a maximum of 5cm on the sides and the top. | <> | <> | [[req:3,R-003]] The puzzle box is flat at the bottom. | <> | <> | [[req:4,R-004]] The puzzle box has a key switch at the bottom of the NeoTrellis puzzle. | <> | <> | [[req:5,R-005]] The puzzle box has an indicator LED at the bottom of the NeoTrellis puzzle. | <> | <> | [[req:6,R-006]] The indicator LED turns green when the system is on and not charging. | <> | <> | [[req:7,R-007]] The indicator LED turns blue when the battery is charging. | <> | <> | [[req:8,R-008]] The indicator LED turns red when the battery does not have enough capacity for the duration of one game and is not charging. | <> | <> | [[req:9,R-009]] The puzzle box has a USB-C port at the bottom of the NeoTrellis puzzle for battery charging. | <> | <> | [[req:10,R-010]] The puzzle box has a distance sensor at the bottom to detect if it is lifted. | <> | <> | [[req:11,R-011]] The puzzle box main board (PCB on the bottom plate) includes a speaker. | <> | <> | [[req:12,R-012]] When the puzzle box is lifted, the mainboard speaker emits an alarm sound for at least 10 seconds. It stops only when it has been on a table for another 10 seconds (detected by the distance sensor). | <> | <> | [[req:13,R-013]] When the game is completed, the puzzle box produces a victory sound. | <> | <> | [[req:14,R-014]] Pressing the "identify" button on the web panel causes the indicator LED to blink. | <> | <> | [[req:15,R-015]] Pressing the "identify" button on the web panel triggers a sound from the speaker. | <> | <> | // section 3.7 is inside the citation, and does not refer to section 3.7 in this document [[req:16,R-016]] The game starts once the scheduler time is reached (refer to cite:[Bek23] section 3.7). |=== === The bomb .Bomb specifications [cols="9h,6h,~"] |=== | ID | <> | Specification | <> | <> | [[req:17,R-017]] The bomb includes a 6-digit 7-segment display for showing the remaining playtime. | <> | <> | [[req:18,R-018]] The bomb contains a keypad for entering the disarm code. | <> | <> | [[req:19,R-019]] The 6-digit 7-segment display turns off when no game is in progress. | <> | <> | [[req:20,R-020]] Once the disarm code is entered on the bomb keypad, the game is complete. | <> | <> | [[req:21,R-021]] When the game is finished, the bomb emits a victory sound. | <> | <> | [[req:22,R-022]] The timer on the bomb counts down from 60:00:00 to 00:00:00. | <> | <> | [[req:23,R-023]] Pressing the "identify" button on the web panel causes the indicator LED to blink. | <> | <> | [[req:24,R-024]] Pressing the "identify" button on the web panel triggers a sound from the speaker. |=== === The game .General game specifications [cols="9h,6h,~"] |=== | ID | <> | Specification | <> | <> | [[req:25,R-025]] The game lasts for 1 hour. | <> | <> | [[req:26,R-026]] The game should be solvable within the given playtime, without the player having prior knowledge of the game or its mechanics. | <> | <> | [[req:27,R-027]] The puzzles should be easy enough to solve without any prior knowledge of the game or its mechanics. | <> | <> | [[req:edge-manual-reset,R-167]] A puzzle module can manually be reset at the discretion of the game operator | <> | <> | [[req:edge-skip-puzzle,R-168]] A puzzle module can manually be set as solved at the discretion of the game operator | <> | <> | [[req:28,R-028]] The disarm code for the bomb consists of 4 digits. | <> | <> | [[req:29,R-029]] Once all games are solved, the mainboard PCB displays the disarm code on a red 7-segment 4-digit screen. | <> | <> | [[req:30,R-030]] The puzzle box records the playtime of each game. | <> | <> | [[req:31,R-031]] The puzzle box features 5 playable puzzles. | <> | <> | [[req:32,R-032]] Only one game is active at a time; the other games do not respond to buttons. | <> | <> | [[req:33,R-033]] The game always starts with the NeoTrellis puzzle. |=== ==== NeoTrellis puzzle .NeoTrellis puzzle requirements [cols="9h,6h,~"] |=== | ID | <> | Specification | <> | <> | [[req:34,R-034]] There is an 8x8 LED matrix where each LED can display different colors. | <> | <> | [[req:35,R-035]] At the start of the puzzle, a pattern is displayed as shown in <>. | <> | <> | [[req:36,R-036]] When a button is pressed, the adjacent LEDs and the pressed LED toggle (If an LED is off, it turns on. If an LED is on, it turns off). | <> | <> | [[req:37,R-037]] All LEDs in the Neotrellis that are turned on are blue. | <> | <> | [[req:38,R-038]] The puzzle is considered solved when all LEDs are turned off, and then the software puzzle starts. |=== ==== Software puzzle .Software puzzle requirements [cols="9h,6h,~"] |=== | ID | <> | Specification | <> | <> | [[req:39,R-039]] The software puzzle board has 6 banana plug connectors with different logic gates displayed next to them (Refer to <> for a sketch and <> for a banana plug example). | <> | <> | [[req:40,R-040]] The software puzzle board has 6 banana plug connectors labeled with the letters A through F (Refer to <> for a sketch). | <> | <> | [[req:41,R-041]] At the start of the puzzle box game, the preparer must connect all cables in parallel (horizontally) to the connectors. | <> | <> | [[req:42,R-042]] There are C code blocks visible only to the players on the bomb side, corresponding to the letters A through F (Refer to <> for the codes). | <> | <> | [[req:43,R-043]] The combinations of logic gates to letters are always the same. | <> | <> | [[req:44,R-044]] The puzzle is considered solved when the cables from the logic gates match the code blocks (Refer to <> and <> for the combinations). | <> | <> | [[req:45,R-045]] Once the puzzle is solved, the green indicator LED will light up (Refer to <> and <>). | <> | <> | [[req:46,R-046]] After the puzzle is solved, the automation puzzle begins. |=== ==== Automation puzzle 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="9h,6h,~"] |=== | ID | <> | Specification | <> | <> | [[req:47,R-047]] After the puzzle is solved, the hardware puzzle begins. |=== ==== Hardware puzzle .Hardware puzzle requirements [cols="9h,6h,~"] |=== | ID | <> | Specification | <> | <> | [[req:48,R-048]] There are eight switches on the hardware puzzle board. | <> | <> | [[req:49,R-049]] The hardware puzzle board features a diagram of a combinatorial circuit with 8 inputs (linked to the switches) and 1 output (Refer to <> for a sketch). | <> | <> | [[req:50,R-050]] The hardware puzzle board includes a red 7-segment 4-digit display (Refer to <> for a sketch). | <> | <> | [[req:51,R-051]] There are 4 potentiometers on the hardware puzzle board (Refer to <> for a sketch). | <> | <> | [[req:52,R-052]] A blue LED on the hardware puzzle board displays the morse code. | <> | <> | [[req:53,R-053]] A green LED on the hardware puzzle board indicates whether the combinatorial circuit is solved. | <> | <> | [[req:54,R-054]] At the start of the puzzle, the potentiometers are inactive. | <> | <> | [[req:55,R-055]] The 7-segment display is off at the beginning of the puzzle. | <> | <> | [[req:56,R-056]] The LED for the combinatorial puzzle is off initially. | <> | <> | [[req:57,R-057]] The morse code LED is off at the puzzle's outset. | <> | <> | [[req:58,R-058]] The preparer must set all switches to the down position at the start of the puzzle box game. | <> | <> | [[req:59,R-059]] The preparer must turn all potentiometers to the left (value '0') at the beginning of the puzzle box game. | <> | <> | [[req:60,R-060]] The puzzle consists of two phases. | <> | <> | [[req:61,R-061]] The puzzle begins in phase 1. | <> | <> | [[req:62,R-062]] During the puzzle, the switches must be toggled to obtain a logical '1' at the output of the combinatorial circuit. | <> | <> | [[req:63,R-063]] When the output of the combinatorial circuit equals '1', the green indicator LED turns on (Refer to <> for a sketch). | <> | <> | [[req:64,R-064]] The puzzle proceeds to phase 2 when the output of the combinatorial circuit is a logical '1'. | <> | <> | [[req:65,R-065]] The switches no longer respond once the puzzle enters phase 2. | <> | <> | [[req:66,R-066]] The indicator LED from phase 1 remains green during phase 2. | <> | <> | [[req:67,R-067]] In phase 2, a morse code is displayed using an LED. This morse code represents 4 numbers from 0 to 9 and repeats every second. | <> | <> | [[req:68,R-068]] The morse code is randomly generated. | <> | <> | [[req:69,R-069]] Each potentiometer can be rotated to display a value from 0 to 9 on the corresponding 4-digit 7-segment display. The order of the potentiometers matches the order of the segments on the display (Refer to <> for a sketch). | <> | <> | [[req:70,R-070]] The puzzle is considered solved when the code displayed on the 7-segment 4-digit screen matches the 4 numbers from the morse code. | <> | <> | [[req:71,R-071]] Once the puzzle is solved, the value shown on the 7-segment 4-digit display cannot be changed. | <> | <> | [[req:72,R-072]] A 2-second victory sound is produced by the speaker upon solving the puzzle. | <> | <> | [[req:73,R-073]] During the victory sound, the 7-segment display blinks twice per second. | <> | <> | [[req:74,R-074]] After the victory sound, the puzzle has been solved and the vault puzzle begins. |=== ==== Vault puzzle .Vault puzzle requirements [cols="9h,6h,~"] |=== | ID | <> | Specification | <> | <> | [[req:75,R-075]] The vault puzzle board features a red 7-segment 4-digit display. | <> | <> | [[req:76,R-076]] On the vault puzzle board, there is a 4x4 grid of holes for ventilation and sound. | <> | <> | [[req:77,R-077]] The vault puzzle board includes a vault door, and the inside of the vault is transparent, allowing you to see inside the puzzle box. | <> | <> | [[req:78,R-078]] A sensor is integrated with the vault to detect when the vault is closed. | <> | <> | [[req:79,R-079]] At the beginning of the puzzle box game, the preparer must close the vault. | <> | <> | [[req:80,R-080]] The puzzle starts at level 1. | <> | <> | [[req:81,R-081]] Initially, the 7-segment display shows a code consisting of a letter and a digit. This code represents a valid key combination for level 1 (Refer to <> for all combinations). | <> | <> | [[req:82,R-082]] There are a total of 5 levels. After each level, a key combination is displayed, starting with a letter followed by a digit, which is valid for that level (Refer to <>). | <> | <> | [[req:83,R-083]] Each level has unique key combinations for the button locations (Refer to <>). | <> | <> | [[req:84,R-084]] Pressing the button corresponding to the letter-digit combinations advances the puzzle to the next level. | <> | <> | [[req:85,R-085]] If an incorrect button is pressed, the game resets to level 1. | <> | <> | [[req:86,R-086]] An error sound is produced by the speaker when an incorrect button is pressed. | <> | <> | [[req:87,R-087]] The 7-segment display blinks when an incorrect button is pressed. | <> | <> | [[req:88,R-088]] After completing 5 levels, the puzzle is solved, and the vault opens. |=== === Battery .Battery requirements [cols="9h,6h,~"] |=== | ID | <> | Specification | <> | <> | [[req:pwr-battery,R-089]] The puzzle box is powered by a rechargeable battery. | <> | <> | [[req:90,R-090]] The battery lasts for a minimum of 4 hours. | <> | <> | [[req:91,R-091]] The battery in the puzzle box can be replaced. |=== === Network Communication .Communication requirements [cols="9h,6h,~"] |=== | ID | <> | Specification | <> | <> | [[req:92,R-092]] The puzzle boxes, bombs, and the puzzle box hub must all be able to communicate with each other. | <> | <> | [[req:93,R-093]] Communication between two devices in the network must have a range of at least 20 meters in an open field. |=== === Framework [cols="9h,6h,~"] |=== | ID | <> | Specification | <> | <> | [[req:main-static,R-130]] The main controller and its software do not need to be modified to implement a new puzzle module | <> | <> | [[req:131,R-131]] Puzzle modules can be added and removed while the main controller is powered on | <> | <> | [[req:pm-swap,R-132]] Puzzle modules can be added and removed while the main controller is powered off | <> | <> | [[req:main-interface,R-133]] The puzzle box provides a single external interface for accessing and controlling game state variables |=== === Puzzle box hub .Puzzle box hub general requirements [cols="9h,6h,~"] |=== | ID | <> | Specification | <> | <> | [[req:94,R-094]] The puzzle box hub hosts a website that can be accessed by a device connected to the network. |=== [[sec:technical]] == Technical Requirements The technical specifications describe the specifications that are important for developers. For example, this could include specific requirements related to current, voltage, or communication protocols. This chapter outlines all the technical specifications of the puzzle box. === Wireless communication .Wireless communication requirements [cols="9h,6h,~"] |=== | ID | <> | Specification | <> | <> | [[req:127,R-127]] The wireless communication between the system controller, bomb, and puzzle box operates over a WiFi mesh or WiFi network. |=== === Framework .Development framework requirements [cols="9h,6h,~"] |=== | ID | <> | Specification | <> | <> | [[req:128,R-128]] A framework has been created to assist future groups in the development of the puzzle box. | <> | <> | [[req:129,R-129]] The framework runs on the main puzzle box controller. | <> | <> | [[req:134,R-134]] Puzzle modules are detected by the main controller module. | <> | <> | [[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' |=== === Main controller .Main controller requirements [cols="9h,6h,~"] |=== | ID | <> | Specification | <> | <> | [[req:main-i2c-ctrl,R-136]] The main controller has at least 1 I2C peripheral. | <> | <> | [[req:main-802-11-ap,R-137]] The main controller can connect to a standard 802.11b/g/n access point. | <> | <> | [[req:main-tcp-socket,R-138]] The main controller can serve TCP socket connection(s). | <> | <> | [[req:main-devkit-supplier,R-139]] The main controller is available as a development kit from Farnell. | <> | <> | [[req:140,R-140]] The main controller can communicate over I²C with a speed of 400kb/s | <> | <> | [[req:main-pwr-efficient,R-166]] The main controller is power efficient. |=== === Puzzle module controller [cols="9h,6h,~"] |=== | ID | <> | Specification | <> | <> | [[req:pm-i2c-ctrl,R-141]] The puzzle module controller has at least 1 I2C peripheral. | <> | <> | [[req:pm-gpio,R-142]] The puzzle module controller has enough I/O ports to control a puzzle. | <> | <> | [[req:pm-pwr-efficient,R-143]] The puzzle module is power efficient. | <> | <> | [[req:pm-clk-ctrl,R-144]] The puzzle module has a configurable clock speed. | <> | <> | [[req:pm-devkit-supplier,R-145]] The puzzle module controller is available as a development kit from Farnell. | <> | <> | [[req:146,R-146]] The puzzle module can communicate over I²C with a speed of 400kb/s |=== === Vault puzzle .Vault puzzle requirements [cols="9h,6h,~"] |=== | ID | <> | Specification | <> | <> | [[req:147,R-147]] The vault puzzle can communicate with the main controller using I²C | <> | <> | [[req:148,R-148]] The vault puzzle can produce a sound signal for the buzzer | <> | <> | [[req:149,R-149]] The vault puzzle can lock & unlock a solenoid lock | <> | <> | [[req:150,R-150]] The vault puzzle can translate and obtain a button press from the 3x4 keypad using 5 inputs | <> | <> | [[req:151,R-151]] The vault puzzle can communicate with a 4x 7 SEG. Display using 2 lines (clock & data) | <> | <> | [[req:152,R-152]] The vault puzzle can read a sensor's value to detect if the vault door is open or closed. |=== === Bomb .Bomb requirements [cols="9h,6h,~"] |=== | ID | <> | Specification | <> | <> | [[req:153,R-153]] The bomb can communicate with the hub using a TCP socket connection | <> | <> | [[req:154,R-154]] The bomb can sync. time using the WiFi connection | <> | <> | [[req:155,R-155]] The bomb can retrieve, and store a given code in order to verify it later on input | <> | <> | [[req:156,R-156]] The bomb can be paired to a puzzlebox using the hub's interface |=== == Preconditions This section describes the aspects of the project which have been set as preconditions and cannot be changed. .Preconditions [cols="9h,~"] |=== | ID | Precondition | <> | [[req:160,R-160]] The delivery of components cannot take longer than two weeks. | <> | [[req:161,R-161]] The price of a single puzzle box is not higher than €150. | <> | [[req:162,R-162]] The existing games are used in the puzzle box. | <> | [[req:163,R-163]] The puzzle box is not allowed to make a connection with the Avans network (Eduroam). | <> | [[req:164,R-164]] The bomb hardware cannot be changed. |=== == Documentation This section lists requirements that apply to documentation produced during this project. [cols="9h,6h,~"] |=== | ID | <> | Specification | <> | <> | [[req:157,R-157]] All documentation is written according to the style guide cite:[styleguide] | <> | <> | [[req:158,R-158]] All documentation is manually checked for spelling and grammar mistakes before being published | <> | <> | [[req:159,R-159]] All project documents are examined once by Jonathan Overes from Avans |=== [appendix] == Attachments [[fig:vault-disp-sketch]] .7 Segment 4 digit screen (sketch) image::img/vault-disp-sketch.png[] [[fig:neotrellis-hardware-sketch]] .NeoTrellis example (sketch) image::img/neotrellis-hardware-sketch.png[] [[fig:neotrellis-toggle]] .Toggling LEDs after the user pressed on the button (purple dot) image::img/neotrellis-toggle.png[width=45%] [[fig:neotrellis-start]] .Starting pattern of the NeoTrellis puzzle image::img/neotrellis-start.png[width=45%] [[fig:software-example-sketch]] .Software puzzle example with logical ports (left) and letters A through F (right) image::img/software-example-sketch.png[] [[fig:software-codes-sketch]] .The different code fragments corresponding with the letter A through F image::img/software-codes-sketch.png[height=35%] [[fig:software-cable-sketch]] .Software puzzle cable example image::img/software-cable-sketch.png[] [[fig:hardware-example-sketch]] .Hardware puzzle on the puzzle box image::img/hardware-example-sketch.png[] [[fig:vault-keypad]] .Buttons combinations with level numbers in the top left image::img/vault-keypad.png[width=45%] include::share/footer.adoc[]