fix(exec/temp):Reduce socket calls for hostname

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

#+TITLE: Ninfacyzga-1 Temperature Logging
#+AUTHOR: Steven Baltakatei Sandoval
#+EMAIL: baltakatei@gmail.com
* Temperature Logging
** 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-27T18:50Z~

** Narrative
The ~ninfacyzga-01~ device may log temperature readings from
temperature sensors attached to it.

Several types of temperature sensors may be equipped:

- A model DS18B20 digital temperature sensor wired to one of the
  Raspberry Pi Zero W's GPIO pins. Temperature readings may be read
  via a ~python~ script.

- An Ozzmaker BerryGPS-IMU temperature sensor (ex:
  BMP388). Temperature readings may be read from a ~python~ script.

- The Raspberry Pi Zero W's internal temperature CPU sensors

Whatever the source, an associated ~python~ script should report the
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
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.

** Description
*** Hardware
- DS18B20 1-Wire Digital Thermometer
- Raspberry Pi Zero W
- Ozzmaker BerryGPS-IMU, Version 3 (see [[https://ozzmaker.com/berrygps-berrygps-imu-quick-start-guide/][ref]]).
*** 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
***** 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.

: [TODO fill me]

***** Install packages via ~apt~
Run the following command to install the required packages.
: $ sudo apt install [TODO: fill me]

*** Normal Startup
*** Normal Operation
*** Normal Shutdown
*** Unscheduled Shutdown
** Appendix A