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