diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Gemfile | 4 | ||||
| -rw-r--r-- | docs/makefile | 6 | ||||
| -rw-r--r-- | docs/requirements.adoc | 512 | ||||
| -rw-r--r-- | docs/share/glossary.adoc | 3 |
4 files changed, 482 insertions, 43 deletions
diff --git a/docs/Gemfile b/docs/Gemfile index 67cd54a..99f5ca1 100644 --- a/docs/Gemfile +++ b/docs/Gemfile @@ -1,7 +1,11 @@ ruby '~> 3.0' source 'https://rubygems.org' +gem 'json' # required for bibtex + gem 'asciidoctor', '~> 2.0' gem 'asciidoctor-pdf', '~> 2.3' gem 'asciidoctor-bibtex', '~> 0.8.0' +# gem 'asciidoctor-interdoc-reftext', '~> 0.5.2' +gem 'asciidoctor-interdoc-reftext', git: 'https://github.com/lonkaars/asciidoctor-interdoc-reftext' diff --git a/docs/makefile b/docs/makefile index a3f5597..e177f6d 100644 --- a/docs/makefile +++ b/docs/makefile @@ -6,13 +6,17 @@ all: requirements.pdf # PDFDEPS += $(ALL_FONTS) PDFDEPS += ./theme.yml +# uncomment to debug include errors +# ASCIIDOCTOR_ARGS += --trace + ASCIIDOCTOR_ARGS += --require asciidoctor-bibtex 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) - asciidoctor $(ASCIIDOCTOR_ARGS) $< + bundle exec asciidoctor $(ASCIIDOCTOR_ARGS) $< diff --git a/docs/requirements.adoc b/docs/requirements.adoc index 94b532b..2170484 100644 --- a/docs/requirements.adoc +++ b/docs/requirements.adoc @@ -15,16 +15,16 @@ The priority of specifications is indicated using the MoSCoW method, see |=== | Priority | Description -| Must have +| [[must,M]]<<must,Must have>> | Represents essential system requirements. Without these, the system will not function. -| Should have +| [[should,S]]<<should,Should have>> | Denotes desirable system features. The system can work without these, but it lacks necessary elements. -| Could have +| [[could,C]]<<could,Could have>> | Refers to additional functionalities that can be implemented if there is extra time. -| Won't have +| [[wont,W]]<<wont,Won't have>> | Specifies requirements that will not be implemented in the current version but may be considered in a future release. |=== @@ -112,87 +112,515 @@ describes all functional requirements of the puzzle box. |=== | ID | Pri. | Specification -| 1. | M -| The dimensions of the puzzle box are 30×30×30cm ± 5% (Length × Width × Height). +| 001 | <<must>> | +The dimensions of the puzzle box are 30×30×30cm ± 5% (Length × Width × Height). -| 2. | M -| The puzzle box extends a maximum of 5cm on the sides and the top. +| 002 | <<must>> | +The puzzle box extends a maximum of 5cm on the sides and the top. -| 3. | M -| The puzzle box is flat at the bottom. +| 003 | <<must>> | +The puzzle box is flat at the bottom. -| 4. | M -| The puzzle box has a key switch at the bottom of the NeoTrellis puzzle. +| <<req:4>> | <<must>> | +[[req:4,R-04]] The puzzle box has a key switch at the bottom of the NeoTrellis puzzle. -| 5. | M -| The puzzle box has an indicator LED at the bottom of the NeoTrellis puzzle. +| <<req:5>> | <<must>> | +[[req:5,R-05]] The puzzle box has an indicator LED at the bottom of the NeoTrellis puzzle. -| 6. | M -| The indicator LED turns green when the system is on and not charging. +| 006 | <<must>> | +The indicator LED turns green when the system is on and not charging. -| 7. | M -| The indicator LED turns blue when the battery is charging. +| 007 | <<must>> | +The indicator LED turns blue when the battery is charging. -| 8. | M -| The indicator LED turns red when the battery does not have enough capacity for the duration of one game and is not charging. +| 008 | <<must>> | +The indicator LED turns red when the battery does not have enough capacity for the duration of one game and is not charging. -| 9. | M -| The puzzle box has a USB-C port at the bottom of the NeoTrellis puzzle for battery charging. +| 009 | <<must>> | +The puzzle box has a USB-C port at the bottom of the NeoTrellis puzzle for battery charging. -| 10. | M -| The puzzle box has a distance sensor at the bottom to detect if it is lifted. +| 010 | <<must>> | +The puzzle box has a distance sensor at the bottom to detect if it is lifted. -| 11. | M -| The puzzle box main board (PCB on the bottom plate) includes a speaker. +| 011 | <<must>> | +The puzzle box main board (PCB on the bottom plate) includes a speaker. -| 12 | W -| 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). +| 012 | <<wont>> | +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). -| 13. | W -| When the game is completed, the puzzle box produces a victory sound. +| 013 | <<wont>> | +When the game is completed, the puzzle box produces a victory sound. -| 14. | W -| Pressing the "identify" button on the web panel causes the indicator LED to blink. +| 014 | <<wont>> | +Pressing the "identify" button on the web panel causes the indicator LED to blink. -| 15. | W -| Pressing the "identify" button on the web panel triggers a sound from the speaker. +| 015 | <<wont>> | +Pressing the "identify" button on the web panel triggers a sound from the speaker. -| 16. | W -| The game starts once the scheduler time is reached (refer to section 3.7 - [2]). +| 016 | <<wont>> | +The game starts once the scheduler time is reached (refer to section 3.7 - [2]). |=== - === The bomb + +.Puzzle box specifications +[cols="1,1,10"] +|=== +| ID | Pri. | Specification + +| 017 | <<must>> | +The bomb includes a 6-digit 7-segment display for showing the remaining playtime. + +| 018 | <<must>> | +The bomb contains a keypad for entering the disarm code. + +| 019 | <<wont>> | +The 6-digit 7-segment display turns off when no game is in progress. + +| 020 | <<wont>> | +Once the disarm code is entered on the bomb keypad, the game is complete. + +| 021 | <<wont>> | +When the game is finished, the bomb emits a victory sound. + +| 022 | <<wont>> | +The timer on the bomb counts down from 60:00:00 to 00:00:00. + +| 023 | <<wont>> | +Pressing the "identify" button on the web panel causes the indicator LED to blink. + +| 024 | <<wont>> | +Pressing the "identify" button on the web panel triggers a sound from the speaker. + +|=== + === The game + +[cols="1,1,10"] +|=== +| 025 | <<wont>> | +The game lasts for 1 hour. + +| 026 | <<wont>> | +The game should be solvable within the given playtime, without the player having prior knowledge of the game or its mechanics. + +| 027 | <<must>> | +The puzzles should be easy enough to solve without any prior knowledge of the game or its mechanics. + +| 167 | <<must>> | +A puzzle module can manually be reset at the discretion of the game operator + +| 168 | <<must>> | +A puzzle module can manually be set as solved at the discretion of the game operator + +| 028 | <<wont>> | +The disarm code for the bomb consists of 4 digits. + +| 029 | <<wont>> | +Once all games are solved, the mainboard PCB displays the disarm code on a red 7-segment 4-digit screen. + +| 030 | <<wont>> | +The puzzle box records the playtime of each game. + +| 031 | <<wont>> | +The puzzle box features 5 playable puzzles. + +| 032 | <<wont>> | +Only one game is active at a time; the other games do not respond to buttons. + +| 033 | <<wont>> | +The game always starts with the NeoTrellis puzzle. +|=== + ==== NeoTrellis puzzle + +[cols="1,1,10"] +|=== +| 034 | <<must>> | +There is an 8x8 LED matrix where each LED can display different colors. + +| 035 | <<wont>> | +At the start of the puzzle, a pattern is displayed as shown in Figure 4. + +| 036 | <<wont>> | +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). + +| 037 | <<wont>> | +All LEDs in the Neotrellis that are turned on are blue. + +| 038 | <<wont>> | +The puzzle is considered solved when all LEDs are turned off, and then the software puzzle starts. +|=== + ==== Software puzzle + +[cols="1,1,10"] +|=== +| 039 | <<should>> | +The software puzzle board has 6 banana plug connectors with different logic gates displayed next to them (Refer to Figure 5 for a sketch and Figure 7 for a banana plug example). + +| 040 | <<should>> | +The software puzzle board has 6 banana plug connectors labeled with the letters A through F (Refer to Figure 5 for a sketch). + +| 041 | <<should>> | +At the start of the puzzle box game, the preparer must connect all cables in parallel (horizontally) to the connectors. + +| 042 | <<wont>> | +There are C code blocks visible only to the players on the bomb side, corresponding to the letters A through F (Refer to Figure 6 for the codes). + +| 043 | <<should>> | +The combinations of logic gates to letters are always the same. + +| 044 | <<wont>> | +The puzzle is considered solved when the cables from the logic gates match the code blocks (Refer to Figure 5 and Figure 6 for the combinations). + +| 045 | <<wont>> | +Once the puzzle is solved, the green indicator LED will light up (Refer to Figure 5 and Figure 6). + +| 046 | <<wont>> | +After the puzzle is solved, the automation puzzle begins. +|=== + ==== Automation puzzle + +[cols="1,1,10"] +|=== +| 047 | <<wont>> | +After the puzzle is solved, the hardware puzzle begins. +|=== + ==== Hardware puzzle + +[cols="1,1,10"] +|=== +| 048 | <<should>> | +There are eight switches on the hardware puzzle board. + +| 049 | <<should>> | +The hardware puzzle board features a diagram of a combinatorial circuit with 8 inputs (linked to the switches) and 1 output (Refer to Figure 8 for a sketch). + +| 050 | <<should>> | +The hardware puzzle board includes a red 7-segment 4-digit display (Refer to Figure 8 for a sketch). + +| 051 | <<should>> | +There are 4 potentiometers on the hardware puzzle board (Refer to Figure 8 for a sketch). + +| 052 | <<should>> | +A blue LED on the hardware puzzle board displays the morse code. + +| 053 | <<should>> | +A green LED on the hardware puzzle board indicates whether the combinatorial circuit is solved. + +| 054 | <<wont>> | +At the start of the puzzle, the potentiometers are inactive. + +| 055 | <<wont>> | +The 7-segment display is off at the beginning of the puzzle. + +| 056 | <<wont>> | +The LED for the combinatorial puzzle is off initially. + +| 057 | <<wont>> | +The morse code LED is off at the puzzle's outset. + +| 058 | <<must>> | +The preparer must set all switches to the down position at the start of the puzzle box game. + +| 059 | <<must>> | +The preparer must turn all potentiometers to the left (value '0') at the beginning of the puzzle box game. + +| 060 | <<wont>> | +The puzzle consists of two phases. + +| 061 | <<wont>> | +The puzzle begins in phase 1. + +| 062 | <<wont>> | +During the puzzle, the switches must be toggled to obtain a logical '1' at the output of the combinatorial circuit. + +| 063 | <<wont>> | +When the output of the combinatorial circuit equals '1', the green indicator LED turns on (Refer to Figure 8 for a sketch). + +| 064 | <<wont>> | +The puzzle proceeds to phase 2 when the output of the combinatorial circuit is a logical '1'. + +| 065 | <<wont>> | +The switches no longer respond once the puzzle enters phase 2. + +| 066 | <<wont>> | +The indicator LED from phase 1 remains green during phase 2. + +| 067 | <<wont>> | +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. + +| 068 | <<wont>> | +The morse code is randomly generated. + +| 069 | <<wont>> | +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 Figure 8 for a sketch). + +| 070 | <<wont>> | +The puzzle is considered solved when the code displayed on the 7-segment 4-digit screen matches the 4 numbers from the morse code. + +| 071 | <<wont>> | +Once the puzzle is solved, the value shown on the 7-segment 4-digit display cannot be changed. + +| 072 | <<wont>> | +A 2-second victory sound is produced by the speaker upon solving the puzzle. + +| 073 | <<wont>> | +During the victory sound, the 7-segment display blinks twice per second. + +| 074 | <<wont>> | +After the victory sound, the puzzle has been solved and the vault puzzle begins. +|=== + ==== Vault puzzle + +[cols="1,1,10"] +|=== +| 075 | <<should>> | +The vault puzzle board features a red 7-segment 4-digit display. + +| 076 | <<should>> | +On the vault puzzle board, there is a 4x4 grid of holes for ventilation and sound. + +| 077 | <<should>> | +The vault puzzle board includes a vault door, and the inside of the vault is transparent, allowing you to see inside the puzzle box. + +| 078 | <<should>> | +A sensor is integrated with the vault to detect when the vault is closed. + +| 079 | <<must>> | +At the beginning of the puzzle box game, the preparer must close the vault. + +| 080 | <<wont>> | +The puzzle starts at level 1. + +| 081 | <<wont>> | +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 Figure 9 for all combinations). + +| 082 | <<wont>> | +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 Figure 9). + +| 083 | <<wont>> | +Each level has unique key combinations for the button locations (Refer to Figure 9). + +| 084 | <<wont>> | +Pressing the button corresponding to the letter-digit combinations advances the puzzle to the next level. + +| 085 | <<wont>> | +If an incorrect button is pressed, the game resets to level 1. + +| 086 | <<wont>> | +An error sound is produced by the speaker when an incorrect button is pressed. + +| 087 | <<wont>> | +The 7-segment display blinks when an incorrect button is pressed. + +| 088 | <<wont>> | +After completing 5 levels, the puzzle is solved, and the vault opens. +|=== + === Battery + +[cols="1,1,10"] +|=== +| 089 | <<must>> | +The puzzle box is powered by a rechargeable battery. + +| 090 | <<must>> | +The battery lasts for a minimum of 4 hours. + +| 091 | <<could>> | +The battery in the puzzle box can be replaced. +|=== + === Network Communication + +[cols="1,1,10"] +|=== +| 092 | <<wont>> | +The puzzle boxes, bombs, and the puzzle box hub must all be able to communicate with each other. + +| 093 | <<must>> | +Communication between two devices in the network must have a range of at least 20 meters in an open field. +|=== + === Framework + +[cols="1,1,10"] +|=== +| 130 | <<must>> | +The main controller and its software do not need to be modified to implement a new puzzle module + +| 131 | <<could>> | +Puzzle modules can be added and removed while the main controller is powered on + +| 132 | <<must>> | +Puzzle modules can be added and removed while the main controller is powered off + +| 133 | <<must>> | +The puzzle box provides a single external interface for accessing and controlling game state variables +|=== + === Puzzle box hub +[cols="1,1,10"] +|=== +| 094 | <<wont>> | +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 + +[cols="1,1,10"] +|=== +| 127 | <<must>> | +The wireless communication between the system controller, bomb, and puzzle box operates over a WiFi mesh or WiFi network. +|=== + === Framework + +[cols="1,1,10"] +|=== +| 128 | <<must>> | +A framework has been created to assist future groups in the development of the puzzle box. + +| 129 | <<must>> | +The framework runs on the main puzzle box controller. + +| 134 | <<must>> | +Puzzle modules are detected by the main controller module. + +| 135 | <<must>> | +Puzzle modules are initialized by the main controller module. + +| 165 | <<must>> | +Puzzle modules repeatedly send 'update' messages to the main controller while their global state is 'uninitialized' +|=== + === Main controller + +[cols="1,1,10"] +|=== +| 136 | <<must>> | +The main controller has at least 1 I2C peripheral. + +| 137 | <<must>> | +The main controller can connect to a standard 802.11b/g/n access point. + +| 138 | <<must>> | +The main controller can serve TCP socket connection(s). + +| 139 | <<must>> | +The main controller is available as a development kit from Farnell. + +| 140 | <<should>> | +The main controller can communicate over I²C with a speed of 400kb/s + +| 166 | <<should>> | +The main controller is power efficient. +|=== + === Puzzle module controller + +[cols="1,1,10"] +|=== +| 141 | <<must>> | +The puzzle module controller has at least 1 I2C peripheral. + +| 142 | <<should>> | +The puzzle module controller has enough I/O ports to control a puzzle. + +| 143 | <<should>> | +The puzzle module is power efficient. + +| 144 | <<must>> | +The puzzle module has a configurable clock speed. + +| 145 | <<must>> | +The puzzle module controller is available as a development kit from Farnell. + +| 146 | <<should>> | +The puzzle module can communicate over I²C with a speed of 400kb/s +|=== + === Vault puzzle + +[cols="1,1,10"] +|=== +| 147 | <<must>> | +The vault puzzle can communicate with the main controller using I²C + +| 148 | <<wont>> | +The vault puzzle can produce a sound signal for the buzzer + +| 149 | <<must>> | +The vault puzzle can lock & unlock a solenoid lock + +| 150 | <<must>> | +The vault puzzle can translate and obtain a button press from the 3x4 keypad using 5 inputs + +| 151 | <<must>> | +The vault puzzle can communicate with a 4x 7 SEG. Display using 2 lines (clock & data) + +| 152 | <<should>> | +The vault puzzle can read a sensor's value to detect if the vault door is open or closed. +|=== + === Bomb + +[cols="1,1,10"] +|=== +| 153 | <<wont>> | +The bomb can communicate with the hub using a TCP socket connection + +| 154 | <<must>> | +The bomb can sync. time using the WiFi connection + +| 155 | <<wont>> | +The bomb can retrieve, and store a given code in order to verify it later on input + +| 156 | <<should>> | +The bomb can be paired to a puzzlebox using the hub's interface +|=== + == Preconditions + +[cols="1,11"] +|=== +| 160 | The delivery of components cannot take longer than two weeks. +| 161 | The price of a single puzzle box is not higher than €150. +| 162 | The existing games are used in the puzzle box. +| 163 | The puzzle box is not allowed to make a connection with the Avans network (Eduroam). +| 164 | The bomb hardware cannot be changed. +|=== + == Documentation +[cols="1,1,10"] +|=== +| 157 | <<should>> | +All documentation is written according to the style guide [3] + +| 158 | <<should>> | +All documentation is manually checked for spelling and grammar mistakes before being published + +| 159 | <<must>> | +All project documents are examined once by Jonathan Overes from Avans +|=== + [appendix] == Explanatory Images -// [#alinea1,reftext='alinea 1'] -// Hoi ik ben een alinea -// -// <<alinea1>> - include::share/footer.adoc[] diff --git a/docs/share/glossary.adoc b/docs/share/glossary.adoc index 5ba8340..b0192a0 100644 --- a/docs/share/glossary.adoc +++ b/docs/share/glossary.adoc @@ -3,4 +3,7 @@ [glossary] RPI:: Raspberry Pi +Main board:: The main board is the PCB on the bottom of the puzzle box, this communicates with the puzzles and the bomb +Puzzle box hub:: The puzzle box hub communicates with the puzzle box and the bomb, as well as helps with configuring them +SID:: security identifiers |