WIP handover edits

3 files changed, 164 insertions, 148 deletions

diff --git a/docs/.gitignore b/docs/.gitignore
index a2f45c2..da49ef2 100644
--- a/docs/.gitignore
+++ b/docs/.gitignore
@@ -1,5 +1,6 @@
 *.pdf
 res
+.$*.bkp
 
 # i know this is bad
 Gemfile.lock
diff --git a/docs/figs.drawio b/docs/figs.drawio
index a40503b..042ce15 100644
--- a/docs/figs.drawio
+++ b/docs/figs.drawio
@@ -1,4 +1,4 @@
-<mxfile host="Electron" modified="2024-03-17T13:05:37.082Z" agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/23.1.5 Chrome/120.0.6099.109 Electron/28.1.0 Safari/537.36" etag="7STPuaY27yiGeP_RMlUo" version="23.1.5" type="device" pages="12">
+<mxfile host="Electron" modified="2024-06-20T12:26:00.414Z" agent="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/24.5.3 Chrome/124.0.6367.207 Electron/30.0.6 Safari/537.36" etag="bh9oF_6ZjHwPEw7YpXsL" version="24.5.3" type="device" pages="12">
   <diagram name="planning-condensed" id="ntlEKQOA_ElMvQzKZB-_">
     <mxGraphModel dx="1646" dy="488" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
       <root>
@@ -213,11 +213,11 @@
     </mxGraphModel>
   </diagram>
   <diagram id="n9IdmxlkFl1pJjqhBrGT" name="system-bus">
-    <mxGraphModel dx="1422" dy="822" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
+    <mxGraphModel dx="566" dy="347" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
       <root>
         <mxCell id="0" />
         <mxCell id="1" parent="0" />
-        <mxCell id="EFqebEYhPqh4IJWovyJC-1" value="Puzzle bus&lt;br&gt;(I²C + power)" style="line;strokeWidth=4;html=1;perimeter=backbonePerimeter;points=[];outlineConnect=0;align=right;labelPosition=left;verticalLabelPosition=middle;verticalAlign=middle;spacingTop=0;spacing=8;fontFamily=Arial;" parent="1" vertex="1">
+        <mxCell id="EFqebEYhPqh4IJWovyJC-1" value="puzzle bus&lt;br&gt;(I²C + power)" style="line;strokeWidth=4;html=1;perimeter=backbonePerimeter;points=[];outlineConnect=0;align=right;labelPosition=left;verticalLabelPosition=middle;verticalAlign=middle;spacingTop=0;spacing=8;fontFamily=Arial;" parent="1" vertex="1">
           <mxGeometry x="80" y="110" width="320" height="20" as="geometry" />
         </mxCell>
         <mxCell id="EFqebEYhPqh4IJWovyJC-3" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;startArrow=classic;startFill=1;fontFamily=Arial;" parent="1" source="EFqebEYhPqh4IJWovyJC-2" target="EFqebEYhPqh4IJWovyJC-1" edge="1">
@@ -228,7 +228,7 @@
             </Array>
           </mxGeometry>
         </mxCell>
-        <mxCell id="EFqebEYhPqh4IJWovyJC-2" value="Main controller" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Arial;" parent="1" vertex="1">
+        <mxCell id="EFqebEYhPqh4IJWovyJC-2" value="main controller" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Arial;" parent="1" vertex="1">
           <mxGeometry x="80" width="80" height="80" as="geometry" />
         </mxCell>
         <mxCell id="EFqebEYhPqh4IJWovyJC-11" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;startArrow=classic;startFill=1;fontFamily=Arial;" parent="1" source="EFqebEYhPqh4IJWovyJC-4" target="EFqebEYhPqh4IJWovyJC-1" edge="1">
@@ -239,7 +239,7 @@
             </Array>
           </mxGeometry>
         </mxCell>
-        <mxCell id="EFqebEYhPqh4IJWovyJC-4" value="Puzzle module 3&lt;br&gt;(neotrellis)" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Arial;" parent="1" vertex="1">
+        <mxCell id="EFqebEYhPqh4IJWovyJC-4" value="neotrellis puzzle module" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Arial;" parent="1" vertex="1">
           <mxGeometry x="200" y="160" width="80" height="80" as="geometry" />
         </mxCell>
         <mxCell id="EFqebEYhPqh4IJWovyJC-10" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;startArrow=classic;startFill=1;fontFamily=Arial;" parent="1" source="EFqebEYhPqh4IJWovyJC-5" target="EFqebEYhPqh4IJWovyJC-1" edge="1">
@@ -250,7 +250,7 @@
             </Array>
           </mxGeometry>
         </mxCell>
-        <mxCell id="EFqebEYhPqh4IJWovyJC-5" value="Puzzle module 4&lt;br style=&quot;border-color: var(--border-color);&quot;&gt;(safe)" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Arial;" parent="1" vertex="1">
+        <mxCell id="EFqebEYhPqh4IJWovyJC-5" value="vault puzzle module" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Arial;" parent="1" vertex="1">
           <mxGeometry x="320" y="160" width="80" height="80" as="geometry" />
         </mxCell>
         <mxCell id="EFqebEYhPqh4IJWovyJC-8" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;startArrow=classic;startFill=1;fontFamily=Arial;" parent="1" source="EFqebEYhPqh4IJWovyJC-6" target="EFqebEYhPqh4IJWovyJC-1" edge="1">
@@ -261,7 +261,7 @@
             </Array>
           </mxGeometry>
         </mxCell>
-        <mxCell id="EFqebEYhPqh4IJWovyJC-6" value="Puzzle module 1&lt;br&gt;(software)" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Arial;" parent="1" vertex="1">
+        <mxCell id="EFqebEYhPqh4IJWovyJC-6" value="software puzzle module" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Arial;" parent="1" vertex="1">
           <mxGeometry x="200" width="80" height="80" as="geometry" />
         </mxCell>
         <mxCell id="EFqebEYhPqh4IJWovyJC-9" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;startArrow=classic;startFill=1;fontFamily=Arial;" parent="1" source="EFqebEYhPqh4IJWovyJC-7" target="EFqebEYhPqh4IJWovyJC-1" edge="1">
@@ -272,7 +272,7 @@
             </Array>
           </mxGeometry>
         </mxCell>
-        <mxCell id="EFqebEYhPqh4IJWovyJC-7" value="Puzzle module 2&lt;br style=&quot;border-color: var(--border-color);&quot;&gt;(hardware)" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Arial;" parent="1" vertex="1">
+        <mxCell id="EFqebEYhPqh4IJWovyJC-7" value="hardware puzzle module" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Arial;" parent="1" vertex="1">
           <mxGeometry x="320" width="80" height="80" as="geometry" />
         </mxCell>
         <mxCell id="EFqebEYhPqh4IJWovyJC-13" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;fontFamily=Arial;" parent="1" source="EFqebEYhPqh4IJWovyJC-12" target="EFqebEYhPqh4IJWovyJC-1" edge="1">
@@ -283,19 +283,19 @@
             </Array>
           </mxGeometry>
         </mxCell>
-        <mxCell id="EFqebEYhPqh4IJWovyJC-12" value="Power supply&lt;br&gt;(battery pack)" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Arial;" parent="1" vertex="1">
+        <mxCell id="EFqebEYhPqh4IJWovyJC-12" value="power supply&lt;br&gt;(battery pack)" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Arial;" parent="1" vertex="1">
           <mxGeometry x="80" y="160" width="80" height="80" as="geometry" />
         </mxCell>
       </root>
     </mxGraphModel>
   </diagram>
   <diagram id="h3DvyZ0KajeRp1tPME5F" name="system-top">
-    <mxGraphModel dx="1422" dy="822" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
+    <mxGraphModel dx="566" dy="347" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
       <root>
         <mxCell id="0" />
         <mxCell id="1" parent="0" />
-        <mxCell id="nQz1uFQE7kBfjPpRPLva-4" value="Puzzle outputs" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;labelPosition=right;verticalLabelPosition=middle;align=left;verticalAlign=middle;spacing=8;fontFamily=Arial;" parent="1" source="nQz1uFQE7kBfjPpRPLva-1" target="nQz1uFQE7kBfjPpRPLva-3" edge="1">
-          <mxGeometry x="-0.8049" y="-20" relative="1" as="geometry">
+        <mxCell id="nQz1uFQE7kBfjPpRPLva-4" value="puzzle outputs" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;labelPosition=right;verticalLabelPosition=middle;align=left;verticalAlign=middle;spacing=8;fontFamily=Arial;" parent="1" source="nQz1uFQE7kBfjPpRPLva-1" target="nQz1uFQE7kBfjPpRPLva-3" edge="1">
+          <mxGeometry x="-0.8054" y="-20" relative="1" as="geometry">
             <Array as="points">
               <mxPoint x="230" y="110" />
               <mxPoint x="230" y="30" />
@@ -311,10 +311,10 @@
             </Array>
           </mxGeometry>
         </mxCell>
-        <mxCell id="nQz1uFQE7kBfjPpRPLva-1" value="Puzzle box" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Arial;" parent="1" vertex="1">
+        <mxCell id="nQz1uFQE7kBfjPpRPLva-1" value="puzzle box" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Arial;" parent="1" vertex="1">
           <mxGeometry x="110" y="90" width="80" height="80" as="geometry" />
         </mxCell>
-        <mxCell id="nQz1uFQE7kBfjPpRPLva-2" value="Puzzle inputs" style="endArrow=classic;html=1;rounded=0;edgeStyle=orthogonalEdgeStyle;elbow=vertical;labelPosition=left;verticalLabelPosition=middle;align=right;verticalAlign=middle;spacing=8;fontFamily=Arial;" parent="1" source="nQz1uFQE7kBfjPpRPLva-3" target="nQz1uFQE7kBfjPpRPLva-1" edge="1">
+        <mxCell id="nQz1uFQE7kBfjPpRPLva-2" value="puzzle inputs" style="endArrow=classic;html=1;rounded=0;edgeStyle=orthogonalEdgeStyle;elbow=vertical;labelPosition=left;verticalLabelPosition=middle;align=right;verticalAlign=middle;spacing=8;fontFamily=Arial;" parent="1" source="nQz1uFQE7kBfjPpRPLva-3" target="nQz1uFQE7kBfjPpRPLva-1" edge="1">
           <mxGeometry x="0.6098" width="50" height="50" relative="1" as="geometry">
             <mxPoint x="70" y="110" as="sourcePoint" />
             <mxPoint x="120" y="130" as="targetPoint" />
@@ -325,10 +325,10 @@
             <mxPoint as="offset" />
           </mxGeometry>
         </mxCell>
-        <mxCell id="nQz1uFQE7kBfjPpRPLva-3" value="Player(s)" style="shape=umlActor;verticalLabelPosition=bottom;verticalAlign=top;html=1;outlineConnect=0;fontFamily=Arial;" parent="1" vertex="1">
+        <mxCell id="nQz1uFQE7kBfjPpRPLva-3" value="player(s)" style="shape=umlActor;verticalLabelPosition=bottom;verticalAlign=top;html=1;outlineConnect=0;fontFamily=Arial;" parent="1" vertex="1">
           <mxGeometry x="135" width="30" height="60" as="geometry" />
         </mxCell>
-        <mxCell id="nQz1uFQE7kBfjPpRPLva-6" value="Charger" style="endArrow=classic;html=1;rounded=0;edgeStyle=elbowEdgeStyle;elbow=vertical;labelPosition=left;verticalLabelPosition=middle;align=right;verticalAlign=middle;dashed=1;spacing=8;fontFamily=Arial;" parent="1" target="nQz1uFQE7kBfjPpRPLva-1" edge="1">
+        <mxCell id="nQz1uFQE7kBfjPpRPLva-6" value="charger" style="endArrow=classic;html=1;rounded=0;edgeStyle=elbowEdgeStyle;elbow=vertical;labelPosition=left;verticalLabelPosition=middle;align=right;verticalAlign=middle;dashed=1;spacing=8;fontFamily=Arial;" parent="1" target="nQz1uFQE7kBfjPpRPLva-1" edge="1">
           <mxGeometry x="-1" width="50" height="50" relative="1" as="geometry">
             <mxPoint x="70" y="150" as="sourcePoint" />
             <mxPoint x="90" y="150.2" as="targetPoint" />
@@ -342,18 +342,18 @@
             <mxPoint as="offset" />
           </mxGeometry>
         </mxCell>
-        <mxCell id="rSJYnGe5hIWkDpeJhH4a-5" value="Bomb" style="rounded=0;whiteSpace=wrap;html=1;dashed=1;fontFamily=Arial;" parent="1" vertex="1">
+        <mxCell id="rSJYnGe5hIWkDpeJhH4a-5" value="bomb" style="rounded=0;whiteSpace=wrap;html=1;dashed=1;fontFamily=Arial;" parent="1" vertex="1">
           <mxGeometry x="310" y="90" width="80" height="80" as="geometry" />
         </mxCell>
       </root>
     </mxGraphModel>
   </diagram>
   <diagram id="V5677hnVqFOUu4LEfIlK" name="main-controller-top">
-    <mxGraphModel dx="1422" dy="822" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
+    <mxGraphModel dx="673" dy="413" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
       <root>
         <mxCell id="0" />
         <mxCell id="1" parent="0" />
-        <mxCell id="E0vY4Tb27X8IZZSuRO_E-1" value="Main controller" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Arial;" parent="1" vertex="1">
+        <mxCell id="E0vY4Tb27X8IZZSuRO_E-1" value="main controller" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Arial;" parent="1" vertex="1">
           <mxGeometry x="70" y="60" width="80" height="80" as="geometry" />
         </mxCell>
         <mxCell id="E0vY4Tb27X8IZZSuRO_E-2" value="" style="endArrow=classic;startArrow=classic;html=1;rounded=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;fontFamily=Arial;" parent="1" source="_QeJvxVuYCE5Bx7Zj5Sh-1" target="E0vY4Tb27X8IZZSuRO_E-1" edge="1">
@@ -362,7 +362,7 @@
             <mxPoint x="140" y="110" as="targetPoint" />
           </mxGeometry>
         </mxCell>
-        <mxCell id="_QeJvxVuYCE5Bx7Zj5Sh-1" value="Puzzle bus" style="line;strokeWidth=4;html=1;perimeter=backbonePerimeter;points=[];outlineConnect=0;align=right;labelPosition=left;verticalLabelPosition=middle;verticalAlign=middle;spacingTop=0;spacing=8;fontFamily=Arial;" parent="1" vertex="1">
+        <mxCell id="_QeJvxVuYCE5Bx7Zj5Sh-1" value="puzzle bus" style="line;strokeWidth=4;html=1;perimeter=backbonePerimeter;points=[];outlineConnect=0;align=right;labelPosition=left;verticalLabelPosition=middle;verticalAlign=middle;spacingTop=0;spacing=8;fontFamily=Arial;" parent="1" vertex="1">
           <mxGeometry x="70" y="170" width="80" height="20" as="geometry" />
         </mxCell>
         <mxCell id="eXW24AF1M1Q80XVxQB3d-1" value="Wi-Fi" style="shape=link;html=1;rounded=0;edgeStyle=orthogonalEdgeStyle;dashed=1;labelPosition=center;verticalLabelPosition=top;align=center;verticalAlign=bottom;fontFamily=Arial;" parent="1" source="E0vY4Tb27X8IZZSuRO_E-1" edge="1">
@@ -376,11 +376,11 @@
     </mxGraphModel>
   </diagram>
   <diagram name="puzzle-module-top" id="5pAH2Yn7Y32GPKnI9U_5">
-    <mxGraphModel dx="1422" dy="822" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
+    <mxGraphModel dx="566" dy="347" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
       <root>
         <mxCell id="BVMe8izj958RTkFm3z60-0" />
         <mxCell id="BVMe8izj958RTkFm3z60-1" parent="BVMe8izj958RTkFm3z60-0" />
-        <mxCell id="BVMe8izj958RTkFm3z60-2" value="Puzzle module" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Arial;" parent="BVMe8izj958RTkFm3z60-1" vertex="1">
+        <mxCell id="BVMe8izj958RTkFm3z60-2" value="puzzle module" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Arial;" parent="BVMe8izj958RTkFm3z60-1" vertex="1">
           <mxGeometry x="120" y="10" width="80" height="80" as="geometry" />
         </mxCell>
         <mxCell id="BVMe8izj958RTkFm3z60-3" value="" style="endArrow=classic;startArrow=classic;html=1;rounded=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;fontFamily=Arial;" parent="BVMe8izj958RTkFm3z60-1" source="BVMe8izj958RTkFm3z60-4" target="BVMe8izj958RTkFm3z60-2" edge="1">
@@ -389,17 +389,17 @@
             <mxPoint x="190" y="60" as="targetPoint" />
           </mxGeometry>
         </mxCell>
-        <mxCell id="BVMe8izj958RTkFm3z60-4" value="Puzzle bus" style="line;strokeWidth=4;html=1;perimeter=backbonePerimeter;points=[];outlineConnect=0;align=right;labelPosition=left;verticalLabelPosition=middle;verticalAlign=middle;spacingTop=0;spacing=8;fontFamily=Arial;" parent="BVMe8izj958RTkFm3z60-1" vertex="1">
+        <mxCell id="BVMe8izj958RTkFm3z60-4" value="puzzle bus" style="line;strokeWidth=4;html=1;perimeter=backbonePerimeter;points=[];outlineConnect=0;align=right;labelPosition=left;verticalLabelPosition=middle;verticalAlign=middle;spacingTop=0;spacing=8;fontFamily=Arial;" parent="BVMe8izj958RTkFm3z60-1" vertex="1">
           <mxGeometry x="120" y="120" width="80" height="20" as="geometry" />
         </mxCell>
-        <mxCell id="tTlcU9ZqAkPjyI4FRPs--0" value="Puzzle outputs" style="endArrow=classic;html=1;rounded=0;edgeStyle=orthogonalEdgeStyle;labelPosition=right;verticalLabelPosition=middle;align=left;verticalAlign=middle;spacing=8;fontFamily=Arial;" parent="BVMe8izj958RTkFm3z60-1" source="BVMe8izj958RTkFm3z60-2" edge="1">
+        <mxCell id="tTlcU9ZqAkPjyI4FRPs--0" value="puzzle outputs" style="endArrow=classic;html=1;rounded=0;edgeStyle=orthogonalEdgeStyle;labelPosition=right;verticalLabelPosition=middle;align=left;verticalAlign=middle;spacing=8;fontFamily=Arial;" parent="BVMe8izj958RTkFm3z60-1" source="BVMe8izj958RTkFm3z60-2" edge="1">
           <mxGeometry x="1" width="50" height="50" relative="1" as="geometry">
             <mxPoint x="150" y="130" as="sourcePoint" />
             <mxPoint x="240" y="50" as="targetPoint" />
             <mxPoint as="offset" />
           </mxGeometry>
         </mxCell>
-        <mxCell id="tTlcU9ZqAkPjyI4FRPs--1" value="Puzzle inputs" style="endArrow=classic;html=1;rounded=0;edgeStyle=orthogonalEdgeStyle;labelPosition=left;verticalLabelPosition=middle;align=right;verticalAlign=middle;spacing=8;fontFamily=Arial;" parent="BVMe8izj958RTkFm3z60-1" target="BVMe8izj958RTkFm3z60-2" edge="1">
+        <mxCell id="tTlcU9ZqAkPjyI4FRPs--1" value="puzzle inputs" style="endArrow=classic;html=1;rounded=0;edgeStyle=orthogonalEdgeStyle;labelPosition=left;verticalLabelPosition=middle;align=right;verticalAlign=middle;spacing=8;fontFamily=Arial;" parent="BVMe8izj958RTkFm3z60-1" target="BVMe8izj958RTkFm3z60-2" edge="1">
           <mxGeometry x="-1" width="50" height="50" relative="1" as="geometry">
             <mxPoint x="80" y="50" as="sourcePoint" />
             <mxPoint x="270" y="60" as="targetPoint" />
@@ -410,11 +410,11 @@
     </mxGraphModel>
   </diagram>
   <diagram name="power-supply-top" id="OyUTR4VJhJkLCMkp9sBg">
-    <mxGraphModel dx="1422" dy="822" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
+    <mxGraphModel dx="471" dy="289" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
       <root>
         <mxCell id="JhLPvhhKfH0WU0wtARFb-0" />
         <mxCell id="JhLPvhhKfH0WU0wtARFb-1" parent="JhLPvhhKfH0WU0wtARFb-0" />
-        <mxCell id="JhLPvhhKfH0WU0wtARFb-2" value="Power supply" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Arial;" parent="JhLPvhhKfH0WU0wtARFb-1" vertex="1">
+        <mxCell id="JhLPvhhKfH0WU0wtARFb-2" value="power supply" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Arial;" parent="JhLPvhhKfH0WU0wtARFb-1" vertex="1">
           <mxGeometry x="120" y="10" width="80" height="80" as="geometry" />
         </mxCell>
         <mxCell id="JhLPvhhKfH0WU0wtARFb-3" value="" style="endArrow=none;startArrow=classic;html=1;rounded=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;fontFamily=Arial;endFill=0;" parent="JhLPvhhKfH0WU0wtARFb-1" source="JhLPvhhKfH0WU0wtARFb-4" target="JhLPvhhKfH0WU0wtARFb-2" edge="1">
@@ -423,10 +423,10 @@
             <mxPoint x="190" y="60" as="targetPoint" />
           </mxGeometry>
         </mxCell>
-        <mxCell id="JhLPvhhKfH0WU0wtARFb-4" value="Puzzle bus" style="line;strokeWidth=4;html=1;perimeter=backbonePerimeter;points=[];outlineConnect=0;align=right;labelPosition=left;verticalLabelPosition=middle;verticalAlign=middle;spacingTop=0;spacing=8;fontFamily=Arial;" parent="JhLPvhhKfH0WU0wtARFb-1" vertex="1">
+        <mxCell id="JhLPvhhKfH0WU0wtARFb-4" value="puzzle bus" style="line;strokeWidth=4;html=1;perimeter=backbonePerimeter;points=[];outlineConnect=0;align=right;labelPosition=left;verticalLabelPosition=middle;verticalAlign=middle;spacingTop=0;spacing=8;fontFamily=Arial;" parent="JhLPvhhKfH0WU0wtARFb-1" vertex="1">
           <mxGeometry x="120" y="120" width="80" height="20" as="geometry" />
         </mxCell>
-        <mxCell id="G88CfNIh1Ql9ssuBFCwE-0" value="Charger" style="endArrow=classic;html=1;rounded=0;edgeStyle=elbowEdgeStyle;elbow=vertical;labelPosition=left;verticalLabelPosition=middle;align=right;verticalAlign=middle;dashed=1;spacing=8;fontFamily=Arial;" parent="JhLPvhhKfH0WU0wtARFb-1" target="JhLPvhhKfH0WU0wtARFb-2" edge="1">
+        <mxCell id="G88CfNIh1Ql9ssuBFCwE-0" value="charger" style="endArrow=classic;html=1;rounded=0;edgeStyle=elbowEdgeStyle;elbow=vertical;labelPosition=left;verticalLabelPosition=middle;align=right;verticalAlign=middle;dashed=1;spacing=8;fontFamily=Arial;" parent="JhLPvhhKfH0WU0wtARFb-1" target="JhLPvhhKfH0WU0wtARFb-2" edge="1">
           <mxGeometry x="-1" width="50" height="50" relative="1" as="geometry">
             <mxPoint x="80" y="50" as="sourcePoint" />
             <mxPoint x="110" y="150" as="targetPoint" />
diff --git a/docs/handover.adoc b/docs/handover.adoc
index c948b7b..0e8af5a 100644
--- a/docs/handover.adoc
+++ b/docs/handover.adoc
@@ -1,13 +1,19 @@
 :document: Handover Report
 include::share/meta.adoc[]
 
-== A Note Before Reading
-The team of year 2023-2024 consisted of only software students, meaning no 
-hardware was developed in this year. We were tasked with simplifying the 
-software to the point where it would only have to be ported into the new hardware,
-which was designed in the year 2022-2023. The goal of this year is to create
-a software framework which can be used to implement new puzzles and to make the 
-development process of these puzzles easier. 
+== Introduction
+
+This is an (at times slightly informal) document that summarizes how the 23-24
+run of this project went. We found the previous handover documents to be
+unhelpful when determining the 'actual' state of the project in the first few
+weeks, and felt they did not address the pitfalls of this project.
+
+The team of year 2023-2024 consisted of only software students (see
+<<tab:proj-comp>>), meaning no hardware was developed in this year. The goal of
+this year is to create a software framework which can be used to implement new
+puzzles and to make the development process of these puzzles easier, and allow
+the entire software stack to be ported to the the hardware designed by the
+22-23 group.
 
 Previous years' groups have put their predecessor's documents inside their own
 project folder, which has resulted in what we called the 'Russian doll folder
@@ -19,35 +25,20 @@ require credentials to log in. Please note that this is very much unofficial,
 and is not managed or endorsed by Avans. <<pn:blansch>> is the contact for
 removal or transfer of these files.
 
-== Introduction
-
-This is an informal document that summarizes how the 23-24 run of this project
-went. We found the previous handover documents to be unhelpful when determining
-the 'actual' state of the project in the first few weeks, and felt they did not
-address the pitfalls of this project.
+== Group history
 
-== Group History
-
-=== 19-20
-
-.19-20 group composition
-[%autowidth]
+[[tab:proj-comp]]
+.Project group composition
 |===
-| Name | Study path
+| Year | Name | Study path
 
+.4+| 19-20
 | Daniël Janssen | Software
 | Dion Legierse | Software
 | Jop van Laanen | Hardware
 | Max van den Heijkant | Software
-|===
-
-=== 20-21
-
-.20-21 group composition
-[%autowidth]
-|===
-| Name | Study path
 
+.4+| 20-21
 | Joost van Wiechen | Hardware
 | Justin Maas | Software
 | [[pn:creemers,Merel Creemers]]Merel Creemers | Hardware{empty}footnote:[The
@@ -59,40 +50,19 @@ may indicate that they were removed from the project group. I am unsure if they
 were a hardware student that worked on the PCBs or a CMD student working on the
 puzzle box chassis.]
 | Vincent Lengowski | Hardware
-|===
-
-=== 21-22
-
-.21-22 group composition
-[%autowidth]
-|===
-| Name | Study path
 
+.5+| 21-22
 | Alex van Kuijk | Hardware
 | Jef Baars | Software
 | Julian de Bruin | Software
 | Lucas van Gastel | Software
 | Toon Rockx | Hardware
-|===
-
-=== 22-23
-
-.22-23 group composition
-[%autowidth]
-|===
-| Name | Study path
 
+.2+| 22-23
 | Frank Bekema | Hardware
 | Jasper Gense | Hardware
-|===
-
-=== 23-24 (current)
-
-.23-24 group composition
-[%autowidth]
-|===
-| Name | Study path
 
+.4+| 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
@@ -101,57 +71,79 @@ communication, and lack of motivation] | Software
 | Thomas in 't Anker | Software
 |===
 
-== Project State
-The current project state is as follows: No new hardware has been designed 
-or developed this year. The software was completely revised, now consisting of a 
-a puzzle bus driver, a main controller, a simple CLI application, and two puzzle 
-modules. Namely the puzzle modules 'Vault' and 'Neotrellis', both using an Arduino 
-as the controller. The main controller (a RPI Pico W) can interact with the 
-different puzzle modules using an I^2^C bus. The I^2^C bus has been configured to 
-be a multi-master I^2^C bus, allowing the puzzle modules and the main controller 
-to initiate a I^2^C transmission. The main controller is able to find 
-new puzzle modules on startup, and does not check for new modules afterwards. A 
-simple CLI application has been developed, which can communicate with the main 
-controller through a TCP connection and simple commands. 
-
-In short: A puzzle bus driver has been implemented to allow for communication 
-between the main controller and the puzzle modules. A CLI application was developed 
-which connects with the main controller to monitor/edit the game state. And the 
-software for the puzzle modules 'Vault' and 'Neotrellis' is in the prototype state.
+== Project state
+
+The current project state is as follows:
+
+* No new hardware has been designed or developed this year
+* The software was completely revised, now consisting of
+** a puzzle bus driver (``pbdrv``)
+** a main controller
+** a simple CLI application
+** two puzzle modules ('Vault' and 'NeoTrellis') integrated using the puzzle
+	 bus driver
+
+* The main controller (a RPI Pico W) can interact with the different puzzle
+	modules using a central shared I^2^C bus (referred to as the 'puzzle bus')
+* The main controller is able to find new puzzle modules on startup, and does
+	not check for new modules afterwards.
+* A simple CLI application has been developed, which can communicate with the
+	main controller through a TCP connection and allows control over various
+	aspects of the puzzle box using simple commands.
 
 == Incidents
 
 During this year's run of the project, we encountered several difficuties we
-feel need to be addressed. We recommend that these incidents are analyzed by
-future project groups and incorporated into the risk analysis section of future
-project plan documents.
+feel need to be addressed in order to be mitigated in future runs of the
+project. We recommend that these incidents are analyzed by future project
+groups and incorporated into the risk analysis section of future project plan
+documents.
 
-=== Misconceptions
+=== Documentation
 
-Make sure to know what you are developing and do some research beforehand, to make 
-sure you have the complete picture about what you are using. Sounds stupid, but it 
-happened for multiple project attempts, and caused time loss. This also includes 
-when you want to use documentation of previous years: go through the documentation 
-and verify it on the lowest possible level for the same reason as previously 
-mentioned.  
+We spent too much time working on documentation at the start of the project.
+Make sure you set clear deadlines for documentation, and try not to spend too
+much time on review procedures, as these cost a lot of time.
 
-=== I^2^C
+Our project documentation was originally written in Microsoft Word, but we
+later transferred all documentation to AsciiDoc because of issues where
+OneDrive would roll back changes. If possible, use a documentation system or
+format that allows using an external version control system like Git to avoid
+losing content.
+
+=== Misconceptions
 
-I^2^C is easy to implement but also easy to underestimate, this project requires a 
-multi-master structure as communication is otherwise too complicated compared to 
-other means of communication.
+Make sure to know what you are developing and do some research beforehand, to
+make sure you have a complete picture about what you are using. Sounds stupid,
+but it happened for multiple project attempts, and caused time loss. This also
+includes when you want to use documentation of previous years: go through the
+documentation and verify it on the lowest possible level for the same reason as
+previously mentioned.  
 
-For I^2^C on hardware level: make sure to use pull-up resistors as it is otherwise 
-impossible to use I^2^C due to incorrect messages. This is also required for 
-controllers which are connected to the I^2^C bus. Make sure to use I^2^C devices 
-that support arbitration when using it as a multi-master. 
+=== I^2^C
 
-The RPI Pico W (RP2040) does supports multi-master to the point of being able to 
-receive messages from other multi-masters as a slave while being configured as master. 
-Everything else about the I^2^C bus works, but due to this limitation a workaround has 
-been implemented to be able to continue using the RPI Pico W. 
-To simplify; a controller is needed which supports multi-master 
-while being able to be addressed as a slave.
+I^2^C is used because it is widely available and easy to implement. We strongly
+recommend 3rd year software students to refresh their knowledge on I^2^C before
+making major design decisions that rely on their conception of how to I^2^C bus
+works.
+
+Please note the following differences between I^2^C devices:
+
+- Regular I^2^C slave peripherals are allowed on the puzzle bus, and can be
+	connected to the puzzle bus as long as they do not cause issues with
+	addressing.
+- I^2^C master controllers must have hardware support for a multi-master
+	hardware configuration (i.e. support bus arbitration on a hardware level).
+	Arbitration support is required to prevent message corruption or electrical
+	shorts in a multi-master setup. Multi-master controllers may also be
+	connected to the puzzle bus, but only as long as they only interact with
+	regular I^2^C slave devices.
+- I^2^C multi-master controllers that are slave-addressable in master mode are
+	the only kind of I^2^C controller suitable for use in puzzle modules.
+
+The RP2040 supports multi-master, but is not addressable as a slave in master
+mode. Due to time constraints, this was mitigated using a workaround (see
+<<fixme:rp2040-i2c>>).
 
 === Development hardware availability
 
@@ -160,19 +152,22 @@ include research on the product lifecycle. Choosing boards/chips that have
 planned long term support makes it easier for the next project team to order
 and use the same chips/boards instead of having to find new ones.
 
-This also includes having enough development boards for multiple people to
-program using the same setup, e.g. the RPI Pico W requires another RPI Pico W
-to be debugged, effectively requiring the project team to have at least 4 RPI
-Pico Ws to be able to develop in the same environment (if there are 2 software
-students).
+Due to a lack of foresight, only 2 Picos were ordered this year, which caused
+unoptimal workload spread during the last weeks of the project. Because of
+this, we also strongly recommend making enough development boards available for
+multiple people to develop using the same setup. Note that the RPI Pico is a
+special case, as it requires another Pico for debugging, effectively requiring
+double the amount of hardware to support developers.
 
 === Auxiliary workarounds and technical limitations
 
-This section details unelegant workarounds that should be removed from the
-code. Workarounds that should be removed are marked with ``FIXME:`` comments
-referring to one of the workarounds mentioned in this section.
+This section details workarounds that were implemented instead of being fixed
+due to time constraints or project scope. Workarounds that should be removed
+are marked with ``FIXME:`` comments referring to one of the workarounds
+mentioned in this section.
 
-RP2040 I^2^C limitations::
+[[fixme:rp2040-i2c,RP2040 I^2^C limitations]]
+<<fixme:rp2040-i2c>>::
 - All puzzle module drivers have a hard-coded 2 second delay between receiving
 	the MAGIC handshake request and the MAGIC handshake response handler. This
 	was done to ensure responses are not ignored by the RP2040 (main controller)
@@ -189,23 +184,43 @@ puzzle modules instead. FreeRTOS does not have an implementation of the
 
 == Recommendations
 
+This section details our recommendations on course of action for future project
+groups.
+
 === Imperatives
-* The 22-23 design document already mentions that the application of the I^2^C
-bus is in a multi-master configuration, but does not mention that this only
-works when pull-up resistors are used on the SCL and SDA lines. The pull-up
-resistors are required, as omitting them makes the bus arbitration process
-very inconsistent which causes frames to be dropped entirely.
-* Start creating prototypes as fast as possible; this benefits the project in the long run, 
-as you have already shown that certain parts of the project are already working and "only" 
-need to be integrated.
-* The Atmega328P chip is sufficient for the puzzle modules as it has enough I/O, mutli-master
-hardware support, and the ability to be addressed as a slave while being in master mode. 
-* The hardware design can be taken from the year 22-23, and the game rules are taken from 
-the year 20-21.
-
-// TODO: rename this bitch
-=== Loose imperatives 
-* The RPI Pico W has programmable IO modules, making it possible to create an I^2^C driver 
-that allows multi-master communication while still being addressable as a slave.
+
+The following points must not be dismissed by future project groups, as they
+are critical for project success:
+
+- The 22-23 design document already mentions that the application of the I^2^C
+	bus is in a multi-master configuration, but does not mention that this only
+	works when pull-up resistors are used on the SCL and SDA lines. The pull-up
+	resistors are required, as omitting them makes the bus arbitration process
+	very inconsistent which causes frames to be dropped entirely.
+- Start creating prototypes as early as possible; this benefits the project in
+	the long run, as you have already shown that certain parts of the project are
+	already working and "only" need to be integrated.
+- The Atmega328P and ATmega2560 MCUs are both sufficient for the puzzle modules
+	as they have enough I/O, mutli-master hardware support, and the ability to be
+	addressed as a slave while being in master mode.
+- The RPI Pico (and Pico W)'s I^2^C peripheral supports multi-master, but does
+	not support being addressed as a slave while in master mode. This is required
+	for puzzle bus integration, and was mitigated using a workaround (see
+	<<fixme:rp2040-i2c>>). A replacement controller should be used instead.
+
+=== Other suggestions
+
+These points are suggestions for future project groups. While we do not think
+these are critical to project success, we still think they are important to
+mention.
+
+- Implement the hardware design from the year 22-23.
+- The original game rules are described in a separate document from the year
+	20-21.
+- The RPI Pico W has programmable I/O modules. Due to time constraints, we did
+	not research if these modules can be used to create a custom I^2^C peripheral
+	(and driver) that allows multi-master communication while still being
+	addressable as a slave. If this is possible, the RPI Pico W can still be used
+	as main controller without the use of workarounds.
 
 include::share/footer.adoc[]