use drawio diagram embedding

This commit is contained in:
tyler miller 2023-10-27 11:44:15 -04:00
parent 9280ecda98
commit 0af037b16a
11 changed files with 6 additions and 234 deletions

View file

@ -4,23 +4,6 @@ ADD pip-requirements.txt /tmp/pip-requirements.txt
RUN pip install -r /tmp/pip-requirements.txt \
&& rm /tmp/pip-requirements.txt
# install drawio for doc diagram gen
ENV DRAWIO_VERSION "21.1.2"
RUN apt update \
&& apt install -yq --no-install-recommends \
xvfb \
wget \
libnotify4 \
libgbm1 \
libasound2 \
libxss1 \
libsecret-1-0 \
&& wget https://github.com/jgraph/drawio-desktop/releases/download/v${DRAWIO_VERSION}/drawio-amd64-${DRAWIO_VERSION}.deb \
&& apt install -y ./drawio-amd64-${DRAWIO_VERSION}.deb \
&& rm -rf /var/lib/apt/lists/* \
&& rm -rf drawio-amd64-${DRAWIO_VERSION}.deb
ENV XVFB_DISPLAY ":42"
FROM dev as prod
# Bundle app source

View file

@ -1,75 +0,0 @@
<mxfile host="65bd71144e">
<diagram id="SKV8PHPIui5c4Fc6kAOh" name="Page-1">
<mxGraphModel dx="623" dy="291" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">
<root>
<mxCell id="0"/>
<mxCell id="1" parent="0"/>
<mxCell id="11" style="edgeStyle=orthogonalEdgeStyle;html=1;entryX=0.5;entryY=1;entryDx=0;entryDy=0;endArrow=diamond;endFill=0;" parent="1" source="2" target="8" edge="1">
<mxGeometry relative="1" as="geometry"/>
</mxCell>
<mxCell id="14" style="edgeStyle=orthogonalEdgeStyle;html=1;endArrow=diamond;endFill=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;" parent="1" source="2" target="12" edge="1">
<mxGeometry relative="1" as="geometry">
<Array as="points">
<mxPoint x="460" y="100"/>
<mxPoint x="425" y="100"/>
</Array>
</mxGeometry>
</mxCell>
<mxCell id="2" value="Hardware Abstraction Layer (Interfaces of core hardware drivers)" style="html=1;align=center;verticalAlign=top;rounded=1;absoluteArcSize=1;arcSize=10;dashed=0;" parent="1" vertex="1">
<mxGeometry x="250" y="260" width="360" height="70" as="geometry"/>
</mxCell>
<mxCell id="3" value="ISPI" style="html=1;align=center;verticalAlign=top;rounded=1;absoluteArcSize=1;arcSize=10;dashed=0;" parent="1" vertex="1">
<mxGeometry x="250" y="290" width="70" height="40" as="geometry"/>
</mxCell>
<mxCell id="4" value="IGPIO" style="html=1;align=center;verticalAlign=top;rounded=1;absoluteArcSize=1;arcSize=10;dashed=0;" parent="1" vertex="1">
<mxGeometry x="320" y="290" width="70" height="40" as="geometry"/>
</mxCell>
<mxCell id="5" value="IUART" style="html=1;align=center;verticalAlign=top;rounded=1;absoluteArcSize=1;arcSize=10;dashed=0;" parent="1" vertex="1">
<mxGeometry x="390" y="290" width="70" height="40" as="geometry"/>
</mxCell>
<mxCell id="6" value="II2C" style="html=1;align=center;verticalAlign=top;rounded=1;absoluteArcSize=1;arcSize=10;dashed=0;" parent="1" vertex="1">
<mxGeometry x="460" y="290" width="70" height="40" as="geometry"/>
</mxCell>
<mxCell id="7" value="..." style="html=1;align=center;verticalAlign=top;rounded=1;absoluteArcSize=1;arcSize=10;dashed=0;" parent="1" vertex="1">
<mxGeometry x="530" y="290" width="80" height="40" as="geometry"/>
</mxCell>
<mxCell id="13" style="edgeStyle=orthogonalEdgeStyle;html=1;entryX=0.5;entryY=1;entryDx=0;entryDy=0;endArrow=diamond;endFill=0;" parent="1" source="8" target="12" edge="1">
<mxGeometry relative="1" as="geometry"/>
</mxCell>
<mxCell id="8" value="Device Drivers &lt;br&gt;(decoupled from underlying&lt;br&gt;&amp;nbsp;hardware driver implementation)" style="html=1;align=center;verticalAlign=top;rounded=1;absoluteArcSize=1;arcSize=10;dashed=0;" parent="1" vertex="1">
<mxGeometry x="250" y="120" width="180" height="100" as="geometry"/>
</mxCell>
<mxCell id="9" value="IMU" style="html=1;align=center;verticalAlign=top;rounded=1;absoluteArcSize=1;arcSize=10;dashed=0;" parent="1" vertex="1">
<mxGeometry x="250" y="180" width="70" height="40" as="geometry"/>
</mxCell>
<mxCell id="10" value="etc etc" style="html=1;align=center;verticalAlign=top;rounded=1;absoluteArcSize=1;arcSize=10;dashed=0;" parent="1" vertex="1">
<mxGeometry x="320" y="180" width="70" height="40" as="geometry"/>
</mxCell>
<mxCell id="12" value="Libraries&lt;br&gt;(Business logic that uses a combination of device and&lt;br&gt;hardware driver interfaces)" style="html=1;align=center;verticalAlign=top;rounded=1;absoluteArcSize=1;arcSize=10;dashed=0;" parent="1" vertex="1">
<mxGeometry x="250" y="10" width="350" height="60" as="geometry"/>
</mxCell>
<mxCell id="16" style="edgeStyle=orthogonalEdgeStyle;html=1;entryX=0.5;entryY=1;entryDx=0;entryDy=0;endArrow=classicThin;endFill=0;" parent="1" source="15" target="5" edge="1">
<mxGeometry relative="1" as="geometry"/>
</mxCell>
<mxCell id="15" value="Hardware-specific implementations of interfaces" style="html=1;align=center;verticalAlign=top;rounded=1;absoluteArcSize=1;arcSize=10;dashed=0;" parent="1" vertex="1">
<mxGeometry x="245" y="370" width="360" height="70" as="geometry"/>
</mxCell>
<mxCell id="17" value="MCU X&lt;br&gt;implementation" style="html=1;align=center;verticalAlign=top;rounded=1;absoluteArcSize=1;arcSize=10;dashed=0;" parent="1" vertex="1">
<mxGeometry x="262.5" y="410" width="117.5" height="70" as="geometry"/>
</mxCell>
<mxCell id="18" value="MCU Y&lt;br&gt;implementation" style="html=1;align=center;verticalAlign=top;rounded=1;absoluteArcSize=1;arcSize=10;dashed=0;" parent="1" vertex="1">
<mxGeometry x="410" y="410" width="120" height="70" as="geometry"/>
</mxCell>
<mxCell id="19" value="" style="shape=curlyBracket;whiteSpace=wrap;html=1;rounded=1;" parent="1" vertex="1">
<mxGeometry x="210" y="400" width="20" height="90" as="geometry"/>
</mxCell>
<mxCell id="20" value="" style="shape=curlyBracket;whiteSpace=wrap;html=1;rounded=1;flipH=1;" parent="1" vertex="1">
<mxGeometry x="620" y="400" width="20" height="90" as="geometry"/>
</mxCell>
<mxCell id="22" value="&lt;h1&gt;&lt;br&gt;&lt;/h1&gt;&lt;div&gt;Implementation is build-time selectable depending on your target environment&lt;/div&gt;" style="text;html=1;strokeColor=none;fillColor=none;spacing=5;spacingTop=-20;whiteSpace=wrap;overflow=hidden;rounded=0;align=right;" parent="1" vertex="1">
<mxGeometry x="20" y="370" width="190" height="110" as="geometry"/>
</mxCell>
</root>
</mxGraphModel>
</diagram>
</mxfile>

File diff suppressed because one or more lines are too long

After

Width:  |  Height:  |  Size: 18 KiB

View file

@ -1,112 +0,0 @@
<mxfile host="65bd71144e">
<diagram id="SKV8PHPIui5c4Fc6kAOh" name="Page-1">
<mxGraphModel dx="1739" dy="1765" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">
<root>
<mxCell id="0"/>
<mxCell id="1" parent="0"/>
<mxCell id="30" value="Application ABC&lt;br&gt;- top-level execution (main())&lt;br&gt;- initializes libraries required for app using&lt;br&gt;interface references from Board Data ABC" style="html=1;align=center;verticalAlign=top;rounded=1;absoluteArcSize=1;arcSize=10;dashed=0;" vertex="1" parent="1">
<mxGeometry x="155" y="-200" width="270" height="160" as="geometry"/>
</mxCell>
<mxCell id="11" style="edgeStyle=orthogonalEdgeStyle;html=1;entryX=0.5;entryY=1;entryDx=0;entryDy=0;endArrow=diamond;endFill=0;" parent="1" source="2" target="8" edge="1">
<mxGeometry relative="1" as="geometry"/>
</mxCell>
<mxCell id="14" style="edgeStyle=orthogonalEdgeStyle;html=1;endArrow=diamond;endFill=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;" parent="1" source="2" target="12" edge="1">
<mxGeometry relative="1" as="geometry">
<Array as="points">
<mxPoint x="460" y="90"/>
<mxPoint x="470" y="90"/>
</Array>
</mxGeometry>
</mxCell>
<mxCell id="2" value="Hardware Abstraction Layer (Interfaces of core hardware drivers)" style="html=1;align=center;verticalAlign=top;rounded=1;absoluteArcSize=1;arcSize=10;dashed=0;" parent="1" vertex="1">
<mxGeometry x="250" y="260" width="360" height="70" as="geometry"/>
</mxCell>
<mxCell id="3" value="ISPI" style="html=1;align=center;verticalAlign=top;rounded=1;absoluteArcSize=1;arcSize=10;dashed=0;" parent="1" vertex="1">
<mxGeometry x="250" y="290" width="70" height="40" as="geometry"/>
</mxCell>
<mxCell id="4" value="IGPIO" style="html=1;align=center;verticalAlign=top;rounded=1;absoluteArcSize=1;arcSize=10;dashed=0;" parent="1" vertex="1">
<mxGeometry x="320" y="290" width="70" height="40" as="geometry"/>
</mxCell>
<mxCell id="5" value="IUART" style="html=1;align=center;verticalAlign=top;rounded=1;absoluteArcSize=1;arcSize=10;dashed=0;" parent="1" vertex="1">
<mxGeometry x="390" y="290" width="70" height="40" as="geometry"/>
</mxCell>
<mxCell id="6" value="II2C" style="html=1;align=center;verticalAlign=top;rounded=1;absoluteArcSize=1;arcSize=10;dashed=0;" parent="1" vertex="1">
<mxGeometry x="460" y="290" width="70" height="40" as="geometry"/>
</mxCell>
<mxCell id="7" value="..." style="html=1;align=center;verticalAlign=top;rounded=1;absoluteArcSize=1;arcSize=10;dashed=0;" parent="1" vertex="1">
<mxGeometry x="530" y="290" width="80" height="40" as="geometry"/>
</mxCell>
<mxCell id="13" style="edgeStyle=orthogonalEdgeStyle;html=1;entryX=0.5;entryY=1;entryDx=0;entryDy=0;endArrow=diamond;endFill=0;" parent="1" source="8" target="12" edge="1">
<mxGeometry relative="1" as="geometry"/>
</mxCell>
<mxCell id="28" style="edgeStyle=orthogonalEdgeStyle;html=1;entryX=0.5;entryY=1;entryDx=0;entryDy=0;endArrow=diamond;endFill=0;" edge="1" parent="1" source="8" target="27">
<mxGeometry relative="1" as="geometry">
<Array as="points">
<mxPoint x="340" y="90"/>
<mxPoint x="290" y="90"/>
</Array>
</mxGeometry>
</mxCell>
<mxCell id="8" value="Device Drivers &lt;br&gt;(decoupled from underlying&lt;br&gt;&amp;nbsp;hardware driver implementation)" style="html=1;align=center;verticalAlign=top;rounded=1;absoluteArcSize=1;arcSize=10;dashed=0;" parent="1" vertex="1">
<mxGeometry x="250" y="120" width="180" height="100" as="geometry"/>
</mxCell>
<mxCell id="9" value="IMU" style="html=1;align=center;verticalAlign=top;rounded=1;absoluteArcSize=1;arcSize=10;dashed=0;" parent="1" vertex="1">
<mxGeometry x="250" y="180" width="70" height="40" as="geometry"/>
</mxCell>
<mxCell id="10" value="etc etc" style="html=1;align=center;verticalAlign=top;rounded=1;absoluteArcSize=1;arcSize=10;dashed=0;" parent="1" vertex="1">
<mxGeometry x="320" y="180" width="70" height="40" as="geometry"/>
</mxCell>
<mxCell id="31" style="edgeStyle=orthogonalEdgeStyle;html=1;entryX=0.5;entryY=1;entryDx=0;entryDy=0;endArrow=diamond;endFill=0;" edge="1" parent="1" source="12" target="27">
<mxGeometry relative="1" as="geometry"/>
</mxCell>
<mxCell id="12" value="Libraries&lt;br&gt;(Business logic that uses a combination of device and&lt;br&gt;hardware driver interfaces)" style="html=1;align=center;verticalAlign=top;rounded=1;absoluteArcSize=1;arcSize=10;dashed=0;" parent="1" vertex="1">
<mxGeometry x="325" y="10" width="290" height="60" as="geometry"/>
</mxCell>
<mxCell id="16" style="edgeStyle=orthogonalEdgeStyle;html=1;entryX=0.5;entryY=1;entryDx=0;entryDy=0;endArrow=classicThin;endFill=0;" parent="1" source="15" target="5" edge="1">
<mxGeometry relative="1" as="geometry"/>
</mxCell>
<mxCell id="26" style="edgeStyle=orthogonalEdgeStyle;html=1;entryX=0.5;entryY=1;entryDx=0;entryDy=0;endArrow=diamond;endFill=0;" edge="1" parent="1" source="15" target="23">
<mxGeometry relative="1" as="geometry"/>
</mxCell>
<mxCell id="15" value="Hardware-specific implementations of interfaces" style="html=1;align=center;verticalAlign=top;rounded=1;absoluteArcSize=1;arcSize=10;dashed=0;" parent="1" vertex="1">
<mxGeometry x="245" y="370" width="360" height="70" as="geometry"/>
</mxCell>
<mxCell id="17" value="MCU X&lt;br&gt;implementation" style="html=1;align=center;verticalAlign=top;rounded=1;absoluteArcSize=1;arcSize=10;dashed=0;" parent="1" vertex="1">
<mxGeometry x="262.5" y="410" width="117.5" height="70" as="geometry"/>
</mxCell>
<mxCell id="18" value="MCU Y&lt;br&gt;implementation" style="html=1;align=center;verticalAlign=top;rounded=1;absoluteArcSize=1;arcSize=10;dashed=0;" parent="1" vertex="1">
<mxGeometry x="410" y="410" width="120" height="70" as="geometry"/>
</mxCell>
<mxCell id="19" value="" style="shape=curlyBracket;whiteSpace=wrap;html=1;rounded=1;" parent="1" vertex="1">
<mxGeometry x="210" y="400" width="20" height="90" as="geometry"/>
</mxCell>
<mxCell id="20" value="" style="shape=curlyBracket;whiteSpace=wrap;html=1;rounded=1;flipH=1;" parent="1" vertex="1">
<mxGeometry x="620" y="400" width="20" height="90" as="geometry"/>
</mxCell>
<mxCell id="22" value="&lt;h1&gt;&lt;br&gt;&lt;/h1&gt;&lt;div&gt;Implementation is build-time selectable depending on your target environment&lt;/div&gt;" style="text;html=1;strokeColor=none;fillColor=none;spacing=5;spacingTop=-20;whiteSpace=wrap;overflow=hidden;rounded=0;align=right;" parent="1" vertex="1">
<mxGeometry x="20" y="370" width="190" height="110" as="geometry"/>
</mxCell>
<mxCell id="29" style="edgeStyle=orthogonalEdgeStyle;html=1;entryX=0.5;entryY=1;entryDx=0;entryDy=0;endArrow=diamond;endFill=0;" edge="1" parent="1" source="23" target="27">
<mxGeometry relative="1" as="geometry">
<Array as="points">
<mxPoint x="105" y="90"/>
<mxPoint x="290" y="90"/>
</Array>
</mxGeometry>
</mxCell>
<mxCell id="23" value="Board Configuration info:&lt;br&gt;- gpio configuration&lt;br&gt;- clock configuration&lt;br&gt;- any special bootup specifics" style="html=1;align=center;verticalAlign=top;rounded=1;absoluteArcSize=1;arcSize=10;dashed=0;" vertex="1" parent="1">
<mxGeometry x="-30" y="120" width="270" height="105" as="geometry"/>
</mxCell>
<mxCell id="24" value="Board A&lt;br&gt;Has &quot;MCU X&quot;" style="html=1;align=center;verticalAlign=top;rounded=1;absoluteArcSize=1;arcSize=10;dashed=0;" vertex="1" parent="1">
<mxGeometry x="-20" y="200" width="120" height="60" as="geometry"/>
</mxCell>
<mxCell id="25" value="Board B&lt;br&gt;Has &quot;MCU Y&quot;" style="html=1;align=center;verticalAlign=top;rounded=1;absoluteArcSize=1;arcSize=10;dashed=0;" vertex="1" parent="1">
<mxGeometry x="110" y="200" width="120" height="60" as="geometry"/>
</mxCell>
<mxCell id="27" value="Board Data ABC&lt;br&gt;- Selects board&lt;br&gt;- initializes board-specific drivers that are&lt;br&gt;required by the application" style="html=1;align=center;verticalAlign=top;rounded=1;absoluteArcSize=1;arcSize=10;dashed=0;" vertex="1" parent="1">
<mxGeometry x="155" y="-120" width="270" height="80" as="geometry"/>
</mxCell>
</root>
</mxGraphModel>
</diagram>
</mxfile>

File diff suppressed because one or more lines are too long

After

Width:  |  Height:  |  Size: 25 KiB

View file

@ -1,25 +0,0 @@
<mxfile host="65bd71144e">
<diagram id="5akZJ5bUuDu-clLUh8Qc" name="Page-1">
<mxGraphModel dx="725" dy="548" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">
<root>
<mxCell id="0"/>
<mxCell id="1" parent="0"/>
<mxCell id="6" style="edgeStyle=none;html=1;entryX=0.25;entryY=1;entryDx=0;entryDy=0;startArrow=classic;startFill=1;exitX=0.5;exitY=0;exitDx=0;exitDy=0;" edge="1" parent="1" source="2" target="3">
<mxGeometry relative="1" as="geometry"/>
</mxCell>
<mxCell id="2" value="ArkOS (RG353M)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;" vertex="1" parent="1">
<mxGeometry x="250" y="480" width="120" height="60" as="geometry"/>
</mxCell>
<mxCell id="3" value="NAS&lt;br&gt;(Unraid + Syncthing container)" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="1">
<mxGeometry x="320" y="380" width="120" height="60" as="geometry"/>
</mxCell>
<mxCell id="5" style="edgeStyle=none;html=1;entryX=0.75;entryY=1;entryDx=0;entryDy=0;startArrow=classic;startFill=1;exitX=0.5;exitY=0;exitDx=0;exitDy=0;" edge="1" parent="1" source="4" target="3">
<mxGeometry relative="1" as="geometry"/>
</mxCell>
<mxCell id="4" value="SteamDeck" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;" vertex="1" parent="1">
<mxGeometry x="390" y="480" width="120" height="60" as="geometry"/>
</mxCell>
</root>
</mxGraphModel>
</diagram>
</mxfile>

File diff suppressed because one or more lines are too long

After

Width:  |  Height:  |  Size: 5.1 KiB

View file

@ -10,7 +10,6 @@ extensions = [
"ablog",
"sphinx.ext.intersphinx",
"sphinx_design",
"sphinxcontrib.drawio",
]
templates_path = ["_templates"]

View file

@ -3,4 +3,3 @@ ablog
sphinx-design
sphinxcontrib-youtube
pydata-sphinx-theme
sphinxcontrib-drawio

View file

@ -84,7 +84,7 @@ Making unit-testable code in embedded development can be challenging. There is a
What does that look like? Something like this:
.. drawio-image:: ../assets/diagrams/hal_concept.drawio
.. image:: ../assets/diagrams/hal_concept.drawio.svg
Notice all SOC/MCU-specific code is encapsulated down in a single library which we abstract out with an interface layer immediately.
@ -107,7 +107,7 @@ What are "board-specifics"? This is the term I use to describe the configuration
Here's an extension of the earlier diagram with these concepts added:
.. drawio-image:: ../assets/diagrams/hal_concept_with_board.drawio
.. image:: ../assets/diagrams/hal_concept_with_board.drawio.svg
Benefits:

View file

@ -13,7 +13,7 @@ Setup Syncthing on arkos
`Syncthing <https://syncthing.net/>`_ is a handy tool for syncronizing files between multiple machines. I currently use 2 devices for playing retro games: a Steam Deck and a `Anbernic RG353m <https://anbernic.com/products/rg353m>`_ running `arkos <https://github.com/christianhaitian/arkos>`_ My goal here is to syncronize save states and games between the devices. Here's my goal for a final setup:
.. drawio-image:: ../assets/diagrams/syncthing_setup.drawio
.. image:: ../assets/diagrams/syncthing_setup.drawio.svg
For now, this writeup only covers RetroArch savestate syncing. There are also plenty of guides and advice online for setting up syncthing on the Steam Deck or a NAS, so the focus here will be ArkOS.