debug(bklog):Fix SECONDS advancing

[EVA-2020-02.git] / doc / location / README.org

diff --git a/doc/location/README.org b/doc/location/README.org
index 92e73b7958d718c56dc7c2a2da832642a25706de..1ffdccd5175273c2f554b4ef8e2261723bc28472 100644 (file)
--- a/doc/location/README.org
+++ b/doc/location/README.org
@@ -1,7 +1,10 @@
 * Location Logging
 This document was created by Steven Baltakatei Sandoval on
 * Location Logging
 This document was created by Steven Baltakatei Sandoval on

-<2020-06-29 Mon 12:14> under a [[https://creativecommons.org/licenses/by-sa/4.0/][Creative Commons BY-SA 4.0 license]]. It
-was updated by Steven Baltakatei Sandoval on <2020-06-29 Mon 18:39>.
+~2020-06-29T12:14Z~ under a [[https://creativecommons.org/licenses/by-sa/4.0/][Creative Commons BY-SA 4.0 license]]. It
+was updated by Steven Baltakatei Sandoval on ~2020-07-12T21:04Z~
+#+TITLE: Ninfacyzga-01 Manual
+#+AUTHOR: Steven Baltakatei Sandoval
+#+EMAIL: baltakatei@gmail.com

 ** Narrative
 Ninfacyzga-01 records (logs) its position in time and space using a
 [[https://en.wikipedia.org/wiki/Satellite_navigation_device][GPS receiver]]. The NMEA location data produced by the receiver is
 ** Narrative
 Ninfacyzga-01 records (logs) its position in time and space using a
 [[https://en.wikipedia.org/wiki/Satellite_navigation_device][GPS receiver]]. The NMEA location data produced by the receiver is


@@ -17,10 +20,13 @@ See the [[https://www.raspberrypi.org/pi-zero-w/][OEM]] webpage for this product
 **** PiZ UpTime 2.0
 See the [[https://alchemy-power.com/piz-uptime-2-0/][OEM]] webpage for this product.
 *** Software
 **** PiZ UpTime 2.0
 See the [[https://alchemy-power.com/piz-uptime-2-0/][OEM]] webpage for this product.
 *** Software

-~bkgpslog~ : The bash script that performs the location data
-collection and processing. Is an executable file contained within this
-repository at ~exec/bkgpslog~. It should be copied to
-~$HOME/.local/bin~.
+~bklog~ : A bash script that saves its stdin stream to a tar file. The
+file may be compressed by ~gzip~ and encrypted by ~age~. It is an
+executable file contained within this repository at ~exec/bklog~. It
+should be copied to ~$HOME/.local/bin~.
+
+~bkgpslog~ : A legacy bash script similar to ~bklog~ but narrower in
+scope in that it only records output from ~gpspipe~.

 
 ~gpsd~ : A background daemon app capable of interfacing with the
 Ozzmaker BerryGPS-IMU's GPS submodule. Installed and initialized by
 
 ~gpsd~ : A background daemon app capable of interfacing with the
 Ozzmaker BerryGPS-IMU's GPS submodule. Installed and initialized by


@@ -31,7 +37,7 @@ stdout consisting of GPS data lines in NMEA format. Installed via
 ~apt~.
 
 ~gpsbabel~ : A command line app that converts GPS data from one format
 ~apt~.
 
 ~gpsbabel~ : A command line app that converts GPS data from one format

-into another. ~bkgpslog~ uses it to convert NMEA data into GPX and
+into another. ~bklog~ may be used to convert NMEA data into GPX and

 KML. Installed via ~apt~.
 
 ~gzip~ : A simple command line app that compresses stdin into a
 KML. Installed via ~apt~.
 
 ~gzip~ : A simple command line app that compresses stdin into a


@@ -43,19 +49,30 @@ executable file contained within this repository at ~exec/age~. It
 should be copied to ~$HOME/.local/bin~.
 
 **** Narrative
 should be copied to ~$HOME/.local/bin~.
 
 **** Narrative

-~bkgpslog~ populates a 60-second buffer with NMEA data from ~gpsd~ via
-~gpspipe~. This buffer is used by ~gpsbabel~ to produce GPX and KML
-versions of the buffer. All 3 buffers are then comprssed with ~gzip~,
-encrypted with ~age~, and then written to disk.
+~bklog~ may be used to log location data by receiving stdout produced
+by ~gpspipe~. ~bklog~ contains options that allow file writes to be
+performed at adjustable time intervals (default: 300 seconds),
+compressed (with ~gzip~), and encrypted (with ~age~). Files are
+written in the form of appendages to a ~tar~ archive saved to a
+specified location. The NMEA data produced by ~gpspipe~ may be
+processed via a ~gpsbabel~ command string specified as an option to
+~bklog~, assuming ~gpsbabel~ is installed.

 
 *** Output
 
 *** Output

+
+Several output file formats have been tested with ~bklog~.
+

 **** File Formats
 ***** NMEA
 **** File Formats
 ***** NMEA

-See the [[https://en.wikipedia.org/wiki/NMEA_0183][Wikipedia page]] for this.
+See the [[https://en.wikipedia.org/wiki/NMEA_0183][Wikipedia page]] for this. This file format is the default
+output of the ~gpspipe -r~ command.

 ***** GPX
 ***** GPX

-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.
+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
+may be converted to this format using ~gpsbabel~.

 ***** KML
 ***** KML

-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.
+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
+may be converted to this format using ~gpsbabel~.
+

 **** Encryption Method
 Files produced by the bkgpslog script are encrypted against a set of
 public keys using [[https://github.com/FiloSottile/age][~age~]], a simple command line encryption tool
 **** Encryption Method
 Files produced by the bkgpslog script are encrypted against a set of
 public keys using [[https://github.com/FiloSottile/age][~age~]], a simple command line encryption tool


@@ -72,21 +89,48 @@ An ~ssh-rsa~ or ~ssh-ed25519~ SSH public key string may be used instead of
 the bech32 public key string produced by ~age-keygen~ for convenience.
 
 Help information for ~age~ is available by running ~$ age --help~.
 the bech32 public key string produced by ~age-keygen~ for convenience.
 
 Help information for ~age~ is available by running ~$ age --help~.

-***** Encryption
-Files may be encrypted to several recipients using a command similar to:
+***** Encryption Commands
+****** Encryption through ~age~
+In order to illustrate how ~bklog~ encrypts files, below is an example
+command illustrating how ~age~ may be used to encrypt a file.
+

 #+BEGIN_EXAMPLE
 #+BEGIN_EXAMPLE

-timeout "60s" gpspipe -r | gpsbabel -i nmea -f - -o gpx -F | age \
+$ echo "asdf" | age -r \
+age1kza7pfshy7xwygf9349zgmk7x53mquvedgw9r98qwyyqhssh830qqjzlsw \
+> "$HOME/secret_file"
+#+END_EXAMPLE
+
+The resulting ~secret-file~ is a binary blob with a plaintext header
+indicating how the blob was encrypted (which version of age was used,
+which public key was used).
+
+****** Encryption through ~bklog~
+~bklog~ may instructed to encrypt files via the ~-e~ and ~-r [pubkey
+string]~ options. An example is shown below:
+
+#+BEGIN_EXAMPLE
+$ gpspipe -r | bklog -e \

 -r age1kza7pfshy7xwygf9349zgmk7x53mquvedgw9r98qwyyqhssh830qqjzlsw \
 -r age1ce3pvzrqfcn2pc6zqzglc8ac8yjk3fzukpy08cesqjjwns53xywqmaq7xw \
 -r age1pu5usxm743sx7rf22985xv2f4s0luzv6r6yx4fa7p8c2zyvp9fvqus2xr5 \
 -r age1kza7pfshy7xwygf9349zgmk7x53mquvedgw9r98qwyyqhssh830qqjzlsw \
 -r age1ce3pvzrqfcn2pc6zqzglc8ac8yjk3fzukpy08cesqjjwns53xywqmaq7xw \
 -r age1pu5usxm743sx7rf22985xv2f4s0luzv6r6yx4fa7p8c2zyvp9fvqus2xr5 \

-> location.gpx.age
+-o "$HOME/Location"

 #+END_EXAMPLE
 
 #+END_EXAMPLE
 

+~bklog~ may be instructed via the ~-e~ and ~-R~ options to watch a
+directory in order to locate public key strings in its files. ~bklog~
+reads the first line of each file and interprets it as a public key
+string.
+

 In this example, the strings beginning with ~age1...~ are
 In this example, the strings beginning with ~age1...~ are

-bech32-formatted public key strings. 
+bech32-formatted public key strings. Please see the [[*Key Generation][Key Generation]]
+section for an explanation.
+
+Since ~age~ also accepts ~ssh~ public key strings, these may also be
+used if they are of the following form (no comment).

 
 

+: ssh-rsa AAAAB3NzaC1yc2EAAAADAQABA…AACAQDLnJbPs7CjwPT+OxXd

 
 

-***** Decryption
+***** Decryption Commands

 Files may be decrypted using a command similar to:
 
 #+BEGIN_EXAMPLE
 Files may be decrypted using a command similar to:
 
 #+BEGIN_EXAMPLE


@@ -94,6 +138,7 @@ cat location.gpx.age | age -d -i key.txt > location.gpx
 #+END_EXAMPLE
 
 The version of ~age~ used to perform the encryption 
 #+END_EXAMPLE
 
 The version of ~age~ used to perform the encryption 

+

 ** Operating Procedures
 *** Initial Startup
 See OEM (Ozzmaker) [[https://ozzmaker.com/berrygps-berrygps-imu-quick-start-guide/][quickstart guide for the BerryGPS-IMU]].
 ** Operating Procedures
 *** Initial Startup
 See OEM (Ozzmaker) [[https://ozzmaker.com/berrygps-berrygps-imu-quick-start-guide/][quickstart guide for the BerryGPS-IMU]].


@@ -108,7 +153,6 @@ conflict so a simple stacking and soldering with long header pins is
 possible.
 
 **** Software Setup
 possible.
 
 **** Software Setup

-

 ***** Install Executables
 
 Install Raspbian 10 Buster onto an SD card image. See the Raspberry Pi
 ***** Install Executables
 
 Install Raspbian 10 Buster onto an SD card image. See the Raspberry Pi


@@ -128,20 +172,109 @@ Install ~syncthing~ for log file transfer capability.
 Place ~age~ binary (the one compiled for ARM CPU architecture for
 Linux) in ~$HOME/.local/bin~.
 
 Place ~age~ binary (the one compiled for ARM CPU architecture for
 Linux) in ~$HOME/.local/bin~.
 

-***** Automatic Start Configuration
+***** Disable Swap File
+Since standard Raspbian 10 (Buster) install involves copying
+unencrypted file system image to SD card which is mounted by the
+Raspberry Pi, system memory may be written to disk in the form of a
+Swap file as described [[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 written to disk, swap file functionality
+must be disabled[fn:ideaheap_20130731_disableswap].
+
+Raspbian 10 uses dphys-swapfile to manage a swap file. It may be
+disabled persistently[fn:rpf_20190702_disableswappersist] by running
+the following command:

 
 

-Edit the user cron job list with ~$ crontab -e~ to add the following
-lines:
+: sudo systemctl disable dphys-swapfile.service
+
+To view the status of the swap file in Raspbian 10, run ~free -m~:
+
+#+BEGIN_EXAMPLE
+pi@ninfacyzga-01:~$ free -m
+          total    used    free  shared  buff/cache   available
+Mem:        432      86      36      21         309         268
+Swap:        99       0      99
+#+END_EXAMPLE
+
+After disabling the swap file and rebooting:

 
 #+BEGIN_EXAMPLE
 
 #+BEGIN_EXAMPLE

-0 * * * * /bin/bash /path/to/bkgpslog --output $HOME/Sync/example_dir
+pi@ninfacyzga-01:~$ free -m
+          total    used    free  shared  buff/cache   available
+Mem:        432      89     214       3         128         289
+Swap:         0       0       0
+#+END_EXAMPLE
+
+[fn:ideaheap_20130731_disableswap] Explanation:
+https://ideaheap.com/2013/07/stopping-sd-card-corruption-on-a-raspberry-pi/
+
+[fn:rpf_20190702_disableswappersist] Persistant disabling of swap in
+Raspbian 10 Buster:
+https://www.raspberrypi.org/forums/viewtopic.php?p=1490692&sid=5c596a124b7805d6b10dab8d3d7caf16#p1490692

 
 

-@reboot /bin/bash /path/to/bkgpslog --output $HOME/Sync/example_dir
+***** Automatic Start Configuration
+
+It is recommended to create a daily ~cron~ job that executes a bash
+script that starts ~bklog~ jobs to record location along with other
+types of data recording. An example of such a script is below:
+
+#+BEGIN_EXAMPLE
+#!/bin/bash
+
+# Log location
+gpspipe -r | /bin/bash "$HOME/.local/bin/bklog" -c -e -z "UTC" -t "/dev/shm" \
+          -r age1kza7pfshy7xwygf9349zgmk7x53mquvedgw9r98qwyyqhssh830qqjzlsw \
+          -r age1ce3pvzrqfcn2pc6zqzglc8ac8yjk3fzukpy08cesqjjwns53xywqmaq7xw \
+          -R "$HOME/.config/bklog/recipients" -w ".nmea" -b "300" -B "day" \
+         -o "$HOME/Sync/Evanescent_Location" -l "location" \
+          -p "gpsbabel -i nmea -f - -o gpx -F - " ".gpx" \
+          -p "gpsbabel -i nmea -f - -o kml -F - " ".kml" &
+# Log pressure
+python ~/.local/bin/bmp388.py | /bin/bash "$HOME/git-OC/ninfacyzga-01/exec/bklog" \
+          -c -e -z "UTC" -t "/dev/shm" \
+          -r age1kza7pfshy7xwygf9349zgmk7x53mquvedgw9r98qwyyqhssh830qqjzlsw \
+          -r age1ce3pvzrqfcn2pc6zqzglc8ac8yjk3fzukpy08cesqjjwns53xywqmaq7xw \
+          -R "$HOME/.config/bklog/recipients" -w ".txt" -b "300" -B "day" \
+         -o "$HOME/Sync/Evanescent_Location" -l "pressure" &

 #+END_EXAMPLE
 
 #+END_EXAMPLE
 

-The first line will run ~bkgpslog~ at the start of every hour.
+This script, if it were saved at
+~"$HOME/.local/bin/cron/dailylog.sh"~ would then be added as a
+line in the ~crontab~ file as shown below:

 
 

-The second line will run ~bkgpslog~ when the system starts up.
+#+BEGIN_EXAMPLE
+$ crontab -e
+0 0 * * * /bin/bash ~/.local/bin/cron/dailylog.sh
+@reboot /bin/bash ~/.local/bin/cron/dailylog.sh
+#+END_EXAMPLE
+
+In the example script, the options are:
+
+: -c : tells bklog to compress output
+: -e : tells bklog log to encrypt output
+: -r : tells bklog to interpret the next argument as a pubkey string
+: -R : tells bklog to interpret the next argument as a directory
+:        where public keys may be found (first line of each file is
+:        read).
+: -o : tells bklog to write output files to the directory represented
+: -t : tells bklog to interpret the next argument as a directory
+:        for storing temporary files
+:        by the next argument
+: -p : tells bklog a command string through which output is piped
+:        before being compressed and encrypted. Also expected is a
+:        file extension to be appended before the compression and
+:        encryption file extensions.
+: -w : tells bklog to save the unprocessed stdin with a specified
+:        file extension (instead of the default '.stdin').
+: -b : tells bklog how long each buffer round (time between file
+:        writes) lasts in seconds.
+: -B : specifies the time-to-live for the bklog script. A valid value may
+:        one of the time elements such as "day" or "hour".
+: -l : specfies a custom string to be used in output file names to
+:        help differentiate tar files produced via bklog from different
+:        sources of data.
+: -z : specifies a time zone to be used to determine the script time-to-live.
+:        By default, bklog uses whatever time is specified by the TZ
+:        environment variable.

 
 ***** Log Transfer Configuration
 Log files may be shared to other machines via ~syncthing~. See [[https://docs.syncthing.net/][this]]
 
 ***** Log Transfer Configuration
 Log files may be shared to other machines via ~syncthing~. See [[https://docs.syncthing.net/][this]]


@@ -158,7 +291,7 @@ An ~age~ encryption key may be generated like so:
 #+BEGIN_EXAMPLE
 $ umask          # Gets current umask
 0022             # Note: This is the default umask for Raspbian 10
 #+BEGIN_EXAMPLE
 $ umask          # Gets current umask
 0022             # Note: This is the default umask for Raspbian 10

-$ umask 066      # Sets umask so key.txt will have no permissions except for owner (you)
+$ umask 066      # So key.txt will have no perms except for owner (you)

 $ umask          # Confirm umask set to 066
 0066
 $ age-keygen > key.txt
 $ umask          # Confirm umask set to 066
 0066
 $ age-keygen > key.txt


@@ -217,4 +350,3 @@ components may be recycled.
 Take extra precuation if lead solder was used in assembling the
 electronics. Consumer electronics in early 21st century should use
 lead-free solder.
 Take extra precuation if lead solder was used in assembling the
 electronics. Consumer electronics in early 21st century should use
 lead-free solder.

-