doc/location/README.org

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