Fix typo

dd.latex

@@ -3,26 +3,71 @@
 \def\changemargin#1#2{\list{}{\rightmargin#2\leftmargin#1}\item[]}
 \let\endchangemargin=\endlist
 
+\usepackage{textcomp}
 \usepackage{todonotes}
 \usepackage{caption}
 \usepackage{pgfgantt}
+\usepackage{setspace}
 \linespread{1}
+
+\def \CapstoneTeamName{Automated Fenceless Grazing}
+\def \CapstoneTeamNumber{CS3}
+\def \GroupMemberOne{Ryan Alder}
+\def \GroupMemberTwo{Danila Fedorin}
+\def \GroupMemberThree{Matthew Sessions}
+\def \CapstoneProjectName{Automated Fenceless Grazing}
+\def \CapstoneSponsorCompany{Oregon State University}
+\def \CapstoneSponsorPerson{Bechir Hamdaoui}
+\def \DocType{Design Document}
+
+\newcommand{\NameSigPair}[1]{\par
+\makebox[2.75in][r]{#1} \hfil 	\makebox[3.25in]{\makebox[2.25in]{\hrulefill} \hfill		\makebox[.75in]{\hrulefill}}
+\par\vspace{-12pt} \textit{\tiny\noindent
+\makebox[2.75in]{} \hfil		\makebox[3.25in]{\makebox[2.25in][r]{Signature} \hfill	\makebox[.75in][r]{Date}}}}
+
 \begin{document}
 
-\title{Fenceless Grazing - Design Document}
-\author{Danila Fedorin, \and Matthew Sessions, \and Ryan Alder}
-\maketitle
-
-\begin{abstract}
-    The Fenceless Grazing Collar system aims to reduce the amount of work
-    needed by farmers to keep herds of grazing animals. The project
-    will be implemented using the LoRa wireless communication protocol to allow
-    for long-range interaction between animal-worn collars and a gateway device.
-    Ths gateway device will also provide an HTTP-based JSON API to apply configuration
-    changes to collars through an application built for Android mobile devices.
-    The MariaDB SQL database management system will be used to store the data
-    received from the collar for viewing and analysis.
-\end{abstract}
+\begin{titlepage}
+    \pagenumbering{gobble}
+    \begin{singlespace}
+        % 4. If you have a logo, use this includegraphics command to put it on the coversheet.
+        %\includegraphics[height=4cm]{CompanyLogo}   
+        \par\vspace{.2in}
+        \centering
+        \scshape{
+            \huge CS Capstone \DocType \par
+            {\large\today}\par
+            \vspace{.5in}
+            \textbf{\Huge\CapstoneProjectName}\par
+            \vfill
+            {\large Prepared for}\par
+            \Huge \CapstoneSponsorCompany\par
+            \vspace{5pt}
+            {\Large\NameSigPair{\CapstoneSponsorPerson}\par}
+            {\large Prepared by }\par
+            Group\CapstoneTeamNumber\par
+            % 5. comment out the line below this one if you do not wish to name your team
+            \CapstoneTeamName\par 
+            \vspace{5pt}
+            {\Large
+                \NameSigPair{\GroupMemberOne}\par
+                \NameSigPair{\GroupMemberTwo}\par
+                \NameSigPair{\GroupMemberThree}\par
+            }
+            \vspace{20pt}
+        }
+        \begin{abstract}
+            The Fenceless Grazing Collar system aims to reduce the amount of work
+            needed by farmers to keep herds of grazing animals. The project
+            will be implemented using the LoRa wireless communication protocol to allow
+            for long-range interaction between animal-worn collars and a gateway device.
+            The gateway device will also provide an HTTP-based JSON API to apply configuration
+            changes to collars through an application built for Android mobile devices.
+            The MariaDB SQL database management system will be used to store the data
+            received from the collar for viewing and analysis.
+        \end{abstract}     
+    \end{singlespace}
+\end{titlepage}
 
 \pagebreak
 \tableofcontents
@@ -98,8 +143,8 @@ This section provides an overview of the design viewpoints used in this document
         Fenceless Grazing Collar system, as well as how the system transitions between them.
 \end{itemize}
 
-\section{Design views}
-\subsection{Context view}
+\section{Design Views}
+\subsection{Context View}
 This section describes the actors that will interact with the Fenceless Grazing Collar
 system, as well as the services (interactions) between these actors and the system.
 
@@ -135,12 +180,11 @@ The following interactions between the system and the users are possible:
         the replacement of the batteries on a collar.
 \end{itemize}
 
-\subsection{Composition view}
+\subsection{Composition View}
 This section describes the systems and subsystems of the Fenceless Grazing Collar
 system, as well as how they fit together. The system is made up of three primary
 components: the smart application, the LoRa gateway, and the individual collars.
-% TODO how do THESE fit together?
-% TODO how do any of them fit together, for that matter.
+See the Interaction view to see how these components behave together.
 
 \subsubsection{Smart Application}
 The smart application will consist of the following libraries, frameworks, and subsystems:
@@ -179,9 +223,23 @@ The LoRa gateway will consist of the following libraries, frameworks, and subsys
 \end{itemize}
 
 \subsubsection{Collar}
-% TODO
+The collar component is the physical device that will be placed onto grazing
+livestock. Conceptually, it made up of the driver and the system logic.
 
-\subsection{Dependency view}
+\begin{itemize}
+    \item \emph{Driver:} The driver component is the software responsible for
+        the interaction of the various components of the collar. As described
+        in the structure viewpoint, the collar will be made of several
+        physical devices, such as an AVR Atmega128 microcontroller, a
+        LoRa shield, and hardware for emitting sound. The driver
+        component is the low-level software (likely written in AVR
+        assembly) for interfacing with these components.
+    \item \emph{System Logic:} Implemented using C, this code will
+        implement the core state machine (see State View), and will
+        issue commands to hardware through the driver.
+\end{itemize}
+
+\subsection{Dependency View}
 The dependencies of each of the components in the Fenceless Grazing Collar
 system are as follows:
 
@@ -191,24 +249,31 @@ system are as follows:
     \item \emph{LoRa Gateway:} The LoRa gateway depends on the deployed
         collar devices to provide data such as their location, battery level,
         and state.
+    \item \emph{Collar System Logic:} The collar system logic will dispatch
+        commands to hardware components using the driver software. Thus,
+        it depends on said driver software to interact with the external
+        world.
         % TODO More thorough?
 \end{itemize}
 
-\subsection{Information view}
+\subsection{Information View}
 \subsubsection{Data Items}
 The following data items will be stored by the Fenceless Grazing Collar system:
 \begin{itemize}
     \item \emph{Device Data Point:} Every 15 (fifteen) seconds, each collar device
         will report its status. The status consists of the collar identifier,
-        the GPS coordinates of the device, the battery level, as well as whether
+        the GPS coordinates of the device, the battery level, the current date
+        and time, as well as whether
         or not the device is currently outside of the prescribed area bounds.
     \item \emph{Stimulus Activation Report:} If a collar uses an auditory or electrical
         stimulus to attempt to influence the behavior of its host animal, the conditions
         of this event will be stored. This data item consists of the GPS location at the
-        time of the event, the level of stimulus used (volume of sound or voltage), as well
-        as the identifier of the collar.
-        % TODO dates
-    \item \emph{Account Data:} % TODO
+        time of the event, the current date and time, the level of stimulus used (volume of sound or voltage),
+        as well as the identifier of the collar.
+    \item \emph{Account Data:} User account data needs to be stored on the server
+        to implement authentication in the HTTP API. Only the minimal information
+        necessary will be stored in the database, namely username/hashed password
+        pairs. The password will be hashed using the BCrypt algorithm.
 \end{itemize}
 
 \subsubsection{Data Stores}
@@ -237,7 +302,7 @@ these updates in the database as described above.
 
 \subsection{Interface View}
 The Fenceless Grazing Collar system will provide two methods of using its services,
-namely the HTTP API and the smart application. % TODO cli?
+namely the HTTP API and the smart application.
 
 \subsubsection{HTTP API}
 The HTTP API, provided by the LoRa gateway's software, defines a programmatic way of
@@ -253,23 +318,34 @@ system and the cliens. The HTTP API defines the following HTTP routes:
         match the information in the database, it will return a JWT token containing
         the user's unique identifier. This token will then be used for further interactions
         with the API.
-    \item \textbf{/auth/<token>/logout:} This route receives a JWT token as a URL
+    \item \textbf{/auth/\textless token\textgreater/logout:} This route receives a JWT token as a URL
         parameter. If the token is valid, this route will invalidate it, thereby logging
         out the application that received this token during its authentication.
-    \item \textbf{/data/<token>/current:} This route, when supplied with a valid authentication
+    \item \textbf{/data/\textless token\textgreater/current:} This route, when supplied with a valid authentication
         JWT token, will return a JSON object containing the most recent device data points
         for each of the active collars in the system.
-    \item \textbf{/data/<token>/collar/<id>} This route, when supplied with
+    \item \textbf{/data/\textless token\textgreater/collar/\textless id\textgreater} This route, when supplied with
         a valid authentication JWT token and a valid collar identifier, will return
         some number of the latest device data points associated with the collar.
         The precise number of points to be returned will be configured with a URL
         parameter. Device data points will be returned in the same format as the \textbf{current} route.
-    \item \textbf{/control/<token>/adjust} This route, when supplied with a
+    \item \textbf{/control/\textless token\textgreater/adjust} This route, when supplied with a
         valid authentication JWT token and a JSON-encoded sequence of coordinates representing
         vertices of the new valid grazing area, will apply this configuration to the collars
         in the field.
 \end{itemize}
 
+An example interaction is shown in Figure \ref{fig:sequence}. The user first performs
+a login operation to retrive a JSON API token, then uses that token to perform another
+API request.
+
+\begin{figure}[h]
+    \centering
+    \includegraphics[width=0.5\textwidth]{sequence.png}
+    \caption{Sequence Diagram for Interaction using HTTP API}
+    \label{fig:sequence}
+\end{figure}
+
 \subsubsection{Smart Application}
 The smart application is another interface used to interact with the services provided
 by the Fenceless Grazing Collar system. It provides a Graphical User Interface (GUI)
@@ -299,7 +375,7 @@ at a time, and the user will be able to switch between tabs at any time. The tab
         grazing area.
 \end{itemize}
 
-\subsection{Stucture view}
+\subsection{Structure View}
 The LoRa gateway will be constructed using a Raspberry Pi 2b and the corresponding LoRa shield.
 The Raspberry Pi and the LoRa shield have compatible pinouts, allowing one to be stacked on top
 of the other without the using of soldering equipment or other, more invasive techniques.
@@ -310,16 +386,15 @@ Ethernet cable. It will also use a 32 Gigabyte SD card for the storage of the Li
 operating system, as well as the MariaDB database.
 
 The each individual Fenceless Grazing Collar will consist of a PCB board containing an Atmega328
-microprocessor, a ?? volt battery pack, and a LoRa receiver / transmitter module. Additionally,
-the PCB will contain a speaker used to produce the auditory stimulus. These component will
+microprocessor, a 9 volt battery pack, and a LoRa receiver / transmitter module. Additionally,
+the PCB will contain a speaker used to produce the auditory stimulus, and a GPS module to
+track the location of the collar. These component will
 be soldered onto the PCB to improve structural integrity. The entire PCB assembly will be housed
 within a 3D-printed casing, used to prevent exposure to moisture and other environmental effects.
 
 % TODO how electric shock?
-% TODO volts
-% TODO elaborate? matt + ryan's advice
 
-\subsection{Interaction view}
+\subsection{Interaction View}
 In the Fenceless Grazing Collar system, the LoRa gateway serves as the mediator between
 the smart application and the deployed collars, due to the absence of LoRa receivers
 and transmitters on standard Android mobile devices. Therefore, both the smart application
@@ -342,7 +417,7 @@ by using the HTTP API to contact the LoRa gateway, which, in turns, broadcasts t
 to the collars. Similarly, the collars deliver location information and stimulus reports
 by sending them to the LoRa gateway, from which they are retreived by the application.
 
-\subsection{State dynamics view}
+\subsection{State Dynamics View}
 Each Fenceless Grazing Collar is a state machine. The states are described as follows:
 \begin{itemize}
     \item \emph{Sleep:} This will be the most common state for the collar. As per the
@@ -383,7 +458,16 @@ The transitions between the states are as follows:
         outside the prescribed grazing area, it will transition into the \emph{Awake; loud} state.
 \end{itemize}
 
-\section{Design rationale}
+This is summarized in Figure \ref{fig:state}.
+
+\begin{figure}[h]
+    \centering
+    \includegraphics[width=0.75\textwidth]{state.png}
+    \caption{State Diagram for Fenceless Grazing System}
+    \label{fig:state}
+\end{figure}
+
+\section{Design Rationale}
 The LoRa communication protocol was used specifically to address the \emph{Support for large areas}
 design concern: LoRa works over \textbf{Lo}ng \textbf{Ra}nge, and is bidirectional. These properties
 make it ideal for the Fenceless Grazing Collar system.