doc/location/README.org

   1 * Location Logging
   2 This document was created by Steven Baltakatei Sandoval on
   3 <2020-06-29 Mon 12:14> under a [[https://creativecommons.org/licenses/by-sa/4.0/][Creative Commons BY-SA 4.0 license]]. It
   4 was updated by Steven Baltakatei Sandoval on <2020-06-29 Mon 22:06>.
   5 ** Narrative
   6 Ninfacyzga-01 records (logs) its position in time and space using a
   7 [[https://en.wikipedia.org/wiki/Satellite_navigation_device][GPS receiver]]. The NMEA location data produced by the receiver is
   8 converted into the more commonly used GPS data storage formats of GPX
   9 and KML. All three types of data are then compressed and encrypted
  10 against a set of public keys. The encrypted data is then written to
  11 disk. Data produced by the receiver is segmented into 60-second chunks
  12 before being processed and written to disk.
  13 ** Description
  14 *** Hardware
  15 **** Raspberry Pi Zero W
  16 See the [[https://www.raspberrypi.org/pi-zero-w/][OEM]] webpage for this product.
  17 **** PiZ UpTime 2.0
  18 See the [[https://alchemy-power.com/piz-uptime-2-0/][OEM]] webpage for this product.
  19 *** Software
  20 ~bkgpslog~ : The bash script that performs the location data
  21 collection and processing. Is an executable file contained within this
  22 repository at ~exec/bkgpslog~. It should be copied to
  23 ~$HOME/.local/bin~.
  24
  25 ~gpsd~ : A background daemon app capable of interfacing with the
  26 Ozzmaker BerryGPS-IMU's GPS submodule. Installed and initialized by
  27 ~apt~.
  28
  29 ~gpspipe~ : A command line app that polls ~gpsd~ and produces a stream
  30 stdout consisting of GPS data lines in NMEA format. Installed via
  31 ~apt~.
  32
  33 ~gpsbabel~ : A command line app that converts GPS data from one format
  34 into another. ~bkgpslog~ uses it to convert NMEA data into GPX and
  35 KML. Installed via ~apt~.
  36
  37 ~gzip~ : A simple command line app that compresses stdin into a
  38 smaller stdout stream.
  39
  40 ~age~ : A simple command line app that encrypts stdin against public
  41 keys specified in its options. Produces encrypted stdout. Is an
  42 executable file contained within this repository at ~exec/age~. It
  43 should be copied to ~$HOME/.local/bin~.
  44
  45 **** Narrative
  46 ~bkgpslog~ populates a 60-second buffer with NMEA data from ~gpsd~ via
  47 ~gpspipe~. This buffer is used by ~gpsbabel~ to produce GPX and KML
  48 versions of the buffer. All 3 buffers are then comprssed with ~gzip~,
  49 encrypted with ~age~, and then written to disk.
  50
  51 *** Output
  52 **** File Formats
  53 ***** NMEA
  54 See the [[https://en.wikipedia.org/wiki/NMEA_0183][Wikipedia page]] for this.
  55 ***** GPX
  56 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.
  57 ***** KML
  58 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.
  59 **** Encryption Method
  60 Files produced by the bkgpslog script are encrypted against a set of
  61 public keys using [[https://github.com/FiloSottile/age][~age~]], a simple command line encryption tool
  62 selected over ~gpg~ because of ~age~'s deliberate lack of
  63 configurability.
  64
  65 The public keys are bech32 strings supplied as options to bkgpslog
  66 when called. The secret key should *NOT* be stored in Ninfacyzga-01.
  67
  68 If a key pair was generated using ~age-keygen~, then it is an [[https://en.wikipedia.org/wiki/Curve25519][~X25519~]]
  69 key pair. See the [[https://age-encryption.org/v1][~age~ Version 1 specification]].
  70
  71 An ~ssh-rsa~ or ~ssh-ed25519~ SSH public key string may be used instead of
  72 the bech32 public key string produced by ~age-keygen~ for convenience.
  73
  74 Help information for ~age~ is available by running ~$ age --help~.
  75 ***** Encryption
  76 Files may be encrypted to several recipients using a command similar to:
  77 #+BEGIN_EXAMPLE
  78 timeout "60s" gpspipe -r | gpsbabel -i nmea -f - -o gpx -F | age \
  79 -r age1kza7pfshy7xwygf9349zgmk7x53mquvedgw9r98qwyyqhssh830qqjzlsw \
  80 -r age1ce3pvzrqfcn2pc6zqzglc8ac8yjk3fzukpy08cesqjjwns53xywqmaq7xw \
  81 -r age1pu5usxm743sx7rf22985xv2f4s0luzv6r6yx4fa7p8c2zyvp9fvqus2xr5 \
  82 > location.gpx.age
  83 #+END_EXAMPLE
  84
  85 In this example, the strings beginning with ~age1...~ are
  86 bech32-formatted public key strings.
  87
  88
  89 ***** Decryption
  90 Files may be decrypted using a command similar to:
  91
  92 #+BEGIN_EXAMPLE
  93 cat location.gpx.age | age -d -i key.txt > location.gpx
  94 #+END_EXAMPLE
  95
  96 The version of ~age~ used to perform the encryption
  97 ** Operating Procedures
  98 *** Initial Startup
  99 See OEM (Ozzmaker) [[https://ozzmaker.com/berrygps-berrygps-imu-quick-start-guide/][quickstart guide for the BerryGPS-IMU]].
 100
 101 **** Physical Setup
 102
 103 BerryGPS-IMU must be electrically connected to the correct pins on the
 104 GPIO header of a Raspberry Pi Zero W.
 105
 106 *Optional*: stack together with PiZ Uptime 2.0 module. No GPIO pins
 107 conflict so a simple stacking and soldering with long header pins is
 108 possible.
 109
 110 **** Software Setup
 111
 112 ***** Install Executables
 113
 114 Install Raspbian 10 Buster onto an SD card image. See the Raspberry Pi
 115 Foundation [[https://www.raspberrypi.org/documentation/installation/installing-images/README.md][installation instructions]]. Configure WiFi to permit log
 116 file transfer. Configure SSH to permit remote administration via the
 117 command line interface.
 118
 119 Make sure to install the ~unattended-upgrades~ package to make sure
 120 the latest security patches for packages are installed. See [[https://linux-audit.com/using-unattended-upgrades-on-debian-and-ubuntu/][this page]]
 121 for a description of how ~unattended-upgrades~ works.
 122
 123 Install ~gpsd~, ~gpspipe~, ~git~, and this repository for location
 124 logging capability.
 125
 126 Install ~syncthing~ for log file transfer capability.
 127
 128 Place ~age~ binary (the one compiled for ARM CPU architecture for
 129 Linux) in ~$HOME/.local/bin~.
 130
 131 ***** Automatic Start Configuration
 132
 133 Edit the user cron job list with ~$ crontab -e~ to add the following
 134 lines:
 135
 136 #+BEGIN_EXAMPLE
 137 0 * * * * /bin/bash ~/bkgpslog --output ~/dir
 138
 139 @reboot /bin/bash ~/bkgpslog --output ~/dir
 140 #+END_EXAMPLE
 141
 142 The first line will run ~bkgpslog~ at the start of every hour and save
 143 output files to the ~dir~ directory in your home folder.
 144
 145 The second line will run ~bkgpslog~ when the system starts up.
 146
 147 ~/bin/bash~ tells ~cron~ to run ~bkgpslog~ with Bash.
 148
 149 If encryption and compression are required, then the appropriate
 150 options must be added. The lines that must be added via ~$ crontab -e~
 151 may resemble:
 152
 153 #+BEGIN_EXAMPLE
 154 0 * * * * /bin/bash ~/bkgpslog -c -e -r age1z2...qkv6p -o ~/dir
 155
 156 @reboot /bin/bash ~/bkgpslog -c -e -r age1z2...qkv6p -o ~/dir
 157 #+END_EXAMPLE
 158
 159 The ~age1z2...qkv6p~ is an ~age~ public key string. See the Encryption
 160 Methods section for an explanation.
 161
 162 The options are:
 163
 164 : -c : tells bkgpslog to compress output
 165 : -e : tells bkgpslog log to encrypt output
 166 : -r : tells bkgpslog to interpret the next argument as a pubkey string
 167 : -o : tells bkgpslog to write output files to the directory represented
 168 :        by the next argument
 169
 170 ***** Log Transfer Configuration
 171 Log files may be shared to other machines via ~syncthing~. See [[https://docs.syncthing.net/][this]]
 172 manual for how to set up a shared folder and add Ninfacyzga-01 as a
 173 device. Syncthing's directory synchronization capability allows a
 174 remote machine to delete files from Ninfacyzga-01 by deleting from the
 175 shared folder that they both share.
 176
 177 When log files are removed from Ninfacyzga-01 is not within the scope
 178 of this document.
 179
 180 ***** Key Generation
 181 An ~age~ encryption key may be generated like so:
 182 #+BEGIN_EXAMPLE
 183 $ umask          # Gets current umask
 184 0022             # Note: This is the default umask for Raspbian 10
 185 $ umask 066      # Sets umask so key.txt will have no permissions except for owner (you)
 186 $ umask          # Confirm umask set to 066
 187 0066
 188 $ age-keygen > key.txt
 189 Public key: age1pu5usxm743sx7rf22985xv2f4s0luzv6r6yx4fa7p8c2zyvp9fvqus2xr5
 190 $ ls -al key.txt
 191 -rw------- 1 baltakatei baltakatei 184 Jun 29 18:28 key.txt
 192 $ umask 0022     # Return umask to default value
 193 $ umask
 194 0022
 195 #+END_EXAMPLE
 196
 197 The resulting public/private keypair data looks like:
 198 #+BEGIN_EXAMPLE
 199 $ cat key.txt
 200 # created: 2020-06-29T18:01:56Z
 201 # public key: age1pu5usxm743sx7rf22985xv2f4s0luzv6r6yx4fa7p8c2zyvp9fvqus2xr5
 202 AGE-SECRET-KEY-1NEUU5U2XGZGL9UYWNPU5DL99TGJJHFSN4F2E2WCCSDJJ6L5ZMLESNTVTU0
 203 #+END_EXAMPLE
 204
 205 The file ~key.txt~ is not password-protected by default and should be
 206 secured like an SSH public key should. The ~$ umask 066~ command run
 207 before the ~$ age-keygen > key.txt~ command ensures ~key.txt~ will not
 208 be readable, writeable, or executable to anyone except the owner
 209 (you).
 210
 211 *** Normal Startup
 212 Turn on Ninfacyzga-01 by supplying 5VDC power to the Raspberry Pi. No
 213 further interaction should be required.
 214 *** Normal Operation
 215 No interaction beyond continually supplying approximately 100mA of
 216 5VDC power and occasionally removing log files to conserve disk space
 217 is required.
 218 **** Log Transfer
 219 Log files may be transferred by use of ~syncthing~ shared folders.
 220 **** Automatic Updates
 221 The ~automatic-upgrades~ package, if installed, should automatically
 222 install security patches to packages installed via ~apt~.
 223 *** Normal Shutdown
 224 The system may be shutdown via SSH by running:
 225
 226 : $ sudo shutdown -r 0
 227
 228 *** Unscheduled Shutdown
 229 Ninfacyzga-01 as described and setup should tolerate unscheduled power
 230 loss. Log files being written every 60 seconds means, at most, 60
 231 seconds worth of location data may be lost.
 232 *** End of Life Disposal
 233 LiPo batteries used by the PiZ Uptime 2.0 module should be disposed of
 234 properly with their potential ignitability in mind, especially if they
 235 are not fully discharged.
 236
 237 Consult your local municipality for its "E-Waste Disposal" (or
 238 equivalent) policy. Metals used in the Raspberry Pi and related
 239 components may be recycled.
 240
 241 Take extra precuation if lead solder was used in assembling the
 242 electronics. Consumer electronics in early 21st century should use
 243 lead-free solder.
 244