From e5de3732057827a6e2194b967e3a419591bcea34 Mon Sep 17 00:00:00 2001 From: lonkaars Date: Thu, 11 Apr 2024 11:34:08 +0200 Subject: WIP docs --- docs/.gitignore | 1 + docs/makefile | 4 + docs/plan.adoc | 376 +++++++++++++++++++++++++++++++++++++++++++++++ docs/share/glossary.adoc | 6 + docs/share/meta.adoc | 9 ++ 5 files changed, 396 insertions(+) create mode 100644 docs/.gitignore create mode 100644 docs/makefile create mode 100644 docs/plan.adoc create mode 100644 docs/share/glossary.adoc create mode 100644 docs/share/meta.adoc diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..a136337 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +*.pdf diff --git a/docs/makefile b/docs/makefile new file mode 100644 index 0000000..4c1d21a --- /dev/null +++ b/docs/makefile @@ -0,0 +1,4 @@ +all: plan.pdf + +%.pdf: %.adoc + asciidoctor -r asciidoctor-pdf -b pdf $< 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[] + diff --git a/docs/share/glossary.adoc b/docs/share/glossary.adoc new file mode 100644 index 0000000..5ba8340 --- /dev/null +++ b/docs/share/glossary.adoc @@ -0,0 +1,6 @@ +[glossary] +== Glossary + +[glossary] +RPI:: Raspberry Pi + diff --git a/docs/share/meta.adoc b/docs/share/meta.adoc new file mode 100644 index 0000000..1df62fe --- /dev/null +++ b/docs/share/meta.adoc @@ -0,0 +1,9 @@ +Thomas in ‘t Anker; Loek Le Blansch; Lars Faase; Elwin Hammer +0.0, 2024-04-01 + +:doctype: book + +[.metadata] +{authors} -- version {revnumber}, {revdate} + + -- 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 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 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 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 0d40eb00c737817ac4c635bdfcf27fc70ce4284b Mon Sep 17 00:00:00 2001 From: lonkaars Date: Sun, 14 Apr 2024 16:05:46 +0200 Subject: start transferring requirements + hello world plugin --- docs/makefile | 2 + docs/plugin/helloworld.rb | 13 +++ docs/requirements.adoc | 198 ++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 213 insertions(+) create mode 100644 docs/plugin/helloworld.rb create mode 100644 docs/requirements.adoc diff --git a/docs/makefile b/docs/makefile index cccc231..a3f5597 100644 --- a/docs/makefile +++ b/docs/makefile @@ -1,4 +1,5 @@ all: plan.pdf +all: requirements.pdf # include font.mk @@ -7,6 +8,7 @@ PDFDEPS += ./theme.yml ASCIIDOCTOR_ARGS += --require asciidoctor-bibtex ASCIIDOCTOR_ARGS += --require asciidoctor-pdf +# ASCIIDOCTOR_ARGS += --require ./plugin/helloworld ASCIIDOCTOR_ARGS += --backend pdf ASCIIDOCTOR_ARGS += --attribute pdf-theme=./theme.yml # ASCIIDOCTOR_ARGS += --attribute pdf-fontsdir=./res/font diff --git a/docs/plugin/helloworld.rb b/docs/plugin/helloworld.rb new file mode 100644 index 0000000..7bfc226 --- /dev/null +++ b/docs/plugin/helloworld.rb @@ -0,0 +1,13 @@ +class HelloWorldMacro < Asciidoctor::Extensions::BlockMacroProcessor + use_dsl + named :helloworld + + def process parent, target, attrs + return + end +end + +Asciidoctor::Extensions.register do + block_macro HelloWorldMacro +end + diff --git a/docs/requirements.adoc b/docs/requirements.adoc new file mode 100644 index 0000000..94b532b --- /dev/null +++ b/docs/requirements.adoc @@ -0,0 +1,198 @@ += Project Requirements: Project Puzzlebox +include::share/meta.adoc[] + +== Introduction + +In this document, the specifications are described prior to the investigation +of the Puzzle Box project. These specifications are partly derived from the +previously established requirements and are further supplemented and modified. +The priority of specifications is indicated using the MoSCoW method, see +<>. + +[[tab:moscow]] +.MoSCoW Method cite:[Wik22] +[cols="1,3"] +|=== +| Priority | Description + +| Must have +| Represents essential system requirements. Without these, the system will not +function. +| Should have +| Denotes desirable system features. The system can work without these, but it +lacks necessary elements. +| Could have +| Refers to additional functionalities that can be implemented if there is +extra time. +| Won't have +| Specifies requirements that will not be implemented in the current version +but may be considered in a future release. +|=== + +This specification document covers hardware, software, and game-specific +details. The focus in this project year for the Puzzle Box is to thoroughly +document the system and create a software framework for future groups. + +== Context + +This chapter describes how the user will interact with the system. This is done +in the form of a user story. This user story covers hardware, software, and +game specifications. From this narrative, many specifications can be derived +for both functional and non-functional requirements +(<> 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="1,1,10"] +|=== +| ID | Pri. | Specification + +| 1. | M +| The dimensions of the puzzle box are 30×30×30cm ± 5% (Length × Width × Height). + +| 2. | M +| The puzzle box extends a maximum of 5cm on the sides and the top. + +| 3. | M +| The puzzle box is flat at the bottom. + +| 4. | M +| The puzzle box has a key switch at the bottom of the NeoTrellis puzzle. + +| 5. | M +| The puzzle box has an indicator LED at the bottom of the NeoTrellis puzzle. + +| 6. | M +| The indicator LED turns green when the system is on and not charging. + +| 7. | M +| The indicator LED turns blue when the battery is charging. + +| 8. | M +| The indicator LED turns red when the battery does not have enough capacity for the duration of one game and is not charging. + +| 9. | M +| The puzzle box has a USB-C port at the bottom of the NeoTrellis puzzle for battery charging. + +| 10. | M +| The puzzle box has a distance sensor at the bottom to detect if it is lifted. + +| 11. | M +| The puzzle box main board (PCB on the bottom plate) includes a speaker. + +| 12 | W +| When the puzzle box is lifted, the mainboard speaker emits an alarm sound for at least 10 seconds. It stops only when it has been on a table for another 10 seconds (detected by the distance sensor). + +| 13. | W +| When the game is completed, the puzzle box produces a victory sound. + +| 14. | W +| Pressing the "identify" button on the web panel causes the indicator LED to blink. + +| 15. | W +| Pressing the "identify" button on the web panel triggers a sound from the speaker. + +| 16. | W +| The game starts once the scheduler time is reached (refer to section 3.7 - [2]). +|=== + + +=== The bomb +=== The game +==== NeoTrellis puzzle +==== Software puzzle +==== Automation puzzle +==== Hardware puzzle +==== Vault puzzle +=== Battery +=== Network Communication +=== Framework +=== Puzzle box hub + +[[sec:technical]] +== Technical Requirements + +=== Wireless communication +=== Framework +=== Main controller +=== Puzzle module controller +=== Vault puzzle +=== Bomb +== Preconditions +== Documentation + +[appendix] +== Explanatory Images + +// [#alinea1,reftext='alinea 1'] +// Hoi ik ben een alinea +// +// <> + +include::share/footer.adoc[] + -- cgit v1.2.3 From 5f5423cd763c75920072aef419eb9160f8f4fd48 Mon Sep 17 00:00:00 2001 From: lonkaars Date: Fri, 19 Apr 2024 15:21:06 +0200 Subject: WIP more requirements --- docs/Gemfile | 4 + docs/makefile | 6 +- docs/requirements.adoc | 512 +++++++++++++++++++++++++++++++++++++++++++---- docs/share/glossary.adoc | 3 + 4 files changed, 482 insertions(+), 43 deletions(-) diff --git a/docs/Gemfile b/docs/Gemfile index 67cd54a..99f5ca1 100644 --- a/docs/Gemfile +++ b/docs/Gemfile @@ -1,7 +1,11 @@ ruby '~> 3.0' source 'https://rubygems.org' +gem 'json' # required for bibtex + gem 'asciidoctor', '~> 2.0' gem 'asciidoctor-pdf', '~> 2.3' gem 'asciidoctor-bibtex', '~> 0.8.0' +# gem 'asciidoctor-interdoc-reftext', '~> 0.5.2' +gem 'asciidoctor-interdoc-reftext', git: 'https://github.com/lonkaars/asciidoctor-interdoc-reftext' diff --git a/docs/makefile b/docs/makefile index a3f5597..e177f6d 100644 --- a/docs/makefile +++ b/docs/makefile @@ -6,13 +6,17 @@ all: requirements.pdf # PDFDEPS += $(ALL_FONTS) PDFDEPS += ./theme.yml +# uncomment to debug include errors +# ASCIIDOCTOR_ARGS += --trace + ASCIIDOCTOR_ARGS += --require asciidoctor-bibtex ASCIIDOCTOR_ARGS += --require asciidoctor-pdf # ASCIIDOCTOR_ARGS += --require ./plugin/helloworld +ASCIIDOCTOR_ARGS += --require asciidoctor-interdoc-reftext ASCIIDOCTOR_ARGS += --backend pdf ASCIIDOCTOR_ARGS += --attribute pdf-theme=./theme.yml # ASCIIDOCTOR_ARGS += --attribute pdf-fontsdir=./res/font ASCIIDOCTOR_ARGS += --attribute bibtex-file=./share/refs.bib %.pdf: %.adoc $(PDFDEPS) - asciidoctor $(ASCIIDOCTOR_ARGS) $< + bundle exec asciidoctor $(ASCIIDOCTOR_ARGS) $< diff --git a/docs/requirements.adoc b/docs/requirements.adoc index 94b532b..2170484 100644 --- a/docs/requirements.adoc +++ b/docs/requirements.adoc @@ -15,16 +15,16 @@ The priority of specifications is indicated using the MoSCoW method, see |=== | Priority | Description -| Must have +| [[must,M]]<> | Represents essential system requirements. Without these, the system will not function. -| Should have +| [[should,S]]<> | Denotes desirable system features. The system can work without these, but it lacks necessary elements. -| Could have +| [[could,C]]<> | Refers to additional functionalities that can be implemented if there is extra time. -| Won't have +| [[wont,W]]<> | Specifies requirements that will not be implemented in the current version but may be considered in a future release. |=== @@ -112,87 +112,515 @@ describes all functional requirements of the puzzle box. |=== | ID | Pri. | Specification -| 1. | M -| The dimensions of the puzzle box are 30×30×30cm ± 5% (Length × Width × Height). +| 001 | <> | +The dimensions of the puzzle box are 30×30×30cm ± 5% (Length × Width × Height). -| 2. | M -| The puzzle box extends a maximum of 5cm on the sides and the top. +| 002 | <> | +The puzzle box extends a maximum of 5cm on the sides and the top. -| 3. | M -| The puzzle box is flat at the bottom. +| 003 | <> | +The puzzle box is flat at the bottom. -| 4. | M -| The puzzle box has a key switch at the bottom of the NeoTrellis puzzle. +| <> | <> | +[[req:4,R-04]] The puzzle box has a key switch at the bottom of the NeoTrellis puzzle. -| 5. | M -| The puzzle box has an indicator LED at the bottom of the NeoTrellis puzzle. +| <> | <> | +[[req:5,R-05]] The puzzle box has an indicator LED at the bottom of the NeoTrellis puzzle. -| 6. | M -| The indicator LED turns green when the system is on and not charging. +| 006 | <> | +The indicator LED turns green when the system is on and not charging. -| 7. | M -| The indicator LED turns blue when the battery is charging. +| 007 | <> | +The indicator LED turns blue when the battery is charging. -| 8. | M -| The indicator LED turns red when the battery does not have enough capacity for the duration of one game and is not charging. +| 008 | <> | +The indicator LED turns red when the battery does not have enough capacity for the duration of one game and is not charging. -| 9. | M -| The puzzle box has a USB-C port at the bottom of the NeoTrellis puzzle for battery charging. +| 009 | <> | +The puzzle box has a USB-C port at the bottom of the NeoTrellis puzzle for battery charging. -| 10. | M -| The puzzle box has a distance sensor at the bottom to detect if it is lifted. +| 010 | <> | +The puzzle box has a distance sensor at the bottom to detect if it is lifted. -| 11. | M -| The puzzle box main board (PCB on the bottom plate) includes a speaker. +| 011 | <> | +The puzzle box main board (PCB on the bottom plate) includes a speaker. -| 12 | W -| When the puzzle box is lifted, the mainboard speaker emits an alarm sound for at least 10 seconds. It stops only when it has been on a table for another 10 seconds (detected by the distance sensor). +| 012 | <> | +When the puzzle box is lifted, the mainboard speaker emits an alarm sound for at least 10 seconds. It stops only when it has been on a table for another 10 seconds (detected by the distance sensor). -| 13. | W -| When the game is completed, the puzzle box produces a victory sound. +| 013 | <> | +When the game is completed, the puzzle box produces a victory sound. -| 14. | W -| Pressing the "identify" button on the web panel causes the indicator LED to blink. +| 014 | <> | +Pressing the "identify" button on the web panel causes the indicator LED to blink. -| 15. | W -| Pressing the "identify" button on the web panel triggers a sound from the speaker. +| 015 | <> | +Pressing the "identify" button on the web panel triggers a sound from the speaker. -| 16. | W -| The game starts once the scheduler time is reached (refer to section 3.7 - [2]). +| 016 | <> | +The game starts once the scheduler time is reached (refer to section 3.7 - [2]). |=== - === The bomb + +.Puzzle box specifications +[cols="1,1,10"] +|=== +| ID | Pri. | Specification + +| 017 | <> | +The bomb includes a 6-digit 7-segment display for showing the remaining playtime. + +| 018 | <> | +The bomb contains a keypad for entering the disarm code. + +| 019 | <> | +The 6-digit 7-segment display turns off when no game is in progress. + +| 020 | <> | +Once the disarm code is entered on the bomb keypad, the game is complete. + +| 021 | <> | +When the game is finished, the bomb emits a victory sound. + +| 022 | <> | +The timer on the bomb counts down from 60:00:00 to 00:00:00. + +| 023 | <> | +Pressing the "identify" button on the web panel causes the indicator LED to blink. + +| 024 | <> | +Pressing the "identify" button on the web panel triggers a sound from the speaker. + +|=== + === The game + +[cols="1,1,10"] +|=== +| 025 | <> | +The game lasts for 1 hour. + +| 026 | <> | +The game should be solvable within the given playtime, without the player having prior knowledge of the game or its mechanics. + +| 027 | <> | +The puzzles should be easy enough to solve without any prior knowledge of the game or its mechanics. + +| 167 | <> | +A puzzle module can manually be reset at the discretion of the game operator + +| 168 | <> | +A puzzle module can manually be set as solved at the discretion of the game operator + +| 028 | <> | +The disarm code for the bomb consists of 4 digits. + +| 029 | <> | +Once all games are solved, the mainboard PCB displays the disarm code on a red 7-segment 4-digit screen. + +| 030 | <> | +The puzzle box records the playtime of each game. + +| 031 | <> | +The puzzle box features 5 playable puzzles. + +| 032 | <> | +Only one game is active at a time; the other games do not respond to buttons. + +| 033 | <> | +The game always starts with the NeoTrellis puzzle. +|=== + ==== NeoTrellis puzzle + +[cols="1,1,10"] +|=== +| 034 | <> | +There is an 8x8 LED matrix where each LED can display different colors. + +| 035 | <> | +At the start of the puzzle, a pattern is displayed as shown in Figure 4. + +| 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). + +| 037 | <> | +All LEDs in the Neotrellis that are turned on are blue. + +| 038 | <> | +The puzzle is considered solved when all LEDs are turned off, and then the software puzzle starts. +|=== + ==== Software puzzle + +[cols="1,1,10"] +|=== +| 039 | <> | +The software puzzle board has 6 banana plug connectors with different logic gates displayed next to them (Refer to Figure 5 for a sketch and Figure 7 for a banana plug example). + +| 040 | <> | +The software puzzle board has 6 banana plug connectors labeled with the letters A through F (Refer to Figure 5 for a sketch). + +| 041 | <> | +At the start of the puzzle box game, the preparer must connect all cables in parallel (horizontally) to the connectors. + +| 042 | <> | +There are C code blocks visible only to the players on the bomb side, corresponding to the letters A through F (Refer to Figure 6 for the codes). + +| 043 | <> | +The combinations of logic gates to letters are always the same. + +| 044 | <> | +The puzzle is considered solved when the cables from the logic gates match the code blocks (Refer to Figure 5 and Figure 6 for the combinations). + +| 045 | <> | +Once the puzzle is solved, the green indicator LED will light up (Refer to Figure 5 and Figure 6). + +| 046 | <> | +After the puzzle is solved, the automation puzzle begins. +|=== + ==== Automation puzzle + +[cols="1,1,10"] +|=== +| 047 | <> | +After the puzzle is solved, the hardware puzzle begins. +|=== + ==== Hardware puzzle + +[cols="1,1,10"] +|=== +| 048 | <> | +There are eight switches on the hardware puzzle board. + +| 049 | <> | +The hardware puzzle board features a diagram of a combinatorial circuit with 8 inputs (linked to the switches) and 1 output (Refer to Figure 8 for a sketch). + +| 050 | <> | +The hardware puzzle board includes a red 7-segment 4-digit display (Refer to Figure 8 for a sketch). + +| 051 | <> | +There are 4 potentiometers on the hardware puzzle board (Refer to Figure 8 for a sketch). + +| 052 | <> | +A blue LED on the hardware puzzle board displays the morse code. + +| 053 | <> | +A green LED on the hardware puzzle board indicates whether the combinatorial circuit is solved. + +| 054 | <> | +At the start of the puzzle, the potentiometers are inactive. + +| 055 | <> | +The 7-segment display is off at the beginning of the puzzle. + +| 056 | <> | +The LED for the combinatorial puzzle is off initially. + +| 057 | <> | +The morse code LED is off at the puzzle's outset. + +| 058 | <> | +The preparer must set all switches to the down position at the start of the puzzle box game. + +| 059 | <> | +The preparer must turn all potentiometers to the left (value '0') at the beginning of the puzzle box game. + +| 060 | <> | +The puzzle consists of two phases. + +| 061 | <> | +The puzzle begins in phase 1. + +| 062 | <> | +During the puzzle, the switches must be toggled to obtain a logical '1' at the output of the combinatorial circuit. + +| 063 | <> | +When the output of the combinatorial circuit equals '1', the green indicator LED turns on (Refer to Figure 8 for a sketch). + +| 064 | <> | +The puzzle proceeds to phase 2 when the output of the combinatorial circuit is a logical '1'. + +| 065 | <> | +The switches no longer respond once the puzzle enters phase 2. + +| 066 | <> | +The indicator LED from phase 1 remains green during phase 2. + +| 067 | <> | +In phase 2, a morse code is displayed using an LED. This morse code represents 4 numbers from 0 to 9 and repeats every second. + +| 068 | <> | +The morse code is randomly generated. + +| 069 | <> | +Each potentiometer can be rotated to display a value from 0 to 9 on the corresponding 4-digit 7-segment display. The order of the potentiometers matches the order of the segments on the display (Refer to Figure 8 for a sketch). + +| 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. + +| 071 | <> | +Once the puzzle is solved, the value shown on the 7-segment 4-digit display cannot be changed. + +| 072 | <> | +A 2-second victory sound is produced by the speaker upon solving the puzzle. + +| 073 | <> | +During the victory sound, the 7-segment display blinks twice per second. + +| 074 | <> | +After the victory sound, the puzzle has been solved and the vault puzzle begins. +|=== + ==== Vault puzzle + +[cols="1,1,10"] +|=== +| 075 | <> | +The vault puzzle board features a red 7-segment 4-digit display. + +| 076 | <> | +On the vault puzzle board, there is a 4x4 grid of holes for ventilation and sound. + +| 077 | <> | +The vault puzzle board includes a vault door, and the inside of the vault is transparent, allowing you to see inside the puzzle box. + +| 078 | <> | +A sensor is integrated with the vault to detect when the vault is closed. + +| 079 | <> | +At the beginning of the puzzle box game, the preparer must close the vault. + +| 080 | <> | +The puzzle starts at level 1. + +| 081 | <> | +Initially, the 7-segment display shows a code consisting of a letter and a digit. This code represents a valid key combination for level 1 (Refer to Figure 9 for all combinations). + +| 082 | <> | +There are a total of 5 levels. After each level, a key combination is displayed, starting with a letter followed by a digit, which is valid for that level (Refer to Figure 9). + +| 083 | <> | +Each level has unique key combinations for the button locations (Refer to Figure 9). + +| 084 | <> | +Pressing the button corresponding to the letter-digit combinations advances the puzzle to the next level. + +| 085 | <> | +If an incorrect button is pressed, the game resets to level 1. + +| 086 | <> | +An error sound is produced by the speaker when an incorrect button is pressed. + +| 087 | <> | +The 7-segment display blinks when an incorrect button is pressed. + +| 088 | <> | +After completing 5 levels, the puzzle is solved, and the vault opens. +|=== + === Battery + +[cols="1,1,10"] +|=== +| 089 | <> | +The puzzle box is powered by a rechargeable battery. + +| 090 | <> | +The battery lasts for a minimum of 4 hours. + +| 091 | <> | +The battery in the puzzle box can be replaced. +|=== + === Network Communication + +[cols="1,1,10"] +|=== +| 092 | <> | +The puzzle boxes, bombs, and the puzzle box hub must all be able to communicate with each other. + +| 093 | <> | +Communication between two devices in the network must have a range of at least 20 meters in an open field. +|=== + === Framework + +[cols="1,1,10"] +|=== +| 130 | <> | +The main controller and its software do not need to be modified to implement a new puzzle module + +| 131 | <> | +Puzzle modules can be added and removed while the main controller is powered on + +| 132 | <> | +Puzzle modules can be added and removed while the main controller is powered off + +| 133 | <> | +The puzzle box provides a single external interface for accessing and controlling game state variables +|=== + === Puzzle box hub +[cols="1,1,10"] +|=== +| 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 + +[cols="1,1,10"] +|=== +| 127 | <> | +The wireless communication between the system controller, bomb, and puzzle box operates over a WiFi mesh or WiFi network. +|=== + === Framework + +[cols="1,1,10"] +|=== +| 128 | <> | +A framework has been created to assist future groups in the development of the puzzle box. + +| 129 | <> | +The framework runs on the main puzzle box controller. + +| 134 | <> | +Puzzle modules are detected by the main controller module. + +| 135 | <> | +Puzzle modules are initialized by the main controller module. + +| 165 | <> | +Puzzle modules repeatedly send 'update' messages to the main controller while their global state is 'uninitialized' +|=== + === Main controller + +[cols="1,1,10"] +|=== +| 136 | <> | +The main controller has at least 1 I2C peripheral. + +| 137 | <> | +The main controller can connect to a standard 802.11b/g/n access point. + +| 138 | <> | +The main controller can serve TCP socket connection(s). + +| 139 | <> | +The main controller is available as a development kit from Farnell. + +| 140 | <> | +The main controller can communicate over I²C with a speed of 400kb/s + +| 166 | <> | +The main controller is power efficient. +|=== + === Puzzle module controller + +[cols="1,1,10"] +|=== +| 141 | <> | +The puzzle module controller has at least 1 I2C peripheral. + +| 142 | <> | +The puzzle module controller has enough I/O ports to control a puzzle. + +| 143 | <> | +The puzzle module is power efficient. + +| 144 | <> | +The puzzle module has a configurable clock speed. + +| 145 | <> | +The puzzle module controller is available as a development kit from Farnell. + +| 146 | <> | +The puzzle module can communicate over I²C with a speed of 400kb/s +|=== + === Vault puzzle + +[cols="1,1,10"] +|=== +| 147 | <> | +The vault puzzle can communicate with the main controller using I²C + +| 148 | <> | +The vault puzzle can produce a sound signal for the buzzer + +| 149 | <> | +The vault puzzle can lock & unlock a solenoid lock + +| 150 | <> | +The vault puzzle can translate and obtain a button press from the 3x4 keypad using 5 inputs + +| 151 | <> | +The vault puzzle can communicate with a 4x 7 SEG. Display using 2 lines (clock & data) + +| 152 | <> | +The vault puzzle can read a sensor's value to detect if the vault door is open or closed. +|=== + === Bomb + +[cols="1,1,10"] +|=== +| 153 | <> | +The bomb can communicate with the hub using a TCP socket connection + +| 154 | <> | +The bomb can sync. time using the WiFi connection + +| 155 | <> | +The bomb can retrieve, and store a given code in order to verify it later on input + +| 156 | <> | +The bomb can be paired to a puzzlebox using the hub's interface +|=== + == Preconditions + +[cols="1,11"] +|=== +| 160 | The delivery of components cannot take longer than two weeks. +| 161 | The price of a single puzzle box is not higher than €150. +| 162 | The existing games are used in the puzzle box. +| 163 | The puzzle box is not allowed to make a connection with the Avans network (Eduroam). +| 164 | The bomb hardware cannot be changed. +|=== + == Documentation +[cols="1,1,10"] +|=== +| 157 | <> | +All documentation is written according to the style guide [3] + +| 158 | <> | +All documentation is manually checked for spelling and grammar mistakes before being published + +| 159 | <> | +All project documents are examined once by Jonathan Overes from Avans +|=== + [appendix] == Explanatory Images -// [#alinea1,reftext='alinea 1'] -// Hoi ik ben een alinea -// -// <> - include::share/footer.adoc[] diff --git a/docs/share/glossary.adoc b/docs/share/glossary.adoc index 5ba8340..b0192a0 100644 --- a/docs/share/glossary.adoc +++ b/docs/share/glossary.adoc @@ -3,4 +3,7 @@ [glossary] RPI:: Raspberry Pi +Main board:: The main board is the PCB on the bottom of the puzzle box, this communicates with the puzzles and the bomb +Puzzle box hub:: The puzzle box hub communicates with the puzzle box and the bomb, as well as helps with configuring them +SID:: security identifiers -- cgit v1.2.3 From 75f953cc96f09a5693672552b0ba0f53173b0262 Mon Sep 17 00:00:00 2001 From: lonkaars Date: Fri, 19 Apr 2024 16:14:31 +0200 Subject: finish requirements document --- docs/img/requirements/hardware-example.png | Bin 0 -> 94788 bytes docs/img/requirements/neotrellis-hardware.png | Bin 0 -> 71544 bytes docs/img/requirements/neotrellis-start.png | Bin 0 -> 3078 bytes docs/img/requirements/neotrellis-toggle.png | Bin 0 -> 22898 bytes docs/img/requirements/software-cable.png | Bin 0 -> 33947 bytes docs/img/requirements/software-codes.png | Bin 0 -> 34224 bytes docs/img/requirements/software-example.png | Bin 0 -> 25814 bytes docs/img/requirements/vault-disp.png | Bin 0 -> 27965 bytes docs/img/requirements/vault-keypad.png | Bin 0 -> 75409 bytes docs/readme.md | 6 +- docs/requirements.adoc | 637 +++++++++++++++----------- 11 files changed, 370 insertions(+), 273 deletions(-) create mode 100644 docs/img/requirements/hardware-example.png create mode 100644 docs/img/requirements/neotrellis-hardware.png create mode 100644 docs/img/requirements/neotrellis-start.png create mode 100644 docs/img/requirements/neotrellis-toggle.png create mode 100644 docs/img/requirements/software-cable.png create mode 100644 docs/img/requirements/software-codes.png create mode 100644 docs/img/requirements/software-example.png create mode 100644 docs/img/requirements/vault-disp.png create mode 100644 docs/img/requirements/vault-keypad.png diff --git a/docs/img/requirements/hardware-example.png b/docs/img/requirements/hardware-example.png new file mode 100644 index 0000000..e6ba035 Binary files /dev/null and b/docs/img/requirements/hardware-example.png differ diff --git a/docs/img/requirements/neotrellis-hardware.png b/docs/img/requirements/neotrellis-hardware.png new file mode 100644 index 0000000..692cd91 Binary files /dev/null and b/docs/img/requirements/neotrellis-hardware.png differ diff --git a/docs/img/requirements/neotrellis-start.png b/docs/img/requirements/neotrellis-start.png new file mode 100644 index 0000000..64fc328 Binary files /dev/null and b/docs/img/requirements/neotrellis-start.png differ diff --git a/docs/img/requirements/neotrellis-toggle.png b/docs/img/requirements/neotrellis-toggle.png new file mode 100644 index 0000000..b83b8cf Binary files /dev/null and b/docs/img/requirements/neotrellis-toggle.png differ diff --git a/docs/img/requirements/software-cable.png b/docs/img/requirements/software-cable.png new file mode 100644 index 0000000..36efbda Binary files /dev/null and b/docs/img/requirements/software-cable.png differ diff --git a/docs/img/requirements/software-codes.png b/docs/img/requirements/software-codes.png new file mode 100644 index 0000000..3d6f946 Binary files /dev/null and b/docs/img/requirements/software-codes.png differ diff --git a/docs/img/requirements/software-example.png b/docs/img/requirements/software-example.png new file mode 100644 index 0000000..7e4e6a9 Binary files /dev/null and b/docs/img/requirements/software-example.png differ diff --git a/docs/img/requirements/vault-disp.png b/docs/img/requirements/vault-disp.png new file mode 100644 index 0000000..95ac43a Binary files /dev/null and b/docs/img/requirements/vault-disp.png differ diff --git a/docs/img/requirements/vault-keypad.png b/docs/img/requirements/vault-keypad.png new file mode 100644 index 0000000..43ed5fd Binary files /dev/null and b/docs/img/requirements/vault-keypad.png differ diff --git a/docs/readme.md b/docs/readme.md index efcf30d..bf7eafe 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -8,15 +8,15 @@ makefile is provided for convenience. ## TODO - transfer documents - - [ ] project plan - - [ ] requirements + - [x] project plan + - [x] requirements - [ ] research - [ ] software design - xrefs for-- - [x] tables - [x] figures - [x] section numbers (headings) - - [ ] requirements + - [x] requirements - [x] figures - [x] citations - [ ] glossary diff --git a/docs/requirements.adoc b/docs/requirements.adoc index 2170484..d678ad7 100644 --- a/docs/requirements.adoc +++ b/docs/requirements.adoc @@ -110,366 +110,399 @@ describes all functional requirements of the puzzle box. .Puzzle box specifications [cols="1,1,10"] |=== -| ID | Pri. | Specification +| ID | <> | Specification -| 001 | <> | -The dimensions of the puzzle box are 30×30×30cm ± 5% (Length × Width × Height). +| <> | <> | +[[req:001,R-001]] The dimensions of the puzzle box are 30×30×30cm ± 5% (Length × Width × Height). -| 002 | <> | -The puzzle box extends a maximum of 5cm on the sides and the top. +| <> | <> | +[[req:002,R-002]] The puzzle box extends a maximum of 5cm on the sides and the top. -| 003 | <> | -The puzzle box is flat at the bottom. +| <> | <> | +[[req:003,R-003]] The puzzle box is flat at the bottom. -| <> | <> | -[[req:4,R-04]] The puzzle box has a key switch at the bottom of the NeoTrellis puzzle. +| <> | <> | +[[req:004,R-004]] The puzzle box has a key switch at the bottom of the NeoTrellis puzzle. -| <> | <> | -[[req:5,R-05]] The puzzle box has an indicator LED at the bottom of the NeoTrellis puzzle. +| <> | <> | +[[req:005,R-005]] The puzzle box has an indicator LED at the bottom of the NeoTrellis puzzle. -| 006 | <> | -The indicator LED turns green when the system is on and not charging. +| <> | <> | +[[req:006,R-006]] The indicator LED turns green when the system is on and not charging. -| 007 | <> | -The indicator LED turns blue when the battery is charging. +| <> | <> | +[[req:007,R-007]] The indicator LED turns blue when the battery is charging. -| 008 | <> | -The indicator LED turns red when the battery does not have enough capacity for the duration of one game and is not charging. +| <> | <> | +[[req:008,R-008]] The indicator LED turns red when the battery does not have enough capacity for the duration of one game and is not charging. -| 009 | <> | -The puzzle box has a USB-C port at the bottom of the NeoTrellis puzzle for battery charging. +| <> | <> | +[[req:009,R-009]] The puzzle box has a USB-C port at the bottom of the NeoTrellis puzzle for battery charging. -| 010 | <> | -The puzzle box has a distance sensor at the bottom to detect if it is lifted. +| <> | <> | +[[req:010,R-010]] The puzzle box has a distance sensor at the bottom to detect if it is lifted. -| 011 | <> | -The puzzle box main board (PCB on the bottom plate) includes a speaker. +| <> | <> | +[[req:011,R-011]] The puzzle box main board (PCB on the bottom plate) includes a speaker. -| 012 | <> | -When the puzzle box is lifted, the mainboard speaker emits an alarm sound for at least 10 seconds. It stops only when it has been on a table for another 10 seconds (detected by the distance sensor). +| <> | <> | +[[req:012,R-012]] When the puzzle box is lifted, the mainboard speaker emits an alarm sound for at least 10 seconds. It stops only when it has been on a table for another 10 seconds (detected by the distance sensor). -| 013 | <> | -When the game is completed, the puzzle box produces a victory sound. +| <> | <> | +[[req:013,R-013]] When the game is completed, the puzzle box produces a victory sound. -| 014 | <> | -Pressing the "identify" button on the web panel causes the indicator LED to blink. +| <> | <> | +[[req:014,R-014]] Pressing the "identify" button on the web panel causes the indicator LED to blink. -| 015 | <> | -Pressing the "identify" button on the web panel triggers a sound from the speaker. +| <> | <> | +[[req:015,R-015]] Pressing the "identify" button on the web panel triggers a sound from the speaker. -| 016 | <> | -The game starts once the scheduler time is reached (refer to section 3.7 - [2]). +| <> | <> | +// section 3.7 is inside the citation, and does not refer to section 3.7 in this document +[[req:016,R-016]] The game starts once the scheduler time is reached (refer to cite:[Bek23] section 3.7). |=== === The bomb -.Puzzle box specifications +.Bomb specifications [cols="1,1,10"] |=== -| ID | Pri. | Specification +| ID | <> | Specification -| 017 | <> | -The bomb includes a 6-digit 7-segment display for showing the remaining playtime. +| <> | <> | +[[req:017,R-017]] The bomb includes a 6-digit 7-segment display for showing the remaining playtime. -| 018 | <> | -The bomb contains a keypad for entering the disarm code. +| <> | <> | +[[req:018,R-018]] The bomb contains a keypad for entering the disarm code. -| 019 | <> | -The 6-digit 7-segment display turns off when no game is in progress. +| <> | <> | +[[req:019,R-019]] The 6-digit 7-segment display turns off when no game is in progress. -| 020 | <> | -Once the disarm code is entered on the bomb keypad, the game is complete. +| <> | <> | +[[req:020,R-020]] Once the disarm code is entered on the bomb keypad, the game is complete. -| 021 | <> | -When the game is finished, the bomb emits a victory sound. +| <> | <> | +[[req:021,R-021]] When the game is finished, the bomb emits a victory sound. -| 022 | <> | -The timer on the bomb counts down from 60:00:00 to 00:00:00. +| <> | <> | +[[req:022,R-022]] The timer on the bomb counts down from 60:00:00 to 00:00:00. -| 023 | <> | -Pressing the "identify" button on the web panel causes the indicator LED to blink. +| <> | <> | +[[req:023,R-023]] Pressing the "identify" button on the web panel causes the indicator LED to blink. -| 024 | <> | -Pressing the "identify" button on the web panel triggers a sound from the speaker. +| <> | <> | +[[req:024,R-024]] Pressing the "identify" button on the web panel triggers a sound from the speaker. |=== === The game +.General game specifications [cols="1,1,10"] |=== -| 025 | <> | -The game lasts for 1 hour. +| ID | <> | Specification + +| <> | <> | +[[req:025,R-025]] The game lasts for 1 hour. -| 026 | <> | -The game should be solvable within the given playtime, without the player having prior knowledge of the game or its mechanics. +| <> | <> | +[[req:026,R-026]] The game should be solvable within the given playtime, without the player having prior knowledge of the game or its mechanics. -| 027 | <> | -The puzzles should be easy enough to solve without any prior knowledge of the game or its mechanics. +| <> | <> | +[[req:027,R-027]] The puzzles should be easy enough to solve without any prior knowledge of the game or its mechanics. -| 167 | <> | -A puzzle module can manually be reset at the discretion of the game operator +| <> | <> | +[[req:167,R-167]] A puzzle module can manually be reset at the discretion of the game operator -| 168 | <> | -A puzzle module can manually be set as solved at the discretion of the game operator +| <> | <> | +[[req:168,R-168]] A puzzle module can manually be set as solved at the discretion of the game operator -| 028 | <> | -The disarm code for the bomb consists of 4 digits. +| <> | <> | +[[req:028,R-028]] The disarm code for the bomb consists of 4 digits. -| 029 | <> | -Once all games are solved, the mainboard PCB displays the disarm code on a red 7-segment 4-digit screen. +| <> | <> | +[[req:029,R-029]] Once all games are solved, the mainboard PCB displays the disarm code on a red 7-segment 4-digit screen. -| 030 | <> | -The puzzle box records the playtime of each game. +| <> | <> | +[[req:030,R-030]] The puzzle box records the playtime of each game. -| 031 | <> | -The puzzle box features 5 playable puzzles. +| <> | <> | +[[req:031,R-031]] The puzzle box features 5 playable puzzles. -| 032 | <> | -Only one game is active at a time; the other games do not respond to buttons. +| <> | <> | +[[req:032,R-032]] Only one game is active at a time; the other games do not respond to buttons. -| 033 | <> | -The game always starts with the NeoTrellis puzzle. +| <> | <> | +[[req:033,R-033]] The game always starts with the NeoTrellis puzzle. |=== ==== NeoTrellis puzzle +.NeoTrellis puzzle requirements [cols="1,1,10"] |=== -| 034 | <> | -There is an 8x8 LED matrix where each LED can display different colors. +| ID | <> | Specification -| 035 | <> | -At the start of the puzzle, a pattern is displayed as shown in Figure 4. +| <> | <> | +[[req:034,R-034]] There is an 8x8 LED matrix where each LED can display different colors. -| 036 | <> | -When a button is pressed, the adjacent LEDs and the pressed LED toggle (If an LED is off, it turns on. If an LED is on, it turns off). +| <> | <> | +[[req:035,R-035]] At the start of the puzzle, a pattern is displayed as shown in <>. -| 037 | <> | -All LEDs in the Neotrellis that are turned on are blue. +| <> | <> | +[[req:036,R-036]] When a button is pressed, the adjacent LEDs and the pressed LED toggle (If an LED is off, it turns on. If an LED is on, it turns off). -| 038 | <> | -The puzzle is considered solved when all LEDs are turned off, and then the software puzzle starts. +| <> | <> | +[[req:037,R-037]] All LEDs in the Neotrellis that are turned on are blue. + +| <> | <> | +[[req:038,R-038]] The puzzle is considered solved when all LEDs are turned off, and then the software puzzle starts. |=== ==== Software puzzle +.Software puzzle requirements [cols="1,1,10"] |=== -| 039 | <> | -The software puzzle board has 6 banana plug connectors with different logic gates displayed next to them (Refer to Figure 5 for a sketch and Figure 7 for a banana plug example). +| ID | <> | Specification + +| <> | <> | +[[req:039,R-039]] The software puzzle board has 6 banana plug connectors with different logic gates displayed next to them (Refer to <> for a sketch and <> for a banana plug example). -| 040 | <> | -The software puzzle board has 6 banana plug connectors labeled with the letters A through F (Refer to Figure 5 for a sketch). +| <> | <> | +[[req:040,R-040]] The software puzzle board has 6 banana plug connectors labeled with the letters A through F (Refer to <> for a sketch). -| 041 | <> | -At the start of the puzzle box game, the preparer must connect all cables in parallel (horizontally) to the connectors. +| <> | <> | +[[req:041,R-041]] At the start of the puzzle box game, the preparer must connect all cables in parallel (horizontally) to the connectors. -| 042 | <> | -There are C code blocks visible only to the players on the bomb side, corresponding to the letters A through F (Refer to Figure 6 for the codes). +| <> | <> | +[[req:042,R-042]] There are C code blocks visible only to the players on the bomb side, corresponding to the letters A through F (Refer to <> for the codes). -| 043 | <> | -The combinations of logic gates to letters are always the same. +| <> | <> | +[[req:043,R-043]] The combinations of logic gates to letters are always the same. -| 044 | <> | -The puzzle is considered solved when the cables from the logic gates match the code blocks (Refer to Figure 5 and Figure 6 for the combinations). +| <> | <> | +[[req:044,R-044]] The puzzle is considered solved when the cables from the logic gates match the code blocks (Refer to <> and <> for the combinations). -| 045 | <> | -Once the puzzle is solved, the green indicator LED will light up (Refer to Figure 5 and Figure 6). +| <> | <> | +[[req:045,R-045]] Once the puzzle is solved, the green indicator LED will light up (Refer to <> and <>). -| 046 | <> | -After the puzzle is solved, the automation puzzle begins. +| <> | <> | +[[req:046,R-046]] After the puzzle is solved, the automation puzzle begins. |=== ==== Automation puzzle +The specific details for this puzzle are not present in the previous +documentation. Due to time constraints, the section will be left empty. + +.Automation puzzle requirements [cols="1,1,10"] |=== -| 047 | <> | -After the puzzle is solved, the hardware puzzle begins. +| ID | <> | Specification + +| <> | <> | +[[req:047,R-047]] After the puzzle is solved, the hardware puzzle begins. |=== ==== Hardware puzzle +.Hardware puzzle requirements [cols="1,1,10"] |=== -| 048 | <> | -There are eight switches on the hardware puzzle board. +| ID | <> | Specification -| 049 | <> | -The hardware puzzle board features a diagram of a combinatorial circuit with 8 inputs (linked to the switches) and 1 output (Refer to Figure 8 for a sketch). +| <> | <> | +[[req:048,R-048]] There are eight switches on the hardware puzzle board. -| 050 | <> | -The hardware puzzle board includes a red 7-segment 4-digit display (Refer to Figure 8 for a sketch). +| <> | <> | +[[req:049,R-049]] The hardware puzzle board features a diagram of a combinatorial circuit with 8 inputs (linked to the switches) and 1 output (Refer to <> for a sketch). -| 051 | <> | -There are 4 potentiometers on the hardware puzzle board (Refer to Figure 8 for a sketch). +| <> | <> | +[[req:050,R-050]] The hardware puzzle board includes a red 7-segment 4-digit display (Refer to <> for a sketch). -| 052 | <> | -A blue LED on the hardware puzzle board displays the morse code. +| <> | <> | +[[req:051,R-051]] There are 4 potentiometers on the hardware puzzle board (Refer to <> for a sketch). -| 053 | <> | -A green LED on the hardware puzzle board indicates whether the combinatorial circuit is solved. +| <> | <> | +[[req:052,R-052]] A blue LED on the hardware puzzle board displays the morse code. -| 054 | <> | -At the start of the puzzle, the potentiometers are inactive. +| <> | <> | +[[req:053,R-053]] A green LED on the hardware puzzle board indicates whether the combinatorial circuit is solved. -| 055 | <> | -The 7-segment display is off at the beginning of the puzzle. +| <> | <> | +[[req:054,R-054]] At the start of the puzzle, the potentiometers are inactive. -| 056 | <> | -The LED for the combinatorial puzzle is off initially. +| <> | <> | +[[req:055,R-055]] The 7-segment display is off at the beginning of the puzzle. -| 057 | <> | -The morse code LED is off at the puzzle's outset. +| <> | <> | +[[req:056,R-056]] The LED for the combinatorial puzzle is off initially. -| 058 | <> | -The preparer must set all switches to the down position at the start of the puzzle box game. +| <> | <> | +[[req:057,R-057]] The morse code LED is off at the puzzle's outset. -| 059 | <> | -The preparer must turn all potentiometers to the left (value '0') at the beginning of the puzzle box game. +| <> | <> | +[[req:058,R-058]] The preparer must set all switches to the down position at the start of the puzzle box game. -| 060 | <> | -The puzzle consists of two phases. +| <> | <> | +[[req:059,R-059]] The preparer must turn all potentiometers to the left (value '0') at the beginning of the puzzle box game. -| 061 | <> | -The puzzle begins in phase 1. +| <> | <> | +[[req:060,R-060]] The puzzle consists of two phases. -| 062 | <> | -During the puzzle, the switches must be toggled to obtain a logical '1' at the output of the combinatorial circuit. +| <> | <> | +[[req:061,R-061]] The puzzle begins in phase 1. -| 063 | <> | -When the output of the combinatorial circuit equals '1', the green indicator LED turns on (Refer to Figure 8 for a sketch). +| <> | <> | +[[req:062,R-062]] During the puzzle, the switches must be toggled to obtain a logical '1' at the output of the combinatorial circuit. -| 064 | <> | -The puzzle proceeds to phase 2 when the output of the combinatorial circuit is a logical '1'. +| <> | <> | +[[req:063,R-063]] When the output of the combinatorial circuit equals '1', the green indicator LED turns on (Refer to <> for a sketch). -| 065 | <> | -The switches no longer respond once the puzzle enters phase 2. +| <> | <> | +[[req:064,R-064]] The puzzle proceeds to phase 2 when the output of the combinatorial circuit is a logical '1'. -| 066 | <> | -The indicator LED from phase 1 remains green during phase 2. +| <> | <> | +[[req:065,R-065]] The switches no longer respond once the puzzle enters phase 2. -| 067 | <> | -In phase 2, a morse code is displayed using an LED. This morse code represents 4 numbers from 0 to 9 and repeats every second. +| <> | <> | +[[req:066,R-066]] The indicator LED from phase 1 remains green during phase 2. -| 068 | <> | -The morse code is randomly generated. +| <> | <> | +[[req:067,R-067]] In phase 2, a morse code is displayed using an LED. This morse code represents 4 numbers from 0 to 9 and repeats every second. -| 069 | <> | -Each potentiometer can be rotated to display a value from 0 to 9 on the corresponding 4-digit 7-segment display. The order of the potentiometers matches the order of the segments on the display (Refer to Figure 8 for a sketch). +| <> | <> | +[[req:068,R-068]] The morse code is randomly generated. -| 070 | <> | -The puzzle is considered solved when the code displayed on the 7-segment 4-digit screen matches the 4 numbers from the morse code. +| <> | <> | +[[req:069,R-069]] Each potentiometer can be rotated to display a value from 0 to 9 on the corresponding 4-digit 7-segment display. The order of the potentiometers matches the order of the segments on the display (Refer to <> for a sketch). -| 071 | <> | -Once the puzzle is solved, the value shown on the 7-segment 4-digit display cannot be changed. +| <> | <> | +[[req:070,R-070]] The puzzle is considered solved when the code displayed on the 7-segment 4-digit screen matches the 4 numbers from the morse code. -| 072 | <> | -A 2-second victory sound is produced by the speaker upon solving the puzzle. +| <> | <> | +[[req:071,R-071]] Once the puzzle is solved, the value shown on the 7-segment 4-digit display cannot be changed. -| 073 | <> | -During the victory sound, the 7-segment display blinks twice per second. +| <> | <> | +[[req:072,R-072]] A 2-second victory sound is produced by the speaker upon solving the puzzle. -| 074 | <> | -After the victory sound, the puzzle has been solved and the vault puzzle begins. +| <> | <> | +[[req:073,R-073]] During the victory sound, the 7-segment display blinks twice per second. + +| <> | <> | +[[req:074,R-074]] After the victory sound, the puzzle has been solved and the vault puzzle begins. |=== ==== Vault puzzle +.Vault puzzle requirements [cols="1,1,10"] |=== -| 075 | <> | -The vault puzzle board features a red 7-segment 4-digit display. +| ID | <> | Specification + +| <> | <> | +[[req:075,R-075]] The vault puzzle board features a red 7-segment 4-digit display. -| 076 | <> | -On the vault puzzle board, there is a 4x4 grid of holes for ventilation and sound. +| <> | <> | +[[req:076,R-076]] On the vault puzzle board, there is a 4x4 grid of holes for ventilation and sound. -| 077 | <> | -The vault puzzle board includes a vault door, and the inside of the vault is transparent, allowing you to see inside the puzzle box. +| <> | <> | +[[req:077,R-077]] The vault puzzle board includes a vault door, and the inside of the vault is transparent, allowing you to see inside the puzzle box. -| 078 | <> | -A sensor is integrated with the vault to detect when the vault is closed. +| <> | <> | +[[req:078,R-078]] A sensor is integrated with the vault to detect when the vault is closed. -| 079 | <> | -At the beginning of the puzzle box game, the preparer must close the vault. +| <> | <> | +[[req:079,R-079]] At the beginning of the puzzle box game, the preparer must close the vault. -| 080 | <> | -The puzzle starts at level 1. +| <> | <> | +[[req:080,R-080]] The puzzle starts at level 1. -| 081 | <> | -Initially, the 7-segment display shows a code consisting of a letter and a digit. This code represents a valid key combination for level 1 (Refer to Figure 9 for all combinations). +| <> | <> | +[[req:081,R-081]] Initially, the 7-segment display shows a code consisting of a letter and a digit. This code represents a valid key combination for level 1 (Refer to <> for all combinations). -| 082 | <> | -There are a total of 5 levels. After each level, a key combination is displayed, starting with a letter followed by a digit, which is valid for that level (Refer to Figure 9). +| <> | <> | +[[req:082,R-082]] There are a total of 5 levels. After each level, a key combination is displayed, starting with a letter followed by a digit, which is valid for that level (Refer to <>). -| 083 | <> | -Each level has unique key combinations for the button locations (Refer to Figure 9). +| <> | <> | +[[req:083,R-083]] Each level has unique key combinations for the button locations (Refer to <>). -| 084 | <> | -Pressing the button corresponding to the letter-digit combinations advances the puzzle to the next level. +| <> | <> | +[[req:084,R-084]] Pressing the button corresponding to the letter-digit combinations advances the puzzle to the next level. -| 085 | <> | -If an incorrect button is pressed, the game resets to level 1. +| <> | <> | +[[req:085,R-085]] If an incorrect button is pressed, the game resets to level 1. -| 086 | <> | -An error sound is produced by the speaker when an incorrect button is pressed. +| <> | <> | +[[req:086,R-086]] An error sound is produced by the speaker when an incorrect button is pressed. -| 087 | <> | -The 7-segment display blinks when an incorrect button is pressed. +| <> | <> | +[[req:087,R-087]] The 7-segment display blinks when an incorrect button is pressed. -| 088 | <> | -After completing 5 levels, the puzzle is solved, and the vault opens. +| <> | <> | +[[req:088,R-088]] After completing 5 levels, the puzzle is solved, and the vault opens. |=== === Battery +.Battery requirements [cols="1,1,10"] |=== -| 089 | <> | -The puzzle box is powered by a rechargeable battery. +| ID | <> | Specification -| 090 | <> | -The battery lasts for a minimum of 4 hours. +| <> | <> | +[[req:089,R-089]] The puzzle box is powered by a rechargeable battery. -| 091 | <> | -The battery in the puzzle box can be replaced. +| <> | <> | +[[req:090,R-090]] The battery lasts for a minimum of 4 hours. + +| <> | <> | +[[req:091,R-091]] The battery in the puzzle box can be replaced. |=== === Network Communication +.Communication requirements [cols="1,1,10"] |=== -| 092 | <> | -The puzzle boxes, bombs, and the puzzle box hub must all be able to communicate with each other. +| ID | <> | Specification + +| <> | <> | +[[req:092,R-092]] The puzzle boxes, bombs, and the puzzle box hub must all be able to communicate with each other. -| 093 | <> | -Communication between two devices in the network must have a range of at least 20 meters in an open field. +| <> | <> | +[[req:093,R-093]] Communication between two devices in the network must have a range of at least 20 meters in an open field. |=== === Framework [cols="1,1,10"] |=== -| 130 | <> | -The main controller and its software do not need to be modified to implement a new puzzle module +| ID | <> | Specification -| 131 | <> | -Puzzle modules can be added and removed while the main controller is powered on +| <> | <> | +[[req:130,R-130]] The main controller and its software do not need to be modified to implement a new puzzle module -| 132 | <> | -Puzzle modules can be added and removed while the main controller is powered off +| <> | <> | +[[req:131,R-131]] Puzzle modules can be added and removed while the main controller is powered on -| 133 | <> | -The puzzle box provides a single external interface for accessing and controlling game state variables +| <> | <> | +[[req:132,R-132]] Puzzle modules can be added and removed while the main controller is powered off + +| <> | <> | +[[req:133,R-133]] The puzzle box provides a single external interface for accessing and controlling game state variables |=== === Puzzle box hub +.Puzzle box hub general requirements [cols="1,1,10"] |=== -| 094 | <> | -The puzzle box hub hosts a website that can be accessed by a device connected to the network. +| ID | <> | Specification + +| <> | <> | +[[req:094,R-094]] The puzzle box hub hosts a website that can be accessed by a device connected to the network. |=== [[sec:technical]] @@ -482,145 +515,209 @@ technical specifications of the puzzle box. === Wireless communication +.Wireless communication requirements [cols="1,1,10"] |=== -| 127 | <> | -The wireless communication between the system controller, bomb, and puzzle box operates over a WiFi mesh or WiFi network. +| ID | <> | Specification + +| <> | <> | +[[req:127,R-127]] The wireless communication between the system controller, bomb, and puzzle box operates over a WiFi mesh or WiFi network. |=== === Framework +.Development framework requirements [cols="1,1,10"] |=== -| 128 | <> | -A framework has been created to assist future groups in the development of the puzzle box. +| ID | <> | Specification + +| <> | <> | +[[req:128,R-128]] A framework has been created to assist future groups in the development of the puzzle box. -| 129 | <> | -The framework runs on the main puzzle box controller. +| <> | <> | +[[req:129,R-129]] The framework runs on the main puzzle box controller. -| 134 | <> | -Puzzle modules are detected by the main controller module. +| <> | <> | +[[req:134,R-134]] Puzzle modules are detected by the main controller module. -| 135 | <> | -Puzzle modules are initialized by the main controller module. +| <> | <> | +[[req:135,R-135]] Puzzle modules are initialized by the main controller module. -| 165 | <> | -Puzzle modules repeatedly send 'update' messages to the main controller while their global state is 'uninitialized' +| <> | <> | +[[req:165,R-165]] Puzzle modules repeatedly send 'update' messages to the main controller while their global state is 'uninitialized' |=== === Main controller +.Main controller requirements [cols="1,1,10"] |=== -| 136 | <> | -The main controller has at least 1 I2C peripheral. +| ID | <> | Specification -| 137 | <> | -The main controller can connect to a standard 802.11b/g/n access point. +| <> | <> | +[[req:136,R-136]] The main controller has at least 1 I2C peripheral. -| 138 | <> | -The main controller can serve TCP socket connection(s). +| <> | <> | +[[req:137,R-137]] The main controller can connect to a standard 802.11b/g/n access point. -| 139 | <> | -The main controller is available as a development kit from Farnell. +| <> | <> | +[[req:138,R-138]] The main controller can serve TCP socket connection(s). -| 140 | <> | -The main controller can communicate over I²C with a speed of 400kb/s +| <> | <> | +[[req:139,R-139]] The main controller is available as a development kit from Farnell. -| 166 | <> | -The main controller is power efficient. +| <> | <> | +[[req:140,R-140]] The main controller can communicate over I²C with a speed of 400kb/s + +| <> | <> | +[[req:166,R-166]] The main controller is power efficient. |=== === Puzzle module controller [cols="1,1,10"] |=== -| 141 | <> | -The puzzle module controller has at least 1 I2C peripheral. +| ID | <> | Specification + +| <> | <> | +[[req:141,R-141]] The puzzle module controller has at least 1 I2C peripheral. -| 142 | <> | -The puzzle module controller has enough I/O ports to control a puzzle. +| <> | <> | +[[req:142,R-142]] The puzzle module controller has enough I/O ports to control a puzzle. -| 143 | <> | -The puzzle module is power efficient. +| <> | <> | +[[req:143,R-143]] The puzzle module is power efficient. -| 144 | <> | -The puzzle module has a configurable clock speed. +| <> | <> | +[[req:144,R-144]] The puzzle module has a configurable clock speed. -| 145 | <> | -The puzzle module controller is available as a development kit from Farnell. +| <> | <> | +[[req:145,R-145]] The puzzle module controller is available as a development kit from Farnell. -| 146 | <> | -The puzzle module can communicate over I²C with a speed of 400kb/s +| <> | <> | +[[req:146,R-146]] The puzzle module can communicate over I²C with a speed of 400kb/s |=== === Vault puzzle +.Vault puzzle requirements [cols="1,1,10"] |=== -| 147 | <> | -The vault puzzle can communicate with the main controller using I²C +| ID | <> | Specification -| 148 | <> | -The vault puzzle can produce a sound signal for the buzzer +| <> | <> | +[[req:147,R-147]] The vault puzzle can communicate with the main controller using I²C -| 149 | <> | -The vault puzzle can lock & unlock a solenoid lock +| <> | <> | +[[req:148,R-148]] The vault puzzle can produce a sound signal for the buzzer -| 150 | <> | -The vault puzzle can translate and obtain a button press from the 3x4 keypad using 5 inputs +| <> | <> | +[[req:149,R-149]] The vault puzzle can lock & unlock a solenoid lock -| 151 | <> | -The vault puzzle can communicate with a 4x 7 SEG. Display using 2 lines (clock & data) +| <> | <> | +[[req:150,R-150]] The vault puzzle can translate and obtain a button press from the 3x4 keypad using 5 inputs -| 152 | <> | -The vault puzzle can read a sensor's value to detect if the vault door is open or closed. +| <> | <> | +[[req:151,R-151]] The vault puzzle can communicate with a 4x 7 SEG. Display using 2 lines (clock & data) + +| <> | <> | +[[req:152,R-152]] The vault puzzle can read a sensor's value to detect if the vault door is open or closed. |=== === Bomb +.Bomb requirements [cols="1,1,10"] |=== -| 153 | <> | -The bomb can communicate with the hub using a TCP socket connection +| ID | <> | Specification + +| <> | <> | +[[req:153,R-153]] The bomb can communicate with the hub using a TCP socket connection -| 154 | <> | -The bomb can sync. time using the WiFi connection +| <> | <> | +[[req:154,R-154]] The bomb can sync. time using the WiFi connection -| 155 | <> | -The bomb can retrieve, and store a given code in order to verify it later on input +| <> | <> | +[[req:155,R-155]] The bomb can retrieve, and store a given code in order to verify it later on input -| 156 | <> | -The bomb can be paired to a puzzlebox using the hub's interface +| <> | <> | +[[req:156,R-156]] The bomb can be paired to a puzzlebox using the hub's interface |=== == Preconditions +This section describes the aspects of the project which have been set as +preconditions and cannot be changed. + +.Preconditions [cols="1,11"] |=== -| 160 | The delivery of components cannot take longer than two weeks. -| 161 | The price of a single puzzle box is not higher than €150. -| 162 | The existing games are used in the puzzle box. -| 163 | The puzzle box is not allowed to make a connection with the Avans network (Eduroam). -| 164 | The bomb hardware cannot be changed. +| ID | Precondition + +| <> | [[req:160,R-160]] The delivery of components cannot take longer than two weeks. +| <> | [[req:161,R-161]] The price of a single puzzle box is not higher than €150. +| <> | [[req:162,R-162]] The existing games are used in the puzzle box. +| <> | [[req:163,R-163]] The puzzle box is not allowed to make a connection with the Avans network (Eduroam). +| <> | [[req:164,R-164]] The bomb hardware cannot be changed. |=== == Documentation +This section lists requirements that apply to documentation produced during +this project. + [cols="1,1,10"] |=== -| 157 | <> | -All documentation is written according to the style guide [3] +| ID | <> | Specification + +| <> | <> | +[[req:157,R-157]] All documentation is written according to the style guide cite:[styleguide] -| 158 | <> | -All documentation is manually checked for spelling and grammar mistakes before being published +| <> | <> | +[[req:158,R-158]] All documentation is manually checked for spelling and grammar mistakes before being published -| 159 | <> | -All project documents are examined once by Jonathan Overes from Avans +| <> | <> | +[[req:159,R-159]] All project documents are examined once by Jonathan Overes from Avans |=== [appendix] == Explanatory Images +[[fig:vault-disp]] +.7 Segment 4 digit screen (sketch) +image::img/requirements/vault-disp.png[] + +[[fig:neotrellis-hardware]] +.NeoTrellis example (sketch) +image::img/requirements/neotrellis-hardware.png[] + +[[fig:neotrellis-toggle]] +.Toggling LEDs after the user pressed on the button (purple dot) +image::img/requirements/neotrellis-toggle.png[width=45%] + +[[fig:neotrellis-start]] +.Starting pattern of the NeoTrellis puzzle +image::img/requirements/neotrellis-start.png[width=45%] + +[[fig:software-example]] +.Software puzzle example with logical ports (left) and letters A through F (right) +image::img/requirements/software-example.png[] + +[[fig:software-codes]] +.The different code fragments corresponding with the letter A through F +image::img/requirements/software-codes.png[height=35%] + +[[fig:software-cable]] +.Software puzzle cable example +image::img/requirements/software-cable.png[] + +[[fig:hardware-example]] +.Hardware puzzle on the puzzle box +image::img/requirements/hardware-example.png[] + +[[fig:vault-keypad]] +.Buttons combinations with level numbers in the top left +image::img/requirements/vault-keypad.png[width=45%] + include::share/footer.adoc[] -- cgit v1.2.3 From 4394f1a0122c81439e648d17c1c0f5855229f74b Mon Sep 17 00:00:00 2001 From: lonkaars Date: Sat, 20 Apr 2024 15:31:58 +0200 Subject: mostly transfer research document --- docs/img/automation-example.png | Bin 0 -> 33537 bytes docs/img/bus-connector.jpg | Bin 0 -> 2928708 bytes docs/img/external-architecture-old.png | Bin 0 -> 36482 bytes docs/img/hardware-example-sketch.png | Bin 0 -> 94788 bytes docs/img/hardware-pcb.jpg | Bin 0 -> 3295631 bytes docs/img/hardware-side.jpg | Bin 0 -> 2924999 bytes docs/img/light-sensor.jpg | Bin 0 -> 2106029 bytes docs/img/main-pcb.jpg | Bin 0 -> 3196425 bytes docs/img/neotrellis-example.png | Bin 0 -> 6859 bytes docs/img/neotrellis-hardware-sketch.png | Bin 0 -> 71544 bytes docs/img/neotrellis-pcb.jpg | Bin 0 -> 3620814 bytes docs/img/neotrellis-side.jpg | Bin 0 -> 2064462 bytes docs/img/neotrellis-start.png | Bin 0 -> 3078 bytes docs/img/neotrellis-toggle.png | Bin 0 -> 22898 bytes docs/img/requirements/hardware-example.png | Bin 94788 -> 0 bytes docs/img/requirements/neotrellis-hardware.png | Bin 71544 -> 0 bytes docs/img/requirements/neotrellis-start.png | Bin 3078 -> 0 bytes docs/img/requirements/neotrellis-toggle.png | Bin 22898 -> 0 bytes docs/img/requirements/software-cable.png | Bin 33947 -> 0 bytes docs/img/requirements/software-codes.png | Bin 34224 -> 0 bytes docs/img/requirements/software-example.png | Bin 25814 -> 0 bytes docs/img/requirements/vault-disp.png | Bin 27965 -> 0 bytes docs/img/requirements/vault-keypad.png | Bin 75409 -> 0 bytes docs/img/software-cable-sketch.png | Bin 0 -> 33947 bytes docs/img/software-codes-sketch.png | Bin 0 -> 34224 bytes docs/img/software-codes.png | Bin 0 -> 54693 bytes docs/img/software-example-sketch.png | Bin 0 -> 25814 bytes docs/img/software-example.png | Bin 0 -> 50387 bytes docs/img/software-pcb.jpg | Bin 0 -> 2867464 bytes docs/img/software-side.jpg | Bin 0 -> 3051226 bytes docs/img/unknown-pcb.jpg | Bin 0 -> 3029716 bytes docs/img/vault-disp-sketch.png | Bin 0 -> 27965 bytes docs/img/vault-interface.png | Bin 0 -> 42493 bytes docs/img/vault-keypad-full.png | Bin 0 -> 288664 bytes docs/img/vault-keypad.png | Bin 0 -> 75409 bytes docs/img/vault-pcb.jpg | Bin 0 -> 2907552 bytes docs/img/vault-side.jpg | Bin 0 -> 2855727 bytes docs/makefile | 1 + docs/plan.adoc | 2 +- docs/readme.md | 9 +- docs/requirements.adoc | 96 ++-- docs/research.adoc | 741 ++++++++++++++++++++++++++ docs/share/glossary.adoc | 2 +- docs/share/meta.adoc | 3 + docs/share/references.adoc | 2 +- docs/share/refs.bib | 3 + docs/theme.yml | 3 + 47 files changed, 809 insertions(+), 53 deletions(-) create mode 100644 docs/img/automation-example.png create mode 100644 docs/img/bus-connector.jpg create mode 100644 docs/img/external-architecture-old.png create mode 100644 docs/img/hardware-example-sketch.png create mode 100644 docs/img/hardware-pcb.jpg create mode 100644 docs/img/hardware-side.jpg create mode 100644 docs/img/light-sensor.jpg create mode 100644 docs/img/main-pcb.jpg create mode 100644 docs/img/neotrellis-example.png create mode 100644 docs/img/neotrellis-hardware-sketch.png create mode 100644 docs/img/neotrellis-pcb.jpg create mode 100644 docs/img/neotrellis-side.jpg create mode 100644 docs/img/neotrellis-start.png create mode 100644 docs/img/neotrellis-toggle.png delete mode 100644 docs/img/requirements/hardware-example.png delete mode 100644 docs/img/requirements/neotrellis-hardware.png delete mode 100644 docs/img/requirements/neotrellis-start.png delete mode 100644 docs/img/requirements/neotrellis-toggle.png delete mode 100644 docs/img/requirements/software-cable.png delete mode 100644 docs/img/requirements/software-codes.png delete mode 100644 docs/img/requirements/software-example.png delete mode 100644 docs/img/requirements/vault-disp.png delete mode 100644 docs/img/requirements/vault-keypad.png create mode 100644 docs/img/software-cable-sketch.png create mode 100644 docs/img/software-codes-sketch.png create mode 100644 docs/img/software-codes.png create mode 100644 docs/img/software-example-sketch.png create mode 100644 docs/img/software-example.png create mode 100644 docs/img/software-pcb.jpg create mode 100644 docs/img/software-side.jpg create mode 100644 docs/img/unknown-pcb.jpg create mode 100644 docs/img/vault-disp-sketch.png create mode 100644 docs/img/vault-interface.png create mode 100644 docs/img/vault-keypad-full.png create mode 100644 docs/img/vault-keypad.png create mode 100644 docs/img/vault-pcb.jpg create mode 100644 docs/img/vault-side.jpg create mode 100644 docs/research.adoc 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 ebcc6e19d2fdddbbce6d3ac93ec9ac29663a1d7e Mon Sep 17 00:00:00 2001 From: lonkaars Date: Sat, 20 Apr 2024 15:53:24 +0200 Subject: give referenced requirements meaningful identifiers + comment TODOs in text --- docs/readme.md | 2 + docs/requirements.adoc | 416 ++++++++++++++++++++++++------------------------- docs/research.adoc | 36 +++-- 3 files changed, 233 insertions(+), 221 deletions(-) diff --git a/docs/readme.md b/docs/readme.md index e58c5fb..c5067b5 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -9,6 +9,8 @@ makefile is provided for convenience. - "I2C" is written as `I^2^C` - "C++" is written as `{cpp}` +- please give cross references, links, image files, figure ids, etc. meaningful + names ## TODO diff --git a/docs/requirements.adoc b/docs/requirements.adoc index 37f914b..e3225a5 100644 --- a/docs/requirements.adoc +++ b/docs/requirements.adoc @@ -112,54 +112,54 @@ describes all functional requirements of the puzzle box. |=== | ID | <> | Specification -| <> | <> | -[[req:001,R-001]] The dimensions of the puzzle box are 30×30×30cm ± 5% (Length × Width × Height). +| <> | <> | +[[req:1,R-001]] The dimensions of the puzzle box are 30×30×30cm ± 5% (Length × Width × Height). -| <> | <> | -[[req:002,R-002]] The puzzle box extends a maximum of 5cm on the sides and the top. +| <> | <> | +[[req:2,R-002]] The puzzle box extends a maximum of 5cm on the sides and the top. -| <> | <> | -[[req:003,R-003]] The puzzle box is flat at the bottom. +| <> | <> | +[[req:3,R-003]] The puzzle box is flat at the bottom. -| <> | <> | -[[req:004,R-004]] The puzzle box has a key switch at the bottom of the NeoTrellis puzzle. +| <> | <> | +[[req:4,R-004]] The puzzle box has a key switch at the bottom of the NeoTrellis puzzle. -| <> | <> | -[[req:005,R-005]] The puzzle box has an indicator LED at the bottom of the NeoTrellis puzzle. +| <> | <> | +[[req:5,R-005]] The puzzle box has an indicator LED at the bottom of the NeoTrellis puzzle. -| <> | <> | -[[req:006,R-006]] The indicator LED turns green when the system is on and not charging. +| <> | <> | +[[req:6,R-006]] The indicator LED turns green when the system is on and not charging. -| <> | <> | -[[req:007,R-007]] The indicator LED turns blue when the battery is charging. +| <> | <> | +[[req:7,R-007]] The indicator LED turns blue when the battery is charging. -| <> | <> | -[[req:008,R-008]] The indicator LED turns red when the battery does not have enough capacity for the duration of one game and is not charging. +| <> | <> | +[[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:009,R-009]] The puzzle box has a USB-C port at the bottom of the NeoTrellis puzzle for battery charging. +| <> | <> | +[[req:9,R-009]] The puzzle box has a USB-C port at the bottom of the NeoTrellis puzzle for battery charging. -| <> | <> | -[[req:010,R-010]] The puzzle box has a distance sensor at the bottom to detect if it is lifted. +| <> | <> | +[[req:10,R-010]] The puzzle box has a distance sensor at the bottom to detect if it is lifted. -| <> | <> | -[[req:011,R-011]] The puzzle box main board (PCB on the bottom plate) includes a speaker. +| <> | <> | +[[req:11,R-011]] The puzzle box main board (PCB on the bottom plate) includes a speaker. -| <> | <> | -[[req:012,R-012]] When the puzzle box is lifted, the mainboard speaker emits an alarm sound for at least 10 seconds. It stops only when it has been on a table for another 10 seconds (detected by the distance sensor). +| <> | <> | +[[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:013,R-013]] When the game is completed, the puzzle box produces a victory sound. +| <> | <> | +[[req:13,R-013]] When the game is completed, the puzzle box produces a victory sound. -| <> | <> | -[[req:014,R-014]] Pressing the "identify" button on the web panel causes the indicator LED to blink. +| <> | <> | +[[req:14,R-014]] Pressing the "identify" button on the web panel causes the indicator LED to blink. -| <> | <> | -[[req:015,R-015]] Pressing the "identify" button on the web panel triggers a sound from the speaker. +| <> | <> | +[[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:016,R-016]] The game starts once the scheduler time is reached (refer to cite:[Bek23] section 3.7). +[[req:16,R-016]] The game starts once the scheduler time is reached (refer to cite:[Bek23] section 3.7). |=== === The bomb @@ -169,29 +169,29 @@ describes all functional requirements of the puzzle box. |=== | ID | <> | Specification -| <> | <> | -[[req:017,R-017]] The bomb includes a 6-digit 7-segment display for showing the remaining playtime. +| <> | <> | +[[req:17,R-017]] The bomb includes a 6-digit 7-segment display for showing the remaining playtime. -| <> | <> | -[[req:018,R-018]] The bomb contains a keypad for entering the disarm code. +| <> | <> | +[[req:18,R-018]] The bomb contains a keypad for entering the disarm code. -| <> | <> | -[[req:019,R-019]] The 6-digit 7-segment display turns off when no game is in progress. +| <> | <> | +[[req:19,R-019]] The 6-digit 7-segment display turns off when no game is in progress. -| <> | <> | -[[req:020,R-020]] Once the disarm code is entered on the bomb keypad, the game is complete. +| <> | <> | +[[req:20,R-020]] Once the disarm code is entered on the bomb keypad, the game is complete. -| <> | <> | -[[req:021,R-021]] When the game is finished, the bomb emits a victory sound. +| <> | <> | +[[req:21,R-021]] When the game is finished, the bomb emits a victory sound. -| <> | <> | -[[req:022,R-022]] The timer on the bomb counts down from 60:00:00 to 00:00:00. +| <> | <> | +[[req:22,R-022]] The timer on the bomb counts down from 60:00:00 to 00:00:00. -| <> | <> | -[[req:023,R-023]] Pressing the "identify" button on the web panel causes the indicator LED to blink. +| <> | <> | +[[req:23,R-023]] Pressing the "identify" button on the web panel causes the indicator LED to blink. -| <> | <> | -[[req:024,R-024]] Pressing the "identify" button on the web panel triggers a sound from the speaker. +| <> | <> | +[[req:24,R-024]] Pressing the "identify" button on the web panel triggers a sound from the speaker. |=== @@ -202,14 +202,14 @@ describes all functional requirements of the puzzle box. |=== | ID | <> | Specification -| <> | <> | -[[req:025,R-025]] The game lasts for 1 hour. +| <> | <> | +[[req:25,R-025]] The game lasts for 1 hour. -| <> | <> | -[[req:026,R-026]] The game should be solvable within the given playtime, without the player having prior knowledge of the game or its mechanics. +| <> | <> | +[[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:027,R-027]] The puzzles should be easy enough to solve without any 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 @@ -217,23 +217,23 @@ describes all functional requirements of the puzzle box. | <> | <> | [[req:168,R-168]] A puzzle module can manually be set as solved at the discretion of the game operator -| <> | <> | -[[req:028,R-028]] The disarm code for the bomb consists of 4 digits. +| <> | <> | +[[req:28,R-028]] The disarm code for the bomb consists of 4 digits. -| <> | <> | -[[req:029,R-029]] Once all games are solved, the mainboard PCB displays the disarm code on a red 7-segment 4-digit screen. +| <> | <> | +[[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:030,R-030]] The puzzle box records the playtime of each game. +| <> | <> | +[[req:30,R-030]] The puzzle box records the playtime of each game. -| <> | <> | -[[req:031,R-031]] The puzzle box features 5 playable puzzles. +| <> | <> | +[[req:31,R-031]] The puzzle box features 5 playable puzzles. -| <> | <> | -[[req:032,R-032]] Only one game is active at a time; the other games do not respond to buttons. +| <> | <> | +[[req:32,R-032]] Only one game is active at a time; the other games do not respond to buttons. -| <> | <> | -[[req:033,R-033]] The game always starts with the NeoTrellis puzzle. +| <> | <> | +[[req:33,R-033]] The game always starts with the NeoTrellis puzzle. |=== ==== NeoTrellis puzzle @@ -243,20 +243,20 @@ describes all functional requirements of the puzzle box. |=== | ID | <> | Specification -| <> | <> | -[[req:034,R-034]] There is an 8x8 LED matrix where each LED can display different colors. +| <> | <> | +[[req:34,R-034]] There is an 8x8 LED matrix where each LED can display different colors. -| <> | <> | -[[req:035,R-035]] At the start of the puzzle, a pattern is displayed as shown in <>. +| <> | <> | +[[req:35,R-035]] At the start of the puzzle, a pattern is displayed as shown in <>. -| <> | <> | -[[req:036,R-036]] When a button is pressed, the adjacent LEDs and the pressed LED toggle (If an LED is off, it turns on. If an LED is on, it turns off). +| <> | <> | +[[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:037,R-037]] All LEDs in the Neotrellis that are turned on are blue. +| <> | <> | +[[req:37,R-037]] All LEDs in the Neotrellis that are turned on are blue. -| <> | <> | -[[req:038,R-038]] The puzzle is considered solved when all LEDs are turned off, and then the software puzzle starts. +| <> | <> | +[[req:38,R-038]] The puzzle is considered solved when all LEDs are turned off, and then the software puzzle starts. |=== ==== Software puzzle @@ -266,29 +266,29 @@ describes all functional requirements of the puzzle box. |=== | 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: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: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: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:041,R-041]] At the start of the puzzle box game, the preparer must connect all cables in parallel (horizontally) to the connectors. +| <> | <> | +[[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: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: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:043,R-043]] The combinations of logic gates to letters are always the same. +| <> | <> | +[[req:43,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: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:045,R-045]] Once the puzzle is solved, the green indicator LED will light up (Refer to <> and <>). +| <> | <> | +[[req:45,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. +| <> | <> | +[[req:46,R-046]] After the puzzle is solved, the automation puzzle begins. |=== ==== Automation puzzle @@ -301,8 +301,8 @@ documentation. Due to time constraints, the section will be left empty. |=== | ID | <> | Specification -| <> | <> | -[[req:047,R-047]] After the puzzle is solved, the hardware puzzle begins. +| <> | <> | +[[req:47,R-047]] After the puzzle is solved, the hardware puzzle begins. |=== ==== Hardware puzzle @@ -312,86 +312,86 @@ documentation. Due to time constraints, the section will be left empty. |=== | ID | <> | Specification -| <> | <> | -[[req:048,R-048]] There are eight switches on the hardware puzzle board. +| <> | <> | +[[req:48,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: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:050,R-050]] The hardware puzzle board includes a red 7-segment 4-digit display (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:051,R-051]] There are 4 potentiometers on the hardware puzzle board (Refer to <> for a sketch). +| <> | <> | +[[req:51,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. +| <> | <> | +[[req:52,R-052]] A blue LED on the hardware puzzle board displays the morse code. -| <> | <> | -[[req:053,R-053]] A green LED on the hardware puzzle board indicates whether the combinatorial circuit is solved. +| <> | <> | +[[req:53,R-053]] A green LED on the hardware puzzle board indicates whether the combinatorial circuit is solved. -| <> | <> | -[[req:054,R-054]] At the start of the puzzle, the potentiometers are inactive. +| <> | <> | +[[req:54,R-054]] At the start of the puzzle, the potentiometers are inactive. -| <> | <> | -[[req:055,R-055]] The 7-segment display is off at the beginning of the puzzle. +| <> | <> | +[[req:55,R-055]] The 7-segment display is off at the beginning of the puzzle. -| <> | <> | -[[req:056,R-056]] The LED for the combinatorial puzzle is off initially. +| <> | <> | +[[req:56,R-056]] The LED for the combinatorial puzzle is off initially. -| <> | <> | -[[req:057,R-057]] The morse code LED is off at the puzzle's outset. +| <> | <> | +[[req:57,R-057]] The morse code LED is off at the puzzle's outset. -| <> | <> | -[[req:058,R-058]] The preparer must set all switches to the down position at the start of the puzzle box game. +| <> | <> | +[[req:58,R-058]] The preparer must set all switches to the down position at the start of the puzzle box game. -| <> | <> | -[[req:059,R-059]] The preparer must turn all potentiometers to the left (value '0') at the beginning 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:060,R-060]] The puzzle consists of two phases. +| <> | <> | +[[req:60,R-060]] The puzzle consists of two phases. -| <> | <> | -[[req:061,R-061]] The puzzle begins in phase 1. +| <> | <> | +[[req:61,R-061]] The puzzle begins in phase 1. -| <> | <> | -[[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:62,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:63,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'. +| <> | <> | +[[req:64,R-064]] The puzzle proceeds to phase 2 when the output of the combinatorial circuit is a logical '1'. -| <> | <> | -[[req:065,R-065]] The switches no longer respond once the puzzle enters phase 2. +| <> | <> | +[[req:65,R-065]] The switches no longer respond once the puzzle enters phase 2. -| <> | <> | -[[req:066,R-066]] The indicator LED from phase 1 remains green during phase 2. +| <> | <> | +[[req:66,R-066]] The indicator LED from phase 1 remains green during phase 2. -| <> | <> | -[[req:067,R-067]] In phase 2, a morse code is displayed using an LED. This morse code represents 4 numbers from 0 to 9 and repeats every second. +| <> | <> | +[[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:068,R-068]] The morse code is randomly generated. +| <> | <> | +[[req:68,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: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: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. +| <> | <> | +[[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:071,R-071]] Once the puzzle is solved, the value shown on the 7-segment 4-digit display cannot be changed. +| <> | <> | +[[req:71,R-071]] Once the puzzle is solved, the value shown on the 7-segment 4-digit display cannot be changed. -| <> | <> | -[[req:072,R-072]] A 2-second victory sound is produced by the speaker upon solving the puzzle. +| <> | <> | +[[req:72,R-072]] A 2-second victory sound is produced by the speaker upon solving the puzzle. -| <> | <> | -[[req:073,R-073]] During the victory sound, the 7-segment display blinks twice per second. +| <> | <> | +[[req:73,R-073]] During the victory sound, the 7-segment display blinks twice per second. -| <> | <> | -[[req:074,R-074]] After the victory sound, the puzzle has been solved and the vault puzzle begins. +| <> | <> | +[[req:74,R-074]] After the victory sound, the puzzle has been solved and the vault puzzle begins. |=== ==== Vault puzzle @@ -401,47 +401,47 @@ documentation. Due to time constraints, the section will be left empty. |=== | ID | <> | Specification -| <> | <> | -[[req:075,R-075]] The vault puzzle board features a red 7-segment 4-digit display. +| <> | <> | +[[req:75,R-075]] The vault puzzle board features a red 7-segment 4-digit display. -| <> | <> | -[[req:076,R-076]] On the vault puzzle board, there is a 4x4 grid of holes for ventilation and sound. +| <> | <> | +[[req:76,R-076]] On the vault puzzle board, there is a 4x4 grid of holes for ventilation and sound. -| <> | <> | -[[req:077,R-077]] The vault puzzle board includes a vault door, and the inside of the vault is transparent, allowing you to see inside the puzzle box. +| <> | <> | +[[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:078,R-078]] A sensor is integrated with the vault to detect when the vault is closed. +| <> | <> | +[[req:78,R-078]] A sensor is integrated with the vault to detect when the vault is closed. -| <> | <> | -[[req:079,R-079]] At the beginning of the puzzle box game, the preparer must close the vault. +| <> | <> | +[[req:79,R-079]] At the beginning of the puzzle box game, the preparer must close the vault. -| <> | <> | -[[req:080,R-080]] The puzzle starts at level 1. +| <> | <> | +[[req:80,R-080]] The puzzle starts at level 1. -| <> | <> | -[[req:081,R-081]] Initially, the 7-segment display shows a code consisting of a letter and a digit. This code represents a valid key combination for level 1 (Refer to <> for all combinations). +| <> | <> | +[[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:082,R-082]] There are a total of 5 levels. After each level, a key combination is displayed, starting with a letter followed by a digit, which is valid for that level (Refer to <>). +| <> | <> | +[[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:083,R-083]] Each level has unique key combinations for the button locations (Refer to <>). +| <> | <> | +[[req:83,R-083]] Each level has unique key combinations for the button locations (Refer to <>). -| <> | <> | -[[req:084,R-084]] Pressing the button corresponding to the letter-digit combinations advances the puzzle to the next level. +| <> | <> | +[[req:84,R-084]] Pressing the button corresponding to the letter-digit combinations advances the puzzle to the next level. -| <> | <> | -[[req:085,R-085]] If an incorrect button is pressed, the game resets to level 1. +| <> | <> | +[[req:85,R-085]] If an incorrect button is pressed, the game resets to level 1. -| <> | <> | -[[req:086,R-086]] An error sound is produced by the speaker when an incorrect button is pressed. +| <> | <> | +[[req:86,R-086]] An error sound is produced by the speaker when an incorrect button is pressed. -| <> | <> | -[[req:087,R-087]] The 7-segment display blinks when an incorrect button is pressed. +| <> | <> | +[[req:87,R-087]] The 7-segment display blinks when an incorrect button is pressed. -| <> | <> | -[[req:088,R-088]] After completing 5 levels, the puzzle is solved, and the vault opens. +| <> | <> | +[[req:88,R-088]] After completing 5 levels, the puzzle is solved, and the vault opens. |=== === Battery @@ -451,14 +451,14 @@ documentation. Due to time constraints, the section will be left empty. |=== | ID | <> | Specification -| <> | <> | -[[req:089,R-089]] The puzzle box is powered by a rechargeable battery. +| <> | <> | +[[req:89,R-089]] The puzzle box is powered by a rechargeable battery. -| <> | <> | -[[req:090,R-090]] The battery lasts for a minimum of 4 hours. +| <> | <> | +[[req:90,R-090]] The battery lasts for a minimum of 4 hours. -| <> | <> | -[[req:091,R-091]] The battery in the puzzle box can be replaced. +| <> | <> | +[[req:91,R-091]] The battery in the puzzle box can be replaced. |=== === Network Communication @@ -468,11 +468,11 @@ documentation. Due to time constraints, the section will be left empty. |=== | ID | <> | Specification -| <> | <> | -[[req:092,R-092]] The puzzle boxes, bombs, and the puzzle box hub must all be able to communicate with each other. +| <> | <> | +[[req:92,R-092]] The puzzle boxes, bombs, and the puzzle box hub must all be able to communicate with each other. -| <> | <> | -[[req:093,R-093]] Communication between two devices in the network must have a range of at least 20 meters in an open field. +| <> | <> | +[[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 @@ -501,8 +501,8 @@ documentation. Due to time constraints, the section will be left empty. |=== | ID | <> | Specification -| <> | <> | -[[req:094,R-094]] The puzzle box hub hosts a website that can be accessed by a device connected to the network. +| <> | <> | +[[req:94,R-094]] The puzzle box hub hosts a website that can be accessed by a device connected to the network. |=== [[sec:technical]] @@ -554,23 +554,23 @@ technical specifications of the puzzle box. |=== | ID | <> | Specification -| <> | <> | -[[req:136,R-136]] The main controller has at least 1 I2C peripheral. +| <> | <> | +[[req:main-i2c-ctrl,R-136]] The main controller has at least 1 I2C peripheral. -| <> | <> | -[[req:137,R-137]] The main controller can connect to a standard 802.11b/g/n access point. +| <> | <> | +[[req:main-802-11-ap,R-137]] The main controller can connect to a standard 802.11b/g/n access point. -| <> | <> | -[[req:138,R-138]] The main controller can serve TCP socket connection(s). +| <> | <> | +[[req:main-tcp-socket,R-138]] The main controller can serve TCP socket connection(s). -| <> | <> | -[[req:139,R-139]] The main controller is available as a development kit from Farnell. +| <> | <> | +[[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:166,R-166]] The main controller is power efficient. +| <> | <> | +[[req:main-pwr-efficient,R-166]] The main controller is power efficient. |=== === Puzzle module controller @@ -579,20 +579,20 @@ technical specifications of the puzzle box. |=== | ID | <> | Specification -| <> | <> | -[[req:141,R-141]] The puzzle module controller has at least 1 I2C peripheral. +| <> | <> | +[[req:pm-i2c-ctrl,R-141]] The puzzle module controller has at least 1 I2C peripheral. -| <> | <> | -[[req:142,R-142]] The puzzle module controller has enough I/O ports to control a puzzle. +| <> | <> | +[[req:pm-gpio,R-142]] The puzzle module controller has enough I/O ports to control a puzzle. -| <> | <> | -[[req:143,R-143]] The puzzle module is power efficient. +| <> | <> | +[[req:pm-pwr-efficient,R-143]] The puzzle module is power efficient. -| <> | <> | -[[req:144,R-144]] The puzzle module has a configurable clock speed. +| <> | <> | +[[req:pm-clk-ctrl,R-144]] The puzzle module has a configurable clock speed. -| <> | <> | -[[req:145,R-145]] The puzzle module controller is available as a development kit from Farnell. +| <> | <> | +[[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 diff --git a/docs/research.adoc b/docs/research.adoc index ab4175e..7e5b78c 100644 --- a/docs/research.adoc +++ b/docs/research.adoc @@ -124,11 +124,15 @@ 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 (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). +* 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 (<>). +* 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 @@ -156,12 +160,14 @@ 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 (R#141). +* Must have at least 1 I^2^C peripheral + (<>). * 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). + (<>). +* Should be power efficient (<>). +* Is available as a development kit from Farnell + (<>). +* 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 @@ -607,14 +613,18 @@ 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 +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: +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 -- 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 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 From 9baf7a839fa79db145ffce8ce807807e4055a1a0 Mon Sep 17 00:00:00 2001 From: lonkaars Date: Sat, 20 Apr 2024 16:42:00 +0200 Subject: WIP initial import of software design document from word --- docs/design.adoc | 515 +++++++++++++++++++++++++++++++++++++++++++++++ docs/readme.md | 2 + docs/share/glossary.adoc | 1 + 3 files changed, 518 insertions(+) diff --git a/docs/design.adoc b/docs/design.adoc index b653633..2bac6b3 100644 --- a/docs/design.adoc +++ b/docs/design.adoc @@ -1,5 +1,520 @@ :document: Software Design include::share/meta.adoc[] +== Introduction + +This document contains all the design considerations made for the separate +software components that make up the puzzle box. This document has a top-down +structure, and has three levels of design 'depth': + +. Top-level (hardware diagrams, OSes, communication buses, etc.) +. Module-level (puzzle inputs/outputs, top-level software diagram, etc.) +. Component-level (software dependencies, game state, etc.) + +Only design details deemed relevant by the document authors are documented +here. Low-level implementation details such as API interfaces, code paths and +workarounds are documented inside the source code repository. + +== Top-Level + +This section of the design document establishes the development target +hardware. It also specifies the modules that are elaborated further in §3. + +Figure 1 shows a block diagram that describes the context in which the puzzle +box is used. The puzzle box in this diagram internally consists of a main +controller and multiple puzzle modules. Other notable details include: + +* The charger is removable, and the puzzle box is intended to be used as a + battery-powered device (i.e. not while tethered). +* Puzzle outputs are used to complete a feedback loop (gameplay) with the + players, as well as eventually provide a solution to diffuse a bomb. This + bomb is part of a standalone project that has already been finished at the + time of writing (2024-03-11), and this project only describes the interface + between the puzzle box and the bomb. +* The puzzle box is capable of bidirectional communication over Wi-Fi. This + connection is used to configure the puzzle box before gameplay or modify its + state during gameplay. + +.Context block diagram + +The rest of this section details the internal hardware modules and the +separation of functionality of these modules. + +=== Puzzle Modules + +The puzzle box hardware produced by the 21-22 group consists of 6 sides, 4 of +which are utilized by puzzle modules. This section defines the properties of a +puzzle module. + +Puzzle modules can occupy one or more physical sides of the puzzle box to +implement the physical interface required for a puzzle or game. In order to +realize a complete game, each of these puzzle modules must have the ability to +control game inputs and outputs. Two approaches for this were considered: + +. Let the main controller handle game state and logic for all puzzle modules. ++ +This approach has the main benefit of allowing puzzle module controllers to be +substituted for I^2^C I/O expanders that draw less power than a complete MCU. ++ +The major drawback of this approach is that the main controller's software +needs to be configured for each different hardware configuration, which makes +the main controller software more complicated. + +. Design an abstract 'game interface' and give each puzzle module its own MCU. ++ +This approach provides the most flexibility, as the main controller's software +is no longer dependent on the physically installed hardware. This approach is +also favorable with regards to testability, as each puzzle module can run +standalone. ++ +The main drawback of this approach is the possible increase in power +consumption, as each puzzle module now must have its own MCU for managing game +state and communication with the main controller. + +The current hardware (developed by the 21-22 group) uses the second approach, +though with MCUs that were not designed for power efficiency. This year +(23-24), the hardware produced by the 21-22 group was utilized due to the 23-24 +group not including students from the hardware study path. Minimizing power +draw for each puzzle module is still a priority, so a different microcontroller +was selected. + +The criteria for a puzzle module controller are: + +* Must have an I^2^C peripheral (R#141). +* Should have enough I/O ports to directly control moderately complex puzzles + (R#142). +* Should be power efficient (R#143). + +The research document [1] compares various microcontrollers matching these +criteria. As a result of this research, the Microchip PIC16F15276 was selected +as the recommended microcontroller for future puzzle modules. The current +development hardware utilizes an ESP32-PICO-D4 module, so the puzzle module +software is written with portability in mind. + +.Generic puzzle module top-level block diagram + +Figure 2 shows a block diagram of how most puzzle modules are implemented. +Since the internal components of the puzzle module block from Figure 2 differ +for each puzzle, they are left out in this section. Section 3 includes the next +detail level for all of the implemented puzzles this year. The puzzle bus is +detailed further in §2.3. + +=== Main Controller + +This section describes the responsibilities of the main controller inside the +puzzle box. The main controller is a central processor that is responsible for +the following: + +* Integrate installed puzzle modules to form a cohesive experience by— +** Detecting and initializing installed puzzle modules. +** Aggregating game state for all installed puzzle modules. +** Reading and writing game state for all installed puzzle modules. +** Broadcasting updates internally. +* Serve TCP socket connections for— +** Sending state updates +** Manually updating game state +** Integration with the bomb + +The specific requirement of being able to serve TCP socket connections was +created so this year's puzzle box could keep compatibility with the software +produced by the 21-22 group. + +As mentioned in the research document [1], the 21-22 group produced the +hardware that is used as development target for this year's (23-24) run of the +puzzle box project. The existing hardware utilizes a Raspberry Pi 3B+ as main +controller, but this controller caused issues with power consumption [2]. +Choosing a different controller during development requires significant +refactoring, so a different main controller has been selected at the start of +this year's run of the puzzle box project. + +The criteria for the main controller are: + +* Must have an I^2^C peripheral (R#136). +* Must be able to connect to a standard 802.11b/g/n access point (R#137). +* Must be able to serve TCP socket connection(s) (R#138). +* Should be power efficient (R#166). + +The requirements document compares various microcontrollers that fit these +criteria. After this comparison, the decision was made to utilize the Raspberry +Pi Pico W as main controller during development. + +.Main controller top-level block diagram + +Figure 3 shows a block diagram of the main controller and its inputs and +outputs. The main controller is the only module in the puzzle box that is able +to communicate over Wi-Fi and is therefore responsible for all communication +between the puzzle box and game operator. The puzzle bus is detailed further in +§2.3. + +=== Communication + +Communication between puzzle modules, the main controller and other auxiliary +peripherals is handled through a central I^2^C bus referred to as the 'puzzle +bus'. This design was again carried over from the hardware design from the +21-22 group [3]. + +The only notable difference made this year was the removal of the +"HarwareInterrupt" line1, which was connected but not utilized [1]. + +Address definitions and protocol specifications are further detailed in §3.3. + +=== Power supply + +One of the user requirements is that the puzzle box runs on battery power +(R#89). Due to the team composition of this year's (23-24) run of the puzzle +box project, a new power supply was not chosen, even though the current power +supply was determined insufficient by the 21-22 group. This year, additional +requirements were specified for the power supply, which were used when +selecting MCUs suitable for battery-powered applications. + +.Power supply module top-level block diagram + +Figure 2 shows a block diagram of how most puzzle modules are implemented. +Besides the additional requirements, the power supply remains the same, and +will not be elaborated further on in this document. + +=== Overview + +Figure 5 is the resulting combination of the modules from Figures 3, 2 and 4. + +.Hardware component overview + +== Modules + +This section elaborates on the top-level specifications from §2 with additional +hardware specifications and software design decisions. + +=== Puzzle Module Framework + +This subsection defines aspects of the 'puzzle framework' and the interface +that allows puzzle modules to integrate with this framework. All communication +described within this subsection refers to 'internal' communication between the +main controller and puzzle module. + +The puzzle framework is the foundation of the puzzle box software, and is +designed to facilitate the following: + +* Allow puzzle modules to be swapped with minimal downtime or maintenance + (R#132). +* Simplify the development process and integration of new puzzle modules + (R#130). +* Provide abstracted interfaces to allow for easy integration of the puzzle box + as part of a larger whole (R#133). + +==== State + +All puzzle modules implement the same state machine shown in Figure 6. Note +that the arrows indicate state transitions that a puzzle module may take on its +own. The main controller also allows the game operator to manually set the +current state as one of the states on the right half of Figure 6, which can be +used to skip a puzzle if a player is stuck (R#168) or reset a game if it is +malfunctioning (R#167). + +Puzzle modules start in the 'uninitialized' state, where they repeatedly send +messages to the main controller (see §3.2.3). The state transition from +'uninitialized' to 'reset' is forced by the main controller upon +initialization. States on the right half of Figure 6 are used during gameplay. + +.Global puzzle module state machine + +The state machine described in Figure 6 is referred to as the global state. +Puzzle modules may also declare and define custom state variables, which is +referred to as auxiliary state. These auxiliary state variables contain +game-specific variables; e.g. the binary state of each button on the Neotrellis +puzzle module, or the last passcode entered on the vault puzzle module. + +Separating the auxiliary state from the generic state allows the main +controller to handle the auxiliary state as an arbitrary blob, which allows for +future expansion without modification of the main controller software. + +==== Commands + +The puzzle module framework describes the following commands: + +* Read state +* Write state +* Update + +The 'read' and 'write' commands are used to communicate both types of state +defined in §3.1.1. + +To avoid issues caused by state synchronization memory consumption on the main +controller and puzzle modules, auxiliary state is only stored on each +respective puzzle module's controller. Only global state is cached on the main +controller to reduce the number of back-and-forth messages required for state +updates. + +These commands are sufficient to realize the puzzle box, but this means that +the puzzle box would rely heavily on polling-based updates internally. To solve +this, the 'update' command was created. This command is utilized for various +kinds of updates, including registering new puzzle modules and updating global +state. + +=== Main Controller + +This subsection defines the function and state of the main controller. + +==== State + +The global state of the main controller is an aggregated version of all +installed puzzle modules and is defined by the state machine shown in Figure 7. + +.Main controller global state machine + +The following list describes when each state is active: + +* If all puzzle modules are in the 'reset' state, the main controller is also + in the 'reset' state. +* If all puzzle modules are in the 'solved' state, the main controller is also + in the 'solved' state. +* Else, the main controller is in the 'playing' state. + +Because the main controller's state is only dependent on the installed puzzle +modules' state, it is only updated when a puzzle module sends an update +notification. When the global state of the main module changes, an update +broadcast is sent to all puzzle modules. + +To simplify the commands used to control the puzzle box, the list of installed +puzzle modules is stored as an auxiliary state variable of the main controller. + +==== Initializing Puzzle Modules + +Puzzle modules start in the 'uninitialized' state (see Figure 6). In this +state, the puzzle module repeatedly sends an update command to the main +controller. The main controller responds to this message by sending a 'set +state' command with the target state as 'reset' as reply. Before this response +is sent, the main controller internally adds the bus address of the puzzle +module requesting to be initialized to the list of installed puzzle modules. +From the main controller's point of view, this reply marks the moment the +initialization is complete. + +.Puzzle module initialization sequence diagram + +(Activated lifeline indicates the module is no longer in 'uninitialized' state) + +==== Bridge + +The bridge is used to remotely access and control the puzzle box. + +The Raspberry Pi 3B+ used as main controller during the 21-22 run of the +project set up a Wi-Fi Mesh network [3] to communicate with the puzzle box. +This year's main controller (Raspberry Pi Pico W [1]) uses a standard +802.11b/g/n access point instead (R#137). + +On this network, the main controller hosts a server that serves TCP socket +connections. These sockets directly forward all internal messages sent to the +main controller bidirectionally (i.e. on behalf of the main controller). +Detailed specifications on the TCP socket server are in §4.1. + +==== Operating System + +The research document [1] contains a detailed comparison of various operating +systems that are suitable to realize the functionality described in this +section. After this comparison, the decision was made to utilize FreeRTOS as +the operating system on the Rasberry Pi Pico W. + +=== Puzzle Bus + +This section describes the addresses and communication protocol used on the +puzzle bus. These specifications only apply to messages sent internally in the +puzzle box, as messages forwarded by the bridge (see §3.2.3) are sent on behalf +of the main controller. + +==== Addresses + +The I^2^C addresses remain mostly unchanged from the 20-21 group's +implementation [4]. Addresses that were modified since the 20-21 implementation +are marked with an asterisk. Table 1 lists these addresses for reference. These +addresses are also used to identify specific puzzle modules. + +.I^2^C address reference +[%autowidth] +|=== +| Peripheral | Address + +| Main controller | 0x10* +| Neotrellis puzzle controller | 0x11* +| Neotrellis button matrix | 0x12* +| Software puzzle controller | 0x03 +| Hardware puzzle controller | 0x04 +| Vault puzzle controller | 0x06 +|=== + +==== Messages + +All messages sent over the puzzle bus have a similar format. This format is +shown in Table 2. Notable details include: + +The 'subject' field does not have to match the I^2^C address of the message +sender or recipient + +Property 0x00 stores a module's global state + +.Puzzle bus message format +[%autowidth] +|=== +| Field | Content + +| Command | Enum: read, write, update +| Subject | I^2^C address (7-bit) +| Property | Address (8-bit) +| Value | Byte string (variable length) +|=== + +The messages described in Table 2 are (de)serialized using Google's protocol +buffer library. This choice was made after considering various alternative +options for sending structured messages [1]. + +Figure 8 shows an example of how messages are exchanged for the initialization +of a puzzle module. + +Figure 9 shows an example exchange where the last puzzle module (A) is solved +while (B) is already solved. + +. First, module A sets it's own state to 'solved' and subsequently informs the + main controller of this change. +. As a result of this update notification, the main controller queries puzzle + module A for its new global state. +. Once the main controller has received and confirmed that all puzzle module + global states are set to 'solved', the main controller sets its own state to + 'solved', and broadcasts an update message to all puzzle modules. +. As a result of the update message from the main controller, module B requests + the main controller's new global state, and is able to verify that all puzzle + modules have been solved. + +In this example, module B could be the vault puzzle module, which displays a +code when the entire puzzle box is solved. + +.Puzzle box finish sequence diagram + +=== NeoTrellis Puzzle + +This subsection defines aspects of the 'NeoTrellis puzzle' module and gives a +summary of how the puzzle is meant to be solved. This module will be created to +facilitate the NeoTrellis puzzle game logic and communication with the main +controller about the puzzle state. + +==== NeoTrellis puzzle gameplay + +The NeoTrellis puzzle is an 8x8 button matrix with Neopixels underneath each +button. The way to solve this puzzle is by dimming every Neopixel in the 8x8 +matrix. This is done by clicking on a button, which switches the state of the +Neopixel underneath the pixel and the Neopixels in each cardinal direction from +the pressed button. This means that if a Neopixel was on and the button was +pressed it will turn off and vice-versa. A visual example can be found in +Appendix B. + +==== Puzzle inputs & outputs + +The inputs and outputs of this puzzle have been taken from the design document +of the previous group which worked on this project (??). This input and output +diagram has been shown in Figure 10. + +.NeoTrellis puzzle in-out + +=== Software Puzzle + +This subsection defines aspects of the 'software puzzle' module and gives a +summary of how the puzzle is meant to be solved. This module will be created to +facilitate the software puzzle game logic and communication with the main +controller about the software puzzle state. + +==== Software puzzle gameplay + +The software puzzle consists of 12 input ports which can be connected using a +banana plug connector. The 6 input ports on the left side of the puzzle each +have their own logical circuit engraved in the box, and the 6 input ports on +the right side of the puzzle have a letter (A through F) engraved in the box. +The way to solve the puzzle is by connecting the banana plug cable from an +input port on the left side of the puzzle to the corresponding input port on +the right side of the puzzle. An example of this can be found in Appendix C. + +When the puzzle starts, the participants of the game will have 6 code-fragments +written on paper, corresponding to the logical circuits on the puzzle box. The +bomb participants will have description of the C-code fragments, while the +puzzle box participants only have the logical circuits on the puzzle box. The +participants must communicate with each other to figure out which a fragment of +C code corresponds with a logical circuit engraved on the puzzle box. Once this +has been done the puzzle box participants can use a banana plug cable to +connect the input and output to each other. Once the correct combination of +logical gates with the correct letter is made, the puzzle is solved (shown by +an LED lighting up above the puzzle). Allowing the participants to both see a +binary code using 16 LEDs above the puzzle, and to continue to the next puzzle. + +==== Puzzle inputs & outputs + +As stated in §3.5.1 the puzzle has 12 inputs, as well as an LED which shows +whether the puzzle has been solved and 16 LEDs showing a binary code. This is +shown in Figure 11. + +.Software puzzle in-out + +=== Hardware Puzzle + +==== Hardware Puzzle gameplay + +The hardware puzzle has a logic gate puzzle engraved on the front plate of the +puzzle box. To solve the puzzle, the user must set the toggle switches to the +correct position. To solve the puzzle, a truth table is used. + +The second part of the puzzle is unlocked after solving the logic gate puzzle, +the user has to listen to a Morse code from which a four-digit code follows. +The user then turns potentiometers to change this code on the display. The +puzzle is solved when the user has put the correct code on the display. Once +successful, the indicator LED will light up. + +==== Puzzle inputs / outputs + +The inputs and outputs of this puzzle have been taken from the design document +of the previous group which worked on this project (21-22). This input and +output diagram has been shown in Figure ??. + +=== Vault Puzzle + +==== Vault puzzle gameplay + +The vault 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 communicates this to the students at the +puzzle box the button they must click. This needs to be done 5 times before the +vault opens and the last code is given to defuse the bomb if a wrong button is +clicked the vault resets and they need to start over from the beginning. + +==== Puzzle inputs & outputs + +.Vault puzzle in-out + +=== Bomb device + +==== Bomb device connection + +The bomb connects to a WiFi-network using the 802.11x standard. The hub hosts +an interface that can be used to identify all the devices including the bomb +and also pair it to a puzzlebox. After that the game can be set-up and a given +countdown time and start time will be communicated to the bomb over a TCP +socket connection. The hub generates a code that will be send to both the +puzzlebox and bomb so that both devices know what would be or can be expected. + +The bomb can also use the WiFi connection to sync. the time. + +==== Device inputs & outputs + +.Bomb device in-out + +== Components +=== Remote Control +==== Socket Server +==== Socket Commands +=== Neotrellis Puzzle +=== Game state diagrams, activity diagrams (if applicable) +=== Software Puzzle +=== Hardware Puzzle +=== Vault Puzzle + +[appendix] +== NeoTrellis puzzle example + +[appendix] +== Software puzzle example include::share/footer.adoc[] diff --git a/docs/readme.md b/docs/readme.md index c5067b5..32814dc 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -18,7 +18,9 @@ makefile is provided for convenience. - [x] project plan - [x] requirements - [x] research + - [ ] footnotes - [ ] software design + - [ ] footnotes - xrefs for-- - [x] tables - [x] figures diff --git a/docs/share/glossary.adoc b/docs/share/glossary.adoc index 8cc19f5..871a8e9 100644 --- a/docs/share/glossary.adoc +++ b/docs/share/glossary.adoc @@ -6,4 +6,5 @@ RPI:: Raspberry Pi Main board:: The main board is the PCB on the bottom of the puzzle box, this communicates with the puzzles and the bomb Puzzle box hub:: The puzzle box hub communicates with the puzzle box and the bomb, as well as helps with configuring them SID:: security identifiers +game operator:: person who organizes a puzzle box play session -- cgit v1.2.3 From 1e124d005c8b3885ca960a3894019331ef288b5e Mon Sep 17 00:00:00 2001 From: lonkaars Date: Sun, 21 Apr 2024 17:03:38 +0200 Subject: add figures and cross-references to design.adoc --- docs/design.adoc | 239 +++++++++++++++++++++++++++------------------ docs/img/bomb-io.png | Bin 0 -> 25112 bytes docs/img/hardware-io.png | Bin 0 -> 45639 bytes docs/img/neotrellis-io.png | Bin 0 -> 21940 bytes docs/img/software-io.png | Bin 0 -> 33531 bytes docs/img/vault-io.png | Bin 0 -> 31991 bytes docs/readme.md | 12 +++ 7 files changed, 155 insertions(+), 96 deletions(-) create mode 100644 docs/img/bomb-io.png create mode 100644 docs/img/hardware-io.png create mode 100644 docs/img/neotrellis-io.png create mode 100644 docs/img/software-io.png create mode 100644 docs/img/vault-io.png diff --git a/docs/design.adoc b/docs/design.adoc index 2bac6b3..533c02a 100644 --- a/docs/design.adoc +++ b/docs/design.adoc @@ -15,14 +15,16 @@ Only design details deemed relevant by the document authors are documented here. Low-level implementation details such as API interfaces, code paths and workarounds are documented inside the source code repository. +[[sec:lv1]] == Top-Level This section of the design document establishes the development target -hardware. It also specifies the modules that are elaborated further in §3. +hardware. It also specifies the modules that are elaborated further in +<>. -Figure 1 shows a block diagram that describes the context in which the puzzle -box is used. The puzzle box in this diagram internally consists of a main -controller and multiple puzzle modules. Other notable details include: +<> shows a block diagram that describes the context in which +the puzzle box is used. The puzzle box in this diagram internally consists of a +main controller and multiple puzzle modules. Other notable details include: * The charger is removable, and the puzzle box is intended to be used as a battery-powered device (i.e. not while tethered). @@ -35,7 +37,9 @@ controller and multiple puzzle modules. Other notable details include: connection is used to configure the puzzle box before gameplay or modify its state during gameplay. +[[fig:system-top]] .Context block diagram +image::img/system-top.svg[] The rest of this section details the internal hardware modules and the separation of functionality of these modules. @@ -80,24 +84,27 @@ was selected. The criteria for a puzzle module controller are: -* Must have an I^2^C peripheral (R#141). +* Must have an I^2^C peripheral (<>). * Should have enough I/O ports to directly control moderately complex puzzles - (R#142). -* Should be power efficient (R#143). + (<>). +* Should be power efficient (<>). -The research document [1] compares various microcontrollers matching these -criteria. As a result of this research, the Microchip PIC16F15276 was selected -as the recommended microcontroller for future puzzle modules. The current -development hardware utilizes an ESP32-PICO-D4 module, so the puzzle module -software is written with portability in mind. +The research document cite:[research] compares various microcontrollers +matching these criteria. As a result of this research, the Microchip +PIC16F15276 was selected as the recommended microcontroller for future puzzle +modules. The current development hardware utilizes an ESP32-PICO-D4 module, so +the puzzle module software is written with portability in mind. +[[fig:puzzle-module-top]] .Generic puzzle module top-level block diagram +image::img/puzzle-module-top.svg[] -Figure 2 shows a block diagram of how most puzzle modules are implemented. -Since the internal components of the puzzle module block from Figure 2 differ -for each puzzle, they are left out in this section. Section 3 includes the next -detail level for all of the implemented puzzles this year. The puzzle bus is -detailed further in §2.3. +<> shows a block diagram of how most puzzle modules are +implemented. Since the internal components of the puzzle module block from +<> differ for each puzzle, they are left out in this +section. <> includes the next detail level for all of the implemented +puzzles this year. The puzzle bus is detailed further in +<>. === Main Controller @@ -119,70 +126,84 @@ The specific requirement of being able to serve TCP socket connections was created so this year's puzzle box could keep compatibility with the software produced by the 21-22 group. -As mentioned in the research document [1], the 21-22 group produced the -hardware that is used as development target for this year's (23-24) run of the -puzzle box project. The existing hardware utilizes a Raspberry Pi 3B+ as main -controller, but this controller caused issues with power consumption [2]. -Choosing a different controller during development requires significant -refactoring, so a different main controller has been selected at the start of -this year's run of the puzzle box project. +As mentioned in the research document cite:[research], the 21-22 group produced +the hardware that is used as development target for this year's (23-24) run of +the puzzle box project. The existing hardware utilizes a Raspberry Pi 3B+ as +main controller, but this controller caused issues with power consumption +cite:[2122_handover]. Choosing a different controller during development +requires significant refactoring, so a different main controller has been +selected at the start of this year's run of the puzzle box project. The criteria for the main controller are: -* Must have an I^2^C peripheral (R#136). -* Must be able to connect to a standard 802.11b/g/n access point (R#137). -* Must be able to serve TCP socket connection(s) (R#138). -* Should be power efficient (R#166). +* Must have an I^2^C peripheral (<>). +* Must be able to connect to a standard 802.11b/g/n access point + (<>). +* Must be able to serve TCP socket connection(s) + (<>). +* Should be power efficient (<>). The requirements document compares various microcontrollers that fit these criteria. After this comparison, the decision was made to utilize the Raspberry Pi Pico W as main controller during development. +[[fig:main-controller-top]] .Main controller top-level block diagram +image::img/main-controller-top.svg[] -Figure 3 shows a block diagram of the main controller and its inputs and -outputs. The main controller is the only module in the puzzle box that is able -to communicate over Wi-Fi and is therefore responsible for all communication -between the puzzle box and game operator. The puzzle bus is detailed further in -§2.3. +<> shows a block diagram of the main controller and +its inputs and outputs. The main controller is the only module in the puzzle +box that is able to communicate over Wi-Fi and is therefore responsible for all +communication between the puzzle box and game operator. The puzzle bus is +detailed further in <>. +[[sec:lv1-communication]] === Communication Communication between puzzle modules, the main controller and other auxiliary peripherals is handled through a central I^2^C bus referred to as the 'puzzle bus'. This design was again carried over from the hardware design from the -21-22 group [3]. +21-22 group cite:[2122_design]. The only notable difference made this year was the removal of the -"HarwareInterrupt" line1, which was connected but not utilized [1]. +"HarwareInterrupt" line1{empty}footnote:[This is not a typo], which was +connected but not utilized cite:[research]. -Address definitions and protocol specifications are further detailed in §3.3. +Address definitions and protocol specifications are further detailed in +<>. === Power supply One of the user requirements is that the puzzle box runs on battery power -(R#89). Due to the team composition of this year's (23-24) run of the puzzle -box project, a new power supply was not chosen, even though the current power -supply was determined insufficient by the 21-22 group. This year, additional -requirements were specified for the power supply, which were used when -selecting MCUs suitable for battery-powered applications. +(<>). Due to the team composition of this year's (23-24) run +of the puzzle box project, a new power supply was not chosen, even though the +current power supply was determined insufficient by the 21-22 group. This year, +additional requirements were specified for the power supply, which were used +when selecting MCUs suitable for battery-powered applications. +[[fig:power-supply-top]] .Power supply module top-level block diagram +image::img/power-supply-top.svg[] -Figure 2 shows a block diagram of how most puzzle modules are implemented. -Besides the additional requirements, the power supply remains the same, and -will not be elaborated further on in this document. +<> shows a block diagram of how most puzzle modules are +implemented. Besides the additional requirements, the power supply remains the +same, and will not be elaborated further on in this document. === Overview -Figure 5 is the resulting combination of the modules from Figures 3, 2 and 4. +<> is the resulting combination of the modules from +<>, <> and +<>. +[[fig:system-bus]] .Hardware component overview +image::img/system-bus.svg[] +[[sec:lv2]] == Modules -This section elaborates on the top-level specifications from §2 with additional -hardware specifications and software design decisions. +This section elaborates on the top-level specifications from <> with +additional hardware specifications and software design decisions. === Puzzle Module Framework @@ -195,33 +216,39 @@ The puzzle framework is the foundation of the puzzle box software, and is designed to facilitate the following: * Allow puzzle modules to be swapped with minimal downtime or maintenance - (R#132). + (<>). * Simplify the development process and integration of new puzzle modules - (R#130). + (<>). * Provide abstracted interfaces to allow for easy integration of the puzzle box - as part of a larger whole (R#133). + as part of a larger whole (<>). +[[sec:framework-state]] ==== State -All puzzle modules implement the same state machine shown in Figure 6. Note -that the arrows indicate state transitions that a puzzle module may take on its -own. The main controller also allows the game operator to manually set the -current state as one of the states on the right half of Figure 6, which can be -used to skip a puzzle if a player is stuck (R#168) or reset a game if it is -malfunctioning (R#167). +All puzzle modules implement the same state machine shown in +<>. Note that the arrows indicate state +transitions that a puzzle module may take on its own. The main controller also +allows the game operator to manually set the current state as one of the states +on the right half of <>, which can be used to +skip a puzzle if a player is stuck (<>) or reset a game if +it is malfunctioning (<>). Puzzle modules start in the 'uninitialized' state, where they repeatedly send -messages to the main controller (see §3.2.3). The state transition from -'uninitialized' to 'reset' is forced by the main controller upon -initialization. States on the right half of Figure 6 are used during gameplay. +messages to the main controller (see <>). The state transition +from 'uninitialized' to 'reset' is forced by the main controller upon +initialization. States on the right half of <> +are used during gameplay. +[[fig:puzzle-module-common-state]] .Global puzzle module state machine +image::img/puzzle-module-common-state.svg[] -The state machine described in Figure 6 is referred to as the global state. -Puzzle modules may also declare and define custom state variables, which is -referred to as auxiliary state. These auxiliary state variables contain -game-specific variables; e.g. the binary state of each button on the Neotrellis -puzzle module, or the last passcode entered on the vault puzzle module. +The state machine described in <> is referred +to as the global state. Puzzle modules may also declare and define custom state +variables, which is referred to as auxiliary state. These auxiliary state +variables contain game-specific variables; e.g. the binary state of each button +on the Neotrellis puzzle module, or the last passcode entered on the vault +puzzle module. Separating the auxiliary state from the generic state allows the main controller to handle the auxiliary state as an arbitrary blob, which allows for @@ -236,7 +263,7 @@ The puzzle module framework describes the following commands: * Update The 'read' and 'write' commands are used to communicate both types of state -defined in §3.1.1. +defined in <>. To avoid issues caused by state synchronization memory consumption on the main controller and puzzle modules, auxiliary state is only stored on each @@ -257,9 +284,12 @@ This subsection defines the function and state of the main controller. ==== State The global state of the main controller is an aggregated version of all -installed puzzle modules and is defined by the state machine shown in Figure 7. +installed puzzle modules and is defined by the state machine shown in +<>. +[[fig:main-controller-state]] .Main controller global state machine +image::img/main-controller-state.svg[] The following list describes when each state is active: @@ -279,53 +309,58 @@ puzzle modules is stored as an auxiliary state variable of the main controller. ==== Initializing Puzzle Modules -Puzzle modules start in the 'uninitialized' state (see Figure 6). In this -state, the puzzle module repeatedly sends an update command to the main -controller. The main controller responds to this message by sending a 'set -state' command with the target state as 'reset' as reply. Before this response -is sent, the main controller internally adds the bus address of the puzzle -module requesting to be initialized to the list of installed puzzle modules. -From the main controller's point of view, this reply marks the moment the -initialization is complete. +Puzzle modules start in the 'uninitialized' state (see +<>). In this state, the puzzle module +repeatedly sends an update command to the main controller. The main controller +responds to this message by sending a 'set state' command with the target state +as 'reset' as reply. Before this response is sent, the main controller +internally adds the bus address of the puzzle module requesting to be +initialized to the list of installed puzzle modules. From the main controller's +point of view, this reply marks the moment the initialization is complete. +[[fig:sequence-puzzle-module-init]] .Puzzle module initialization sequence diagram +image::img/sequence-puzzle-module-init.svg[] (Activated lifeline indicates the module is no longer in 'uninitialized' state) +[[sec:main-bridge]] ==== Bridge The bridge is used to remotely access and control the puzzle box. The Raspberry Pi 3B+ used as main controller during the 21-22 run of the -project set up a Wi-Fi Mesh network [3] to communicate with the puzzle box. -This year's main controller (Raspberry Pi Pico W [1]) uses a standard -802.11b/g/n access point instead (R#137). +project set up a Wi-Fi Mesh network cite:[2122_design] to communicate with the +puzzle box. This year's main controller (Raspberry Pi Pico W cite:[research]) +uses a standard 802.11b/g/n access point instead (<>). On this network, the main controller hosts a server that serves TCP socket connections. These sockets directly forward all internal messages sent to the main controller bidirectionally (i.e. on behalf of the main controller). -Detailed specifications on the TCP socket server are in §4.1. +Detailed specifications on the TCP socket server are in +<>. ==== Operating System -The research document [1] contains a detailed comparison of various operating -systems that are suitable to realize the functionality described in this -section. After this comparison, the decision was made to utilize FreeRTOS as -the operating system on the Rasberry Pi Pico W. +The research document cite:[research] contains a detailed comparison of various +operating systems that are suitable to realize the functionality described in +this section. After this comparison, the decision was made to utilize FreeRTOS +as the operating system on the Rasberry Pi Pico W. +[[sec:lv2-bus]] === Puzzle Bus This section describes the addresses and communication protocol used on the puzzle bus. These specifications only apply to messages sent internally in the -puzzle box, as messages forwarded by the bridge (see §3.2.3) are sent on behalf -of the main controller. +puzzle box, as messages forwarded by the bridge (see <>) are +sent on behalf of the main controller. ==== Addresses The I^2^C addresses remain mostly unchanged from the 20-21 group's -implementation [4]. Addresses that were modified since the 20-21 implementation -are marked with an asterisk. Table 1 lists these addresses for reference. These -addresses are also used to identify specific puzzle modules. +implementation cite:[2021_design]. Addresses that were modified since the 20-21 +implementation are marked with an asterisk. Table 1 lists these addresses for +reference. These addresses are also used to identify specific puzzle modules. .I^2^C address reference [%autowidth] @@ -363,13 +398,13 @@ Property 0x00 stores a module's global state The messages described in Table 2 are (de)serialized using Google's protocol buffer library. This choice was made after considering various alternative -options for sending structured messages [1]. +options for sending structured messages cite:[research]. -Figure 8 shows an example of how messages are exchanged for the initialization -of a puzzle module. +<> shows an example of how messages are +exchanged for the initialization of a puzzle module. -Figure 9 shows an example exchange where the last puzzle module (A) is solved -while (B) is already solved. +<> shows an example exchange where the last puzzle +module (A) is solved while (B) is already solved. . First, module A sets it's own state to 'solved' and subsequently informs the main controller of this change. @@ -385,7 +420,9 @@ while (B) is already solved. In this example, module B could be the vault puzzle module, which displays a code when the entire puzzle box is solved. +[[fig:sequence-puzzle-finish]] .Puzzle box finish sequence diagram +image::img/sequence-puzzle-finish.svg[] === NeoTrellis Puzzle @@ -408,9 +445,11 @@ Appendix B. The inputs and outputs of this puzzle have been taken from the design document of the previous group which worked on this project (??). This input and output -diagram has been shown in Figure 10. +diagram has been shown in <>. +[[fig:neotrellis-io]] .NeoTrellis puzzle in-out +image::img/neotrellis-io.png[] === Software Puzzle @@ -419,6 +458,7 @@ summary of how the puzzle is meant to be solved. This module will be created to facilitate the software puzzle game logic and communication with the main controller about the software puzzle state. +[[sec:software-gameplay]] ==== Software puzzle gameplay The software puzzle consists of 12 input ports which can be connected using a @@ -443,11 +483,13 @@ binary code using 16 LEDs above the puzzle, and to continue to the next puzzle. ==== Puzzle inputs & outputs -As stated in §3.5.1 the puzzle has 12 inputs, as well as an LED which shows -whether the puzzle has been solved and 16 LEDs showing a binary code. This is -shown in Figure 11. +As stated in <> the puzzle has 12 inputs, as well as an +LED which shows whether the puzzle has been solved and 16 LEDs showing a binary +code. This is shown in <>. +[[fig:software-io]] .Software puzzle in-out +image::img/software-io.png[] === Hardware Puzzle @@ -482,7 +524,9 @@ clicked the vault resets and they need to start over from the beginning. ==== Puzzle inputs & outputs +[[fig:vault-io]] .Vault puzzle in-out +image::img/vault-io.png[] === Bomb device @@ -499,9 +543,12 @@ The bomb can also use the WiFi connection to sync. the time. ==== Device inputs & outputs +[[fig:bomb-io]] .Bomb device in-out +image::img/bomb-io.png[] == Components +[[sec:lv3-remote-control]] === Remote Control ==== Socket Server ==== Socket Commands diff --git a/docs/img/bomb-io.png b/docs/img/bomb-io.png new file mode 100644 index 0000000..20d33da Binary files /dev/null and b/docs/img/bomb-io.png differ diff --git a/docs/img/hardware-io.png b/docs/img/hardware-io.png new file mode 100644 index 0000000..54bf1d7 Binary files /dev/null and b/docs/img/hardware-io.png differ diff --git a/docs/img/neotrellis-io.png b/docs/img/neotrellis-io.png new file mode 100644 index 0000000..5f28562 Binary files /dev/null and b/docs/img/neotrellis-io.png differ diff --git a/docs/img/software-io.png b/docs/img/software-io.png new file mode 100644 index 0000000..4915315 Binary files /dev/null and b/docs/img/software-io.png differ diff --git a/docs/img/vault-io.png b/docs/img/vault-io.png new file mode 100644 index 0000000..b76da9f Binary files /dev/null and b/docs/img/vault-io.png differ diff --git a/docs/readme.md b/docs/readme.md index 32814dc..2810343 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -28,8 +28,20 @@ makefile is provided for convenience. - [x] requirements - [x] figures - [x] citations +- [ ] table of tables +- [ ] table of figures - [ ] glossary (w/ cross-references) - [ ] PDF style +- [ ] give used requirements more meaningful id's + +## for later reference + +### get citation keys from .docx file + +``` +$ unar file.docx +$ grep -o 'CITATION[^<]\+' file/word/document.xml | awk '!x[$2]++ { i++; print "[" i "] " $2 }' +``` [rubydl]: https://www.ruby-lang.org/en/documentation/installation/ [asciidoc]: https://asciidoc.org/ -- cgit v1.2.3 From acea0828b8638764fa698aae54ba403912354bb8 Mon Sep 17 00:00:00 2001 From: lonkaars Date: Mon, 22 Apr 2024 16:53:05 +0200 Subject: clean up documents --- docs/.bundle/config | 2 ++ docs/Gemfile | 2 ++ docs/makefile | 1 + docs/readme.md | 6 +++--- docs/share/meta.adoc | 10 ++++++++++ docs/theme.yml | 49 ++++++++++++++++++++++++++++++++++++------------- 6 files changed, 54 insertions(+), 16 deletions(-) create mode 100644 docs/.bundle/config diff --git a/docs/.bundle/config b/docs/.bundle/config new file mode 100644 index 0000000..92d0e5f --- /dev/null +++ b/docs/.bundle/config @@ -0,0 +1,2 @@ +--- +BUNDLE_PATH: "res/bundle" diff --git a/docs/Gemfile b/docs/Gemfile index 99f5ca1..efd0f36 100644 --- a/docs/Gemfile +++ b/docs/Gemfile @@ -8,4 +8,6 @@ gem 'asciidoctor-pdf', '~> 2.3' gem 'asciidoctor-bibtex', '~> 0.8.0' # gem 'asciidoctor-interdoc-reftext', '~> 0.5.2' gem 'asciidoctor-interdoc-reftext', git: 'https://github.com/lonkaars/asciidoctor-interdoc-reftext' +gem 'asciidoctor-lists', '~> 1.0' +gem 'text-hyphen', '~> 1.5' diff --git a/docs/makefile b/docs/makefile index 1fbb5b4..452eddf 100644 --- a/docs/makefile +++ b/docs/makefile @@ -15,6 +15,7 @@ ASCIIDOCTOR_ARGS += --require asciidoctor-bibtex ASCIIDOCTOR_ARGS += --require asciidoctor-pdf # ASCIIDOCTOR_ARGS += --require ./plugin/helloworld ASCIIDOCTOR_ARGS += --require asciidoctor-interdoc-reftext +ASCIIDOCTOR_ARGS += --require asciidoctor-lists ASCIIDOCTOR_ARGS += --backend pdf %.pdf: %.adoc $(PDFDEPS) bundle exec asciidoctor $(ASCIIDOCTOR_ARGS) $< diff --git a/docs/readme.md b/docs/readme.md index 2810343..215df50 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -28,10 +28,10 @@ makefile is provided for convenience. - [x] requirements - [x] figures - [x] citations -- [ ] table of tables -- [ ] table of figures +- [x] table of tables +- [x] table of figures - [ ] glossary (w/ cross-references) -- [ ] PDF style +- [x] PDF style - [ ] give used requirements more meaningful id's ## for later reference diff --git a/docs/share/meta.adoc b/docs/share/meta.adoc index 15d8d18..2e15b79 100644 --- a/docs/share/meta.adoc +++ b/docs/share/meta.adoc @@ -29,5 +29,15 @@ endif::[] // followed by a table of contents :toc: +[discrete] +== List of Figures +list-of::image[] + +[discrete] +== List of Tables +list-of::table[] + +<<< + // also https://docs.asciidoctor.org/asciidoc/latest/attributes/document-attributes-ref diff --git a/docs/theme.yml b/docs/theme.yml index 1537f50..5844a86 100644 --- a/docs/theme.yml +++ b/docs/theme.yml @@ -9,6 +9,7 @@ page: base: hyphens: true text-align: justify + font-size: 10.5 prose: margin-bottom: 3mm @@ -17,24 +18,20 @@ prose: # catalog: # serif: # bold: texgyreschola-bold.otf -# bold_italic: texgyreschola-bolditalic.otf +# bold-italic: texgyreschola-bolditalic.otf # italic: texgyreschola-italic.otf # normal: texgyreschola-regular.otf -# sans_serif: +# sans-serif: # bold: Inter-Bold.otf -# bold_italic: Inter-BoldItalic.otf +# bold-italic: Inter-BoldItalic.otf # italic: Inter-Italic.otf # normal: Inter-Regular.otf # monospace: # bold: JetBrainsMono-Bold.ttf -# bold_italic: JetBrainsMono-BoldItalic.ttf +# bold-italic: JetBrainsMono-BoldItalic.ttf # italic: JetBrainsMono-Italic.ttf # normal: JetBrainsMono-Regular.ttf -base: - # font-family: serif - font-size: 10.5 - title-page: align: center title: @@ -65,13 +62,39 @@ caption: align: center end: bottom -example: - caption: - end: $caption-end +image: + align: center + +list: + indent: 10mm + +description-list: + term-font-style: bold + table: + align: center + border-color: transparent + cell-padding: [0.2pt, 2pt] + border-color: '#000000' + border-width: [ 0.5pt, 0pt, 0.5pt, 0pt ] + head: + font-style: bold + border-bottom-width: 1pt + cell: + border-width: 0pt caption: end: $caption-end -list: - indent: 10mm +footnotes: + font-size: round($base-font-size * 0.75) + +footer: + height: 1in + vertical-align: middle + recto: + center: + content: '{page-number}' + verso: + center: + content: '{page-number}' -- cgit v1.2.3 From dd8379e545b4beb6611a8152bca87e9276dde797 Mon Sep 17 00:00:00 2001 From: lonkaars Date: Mon, 22 Apr 2024 17:07:44 +0200 Subject: finish TODOs --- docs/design.adoc | 23 ++++++++++++----------- docs/readme.md | 24 +++--------------------- docs/reqs.adoc | 24 ++++++++++++------------ docs/research.adoc | 36 ++++++++++++++++++------------------ docs/theme.yml | 2 +- 5 files changed, 46 insertions(+), 63 deletions(-) diff --git a/docs/design.adoc b/docs/design.adoc index 533c02a..5ebbb15 100644 --- a/docs/design.adoc +++ b/docs/design.adoc @@ -175,11 +175,11 @@ Address definitions and protocol specifications are further detailed in === Power supply One of the user requirements is that the puzzle box runs on battery power -(<>). Due to the team composition of this year's (23-24) run -of the puzzle box project, a new power supply was not chosen, even though the -current power supply was determined insufficient by the 21-22 group. This year, -additional requirements were specified for the power supply, which were used -when selecting MCUs suitable for battery-powered applications. +(<>). Due to the team composition of this year's +(23-24) run of the puzzle box project, a new power supply was not chosen, even +though the current power supply was determined insufficient by the 21-22 group. +This year, additional requirements were specified for the power supply, which +were used when selecting MCUs suitable for battery-powered applications. [[fig:power-supply-top]] .Power supply module top-level block diagram @@ -216,11 +216,11 @@ The puzzle framework is the foundation of the puzzle box software, and is designed to facilitate the following: * Allow puzzle modules to be swapped with minimal downtime or maintenance - (<>). + (<>). * Simplify the development process and integration of new puzzle modules - (<>). + (<>). * Provide abstracted interfaces to allow for easy integration of the puzzle box - as part of a larger whole (<>). + as part of a larger whole (<>). [[sec:framework-state]] ==== State @@ -230,8 +230,8 @@ All puzzle modules implement the same state machine shown in transitions that a puzzle module may take on its own. The main controller also allows the game operator to manually set the current state as one of the states on the right half of <>, which can be used to -skip a puzzle if a player is stuck (<>) or reset a game if -it is malfunctioning (<>). +skip a puzzle if a player is stuck (<>) or +reset a game if it is malfunctioning (<>). Puzzle modules start in the 'uninitialized' state, where they repeatedly send messages to the main controller (see <>). The state transition @@ -332,7 +332,8 @@ The bridge is used to remotely access and control the puzzle box. The Raspberry Pi 3B+ used as main controller during the 21-22 run of the project set up a Wi-Fi Mesh network cite:[2122_design] to communicate with the puzzle box. This year's main controller (Raspberry Pi Pico W cite:[research]) -uses a standard 802.11b/g/n access point instead (<>). +uses a standard 802.11b/g/n access point instead +(<>). On this network, the main controller hosts a server that serves TCP socket connections. These sockets directly forward all internal messages sent to the diff --git a/docs/readme.md b/docs/readme.md index 215df50..99cbb24 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -12,27 +12,9 @@ makefile is provided for convenience. - please give cross references, links, image files, figure ids, etc. meaningful names -## TODO - -- transfer documents - - [x] project plan - - [x] requirements - - [x] research - - [ ] footnotes - - [ ] software design - - [ ] footnotes -- xrefs for-- - - [x] tables - - [x] figures - - [x] section numbers (headings) - - [x] requirements -- [x] figures -- [x] citations -- [x] table of tables -- [x] table of figures -- [ ] glossary (w/ cross-references) -- [x] PDF style -- [ ] give used requirements more meaningful id's +## todo (low priority) + +- cross-references to glossary ## for later reference diff --git a/docs/reqs.adoc b/docs/reqs.adoc index edddbdd..8ad24a8 100644 --- a/docs/reqs.adoc +++ b/docs/reqs.adoc @@ -211,11 +211,11 @@ describes all functional requirements of the puzzle box. | <> | <> | [[req:27,R-027]] The puzzles should be easy enough to solve without any prior knowledge of the game or its mechanics. -| <> | <> | -[[req:167,R-167]] A puzzle module can manually be reset at the discretion of the game operator +| <> | <> | +[[req:edge-manual-reset,R-167]] A puzzle module can manually be reset at the discretion of the game operator -| <> | <> | -[[req:168,R-168]] A puzzle module can manually be set as solved at the discretion of the game operator +| <> | <> | +[[req:edge-skip-puzzle,R-168]] A puzzle module can manually be set as solved at the discretion of the game operator | <> | <> | [[req:28,R-028]] The disarm code for the bomb consists of 4 digits. @@ -451,8 +451,8 @@ documentation. Due to time constraints, the section will be left empty. |=== | ID | <> | Specification -| <> | <> | -[[req:89,R-089]] The puzzle box is powered by a rechargeable battery. +| <> | <> | +[[req:pwr-battery,R-089]] The puzzle box is powered by a rechargeable battery. | <> | <> | [[req:90,R-090]] The battery lasts for a minimum of 4 hours. @@ -481,17 +481,17 @@ documentation. Due to time constraints, the section will be left empty. |=== | ID | <> | Specification -| <> | <> | -[[req:130,R-130]] The main controller and its software do not need to be modified to implement a new puzzle module +| <> | <> | +[[req:main-static,R-130]] The main controller and its software do not need to be modified to implement a new puzzle module | <> | <> | [[req:131,R-131]] Puzzle modules can be added and removed while the main controller is powered on -| <> | <> | -[[req:132,R-132]] Puzzle modules can be added and removed while the main controller is powered off +| <> | <> | +[[req:pm-swap,R-132]] Puzzle modules can be added and removed while the main controller is powered off -| <> | <> | -[[req:133,R-133]] The puzzle box provides a single external interface for accessing and controlling game state variables +| <> | <> | +[[req:main-interface,R-133]] The puzzle box provides a single external interface for accessing and controlling game state variables |=== === Puzzle box hub diff --git a/docs/research.adoc b/docs/research.adoc index 5d4f381..a6ef255 100644 --- a/docs/research.adoc +++ b/docs/research.adoc @@ -133,8 +133,8 @@ as main controller unit: * Is available as a development kit from Farnell (<>). -<> lists the considered MCU options matching the above criteria. This -list is a compilation of microcontroller offerings from the following +<> lists the considered MCU options matching the above criteria. +This list is a compilation of microcontroller offerings from the following manufacturers: Atmel, Espressif, Raspberry Pi. Of these controllers, the Raspberry Pi RP2040 has the lowest clock speed and @@ -143,7 +143,7 @@ than the other options. It also happens to be less expensive than all other options. Due to these reasons, the RP2040 was chosen as main controller MCU. The Raspberry Pi Pico W board is utilized during development. -[[tab:1]] +[[tab:main-mcu]] .Main controller MCU candidates [%autowidth] |=== @@ -151,7 +151,7 @@ The Raspberry Pi Pico W board is utilized during development. | WFI32E01PC | 1 | 256 KB | 1 MB | 200 MHz | ESP8266 | 1 | 50 KB | 16 MB | 160 MHz -| RP2040 | 2 | 264 KB | 2 MB | 133 MHz +| RP2040 | 2 | 264 KB | 2 MB | 133 MHz{empty}footnote:[Adjusting the clock speed for the main controller is not necessary, even though the RP2040 supports clock speed configuration (see <>)] |=== === Puzzle module controller @@ -167,12 +167,12 @@ for controlling the puzzle modules: (<>). * Has a configurable clock speed (<>). -<> lists the considered MCU options matching the above criteria. This -list is a compilation of microcontroller offerings from the following +<> lists the considered MCU options matching the above criteria. +This list is a compilation of microcontroller offerings from the following manufacturers: Atmel, STMicroelectronics, Raspberry Pi. -All the MCUs listed in <> support some version of a low-power mode. The -RP2040 is again included and appears here because it supports clock speed +All the MCUs listed in <> support some version of a low-power mode. +The RP2040 is again included and appears here because it supports clock speed configuration and has a clock gate for each peripheral [2], which may make it a feasible option with regards to power consumption. Choosing the RP2040 may also simplify the development process as only a single MCU toolchain needs to be @@ -187,7 +187,7 @@ Because this year's run of this project was carried out by a team consisting only of software students, this choice remains as a recommendation. The puzzle box hardware may still use the ESP32 development kits from the 21-22 group. -[[tab:2]] +[[tab:pm-mcu]] .Puzzle module controller MCU candidates [%autowidth] |=== @@ -255,10 +255,10 @@ distributions of Debian are, so this OS is be considered familiar. === Conclusions -<> summarizes the considered operating systems based on the criteria -outlined at the start of this section. +<> summarizes the considered operating systems based on the +criteria outlined at the start of this section. -[[tab:3]] +[[tab:main-os]] .Main controller OS comparison [%autowidth] |=== @@ -279,13 +279,13 @@ keeping in mind RTOS-specific frameworks, and what features do they have? === General framework comparison -In <> is a general comparison shown of multiple different frameworks. -These are either a header-only testing framework, a testing framework -specifically designed for embedded systems, a general-purpose {cpp} library, or a -specialized {cpp} unit testing framework. The following subsections will give -more information about each framework and their features. +In <> is a general comparison shown of multiple different +frameworks. These are either a header-only testing framework, a testing +framework specifically designed for embedded systems, a general-purpose {cpp} +library, or a specialized {cpp} unit testing framework. The following +subsections will give more information about each framework and their features. -[[tab:4]] +[[tab:test-framework]] .General testing framework comparison cite:[Ali24,Joh21] [%autowidth] |=== diff --git a/docs/theme.yml b/docs/theme.yml index 5844a86..b26ad75 100644 --- a/docs/theme.yml +++ b/docs/theme.yml @@ -74,7 +74,7 @@ description-list: table: align: center border-color: transparent - cell-padding: [0.2pt, 2pt] + cell-padding: [0.2pt, 5pt] border-color: '#000000' border-width: [ 0.5pt, 0pt, 0.5pt, 0pt ] head: -- cgit v1.2.3 From 424c5a281282451b224da0ba26e35fb03bf2ecf5 Mon Sep 17 00:00:00 2001 From: lonkaars Date: Tue, 23 Apr 2024 17:48:14 +0200 Subject: remove hello world plugin test --- docs/makefile | 1 - docs/plugin/helloworld.rb | 13 ------------- 2 files changed, 14 deletions(-) delete mode 100644 docs/plugin/helloworld.rb diff --git a/docs/makefile b/docs/makefile index 452eddf..f175830 100644 --- a/docs/makefile +++ b/docs/makefile @@ -13,7 +13,6 @@ PDFDEPS += ./theme.yml ASCIIDOCTOR_ARGS += --require asciidoctor-bibtex ASCIIDOCTOR_ARGS += --require asciidoctor-pdf -# ASCIIDOCTOR_ARGS += --require ./plugin/helloworld ASCIIDOCTOR_ARGS += --require asciidoctor-interdoc-reftext ASCIIDOCTOR_ARGS += --require asciidoctor-lists ASCIIDOCTOR_ARGS += --backend pdf diff --git a/docs/plugin/helloworld.rb b/docs/plugin/helloworld.rb deleted file mode 100644 index 7bfc226..0000000 --- a/docs/plugin/helloworld.rb +++ /dev/null @@ -1,13 +0,0 @@ -class HelloWorldMacro < Asciidoctor::Extensions::BlockMacroProcessor - use_dsl - named :helloworld - - def process parent, target, attrs - return - end -end - -Asciidoctor::Extensions.register do - block_macro HelloWorldMacro -end - -- cgit v1.2.3