\documentclass[10pt, draftclsnofoot,onecolumn]{IEEEtran}

\def\changemargin#1#2{\list{}{\rightmargin#2\leftmargin#1}\item[]}
\let\endchangemargin=\endlist

\usepackage{todonotes}
\usepackage{caption}
\usepackage{pgfgantt}
\linespread{1}
\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.
\end{abstract}

\pagebreak
\tableofcontents

\pagebreak

\section{Smart Application}
This section outlines the design of the smart application, used for manipulating
deployed collars from a user device.

\subsection{Application Platform}
The smart application will be a smartphone program based on the Android mobile operating
system. This allows the application to be installed on the majority of phones
currently in use in the United States [citation needed], and minimizes the complexity
of developing the project. The application will be written in the Kotlin language,
which is designed as a replacement for Java. Because Koltin is one of the official languages
for the Android platform, it will be used with the standard libraries and frameworks
provided by the platform. The usage of Kotlin and standard libraries will not only
improve code quality (due to various features of the Koltin language such as
compile-time null safety and automatic code synthesis), but will also improve
user experience by avoiding additional layers of abstraction between the
application and the user.

\subsection{Communication with Other Components}
Because the application is intended as a means of controlling Fenceless Grazing Collars
in the field, there must exist a way for communicating information between the application
and the collars themselves. Direct communication with individual collars is not possible due
to the lack of a LoRa receiver on the typical Android device. To work around this, the application
will communicate with the LoRa gateway, a device equipped with a LoRa transmitter and
receiver. The Android application will perform requests
to the LoRa gateway via an HTTP API, and display the result of the interaction to
the user. For details on the HTTP API, see the corresponding section.

\section{Application Server}
This section describes the software running on the LoRa gateway that is
responsible for handling API requests from the Smart Application.

\subsection{Language and Platform}
The LoRa gateway is a Raspberry Pi equipped with
a hardware shield to allow for LoRa-based communication. The Raspberry Pi
platform has official support for using the Python programming language to
interface with external components like the shield[citation needed], and thus Python
will be used to implement the software for both the Application-Server
interaction, and for the Gateway-Collar communication.

\subsection{Data Storage}
The Application Server will store and retreive data into a MariaDB SQL database
configured on the same device as the server software. The following data will be
logged every 15 (fifteen) seconds, for each collar:
\begin{itemize}
    \item The identifier of the collar
    \item The GPS coordinates
    \item The battery level
    \item Whether the GPS coordinates are currently outside of expected bounds.
\end{itemize}

Furthermore, each time that an auditory or electrical stimulus is used, the
following information will be logged:
\begin{itemize}
    \item The identifier of the collar
    \item The GPS coordinates
    \item The "severity" of the stimulus
\end{itemize}

Here, the severity of stimulus refers to the notion of progressively
increasing stimuli: if an animal does not respond to a sound of a particular
volume, the next attempt will increase the volume to a higher level, or
invoke electric shocks.

\subsection{Frameworks and Libraries}
The Python application will use the SQLAlchemy Object Relational Model (ORM)
library to simplify access to the database. This library provides an
object-oriented approach of manipulating data stored in a relational database.
This approach is useful for the server due to Python's preference for the
object-oriented model.

The Flask web application framework will be used to provide the HTTP API.
The framework introduces minimal additional complexity, but provides
all the necessary features to implement the HTTP API as specified in
the corresponding section.

\section{HTTP API}
This section describes the HTTP API that is used in the interaction
of the Application Server and the Smart Application. The API
specifies a "server" and a "client". The "server" is the
software running on the LoRa gateway, having access to the database
and able to communicate with collars in the field. The "client"
is any party wishing to use the HTTP API to trigger an action
or retreive information from the grazing collars. At present,
this is simply the Smart Application.

\subsection{Authentication}
Authentication will be achieved through the use of JSON Web Token
(JWT) technology. The procedure for verifying a client's identity
is as follows:

% TODO ol instead of ul
\begin{itemize}
    \item Receive JSON object containing username and password from the client.
    \item Compute password hash using BCrypt, and search database for matching credentials.
    \item If found, create JWT token containing the unique identifier of the user.
    \item Return JWT token to client in the HTTP response.
\end{itemize}

The client is expected to then provide the generated JWT token when making further
API requests.

\subsection{Encoding}
The API will use JSON for requests and responses. On the client side, simple data, such as the JWT authentication
token, will be encoded in the URL of the API request, while complex data, such as coordinates,
will be encoded in JSON. 

\subsection{API}
The API provides the following methods:

\begin{itemize}
    \item \textbf{/auth/login}
        \begin{itemize}
            \item \emph{URL Parameters:} none
            \item \emph{Parameters:} username and password of the account that is being logged into.
            \item \emph{Result:} JWT for use in further API requests.
        \end{itemize}
    \item \textbf{/auth/<token>/logout}
        \begin{itemize}
            \item \emph{URL Parameters:} none
            \item \emph{Parameters:} none
            \item \emph{Result:} JWT token is no longer valid for future requests.
        \end{itemize}
    \item \textbf{/data/<token>/current}
        \begin{itemize}
            \item \emph{URL Parameters:} none
            \item \emph{Parameters:} none
            \item \emph{Result:} list of coordinates, battery levels, and "in-bounds" tags for each active collar.
        \end{itemize}
    \item \textbf{/data/<token>/collar/<id>}
        \begin{itemize}
            \item \emph{URL Parameters:} identifier of collar.
            \item \emph{Parameters:} none
            \item \emph{Result:} list of data points for the collar with the given identifier.
        \end{itemize}
    \item \textbf{/adjust/<token>}
        \begin{itemize}
            \item \emph{URL Parameters:} none
            \item \emph{Parameters:} list of coordinates specifying the vertices of new boundary area.
            \item \emph{Result:} LoRa command to adjust boundary is issued.
        \end{itemize}
\end{itemize}

\end{document}