diff options
| -rw-r--r-- | docs/makefile | 2 | ||||
| -rw-r--r-- | docs/plugin/helloworld.rb | 13 | ||||
| -rw-r--r-- | docs/requirements.adoc | 198 |
3 files changed, 213 insertions, 0 deletions
diff --git a/docs/makefile b/docs/makefile index cccc231..a3f5597 100644 --- a/docs/makefile +++ b/docs/makefile @@ -1,4 +1,5 @@ all: plan.pdf +all: requirements.pdf # include font.mk @@ -7,6 +8,7 @@ PDFDEPS += ./theme.yml ASCIIDOCTOR_ARGS += --require asciidoctor-bibtex ASCIIDOCTOR_ARGS += --require asciidoctor-pdf +# ASCIIDOCTOR_ARGS += --require ./plugin/helloworld ASCIIDOCTOR_ARGS += --backend pdf ASCIIDOCTOR_ARGS += --attribute pdf-theme=./theme.yml # ASCIIDOCTOR_ARGS += --attribute pdf-fontsdir=./res/font diff --git a/docs/plugin/helloworld.rb b/docs/plugin/helloworld.rb new file mode 100644 index 0000000..7bfc226 --- /dev/null +++ b/docs/plugin/helloworld.rb @@ -0,0 +1,13 @@ +class HelloWorldMacro < Asciidoctor::Extensions::BlockMacroProcessor + use_dsl + named :helloworld + + def process parent, target, attrs + return + end +end + +Asciidoctor::Extensions.register do + block_macro HelloWorldMacro +end + diff --git a/docs/requirements.adoc b/docs/requirements.adoc new file mode 100644 index 0000000..94b532b --- /dev/null +++ b/docs/requirements.adoc @@ -0,0 +1,198 @@ += Project Requirements: Project Puzzlebox +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>>. + +[[tab:moscow]] +.MoSCoW Method cite:[Wik22] +[cols="1,3"] +|=== +| Priority | Description + +| Must have +| Represents essential system requirements. Without these, the system will not +function. +| Should have +| Denotes desirable system features. The system can work without these, but it +lacks necessary elements. +| Could have +| Refers to additional functionalities that can be implemented if there is +extra time. +| Won't have +| 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 +(<<sec:functional>> and <<sec:technical>>). + +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="1,1,10"] +|=== +| ID | Pri. | Specification + +| 1. | M +| 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. + +| 3. | M +| The puzzle box is flat at the bottom. + +| 4. | M +| 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. + +| 6. | M +| 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. + +| 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. + +| 9. | M +| 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. + +| 11. | M +| 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). + +| 13. | W +| 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. + +| 15. | W +| 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]). +|=== + + +=== The bomb +=== The game +==== NeoTrellis puzzle +==== Software puzzle +==== Automation puzzle +==== Hardware puzzle +==== Vault puzzle +=== Battery +=== Network Communication +=== Framework +=== Puzzle box hub + +[[sec:technical]] +== Technical Requirements + +=== Wireless communication +=== Framework +=== Main controller +=== Puzzle module controller +=== Vault puzzle +=== Bomb +== Preconditions +== Documentation + +[appendix] +== Explanatory Images + +// [#alinea1,reftext='alinea 1'] +// Hoi ik ben een alinea +// +// <<alinea1>> + +include::share/footer.adoc[] + |