From e5de3732057827a6e2194b967e3a419591bcea34 Mon Sep 17 00:00:00 2001 From: lonkaars Date: Thu, 11 Apr 2024 11:34:08 +0200 Subject: WIP docs --- docs/plan.adoc | 376 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 376 insertions(+) create mode 100644 docs/plan.adoc (limited to 'docs/plan.adoc') diff --git a/docs/plan.adoc b/docs/plan.adoc new file mode 100644 index 0000000..70db19d --- /dev/null +++ b/docs/plan.adoc @@ -0,0 +1,376 @@ += Puzzle Box Project Plan +include::share/meta.adoc[] + +== Table of Contents +:toc: + +== Introduction + +This document has been written by students following the computer science +curriculum at Avans University of Applied Sciences in Den Bosch. The purpose of +this document is to plan out the puzzle box project, in which realistic goals +will be established. Key points of this document include the way this project +is going to be developed, the expected outcome, and project management. +Throughout the semester project, this approach ensures process control and +provides a clear overview of activities and the work organization. + +== Background information + +This section gives the reader background information as to why the project is +necessary. + +=== Project + +During the introductory week, students participate in a competition task on +Monday afternoon. The goal is for teams to perform tasks related to electrical +engineering and computer science programs. The competitive element and +interaction with other groups are crucial. For the 19-20 introduction, the bomb +task was created, inspired by the game "Keep Talking and Nobody Explodes." A +description of the game can be found on the website [1]. + +Originally, the plan was to create a bomb that needs to be defused and a puzzle +box generating codes for defusing the bomb. A previous group successfully +developed a bomb requiring software and hardware creation by intro students, +followed by entering defusing codes. This system includes an RPI connecting to +the internet for bomb countdown time synchronization and remote control. +Additionally, a configuration program for PCs allows the bomb to be set to +countdown at a specific time. The bomb's hardware is ready, but a puzzle box +could still be created. + +This puzzle box would generate codes to be entered on the bomb for defusing. +The bomb's software can be expanded for collaboration with puzzle boxes or +other additional features. Several puzzles for the puzzle box were developed in +the 20-21 academic year and improved upon in 21-22. A design for the box's +appearance has been created, along with software and a web-based user interface +for accessing a mesh network set up by the boxes. + +== Project definition + +This section describes the different aspect of the project, including the +analysis of the project, the approach to completing the project, and the goal +of the project. + +=== Problem analysis + +Currently, the idea of defusing a bomb has been realized and is being used in +the introductory weeks at Avans. However, a puzzle box has yet to be realized. + +Several puzzles were already developed in the 20-21 academic year and improved +upon in the 21-22 academic year. A design for the box's appearance has been +created, along with the software and web-based user interface for accessing a +mesh network which is set up by the boxes. + +The puzzle box hardware and software need to transition from prototype status +to a final product, including the integration with the bombs. The hardware is +not complete for all puzzles, as these have been redesigned in the 22-23 +academic year. + +=== Project approach + +During this project, kanban is used, in which different tasks are described +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. + +=== Project goal + +The purpose and motivation of this project is to create a puzzle box that +interacts with the existing bomb, which can be used in the introductory week. + +The bomb would have to be defused using codes given by the puzzle box. The +puzzle box would consist of several puzzles for the student to solve. These +puzzles are related to the Smart Hardware and Smart Software study paths. + +The focus of this year's run of the puzzle box project (23-24) is to create a +new software framework from scratch, that allows future students working on +this project to easily integrate new puzzle modules, or port the existing +puzzles to different hardware. Previous iterations of this project were +realized with complicated libraries and/or frameworks, which requires extensive +research for students unfamiliar with them. + +=== Halfway goal + +Due to this project being divided over two periods a halfway goal has been +established. This goal must be reached in week seven of the project. The first +half of this project focuses on researching and designing the final product. As +a result, several documents are created. The documents delivered in this phase +of the project are the following: + +- Project Plan (this document) +- Requirements document +- Research document (1st version) +- Design document (top-level software design) + +=== Project outcome + +The outcome of the project is that the puzzle box software has been brought to +a product-level. Furthermore, a software framework has been implemented, which +uses only software and programming languages native to the curriculum. A +temporary cli-interface has been realized, allowing for management of the game +state. + +=== Project deliverables + +- Project Plan +- Requirements Specification +- Design Specification +- Site acceptance test +- Factory acceptance test +- Qualification Document +- Puzzle box games/interface +- Handover plan + +=== Product quality + +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. + +== Project phases + +=== Research phase + +This project consists of several research topics which are stated below. + +Investigating the already existing code/software that has been written by +previous project members to determine if the code/software could be +reused/ported to another controller or software language. + +Another vital research topic to explore is the unit testing framework. By +investigating different unit testing frameworks, project teams can identify the +most suitable one for their specific needs, enabling them to maintain code +quality, detect bugs early, and facilitate smoother integration processes. That +means that for this project a new, robust, and future proof unit testing +framework needs to be chosen since there is none now. + +Lastly, researching the controller, there is already a controller picked for a +prototype version of the puzzle box for this project, but it is unclear which +controller it is and if it is still a good option to continue using since the +puzzle box itself uses a Raspberry Pi, but the puzzle box consists out of +several puzzle modules which each must have their own controller. The raspberry +Pi for the box itself should be fine but for now it is unclear what is used for +the modules and what is the best option to move forward. + +A design document will be set-up in where the decisions will be made based on +the conclusion of the research document for the following components: + +- Puzzle modules (four sides) +- Main controller +- Communiction (with the bomb) +- Power supply + +=== Development phase + +The development phase is used to develop a product, or a predetermined part of +the product based on the research done in the previous phase and agreements +made with the customer. + +This project and thus this phase will be executed using the well-known +KANBAN-method to not only bring more structure and an overview of the product +development but also to make sure that everything is according to the plan and +the customer is satisfied. This means that there will be regularly meetings +with the customer to verify that the requirements are met as expected by the +customer. + +The development will be done using Visual Studio Code in combination with +several add-ons, if necessary, together with GitHub (GIT) for version +management. GitHub will also be used to manage project related tasks so that +all the tasks and issues can be tracked. + +The software will be created according to the tasks planned in GitHub projects. +Each piece of software needs to be tested using a testing framework. + +The development will exist out of five main tasks which are: + +- Main controller +- Side 1 +- Side 2 +- Side 3 +- Side 4 + +The main controller's development will take up the most time thus will be +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. + +=== Qualification + +The last phase is the phase where everything needs to be tested and verified to +the agreed upon specifications. This will also be done using the KANBAN-method +as discussed in the previous chapter. + +Testing of the code will be done using a unit testing framework to test +individual components, later manual testing is needed to test the complete +system which will be documented in a FAT. The customer will also be able to +test and verify the results during this phase to make sure that everything was +executed according to the plan. + +Lastly, a document needs to be made with a recap of everything of this project, +from research, decisions that have been made to verify progress and a +conclusion with tips to continue this project so that the next project group +can continue this project. + +Also all the other documents will need to be finalized and double checked, +especially the design document since it will function as a 'blueprint' of the +project. + +== Project control + +=== Risk management + +What the possible risks are, and how they are managed, can be seen in the table +below. + +.Risk management calculations +[cols="2,1"] +|=== +| General risk calculation (Chance x Impact) | Outcome + +| HxH | High +| HxA | High +| HxL | Average +| AxH | High +| AxA | Average +| AxL | Low +| LxH | Average +| LxA | Low +| LxL | Low +|=== + +=== Quality control + +This project just as any other project need to meet a certain level of quality +and this quality needs to be controlled or better said verified/management. + +The level of quality must be defined within each task so that it is easier to +verify, this also why tasks should be created as SMART tasks. After that the +quality can be verified by someone else on the project and/or the customer +using the definition within the task. + +The quality of the project itself should be defined within a separate so called +qualification document. A qualification document for a technical project serves +as a crucial piece of information that outlines the necessary qualifications +and criteria for individuals or teams involved in the project. + +This document typically includes details such as the required technical skills, +educational background, work experience, certifications, and any other specific +requirements needed to successfully contribute to the project. By clearly +defining the qualifications needed, this document helps ensure that the right +individuals are selected for the project, leading to its successful completion. + +=== Project scope + +The aim of this project is to create a puzzle box with 4 different puzzles +representing the different directions in this study. Examining the existing +hardware designs is an important task to get a good idea of their status. The +existing hardware designs from previous groups will be used as a reference to +develop the software on. The software will enable interaction between the user +and the puzzle box for solving the different puzzles. + +So, the task in this project is to develop this software using the given +hardware designs. If certain parts of this hardware don’t work, this should be +described in the handover document so that the next hardware student can work +on it. + +It was decided to focus only on the puzzle box itself because this project +requires a lot of research to ground out the documents of the previous groups. +So, the loose bomb and web interface are left out of this project and can be +realised later. + +In addition, contact will be kept with the customer to properly incorporate the +requirements into the final product and both parties will not face any +surprises. + +== Parties & Roles + +This section defines the entities involved in this project and describes their +role in the project. + +=== Team members + +<> lists the executive party involved in this project. These +people are responsible for implementation, documentation, testing and +communication with the stakeholders. + +[[tab:members]] +.Team member table +[cols="3*"] +|=== +| Name | Role | Study path + +| Thomas in ‘t Anker | Developer | Software +| Loek Le Blansch | Developer & Project lead | Software +| Lars Faase | Developer | Software +| Elwin Hammer | Developer | Software +|=== + +=== 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. + +[[tab:stakeholders]] +.Project communication table +[cols="2,1,2,1"] +|=== +|Name|Role|Communication tool(s)|Frequency + +|Jasper van den Heuvel|Client|School email; Teams|Weekly +|Jonathan Overes|Client|School email; Teams|Weekly +|=== + +=== Version management + +All source code developed during this project is kept under version control +using the Git [2] version control system and is available online at GitHub [3]. +Each software component has a 3-digit version number following semantic +versioning [4] conventions (major, minor, patch). + +This repository also utilizes Git submodules to track the versions of the +utilized libraries and SDKs. Submodules refer to commits, and can automatically +be initialized and managed using Git, so are not further specified in this +document. + +All project documentation is realized using Microsoft Office products and is +therefore stored in a SharePoint folder [5]. These documents use a simple +2-digit (major, minor) version number system. The documents are published at +the discretion of the authors, with each new version incrementing the minor +version number. Major version number 0 is utilized for the document draft +versions, while 1 is utilized for documents after the project goal is reached. +A copy of all the documents is kept for each officially published version. + +== Planning + +This project utilizes GitHub Projects [6] to manage and allocate tasks to team +members. GitHub Projects supports multiple workflows, but this project only +follows the Kanban [7] workflow. Since the Kanban workflow does not require +sprints, the project is divided into milestones. A milestone is considered +complete once all tasks assigned to it are both marked as ‘complete’ and have +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. + +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. + +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 qualification phase (§5.3) consists of validating the results of the +development phase, fixing issues when they are discovered, and finalizing all +project documentation. + +include::share/glossary.adoc[] + -- cgit v1.2.3 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/.gitignore | 1 + docs/font.mk | 36 ++++++++++++++++++++++++++++++ docs/makefile | 13 +++++++++-- docs/plan.adoc | 5 +---- docs/share/meta.adoc | 11 +++++----- docs/theme.yml | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 116 insertions(+), 12 deletions(-) create mode 100644 docs/font.mk create mode 100644 docs/theme.yml (limited to 'docs/plan.adoc') diff --git a/docs/.gitignore b/docs/.gitignore index a136337..397e45c 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1 +1,2 @@ *.pdf +res diff --git a/docs/font.mk b/docs/font.mk new file mode 100644 index 0000000..8646e0f --- /dev/null +++ b/docs/font.mk @@ -0,0 +1,36 @@ +TEX_GYRE_SCHOLA += res/font/texgyreschola-bold.otf +TEX_GYRE_SCHOLA += res/font/texgyreschola-bolditalic.otf +TEX_GYRE_SCHOLA += res/font/texgyreschola-italic.otf +TEX_GYRE_SCHOLA += res/font/texgyreschola-regular.otf +$(TEX_GYRE_SCHOLA) &: + mkdir -p res/font + curl -sLo- 'https://www.gust.org.pl/projects/e-foundry/tex-gyre/schola/qcs2.005otf.zip' > texgyreschola.zip + unzip -oq texgyreschola.zip -d res/font + rm texgyreschola.zip + +JETBRAINS_MONO += res/font/JetBrainsMono-Bold.ttf +JETBRAINS_MONO += res/font/JetBrainsMono-BoldItalic.ttf +JETBRAINS_MONO += res/font/JetBrainsMono-Italic.ttf +JETBRAINS_MONO += res/font/JetBrainsMono-Regular.ttf +$(JETBRAINS_MONO) &: + mkdir -p res/font + curl -sLo- 'https://download-cdn.jetbrains.com/fonts/JetBrainsMono-2.304.zip' > jetbrainsmono.zip + unzip -oqj jetbrainsmono.zip -x 'fonts/webfonts/*' 'fonts/variable/*' '*/JetBrainsMonoNL-*' 'AUTHORS.txt' 'OFL.txt' -d res/font + rm jetbrainsmono.zip + +INTER += res/font/Inter-Bold.otf +INTER += res/font/Inter-BoldItalic.otf +INTER += res/font/Inter-Italic.otf +INTER += res/font/Inter-Regular.otf +$(INTER) &: + mkdir -p res/font + curl -sLo- 'https://github.com/rsms/inter/releases/download/v4.0/Inter-4.0.zip' > inter.zip + unzip -oqj inter.zip -x 'web/*' 'extras/ttf/*' '*.ttc' '*Variable*.ttf' '*/InterDisplay-*' 'LICENSE.txt' 'help.txt' -d res/font + rm inter.zip + +SANS_SERIF_FONTS := $(INTER) +SERIF_FONTS := $(TEX_GYRE_SCHOLA) +MONOSPACE_FONTS := $(JETBRAINS_MONO) + +ALL_FONTS := $(SANS_SERIF_FONTS) $(SERIF_FONTS) $(MONOSPACE_FONTS) + diff --git a/docs/makefile b/docs/makefile index 4c1d21a..385ed09 100644 --- a/docs/makefile +++ b/docs/makefile @@ -1,4 +1,13 @@ all: plan.pdf -%.pdf: %.adoc - asciidoctor -r asciidoctor-pdf -b pdf $< +include font.mk + +# PDFDEPS += $(ALL_FONTS) +PDFDEPS += ./theme.yml + +ASCIIDOCTOR_ARGS += --backend pdf +ASCIIDOCTOR_ARGS += --attribute pdf-theme=./theme.yml +# ASCIIDOCTOR_ARGS += --attribute pdf-fontsdir=./res/font +%.pdf: %.adoc $(PDFDEPS) + asciidoctor --require asciidoctor-pdf $(ASCIIDOCTOR_ARGS) $< + diff --git a/docs/plan.adoc b/docs/plan.adoc index 70db19d..b69c7bc 100644 --- a/docs/plan.adoc +++ b/docs/plan.adoc @@ -1,9 +1,6 @@ -= Puzzle Box Project Plan += Project Plan: Project Puzzlebox include::share/meta.adoc[] -== Table of Contents -:toc: - == Introduction This document has been written by students following the computer science diff --git a/docs/share/meta.adoc b/docs/share/meta.adoc index 1df62fe..ad99228 100644 --- a/docs/share/meta.adoc +++ b/docs/share/meta.adoc @@ -1,9 +1,8 @@ +:sectnums: +:title-page: +:toc: +:toclevels: 4 +:pagenums: Thomas in ‘t Anker; Loek Le Blansch; Lars Faase; Elwin Hammer 0.0, 2024-04-01 -:doctype: book - -[.metadata] -{authors} -- version {revnumber}, {revdate} - - 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/plan.adoc') 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 a24ebd2dce62255873ec204065262c8743245769 Mon Sep 17 00:00:00 2001 From: lonkaars Date: Sun, 14 Apr 2024 14:43:33 +0200 Subject: fix source management in asciidoc --- docs/.gitignore | 3 + docs/Gemfile | 7 ++ docs/makefile | 7 +- docs/plan.adoc | 37 ++++----- docs/readme.md | 12 ++- docs/share/footer.adoc | 4 + docs/share/references.adoc | 5 ++ docs/share/refs.bib | 191 +++++++++++++++++++++++++++++++++++++++++++++ 8 files changed, 242 insertions(+), 24 deletions(-) create mode 100644 docs/Gemfile create mode 100644 docs/share/footer.adoc create mode 100644 docs/share/references.adoc create mode 100644 docs/share/refs.bib (limited to 'docs/plan.adoc') diff --git a/docs/.gitignore b/docs/.gitignore index 397e45c..a2f45c2 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,2 +1,5 @@ *.pdf res + +# i know this is bad +Gemfile.lock diff --git a/docs/Gemfile b/docs/Gemfile new file mode 100644 index 0000000..67cd54a --- /dev/null +++ b/docs/Gemfile @@ -0,0 +1,7 @@ +ruby '~> 3.0' +source 'https://rubygems.org' + +gem 'asciidoctor', '~> 2.0' +gem 'asciidoctor-pdf', '~> 2.3' +gem 'asciidoctor-bibtex', '~> 0.8.0' + diff --git a/docs/makefile b/docs/makefile index 385ed09..cccc231 100644 --- a/docs/makefile +++ b/docs/makefile @@ -1,13 +1,16 @@ all: plan.pdf -include font.mk +# include font.mk # PDFDEPS += $(ALL_FONTS) PDFDEPS += ./theme.yml +ASCIIDOCTOR_ARGS += --require asciidoctor-bibtex +ASCIIDOCTOR_ARGS += --require asciidoctor-pdf ASCIIDOCTOR_ARGS += --backend pdf ASCIIDOCTOR_ARGS += --attribute pdf-theme=./theme.yml # ASCIIDOCTOR_ARGS += --attribute pdf-fontsdir=./res/font +ASCIIDOCTOR_ARGS += --attribute bibtex-file=./share/refs.bib %.pdf: %.adoc $(PDFDEPS) - asciidoctor --require asciidoctor-pdf $(ASCIIDOCTOR_ARGS) $< + asciidoctor $(ASCIIDOCTOR_ARGS) $< diff --git a/docs/plan.adoc b/docs/plan.adoc index 778506a..63df9a0 100644 --- a/docs/plan.adoc +++ b/docs/plan.adoc @@ -23,7 +23,7 @@ Monday afternoon. The goal is for teams to perform tasks related to electrical engineering and computer science programs. The competitive element and interaction with other groups are crucial. For the 19-20 introduction, the bomb task was created, inspired by the game "Keep Talking and Nobody Explodes." A -description of the game can be found on the website [1]. +description of the game can be found on the website cite:[Kee23]. Originally, the plan was to create a bomb that needs to be defused and a puzzle box generating codes for defusing the bomb. A previous group successfully @@ -329,9 +329,9 @@ discussed. === Version management All source code developed during this project is kept under version control -using the Git [2] version control system and is available online at GitHub [3]. -Each software component has a 3-digit version number following semantic -versioning [4] conventions (major, minor, patch). +using the Git cite:[gitscm] version control system and is available online at +GitHub cite:[gitrepo]. Each software component has a 3-digit version number +following semantic versioning cite:[semver] conventions (major, minor, patch). This repository also utilizes Git submodules to track the versions of the utilized libraries and SDKs. Submodules refer to commits, and can automatically @@ -339,24 +339,25 @@ be initialized and managed using Git, so are not further specified in this document. All project documentation is realized using Microsoft Office products and is -therefore stored in a SharePoint folder [5]. These documents use a simple -2-digit (major, minor) version number system. The documents are published at -the discretion of the authors, with each new version incrementing the minor -version number. Major version number 0 is utilized for the document draft -versions, while 1 is utilized for documents after the project goal is reached. -A copy of all the documents is kept for each officially published version. +therefore stored in a SharePoint folder cite:[sharepoint]. These documents use +a simple 2-digit (major, minor) version number system. The documents are +published at the discretion of the authors, with each new version incrementing +the minor version number. Major version number 0 is utilized for the document +draft versions, while 1 is utilized for documents after the project goal is +reached. A copy of all the documents is kept for each officially published +version. == Planning -This project utilizes GitHub Projects [6] to manage and allocate tasks to team -members. GitHub Projects supports multiple workflows, but this project only -follows the Kanban [7] workflow. Since the Kanban workflow does not require -sprints, the project is divided into milestones. A milestone is considered -complete once all tasks assigned to it are both marked as ‘complete’ and have -been reviewed. +This project utilizes GitHub Projects cite:[githubprojects] to manage and +allocate tasks to team members. GitHub Projects supports multiple workflows, +but this project only follows the Kanban cite:[atlassiankanban] workflow. Since +the Kanban workflow does not require sprints, the project is divided into +milestones. A milestone is considered complete once all tasks assigned to it +are both marked as ‘complete’ and have been reviewed. At the request of the stakeholders, time spent working on the project is -tracked by each team member using Clockify [8]. +tracked by each team member using Clockify cite:[clockify]. [[fig:planning-condensed]] .Condensed Gantt planning @@ -381,5 +382,5 @@ 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[] +include::share/footer.adoc[] diff --git a/docs/readme.md b/docs/readme.md index 262cac1..efcf30d 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -1,8 +1,9 @@ # docs -This folder contains the project documentation in [asciidoc][asciidoc] format. -A makefile is provided for easily compiling these documents into PDFs for -submission. +This folder contains the project documentation in [AsciiDoc][asciidoc] format. +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. ## TODO @@ -17,7 +18,10 @@ submission. - [x] section numbers (headings) - [ ] requirements - [x] figures -- [ ] citations +- [x] citations - [ ] glossary - [ ] PDF style +[rubydl]: https://www.ruby-lang.org/en/documentation/installation/ +[asciidoc]: https://asciidoc.org/ + diff --git a/docs/share/footer.adoc b/docs/share/footer.adoc new file mode 100644 index 0000000..b3edec3 --- /dev/null +++ b/docs/share/footer.adoc @@ -0,0 +1,4 @@ +include::references.adoc[] + +include::glossary.adoc[] + diff --git a/docs/share/references.adoc b/docs/share/references.adoc new file mode 100644 index 0000000..e475900 --- /dev/null +++ b/docs/share/references.adoc @@ -0,0 +1,5 @@ +[references] +== References + +bibliography::[] + diff --git a/docs/share/refs.bib b/docs/share/refs.bib new file mode 100644 index 0000000..f2cb813 --- /dev/null +++ b/docs/share/refs.bib @@ -0,0 +1,191 @@ +@online{githubprojects, + title = {About Projects - GitHub Docs}, + url = {https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects}, + msbib-accessed = {2024-02-15}, + year = {2024}, +} + +@online{clockify, + title = {Clockify - The most popular free time tracker for teams}, + url = {https://clockify.me/}, + msbib-accessed = {2024-02-15}, + year = {2024}, +} + +@online{gitscm, + title = {Git}, + url = {https://git-scm.com/}, + month = feb, + msbib-day = {15}, + year = {2024}, +} + +@online{Kee23, + title = {Keep talking and nobody explodes - defuse a bomb with your friends.}, + url = {https://keeptalkinggame.com/}, + month = oct, + msbib-day = {10}, + year = {2023}, +} + +@online{gitrepo, + author = {Blansch, Loek Le and Hammer, Elwin and Faase, Lars and in 't Anker, Thomas}, + title = {lonkaars/puzzelbox: Avans Hogeschool project Puzzelbox}, + url = {https://github.com/lonkaars/puzzelbox}, + month = feb, + msbib-day = {15}, + year = {2024}, +} + +@online{sharepoint, + author = {Blansch, Loek Le and Hammer, Elwin and Faase, Lars and in 't Anker, Thomas}, + title = {PROJ-PUZZLE}, + url = {https://avans-my.sharepoint.com/:f:/r/personal/tv_intanker_student_avans_nl/Documents/PROJ-PUZZLE?csf=1&web=1&e=wbKFig}, + month = feb, + msbib-day = {15}, + year = {2024}, +} + +@online{semver, + author = {Preston-Werner, Tom}, + title = {Semantic Versioning 2.0.0}, + url = {https://semver.org/}, + month = jun, + msbib-day = {6}, + year = {2023}, +} + +@online{atlassiankanban, + author = {Radigan, Dan}, + title = {Kanban - A brief introduction}, + url = {https://www.atlassian.com/agile/kanban}, + msbib-accessed = {2024-02-15}, + year = {2024}, +} + +@techreport{Bek23, + author = {Bekema, Frank and Gense, Jasper}, + title = {Programma van Eisen Puzzel box}, + year = {2023}, +} + +@techreport{styleguide, + author = {Blansch, Loek Le and Hammer, Elwin and Faase, Lars and in 't Anker, Thomas}, + title = {Style guide}, + location = {'s-Hertogenbosch}, + publisher = {Avans University of Applied Sciences}, + year = {2024}, +} + +@online{Wik22, + author = {Wikipedia-contributors}, + title = {MOSCOW-Methode}, + url = {https://nl.wikipedia.org/wiki/MoSCoW-methode}, + month = apr, + msbib-day = {5}, + year = {2022}, +} + +@online{rpicpu, + url = {https://www.raspberrypi.com/documentation/computers/processors.html}, +} + +@online{Ali24, + title = {A list of open-source C++ libraries}, + url = {https://en.cppreference.com/w/cpp/links/libs}, + msbib-accessed = {2024-02-25}, +} + +@online{Boo24, + url = {https://www.boost.org/doc/libs/1_75_0/libs/test/doc/html/index.html}, + msbib-accessed = {2024-02-28}, +} + +@online{Git24, + title = {GitHub - boostorg/test: The reference C++ unit testing framework (TDD, xUnit, C++03/11/14/17).}, + url = {https://github.com/boostorg/test}, + msbib-accessed = {2024-02-28}, +} + +@online{Neo, + title = {Neotrellis}, + url = {https://learn.adafruit.com/adafruit-neotrellis/overview}, +} + +@techreport{rp2040ds, + title = {RP2040 Datasheet}, + publisher = {Raspberry Pi Ltd}, + year = {2024}, +} + +@online{Cat24, + author = {Catchorg}, + title = {Github - catchorg/Catch2: A modern, C++-native, test framework for unit-tests.}, + msbib-accessed = {2024-02-25}, +} + +@online{Cpp24, + author = {Cpputest}, + title = {Github - cpputest/cpputest: CppUTest unit testing and mocking framework for C/C++.}, + url = {https://github.com/cpputest/cpputest}, + msbib-accessed = {2024-02-25}, +} + +@online{Doc24, + author = {Doctest}, + title = {Github - doctest/doctest: The fastest feature-rich C++11/14/17/20/23 single-header testing framework.}, + url = {https://github.com/doctest/doctest}, + msbib-accessed = {2024-02-25}, +} + +@online{goo24, + author = {google}, + title = {GitHub - google/googletest: GoogleTest - Google Testing and Mocking Framework.}, + url = {https://github.com/google/googletest}, + msbib-accessed = {2024-02-28}, +} + +@online{Joh21, + author = {Johnston, P.}, + title = {Embedded systems testing resources}, + url = {https://embeddedartistry.com/blog/2018/10/18/embedded-systems-testing-resources/}, + month = jun, + msbib-day = {10}, + msbib-accessed = {2024-02-25}, + year = {2021}, +} + +@techreport{research, + author = {Blansch, Loek Le and Hammer, Elwin and Faase, Lars and in 't Anker, Thomas}, + title = {Research Document}, + location = {'s-Hertogenbosch}, + publisher = {Avans University of Applied Sciences}, + year = {2024}, +} + +@techreport{2021_design, + author = {Creemers, Merel and van Wiechen, Joost and Lengowski, Vincent and Maas, Justin}, + title = {Ontwerpdocument}, + language = {dutch}, + location = {'s-Hertogenbosch}, + publisher = {Avans University of Applied Sciences}, + year = {2021}, +} + +@techreport{2122_handover, + author = {van Gastel, Lucas and de Bruin, Julian and Rockx, Toon and van Kuijk, Alex and Baars, Jef}, + title = {Overdrachtsdocument}, + language = {dutch}, + location = {'s-Hertogenbosch}, + publisher = {Avans University of Applied Sciences}, + year = {2022}, +} + +@techreport{2122_design, + author = {van Gastel, Lucas and de Bruin, Julian and Rockx, Toon and van Kuijk, Alex and Baars, Jef}, + title = {Design document}, + language = {dutch}, + location = {'s-Hertogenbosch}, + publisher = {Avans University of Applied Sciences}, + year = {2022}, +} -- 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/plan.adoc') 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 d6eaa7a8a6e4332c473368230e0a0782a737bd39 Mon Sep 17 00:00:00 2001 From: lonkaars Date: Sat, 20 Apr 2024 16:12:22 +0200 Subject: small refactor + create software design document --- docs/design.adoc | 5 + docs/makefile | 6 +- docs/plan.adoc | 2 +- docs/reqs.adoc | 723 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/requirements.adoc | 723 ------------------------------------------------- docs/research.adoc | 24 +- docs/share/meta.adoc | 31 ++- 7 files changed, 766 insertions(+), 748 deletions(-) create mode 100644 docs/design.adoc create mode 100644 docs/reqs.adoc delete mode 100644 docs/requirements.adoc (limited to 'docs/plan.adoc') diff --git a/docs/design.adoc b/docs/design.adoc new file mode 100644 index 0000000..b653633 --- /dev/null +++ b/docs/design.adoc @@ -0,0 +1,5 @@ +:document: Software Design +include::share/meta.adoc[] + + +include::share/footer.adoc[] diff --git a/docs/makefile b/docs/makefile index 496a6e6..1fbb5b4 100644 --- a/docs/makefile +++ b/docs/makefile @@ -1,6 +1,7 @@ all: plan.pdf -all: requirements.pdf +all: reqs.pdf all: research.pdf +all: design.pdf # include font.mk @@ -15,9 +16,6 @@ ASCIIDOCTOR_ARGS += --require asciidoctor-pdf # ASCIIDOCTOR_ARGS += --require ./plugin/helloworld ASCIIDOCTOR_ARGS += --require asciidoctor-interdoc-reftext ASCIIDOCTOR_ARGS += --backend pdf -ASCIIDOCTOR_ARGS += --attribute pdf-theme=./theme.yml -# ASCIIDOCTOR_ARGS += --attribute pdf-fontsdir=./res/font -ASCIIDOCTOR_ARGS += --attribute bibtex-file=./share/refs.bib %.pdf: %.adoc $(PDFDEPS) bundle exec asciidoctor $(ASCIIDOCTOR_ARGS) $< diff --git a/docs/plan.adoc b/docs/plan.adoc index 8825459..e935c86 100644 --- a/docs/plan.adoc +++ b/docs/plan.adoc @@ -1,4 +1,4 @@ -= Project Plan: {project} +:document: Project Plan include::share/meta.adoc[] == Introduction diff --git a/docs/reqs.adoc b/docs/reqs.adoc new file mode 100644 index 0000000..edddbdd --- /dev/null +++ b/docs/reqs.adoc @@ -0,0 +1,723 @@ +:document: Project Requirements +include::share/meta.adoc[] + +== Introduction + +In this document, the specifications are described prior to the investigation +of the Puzzle Box project. These specifications are partly derived from the +previously established requirements and are further supplemented and modified. +The priority of specifications is indicated using the MoSCoW method, see +<>. + +[[tab:moscow]] +.MoSCoW Method cite:[Wik22] +[cols="20h,~"] +|=== +| Priority | Description + +| [[must,M]]<> +| Represents essential system requirements. Without these, the system will not +function. +| [[should,S]]<> +| Denotes desirable system features. The system can work without these, but it +lacks necessary elements. +| [[could,C]]<> +| Refers to additional functionalities that can be implemented if there is +extra time. +| [[wont,W]]<> +| Specifies requirements that will not be implemented in the current version +but may be considered in a future release. +|=== + +This specification document covers hardware, software, and game-specific +details. The focus in this project year for the Puzzle Box is to thoroughly +document the system and create a software framework for future groups. + +== Context + +This chapter describes how the user will interact with the system. This is done +in the form of a user story. This user story covers hardware, software, and +game specifications. From this narrative, many specifications can be derived +for both functional and non-functional requirements +(<> and <>). + +The game administrator picks up the puzzle box and places it on a flat surface. +By using the key switch, the puzzle box is turned on, and the green indicator +LED lights up. Through the mesh network established by the external puzzle box +hub, the corresponding web panel can be accessed. The web panel provides +instructions for configuring the puzzle box, including linking it to any bomb. +The instructions issue a warning if any of the start conditions are not +properly set. If a criterion is incorrectly configured, it is highlighted for +resolution. Additionally, a warning is given if the battery capacity is +insufficient for one game duration, causing the indicator LED on the puzzle box +to turn red. In such cases, the battery should be charged using the USB-C +cable. While the puzzle box is charging, the indicator LED is blue. Once there +are no warnings and the puzzle box is adequately charged, the game can be +started in the web panel. + +The puzzle box begins with the NeoTrellis game. In this game, players must turn +off all LEDs on an 8x8 button LED matrix. When any button is pressed, the +directly adjacent LEDs toggle. If a lit LED is toggled, it turns off; if an +unlit LED is toggled, it turns on. Once all LEDs are turned off, the game is +solved, and the software puzzle begins. + +On the software puzzle, there are 6 banana plug connectors on both the left and +right sides. The ones on the left are labeled with various logical gates, while +the ones on the right are labeled from A to F. Participants in the bomb game +have 6 pieces of C-code written on paper, corresponding to the logical gates on +the puzzle box. The bomb participants must provide a description of the C-code +to the puzzle box participants, allowing them to correctly connect the +appropriate logical gate to the corresponding letter. Once the correct +combination of logical gates with the correct letter is made, the game is +solved. Subsequently, the automation puzzle is initiated. + +Since there is no concept available for the automation puzzle yet, the hardware +puzzle is started directly. + +The hardware puzzle is played in two distinct phases. In Phase 1, the objective +is to solve a combinatorial circuit such that its output becomes '1'. There are +8 inputs for this circuit, each controlled by an on/off switch. Once the +combinatorial circuit evaluates to '1', the LED at the output lights up, +indicating the completion of the first phase. In Phase 2, another LED blinks, +consistently repeating a pattern. This pattern represents a randomly generated +Morse code, corresponding to a number from 0 to 9999. Participants use a Morse +code table to decipher the correct number. Using four potentiometers, the +participants can set a number on a 7-segment display. When this number matches +the randomly generated one, the hardware puzzle is solved. Subsequently, the +vault puzzle is initiated. + +In the vault puzzle, a 7-segment display shows a random combination of a letter +and a digit. Participants have access to a list containing the correct button +combination for the corresponding letter and digit. The vault puzzle consists +of 5 levels, each displaying a unique button combination from the list. When +participants correctly press the button on the keypad, the level advances, and +a new value is shown. Pressing the wrong button restarts the game at level 1. +Once all 5 levels are completed, the vault door unlocks, allowing access to the +inside of the puzzle box. On the mainboard, there is a 7-segment display +showing a code. This code must be relayed to the participants of the bomb game. +Once the bomb team receives the code, the puzzle box is considered solved. + +[[sec:functional]] +== Functional Requirements + +The functional requirements describe the things which are important to the +client. This is mainly about the way the product is going to be used, what it +is going to look like, and how the product reacts to interaction. This chapter +describes all functional requirements of the puzzle box. + +=== The puzzle box + +.Puzzle box specifications +[cols="8h,5h,~"] +|=== +| ID | <> | Specification + +| <> | <> | +[[req:1,R-001]] The dimensions of the puzzle box are 30×30×30cm ± 5% (Length × Width × Height). + +| <> | <> | +[[req:2,R-002]] The puzzle box extends a maximum of 5cm on the sides and the top. + +| <> | <> | +[[req:3,R-003]] The puzzle box is flat at the bottom. + +| <> | <> | +[[req:4,R-004]] The puzzle box has a key switch at the bottom of the NeoTrellis puzzle. + +| <> | <> | +[[req:5,R-005]] The puzzle box has an indicator LED at the bottom of the NeoTrellis puzzle. + +| <> | <> | +[[req:6,R-006]] The indicator LED turns green when the system is on and not charging. + +| <> | <> | +[[req:7,R-007]] The indicator LED turns blue when the battery is charging. + +| <> | <> | +[[req:8,R-008]] The indicator LED turns red when the battery does not have enough capacity for the duration of one game and is not charging. + +| <> | <> | +[[req:9,R-009]] The puzzle box has a USB-C port at the bottom of the NeoTrellis puzzle for battery charging. + +| <> | <> | +[[req:10,R-010]] The puzzle box has a distance sensor at the bottom to detect if it is lifted. + +| <> | <> | +[[req:11,R-011]] The puzzle box main board (PCB on the bottom plate) includes a speaker. + +| <> | <> | +[[req:12,R-012]] When the puzzle box is lifted, the mainboard speaker emits an alarm sound for at least 10 seconds. It stops only when it has been on a table for another 10 seconds (detected by the distance sensor). + +| <> | <> | +[[req:13,R-013]] When the game is completed, the puzzle box produces a victory sound. + +| <> | <> | +[[req:14,R-014]] Pressing the "identify" button on the web panel causes the indicator LED to blink. + +| <> | <> | +[[req:15,R-015]] Pressing the "identify" button on the web panel triggers a sound from the speaker. + +| <> | <> | +// section 3.7 is inside the citation, and does not refer to section 3.7 in this document +[[req:16,R-016]] The game starts once the scheduler time is reached (refer to cite:[Bek23] section 3.7). +|=== + +=== The bomb + +.Bomb specifications +[cols="8h,5h,~"] +|=== +| ID | <> | Specification + +| <> | <> | +[[req:17,R-017]] The bomb includes a 6-digit 7-segment display for showing the remaining playtime. + +| <> | <> | +[[req:18,R-018]] The bomb contains a keypad for entering the disarm code. + +| <> | <> | +[[req:19,R-019]] The 6-digit 7-segment display turns off when no game is in progress. + +| <> | <> | +[[req:20,R-020]] Once the disarm code is entered on the bomb keypad, the game is complete. + +| <> | <> | +[[req:21,R-021]] When the game is finished, the bomb emits a victory sound. + +| <> | <> | +[[req:22,R-022]] The timer on the bomb counts down from 60:00:00 to 00:00:00. + +| <> | <> | +[[req:23,R-023]] Pressing the "identify" button on the web panel causes the indicator LED to blink. + +| <> | <> | +[[req:24,R-024]] Pressing the "identify" button on the web panel triggers a sound from the speaker. + +|=== + +=== The game + +.General game specifications +[cols="8h,5h,~"] +|=== +| ID | <> | Specification + +| <> | <> | +[[req:25,R-025]] The game lasts for 1 hour. + +| <> | <> | +[[req:26,R-026]] The game should be solvable within the given playtime, without the player having prior knowledge of the game or its mechanics. + +| <> | <> | +[[req:27,R-027]] The puzzles should be easy enough to solve without any prior knowledge of the game or its mechanics. + +| <> | <> | +[[req:167,R-167]] A puzzle module can manually be reset at the discretion of the game operator + +| <> | <> | +[[req:168,R-168]] A puzzle module can manually be set as solved at the discretion of the game operator + +| <> | <> | +[[req:28,R-028]] The disarm code for the bomb consists of 4 digits. + +| <> | <> | +[[req:29,R-029]] Once all games are solved, the mainboard PCB displays the disarm code on a red 7-segment 4-digit screen. + +| <> | <> | +[[req:30,R-030]] The puzzle box records the playtime of each game. + +| <> | <> | +[[req:31,R-031]] The puzzle box features 5 playable puzzles. + +| <> | <> | +[[req:32,R-032]] Only one game is active at a time; the other games do not respond to buttons. + +| <> | <> | +[[req:33,R-033]] The game always starts with the NeoTrellis puzzle. +|=== + +==== NeoTrellis puzzle + +.NeoTrellis puzzle requirements +[cols="8h,5h,~"] +|=== +| ID | <> | Specification + +| <> | <> | +[[req:34,R-034]] There is an 8x8 LED matrix where each LED can display different colors. + +| <> | <> | +[[req:35,R-035]] At the start of the puzzle, a pattern is displayed as shown in <>. + +| <> | <> | +[[req:36,R-036]] When a button is pressed, the adjacent LEDs and the pressed LED toggle (If an LED is off, it turns on. If an LED is on, it turns off). + +| <> | <> | +[[req:37,R-037]] All LEDs in the Neotrellis that are turned on are blue. + +| <> | <> | +[[req:38,R-038]] The puzzle is considered solved when all LEDs are turned off, and then the software puzzle starts. +|=== + +==== Software puzzle + +.Software puzzle requirements +[cols="8h,5h,~"] +|=== +| ID | <> | Specification + +| <> | <> | +[[req:39,R-039]] The software puzzle board has 6 banana plug connectors with different logic gates displayed next to them (Refer to <> for a sketch and <> for a banana plug example). + +| <> | <> | +[[req:40,R-040]] The software puzzle board has 6 banana plug connectors labeled with the letters A through F (Refer to <> for a sketch). + +| <> | <> | +[[req:41,R-041]] At the start of the puzzle box game, the preparer must connect all cables in parallel (horizontally) to the connectors. + +| <> | <> | +[[req:42,R-042]] There are C code blocks visible only to the players on the bomb side, corresponding to the letters A through F (Refer to <> for the codes). + +| <> | <> | +[[req:43,R-043]] The combinations of logic gates to letters are always the same. + +| <> | <> | +[[req:44,R-044]] The puzzle is considered solved when the cables from the logic gates match the code blocks (Refer to <> and <> for the combinations). + +| <> | <> | +[[req:45,R-045]] Once the puzzle is solved, the green indicator LED will light up (Refer to <> and <>). + +| <> | <> | +[[req:46,R-046]] After the puzzle is solved, the automation puzzle begins. +|=== + +==== Automation puzzle + +The specific details for this puzzle are not present in the previous +documentation. Due to time constraints, the section will be left empty. + +.Automation puzzle requirements +[cols="8h,5h,~"] +|=== +| ID | <> | Specification + +| <> | <> | +[[req:47,R-047]] After the puzzle is solved, the hardware puzzle begins. +|=== + +==== Hardware puzzle + +.Hardware puzzle requirements +[cols="8h,5h,~"] +|=== +| ID | <> | Specification + +| <> | <> | +[[req:48,R-048]] There are eight switches on the hardware puzzle board. + +| <> | <> | +[[req:49,R-049]] The hardware puzzle board features a diagram of a combinatorial circuit with 8 inputs (linked to the switches) and 1 output (Refer to <> for a sketch). + +| <> | <> | +[[req:50,R-050]] The hardware puzzle board includes a red 7-segment 4-digit display (Refer to <> for a sketch). + +| <> | <> | +[[req:51,R-051]] There are 4 potentiometers on the hardware puzzle board (Refer to <> for a sketch). + +| <> | <> | +[[req:52,R-052]] A blue LED on the hardware puzzle board displays the morse code. + +| <> | <> | +[[req:53,R-053]] A green LED on the hardware puzzle board indicates whether the combinatorial circuit is solved. + +| <> | <> | +[[req:54,R-054]] At the start of the puzzle, the potentiometers are inactive. + +| <> | <> | +[[req:55,R-055]] The 7-segment display is off at the beginning of the puzzle. + +| <> | <> | +[[req:56,R-056]] The LED for the combinatorial puzzle is off initially. + +| <> | <> | +[[req:57,R-057]] The morse code LED is off at the puzzle's outset. + +| <> | <> | +[[req:58,R-058]] The preparer must set all switches to the down position at the start of the puzzle box game. + +| <> | <> | +[[req:59,R-059]] The preparer must turn all potentiometers to the left (value '0') at the beginning of the puzzle box game. + +| <> | <> | +[[req:60,R-060]] The puzzle consists of two phases. + +| <> | <> | +[[req:61,R-061]] The puzzle begins in phase 1. + +| <> | <> | +[[req:62,R-062]] During the puzzle, the switches must be toggled to obtain a logical '1' at the output of the combinatorial circuit. + +| <> | <> | +[[req:63,R-063]] When the output of the combinatorial circuit equals '1', the green indicator LED turns on (Refer to <> for a sketch). + +| <> | <> | +[[req:64,R-064]] The puzzle proceeds to phase 2 when the output of the combinatorial circuit is a logical '1'. + +| <> | <> | +[[req:65,R-065]] The switches no longer respond once the puzzle enters phase 2. + +| <> | <> | +[[req:66,R-066]] The indicator LED from phase 1 remains green during phase 2. + +| <> | <> | +[[req:67,R-067]] In phase 2, a morse code is displayed using an LED. This morse code represents 4 numbers from 0 to 9 and repeats every second. + +| <> | <> | +[[req:68,R-068]] The morse code is randomly generated. + +| <> | <> | +[[req:69,R-069]] Each potentiometer can be rotated to display a value from 0 to 9 on the corresponding 4-digit 7-segment display. The order of the potentiometers matches the order of the segments on the display (Refer to <> for a sketch). + +| <> | <> | +[[req:70,R-070]] The puzzle is considered solved when the code displayed on the 7-segment 4-digit screen matches the 4 numbers from the morse code. + +| <> | <> | +[[req:71,R-071]] Once the puzzle is solved, the value shown on the 7-segment 4-digit display cannot be changed. + +| <> | <> | +[[req:72,R-072]] A 2-second victory sound is produced by the speaker upon solving the puzzle. + +| <> | <> | +[[req:73,R-073]] During the victory sound, the 7-segment display blinks twice per second. + +| <> | <> | +[[req:74,R-074]] After the victory sound, the puzzle has been solved and the vault puzzle begins. +|=== + +==== Vault puzzle + +.Vault puzzle requirements +[cols="8h,5h,~"] +|=== +| ID | <> | Specification + +| <> | <> | +[[req:75,R-075]] The vault puzzle board features a red 7-segment 4-digit display. + +| <> | <> | +[[req:76,R-076]] On the vault puzzle board, there is a 4x4 grid of holes for ventilation and sound. + +| <> | <> | +[[req:77,R-077]] The vault puzzle board includes a vault door, and the inside of the vault is transparent, allowing you to see inside the puzzle box. + +| <> | <> | +[[req:78,R-078]] A sensor is integrated with the vault to detect when the vault is closed. + +| <> | <> | +[[req:79,R-079]] At the beginning of the puzzle box game, the preparer must close the vault. + +| <> | <> | +[[req:80,R-080]] The puzzle starts at level 1. + +| <> | <> | +[[req:81,R-081]] Initially, the 7-segment display shows a code consisting of a letter and a digit. This code represents a valid key combination for level 1 (Refer to <> for all combinations). + +| <> | <> | +[[req:82,R-082]] There are a total of 5 levels. After each level, a key combination is displayed, starting with a letter followed by a digit, which is valid for that level (Refer to <>). + +| <> | <> | +[[req:83,R-083]] Each level has unique key combinations for the button locations (Refer to <>). + +| <> | <> | +[[req:84,R-084]] Pressing the button corresponding to the letter-digit combinations advances the puzzle to the next level. + +| <> | <> | +[[req:85,R-085]] If an incorrect button is pressed, the game resets to level 1. + +| <> | <> | +[[req:86,R-086]] An error sound is produced by the speaker when an incorrect button is pressed. + +| <> | <> | +[[req:87,R-087]] The 7-segment display blinks when an incorrect button is pressed. + +| <> | <> | +[[req:88,R-088]] After completing 5 levels, the puzzle is solved, and the vault opens. +|=== + +=== Battery + +.Battery requirements +[cols="8h,5h,~"] +|=== +| ID | <> | Specification + +| <> | <> | +[[req:89,R-089]] The puzzle box is powered by a rechargeable battery. + +| <> | <> | +[[req:90,R-090]] The battery lasts for a minimum of 4 hours. + +| <> | <> | +[[req:91,R-091]] The battery in the puzzle box can be replaced. +|=== + +=== Network Communication + +.Communication requirements +[cols="8h,5h,~"] +|=== +| ID | <> | Specification + +| <> | <> | +[[req:92,R-092]] The puzzle boxes, bombs, and the puzzle box hub must all be able to communicate with each other. + +| <> | <> | +[[req:93,R-093]] Communication between two devices in the network must have a range of at least 20 meters in an open field. +|=== + +=== Framework + +[cols="8h,5h,~"] +|=== +| ID | <> | Specification + +| <> | <> | +[[req:130,R-130]] The main controller and its software do not need to be modified to implement a new puzzle module + +| <> | <> | +[[req:131,R-131]] Puzzle modules can be added and removed while the main controller is powered on + +| <> | <> | +[[req:132,R-132]] Puzzle modules can be added and removed while the main controller is powered off + +| <> | <> | +[[req:133,R-133]] The puzzle box provides a single external interface for accessing and controlling game state variables +|=== + +=== Puzzle box hub + +.Puzzle box hub general requirements +[cols="8h,5h,~"] +|=== +| ID | <> | Specification + +| <> | <> | +[[req:94,R-094]] The puzzle box hub hosts a website that can be accessed by a device connected to the network. +|=== + +[[sec:technical]] +== Technical Requirements + +The technical specifications describe the specifications that are important for +developers. For example, this could include specific requirements related to +current, voltage, or communication protocols. This chapter outlines all the +technical specifications of the puzzle box. + +=== Wireless communication + +.Wireless communication requirements +[cols="8h,5h,~"] +|=== +| ID | <> | Specification + +| <> | <> | +[[req:127,R-127]] The wireless communication between the system controller, bomb, and puzzle box operates over a WiFi mesh or WiFi network. +|=== + +=== Framework + +.Development framework requirements +[cols="8h,5h,~"] +|=== +| ID | <> | Specification + +| <> | <> | +[[req:128,R-128]] A framework has been created to assist future groups in the development of the puzzle box. + +| <> | <> | +[[req:129,R-129]] The framework runs on the main puzzle box controller. + +| <> | <> | +[[req:134,R-134]] Puzzle modules are detected by the main controller module. + +| <> | <> | +[[req:135,R-135]] Puzzle modules are initialized by the main controller module. + +| <> | <> | +[[req:165,R-165]] Puzzle modules repeatedly send 'update' messages to the main controller while their global state is 'uninitialized' +|=== + +=== Main controller + +.Main controller requirements +[cols="8h,5h,~"] +|=== +| ID | <> | Specification + +| <> | <> | +[[req:main-i2c-ctrl,R-136]] The main controller has at least 1 I2C peripheral. + +| <> | <> | +[[req:main-802-11-ap,R-137]] The main controller can connect to a standard 802.11b/g/n access point. + +| <> | <> | +[[req:main-tcp-socket,R-138]] The main controller can serve TCP socket connection(s). + +| <> | <> | +[[req:main-devkit-supplier,R-139]] The main controller is available as a development kit from Farnell. + +| <> | <> | +[[req:140,R-140]] The main controller can communicate over I²C with a speed of 400kb/s + +| <> | <> | +[[req:main-pwr-efficient,R-166]] The main controller is power efficient. +|=== + +=== Puzzle module controller + +[cols="8h,5h,~"] +|=== +| ID | <> | Specification + +| <> | <> | +[[req:pm-i2c-ctrl,R-141]] The puzzle module controller has at least 1 I2C peripheral. + +| <> | <> | +[[req:pm-gpio,R-142]] The puzzle module controller has enough I/O ports to control a puzzle. + +| <> | <> | +[[req:pm-pwr-efficient,R-143]] The puzzle module is power efficient. + +| <> | <> | +[[req:pm-clk-ctrl,R-144]] The puzzle module has a configurable clock speed. + +| <> | <> | +[[req:pm-devkit-supplier,R-145]] The puzzle module controller is available as a development kit from Farnell. + +| <> | <> | +[[req:146,R-146]] The puzzle module can communicate over I²C with a speed of 400kb/s +|=== + +=== Vault puzzle + +.Vault puzzle requirements +[cols="8h,5h,~"] +|=== +| ID | <> | Specification + +| <> | <> | +[[req:147,R-147]] The vault puzzle can communicate with the main controller using I²C + +| <> | <> | +[[req:148,R-148]] The vault puzzle can produce a sound signal for the buzzer + +| <> | <> | +[[req:149,R-149]] The vault puzzle can lock & unlock a solenoid lock + +| <> | <> | +[[req:150,R-150]] The vault puzzle can translate and obtain a button press from the 3x4 keypad using 5 inputs + +| <> | <> | +[[req:151,R-151]] The vault puzzle can communicate with a 4x 7 SEG. Display using 2 lines (clock & data) + +| <> | <> | +[[req:152,R-152]] The vault puzzle can read a sensor's value to detect if the vault door is open or closed. +|=== + +=== Bomb + +.Bomb requirements +[cols="8h,5h,~"] +|=== +| ID | <> | Specification + +| <> | <> | +[[req:153,R-153]] The bomb can communicate with the hub using a TCP socket connection + +| <> | <> | +[[req:154,R-154]] The bomb can sync. time using the WiFi connection + +| <> | <> | +[[req:155,R-155]] The bomb can retrieve, and store a given code in order to verify it later on input + +| <> | <> | +[[req:156,R-156]] The bomb can be paired to a puzzlebox using the hub's interface +|=== + +== Preconditions + +This section describes the aspects of the project which have been set as +preconditions and cannot be changed. + +.Preconditions +[cols="8h,~"] +|=== +| ID | Precondition + +| <> | [[req:160,R-160]] The delivery of components cannot take longer than two weeks. +| <> | [[req:161,R-161]] The price of a single puzzle box is not higher than €150. +| <> | [[req:162,R-162]] The existing games are used in the puzzle box. +| <> | [[req:163,R-163]] The puzzle box is not allowed to make a connection with the Avans network (Eduroam). +| <> | [[req:164,R-164]] The bomb hardware cannot be changed. +|=== + +== Documentation + +This section lists requirements that apply to documentation produced during +this project. + +[cols="8h,5h,~"] +|=== +| ID | <> | Specification + +| <> | <> | +[[req:157,R-157]] All documentation is written according to the style guide cite:[styleguide] + +| <> | <> | +[[req:158,R-158]] All documentation is manually checked for spelling and grammar mistakes before being published + +| <> | <> | +[[req:159,R-159]] All project documents are examined once by Jonathan Overes from Avans +|=== + +[appendix] +== Attachments + +[[fig:vault-disp-sketch]] +.7 Segment 4 digit screen (sketch) +image::img/vault-disp-sketch.png[] + +[[fig:neotrellis-hardware-sketch]] +.NeoTrellis example (sketch) +image::img/neotrellis-hardware-sketch.png[] + +[[fig:neotrellis-toggle]] +.Toggling LEDs after the user pressed on the button (purple dot) +image::img/neotrellis-toggle.png[width=45%] + +[[fig:neotrellis-start]] +.Starting pattern of the NeoTrellis puzzle +image::img/neotrellis-start.png[width=45%] + +[[fig:software-example-sketch]] +.Software puzzle example with logical ports (left) and letters A through F (right) +image::img/software-example-sketch.png[] + +[[fig:software-codes-sketch]] +.The different code fragments corresponding with the letter A through F +image::img/software-codes-sketch.png[height=35%] + +[[fig:software-cable-sketch]] +.Software puzzle cable example +image::img/software-cable-sketch.png[] + +[[fig:hardware-example-sketch]] +.Hardware puzzle on the puzzle box +image::img/hardware-example-sketch.png[] + +[[fig:vault-keypad]] +.Buttons combinations with level numbers in the top left +image::img/vault-keypad.png[width=45%] + +include::share/footer.adoc[] + diff --git a/docs/requirements.adoc b/docs/requirements.adoc deleted file mode 100644 index e3225a5..0000000 --- a/docs/requirements.adoc +++ /dev/null @@ -1,723 +0,0 @@ -= Project Requirements: {project} -include::share/meta.adoc[] - -== Introduction - -In this document, the specifications are described prior to the investigation -of the Puzzle Box project. These specifications are partly derived from the -previously established requirements and are further supplemented and modified. -The priority of specifications is indicated using the MoSCoW method, see -<>. - -[[tab:moscow]] -.MoSCoW Method cite:[Wik22] -[cols="20h,~"] -|=== -| Priority | Description - -| [[must,M]]<> -| Represents essential system requirements. Without these, the system will not -function. -| [[should,S]]<> -| Denotes desirable system features. The system can work without these, but it -lacks necessary elements. -| [[could,C]]<> -| Refers to additional functionalities that can be implemented if there is -extra time. -| [[wont,W]]<> -| Specifies requirements that will not be implemented in the current version -but may be considered in a future release. -|=== - -This specification document covers hardware, software, and game-specific -details. The focus in this project year for the Puzzle Box is to thoroughly -document the system and create a software framework for future groups. - -== Context - -This chapter describes how the user will interact with the system. This is done -in the form of a user story. This user story covers hardware, software, and -game specifications. From this narrative, many specifications can be derived -for both functional and non-functional requirements -(<> and <>). - -The game administrator picks up the puzzle box and places it on a flat surface. -By using the key switch, the puzzle box is turned on, and the green indicator -LED lights up. Through the mesh network established by the external puzzle box -hub, the corresponding web panel can be accessed. The web panel provides -instructions for configuring the puzzle box, including linking it to any bomb. -The instructions issue a warning if any of the start conditions are not -properly set. If a criterion is incorrectly configured, it is highlighted for -resolution. Additionally, a warning is given if the battery capacity is -insufficient for one game duration, causing the indicator LED on the puzzle box -to turn red. In such cases, the battery should be charged using the USB-C -cable. While the puzzle box is charging, the indicator LED is blue. Once there -are no warnings and the puzzle box is adequately charged, the game can be -started in the web panel. - -The puzzle box begins with the NeoTrellis game. In this game, players must turn -off all LEDs on an 8x8 button LED matrix. When any button is pressed, the -directly adjacent LEDs toggle. If a lit LED is toggled, it turns off; if an -unlit LED is toggled, it turns on. Once all LEDs are turned off, the game is -solved, and the software puzzle begins. - -On the software puzzle, there are 6 banana plug connectors on both the left and -right sides. The ones on the left are labeled with various logical gates, while -the ones on the right are labeled from A to F. Participants in the bomb game -have 6 pieces of C-code written on paper, corresponding to the logical gates on -the puzzle box. The bomb participants must provide a description of the C-code -to the puzzle box participants, allowing them to correctly connect the -appropriate logical gate to the corresponding letter. Once the correct -combination of logical gates with the correct letter is made, the game is -solved. Subsequently, the automation puzzle is initiated. - -Since there is no concept available for the automation puzzle yet, the hardware -puzzle is started directly. - -The hardware puzzle is played in two distinct phases. In Phase 1, the objective -is to solve a combinatorial circuit such that its output becomes '1'. There are -8 inputs for this circuit, each controlled by an on/off switch. Once the -combinatorial circuit evaluates to '1', the LED at the output lights up, -indicating the completion of the first phase. In Phase 2, another LED blinks, -consistently repeating a pattern. This pattern represents a randomly generated -Morse code, corresponding to a number from 0 to 9999. Participants use a Morse -code table to decipher the correct number. Using four potentiometers, the -participants can set a number on a 7-segment display. When this number matches -the randomly generated one, the hardware puzzle is solved. Subsequently, the -vault puzzle is initiated. - -In the vault puzzle, a 7-segment display shows a random combination of a letter -and a digit. Participants have access to a list containing the correct button -combination for the corresponding letter and digit. The vault puzzle consists -of 5 levels, each displaying a unique button combination from the list. When -participants correctly press the button on the keypad, the level advances, and -a new value is shown. Pressing the wrong button restarts the game at level 1. -Once all 5 levels are completed, the vault door unlocks, allowing access to the -inside of the puzzle box. On the mainboard, there is a 7-segment display -showing a code. This code must be relayed to the participants of the bomb game. -Once the bomb team receives the code, the puzzle box is considered solved. - -[[sec:functional]] -== Functional Requirements - -The functional requirements describe the things which are important to the -client. This is mainly about the way the product is going to be used, what it -is going to look like, and how the product reacts to interaction. This chapter -describes all functional requirements of the puzzle box. - -=== The puzzle box - -.Puzzle box specifications -[cols="8h,5h,~"] -|=== -| ID | <> | Specification - -| <> | <> | -[[req:1,R-001]] The dimensions of the puzzle box are 30×30×30cm ± 5% (Length × Width × Height). - -| <> | <> | -[[req:2,R-002]] The puzzle box extends a maximum of 5cm on the sides and the top. - -| <> | <> | -[[req:3,R-003]] The puzzle box is flat at the bottom. - -| <> | <> | -[[req:4,R-004]] The puzzle box has a key switch at the bottom of the NeoTrellis puzzle. - -| <> | <> | -[[req:5,R-005]] The puzzle box has an indicator LED at the bottom of the NeoTrellis puzzle. - -| <> | <> | -[[req:6,R-006]] The indicator LED turns green when the system is on and not charging. - -| <> | <> | -[[req:7,R-007]] The indicator LED turns blue when the battery is charging. - -| <> | <> | -[[req:8,R-008]] The indicator LED turns red when the battery does not have enough capacity for the duration of one game and is not charging. - -| <> | <> | -[[req:9,R-009]] The puzzle box has a USB-C port at the bottom of the NeoTrellis puzzle for battery charging. - -| <> | <> | -[[req:10,R-010]] The puzzle box has a distance sensor at the bottom to detect if it is lifted. - -| <> | <> | -[[req:11,R-011]] The puzzle box main board (PCB on the bottom plate) includes a speaker. - -| <> | <> | -[[req:12,R-012]] When the puzzle box is lifted, the mainboard speaker emits an alarm sound for at least 10 seconds. It stops only when it has been on a table for another 10 seconds (detected by the distance sensor). - -| <> | <> | -[[req:13,R-013]] When the game is completed, the puzzle box produces a victory sound. - -| <> | <> | -[[req:14,R-014]] Pressing the "identify" button on the web panel causes the indicator LED to blink. - -| <> | <> | -[[req:15,R-015]] Pressing the "identify" button on the web panel triggers a sound from the speaker. - -| <> | <> | -// section 3.7 is inside the citation, and does not refer to section 3.7 in this document -[[req:16,R-016]] The game starts once the scheduler time is reached (refer to cite:[Bek23] section 3.7). -|=== - -=== The bomb - -.Bomb specifications -[cols="8h,5h,~"] -|=== -| ID | <> | Specification - -| <> | <> | -[[req:17,R-017]] The bomb includes a 6-digit 7-segment display for showing the remaining playtime. - -| <> | <> | -[[req:18,R-018]] The bomb contains a keypad for entering the disarm code. - -| <> | <> | -[[req:19,R-019]] The 6-digit 7-segment display turns off when no game is in progress. - -| <> | <> | -[[req:20,R-020]] Once the disarm code is entered on the bomb keypad, the game is complete. - -| <> | <> | -[[req:21,R-021]] When the game is finished, the bomb emits a victory sound. - -| <> | <> | -[[req:22,R-022]] The timer on the bomb counts down from 60:00:00 to 00:00:00. - -| <> | <> | -[[req:23,R-023]] Pressing the "identify" button on the web panel causes the indicator LED to blink. - -| <> | <> | -[[req:24,R-024]] Pressing the "identify" button on the web panel triggers a sound from the speaker. - -|=== - -=== The game - -.General game specifications -[cols="8h,5h,~"] -|=== -| ID | <> | Specification - -| <> | <> | -[[req:25,R-025]] The game lasts for 1 hour. - -| <> | <> | -[[req:26,R-026]] The game should be solvable within the given playtime, without the player having prior knowledge of the game or its mechanics. - -| <> | <> | -[[req:27,R-027]] The puzzles should be easy enough to solve without any prior knowledge of the game or its mechanics. - -| <> | <> | -[[req:167,R-167]] A puzzle module can manually be reset at the discretion of the game operator - -| <> | <> | -[[req:168,R-168]] A puzzle module can manually be set as solved at the discretion of the game operator - -| <> | <> | -[[req:28,R-028]] The disarm code for the bomb consists of 4 digits. - -| <> | <> | -[[req:29,R-029]] Once all games are solved, the mainboard PCB displays the disarm code on a red 7-segment 4-digit screen. - -| <> | <> | -[[req:30,R-030]] The puzzle box records the playtime of each game. - -| <> | <> | -[[req:31,R-031]] The puzzle box features 5 playable puzzles. - -| <> | <> | -[[req:32,R-032]] Only one game is active at a time; the other games do not respond to buttons. - -| <> | <> | -[[req:33,R-033]] The game always starts with the NeoTrellis puzzle. -|=== - -==== NeoTrellis puzzle - -.NeoTrellis puzzle requirements -[cols="8h,5h,~"] -|=== -| ID | <> | Specification - -| <> | <> | -[[req:34,R-034]] There is an 8x8 LED matrix where each LED can display different colors. - -| <> | <> | -[[req:35,R-035]] At the start of the puzzle, a pattern is displayed as shown in <>. - -| <> | <> | -[[req:36,R-036]] When a button is pressed, the adjacent LEDs and the pressed LED toggle (If an LED is off, it turns on. If an LED is on, it turns off). - -| <> | <> | -[[req:37,R-037]] All LEDs in the Neotrellis that are turned on are blue. - -| <> | <> | -[[req:38,R-038]] The puzzle is considered solved when all LEDs are turned off, and then the software puzzle starts. -|=== - -==== Software puzzle - -.Software puzzle requirements -[cols="8h,5h,~"] -|=== -| ID | <> | Specification - -| <> | <> | -[[req:39,R-039]] The software puzzle board has 6 banana plug connectors with different logic gates displayed next to them (Refer to <> for a sketch and <> for a banana plug example). - -| <> | <> | -[[req:40,R-040]] The software puzzle board has 6 banana plug connectors labeled with the letters A through F (Refer to <> for a sketch). - -| <> | <> | -[[req:41,R-041]] At the start of the puzzle box game, the preparer must connect all cables in parallel (horizontally) to the connectors. - -| <> | <> | -[[req:42,R-042]] There are C code blocks visible only to the players on the bomb side, corresponding to the letters A through F (Refer to <> for the codes). - -| <> | <> | -[[req:43,R-043]] The combinations of logic gates to letters are always the same. - -| <> | <> | -[[req:44,R-044]] The puzzle is considered solved when the cables from the logic gates match the code blocks (Refer to <> and <> for the combinations). - -| <> | <> | -[[req:45,R-045]] Once the puzzle is solved, the green indicator LED will light up (Refer to <> and <>). - -| <> | <> | -[[req:46,R-046]] After the puzzle is solved, the automation puzzle begins. -|=== - -==== Automation puzzle - -The specific details for this puzzle are not present in the previous -documentation. Due to time constraints, the section will be left empty. - -.Automation puzzle requirements -[cols="8h,5h,~"] -|=== -| ID | <> | Specification - -| <> | <> | -[[req:47,R-047]] After the puzzle is solved, the hardware puzzle begins. -|=== - -==== Hardware puzzle - -.Hardware puzzle requirements -[cols="8h,5h,~"] -|=== -| ID | <> | Specification - -| <> | <> | -[[req:48,R-048]] There are eight switches on the hardware puzzle board. - -| <> | <> | -[[req:49,R-049]] The hardware puzzle board features a diagram of a combinatorial circuit with 8 inputs (linked to the switches) and 1 output (Refer to <> for a sketch). - -| <> | <> | -[[req:50,R-050]] The hardware puzzle board includes a red 7-segment 4-digit display (Refer to <> for a sketch). - -| <> | <> | -[[req:51,R-051]] There are 4 potentiometers on the hardware puzzle board (Refer to <> for a sketch). - -| <> | <> | -[[req:52,R-052]] A blue LED on the hardware puzzle board displays the morse code. - -| <> | <> | -[[req:53,R-053]] A green LED on the hardware puzzle board indicates whether the combinatorial circuit is solved. - -| <> | <> | -[[req:54,R-054]] At the start of the puzzle, the potentiometers are inactive. - -| <> | <> | -[[req:55,R-055]] The 7-segment display is off at the beginning of the puzzle. - -| <> | <> | -[[req:56,R-056]] The LED for the combinatorial puzzle is off initially. - -| <> | <> | -[[req:57,R-057]] The morse code LED is off at the puzzle's outset. - -| <> | <> | -[[req:58,R-058]] The preparer must set all switches to the down position at the start of the puzzle box game. - -| <> | <> | -[[req:59,R-059]] The preparer must turn all potentiometers to the left (value '0') at the beginning of the puzzle box game. - -| <> | <> | -[[req:60,R-060]] The puzzle consists of two phases. - -| <> | <> | -[[req:61,R-061]] The puzzle begins in phase 1. - -| <> | <> | -[[req:62,R-062]] During the puzzle, the switches must be toggled to obtain a logical '1' at the output of the combinatorial circuit. - -| <> | <> | -[[req:63,R-063]] When the output of the combinatorial circuit equals '1', the green indicator LED turns on (Refer to <> for a sketch). - -| <> | <> | -[[req:64,R-064]] The puzzle proceeds to phase 2 when the output of the combinatorial circuit is a logical '1'. - -| <> | <> | -[[req:65,R-065]] The switches no longer respond once the puzzle enters phase 2. - -| <> | <> | -[[req:66,R-066]] The indicator LED from phase 1 remains green during phase 2. - -| <> | <> | -[[req:67,R-067]] In phase 2, a morse code is displayed using an LED. This morse code represents 4 numbers from 0 to 9 and repeats every second. - -| <> | <> | -[[req:68,R-068]] The morse code is randomly generated. - -| <> | <> | -[[req:69,R-069]] Each potentiometer can be rotated to display a value from 0 to 9 on the corresponding 4-digit 7-segment display. The order of the potentiometers matches the order of the segments on the display (Refer to <> for a sketch). - -| <> | <> | -[[req:70,R-070]] The puzzle is considered solved when the code displayed on the 7-segment 4-digit screen matches the 4 numbers from the morse code. - -| <> | <> | -[[req:71,R-071]] Once the puzzle is solved, the value shown on the 7-segment 4-digit display cannot be changed. - -| <> | <> | -[[req:72,R-072]] A 2-second victory sound is produced by the speaker upon solving the puzzle. - -| <> | <> | -[[req:73,R-073]] During the victory sound, the 7-segment display blinks twice per second. - -| <> | <> | -[[req:74,R-074]] After the victory sound, the puzzle has been solved and the vault puzzle begins. -|=== - -==== Vault puzzle - -.Vault puzzle requirements -[cols="8h,5h,~"] -|=== -| ID | <> | Specification - -| <> | <> | -[[req:75,R-075]] The vault puzzle board features a red 7-segment 4-digit display. - -| <> | <> | -[[req:76,R-076]] On the vault puzzle board, there is a 4x4 grid of holes for ventilation and sound. - -| <> | <> | -[[req:77,R-077]] The vault puzzle board includes a vault door, and the inside of the vault is transparent, allowing you to see inside the puzzle box. - -| <> | <> | -[[req:78,R-078]] A sensor is integrated with the vault to detect when the vault is closed. - -| <> | <> | -[[req:79,R-079]] At the beginning of the puzzle box game, the preparer must close the vault. - -| <> | <> | -[[req:80,R-080]] The puzzle starts at level 1. - -| <> | <> | -[[req:81,R-081]] Initially, the 7-segment display shows a code consisting of a letter and a digit. This code represents a valid key combination for level 1 (Refer to <> for all combinations). - -| <> | <> | -[[req:82,R-082]] There are a total of 5 levels. After each level, a key combination is displayed, starting with a letter followed by a digit, which is valid for that level (Refer to <>). - -| <> | <> | -[[req:83,R-083]] Each level has unique key combinations for the button locations (Refer to <>). - -| <> | <> | -[[req:84,R-084]] Pressing the button corresponding to the letter-digit combinations advances the puzzle to the next level. - -| <> | <> | -[[req:85,R-085]] If an incorrect button is pressed, the game resets to level 1. - -| <> | <> | -[[req:86,R-086]] An error sound is produced by the speaker when an incorrect button is pressed. - -| <> | <> | -[[req:87,R-087]] The 7-segment display blinks when an incorrect button is pressed. - -| <> | <> | -[[req:88,R-088]] After completing 5 levels, the puzzle is solved, and the vault opens. -|=== - -=== Battery - -.Battery requirements -[cols="8h,5h,~"] -|=== -| ID | <> | Specification - -| <> | <> | -[[req:89,R-089]] The puzzle box is powered by a rechargeable battery. - -| <> | <> | -[[req:90,R-090]] The battery lasts for a minimum of 4 hours. - -| <> | <> | -[[req:91,R-091]] The battery in the puzzle box can be replaced. -|=== - -=== Network Communication - -.Communication requirements -[cols="8h,5h,~"] -|=== -| ID | <> | Specification - -| <> | <> | -[[req:92,R-092]] The puzzle boxes, bombs, and the puzzle box hub must all be able to communicate with each other. - -| <> | <> | -[[req:93,R-093]] Communication between two devices in the network must have a range of at least 20 meters in an open field. -|=== - -=== Framework - -[cols="8h,5h,~"] -|=== -| ID | <> | Specification - -| <> | <> | -[[req:130,R-130]] The main controller and its software do not need to be modified to implement a new puzzle module - -| <> | <> | -[[req:131,R-131]] Puzzle modules can be added and removed while the main controller is powered on - -| <> | <> | -[[req:132,R-132]] Puzzle modules can be added and removed while the main controller is powered off - -| <> | <> | -[[req:133,R-133]] The puzzle box provides a single external interface for accessing and controlling game state variables -|=== - -=== Puzzle box hub - -.Puzzle box hub general requirements -[cols="8h,5h,~"] -|=== -| ID | <> | Specification - -| <> | <> | -[[req:94,R-094]] The puzzle box hub hosts a website that can be accessed by a device connected to the network. -|=== - -[[sec:technical]] -== Technical Requirements - -The technical specifications describe the specifications that are important for -developers. For example, this could include specific requirements related to -current, voltage, or communication protocols. This chapter outlines all the -technical specifications of the puzzle box. - -=== Wireless communication - -.Wireless communication requirements -[cols="8h,5h,~"] -|=== -| ID | <> | Specification - -| <> | <> | -[[req:127,R-127]] The wireless communication between the system controller, bomb, and puzzle box operates over a WiFi mesh or WiFi network. -|=== - -=== Framework - -.Development framework requirements -[cols="8h,5h,~"] -|=== -| ID | <> | Specification - -| <> | <> | -[[req:128,R-128]] A framework has been created to assist future groups in the development of the puzzle box. - -| <> | <> | -[[req:129,R-129]] The framework runs on the main puzzle box controller. - -| <> | <> | -[[req:134,R-134]] Puzzle modules are detected by the main controller module. - -| <> | <> | -[[req:135,R-135]] Puzzle modules are initialized by the main controller module. - -| <> | <> | -[[req:165,R-165]] Puzzle modules repeatedly send 'update' messages to the main controller while their global state is 'uninitialized' -|=== - -=== Main controller - -.Main controller requirements -[cols="8h,5h,~"] -|=== -| ID | <> | Specification - -| <> | <> | -[[req:main-i2c-ctrl,R-136]] The main controller has at least 1 I2C peripheral. - -| <> | <> | -[[req:main-802-11-ap,R-137]] The main controller can connect to a standard 802.11b/g/n access point. - -| <> | <> | -[[req:main-tcp-socket,R-138]] The main controller can serve TCP socket connection(s). - -| <> | <> | -[[req:main-devkit-supplier,R-139]] The main controller is available as a development kit from Farnell. - -| <> | <> | -[[req:140,R-140]] The main controller can communicate over I²C with a speed of 400kb/s - -| <> | <> | -[[req:main-pwr-efficient,R-166]] The main controller is power efficient. -|=== - -=== Puzzle module controller - -[cols="8h,5h,~"] -|=== -| ID | <> | Specification - -| <> | <> | -[[req:pm-i2c-ctrl,R-141]] The puzzle module controller has at least 1 I2C peripheral. - -| <> | <> | -[[req:pm-gpio,R-142]] The puzzle module controller has enough I/O ports to control a puzzle. - -| <> | <> | -[[req:pm-pwr-efficient,R-143]] The puzzle module is power efficient. - -| <> | <> | -[[req:pm-clk-ctrl,R-144]] The puzzle module has a configurable clock speed. - -| <> | <> | -[[req:pm-devkit-supplier,R-145]] The puzzle module controller is available as a development kit from Farnell. - -| <> | <> | -[[req:146,R-146]] The puzzle module can communicate over I²C with a speed of 400kb/s -|=== - -=== Vault puzzle - -.Vault puzzle requirements -[cols="8h,5h,~"] -|=== -| ID | <> | Specification - -| <> | <> | -[[req:147,R-147]] The vault puzzle can communicate with the main controller using I²C - -| <> | <> | -[[req:148,R-148]] The vault puzzle can produce a sound signal for the buzzer - -| <> | <> | -[[req:149,R-149]] The vault puzzle can lock & unlock a solenoid lock - -| <> | <> | -[[req:150,R-150]] The vault puzzle can translate and obtain a button press from the 3x4 keypad using 5 inputs - -| <> | <> | -[[req:151,R-151]] The vault puzzle can communicate with a 4x 7 SEG. Display using 2 lines (clock & data) - -| <> | <> | -[[req:152,R-152]] The vault puzzle can read a sensor's value to detect if the vault door is open or closed. -|=== - -=== Bomb - -.Bomb requirements -[cols="8h,5h,~"] -|=== -| ID | <> | Specification - -| <> | <> | -[[req:153,R-153]] The bomb can communicate with the hub using a TCP socket connection - -| <> | <> | -[[req:154,R-154]] The bomb can sync. time using the WiFi connection - -| <> | <> | -[[req:155,R-155]] The bomb can retrieve, and store a given code in order to verify it later on input - -| <> | <> | -[[req:156,R-156]] The bomb can be paired to a puzzlebox using the hub's interface -|=== - -== Preconditions - -This section describes the aspects of the project which have been set as -preconditions and cannot be changed. - -.Preconditions -[cols="8h,~"] -|=== -| ID | Precondition - -| <> | [[req:160,R-160]] The delivery of components cannot take longer than two weeks. -| <> | [[req:161,R-161]] The price of a single puzzle box is not higher than €150. -| <> | [[req:162,R-162]] The existing games are used in the puzzle box. -| <> | [[req:163,R-163]] The puzzle box is not allowed to make a connection with the Avans network (Eduroam). -| <> | [[req:164,R-164]] The bomb hardware cannot be changed. -|=== - -== Documentation - -This section lists requirements that apply to documentation produced during -this project. - -[cols="8h,5h,~"] -|=== -| ID | <> | Specification - -| <> | <> | -[[req:157,R-157]] All documentation is written according to the style guide cite:[styleguide] - -| <> | <> | -[[req:158,R-158]] All documentation is manually checked for spelling and grammar mistakes before being published - -| <> | <> | -[[req:159,R-159]] All project documents are examined once by Jonathan Overes from Avans -|=== - -[appendix] -== Attachments - -[[fig:vault-disp-sketch]] -.7 Segment 4 digit screen (sketch) -image::img/vault-disp-sketch.png[] - -[[fig:neotrellis-hardware-sketch]] -.NeoTrellis example (sketch) -image::img/neotrellis-hardware-sketch.png[] - -[[fig:neotrellis-toggle]] -.Toggling LEDs after the user pressed on the button (purple dot) -image::img/neotrellis-toggle.png[width=45%] - -[[fig:neotrellis-start]] -.Starting pattern of the NeoTrellis puzzle -image::img/neotrellis-start.png[width=45%] - -[[fig:software-example-sketch]] -.Software puzzle example with logical ports (left) and letters A through F (right) -image::img/software-example-sketch.png[] - -[[fig:software-codes-sketch]] -.The different code fragments corresponding with the letter A through F -image::img/software-codes-sketch.png[height=35%] - -[[fig:software-cable-sketch]] -.Software puzzle cable example -image::img/software-cable-sketch.png[] - -[[fig:hardware-example-sketch]] -.Hardware puzzle on the puzzle box -image::img/hardware-example-sketch.png[] - -[[fig:vault-keypad]] -.Buttons combinations with level numbers in the top left -image::img/vault-keypad.png[width=45%] - -include::share/footer.adoc[] - diff --git a/docs/research.adoc b/docs/research.adoc index 7e5b78c..5d4f381 100644 --- a/docs/research.adoc +++ b/docs/research.adoc @@ -1,4 +1,4 @@ -= Research: {project} +:document: Research include::share/meta.adoc[] == Microcontrollers used in the current state. @@ -124,15 +124,14 @@ controller and controller used in puzzle modules. The following criteria were used to compare MCUs that are suitable candidates as main controller unit: -* Must have at least 1 I^2^C peripheral - (<>). +* Must have at least 1 I^2^C peripheral (<>). * Must be able to connect to a standard 802.11b/g/n access point - (<>). + (<>). * Must be able to serve TCP socket connection(s) - (<>). -* Should be power efficient (<>). + (<>). +* Should be power efficient (<>). * Is available as a development kit from Farnell - (<>). + (<>). <> lists the considered MCU options matching the above criteria. This list is a compilation of microcontroller offerings from the following @@ -160,14 +159,13 @@ The Raspberry Pi Pico W board is utilized during development. The following criteria were used to compare MCUs that are suitable candidates for controlling the puzzle modules: -* Must have at least 1 I^2^C peripheral - (<>). +* Must have at least 1 I^2^C peripheral (<>). * Should has enough I/O ports to directly control moderately complex puzzles - (<>). -* Should be power efficient (<>). + (<>). +* Should be power efficient (<>). * Is available as a development kit from Farnell - (<>). -* Has a configurable clock speed (<>). + (<>). +* Has a configurable clock speed (<>). <> lists the considered MCU options matching the above criteria. This list is a compilation of microcontroller offerings from the following diff --git a/docs/share/meta.adoc b/docs/share/meta.adoc index 0b6cb78..15d8d18 100644 --- a/docs/share/meta.adoc +++ b/docs/share/meta.adoc @@ -1,8 +1,13 @@ -:sectnums: -:title-page: -:toc: -:toclevels: 4 -:pagenums: +// (these files are included from the parent directory) +:pdf-theme: ./theme.yml +// :pdf-fontsdir: ./res/font +:bibtex-file: ./share/refs.bib + +// document / project info +ifndef::document[] +:document: DOCUMENT TITLE +endif::[] +:project: Project Puzzlebox :revnumber: 0.0 :revdate: 2024-04-01 :revremark: draft @@ -10,7 +15,19 @@ :author_2: Loek Le Blansch :author_3: Lars Faase :author_4: Elwin Hammer + +// numbering / reference styles +:sectnums: +:toclevels: 4 +:pagenums: :xrefstyle: short -:project: Project Puzzlebox -// see https://docs.asciidoctor.org/asciidoc/latest/attributes/document-attributes-ref +// (set and display title) += {document}: {project} +// start each document with a title page +:title-page: +// followed by a table of contents +:toc: + +// also https://docs.asciidoctor.org/asciidoc/latest/attributes/document-attributes-ref + -- cgit v1.2.3