Merge pull request #114 from SenaxInc/copilot/add-4ma-20ma-sensor-options

Add 4mA-20mA sensor type options (pressure vs ultrasonic)

Author: dorkmo

TankAlarm-112025-Client-BluesOpta/README.md

@@ -89,6 +89,70 @@ The client creates a default configuration on first boot. You can update configu
 - **Min Inches**: Tank level in inches at minimum sensor value
 - **Max Inches**: Tank level in inches at maximum sensor value
 
+### 4-20mA Current Loop Sensor Configuration
+
+For 4-20mA current loop sensors, two mounting options are supported:
+
+#### Pressure Sensor (Bottom-Mounted)
+Used for sensors like the Dwyer 626-06-CB-P1-E5-S1 (0-5 PSI) mounted near the bottom of the tank.
+
+- **Current Loop Type**: "pressure"
+- **How it works**: Measures the pressure of the liquid column above the sensor
+  - 4mA = Empty tank (0 PSI / no liquid above sensor)
+  - 20mA = Full tank (max PSI / max liquid height)
+- **Sensor Range**: The native measurement range (e.g., 0-5 PSI, 0-2 bar)
+  - `sensorRangeMin`: Minimum value (typically 0)
+  - `sensorRangeMax`: Maximum value (e.g., 5 for 0-5 PSI)
+  - `sensorRangeUnit`: Unit of measurement ("PSI", "bar", etc.)
+- **Sensor Mount Height**: Height of sensor above tank bottom (usually 0-2 inches)
+- **Max Value**: Maximum liquid height the sensor can measure (corresponds to 20mA)
+
+**Example Configuration** (0-5 PSI sensor, 1 PSI per 2.3 ft of water):
+- Sensor mounted 2 inches above tank bottom
+- Max sensor range = 5 PSI = ~138 inches of water
+- Tank height = 120 inches
+- Configuration:
+  - `currentLoopType`: "pressure"
+  - `sensorRangeMin`: 0
+  - `sensorRangeMax`: 5
+  - `sensorRangeUnit`: "PSI"
+  - `sensorMountHeight`: 2.0
+  - `maxValue`: 118.0 (tank height minus mount height: 120 - 2 = 118 inches)
+
+> **Note:** For pressure sensors, set `maxValue` to the tank's usable height minus the sensor mount height. The implementation adds `sensorMountHeight` to the measured value, so `maxValue` should represent the height of liquid *above* the sensor, not the total tank height.
+
+#### Ultrasonic Sensor (Top-Mounted)
+Used for sensors like the Siemens Sitrans LU240 mounted on top of the tank looking down.
+
+- **Current Loop Type**: "ultrasonic"
+- **How it works**: Measures the distance from the sensor to the liquid surface
+  - 4mA = Full tank (liquid close to sensor)
+  - 20mA = Empty tank (liquid far from sensor)
+- **Sensor Range**: The native measurement range (e.g., 0-10 meters, 0-30 feet)
+  - `sensorRangeMin`: Minimum distance (typically 0)
+  - `sensorRangeMax`: Maximum distance (e.g., 10 for 0-10m)
+  - `sensorRangeUnit`: Unit of measurement ("m", "ft", "in", etc.)
+- **Sensor Mount Height**: Distance from sensor to tank bottom when tank is empty
+- **Max Value**: Maximum liquid height (tank capacity)
+
+**Example Configuration** (ultrasonic sensor with 0-10m range on 10-foot tank):
+- Sensor mounted 124 inches above tank bottom (tank is 120 inches + 4 inch clearance)
+- Maximum tank fill level = 120 inches
+- Configuration:
+  - `currentLoopType`: "ultrasonic"
+  - `sensorRangeMin`: 0
+  - `sensorRangeMax`: 10
+  - `sensorRangeUnit`: "m"
+  - `sensorMountHeight`: 124.0
+  - `maxValue`: 120.0
+
+**Calibration Tips for 4-20mA Sensors:**
+1. Record the actual mA output at known liquid levels (empty, half-full, full)
+2. Verify sensor mount height is accurate
+3. Enter the correct sensor native range (as specified in sensor datasheet)
+4. Check for temperature effects on readings
+5. Consider the specific gravity of the liquid (for pressure sensors)
+
 ### Float Switch Configuration (Digital Sensors)
 Float switches can be configured as either normally-open (NO) or normally-closed (NC):
 

TankAlarm-112025-Client-BluesOpta/TankAlarm-112025-Client-BluesOpta.ino

@@ -210,6 +210,14 @@ enum SensorType : uint8_t {
   SENSOR_HALL_EFFECT_RPM = 3
 };
 
+// 4-20mA current loop sensor subtypes
+enum CurrentLoopSensorType : uint8_t {
+  CURRENT_LOOP_PRESSURE = 0,    // Pressure sensor mounted near bottom of tank (e.g., Dwyer 626-06-CB-P1-E5-S1)
+                                // 4mA = empty (0 PSI), 20mA = full (max PSI)
+  CURRENT_LOOP_ULTRASONIC = 1   // Ultrasonic sensor mounted on top of tank (e.g., Siemens Sitrans LU240)
+                                // 4mA = full (sensor close to liquid), 20mA = empty (sensor far from liquid)
+};
+
 // Relay trigger conditions - which alarm type triggers the relay
 enum RelayTrigger : uint8_t {
   RELAY_TRIGGER_ANY = 0,   // Trigger on any alarm (high or low)
@@ -251,6 +259,13 @@ struct TankConfig {
   // Digital sensor (float switch) specific settings
   char digitalTrigger[16]; // 'activated' or 'not_activated' - when to trigger alarm for digital sensors
   char digitalSwitchMode[4]; // 'NO' for normally-open, 'NC' for normally-closed (default: NO)
+  // 4-20mA current loop sensor settings
+  CurrentLoopSensorType currentLoopType; // Pressure (bottom-mounted) or Ultrasonic (top-mounted)
+  float sensorMountHeight; // For ultrasonic: distance from sensor to tank bottom (inches)
+                           // For pressure: height of sensor above tank bottom (inches, usually 0-2)
+  float sensorRangeMin;    // Minimum native sensor range (e.g., 0 for 0-5 PSI or 0-10m)
+  float sensorRangeMax;    // Maximum native sensor range (e.g., 5 for 0-5 PSI, 10 for 0-10m)
+  char sensorRangeUnit[8]; // Unit for sensor range: "PSI", "bar", "m", "ft", "in", etc.
 };
 
 struct ClientConfig {
@@ -633,6 +648,11 @@ static void createDefaultConfig(ClientConfig &cfg) {
   cfg.tanks[0].relayMode = RELAY_MODE_MOMENTARY; // Default: momentary 30 min activation
   cfg.tanks[0].digitalTrigger[0] = '\0'; // Not a digital sensor by default
   strlcpy(cfg.tanks[0].digitalSwitchMode, "NO", sizeof(cfg.tanks[0].digitalSwitchMode)); // Default: normally-open
+  cfg.tanks[0].currentLoopType = CURRENT_LOOP_PRESSURE; // Default: pressure sensor (most common)
+  cfg.tanks[0].sensorMountHeight = 0.0f; // Default: sensor at tank bottom
+  cfg.tanks[0].sensorRangeMin = 0.0f;    // Default: 0 (e.g., 0 PSI or 0 meters)
+  cfg.tanks[0].sensorRangeMax = 5.0f;    // Default: 5 (e.g., 5 PSI for typical pressure sensor)
+  strlcpy(cfg.tanks[0].sensorRangeUnit, "PSI", sizeof(cfg.tanks[0].sensorRangeUnit)); // Default: PSI
 }
 
 static bool loadConfigFromFlash(ClientConfig &cfg) {
@@ -768,6 +788,20 @@ static bool loadConfigFromFlash(ClientConfig &cfg) {
     } else {
       strlcpy(cfg.tanks[i].digitalSwitchMode, "NO", sizeof(cfg.tanks[i].digitalSwitchMode)); // Default: normally-open
     }
+    // Load 4-20mA current loop sensor type (pressure or ultrasonic)
+    const char *currentLoopTypeStr = t["currentLoopType"].as<const char *>();
+    if (currentLoopTypeStr && strcmp(currentLoopTypeStr, "ultrasonic") == 0) {
+      cfg.tanks[i].currentLoopType = CURRENT_LOOP_ULTRASONIC;
+    } else {
+      cfg.tanks[i].currentLoopType = CURRENT_LOOP_PRESSURE; // Default: pressure sensor
+    }
+    // Load sensor mount height (for calibration) - validate non-negative
+    cfg.tanks[i].sensorMountHeight = t["sensorMountHeight"].is<float>() ? fmaxf(0.0f, t["sensorMountHeight"].as<float>()) : 0.0f;
+    // Load sensor native range settings
+    cfg.tanks[i].sensorRangeMin = t["sensorRangeMin"].is<float>() ? t["sensorRangeMin"].as<float>() : 0.0f;
+    cfg.tanks[i].sensorRangeMax = t["sensorRangeMax"].is<float>() ? t["sensorRangeMax"].as<float>() : 5.0f;
+    const char *rangeUnitStr = t["sensorRangeUnit"].as<const char *>();
+    strlcpy(cfg.tanks[i].sensorRangeUnit, rangeUnitStr ? rangeUnitStr : "PSI", sizeof(cfg.tanks[i].sensorRangeUnit));
   }
 
   return true;
@@ -838,6 +872,17 @@ static bool saveConfigToFlash(const ClientConfig &cfg) {
     }
     // Save digital switch mode (NO/NC)
     t["digitalSwitchMode"] = cfg.tanks[i].digitalSwitchMode;
+    // Save 4-20mA current loop sensor type
+    switch (cfg.tanks[i].currentLoopType) {
+      case CURRENT_LOOP_ULTRASONIC: t["currentLoopType"] = "ultrasonic"; break;
+      default: t["currentLoopType"] = "pressure"; break;
+    }
+    // Save sensor mount height (for calibration)
+    t["sensorMountHeight"] = cfg.tanks[i].sensorMountHeight;
+    // Save sensor native range settings
+    t["sensorRangeMin"] = cfg.tanks[i].sensorRangeMin;
+    t["sensorRangeMax"] = cfg.tanks[i].sensorRangeMax;
+    t["sensorRangeUnit"] = cfg.tanks[i].sensorRangeUnit;
   }
 
   #if defined(ARDUINO_OPTA) || defined(ARDUINO_ARCH_MBED)
@@ -895,13 +940,20 @@ static void printHardwareRequirements(const ClientConfig &cfg) {
   bool needsCurrentLoop = false;
   bool needsRelayOutput = false;
   bool needsRpmSensor = false;
+  bool hasPressureSensor = false;
+  bool hasUltrasonicSensor = false;
 
   for (uint8_t i = 0; i < cfg.tankCount; ++i) {
     if (cfg.tanks[i].sensorType == SENSOR_ANALOG) {
       needsAnalogExpansion = true;
     }
     if (cfg.tanks[i].sensorType == SENSOR_CURRENT_LOOP) {
       needsCurrentLoop = true;
+      if (cfg.tanks[i].currentLoopType == CURRENT_LOOP_PRESSURE) {
+        hasPressureSensor = true;
+      } else if (cfg.tanks[i].currentLoopType == CURRENT_LOOP_ULTRASONIC) {
+        hasUltrasonicSensor = true;
+      }
     }
     if (cfg.tanks[i].sensorType == SENSOR_HALL_EFFECT_RPM) {
       needsRpmSensor = true;
@@ -919,6 +971,12 @@ static void printHardwareRequirements(const ClientConfig &cfg) {
   }
   if (needsCurrentLoop) {
     Serial.println(F("Current loop interface required (4-20mA module)"));
+    if (hasPressureSensor) {
+      Serial.println(F("  - Pressure sensor (bottom-mounted, e.g., Dwyer 626-06-CB-P1-E5-S1)"));
+    }
+    if (hasUltrasonicSensor) {
+      Serial.println(F("  - Ultrasonic sensor (top-mounted, e.g., Siemens Sitrans LU240)"));
+    }
   }
   if (needsRpmSensor) {
     Serial.println(F("Hall effect RPM sensor connected to digital input"));
@@ -1280,6 +1338,30 @@ static void applyConfigUpdate(const JsonDocument &doc) {
           strlcpy(gConfig.tanks[i].digitalSwitchMode, "NO", sizeof(gConfig.tanks[i].digitalSwitchMode));
         }
       }
+      // Handle 4-20mA current loop sensor type (pressure or ultrasonic)
+      if (t.containsKey("currentLoopType")) {
+        const char *currentLoopTypeStr = t["currentLoopType"].as<const char *>();
+        if (currentLoopTypeStr && strcmp(currentLoopTypeStr, "ultrasonic") == 0) {
+          gConfig.tanks[i].currentLoopType = CURRENT_LOOP_ULTRASONIC;
+        } else {
+          gConfig.tanks[i].currentLoopType = CURRENT_LOOP_PRESSURE;
+        }
+      }
+      // Handle sensor mount height (for calibration) - validate non-negative
+      if (t.containsKey("sensorMountHeight")) {
+        gConfig.tanks[i].sensorMountHeight = fmaxf(0.0f, t["sensorMountHeight"].as<float>());
+      }
+      // Handle sensor native range settings
+      if (t.containsKey("sensorRangeMin")) {
+        gConfig.tanks[i].sensorRangeMin = t["sensorRangeMin"].as<float>();
+      }
+      if (t.containsKey("sensorRangeMax")) {
+        gConfig.tanks[i].sensorRangeMax = t["sensorRangeMax"].as<float>();
+      }
+      if (t.containsKey("sensorRangeUnit")) {
+        const char *unitStr = t["sensorRangeUnit"].as<const char *>();
+        strlcpy(gConfig.tanks[i].sensorRangeUnit, unitStr ? unitStr : "PSI", sizeof(gConfig.tanks[i].sensorRangeUnit));
+      }
     }
   }
 
@@ -1480,7 +1562,36 @@ static float readTankSensor(uint8_t idx) {
       if (milliamps < 0.0f) {
         return gTankState[idx].currentInches; // keep previous on failure
       }
-      return linearMap(milliamps, 4.0f, 20.0f, 0.0f, cfg.maxValue);
+      
+      // Handle different 4-20mA sensor types
+      float levelInches;
+      if (cfg.currentLoopType == CURRENT_LOOP_ULTRASONIC) {
+        // Ultrasonic sensor mounted on TOP of tank (e.g., Siemens Sitrans LU240)
+        // 4mA = full tank (sensor close to liquid surface)
+        // 20mA = empty tank (sensor far from liquid surface)
+        // sensorMountHeight = distance from sensor to tank bottom when empty
+        // maxValue = tank height (max liquid level)
+        // The sensor measures distance from sensor to liquid surface
+        // Distance at 4mA = 0 (full), Distance at 20mA = sensorMountHeight (empty)
+        float distanceFromSensor = linearMap(milliamps, 4.0f, 20.0f, 0.0f, cfg.sensorMountHeight);
+        levelInches = cfg.sensorMountHeight - distanceFromSensor;
+        // Clamp to valid range (0 to maxValue)
+        if (levelInches < 0.0f) levelInches = 0.0f;
+        if (levelInches > cfg.maxValue) levelInches = cfg.maxValue;
+      } else {
+        // Pressure sensor mounted near BOTTOM of tank (e.g., Dwyer 626-06-CB-P1-E5-S1)
+        // 4mA = empty tank (0 PSI / no liquid above sensor)
+        // 20mA = full tank (max PSI / max liquid height above sensor)
+        // sensorMountHeight = height of sensor above tank bottom (usually 0-2 inches)
+        // maxValue = maximum liquid height the sensor measures (corresponds to max PSI)
+        float rawLevel = linearMap(milliamps, 4.0f, 20.0f, 0.0f, cfg.maxValue);
+        // Add mount height offset (sensor is mounted above tank bottom)
+        levelInches = rawLevel + cfg.sensorMountHeight;
+        // Clamp to valid range (sensorMountHeight to maxValue + sensorMountHeight)
+        if (levelInches < cfg.sensorMountHeight) levelInches = cfg.sensorMountHeight;
+        if (levelInches > cfg.maxValue + cfg.sensorMountHeight) levelInches = cfg.maxValue + cfg.sensorMountHeight;
+      }
+      return levelInches;
     }
     case SENSOR_HALL_EFFECT_RPM: {
       // Hall effect RPM sensor - sample pulses for a few seconds each measurement period