From 7dd019030560ad38fe4b93954a3a359ac5e43613 Mon Sep 17 00:00:00 2001 From: lonkaars Date: Fri, 12 Apr 2024 15:08:14 +0200 Subject: generate bad looking pdfs w/ makefile --- docs/theme.yml | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 docs/theme.yml (limited to 'docs/theme.yml') diff --git a/docs/theme.yml b/docs/theme.yml new file mode 100644 index 0000000..0ca5d6b --- /dev/null +++ b/docs/theme.yml @@ -0,0 +1,62 @@ +# extends: default + +page: + size: a4 + margin: [1in, 1in, 1in, 1in] + numbering: + start-at: toc + +base: + hyphens: true + text-align: justify + +prose: + margin-bottom: 3mm + +# font: +# catalog: +# serif: +# bold: texgyreschola-bold.otf +# bold_italic: texgyreschola-bolditalic.otf +# italic: texgyreschola-italic.otf +# normal: texgyreschola-regular.otf +# sans_serif: +# bold: Inter-Bold.otf +# bold_italic: Inter-BoldItalic.otf +# italic: Inter-Italic.otf +# normal: Inter-Regular.otf +# monospace: +# bold: JetBrainsMono-Bold.ttf +# bold_italic: JetBrainsMono-BoldItalic.ttf +# italic: JetBrainsMono-Italic.ttf +# normal: JetBrainsMono-Regular.ttf + +base: + # font-family: serif + font-size: 10.5 + +title-page: + align: center + title: + margin-top: 1cm + font-size: 18 + font-style: bold + subtitle: + margin-bottom: 1cm + font-size: 16 + authors: + margin-bottom: 1cm + +heading: + align: left + margin-top: 15pt + margin-bottom: 5pt + font-style: bold + h2-font-size: $base-font-size * 1.7 + h3-font-size: $base-font-size * 1.4 + h4-font-size: $base-font-size * 1.2 + h5-font-size: $base-font-size + +toc: + indent: 5mm + line-height: 1.4 -- cgit v1.2.3 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/figs.drawio | 904 +++++ 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 + docs/plan.adoc | 50 +- docs/readme.md | 23 + docs/share/meta.adoc | 11 +- docs/theme.yml | 12 + 23 files changed, 6566 insertions(+), 22 deletions(-) create mode 100644 docs/figs.drawio 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 create mode 100644 docs/readme.md (limited to 'docs/theme.yml') diff --git a/docs/figs.drawio b/docs/figs.drawio new file mode 100644 index 0000000..a40503b --- /dev/null +++ b/docs/figs.drawio @@ -0,0 +1,904 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 diff --git a/docs/plan.adoc b/docs/plan.adoc index b69c7bc..778506a 100644 --- a/docs/plan.adoc +++ b/docs/plan.adoc @@ -69,7 +69,7 @@ that are actually in constant motion. The advantage of this is that it is actually always clear who is working on which task and which tasks still need to be done. This does require each project member to keep track of their tasks on the kanban board, to ensure efficiency and discipline while the project is -ongoing. The tools to enforce this are shown in §7.3. +ongoing. The tools to enforce this are shown in <>. === Project goal @@ -123,10 +123,12 @@ state. Multiple tests will be created to safeguard the quality of the project. Code and document reviews are also used to safeguard quality. More about this can be -found in §6.2. +found in <>. +[[sec:phasing]] == Project phases +[[sec:phase-research]] === Research phase This project consists of several research topics which are stated below. @@ -158,6 +160,7 @@ the conclusion of the research document for the following components: - Communiction (with the bomb) - Power supply +[[sec:phase-development]] === Development phase The development phase is used to develop a product, or a predetermined part of @@ -192,6 +195,7 @@ executed parallel to the development of the four sides. The development of the sides will also mostly be parallel with just a small delay creating an overlap between the sides. +[[sec:phase-qualification]] === Qualification The last phase is the phase where everything needs to be tested and verified to @@ -236,6 +240,7 @@ below. | LxL | Low |=== +[[sec:control-quality]] === Quality control This project just as any other project need to meet a certain level of quality @@ -305,9 +310,10 @@ communication with the stakeholders. === Communication -Table 3 lists the stakeholders which receive regular updates about the project. -These people are informed about the current progress and are involved in any -meetings where requirements and/or specifications are discussed. +<> lists the stakeholders which receive regular updates +about the project. These people are informed about the current progress and +are involved in any meetings where requirements and/or specifications are +discussed. [[tab:stakeholders]] .Project communication table @@ -319,6 +325,7 @@ meetings where requirements and/or specifications are discussed. |Jonathan Overes|Client|School email; Teams|Weekly |=== +[[sec:version-management]] === Version management All source code developed during this project is kept under version control @@ -351,23 +358,28 @@ been reviewed. At the request of the stakeholders, time spent working on the project is tracked by each team member using Clockify [8]. -Figure 1 shows a Gantt-chart including the phases from section 5. The -milestones are indicated with vertical dashed lines and are marked with week -numbers. +[[fig:planning-condensed]] +.Condensed Gantt planning +image::img/planning-condensed.svg[] -The research phase (§5.1) includes the planning and writing of the initial -draft versions of all the project documents. The documentation is also -continuously updated during the development phase, but this is not shown in -Figure 1. +<> shows a Gantt-chart including the phases from +<>. The milestones are indicated with vertical dashed lines and +are marked with week numbers. -The development phase (§5.2) consists of the continuous development of the main -(central) controller software and various accompanying tests. During this -phase, the software for each puzzle box side is developed in parallel. Each -side’s software development is staggered to avoid the accumulation of tasks. +The research phase (<>) includes the planning and writing +of the initial draft versions of all the project documents. The documentation +is also continuously updated during the development phase, but this is not +shown in <>. -The qualification phase (§5.3) consists of validating the results of the -development phase, fixing issues when they are discovered, and finalizing all -project documentation. +The development phase (<>) consists of the continuous +development of the main (central) controller software and various accompanying +tests. During this phase, the software for each puzzle box side is developed in +parallel. Each side’s software development is staggered to avoid the +accumulation of tasks. + +The qualification phase (<>) consists of validating +the results of the development phase, fixing issues when they are discovered, +and finalizing all project documentation. include::share/glossary.adoc[] diff --git a/docs/readme.md b/docs/readme.md new file mode 100644 index 0000000..262cac1 --- /dev/null +++ b/docs/readme.md @@ -0,0 +1,23 @@ +# docs + +This folder contains the project documentation in [asciidoc][asciidoc] format. +A makefile is provided for easily compiling these documents into PDFs for +submission. + +## TODO + +- transfer documents + - [ ] project plan + - [ ] requirements + - [ ] research + - [ ] software design +- xrefs for-- + - [x] tables + - [x] figures + - [x] section numbers (headings) + - [ ] requirements +- [x] figures +- [ ] citations +- [ ] glossary +- [ ] PDF style + diff --git a/docs/share/meta.adoc b/docs/share/meta.adoc index ad99228..2e54c18 100644 --- a/docs/share/meta.adoc +++ b/docs/share/meta.adoc @@ -3,6 +3,11 @@ :toc: :toclevels: 4 :pagenums: -Thomas in ‘t Anker; Loek Le Blansch; Lars Faase; Elwin Hammer -0.0, 2024-04-01 - +:revnumber: 0.0 +:revdate: 2024-04-01 +:revremark: draft +:author_1: Thomas in ‘t Anker +:author_2: Loek Le Blansch +:author_3: Lars Faase +:author_4: Elwin Hammer +:xrefstyle: short diff --git a/docs/theme.yml b/docs/theme.yml index 0ca5d6b..824c74b 100644 --- a/docs/theme.yml +++ b/docs/theme.yml @@ -60,3 +60,15 @@ heading: toc: indent: 5mm line-height: 1.4 + +caption: + align: center + end: bottom + +table: + caption: + end: $caption-end + +list: + indent: 10mm + -- 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/theme.yml') 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 acea0828b8638764fa698aae54ba403912354bb8 Mon Sep 17 00:00:00 2001 From: lonkaars Date: Mon, 22 Apr 2024 16:53:05 +0200 Subject: clean up documents --- docs/.bundle/config | 2 ++ docs/Gemfile | 2 ++ docs/makefile | 1 + docs/readme.md | 6 +++--- docs/share/meta.adoc | 10 ++++++++++ docs/theme.yml | 49 ++++++++++++++++++++++++++++++++++++------------- 6 files changed, 54 insertions(+), 16 deletions(-) create mode 100644 docs/.bundle/config (limited to 'docs/theme.yml') diff --git a/docs/.bundle/config b/docs/.bundle/config new file mode 100644 index 0000000..92d0e5f --- /dev/null +++ b/docs/.bundle/config @@ -0,0 +1,2 @@ +--- +BUNDLE_PATH: "res/bundle" diff --git a/docs/Gemfile b/docs/Gemfile index 99f5ca1..efd0f36 100644 --- a/docs/Gemfile +++ b/docs/Gemfile @@ -8,4 +8,6 @@ gem 'asciidoctor-pdf', '~> 2.3' gem 'asciidoctor-bibtex', '~> 0.8.0' # gem 'asciidoctor-interdoc-reftext', '~> 0.5.2' gem 'asciidoctor-interdoc-reftext', git: 'https://github.com/lonkaars/asciidoctor-interdoc-reftext' +gem 'asciidoctor-lists', '~> 1.0' +gem 'text-hyphen', '~> 1.5' diff --git a/docs/makefile b/docs/makefile index 1fbb5b4..452eddf 100644 --- a/docs/makefile +++ b/docs/makefile @@ -15,6 +15,7 @@ ASCIIDOCTOR_ARGS += --require asciidoctor-bibtex ASCIIDOCTOR_ARGS += --require asciidoctor-pdf # ASCIIDOCTOR_ARGS += --require ./plugin/helloworld ASCIIDOCTOR_ARGS += --require asciidoctor-interdoc-reftext +ASCIIDOCTOR_ARGS += --require asciidoctor-lists ASCIIDOCTOR_ARGS += --backend pdf %.pdf: %.adoc $(PDFDEPS) bundle exec asciidoctor $(ASCIIDOCTOR_ARGS) $< diff --git a/docs/readme.md b/docs/readme.md index 2810343..215df50 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -28,10 +28,10 @@ makefile is provided for convenience. - [x] requirements - [x] figures - [x] citations -- [ ] table of tables -- [ ] table of figures +- [x] table of tables +- [x] table of figures - [ ] glossary (w/ cross-references) -- [ ] PDF style +- [x] PDF style - [ ] give used requirements more meaningful id's ## for later reference diff --git a/docs/share/meta.adoc b/docs/share/meta.adoc index 15d8d18..2e15b79 100644 --- a/docs/share/meta.adoc +++ b/docs/share/meta.adoc @@ -29,5 +29,15 @@ endif::[] // followed by a table of contents :toc: +[discrete] +== List of Figures +list-of::image[] + +[discrete] +== List of Tables +list-of::table[] + +<<< + // also https://docs.asciidoctor.org/asciidoc/latest/attributes/document-attributes-ref diff --git a/docs/theme.yml b/docs/theme.yml index 1537f50..5844a86 100644 --- a/docs/theme.yml +++ b/docs/theme.yml @@ -9,6 +9,7 @@ page: base: hyphens: true text-align: justify + font-size: 10.5 prose: margin-bottom: 3mm @@ -17,24 +18,20 @@ prose: # catalog: # serif: # bold: texgyreschola-bold.otf -# bold_italic: texgyreschola-bolditalic.otf +# bold-italic: texgyreschola-bolditalic.otf # italic: texgyreschola-italic.otf # normal: texgyreschola-regular.otf -# sans_serif: +# sans-serif: # bold: Inter-Bold.otf -# bold_italic: Inter-BoldItalic.otf +# bold-italic: Inter-BoldItalic.otf # italic: Inter-Italic.otf # normal: Inter-Regular.otf # monospace: # bold: JetBrainsMono-Bold.ttf -# bold_italic: JetBrainsMono-BoldItalic.ttf +# bold-italic: JetBrainsMono-BoldItalic.ttf # italic: JetBrainsMono-Italic.ttf # normal: JetBrainsMono-Regular.ttf -base: - # font-family: serif - font-size: 10.5 - title-page: align: center title: @@ -65,13 +62,39 @@ caption: align: center end: bottom -example: - caption: - end: $caption-end +image: + align: center + +list: + indent: 10mm + +description-list: + term-font-style: bold + table: + align: center + border-color: transparent + cell-padding: [0.2pt, 2pt] + border-color: '#000000' + border-width: [ 0.5pt, 0pt, 0.5pt, 0pt ] + head: + font-style: bold + border-bottom-width: 1pt + cell: + border-width: 0pt caption: end: $caption-end -list: - indent: 10mm +footnotes: + font-size: round($base-font-size * 0.75) + +footer: + height: 1in + vertical-align: middle + recto: + center: + content: '{page-number}' + verso: + center: + content: '{page-number}' -- cgit v1.2.3 From dd8379e545b4beb6611a8152bca87e9276dde797 Mon Sep 17 00:00:00 2001 From: lonkaars Date: Mon, 22 Apr 2024 17:07:44 +0200 Subject: finish TODOs --- docs/design.adoc | 23 ++++++++++++----------- docs/readme.md | 24 +++--------------------- docs/reqs.adoc | 24 ++++++++++++------------ docs/research.adoc | 36 ++++++++++++++++++------------------ docs/theme.yml | 2 +- 5 files changed, 46 insertions(+), 63 deletions(-) (limited to 'docs/theme.yml') diff --git a/docs/design.adoc b/docs/design.adoc index 533c02a..5ebbb15 100644 --- a/docs/design.adoc +++ b/docs/design.adoc @@ -175,11 +175,11 @@ 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 -(<>). 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 @@ -216,11 +216,11 @@ 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 - (<>). + (<>). * Simplify the development process and integration of new puzzle modules - (<>). + (<>). * Provide abstracted interfaces to allow for easy integration of the puzzle box - as part of a larger whole (<>). + as part of a larger whole (<>). [[sec:framework-state]] ==== State @@ -230,8 +230,8 @@ All puzzle modules implement the same state machine shown in 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 (<>). +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 <>). The state transition @@ -332,7 +332,8 @@ 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 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 (<>). +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 diff --git a/docs/readme.md b/docs/readme.md index 215df50..99cbb24 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -12,27 +12,9 @@ makefile is provided for convenience. - please give cross references, links, image files, figure ids, etc. meaningful names -## TODO - -- transfer documents - - [x] project plan - - [x] requirements - - [x] research - - [ ] footnotes - - [ ] software design - - [ ] footnotes -- xrefs for-- - - [x] tables - - [x] figures - - [x] section numbers (headings) - - [x] requirements -- [x] figures -- [x] citations -- [x] table of tables -- [x] table of figures -- [ ] glossary (w/ cross-references) -- [x] PDF style -- [ ] give used requirements more meaningful id's +## todo (low priority) + +- cross-references to glossary ## for later reference diff --git a/docs/reqs.adoc b/docs/reqs.adoc index edddbdd..8ad24a8 100644 --- a/docs/reqs.adoc +++ b/docs/reqs.adoc @@ -211,11 +211,11 @@ describes all functional requirements of the puzzle box. | <> | <> | [[req:27,R-027]] The puzzles should be easy enough to solve without any prior knowledge of the game or its mechanics. -| <> | <> | -[[req:167,R-167]] A puzzle module can manually be reset at the discretion of the game operator +| <> | <> | +[[req:edge-manual-reset,R-167]] A puzzle module can manually be reset at the discretion of the game operator -| <> | <> | -[[req:168,R-168]] A puzzle module can manually be set as solved at the discretion of the game operator +| <> | <> | +[[req:edge-skip-puzzle,R-168]] A puzzle module can manually be set as solved at the discretion of the game operator | <> | <> | [[req:28,R-028]] The disarm code for the bomb consists of 4 digits. @@ -451,8 +451,8 @@ documentation. Due to time constraints, the section will be left empty. |=== | ID | <> | Specification -| <> | <> | -[[req:89,R-089]] The puzzle box is powered by a rechargeable battery. +| <> | <> | +[[req:pwr-battery,R-089]] The puzzle box is powered by a rechargeable battery. | <> | <> | [[req:90,R-090]] The battery lasts for a minimum of 4 hours. @@ -481,17 +481,17 @@ documentation. Due to time constraints, the section will be left empty. |=== | ID | <> | Specification -| <> | <> | -[[req:130,R-130]] The main controller and its software do not need to be modified to implement a new puzzle module +| <> | <> | +[[req:main-static,R-130]] The main controller and its software do not need to be modified to implement a new puzzle module | <> | <> | [[req:131,R-131]] Puzzle modules can be added and removed while the main controller is powered on -| <> | <> | -[[req:132,R-132]] Puzzle modules can be added and removed while the main controller is powered off +| <> | <> | +[[req:pm-swap,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 +| <> | <> | +[[req:main-interface,R-133]] The puzzle box provides a single external interface for accessing and controlling game state variables |=== === Puzzle box hub diff --git a/docs/research.adoc b/docs/research.adoc index 5d4f381..a6ef255 100644 --- a/docs/research.adoc +++ b/docs/research.adoc @@ -133,8 +133,8 @@ as main controller unit: * Is available as a development kit from Farnell (<>). -<> lists the considered MCU options matching the above criteria. This -list is a compilation of microcontroller offerings from the following +<> 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 @@ -143,7 +143,7 @@ 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]] +[[tab:main-mcu]] .Main controller MCU candidates [%autowidth] |=== @@ -151,7 +151,7 @@ The Raspberry Pi Pico W board is utilized during development. | WFI32E01PC | 1 | 256 KB | 1 MB | 200 MHz | ESP8266 | 1 | 50 KB | 16 MB | 160 MHz -| RP2040 | 2 | 264 KB | 2 MB | 133 MHz +| RP2040 | 2 | 264 KB | 2 MB | 133 MHz{empty}footnote:[Adjusting the clock speed for the main controller is not necessary, even though the RP2040 supports clock speed configuration (see <>)] |=== === Puzzle module controller @@ -167,12 +167,12 @@ for controlling the puzzle modules: (<>). * Has a configurable clock speed (<>). -<> lists the considered MCU options matching the above criteria. This -list is a compilation of microcontroller offerings from the following +<> 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 +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 @@ -187,7 +187,7 @@ 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]] +[[tab:pm-mcu]] .Puzzle module controller MCU candidates [%autowidth] |=== @@ -255,10 +255,10 @@ distributions of Debian are, so this OS is be considered familiar. === Conclusions -<> summarizes the considered operating systems based on the criteria -outlined at the start of this section. +<> summarizes the considered operating systems based on the +criteria outlined at the start of this section. -[[tab:3]] +[[tab:main-os]] .Main controller OS comparison [%autowidth] |=== @@ -279,13 +279,13 @@ 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. +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]] +[[tab:test-framework]] .General testing framework comparison cite:[Ali24,Joh21] [%autowidth] |=== diff --git a/docs/theme.yml b/docs/theme.yml index 5844a86..b26ad75 100644 --- a/docs/theme.yml +++ b/docs/theme.yml @@ -74,7 +74,7 @@ description-list: table: align: center border-color: transparent - cell-padding: [0.2pt, 2pt] + cell-padding: [0.2pt, 5pt] border-color: '#000000' border-width: [ 0.5pt, 0pt, 0.5pt, 0pt ] head: -- cgit v1.2.3