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

Intermediate commit v2; Proper IEEE format.

Browse Source
This commit is contained in:
Danila Fedorin 2019-11-21 01:14:42 -08:00
parent 492615343f
commit 63dd2b41cb
1 changed files with 296 additions and 132 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

408
dd.latex
View File

@ -27,146 +27,310 @@
\pagebreak
\section{Smart Application}
This section outlines the design of the smart application, used for manipulating
deployed collars from a user device.
\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.
\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.
This document is written by Danila Fedorin, Matthew Sessions, and Ryan Alder,
working on the project through Oregon State University.
\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{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.
\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:
The design concerns for this group are as follows:
\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.
\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}
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:
\section{Design Viewpoints}
This section provides an overview of the design viewpoints used in this document.
\begin{itemize}
\item \textbf{/auth/login}
\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{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.
\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}
\item \textbf{/auth/<token>/logout}
\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{URL Parameters:} none
\item \emph{Parameters:} none
\item \emph{Result:} JWT token is no longer valid for future requests.
\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}
\item \textbf{/data/<token>/current}
\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{URL Parameters:} none
\item \emph{Parameters:} none
\item \emph{Result:} list of coordinates, battery levels, and "in-bounds" tags for each active collar.
\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}
\item \textbf{/data/<token>/collar/<id>}
\subsubsection{LoRa Gateway}
The LoRa gateway will consist of the following libraries, frameworks, and subsystems:
\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.
\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}
\item \textbf{/adjust/<token>}
\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{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.
\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}