\documentclass[10pt, draftclsnofoot,onecolumn, compsoc]{IEEEtran} \def\changemargin#1#2{\list{}{\rightmargin#2\leftmargin#1}\item[]} \let\endchangemargin=\endlist \usepackage{textcomp} \usepackage{todonotes} \usepackage{caption} \usepackage{pgfgantt} \usepackage{setspace} \linespread{1} \def \CapstoneTeamName{Automated Fenceless Grazing} \def \CapstoneTeamNumber{CS3} \def \GroupMemberOne{Ryan Alder} \def \GroupMemberTwo{Danila Fedorin} \def \GroupMemberThree{Matthew Sessions} \def \CapstoneProjectName{Automated Fenceless Grazing} \def \CapstoneSponsorCompany{Oregon State University} \def \CapstoneSponsorPerson{Bechir Hamdaoui} \def \DocType{Design Document} \newcommand{\NameSigPair}[1]{\par \makebox[2.75in][r]{#1} \hfil \makebox[3.25in]{\makebox[2.25in]{\hrulefill} \hfill \makebox[.75in]{\hrulefill}} \par\vspace{-12pt} \textit{\tiny\noindent \makebox[2.75in]{} \hfil \makebox[3.25in]{\makebox[2.25in][r]{Signature} \hfill \makebox[.75in][r]{Date}}}} \begin{document} \begin{titlepage} \pagenumbering{gobble} \begin{singlespace} % 4. If you have a logo, use this includegraphics command to put it on the coversheet. %\includegraphics[height=4cm]{CompanyLogo} \par\vspace{.2in} \centering \scshape{ \huge CS Capstone \DocType \par {\large\today}\par \vspace{.5in} \textbf{\Huge\CapstoneProjectName}\par \vfill {\large Prepared for}\par \Huge \CapstoneSponsorCompany\par \vspace{5pt} {\Large\NameSigPair{\CapstoneSponsorPerson}\par} {\large Prepared by }\par Group\CapstoneTeamNumber\par % 5. comment out the line below this one if you do not wish to name your team \CapstoneTeamName\par \vspace{5pt} {\Large \NameSigPair{\GroupMemberOne}\par \NameSigPair{\GroupMemberTwo}\par \NameSigPair{\GroupMemberThree}\par } \vspace{20pt} } \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. The gateway device will also provide an HTTP-based JSON API to apply configuration changes to collars through an application built for Android mobile devices. The MariaDB SQL database management system will be used to store the data received from the collar for viewing and analysis. \end{abstract} \end{singlespace} \end{titlepage} \pagebreak \tableofcontents \pagebreak \section{Introduction} The Fenceless Grazing Collar system is designed to reduce the amount of manual labor performed by farmers owning herds of livestock. By automating the herding of animals such as cattle, farmers may be able to save a significant amount of time and money. The Fenceless Grazing Collar system consists of a smart application, a "gateway", and individual collars to be placed onto animals. \section{Changes} The following changes have been made to this document as the term went on: \vspace{0.1in} \begin{tabular}{p{0.4\linewidth}p{0.45\linewidth}} \hline Before & After \\ \hline \\ Only LoRa was described in the design. & LoRaWAN explicitly mentioned and described. \\ \\ MariaDB was used for data storage. & SQLite used due to smaller footprint and easier setup. \\ \\ Gateway was responsible for LoRaWAN. & LoRaWAN offloaded to The Things Network. \\ \\ LoRa shield was used for Gateway. & LoRa concentrator does not come as a Raspberry Pi shield. A custom adapter is used to connect the concentrator to the Gateway. \end{tabular} % Collars are attached to live animals that emit an auditory or electrical stimulus when the animal % leaves its designated area, preventing it from traveling further outside % the established grazing boundaries. % TODO this is bad; improve later. \section{Glossary} \begin{itemize} \item \emph{LoRa:} A radio-based protocol for \textbf{Lo}ng\textbf{Ra}nge communication. \item \emph{LoRaWAN:} A \textbf{W}ireless \textbf{A}ccess \textbf{N}etwork based on LoRa. \item \emph{The Things Network}: A free, internet-based implementation of a LoRaWAN network server. Handles encoding and decoding of packets for the LoRaWAN protocol. \item \emph{HTTP:} HyperText Transfer Protocol, which is currently the most popular standard for web servers and APIs. \item \emph{JSON:} JavaScript Object Notation, a language for encodings structured data. \end{itemize} \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. See the Interaction view to see how these components behave together. \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 LoRaWAN concentrator. 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 use the LoRaWAN protocol. To facilitate the implementation of the LoRaWAN protocol, the LoRa interface will transmit LoRa packets to the Things Network over the internet, which will respond with decoded data to the MQTT process (described below). % TODO things network? \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 use the SQL-based database on the gateway to interact with the MQTT process. \item \emph{Database Management Software:} The LoRa gateway will host the SQL-based database subsystem. For details on data storage, see the Information view. \item \emph{MQTT Process:} The MQTT process will run on the gateway, sending and receiving data to the Things Network, which will handle the the LoRaWAN implementation. This process will use the SQL-based database to store incoming data points, as well as to listen for commands from the API Server Software. Commands from the API Server Software could prompt the MQTT process to send data over the Things Network and LoRaWAN to the collars. \end{itemize} \subsubsection{Collar} The collar component is the physical device that will be placed onto grazing livestock. Conceptually, it made up of the driver and the system logic. \begin{itemize} \item \emph{Driver:} The driver component is the software responsible for the interaction of the various components of the collar. As described in the structure viewpoint, the collar will be made of several physical devices, such as an AVR Atmega128 microcontroller, a LoRa concentrator, and hardware for emitting sound. The driver % TODO matt explain new setup component is the low-level software (likely written in AVR assembly) for interfacing with these components. \item \emph{System Logic:} Implemented using C, this code will implement the core state machine (see State View), and will issue commands to hardware through the driver. \end{itemize} \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. The LoRa gateway also depends on the Things Network to handle LoRaWAN encoding and decoding. \item \emph{Collar System Logic:} The collar system logic will dispatch commands to hardware components using the driver software. Thus, it depends on said driver software to interact with the external world. % 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, the current date and time, 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 current date and time, the level of stimulus used (volume of sound or voltage), as well as the identifier of the collar. \item \emph{Account Data:} User account data needs to be stored on the server to implement authentication in the HTTP API. Only the minimal information necessary will be stored in the database, namely username/hashed password pairs. The password will be hashed using the BCrypt algorithm. \end{itemize} \subsubsection{Data Stores} The SQLite 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 SQLite 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. \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/\textless token\textgreater/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/\textless token\textgreater/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/\textless token\textgreater/collar/\textless id\textgreater} 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/\textless token\textgreater/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} An example interaction is shown in Figure \ref{fig:sequence}. The user first performs a login operation to retrive a JSON API token, then uses that token to perform another API request. \begin{figure}[h] \centering \includegraphics[width=0.5\textwidth]{sequence.png} \caption{Sequence Diagram for Interaction using HTTP API} \label{fig:sequence} \end{figure} \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{Structure View} The LoRa gateway will be constructed using a Raspberry Pi 2b and the corresponding LoRaWAN concentrator. A custom adapter will be created to connect the two. 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 9 volt battery pack, and a LoRa receiver / transmitter module. Additionally, the PCB will contain a speaker used to produce the auditory stimulus, and a GPS module to track the location of the collar. 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? \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 LoRaWAN 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. The states are described as follows: \begin{itemize} \item \emph{Sleep:} This will be the most common state for the collar. As per the \emph{Long battery life} design concern, it's necessary that the collars remain functional for long periods of time without maintenance. By putting the hardware of the collar into sleep, the system will lower power consumption, and thus improve battery life. \item \emph{Awake; quiet} The device will be in this state when it is gathering and trasmitting GPS data to the LoRa gateway, while the host animal is within the prescribed grazing area. No sound or other stimulus is necessary in this state. \item \emph{Awake; loud} The device will be in the state when the host animal is within a small distance outside the prescribed grazing area, and had not spent a long period of time there. In this state, the auditory stimulus will be active with the intention of preventing the animal from further negative action. \item \emph{Awake; shocking} The device will be in this state when the host animal has traveled far outside the prescribed grazing area, or has remained within a small distance of the area for a long time. The electrical stimulus component is active in this state. \end{itemize} The transitions between the states are as follows: \begin{itemize} \item Every 15 seconds, if the device is in the \emph{Sleep} state, it will transition into the \emph{Awake; quiet} state. \item In the \emph{Awake; quiet} state, if the GPS coordinates are within the prescribed grazing area, the device will return into the \emph{Sleep} state. \item In the \emph{Awake; quiet} state, if the GPS coordinates are within a 10ft distance outside the prescribed grazing area, the device will transmit a stimulus activation report, and transition into the \emph{Awake; loud} state. \item In the \emph{Awake; loud} state, if the GPS coordinates are within the prescribed grazing area, the device will transition into the \emph{Sleep} state. \item in the \emph{Awake; loud} state, if the device has spent 30 seconds outside, but in close proximity to, the prescribed grazing area, it will transmit a stimulus activation report, and transition into the \emph{Awake; shocking} state. \item in the \emph{Awake; loud} state, if the device is further than 10ft outside the grazing area, it will transmit a stimulus activation report, and transition into the \emph{Awake; shocking} state. \item in the \emph{Awake; shocking} state, if the device is within a 10ft distance outside the prescribed grazing area, it will transition into the \emph{Awake; loud} state. \end{itemize} This is summarized in Figure \ref{fig:state}. \begin{figure}[h] \centering \includegraphics[width=0.75\textwidth]{state.png} \caption{State Diagram for Fenceless Grazing System} \label{fig:state} \end{figure} \section{Design Rationale} The LoRa communication protocol was used specifically to address the \emph{Support for large areas} design concern: LoRa works over \textbf{Lo}ng \textbf{Ra}nge, and is bidirectional. These properties make it ideal for the Fenceless Grazing Collar system. The LoRa gateway's API was chosen to be HTTP-based, rather than Bluetooth-based, to allow for both remote communication and alternative clients (such as web interfaces). This necessitates the use of a public-facing server (and likely a domain name to allow for DNS resolution). Kotlin was chosen over Java due to its superior type system, which helps mitigate the Million Dollar Mistake [citation needed], as well as because of its capacity to reduce boilerplate. This is an acceptable decision due to Google's official support of the Kotlin language. \section{Conclusion} The Fenceless Grazing Collar system provides reliable, accessible, and scalable solution for replacing manual labor in livestock herding. Through the use of physical collars attached to live animals, providing auditory and electric stimuli, the system encourages animals to stay within prescribed grazing boundaries without the need of direct human involvement. LoRa communication is used to manage the collar devices spread out in the field, and both an HTTP JSON-based API and a smart application are provided to expose the configuration and data collection functionality of the collars to the user. \end{document}