Added support for resolution 9-12 bits

Author: mathieucarbou

README.md

@@ -88,8 +88,26 @@ uint32_t getExpirationDelay() const;
 // Register callback for temperature changes
 // "changed" parameter indicates if temperature changed by > 0.3°C
 void listen(DS18ChangeCallback callback);
+
+// Set temperature resolution (9, 10, 11, or 12 bits)
+// Higher resolution = more precise but slower conversion
+// Returns true if successful
+bool setResolution(DS18::Resolution resolution);
+
+// Get current resolution setting
+DS18::Resolution getResolution() const;
+
+// Get conversion time in milliseconds for current resolution
+uint16_t getConversionTime() const;
 ```
 
+**Resolution Options:**
+
+- `RESOLUTION_9_BIT`: 0.5°C precision, 94ms conversion time
+- `RESOLUTION_10_BIT`: 0.25°C precision, 188ms conversion time
+- `RESOLUTION_11_BIT`: 0.125°C precision, 375ms conversion time
+- `RESOLUTION_12_BIT`: 0.0625°C precision, 750ms conversion time (default)
+
 ### Information
 
 ```c++
@@ -232,7 +250,7 @@ void setup() {
     continue;
 
   temp.begin(18);
-  
+
   temp.listen([](float temperature, bool changed) {
     JsonDocument doc;
     temp.toJson(doc.to<JsonObject>());
@@ -260,25 +278,55 @@ void setup() {
     continue;
 
   temp.begin(18);
-  
+
   // Temperature readings expire after 30 seconds
   temp.setExpirationDelay(30);
 }
 
 void loop() {
   temp.read();
-  
+
   if (temp.isValid()) {
     float t = temp.getTemperature().value_or(0);
     Serial.printf("Valid temperature: %.2f°C\n", t);
   } else if (temp.isExpired()) {
     Serial.println("Temperature reading expired!");
   }
-  
+
   delay(2000);
 }
 ```
 
+### Resolution Control
+
+```c++
+#include <MycilaDS18.h>
+
+Mycila::DS18 temp;
+
+void setup() {
+  Serial.begin(115200);
+  while (!Serial)
+    continue;
+
+  temp.begin(18);
+
+  // Set resolution to 10-bit for faster conversion
+  // Trade-off: lower precision but faster readings
+  if (temp.setResolution(Mycila::DS18::Resolution::RESOLUTION_10_BIT)) {
+    Serial.println("Resolution set to 10-bit");
+  }
+
+  Serial.printf("Current resolution: %d-bit\n", 9 + static_cast<int>(temp.getResolution()));
+  Serial.printf("Conversion time: %d ms\n", temp.getConversionTime());
+}
+
+void loop() {
+  temp.read();
+  delay(1000);
+}
+```
+
 ## Advanced Usage
 
 ### Safe Temperature Access with std::optional
@@ -309,6 +357,7 @@ The library includes several examples in the `examples/` folder:
 - **SetAddress**: Using a specific sensor address
 - **MultipleDS18**: Multiple sensors on the same bus
 - **Json**: JSON output support
+- **Resolution**: Controlling sensor resolution for precision/speed trade-offs
 
 ## License
 

docs/index.md

@@ -88,8 +88,26 @@ uint32_t getExpirationDelay() const;
 // Register callback for temperature changes
 // "changed" parameter indicates if temperature changed by > 0.3°C
 void listen(DS18ChangeCallback callback);
+
+// Set temperature resolution (9, 10, 11, or 12 bits)
+// Higher resolution = more precise but slower conversion
+// Returns true if successful
+bool setResolution(DS18::Resolution resolution);
+
+// Get current resolution setting
+DS18::Resolution getResolution() const;
+
+// Get conversion time in milliseconds for current resolution
+uint16_t getConversionTime() const;
 ```
 
+**Resolution Options:**
+
+- `RESOLUTION_9_BIT`: 0.5°C precision, 94ms conversion time
+- `RESOLUTION_10_BIT`: 0.25°C precision, 188ms conversion time
+- `RESOLUTION_11_BIT`: 0.125°C precision, 375ms conversion time
+- `RESOLUTION_12_BIT`: 0.0625°C precision, 750ms conversion time (default)
+
 ### Information
 
 ```c++
@@ -232,7 +250,7 @@ void setup() {
     continue;
 
   temp.begin(18);
-  
+
   temp.listen([](float temperature, bool changed) {
     JsonDocument doc;
     temp.toJson(doc.to<JsonObject>());
@@ -260,25 +278,55 @@ void setup() {
     continue;
 
   temp.begin(18);
-  
+
   // Temperature readings expire after 30 seconds
   temp.setExpirationDelay(30);
 }
 
 void loop() {
   temp.read();
-  
+
   if (temp.isValid()) {
     float t = temp.getTemperature().value_or(0);
     Serial.printf("Valid temperature: %.2f°C\n", t);
   } else if (temp.isExpired()) {
     Serial.println("Temperature reading expired!");
   }
-  
+
   delay(2000);
 }
 ```
 
+### Resolution Control
+
+```c++
+#include <MycilaDS18.h>
+
+Mycila::DS18 temp;
+
+void setup() {
+  Serial.begin(115200);
+  while (!Serial)
+    continue;
+
+  temp.begin(18);
+
+  // Set resolution to 10-bit for faster conversion
+  // Trade-off: lower precision but faster readings
+  if (temp.setResolution(Mycila::DS18::Resolution::RESOLUTION_10_BIT)) {
+    Serial.println("Resolution set to 10-bit");
+  }
+
+  Serial.printf("Current resolution: %d-bit\n", 9 + static_cast<int>(temp.getResolution()));
+  Serial.printf("Conversion time: %d ms\n", temp.getConversionTime());
+}
+
+void loop() {
+  temp.read();
+  delay(1000);
+}
+```
+
 ## Advanced Usage
 
 ### Safe Temperature Access with std::optional
@@ -309,6 +357,7 @@ The library includes several examples in the `examples/` folder:
 - **SetAddress**: Using a specific sensor address
 - **MultipleDS18**: Multiple sensors on the same bus
 - **Json**: JSON output support
+- **Resolution**: Controlling sensor resolution for precision/speed trade-offs
 
 ## License
 

examples/Resolution/Resolution.ino

@@ -0,0 +1,50 @@
+#include <Arduino.h>
+#include <MycilaDS18.h>
+
+Mycila::DS18 temp;
+
+void setup() {
+  Serial.begin(115200);
+  while (!Serial)
+    continue;
+
+  temp.setThreshold(0.0f); // any temperature change will be reported in callback
+
+  temp.listen([](float temperature, bool changed) {
+    if (changed) {
+      Serial.printf("Temperature changed: %f°C\n", temperature);
+    }
+  });
+
+  temp.begin(18);
+
+  Serial.printf("Current resolution: %d-bit\n", static_cast<int>(temp.getResolution()));
+  Serial.printf("Conversion time: %d ms\n", temp.getConversionTime());
+}
+
+uint32_t last = 0;
+uint8_t res = 3; // Mycila::DS18::Resolution::RESOLUTION_12_BIT;
+
+void loop() {
+  if (millis() - last > 10000) {
+    res = (res + 1) % 4;
+    Serial.printf("Changing resolution to %d-bit\n", 9 + res);
+    // Set resolution to 10-bit for faster conversion
+    // Options:
+    // - RESOLUTION_9_BIT:  0.5°C precision,    94ms conversion time
+    // - RESOLUTION_10_BIT: 0.25°C precision,  188ms conversion time
+    // - RESOLUTION_11_BIT: 0.125°C precision, 375ms conversion time
+    // - RESOLUTION_12_BIT: 0.0625°C precision, 750ms conversion time (default)
+    if (!temp.setResolution(static_cast<Mycila::DS18::Resolution>(9 + res))) {
+      Serial.println("Failed to set resolution");
+    }
+
+    Serial.printf("Current resolution: %d-bit\n", static_cast<int>(temp.getResolution()));
+    Serial.printf("Conversion time: %d ms\n", temp.getConversionTime());
+
+    last = millis();
+  }
+
+  temp.read();
+  delay(temp.getConversionTime() + 100);
+}

platformio.ini

@@ -26,7 +26,8 @@ lib_dir = .
 ; src_dir = examples/Search
 ; src_dir = examples/Json
 ; src_dir = examples/SetAddress
-src_dir = examples/MultipleDS18
+; src_dir = examples/MultipleDS18
+src_dir = examples/Resolution
 
 [env:arduino-3]
 platform = https://github.com/pioarduino/platform-espressif32/releases/download/55.03.34/platform-espressif32.zip

src/MycilaDS18.cpp

@@ -148,11 +148,11 @@ bool Mycila::DS18::read() {
   // read is valid, record the time
   _lastTime = millis();
 
-  const bool changed = std::abs(read - _temperature) >= MYCILA_DS18_RELEVANT_TEMPERATURE_CHANGE || !isValid();
+  const bool changed = std::abs(read - _temperature) > _threshold || !isValid();
 
   if (changed) {
     _temperature = read;
-    ESP_LOGD(TAG, "%s 0x%llx @ pin %d: %.2f °C", _name, _deviceAddress, _pin, read);
+    ESP_LOGD(TAG, "%s 0x%llx @ pin %d: %f °C", _name, _deviceAddress, _pin, read);
   }
 
   if (_callback)
@@ -161,6 +161,57 @@ bool Mycila::DS18::read() {
   return true;
 }
 
+bool Mycila::DS18::setResolution(DS18::Resolution resolution) {
+  if (!_enabled)
+    return false;
+
+  std::lock_guard<std::mutex> lock(_mutex);
+
+  OneWire32::Resolution owRes;
+  switch (resolution) {
+    case DS18::Resolution::RESOLUTION_9_BIT:
+      owRes = OneWire32::RESOLUTION_9_BIT;
+      break;
+    case DS18::Resolution::RESOLUTION_10_BIT:
+      owRes = OneWire32::RESOLUTION_10_BIT;
+      break;
+    case DS18::Resolution::RESOLUTION_11_BIT:
+      owRes = OneWire32::RESOLUTION_11_BIT;
+      break;
+    case DS18::Resolution::RESOLUTION_12_BIT:
+      owRes = OneWire32::RESOLUTION_12_BIT;
+      break;
+    default:
+      return false;
+  }
+
+  if (_oneWire->setResolution(_deviceAddress, owRes)) {
+    _resolution = resolution;
+    ESP_LOGI(TAG, "%s 0x%llx @ pin %d: Resolution set to %d-bit (%d ms conversion time)", _name, _deviceAddress, _pin, static_cast<int>(resolution), getConversionTime());
+    return true;
+  }
+
+  return false;
+}
+
+Mycila::DS18::Resolution Mycila::DS18::getResolution() const {
+  return _resolution;
+}
+
+uint16_t Mycila::DS18::getConversionTime() const {
+  switch (_resolution) {
+    case DS18::Resolution::RESOLUTION_9_BIT:
+      return 94;
+    case DS18::Resolution::RESOLUTION_10_BIT:
+      return 188;
+    case DS18::Resolution::RESOLUTION_11_BIT:
+      return 375;
+    case DS18::Resolution::RESOLUTION_12_BIT:
+    default:
+      return 750;
+  }
+}
+
 #ifdef MYCILA_JSON_SUPPORT
 void Mycila::DS18::toJson(const JsonObject& root) const {
   root["enabled"] = _enabled;
@@ -171,5 +222,7 @@ void Mycila::DS18::toJson(const JsonObject& root) const {
   root["temp"] = getTemperature().value_or(0);
   root["time"] = _lastTime;
   root["valid"] = isValid();
+  root["resolution"] = static_cast<int>(_resolution);
+  root["conversion_time"] = getConversionTime();
 }
 #endif