doc(location):Add README for location logging, add age ref files
[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
4was updated by Steven Baltakatei Sandoval on <2020-06-29 Mon 16:05>.
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.
57***** KML
58See the [[https://en.wikipedia.org/wiki/Keyhole_Markup_Language][Wikipedia page]] for this.
59**** Encryption Method
60Files produced by the bkgpslog script are encrypted against a set of
61public keys using [[https://github.com/FiloSottile/age][age]]. The public keys are bech32 strings supplied as
62options to bkgpslog when called.
63** Operating Procedures
64*** Initial Startup
65*** Normal Startup
66*** Normal Shutdown
67*** Unscheduled Shutdown
68*** End of Life Disposal
69