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-29T12:14Z under a Creative Commons BY-SA 4.0 license. It -was updated by Steven Baltakatei Sandoval on 2020-06-30T17:13Z -

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. Disable Swap File
  -
  -
  -Since standard Raspbian 10 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 disabled. -
  - -
  -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
-
```
  - -
  -The swap file may be disabled by: -
  - -
```
-pi@ninfacyzga-01:~$ sudo dphys-swapfile swapoff
-pi@ninfacyzga-01:~$ sudo dphys-swapfile uninstall
-pi@ninfacyzga-01:~$ sudo update-rc.d dphys-swapfile remove
-pi@ninfacyzga-01:~$ free -m
-              total        used        free      shared  buff/cache   available
-Mem:            432          96          33          22         302         258
-Swap:             0           0           0
-
```
  -
  -
3. 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
-
-
```
  -
  -
4. 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. -
  -
  -
5. 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. -