173 lines
7.6 KiB
Plaintext
173 lines
7.6 KiB
Plaintext
\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}
|