add esp8266 net preset

Author: ZeroBitsTech

CHANGELOG.md

@@ -8,6 +8,8 @@
 
 ## Unreleased
 
+- Added `ZeroNetProfileEsp8266`, a constrained MQTT-first preset for Wemos / ESP8266.
+- Added optional offline queue gating in `ZeroHttpPump` and `ZeroMqttPump` so constrained boards can refuse backlog when link or transport is down.
 - Added generic compare workloads for `EnvMonitor`, `TelemetryGateway`, and `IndustrialLoop`.
 - Added repeatable ESP32 compare runners plus a cross-target workload compile matrix.
 - Improved telemetry gateway tuning so module throughput rises without queue buildup.

README.md

@@ -104,6 +104,7 @@ The optional network helpers are currently marked **BETA**:
 - `ZeroHttpPump`
 - `ZeroMqttPump`
 - `ZeroWiFiMaintainer`
+- `ZeroNetProfileEsp8266` (recommended constrained starting point for Wemos / ESP8266)
 
 They are already useful and validated on desktop plus ESP32 hardware, but they are still under active tuning for footprint, retry behavior, and cross-board transport quirks. The core runtime is the stable layer; the network helpers should be treated as add-on modules that are ready for evaluation and controlled deployments.
 
@@ -113,6 +114,11 @@ Current target maturity:
 - **ESP8266 / Wemos:** still BETA. Live delivery is real, but timing cost is still under active hardening.
 - **Other supported families:** compile-validated, but network helper maturity should still be treated as evaluation-grade until they receive the same live validation depth.
 
+Recommended board-specific path:
+
+- **ESP32:** use the default network module configs first, then validate against your real endpoint.
+- **ESP8266 / Wemos:** start with `ZeroNetProfileEsp8266`. It is a BETA, MQTT-first constrained preset that disables periodic HTTP dispatch by default and prevents offline queue buildup so constrained boards do not need heavy manual tuning just to stay responsive.
+
 Current best module tradeoff reference (ESP32, `LEAN_NET`, manual pattern vs module pattern):
 
 - RAM overhead: `+408 bytes`

docs/wiki/Beta-Modules.md

@@ -6,6 +6,7 @@ The following optional modules are currently marked **BETA**:
 - `ZeroHttpPump`
 - `ZeroMqttPump`
 - `ZeroTransportMetrics`
+- `ZeroNetProfileEsp8266`
 
 They are already useful and validated on desktop plus ESP32 smoke tests, but they are not yet considered fully field-proven across all transport stacks and all board families.
 
@@ -15,6 +16,10 @@ They are already useful and validated on desktop plus ESP32 smoke tests, but the
 - **ESP8266 / Wemos:** still BETA. Live transport works, but timing cost is still under active hardening.
 - **Other targets:** compile-supported, but network helpers should still be treated as validation targets until they see the same live-network coverage.
 
+Recommended default:
+
+- For constrained ESP8266 boards, start with `ZeroNetProfileEsp8266`. It is a BETA, MQTT-first constrained preset that keeps HTTP degraded by default and rejects offline queueing so the board stays more predictable without hand-tuning every interval.
+
 ## What BETA Means Here
 
 - API shape is usable, but may still tighten as real-world patterns accumulate.

examples/LiveNetworkNode/LiveNetworkNode.ino

@@ -2,6 +2,7 @@
 #include <adapters/PowerSaveLoopAdapter.h>
 #include <modules/net/ZeroHttpPump.h>
 #include <modules/net/ZeroMqttPump.h>
+#include <modules/net/ZeroNetProfileEsp8266.h>
 #include <modules/net/ZeroWiFiMaintainer.h>
 
 #if defined(ARDUINO_ARCH_ESP8266)
@@ -18,17 +19,18 @@
 using zerokernel::Kernel;
 using zerokernel::modules::net::ZeroHttpPump;
 using zerokernel::modules::net::ZeroMqttPump;
+using zerokernel::modules::net::ZeroNetProfileEsp8266;
 using zerokernel::modules::net::ZeroTransportMetrics;
 using zerokernel::modules::net::ZeroWiFiMaintainer;
 
 namespace {
 
 const unsigned long kSamplePeriodUs = 100000UL;
 #if defined(ARDUINO_ARCH_ESP8266)
-const unsigned long kSampleTaskIntervalMs = 100UL;
-const unsigned long kHttpDispatchPeriodMs = 1500UL;
-const unsigned long kMqttDispatchPeriodMs = 1000UL;
-const unsigned long kHttpIoTimeoutMs = 200UL;
+const unsigned long kSampleTaskIntervalMs = ZeroNetProfileEsp8266::kSampleTaskIntervalMs;
+const unsigned long kHttpDispatchPeriodMs = ZeroNetProfileEsp8266::kHttpDispatchPeriodMs;
+const unsigned long kMqttDispatchPeriodMs = ZeroNetProfileEsp8266::kMqttDispatchPeriodMs;
+const unsigned long kHttpIoTimeoutMs = ZeroNetProfileEsp8266::kHttpIoTimeoutMs;
 #else
 const unsigned long kSampleTaskIntervalMs = 1UL;
 const unsigned long kHttpDispatchPeriodMs = 500UL;
@@ -282,7 +284,8 @@ void sampleTask() {
 void dispatchTask() {
   const unsigned long nowMs = millis();
 
-  const bool httpDue = (nowMs - g_lastHttpDispatchAtMs) >= kHttpDispatchPeriodMs;
+  const bool httpDue = kHttpDispatchPeriodMs > 0 &&
+                       (nowMs - g_lastHttpDispatchAtMs) >= kHttpDispatchPeriodMs;
   const bool mqttDue = (nowMs - g_lastMqttDispatchAtMs) >= kMqttDispatchPeriodMs;
 
   if (httpDue && g_httpPump.queuedCount() == 0 && !g_httpPump.isBusy()) {
@@ -403,12 +406,18 @@ void setup() {
   ZeroKernel.subscribeTypedFast(kMqttStateTopic, onTypedState);
 
   ZeroWiFiMaintainer::Config wifiConfig;
+#if defined(ARDUINO_ARCH_ESP8266)
+  wifiConfig = ZeroNetProfileEsp8266::wifiConfig();
+#endif
   wifiConfig.manageCapabilities = true;
   wifiConfig.capabilityMask = Kernel::kCapNetwork;
   wifiConfig.stateTopicKey = kWiFiStateTopic;
   g_wifiMaintainer.begin(ZeroKernel, isWiFiConnected, connectWiFi, disconnectWiFi, wifiConfig);
 
   ZeroHttpPump::Config httpConfig;
+#if defined(ARDUINO_ARCH_ESP8266)
+  httpConfig = ZeroNetProfileEsp8266::httpConfig();
+#endif
   g_httpPump.begin(ZeroKernel,
                    httpConnectStep,
                    httpWriteStep,
@@ -418,6 +427,9 @@ void setup() {
   g_httpPump.setLinkProbe(isWiFiConnected);
 
   ZeroMqttPump::Config mqttConfig;
+#if defined(ARDUINO_ARCH_ESP8266)
+  mqttConfig = ZeroNetProfileEsp8266::mqttConfig();
+#endif
   mqttConfig.stateTopicKey = kMqttStateTopic;
   g_mqttPump.begin(ZeroKernel,
                    mqttLinkProbe,
@@ -428,11 +440,11 @@ void setup() {
   g_mqttPump.setTransportProbe(isWiFiConnected);
 
 #if defined(ARDUINO_ARCH_ESP8266)
-  ZeroKernel.addTask("Sample", sampleTask, 100, 0);
-  ZeroKernel.addTask("WiFiMaint", wifiMaintainerTask, 100, 0);
-  ZeroKernel.addTask("HttpPump", httpPumpTask, 100, 0);
-  ZeroKernel.addTask("MqttPump", mqttPumpTask, 100, 0);
-  ZeroKernel.addTask("Dispatch", dispatchTask, 100, 0);
+  ZeroKernel.addTask("Sample", sampleTask, ZeroNetProfileEsp8266::kSampleTaskIntervalMs, 0);
+  ZeroKernel.addTask("WiFiMaint", wifiMaintainerTask, ZeroNetProfileEsp8266::kWiFiTaskIntervalMs, 0);
+  ZeroKernel.addTask("HttpPump", httpPumpTask, ZeroNetProfileEsp8266::kHttpTaskIntervalMs, 0);
+  ZeroKernel.addTask("MqttPump", mqttPumpTask, ZeroNetProfileEsp8266::kMqttTaskIntervalMs, 0);
+  ZeroKernel.addTask("Dispatch", dispatchTask, ZeroNetProfileEsp8266::kDispatchTaskIntervalMs, 0);
 #else
   ZeroKernel.addTask("Sample", sampleTask, kSampleTaskIntervalMs, 0);
   ZeroKernel.addTask("WiFiMaint", wifiMaintainerTask, 100, kWiFiMaintStartDelayMs);

src/modules/net/ZeroHttpPump.h

@@ -57,6 +57,7 @@ class ZeroHttpPump {
     unsigned long phaseTimeoutMs;
     uint8_t maxRetries;
     bool dropOldestOnFull;
+    bool queueWhenLinkDown;
     bool emitCompletionEvents;
 
     Config()
@@ -79,6 +80,7 @@ class ZeroHttpPump {
 #endif
           maxRetries(2),
           dropOldestOnFull(true),
+          queueWhenLinkDown(true),
           emitCompletionEvents(true) {}
   };
 
@@ -151,6 +153,11 @@ class ZeroHttpPump {
       return false;
     }
 
+    if (!config_.queueWhenLinkDown && linkProbe_ != NULL && !linkProbe_()) {
+      metrics_.recordQueueDrop();
+      return false;
+    }
+
     Request queued = request;
     if (queued.retriesRemaining == 0) {
       queued.retriesRemaining = config_.maxRetries;

src/modules/net/ZeroMqttPump.h

@@ -41,6 +41,7 @@ class ZeroMqttPump {
     unsigned long idleLoopIntervalMs;
     uint8_t maxRetries;
     bool dropOldestOnFull;
+    bool queueWhenTransportDown;
     Kernel::TopicKey stateTopicKey;
 
     Config()
@@ -51,6 +52,7 @@ class ZeroMqttPump {
           idleLoopIntervalMs(250),
           maxRetries(2),
           dropOldestOnFull(true),
+          queueWhenTransportDown(true),
           stateTopicKey(0) {}
   };
 
@@ -121,6 +123,15 @@ class ZeroMqttPump {
       return false;
     }
 
+    if (!config_.queueWhenTransportDown) {
+      const bool transportReady = transportProbe_ != NULL ? transportProbe_()
+                                                          : (connected_ || (linkProbe_ != NULL && linkProbe_()));
+      if (!transportReady) {
+        metrics_.recordQueueDrop();
+        return false;
+      }
+    }
+
     Message message;
     message.topicKey = topicKey;
     message.value = value;

src/modules/net/ZeroNetProfileEsp8266.h

@@ -0,0 +1,66 @@
+#ifndef ZEROKERNEL_MODULES_NET_ZERONETPROFILEESP8266_H
+#define ZEROKERNEL_MODULES_NET_ZERONETPROFILEESP8266_H
+
+#include "ZeroHttpPump.h"
+#include "ZeroMqttPump.h"
+#include "ZeroWiFiMaintainer.h"
+
+namespace zerokernel {
+namespace modules {
+namespace net {
+
+// Recommended constrained-network preset for ESP8266-class boards.
+// This profile intentionally prefers MQTT cadence over aggressive HTTP churn.
+struct ZeroNetProfileEsp8266 {
+  static const unsigned long kSampleTaskIntervalMs = 100UL;
+  static const unsigned long kWiFiTaskIntervalMs = 100UL;
+  static const unsigned long kHttpTaskIntervalMs = 100UL;
+  static const unsigned long kMqttTaskIntervalMs = 100UL;
+  static const unsigned long kDispatchTaskIntervalMs = 100UL;
+  static const unsigned long kReportTaskIntervalMs = 250UL;
+
+  static const unsigned long kHttpDispatchPeriodMs = 0UL;
+  static const unsigned long kMqttDispatchPeriodMs = 1000UL;
+  static const unsigned long kHttpIoTimeoutMs = 200UL;
+
+  static ZeroWiFiMaintainer::Config wifiConfig() {
+    ZeroWiFiMaintainer::Config config;
+    config.pollIntervalMs = 1000UL;
+    config.retryBaseMs = 10000UL;
+    config.retryMaxMs = 30000UL;
+    config.retryJitterMs = 500UL;
+    config.stablePollMultiplier = 4;
+    config.stableThreshold = 6;
+    return config;
+  }
+
+  static ZeroHttpPump::Config httpConfig() {
+    ZeroHttpPump::Config config;
+    config.pollIntervalMs = 100UL;
+    config.retryBaseMs = 700UL;
+    config.retryMaxMs = 3200UL;
+    config.retryJitterMs = 180UL;
+    config.phaseTimeoutMs = 300UL;
+    config.maxRetries = 2;
+    config.queueWhenLinkDown = false;
+    return config;
+  }
+
+  static ZeroMqttPump::Config mqttConfig() {
+    ZeroMqttPump::Config config;
+    config.pollIntervalMs = 150UL;
+    config.retryBaseMs = 600UL;
+    config.retryMaxMs = 3000UL;
+    config.retryJitterMs = 180UL;
+    config.idleLoopIntervalMs = 300UL;
+    config.maxRetries = 2;
+    config.queueWhenTransportDown = false;
+    return config;
+  }
+};
+
+}  // namespace net
+}  // namespace modules
+}  // namespace zerokernel
+
+#endif