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