diff --git a/dd.latex b/dd.latex index 2a3373a..d3eae41 100644 --- a/dd.latex +++ b/dd.latex @@ -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} - \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//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//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//collar/} - \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/} - \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} + \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//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//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//collar/} 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//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}