Merge branch 'develop' of https://zdv2.bktei.com/gitweb/ninfacyzga-01 into develop
[EVA-2020-02.git] / doc / temperature / README.org
CommitLineData
036dc86d
SBS
1#+TITLE: Ninfacyzga-1 Temperature Logging
2#+AUTHOR: Steven Baltakatei Sandoval
3#+EMAIL: baltakatei@gmail.com
4* Temperature Logging
5** About
6This 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
c3dcde61 8updated by Steven Baltakatei Sandoval on ~2020-10-27T18:50Z~
036dc86d
SBS
9
10** Narrative
11The ~ninfacyzga-01~ device may log temperature readings from
12temperature sensors attached to it.
13
14Several 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
25Whatever the source, an associated ~python~ script should report the
c3dcde61
SBS
26temperature and associated metadata within a JSON value outputted to
27the script's "stdout" stream and formatted using the following
28standards:
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]].
036dc86d
SBS
44
45In turn, this "stdout" is then piped into the ~bklog~ which takes care
c3dcde61
SBS
46of packaging, encrypting, and appending the stream of JSON lines to a
47timestamped ~tar~ file.
036dc86d
SBS
48
49~cron~ is used to call a single script which performs all of the above
50actions 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~.
c3dcde61
SBS
60*** Output
61**** Simple
62Temperature readings may be recorded into a comma-delimited format:
63
64#+BEGIN_EXAMPLE
6520201027T182039+0000,1603822839,18.37500
6620201027T182041+0000,1603822841,18.43700
6720201027T182043+0000,1603822843,18.43700
6820201027T182045+0000,1603822845,18.43700
69#+END_EXAMPLE
70
71**** JSON-LD log
72A 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
036dc86d
SBS
90
91** Operating Procedures
92*** Initial Startup
93**** Perform initial setup.
94See [[file:../setup/README.org][Main Setup]] procedure.
95**** Install Hardware for temperature logging
c3dcde61
SBS
96***** DS18B20 1-Wire wiring
97The DS18B20 temperature sensor must be connected to the Raspberry Pi's
98GPIO pins through a circuit assembly that contains a "pull-up" 4.7KΩ
99resistor. A circuit diagram may be found [[https://electrosome.com/ds18b20-sensor-raspberry-pi-python/][here]]. The data lead should be
100connected to GPIO pin 4 (physical pin number 7; see [[https://pinout.xyz/][ref]]). Using a
101different GPIO pin will require a slightly different 1-Wire
102configuration.
103
104**** Install Software for temperature logging
105***** DS18B20 1-Wire programming
106The DS18B20 temperature sensor output may be polled by a Python script
107via the Raspberry Pi's "1-Wire" communications protocol.
108
109****** Enabling 1-Wire support
1101-Wire support at GPIO pin 4 is enabled by adding the following lines
111to ~/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
118The temperature sensor output may be manually polled by running the
119following commands:
120
121: sudo modprobe w1-gpio
122: sudo modprobe w1-therm
123: cd /sys/bus/w1/devices/
124
125There 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
131An example of such output will resemble:
132
133#+BEGIN_EXAMPLE
1342a 01 55 05 7f a5 a5 66 76 : crc=76 YES
1352a 01 55 05 7f a5 a5 66 76 t=18625
136#+END_EXAMPLE
137
138The ~YES~ in the first line indicates the 1-Wire protocol is
139functioning. The ~t=18625~ indicates that the DS18B20 sensor is
140detecting the temperature to be ~18.625°C~.
141
142****** Sample script to automatically poll DS18B20 sensor
143
144A sample python script for automatically outputting a stream of
145temperature readings via stdout is explained [[https://pimylifeup.com/raspberry-pi-temperature-sensor/][here]] (along with wiring
146instructions) and found [[https://github.com/pimylifeup/temperature_sensor][here]].
147
148***** Install temperature logging scripts
149Several scripts in this repository should be installed to the local
150user's executable directory at ~$HOME/.local/bin~.
151
152Cron jobs should be configured (via ~$ crontab -e~) to call these
153scripts automatically.
036dc86d 154
c3dcde61 155: [TODO fill me]
036dc86d
SBS
156
157***** Install packages via ~apt~
158Run the following command to install the required packages.
c3dcde61 159: $ sudo apt install [TODO: fill me]
036dc86d
SBS
160
161*** Normal Startup
162*** Normal Operation
163*** Normal Shutdown
164*** Unscheduled Shutdown
165** Appendix A