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