Ninfacyzga-01 Manual

1. Location Logging +
- 1.1. Narrative
- 1.2. Description +
  - 1.2.1. Hardware
  - 1.2.2. Software
  - 1.2.3. Output
  +
- 1.3. Operating Procedures +
  +
+

1 Location Logging

+This document was created by Steven Baltakatei Sandoval on +<2020-06-29 Mon 12:14> under a Creative Commons BY-SA 4.0 license. It +was updated by Steven Baltakatei Sandoval on <2020-06-29 Mon 22:06>. +

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

Raspberry Pi Zero W
+
+
+See the OEM webpage for this product. +
+
+
PiZ UpTime 2.0
+
+
+See the OEM webpage for this product. +
+
+

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. +

+ +

Narrative
+
+
+bkgpslog populates a 60-second buffer with NMEA data from gpsd via +gpspipe. This buffer is used by gpsbabel to produce GPX and KML +versions of the buffer. All 3 buffers are then comprssed with gzip, +encrypted with age, and then written to disk. +
+
+

+ +

1.2.3 Output

File Formats
+
1. NMEA
  +
  +
  +See the Wikipedia page for this. +
  +
  +
2. GPX
  +
  +
  +See the Wikipedia page for this. WGS84 is the datum used. +
  +
  +
3. KML
  +
  +
  +See the Wikipedia page for this. WGS84 is the datum used. +
  +
  +
+
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 over gpg because of age'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 an X25519 +key pair. See the age Version 1 specification. +
+ +
+An ssh-rsa or ssh-ed25519 SSH public key string may be used instead of +the bech32 public key string produced by age-keygen for convenience. +
+ +
+Help information for age is available by running $ age --help. +
+
+
1. 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. +
  +
  +
2. 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 +
  +
  +
+

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
+
1. 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 how unattended-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. +
  +
  +
2. 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 the dir directory in your home folder. +
  + +
  +The second line will run bkgpslog when the system starts up. +
  + +
  +/bin/bash tells cron to run bkgpslog 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 an age 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
+
+
```
  +
  +
3. 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. +
  +
  +
4. 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      # Sets umask so key.txt will have no permissions 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 ensures key.txt will not +be readable, writeable, or executable to anyone except the owner +(you). +
  +
  +
+

+ +

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. +

Log Transfer
+
+
+Log files may be transferred by use of syncthing shared folders. +
+
+
Automatic Updates
+
+
+The automatic-upgrades package, if installed, should automatically +install security patches to packages installed via apt. +
+
+

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. +