From d6eaa7a8a6e4332c473368230e0a0782a737bd39 Mon Sep 17 00:00:00 2001 From: lonkaars Date: Sat, 20 Apr 2024 16:12:22 +0200 Subject: small refactor + create software design document --- docs/design.adoc | 5 + docs/makefile | 6 +- docs/plan.adoc | 2 +- docs/reqs.adoc | 723 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/requirements.adoc | 723 ------------------------------------------------- docs/research.adoc | 24 +- docs/share/meta.adoc | 31 ++- 7 files changed, 766 insertions(+), 748 deletions(-) create mode 100644 docs/design.adoc create mode 100644 docs/reqs.adoc delete mode 100644 docs/requirements.adoc diff --git a/docs/design.adoc b/docs/design.adoc new file mode 100644 index 0000000..b653633 --- /dev/null +++ b/docs/design.adoc @@ -0,0 +1,5 @@ +:document: Software Design +include::share/meta.adoc[] + + +include::share/footer.adoc[] diff --git a/docs/makefile b/docs/makefile index 496a6e6..1fbb5b4 100644 --- a/docs/makefile +++ b/docs/makefile @@ -1,6 +1,7 @@ all: plan.pdf -all: requirements.pdf +all: reqs.pdf all: research.pdf +all: design.pdf # include font.mk @@ -15,9 +16,6 @@ ASCIIDOCTOR_ARGS += --require asciidoctor-pdf # ASCIIDOCTOR_ARGS += --require ./plugin/helloworld ASCIIDOCTOR_ARGS += --require asciidoctor-interdoc-reftext ASCIIDOCTOR_ARGS += --backend pdf -ASCIIDOCTOR_ARGS += --attribute pdf-theme=./theme.yml -# ASCIIDOCTOR_ARGS += --attribute pdf-fontsdir=./res/font -ASCIIDOCTOR_ARGS += --attribute bibtex-file=./share/refs.bib %.pdf: %.adoc $(PDFDEPS) bundle exec asciidoctor $(ASCIIDOCTOR_ARGS) $< diff --git a/docs/plan.adoc b/docs/plan.adoc index 8825459..e935c86 100644 --- a/docs/plan.adoc +++ b/docs/plan.adoc @@ -1,4 +1,4 @@ -= Project Plan: {project} +:document: Project Plan include::share/meta.adoc[] == Introduction diff --git a/docs/reqs.adoc b/docs/reqs.adoc new file mode 100644 index 0000000..edddbdd --- /dev/null +++ b/docs/reqs.adoc @@ -0,0 +1,723 @@ +: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="8h,5h,~"] +|=== +| 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="8h,5h,~"] +|=== +| 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="8h,5h,~"] +|=== +| 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:167,R-167]] A puzzle module can manually be reset at the discretion of the game operator + +| <> | <> | +[[req:168,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="8h,5h,~"] +|=== +| 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="8h,5h,~"] +|=== +| 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="8h,5h,~"] +|=== +| ID | <> | Specification + +| <> | <> | +[[req:47,R-047]] After the puzzle is solved, the hardware puzzle begins. +|=== + +==== Hardware puzzle + +.Hardware puzzle requirements +[cols="8h,5h,~"] +|=== +| 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="8h,5h,~"] +|=== +| 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="8h,5h,~"] +|=== +| ID | <> | Specification + +| <> | <> | +[[req:89,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="8h,5h,~"] +|=== +| 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="8h,5h,~"] +|=== +| ID | <> | Specification + +| <> | <> | +[[req:130,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:132,R-132]] Puzzle modules can be added and removed while the main controller is powered off + +| <> | <> | +[[req:133,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="8h,5h,~"] +|=== +| 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="8h,5h,~"] +|=== +| 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="8h,5h,~"] +|=== +| 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="8h,5h,~"] +|=== +| 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="8h,5h,~"] +|=== +| 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="8h,5h,~"] +|=== +| 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="8h,5h,~"] +|=== +| 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="8h,~"] +|=== +| 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="8h,5h,~"] +|=== +| 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[] + diff --git a/docs/requirements.adoc b/docs/requirements.adoc deleted file mode 100644 index e3225a5..0000000 --- a/docs/requirements.adoc +++ /dev/null @@ -1,723 +0,0 @@ -= Project Requirements: {project} -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="8h,5h,~"] -|=== -| 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="8h,5h,~"] -|=== -| 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="8h,5h,~"] -|=== -| 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:167,R-167]] A puzzle module can manually be reset at the discretion of the game operator - -| <> | <> | -[[req:168,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="8h,5h,~"] -|=== -| 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="8h,5h,~"] -|=== -| 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="8h,5h,~"] -|=== -| ID | <> | Specification - -| <> | <> | -[[req:47,R-047]] After the puzzle is solved, the hardware puzzle begins. -|=== - -==== Hardware puzzle - -.Hardware puzzle requirements -[cols="8h,5h,~"] -|=== -| 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="8h,5h,~"] -|=== -| 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="8h,5h,~"] -|=== -| ID | <> | Specification - -| <> | <> | -[[req:89,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="8h,5h,~"] -|=== -| 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="8h,5h,~"] -|=== -| ID | <> | Specification - -| <> | <> | -[[req:130,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:132,R-132]] Puzzle modules can be added and removed while the main controller is powered off - -| <> | <> | -[[req:133,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="8h,5h,~"] -|=== -| 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="8h,5h,~"] -|=== -| 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="8h,5h,~"] -|=== -| 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="8h,5h,~"] -|=== -| 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="8h,5h,~"] -|=== -| 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="8h,5h,~"] -|=== -| 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="8h,5h,~"] -|=== -| 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="8h,~"] -|=== -| 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="8h,5h,~"] -|=== -| 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[] - diff --git a/docs/research.adoc b/docs/research.adoc index 7e5b78c..5d4f381 100644 --- a/docs/research.adoc +++ b/docs/research.adoc @@ -1,4 +1,4 @@ -= Research: {project} +:document: Research include::share/meta.adoc[] == Microcontrollers used in the current state. @@ -124,15 +124,14 @@ controller and controller used in puzzle modules. The following criteria were used to compare MCUs that are suitable candidates as main controller unit: -* Must have at least 1 I^2^C peripheral - (<>). +* Must have at least 1 I^2^C peripheral (<>). * Must be able to connect to a standard 802.11b/g/n access point - (<>). + (<>). * Must be able to serve TCP socket connection(s) - (<>). -* Should be power efficient (<>). + (<>). +* Should be power efficient (<>). * Is available as a development kit from Farnell - (<>). + (<>). <> lists the considered MCU options matching the above criteria. This list is a compilation of microcontroller offerings from the following @@ -160,14 +159,13 @@ The Raspberry Pi Pico W board is utilized during development. The following criteria were used to compare MCUs that are suitable candidates for controlling the puzzle modules: -* Must have at least 1 I^2^C peripheral - (<>). +* Must have at least 1 I^2^C peripheral (<>). * Should has enough I/O ports to directly control moderately complex puzzles - (<>). -* Should be power efficient (<>). + (<>). +* Should be power efficient (<>). * Is available as a development kit from Farnell - (<>). -* Has a configurable clock speed (<>). + (<>). +* Has a configurable clock speed (<>). <> lists the considered MCU options matching the above criteria. This list is a compilation of microcontroller offerings from the following diff --git a/docs/share/meta.adoc b/docs/share/meta.adoc index 0b6cb78..15d8d18 100644 --- a/docs/share/meta.adoc +++ b/docs/share/meta.adoc @@ -1,8 +1,13 @@ -:sectnums: -:title-page: -:toc: -:toclevels: 4 -:pagenums: +// (these files are included from the parent directory) +:pdf-theme: ./theme.yml +// :pdf-fontsdir: ./res/font +:bibtex-file: ./share/refs.bib + +// document / project info +ifndef::document[] +:document: DOCUMENT TITLE +endif::[] +:project: Project Puzzlebox :revnumber: 0.0 :revdate: 2024-04-01 :revremark: draft @@ -10,7 +15,19 @@ :author_2: Loek Le Blansch :author_3: Lars Faase :author_4: Elwin Hammer + +// numbering / reference styles +:sectnums: +:toclevels: 4 +:pagenums: :xrefstyle: short -:project: Project Puzzlebox -// see https://docs.asciidoctor.org/asciidoc/latest/attributes/document-attributes-ref +// (set and display title) += {document}: {project} +// start each document with a title page +:title-page: +// followed by a table of contents +:toc: + +// also https://docs.asciidoctor.org/asciidoc/latest/attributes/document-attributes-ref + -- cgit v1.2.3