CS-46X/dd
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Make small fixes and add required title page

Browse Source
This commit is contained in:
Danila Fedorin 2019-11-23 22:50:15 -08:00
parent 9ec10678a8
commit 8cca577d3d
1 changed files with 124 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

164
dd.latex
View File

@ -3,26 +3,71 @@
\def\changemargin#1#2{\list{}{\rightmargin#2\leftmargin#1}\item[]} \def\changemargin#1#2{\list{}{\rightmargin#2\leftmargin#1}\item[]}
\let\endchangemargin=\endlist \let\endchangemargin=\endlist
\usepackage{textcomp}
\usepackage{todonotes} \usepackage{todonotes}
\usepackage{caption} \usepackage{caption}
\usepackage{pgfgantt} \usepackage{pgfgantt}
\usepackage{setspace}
\linespread{1} \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} \begin{document}
\title{Fenceless Grazing - Design Document} \begin{titlepage}
\author{Danila Fedorin, \and Matthew Sessions, \and Ryan Alder} \pagenumbering{gobble}
\maketitle \begin{singlespace}
% 4. If you have a logo, use this includegraphics command to put it on the coversheet.
\begin{abstract} %\includegraphics[height=4cm]{CompanyLogo}
The Fenceless Grazing Collar system aims to reduce the amount of work \par\vspace{.2in}
needed by farmers to keep herds of grazing animals. The project \centering
will be implemented using the LoRa wireless communication protocol to allow \scshape{
for long-range interaction between animal-worn collars and a gateway device. \huge CS Capstone \DocType \par
Ths gateway device will also provide an HTTP-based JSON API to apply configuration {\large\today}\par
changes to collars through an application built for Android mobile devices. \vspace{.5in}
The MariaDB SQL database management system will be used to store the data \textbf{\Huge\CapstoneProjectName}\par
received from the collar for viewing and analysis. \vfill
\end{abstract} {\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.
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}
\end{singlespace}
\end{titlepage}
\pagebreak \pagebreak
\tableofcontents \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. Fenceless Grazing Collar system, as well as how the system transitions between them.
\end{itemize} \end{itemize}
\section{Design views} \section{Design Views}
\subsection{Context view} \subsection{Context View}
This section describes the actors that will interact with the Fenceless Grazing Collar 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. 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. the replacement of the batteries on a collar.
\end{itemize} \end{itemize}
\subsection{Composition view} \subsection{Composition View}
This section describes the systems and subsystems of the Fenceless Grazing Collar 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 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. components: the smart application, the LoRa gateway, and the individual collars.
% TODO how do THESE fit together? See the Interaction view to see how these components behave together.
% TODO how do any of them fit together, for that matter.
\subsubsection{Smart Application} \subsubsection{Smart Application}
The smart application will consist of the following libraries, frameworks, and subsystems: 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} \end{itemize}
\subsubsection{Collar} \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 The dependencies of each of the components in the Fenceless Grazing Collar
system are as follows: system are as follows:
@ -191,24 +249,31 @@ system are as follows:
\item \emph{LoRa Gateway:} The LoRa gateway depends on the deployed \item \emph{LoRa Gateway:} The LoRa gateway depends on the deployed
collar devices to provide data such as their location, battery level, collar devices to provide data such as their location, battery level,
and state. 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? % TODO More thorough?
\end{itemize} \end{itemize}
\subsection{Information view} \subsection{Information View}
\subsubsection{Data Items} \subsubsection{Data Items}
The following data items will be stored by the Fenceless Grazing Collar system: The following data items will be stored by the Fenceless Grazing Collar system:
\begin{itemize} \begin{itemize}
\item \emph{Device Data Point:} Every 15 (fifteen) seconds, each collar device \item \emph{Device Data Point:} Every 15 (fifteen) seconds, each collar device
will report its status. The status consists of the collar identifier, 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. 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 \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 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 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 time of the event, the current date and time, the level of stimulus used (volume of sound or voltage),
as the identifier of the collar. as well as the identifier of the collar.
% TODO dates \item \emph{Account Data:} User account data needs to be stored on the server
\item \emph{Account Data:} % TODO 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} \end{itemize}
\subsubsection{Data Stores} \subsubsection{Data Stores}
@ -237,7 +302,7 @@ these updates in the database as described above.
\subsection{Interface View} \subsection{Interface View}
The Fenceless Grazing Collar system will provide two methods of using its services, 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} \subsubsection{HTTP API}
The HTTP API, provided by the LoRa gateway's software, defines a programmatic way of 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 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 the user's unique identifier. This token will then be used for further interactions
with the API. 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 parameter. If the token is valid, this route will invalidate it, thereby logging
out the application that received this token during its authentication. 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 JWT token, will return a JSON object containing the most recent device data points
for each of the active collars in the system. 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 a valid authentication JWT token and a valid collar identifier, will return
some number of the latest device data points associated with the collar. 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 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. 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 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 vertices of the new valid grazing area, will apply this configuration to the collars
in the field. in the field.
\end{itemize} \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} \subsubsection{Smart Application}
The smart application is another interface used to interact with the services provided 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) 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. grazing area.
\end{itemize} \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 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 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. 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. operating system, as well as the MariaDB database.
The each individual Fenceless Grazing Collar will consist of a PCB board containing an Atmega328 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, 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. These component will 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 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. within a 3D-printed casing, used to prevent exposure to moisture and other environmental effects.
% TODO how electric shock? % 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 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 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 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 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. 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: Each Fenceless Grazing Collar is a state machine. The states are described as follows:
\begin{itemize} \begin{itemize}
\item \emph{Sleep:} This will be the most common state for the collar. As per the \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. outside the prescribed grazing area, it will transition into the \emph{Awake; loud} state.
\end{itemize} \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} 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 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. make it ideal for the Fenceless Grazing Collar system.