Ninfacyzga-01 Manual
Table of Contents
1 Location Logging
This document was created by Steven Baltakatei Sandoval on
2020-06-29T12:14Z
under a Creative Commons BY-SA 4.0 license. It
was updated by Steven Baltakatei Sandoval on 2020-06-30T19:44Z
1.1 Narrative
Ninfacyzga-01 records (logs) its position in time and space using a GPS receiver. The NMEA location data produced by the receiver is converted into the more commonly used GPS data storage formats of GPX and KML. All three types of data are then compressed and encrypted against a set of public keys. The encrypted data is then written to disk. Data produced by the receiver is segmented into 60-second chunks before being processed and written to disk.
1.2 Description
1.2.1 Hardware
1.2.2 Software
bkgpslog
: The bash script that performs the location data
collection and processing. Is an executable file contained within this
repository at exec/bkgpslog
. It should be copied to
$HOME/.local/bin
.
gpsd
: A background daemon app capable of interfacing with the
Ozzmaker BerryGPS-IMU's GPS submodule. Installed and initialized by
apt
.
gpspipe
: A command line app that polls gpsd
and produces a stream
stdout consisting of GPS data lines in NMEA format. Installed via
apt
.
gpsbabel
: A command line app that converts GPS data from one format
into another. bkgpslog
uses it to convert NMEA data into GPX and
KML. Installed via apt
.
gzip
: A simple command line app that compresses stdin into a
smaller stdout stream.
age
: A simple command line app that encrypts stdin against public
keys specified in its options. Produces encrypted stdout. Is an
executable file contained within this repository at exec/age
. It
should be copied to $HOME/.local/bin
.
1.2.3 Output
- File Formats
- NMEA
See the Wikipedia page for this.
- GPX
See the Wikipedia page for this. WGS84 is the datum used.
- KML
See the Wikipedia page for this. WGS84 is the datum used.
- NMEA
- Encryption Method
Files produced by the bkgpslog script are encrypted against a set of public keys using
age
, a simple command line encryption tool selected overgpg
because ofage
's deliberate lack of configurability.The public keys are bech32 strings supplied as options to bkgpslog when called. The secret key should NOT be stored in Ninfacyzga-01.
If a key pair was generated using
age-keygen
, then it is anX25519
key pair. See theage
Version 1 specification.An
ssh-rsa
orssh-ed25519
SSH public key string may be used instead of the bech32 public key string produced byage-keygen
for convenience.Help information for
age
is available by running$ age --help
.- Encryption Commands
Files may be encrypted to several recipients using a command similar to:
timeout "60s" gpspipe -r | gpsbabel -i nmea -f - -o gpx -F | age \ -r age1kza7pfshy7xwygf9349zgmk7x53mquvedgw9r98qwyyqhssh830qqjzlsw \ -r age1ce3pvzrqfcn2pc6zqzglc8ac8yjk3fzukpy08cesqjjwns53xywqmaq7xw \ -r age1pu5usxm743sx7rf22985xv2f4s0luzv6r6yx4fa7p8c2zyvp9fvqus2xr5 \ > location.gpx.age
In this example, the strings beginning with
age1...
are bech32-formatted public key strings. - Decryption Commands
Files may be decrypted using a command similar to:
cat location.gpx.age | age -d -i key.txt > location.gpx
The version of
age
used to perform the encryption
- Encryption Commands
1.3 Operating Procedures
1.3.1 Initial Startup
See OEM (Ozzmaker) quickstart guide for the BerryGPS-IMU.
- Physical Setup
BerryGPS-IMU must be electrically connected to the correct pins on the GPIO header of a Raspberry Pi Zero W.
Optional: stack together with PiZ Uptime 2.0 module. No GPIO pins conflict so a simple stacking and soldering with long header pins is possible.
- Software Setup
- Install Executables
Install Raspbian 10 Buster onto an SD card image. See the Raspberry Pi Foundation installation instructions. Configure WiFi to permit log file transfer. Configure SSH to permit remote administration via the command line interface.
Make sure to install the
unattended-upgrades
package to make sure the latest security patches for packages are installed. See this page for a description of howunattended-upgrades
works.Install
gpsd
,gpspipe
,git
, and this repository for location logging capability.Install
syncthing
for log file transfer capability.Place
age
binary (the one compiled for ARM CPU architecture for Linux) in$HOME/.local/bin
. - Disable Swap File
Since standard Raspbian 10 (Buster) install involves copying unencrypted file system image to SD card which is mounted by the Raspberry Pi, system memory may be written to disk in the form of a Swap file as described here. In order to reduce the chance that location log data is ever written to disk, swap file functionality must be disabled1.
Raspbian 10 uses dphys-swapfile to manage a swap file. It may be disabled persistently2 by running the following command:
sudo systemctl disable dphys-swapfile.service
To view the status of the swap file in Raspbian 10, run
free -m
:pi@ninfacyzga-01:~$ free -m total used free shared buff/cache available Mem: 432 86 36 21 309 268 Swap: 99 0 99
After disabling the swap file and rebooting:
pi@ninfacyzga-01:~$ free -m total used free shared buff/cache available Mem: 432 89 214 3 128 289 Swap: 0 0 0
- Automatic Start Configuration
Edit the user cron job list with
$ crontab -e
to add the following lines:0 * * * * /bin/bash ~/bkgpslog --output ~/dir @reboot /bin/bash ~/bkgpslog --output ~/dir
The first line will run
bkgpslog
at the start of every hour and save output files to thedir
directory in your home folder.The second line will run
bkgpslog
when the system starts up./bin/bash
tellscron
to runbkgpslog
with Bash.If encryption and compression are required, then the appropriate options must be added. The lines that must be added via
$ crontab -e
may resemble:0 * * * * /bin/bash ~/bkgpslog -c -e -r age1z2...qkv6p -o ~/dir @reboot /bin/bash ~/bkgpslog -c -e -r age1z2...qkv6p -o ~/dir
The
age1z2...qkv6p
is anage
public key string. Please see the Key Generation section for an explanation.The options are:
-c : tells bkgpslog to compress output -e : tells bkgpslog log to encrypt output -r : tells bkgpslog to interpret the next argument as a pubkey string -o : tells bkgpslog to write output files to the directory represented by the next argument
- Log Transfer Configuration
Log files may be shared to other machines via
syncthing
. See this manual for how to set up a shared folder and add Ninfacyzga-01 as a device. Syncthing's directory synchronization capability allows a remote machine to delete files from Ninfacyzga-01 by deleting from the shared folder that they both share.When log files are removed from Ninfacyzga-01 is not within the scope of this document.
- Key Generation
An
age
encryption key may be generated like so:$ umask # Gets current umask 0022 # Note: This is the default umask for Raspbian 10 $ umask 066 # So key.txt will have no perms except for owner (you) $ umask # Confirm umask set to 066 0066 $ age-keygen > key.txt Public key: age1pu5usxm743sx7rf22985xv2f4s0luzv6r6yx4fa7p8c2zyvp9fvqus2xr5 $ ls -al key.txt -rw------- 1 baltakatei baltakatei 184 Jun 29 18:28 key.txt $ umask 0022 # Return umask to default value $ umask 0022
The resulting public/private keypair data looks like:
$ cat key.txt # created: 2020-06-29T18:01:56Z # public key: age1pu5usxm743sx7rf22985xv2f4s0luzv6r6yx4fa7p8c2zyvp9fvqus2xr5 AGE-SECRET-KEY-1NEUU5U2XGZGL9UYWNPU5DL99TGJJHFSN4F2E2WCCSDJJ6L5ZMLESNTVTU0
The file
key.txt
is not password-protected by default and should be secured like an SSH public key should. The$ umask 066
command run before the$ age-keygen > key.txt
command ensureskey.txt
will not be readable, writeable, or executable to anyone except the owner (you).
- Install Executables
1.3.2 Normal Startup
Turn on Ninfacyzga-01 by supplying 5VDC power to the Raspberry Pi. No further interaction should be required.
1.3.3 Normal Operation
No interaction beyond continually supplying approximately 100mA of 5VDC power and occasionally removing log files to conserve disk space is required.
1.3.4 Normal Shutdown
The system may be shutdown via SSH by running:
$ sudo shutdown -r 0
1.3.5 Unscheduled Shutdown
Ninfacyzga-01 as described and setup should tolerate unscheduled power loss. Log files being written every 60 seconds means, at most, 60 seconds worth of location data may be lost.
1.3.6 End of Life Disposal
LiPo batteries used by the PiZ Uptime 2.0 module should be disposed of properly with their potential ignitability in mind, especially if they are not fully discharged.
Consult your local municipality for its "E-Waste Disposal" (or equivalent) policy. Metals used in the Raspberry Pi and related components may be recycled.
Take extra precuation if lead solder was used in assembling the electronics. Consumer electronics in early 21st century should use lead-free solder.
Footnotes:
Persistant disabling of swap in Raspbian 10 Buster: https://www.raspberrypi.org/forums/viewtopic.php?p=1490692&sid=5c596a124b7805d6b10dab8d3d7caf16#p1490692