From 4d1d629ab7a3bd9d661ec5ed25fcf0b4837b946d Mon Sep 17 00:00:00 2001 From: lonkaars Date: Sun, 21 May 2023 14:05:59 +0200 Subject: more documentation --- assets/.gitignore | 1 + assets/architecture-level-0.pdf | Bin 0 -> 6094 bytes assets/figs.drawio | 47 ++++++++++++++ doc/.gitignore | 2 + doc/base.tex | 24 +++++-- doc/dui.md | 136 +++++++++++++++++++++++++++++++++++----- doc/makefile | 8 +-- doc/refs.bib | 0 8 files changed, 192 insertions(+), 26 deletions(-) create mode 100644 assets/.gitignore create mode 100644 assets/architecture-level-0.pdf create mode 100644 assets/figs.drawio create mode 100644 doc/refs.bib 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 Binary files /dev/null and b/assets/architecture-level-0.pdf differ 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 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 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 +\ -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 -- cgit v1.2.3