debug(bkgpslog):Clarified debug messages
[EVA-2020-02.git] / doc / location / README.org
... / ...
CommitLineData
1* Location Logging
2This document was created by Steven Baltakatei Sandoval on
3~2020-06-29T12:14Z~ 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-30T19:44Z~
5#+TITLE: Ninfacyzga-01 Manual
6#+AUTHOR: Steven Baltakatei Sandoval
7#+EMAIL: baltakatei@gmail.com
8** Narrative
9Ninfacyzga-01 records (logs) its position in time and space using a
10[[https://en.wikipedia.org/wiki/Satellite_navigation_device][GPS receiver]]. The NMEA location data produced by the receiver is
11converted into the more commonly used GPS data storage formats of GPX
12and KML. All three types of data are then compressed and encrypted
13against a set of public keys. The encrypted data is then written to
14disk. Data produced by the receiver is segmented into 60-second chunks
15before being processed and written to disk.
16** Description
17*** Hardware
18**** Raspberry Pi Zero W
19See the [[https://www.raspberrypi.org/pi-zero-w/][OEM]] webpage for this product.
20**** PiZ UpTime 2.0
21See the [[https://alchemy-power.com/piz-uptime-2-0/][OEM]] webpage for this product.
22*** Software
23~bkgpslog~ : The bash script that performs the location data
24collection and processing. Is an executable file contained within this
25repository at ~exec/bkgpslog~. It should be copied to
26~$HOME/.local/bin~.
27
28~gpsd~ : A background daemon app capable of interfacing with the
29Ozzmaker BerryGPS-IMU's GPS submodule. Installed and initialized by
30~apt~.
31
32~gpspipe~ : A command line app that polls ~gpsd~ and produces a stream
33stdout consisting of GPS data lines in NMEA format. Installed via
34~apt~.
35
36~gpsbabel~ : A command line app that converts GPS data from one format
37into another. ~bkgpslog~ uses it to convert NMEA data into GPX and
38KML. Installed via ~apt~.
39
40~gzip~ : A simple command line app that compresses stdin into a
41smaller stdout stream.
42
43~age~ : A simple command line app that encrypts stdin against public
44keys specified in its options. Produces encrypted stdout. Is an
45executable file contained within this repository at ~exec/age~. It
46should be copied to ~$HOME/.local/bin~.
47
48**** Narrative
49~bkgpslog~ populates a 60-second buffer with NMEA data from ~gpsd~ via
50~gpspipe~. This buffer is used by ~gpsbabel~ to produce GPX and KML
51versions of the buffer. All 3 buffers are then comprssed with ~gzip~,
52encrypted with ~age~, and then written to disk.
53
54*** Output
55**** File Formats
56***** NMEA
57See the [[https://en.wikipedia.org/wiki/NMEA_0183][Wikipedia page]] for this.
58***** GPX
59See 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.
60***** KML
61See 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.
62**** Encryption Method
63Files produced by the bkgpslog script are encrypted against a set of
64public keys using [[https://github.com/FiloSottile/age][~age~]], a simple command line encryption tool
65selected over ~gpg~ because of ~age~'s deliberate lack of
66configurability.
67
68The public keys are bech32 strings supplied as options to bkgpslog
69when called. The secret key should *NOT* be stored in Ninfacyzga-01.
70
71If a key pair was generated using ~age-keygen~, then it is an [[https://en.wikipedia.org/wiki/Curve25519][~X25519~]]
72key pair. See the [[https://age-encryption.org/v1][~age~ Version 1 specification]].
73
74An ~ssh-rsa~ or ~ssh-ed25519~ SSH public key string may be used instead of
75the bech32 public key string produced by ~age-keygen~ for convenience.
76
77Help information for ~age~ is available by running ~$ age --help~.
78***** Encryption Commands
79Files may be encrypted to several recipients using a command similar to:
80#+BEGIN_EXAMPLE
81timeout "60s" gpspipe -r | gpsbabel -i nmea -f - -o gpx -F | age \
82-r age1kza7pfshy7xwygf9349zgmk7x53mquvedgw9r98qwyyqhssh830qqjzlsw \
83-r age1ce3pvzrqfcn2pc6zqzglc8ac8yjk3fzukpy08cesqjjwns53xywqmaq7xw \
84-r age1pu5usxm743sx7rf22985xv2f4s0luzv6r6yx4fa7p8c2zyvp9fvqus2xr5 \
85> location.gpx.age
86#+END_EXAMPLE
87
88In this example, the strings beginning with ~age1...~ are
89bech32-formatted public key strings.
90
91
92***** Decryption Commands
93Files may be decrypted using a command similar to:
94
95#+BEGIN_EXAMPLE
96cat location.gpx.age | age -d -i key.txt > location.gpx
97#+END_EXAMPLE
98
99The version of ~age~ used to perform the encryption
100** Operating Procedures
101*** Initial Startup
102See OEM (Ozzmaker) [[https://ozzmaker.com/berrygps-berrygps-imu-quick-start-guide/][quickstart guide for the BerryGPS-IMU]].
103
104**** Physical Setup
105
106BerryGPS-IMU must be electrically connected to the correct pins on the
107GPIO header of a Raspberry Pi Zero W.
108
109*Optional*: stack together with PiZ Uptime 2.0 module. No GPIO pins
110conflict so a simple stacking and soldering with long header pins is
111possible.
112
113**** Software Setup
114***** Install Executables
115
116Install Raspbian 10 Buster onto an SD card image. See the Raspberry Pi
117Foundation [[https://www.raspberrypi.org/documentation/installation/installing-images/README.md][installation instructions]]. Configure WiFi to permit log
118file transfer. Configure SSH to permit remote administration via the
119command line interface.
120
121Make sure to install the ~unattended-upgrades~ package to make sure
122the latest security patches for packages are installed. See [[https://linux-audit.com/using-unattended-upgrades-on-debian-and-ubuntu/][this page]]
123for a description of how ~unattended-upgrades~ works.
124
125Install ~gpsd~, ~gpspipe~, ~git~, and this repository for location
126logging capability.
127
128Install ~syncthing~ for log file transfer capability.
129
130Place ~age~ binary (the one compiled for ARM CPU architecture for
131Linux) in ~$HOME/.local/bin~.
132
133***** Disable Swap File
134Since standard Raspbian 10 (Buster) install involves copying
135unencrypted file system image to SD card which is mounted by the
136Raspberry Pi, system memory may be written to disk in the form of a
137Swap file as described [[https://ideaheap.com/2013/07/stopping-sd-card-corruption-on-a-raspberry-pi/][here]]. In order to reduce the chance that
138location log data is ever written to disk, swap file functionality
139must be disabled[fn:ideaheap_20130731_disableswap].
140
141Raspbian 10 uses dphys-swapfile to manage a swap file. It may be
142disabled persistently[fn:rpf_20190702_disableswappersist] by running
143the following command:
144
145: sudo systemctl disable dphys-swapfile.service
146
147To view the status of the swap file in Raspbian 10, run ~free -m~:
148
149#+BEGIN_EXAMPLE
150pi@ninfacyzga-01:~$ free -m
151 total used free shared buff/cache available
152Mem: 432 86 36 21 309 268
153Swap: 99 0 99
154#+END_EXAMPLE
155
156After disabling the swap file and rebooting:
157
158#+BEGIN_EXAMPLE
159pi@ninfacyzga-01:~$ free -m
160 total used free shared buff/cache available
161Mem: 432 89 214 3 128 289
162Swap: 0 0 0
163#+END_EXAMPLE
164
165[fn:ideaheap_20130731_disableswap] Explanation:
166https://ideaheap.com/2013/07/stopping-sd-card-corruption-on-a-raspberry-pi/
167
168[fn:rpf_20190702_disableswappersist] Persistant disabling of swap in
169Raspbian 10 Buster:
170https://www.raspberrypi.org/forums/viewtopic.php?p=1490692&sid=5c596a124b7805d6b10dab8d3d7caf16#p1490692
171
172***** Automatic Start Configuration
173
174Edit the user cron job list with ~$ crontab -e~ to add the following
175lines:
176
177#+BEGIN_EXAMPLE
1780 * * * * /bin/bash ~/bkgpslog --output ~/dir
179
180@reboot /bin/bash ~/bkgpslog --output ~/dir
181#+END_EXAMPLE
182
183The first line will run ~bkgpslog~ at the start of every hour and save
184output files to the ~dir~ directory in your home folder.
185
186The second line will run ~bkgpslog~ when the system starts up.
187
188~/bin/bash~ tells ~cron~ to run ~bkgpslog~ with Bash.
189
190If encryption and compression are required, then the appropriate
191options must be added. The lines that must be added via ~$ crontab -e~
192may resemble:
193
194#+BEGIN_EXAMPLE
1950 * * * * /bin/bash ~/bkgpslog -c -e -r age1z2...qkv6p -o ~/dir
196
197@reboot /bin/bash ~/bkgpslog -c -e -r age1z2...qkv6p -o ~/dir
198#+END_EXAMPLE
199
200The ~age1z2...qkv6p~ is an ~age~ public key string. Please see the
201[[*Key Generation][Key Generation]] section for an explanation.
202
203The options are:
204
205: -c : tells bkgpslog to compress output
206: -e : tells bkgpslog log to encrypt output
207: -r : tells bkgpslog to interpret the next argument as a pubkey string
208: -o : tells bkgpslog to write output files to the directory represented
209: by the next argument
210
211***** Log Transfer Configuration
212Log files may be shared to other machines via ~syncthing~. See [[https://docs.syncthing.net/][this]]
213manual for how to set up a shared folder and add Ninfacyzga-01 as a
214device. Syncthing's directory synchronization capability allows a
215remote machine to delete files from Ninfacyzga-01 by deleting from the
216shared folder that they both share.
217
218When log files are removed from Ninfacyzga-01 is not within the scope
219of this document.
220
221***** Key Generation
222An ~age~ encryption key may be generated like so:
223#+BEGIN_EXAMPLE
224$ umask # Gets current umask
2250022 # Note: This is the default umask for Raspbian 10
226$ umask 066 # So key.txt will have no perms except for owner (you)
227$ umask # Confirm umask set to 066
2280066
229$ age-keygen > key.txt
230Public key: age1pu5usxm743sx7rf22985xv2f4s0luzv6r6yx4fa7p8c2zyvp9fvqus2xr5
231$ ls -al key.txt
232-rw------- 1 baltakatei baltakatei 184 Jun 29 18:28 key.txt
233$ umask 0022 # Return umask to default value
234$ umask
2350022
236#+END_EXAMPLE
237
238The resulting public/private keypair data looks like:
239#+BEGIN_EXAMPLE
240$ cat key.txt
241# created: 2020-06-29T18:01:56Z
242# public key: age1pu5usxm743sx7rf22985xv2f4s0luzv6r6yx4fa7p8c2zyvp9fvqus2xr5
243AGE-SECRET-KEY-1NEUU5U2XGZGL9UYWNPU5DL99TGJJHFSN4F2E2WCCSDJJ6L5ZMLESNTVTU0
244#+END_EXAMPLE
245
246The file ~key.txt~ is not password-protected by default and should be
247secured like an SSH public key should. The ~$ umask 066~ command run
248before the ~$ age-keygen > key.txt~ command ensures ~key.txt~ will not
249be readable, writeable, or executable to anyone except the owner
250(you).
251
252*** Normal Startup
253Turn on Ninfacyzga-01 by supplying 5VDC power to the Raspberry Pi. No
254further interaction should be required.
255*** Normal Operation
256No interaction beyond continually supplying approximately 100mA of
2575VDC power and occasionally removing log files to conserve disk space
258is required.
259**** Log Transfer
260Log files may be transferred by use of ~syncthing~ shared folders.
261**** Automatic Updates
262The ~automatic-upgrades~ package, if installed, should automatically
263install security patches to packages installed via ~apt~.
264*** Normal Shutdown
265The system may be shutdown via SSH by running:
266
267: $ sudo shutdown -r 0
268
269*** Unscheduled Shutdown
270Ninfacyzga-01 as described and setup should tolerate unscheduled power
271loss. Log files being written every 60 seconds means, at most, 60
272seconds worth of location data may be lost.
273*** End of Life Disposal
274LiPo batteries used by the PiZ Uptime 2.0 module should be disposed of
275properly with their potential ignitability in mind, especially if they
276are not fully discharged.
277
278Consult your local municipality for its "E-Waste Disposal" (or
279equivalent) policy. Metals used in the Raspberry Pi and related
280components may be recycled.
281
282Take extra precuation if lead solder was used in assembling the
283electronics. Consumer electronics in early 21st century should use
284lead-free solder.
285