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