doc/temperature/README.org

   1 #+TITLE: Ninfacyzga-1 Temperature Logging
   2 #+AUTHOR: Steven Baltakatei Sandoval
   3 #+EMAIL: baltakatei@gmail.com
   4 * Temperature Logging
   5 ** About
   6 This document was created by Steven Baltakatei Sandoval on
   7 ~2020-10-24T23:37Z~ under a [[https://creativecommons.org/licenses/by-sa/4.0/][Creative Commons BY-SA 4.0 license]]. It was
   8 updated by Steven Baltakatei Sandoval on ~2020-10-27T18:50Z~
   9
  10 ** Narrative
  11 The ~ninfacyzga-01~ device may log temperature readings from
  12 temperature sensors attached to it.
  13
  14 Several types of temperature sensors may be equipped:
  15
  16 - A model DS18B20 digital temperature sensor wired to one of the
  17   Raspberry Pi Zero W's GPIO pins. Temperature readings may be read
  18   via a ~python~ script.
  19
  20 - An Ozzmaker BerryGPS-IMU temperature sensor (ex:
  21   BMP388). Temperature readings may be read from a ~python~ script.
  22
  23 - The Raspberry Pi Zero W's internal temperature CPU sensors
  24
  25 Whatever the source, an associated ~python~ script should report the
  26 temperature and associated metadata within a JSON value outputted to
  27 the script's "stdout" stream and formatted using the following
  28 standards:
  29
  30 - [[https://www.json.org/json-en.html][JSON]] (JavaScript Object Notation): A data-interchange format.
  31
  32 - [[https://jsonlines.org/][JSON Lines]] : A method of formatting JSON values so they may be
  33   streamed using newline characters as separators.
  34
  35 - [[https://www.w3.org/TR/json-ld/][JSON-LD]] (JSON Linked Data): A messaging format capable of encoding
  36   RDF data (ex: RDF triples) in a JSON value.
  37
  38 - [[https://www.w3.org/TR/vocab-ssn/][SSN]] (Semantic Sensor Network Ontology): A namespace for building RDF
  39   graphs describing relationships between various characteristics of a
  40   sensing system (ex: Which sensor made the observation? What kind of
  41   observation was made? Which station was the sensor a part of? Where
  42   was the station? When was an observation made?). An example
  43   application of SSN ontology to NOAA weather data can be found [[https://github.com/anhlt18vn/Semantic2019][here]].
  44
  45 In turn, this "stdout" is then piped into the ~bklog~ which takes care
  46 of packaging, encrypting, and appending the stream of JSON lines to a
  47 timestamped ~tar~ file.
  48
  49 ~cron~ is used to call a single script which performs all of the above
  50 actions at regular time intervals.
  51
  52 ** Description
  53 *** Hardware
  54 - DS18B20 1-Wire Digital Thermometer
  55 - Raspberry Pi Zero W
  56 - Ozzmaker BerryGPS-IMU, Version 3 (see [[https://ozzmaker.com/berrygps-berrygps-imu-quick-start-guide/][ref]]).
  57 *** Software
  58 - [[https://www.raspberrypi.org/downloads/raspberry-pi-os/][Raspberry Pi OS]] : A GNU/Linux operating system derived from
  59   Debian 10. This procedure was developed with version ~August 2020~.
  60 *** Output
  61 **** Simple
  62 Temperature readings may be recorded into a comma-delimited format:
  63
  64 #+BEGIN_EXAMPLE
  65 20201027T182039+0000,1603822839,18.37500
  66 20201027T182041+0000,1603822841,18.43700
  67 20201027T182043+0000,1603822843,18.43700
  68 20201027T182045+0000,1603822845,18.43700
  69 #+END_EXAMPLE
  70
  71 **** JSON-LD log
  72 A typical temperature reading will be formatted thus:
  73
  74 (TODO: Insert example output following JSON-LD, SSN standards)
  75
  76 #+BEGIN_EXAMPLE
  77 {
  78     "@context": {
  79         "sosa": "http://www.w3.org/ns/sosa/",
  80         "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
  81         "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
  82         "xsd": "http://www.w3.org/2001/XMLSchema#"
  83         "ssn": "http://www.w3.org/ns/ssn/"
  84     }
  85     "temperature"
  86 }
  87 #+END_EXAMPLE
  88
  89
  90
  91 ** Operating Procedures
  92 *** Initial Startup
  93 **** Perform initial setup.
  94 See [[file:../setup/README.org][Main Setup]] procedure.
  95 **** Install Hardware for temperature logging
  96 ***** DS18B20 1-Wire wiring
  97 The DS18B20 temperature sensor must be connected to the Raspberry Pi's
  98 GPIO pins through a circuit assembly that contains a "pull-up" 4.7KΩ
  99 resistor. A circuit diagram may be found [[https://electrosome.com/ds18b20-sensor-raspberry-pi-python/][here]]. The data lead should be
 100 connected to GPIO pin 4 (physical pin number 7; see [[https://pinout.xyz/][ref]]). Using a
 101 different GPIO pin will require a slightly different 1-Wire
 102 configuration.
 103
 104 **** Install Software for temperature logging
 105 ***** DS18B20 1-Wire programming
 106 The DS18B20 temperature sensor output may be polled by a Python script
 107 via the Raspberry Pi's "1-Wire" communications protocol.
 108
 109 ****** Enabling 1-Wire support
 110 1-Wire support at GPIO pin 4 is enabled by adding the following lines
 111 to ~/boot/config.txt~:
 112
 113 : # Enable 1-Wire at GPIO 4 (DS18B20 temperature probe)
 114 : dtoverlay=w1-gpio,gpiopin=4
 115
 116 ****** Testing DS18B20 1-Wire availability
 117
 118 The temperature sensor output may be manually polled by running the
 119 following commands:
 120
 121 : sudo modprobe w1-gpio
 122 : sudo modprobe w1-therm
 123 : cd /sys/bus/w1/devices/
 124
 125 There should be a directory with a name resembling
 126 ~28-3c01b556f672~. Enter it and read the ~w1_slave~ file.
 127
 128 : cd 28-3c01b556f672
 129 : cat w1_slave
 130
 131 An example of such output will resemble:
 132
 133 #+BEGIN_EXAMPLE
 134 2a 01 55 05 7f a5 a5 66 76 : crc=76 YES
 135 2a 01 55 05 7f a5 a5 66 76 t=18625
 136 #+END_EXAMPLE
 137
 138 The ~YES~ in the first line indicates the 1-Wire protocol is
 139 functioning.  The ~t=18625~ indicates that the DS18B20 sensor is
 140 detecting the temperature to be ~18.625°C~.
 141
 142 ****** Sample script to automatically poll DS18B20 sensor
 143
 144 A sample python script for automatically outputting a stream of
 145 temperature readings via stdout is explained [[https://pimylifeup.com/raspberry-pi-temperature-sensor/][here]] (along with wiring
 146 instructions) and found [[https://github.com/pimylifeup/temperature_sensor][here]].
 147
 148 ***** Install temperature logging scripts
 149 Several scripts in this repository should be installed to the local
 150 user's executable directory at ~$HOME/.local/bin~.
 151
 152 Cron jobs should be configured (via ~$ crontab -e~) to call these
 153 scripts automatically.
 154
 155 : [TODO fill me]
 156
 157 ***** Install packages via ~apt~
 158 Run the following command to install the required packages.
 159 : $ sudo apt install [TODO: fill me]
 160
 161 *** Normal Startup
 162 *** Normal Operation
 163 *** Normal Shutdown
 164 *** Unscheduled Shutdown
 165 ** Appendix A