User Tools

Site Tools


oak:tutorials:onewiretemp

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
oak:tutorials:onewiretemp [2016/03/20 15:14]
exeng Initial DRAFT
oak:tutorials:onewiretemp [2016/03/26 17:17] (current)
bjh [Initialization and Setup()]
Line 1: Line 1:
-====== ​ "THIS TUTORIAL HAS NOT YET BEEN REVIEWED, PLEASE DO NOT USE UNTIL IT HAS" ====== 
-===== This tutorial is currently being edited. Please do not update until this statement has be removed. ===== 
  
  
-======Temperature Sensing and the 1-Wire Bus======+====== ​Oak: Temperature Sensing and the 1-Wire Bus Lesson ​======
  
-This tutorial demonstrates ​how to use the Oak to read temperature data from the DS18B20 1-Wire Digital Thermometer ​and publish that data to the Particle.io Dashboard logIt will also demonstrate how to use the deep sleep capability ​of the Oak platform to minimize power requirements (if desired) between temperature readings.+This lesson will demonstrate ​how to use the Oak to read and publish ​temperature data from the DS18B20 1-Wire Digital Thermometer. 
 + 
 +=====Components Used:​===== 
 + 
 + 
 +^ Part       ^ Quantity ​         ^Identification^ 
 +| Oak with soldered headers |1| | 
 +| Breadboard| 1| | 
 +| One Wire Temperature Sensor TO-92| 1| DS18B20| 
 +| 4.7K Ohm ¼W Resistor| 1| Yellow-Purple-Red| 
 +| Jumper Wires| 6| | 
 + 
 +[NOTE: You can find an index of the parts in the starter and ultimate kits here: [[oak:​tutorials:​kit_parts|Starter and Ultimate Kit Parts List]]]
  
 ===== Concepts: ===== ===== Concepts: =====
  
-  * How to connect a 1-Wire ​DS18B20 digital thermometer ​to the Oak platform. +In this lesson we demonstrate how to connect a 1-Wire ​device ​to the Oak platform ​using the 1-Wire bus compatible DS18B20 Digital ThermometerWe demonstrate the use of a pull-up resistor on the DS18B20 device DQ line (1-Wire Bus Data Input/​Output)And finally, we show you how to publish ​the temperature data received from the device ​to the Particle.io Dashboard log.
-  * How to read DS18S20 temperature data. +
-  * How to publish temperature data to the Particle.io Dashboard log+
-  * How to use deep sleep capabilities of the Oak to minimize power usage between readings.+
  
-===== What's required: ===== 
  
-  - Oak by Digistump [http://​digistump.com/​products/​145] 
-  - An active Particle.io account [https://​www.particle.io/​] 
-  - Your Oak configured with the latest firmware 
-  - Your Oak claimed as a device on your Particle.io account 
-  - A D18B20 1-Wire Digital Thermometer [http://​digistump.com/​products/​57] 
-  - A 4.7K Ohm resister (3.3K and 2.2K can be substituted) 
-  - OneWire library supporting the ESP8622 
  
-===== Connecting the DS18B20 device to the Oak =====+===== Circuit: ​=====  
 +{{:​oak:​tutorials:​ds18b20example.jpg?​direct@300|}}
  
-The 1-Wire DS18B20 digital thermometer can operate at either 3.3 volts or 5 volts. Since the Oak is a 3.3V device, in this tutorial we will use the 3.3V supplied by the Oak's VCC 3.3V pin to power the DS18B20. The DS18B20 Data Input/​Output lead (DQmust be pulled up to 3.3V using a 4.7K resister. ​ While the DS18B20 does support a parasitic modethis will not be demonstrated in this tutorial. Parasitic mode does not require the DS18B20 VDD lead to be connected to external powerbut it does require a strong pullup on the 1-Wire bus. To learn more about operating the DS18B20 in parasitic mode, see the DS18B20 device data sheet (https://​datasheets.maximintegrated.com/​en/​ds/​DS18B20.pdf).+Note the orientation of the leads on the DS18B20 deviceFrom left to right they are: (1GND(2) DQ, (3Vdd.
  
-===== Publishing Temperature Data =====+==== Connecting the DS18B20 device to the Oak ====
  
-The provided example sketch (see below) uses the Particle.io function Particle.publish() to post temperature readings to the particle.io Dashboard logIn order to do this you must have an active Particle.io account, a functional Oak running ​the latest firmware, and that Oak claimed as an active device on Particle.io.+The 1-Wire DS18B20 digital thermometer can operate at either 3.3V or 5V. For this lesson we use the 3.3V supplied by the Oak's VCC 3.3V pin. The DS18B20 Data Input/​Output lead (DQis pulled up to 3.3V by using a 4.7K ohm resister between VCC and the DQ lead.
  
-The actual command used is: +=== Fritzing Diagram ===
-Particle.publish("​Temp (F)", tempFstring,​ 60, PRIVATE); where “Temp(F): is the event name and tempFstring is the actual temperature reading in string format.+
  
-For more information and other examples for how to use the Particle.publish function and other Particle device firmware Cloud functions, see https://​docs.particle.io/​reference/​firmware/​core/​+  - Oak powered through USB or VIN/GND 
 +  - The DS18B20 Vdd lead (3) is powered by Oak's VCC (3.3V) 
 +  - Black wires - Ground connections 
 +  - Red wires - Oak VCC 3.3V 
 +  - White wire – pin 2 to DS18B20 DQ 1-Wire bus lead (2) 
 +  - 4.7K pull-up resister from Oak VCC 3.3V to DS18B20 DQ 1-Wire bus lead (2) 
 +  - DS18B20 GND lead (1) to Oak GND
  
-===== Oak Deep Sleep function =====+If you would like to learn more about the DS18B20 1-Wire device features and capabilities,​ please refer to the Maxim Integrated datasheet for the device. [[https://​datasheets.maximintegrated.com/​en/​ds/​DS18B20.pdf]] ​
  
-The Oak is capable of entering a deep sleep to minimize power requirements. This may be desirable if, for example, your Oak will be battery powered. The provided example sketch demonstrates this mode of operation but will also support operating in a non-sleeping mode.+===== Code: =====
  
-To indicate to the sketch that sleep mode is desired, we use pin 5 (pulled HIGH) as essentially as "​switch"​If pin 5 is HIGH when read in setup(), the sketch operate in sleep mode. This will be considered the default operating mode and as such pin 5 will be defined as INPUT_PULLUP. ​+==== Particle.publish() ====
  
-To facilitate the Oak's deep sleep and wake-up capabilities,​ you must also connect pin 10 (WAKE) ​to the reset (RST) pinThis allows ​the Oak to trigger a RESET after a user specified sleep period has expired. While in sleep mode, the sketch will enter and run setup after each time RESET occursIn this mode it never enters loop().+The Particle.io provides a method to display events ​and data to a Dashboard log that is associated with an active deviceSince the Oak does not support serial output through ​the USB connector, this is convenient and useful way to view your Oak device outputTo take advantage of this functionality,​ you simply need to create an account on Particle.io,​ claim your Oak device there and make sure that it is seen and active on Particle.io. You can find more information for Particle.io here: [[https://​www.particle.io/]]
  
-If you prefer ​to operate ​the Oak in non-sleep mode, or if you want to prevent it from sleeping (when in sleep mode) to allow for new sketch uploads, pin 5 simple ​needs to be connected to ground (GND) thus pulling pin 5 LOWWhen pin 5 is LOW at power up the sketch will not sleep and does enter loop() where it remains ​and repeatedly reads and publishes ​data from the DS18B20 device. This mode consumes more power than does operating in a sleep mode.+Once you are setup on Particle.io,​ publishing data to the log is quite simple. ​The function Particle.publish()allows one to easily send events ​and data to the log.
  
-If pin 5 is HIGH at power up (sleep mode), the example sketch will stay in sleep mode as long as pin 5 remains HIGH. If at anytime pin 5 is pulled LOWthe sketch will enter non-sleep mode following the next RESET. Once in non-sleep modeit will remain in this mode at long as the Oak is powered up regardless of the state of pin 5 (HIGH or LOW).+<​code>​ 
 +Particle.publish("Temp (F)"tempFstring60PRIVATE);  
 +</​code>​
  
 +Where “Temp(F)"​ is the event name and tempFstring is the actual temperature reading in string format.
  
-==== Sleep Mode configuration====+You should see log entries with temperature like this. 
 +{{:oak:​tutorials:​ds18b20particlelog.jpg?​direct&​200|}}
  
-  - Oak powered through USB or VIN/GND +For more information and other examples for how to use the Particle.publish function and other Particle device firmware Cloud functions, see [[https://docs.particle.io/​reference/​firmware/​core/​]]
-  - The DS18B20 is powered by Oak's VCC (3.3V) +
-  - Black wires - Ground connections +
-  - Red wires - VCC 3.3V connections +
-  - Yellow wire - pin 10 (WAKE) ​to RESET (RST) +
-  - White wire – pin 2 to DS18B20 DQ (note4.7K pull-up resister)+
  
-[[oak-temp-sensing-1-wire-bus-1.jpg|{{oak-temp-sensing-1-wire-bus-1.jpg}}]] +==== getTemp() ​==== 
-=== Sleep Mode Configuration ​===+1-Wire bus access and protocol is done by the function getTemp(). This is basically the standard DS18B20 example sketch. The only changes made to getTemp() are the addition of temperature conversion to Fahrenheit and modified return errors to provide additional info for any errors encountered by getTemp(). ​
  
-In Sleep Mode (after reading and publishing ​temperature ​data) the Oak enters deep sleep and delays for a user specified number of seconds. When sleep time has expired, a RESET is triggered via pin 10 (WAKE). Following a RESET, ​the sketch starts ​from the beginning and never enters loop().+<​code>​ 
 +// OneWire DS18B20 ​temperature ​reader with conversion to degrees F 
 +float getTemp()
 +  // Returns ​the temperature ​from a single 1-Wire DS18S20 in DEG Fahrenheit
  
-==== Non-Sleep Mode configuration (or how to prevent Sleep Mode after RESET) ====+  byte data[12]; 
 +  byte addr[8];
  
-  ​- Oak powered through USB or VIN/GND +  ​if !ds.search(addr)) { 
-  - The DS18B20 is powered by Oak's VCC (3.3V+      //no more sensors on chain, reset search 
-  - Black wires - Ground connection +      //​Serial.println("No more addresses."​)
-  - Red wires - VCC 3.3V +      ds.reset_search(); 
-  - Yellow wire - pin 10 (WAKEto RESET (RST+      ​return ​-1000; 
-  White wire – pin 2 to DS18B20 DQ (note: 4.7K pull-up resister) +  ​}
-  ​- Blue wire – pin 5 to GND (ground)+
  
-[[oak-temp-sensing-1-wire-bus-2.jpg|{{oak-temp-sensing-1-wire-bus-2.jpg}}]]+  if ( OneWire::​crc8( addr, 7) != addr[7]) { 
 +      //Serial.println("​CRC is not valid!"​);​ 
 +      return ​-2000; 
 +  ​}
  
-=== Non-Sleep Mode Configuration ===+  if ( addr[0] !0x10 && addr[0] !0x28) { 
 +      //​Serial.print("​Device is not recognized"​);​ 
 +      return ​-3000; 
 +  }
  
-Note the addition of the Blue wire connecting pin 5 to groundIn non-sleep mode the Oak enters setup() and reads pin 5 to determine the desired modeSince pin 5 is pulled to ground ​(LOWthe sketch will enter loop() where it continually requests temperature data from the DS18B20 and publishes that date to the particle.io Dashboard log. Data is requested ​at intervals set by “sleepTimeS” which specifies ​the number of seconds to delay between readings. ​+  ds.reset()
 +  ds.select(addr)
 +  ds.write(0x44,1); // start conversion, with parasite power on at the end
  
-If the Oak was started in Sleep Mode (pin HIGH)it can be forced into non-sleep mode by simply connecting ​pin to groundAt the next wake-up / reset, ​the sketch will see pin 5 high and enter Non-Sleep modeThis mode will allow new sketches ​to be uploaded.+  byte present = ds.reset(); 
 +  ds.select(addr); ​    
 +  ds.write(0xBE);​ // Read Scratchpad 
 + 
 +   
 +  for (int i = 0; i < 9; i++) { // we need 9 bytes 
 +    data[i] = ds.read();​ 
 +  } 
 +   
 +  ds.reset_search();​ 
 +   
 +  byte MSB = data[1]; 
 +  byte LSB = data[0]; 
 + 
 +  float tempRead = ((MSB << 8) | LSB); //using two's compliment 
 +  float TemperatureSum = tempRead / 16; 
 +   
 +  // Convert to degrees Fahrenheit 
 +  TemperatureSum = TemperatureSum * 9 / + 32; 
 +   
 +  return TemperatureSum;​  
 +} //END getTemp() 
 +</​code>​ 
 + 
 +==== Initialization and Setup() ==== 
 + 
 +DS18B20_Pin defines the pin to use for the 1-Wire bus (DQ line). In this example ​it is set to pin 2 but can be changed to any pin that can tolerate being pulled up at power on. 
 + 
 +The OakLEDpin, pin 1 is used to provide a visual output when temperature is being read. 
 + 
 +sleepTimeS specifies ​the delay in seconds between readings. We don't actually sleep but rather simply delay a specified amount of time in seconds before that next temperature update. It's important to keep this relatively coarse as we don't want to flood Particle.io with constant updates to the logFor slow changing inputs, 30 seconds ​to 1 minute is about right but you can easily change this to suit your own needs.
  
 <​code>​ <​code>​
Line 87: Line 132:
   periodic calls to particle.Publish() to log temperature readings.   periodic calls to particle.Publish() to log temperature readings.
   Requires:   Requires:
-   * Particle.io account+   * Particle.io account ​to facilitate temperature output.
    * Digistump Oak with current firmware and active on particle.io    * Digistump Oak with current firmware and active on particle.io
    * DS18B20 OneWire temperature probe    * DS18B20 OneWire temperature probe
Line 95: Line 140:
    * Periodic temperature reads - frequency controlled by sleepTimeS    * Periodic temperature reads - frequency controlled by sleepTimeS
    * Publishes readings to particle.io    * Publishes readings to particle.io
-   * Enters deep sleep to conserve power when Sleep_pin = HIGH  
-     ​WARNING:​ Pin 10-WAKE must be connected to RESET pin for wakeup to occur 
-     else you will enter and endless sleep. 
-   * Watches Sleep_pin to determine whether or not to go into deep sleep. ​ 
-     HIGH = sleep, LOW enters loop() and non sleep mode 
-     NOTE: Non sleep mode allows for new sketch uploads 
 ********************************************************************** **********************************************************************
 */  */ 
 #include <​OneWire.h>​ // Using OneWire lib from the Oak package #include <​OneWire.h>​ // Using OneWire lib from the Oak package
  
-int Sleep_pin = 5;   // (Configure as INPUT_PULLUP to default HIGH) 
 int DS18S20_Pin = 2; // DS18S20 Signal on pin 2 int DS18S20_Pin = 2; // DS18S20 Signal on pin 2
 int OakLEDpin = 1;   // Oak onboard LED pin 1 int OakLEDpin = 1;   // Oak onboard LED pin 1
  
-int sleepTimeS = 30; // 30 seconds - adjust ​needed+int sleepTimeS = 30; // 30 seconds - adjust ​as needed
  
 float tempF = 0;     // Temperature in degrees F float tempF = 0;     // Temperature in degrees F
Line 118: Line 156:
  
 void setup(void) { void setup(void) {
-  pinMode(Sleep_pin,​ INPUT_PULLUP);​ // Use pullup mode to default HIGH 
   pinMode(OakLEDpin,​ OUTPUT);   pinMode(OakLEDpin,​ OUTPUT);
-  
   digitalWrite(OakLEDpin,​HIGH);​ // Turn on onboard LED   digitalWrite(OakLEDpin,​HIGH);​ // Turn on onboard LED
-  ​//Particle.publish("​Oak Setup",​ "​Started",​ 60, PRIVATE);+  Particle.publish("​Oak Setup",​ "​Started",​ 60, PRIVATE);
     ​     ​
   if (!ds.reset()) {   if (!ds.reset()) {
Line 136: Line 172:
      ​Particle.publish("​Temp (F)", tempFstring,​ 60, PRIVATE);      ​Particle.publish("​Temp (F)", tempFstring,​ 60, PRIVATE);
   }   }
-  ​//Particle.publish("​Oak Setup",​ "​Complete",​ 60, PRIVATE); +  Particle.publish("​Oak Setup",​ "​Complete",​ 60, PRIVATE);  ​
-  +
   delay(1000);​ // Pluse stretch onboard LED   delay(1000);​ // Pluse stretch onboard LED
   digitalWrite(OakLEDpin,​LOW);​   digitalWrite(OakLEDpin,​LOW);​
- 
-  // Check to see if sleep mode selected 
-  if (digitalRead(Sleep_pin) == HIGH) { 
-     ​Particle.publish("​Oak Setup",​ "​Entering Deep Sleep",​ 60, PRIVATE); 
-     ​ESP.deepSleep(sleepTimeS*1000000,​ WAKE_RF_DEFAULT);​ // Sleep 
-  } 
-  else { 
-     ​Particle.publish("​Oak Setup","​Entering Non Sleep Mode",​60,​PRIVATE);​ 
-  } 
 } //END setup() } //END setup()
 +</​code>​
  
 +==== Main loop() ====
 +Once we enter loop() the example sketch continues to read temperature from the DS18B20 and publishes the reading and/or errors to the Particle.io Dashboard log. The Oak onboard LED is simply used to provide a visual (local display) of activity. There is a user specified delay between each call to getTemp() to provide course updates to Particle.io.
 +
 +<​code>​
 void loop(void) { void loop(void) {
- +  ​// Get DS18B20 device temperature readings a publish to Particle.io Dashboard log
-  ​// We are here because Non Sleep Mode selected +
-  // Will remains in loop() until reset or power cycle occurs.+
  
   digitalWrite(OakLEDpin,​HIGH);​ // Turn on onboard LED   digitalWrite(OakLEDpin,​HIGH);​ // Turn on onboard LED
Line 169: Line 198:
   digitalWrite(OakLEDpin,​LOW);​ // Turn off onboard LED   digitalWrite(OakLEDpin,​LOW);​ // Turn off onboard LED
  
-  // Delay before next read+  // Delay sleepTimeS number of seconds ​before next read
   for(int i=0; i<​sleepTimeS;​ i++) {   for(int i=0; i<​sleepTimeS;​ i++) {
      ​delay(1000);​ // This delay * sleepTimes slows updates to particle.io log      ​delay(1000);​ // This delay * sleepTimes slows updates to particle.io log
   }   }
 } //END loop() } //END loop()
- 
-// OneWire DS18B20 temperature reader with conversion to degrees F 
-float getTemp(){ 
-  //returns the temperature from one DS18S20 in DEG Fahrenheit 
- 
-  byte data[12]; 
-  byte addr[8]; 
- 
-  if ( !ds.search(addr)) { 
-      //no more sensors on chain, reset search 
-      //​Serial.println("​No more addresses."​);​ 
-      ds.reset_search();​ 
-      return -1000; 
-  } 
- 
-  if ( OneWire::​crc8( addr, 7) != addr[7]) { 
-      //​Serial.println("​CRC is not valid!"​);​ 
-      return -2000; 
-  } 
- 
-  if ( addr[0] != 0x10 && addr[0] != 0x28) { 
-      //​Serial.print("​Device is not recognized"​);​ 
-      return -3000; 
-  } 
- 
-  ds.reset(); 
-  ds.select(addr);​ 
-  ds.write(0x44,​1);​ // start conversion, with parasite power on at the end 
- 
-  byte present = ds.reset(); 
-  ds.select(addr); ​   ​ 
-  ds.write(0xBE);​ // Read Scratchpad 
- 
-  ​ 
-  for (int i = 0; i < 9; i++) { // we need 9 bytes 
-    data[i] = ds.read(); 
-  } 
-  ​ 
-  ds.reset_search();​ 
-  ​ 
-  byte MSB = data[1]; 
-  byte LSB = data[0]; 
- 
-  float tempRead = ((MSB << 8) | LSB); //using two's compliment 
-  float TemperatureSum = tempRead / 16; 
-  ​ 
-  // Convert to degrees Fahrenheit 
-  TemperatureSum = TemperatureSum * 9 / 5 + 32; 
-  ​ 
-  return TemperatureSum; ​ 
-} //END getTemp() 
 </​code>​ </​code>​
  
-===== Conclusion ===== +===== Conclusion===== 
- +In this lesson we demonstrated how to connect ​a 1-Wire device to the Oak and read temperature data from a 1-Wire ​DS18B20 ​digital ​thermometer. ​We also demonstrated ​how to publish ​that data to the Particle.io Dashboard log. We hope that you found this lesson to be both useful and informative. If you would like to explore ​the 1-Wire bus protocols and other 1-Wire devices, a simple search should yield plenty ​of useful information,​ tutorials and examplesAs for the DS18B20 Digital Thermometerwhy not drop a waterproof version of the device into your pool and have it tell you when the water is fine or simply use it as the basis for home grown weather station. 
- + 
-This tutorial has demonstrated how to connect and read temperature data from the DS18B20 thermometer. ​It provided an example of how to publish data to the Particle.io Dashboard log. And finally, it demonstrated ​the deep sleep capabilities ​of the Oak +
- +
-While the example sketch may be more complicated that necessary, the hope is that it has served ​as a useful example for creating new sketches with the Oak platform. Feel free to use and modify this example to  create your own sketches using the concepts demonstrated here.+
  
-Finally, we hope that you have found this tutorial to be both useful and informative. 
oak/tutorials/onewiretemp.1458512059.txt.gz · Last modified: 2016/03/20 15:14 by exeng