From 898bc5d79c70c859d66b8c1548446c6e45302421 Mon Sep 17 00:00:00 2001 From: lonkaars Date: Fri, 12 Apr 2024 17:06:39 +0200 Subject: fix xrefs + add figures --- docs/img/22-23/HardwarePuzzel.png | Bin 0 -> 283478 bytes docs/img/22-23/Kluis.png | Bin 0 -> 246643 bytes docs/img/22-23/Neotrellis.png | Bin 0 -> 293754 bytes docs/img/22-23/SV.png | Bin 0 -> 237192 bytes docs/img/22-23/SoftwarePuzzel.png | Bin 0 -> 323720 bytes docs/img/Figures-puzzlebox-bomb.png | Bin 0 -> 25112 bytes docs/img/Figures-vault-puzzle-io.png | Bin 0 -> 33649 bytes docs/img/main-controller-state.svg | 3 + docs/img/main-controller-top.svg | 3 + docs/img/planning-condensed.svg | 3 + docs/img/power-supply-top.svg | 3 + docs/img/puzzle-bus-connector.svg | 5558 ++++++++++++++++++++++++++++++ docs/img/puzzle-module-common-state.svg | 3 + docs/img/puzzle-module-top.svg | 3 + docs/img/sequence-puzzle-finish.svg | 3 + docs/img/sequence-puzzle-module-init.svg | 3 + docs/img/system-bus.svg | 3 + docs/img/system-top.svg | 3 + 18 files changed, 5588 insertions(+) create mode 100644 docs/img/22-23/HardwarePuzzel.png create mode 100644 docs/img/22-23/Kluis.png create mode 100644 docs/img/22-23/Neotrellis.png create mode 100644 docs/img/22-23/SV.png create mode 100644 docs/img/22-23/SoftwarePuzzel.png create mode 100644 docs/img/Figures-puzzlebox-bomb.png create mode 100644 docs/img/Figures-vault-puzzle-io.png create mode 100644 docs/img/main-controller-state.svg create mode 100644 docs/img/main-controller-top.svg create mode 100644 docs/img/planning-condensed.svg create mode 100644 docs/img/power-supply-top.svg create mode 100644 docs/img/puzzle-bus-connector.svg create mode 100644 docs/img/puzzle-module-common-state.svg create mode 100644 docs/img/puzzle-module-top.svg create mode 100644 docs/img/sequence-puzzle-finish.svg create mode 100644 docs/img/sequence-puzzle-module-init.svg create mode 100644 docs/img/system-bus.svg create mode 100644 docs/img/system-top.svg (limited to 'docs/img') diff --git a/docs/img/22-23/HardwarePuzzel.png b/docs/img/22-23/HardwarePuzzel.png new file mode 100644 index 0000000..fe3f260 Binary files /dev/null and b/docs/img/22-23/HardwarePuzzel.png differ diff --git a/docs/img/22-23/Kluis.png b/docs/img/22-23/Kluis.png new file mode 100644 index 0000000..43a2257 Binary files /dev/null and b/docs/img/22-23/Kluis.png differ diff --git a/docs/img/22-23/Neotrellis.png b/docs/img/22-23/Neotrellis.png new file mode 100644 index 0000000..adc650b Binary files /dev/null and b/docs/img/22-23/Neotrellis.png differ diff --git a/docs/img/22-23/SV.png b/docs/img/22-23/SV.png new file mode 100644 index 0000000..f63d1ea Binary files /dev/null and b/docs/img/22-23/SV.png differ diff --git a/docs/img/22-23/SoftwarePuzzel.png b/docs/img/22-23/SoftwarePuzzel.png new file mode 100644 index 0000000..86c9e94 Binary files /dev/null and b/docs/img/22-23/SoftwarePuzzel.png differ diff --git a/docs/img/Figures-puzzlebox-bomb.png b/docs/img/Figures-puzzlebox-bomb.png new file mode 100644 index 0000000..20d33da Binary files /dev/null and b/docs/img/Figures-puzzlebox-bomb.png differ diff --git a/docs/img/Figures-vault-puzzle-io.png b/docs/img/Figures-vault-puzzle-io.png new file mode 100644 index 0000000..74e420c Binary files /dev/null and b/docs/img/Figures-vault-puzzle-io.png differ diff --git a/docs/img/main-controller-state.svg b/docs/img/main-controller-state.svg new file mode 100644 index 0000000..6e0333b --- /dev/null +++ b/docs/img/main-controller-state.svg @@ -0,0 +1,3 @@ + + +
Reset
Playing
Solved
 \ No newline at end of file diff --git a/docs/img/main-controller-top.svg b/docs/img/main-controller-top.svg new file mode 100644 index 0000000..5bb7cda --- /dev/null +++ b/docs/img/main-controller-top.svg @@ -0,0 +1,3 @@ + + +
Main controller
Puzzle bus
Wi-Fi
 \ No newline at end of file diff --git a/docs/img/planning-condensed.svg b/docs/img/planning-condensed.svg new file mode 100644 index 0000000..e693b95 --- /dev/null +++ b/docs/img/planning-condensed.svg @@ -0,0 +1,3 @@ + + +
16
13
7
10
11
12
Research
Planning
Design
Main controller development
Side 1 development
Side 2 development
Side 3 development
Side 4 development
Test development
week no.
Validation
Documentation
 \ No newline at end of file diff --git a/docs/img/power-supply-top.svg b/docs/img/power-supply-top.svg new file mode 100644 index 0000000..89107a6 --- /dev/null +++ b/docs/img/power-supply-top.svg @@ -0,0 +1,3 @@ + + +
Power supply
Puzzle bus
Charger
 \ No newline at end of file diff --git a/docs/img/puzzle-bus-connector.svg b/docs/img/puzzle-bus-connector.svg new file mode 100644 index 0000000..9a45137 --- /dev/null +++ b/docs/img/puzzle-bus-connector.svg @@ -0,0 +1,5558 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/img/puzzle-module-common-state.svg b/docs/img/puzzle-module-common-state.svg new file mode 100644 index 0000000..b5688ef --- /dev/null +++ b/docs/img/puzzle-module-common-state.svg @@ -0,0 +1,3 @@ + + +
Uninitialized
Reset
Playing
Solved
 \ No newline at end of file diff --git a/docs/img/puzzle-module-top.svg b/docs/img/puzzle-module-top.svg new file mode 100644 index 0000000..79c16ed --- /dev/null +++ b/docs/img/puzzle-module-top.svg @@ -0,0 +1,3 @@ + + +
Puzzle module
Puzzle bus
Puzzle outputs
Puzzle inputs
 \ No newline at end of file diff --git a/docs/img/sequence-puzzle-finish.svg b/docs/img/sequence-puzzle-finish.svg new file mode 100644 index 0000000..d1dc35a --- /dev/null +++ b/docs/img/sequence-puzzle-finish.svg @@ -0,0 +1,3 @@ + + +
Main
state := solved
A
state := solved
B
update
update
main state?
= solved
update
state?
= solved
1
2
3
4
 \ No newline at end of file diff --git a/docs/img/sequence-puzzle-module-init.svg b/docs/img/sequence-puzzle-module-init.svg new file mode 100644 index 0000000..2e8db4f --- /dev/null +++ b/docs/img/sequence-puzzle-module-init.svg @@ -0,0 +1,3 @@ + + +
Main
update
A
state := reset
state := reset
power on
update
 \ No newline at end of file diff --git a/docs/img/system-bus.svg b/docs/img/system-bus.svg new file mode 100644 index 0000000..440227a --- /dev/null +++ b/docs/img/system-bus.svg @@ -0,0 +1,3 @@ + + +
Puzzle bus
(I²C + power)
Main controller
Puzzle module 3
(neotrellis)
Puzzle module 4
(safe)
Puzzle module 1
(software)
Puzzle module 2
(hardware)
Power supply
(battery pack)
 \ No newline at end of file diff --git a/docs/img/system-top.svg b/docs/img/system-top.svg new file mode 100644 index 0000000..0a9e8c0 --- /dev/null +++ b/docs/img/system-top.svg @@ -0,0 +1,3 @@ + + +
Puzzle outputs
Puzzle box
Puzzle inputs
Player(s)
Charger
Wi-Fi
Bomb
 \ No newline at end of file -- cgit v1.2.3 From 75f953cc96f09a5693672552b0ba0f53173b0262 Mon Sep 17 00:00:00 2001 From: lonkaars Date: Fri, 19 Apr 2024 16:14:31 +0200 Subject: finish requirements document --- docs/img/requirements/hardware-example.png | Bin 0 -> 94788 bytes docs/img/requirements/neotrellis-hardware.png | Bin 0 -> 71544 bytes docs/img/requirements/neotrellis-start.png | Bin 0 -> 3078 bytes docs/img/requirements/neotrellis-toggle.png | Bin 0 -> 22898 bytes docs/img/requirements/software-cable.png | Bin 0 -> 33947 bytes docs/img/requirements/software-codes.png | Bin 0 -> 34224 bytes docs/img/requirements/software-example.png | Bin 0 -> 25814 bytes docs/img/requirements/vault-disp.png | Bin 0 -> 27965 bytes docs/img/requirements/vault-keypad.png | Bin 0 -> 75409 bytes docs/readme.md | 6 +- docs/requirements.adoc | 637 +++++++++++++++----------- 11 files changed, 370 insertions(+), 273 deletions(-) create mode 100644 docs/img/requirements/hardware-example.png create mode 100644 docs/img/requirements/neotrellis-hardware.png create mode 100644 docs/img/requirements/neotrellis-start.png create mode 100644 docs/img/requirements/neotrellis-toggle.png create mode 100644 docs/img/requirements/software-cable.png create mode 100644 docs/img/requirements/software-codes.png create mode 100644 docs/img/requirements/software-example.png create mode 100644 docs/img/requirements/vault-disp.png create mode 100644 docs/img/requirements/vault-keypad.png (limited to 'docs/img') diff --git a/docs/img/requirements/hardware-example.png b/docs/img/requirements/hardware-example.png new file mode 100644 index 0000000..e6ba035 Binary files /dev/null and b/docs/img/requirements/hardware-example.png differ diff --git a/docs/img/requirements/neotrellis-hardware.png b/docs/img/requirements/neotrellis-hardware.png new file mode 100644 index 0000000..692cd91 Binary files /dev/null and b/docs/img/requirements/neotrellis-hardware.png differ diff --git a/docs/img/requirements/neotrellis-start.png b/docs/img/requirements/neotrellis-start.png new file mode 100644 index 0000000..64fc328 Binary files /dev/null and b/docs/img/requirements/neotrellis-start.png differ diff --git a/docs/img/requirements/neotrellis-toggle.png b/docs/img/requirements/neotrellis-toggle.png new file mode 100644 index 0000000..b83b8cf Binary files /dev/null and b/docs/img/requirements/neotrellis-toggle.png differ diff --git a/docs/img/requirements/software-cable.png b/docs/img/requirements/software-cable.png new file mode 100644 index 0000000..36efbda Binary files /dev/null and b/docs/img/requirements/software-cable.png differ diff --git a/docs/img/requirements/software-codes.png b/docs/img/requirements/software-codes.png new file mode 100644 index 0000000..3d6f946 Binary files /dev/null and b/docs/img/requirements/software-codes.png differ diff --git a/docs/img/requirements/software-example.png b/docs/img/requirements/software-example.png new file mode 100644 index 0000000..7e4e6a9 Binary files /dev/null and b/docs/img/requirements/software-example.png differ diff --git a/docs/img/requirements/vault-disp.png b/docs/img/requirements/vault-disp.png new file mode 100644 index 0000000..95ac43a Binary files /dev/null and b/docs/img/requirements/vault-disp.png differ diff --git a/docs/img/requirements/vault-keypad.png b/docs/img/requirements/vault-keypad.png new file mode 100644 index 0000000..43ed5fd Binary files /dev/null and b/docs/img/requirements/vault-keypad.png differ diff --git a/docs/readme.md b/docs/readme.md index efcf30d..bf7eafe 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -8,15 +8,15 @@ makefile is provided for convenience. ## TODO - transfer documents - - [ ] project plan - - [ ] requirements + - [x] project plan + - [x] requirements - [ ] research - [ ] software design - xrefs for-- - [x] tables - [x] figures - [x] section numbers (headings) - - [ ] requirements + - [x] requirements - [x] figures - [x] citations - [ ] glossary diff --git a/docs/requirements.adoc b/docs/requirements.adoc index 2170484..d678ad7 100644 --- a/docs/requirements.adoc +++ b/docs/requirements.adoc @@ -110,366 +110,399 @@ describes all functional requirements of the puzzle box. .Puzzle box specifications [cols="1,1,10"] |=== -| ID | Pri. | Specification +| ID | <> | Specification -| 001 | <> | -The dimensions of the puzzle box are 30×30×30cm ± 5% (Length × Width × Height). +| <> | <> | +[[req:001,R-001]] The dimensions of the puzzle box are 30×30×30cm ± 5% (Length × Width × Height). -| 002 | <> | -The puzzle box extends a maximum of 5cm on the sides and the top. +| <> | <> | +[[req:002,R-002]] The puzzle box extends a maximum of 5cm on the sides and the top. -| 003 | <> | -The puzzle box is flat at the bottom. +| <> | <> | +[[req:003,R-003]] The puzzle box is flat at the bottom. -| <> | <> | -[[req:4,R-04]] The puzzle box has a key switch at the bottom of the NeoTrellis puzzle. +| <> | <> | +[[req:004,R-004]] The puzzle box has a key switch at the bottom of the NeoTrellis puzzle. -| <> | <> | -[[req:5,R-05]] The puzzle box has an indicator LED at the bottom of the NeoTrellis puzzle. +| <> | <> | +[[req:005,R-005]] The puzzle box has an indicator LED at the bottom of the NeoTrellis puzzle. -| 006 | <> | -The indicator LED turns green when the system is on and not charging. +| <> | <> | +[[req:006,R-006]] The indicator LED turns green when the system is on and not charging. -| 007 | <> | -The indicator LED turns blue when the battery is charging. +| <> | <> | +[[req:007,R-007]] The indicator LED turns blue when the battery is charging. -| 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:008,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. -| 009 | <> | -The puzzle box has a USB-C port at the bottom of the NeoTrellis puzzle for battery charging. +| <> | <> | +[[req:009,R-009]] The puzzle box has a USB-C port at the bottom of the NeoTrellis puzzle for battery charging. -| 010 | <> | -The puzzle box has a distance sensor at the bottom to detect if it is lifted. +| <> | <> | +[[req:010,R-010]] The puzzle box has a distance sensor at the bottom to detect if it is lifted. -| 011 | <> | -The puzzle box main board (PCB on the bottom plate) includes a speaker. +| <> | <> | +[[req:011,R-011]] The puzzle box main board (PCB on the bottom plate) includes a speaker. -| 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:012,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). -| 013 | <> | -When the game is completed, the puzzle box produces a victory sound. +| <> | <> | +[[req:013,R-013]] When the game is completed, the puzzle box produces a victory sound. -| 014 | <> | -Pressing the "identify" button on the web panel causes the indicator LED to blink. +| <> | <> | +[[req:014,R-014]] Pressing the "identify" button on the web panel causes the indicator LED to blink. -| 015 | <> | -Pressing the "identify" button on the web panel triggers a sound from the speaker. +| <> | <> | +[[req:015,R-015]] Pressing the "identify" button on the web panel triggers a sound from the speaker. -| 016 | <> | -The game starts once the scheduler time is reached (refer to section 3.7 - [2]). +| <> | <> | +// section 3.7 is inside the citation, and does not refer to section 3.7 in this document +[[req:016,R-016]] The game starts once the scheduler time is reached (refer to cite:[Bek23] section 3.7). |=== === The bomb -.Puzzle box specifications +.Bomb specifications [cols="1,1,10"] |=== -| ID | Pri. | Specification +| ID | <> | Specification -| 017 | <> | -The bomb includes a 6-digit 7-segment display for showing the remaining playtime. +| <> | <> | +[[req:017,R-017]] The bomb includes a 6-digit 7-segment display for showing the remaining playtime. -| 018 | <> | -The bomb contains a keypad for entering the disarm code. +| <> | <> | +[[req:018,R-018]] The bomb contains a keypad for entering the disarm code. -| 019 | <> | -The 6-digit 7-segment display turns off when no game is in progress. +| <> | <> | +[[req:019,R-019]] The 6-digit 7-segment display turns off when no game is in progress. -| 020 | <> | -Once the disarm code is entered on the bomb keypad, the game is complete. +| <> | <> | +[[req:020,R-020]] Once the disarm code is entered on the bomb keypad, the game is complete. -| 021 | <> | -When the game is finished, the bomb emits a victory sound. +| <> | <> | +[[req:021,R-021]] When the game is finished, the bomb emits a victory sound. -| 022 | <> | -The timer on the bomb counts down from 60:00:00 to 00:00:00. +| <> | <> | +[[req:022,R-022]] The timer on the bomb counts down from 60:00:00 to 00:00:00. -| 023 | <> | -Pressing the "identify" button on the web panel causes the indicator LED to blink. +| <> | <> | +[[req:023,R-023]] Pressing the "identify" button on the web panel causes the indicator LED to blink. -| 024 | <> | -Pressing the "identify" button on the web panel triggers a sound from the speaker. +| <> | <> | +[[req:024,R-024]] Pressing the "identify" button on the web panel triggers a sound from the speaker. |=== === The game +.General game specifications [cols="1,1,10"] |=== -| 025 | <> | -The game lasts for 1 hour. +| ID | <> | Specification + +| <> | <> | +[[req:025,R-025]] The game lasts for 1 hour. -| 026 | <> | -The game should be solvable within the given playtime, without the player having prior knowledge of the game or its mechanics. +| <> | <> | +[[req:026,R-026]] The game should be solvable within the given playtime, without the player having prior knowledge of the game or its mechanics. -| 027 | <> | -The puzzles should be easy enough to solve without any prior knowledge of the game or its mechanics. +| <> | <> | +[[req:027,R-027]] The puzzles should be easy enough to solve without any prior knowledge of the game or its mechanics. -| 167 | <> | -A puzzle module can manually be reset at the discretion of the game operator +| <> | <> | +[[req:167,R-167]] A puzzle module can manually be reset at the discretion of the game operator -| 168 | <> | -A puzzle module can manually be set as solved 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 -| 028 | <> | -The disarm code for the bomb consists of 4 digits. +| <> | <> | +[[req:028,R-028]] The disarm code for the bomb consists of 4 digits. -| 029 | <> | -Once all games are solved, the mainboard PCB displays the disarm code on a red 7-segment 4-digit screen. +| <> | <> | +[[req:029,R-029]] Once all games are solved, the mainboard PCB displays the disarm code on a red 7-segment 4-digit screen. -| 030 | <> | -The puzzle box records the playtime of each game. +| <> | <> | +[[req:030,R-030]] The puzzle box records the playtime of each game. -| 031 | <> | -The puzzle box features 5 playable puzzles. +| <> | <> | +[[req:031,R-031]] The puzzle box features 5 playable puzzles. -| 032 | <> | -Only one game is active at a time; the other games do not respond to buttons. +| <> | <> | +[[req:032,R-032]] Only one game is active at a time; the other games do not respond to buttons. -| 033 | <> | -The game always starts with the NeoTrellis puzzle. +| <> | <> | +[[req:033,R-033]] The game always starts with the NeoTrellis puzzle. |=== ==== NeoTrellis puzzle +.NeoTrellis puzzle requirements [cols="1,1,10"] |=== -| 034 | <> | -There is an 8x8 LED matrix where each LED can display different colors. +| ID | <> | Specification -| 035 | <> | -At the start of the puzzle, a pattern is displayed as shown in Figure 4. +| <> | <> | +[[req:034,R-034]] There is an 8x8 LED matrix where each LED can display different colors. -| 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:035,R-035]] At the start of the puzzle, a pattern is displayed as shown in <>. -| 037 | <> | -All LEDs in the Neotrellis that are turned on are blue. +| <> | <> | +[[req:036,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). -| 038 | <> | -The puzzle is considered solved when all LEDs are turned off, and then the software puzzle starts. +| <> | <> | +[[req:037,R-037]] All LEDs in the Neotrellis that are turned on are blue. + +| <> | <> | +[[req:038,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="1,1,10"] |=== -| 039 | <> | -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). +| ID | <> | Specification + +| <> | <> | +[[req:039,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). -| 040 | <> | -The software puzzle board has 6 banana plug connectors labeled with the letters A through F (Refer to Figure 5 for a sketch). +| <> | <> | +[[req:040,R-040]] The software puzzle board has 6 banana plug connectors labeled with the letters A through F (Refer to <> for a sketch). -| 041 | <> | -At the start of the puzzle box game, the preparer must connect all cables in parallel (horizontally) to the connectors. +| <> | <> | +[[req:041,R-041]] At the start of the puzzle box game, the preparer must connect all cables in parallel (horizontally) to the connectors. -| 042 | <> | -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). +| <> | <> | +[[req:042,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). -| 043 | <> | -The combinations of logic gates to letters are always the same. +| <> | <> | +[[req:043,R-043]] The combinations of logic gates to letters are always the same. -| 044 | <> | -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). +| <> | <> | +[[req:044,R-044]] The puzzle is considered solved when the cables from the logic gates match the code blocks (Refer to <> and <> for the combinations). -| 045 | <> | -Once the puzzle is solved, the green indicator LED will light up (Refer to Figure 5 and Figure 6). +| <> | <> | +[[req:045,R-045]] Once the puzzle is solved, the green indicator LED will light up (Refer to <> and <>). -| 046 | <> | -After the puzzle is solved, the automation puzzle begins. +| <> | <> | +[[req:046,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="1,1,10"] |=== -| 047 | <> | -After the puzzle is solved, the hardware puzzle begins. +| ID | <> | Specification + +| <> | <> | +[[req:047,R-047]] After the puzzle is solved, the hardware puzzle begins. |=== ==== Hardware puzzle +.Hardware puzzle requirements [cols="1,1,10"] |=== -| 048 | <> | -There are eight switches on the hardware puzzle board. +| ID | <> | Specification -| 049 | <> | -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). +| <> | <> | +[[req:048,R-048]] There are eight switches on the hardware puzzle board. -| 050 | <> | -The hardware puzzle board includes a red 7-segment 4-digit display (Refer to Figure 8 for a sketch). +| <> | <> | +[[req:049,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). -| 051 | <> | -There are 4 potentiometers on the hardware puzzle board (Refer to Figure 8 for a sketch). +| <> | <> | +[[req:050,R-050]] The hardware puzzle board includes a red 7-segment 4-digit display (Refer to <> for a sketch). -| 052 | <> | -A blue LED on the hardware puzzle board displays the morse code. +| <> | <> | +[[req:051,R-051]] There are 4 potentiometers on the hardware puzzle board (Refer to <> for a sketch). -| 053 | <> | -A green LED on the hardware puzzle board indicates whether the combinatorial circuit is solved. +| <> | <> | +[[req:052,R-052]] A blue LED on the hardware puzzle board displays the morse code. -| 054 | <> | -At the start of the puzzle, the potentiometers are inactive. +| <> | <> | +[[req:053,R-053]] A green LED on the hardware puzzle board indicates whether the combinatorial circuit is solved. -| 055 | <> | -The 7-segment display is off at the beginning of the puzzle. +| <> | <> | +[[req:054,R-054]] At the start of the puzzle, the potentiometers are inactive. -| 056 | <> | -The LED for the combinatorial puzzle is off initially. +| <> | <> | +[[req:055,R-055]] The 7-segment display is off at the beginning of the puzzle. -| 057 | <> | -The morse code LED is off at the puzzle's outset. +| <> | <> | +[[req:056,R-056]] The LED for the combinatorial puzzle is off initially. -| 058 | <> | -The preparer must set all switches to the down position at the start of the puzzle box game. +| <> | <> | +[[req:057,R-057]] The morse code LED is off at the puzzle's outset. -| 059 | <> | -The preparer must turn all potentiometers to the left (value '0') at the beginning of the puzzle box game. +| <> | <> | +[[req:058,R-058]] The preparer must set all switches to the down position at the start of the puzzle box game. -| 060 | <> | -The puzzle consists of two phases. +| <> | <> | +[[req:059,R-059]] The preparer must turn all potentiometers to the left (value '0') at the beginning of the puzzle box game. -| 061 | <> | -The puzzle begins in phase 1. +| <> | <> | +[[req:060,R-060]] The puzzle consists of two phases. -| 062 | <> | -During the puzzle, the switches must be toggled to obtain a logical '1' at the output of the combinatorial circuit. +| <> | <> | +[[req:061,R-061]] The puzzle begins in phase 1. -| 063 | <> | -When the output of the combinatorial circuit equals '1', the green indicator LED turns on (Refer to Figure 8 for a sketch). +| <> | <> | +[[req:062,R-062]] During the puzzle, the switches must be toggled to obtain a logical '1' at the output of the combinatorial circuit. -| 064 | <> | -The puzzle proceeds to phase 2 when the output of the combinatorial circuit is a logical '1'. +| <> | <> | +[[req:063,R-063]] When the output of the combinatorial circuit equals '1', the green indicator LED turns on (Refer to <> for a sketch). -| 065 | <> | -The switches no longer respond once the puzzle enters phase 2. +| <> | <> | +[[req:064,R-064]] The puzzle proceeds to phase 2 when the output of the combinatorial circuit is a logical '1'. -| 066 | <> | -The indicator LED from phase 1 remains green during phase 2. +| <> | <> | +[[req:065,R-065]] The switches no longer respond once the puzzle enters phase 2. -| 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:066,R-066]] The indicator LED from phase 1 remains green during phase 2. -| 068 | <> | -The morse code is randomly generated. +| <> | <> | +[[req:067,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. -| 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 Figure 8 for a sketch). +| <> | <> | +[[req:068,R-068]] The morse code is randomly generated. -| 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:069,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). -| 071 | <> | -Once the puzzle is solved, the value shown on the 7-segment 4-digit display cannot be changed. +| <> | <> | +[[req:070,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. -| 072 | <> | -A 2-second victory sound is produced by the speaker upon solving the puzzle. +| <> | <> | +[[req:071,R-071]] Once the puzzle is solved, the value shown on the 7-segment 4-digit display cannot be changed. -| 073 | <> | -During the victory sound, the 7-segment display blinks twice per second. +| <> | <> | +[[req:072,R-072]] A 2-second victory sound is produced by the speaker upon solving the puzzle. -| 074 | <> | -After the victory sound, the puzzle has been solved and the vault puzzle begins. +| <> | <> | +[[req:073,R-073]] During the victory sound, the 7-segment display blinks twice per second. + +| <> | <> | +[[req:074,R-074]] After the victory sound, the puzzle has been solved and the vault puzzle begins. |=== ==== Vault puzzle +.Vault puzzle requirements [cols="1,1,10"] |=== -| 075 | <> | -The vault puzzle board features a red 7-segment 4-digit display. +| ID | <> | Specification + +| <> | <> | +[[req:075,R-075]] The vault puzzle board features a red 7-segment 4-digit display. -| 076 | <> | -On the vault puzzle board, there is a 4x4 grid of holes for ventilation and sound. +| <> | <> | +[[req:076,R-076]] On the vault puzzle board, there is a 4x4 grid of holes for ventilation and sound. -| 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:077,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. -| 078 | <> | -A sensor is integrated with the vault to detect when the vault is closed. +| <> | <> | +[[req:078,R-078]] A sensor is integrated with the vault to detect when the vault is closed. -| 079 | <> | -At the beginning of the puzzle box game, the preparer must close the vault. +| <> | <> | +[[req:079,R-079]] At the beginning of the puzzle box game, the preparer must close the vault. -| 080 | <> | -The puzzle starts at level 1. +| <> | <> | +[[req:080,R-080]] The puzzle starts at level 1. -| 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 Figure 9 for all combinations). +| <> | <> | +[[req:081,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). -| 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 Figure 9). +| <> | <> | +[[req:082,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 <>). -| 083 | <> | -Each level has unique key combinations for the button locations (Refer to Figure 9). +| <> | <> | +[[req:083,R-083]] Each level has unique key combinations for the button locations (Refer to <>). -| 084 | <> | -Pressing the button corresponding to the letter-digit combinations advances the puzzle to the next level. +| <> | <> | +[[req:084,R-084]] Pressing the button corresponding to the letter-digit combinations advances the puzzle to the next level. -| 085 | <> | -If an incorrect button is pressed, the game resets to level 1. +| <> | <> | +[[req:085,R-085]] If an incorrect button is pressed, the game resets to level 1. -| 086 | <> | -An error sound is produced by the speaker when an incorrect button is pressed. +| <> | <> | +[[req:086,R-086]] An error sound is produced by the speaker when an incorrect button is pressed. -| 087 | <> | -The 7-segment display blinks when an incorrect button is pressed. +| <> | <> | +[[req:087,R-087]] The 7-segment display blinks when an incorrect button is pressed. -| 088 | <> | -After completing 5 levels, the puzzle is solved, and the vault opens. +| <> | <> | +[[req:088,R-088]] After completing 5 levels, the puzzle is solved, and the vault opens. |=== === Battery +.Battery requirements [cols="1,1,10"] |=== -| 089 | <> | -The puzzle box is powered by a rechargeable battery. +| ID | <> | Specification -| 090 | <> | -The battery lasts for a minimum of 4 hours. +| <> | <> | +[[req:089,R-089]] The puzzle box is powered by a rechargeable battery. -| 091 | <> | -The battery in the puzzle box can be replaced. +| <> | <> | +[[req:090,R-090]] The battery lasts for a minimum of 4 hours. + +| <> | <> | +[[req:091,R-091]] The battery in the puzzle box can be replaced. |=== === Network Communication +.Communication requirements [cols="1,1,10"] |=== -| 092 | <> | -The puzzle boxes, bombs, and the puzzle box hub must all be able to communicate with each other. +| ID | <> | Specification + +| <> | <> | +[[req:092,R-092]] The puzzle boxes, bombs, and the puzzle box hub must all be able to communicate with each other. -| 093 | <> | -Communication between two devices in the network must have a range of at least 20 meters in an open field. +| <> | <> | +[[req:093,R-093]] 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 | <> | -The main controller and its software do not need to be modified to implement a new puzzle module +| ID | <> | Specification -| 131 | <> | -Puzzle modules can be added and removed while the main controller is powered on +| <> | <> | +[[req:130,R-130]] The main controller and its software do not need to be modified to implement a new puzzle module -| 132 | <> | -Puzzle modules can be added and removed while the main controller is powered off +| <> | <> | +[[req:131,R-131]] Puzzle modules can be added and removed while the main controller is powered on -| 133 | <> | -The puzzle box provides a single external interface for accessing and controlling game state variables +| <> | <> | +[[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="1,1,10"] |=== -| 094 | <> | -The puzzle box hub hosts a website that can be accessed by a device connected to the network. +| ID | <> | Specification + +| <> | <> | +[[req:094,R-094]] The puzzle box hub hosts a website that can be accessed by a device connected to the network. |=== [[sec:technical]] @@ -482,145 +515,209 @@ technical specifications of the puzzle box. === Wireless communication +.Wireless communication requirements [cols="1,1,10"] |=== -| 127 | <> | -The wireless communication between the system controller, bomb, and puzzle box operates over a WiFi mesh or WiFi network. +| 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="1,1,10"] |=== -| 128 | <> | -A framework has been created to assist future groups in the development of the puzzle box. +| ID | <> | Specification + +| <> | <> | +[[req:128,R-128]] A framework has been created to assist future groups in the development of the puzzle box. -| 129 | <> | -The framework runs on the main puzzle box controller. +| <> | <> | +[[req:129,R-129]] The framework runs on the main puzzle box controller. -| 134 | <> | -Puzzle modules are detected by the main controller module. +| <> | <> | +[[req:134,R-134]] Puzzle modules are detected by the main controller module. -| 135 | <> | -Puzzle modules are initialized by the main controller module. +| <> | <> | +[[req:135,R-135]] Puzzle modules are initialized by the main controller module. -| 165 | <> | -Puzzle modules repeatedly send 'update' messages to the main controller while their global state is 'uninitialized' +| <> | <> | +[[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="1,1,10"] |=== -| 136 | <> | -The main controller has at least 1 I2C peripheral. +| ID | <> | Specification -| 137 | <> | -The main controller can connect to a standard 802.11b/g/n access point. +| <> | <> | +[[req:136,R-136]] The main controller has at least 1 I2C peripheral. -| 138 | <> | -The main controller can serve TCP socket connection(s). +| <> | <> | +[[req:137,R-137]] The main controller can connect to a standard 802.11b/g/n access point. -| 139 | <> | -The main controller is available as a development kit from Farnell. +| <> | <> | +[[req:138,R-138]] The main controller can serve TCP socket connection(s). -| 140 | <> | -The main controller can communicate over I²C with a speed of 400kb/s +| <> | <> | +[[req:139,R-139]] The main controller is available as a development kit from Farnell. -| 166 | <> | -The main controller is power efficient. +| <> | <> | +[[req:140,R-140]] The main controller can communicate over I²C with a speed of 400kb/s + +| <> | <> | +[[req:166,R-166]] The main controller is power efficient. |=== === Puzzle module controller [cols="1,1,10"] |=== -| 141 | <> | -The puzzle module controller has at least 1 I2C peripheral. +| ID | <> | Specification + +| <> | <> | +[[req:141,R-141]] The puzzle module controller has at least 1 I2C peripheral. -| 142 | <> | -The puzzle module controller has enough I/O ports to control a puzzle. +| <> | <> | +[[req:142,R-142]] The puzzle module controller has enough I/O ports to control a puzzle. -| 143 | <> | -The puzzle module is power efficient. +| <> | <> | +[[req:143,R-143]] The puzzle module is power efficient. -| 144 | <> | -The puzzle module has a configurable clock speed. +| <> | <> | +[[req:144,R-144]] The puzzle module has a configurable clock speed. -| 145 | <> | -The puzzle module controller is available as a development kit from Farnell. +| <> | <> | +[[req:145,R-145]] The puzzle module controller is available as a development kit from Farnell. -| 146 | <> | -The puzzle module can communicate over I²C with a speed of 400kb/s +| <> | <> | +[[req:146,R-146]] The puzzle module can communicate over I²C with a speed of 400kb/s |=== === Vault puzzle +.Vault puzzle requirements [cols="1,1,10"] |=== -| 147 | <> | -The vault puzzle can communicate with the main controller using I²C +| ID | <> | Specification -| 148 | <> | -The vault puzzle can produce a sound signal for the buzzer +| <> | <> | +[[req:147,R-147]] The vault puzzle can communicate with the main controller using I²C -| 149 | <> | -The vault puzzle can lock & unlock a solenoid lock +| <> | <> | +[[req:148,R-148]] The vault puzzle can produce a sound signal for the buzzer -| 150 | <> | -The vault puzzle can translate and obtain a button press from the 3x4 keypad using 5 inputs +| <> | <> | +[[req:149,R-149]] The vault puzzle can lock & unlock a solenoid lock -| 151 | <> | -The vault puzzle can communicate with a 4x 7 SEG. Display using 2 lines (clock & data) +| <> | <> | +[[req:150,R-150]] The vault puzzle can translate and obtain a button press from the 3x4 keypad using 5 inputs -| 152 | <> | -The vault puzzle can read a sensor's value to detect if the vault door is open or closed. +| <> | <> | +[[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="1,1,10"] |=== -| 153 | <> | -The bomb can communicate with the hub using a TCP socket connection +| ID | <> | Specification + +| <> | <> | +[[req:153,R-153]] The bomb can communicate with the hub using a TCP socket connection -| 154 | <> | -The bomb can sync. time using the WiFi connection +| <> | <> | +[[req:154,R-154]] The bomb can sync. time using the WiFi connection -| 155 | <> | -The bomb can retrieve, and store a given code in order to verify it later on input +| <> | <> | +[[req:155,R-155]] The bomb can retrieve, and store a given code in order to verify it later on input -| 156 | <> | -The bomb can be paired to a puzzlebox using the hub's interface +| <> | <> | +[[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="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. +| 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="1,1,10"] |=== -| 157 | <> | -All documentation is written according to the style guide [3] +| ID | <> | Specification + +| <> | <> | +[[req:157,R-157]] All documentation is written according to the style guide cite:[styleguide] -| 158 | <> | -All documentation is manually checked for spelling and grammar mistakes before being published +| <> | <> | +[[req:158,R-158]] All documentation is manually checked for spelling and grammar mistakes before being published -| 159 | <> | -All project documents are examined once by Jonathan Overes from Avans +| <> | <> | +[[req:159,R-159]] All project documents are examined once by Jonathan Overes from Avans |=== [appendix] == Explanatory Images +[[fig:vault-disp]] +.7 Segment 4 digit screen (sketch) +image::img/requirements/vault-disp.png[] + +[[fig:neotrellis-hardware]] +.NeoTrellis example (sketch) +image::img/requirements/neotrellis-hardware.png[] + +[[fig:neotrellis-toggle]] +.Toggling LEDs after the user pressed on the button (purple dot) +image::img/requirements/neotrellis-toggle.png[width=45%] + +[[fig:neotrellis-start]] +.Starting pattern of the NeoTrellis puzzle +image::img/requirements/neotrellis-start.png[width=45%] + +[[fig:software-example]] +.Software puzzle example with logical ports (left) and letters A through F (right) +image::img/requirements/software-example.png[] + +[[fig:software-codes]] +.The different code fragments corresponding with the letter A through F +image::img/requirements/software-codes.png[height=35%] + +[[fig:software-cable]] +.Software puzzle cable example +image::img/requirements/software-cable.png[] + +[[fig:hardware-example]] +.Hardware puzzle on the puzzle box +image::img/requirements/hardware-example.png[] + +[[fig:vault-keypad]] +.Buttons combinations with level numbers in the top left +image::img/requirements/vault-keypad.png[width=45%] + include::share/footer.adoc[] -- cgit v1.2.3 From 4394f1a0122c81439e648d17c1c0f5855229f74b Mon Sep 17 00:00:00 2001 From: lonkaars Date: Sat, 20 Apr 2024 15:31:58 +0200 Subject: mostly transfer research document --- docs/img/automation-example.png | Bin 0 -> 33537 bytes docs/img/bus-connector.jpg | Bin 0 -> 2928708 bytes docs/img/external-architecture-old.png | Bin 0 -> 36482 bytes docs/img/hardware-example-sketch.png | Bin 0 -> 94788 bytes docs/img/hardware-pcb.jpg | Bin 0 -> 3295631 bytes docs/img/hardware-side.jpg | Bin 0 -> 2924999 bytes docs/img/light-sensor.jpg | Bin 0 -> 2106029 bytes docs/img/main-pcb.jpg | Bin 0 -> 3196425 bytes docs/img/neotrellis-example.png | Bin 0 -> 6859 bytes docs/img/neotrellis-hardware-sketch.png | Bin 0 -> 71544 bytes docs/img/neotrellis-pcb.jpg | Bin 0 -> 3620814 bytes docs/img/neotrellis-side.jpg | Bin 0 -> 2064462 bytes docs/img/neotrellis-start.png | Bin 0 -> 3078 bytes docs/img/neotrellis-toggle.png | Bin 0 -> 22898 bytes docs/img/requirements/hardware-example.png | Bin 94788 -> 0 bytes docs/img/requirements/neotrellis-hardware.png | Bin 71544 -> 0 bytes docs/img/requirements/neotrellis-start.png | Bin 3078 -> 0 bytes docs/img/requirements/neotrellis-toggle.png | Bin 22898 -> 0 bytes docs/img/requirements/software-cable.png | Bin 33947 -> 0 bytes docs/img/requirements/software-codes.png | Bin 34224 -> 0 bytes docs/img/requirements/software-example.png | Bin 25814 -> 0 bytes docs/img/requirements/vault-disp.png | Bin 27965 -> 0 bytes docs/img/requirements/vault-keypad.png | Bin 75409 -> 0 bytes docs/img/software-cable-sketch.png | Bin 0 -> 33947 bytes docs/img/software-codes-sketch.png | Bin 0 -> 34224 bytes docs/img/software-codes.png | Bin 0 -> 54693 bytes docs/img/software-example-sketch.png | Bin 0 -> 25814 bytes docs/img/software-example.png | Bin 0 -> 50387 bytes docs/img/software-pcb.jpg | Bin 0 -> 2867464 bytes docs/img/software-side.jpg | Bin 0 -> 3051226 bytes docs/img/unknown-pcb.jpg | Bin 0 -> 3029716 bytes docs/img/vault-disp-sketch.png | Bin 0 -> 27965 bytes docs/img/vault-interface.png | Bin 0 -> 42493 bytes docs/img/vault-keypad-full.png | Bin 0 -> 288664 bytes docs/img/vault-keypad.png | Bin 0 -> 75409 bytes docs/img/vault-pcb.jpg | Bin 0 -> 2907552 bytes docs/img/vault-side.jpg | Bin 0 -> 2855727 bytes docs/makefile | 1 + docs/plan.adoc | 2 +- docs/readme.md | 9 +- docs/requirements.adoc | 96 ++-- docs/research.adoc | 741 ++++++++++++++++++++++++++ docs/share/glossary.adoc | 2 +- docs/share/meta.adoc | 3 + docs/share/references.adoc | 2 +- docs/share/refs.bib | 3 + docs/theme.yml | 3 + 47 files changed, 809 insertions(+), 53 deletions(-) create mode 100644 docs/img/automation-example.png create mode 100644 docs/img/bus-connector.jpg create mode 100644 docs/img/external-architecture-old.png create mode 100644 docs/img/hardware-example-sketch.png create mode 100644 docs/img/hardware-pcb.jpg create mode 100644 docs/img/hardware-side.jpg create mode 100644 docs/img/light-sensor.jpg create mode 100644 docs/img/main-pcb.jpg create mode 100644 docs/img/neotrellis-example.png create mode 100644 docs/img/neotrellis-hardware-sketch.png create mode 100644 docs/img/neotrellis-pcb.jpg create mode 100644 docs/img/neotrellis-side.jpg create mode 100644 docs/img/neotrellis-start.png create mode 100644 docs/img/neotrellis-toggle.png delete mode 100644 docs/img/requirements/hardware-example.png delete mode 100644 docs/img/requirements/neotrellis-hardware.png delete mode 100644 docs/img/requirements/neotrellis-start.png delete mode 100644 docs/img/requirements/neotrellis-toggle.png delete mode 100644 docs/img/requirements/software-cable.png delete mode 100644 docs/img/requirements/software-codes.png delete mode 100644 docs/img/requirements/software-example.png delete mode 100644 docs/img/requirements/vault-disp.png delete mode 100644 docs/img/requirements/vault-keypad.png create mode 100644 docs/img/software-cable-sketch.png create mode 100644 docs/img/software-codes-sketch.png create mode 100644 docs/img/software-codes.png create mode 100644 docs/img/software-example-sketch.png create mode 100644 docs/img/software-example.png create mode 100644 docs/img/software-pcb.jpg create mode 100644 docs/img/software-side.jpg create mode 100644 docs/img/unknown-pcb.jpg create mode 100644 docs/img/vault-disp-sketch.png create mode 100644 docs/img/vault-interface.png create mode 100644 docs/img/vault-keypad-full.png create mode 100644 docs/img/vault-keypad.png create mode 100644 docs/img/vault-pcb.jpg create mode 100644 docs/img/vault-side.jpg create mode 100644 docs/research.adoc (limited to 'docs/img') diff --git a/docs/img/automation-example.png b/docs/img/automation-example.png new file mode 100644 index 0000000..33c7259 Binary files /dev/null and b/docs/img/automation-example.png differ diff --git a/docs/img/bus-connector.jpg b/docs/img/bus-connector.jpg new file mode 100644 index 0000000..90ffbc2 Binary files /dev/null and b/docs/img/bus-connector.jpg differ diff --git a/docs/img/external-architecture-old.png b/docs/img/external-architecture-old.png new file mode 100644 index 0000000..ee5c1cd Binary files /dev/null and b/docs/img/external-architecture-old.png differ diff --git a/docs/img/hardware-example-sketch.png b/docs/img/hardware-example-sketch.png new file mode 100644 index 0000000..e6ba035 Binary files /dev/null and b/docs/img/hardware-example-sketch.png differ diff --git a/docs/img/hardware-pcb.jpg b/docs/img/hardware-pcb.jpg new file mode 100644 index 0000000..e317c4e Binary files /dev/null and b/docs/img/hardware-pcb.jpg differ diff --git a/docs/img/hardware-side.jpg b/docs/img/hardware-side.jpg new file mode 100644 index 0000000..800b3ad Binary files /dev/null and b/docs/img/hardware-side.jpg differ diff --git a/docs/img/light-sensor.jpg b/docs/img/light-sensor.jpg new file mode 100644 index 0000000..cf00dfb Binary files /dev/null and b/docs/img/light-sensor.jpg differ diff --git a/docs/img/main-pcb.jpg b/docs/img/main-pcb.jpg new file mode 100644 index 0000000..c6d1c2c Binary files /dev/null and b/docs/img/main-pcb.jpg differ diff --git a/docs/img/neotrellis-example.png b/docs/img/neotrellis-example.png new file mode 100644 index 0000000..2f836cd Binary files /dev/null and b/docs/img/neotrellis-example.png differ diff --git a/docs/img/neotrellis-hardware-sketch.png b/docs/img/neotrellis-hardware-sketch.png new file mode 100644 index 0000000..692cd91 Binary files /dev/null and b/docs/img/neotrellis-hardware-sketch.png differ diff --git a/docs/img/neotrellis-pcb.jpg b/docs/img/neotrellis-pcb.jpg new file mode 100644 index 0000000..1b193b4 Binary files /dev/null and b/docs/img/neotrellis-pcb.jpg differ diff --git a/docs/img/neotrellis-side.jpg b/docs/img/neotrellis-side.jpg new file mode 100644 index 0000000..96ac5a7 Binary files /dev/null and b/docs/img/neotrellis-side.jpg differ diff --git a/docs/img/neotrellis-start.png b/docs/img/neotrellis-start.png new file mode 100644 index 0000000..64fc328 Binary files /dev/null and b/docs/img/neotrellis-start.png differ diff --git a/docs/img/neotrellis-toggle.png b/docs/img/neotrellis-toggle.png new file mode 100644 index 0000000..b83b8cf Binary files /dev/null and b/docs/img/neotrellis-toggle.png differ diff --git a/docs/img/requirements/hardware-example.png b/docs/img/requirements/hardware-example.png deleted file mode 100644 index e6ba035..0000000 Binary files a/docs/img/requirements/hardware-example.png and /dev/null differ diff --git a/docs/img/requirements/neotrellis-hardware.png b/docs/img/requirements/neotrellis-hardware.png deleted file mode 100644 index 692cd91..0000000 Binary files a/docs/img/requirements/neotrellis-hardware.png and /dev/null differ diff --git a/docs/img/requirements/neotrellis-start.png b/docs/img/requirements/neotrellis-start.png deleted file mode 100644 index 64fc328..0000000 Binary files a/docs/img/requirements/neotrellis-start.png and /dev/null differ diff --git a/docs/img/requirements/neotrellis-toggle.png b/docs/img/requirements/neotrellis-toggle.png deleted file mode 100644 index b83b8cf..0000000 Binary files a/docs/img/requirements/neotrellis-toggle.png and /dev/null differ diff --git a/docs/img/requirements/software-cable.png b/docs/img/requirements/software-cable.png deleted file mode 100644 index 36efbda..0000000 Binary files a/docs/img/requirements/software-cable.png and /dev/null differ diff --git a/docs/img/requirements/software-codes.png b/docs/img/requirements/software-codes.png deleted file mode 100644 index 3d6f946..0000000 Binary files a/docs/img/requirements/software-codes.png and /dev/null differ diff --git a/docs/img/requirements/software-example.png b/docs/img/requirements/software-example.png deleted file mode 100644 index 7e4e6a9..0000000 Binary files a/docs/img/requirements/software-example.png and /dev/null differ diff --git a/docs/img/requirements/vault-disp.png b/docs/img/requirements/vault-disp.png deleted file mode 100644 index 95ac43a..0000000 Binary files a/docs/img/requirements/vault-disp.png and /dev/null differ diff --git a/docs/img/requirements/vault-keypad.png b/docs/img/requirements/vault-keypad.png deleted file mode 100644 index 43ed5fd..0000000 Binary files a/docs/img/requirements/vault-keypad.png and /dev/null differ diff --git a/docs/img/software-cable-sketch.png b/docs/img/software-cable-sketch.png new file mode 100644 index 0000000..36efbda Binary files /dev/null and b/docs/img/software-cable-sketch.png differ diff --git a/docs/img/software-codes-sketch.png b/docs/img/software-codes-sketch.png new file mode 100644 index 0000000..3d6f946 Binary files /dev/null and b/docs/img/software-codes-sketch.png differ diff --git a/docs/img/software-codes.png b/docs/img/software-codes.png new file mode 100644 index 0000000..af1c972 Binary files /dev/null and b/docs/img/software-codes.png differ diff --git a/docs/img/software-example-sketch.png b/docs/img/software-example-sketch.png new file mode 100644 index 0000000..7e4e6a9 Binary files /dev/null and b/docs/img/software-example-sketch.png differ diff --git a/docs/img/software-example.png b/docs/img/software-example.png new file mode 100644 index 0000000..025e6fe Binary files /dev/null and b/docs/img/software-example.png differ diff --git a/docs/img/software-pcb.jpg b/docs/img/software-pcb.jpg new file mode 100644 index 0000000..70e9aa1 Binary files /dev/null and b/docs/img/software-pcb.jpg differ diff --git a/docs/img/software-side.jpg b/docs/img/software-side.jpg new file mode 100644 index 0000000..c62da4e Binary files /dev/null and b/docs/img/software-side.jpg differ diff --git a/docs/img/unknown-pcb.jpg b/docs/img/unknown-pcb.jpg new file mode 100644 index 0000000..0af620f Binary files /dev/null and b/docs/img/unknown-pcb.jpg differ diff --git a/docs/img/vault-disp-sketch.png b/docs/img/vault-disp-sketch.png new file mode 100644 index 0000000..95ac43a Binary files /dev/null and b/docs/img/vault-disp-sketch.png differ diff --git a/docs/img/vault-interface.png b/docs/img/vault-interface.png new file mode 100644 index 0000000..ac7ad03 Binary files /dev/null and b/docs/img/vault-interface.png differ diff --git a/docs/img/vault-keypad-full.png b/docs/img/vault-keypad-full.png new file mode 100644 index 0000000..41f9836 Binary files /dev/null and b/docs/img/vault-keypad-full.png differ diff --git a/docs/img/vault-keypad.png b/docs/img/vault-keypad.png new file mode 100644 index 0000000..43ed5fd Binary files /dev/null and b/docs/img/vault-keypad.png differ diff --git a/docs/img/vault-pcb.jpg b/docs/img/vault-pcb.jpg new file mode 100644 index 0000000..ebea627 Binary files /dev/null and b/docs/img/vault-pcb.jpg differ diff --git a/docs/img/vault-side.jpg b/docs/img/vault-side.jpg new file mode 100644 index 0000000..1922985 Binary files /dev/null and b/docs/img/vault-side.jpg differ diff --git a/docs/makefile b/docs/makefile index e177f6d..496a6e6 100644 --- a/docs/makefile +++ b/docs/makefile @@ -1,5 +1,6 @@ all: plan.pdf all: requirements.pdf +all: research.pdf # include font.mk diff --git a/docs/plan.adoc b/docs/plan.adoc index 63df9a0..8825459 100644 --- a/docs/plan.adoc +++ b/docs/plan.adoc @@ -1,4 +1,4 @@ -= Project Plan: Project Puzzlebox += Project Plan: {project} include::share/meta.adoc[] == Introduction diff --git a/docs/readme.md b/docs/readme.md index bf7eafe..e58c5fb 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -5,12 +5,17 @@ To compile the documents, make sure you have [Ruby][rubydl] and the dependencies installed by running the `bundle` command in this folder. A makefile is provided for convenience. +## notes for writers + +- "I2C" is written as `I^2^C` +- "C++" is written as `{cpp}` + ## TODO - transfer documents - [x] project plan - [x] requirements - - [ ] research + - [x] research - [ ] software design - xrefs for-- - [x] tables @@ -19,7 +24,7 @@ makefile is provided for convenience. - [x] requirements - [x] figures - [x] citations -- [ ] glossary +- [ ] glossary (w/ cross-references) - [ ] PDF style [rubydl]: https://www.ruby-lang.org/en/documentation/installation/ diff --git a/docs/requirements.adoc b/docs/requirements.adoc index d678ad7..37f914b 100644 --- a/docs/requirements.adoc +++ b/docs/requirements.adoc @@ -1,4 +1,4 @@ -= Project Requirements: Project Puzzlebox += Project Requirements: {project} include::share/meta.adoc[] == Introduction @@ -11,7 +11,7 @@ The priority of specifications is indicated using the MoSCoW method, see [[tab:moscow]] .MoSCoW Method cite:[Wik22] -[cols="1,3"] +[cols="20h,~"] |=== | Priority | Description @@ -108,7 +108,7 @@ describes all functional requirements of the puzzle box. === The puzzle box .Puzzle box specifications -[cols="1,1,10"] +[cols="8h,5h,~"] |=== | ID | <> | Specification @@ -165,7 +165,7 @@ describes all functional requirements of the puzzle box. === The bomb .Bomb specifications -[cols="1,1,10"] +[cols="8h,5h,~"] |=== | ID | <> | Specification @@ -198,7 +198,7 @@ describes all functional requirements of the puzzle box. === The game .General game specifications -[cols="1,1,10"] +[cols="8h,5h,~"] |=== | ID | <> | Specification @@ -239,7 +239,7 @@ describes all functional requirements of the puzzle box. ==== NeoTrellis puzzle .NeoTrellis puzzle requirements -[cols="1,1,10"] +[cols="8h,5h,~"] |=== | ID | <> | Specification @@ -262,30 +262,30 @@ describes all functional requirements of the puzzle box. ==== Software puzzle .Software puzzle requirements -[cols="1,1,10"] +[cols="8h,5h,~"] |=== | ID | <> | Specification | <> | <> | -[[req:039,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:039,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:040,R-040]] The software puzzle board has 6 banana plug connectors labeled with the letters A through F (Refer to <> for a sketch). +[[req:040,R-040]] The software puzzle board has 6 banana plug connectors labeled with the letters A through F (Refer to <> for a sketch). | <> | <> | [[req:041,R-041]] At the start of the puzzle box game, the preparer must connect all cables in parallel (horizontally) to the connectors. | <> | <> | -[[req:042,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:042,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:043,R-043]] The combinations of logic gates to letters are always the same. | <> | <> | -[[req:044,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:044,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:045,R-045]] Once the puzzle is solved, the green indicator LED will light up (Refer to <> and <>). +[[req:045,R-045]] Once the puzzle is solved, the green indicator LED will light up (Refer to <> and <>). | <> | <> | [[req:046,R-046]] After the puzzle is solved, the automation puzzle begins. @@ -297,7 +297,7 @@ 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="1,1,10"] +[cols="8h,5h,~"] |=== | ID | <> | Specification @@ -308,7 +308,7 @@ documentation. Due to time constraints, the section will be left empty. ==== Hardware puzzle .Hardware puzzle requirements -[cols="1,1,10"] +[cols="8h,5h,~"] |=== | ID | <> | Specification @@ -316,13 +316,13 @@ documentation. Due to time constraints, the section will be left empty. [[req:048,R-048]] There are eight switches on the hardware puzzle board. | <> | <> | -[[req:049,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:049,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:050,R-050]] The hardware puzzle board includes a red 7-segment 4-digit display (Refer to <> for a sketch). +[[req:050,R-050]] The hardware puzzle board includes a red 7-segment 4-digit display (Refer to <> for a sketch). | <> | <> | -[[req:051,R-051]] There are 4 potentiometers on the hardware puzzle board (Refer to <> for a sketch). +[[req:051,R-051]] There are 4 potentiometers on the hardware puzzle board (Refer to <> for a sketch). | <> | <> | [[req:052,R-052]] A blue LED on the hardware puzzle board displays the morse code. @@ -358,7 +358,7 @@ documentation. Due to time constraints, the section will be left empty. [[req:062,R-062]] During the puzzle, the switches must be toggled to obtain a logical '1' at the output of the combinatorial circuit. | <> | <> | -[[req:063,R-063]] When the output of the combinatorial circuit equals '1', the green indicator LED turns on (Refer to <> for a sketch). +[[req:063,R-063]] When the output of the combinatorial circuit equals '1', the green indicator LED turns on (Refer to <> for a sketch). | <> | <> | [[req:064,R-064]] The puzzle proceeds to phase 2 when the output of the combinatorial circuit is a logical '1'. @@ -376,7 +376,7 @@ documentation. Due to time constraints, the section will be left empty. [[req:068,R-068]] The morse code is randomly generated. | <> | <> | -[[req:069,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:069,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:070,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. @@ -397,7 +397,7 @@ documentation. Due to time constraints, the section will be left empty. ==== Vault puzzle .Vault puzzle requirements -[cols="1,1,10"] +[cols="8h,5h,~"] |=== | ID | <> | Specification @@ -447,7 +447,7 @@ documentation. Due to time constraints, the section will be left empty. === Battery .Battery requirements -[cols="1,1,10"] +[cols="8h,5h,~"] |=== | ID | <> | Specification @@ -464,7 +464,7 @@ documentation. Due to time constraints, the section will be left empty. === Network Communication .Communication requirements -[cols="1,1,10"] +[cols="8h,5h,~"] |=== | ID | <> | Specification @@ -477,7 +477,7 @@ documentation. Due to time constraints, the section will be left empty. === Framework -[cols="1,1,10"] +[cols="8h,5h,~"] |=== | ID | <> | Specification @@ -497,7 +497,7 @@ documentation. Due to time constraints, the section will be left empty. === Puzzle box hub .Puzzle box hub general requirements -[cols="1,1,10"] +[cols="8h,5h,~"] |=== | ID | <> | Specification @@ -516,7 +516,7 @@ technical specifications of the puzzle box. === Wireless communication .Wireless communication requirements -[cols="1,1,10"] +[cols="8h,5h,~"] |=== | ID | <> | Specification @@ -527,7 +527,7 @@ technical specifications of the puzzle box. === Framework .Development framework requirements -[cols="1,1,10"] +[cols="8h,5h,~"] |=== | ID | <> | Specification @@ -550,7 +550,7 @@ technical specifications of the puzzle box. === Main controller .Main controller requirements -[cols="1,1,10"] +[cols="8h,5h,~"] |=== | ID | <> | Specification @@ -575,7 +575,7 @@ technical specifications of the puzzle box. === Puzzle module controller -[cols="1,1,10"] +[cols="8h,5h,~"] |=== | ID | <> | Specification @@ -601,7 +601,7 @@ technical specifications of the puzzle box. === Vault puzzle .Vault puzzle requirements -[cols="1,1,10"] +[cols="8h,5h,~"] |=== | ID | <> | Specification @@ -627,7 +627,7 @@ technical specifications of the puzzle box. === Bomb .Bomb requirements -[cols="1,1,10"] +[cols="8h,5h,~"] |=== | ID | <> | Specification @@ -650,7 +650,7 @@ This section describes the aspects of the project which have been set as preconditions and cannot be changed. .Preconditions -[cols="1,11"] +[cols="8h,~"] |=== | ID | Precondition @@ -666,7 +666,7 @@ preconditions and cannot be changed. This section lists requirements that apply to documentation produced during this project. -[cols="1,1,10"] +[cols="8h,5h,~"] |=== | ID | <> | Specification @@ -681,43 +681,43 @@ this project. |=== [appendix] -== Explanatory Images +== Attachments -[[fig:vault-disp]] +[[fig:vault-disp-sketch]] .7 Segment 4 digit screen (sketch) -image::img/requirements/vault-disp.png[] +image::img/vault-disp-sketch.png[] -[[fig:neotrellis-hardware]] +[[fig:neotrellis-hardware-sketch]] .NeoTrellis example (sketch) -image::img/requirements/neotrellis-hardware.png[] +image::img/neotrellis-hardware-sketch.png[] [[fig:neotrellis-toggle]] .Toggling LEDs after the user pressed on the button (purple dot) -image::img/requirements/neotrellis-toggle.png[width=45%] +image::img/neotrellis-toggle.png[width=45%] [[fig:neotrellis-start]] .Starting pattern of the NeoTrellis puzzle -image::img/requirements/neotrellis-start.png[width=45%] +image::img/neotrellis-start.png[width=45%] -[[fig:software-example]] +[[fig:software-example-sketch]] .Software puzzle example with logical ports (left) and letters A through F (right) -image::img/requirements/software-example.png[] +image::img/software-example-sketch.png[] -[[fig:software-codes]] +[[fig:software-codes-sketch]] .The different code fragments corresponding with the letter A through F -image::img/requirements/software-codes.png[height=35%] +image::img/software-codes-sketch.png[height=35%] -[[fig:software-cable]] +[[fig:software-cable-sketch]] .Software puzzle cable example -image::img/requirements/software-cable.png[] +image::img/software-cable-sketch.png[] -[[fig:hardware-example]] +[[fig:hardware-example-sketch]] .Hardware puzzle on the puzzle box -image::img/requirements/hardware-example.png[] +image::img/hardware-example-sketch.png[] [[fig:vault-keypad]] .Buttons combinations with level numbers in the top left -image::img/requirements/vault-keypad.png[width=45%] +image::img/vault-keypad.png[width=45%] include::share/footer.adoc[] diff --git a/docs/research.adoc b/docs/research.adoc new file mode 100644 index 0000000..ab4175e --- /dev/null +++ b/docs/research.adoc @@ -0,0 +1,741 @@ += Research: {project} +include::share/meta.adoc[] + +== Microcontrollers used in the current state. + +=== Research + +// TOOD: figures 1 through 4 waren geen cross-references meer in het originele +// document, en moeten nog opgelosd worden +The boxes consist of four sides in use (games) which can be seen in the +Attachments figures 1 through 4. One of the games (safe puzzle) seems to be +unfinished upon visual inspection which also includes a lose display. The games +that seem to be implement are the following: + +* Safe puzzle: <> +* Neotrellis puzzle: <> +* Software puzzle: <> +* Hardware puzzle: <> + +The bus cable (<>) consists out of five connectors with ten +lines, the main controller (as already known) is a Raspberry Pi 3B+ with an 8GB +MicroSD card and a custom PCB 'head' see <>. There are 4 custom +PCB's with a microcontroller slot and a connector for the 10-line bus, two of +those are used for the sides and one is unused and also empty see +<>. Of all the custom PCB's only one seems to be professional +made from a factory see <>, the others seem to be made at +school in the lab. + +* Safe puzzle PCB: <> +* Software puzzle PCB: <> + +There is also one development board from Adafruit see <> +but this one does not seem to be connected to any bus. The underside of the box +has a large light sensitive sensor which is also not connected see +<>. + +The more professional custom-made PCB has an ESP32-PICO-D4 as microcontroller +see <>. The other custom-made PCB's do not have any +microcontroller installed but seem to be made to be used by a ESP32-PICO-KIT +V4/V4.1. + +=== Summery + +There seems to be four games implemented where of only one may work because of +its integrated ESP32, the other three also may work if the missing ESP32's are +included but it is unclear if the 'unknown' PCB should be used in combination +with the Neotrellis panel and what need to be done with the safe side to get it +to work. + +=== Conclusion + +It could be quite possible that the 'unknown' PCB should be connected to the +Neotrellis panel based on the data lines properties. But besides that, only the +software may need to be updated in order to run on the ESP32's as soon as the +'missing' ESP32 dev kits are in stock. + +But everything could be made less complex, more cost effective and power +efficient by using other type of microcontrollers. The RPI could be downgraded +to a RPI Zero or an ESP32 dev kit. The microcontrollers used for the sides +could be replaced by a much smaller chip like the ATTiny or a Atmega32. + +This can only be done if the following requirements are met: + +* Dev. Board or daughterboard with spring or screw terminals +* A microcontroller with enough IO +* A microcontroller with all the required communication busses. +* It may not cost more than one day to rebuild the system. + +A follow up research should reveal which microcontroller and dev. Board / +daughterboard is best fitted for this project. + +=== NOTES + +The Dev kits are not available and newer types do not meet the current +footprint of the custom PCB's. So it is suggested that the next group will +design a pcb with another MCU on it in order to match the pin layout and make +use of a smaller more efficient chip. Or they can convert the prototype PCB's +to a production version with the ESP32 chip on it (if the chip it self it still +available at that time) or pick another MCU in that stage anyway. + +The hardware side uses a single DSP (HC166) to process the input of the +switches, the software side uses two shift registers (74HC59SD) to control the +LED's. + +Issues + +. Button row 4, col 1 for the safe side needs to be replaced (missing a pin) +. LED strips for the software and hardware sides only work for 50%. + +==== (Appendix Loek) + +The puzzle bus connector (see <>) appears to have 10 +conductors in total. The hardware schematics from 21-22 reveal the pinout of +this bus connector, which is shown in <>. + +After searching through the other design documents from this year, no +references to the "HarwareInterrput" line or interrupts in general were found. +The puzzle source code folders also did not contain code which initialized this +line as an interrupt. It is assumed this line is unusable, as it is connected +but has no specified functionality. + +// this is super verbose but works +:fig-caption: {figure-caption} {counter:figure-number} +[[fig:puzzle-bus-connector,{fig-caption}]] +.Puzzle bus pinout +[caption="{fig-caption}. "] +==== +image::img/puzzle-bus-connector.svg[scale=150%] + +[.text-center] +Source: cite:[2122_design] + +(Connector key is next to pin 5) +==== + +== Controllers + +To mitigate power consumption issues discovered by the 21-22 group, new +controllers were chosen for this year's (23-24) run of the puzzle box project. +This section compares different microcontroller options for both the main +controller and controller used in puzzle modules. + +=== Main controller + +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 (R#136). +* Must be able to connect to a standard 802.11b/g/n access point (R#137). +* Must be able to serve TCP socket connection(s) (R#138). +* Should be power efficient (R#166). +* Is available as a development kit from Farnell (R#139). + +<> lists the considered MCU options matching the above criteria. This +list is a compilation of microcontroller offerings from the following +manufacturers: Atmel, Espressif, Raspberry Pi. + +Of these controllers, the Raspberry Pi RP2040 has the lowest clock speed and +highest memory. Its lower clock speed means that it will likely draw less power +than the other options. It also happens to be less expensive than all other +options. Due to these reasons, the RP2040 was chosen as main controller MCU. +The Raspberry Pi Pico W board is utilized during development. + +[[tab:1]] +.Main controller MCU candidates +[%autowidth] +|=== +| Model | I^2^C peripheral count | SRAM | Flash | Clock speed + +| WFI32E01PC | 1 | 256 KB | 1 MB | 200 MHz +| ESP8266 | 1 | 50 KB | 16 MB | 160 MHz +| RP2040 | 2 | 264 KB | 2 MB | 133 MHz +|=== + +=== Puzzle module controller + +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 (R#141). +* Should has enough I/O ports to directly control moderately complex puzzles + (R#142). +* Should be power efficient (R#143). +* Is available as a development kit from Farnell (R#145). +* Has a configurable clock speed (R#144). + +<> lists the considered MCU options matching the above criteria. This +list is a compilation of microcontroller offerings from the following +manufacturers: Atmel, STMicroelectronics, Raspberry Pi. + +All the MCUs listed in <> support some version of a low-power mode. The +RP2040 is again included and appears here because it supports clock speed +configuration and has a clock gate for each peripheral [2], which may make it a +feasible option with regards to power consumption. Choosing the RP2040 may also +simplify the development process as only a single MCU toolchain needs to be +maintained. + +The Microchip PIC16F15276 is the most power efficient on this list and is the +recommended MCU for puzzle modules. It supports both extreme underclocking and +has a low power mode. This chip is available as the 'MICROCHIP EV35F40A' +evaluation kit. + +Because this year's run of this project was carried out by a team consisting +only of software students, this choice remains as a recommendation. The puzzle +box hardware may still use the ESP32 development kits from the 21-22 group. + +[[tab:2]] +.Puzzle module controller MCU candidates +[%autowidth] +|=== +| Model | I/O ports | I^2^C peripheral count | SRAM | Flash | Clock speed + +| PIC16F15276 | 40 | 1 | 2 KB | 28 KB | 32 kHz – 32 MHz +| STM8L152C6T6 | 41 | 1 | 2 KB | 32 KB | 38 kHz – 16 MHz +| RP2040 | 26 | 2 | 264 KB | 2 MB | 10 MHz – 133 MHz +|=== + +=== Conclusions + +The main MCU that is utilized for this year's (23-24) run of this project is +the Raspberry Pi RP2040 on the Raspberry Pi Pico W. The recommended MCU for new +puzzle modules is the Microchip PIC16F15276. The existing puzzle modules still +utilize the ESP32 development kits chosen by the 21-22 group. + +== Main Controller OS + +Because the hardware produced by the 21-22 group uses a Raspberry Pi 3B+ as +main controller, the usage of this specific board was turned into a +prerequisite for this project (??). The Raspberry Pi 3B+ uses the Broadcom +BCM2837 chipset, which supports the aarch64 instruction set cite:[rpicpu]. +Because the puzzle box should be able to run on battery power (??), the CPU +should be under as little load as possible to preserve power. Choosing the +right operating system is crucial to ensure maximum control over which +processes consume CPU resources. This section indexes the available operating +systems that support the aarch64 instruction set to support the decision for +main controller OS in the design document [??]. + +Each operating system is evaluated on the following criteria: + +* Number of 'base' software packages (pre-installed software) +* Size of base installation (base disk utilization) +* Time required to get set-up +* Software iteration time (amount of work required to complete a + compile-upload-run cycle) +* Whether it is covered by the standard curriculum at Avans University of + Applied Sciences + +All of these factors (except for curriculum coverage) should be low. This means +that operating systems that are minimalistic by default are preferred. + +=== Raspberry Pi OS Lite (Debian) + +The manufacturer of the Raspberry Pi boards publishes a modified version of the +Debian Linux distribution which is aimed at general-purpose users [??]. It +comes with an easy-to-use installer, and is the only OS officially supported by +the manufacturer of this board. All the required drivers come pre-installed, +which means this OS has very little setup time. + +Raspberry Pi OS comes in 3 different varieties [??], the 'Light' variant of +which is the most minimalistic. This variant comes with the least number of +pre-installed software packages and has a base image size of 2.6 GiB after +extracting the archive from the official download page [??]. + +This exact OS is not covered in the normal curriculum, but other derivative +distributions of Debian are, so this OS is be considered familiar. + +=== Void Linux + +=== Linux From Scratch + +=== Bare-metal Firmware + +=== Conclusions + +<> summarizes the considered operating systems based on the criteria +outlined at the start of this section. + +[[tab:3]] +.Main controller OS comparison +[%autowidth] +|=== +| | Packages | Size | Set-up time | Iteration time | Covered + +| Raspberry Pi OS Lite | 592 | 2.6 GiB | Medium | Short | Yes +| Void Linux | 126 | 334 MiB | Short | Short | No +| Linux from scratch | n/a | 25+ MiB | Long | Long | Yes +| Bare-metal firmware | n/a | n/a | Long | Long | No +|=== + +== Unit Testing Framework Research (Thomas) + +=== Research question + +Which unit testing frameworks are available and relevant to the project, +keeping in mind RTOS-specific frameworks, and what features do they have? + +=== General framework comparison + +In <> is a general comparison shown of multiple different frameworks. +These are either a header-only testing framework, a testing framework +specifically designed for embedded systems, a general-purpose {cpp} library, or a +specialized {cpp} unit testing framework. The following subsections will give +more information about each framework and their features. + +[[tab:4]] +.General testing framework comparison cite:[Ali24,Joh21] +[%autowidth] +|=== +| Framework | Language | Lightweight | Mocking Support | Portable + +| CppUTest | C/{cpp} | Yes | Yes (CppUMock) | Yes +| Catch | {cpp} | Yes | Limited | Yes +| Doctest | {cpp} | Yes | Limited | Yes +| Google Test | {cpp} | No | Yes (GMock) | Yes +| Boost.Test | C | Yes | Limited | Yes +|=== + +=== CppUTest + +A C/{cpp} based unit testing framework, designed specifically for testing C/{cpp} +applications on embedded systems. It can be used for testing general C/{cpp} code +and supports TDD-style tests (Test-Driven Development). This is due to it being +a header-only testing framework, and not requiring linking of external +libraries. + +It offers multiple different assertion macros for verifying expected behavior +and supports the mocking of functions and memory leak detection. It works on +most platforms, including Unix-based systems, Cygwin, and MacOS. It can be +integrated with build systems like Make or CMake. The framework is also +compatible with RTOS-based applications and Raspberry Pi, both require +configuring the development environment to allow CppUTest to work. It supports +up to the {cpp}17 standard, after which there is experimental support for the +{cpp}20 & {cpp}23 standards. cite:[Cpp24] + +=== Catch + +A {cpp} unit testing framework designed in a straightforward and expressive +manner. Just like CppUTest it is a header-only testing framework and doesn't +have any external dependencies, but instead of supporting TDD-style testing, it +supports BDD-style testing. Which is Behavior-Driven Development-style testing, +where test cases can be written in a natural language format (Given-When-Then +statements). + +It offers a simplified testing syntax, and assertions look like {cpp} Boolean +expressions. It allows the developer to organize tests into sections, providing +a local (in file) way to share setup and teardown code. It also allows +developers to tag tests and run tests selectively using their tags. The +framework is also compatible with RTOS-based applications and can be used on a +Raspberry Pi. It supports up to the {cpp}20 standard, after which there is +experimental support for the {cpp}23 standard. cite:[Cat24] + +=== Doctest + +A {cpp} based unit testing framework, designed to be minimalistic, easy to +integrate and expressive. It supports {cpp}11/14/17/20/23 and allows for writing +tests directly in production code, due to it being a single-header library. + +The tests written with this framework are automatically discovered and executed +without any manual registration. It has no separate compilation steps for the +tests as it is header-only and is thread-safe by default. It also allows for +customizable test output formats and is compatible with RTOS/Raspberry Pi. +cite:[Doc24] + +=== Google Test + +A {cpp} based testing framework, following the xUnit architecture, which is used +for structuring tests. It is a single-header library just like doctest; +however, it does require the developer to write tests in separate test files. +It has minimal external dependencies allowing it to easily integrate into +projects. + +It supports mocking functions and has a large variety of assertions for +verifying expected behavior, including death tests. It allows the developer to +run tests multiple times with different input values and the developer can set +up common test environments using fixtures. Furthermore, it allows for custom +assertions and test output. It is also thread-safe by default. It supports +testing for RTOS/Raspberry Pi, as well as {cpp}20 and lower. There is +experimental support for {cpp}23. cite:[goo24] + +=== Boost.Test + +A {cpp} based unit testing framework, designed for writing, and organizing unit +tests. It is compatible with {cpp}11/14/17 and can be integrated with {cpp} +projects running on RTOS platforms. However, even though you can use Boost.Test +on the Raspberry Pi, it does not have direct Raspberry Pi-specific features. + +It supports the creation of test suites, allowing the developer to group test +cases into logical suites. Furthermore, it provides a wide range of assertion +macros for checking test conditions and can generate test result reports in +various formats (e.g. XML, human-readable). It works on most platforms, +including Windows, Linux, macOS, and other Unix systems. cite:[Boo24,Git24] + +=== Conclusion + +After going through the researched unit tests a few things can be noted for +each framework. CppUTest has been designed for embedded system testing and has +features for memory leak detection and mocking. However, it is supported until +{cpp}17 while the other versions for {cpp} are all experimental. Catch allows for +easy test creation. Furthermore, it allows for test tagging meaning you are +able to run tests selectively using their tags and it is supported up to {cpp}20. +Doctest allows for writing tests directly in production code, meaning a second +test file is not necessary. It has an automatic test discovery function, as +well as being thread safe on default and allowing customizable test output +formats. Google Test uses xUnit test architecture and supports mocking +functions. It has a large variety of assertions including death assertions and +supports running tests multiple times with different input values. It allows +custom test assertions / test output and is thread-safe by default. It also has +support up to {cpp}20. Boost.Test allows for writing and organizing unit tests +and has support for {cpp}11/14/17. It supports the creation of test suites, +making test grouping possible. It has a large range of assertion macros and can +generate test result reports in multiple different formats. + +After going through the notable features of the different testing frameworks +Google Test was chosen as the testing framework for this project. As it has a +structured syntax, readability and a lot of features required for reliable +testing. Including mocking tests, a large amount of assertions, multiple test +with different input support, and lastly being supported in the newest +non-experimental version of {cpp}. + +== Original Puzzle Box Functionality Research (Thomas) + +=== Research question + +What gameplay functionality should the original puzzle box have had? + +=== Group 2019-2020 + +==== Hardware Puzzle + +The hardware puzzle was to be a puzzle consisting of two parts, a puzzle using +a 555-oscillator and a puzzle using a multi meter. The 555-oscillator puzzle +would be used to give students an idea how they can create a typical hardware +application. The multi meter puzzle would introduce students to the usage of +the multi meter, while giving the bomb group the values measured using the +multimeter which then correlates with 3 different potentiometers. + +==== Software Puzzle + +The software puzzle was to be a puzzle which introduces the student to an +Arduino. The puzzle box would contain an Arduino, a few switches, and a few +LEDs. The student would be able to program the Arduino by using a visual +drag-and-drop programming language. This program would have to get an input +value, which is given by the switches, and an output value shown on the LEDs. +The idea is to get both the input and output value correspond with each other. + +==== Automation Puzzle + +The automation puzzle would introduce the student to a factory structure, +consisting of multiple 'tubes' which contain a certain color. These colors +could be mixed by the students to get the corresponding colors shown in their +game manual. The tubes which contain these colors would have to follow a +specific route, and are to join with other tubes, creating new colors which +makes the puzzle a bit more complex. The valves to open and close the tubes are +grouped to add another difficulty level to the puzzle. See +<> for an example of this puzzle. + +==== Safe Puzzle + +The safe puzzle is a puzzle created to test the communication skills of the +student. It shows a code on the puzzle box, which then needs to be given to +students with the game manual, who give the students at the puzzle box the +button they must click. This needs to be done 5 times before the safe opens and +the last code is given to defuse the bomb if a wrong button is clicked the safe +resets and they need to start over from the beginning. See +<> & <>. + +=== Group 2020-2021 + +The automation and safe puzzle were not changed this year. + +==== Hardware Puzzle + +The hardware puzzle was revised this year, it would include a quiz which helps +the students with solving the puzzle and has a completely different interface +from the first one. The quiz questions can be found in the document +"Speluitleg_puzzlebox_39-06-2021", which can be found in this project's +directory. Once the students solve the quiz, they can push the button found in +the puzzle, and morse code will be given to the students. The code given using +morse code is one of the required codes to disarm the bomb. + +==== Software Puzzle + +The software puzzle was also revised this year, instead of a puzzle using a +visual drag-and-drop programming language it would instead contain two columns +which would need to relate to each other. One column shows digital ports, which +is part of 'Digitale Techniek' and the second column contains letters +corresponding with C code. This code can be found in the game manual and +requires the students to communicate between each other which letter which code +is. Once all cables are connected the LEDs above the puzzle will glow in +binary, this needs to be deciphered into decimals to get another code to defuse +the bomb. An example of this puzzle can be seen in <> & +<>. + +==== Neotrellis Puzzle + +A new puzzle was added to the box, namely a neotrellis-type puzzle. This would +mainly be a puzzle requiring a lot of figuring out, as it does not correlate +with any of the three directions in the Technical Computer Science curriculum. +It would contain an 8x8 LED button system, where you can toggle the LEDs by +clicking on a button. You complete the puzzle by getting a matching pattern +with the one given in the game manual. See <>, +<> & <> for examples of this +puzzle. + +=== Group 2021-2022 + +The software, automation, safe, and neotrellis puzzles were not changed this +year. + +==== Hardware Puzzle + +The hardware puzzle was revised again this year, removing the quiz, and making +it a data flow puzzle using logic gates and circuitry. There wasn't any more +information about the way to solve the puzzle. See <> for an +example of this puzzle on the puzzle box. + +=== Group 2022-2023 + +No puzzles were changed this year. + +=== Conclusion + +The puzzles have gone through a lot of changes and designs, but in the end the +following puzzles will be used from project group 2019-2020: + +* Automation puzzle +* Safe puzzle + +The following puzzles will be used from project group 2020-2021: + +* Software puzzle +* Neotrellis puzzle + +And the following puzzle will be used from project group 2021-2022: + +* Hardware puzzle + +The way these puzzles are solved has been summarized in this research document, +but the most complete versions of how to solve these puzzles are given in the +group's respective design document. + +== Research of hardware designs of previous groups (21-22 and 22-23) + +This part of the research looks at the hardware designs of the previous groups +that did this project. These are compared with each other and finally the +points of interest are given that the software must meet in order to work with +this hardware. + +=== Design of 21-22 group + +This group has developed a puzzle box with a puzzle on all sides. Each puzzle +has to answer a question from the different directions in this study. So, think +software, hardware and an automation puzzle. The 21-22 group designed and +started the realisation of a physical puzzle box. The status of the puzzle box +is a carved wooden box containing one mainboard hat for the Raspberry PI 3B+ +(chosen for its availability), one puzzle based on the ESP32-PICO-D4 system on +chip (SOC) and three puzzle prototypes based on the ESP32-PICO-KIT (D4 +development kit). The puzzle boards are mounted on the sidewalls of the wooden +box and are game technically largely functional. Behind this chosen hardware is +not a thoughtful choice but was chosen mainly due to availability and because +these components have been used by students before. + +The four puzzles have game-playing software, but the puzzles have not yet been +play-tested. All puzzles run on the same state machine, the communication +module for I2C communication between the puzzles is integrated but not yet +fully implemented. So, communication is possible but not processed in the state +machine other than resetting the game and reading the state. The I2C module for +the mainboard has also been worked out in a {cpp} application for the Raspberry +PI 3B+. + +To communicate via a network between the puzzle box and the bomb, a hub is +used. Next to the connection between the devices in the local network, the hub +will also connect to the internet for time synchronization and external +configuration. The hub will also act as a webserver for the configuration of +the boxes and bombs and, as a network manager for the communication between the +devices. The hub makes also use of a Raspberry Pi 3B. The raspberry pi for the +main hub will be combined with a wireless USB dongle due to the need for +multiple wireless radios. The USB dongle used for this project has not been +defined, any dongle supporting the 802.11x standard will qualify. + +=== Design of 22-23 group + +What did the group from 22-23 develop as a hardware design? + +At the start of their project, the 22-23 group has been busy re-structuring the +puzzle box developed by 21-22. The basis of 21-22 was not well structured, +there were low requirements and specifications and little research available. +As a result, this group (21-22) did have time to realise their design. However, +the end result of this was a half-working puzzle box with no coherent hardware. +As a result, the 22-23 group chose not to implement hardware but first +structured the project properly with requirements and then went on to create a +thoughtful design. + +The new design consists of a mainboard connected to the puzzle box via a puzzle +bus (consisting of: 5V, 3.3V and I2C). The idea of the puzzle box is that it is +developed modular way so that puzzles can easily be removed and inserted. +Therefore, one standard interface (puzzle bus) is designed to which every +puzzle can be connected. Each puzzle therefore also needs its own +microcontroller to control the logic. So, the choice of microcontroller of both +the puzzles and the mainboard has not yet been made by this group. However, +this group did give a number of points that the microcontroller must meet in +order to work with the hardware design: + +* Operationeel op een voedingsspanning van 3.3V of 5V +* Ondersteuning van I2C +* Voldoende I/O voor aansturing puzzels +* Sleep mode (aanbevolen) + +The main architecture (<>) includes the USB-C adapters, +puzzle boxes, bombs, puzzle box hub and the computer. These components are +powered by batteries and communicate with each other via Wifi meshing (is not +yet working). Through the puzzle box hub, a computer can be used to configure +and start the system. So, the puzzle box itself consists of several sides on +which a puzzle can be played. With the outcomes of all these puzzles, the +entire box can be solved and opened. + +[[fig:architecture-main]] +.Main architecture +image::img/external-architecture-old.png[width=45%] + +=== What are the differences between the designs of the 21-22 and 22-23 groups? + +Overall, the designs of the two groups are not far apart. The topology is +similar to each other. What does differ is that the 21-22 group chose available +ESP32 modules for the separate puzzles, while the 22-23 group left the choice +of microcontrollers open. This is because this group consisted only of hardware +students and the choice of microcontrollers also affects the software to be +written. The other difference is that the 21-22 group only tells how they +realise the design without indicating which design choices they made for this +and what other options there were. The 22-23 group did do this and described it +in the design document. TODO Refer to design document + +=== What to consider when developing software + +The hardware group (22-23), in addition to the recommendations in the +requirements package, has provided enough information to work with as a +software group. TODO: Refereren naar eisenpakket 22/23 It was recommended by +last year's group that software students pick up the following steps: + +. Choose suitable microcontrollers +. Understand the operation of wifi mesh + set up the web page +. Create software design for puzzles and mainboard +. Integrate the software into the puzzle box + +With all these recommendations combined, the following points should be kept in +mind when developing the software: + +* Software should be written separately for each puzzle as a module. ++ +As described, each puzzle is a separate module so that these puzzles can be +adapted later when required. So, provide a good architecture in which puzzles +can be modified, added or removed without changing the whole structure of the +software. +* Make sure the software works with the given hardware designs of groups 21-22 + and 22-23. Elwin's research showed that the main board consists of a + Raspberry Pi. The puzzles are run on an ESP32, so the software for this + should consist of a language compatible with these devices, for example {cpp} + or Python. +* The individual modules communicate via the I2C communication protocol. So, + make sure it is clear that the Raspberry Pi is the master and the ESP32s + serve as slaves. The addresses of the separate ESP32s should be unique and + properly configured for this purpose. +* The software must be flexible to allow modules to be modified later +* If the puzzles need to be modified later, the software must be written in a + way that can be understood. Think of good documentation and comments + accompanying the code. In addition, use programming languages from the + standard curriculum of the program. So that other students can continue + working with them later. +* The 22-23 has not yet been able to calculate the power supply of the puzzles, + so this should be taken into account when implementing the systems. Think of + a certain function or power-saving mode that turns off certain + puzzles/modules when not in use. +* Provide test documents +* Provide well-documented software, think comments in the code and a handover + document. The intention is that after this project, the software will be + almost ready for use, groups should also be able to understand the software + at a later stage. Also, for students with lesser software knowledge. + +[appendix] +== Attachments + +[[fig:vault-side]] +.Safe side +image::img/vault-side.jpg[width=45%] + +[[fig:neotrellis-side]] +.Neotrellis side +image::img/neotrellis-side.jpg[width=45%] + +[[fig:software-side]] +.Software side +image::img/software-side.jpg[width=45%] + +[[fig:hardware-side]] +.Hardware side +image::img/hardware-side.jpg[width=45%] + +[[fig:software-pcb]] +.Software side PCB +image::img/software-pcb.jpg[width=45%] + +[[fig:vault-pcb]] +.Safe side PCB +image::img/vault-pcb.jpg[width=45%] + +[[fig:unknown-pcb]] +.Unknown PCB +image::img/unknown-pcb.jpg[width=45%] + +[[fig:hardware-pcb]] +.Hardware side PCB +image::img/hardware-pcb.jpg[width=45%] + +[[fig:bus-connector]] +.Bus cable +image::img/bus-connector.jpg[width=45%] + +[[fig:neotrellis-pcb]] +.Neotrellis side PCB +image::img/neotrellis-pcb.jpg[width=45%] + +[[fig:light-sensor]] +.Light sensor +image::img/light-sensor.jpg[width=45%] + +[[fig:main-pcb]] +.RPI PCB (Head) +image::img/main-pcb.jpg[width=45%] + +[[fig:automation-example]] +.Automation puzzle example +image::img/automation-example.png[width=35%] + +[[fig:software-example]] +.Software puzzle box example +image::img/software-example.png[width=45%] + +[[fig:software-codes]] +.Software puzzle game manual example +image::img/software-codes.png[height=30%] + +[[fig:neotrellis-toggle]] +.Neotrellis puzzle toggle example +image::img/neotrellis-toggle.png[width=45%] + +[[fig:neotrellis-example]] +.Neotrellis puzzle 8x8 example +image::img/neotrellis-example.png[] + +[[fig:neotrellis-start]] +.Neotrellis pattern example +image::img/neotrellis-start.png[width=45%] + +[[fig:vault-interface]] +.Safe puzzle schematic example +image::img/vault-interface.png[width=40%] + +[[fig:vault-keypad-full]] +.Safe puzzle combinations given in the manual +image::img/vault-keypad-full.png[width=45%] + +include::share/footer.adoc[] diff --git a/docs/share/glossary.adoc b/docs/share/glossary.adoc index b0192a0..8cc19f5 100644 --- a/docs/share/glossary.adoc +++ b/docs/share/glossary.adoc @@ -1,4 +1,4 @@ -[glossary] +[appendix] == Glossary [glossary] diff --git a/docs/share/meta.adoc b/docs/share/meta.adoc index 2e54c18..0b6cb78 100644 --- a/docs/share/meta.adoc +++ b/docs/share/meta.adoc @@ -11,3 +11,6 @@ :author_3: Lars Faase :author_4: Elwin Hammer :xrefstyle: short +:project: Project Puzzlebox + +// see https://docs.asciidoctor.org/asciidoc/latest/attributes/document-attributes-ref diff --git a/docs/share/references.adoc b/docs/share/references.adoc index e475900..e7f5b61 100644 --- a/docs/share/references.adoc +++ b/docs/share/references.adoc @@ -1,4 +1,4 @@ -[references] +[appendix] == References bibliography::[] diff --git a/docs/share/refs.bib b/docs/share/refs.bib index f2cb813..b6fe625 100644 --- a/docs/share/refs.bib +++ b/docs/share/refs.bib @@ -1,3 +1,5 @@ +% see https://tug.ctan.org/info/biblatex-cheatsheet/biblatex-cheatsheet.pdf + @online{githubprojects, title = {About Projects - GitHub Docs}, url = {https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects}, @@ -97,6 +99,7 @@ } @online{Boo24, + title = {Boost.Test - 1.75.0}, url = {https://www.boost.org/doc/libs/1_75_0/libs/test/doc/html/index.html}, msbib-accessed = {2024-02-28}, } diff --git a/docs/theme.yml b/docs/theme.yml index 824c74b..1537f50 100644 --- a/docs/theme.yml +++ b/docs/theme.yml @@ -65,6 +65,9 @@ caption: align: center end: bottom +example: + caption: + end: $caption-end table: caption: end: $caption-end -- cgit v1.2.3 From 1e124d005c8b3885ca960a3894019331ef288b5e Mon Sep 17 00:00:00 2001 From: lonkaars Date: Sun, 21 Apr 2024 17:03:38 +0200 Subject: add figures and cross-references to design.adoc --- docs/design.adoc | 239 +++++++++++++++++++++++++++------------------ docs/img/bomb-io.png | Bin 0 -> 25112 bytes docs/img/hardware-io.png | Bin 0 -> 45639 bytes docs/img/neotrellis-io.png | Bin 0 -> 21940 bytes docs/img/software-io.png | Bin 0 -> 33531 bytes docs/img/vault-io.png | Bin 0 -> 31991 bytes docs/readme.md | 12 +++ 7 files changed, 155 insertions(+), 96 deletions(-) create mode 100644 docs/img/bomb-io.png create mode 100644 docs/img/hardware-io.png create mode 100644 docs/img/neotrellis-io.png create mode 100644 docs/img/software-io.png create mode 100644 docs/img/vault-io.png (limited to 'docs/img') diff --git a/docs/design.adoc b/docs/design.adoc index 2bac6b3..533c02a 100644 --- a/docs/design.adoc +++ b/docs/design.adoc @@ -15,14 +15,16 @@ Only design details deemed relevant by the document authors are documented here. Low-level implementation details such as API interfaces, code paths and workarounds are documented inside the source code repository. +[[sec:lv1]] == Top-Level This section of the design document establishes the development target -hardware. It also specifies the modules that are elaborated further in §3. +hardware. It also specifies the modules that are elaborated further in +<>. -Figure 1 shows a block diagram that describes the context in which the puzzle -box is used. The puzzle box in this diagram internally consists of a main -controller and multiple puzzle modules. Other notable details include: +<> shows a block diagram that describes the context in which +the puzzle box is used. The puzzle box in this diagram internally consists of a +main controller and multiple puzzle modules. Other notable details include: * The charger is removable, and the puzzle box is intended to be used as a battery-powered device (i.e. not while tethered). @@ -35,7 +37,9 @@ controller and multiple puzzle modules. Other notable details include: connection is used to configure the puzzle box before gameplay or modify its state during gameplay. +[[fig:system-top]] .Context block diagram +image::img/system-top.svg[] The rest of this section details the internal hardware modules and the separation of functionality of these modules. @@ -80,24 +84,27 @@ was selected. The criteria for a puzzle module controller are: -* Must have an I^2^C peripheral (R#141). +* Must have an I^2^C peripheral (<>). * Should have enough I/O ports to directly control moderately complex puzzles - (R#142). -* Should be power efficient (R#143). + (<>). +* Should be power efficient (<>). -The research document [1] compares various microcontrollers matching these -criteria. As a result of this research, the Microchip PIC16F15276 was selected -as the recommended microcontroller for future puzzle modules. The current -development hardware utilizes an ESP32-PICO-D4 module, so the puzzle module -software is written with portability in mind. +The research document cite:[research] compares various microcontrollers +matching these criteria. As a result of this research, the Microchip +PIC16F15276 was selected as the recommended microcontroller for future puzzle +modules. The current development hardware utilizes an ESP32-PICO-D4 module, so +the puzzle module software is written with portability in mind. +[[fig:puzzle-module-top]] .Generic puzzle module top-level block diagram +image::img/puzzle-module-top.svg[] -Figure 2 shows a block diagram of how most puzzle modules are implemented. -Since the internal components of the puzzle module block from Figure 2 differ -for each puzzle, they are left out in this section. Section 3 includes the next -detail level for all of the implemented puzzles this year. The puzzle bus is -detailed further in §2.3. +<> shows a block diagram of how most puzzle modules are +implemented. Since the internal components of the puzzle module block from +<> differ for each puzzle, they are left out in this +section. <> includes the next detail level for all of the implemented +puzzles this year. The puzzle bus is detailed further in +<>. === Main Controller @@ -119,70 +126,84 @@ The specific requirement of being able to serve TCP socket connections was created so this year's puzzle box could keep compatibility with the software produced by the 21-22 group. -As mentioned in the research document [1], the 21-22 group produced the -hardware that is used as development target for this year's (23-24) run of the -puzzle box project. The existing hardware utilizes a Raspberry Pi 3B+ as main -controller, but this controller caused issues with power consumption [2]. -Choosing a different controller during development requires significant -refactoring, so a different main controller has been selected at the start of -this year's run of the puzzle box project. +As mentioned in the research document cite:[research], the 21-22 group produced +the hardware that is used as development target for this year's (23-24) run of +the puzzle box project. The existing hardware utilizes a Raspberry Pi 3B+ as +main controller, but this controller caused issues with power consumption +cite:[2122_handover]. Choosing a different controller during development +requires significant refactoring, so a different main controller has been +selected at the start of this year's run of the puzzle box project. The criteria for the main controller are: -* Must have an I^2^C peripheral (R#136). -* Must be able to connect to a standard 802.11b/g/n access point (R#137). -* Must be able to serve TCP socket connection(s) (R#138). -* Should be power efficient (R#166). +* Must have an 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 (<>). The requirements document compares various microcontrollers that fit these criteria. After this comparison, the decision was made to utilize the Raspberry Pi Pico W as main controller during development. +[[fig:main-controller-top]] .Main controller top-level block diagram +image::img/main-controller-top.svg[] -Figure 3 shows a block diagram of the main controller and its inputs and -outputs. The main controller is the only module in the puzzle box that is able -to communicate over Wi-Fi and is therefore responsible for all communication -between the puzzle box and game operator. The puzzle bus is detailed further in -§2.3. +<> shows a block diagram of the main controller and +its inputs and outputs. The main controller is the only module in the puzzle +box that is able to communicate over Wi-Fi and is therefore responsible for all +communication between the puzzle box and game operator. The puzzle bus is +detailed further in <>. +[[sec:lv1-communication]] === Communication Communication between puzzle modules, the main controller and other auxiliary peripherals is handled through a central I^2^C bus referred to as the 'puzzle bus'. This design was again carried over from the hardware design from the -21-22 group [3]. +21-22 group cite:[2122_design]. The only notable difference made this year was the removal of the -"HarwareInterrupt" line1, which was connected but not utilized [1]. +"HarwareInterrupt" line1{empty}footnote:[This is not a typo], which was +connected but not utilized cite:[research]. -Address definitions and protocol specifications are further detailed in §3.3. +Address definitions and protocol specifications are further detailed in +<>. === Power supply One of the user requirements is that the puzzle box runs on battery power -(R#89). Due to the team composition of this year's (23-24) run of the puzzle -box project, a new power supply was not chosen, even though the current power -supply was determined insufficient by the 21-22 group. This year, additional -requirements were specified for the power supply, which were used when -selecting MCUs suitable for battery-powered applications. +(<>). Due to the team composition of this year's (23-24) run +of the puzzle box project, a new power supply was not chosen, even though the +current power supply was determined insufficient by the 21-22 group. This year, +additional requirements were specified for the power supply, which were used +when selecting MCUs suitable for battery-powered applications. +[[fig:power-supply-top]] .Power supply module top-level block diagram +image::img/power-supply-top.svg[] -Figure 2 shows a block diagram of how most puzzle modules are implemented. -Besides the additional requirements, the power supply remains the same, and -will not be elaborated further on in this document. +<> shows a block diagram of how most puzzle modules are +implemented. Besides the additional requirements, the power supply remains the +same, and will not be elaborated further on in this document. === Overview -Figure 5 is the resulting combination of the modules from Figures 3, 2 and 4. +<> is the resulting combination of the modules from +<>, <> and +<>. +[[fig:system-bus]] .Hardware component overview +image::img/system-bus.svg[] +[[sec:lv2]] == Modules -This section elaborates on the top-level specifications from §2 with additional -hardware specifications and software design decisions. +This section elaborates on the top-level specifications from <> with +additional hardware specifications and software design decisions. === Puzzle Module Framework @@ -195,33 +216,39 @@ The puzzle framework is the foundation of the puzzle box software, and is designed to facilitate the following: * Allow puzzle modules to be swapped with minimal downtime or maintenance - (R#132). + (<>). * Simplify the development process and integration of new puzzle modules - (R#130). + (<>). * Provide abstracted interfaces to allow for easy integration of the puzzle box - as part of a larger whole (R#133). + as part of a larger whole (<>). +[[sec:framework-state]] ==== State -All puzzle modules implement the same state machine shown in Figure 6. Note -that the arrows indicate state transitions that a puzzle module may take on its -own. The main controller also allows the game operator to manually set the -current state as one of the states on the right half of Figure 6, which can be -used to skip a puzzle if a player is stuck (R#168) or reset a game if it is -malfunctioning (R#167). +All puzzle modules implement the same state machine shown in +<>. Note that the arrows indicate state +transitions that a puzzle module may take on its own. The main controller also +allows the game operator to manually set the current state as one of the states +on the right half of <>, which can be used to +skip a puzzle if a player is stuck (<>) or reset a game if +it is malfunctioning (<>). Puzzle modules start in the 'uninitialized' state, where they repeatedly send -messages to the main controller (see §3.2.3). The state transition from -'uninitialized' to 'reset' is forced by the main controller upon -initialization. States on the right half of Figure 6 are used during gameplay. +messages to the main controller (see <>). The state transition +from 'uninitialized' to 'reset' is forced by the main controller upon +initialization. States on the right half of <> +are used during gameplay. +[[fig:puzzle-module-common-state]] .Global puzzle module state machine +image::img/puzzle-module-common-state.svg[] -The state machine described in Figure 6 is referred to as the global state. -Puzzle modules may also declare and define custom state variables, which is -referred to as auxiliary state. These auxiliary state variables contain -game-specific variables; e.g. the binary state of each button on the Neotrellis -puzzle module, or the last passcode entered on the vault puzzle module. +The state machine described in <> is referred +to as the global state. Puzzle modules may also declare and define custom state +variables, which is referred to as auxiliary state. These auxiliary state +variables contain game-specific variables; e.g. the binary state of each button +on the Neotrellis puzzle module, or the last passcode entered on the vault +puzzle module. Separating the auxiliary state from the generic state allows the main controller to handle the auxiliary state as an arbitrary blob, which allows for @@ -236,7 +263,7 @@ The puzzle module framework describes the following commands: * Update The 'read' and 'write' commands are used to communicate both types of state -defined in §3.1.1. +defined in <>. To avoid issues caused by state synchronization memory consumption on the main controller and puzzle modules, auxiliary state is only stored on each @@ -257,9 +284,12 @@ This subsection defines the function and state of the main controller. ==== State The global state of the main controller is an aggregated version of all -installed puzzle modules and is defined by the state machine shown in Figure 7. +installed puzzle modules and is defined by the state machine shown in +<>. +[[fig:main-controller-state]] .Main controller global state machine +image::img/main-controller-state.svg[] The following list describes when each state is active: @@ -279,53 +309,58 @@ puzzle modules is stored as an auxiliary state variable of the main controller. ==== Initializing Puzzle Modules -Puzzle modules start in the 'uninitialized' state (see Figure 6). In this -state, the puzzle module repeatedly sends an update command to the main -controller. The main controller responds to this message by sending a 'set -state' command with the target state as 'reset' as reply. Before this response -is sent, the main controller internally adds the bus address of the puzzle -module requesting to be initialized to the list of installed puzzle modules. -From the main controller's point of view, this reply marks the moment the -initialization is complete. +Puzzle modules start in the 'uninitialized' state (see +<>). In this state, the puzzle module +repeatedly sends an update command to the main controller. The main controller +responds to this message by sending a 'set state' command with the target state +as 'reset' as reply. Before this response is sent, the main controller +internally adds the bus address of the puzzle module requesting to be +initialized to the list of installed puzzle modules. From the main controller's +point of view, this reply marks the moment the initialization is complete. +[[fig:sequence-puzzle-module-init]] .Puzzle module initialization sequence diagram +image::img/sequence-puzzle-module-init.svg[] (Activated lifeline indicates the module is no longer in 'uninitialized' state) +[[sec:main-bridge]] ==== Bridge The bridge is used to remotely access and control the puzzle box. The Raspberry Pi 3B+ used as main controller during the 21-22 run of the -project set up a Wi-Fi Mesh network [3] to communicate with the puzzle box. -This year's main controller (Raspberry Pi Pico W [1]) uses a standard -802.11b/g/n access point instead (R#137). +project set up a Wi-Fi Mesh network cite:[2122_design] to communicate with the +puzzle box. This year's main controller (Raspberry Pi Pico W cite:[research]) +uses a standard 802.11b/g/n access point instead (<>). On this network, the main controller hosts a server that serves TCP socket connections. These sockets directly forward all internal messages sent to the main controller bidirectionally (i.e. on behalf of the main controller). -Detailed specifications on the TCP socket server are in §4.1. +Detailed specifications on the TCP socket server are in +<>. ==== Operating System -The research document [1] contains a detailed comparison of various operating -systems that are suitable to realize the functionality described in this -section. After this comparison, the decision was made to utilize FreeRTOS as -the operating system on the Rasberry Pi Pico W. +The research document cite:[research] contains a detailed comparison of various +operating systems that are suitable to realize the functionality described in +this section. After this comparison, the decision was made to utilize FreeRTOS +as the operating system on the Rasberry Pi Pico W. +[[sec:lv2-bus]] === Puzzle Bus This section describes the addresses and communication protocol used on the puzzle bus. These specifications only apply to messages sent internally in the -puzzle box, as messages forwarded by the bridge (see §3.2.3) are sent on behalf -of the main controller. +puzzle box, as messages forwarded by the bridge (see <>) are +sent on behalf of the main controller. ==== Addresses The I^2^C addresses remain mostly unchanged from the 20-21 group's -implementation [4]. Addresses that were modified since the 20-21 implementation -are marked with an asterisk. Table 1 lists these addresses for reference. These -addresses are also used to identify specific puzzle modules. +implementation cite:[2021_design]. Addresses that were modified since the 20-21 +implementation are marked with an asterisk. Table 1 lists these addresses for +reference. These addresses are also used to identify specific puzzle modules. .I^2^C address reference [%autowidth] @@ -363,13 +398,13 @@ Property 0x00 stores a module's global state The messages described in Table 2 are (de)serialized using Google's protocol buffer library. This choice was made after considering various alternative -options for sending structured messages [1]. +options for sending structured messages cite:[research]. -Figure 8 shows an example of how messages are exchanged for the initialization -of a puzzle module. +<> shows an example of how messages are +exchanged for the initialization of a puzzle module. -Figure 9 shows an example exchange where the last puzzle module (A) is solved -while (B) is already solved. +<> shows an example exchange where the last puzzle +module (A) is solved while (B) is already solved. . First, module A sets it's own state to 'solved' and subsequently informs the main controller of this change. @@ -385,7 +420,9 @@ while (B) is already solved. In this example, module B could be the vault puzzle module, which displays a code when the entire puzzle box is solved. +[[fig:sequence-puzzle-finish]] .Puzzle box finish sequence diagram +image::img/sequence-puzzle-finish.svg[] === NeoTrellis Puzzle @@ -408,9 +445,11 @@ Appendix B. The inputs and outputs of this puzzle have been taken from the design document of the previous group which worked on this project (??). This input and output -diagram has been shown in Figure 10. +diagram has been shown in <>. +[[fig:neotrellis-io]] .NeoTrellis puzzle in-out +image::img/neotrellis-io.png[] === Software Puzzle @@ -419,6 +458,7 @@ summary of how the puzzle is meant to be solved. This module will be created to facilitate the software puzzle game logic and communication with the main controller about the software puzzle state. +[[sec:software-gameplay]] ==== Software puzzle gameplay The software puzzle consists of 12 input ports which can be connected using a @@ -443,11 +483,13 @@ binary code using 16 LEDs above the puzzle, and to continue to the next puzzle. ==== Puzzle inputs & outputs -As stated in §3.5.1 the puzzle has 12 inputs, as well as an LED which shows -whether the puzzle has been solved and 16 LEDs showing a binary code. This is -shown in Figure 11. +As stated in <> the puzzle has 12 inputs, as well as an +LED which shows whether the puzzle has been solved and 16 LEDs showing a binary +code. This is shown in <>. +[[fig:software-io]] .Software puzzle in-out +image::img/software-io.png[] === Hardware Puzzle @@ -482,7 +524,9 @@ clicked the vault resets and they need to start over from the beginning. ==== Puzzle inputs & outputs +[[fig:vault-io]] .Vault puzzle in-out +image::img/vault-io.png[] === Bomb device @@ -499,9 +543,12 @@ The bomb can also use the WiFi connection to sync. the time. ==== Device inputs & outputs +[[fig:bomb-io]] .Bomb device in-out +image::img/bomb-io.png[] == Components +[[sec:lv3-remote-control]] === Remote Control ==== Socket Server ==== Socket Commands diff --git a/docs/img/bomb-io.png b/docs/img/bomb-io.png new file mode 100644 index 0000000..20d33da Binary files /dev/null and b/docs/img/bomb-io.png differ diff --git a/docs/img/hardware-io.png b/docs/img/hardware-io.png new file mode 100644 index 0000000..54bf1d7 Binary files /dev/null and b/docs/img/hardware-io.png differ diff --git a/docs/img/neotrellis-io.png b/docs/img/neotrellis-io.png new file mode 100644 index 0000000..5f28562 Binary files /dev/null and b/docs/img/neotrellis-io.png differ diff --git a/docs/img/software-io.png b/docs/img/software-io.png new file mode 100644 index 0000000..4915315 Binary files /dev/null and b/docs/img/software-io.png differ diff --git a/docs/img/vault-io.png b/docs/img/vault-io.png new file mode 100644 index 0000000..b76da9f Binary files /dev/null and b/docs/img/vault-io.png differ diff --git a/docs/readme.md b/docs/readme.md index 32814dc..2810343 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -28,8 +28,20 @@ makefile is provided for convenience. - [x] requirements - [x] figures - [x] citations +- [ ] table of tables +- [ ] table of figures - [ ] glossary (w/ cross-references) - [ ] PDF style +- [ ] give used requirements more meaningful id's + +## for later reference + +### get citation keys from .docx file + +``` +$ unar file.docx +$ grep -o 'CITATION[^<]\+' file/word/document.xml | awk '!x[$2]++ { i++; print "[" i "] " $2 }' +``` [rubydl]: https://www.ruby-lang.org/en/documentation/installation/ [asciidoc]: https://asciidoc.org/ -- cgit v1.2.3