0.1.5 add retries to begin() + refactor (#7)

* 0.1.5 add retries to begin() + refactor

.github/workflows/arduino_test_runner.yml

@@ -11,4 +11,3 @@ jobs:
       - uses: actions/checkout@v2
       - uses: Arduino-CI/action@master
           #   Arduino-CI/[email protected]
-

DS18B20_INT.cpp

@@ -1,17 +1,18 @@
 //
 //    FILE: DS18B20_INT.cpp
 //  AUTHOR: [email protected]
-// VERSION: 0.1.3
+// VERSION: 0.1.5
 //    DATE: 2017-07-25
 // PUPROSE: library for DS18B20 temperature sensor - integer only.
 //     URL: https://github.com/RobTillaart/DS18B20_INT
 //
-// HISTORY:
-// 0.1.0    2017-07-25  initial version
-// 0.1.1    2019-
-// 0.1.2    2020-08-05  refactor / sync with DS18B20 
-// 0.1.3    2020-12-20  add arduino-ci + unit test
-// 0.1.4    2021-05-26  add onewire.reset() to begin()
+//  HISTORY:
+//  0.1.0   2017-07-25  initial version
+//  0.1.1   2019-
+//  0.1.2   2020-08-05  refactor / sync with DS18B20 
+//  0.1.3   2020-12-20  add arduino-ci + unit test
+//  0.1.4   2021-05-26  add onewire.reset() to begin()
+//  0.1.5   2021-06-16  add retries param to begin()
 
 
 #include "DS18B20_INT.h"
@@ -21,6 +22,7 @@
 #define READSCRATCH     0xBE
 #define WRITESCRATCH    0x4E
 
+
 // Device resolution
 #define TEMP_9_BIT  0x1F //  9 bit
 
@@ -32,10 +34,10 @@ DS18B20_INT::DS18B20_INT(OneWire* _oneWire)
 }
 
 
-bool DS18B20_INT::begin(void)
+bool DS18B20_INT::begin(uint8_t retries)
 {
   _addresFound = false;
-  for (uint8_t retries = 3; (retries > 0) && (_addresFound == false); retries--)
+  for (uint8_t rtr = retries; (rtr > 0) && (_addresFound == false); rtr--)
   {
     _wire->reset();
     _wire->reset_search();
@@ -83,10 +85,22 @@ int16_t DS18B20_INT::getTempC(void)
   rawTemperature |= _wire->read();
   _wire->reset();
   rawTemperature >>= 4;
-
   if (rawTemperature < -55) return DEVICE_DISCONNECTED;
   return rawTemperature;
 }
 
 
+bool  DS18B20_INT::getAddress(uint8_t* buf)
+{
+  if (_addresFound)
+  {
+    for (uint8_t i = 0; i < 8; i++)
+    {
+      buf[i] = _deviceAddress[i];
+    }
+  }
+  return _addresFound;
+}
+
+
 //  -- END OF FILE --

DS18B20_INT.h

@@ -2,7 +2,7 @@
 //
 //    FILE: DS18B20_INT.h
 //  AUTHOR: [email protected]
-// VERSION: 0.1.4
+// VERSION: 0.1.5
 //    DATE: 2017-07-25
 // PUPROSE: Minimalistic library for DS18B20 temperature sensor
 //          uses only integer math (no float to minimize footprint)
@@ -19,9 +19,14 @@
 //   \---+
 //
 
+
+#define DS18B20_INT_LIB_VERSION     (F("0.1.5"))
+
+
 #include "Arduino.h"
 #include "OneWire.h"
 
+
 // Error Code
 #define DEVICE_DISCONNECTED     -127
 
@@ -31,16 +36,17 @@ typedef uint8_t DeviceAddress[8];
 class DS18B20_INT
 {
 public:
-  explicit DS18B20_INT(OneWire *);
-  bool     begin(void);
-  void     requestTemperatures(void);
-  bool     isConversionComplete(void);
-  int16_t  getTempC(void);
+  explicit  DS18B20_INT(OneWire *);
+  bool      begin(uint8_t retries = 3);
+  void      requestTemperatures(void);
+  int16_t   getTempC(void);
+  bool      isConversionComplete(void);
+  bool      getAddress(uint8_t* buf);
 
 private:
-  uint8_t  _deviceAddress[8];
-  OneWire* _wire;
-  bool     _addresFound;
+  DeviceAddress _deviceAddress;
+  OneWire*      _wire;
+  bool          _addresFound;
 };
 
 //  -- END OF FILE --

README.md

@@ -3,19 +3,25 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/RobTillaart/DS18B20_INT/blob/master/LICENSE)
 [![GitHub release](https://img.shields.io/github/release/RobTillaart/DS18B20_INT.svg?maxAge=3600)](https://github.com/RobTillaart/DS18B20_INT/releases)
 
+
 # DS18B20_INT
 
-Minimalistic library for the DS18B20 temperature sensor.
+Minimalistic library for the DS18B20 temperature sensor - restricted to one sensor per pin.
+
 
-## Description
+## Arduino Temperature Control Library (ATCL)
 
 This DS18B20 library is a minimalistic library for a DS18B20 sensor.
 It will give only temperatures in whole degrees C.
 Goal is to minimize footprint.
 
 If you need more functions or control over the DS18B20 family I refer to the library
 of Miles Burton - https://github.com/milesburton/Arduino-Temperature-Control-Library
-or to 
+
+I'm a great fan of the above library however some time ago I needed to strip it down 
+to save a few dozen bytes. I reworked that minimalistic version into a library and I 
+added a number of Arduino examples to help you get started.
+
 
 ## Interface
 
@@ -24,17 +30,22 @@ mode, no Fahrenheit and no alarm functions. The only feature the class supports
 the asynchronous reading of the temperature by means of three core functions:
 
 - **DS18B20_INT(onewire)** constructor needs a reference to OneWire object.
-- **begin()** resets oneWire and set resolution to 9 bit.  
-returns true if all is OK.
-- **requestTemperatures()** trigger temperature comversion
-- **isConversionComplete()** check if conversion is complete
-- **int16_t readTempC()** returns temperature in whole degrees only. -55..125  
+- **bool begin(uint8_t retries = 3)** resets oneWire and set resolution to 9 bit.  
+returns true if all is OK. there will be a number of retries to connect, default 3. 
+- **void requestTemperatures()** trigger temperature comversion
+- **bool isConversionComplete()** check if conversion is complete
+- **int16_t getTempC()** returns temperature in whole degrees only. -55..125  
 -127 = DEVICE_DISCONNECTED  
 
+- **bool getAddress()** returns true if the sensor is configured (available)
+
+
+
 
 ## Operation
 
 This library supports only one DS18B20 per Arduino/ MCU pin.
+
 ```
     //  BOTTOM VIEW
     //
@@ -44,14 +55,35 @@ This library supports only one DS18B20 per Arduino/ MCU pin.
     //  |  o |  2    DATA
     //  \  o |  3    VCC
     //   \---+
-    //
+
 ```
 
 Connect a pull-up resistor 4.7 KOhm between pin3 and pin2. 
 When the wires are longer this resistor needs to be smaller.
 
 Check examples.
 
+
+### Pull up resistor
+
+An **indicative** table for pull up resistors, (E12 series), to get started.
+
+Note: thicker wires require smaller resistors (typically 1 step in E12 series) 
+
+
+| Length        | - 5.0 Volt  | - 3.3 Volt |
+|--------------:|------------:|----------:|
+| 10cm (4")     | 10K0  | 6K8 |
+| 20cm (8")     |  8K2  | 4K7 |
+| 50cm (20")    |  4K7  | 3K3 | 
+| 100cm (3'4")  |  3K3  | 2K2 | 
+| 200cm (6'8")  |  2K2  | 1K0 | 
+| 500cm (16'8") |  1K0  | \*  |  
+| longer        |    *  | \*  |
+
+\* = no info, smaller 
+
+
 ## Credits
 
 Miles Burton who originally developed the Arduino Temperature Control Library.

examples/DS18B20_INT/DS18B20_INT.ino

@@ -14,6 +14,7 @@ DS18B20_INT sensor(&oneWire);
 
 uint32_t start, stop;
 
+
 void setup()
 {
   Serial.begin(115200);
@@ -40,4 +41,4 @@ void loop()
   delay(1000);
 }
 
-// -- END OF FILE --
+// -- END OF FILE --

examples/DS18B20_getAddress/DS18B20_getAddress.ino

@@ -0,0 +1,60 @@
+//
+//    FILE: DS18B20_getAddress.ino
+//  AUTHOR: Rob Tillaart
+// VERSION: 0.0.1
+// PURPOSE: DS18B20 lib getAddress demo
+//
+// HISTORY:
+// 0.0.1 = 2021-06-16 initial version
+
+
+#include <OneWire.h>
+#include <DS18B20_INT.h>
+
+
+#define ONE_WIRE_BUS 2
+
+OneWire     oneWire(ONE_WIRE_BUS);
+DS18B20_INT sensor(&oneWire);
+
+DeviceAddress da;
+
+
+void setup()
+{
+  Serial.begin(115200);
+  Serial.println(__FILE__);
+  Serial.print("DS18B20_INT_LIB_VERSION: ");
+  Serial.println(DS18B20_INT_LIB_VERSION);
+
+  Serial.print("\ngetAddress: ");
+  Serial.println(sensor.getAddress(da));
+
+  sensor.begin();
+
+  Serial.print("\ngetAddress: ");
+  Serial.println(sensor.getAddress(da));
+
+  if (!sensor.getAddress(da))
+  {
+    Serial.println("No address found!");
+    return;
+  }
+
+  Serial.print("Address: ");
+  for (uint8_t i = 0; i < 8; i++)
+  {
+    if (da[i] < 0x10) Serial.print('0');
+    Serial.print(da[i], HEX);
+  }
+  Serial.println();
+}
+
+
+void loop()
+{
+
+}
+
+
+// -- END OF FILE --

examples/DS18B20_minimum/DS18B20_minimum.ino

@@ -0,0 +1,40 @@
+//
+//    FILE: DS18B20_minimum.ino
+//  AUTHOR: Rob Tillaart
+// VERSION: 0.0.1
+// PURPOSE: most minimal sketch
+//
+// WARNING: this sketch does not wait for isConversionComplete()
+//          and therefor temperature read is probably incorrect
+//          but it is fast and maybe accurate enough...
+//
+// HISTORY:
+// 0.0.1 = 2021-06-16 initial version
+
+
+#include <OneWire.h>
+#include <DS18B20_INT.h>
+
+
+#define ONE_WIRE_BUS 2
+
+OneWire     oneWire(ONE_WIRE_BUS);
+DS18B20_INT sensor(&oneWire);
+
+
+void setup(void)
+{
+  Serial.begin(115200);
+  Serial.println(__FILE__);
+
+  sensor.begin();
+}
+
+
+void loop(void)
+{
+  sensor.requestTemperatures();
+  Serial.println(sensor.getTempC());
+}
+
+// -- END OF FILE --

examples/DS18B20_simple/DS18B20_simple.ino

@@ -0,0 +1,42 @@
+//
+//    FILE: DS18B20_simple.ino
+//  AUTHOR: Rob Tillaart
+// VERSION: 0.0.1
+// PURPOSE: equivalent of DallasTemperature library Simple
+//
+// HISTORY:
+// 0.0.1 = 2021-06-16 initial version
+
+
+#include <OneWire.h>
+#include <DS18B20_INT.h>
+
+
+#define ONE_WIRE_BUS 2
+
+OneWire     oneWire(ONE_WIRE_BUS);
+DS18B20_INT sensor(&oneWire);
+
+
+void setup(void)
+{
+  Serial.begin(115200);
+  Serial.println(__FILE__);
+  Serial.print("DS18B20_INT_LIB_VERSION: ");
+  Serial.println(DS18B20_INT_LIB_VERSION);
+
+  sensor.begin();
+}
+
+
+void loop(void)
+{ 
+  sensor.requestTemperatures();
+
+  while (!sensor.isConversionComplete());  // wait until sensor is ready
+
+  Serial.print("Temp: ");
+  Serial.println(sensor.getTempC());
+}
+
+// -- END OF FILE --

keywords.txt

@@ -9,9 +9,11 @@ begin KEYWORD2
 getTempC	KEYWORD2
 requestTemperatures	KEYWORD2
 isConversionComplete	KEYWORD2
+getAddress	KEYWORD2
 
 
 # Constants (LITERAL1)
+DS18B20_INT_LIB_VERSION	LITERAL1
 DEVICE_DISCONNECTED	LITERAL1