diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/.gitignore | 1 | ||||
| -rw-r--r-- | docs/figs.drawio | 58 | ||||
| -rw-r--r-- | docs/handover.adoc | 253 |
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<br>(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<br>(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<br>(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<br style="border-color: var(--border-color);">(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<br>(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<br style="border-color: var(--border-color);">(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<br>(battery pack)" style="rounded=0;whiteSpace=wrap;html=1;fontFamily=Arial;" parent="1" vertex="1"> + <mxCell id="EFqebEYhPqh4IJWovyJC-12" value="power supply<br>(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[] |