Add levelChangeThreshold config and update sample interval

Introduces a new 'levelChangeThreshold' parameter to client configuration, allowing per-site control of change-based telemetry uploads. Default sample interval is increased from 300 to 1800 seconds across documentation, client, and server code. UI and config handling updated to support the new threshold, with logic to suppress or enable delta-triggered telemetry based on its value.

Author: dorkmo

TankAlarm-112025-Client-BluesOpta/FLEET_IMPLEMENTATION_SUMMARY.md

@@ -149,7 +149,8 @@ The Tank Alarm system has been updated to use **Blues Notehub fleet-based device
   "site": "Tank Farm A",
   "deviceLabel": "Tank-01",
   "serverFleet": "tankalarm-server",
-  "sampleSeconds": 300,
+  "sampleSeconds": 1800,
+  "levelChangeThreshold": 0,
   "reportHour": 5,
   "reportMinute": 0,
   "dailyEmail": "[email protected]",
@@ -170,7 +171,7 @@ The Tank Alarm system has been updated to use **Blues Notehub fleet-based device
 }
 ```
 
-SMS recipients now reside exclusively in the server configuration. Client-side `alarmSms` flags simply signal whether a tank should request SMS escalation when it triggers an alarm.
+SMS recipients now reside exclusively in the server configuration. Client-side `alarmSms` flags simply signal whether a tank should request SMS escalation when it triggers an alarm. The new `levelChangeThreshold` key (in inches) is optional; leave it at `0` to suppress change-based telemetry or set a value via the server console to resume delta-triggered reports for that site.
 
 ### Server Config Example
 ```json

TankAlarm-112025-Client-BluesOpta/MIGRATION_GUIDE.md

@@ -159,7 +159,7 @@ For each client:
 ## Step 7: Verify Communication
 
 1. **Check Telemetry Flow (Client → Server):**
-   - Wait for client to take samples (~5 minutes with default 300s interval)
+   - Wait for client to take samples (~30 minutes with default 1800s interval unless you lowered it)
    - In Notehub, navigate to **Events**
    - Filter by client device
    - Look for notes with format: `fleet.tankalarm-server:telemetry.qi`
@@ -268,11 +268,14 @@ Once verified working:
   "site": "Tank Farm A",
   "deviceLabel": "Tank-01",
   "serverFleet": "tankalarm-server",
-  "sampleSeconds": 300,
+   "sampleSeconds": 1800,
+   "levelChangeThreshold": 0,
   ...
 }
 ```
 
+`levelChangeThreshold` (in inches) lets you opt-in to change-based telemetry per site. Leave it at `0` to disable periodic uploads and rely on alarms/daily reports, or set a threshold (for example `2.5`) via the server UI to resume delta-triggered telemetry.
+
 ### Server Config (LittleFS: /server_config.json)
 
 **Old format:**

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

@@ -96,7 +96,11 @@ static size_t strlcpy(char *dst, const char *src, size_t size) {
 #endif
 
 #ifndef DEFAULT_SAMPLE_SECONDS
-#define DEFAULT_SAMPLE_SECONDS 300
+#define DEFAULT_SAMPLE_SECONDS 1800
+#endif
+
+#ifndef DEFAULT_LEVEL_CHANGE_THRESHOLD_INCHES
+#define DEFAULT_LEVEL_CHANGE_THRESHOLD_INCHES 0.0f
 #endif
 
 #ifndef DEFAULT_REPORT_HOUR
@@ -163,6 +167,7 @@ struct ClientConfig {
   char serverFleet[32]; // Target fleet name for server (e.g., "tankalarm-server")
   char dailyEmail[64];
   uint16_t sampleSeconds;
+  float minLevelChangeInches;
   uint8_t reportHour;
   uint8_t reportMinute;
   uint8_t tankCount;
@@ -369,6 +374,7 @@ static void createDefaultConfig(ClientConfig &cfg) {
   strlcpy(cfg.serverFleet, "tankalarm-server", sizeof(cfg.serverFleet));
   strlcpy(cfg.dailyEmail, "[email protected]", sizeof(cfg.dailyEmail));
   cfg.sampleSeconds = DEFAULT_SAMPLE_SECONDS;
+  cfg.minLevelChangeInches = DEFAULT_LEVEL_CHANGE_THRESHOLD_INCHES;
   cfg.reportHour = DEFAULT_REPORT_HOUR;
   cfg.reportMinute = DEFAULT_REPORT_MINUTE;
   cfg.tankCount = 1;
@@ -416,6 +422,10 @@ static bool loadConfigFromFlash(ClientConfig &cfg) {
   strlcpy(cfg.dailyEmail, doc["dailyEmail"].as<const char *>() ? doc["dailyEmail"].as<const char *>() : "", sizeof(cfg.dailyEmail));
 
   cfg.sampleSeconds = doc["sampleSeconds"].is<uint16_t>() ? doc["sampleSeconds"].as<uint16_t>() : DEFAULT_SAMPLE_SECONDS;
+  cfg.minLevelChangeInches = doc["levelChangeThreshold"].is<float>() ? doc["levelChangeThreshold"].as<float>() : DEFAULT_LEVEL_CHANGE_THRESHOLD_INCHES;
+  if (cfg.minLevelChangeInches < 0.0f) {
+    cfg.minLevelChangeInches = 0.0f;
+  }
   cfg.reportHour = doc["reportHour"].is<uint8_t>() ? doc["reportHour"].as<uint8_t>() : DEFAULT_REPORT_HOUR;
   cfg.reportMinute = doc["reportMinute"].is<uint8_t>() ? doc["reportMinute"].as<uint8_t>() : DEFAULT_REPORT_MINUTE;
 
@@ -455,6 +465,7 @@ static bool saveConfigToFlash(const ClientConfig &cfg) {
   doc["deviceLabel"] = cfg.deviceLabel;
   doc["serverFleet"] = cfg.serverFleet;
   doc["sampleSeconds"] = cfg.sampleSeconds;
+  doc["levelChangeThreshold"] = cfg.minLevelChangeInches;
   doc["reportHour"] = cfg.reportHour;
   doc["reportMinute"] = cfg.reportMinute;
   doc["dailyEmail"] = cfg.dailyEmail;
@@ -739,13 +750,22 @@ static void reinitializeHardware() {
     gTankState[i].sensorFailed = false;
     gTankState[i].lastValidReading = 0.0f;
     gTankState[i].hasLastValidReading = false;
+    gTankState[i].lastReportedInches = -9999.0f;
   }
 
   Serial.println(F("Hardware reinitialized after config update"));
 }
 
+static void resetTelemetryBaselines() {
+  for (uint8_t i = 0; i < MAX_TANKS; ++i) {
+    gTankState[i].lastReportedInches = -9999.0f;
+  }
+}
+
 static void applyConfigUpdate(const JsonDocument &doc) {
   bool hardwareChanged = false;
+  bool telemetryPolicyChanged = false;
+  float previousThreshold = gConfig.minLevelChangeInches;
 
   if (doc.containsKey("site")) {
     strlcpy(gConfig.siteName, doc["site"].as<const char *>(), sizeof(gConfig.siteName));
@@ -759,6 +779,13 @@ static void applyConfigUpdate(const JsonDocument &doc) {
   if (doc.containsKey("sampleSeconds")) {
     gConfig.sampleSeconds = doc["sampleSeconds"].as<uint16_t>();
   }
+  if (doc.containsKey("levelChangeThreshold")) {
+    gConfig.minLevelChangeInches = doc["levelChangeThreshold"].as<float>();
+    if (gConfig.minLevelChangeInches < 0.0f) {
+      gConfig.minLevelChangeInches = 0.0f;
+    }
+    telemetryPolicyChanged = (fabsf(previousThreshold - gConfig.minLevelChangeInches) > 0.0001f);
+  }
   if (doc.containsKey("reportHour")) {
     gConfig.reportHour = doc["reportHour"].as<uint8_t>();
   }
@@ -809,6 +836,8 @@ static void applyConfigUpdate(const JsonDocument &doc) {
 
   if (hardwareChanged) {
     reinitializeHardware();
+  } else if (telemetryPolicyChanged) {
+    resetTelemetryBaselines();
   }
 
   printHardwareRequirements(gConfig);
@@ -1001,8 +1030,11 @@ static void sampleTanks() {
     evaluateAlarms(i);
 
     if (gConfig.tanks[i].enableServerUpload && !gTankState[i].sensorFailed) {
-      float delta = fabs(inches - gTankState[i].lastReportedInches);
-      if (delta >= 0.5f || gTankState[i].lastReportedInches < 0.0f) {
+      const float threshold = gConfig.minLevelChangeInches;
+      const bool needBaseline = (gTankState[i].lastReportedInches < 0.0f);
+      const bool thresholdEnabled = (threshold > 0.0f);
+      const bool changeExceeded = thresholdEnabled && (fabs(inches - gTankState[i].lastReportedInches) >= threshold);
+      if (needBaseline || changeExceeded) {
         sendTelemetry(i, "sample", false);
         gTankState[i].lastReportedInches = inches;
       }

TankAlarm-112025-Server-BluesOpta/FLEET_SETUP.md

@@ -46,7 +46,8 @@ The client configuration file (`/client_config.json` on LittleFS) includes:
   "site": "Tank Farm A",
   "deviceLabel": "Tank-01",
   "serverFleet": "tankalarm-server",
-  "sampleSeconds": 300,
+   "sampleSeconds": 1800,
+   "levelChangeThreshold": 0,
   "reportHour": 5,
   "reportMinute": 0,
   "dailyEmail": "[email protected]",
@@ -70,7 +71,7 @@ The client configuration file (`/client_config.json` on LittleFS) includes:
 }
 ```
 
-Server-managed SMS contacts have been removed from the client schema; per-tank `alarmSms` flags now simply request that the server escalate alerts via its own contact list.
+Server-managed SMS contacts have been removed from the client schema; per-tank `alarmSms` flags now simply request that the server escalate alerts via its own contact list. The `levelChangeThreshold` value (in inches) controls when the client sends change-based telemetry. `0` disables those transmissions, so by default only daily reports and alarms consume data until you enable a per-site threshold via the server console.
 
 **Key field:** `serverFleet` - Must match the server's fleet name in Notehub
 
@@ -126,7 +127,7 @@ The server configuration file (`/server_config.json` on LittleFS) includes:
    - Configuration saved to flash
 
 2. **Monitor telemetry:**
-   - Wait for sample interval (~5 minutes default)
+   - Wait for sample interval (~30 minutes default; lower if you configured a smaller value)
    - Server web UI should show tank levels
    - Check Notehub Events to see note traffic
 

TankAlarm-112025-Server-BluesOpta/SETUP.md

@@ -111,7 +111,8 @@ The server’s intranet dashboard lets you push JSON configuration updates direc
    {
      "client": "dev:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "config": {
-       "sampleSeconds": 600,
+      "sampleSeconds": 1800,
+      "levelChangeThreshold": 0,
        "tanks": [
          {
            "id": "A",

TankAlarm-112025-Server-BluesOpta/TankAlarm-112025-Server-BluesOpta.ino

@@ -473,7 +473,8 @@ static const char CONFIG_GENERATOR_HTML[] PROGMEM = R"HTML(
           <label class="field"><span>Site Name</span><input id="siteName" type="text" placeholder="Site Name" required></label>
           <label class="field"><span>Device Label</span><input id="deviceLabel" type="text" placeholder="Device Label" required></label>
           <label class="field"><span>Server Fleet</span><input id="serverFleet" type="text" value="tankalarm-server"></label>
-          <label class="field"><span>Sample Seconds</span><input id="sampleSeconds" type="number" value="300"></label>
+          <label class="field"><span>Sample Seconds</span><input id="sampleSeconds" type="number" value="1800"></label>
+          <label class="field"><span>Level Change Threshold (in)</span><input id="levelChangeThreshold" type="number" step="0.1" value="0" placeholder="0 = disabled"></label>
           <label class="field"><span>Report Hour</span><input id="reportHour" type="number" value="5"></label>
           <label class="field"><span>Report Minute</span><input id="reportMinute" type="number" value="0"></label>
           <label class="field"><span>Daily Email</span><input id="dailyEmail" type="email"></label>
@@ -639,11 +640,13 @@ static const char CONFIG_GENERATOR_HTML[] PROGMEM = R"HTML(
     }
 
     document.getElementById('downloadBtn').addEventListener('click', () => {
+      const levelChange = parseFloat(document.getElementById('levelChangeThreshold').value);
       const config = {
         site: document.getElementById('siteName').value.trim(),
         deviceLabel: document.getElementById('deviceLabel').value.trim() || 'Client-112025',
         serverFleet: document.getElementById('serverFleet').value.trim() || 'tankalarm-server',
-        sampleSeconds: parseInt(document.getElementById('sampleSeconds').value, 10) || 300,
+        sampleSeconds: parseInt(document.getElementById('sampleSeconds').value, 10) || 1800,
+        levelChangeThreshold: Math.max(0, isNaN(levelChange) ? 0 : levelChange),
         reportHour: parseInt(document.getElementById('reportHour').value, 10) || 5,
         reportMinute: parseInt(document.getElementById('reportMinute').value, 10) || 0,
         dailyEmail: document.getElementById('dailyEmail').value.trim(),
@@ -1771,6 +1774,7 @@ static const char CLIENT_CONSOLE_HTML[] PROGMEM = R"HTML(
           <label class="field"><span>Device Label</span><input id="deviceLabelInput" type="text" placeholder="Device label"></label>
           <label class="field"><span>Server Fleet</span><input id="routeInput" type="text" placeholder="tankalarm-server"></label>
           <label class="field"><span>Sample Seconds</span><input id="sampleSecondsInput" type="number" min="30" step="30"></label>
+          <label class="field"><span>Level Change Threshold (in)</span><input id="levelChangeThresholdInput" type="number" min="0" step="0.1" placeholder="0 = disabled"></label>
           <label class="field"><span>Report Hour (0-23)</span><input id="reportHourInput" type="number" min="0" max="23"></label>
           <label class="field"><span>Report Minute (0-59)</span><input id="reportMinuteInput" type="number" min="0" max="59"></label>
           <label class="field"><span>SMS Primary</span><input id="smsPrimaryInput" type="text" placeholder="+1234567890"></label>
@@ -1886,6 +1890,7 @@ static const char CLIENT_CONSOLE_HTML[] PROGMEM = R"HTML(
         deviceLabel: document.getElementById('deviceLabelInput'),
         route: document.getElementById('routeInput'),
         sampleSeconds: document.getElementById('sampleSecondsInput'),
+        levelChangeThreshold: document.getElementById('levelChangeThresholdInput'),
         reportHour: document.getElementById('reportHourInput'),
         reportMinute: document.getElementById('reportMinuteInput'),
         smsPrimary: document.getElementById('smsPrimaryInput'),
@@ -2214,7 +2219,8 @@ static const char CLIENT_CONSOLE_HTML[] PROGMEM = R"HTML(
           site: client ? (client.site || '') : '',
           deviceLabel: client ? `${((client.site || 'Client')).replace(/\s+/g, '-')}-${client.tank || tankId || 'A'}` : 'Client-112025',
           serverFleet: 'tankalarm-server',
-          sampleSeconds: 300,
+          sampleSeconds: 1800,
+          levelChangeThreshold: 0,
           reportHour: 5,
           reportMinute: 0,
           dailyEmail: serverDefaults.dailyEmail || '',
@@ -2297,7 +2303,8 @@ static const char CLIENT_CONSOLE_HTML[] PROGMEM = R"HTML(
     els.site.value = config.site || '';
     els.deviceLabel.value = config.deviceLabel || '';
     els.route.value = config.serverFleet || '';
-    els.sampleSeconds.value = valueOr(config.sampleSeconds, 300);
+    els.sampleSeconds.value = valueOr(config.sampleSeconds, 1800);
+    els.levelChangeThreshold.value = valueOr(config.levelChangeThreshold, 0);
     els.reportHour.value = valueOr(config.reportHour, 5);
     els.reportMinute.value = valueOr(config.reportMinute, 0);
         els.dailyEmail.value = config.dailyEmail || '';
@@ -2341,7 +2348,8 @@ static const char CLIENT_CONSOLE_HTML[] PROGMEM = R"HTML(
           site: els.site.value.trim(),
           deviceLabel: els.deviceLabel.value.trim(),
           serverFleet: els.route.value.trim() || 'tankalarm-server',
-          sampleSeconds: parseInt(els.sampleSeconds.value, 10) || 300,
+          sampleSeconds: parseInt(els.sampleSeconds.value, 10) || 1800,
+          levelChangeThreshold: Math.max(0, parseFloat(els.levelChangeThreshold.value) || 0),
           reportHour: parseInt(els.reportHour.value, 10) || 5,
           reportMinute: parseInt(els.reportMinute.value, 10) || 0,
           dailyEmail: els.dailyEmail.value.trim(),