more documentation

8 files changed, 192 insertions, 26 deletions

diff --git a/assets/.gitignore b/assets/.gitignore
new file mode 100644
index 0000000..cac82ea
--- /dev/null
+++ b/assets/.gitignore
@@ -0,0 +1 @@
+.$*
diff --git a/assets/architecture-level-0.pdf b/assets/architecture-level-0.pdf
new file mode 100644
index 0000000..48f00a6
--- /dev/null
+++ b/assets/architecture-level-0.pdf
diff --git a/assets/figs.drawio b/assets/figs.drawio
new file mode 100644
index 0000000..e7c4c8e
--- /dev/null
+++ b/assets/figs.drawio
@@ -0,0 +1,47 @@
+<mxfile host="Electron" modified="2023-05-21T10:31:13.607Z" agent="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/21.2.8 Chrome/112.0.5615.165 Electron/24.2.0 Safari/537.36" etag="R9LFAPF_hEjrUPbKqP4R" version="21.2.8" type="device">
+  <diagram name="architecture-level-0" id="JjuOE3DOjDeLsN0qBT10">
+    <mxGraphModel dx="566" dy="347" 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="8eRd1MbYxd4dPG-S6lUb-1" value="Arduino Nicla Vision" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+          <mxGeometry x="280" y="40" width="80" height="100" as="geometry" />
+        </mxCell>
+        <mxCell id="8eRd1MbYxd4dPG-S6lUb-8" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;" edge="1" parent="1" source="8eRd1MbYxd4dPG-S6lUb-2" target="8eRd1MbYxd4dPG-S6lUb-4">
+          <mxGeometry relative="1" as="geometry">
+            <Array as="points">
+              <mxPoint x="150" y="60" />
+              <mxPoint x="150" y="60" />
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="8eRd1MbYxd4dPG-S6lUb-9" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;" edge="1" parent="1" source="8eRd1MbYxd4dPG-S6lUb-2" target="8eRd1MbYxd4dPG-S6lUb-3">
+          <mxGeometry relative="1" as="geometry">
+            <Array as="points">
+              <mxPoint x="150" y="120" />
+              <mxPoint x="150" y="120" />
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="8eRd1MbYxd4dPG-S6lUb-10" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;startArrow=classic;startFill=1;" edge="1" parent="1" source="8eRd1MbYxd4dPG-S6lUb-2" target="8eRd1MbYxd4dPG-S6lUb-1">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="8eRd1MbYxd4dPG-S6lUb-2" value="Pololu Zumo 32U4" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+          <mxGeometry x="160" y="40" width="80" height="100" as="geometry" />
+        </mxCell>
+        <mxCell id="8eRd1MbYxd4dPG-S6lUb-3" value="Tracks" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+          <mxGeometry x="40" y="100" width="100" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="8eRd1MbYxd4dPG-S6lUb-4" value="OLED display" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+          <mxGeometry x="40" y="40" width="100" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="8eRd1MbYxd4dPG-S6lUb-13" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;" edge="1" parent="1" source="8eRd1MbYxd4dPG-S6lUb-6" target="8eRd1MbYxd4dPG-S6lUb-1">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="8eRd1MbYxd4dPG-S6lUb-6" value="2MP Camera" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+          <mxGeometry x="380" y="70" width="100" height="40" as="geometry" />
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>
diff --git a/doc/.gitignore b/doc/.gitignore
index 25dcb3b..e5139ef 100644
--- a/doc/.gitignore
+++ b/doc/.gitignore
@@ -12,6 +12,8 @@
 *.toc
 *.synctex(busy)
 *.md.tex
+*.lof
+*.lot
 
 # ignore output files
 *.pdf
diff --git a/doc/base.tex b/doc/base.tex
index 9c1c908..edadce3 100644
--- a/doc/base.tex
+++ b/doc/base.tex
@@ -12,10 +12,13 @@
 \usepackage{booktabs}
 \usepackage{needspace}
 \usepackage{hyperref}
-% \usepackage[backend=biber,
-% 	bibencoding=utf8,
-% 	style=apa
-% ]{biblatex}
+\usepackage{graphicx}
+\usepackage[toc]{glossaries}
+\usepackage[backend=biber,
+	bibencoding=utf8,
+	style=apa
+]{biblatex}
+\addbibresource{refs.bib}
 
 \setmainfont{TeX Gyre Schola}
 \setmathfont{TeX Gyre Schola Math}
@@ -42,6 +45,13 @@
 	Niels Stunnebrink\\2184532
 }
 
+\newcommand{\req}[1]{$^{\text{\ref{req:#1}}}$}
+\newcommand{\up}[1]{$^{\text{#1}}$}
+\newcommand{\sub}[1]{$_{\text{#1}}$}
+
+\floatplacement{figure}{H}
+\floatplacement{table}{H}
+
 \begin{document}
 \begin{titlepage}
 \maketitle
@@ -52,5 +62,11 @@
 \newpage
 
 \input{\jobname.md.tex}
+
+% \printbibliography[heading=bibintoc]
+% \printglossaries
+% \listoftables
+% \listoffigures
+
 \end{document}
 
diff --git a/doc/dui.md b/doc/dui.md
index 65f242d..f70f4ef 100644
--- a/doc/dui.md
+++ b/doc/dui.md
@@ -1,29 +1,105 @@
 # Introduction
 
-# Problem statement
+\<inleiding iemand?\>
 
-The following is the original project description (translated to English):
+# Problem statement
 
-> I would like to bring to market a vehicle that can drive independently from A
-> to B. The vehicle must take into account traffic rules, road signs, traffic
-> lights, etc. Research is being conducted using a small cart, the Pololu Zumo
-> 32U4, on which a camera module Nicla Vision is mounted. The aim is to
-> investigate the most appropriate method of recognizing the road, traffic
-> signs and traffic lights. This should be demonstrated with a proof of
-> concept. The cart does not need to drive fast, so the image processing does
-> not need to be very fast. Assume one frame per second (or faster).
+The following is the original project description (translated to English).
+References have been added in superscript that link to requirements set in
+section \ref{specifications}.
+
+> I would like to bring to market a vehicle that can drive
+> independently\req{autonomous} from A to B. The vehicle must take into account
+> traffic rules\req{traffic-rules}, road signs\req{signs}, traffic
+> lights\req{traffic-lights}, etc. Research is being conducted using a small
+> cart, the Pololu Zumo 32U4\req{zumo}, on which a camera module Nicla
+> Vision\req{nicla} is mounted. The aim is to investigate the most appropriate
+> method of recognizing the road, traffic signs and traffic lights. This should
+> be demonstrated with a proof of concept. The cart does not need to drive
+> fast\req{drspeed}, so the image processing\req{mvision} does not need to be
+> very fast. Assume one frame per second (or faster)\req{imspeed}.
 
 # Specifications
 
+The following is a list of specifications derived from the original project
+description in section \ref{problem-statement}.
+
+\begin{enumerate}
+  \item \label{req:autonomous}
+    The vehicle is autonomous
+  \item
+    The vehicle can detect how its positioned and orientated relative to a road
+  \item \label{req:traffic-rules}
+    The vehicle conforms to the following set of traffic rules
+  \begin{enumerate}
+    \item Driving when not on a road is not allowed
+    \item The vehicle can follow a road by steering itself accordingly
+    \item Driving off the road is only allowed when necessary for the camera to
+          keep seeing the road
+  \end{enumerate}
+  \item \label{req:traffic-lights}
+  The vehicle handles traffic lights in the following way
+  \begin{enumerate}
+    \item Stop at a red traffic light
+    \item Speed up at an orange traffic light
+    \item Continue driving normally at a green traffic light
+  \end{enumerate}
+  \item \label{req:signs}
+    The vehicle acts on traffic signs in the following way
+  \begin{enumerate}
+    \item Stop at a stop sign, and continue driving after a few seconds
+    \item Turn left at a left sign
+    \item Turn right at a right sign
+    \item Slow down at a low speed limit sign
+    \item Speed up to normal speed at a high speed limit sign
+  \end{enumerate}
+  \item \label{req:zumo}
+    The vehicle used is a Pololu Zumo 32U4
+  \item \label{req:nicla}
+    The camera module used is an Arduino Nicla Vision
+  \item \label{req:mvision}
+    Computer vision / image processing is used as the only input
+  \item \label{req:drspeed}
+    There is no minimum speed the car has to drive at
+  \item \label{req:imspeed}
+    The image processing pipeline runs at 1 frame per second or higher
+  \item
+    The Zumo displays the name of the last detected sign on it's OLED display
+\end{enumerate}
+
 # Architecture
 
+## Overview
+
+![Architecture overview (level 0)
+\label{fig:architecture-level-0}](../assets/architecture-level-0.pdf)
+
+Figure \ref{fig:architecture-level-0} shows the hardware used in this project.
+Both the Pololu Zumo 32U4 (referred to as just "Zumo"), and the Arduino Nicla
+Vision ("Nicla") have additional sensors and/or outputs on-board, but are
+unused.
+
+## Distribution of features
+
+Because creating a software architecture that does all machine vision-related
+tasks on the Nicla, and all driving related tasks on the Zumo would create
+significant overhead, and because the microcontroller on the Zumo is
+significantly harder to debug than the Nicla, a monolithic architecture was
+chosen. In this architecture, both the detection of 'traffic objects' and the
+decisionmaking on how to handle each object is done on the Nicla board.
+
+Figure \ref{fig:architecture-level-0} shows that a bidirectional communication
+line exists between the Zumo and Nicla. This line is only used to send control
+commands to the Zumo. Section \ref{niclazumo-communication-protocol} describes
+which commands are sent over these lines.
+
 ## Nicla/Zumo communication protocol
 
 The communication protocol used to control the Zumo from the Nicla uses UART to
-send ranged numbers in a single byte. Figure \ref{tab:protocol-ranges} shows
+send ranged numbers in a single byte. Table \ref{tab:protocol-ranges} shows
 which number ranges correspond to which controls.
 
-\begin{figure}[h]
+\begin{table}
 \centering
 \begin{tabular}{rl}
 \toprule
@@ -37,16 +113,16 @@ Steering & \texttt{0x20} - \texttt{0xff}\\
 \end{tabular}
 \caption{Protocol command ranges}
 \label{tab:protocol-ranges}
-\end{figure}
+\end{table}
 
 ### Signs
 
 The Zumo stores the last sign received, and displays it's name on the OLED
-display using the lookup table in figure \ref{tab:protocol-signs}. The sign ID
+display using the lookup table in table \ref{tab:protocol-signs}. The sign ID
 is calculated by subtracting the start offset of the sign command range from
-the command as shown in figure \ref{tab:protocol-ranges}.
+the command as shown in table \ref{tab:protocol-ranges}.
 
-\begin{figure}[h]
+\begin{table}
 \centering
 \begin{tabular}{ll}
 \toprule
@@ -65,7 +141,7 @@ the command as shown in figure \ref{tab:protocol-ranges}.
 \end{tabular}
 \caption{Sign lookup table}
 \label{tab:protocol-signs}
-\end{figure}
+\end{table}
 
 ### Speed
 
@@ -184,6 +260,32 @@ nog niet}.
 }
 \communicationConclusion
 
+## Compiling and linking code for the Zumo
+
+This section tries to answer the question "What are possible debugging options
+for code running on the Zumo robot?".
+
+Debugging running code can usually be done using an on-device debugger, and a
+program that interfaces with the debugger and gcc on a computer. Because gcc
+only gives valuable information when it has access to the executable file
+running on the microcontroller, an attempt at making a makefile-based toolchain
+was made.
+
+Pololu provides C++ libraries for controlling various parts of the Zumo's
+hardware. These libraries make use of functions and classes that are part of
+the Arduino core library. The Arduino libraries are all open source, and can in
+theory be compiled and linked using make, but this would take more effort than
+it's worth, since the Zumo has very little responsibility in the end product.
+
+\def\buildSystemConclusion{
+Because making a custom build system would take too much time, and because the
+Zumo robot's code is very simple, unit tests are used to debug the Zumo's code.
+For compiling and uploading the full Zumo firmware, the Arduino IDE is used in
+combination with the standard Pololu boards and Libraries.
+}
+\buildSystemConclusion
+
 # Conclusion
 
 \communicationConclusion
+\buildSystemConclusion
diff --git a/doc/makefile b/doc/makefile
index 9f4dfa0..a960c63 100644
--- a/doc/makefile
+++ b/doc/makefile
@@ -1,10 +1,8 @@
 .PHONY: all clean
 
-TARGET := $(patsubst %.md,%.pdf, $(wildcard *.md))
+all: dui.pdf
 
-all: $(TARGET)
-
-garbage = $1.aux $1.bbl $1.bcf $1.blg $1.fdb_latexmk $1.fls $1.log $1.out $1.run.xml $1.synctex.gz $1.toc $1.md.tex
+dui.pdf: ../assets/architecture-level-0.pdf
 
 %.pdf: %.svg
 	rsvg-convert -f pdf -o $@ $<
@@ -16,5 +14,5 @@ garbage = $1.aux $1.bbl $1.bcf $1.blg $1.fdb_latexmk $1.fls $1.log $1.out $1.run
 	pandoc -t latex -o $@ $<
 
 clean:
-	$(RM) $(call garbage,research) research.pdf
+	$(RM) dui.aux dui.bbl dui.bcf dui.blg dui.fdb_latexmk dui.fls dui.log dui.out dui.run.xml dui.synctex.gz dui.toc dui.md.tex dui.pdf
 
diff --git a/doc/refs.bib b/doc/refs.bib
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/doc/refs.bib