Merge branch 'develop' of https://zdv2.bktei.com/gitweb/ninfacyzga-01 into develop

[EVA-2020-02.git] / doc / temperature / README.org

diff --git a/doc/temperature/README.org b/doc/temperature/README.org
index f48a44ca931fced6c29e0c40ce0d6d1f44804d27..64b0760a76624d4cf93b5c99b5379d3bfd76c687 100644 (file)
--- a/doc/temperature/README.org
+++ b/doc/temperature/README.org
@@ -5,7 +5,7 @@
 ** About
 This document was created by Steven Baltakatei Sandoval on
 ~2020-10-24T23:37Z~ under a [[https://creativecommons.org/licenses/by-sa/4.0/][Creative Commons BY-SA 4.0 license]]. It was
 ** About
 This document was created by Steven Baltakatei Sandoval on
 ~2020-10-24T23:37Z~ under a [[https://creativecommons.org/licenses/by-sa/4.0/][Creative Commons BY-SA 4.0 license]]. It was

-updated by Steven Baltakatei Sandoval on ~2020-10-24T23:59Z~
+updated by Steven Baltakatei Sandoval on ~2020-10-27T18:50Z~

 
 ** Narrative
 The ~ninfacyzga-01~ device may log temperature readings from
 
 ** Narrative
 The ~ninfacyzga-01~ device may log temperature readings from


@@ -23,12 +23,28 @@ Several types of temperature sensors may be equipped:
 - The Raspberry Pi Zero W's internal temperature CPU sensors
 
 Whatever the source, an associated ~python~ script should report the
 - The Raspberry Pi Zero W's internal temperature CPU sensors
 
 Whatever the source, an associated ~python~ script should report the

-temperature in the form of JSON data sent to the script's standard
-output ("stdout") stream.
+temperature and associated metadata within a JSON value outputted to
+the script's "stdout" stream and formatted using the following
+standards:
+
+- [[https://www.json.org/json-en.html][JSON]] (JavaScript Object Notation): A data-interchange format.
+
+- [[https://jsonlines.org/][JSON Lines]] : A method of formatting JSON values so they may be
+  streamed using newline characters as separators.
+
+- [[https://www.w3.org/TR/json-ld/][JSON-LD]] (JSON Linked Data): A messaging format capable of encoding
+  RDF data (ex: RDF triples) in a JSON value.
+
+- [[https://www.w3.org/TR/vocab-ssn/][SSN]] (Semantic Sensor Network Ontology): A namespace for building RDF
+  graphs describing relationships between various characteristics of a
+  sensing system (ex: Which sensor made the observation? What kind of
+  observation was made? Which station was the sensor a part of? Where
+  was the station? When was an observation made?). An example
+  application of SSN ontology to NOAA weather data can be found [[https://github.com/anhlt18vn/Semantic2019][here]].

 
 In turn, this "stdout" is then piped into the ~bklog~ which takes care
 
 In turn, this "stdout" is then piped into the ~bklog~ which takes care

-of packaging, encrypting, and appending the JSON data to a timestamped
-~tar~ file.
+of packaging, encrypting, and appending the stream of JSON lines to a
+timestamped ~tar~ file.

 
 ~cron~ is used to call a single script which performs all of the above
 actions at regular time intervals.
 
 ~cron~ is used to call a single script which performs all of the above
 actions at regular time intervals.


@@ -41,18 +57,106 @@ actions at regular time intervals.
 *** Software
 - [[https://www.raspberrypi.org/downloads/raspberry-pi-os/][Raspberry Pi OS]] : A GNU/Linux operating system derived from
   Debian 10. This procedure was developed with version ~August 2020~.
 *** Software
 - [[https://www.raspberrypi.org/downloads/raspberry-pi-os/][Raspberry Pi OS]] : A GNU/Linux operating system derived from
   Debian 10. This procedure was developed with version ~August 2020~.

+*** Output
+**** Simple
+Temperature readings may be recorded into a comma-delimited format:
+
+#+BEGIN_EXAMPLE
+20201027T182039+0000,1603822839,18.37500
+20201027T182041+0000,1603822841,18.43700
+20201027T182043+0000,1603822843,18.43700
+20201027T182045+0000,1603822845,18.43700
+#+END_EXAMPLE
+
+**** JSON-LD log
+A typical temperature reading will be formatted thus:
+
+(TODO: Insert example output following JSON-LD, SSN standards)
+
+#+BEGIN_EXAMPLE
+{
+    "@context": {
+        "sosa": "http://www.w3.org/ns/sosa/",
+        "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
+        "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
+        "xsd": "http://www.w3.org/2001/XMLSchema#"
+        "ssn": "http://www.w3.org/ns/ssn/"
+    }
+    "temperature"
+}
+#+END_EXAMPLE
+
+

 
 ** Operating Procedures
 *** Initial Startup
 **** Perform initial setup.
 See [[file:../setup/README.org][Main Setup]] procedure.
 **** Install Hardware for temperature logging
 
 ** Operating Procedures
 *** Initial Startup
 **** Perform initial setup.
 See [[file:../setup/README.org][Main Setup]] procedure.
 **** Install Hardware for temperature logging

+***** DS18B20 1-Wire wiring
+The DS18B20 temperature sensor must be connected to the Raspberry Pi's
+GPIO pins through a circuit assembly that contains a "pull-up" 4.7KΩ
+resistor. A circuit diagram may be found [[https://electrosome.com/ds18b20-sensor-raspberry-pi-python/][here]]. The data lead should be
+connected to GPIO pin 4 (physical pin number 7; see [[https://pinout.xyz/][ref]]). Using a
+different GPIO pin will require a slightly different 1-Wire
+configuration.
+
+**** Install Software for temperature logging
+***** DS18B20 1-Wire programming
+The DS18B20 temperature sensor output may be polled by a Python script
+via the Raspberry Pi's "1-Wire" communications protocol.
+
+****** Enabling 1-Wire support
+1-Wire support at GPIO pin 4 is enabled by adding the following lines
+to ~/boot/config.txt~:
+
+: # Enable 1-Wire at GPIO 4 (DS18B20 temperature probe)
+: dtoverlay=w1-gpio,gpiopin=4
+
+****** Testing DS18B20 1-Wire availability
+
+The temperature sensor output may be manually polled by running the
+following commands:
+
+: sudo modprobe w1-gpio
+: sudo modprobe w1-therm
+: cd /sys/bus/w1/devices/
+
+There should be a directory with a name resembling
+~28-3c01b556f672~. Enter it and read the ~w1_slave~ file.
+
+: cd 28-3c01b556f672
+: cat w1_slave
+
+An example of such output will resemble:
+
+#+BEGIN_EXAMPLE
+2a 01 55 05 7f a5 a5 66 76 : crc=76 YES
+2a 01 55 05 7f a5 a5 66 76 t=18625
+#+END_EXAMPLE
+
+The ~YES~ in the first line indicates the 1-Wire protocol is
+functioning.  The ~t=18625~ indicates that the DS18B20 sensor is
+detecting the temperature to be ~18.625°C~.
+
+****** Sample script to automatically poll DS18B20 sensor
+
+A sample python script for automatically outputting a stream of
+temperature readings via stdout is explained [[https://pimylifeup.com/raspberry-pi-temperature-sensor/][here]] (along with wiring
+instructions) and found [[https://github.com/pimylifeup/temperature_sensor][here]].
+
+***** Install temperature logging scripts
+Several scripts in this repository should be installed to the local
+user's executable directory at ~$HOME/.local/bin~.
+
+Cron jobs should be configured (via ~$ crontab -e~) to call these
+scripts automatically.

 
 

-**** Install Software for temperature loggin
+: [TODO fill me]

 
 ***** Install packages via ~apt~
 Run the following command to install the required packages.
 
 ***** Install packages via ~apt~
 Run the following command to install the required packages.

-: $ sudo apt install [fill me]
+: $ sudo apt install [TODO: fill me]

 
 *** Normal Startup
 *** Normal Operation
 
 *** Normal Startup
 *** Normal Operation