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 16:05>.
   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.
  57 ***** KML
  58 See the [[https://en.wikipedia.org/wiki/Keyhole_Markup_Language][Wikipedia page]] for this.
  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]]. The public keys are bech32 strings supplied as
  62 options to bkgpslog when called.
  63 ** Operating Procedures
  64 *** Initial Startup
  65 *** Normal Startup
  66 *** Normal Shutdown
  67 *** Unscheduled Shutdown
  68 *** End of Life Disposal
  69