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

* 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>.
** 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
converted into the more commonly used GPS data storage formats of GPX
and KML. All three types of data are then compressed and encrypted
against a set of public keys. The encrypted data is then written to
disk. Data produced by the receiver is segmented into 60-second chunks
before being processed and written to disk.
** Description
*** Hardware
**** Raspberry Pi Zero W
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
~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~.

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

~gpspipe~ : A command line app that polls ~gpsd~ and produces a stream
stdout consisting of GPS data lines in NMEA format. Installed via
~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
KML. Installed via ~apt~.

~gzip~ : A simple command line app that compresses stdin into a
smaller stdout stream.

~age~ : A simple command line app that encrypts stdin against public
keys specified in its options. Produces encrypted stdout. Is an
executable file contained within this repository at ~exec/age~. It
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.

*** Output
**** File Formats
***** NMEA
See the [[https://en.wikipedia.org/wiki/NMEA_0183][Wikipedia page]] for this.
***** 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.
***** 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.
**** 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
selected over ~gpg~ because of ~age~'s deliberate lack of
configurability.

The public keys are bech32 strings supplied as options to bkgpslog
when called. The secret key should *NOT* be stored in Ninfacyzga-01.

If a key pair was generated using ~age-keygen~, then it is an [[https://en.wikipedia.org/wiki/Curve25519][~X25519~]]
key pair. See the [[https://age-encryption.org/v1][~age~ Version 1 specification]].

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~.
***** Encryption
Files may be encrypted to several recipients using a command similar to:
#+BEGIN_EXAMPLE
timeout "60s" gpspipe -r | gpsbabel -i nmea -f - -o gpx -F | age \
-r age1kza7pfshy7xwygf9349zgmk7x53mquvedgw9r98qwyyqhssh830qqjzlsw \
-r age1ce3pvzrqfcn2pc6zqzglc8ac8yjk3fzukpy08cesqjjwns53xywqmaq7xw \
-r age1pu5usxm743sx7rf22985xv2f4s0luzv6r6yx4fa7p8c2zyvp9fvqus2xr5 \
> location.gpx.age
#+END_EXAMPLE

In this example, the strings beginning with ~age1...~ are
bech32-formatted public key strings. 


***** Decryption
Files may be decrypted using a command similar to:

#+BEGIN_EXAMPLE
cat location.gpx.age | age -d -i key.txt > location.gpx
#+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]].

**** Physical Setup

BerryGPS-IMU must be electrically connected to the correct pins on the
GPIO header of a Raspberry Pi Zero W.

*Optional*: stack together with PiZ Uptime 2.0 module. No GPIO pins
conflict so a simple stacking and soldering with long header pins is
possible.

**** Software Setup

***** Install Executables

Install Raspbian 10 Buster onto an SD card image. See the Raspberry Pi
Foundation [[https://www.raspberrypi.org/documentation/installation/installing-images/README.md][installation instructions]]. Configure WiFi to permit log
file transfer. Configure SSH to permit remote administration via the
command line interface.

Make sure to install the ~unattended-upgrades~ package to make sure
the latest security patches for packages are installed. See [[https://linux-audit.com/using-unattended-upgrades-on-debian-and-ubuntu/][this page]]
for a description of how ~unattended-upgrades~ works.

Install ~gpsd~, ~gpspipe~, ~git~, and this repository for location
logging capability.

Install ~syncthing~ for log file transfer capability.

Place ~age~ binary (the one compiled for ARM CPU architecture for
Linux) in ~$HOME/.local/bin~.

***** Automatic Start Configuration

Edit the user cron job list with ~$ crontab -e~ to add the following
lines:

#+BEGIN_EXAMPLE
0 * * * * /bin/bash /path/to/bkgpslog --output $HOME/Sync/example_dir

@reboot /bin/bash /path/to/bkgpslog --output $HOME/Sync/example_dir
#+END_EXAMPLE

The first line will run ~bkgpslog~ at the start of every hour.

The second line will run ~bkgpslog~ when the system starts up.

***** Log Transfer Configuration
Log files may be shared to other machines via ~syncthing~. See [[https://docs.syncthing.net/][this]]
manual for how to set up a shared folder and add Ninfacyzga-01 as a
device. Syncthing's directory synchronization capability allows a
remote machine to delete files from Ninfacyzga-01 by deleting from the
shared folder that they both share.

When log files are removed from Ninfacyzga-01 is not within the scope
of this document.

***** Key Generation
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
$ umask 066      # Sets umask so key.txt will have no permissions except for owner (you)
$ umask          # Confirm umask set to 066
0066
$ age-keygen > key.txt
Public key: age1pu5usxm743sx7rf22985xv2f4s0luzv6r6yx4fa7p8c2zyvp9fvqus2xr5
$ ls -al key.txt
-rw------- 1 baltakatei baltakatei 184 Jun 29 18:28 key.txt
$ umask 0022     # Return umask to default value
$ umask          
0022
#+END_EXAMPLE

The resulting public/private keypair data looks like:
#+BEGIN_EXAMPLE
$ cat key.txt
# created: 2020-06-29T18:01:56Z
# public key: age1pu5usxm743sx7rf22985xv2f4s0luzv6r6yx4fa7p8c2zyvp9fvqus2xr5
AGE-SECRET-KEY-1NEUU5U2XGZGL9UYWNPU5DL99TGJJHFSN4F2E2WCCSDJJ6L5ZMLESNTVTU0
#+END_EXAMPLE

The file ~key.txt~ is not password-protected by default and should be
secured like an SSH public key should. The ~$ umask 066~ command run
before the ~$ age-keygen > key.txt~ command ensures ~key.txt~ will not
be readable, writeable, or executable to anyone except the owner
(you).

*** Normal Startup
Turn on Ninfacyzga-01 by supplying 5VDC power to the Raspberry Pi. No
further interaction should be required.
*** Normal Operation
No interaction beyond continually supplying approximately 100mA of
5VDC power and occasionally removing log files to conserve disk space
is required.
**** Log Transfer
Log files may be transferred by use of ~syncthing~ shared folders.
**** Automatic Updates
The ~automatic-upgrades~ package, if installed, should automatically
install security patches to packages installed via ~apt~.
*** Normal Shutdown
The system may be shutdown via SSH by running:

: $ sudo shutdown -r 0

*** Unscheduled Shutdown
Ninfacyzga-01 as described and setup should tolerate unscheduled power
loss. Log files being written every 60 seconds means, at most, 60
seconds worth of location data may be lost.
*** End of Life Disposal
LiPo batteries used by the PiZ Uptime 2.0 module should be disposed of
properly with their potential ignitability in mind, especially if they
are not fully discharged.

Consult your local municipality for its "E-Waste Disposal" (or
equivalent) policy. Metals used in the Raspberry Pi and related
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.
Commit	Line	Data
170f63ba SBS	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
27a8996a	4	was updated by Steven Baltakatei Sandoval on <2020-06-29 Mon 18:39>.
170f63ba SBS	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
27a8996a	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.
170f63ba	57	***** KML
27a8996a	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.
170f63ba SBS	59	**** Encryption Method
170f63ba SBS	60	Files produced by the bkgpslog script are encrypted against a set of
27a8996a SBS	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
170f63ba SBS	97	** Operating Procedures
170f63ba SBS	98	*** Initial Startup
27a8996a SBS	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 /path/to/bkgpslog --output $HOME/Sync/example_dir
	138
	139	@reboot /bin/bash /path/to/bkgpslog --output $HOME/Sync/example_dir
	140	#+END_EXAMPLE
	141
	142	The first line will run ~bkgpslog~ at the start of every hour.
	143
	144	The second line will run ~bkgpslog~ when the system starts up.
	145
	146	***** Log Transfer Configuration
	147	Log files may be shared to other machines via ~syncthing~. See [[https://docs.syncthing.net/][this]]
	148	manual for how to set up a shared folder and add Ninfacyzga-01 as a
	149	device. Syncthing's directory synchronization capability allows a
	150	remote machine to delete files from Ninfacyzga-01 by deleting from the
	151	shared folder that they both share.
	152
	153	When log files are removed from Ninfacyzga-01 is not within the scope
	154	of this document.
	155
	156	***** Key Generation
	157	An ~age~ encryption key may be generated like so:
	158	#+BEGIN_EXAMPLE
	159	$ umask # Gets current umask
	160	0022 # Note: This is the default umask for Raspbian 10
	161	$ umask 066 # Sets umask so key.txt will have no permissions except for owner (you)
	162	$ umask # Confirm umask set to 066
163	0066
164	$ age-keygen > key.txt
165	Public key: age1pu5usxm743sx7rf22985xv2f4s0luzv6r6yx4fa7p8c2zyvp9fvqus2xr5
166	$ ls -al key.txt
167	-rw------- 1 baltakatei baltakatei 184 Jun 29 18:28 key.txt
168	$ umask 0022 # Return umask to default value
169	$ umask
170	0022
171	#+END_EXAMPLE
172
173	The resulting public/private keypair data looks like:
174	#+BEGIN_EXAMPLE
175	$ cat key.txt
176	# created: 2020-06-29T18:01:56Z
177	# public key: age1pu5usxm743sx7rf22985xv2f4s0luzv6r6yx4fa7p8c2zyvp9fvqus2xr5
178	AGE-SECRET-KEY-1NEUU5U2XGZGL9UYWNPU5DL99TGJJHFSN4F2E2WCCSDJJ6L5ZMLESNTVTU0
179	#+END_EXAMPLE
180
181	The file ~key.txt~ is not password-protected by default and should be
182	secured like an SSH public key should. The ~$ umask 066~ command run
183	before the ~$ age-keygen > key.txt~ command ensures ~key.txt~ will not
184	be readable, writeable, or executable to anyone except the owner
185	(you).
186
170f63ba	187	*** Normal Startup
27a8996a SBS	188	Turn on Ninfacyzga-01 by supplying 5VDC power to the Raspberry Pi. No
	189	further interaction should be required.
	190	*** Normal Operation
	191	No interaction beyond continually supplying approximately 100mA of
	192	5VDC power and occasionally removing log files to conserve disk space
	193	is required.
	194	**** Log Transfer
	195	Log files may be transferred by use of ~syncthing~ shared folders.
	196	**** Automatic Updates
	197	The ~automatic-upgrades~ package, if installed, should automatically
	198	install security patches to packages installed via ~apt~.
170f63ba	199	*** Normal Shutdown
27a8996a SBS	200	The system may be shutdown via SSH by running:
	201
	202	: $ sudo shutdown -r 0
	203
170f63ba	204	*** Unscheduled Shutdown
27a8996a SBS	205	Ninfacyzga-01 as described and setup should tolerate unscheduled power
	206	loss. Log files being written every 60 seconds means, at most, 60
	207	seconds worth of location data may be lost.
170f63ba	208	*** End of Life Disposal
27a8996a SBS	209	LiPo batteries used by the PiZ Uptime 2.0 module should be disposed of
	210	properly with their potential ignitability in mind, especially if they
	211	are not fully discharged.
	212
	213	Consult your local municipality for its "E-Waste Disposal" (or
	214	equivalent) policy. Metals used in the Raspberry Pi and related
	215	components may be recycled.
	216
	217	Take extra precuation if lead solder was used in assembling the
	218	electronics. Consumer electronics in early 21st century should use
	219	lead-free solder.
170f63ba	220