add disclaimers

7 files changed, 65 insertions, 31 deletions

diff --git a/.editorconfig b/.editorconfig
index cd37156..bd1f474 100644
--- a/.editorconfig
+++ b/.editorconfig
@@ -5,7 +5,7 @@ indent_style = tab
 end_of_line = lf
 insert_final_newline = true
 
-[*.md]
+[*.{md,yml}]
 indent_style = space
 indent_size = 2
 
diff --git a/docs/design.adoc b/docs/design.adoc
index 6a52b38..06cd100 100644
--- a/docs/design.adoc
+++ b/docs/design.adoc
@@ -146,7 +146,13 @@ The criteria for the main controller are:
 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.
-// TODO: this was a bad choice
+
+NOTE: This was written while we did not know the puzzle bus specifically
+requires slave-addressible I^2^C multi-master controllers to function properly.
+While the research concludes the RP2040 is a suitable microcontroller for the
+main controller, it is not. The RP2040 was still used, but has required
+implementing workarounds. Please see the handover report for more details on
+how this impacted the project cite:[handover].
 
 [[fig:main-controller-top]]
 .Main controller top-level block diagram
diff --git a/docs/handover.adoc b/docs/handover.adoc
index 6918256..77d5da0 100644
--- a/docs/handover.adoc
+++ b/docs/handover.adoc
@@ -29,16 +29,17 @@ removal or transfer of these files.
 
 [[tab:proj-comp]]
 .Project group composition
+[cols="15,35,20",width=55%]
 |===
 | Year | Name | Study path
 
-.4+| 19-20
+.4+h| 19-20
 | Daniël Janssen | Software
 | Dion Legierse | Software
 | Jop van Laanen | Hardware
 | Max van den Heijkant | Software
 
-.4+| 20-21
+.4+h| 20-21
 | Joost van Wiechen | Hardware
 | Justin Maas | Software
 | [[pn:creemers,Merel Creemers]]Merel Creemers | Hardware{empty}footnote:[The
@@ -51,18 +52,18 @@ were a hardware student that worked on the PCBs or a CMD student working on the
 puzzle box chassis.]
 | Vincent Lengowski | Hardware
 
-.5+| 21-22
+.5+h| 21-22
 | Alex van Kuijk | Hardware
 | Jef Baars | Software
 | Julian de Bruin | Software
 | Lucas van Gastel | Software
 | Toon Rockx | Hardware
 
-.2+| 22-23
+.2+h| 22-23
 | Frank Bekema | Hardware
 | Jasper Gense | Hardware
 
-.4+| 23-24
+.4+h| 23-24
 | Elwin Hammer | Software
 | [[pn:faase,Lars Faase]]Lars Faase{empty}footnote:[<<pn:faase>> was removed
 from the project group on 2024-06-03 following complaints about the lack of
diff --git a/docs/reqs.adoc b/docs/reqs.adoc
index 8ad24a8..611c8f3 100644
--- a/docs/reqs.adoc
+++ b/docs/reqs.adoc
@@ -108,7 +108,7 @@ describes all functional requirements of the puzzle box.
 === The puzzle box
 
 .Puzzle box specifications
-[cols="8h,5h,~"]
+[cols="9h,6h,~"]
 |===
 | ID | <<tab:moscow,Pri.>> | Specification
 
@@ -165,7 +165,7 @@ describes all functional requirements of the puzzle box.
 === The bomb
 
 .Bomb specifications
-[cols="8h,5h,~"]
+[cols="9h,6h,~"]
 |===
 | ID | <<tab:moscow,Pri.>> | Specification
 
@@ -198,7 +198,7 @@ describes all functional requirements of the puzzle box.
 === The game
 
 .General game specifications
-[cols="8h,5h,~"]
+[cols="9h,6h,~"]
 |===
 | ID | <<tab:moscow,Pri.>> | Specification
 
@@ -239,7 +239,7 @@ describes all functional requirements of the puzzle box.
 ==== NeoTrellis puzzle
 
 .NeoTrellis puzzle requirements
-[cols="8h,5h,~"]
+[cols="9h,6h,~"]
 |===
 | ID | <<tab:moscow,Pri.>> | Specification
 
@@ -262,7 +262,7 @@ describes all functional requirements of the puzzle box.
 ==== Software puzzle
 
 .Software puzzle requirements
-[cols="8h,5h,~"]
+[cols="9h,6h,~"]
 |===
 | ID | <<tab:moscow,Pri.>> | Specification
 
@@ -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="8h,5h,~"]
+[cols="9h,6h,~"]
 |===
 | ID | <<tab:moscow,Pri.>> | Specification
 
@@ -308,7 +308,7 @@ documentation. Due to time constraints, the section will be left empty.
 ==== Hardware puzzle
 
 .Hardware puzzle requirements
-[cols="8h,5h,~"]
+[cols="9h,6h,~"]
 |===
 | ID | <<tab:moscow,Pri.>> | Specification
 
@@ -397,7 +397,7 @@ documentation. Due to time constraints, the section will be left empty.
 ==== Vault puzzle
 
 .Vault puzzle requirements
-[cols="8h,5h,~"]
+[cols="9h,6h,~"]
 |===
 | ID | <<tab:moscow,Pri.>> | Specification
 
@@ -447,7 +447,7 @@ documentation. Due to time constraints, the section will be left empty.
 === Battery
 
 .Battery requirements
-[cols="8h,5h,~"]
+[cols="9h,6h,~"]
 |===
 | ID | <<tab:moscow,Pri.>> | Specification
 
@@ -464,7 +464,7 @@ documentation. Due to time constraints, the section will be left empty.
 === Network Communication
 
 .Communication requirements
-[cols="8h,5h,~"]
+[cols="9h,6h,~"]
 |===
 | ID | <<tab:moscow,Pri.>> | Specification
 
@@ -477,7 +477,7 @@ documentation. Due to time constraints, the section will be left empty.
 
 === Framework
 
-[cols="8h,5h,~"]
+[cols="9h,6h,~"]
 |===
 | ID | <<tab:moscow,Pri.>> | 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="8h,5h,~"]
+[cols="9h,6h,~"]
 |===
 | ID | <<tab:moscow,Pri.>> | Specification
 
@@ -516,7 +516,7 @@ technical specifications of the puzzle box.
 === Wireless communication
 
 .Wireless communication requirements
-[cols="8h,5h,~"]
+[cols="9h,6h,~"]
 |===
 | ID | <<tab:moscow,Pri.>> | Specification
 
@@ -527,7 +527,7 @@ technical specifications of the puzzle box.
 === Framework
 
 .Development framework requirements
-[cols="8h,5h,~"]
+[cols="9h,6h,~"]
 |===
 | ID | <<tab:moscow,Pri.>> | Specification
 
@@ -550,7 +550,7 @@ technical specifications of the puzzle box.
 === Main controller
 
 .Main controller requirements
-[cols="8h,5h,~"]
+[cols="9h,6h,~"]
 |===
 | ID | <<tab:moscow,Pri.>> | Specification
 
@@ -575,7 +575,7 @@ technical specifications of the puzzle box.
 
 === Puzzle module controller
 
-[cols="8h,5h,~"]
+[cols="9h,6h,~"]
 |===
 | ID | <<tab:moscow,Pri.>> | Specification
 
@@ -601,7 +601,7 @@ technical specifications of the puzzle box.
 === Vault puzzle
 
 .Vault puzzle requirements
-[cols="8h,5h,~"]
+[cols="9h,6h,~"]
 |===
 | ID | <<tab:moscow,Pri.>> | Specification
 
@@ -627,7 +627,7 @@ technical specifications of the puzzle box.
 === Bomb
 
 .Bomb requirements
-[cols="8h,5h,~"]
+[cols="9h,6h,~"]
 |===
 | ID | <<tab:moscow,Pri.>> | 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="8h,~"]
+[cols="9h,~"]
 |===
 | ID | Precondition
 
@@ -666,7 +666,7 @@ preconditions and cannot be changed.
 This section lists requirements that apply to documentation produced during
 this project.
 
-[cols="8h,5h,~"]
+[cols="9h,6h,~"]
 |===
 | ID | <<tab:moscow,Pri.>> | Specification
 
diff --git a/docs/research.adoc b/docs/research.adoc
index 753206c..acab4ab 100644
--- a/docs/research.adoc
+++ b/docs/research.adoc
@@ -143,6 +143,13 @@ 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.
 
+NOTE: This was written while we did not know the puzzle bus specifically
+requires slave-addressible I^2^C multi-master controllers to function properly.
+While the research concludes the RP2040 is a suitable microcontroller for the
+main controller, it is not. The RP2040 was still used, but has required
+implementing workarounds. Please see the handover report for more details on
+how this impacted the project cite:[handover].
+
 [[tab:main-mcu]]
 .Main controller MCU candidates
 [%autowidth]
@@ -173,10 +180,10 @@ manufacturers: Atmel, STMicroelectronics, Raspberry Pi.
 
 All the MCUs listed in <<tab:pm-mcu>> 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.
+configuration and has a clock gate for each peripheral cite:[rp2040ds], 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
@@ -187,6 +194,10 @@ 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.
 
+NOTE: This was written while we did not know the puzzle bus specifically
+requires slave-addressible I^2^C multi-master controllers to function properly.
+We have not verified if the PIC16F15276 supports this feature.
+
 [[tab:pm-mcu]]
 .Puzzle module controller MCU candidates
 [%autowidth]
diff --git a/docs/share/refs.bib b/docs/share/refs.bib
index b6fe625..1c37465 100644
--- a/docs/share/refs.bib
+++ b/docs/share/refs.bib
@@ -166,6 +166,14 @@
 	year = {2024},
 }
 
+@techreport{handover,
+	author = {Blansch, Loek Le and Hammer, Elwin and Faase, Lars and in 't Anker, Thomas},
+	title = {Handover Report},
+	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},
diff --git a/docs/theme.yml b/docs/theme.yml
index b26ad75..49f729f 100644
--- a/docs/theme.yml
+++ b/docs/theme.yml
@@ -61,6 +61,7 @@ toc:
 caption:
   align: center
   end: bottom
+  margin_inside: 6pt
 
 image:
   align: center
@@ -98,3 +99,10 @@ footer:
     center:
       content: '{page-number}'
 
+admonition:
+  column_rule_color: '#000000'
+  column_rule_width: 1pt
+  padding: [3pt, 6pt, 3pt, 6pt]
+  label:
+    font_style: bold
+