interrupts

Author: dizcza

README.md

@@ -1,9 +1,22 @@
 # arduino-esp library for Sensirion SDP3x and SDP8xx series
 
-This repository is tailored specifically for ESP boards and achieves **3X** faster performance.
+ESP-IDF & Arduino friendly implementation of communication with Sensirion differential pressure sensors.
 
-To read the first three bytes (two for diff pressure and one CRC), it takes only 158 us compared to
-450 us of a general-purpose arduino library [SDP3x-Arduino](https://github.com/DataDrake/SDP3x-Arduino).
+Compared to a general-purpose arduino library [SDP3x-Arduino](https://github.com/DataDrake/SDP3x-Arduino), it's:
+
+1. a bit faster (158 vs 170 us) because of the optimized `i2c_master_read_from_device` and `i2c_master_write_from_device` functions. Benchmarks are measured for the 400kHz I2C clock frequency (`Wire.setClock()`).
+2. it has support for interrupt handlers (available for SDP3x sensors only). With interrupts, you can achieve reliable sensor updates at ~2100 Hz frequency. See the [SDP3x\_Interrupts](./examples/SDP3x_Interrupts/SDP3x_Interrupts.ino) demo.
+2. ESP-IDF friendly: run this code either in Arduino or in your favourite ESP-IDF framework. For pure C implementation, refer to [`sdpsensor.c`](https://github.com/dizcza/esp32-sdpsensor/blob/master/main/sdpsensor.c).
+3. DataDrake's implementation has a bug in the reset function. It's fixed here.
+4. Each function returns a descriptive error code defined in [`esp_err.h`](https://github.com/espressif/esp-idf/blob/master/components/esp_common/include/esp_err.h). To check for success, call `if (err == ESP_OK) ...`.
+
+## I2C address
+
+Typical I2C sensor addresses:
+
+* SDP31 & SDP32: `0x21`, `0x22`, `0x23`
+* SDP8x0: `0x25`
+* SDP8x1: `0x26`
 
 ## Usage
 
@@ -26,3 +39,8 @@ Serial output:
 
 If the sensor was working in a continuous mode, prior to executing any I2C commands, it ought to be reset by calling either the `stopContinuous()` or `reset()` function. Note, however, that the `reset` commands are received by *all* I2C peripherals connected to the same I2C line (port), because it employs the `0x00` address, which is the I2C general call address.
 
+
+## Capillary filter
+
+To operate as a differential pressure sensor it must have a mechanical capillary filter attached to one of the ports. A low-pass frequency filter adapts to slowly changing atmospheric pressure, allowing mid- & high-frequency bands of differential pressure to be read from the other open port. Without the filter attached, the difference in pressure will be negligible.
+

examples/SDP3x/SDP3x.ino

@@ -1,13 +1,18 @@
 /**
  * An example to use an SDP3x sensor with an ESP32 board.
  * 
- * Prior setup:
+ * Software setup:
  *   1) install the arduino-esp library
  *   2) select your ESP board in "Tools" -> "Board"
  *   3) select the right port in "Tools" -> "Port"
  *   4) turn on the logs by setting "Tools" -> "Core Debug Level" -> "Info"
+ * Hardware setup:
+ *   1) connect GPIO SDA to pin 19
+ *   2) connect GPIO SCL to pin 23
+ * or change the code appropriately.
  */
 #include "sdpsensor.h"
+#include <Wire.h>
 
 
 /* An SDP sensor instance.
@@ -38,7 +43,8 @@ bool initSensorSingleTrial() {
 void setup() {
   Serial.begin(115200);
   delay(1000); // let serial console settle
-  sdp.initI2C(19, 23);  // same as Wire.begin(SDA, SCL)
+  Wire.begin(19, 23);  // sdp.initI2C() is also possible
+  Wire.setClock(400000);  // (optionally) set I2C frequency to high
 
   // choose how you want to initialize the sensor
   bool success = initSensorSingleTrial();
@@ -60,11 +66,17 @@ void setup() {
 
 
 void loop() {
+  char message[256];
   delay(1000);
   int16_t pressure;
   esp_err_t err = sdp.readDiffPressure(&pressure);
   if (err == ESP_OK) {
     // success; process the 'pressure' here
+    float pressurePa = (float) pressure / sdp.getPressureScale();
+    sprintf(message, "Pressure %d / %d = %.5f Pa", pressure, sdp.getPressureScale(), pressurePa);
+    Serial.println(message);
+  } else {
+    Serial.print("FAILED: ");
+    Serial.println(esp_err_to_name(err));
   }
-  ESP_LOGI("main", "raw pressure: %d, err code: %s", pressure, esp_err_to_name(err));
 }

examples/SDP3x_Interrupts/SDP3x_Interrupts.ino

@@ -0,0 +1,96 @@
+/**
+ * An example to use SDP3x sensor interrupts.
+ * 
+ * Software setup:
+ *   1) install the arduino-esp library
+ *   2) select your ESP board in "Tools" -> "Board"
+ *   3) select the right port in "Tools" -> "Port"
+ *   4) turn on the logs by setting "Tools" -> "Core Debug Level" -> "Info"
+ * Hardware setup:
+ *   1) connect GPIO SDA to pin 19
+ *   2) connect GPIO SCL to pin 23
+ *   3) connect GPIO IRQ to pin 4 (!)
+ * or change the code appropriately.
+ */
+
+#include <Wire.h>
+
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+
+#include "sdpsensor.h"
+
+#define GPIO_IRQ_PIN  4  // SDP3x IRQ pin connected to your board
+
+static TaskHandle_t read_sensor_task_handle;
+
+SDPSensor sdp(0x21);
+
+
+static void IRAM_ATTR sdpsensor_irq_handler() {
+  BaseType_t xHigherPriorityTaskWoken = pdFALSE;
+  vTaskNotifyGiveFromISR(read_sensor_task_handle, &xHigherPriorityTaskWoken);
+
+  /* If xHigherPriorityTaskWoken is now set to pdTRUE then a context switch
+   should be performed to ensure the interrupt returns directly to the highest
+   priority task.  The macro used for this purpose is dependent on the port in
+   use and may be called portEND_SWITCHING_ISR(). */
+  portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
+}
+
+
+static void sdptask_read_sensor() {
+  esp_err_t err;
+  int16_t diff_pressure;
+
+  while (1) {
+    // wait for an interrupt
+    ulTaskNotifyTake(pdTRUE, portMAX_DELAY);
+
+    err = sdp.readDiffPressure(&diff_pressure);
+
+    if (err == ESP_OK) {
+      // send to a receiver here
+    }
+
+    // Note that you should never print here any messages because
+    // printing to serial is VERY slow. It's done for demonstration
+    // purposes here.
+    Serial.print("Raw diff pressure: ");
+    Serial.println(diff_pressure);
+  }
+}
+
+
+void setup() {
+  Serial.begin(115200);
+  delay(1000); // let serial console settle
+  Wire.begin(19, 23);
+
+  // you should be already familiar with this
+  while (sdp.stopContinuous() != ESP_OK);
+  while (sdp.begin() != ESP_OK);
+  while (sdp.startContinuous() != ESP_OK);
+
+  uint32_t modelNumber;
+  sdp.getInfo(&modelNumber, NULL, NULL, NULL);
+  if (!(modelNumber == 31 || modelNumber == 32)) {
+    Serial.println("WARNING! Your SDP sensor does NOT support interrupts!");
+  }
+
+  if (sdp.attachIRQHandler(GPIO_IRQ_PIN, sdpsensor_irq_handler) != ESP_OK) {
+    Serial.println("Failed to hook an interrupt handler. Check the wiring.");
+    return;
+  }
+  
+  // start a task on the second core with the priority '1'
+  xTaskCreatePinnedToCore((TaskFunction_t) sdptask_read_sensor, "sdp_read", 4096, NULL, 1, &read_sensor_task_handle, APP_CPU_NUM);
+
+  // allow the sensor to run the first measurement
+  xTaskNotifyGive(read_sensor_task_handle);
+}
+
+
+void loop() {
+  // sdptask_read_sensor task is running
+}

examples/SDP3x_Watchdog/SDP3x_Watchdog.ino

@@ -3,12 +3,18 @@
  *   with a watchdog that barks each time three errors are
  *   encountered in a row.
  * 
- * Prior setup:
+ * Software setup:
  *   1) install the arduino-esp library
  *   2) select your ESP board in "Tools" -> "Board"
  *   3) select the right port in "Tools" -> "Port"
  *   4) turn on the logs by setting "Tools" -> "Core Debug Level" -> "Info"
+ * Hardware setup:
+ *   1) connect GPIO SDA to pin 19
+ *   2) connect GPIO SCL to pin 23
+ * or change the code appropriately.
  */
+
+#include <Wire.h>
 #include "sdpsensor.h"
 
 
@@ -23,7 +29,7 @@ SDPSensor sdp(0x21);
 uint32_t failsCount = 0;
 
 /* Max SDP successive failed reads before a SW reset */
-const uint32_t maxSuccessiveFailsCount = 3;
+const uint32_t maxSuccessiveFailsCount = 1;
 
 /**
  * Check the error code status of the last read measurement.
@@ -35,31 +41,33 @@ const uint32_t maxSuccessiveFailsCount = 3;
  *
  * @param status - the error code of the last measurement
  */
-void watchdogCheck(esp_err_t status) {
+bool watchdogCheck(esp_err_t status) {
     if (status == ESP_OK) {
         failsCount = 0;
     } else {
         failsCount++;
     }
 
     if (failsCount >= maxSuccessiveFailsCount) {
-        ESP_LOGW("watchdog", "SDPWatchdog barked. Resetting...");
+        Serial.println("SDPWatchdog barked. Resetting...");
         esp_err_t err = ESP_FAIL;
         do {
             err = sdp.reset();  // sdp.stopContinuous() is a safer version
             if (err == ESP_OK) {
                 err = sdp.startContinuous();
             }
         } while (err != ESP_OK);
+        return true;
     }
 
+    return false;
 }
 
 
 void setup() {
   Serial.begin(115200);
   delay(1000); // let serial console settle
-  sdp.initI2C(19, 23);  // same as Wire.begin(SDA, SCL)
+  Wire.begin(19, 23);
 
   // try until succeeds
   while (sdp.stopContinuous() != ESP_OK);  // sdp.reset() is also possible
@@ -69,14 +77,14 @@ void setup() {
 
 
 void loop() {
-  delay(1000);
   int16_t pressure;
-  esp_err_t err = sdp.readDiffPressure(&pressure);
-  ESP_LOGI("sdp", "raw pressure: %d, err code: %s", pressure, esp_err_to_name(err));
+  esp_err_t err;
+
+  do {
+    // read the sensor without delay until the watchdog starts barking ...
+    err = sdp.readDiffPressure(&pressure);
+  } while (!watchdogCheck(err));
 
-  /*
-   *  Optionally, check the last result code.
-   *  If enough errors occur, a software reset is issued.
-   */
-  watchdogCheck(err);
+  // wait & repeat
+  delay(3000);
 }

sdpsensor.cpp

@@ -261,6 +261,33 @@ esp_err_t SDPSensor::reset() {
 }
 
 
+esp_err_t SDPSensor::attachIRQHandler(int irqGPIO, void (*irqHandler)() ) {
+    gpio_config_t irq_io_conf = {
+    		.pin_bit_mask = 1ULL << irqGPIO,            // IRQ pin
+			.mode = GPIO_MODE_INPUT,                    // input mode
+			.pull_up_en = GPIO_PULLUP_ENABLE,           // enable pull-up
+			.pull_down_en = GPIO_PULLDOWN_DISABLE,      // disable pull-down
+			.intr_type = GPIO_INTR_NEGEDGE              // falling edge interrupt
+    };
+    esp_err_t err;
+    err = gpio_config(&irq_io_conf);
+    if (err != ESP_OK) {
+        return err;
+    }
+    // install the GPIO ISR service
+    err = gpio_install_isr_service(0);
+    if (err != ESP_OK) {
+        return err;
+    }
+    // hook an ISR handler for the specific GPIO pin
+    err = gpio_isr_handler_add((gpio_num_t) irqGPIO, (gpio_isr_t) irqHandler, NULL);
+    if (err == ESP_OK) {
+        ESP_LOGI(TAG_SDPSENSOR, "Attached an IRQ handler to GPIO pin %d", irqGPIO);
+    }
+    return err;
+}
+
+
 esp_err_t SDPSensor::readDiffPressure(int16_t *diffPressureRaw) {
     if (!initialized) return ESP_ERR_INVALID_STATE;
 

sdpsensor.h

@@ -8,6 +8,7 @@
 #ifndef SDPSENSOR_H_
 #define SDPSENSOR_H_
 
+#include "esp_err.h"
 #include "driver/i2c.h"
 
 
@@ -105,6 +106,15 @@ class SDPSensor {
          */
         esp_err_t reset();
 
+        /**
+         * Attach the IRQ handler callback to a dedicated GPIO sensor pin.
+         * Only the SDP3x sensor series have an IRQ pin.
+         *
+         * @param irqGPIO     - GPIO interrupt pin number
+         * @param irqHandler  - interrupt handler callback function
+         * @returns the error code (defined in esp_err.h)
+         */
+        esp_err_t attachIRQHandler(int irqGPIO, void (*irqHandler)() );
 
         /**
          * Read the raw (unnormalized) differential pressure value and