Update design document

Makefile

@@ -1,10 +1,13 @@
 archive.pdf: intro.pdf requirements.pdf design-doc.pdf \
     binary/techreview-ryan.pdf techreview-daniel.pdf binary/techreview-matt.pdf \
     binary/blog-ryan.pdf blog-daniel.pdf binary/blog-matt.pdf \
+    binary/poster.pdf \
     readme.pdf resources.pdf reflection.pdf listings.pdf images.pdf review.pdf todo.pdf
+	ruby toc.rb
 	pdfjam --no-tidy --outfile archive.pdf -- intro.pdf requirements.pdf design-doc.pdf \
 	    binary/techreview-ryan.pdf techreview-daniel.pdf binary/techreview-matt.pdf \
 	    binary/blog-ryan.pdf blog-daniel.pdf binary/blog-matt.pdf \
+	    binary/poster.pdf \
 	    readme.pdf resources.pdf reflection.pdf listings.pdf images.pdf review.pdf todo.pdf
 
 todo.pdf: todo.tex
@@ -72,7 +75,10 @@ review-collar.tex: external/collar/REVIEW.md
 review.pdf: review-app.tex review-server.tex review-collar.tex review.tex
 	pdflatex review.tex
 
-intro.pdf: intro.tex
+generated.toc:
+	touch generated.toc
+
+intro.pdf: intro.tex generated.toc
 	pdflatex intro.tex
 
 blog-daniel.pdf: external/blog-daniel/blog.tex

default.nix

@@ -2,6 +2,8 @@ with import <nixpkgs> {};
 
 mkShell {
   buildInputs = [
+    pdftk
+    ruby
     pandoc
     (texlive.combine {
       inherit (texlive)

intro.tex

@@ -72,11 +72,60 @@
 \end{titlepage}
 
 \pagebreak
-\section*{Foreword}
-% TODO
+\section*{Table of Contents}
+\input{generated.toc}
 
 \pagebreak
-\section{Project Introduction}
+\section*{Foreword}
+\subsection*{Release Notes}
+In its present version, the project is capable of the following things:
+
+\begin{itemize}
+    \item \textbf{GPS reporting}: Each collar has the ability to gather GPS information frequently and transmit this information back to the gateway. Each end-device has a certain frequency of communication, and can be set to send messages once every certain time period. This value is defined based on the number of end-devices, battery constraints, and desired latency. For example, the frequency can be set to once every 5 minutes. Then, the gateway will hear over LoRa a transmission from an end-device once every 5 minutes. This information is decoded and saved to the database. The contents of this message is the current location of the end-device. This allows each collar to frequently inform the gateway and eventually the user of its current location, and the database provides a history of each collar.
+
+    \item \textbf{Observing all animals on the Android application}: The Android application can display to the user the most recent location of each end-device based on the last received transmission. This information is displayed on a fully interactive map, allowing the user to navigate the map by zooming or panning. This provides the user with the ability to observe each animal's location, which is accurate to about a foot.
+
+    \item \textbf{Defining grazing boundaries}: The Android application fully supports defining boundaries by adding and manipulating coordinates on an interactive map. The user has the ability to add a grazing boundary using up to ten different points. Once the user has defined these points on the map, and is happy with the resulting boundary, this information is send over HTTP back to the server which then saves this information into the database. The gateway will then poll this database frequently, and once it notices that a new boundary has been defined it will queue this new data to be sent to every end-device on the next transmission. Then, the new boundaries are sent out and received by each collar which overwrites the old boundaries in memory.
+
+    \item \textbf{Bounds checking}: Each collar has the ability to determine it's location and check whether or not it is with the grazing bounds through the use of an algorithm. This algorithm determines whether or not a GPS location is constrained by an area defined by a various number of coordinates. This provides the collar with the functionality to divert animals away from boundaries once the stimulus has been decided on and implemented. That is, currently the collar only knows when it is no longer in bounds but does not presently do anything about it. However, it is trivial to do something with this information once stimulus hardware has been implemented. 
+
+    \item \textbf{Observing end-node movement history}: The Android application has the ability to select one specific collar and observe the history of this collar. The movement of this collar is then displayed onto the interactive map with lines, and the rancher has the ability to see exactly where this animal has been over a certain time period. All of this information is sent to the Android application from the server, and the server gathers this history from the database. As each communication from the end-devices are saved to the database, it is trivial to go through all history for one specific collar.
+\end{itemize}
+
+\subsection*{Next Steps}
+To pick the project up, we recommend that different hardware be used for the collar devices. We have run
+into some serious limitations while using the LoRa-enabled ATMega controllers; the combination of LoRa,
+GPS, and Protobuf firmware was too large to fit in device memory. This led us to develop our own, stripped
+down versions of a lot of the software. Yet even with this, the firmware on the collar ends up running
+in a very constrained environment, and small changes that increase stack usage even by a small amount
+can lead to crashes.
+
+At present, the collar is capable of sending its position, retrieving valid grazing areas, and verifying
+that it is in a valid position. The next step on the collar side, then (after the hardware changes suggested
+above) would be to add to the collar a physical indication of whether or not it is in a valid grazing
+boundary (see the Design Document below for an idea of what that is). This physical indication can be
+an LED light, but the final goal would be to have that indication be a buzzer or an electric shock.
+
+The gateway software is capable of receiving and configuring a single collar device (See Appendix 4
+for an explanation of why only a single device is currently supported). The next step for the 
+gateway software, then, is to add support for multiple collar devices. Additionally, the gateway
+software currently uses the Things Network to decode and process LoRaWAN packets. This is less
+than ideal since it requires a connection to the Internet (rather than allowing the system
+to work on a LAN), and because it uses a third-party service to process animal data. To avoid
+this, the best course of action would be to use a local LoRaWAN implementation on the gateway.
+At the time of writing such software is not easily available, and was deemed too difficult to
+create. Finally, we recommend that a mechanism be added to the gateway software to verify
+that a collar has received an updated grazing boundary.
+
+The Android application is, in our view, the lowest priority at present. It is capable
+of authenticating and working with the API server, viewing animal locations,
+and of modifying collar grazing boundaries. Next steps could include the display of additional
+statistics (this would also require changes to the API server).
+
+Please refer to Appendix 4 for a description of all things that need to be done.
+
+\pagebreak
+\section*{Project Introduction}
 The Fenceless Grazing System was designed and implemented as requested by OSU professor Bechir Hamdaoui,
 who also served as the project's client.
 Prof. Hamdaoui believes that there is an emerging market for smart collar systems, and wanted to explore
@@ -113,36 +162,14 @@ became more difficult. While previously, hardware components were distributed am
 did meaningfully affect the project deliverables, as the team was able to set up a system for remotely
 modifying the physical components' firmware.
 
-\subsection*{Next Steps}
-To pick the project up, we recommend that different hardware be used for the collar devices. We have run
-into some serious limitations while using the LoRa-enabled ATMega controllers; the combination of LoRa,
-GPS, and Protobuf firmware was too large to fit in device memory. This led us to develop our own, stripped
-down versions of a lot of the software. Yet even with this, the firmware on the collar ends up running
-in a very constrained environment, and small changes that increase stack usage even by a small amount
-can lead to crashes.
+For information on how to pick up the project, see the \emph{Next Steps} section of the \emph{Foreword}, and
+Appendix 4.
 
-At present, the collar is capable of sending its position, retrieving valid grazing areas, and verifying
-that it is in a valid position. The next step on the collar side, then (after the hardware changes suggested
-above) would be to add to the collar a physical indication of whether or not it is in a valid grazing
-boundary (see the Design Document below for an idea of what that is). This physical indication can be
-an LED light, but the final goal would be to have that indication be a buzzer or an electric shock.
-
-The gateway software is capable of receiving and configuring a single collar device (See Appendix 4
-for an explanation of why only a single device is currently supported). The next step for the 
-gateway software, then, is to add support for multiple collar devices. Additionally, the gateway
-software currently uses the Things Network to decode and process LoRaWAN packets. This is less
-than ideal since it requires a connection to the Internet (rather than allowing the system
-to work on a LAN), and because it uses a third-party service to process animal data. To avoid
-this, the best course of action would be to use a local LoRaWAN implementation on the gateway.
-At the time of writing such software is not easily available, and was deemed too difficult to
-create. Finally, we recommend that a mechanism be added to the gateway software to verify
-that a collar has received an updated grazing boundary.
-
-The Android application is, in our view, the lowest priority at present. It is capable
-of authenticating and working with the API server, viewing animal locations,
-and of modifying collar grazing boundaries. Next steps could include the display of additional
-statistics (this would also require changes to the API server).
-
-Please refer to Appendix 4 for a description of all things that need to be done.
+\subsection*{A Note on Tables of Contents}
+A large portion of this document is generated from existing files relating to this project, such as the design document,
+the various tech reviews, and the weekly blog posts. Many of these have their own tables of contents. These
+tables refer to the page number within overarching section: if the design document begins on page 10, and its table
+of contents says that a section is on page 3, this refers to the third page from the beginning of the section, which
+would be the 12th page in the document overall.
 
 \end{document}

readme.tex

@@ -34,8 +34,11 @@ All of these components work together to provide the required functionality of t
 \begin{figure}[h]
     \centering
     \includegraphics[width=0.8\linewidth]{stack.png}
+    \caption{Project Structure Diagram}
 \end{figure}
 
+The following sections are generated from the README files found in the repositories for this project. In case there are some visual bugs (which is not uncommon with LaTeX generated from Markdown), please refer to the original markdown files found in the project archive.
+
 \pagebreak
 \input{readme-app.tex}
 
@@ -47,8 +50,6 @@ All of these components work together to provide the required functionality of t
 
 \pagebreak
 \input{readme-gateway.tex}
-
-\pagebreak
 \input{readme-collar.tex}
 
 \end{document}

toc.rb

@@ -0,0 +1,50 @@
+def all_pages(name, pdf)
+  return [:pdf, name, pdf]
+end
+
+def all_no_entry(name, pdf)
+  return [:pdf_no_entry, name, pdf]
+end
+
+def section_offset(name, page)
+  return [:section, name, page]
+end
+
+pdf_structure = [
+  all_no_entry("Introduction", "intro.pdf"),
+  all_pages("Requirements Document", "requirements.pdf"),
+  all_pages("Design Document", "design-doc.pdf"),
+  all_pages("Ryan Alder's Tech Review", "binary/techreview-ryan.pdf"),
+  all_pages("Danila Fedorin's Tech Review", "techreview-daniel.pdf"),
+  all_pages("Matthew Sessions' Tech Review", "binary/techreview-matt.pdf"),
+  all_pages("Ryan Alder's Blog Posts", "binary/blog-ryan.pdf"),
+  all_pages("Danila Fedorin's Blog Posts", "blog-daniel.pdf"),
+  all_pages("Matthew Sessions' Blog Posts", "binary/blog-matt.pdf"),
+  all_pages("Expo Poster", "binary/poster.pdf"),
+  all_pages("Project Documentation", "readme.pdf"),
+  all_pages("Learning Resources", "resources.pdf"),
+  all_pages("Conclusions and Reflections", "reflection.pdf"),
+  all_pages("Appendix 1: Essential Code Listings", "listings.pdf"),
+  all_pages("Appendix 2: Project Images", "images.pdf"),
+  all_pages("Appendix 2: Code Review Changes", "review.pdf"),
+  all_pages("Appendix 4: Remaining Work", "todo.pdf")
+]
+
+toc = File.open("generated.toc", "w")
+
+page_tally = 1
+section_counter = 1
+pdf_structure.each do |entry|
+  next unless entry[0] == :pdf or entry[0] == :pdf_no_entry
+  type, name, pdf = entry
+  page_count = `pdftk #{pdf} dump_data | grep NumberOfPages`.split(":")[1].to_i
+  output = "\\contentsline {section}{\\numberline {#{section_counter}}#{name}}{#{page_tally}}%"
+
+  if type == :pdf
+    toc.puts output
+    puts output
+  end
+
+  section_counter += 1
+  page_tally += page_count
+end