debug(bkgpslog):Add debug messages for functions
[EVA-2020-02.git] / doc / location / README.org
CommitLineData
170f63ba
SBS
1* Location Logging
2This document was created by Steven Baltakatei Sandoval on
abd68e66 3~2020-06-29T12:14Z~ under a [[https://creativecommons.org/licenses/by-sa/4.0/][Creative Commons BY-SA 4.0 license]]. It
dac703dd 4was updated by Steven Baltakatei Sandoval on ~2020-06-30T19:44Z~
f7628e90
SBS
5#+TITLE: Ninfacyzga-01 Manual
6#+AUTHOR: Steven Baltakatei Sandoval
f7628e90 7#+EMAIL: baltakatei@gmail.com
170f63ba
SBS
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
27a8996a 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.
170f63ba 60***** KML
27a8996a 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.
170f63ba
SBS
62**** Encryption Method
63Files produced by the bkgpslog script are encrypted against a set of
27a8996a
SBS
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~.
f7628e90 78***** Encryption Commands
27a8996a
SBS
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
f7628e90 92***** Decryption Commands
27a8996a
SBS
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
170f63ba
SBS
100** Operating Procedures
101*** Initial Startup
27a8996a
SBS
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
27a8996a
SBS
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
abd68e66 133***** Disable Swap File
dac703dd
SBS
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
abd68e66
SBS
146
147To view the status of the swap file in Raspbian 10, run ~free -m~:
148
149#+BEGIN_EXAMPLE
150pi@ninfacyzga-01:~$ free -m
dac703dd
SBS
151 total used free shared buff/cache available
152Mem: 432 86 36 21 309 268
153Swap: 99 0 99
abd68e66
SBS
154#+END_EXAMPLE
155
dac703dd 156After disabling the swap file and rebooting:
abd68e66
SBS
157
158#+BEGIN_EXAMPLE
abd68e66 159pi@ninfacyzga-01:~$ free -m
dac703dd
SBS
160 total used free shared buff/cache available
161Mem: 432 89 214 3 128 289
162Swap: 0 0 0
abd68e66
SBS
163#+END_EXAMPLE
164
dac703dd
SBS
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
27a8996a
SBS
172***** Automatic Start Configuration
173
174Edit the user cron job list with ~$ crontab -e~ to add the following
175lines:
176
177#+BEGIN_EXAMPLE
b11c81de 1780 * * * * /bin/bash ~/bkgpslog --output ~/dir
27a8996a 179
b11c81de 180@reboot /bin/bash ~/bkgpslog --output ~/dir
27a8996a
SBS
181#+END_EXAMPLE
182
b11c81de
SBS
183The first line will run ~bkgpslog~ at the start of every hour and save
184output files to the ~dir~ directory in your home folder.
27a8996a
SBS
185
186The second line will run ~bkgpslog~ when the system starts up.
187
b11c81de
SBS
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
f7628e90
SBS
200The ~age1z2...qkv6p~ is an ~age~ public key string. Please see the
201[[*Key Generation][Key Generation]] section for an explanation.
b11c81de
SBS
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
27a8996a
SBS
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
dac703dd 226$ umask 066 # So key.txt will have no perms except for owner (you)
27a8996a
SBS
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
170f63ba 252*** Normal Startup
27a8996a
SBS
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~.
170f63ba 264*** Normal Shutdown
27a8996a
SBS
265The system may be shutdown via SSH by running:
266
267: $ sudo shutdown -r 0
268
170f63ba 269*** Unscheduled Shutdown
27a8996a
SBS
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.
170f63ba 273*** End of Life Disposal
27a8996a
SBS
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.
170f63ba 285