debug(bkgpslog):Add debug messages for functions
[EVA-2020-02.git] / doc / location / README.html
CommitLineData
3f9df02d
SBS
1<?xml version="1.0" encoding="utf-8"?>
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
3"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
4<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
5<head>
dac703dd 6<!-- 2020-06-30 Tue 19:45 -->
3f9df02d
SBS
7<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
8<meta name="viewport" content="width=device-width, initial-scale=1" />
9<title>Ninfacyzga-01 Manual</title>
10<meta name="generator" content="Org mode" />
11<meta name="author" content="Steven Baltakatei Sandoval" />
12<style type="text/css">
13 <!--/*--><![CDATA[/*><!--*/
14 .title { text-align: center;
15 margin-bottom: .2em; }
16 .subtitle { text-align: center;
17 font-size: medium;
18 font-weight: bold;
19 margin-top:0; }
20 .todo { font-family: monospace; color: red; }
21 .done { font-family: monospace; color: green; }
22 .priority { font-family: monospace; color: orange; }
23 .tag { background-color: #eee; font-family: monospace;
24 padding: 2px; font-size: 80%; font-weight: normal; }
25 .timestamp { color: #bebebe; }
26 .timestamp-kwd { color: #5f9ea0; }
27 .org-right { margin-left: auto; margin-right: 0px; text-align: right; }
28 .org-left { margin-left: 0px; margin-right: auto; text-align: left; }
29 .org-center { margin-left: auto; margin-right: auto; text-align: center; }
30 .underline { text-decoration: underline; }
31 #postamble p, #preamble p { font-size: 90%; margin: .2em; }
32 p.verse { margin-left: 3%; }
33 pre {
34 border: 1px solid #ccc;
35 box-shadow: 3px 3px 3px #eee;
36 padding: 8pt;
37 font-family: monospace;
38 overflow: auto;
39 margin: 1.2em;
40 }
41 pre.src {
42 position: relative;
43 overflow: visible;
44 padding-top: 1.2em;
45 }
46 pre.src:before {
47 display: none;
48 position: absolute;
49 background-color: white;
50 top: -10px;
51 right: 10px;
52 padding: 3px;
53 border: 1px solid black;
54 }
55 pre.src:hover:before { display: inline;}
56 /* Languages per Org manual */
57 pre.src-asymptote:before { content: 'Asymptote'; }
58 pre.src-awk:before { content: 'Awk'; }
59 pre.src-C:before { content: 'C'; }
60 /* pre.src-C++ doesn't work in CSS */
61 pre.src-clojure:before { content: 'Clojure'; }
62 pre.src-css:before { content: 'CSS'; }
63 pre.src-D:before { content: 'D'; }
64 pre.src-ditaa:before { content: 'ditaa'; }
65 pre.src-dot:before { content: 'Graphviz'; }
66 pre.src-calc:before { content: 'Emacs Calc'; }
67 pre.src-emacs-lisp:before { content: 'Emacs Lisp'; }
68 pre.src-fortran:before { content: 'Fortran'; }
69 pre.src-gnuplot:before { content: 'gnuplot'; }
70 pre.src-haskell:before { content: 'Haskell'; }
71 pre.src-hledger:before { content: 'hledger'; }
72 pre.src-java:before { content: 'Java'; }
73 pre.src-js:before { content: 'Javascript'; }
74 pre.src-latex:before { content: 'LaTeX'; }
75 pre.src-ledger:before { content: 'Ledger'; }
76 pre.src-lisp:before { content: 'Lisp'; }
77 pre.src-lilypond:before { content: 'Lilypond'; }
78 pre.src-lua:before { content: 'Lua'; }
79 pre.src-matlab:before { content: 'MATLAB'; }
80 pre.src-mscgen:before { content: 'Mscgen'; }
81 pre.src-ocaml:before { content: 'Objective Caml'; }
82 pre.src-octave:before { content: 'Octave'; }
83 pre.src-org:before { content: 'Org mode'; }
84 pre.src-oz:before { content: 'OZ'; }
85 pre.src-plantuml:before { content: 'Plantuml'; }
86 pre.src-processing:before { content: 'Processing.js'; }
87 pre.src-python:before { content: 'Python'; }
88 pre.src-R:before { content: 'R'; }
89 pre.src-ruby:before { content: 'Ruby'; }
90 pre.src-sass:before { content: 'Sass'; }
91 pre.src-scheme:before { content: 'Scheme'; }
92 pre.src-screen:before { content: 'Gnu Screen'; }
93 pre.src-sed:before { content: 'Sed'; }
94 pre.src-sh:before { content: 'shell'; }
95 pre.src-sql:before { content: 'SQL'; }
96 pre.src-sqlite:before { content: 'SQLite'; }
97 /* additional languages in org.el's org-babel-load-languages alist */
98 pre.src-forth:before { content: 'Forth'; }
99 pre.src-io:before { content: 'IO'; }
100 pre.src-J:before { content: 'J'; }
101 pre.src-makefile:before { content: 'Makefile'; }
102 pre.src-maxima:before { content: 'Maxima'; }
103 pre.src-perl:before { content: 'Perl'; }
104 pre.src-picolisp:before { content: 'Pico Lisp'; }
105 pre.src-scala:before { content: 'Scala'; }
106 pre.src-shell:before { content: 'Shell Script'; }
107 pre.src-ebnf2ps:before { content: 'ebfn2ps'; }
108 /* additional language identifiers per "defun org-babel-execute"
109 in ob-*.el */
110 pre.src-cpp:before { content: 'C++'; }
111 pre.src-abc:before { content: 'ABC'; }
112 pre.src-coq:before { content: 'Coq'; }
113 pre.src-groovy:before { content: 'Groovy'; }
114 /* additional language identifiers from org-babel-shell-names in
115 ob-shell.el: ob-shell is the only babel language using a lambda to put
116 the execution function name together. */
117 pre.src-bash:before { content: 'bash'; }
118 pre.src-csh:before { content: 'csh'; }
119 pre.src-ash:before { content: 'ash'; }
120 pre.src-dash:before { content: 'dash'; }
121 pre.src-ksh:before { content: 'ksh'; }
122 pre.src-mksh:before { content: 'mksh'; }
123 pre.src-posh:before { content: 'posh'; }
124 /* Additional Emacs modes also supported by the LaTeX listings package */
125 pre.src-ada:before { content: 'Ada'; }
126 pre.src-asm:before { content: 'Assembler'; }
127 pre.src-caml:before { content: 'Caml'; }
128 pre.src-delphi:before { content: 'Delphi'; }
129 pre.src-html:before { content: 'HTML'; }
130 pre.src-idl:before { content: 'IDL'; }
131 pre.src-mercury:before { content: 'Mercury'; }
132 pre.src-metapost:before { content: 'MetaPost'; }
133 pre.src-modula-2:before { content: 'Modula-2'; }
134 pre.src-pascal:before { content: 'Pascal'; }
135 pre.src-ps:before { content: 'PostScript'; }
136 pre.src-prolog:before { content: 'Prolog'; }
137 pre.src-simula:before { content: 'Simula'; }
138 pre.src-tcl:before { content: 'tcl'; }
139 pre.src-tex:before { content: 'TeX'; }
140 pre.src-plain-tex:before { content: 'Plain TeX'; }
141 pre.src-verilog:before { content: 'Verilog'; }
142 pre.src-vhdl:before { content: 'VHDL'; }
143 pre.src-xml:before { content: 'XML'; }
144 pre.src-nxml:before { content: 'XML'; }
145 /* add a generic configuration mode; LaTeX export needs an additional
146 (add-to-list 'org-latex-listings-langs '(conf " ")) in .emacs */
147 pre.src-conf:before { content: 'Configuration File'; }
148
149 table { border-collapse:collapse; }
150 caption.t-above { caption-side: top; }
151 caption.t-bottom { caption-side: bottom; }
152 td, th { vertical-align:top; }
153 th.org-right { text-align: center; }
154 th.org-left { text-align: center; }
155 th.org-center { text-align: center; }
156 td.org-right { text-align: right; }
157 td.org-left { text-align: left; }
158 td.org-center { text-align: center; }
159 dt { font-weight: bold; }
160 .footpara { display: inline; }
161 .footdef { margin-bottom: 1em; }
162 .figure { padding: 1em; }
163 .figure p { text-align: center; }
164 .inlinetask {
165 padding: 10px;
166 border: 2px solid gray;
167 margin: 10px;
168 background: #ffffcc;
169 }
170 #org-div-home-and-up
171 { text-align: right; font-size: 70%; white-space: nowrap; }
172 textarea { overflow-x: auto; }
173 .linenr { font-size: smaller }
174 .code-highlighted { background-color: #ffff00; }
175 .org-info-js_info-navigation { border-style: none; }
176 #org-info-js_console-label
177 { font-size: 10px; font-weight: bold; white-space: nowrap; }
178 .org-info-js_search-highlight
179 { background-color: #ffff00; color: #000000; font-weight: bold; }
180 .org-svg { width: 90%; }
181 /*]]>*/-->
182</style>
183<script type="text/javascript">
184/*
185@licstart The following is the entire license notice for the
186JavaScript code in this tag.
187
188Copyright (C) 2012-2018 Free Software Foundation, Inc.
189
190The JavaScript code in this tag is free software: you can
191redistribute it and/or modify it under the terms of the GNU
192General Public License (GNU GPL) as published by the Free Software
193Foundation, either version 3 of the License, or (at your option)
194any later version. The code is distributed WITHOUT ANY WARRANTY;
195without even the implied warranty of MERCHANTABILITY or FITNESS
196FOR A PARTICULAR PURPOSE. See the GNU GPL for more details.
197
198As additional permission under GNU GPL version 3 section 7, you
199may distribute non-source (e.g., minimized or compacted) forms of
200that code without the copy of the GNU GPL normally required by
201section 4, provided you include this license notice and a URL
202through which recipients can access the Corresponding Source.
203
204
205@licend The above is the entire license notice
206for the JavaScript code in this tag.
207*/
208<!--/*--><![CDATA[/*><!--*/
209 function CodeHighlightOn(elem, id)
210 {
211 var target = document.getElementById(id);
212 if(null != target) {
213 elem.cacheClassElem = elem.className;
214 elem.cacheClassTarget = target.className;
215 target.className = "code-highlighted";
216 elem.className = "code-highlighted";
217 }
218 }
219 function CodeHighlightOff(elem, id)
220 {
221 var target = document.getElementById(id);
222 if(elem.cacheClassElem)
223 elem.className = elem.cacheClassElem;
224 if(elem.cacheClassTarget)
225 target.className = elem.cacheClassTarget;
226 }
227/*]]>*///-->
228</script>
229</head>
230<body>
231<div id="content">
232<h1 class="title">Ninfacyzga-01 Manual</h1>
233<div id="table-of-contents">
234<h2>Table of Contents</h2>
235<div id="text-table-of-contents">
236<ul>
dac703dd 237<li><a href="#org4ab28d5">1. Location Logging</a>
3f9df02d 238<ul>
dac703dd
SBS
239<li><a href="#org3a44301">1.1. Narrative</a></li>
240<li><a href="#orgeb3a61f">1.2. Description</a>
3f9df02d 241<ul>
dac703dd
SBS
242<li><a href="#org68434d8">1.2.1. Hardware</a></li>
243<li><a href="#org6bf1f28">1.2.2. Software</a></li>
244<li><a href="#orga640ec2">1.2.3. Output</a></li>
3f9df02d
SBS
245</ul>
246</li>
dac703dd 247<li><a href="#org78712e3">1.3. Operating Procedures</a>
3f9df02d 248<ul>
dac703dd
SBS
249<li><a href="#orgcc76a4c">1.3.1. Initial Startup</a></li>
250<li><a href="#org8fbf566">1.3.2. Normal Startup</a></li>
251<li><a href="#orgbc8af37">1.3.3. Normal Operation</a></li>
252<li><a href="#org46c0af5">1.3.4. Normal Shutdown</a></li>
253<li><a href="#org662e1e8">1.3.5. Unscheduled Shutdown</a></li>
254<li><a href="#org70e088c">1.3.6. End of Life Disposal</a></li>
3f9df02d
SBS
255</ul>
256</li>
257</ul>
258</li>
259</ul>
260</div>
261</div>
dac703dd
SBS
262<div id="outline-container-org4ab28d5" class="outline-2">
263<h2 id="org4ab28d5"><span class="section-number-2">1</span> Location Logging</h2>
3f9df02d
SBS
264<div class="outline-text-2" id="text-1">
265<p>
266This document was created by Steven Baltakatei Sandoval on
abd68e66 267<code>2020-06-29T12:14Z</code> under a <a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative Commons BY-SA 4.0 license</a>. It
dac703dd 268was updated by Steven Baltakatei Sandoval on <code>2020-06-30T19:44Z</code>
3f9df02d
SBS
269</p>
270</div>
dac703dd
SBS
271<div id="outline-container-org3a44301" class="outline-3">
272<h3 id="org3a44301"><span class="section-number-3">1.1</span> Narrative</h3>
3f9df02d
SBS
273<div class="outline-text-3" id="text-1-1">
274<p>
275Ninfacyzga-01 records (logs) its position in time and space using a
276<a href="https://en.wikipedia.org/wiki/Satellite_navigation_device">GPS receiver</a>. The NMEA location data produced by the receiver is
277converted into the more commonly used GPS data storage formats of GPX
278and KML. All three types of data are then compressed and encrypted
279against a set of public keys. The encrypted data is then written to
280disk. Data produced by the receiver is segmented into 60-second chunks
281before being processed and written to disk.
282</p>
283</div>
284</div>
dac703dd
SBS
285<div id="outline-container-orgeb3a61f" class="outline-3">
286<h3 id="orgeb3a61f"><span class="section-number-3">1.2</span> Description</h3>
3f9df02d
SBS
287<div class="outline-text-3" id="text-1-2">
288</div>
dac703dd
SBS
289<div id="outline-container-org68434d8" class="outline-4">
290<h4 id="org68434d8"><span class="section-number-4">1.2.1</span> Hardware</h4>
3f9df02d
SBS
291<div class="outline-text-4" id="text-1-2-1">
292</div>
293<ol class="org-ol">
dac703dd 294<li><a id="org3fcab7d"></a>Raspberry Pi Zero W<br />
3f9df02d
SBS
295<div class="outline-text-5" id="text-1-2-1-1">
296<p>
297See the <a href="https://www.raspberrypi.org/pi-zero-w/">OEM</a> webpage for this product.
298</p>
299</div>
300</li>
dac703dd 301<li><a id="org4a38c06"></a>PiZ UpTime 2.0<br />
3f9df02d
SBS
302<div class="outline-text-5" id="text-1-2-1-2">
303<p>
304See the <a href="https://alchemy-power.com/piz-uptime-2-0/">OEM</a> webpage for this product.
305</p>
306</div>
307</li>
308</ol>
309</div>
dac703dd
SBS
310<div id="outline-container-org6bf1f28" class="outline-4">
311<h4 id="org6bf1f28"><span class="section-number-4">1.2.2</span> Software</h4>
3f9df02d
SBS
312<div class="outline-text-4" id="text-1-2-2">
313<p>
314<code>bkgpslog</code> : The bash script that performs the location data
315collection and processing. Is an executable file contained within this
316repository at <code>exec/bkgpslog</code>. It should be copied to
317<code>$HOME/.local/bin</code>.
318</p>
319
320<p>
321<code>gpsd</code> : A background daemon app capable of interfacing with the
322Ozzmaker BerryGPS-IMU's GPS submodule. Installed and initialized by
323<code>apt</code>.
324</p>
325
326<p>
327<code>gpspipe</code> : A command line app that polls <code>gpsd</code> and produces a stream
328stdout consisting of GPS data lines in NMEA format. Installed via
329<code>apt</code>.
330</p>
331
332<p>
333<code>gpsbabel</code> : A command line app that converts GPS data from one format
334into another. <code>bkgpslog</code> uses it to convert NMEA data into GPX and
335KML. Installed via <code>apt</code>.
336</p>
337
338<p>
339<code>gzip</code> : A simple command line app that compresses stdin into a
340smaller stdout stream.
341</p>
342
343<p>
344<code>age</code> : A simple command line app that encrypts stdin against public
345keys specified in its options. Produces encrypted stdout. Is an
346executable file contained within this repository at <code>exec/age</code>. It
347should be copied to <code>$HOME/.local/bin</code>.
348</p>
349</div>
350
351<ol class="org-ol">
dac703dd 352<li><a id="org33a99e7"></a>Narrative<br />
3f9df02d
SBS
353<div class="outline-text-5" id="text-1-2-2-1">
354<p>
355<code>bkgpslog</code> populates a 60-second buffer with NMEA data from <code>gpsd</code> via
356<code>gpspipe</code>. This buffer is used by <code>gpsbabel</code> to produce GPX and KML
357versions of the buffer. All 3 buffers are then comprssed with <code>gzip</code>,
358encrypted with <code>age</code>, and then written to disk.
359</p>
360</div>
361</li>
362</ol>
363</div>
364
dac703dd
SBS
365<div id="outline-container-orga640ec2" class="outline-4">
366<h4 id="orga640ec2"><span class="section-number-4">1.2.3</span> Output</h4>
3f9df02d
SBS
367<div class="outline-text-4" id="text-1-2-3">
368</div>
369<ol class="org-ol">
dac703dd 370<li><a id="orgbe90ee3"></a>File Formats<br />
3f9df02d 371<ol class="org-ol">
dac703dd 372<li><a id="orga69e180"></a>NMEA<br />
3f9df02d
SBS
373<div class="outline-text-6" id="text-1-2-3-1-1">
374<p>
375See the <a href="https://en.wikipedia.org/wiki/NMEA_0183">Wikipedia page</a> for this.
376</p>
377</div>
378</li>
dac703dd 379<li><a id="org03fca13"></a>GPX<br />
3f9df02d
SBS
380<div class="outline-text-6" id="text-1-2-3-1-2">
381<p>
382See the <a href="https://en.wikipedia.org/wiki/GPS_Exchange_Format">Wikipedia page</a> for this. <a href="http://wiki.gis.com/wiki/index.php/WGS84">WGS84</a> is the datum used.
383</p>
384</div>
385</li>
dac703dd 386<li><a id="org9469dda"></a>KML<br />
3f9df02d
SBS
387<div class="outline-text-6" id="text-1-2-3-1-3">
388<p>
389See the <a href="https://en.wikipedia.org/wiki/Keyhole_Markup_Language">Wikipedia page</a> for this. <a href="http://wiki.gis.com/wiki/index.php/WGS84">WGS84</a> is the datum used.
390</p>
391</div>
392</li>
393</ol>
394</li>
dac703dd 395<li><a id="org4923cfc"></a>Encryption Method<br />
3f9df02d
SBS
396<div class="outline-text-5" id="text-1-2-3-2">
397<p>
398Files produced by the bkgpslog script are encrypted against a set of
399public keys using <a href="https://github.com/FiloSottile/age"><code>age</code></a>, a simple command line encryption tool
400selected over <code>gpg</code> because of <code>age</code>'s deliberate lack of
401configurability.
402</p>
403
404<p>
405The public keys are bech32 strings supplied as options to bkgpslog
406when called. The secret key should <b>NOT</b> be stored in Ninfacyzga-01.
407</p>
408
409<p>
410If a key pair was generated using <code>age-keygen</code>, then it is an <a href="https://en.wikipedia.org/wiki/Curve25519"><code>X25519</code></a>
411key pair. See the <a href="https://age-encryption.org/v1"><code>age</code> Version 1 specification</a>.
412</p>
413
414<p>
415An <code>ssh-rsa</code> or <code>ssh-ed25519</code> SSH public key string may be used instead of
416the bech32 public key string produced by <code>age-keygen</code> for convenience.
417</p>
418
419<p>
420Help information for <code>age</code> is available by running <code>$ age --help</code>.
421</p>
422</div>
423<ol class="org-ol">
dac703dd 424<li><a id="org5f006f6"></a>Encryption Commands<br />
3f9df02d
SBS
425<div class="outline-text-6" id="text-1-2-3-2-1">
426<p>
427Files may be encrypted to several recipients using a command similar to:
428</p>
429<pre class="example">
430timeout "60s" gpspipe -r | gpsbabel -i nmea -f - -o gpx -F | age \
431-r age1kza7pfshy7xwygf9349zgmk7x53mquvedgw9r98qwyyqhssh830qqjzlsw \
432-r age1ce3pvzrqfcn2pc6zqzglc8ac8yjk3fzukpy08cesqjjwns53xywqmaq7xw \
433-r age1pu5usxm743sx7rf22985xv2f4s0luzv6r6yx4fa7p8c2zyvp9fvqus2xr5 \
434&gt; location.gpx.age
435</pre>
436
437<p>
438In this example, the strings beginning with <code>age1...</code> are
439bech32-formatted public key strings.
440</p>
441</div>
442</li>
443
444
dac703dd 445<li><a id="orgd0d1b14"></a>Decryption Commands<br />
3f9df02d
SBS
446<div class="outline-text-6" id="text-1-2-3-2-2">
447<p>
448Files may be decrypted using a command similar to:
449</p>
450
451<pre class="example">
452cat location.gpx.age | age -d -i key.txt &gt; location.gpx
453</pre>
454
455<p>
456The version of <code>age</code> used to perform the encryption
457</p>
458</div>
459</li>
460</ol>
461</li>
462</ol>
463</div>
464</div>
dac703dd
SBS
465<div id="outline-container-org78712e3" class="outline-3">
466<h3 id="org78712e3"><span class="section-number-3">1.3</span> Operating Procedures</h3>
3f9df02d
SBS
467<div class="outline-text-3" id="text-1-3">
468</div>
dac703dd
SBS
469<div id="outline-container-orgcc76a4c" class="outline-4">
470<h4 id="orgcc76a4c"><span class="section-number-4">1.3.1</span> Initial Startup</h4>
3f9df02d
SBS
471<div class="outline-text-4" id="text-1-3-1">
472<p>
473See OEM (Ozzmaker) <a href="https://ozzmaker.com/berrygps-berrygps-imu-quick-start-guide/">quickstart guide for the BerryGPS-IMU</a>.
474</p>
475</div>
476
477<ol class="org-ol">
dac703dd 478<li><a id="orgae43b4b"></a>Physical Setup<br />
3f9df02d
SBS
479<div class="outline-text-5" id="text-1-3-1-1">
480<p>
481BerryGPS-IMU must be electrically connected to the correct pins on the
482GPIO header of a Raspberry Pi Zero W.
483</p>
484
485<p>
486<b>Optional</b>: stack together with PiZ Uptime 2.0 module. No GPIO pins
487conflict so a simple stacking and soldering with long header pins is
488possible.
489</p>
490</div>
491</li>
492
dac703dd 493<li><a id="orgb3c2fc2"></a>Software Setup<br />
3f9df02d 494<ol class="org-ol">
dac703dd 495<li><a id="org651214a"></a>Install Executables<br />
3f9df02d
SBS
496<div class="outline-text-6" id="text-1-3-1-2-1">
497<p>
498Install Raspbian 10 Buster onto an SD card image. See the Raspberry Pi
499Foundation <a href="https://www.raspberrypi.org/documentation/installation/installing-images/README.md">installation instructions</a>. Configure WiFi to permit log
500file transfer. Configure SSH to permit remote administration via the
501command line interface.
502</p>
503
504<p>
505Make sure to install the <code>unattended-upgrades</code> package to make sure
506the latest security patches for packages are installed. See <a href="https://linux-audit.com/using-unattended-upgrades-on-debian-and-ubuntu/">this page</a>
507for a description of how <code>unattended-upgrades</code> works.
508</p>
509
510<p>
511Install <code>gpsd</code>, <code>gpspipe</code>, <code>git</code>, and this repository for location
512logging capability.
513</p>
514
515<p>
516Install <code>syncthing</code> for log file transfer capability.
517</p>
518
519<p>
520Place <code>age</code> binary (the one compiled for ARM CPU architecture for
521Linux) in <code>$HOME/.local/bin</code>.
522</p>
523</div>
524</li>
525
dac703dd 526<li><a id="org1cc0c53"></a>Disable Swap File<br />
3f9df02d
SBS
527<div class="outline-text-6" id="text-1-3-1-2-2">
528<p>
dac703dd
SBS
529Since standard Raspbian 10 (Buster) install involves copying
530unencrypted file system image to SD card which is mounted by the
531Raspberry Pi, system memory may be written to disk in the form of a
532Swap file as described <a href="https://ideaheap.com/2013/07/stopping-sd-card-corruption-on-a-raspberry-pi/">here</a>. In order to reduce the chance that
533location log data is ever written to disk, swap file functionality
534must be disabled<sup><a id="fnr.1" class="footref" href="#fn.1">1</a></sup>.
abd68e66
SBS
535</p>
536
dac703dd
SBS
537<p>
538Raspbian 10 uses dphys-swapfile to manage a swap file. It may be
539disabled persistently<sup><a id="fnr.2" class="footref" href="#fn.2">2</a></sup> by running
540the following command:
541</p>
542
543<pre class="example">
544sudo systemctl disable dphys-swapfile.service
545
546</pre>
547
abd68e66
SBS
548<p>
549To view the status of the swap file in Raspbian 10, run <code>free -m</code>:
550</p>
551
552<pre class="example">
553pi@ninfacyzga-01:~$ free -m
dac703dd
SBS
554 total used free shared buff/cache available
555Mem: 432 86 36 21 309 268
556Swap: 99 0 99
abd68e66
SBS
557</pre>
558
559<p>
dac703dd 560After disabling the swap file and rebooting:
abd68e66
SBS
561</p>
562
563<pre class="example">
abd68e66 564pi@ninfacyzga-01:~$ free -m
dac703dd
SBS
565 total used free shared buff/cache available
566Mem: 432 89 214 3 128 289
567Swap: 0 0 0
abd68e66
SBS
568</pre>
569</div>
570</li>
571
dac703dd 572<li><a id="orgfdbf7d1"></a>Automatic Start Configuration<br />
abd68e66
SBS
573<div class="outline-text-6" id="text-1-3-1-2-3">
574<p>
3f9df02d
SBS
575Edit the user cron job list with <code>$ crontab -e</code> to add the following
576lines:
577</p>
578
579<pre class="example">
5800 * * * * /bin/bash ~/bkgpslog --output ~/dir
581
582@reboot /bin/bash ~/bkgpslog --output ~/dir
583</pre>
584
585<p>
586The first line will run <code>bkgpslog</code> at the start of every hour and save
587output files to the <code>dir</code> directory in your home folder.
588</p>
589
590<p>
591The second line will run <code>bkgpslog</code> when the system starts up.
592</p>
593
594<p>
595<code>/bin/bash</code> tells <code>cron</code> to run <code>bkgpslog</code> with Bash.
596</p>
597
598<p>
599If encryption and compression are required, then the appropriate
600options must be added. The lines that must be added via <code>$ crontab -e</code>
601may resemble:
602</p>
603
604<pre class="example">
6050 * * * * /bin/bash ~/bkgpslog -c -e -r age1z2...qkv6p -o ~/dir
606
607@reboot /bin/bash ~/bkgpslog -c -e -r age1z2...qkv6p -o ~/dir
608</pre>
609
610<p>
611The <code>age1z2...qkv6p</code> is an <code>age</code> public key string. Please see the
dac703dd 612<a href="#org4647532">Key Generation</a> section for an explanation.
3f9df02d
SBS
613</p>
614
615<p>
616The options are:
617</p>
618
619<pre class="example">
620-c : tells bkgpslog to compress output
621-e : tells bkgpslog log to encrypt output
622-r : tells bkgpslog to interpret the next argument as a pubkey string
623-o : tells bkgpslog to write output files to the directory represented
624 by the next argument
625
626</pre>
627</div>
628</li>
629
dac703dd 630<li><a id="org2de2dd5"></a>Log Transfer Configuration<br />
abd68e66 631<div class="outline-text-6" id="text-1-3-1-2-4">
3f9df02d
SBS
632<p>
633Log files may be shared to other machines via <code>syncthing</code>. See <a href="https://docs.syncthing.net/">this</a>
634manual for how to set up a shared folder and add Ninfacyzga-01 as a
635device. Syncthing's directory synchronization capability allows a
636remote machine to delete files from Ninfacyzga-01 by deleting from the
637shared folder that they both share.
638</p>
639
640<p>
641When log files are removed from Ninfacyzga-01 is not within the scope
642of this document.
643</p>
644</div>
645</li>
646
dac703dd 647<li><a id="org4647532"></a>Key Generation<br />
abd68e66 648<div class="outline-text-6" id="text-1-3-1-2-5">
3f9df02d
SBS
649<p>
650An <code>age</code> encryption key may be generated like so:
651</p>
652<pre class="example">
653$ umask # Gets current umask
6540022 # Note: This is the default umask for Raspbian 10
dac703dd 655$ umask 066 # So key.txt will have no perms except for owner (you)
3f9df02d
SBS
656$ umask # Confirm umask set to 066
6570066
658$ age-keygen &gt; key.txt
659Public key: age1pu5usxm743sx7rf22985xv2f4s0luzv6r6yx4fa7p8c2zyvp9fvqus2xr5
660$ ls -al key.txt
661-rw------- 1 baltakatei baltakatei 184 Jun 29 18:28 key.txt
662$ umask 0022 # Return umask to default value
663$ umask
6640022
665</pre>
666
667<p>
668The resulting public/private keypair data looks like:
669</p>
670<pre class="example">
671$ cat key.txt
672# created: 2020-06-29T18:01:56Z
673# public key: age1pu5usxm743sx7rf22985xv2f4s0luzv6r6yx4fa7p8c2zyvp9fvqus2xr5
674AGE-SECRET-KEY-1NEUU5U2XGZGL9UYWNPU5DL99TGJJHFSN4F2E2WCCSDJJ6L5ZMLESNTVTU0
675</pre>
676
677<p>
678The file <code>key.txt</code> is not password-protected by default and should be
679secured like an SSH public key should. The <code>$ umask 066</code> command run
680before the <code>$ age-keygen &gt; key.txt</code> command ensures <code>key.txt</code> will not
681be readable, writeable, or executable to anyone except the owner
682(you).
683</p>
684</div>
685</li>
686</ol>
687</li>
688</ol>
689</div>
690
dac703dd
SBS
691<div id="outline-container-org8fbf566" class="outline-4">
692<h4 id="org8fbf566"><span class="section-number-4">1.3.2</span> Normal Startup</h4>
3f9df02d
SBS
693<div class="outline-text-4" id="text-1-3-2">
694<p>
695Turn on Ninfacyzga-01 by supplying 5VDC power to the Raspberry Pi. No
696further interaction should be required.
697</p>
698</div>
699</div>
dac703dd
SBS
700<div id="outline-container-orgbc8af37" class="outline-4">
701<h4 id="orgbc8af37"><span class="section-number-4">1.3.3</span> Normal Operation</h4>
3f9df02d
SBS
702<div class="outline-text-4" id="text-1-3-3">
703<p>
704No interaction beyond continually supplying approximately 100mA of
7055VDC power and occasionally removing log files to conserve disk space
706is required.
707</p>
708</div>
709<ol class="org-ol">
dac703dd 710<li><a id="orgeaa5887"></a>Log Transfer<br />
3f9df02d
SBS
711<div class="outline-text-5" id="text-1-3-3-1">
712<p>
713Log files may be transferred by use of <code>syncthing</code> shared folders.
714</p>
715</div>
716</li>
dac703dd 717<li><a id="org51a37e4"></a>Automatic Updates<br />
3f9df02d
SBS
718<div class="outline-text-5" id="text-1-3-3-2">
719<p>
720The <code>automatic-upgrades</code> package, if installed, should automatically
721install security patches to packages installed via <code>apt</code>.
722</p>
723</div>
724</li>
725</ol>
726</div>
dac703dd
SBS
727<div id="outline-container-org46c0af5" class="outline-4">
728<h4 id="org46c0af5"><span class="section-number-4">1.3.4</span> Normal Shutdown</h4>
3f9df02d
SBS
729<div class="outline-text-4" id="text-1-3-4">
730<p>
731The system may be shutdown via SSH by running:
732</p>
733
734<pre class="example">
735$ sudo shutdown -r 0
736
737</pre>
738</div>
739</div>
740
dac703dd
SBS
741<div id="outline-container-org662e1e8" class="outline-4">
742<h4 id="org662e1e8"><span class="section-number-4">1.3.5</span> Unscheduled Shutdown</h4>
3f9df02d
SBS
743<div class="outline-text-4" id="text-1-3-5">
744<p>
745Ninfacyzga-01 as described and setup should tolerate unscheduled power
746loss. Log files being written every 60 seconds means, at most, 60
747seconds worth of location data may be lost.
748</p>
749</div>
750</div>
dac703dd
SBS
751<div id="outline-container-org70e088c" class="outline-4">
752<h4 id="org70e088c"><span class="section-number-4">1.3.6</span> End of Life Disposal</h4>
3f9df02d
SBS
753<div class="outline-text-4" id="text-1-3-6">
754<p>
755LiPo batteries used by the PiZ Uptime 2.0 module should be disposed of
756properly with their potential ignitability in mind, especially if they
757are not fully discharged.
758</p>
759
760<p>
761Consult your local municipality for its "E-Waste Disposal" (or
762equivalent) policy. Metals used in the Raspberry Pi and related
763components may be recycled.
764</p>
765
766<p>
767Take extra precuation if lead solder was used in assembling the
768electronics. Consumer electronics in early 21st century should use
769lead-free solder.
770</p>
771</div>
772</div>
773</div>
774</div>
dac703dd
SBS
775<div id="footnotes">
776<h2 class="footnotes">Footnotes: </h2>
777<div id="text-footnotes">
778
779<div class="footdef"><sup><a id="fn.1" class="footnum" href="#fnr.1">1</a></sup> <div class="footpara"><p class="footpara">
780Explanation:
781<a href="https://ideaheap.com/2013/07/stopping-sd-card-corruption-on-a-raspberry-pi/">https://ideaheap.com/2013/07/stopping-sd-card-corruption-on-a-raspberry-pi/</a>
782</p></div></div>
783
784<div class="footdef"><sup><a id="fn.2" class="footnum" href="#fnr.2">2</a></sup> <div class="footpara"><p class="footpara">
785Persistant disabling of swap in
786Raspbian 10 Buster:
787<a href="https://www.raspberrypi.org/forums/viewtopic.php?p=1490692&amp;sid=5c596a124b7805d6b10dab8d3d7caf16#p1490692">https://www.raspberrypi.org/forums/viewtopic.php?p=1490692&amp;sid=5c596a124b7805d6b10dab8d3d7caf16#p1490692</a>
788</p></div></div>
789
790
3f9df02d 791</div>
dac703dd 792</div></div>
3f9df02d 793<div id="postamble" class="status">
3f9df02d 794<p class="author">Author: Steven Baltakatei Sandoval</p>
dac703dd 795<p class="date">Created: 2020-06-30 Tue 19:45</p>
3f9df02d
SBS
796<p class="validation"><a href="http://validator.w3.org/check?uri=referer">Validate</a></p>
797</div>
798</body>
799</html>