\documentclass{kravspec}

% Swedish characters and formatting
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage[swedish]{babel}
\usepackage{float}
\usepackage{placeins} % \FloatBarrier

% Gives YYYY-MM-DD date format
\usepackage{datetime}

\usepackage[hidelinks]{hyperref}
\usepackage{booktabs}

\usepackage{todonotes}
% \RequirePackage[table]{xcolor} % Alternating table colours

\usepackage{utils}
\usepackage{amsmath}
\usepackage{quot}
\usepackage{paralist}
\usepackage{enumitem}
\usepackage{xcolor}
\usepackage{listings}

% === Inställningar för kurs, nyttjas även av kravspec

\usepackage{courseinfo}

\renewcommand{\coursecode}{TSEA29}
\renewcommand{\coursename}{Konstruktion med mikrodatorer}
\renewcommand{\groupname}{Grupp 8}

\usepackage{import}

% === Inställningar för kravspec.

\renewcommand\projtitle{KMM-Lagerrobot}

% Avkommentera och sätt information när relevant
\renewcommand\granskare{Hugo Hörnquist & 2018--12--15}
% \renewcommand\godkannare{Godkännare & YYYY--MM--DD}

% Byt ut "\safegitver{v}" mot "v" om det blir problem.
\renewcommand\version{\safegitver{ERR~??}}

\newcommand{\atmega}{\textsc{ATmega1284p}}
\newcommand{\pair}[2]{\left(#1,\, #2\right)}
\newcommand{\bnfr}[1]{\left<\text{#1}\right>}

\title{Teknisk Dokumentation}
\author{\groupname\ \\ \textbf{Redaktör}: Matilda Kaalhus}
\date{\today}

\begin{document}
\renewcommand{\dateseparator}{--}
\yyyymmdddate

\maketitle
\stepcounter{page}

\projid{}

\tableofcontents

\chapter*{Dokumenthistorik}
\begin{dochistory}
	\dhist{1.1}{2018--12--15}{Hugo Hörnquist}%
		{Uppdaterade kopplingsschemat för Sensormodul, då fel version
		var inlagd innan.}
	\dhist{1.0}{2018--12--13}{Matilda Kaalhus}{Slutgiltiga versionen.}
\end{dochistory}

\chapter{Inledning}\label{chap:Inledning}
Detta dokument är den tekniska dokumentationen av en lagerrobot som
utvecklats under höstterminen 2018 vid Linköpings Universitet i kursen TSEA29
Konstruktion med mikrodatorer. Denna robot består av tre hårdvarumoduler,
i form av två virkort och en Raspberry Pi 3 (se~\ref{robotsid}) som
tillsammans fyller fyra \quot{roller}, beskrivna nedan. Utöver roboten så
används en extern dator med ett grafiskt användargränssnitt för att bland annat
styr roboten manuellt.

Roboten hanterar direkta kommandon från ett
användargränssnitt på en extern dator. Kommandona skickas trådlöst via en
wifi-länk till en Raspberry Pi 3, där de tas emot av kommunikationsenheten och
sedan skickas vidare till relevanta moduler i systemet.
Roboten kan även autonomt ta sig till en \quot{vara}
som är definierad i det rutnät som roboten rör sig i. Detta rutnät definieras
genom användargränssnittet på den externa datorn. Vid autonom styrning används
sensordata från sensorenheten i styrenheten till att reglera robotens körning.
Logikenheten använder behandlad sensordata för att bestämma hur roboten ska ta
sig fram i lagret och skickar därefter kommandon till styrenheten. Under tiden
tar kommunikationsenheten emot styr-och-sensordata från de relevanta enheterna
för att kunna uppdatera användaren om vad roboten gör i nuläget. Robotens arm
kan sen styras manuellt för att plocka upp \quot{varan}, därefter tar sig
roboten autonomt till utlämningsstationen och autonomt lämnar \quot{varan}.
Vid manuell upplockning skickar kommunikationsenheten indata från
kontrollen, som används för armens styrning, till styrenheten som rör
och reglerar armen.

\begin{figure}[H]
	\center
	\includegraphics[width=\textwidth]{img/inledning-blockschema}
	\caption{Övergripande blockschema för systemet\label{img:sysblock}}
\end{figure}

I \emph{Figur~\ref{img:sysblock}} ovan visas ett blockschema över hur de olika
enheterna, sensorer och motorer kommer att kommunicera med varandra. Denna
kommunikation beskrivs mer detaljerat i kapitel~\ref{chap:Systemet}.

Roboten använder sig av en linjesensor och en IR-sensor för att
ta sig fram i lagret och upptäcka hinder på vägen. Linjesensorn är placerad
på undersidan av roboten, något förskjuten i ordinarie färdriktning.
IR-sensorn är placerad på framsidan av robotens basplatta,
framför robotens arm sådant att sensorn pekar framåt i robotens
färdriktning.

Det finns två drivkretsar till hjulen för att röra roboten framåt och svänga.
Den ena drivkretsen har uppgiften att styra motorerna på
de vänstra hjulen och den andra styr motorerna på
de högra hjulen. Dessa drivkretsar är placerade på den robotplattform som
projektet utgår ifrån intill deras respektive hjulpar. Armen styrs av sina
inbyggda servon och ingår även den i robotplattformen.

\section{Syfte}
Syftet med detta projekt är att skapa en funktionell laggerrobot som autonomt kan
röra sig på en given bana samt manuellt plocka upp varor för att sedan autonomt
avlämna dessa på en utsatt avlämningsstation. Detta dokument har i syfte att
beskriva hur denna robot är konstruerad i form hård- och mjukvara. Systemet är
uppbyggt av fyra huvudmoduler, sensor-, logik-, kommunikation- och styrmodulen
som alla finns dokumenterade i detta dokument.

\chapter{Produkten}\label{chap:Produkten}
Den allmänna funktionaliteten av produkten som beskrivs i detta dokument är den av
en lagerrobot. Den kan styras både genom ett användargränssitt på en extern dator
via en wifi-länk och denna styrning kan vara både fri enligt användarens 
instruktioner eller i autonomt läge där systemet själv kan navigera i ett 
rutnätslager som specificerats genom det externa gränssnittet. En specificerad 
punkt i rutnätet kommer definieras som upplockningsstation dit systemet kommer
navigera för att gå in i manuellt armstyrningsläge. Där kommer användaren styra
armen tillhörande systemet för att plocka upp \quot{vara}. Vid signal från användaren
kommer systemet återgå till autonomt läge för att navigera till fördefinierad
avlämningsstation i rutnätet och lämna av varan.

Det allmänna användningsområdet för denna produkt är främst som lagerrobot vid ett
lager som är konstruerat enligt banspecifikationen.

\begin{figure}[h]
	\centering
	\includegraphics[width=\textwidth]{img/robot-sidan}
	\caption{Bild av roboten.\label{robotsid}}
\end{figure}

\chapter{Teori}\label{chap:Teori}

\section{Datastrukturer}

\subsection{Kart-nod}

I logikenheten så representeras kartan av lagret som ett antal noder med x- och
y-koordinater och vägar som leder ut ur noden. Varje nod är alltså en korsning i
lagret och har ett unikt sett koordinater. Den har även information om vägarna
upp, ner, vänster och höger, där värdet $1$ innebär en tillgänglig väg, och
värdet $0$ innebär att väg där inte finns, eller att roboten upptäckt ett hinder
på denna väg. Till nod struct:en tillhör de nedanstående fält som initialiseras 
vid skapandet av en ny nod:\\
self.xCoord\\
self.yCoord\\
self.wayUp\\
self.wayRight\\
self.wayDown\\
self.wayLeft\\

Till Node klassen tillhör även en funktion addObstacle som sätter en av nodens
fyra vägar till $0$ beroende på vilken input den får. 

\subsection{TCP}\label{subsec:tcp}
Både \quot{server}-delen som sitter på den externa datorn och \quot{client}-delen
på RP3:an är skriven i python, och är implementerad som ett TCP-bibliotek.
Biblioteket är uppbyggt som två klasser, server och client, som innehåller
wrapper funktioner för att underlätta kommunikationen mellan enheterna.
Klasserna innehåller varsin socket medlem, så det går att skriva egna
funktioner via denna. I kommunikationsenheten så importeras \quot{client}-delen
som ett bibliotek, men servern på den externa datorn är sitt egna program, och
pratar via en unix-socket.

\section{Algoritmer}

\subsection{PD-reglering}
PD-reglering används av styrmodulen för att korrigera sin styrning med den
sensordata den får angående dess position i relation till den tejp den ska följa.
PD-reglering är reglering som tar hänsyn till det proportionella felet, det vill
säga det avstånd mellan önskad position och nuvarande position, och derivatan av
styrning, det vill säga skillnaden mellan det nuvarande proportionella felet och
det förra proportionella felet.

Den enklaste typen av reglering är den som endast tar hänsyn till det
proportionella felet eftersom det kommer indikera vilken generell korrigering
behövs. Problemet med att endast använda proportionellt fel för att avgöra
korrigering är att vid mindre responsiva eller fördröjda system kommer
överslaget från den önskade positionen hindra en effektiv styrning. Denna
reglering kan vidareutvecklas genom att lägga till ännu ett element i
korrigeringsalgoritmen, en integralskonstant, som tar hänsyn till konstanta fel
som skillnader mellan drivkretseffektivtet eller liknande. Detta skulle
resultera i en så kallad PID-reglering.

\subsection{Pathfinding}
Robotens väg igenom lagret fungerar på så sätt att pathfinderfunktionen
först kallas. Där i letas först upp vilken nod som roboten ska
ha som sin slutnod. Detta bestäms efter vilken av de två noder som
utlämnings stationen ligger emellan som är närmast till robotens
nuvarande position. Sedan räknas närmaste vägen ut med hjälp av en egenskriven
bredden-först sökalgoritm. Då roboten ska kunna hantera hinder i vårt lager är
algoritmen anpassad för detta.

När en väg hittats så kommer roboten börja köra. För varje ny nod som
roboten kommer till så kommer den vända sig i nästa nods riktning och
sedan kolla ifall det finns ett hinder på denna väg. Om det inte finns
något hinder kommer det fortsätta till noden som planerat annars tas
vägen bort som en möjlig transportväg och en ny väg till slutnoden
räknas ut från den nuvarande positionen.

\section{Protokoll}\label{sec:protokoll}
För att kunna kommunicera mellan de olika enheterna och för att de ska förstå
varandras meddelanden, har vi tagit fram en del protokoll. Dessa protokoll är
en anvisning på hur meddelande ska byggas för att de ska vara tolkningsbara.

Ett antal olika protokoll används mellan enheterna. Anledningen till olika är
olika krav på mängden data, diversiteten av data, samt tillgänglig hårdvara.

\subsection{Kommando-protokoll}\label{sub:kommprot}
Detta visar formen på alla kommandon som skickas till styrenheten. Detta
protokoll ska följas hela vägen från den externa datorn, via logikenheten och
till styrenheten. Alla kommandon respresenteras av 8 karaktärer anting 1:or
eller 0:or. Fram till den process som hanterar kommunikationen mellan
kommunikations- och styrenheten så är dessa kommandon strängar innan de
omvandlas till heltal.\\
"0000----"\\
Kommando lista ----:\\
0001: stop\\
0010: Tangent pil upp - kör rakt fram\\
0011: följ linjen framåt\\
0100: Tangent pil ner - backa\\
0101: följ linjen bakåt\\
0110: Tangent pil vänster - sväng vänster\\
0111: Tangent pil höger - sväng höger\\
1000: Tangent PgUp - 45 vänster\\
1001: Tangent PgDn - 45 höger

\subsection{Arm-protokoll}\label{sub:armprot}
Arm protokollet visar hur kommandon till armen ska skrivas. Dessa ska skickas
från den externa datorn vid tangenttryck. Om roboten befinner sig i manuellt
läge kan dessa skickas när som, annars behöver roboten vara framme vid en
upplockningsstation. Formatet på dessa kommandon fungerar som ovan\\
"1111----"\\
Kommando lista ----:\\
0001: Tangent 1 - Medurs vridning klo\\
0010: Tangent 2 - Moturs vridning klo\\
0011: Tangent q - IN\\
0100: Tangent w - UT\\
0101: Tangent a - UPP\\
0110: Tangent s - NER\\
0111: Tangent z - VÄNSTER\\
1000: Tangent x - HÖGER\\
1001: Tangent , - KLÄM\\
1010: Tangent \. - SLÄPP

\subsection{Kart-protokoll}
Detta protokoll ska följas vid meddelande innehållande lagret och varor. Denna
typen av meddelande skickas från den externa datorn då användaren fyllt i
storlek på lagret, och valt varors position och nummer. \quot{X,Y,x,y}
Där
\begin{enumerate}
	\item [\texttt X] är storleken på lagret i X-led, i antal rutor.
	\item [\texttt Y] är storleken på lagret i Y-led, i antal rutor.
	\item [\texttt x] är utlämningsstationens x-koordinat
	\item [\texttt y] är utlämningsstationens y-koordinat.
\end{enumerate}

Då utlämningsstationen alltid ligger i ett av lagrets fyra hörn har den 4
möjliga positioner:
\( \pair 0 0,\, \pair 0 Y,\, \pair X 0 \text{ och } \pair X Y \).

\subsection{Varu-protokoll}
Varu-protokollet är det protokoll som följs när man skickar information om de
varor som finns i lagret, från den externa enheten till kommunikationsenheten och
sedan vidare till logikenheten.
\quot{v1,x1,y1,s1;v2,x2,y2,s2;...}
Där för varje vara i lagret det anges:
\begin{enumerate}
	\item [\texttt v] varonumret/namnet.
	\item [\texttt x] är x-koordinaten på rutan som varans upplockningsstation
		beffiner sig på.
	\item [\texttt y] är y-koordinaten på rutan
	\item [\texttt s] är vilken sida på rutan som varan befinner sig på.
		Sidorna benäms 0-3 och är namngedda klockvis där 0 är vänstra sidan på
		rektangeln och 3 nedre sidan.
\end{enumerate}

\subsection{Paket}\label{subsec:paket}
% De paket med sensordata som skickas från Sensorenheten är byggda i C i form av
% strukturer. Dessa skickas via UART-USB koppling till RP3 och via exde protokollet
% m.h.a I/O kopplingar till Styrmodulen. Både IR- och Linjesensordatan packeteras
% i samma grundstruktur, det som skiljer sig är vad vi skickar in för data i
% payload unionen.

Data som skickas via UART (kommunikationsenheten till styr- och sensorenheten)
paketeras i paket, vilka är implementerade genom C strukturer. All data följer
samma grundstruktur. Alla paket börjar med ett pakethuvud som berättar vad
paketet kommer att innehålla, samt hur långt (i UART frames) det kommer vara. 


Strukturen på dessa paket är följande:

\begin{align*}
	struct~\text{packet} & \to \{ \text{header}, \text{payload} \} \\
	struct~\text{header} & \to \{ \text{\texttt{uint8\_t} } id \\
	& \phantom{\to \{} \text{\texttt{command\_type} } type \\
	& \phantom{\to \{}\text{\texttt{uint8\_t} } length \} \\
	union~\text{payload} & \to \{ \text{\texttt{struct handshake}} \\
	& \phantom{\to \{}\text{\texttt{uint8\_t distance}} \\
 	& \phantom{\to \{}\text{\texttt{char steercomm}} \\
 	& \phantom{\to \{}\text{\texttt{char steerdata}} \\
 	& \phantom{\to \{}\text{\texttt{enum linedata}} \}
\end{align*}

\subsubsection{UART handskakning}
AVR:en sänder ut en handshake signal i form av tidigare beskrivet
packetprotokoll som då väntar på ett svar på samma form. Sensormodulen
skickar ut synksignal SYN och tar sedan emot ett acknowledge-signal ACK 
från RP3:an som då bekräftar att kommunikationen mellan dem är uppsatt 
och paket kan börja sändas från Sensormodulen.

\subsection{ExDe}
ExDe är en synkron, enkelriktad, databuss, och är ett alternativ till
UART. Den består av 3 pin, vilka är:
\begin{itemize}
	\item Data
	\item Sync
	\item Retursync / handskakning
\end{itemize}

Bussen körs genom att varje bit läggs under ett intervall på
data-pinnen, och i \quot{mitten} av intervallet går synk-signalen en
mycket kort tid hög. I figur~\ref{img:exde} visas sändning av
sekvensen \( 0, 1, 1, 1, 0, 0, 1, 0, 0, 1 \).

\begin{figure}[h]
	\center
	\includegraphics[width=\textwidth]{img/exde}
	\caption{Exempel på överföring via ExDe.\label{img:exde}}
\end{figure}

Notera att ingen standard angående storlek på paket finns, samt ingen
form av paket start/stop. Det är upp till användaren att sätta upp om
sådant behövs.

\subsubsection{ExDe handskakning}

Den tredje linan används för handskakning. Vid start ska den sändande
enheten skicka ut en synk-signal \quot{nu och då}. När den mottagande
enheten plockar upp den ska den skicka tillbaka en egen synksignal på
motsvarande form\footnote{Det här är enda gången den mottagande
enheten skickar någonting}. När sändaren fått tillbaka signalen anses
handskakningen komplett, och överföring av data kan påbörjas.

\subsection{GaG \& Robert}
På den externa datorn kör två program. Användargränssnittet (GaG),
samt servern som vidarebefodrar meddelanden mellan GaG och
kommunikationsmodulen. Serverns, vilken nedan (för enkelhetens skull)
kallas Robert, finns dokumenterad i sektion~\ref{subsec:tcp}.

GaG och Robert delar meddelanden med varandra över en sockel. 
Alla meddelanden utgår från att Robert skickar någonting till GaG, och
GaG svarar enligt protokollet.\footnote{Protokollet är på BNF form,
kort introduktion finns i appendix~\ref{chp:bnf}}

\subsubsection{Allmänna deklarationer}

\begin{align*}
	\bnfr{cm} & ::= \bnfr{int} \# \text{centimeter är heltal} \\
	\bnfr{id} & ::= \bnfr{int} \\
	\bnfr{prodid} & ::= \bnfr{id} \\
	\bnfr{direction} & ::= \bnfr{left}\big|\bnfr{up}\big|\bnfr{right}\big|\bnfr{down}
\end{align*}

\subsubsection{Kartdata}
\begin{itemize}
	\item Första koordinaten än kartans storlek.
	\item Andra koordinaten är utlämningsstationens plats (var inte den alltid i origo?)
\end{itemize}

\begin{align*}
	`karta' & \to `karta' \bnfr{kart-data} \\
	\bnfr{kart-data} & ::= \bnfr{coord} \bnfr{coord} \\
	\bnfr{coord} & ::= \bnfr{int} \bnfr{int}
\end{align*}

\subsubsection{Sidlängd}
Längden på en kvadrat i banan i cm.

\begin{align*}
	`sidelength' & \to `sidelength' \bnfr{cm}
\end{align*}

\subsubsection{Plockstationer}
Lista över var plockstationer är belägna.
Svaret börjar med ett heltal vilket är antalet plockstationer, fölt av en lista
av dem. \(\bnfr{id}\) är ett godtyckligt (unikt) numeriskt id (av plockstationen $\iff$
prodkuten).

Sen är det en koordinat för vilken rektangel produkten står i, och sedan vilken
riktning man ska komma åt produkten från.

\begin{align*}
	`prodlist' & \to `prodlist' \bnfr{int} \big\{ \bnfr{product} \big\} \\
	\bnfr{product} & ::= \bnfr{prodid} \bnfr{coord} \bnfr{side} \\
	\bnfr{side} & ::= \bnfr{direction}
\end{align*}

\subsubsection{Hämta Prodkut}
\begin{align*}
	`fetchprod' & \to `fetchprod' \bnfr{prodid}
\end{align*}

\subsubsection{Armkommandon}
\begin{align*}
	`armcomm' & \to `armcomm' \bnfr{armcomm}
\end{align*}

\( \bnfr{armcomm} \) är ett heltal \( \in [ F1_{16}, FA_{16} ] \), där
de olika värdena representerar:

\begin{verbatim}
| Nr | value     | Tangenent | kommand       |
|----|-----------|-----------|---------------|
| F1 | 11110001  | 1         | CW            |
| F2 | 11110010  | 2         | CCW           |
| F3 | 11110011  | q         | IN            |
| F4 | 11110100  | w         | UT            |
| F5 | 11110101  | a         | UPP           |
| F6 | 11110110  | s         | NER           |
| F7 | 11110111  | z         | VÄNSTER       |
| F8 | 11111000  | x         | HÖGER         |
| F9 | 11111001  | ,         | KLÄM (-check) |
| FA | 11111010  | .         | SLÄPP         |
\end{verbatim}

\subsubsection{Styrkommando}
\begin{align*}
	`styrcomm' & \to `styrcomm' \bnfr{styrcomm}
\end{align*}

\( \bnfr{styrcomm} \) är ett heltal \( \in [ 1, 9 ] \), där
de olika värdena representerar:

\begin{verbatim}
| Nr | value     | Tangenent | kommand        |
|----|-----------|-----------|----------------|
|  1 | 00000001  | None      | Stop           |
|  2 | 00000010  | Pil Up    | Kör rakt fram  |
|  3 | 00000011  | None      | Följ linje bak |
|  4 | 00000100  | Pil Ner   | Backa          |
|  5 | 00000101  | None      | Följ linje fram|
|  6 | 00000110  | Pil Vän   | Sväng vänster  |
|  7 | 00000111  | Pil Hög   | Sväng höger    |
|  8 | 00001000  | PgUp      | 45 grad vänster|
|  9 | 00001001  | PgDown    | 45 grad höger  |
\end{verbatim}

\subsubsection{Telemetri}

\( \emptyset \) innebär att ingenting returneras.

\begin{align*}
	`thought' \bnfr{any string} & \to \emptyset \\
	`set\_robot' \bnfr{coord} & \to \emptyset \\
	`set\_heading' \bnfr{direction} & \to \emptyset
\end{align*}

\section{Datadelare}
Datadelare används på Rasberry Pi:en för att inkommande data ska delas med både
kommunikations- och logikenheten. Datadelaren skötar UART handskakningarna och
sedan fork:as för att starta processer som sköter styr- respektive
sensorenhetens kommunikation med RP3:an.

\chapter{Systemet}\label{chap:Systemet}
Detta kapitel syftar att beskriva hur systemet hänger samman och har 
stort fokus på att beskrivat kommunikationen mellan modulerna. Mer 
modulspecifik information finns att hitta i respektive delkapitel i nästkommande
kapitel~\ref{chap:Modulerna}.

\section{Kommunikationen mellan enheter}
Fördelningen av arbete mellan modulerna kräver god kommunikation mellan 
modulerna för att systemet ska fungera som önskat. Denna kommunikation sker 
på fyra olika typer av protokoll; TCP-sockets, buffertfiler, UART-kommunikation och eget 
EXDE-protokoll. Bilden nedan ~\ref{img:inblock} visar i vilka riktningar datavägarna 
går i och mellan vilka moduler som de går mellan. Utförligare beskrivningar av de olika 
protokollen finns att finna i ~\ref{sec:protokoll} samt nedan för modul-till-modul-specifik 
beskrivning av deras kommunikation.

\begin{figure}[H]
	\centering
	\includegraphics[width=\textwidth]{img/inledning-blockschema}
	\caption{Kommunikationen mellan produktens enheter.
	\label{img:inblock}}.
\end{figure}

\subsection{Logik- och Kommunikationsenhet}
Mellan logik och kommunikationsenhet så sköts kommunikationen via
bufferfiler. Enheterna har hårdkodade platser i map-strukturen som de
läser/skriver till för att prata med varandra.

\subsection{Logik- och Sensorenhet}
Kommunikationen mellan dessa enheter sköts via en UART-USB kabel, med ett
protokoll skrivet av gruppen, med handskakning så att de olika fysiska enheterna
“vet vem som är vem”. Nerskalad sensordata skickas från sensorenheten till
logikenheten via data-delaren på kommunikationsenheten. Den nedskalade
sensordata innebär att det enda som logikenheten får (och behöver få) är om
roboten är på linjen, på linjen lite till vänster, på linjen lite till höger,
vid en t-korsning åt höger, vid en t-korsning åt vänster, vid en fyr-vägs
korsning, vid upp-plockningsstationen, eller ej vid en linje. Detta för skicka
kommandon utefter den väg som roboten räknat ut.
Logikenheten kommer även få avståndsdata från IR-sensorn i form av metern.
Detta så att logikenheten kan hantera hinder och upphämtning av varor.

\subsection{Kommunikations- och Sensorenhet}
Använder sig av samma teknik som logikenheten, och tar emot samma
information. Detta sköts av en extern process, en data-delare.

\subsection{Logik- och Styrenhet}
Mellan logik- och styrenheten går det en USB UART. De kommandon som logikenheten
vill skicka till styrenheten sparas på en buffer. Den tråd som hanterar
skickandet och mottagandet av meddelanden mellan enheterna hämtar sedan
information från buffern för att kunna skicka vidare till styrenheten. Denna
tråden sköter även hämtningen av styrdata över UART:en och sparar datan på en
fil som logikenheten sedan läser ifrån. Kommandona skickas enligt det protokoll
som gruppen skrivit, se~\ref{sub:kommprot} och~\ref{sub:armprot}.

\subsection{Kommunikations- och Styrenhet}
Då kommunikationsenheten och logikenheten båda två ligger på samma kort så
använder de samma kommunikationsvägar. Kommunikationen mellan kommunikations-
och styrenheten fungerar därför på samma sätt som den mellan logik- och
styrenheten. All denna kommunikation går på samma UART.

\subsection{Kommunikationsenheten och Externa datorn}
Kommunikationen mellan den externa datorn och RP3:an sköts av en TCP-sockets som öppnas
när roboten start/resetas. Värt att nämna är att den externa datorn mest kommer
att ligga och lyssna på att roboten behöver något i autonomt läge, då den inte
kommer att behöva indata mer än i början, då kartan och varan som roboten ska
hämta kommer skickas över. Om nu roboten slår över i manuellt läge så kommer den
fråga den externa datorn efter nästkommande kommando. Den externa datorn kommer
då behöva bygga upp en kö av kommandon om den skickar dessa snabbare än roboten
kan utföra de, då kommunikationsenheten endast kommer be om ett meddelande i
taget.

\subsection{Sensorenhet- och Styrenhet}
Sensorenheten packeterar sensordata från IR-sensor samt Linjesensorn
och skickar över dessa till Styrenheten via ett protokoll som vi valt
att kalla 'exde'. Dessa aktiveras via en setup samt en sändingsrutin
som görs från båda hållen. Linjedatan skickas till Styrmodulen från
Sensormodulen i paket dock består datan inom paketet av "råa"
11-bitssekvenser istället för den nedskalade abstraherade värden som
logikmodulen får. En 1:a indikerar att sensorn är på banan (tejpen) och
en nolla indikerar att den är utanför. Styrmodulen använder sedan denna
data för att kunna PD-reglera sin styrning för att följa tejpen.

\chapter{Modulerna}\label{chap:Modulerna}

\section{Logikmodul}

\begin{figure}[h]
	\centering
	\includegraphics[width=\textwidth]{img/kopplingsschema-rp3}
	\caption{Kopplingsschema för RPi3:an, där logikmodulen och
	kommunikationsmodulen ligger på. \label{img:rp3koppl}}
\end{figure}

\begin{figure}[h]
	\centering
	\includegraphics[width=\textwidth]{img/logik-flodesschema}
	\caption{Flödesschema för logikenheten\label{img:logikflod}}
\end{figure}

Logikenheten är den enhet som sköter allt logiskt tänkande. Denna är alltså inte
aktiv i manuellt läge då kommandon skickas direkt från kommunikationsenheten
till styrenheten. De enda funktionerna som utförs i manuellt läge är att kolla
ifall reset knappen eller switch knappen tryckts ner och utför i sådant fall
rätt åtgärder. Dessa funktioner utförs alltid, alltså även i autonomt läge.

Vid start av roboten frågar kommunikationsenheten användaren efter
lagrets rutors sidolängd. För att logikenheten ska kunna starta behövs
denna längd och denna loopar alltså tills ett meddelande med storleken tagits
emot.

I autonomt läge behöver logikenheten en del information för att veta vart
roboten ska och sedan leda den dit. 

Den informationen logikenheten behöver är:
\begin{itemize}
	\item Lagrets utseende
	\item Var vilka varor finns i lagret
	\item Var varor ska lämnas
	\item Vilken vara som ska plockas upp
\end{itemize}

Logikmodulen påbörjar sitt program med att vänta på ovanstående data
från kommunikationsmodulen. Där efter letar modulen upp en lämplig väg till sitt
mål, som antingen är en korsning intill en plockstation, eller
utlämningsstationen.

Om målet är en plockstation åker roboten från korsninngen mot
plockstationen tills den hittar den. Därefter svänger den in och
ställer sig i position för att plocka upp. Logikenheten meddelar sedan
kommunikationsenheten att en vara skall plockas upp, och väntar på att
den signalerar till baka att varan är upplockad. Slutligen sätts
utlämningsstationen som nytt mål.

Om målet istället är utlämningsstationen åker roboten dit. Där ska den följa den
väg som \quot{lämnar lagret}. När den är framme vid den t-korsning som signifierar
positionen för avlämning så skickas ett kommando till styrenheten att lämna
varan. Logikenheten meddelar kommunikationsenheten att varan är levererad och
kommer sedan vänta på att kommunikationsenheten meddelar om en ny vara som ska 
hämtas. 

\FloatBarrier

\section{Kommunikationmodul}

\begin{figure}[H]
	\centering
	\includegraphics[width=\textwidth]{kommunikations-flodesschema}
	\caption{Flödesschema för kommunikationsenheten\label{img:komflod}}
\end{figure}

Vid kommunikationsenhetens uppstart begärs storleken av varje ruta (i
cm) från den externa datorn. Därefter skickar den en signal till
logikenheten, och väntar på ett \quot{ready} svar innan dess huvud-loop
kör igång.

Kommunikationsenhetens huvud-loop är uppdelad i två delar, en som
alltid gör samma sak, och en som gör olika saker beroende på om den är
i autonomt eller manuellt läge.

I den generella delen kollas om RESET- eller SWITCH-knappen tryckts ner,
och utför deras rutiner vid behov.

\paragraph{Manuellt}

I manuellt läge vidarebefodrar kommunikationsmodulen kommandon från
externa datorn till styrenheten. Detta sker genom att kommunikationsenheten 
kallar på klient.

När ett kommando tagits emot läggs detta på en buffer av datadelaren.
Den tråd som tar hand om kommunikationen mellan styrenheten och de
enheter som ligger på RP3:an kommer sedan hämta information från
buffern och skicka vidare över UART till styrenheten.
I manuellt läge gör inte kommunikationsenheten mer än så.

\paragraph{Autonomt}

Formen på kartan begärs ut om den inte redan är känd, och skickas
sedan vidare till logikenheten.

På samma sätt hämtas en lista av varor och deras positioner, samt
slutligen vilken vara som ska hämtas.

Kommunikationsenheten väntar sedan på en signal från logikenheten att
roboten är redo för att plocka upp en vara. Då begär
Kommunikationsenheten armkommandon från den externa datorn, och utför
dem, tills att en \quot{pickup done}-signal kommer.

Kommunikationsenheten kollar varje loop om denna har fått något nytt
meddelande från logikenheten. Möjliga meddelanden är:
\begin{itemize}
	\item In position
	\item Getting Item
	\item Item Delivered
	\item Next node
\end{itemize}

Vid ett \quot{Next Node} meddelande så skickar kommunikationsenheten vidare
denna nod till externa datorn för att användaren ska kunna se hur roboten beter
sig och var den är på väg. De andra meddelandena sätter flaggor för att
main loopen ska fungera korrekt.

\section{Styrmodulen}
Styrmodulen ansvarar för den fysiska styrningen av robotplattformen, alltså
styrning av de drivkretsar kopplade till hjulen samt styrningen av de servon som
utgör armen. Denna modul är därför strikt beroende av de kommandon och
sensordata som den får från andra moduler för att utföra sina uppgifter på
önskat sätt. Eftersom styrmodulen agerar som mellanhanden mellan besluten av
styrning och den hårdvaruimplementationen av styrningen så prioriterades
abstraktion och läsbarhet vid utvecklandet av modulen. Detta innebär att modulen
är främst uppdelad i tre ansvarsområden: huvudområde, hjulstyrning och
armstyrning.

\begin{figure}[h]
	\centering
	%\includegraphics[width=5cm,height=10cm]{flodesschema}
	\includegraphics[width=\textwidth]{img/styrmoduluppdelning}
	\caption{Beskrivande bild över koduppbyggnaden av styrmodulen  \label{img:styrflod}}
\end{figure}

Bilden nedan illustrerar det informationsflöde och kontrollflöde som finns i modulen. De rundade pilarna mellan styrenhet och de andra delarna av modulen indikerar hur styrenheten kallar på metoder för att utföra tidsbegränsade uppgifter.

\subsection{Styrenhet}
Huvudområde är den fil styrenhet.c som hanterar all
kommunikation till andra moduler och delegerar ut CPU-tid åt utförande av den
önskade funktionaliteten. Det är här main-funktionen ligger som börjar med att
initialisera och konfigurera all kommunikation till och från modulen för att
sedan gå in en evig for-loop. Denna eviga for-loop återvänder kontrollflödet
till efter en uppgift har utförts till sitt slut eller efter ett läge har
brutits genom signal från extern modul. Här uppdateras de register som används
för att kontrollera om extern modul har signalerat för avbrytning, vilket
innebär att den nya signalen som skrivits in i den interna globala variabeln
\quot{command register} skriver över det tidigare värdet i den interna globala
variabeln \quot{copy register}. Tanken med detta är att externa signaler inte ska
interagera med funktionaliteten direkt utan ska slussa genom dessa register för
att undvika brytning av utförande vid olämplig tidpunkt. Flaggan som återställs
används för att signalera om \quot{command register} och \quot{copy register} skiljer sig
åt. Därefter används värdet i \quot{copy register} som det kommando som ska utföras
och väljer mellan om det är arm- eller hjulrelaterat baserat på den inledande
kodningen av kommadon.

Armrelaterade kommandon som skickas från
logik/kommunikationsmodulerna består inledningsvis av fyra 1:or och
hjulrelaterade kommandon som skickas består inledningsvis av fyra 0:or enligt 
armkommando-protokoll~\ref{sub:armprot}. Detta ska
underlätta för särskiljning mellan de två olika typerna av kommandon.
De båda kommandohanterarna är väldigt lika som två switch-satser som matchar
kommandot till det som ligger i \quot{copy register} till ett av sina fall och
delegerar ut uppgift att utföras i respektive områdesspecifika fil. Skillnaderna
är att i armkommandohanteraren så kontrolleras först ett armlås som endast låses
upp om robotplattformen är i standby-läge och vissa av fallen i
hjulkommandohanteraren inte går direkt in i en metod i sin områdesspecifika fil.
Istället går dessa \quot{lägen} genom metoder i huvudfilen för att behålla det
främsta av den kontrollen som sedan anropar metoder i områdesspecifika filen.
Dessa lägen är de som använder sig av flaggan för att bryta sig ut ur och
återvända till den for-loop i main funktionen.


\subsection{Hjulstyrning}
Hjulstyrningsområdet är istället den hårdvarunära implementationen av
funktionalitet kring hjulstyrning. Det är alltså där pinspecifika instruktioner
och liknande implementeras för att underlätta läsbarheten och eventuellt
underhåll som kräver att byta pinnar eller mikrokontroller eller liknande.
Drivkretsarna använder sig av pulsbreddsmodulering för att kontrollera
hastigheten de driver hjulen. Detta arbete sköter mikrokontrollern genom
att sätta inställningar i initialiseringen av drivkretsarna för att aktivera den
alternativa inbyggda funktionaliteten till de kopplade pinnarna. Efter detta
måste endast kontrollregistrarna som bestämmer arbetscykeln sättas till
önskat värde. Detta är i nästan alla fall den definierade konstanten
PWM\_STANDARD som används för att lätt kunna anpassas om högre eller
lägre hastighet skulle önskas. Drivkretsarna ska alltid vara PWM\_STANDARD
eller 0 förutom när roboten ska följa tejpen. Då kommer PD-regleringen styra
hur de två drivkretsarna ska minska eller öka sin arbetscykel för att korrigera
efter tejpen. Värdet är dock centrerat på PWM\_STANDARD.

Riktningarna på hjulen sätts istället genom att sätta pinnarna kopplade till
DIR (se Kopplingsschema) till 1 eller 0. Eftersom drivkretsarna är spegelvända
kommer förflyttning från punkt kräva att riktningarna är inverterade av varandra,
alltså att en DIR är satt till 0 och den andra till 1. Förflyttning på plats,
alltså att rotera på plats, kräver istället att de båda riktningarna är satta
till samma värde. För att förenkla vidareutveckling av andra mer komplexa
kommandon så finns en metod som sätter passande riktningar, help\_dir, som ändrar
värdena på pinnarna till passande vid given riktning.


\subsection{Armstyrning}
Armstyrningsfilen är istället fokuserad på att vara ett lättförståeligt och
användbart gränssnitt till det strikta format som armservona tillhörande
robotplattformen kräver. Tanken är att vid byte av armservon eller
implementation av nya armrelaterade kommandon ska läsbarheten och modulariteten
av uppdelningen av koden kunna underlätta det arbetet.

Armservona är AX-12or kommunicerar via en halvduplex UART dataväg. Detta, 
kombinerat med att dess önskade bits per second ligger på 1M bits/s, gör det 
lämpligare att kommunicera med armen via en hårdvaru-UART. Detta är anledningen 
att kommunikationen mellan sensor- och styrmodul inte sker genom en hårdvaru-UART 
som planerat utan genom en mjukvaruimplementerad lättviktig dataväg, då 
mikrokontrollern endast har två hårdvaru-UARTs. Då datavägen är enkelriktad men 
data måste åt båda håll så är det kritiskt att hindra data från att krocka för att 
armservona ska fungera som önskat. Det kräver även att mikrokontrollerns hårdvaru-
UARTs pinnar ska kopplas samman med en resistor för att undvika flytande värden på pinnen 
enligt specifikation i AX-12s datablad. Detta skulle även kunna implementeras med en 
intern pull-up resistor inom mikrokontrollern, men under projektets gång så användes extern 
resistor för att eliminera felkälla.

Armservona har fördefinierat kommunikationsprotokoll som finns beskrivet i deras datablad, 
och den främsta uppgiften som finns i armstyrningsfilen är att etablera ett mer tillgängligt 
gränssnitt som sköter konverteringen till önskat format. För att skriva till armservona används 
globala interna arrays som parametrar och metoden transmit packet. Transmit packet tar vissa 
värden som parametrar, som ID på det servo man vill styra, vilken instruktion man vill utföra samt 
hur många parametrar som ska användas i paketet. Genom transmit packet kan man då ha ett 
flexibelt antal parametrar som används beroende på vad man vill utföra som nås genom den globala 
arrayn. Det instruktionspaket som skickas till servot kommer i vissa fall generera ett statuspaket 
som ska returneras till mikrokontrollern. Detta accepteras av receive\_packet-metoden för att hindra 
kollision i datavägen. 

\subsection{Kopplingar på virkort}
Virkorten som styrmodulen är implementerad på är rimligtvis så nedskalad och begränsad. De 
komponenter som finns är \quot{atmega} kopplad till systemklockan, resistor, resetknapp samt 
de datavägar till och från modulen. För att underlätta så valdes virsladdarnas att vara färgkodade. 
De svarta virsladdarna är till jord eller konstanta 0:or, de röda är till ström eller konstanta 1:or, de 
gröna är för data in mot \quot{atmega} och de gula för data ut från \quot{atmega}. Nedan finns även 
kopplingsschemat som stöd till att förstå kopplingarna på virkortet.

\begin{figure}[h]
	\centering
	%\includegraphics[width=5cm,height=10cm]{flodesschema}
	\includegraphics[width=\textwidth]{img/styrenhet}
	\caption{Kopplingsschema över styrmodulens på virkortet.  \label{img:styrenhet}}
\end{figure}

\section{Sensormodul}

Sensormodulens uppgift är att samla in all mätdata till roboten, och
vidarebefodra datan till de övriga modulerna på lämpligt format. 

Roboten har två sensorer: en IR-sensor som \quot{tittar} framåt och
hittar hinder, samt en linjesensor som berättar hur bra vi håller oss
på banan.

\begin{figure}[h]
	\centering
	\includegraphics[width=\textwidth]{Sensormodul}
	\caption{Kopplingsschema över Sensormodulen\label{img:sensorkoppl}}
\end{figure}

\paragraph{IR-sensorn}
IR-sensorn ger en analog signal motsvarande hur långt bort ett hinder
är. För inläsning nyttjas \atmega{}:ns \textsc{ADC} (Analog Digital
Converter). De inlästa värdena konverteras sedan tillbaka till cm.

\paragraph{Linjesensorn}
Linjesensorn har ett antal ljus-sensorerer sida vid sida. Läsning sker
av dem sekventiellt, och ger oss en lista av digitala värden.

\subsection{Sändning av data}
% Sensormodulens uppgift är därmed samla in rådata från IR-sensorn samt Linjesensorn
% och paketera denna för att sedan skicka vidare via skrivna protokoll till de
% andra modulerna. Paketen skickas via UART protokollet till Kommunikations- och
% Logikmodulen. Till Styrmodulen används direkt koppling mellan I/O pins från de
% två modulerna som körs via exde protokollet. Packeteringen sker som tidigare nämnt
% via ett eget byggt paketeringsprotokoll vilket tar rådatan och lägger in den i
% data unionsdelen inom paketstrukturen. I och med att den är en unionsstruktur så
% kommer den att välja ut de värden som får input och utifrån det veta vilken typ
% av data som är relevant för överföringen till de andra modulerna.

Till Logik-/Kommunikationsmodulen skickas data via UART-paketen
beskrivna i stycke~\ref{subsec:paket}. Den data som skickas är
avståndet till hindret framför i cm, samt var vi är på linjen.

Styrmodulen får data via ExDe systemet, och får enbart rå linjedata.

\subsection{Huvudrutin}
% Huvud-loopen har i uppdrag att köra set-up rutinerna för de båda sensor samt
% kommunikationsvägarna mellan sensor och kommunikations-, logik- och styrmodulen.
% Här sätts även paketen upp och skickas kontinuerligt till de 
% andra modulerna efter att de paketerats m.h.a avbrottsrutiner från AVR:en.
% Detta fungerar enligt figur~\ref{img:sensflod}.

Programmets struktur kan ses i figur~\ref{img:sensflod}.

Programmet börjar med att initialisera all hårdvara, följt av att det
väntar på handskakningar från de andra modulerna.
Det påbörjar sedan en loop där den:
\begin{enumerate}
	\item Läser linjedata
	\item Antingen:
		\begin{itemize}
			\item Påbörja asynkron överföring av \emph{linjedata} till logik-/kommunikationsenheten
				\\\textbf{ELLER}
			\item Läs längdata med IR-sensorn. 
			\item Påbörja asynkron överföring av \emph{längddata} till
				logik-/kommunikationsenheten.
		\end{itemize}
	\item Skickar linjedata till styr
	\item Inväntar TX\_complete
	\item Upprepar
\end{enumerate}

Till logik- och kommunikationsenheten skickas data asynkront över
UART. Det låter oss samtidigt skicka data till styrenheten över ExDe,
vilket är mer CPU-krävande.
FlipFlop är en \quot{flipfloppande} variabel som varannan gång är sann, 
varannan falsk. Detta för att logik- och kommunikationsenheterna ej behöver
data lika ofta som styrenheten.

När allt det är klart ser vi till att alla paket skickats klart, och
efter det upprepar hela processen.

\begin{figure}[h]
	\centering
	\includegraphics[width=5cm,height=10cm]{Flod_Sensormodul}
	%\missingfigure{Flödesschema för sensormodulen}
	\caption{Flödesschema för sensormodulen\label{img:sensflod}}
\end{figure}

\subsection{Koppling från Sensormodul}
På brädet så från Sensormodulen så finns det 4 portar som i den här
uppsättningen används på följande sätt:
\begin{enumerate}[font=$\bullet$~\normalfont\scshape\color{red!50!black}]
\item [Port 1] alternativ ström in + data pins, ger ej ström när annan ström används
\item [Port 2] JTAG port
\item [Port 3] buss till andra brädet 
\item [Port 4] UART och IR-sensor-kopping.
\end{enumerate}

\chapter{Slutsatser}\label{chap:Slutsatser}
Det finns en del förbättringar som kan göras på produkten. Autonom uppplockning
av varan, samt ditskruvandet av en skärm för att visa information på själva
roboten är båda saker som, i mån om tid, kan göras.
Vidar så kan, i logikenheten, en kö av varor implementeras, som roboten sedan
ska plocka upp en och en för att sedan lasta av på avplockningsstationen.

Det grafiska användargränssnittet kan förbättras,så att robotens nuvarande
position visas i realtid. En annan förbättring till det grafiska
användargränssnittet varans position ska även visas på datorns gränssnitt.

\appendix

\chapter{BNF}\label{chp:bnf}

BNF står för Backus Naur Form, och är ett formellt språk för att
beskriva andra formella språk. Vi har en kort genomgång av det här då
vi använder några små förlängningar till det.

\begin{description}
	\item[\(\bnfr{a}     ::= `a'                       \)] innebär att \( \bnfr{a}\)  är en symbol som alltid är strängen \quot{a}.
	\item[\(\bnfr{b}     ::= \bnfr{a}\big|\bnfr{c}     \)] innebär att \( \bnfr{b} \) är en symbol som antingen är symbolen \(\bnfr{a}\) eller symbolen \(\bnfr{c}\).
	\item[\(\bnfr{query} \to \bnfr{response}           \)] visar en förfrågan mellan enheterna. \emph{OBS} Ej standard BNF.
	\item[\(\bnfr{s}     ::= \bnfr{a} \bnfr{b}         \)] innebär \(\bnfr{a}\) följt av \(\bnfr{b}\) \emph{med} whitespace mellan.
	\item[\(\bnfr{s}     ::= \bnfr{a}\bnfr{b}          \)] innebär \(\bnfr{a}\) följt av \(\bnfr{b}\) \emph{utan} whitespace mellan.
	\item[\(\bnfr{l}     ::= \big\{ \bnfr{a} \big\}    \)] innebär en eller flera \(\bnfr{a}\) objekt, sepparerade med whitespace.
\end{description}

\chapter{Kodlistningar}

Nedan följer ett antal kodlistningar vi tyckte var av extra stor vikt.
För komplett källkod, kontakta gruppen eller se
\url{https://gitlab.ida.liu.se/kmm-lagerrobot}.

\section{UART packets}
\lstinputlisting{uart-packet/packet/src/packet.h}

\section{UART Connections}
\lstinputlisting{uart-packet/packet/src/uart_common.h}

\section{Styrenhet}
\lstinputlisting{headermapp/styrenhet.h}

\section{Armstyrning}
\lstinputlisting{headermapp/arm_servo.h}

\section{Hjulstyrning}
\lstinputlisting{headermapp/wheels.h}

\end{document}
