dd/dd.latex

\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{Identification}
This document describes the design of the Fenceless Grazing Collar system,
following the IEEE Standard 1016-2009. It covers the design of all components
of the FGC system, namely the Smart Application, API Server, LoRa Gateway,
and the Collars.

This document is written by Danila Fedorin, Matthew Sessions, and Ryan Alder,
working on the project through Oregon State University.

\section{Design Stakeholders and Concerns}
The primary stakeholders for this project are farmers who may replace their
manual herding of animals with the automated Fencless Grazing Collar system.

The design concerns for this group are as follows:
\begin{itemize}
    \item \emph{Support for large areas:} Grazing can take place over large plots
        of land, and thus, it is important that the Fenceless Grazing Collar system can
        reliably function over large distances.
    \item \emph{Support for large herds:} The majority of farmers have many animals
        that need herding. The Fenceless Grazing Collar system must be able to
        support such configurations.
    \item \emph{Long battery life:} Since the purpose of the Fenceless Grazing Collar System
        is to avoid manual labor in animal herding, it must not require frequent
        maintenance. A long battery life will prevent the need for frequent battery
        replacements.
    \item \emph{Reliability:} Animals must consistently remain within
        prescribed boundaries to prevent livestock loss. It is therefore
        crucial that the system reliably works at all times.
    \item \emph{Accessibility:} The system must support simple configuration
        and management without requiring significant technical skill.
\end{itemize}

\section{Design Viewpoints}
This section provides an overview of the design viewpoints used in this document.

\begin{itemize}
    \item \emph{Context viewpoint:} This viewpoint will define the actors (external active elements
        interacting with the Fenceless Grazing Collar system), and the
        use cases of the system.
    \item \emph{Composition viewpoint:} This viewpoint will define the systems, subsystems, frameworks,
        and other components of the Fenceless Grazing Collar system, as well as how they fit together and
        interact.
    \item \emph{Dependency viewpoint:} This viewpoint will define the dependencies of the systems and subsystems
        of the Fenceless Grazing Collar system.
    \item \emph{Information viewpoint:} This viewpoint will define the types of data items stored in the
        system, as well as the access mechanisms to these data items.
    \item \emph{Interface viewpoint:} This viewpoint will provide an explanation of how to correctly
        use the services provided by the Fenceless Grazing Collar system.
    \item \emph{Structure viewpoint:} This viewpoint will define the physical structure of the system
        in terms of its components.
    \item \emph{Interaction viewpoint:} This viewpoint will define the interactions between the various
        components of the system.
    \item \emph{State dynamics viewpoint:} This viewpoint will describe the internal states of the 
        Fenceless Grazing Collar system, as well as how the system transitions between them.
\end{itemize}

\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.

\subsubsection{Livestock}
The Fenceless Grazing Collars will be placed on live animals, and be used to track their
behavior. The interactions between the collars and the animals are as follows:
\begin{itemize}
    \item \emph{Movement:} Animals will move haphazardly when not acted upon
        by the collars. Because the collar is attached to the animal, its position
        will change as the animal moves.
    \item \emph{Auditory Stimulus:} If the animal leaves a prescribed area,
        the collar will emit an unpleasant sound, intended to prevent the animal
        from going further outside the defined grazing boundaries. 
    \item \emph{Electrical Stimulus:} If the animal continues to move away
        from the prescribed grazing area, the collar will transition from
        using an audotiry simulus to applying a mild shock to the animal.
\end{itemize}

\subsubsection{Users}
The Fencelss Grazing Collars will be configured and monitored by farmers.
The following interactions between the system and the users are possible:
\begin{itemize}
    \item \emph{Adjustment of Boundaries:} Users will be able to adjust
        the prescribed grazing areas, altering the boundaries at which
        various stimuli are invoked. This will be possible through
        a \emph{smart application}, as well as directly through the
        \emph{LoRa gateway}.
    \item \emph{Request for Data:} Users may query the system for the
        locations of the animals, instances of the use of auditory or electrical
        stimuli, or the battery levels of the collars.
    \item \emph{Maintenance:} Users will perform maintenance on the Fenceless
        Grazing Collar devices. The most common instance of maintenance is
        the replacement of the batteries on a collar.
\end{itemize}

\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.

\subsubsection{Smart Application}
The smart application will consist of the following libraries, frameworks, and subsystems:

\begin{itemize}
    \item \emph{Android Platform:} The application will be implemented using
        the Android mobile operating system, as well as its set of supporting
        software and libraries. The Android platform was chosen for its
        ubiquity and ease of use.
    \item \emph{Kotlin Programming Language:} The Kotlin programming languages,
        created by IntelliJ, will be used to implement the Android application.
        Kotlin's "standard library" (the set of methods and procedures
        available to the programmer by default), as well as Kotlin-specific
        Android libraries such as Anko will be used as part of the smart application.
\end{itemize}

\subsubsection{LoRa Gateway}
The LoRa gateway will consist of the following libraries, frameworks, and subsystems:
\begin{itemize}
    \item \emph{Raspberry Pi:} The LoRa gateway's primary subcomponent will be
        the Raspberry Pi, a single-board Linux computer. The Raspberry Pi
        is capable of interfacing with hardware components such as the LoRa
        shield. It also supports the execution of arbitrary programs, such
        as the API server and database management software.
    \item \emph{LoRa Interface:} The LoRa interface will be used as part of the
        LoRa gateway to allow communication between the gateway and the collars
        in the field. The LoRa interface will be invoked from the API server
        software.
    \item \emph{API Server Software:} The LoRa gateway will execute an API
        server, which will be responsible for the communication between
        the smart application and the gateway itself. The API server software
        will use the LoRa interface and receive and send data to deployed collars.
    \item \emph{Database Management Software:} The LoRa gateway will host
        the SQL-based database subsystem. For details on data storage, see
        the Information view.
\end{itemize}

\subsubsection{Collar}
% TODO

\subsection{Dependency view}
The dependencies of each of the components in the Fenceless Grazing Collar
system are as follows:

\begin{itemize}
    \item \emph{Smart Application:} The smart application depends on the LoRa
        gateway to provide information from the collars via an HTTP API.
    \item \emph{LoRa Gateway:} The LoRa gateway depends on the deployed
        collar devices to provide data such as their location, battery level,
        and state.
        % TODO More thorough?
\end{itemize}

\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
        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
\end{itemize}

\subsubsection{Data Stores}
The MariaDB database management software will be used on the LoRa gateway to store each data
item. Each type of data item will be stored in a corresponding table in an SQL database.
Because the data does not have a complex structure, no normalization is necessary, and
the database schema corresponding to each type of data item is exactly as defined above.

\subsubsection{Access Mechamisms}
In the LoRa gateway, SQL queries will be used to store and retrieve data from the MariaDB
database. To facilitate the formulation of complex queries, and to improve code clarity,
the SQLAclehmy Object Relational Model (ORM) will be used. This library maps data presented
in a relational model to objects, thereby allowing for an object-oriented style of interaction
with the database.

In the smart application, data access will be performed through interaction with the LoRa gateway's
HTTP API. In this design, the smart application itself will not store data, but rather make
requests for the data from the gateway, which will, in turn, access the data as described above.
This alows for the abstraction of the details of database storage from the smart application
and potential future user-facing components.

Similarly, the Fenceless Grazing Collars will not directly read or write data from the database.
Rather, they will interact with the LoRa gateway using the LoRa (Long Range) communication
protocol, and broadcasting updates regarding their status. The LoRa gateway will then store
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?

\subsubsection{HTTP API}
The HTTP API, provided by the LoRa gateway's software, defines a programmatic way of
accessing the information in the system, as well as configuring the behavior
of the component collars. The HTTP API will use JSON Web Token (JWT) technology
for authenticating clients (users of the interface), and plain JSON as the data
interchange format used for communicating information between the Fenceless Grazing Collar
system and the cliens. The HTTP API defines the following HTTP routes:

\begin{itemize}
    \item \textbf{/auth/login:} This route receives, in a JSON HTTP request, the username
        and password of the account which is to be authenticated. If the username and password
        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
        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
        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
        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
        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}

\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)
for the HTTP API, allowing users to request data from the sysem and update its configuration
without directly invoking HTTP. This is primarily motivated by the \emph{Accessiblity} design concern.

The smart application interface will be split into three "tabs". Only one tab will be visible
at a time, and the user will be able to switch between tabs at any time. The tabs will be as follows:

\begin{itemize}
    \item \emph{Collar map:} This tab will contain a map of the configured grazing area. On the map,
        the application will also display the location of each animal. Using color and a visual icon,
        it will indicate the battery level of each collar. The application will update
        the map every 15 (fifteen) seconds, a time period which corresponds to the delay between
        device data points being received by the LoRa gateway.

    \item \emph{Collar list:} This tab will provide a textual representation of the device
        data points of each individual collar. In this tab, the application will display a list
        of every active collar, together with its location and battery level.

    \item \emph{Report list:} This tab will provide a textual representation of the stimulus
        activation reports as described in the Information section.

    \item \emph{Adjustment map:} This tab will contain another map. Through this map, it will
        be possible to adjust the boundaries of the grazing area. This will be done by creating,
        moving, and deleting vertices of a polygon, the inside of which represents the valid
        grazing area.
\end{itemize}

\subsection{Stucture 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.
This construction also allows for the simple disassembly of the entire system.

The Raspberry Pi component of the LoRa gateway will be connected to the internet using an
Ethernet cable. It will also use a 32 Gigabyte SD card for the storage of the Linux (Raspbian)
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
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}
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
and the individual collars need to interact with the LoRa gateway.

The smart application interacts with the LoRa gateway through the use of the HTTP API, as specified
in the Interface view. Each action performed by the user in the application (such as listing
all collar locations, listing all stimulus activiation reports, or viewing the map) corresponds
to an API request made by the application to the LoRa gateway over internet.

The collars interact with the LoRa gateway using the LoRa protocol. As described in the Information view,
the collars will broadcast their device state every 15 (fifteen) seconds.
Furthermore, the collars will broadcast information in the event of a use of an auditory
or electical stimulus. These broadcasts will be received by the LoRa gateway, and added to
the database as appropriate.

The interaction between the smart application and the Fenceless Grazing Collars is transitive, and
goes through the LoRa gateway: the application updates the grazing boundaries of deployed devices
by using the HTTP API to contact the LoRa gateway, which, in turns, broadcasts the update command
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}
Each fenceless grazing collar is a state machine. It has multiple states,

\section{Design overlays}
\section{Design rationale}

\end{document}