doc/location/README.org

   1 * Location Logging
   2 #+TITLE: Ninfacyzga-01 Manual
   3 #+AUTHOR: Steven Baltakatei Sandoval
   4 #+EMAIL: baltakatei@gmail.com
   5 ** About
   6 This document was created by Steven Baltakatei Sandoval on
   7 ~2020-06-29T12:14Z~ under a [[https://creativecommons.org/licenses/by-sa/4.0/][Creative Commons BY-SA 4.0 license]]. It
   8 was updated by Steven Baltakatei Sandoval on ~2020-10-08T18:03Z~
   9
  10 ** Narrative
  11 Ninfacyzga-01 records (logs) its position in time and space using a
  12 [[https://en.wikipedia.org/wiki/Satellite_navigation_device][GPS receiver]]. The NMEA location data produced by the receiver is
  13 converted into the more commonly used GPS data storage formats of GPX
  14 and KML. All three types of data are then compressed and encrypted
  15 against a set of public keys. The encrypted data is then written to
  16 disk. Data produced by the receiver is segmented into 60-second chunks
  17 before being processed and written to disk.
  18 ** Description
  19 *** Hardware
  20 **** Raspberry Pi Zero W
  21 See the [[https://www.raspberrypi.org/pi-zero-w/][OEM]] webpage for this product.
  22 **** PiZ UpTime 2.0
  23 See the [[https://alchemy-power.com/piz-uptime-2-0/][OEM]] webpage for this product.
  24 *** Software
  25 ~bklog~ : A bash script that saves its stdin stream to a tar file. The
  26 file may be compressed by ~gzip~ and encrypted by ~age~. It is an
  27 executable file contained within this repository at ~exec/bklog~. It
  28 should be copied to ~$HOME/.local/bin~.
  29
  30 ~bkgpslog~ : A legacy bash script similar to ~bklog~ but narrower in
  31 scope in that it only records output from ~gpspipe~.
  32
  33 ~gpsd~ : A background daemon app capable of interfacing with the
  34 Ozzmaker BerryGPS-IMU's GPS submodule. Installed and initialized by
  35 ~apt~.
  36
  37 ~gpspipe~ : A command line app that polls ~gpsd~ and produces a stream
  38 stdout consisting of GPS data lines in NMEA format. Installed via
  39 ~apt~.
  40
  41 ~gpsbabel~ : A command line app that converts GPS data from one format
  42 into another. ~bklog~ may be used to convert NMEA data into GPX and
  43 KML. Installed via ~apt~.
  44
  45 ~gzip~ : A simple command line app that compresses stdin into a
  46 smaller stdout stream.
  47
  48 ~age~ : A simple command line app that encrypts stdin against public
  49 keys specified in its options. Produces encrypted stdout. Is an
  50 executable file contained within this repository at ~exec/age~. It
  51 should be copied to ~$HOME/.local/bin~.
  52
  53 **** Narrative
  54 ~bklog~ may be used to log location data by receiving stdout produced
  55 by ~gpspipe~. ~bklog~ contains options that allow file writes to be
  56 performed at adjustable time intervals (default: 300 seconds),
  57 compressed (with ~gzip~), and encrypted (with ~age~). Files are
  58 written in the form of appendages to a ~tar~ archive saved to a
  59 specified location. The NMEA data produced by ~gpspipe~ may be
  60 processed via a ~gpsbabel~ command string specified as an option to
  61 ~bklog~, assuming ~gpsbabel~ is installed.
  62
  63 *** Output
  64
  65 Several output file formats have been tested with ~bklog~.
  66
  67 **** File Formats
  68 ***** NMEA
  69 ~NMEA~ is an acronym for National marine Electronics Association. The
  70 NMEA format described in this document follows the NMEA 0183
  71 standard. It is a newline-delimited streaming text format that encodes
  72 global positioning system (GPS) data such as WGS84 location, time and
  73 date information, satellite count, accuracy, and other
  74 information. Each line is an "NMEA sentence". Descriptions of various
  75 NMEA sentences can be found on [[http://aprs.gids.nl/nmea/][this]] webpage.
  76
  77 See the [[https://en.wikipedia.org/wiki/NMEA_0183][Wikipedia page for NMEA 0183]] for this. This file format is the
  78 default output of the ~gpspipe -r~ command.
  79 ***** GPX
  80 See the [[https://en.wikipedia.org/wiki/GPS_Exchange_Format][Wikipedia page]] for this. [[http://wiki.gis.com/wiki/index.php/WGS84][WGS84]] is the datum used. An NMEA file
  81 may be converted to this format using ~gpsbabel~.
  82 ***** KML
  83 See the [[https://en.wikipedia.org/wiki/Keyhole_Markup_Language][Wikipedia page]] for this. [[http://wiki.gis.com/wiki/index.php/WGS84][WGS84]] is the datum used. An NMEA file
  84 may be converted to this format using ~gpsbabel~.
  85
  86 **** Encryption Method
  87 See [[file:../setup/README.org][Main Setup]] procedures.
  88
  89 ** Operating Procedures
  90 *** Initial Startup
  91 See OEM (Ozzmaker) [[https://ozzmaker.com/berrygps-berrygps-imu-quick-start-guide/][quickstart guide for the BerryGPS-IMU]].
  92 **** Physical Setup
  93
  94 BerryGPS-IMU must be electrically connected to the correct pins on the
  95 GPIO header of a Raspberry Pi Zero W.
  96
  97 *Optional*: stack together with PiZ Uptime 2.0 module. No GPIO pins
  98 conflict so a simple stacking and soldering with long header pins is
  99 possible.
 100
 101 **** Software Setup
 102 ***** Install Executables
 103 Follow the [[file:../setup/README.org][Main Setup]] procedures to obtain required files from this
 104 repository.
 105
 106 Install ~gpsd~, ~gpsd-clients~.
 107
 108 : $ sudo apt install gpsd gpsd-clients
 109
 110 ***** Setup Serial for BerryGPS
 111 The Ozzmaker BerryGPS-IMU unit requires that the serial console be
 112 disabled and the serial port enabled. (see [[https://ozzmaker.com/berrygps-setup-guide-raspberry-pi/][ref]]).
 113
 114 : $ sudo raspi-config
 115
 116 Navigate to ~5 Interfacing Options~, then ~P6 Serial~.
 117
 118 When prompted "Would you like a login shell to be accessible over
 119 serial?", answer ~No~.
 120
 121 When prompted "Would you like the serial port hardware to be
 122 enabled?", answer ~Yes~.
 123
 124 ***** Configure ~gpsd~
 125 ~gpsd~ needs to know which serial port to look at for NMEA location
 126 data generated by the GPS unit. This can be done by modifying the
 127 ~gpsd~ configuration file at ~/etc/default/gpsd~.
 128
 129 : sudo nano /etc/default/gpsd
 130
 131 Change
 132
 133 : DEVICES=""
 134
 135 to
 136
 137 : DEVICES="/dev/serial0"
 138
 139 ***** Automatic Start Configuration
 140 It is recommended to create a daily ~cron~ job that executes a bash
 141 script that starts ~bklog~ jobs to record location along with other
 142 types of data recording. An example of such a script is below:
 143
 144 #+BEGIN_EXAMPLE
 145 #!/bin/bash
 146
 147 # Log location
 148 gpspipe -r | /bin/bash "$HOME/.local/bin/bklog" -c -e -z "UTC" -t "/dev/shm" \
 149           -r age1kza7pfshy7xwygf9349zgmk7x53mquvedgw9r98qwyyqhssh830qqjzlsw \
 150           -r age1ce3pvzrqfcn2pc6zqzglc8ac8yjk3fzukpy08cesqjjwns53xywqmaq7xw \
 151           -R "$HOME/.config/bklog/recipients" -w ".nmea" -b "300" -B "day" \
 152           -o "$HOME/Sync/Evanescent_Location" -l "location" \
 153           -p "gpsbabel -i nmea -f - -o gpx -F - " ".gpx" \
 154           -p "gpsbabel -i nmea -f - -o kml -F - " ".kml" &
 155 # Log pressure
 156 python ~/.local/bin/bmp388.py | /bin/bash "$HOME/git-OC/ninfacyzga-01/exec/bklog" \
 157           -c -e -z "UTC" -t "/dev/shm" \
 158           -r age1kza7pfshy7xwygf9349zgmk7x53mquvedgw9r98qwyyqhssh830qqjzlsw \
 159           -r age1ce3pvzrqfcn2pc6zqzglc8ac8yjk3fzukpy08cesqjjwns53xywqmaq7xw \
 160           -R "$HOME/.config/bklog/recipients" -w ".txt" -b "300" -B "day" \
 161           -o "$HOME/Sync/Evanescent_Location" -l "pressure" &
 162 #+END_EXAMPLE
 163
 164 This script, if it were saved at
 165 ~"$HOME/.local/bin/cron/dailylog.sh"~ would then be added as a
 166 line in the ~crontab~ file as shown below:
 167
 168 #+BEGIN_EXAMPLE
 169 $ crontab -e
 170 0 0 * * * /bin/bash ~/.local/bin/cron/dailylog.sh
 171 @reboot /bin/bash ~/.local/bin/cron/dailylog.sh
 172 #+END_EXAMPLE
 173
 174 In the example script, the options are:
 175
 176 : -c : tells bklog to compress output
 177 : -e : tells bklog log to encrypt output
 178 : -r : tells bklog to interpret the next argument as a pubkey string
 179 : -R : tells bklog to interpret the next argument as a directory
 180 :        where public keys may be found (first line of each file is
 181 :        read).
 182 : -o : tells bklog to write output files to the directory represented
 183 : -t : tells bklog to interpret the next argument as a directory
 184 :        for storing temporary files
 185 :        by the next argument
 186 : -p : tells bklog a command string through which output is piped
 187 :        before being compressed and encrypted. Also expected is a
 188 :        file extension to be appended before the compression and
 189 :        encryption file extensions.
 190 : -w : tells bklog to save the unprocessed stdin with a specified
 191 :        file extension (instead of the default '.stdin').
 192 : -b : tells bklog how long each buffer round (time between file
 193 :        writes) lasts in seconds.
 194 : -B : specifies the time-to-live for the bklog script. A valid value may
 195 :        one of the time elements such as "day" or "hour".
 196 : -l : specfies a custom string to be used in output file names to
 197 :        help differentiate tar files produced via bklog from different
 198 :        sources of data.
 199 : -z : specifies a time zone to be used to determine the script time-to-live.
 200 :        By default, bklog uses whatever time is specified by the TZ
 201 :        environment variable.
 202
 203 ***** Log Transfer Configuration
 204 See [[file:../setup/README.org][Main Setup]] procedures.
 205
 206 Log files may be shared to other machines via ~syncthing~. See [[https://docs.syncthing.net/][this]]
 207 manual for how to set up a shared folder and add Ninfacyzga-01 as a
 208 device. Syncthing's directory synchronization capability allows a
 209 remote machine to delete files from Ninfacyzga-01 by deleting from the
 210 shared folder that they both share.
 211
 212 When log files are removed from Ninfacyzga-01 is not within the scope
 213 of this document.
 214
 215 ***** Key Generation
 216 See [[file:../setup/README.org][Main Setup]] procedures.
 217
 218 *** Normal Startup
 219 Turn on Ninfacyzga-01 by supplying 5VDC power to the Raspberry Pi. No
 220 further interaction should be required.
 221 *** Normal Operation
 222 No interaction beyond continually supplying approximately 100mA of
 223 5VDC power and occasionally removing log files to conserve disk space
 224 is required.
 225 **** Log Transfer
 226 Log files may be transferred by use of ~syncthing~ shared folders.
 227 **** Automatic Updates
 228 The ~automatic-upgrades~ package, if installed, should automatically
 229 install security patches to packages installed via ~apt~.
 230 *** Normal Shutdown
 231 The system may be shutdown via SSH by running:
 232
 233 : $ sudo shutdown -r 0
 234
 235 *** Unscheduled Shutdown
 236 Ninfacyzga-01 as described and setup should tolerate unscheduled power
 237 loss. Log files being written every 60 seconds means, at most, 60
 238 seconds worth of location data may be lost.
 239 *** End of Life Disposal
 240 See [[file:../setup/README.org][Main Setup]] procedures.