\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{Introduction}
The Fenceless Grazing Collar project is primarily divided into three parts: the hardware
in the field (the physical collars placed onto animals), the communication protocol
and software linking the collars to other devices used to control the settings
of the collars, and the smart application which used to configure the collars
through a user-friendly interface.

\section{Hardware}
To separate responsibilities between program logic and driver logic driver software will be developed for AVR to drive the hardware devices, this software is also known as a driver. In software the driver is a program or set of instructions that control some piece of hardware. In our project this driver is to be used by the logic code of the program to control any hardware connected to our collar. Drivers will be written for the collars to allow for control of devices such as: the LoRa transceiver, buzzer, haptic feedback, shocker, and GPS. As the LoRa device is the most complex to drive, more general driver code will be written that will be used by the main program than what is to be written for the other peripherals. The buzzer, haptic, shocker, and GPS drivers will provide a higher level interface for driving these peripherals that is more complete in its control of the devices. All libraries are to be written in pure AVR C to maximize learning and control.

For debugging of the AVR parts of the project, serial debug libraries will be implemented to allow observation of the system from a connected computer. The debugging library will be written in pure AVR C and coded to work specifically with our chosen  micro-controller. This debugging library will need to be implemented asynchronously to prevent stalling of other hardware drivers to the connected peripherals. Having an asynchronous debugging library provides an extra method to debug the I2C and SPI protocols both in real-world test and simulated tests.

To test the embedded firmware of the project, AVR simulation will be used. Simulation will allow for the basic debugging of signals without the need for an oscilloscope or other logic analyzer. While the simulation will not always reflect real-world conditions, it will illustrate general operation of the collar in ideal conditions. The program used to simulate will be simavr, this being a program that supports most-all AVR micro-controllers. This program allows for the output of digital signals such as: pins, registers, SPI, and I2C. Signals output by simavr are easily viewable in the program GtkWave which is an open source alternative to Modelsim.

All devices in the project need to be portable or semi-portable. There are two types of devices in the system. The collar which is to be put on an animal and needs to be purely portable. The gateway which should be able to fit in a backpack and be semi-portable. The collar will use a 14500 Lipo which is used in many AVR development boards with LoRa. The gateway is a 
Raspberry Pi and will be easily powered through a USB power bank unless a more robust solution is required.

\section{LoRa}
Communication over vast distances will be solved via the LoRa (Long Range) technology patented by Semtech. In order to fully implement the LoRa protocol patented transmitters and receivers are required. The first step in this process is to purchase and integrate the LoRa transmitters and receivers to each end node and the gateway. Actual integration with the LoRa receivers to our backend logic and server will likely be the most complicated part, and as a result is expected to take until spring quarter at the very latest to fully implement. Depending on time constraints, boards with LoRa transmitters and receivers already attached may be purchased. Drivers will need to be written and integrated into our software stack before testing can begin. Setting up the communication between these devices, ensuring scalability, and providing a reliable service are necessary for this project. Hardware will need to be sourced, integrated, and tested on each collar. The number of gateways will need to be determined on a case-by-case basis for each farm. A study will need to be conducted into the optimal way to setup a LoRa network, with distance and battery life taken into consideration. Once the number of communications per day are determined, the distance required, and the battery life needed the number of gateways can be determined. Each farm will have different requirements (number of animals, distance between end nodes and gateways, etc.) and in order to determine limitations in terms of these variables data will need to be gathered with an actual LoRa network. Once the LoRa proprietary chips are purchased and integrated into the end nodes and gateway data collection and testing will begin. Our primary goal upon receiving hardware is ensuring that everything works as intended, including building a software backend to support transmitting and receiving information between nodes. In order to ensure correct functionality and implementation of the LoRaWAN protocol extensive time will be spent testing our hardware. Once we have successfully communicated between two LoRa chips via the chirp spread spectrum (CSS) technology data will be gathered in terms of distance of communication over different types of land. For example, we need to categorize our hardware and give a maximum distance over flat land, through buildings, and other terrain.  The next step in terms of data collection of the capabilities of the LoRa network will be to determine how frequently we need each end-node to communicate to the server, and how many end nodes are required per farm. With this information the number of gateways can be determined based on the frequency of packet collisions in the network. This may need to be tested with the actual hardware to provide accuracy, which can only be accomplished once the actual hardware is set in stone due to the necessity of gathering multiple devices. This may not be necessary for our project, and possibly can remain at theoretical stage based on any time constraints we encounter. For example, the theoretical collision rate between end nodes transmitting at a certain frequency can be determined which will provide good estimates for the required hardware for each network. Overall, communication between two LoRa transmitters/receivers needs to be completed by at least week 5 in the winter term in order to move onto driver development and LoRa capability testing.

\section{Smart Application}
One of the requirements for the project is the development of a smart application which
serves to control the collar devices in the field. This application will be developed
using the Kotlin programming language for the Android platform, with the aim to
support 95\% of the devices currently available on the platform (the analysis of the
requried Android version to fulfil this requirement will be performed when
the application begins development). The application will use a JSON HTTP API
to interact with an external device, the LoRa gateway and data server. This
means that the applications themselves will not store any data about the collars
except for caching, and will rely entirely on the LoRa gateway to interact
with the collars in the field.

The LoRa gateway will be a Raspberry Pi Linux machine, configured to store data
gathered from the fenceless collars, as well as to forward communication from the
Android devices to the collars placed onto animals. To do so, the Raspberry Pi
will provide a JSON HTTP API, exposed to the open internet and protected through
authentication based on the JSON Web Token (JWT) technology. The server,
written in Python, will receive authentication requests from the Android
applications (or other client applications), and generate JSON tokens signed
with a secret key. These JSON tokens will be returned to the applications
to indicate a completed authentication, and then used to authorize further
requests to the machine. 

The LoRa gateway will interact with LoRa-equipped collars in the field through
the use of a Raspberry Pi-compatible LoRa shield (a hardware component that
can be added to the Raspberry Pi without soldering or other "intensive" hardware
work). 

The LoRa gateway will be configured with a MySQL database storing the recent
GPS data for each animal in the field. Location data will be stored in 15 second intervals,
to prevent excessive pollution of the database with redundant information, and to
reduce the storage requirement of the LoRa gateway. Additionally, each time that
a stimulus is used by a collar to prevent an animal from leaving the desired
area, this event will also be logged by the collar, to provide farmers with
potentially critical information about the behavior of the animals. In order
to properly tell apart the various animals, the unique identifier of each
collar will also be stored in the database along with every location and
stimulus entry. When a client (such as an Android application as described above)
requests a specific piece of information, the server on the Raspberry Pi will
perform an SQL query matching the type of the request, and convert the resulting
data into the JSON format expected by the API. This way, the server-side implementation
of data storage does not affect the client code, and future changes (such as 
switching to a different SQL database, or to a NoSQL storage system) will
be easier to integrate.

\section{Conclusion}
Over the course of the next six months our team will develop and build the hardware and software required for our project including the physical collars on the animals, the communication protocol LoRa and LoRaWAN, and the software linking the collars to the Android application. Drivers will be written and integrated on each collar to connect all of the components into one central interface system complete with a logic program sending and receiving data from the server. This communication will be provided via the LoRa communication protocol, providing a long distance low bandwidth interface. Extensive testing will be conducted into the efficiency and scalability of the LoRa system to ensure proper implementation across all varieties of farms and farmland. Lastly, an Android application and HTTP server will be written to allow user interaction with all collars across the farm. These applications will be complete with an SQL database and API allowing for simple communication between the phone and server. Data about each animal, their location, and other information will be stored in the server and readily available to the user. All of these components will come together to provide a complete, working prototype to simplify the work required by farmers and decrease overall interaction with their livestock.


\end{document}