split esp8266 http and mqtt presets

Author: ZeroBitsTech

CHANGELOG.md

@@ -9,6 +9,7 @@
 ## Unreleased
 
 - Added `ZeroNetProfileEsp8266`, a constrained MQTT-first preset for Wemos / ESP8266.
+- Added `ZeroNetProfileEsp8266Http`, an opt-in HTTP-first constrained preset for Wemos / ESP8266 so HTTP and MQTT can be tuned separately instead of forcing one compromise path.
 - Refined `ZeroNetProfileEsp8266` so HTTP stays truly off by default, MQTT idle churn is lower, and the official Wemos live compare now shows MQTT delivery with timing that beats the naive baseline in the same window.
 - Added optional offline queue gating in `ZeroHttpPump` and `ZeroMqttPump` so constrained boards can refuse backlog when link or transport is down.
 - Reduced scheduler contention in the ESP8266 preset by staggering network task start offsets and lowering idle network task cadence.

README.md

@@ -105,6 +105,7 @@ The optional network helpers are currently marked **BETA**:
 - `ZeroMqttPump`
 - `ZeroWiFiMaintainer`
 - `ZeroNetProfileEsp8266` (recommended constrained starting point for Wemos / ESP8266)
+- `ZeroNetProfileEsp8266Http` (opt-in constrained HTTP-first variant 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.
 
@@ -118,6 +119,7 @@ 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 constrained MQTT-first preset that disables periodic HTTP dispatch by default, prevents offline queue buildup, lowers idle MQTT churn, staggers lighter network task cadence, and recommends a lighter idle strategy. In current validation it is the preferred path for Wemos MQTT delivery, while HTTP remains degraded/off by default unless you deliberately opt back in.
+- **ESP8266 / Wemos (HTTP-specific):** use `ZeroNetProfileEsp8266Http` only when your node is intentionally HTTP-first. It keeps the same constrained timing discipline, but does not try to combine HTTP and MQTT in the same default path. Treat it as an opt-in experimental profile until your own endpoint validation confirms live delivery under your Wi-Fi conditions.
 
 Current best module tradeoff reference (ESP32, `LEAN_NET`, manual pattern vs module pattern):
 

docs/wiki/Beta-Modules.md

@@ -19,6 +19,7 @@ They are already useful and validated on desktop plus ESP32 smoke tests, but the
 Recommended default:
 
 - For constrained ESP8266 boards, start with `ZeroNetProfileEsp8266`. It is the recommended MQTT-first constrained preset: HTTP stays degraded/off by default, offline queueing is rejected, idle MQTT churn is lower, and the preset uses a lighter recommended idle strategy plus staggered network task starts so the board stays more predictable without hand-tuning every interval.
+- If your board is intentionally HTTP-first, use `ZeroNetProfileEsp8266Http` as a separate opt-in path. It keeps the constrained timing discipline but avoids pretending that one default cadence can serve HTTP-heavy and MQTT-heavy nodes equally well. Treat it as experimental until your own endpoint validation confirms live delivery.
 
 ## What BETA Means Here
 

examples/LiveNetworkNode/LiveNetworkNode.ino

@@ -3,6 +3,7 @@
 #include <modules/net/ZeroHttpPump.h>
 #include <modules/net/ZeroMqttPump.h>
 #include <modules/net/ZeroNetProfileEsp8266.h>
+#include <modules/net/ZeroNetProfileEsp8266Http.h>
 #include <modules/net/ZeroWiFiMaintainer.h>
 
 #if defined(ARDUINO_ARCH_ESP8266)
@@ -20,21 +21,29 @@ using zerokernel::Kernel;
 using zerokernel::modules::net::ZeroHttpPump;
 using zerokernel::modules::net::ZeroMqttPump;
 using zerokernel::modules::net::ZeroNetProfileEsp8266;
+using zerokernel::modules::net::ZeroNetProfileEsp8266Http;
 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 = ZeroNetProfileEsp8266::kSampleTaskIntervalMs;
-const bool kEnableHttpByDefault = ZeroNetProfileEsp8266::kEnableHttpByDefault;
-const unsigned long kHttpDispatchPeriodMs = ZeroNetProfileEsp8266::kHttpDispatchPeriodMs;
-const unsigned long kMqttDispatchPeriodMs = ZeroNetProfileEsp8266::kMqttDispatchPeriodMs;
-const unsigned long kHttpIoTimeoutMs = ZeroNetProfileEsp8266::kHttpIoTimeoutMs;
+#if defined(ZEROKERNEL_LIVE_ESP8266_HTTP_FIRST)
+typedef ZeroNetProfileEsp8266Http ZeroNetActiveEsp8266Profile;
+#else
+typedef ZeroNetProfileEsp8266 ZeroNetActiveEsp8266Profile;
+#endif
+const unsigned long kSampleTaskIntervalMs = ZeroNetActiveEsp8266Profile::kSampleTaskIntervalMs;
+const bool kEnableHttpByDefault = ZeroNetActiveEsp8266Profile::kEnableHttpByDefault;
+const bool kEnableMqttByDefault = ZeroNetActiveEsp8266Profile::kEnableMqttByDefault;
+const unsigned long kHttpDispatchPeriodMs = ZeroNetActiveEsp8266Profile::kHttpDispatchPeriodMs;
+const unsigned long kMqttDispatchPeriodMs = ZeroNetActiveEsp8266Profile::kMqttDispatchPeriodMs;
+const unsigned long kHttpIoTimeoutMs = ZeroNetActiveEsp8266Profile::kHttpIoTimeoutMs;
 #else
 const unsigned long kSampleTaskIntervalMs = 1UL;
 const bool kEnableHttpByDefault = true;
+const bool kEnableMqttByDefault = true;
 const unsigned long kHttpDispatchPeriodMs = 500UL;
 const unsigned long kMqttDispatchPeriodMs = 500UL;
 const unsigned long kHttpIoTimeoutMs = 500UL;
@@ -305,7 +314,7 @@ void dispatchTask() {
     }
   }
 
-  if (mqttDue) {
+  if (kEnableMqttByDefault && mqttDue) {
     g_lastMqttDispatchAtMs = nowMs;
     if (g_mqttPump.queuedCount() < ZeroMqttPump::kQueueCapacity) {
       g_mqttPump.enqueue(kTelemetryTopic, Kernel::EventValue::fromUnsigned(g_sensorValue), 1);
@@ -404,7 +413,7 @@ void setup() {
 
   ZeroKernel.begin(boardMillis);
 #if defined(ARDUINO_ARCH_ESP8266)
-  ZeroKernel.setIdleStrategy(ZeroNetProfileEsp8266::kRecommendedIdleStrategy);
+  ZeroKernel.setIdleStrategy(ZeroNetActiveEsp8266Profile::kRecommendedIdleStrategy);
 #else
   ZeroKernel.setIdleStrategy(Kernel::kIdleSleep);
 #endif
@@ -413,7 +422,7 @@ void setup() {
 
   ZeroWiFiMaintainer::Config wifiConfig;
 #if defined(ARDUINO_ARCH_ESP8266)
-  wifiConfig = ZeroNetProfileEsp8266::wifiConfig();
+  wifiConfig = ZeroNetActiveEsp8266Profile::wifiConfig();
 #endif
   wifiConfig.manageCapabilities = true;
   wifiConfig.capabilityMask = Kernel::kCapNetwork;
@@ -422,7 +431,7 @@ void setup() {
 
   ZeroHttpPump::Config httpConfig;
 #if defined(ARDUINO_ARCH_ESP8266)
-  httpConfig = ZeroNetProfileEsp8266::httpConfig();
+  httpConfig = ZeroNetActiveEsp8266Profile::httpConfig();
 #endif
   if (kEnableHttpByDefault) {
     g_httpPump.begin(ZeroKernel,
@@ -436,29 +445,33 @@ void setup() {
 
   ZeroMqttPump::Config mqttConfig;
 #if defined(ARDUINO_ARCH_ESP8266)
-  mqttConfig = ZeroNetProfileEsp8266::mqttConfig();
+  mqttConfig = ZeroNetActiveEsp8266Profile::mqttConfig();
 #endif
-  mqttConfig.stateTopicKey = kMqttStateTopic;
-  g_mqttPump.begin(ZeroKernel,
-                   mqttLinkProbe,
-                   mqttConnectStep,
-                   mqttLoopStep,
-                   mqttPublishStep,
-                   mqttConfig);
-  g_mqttPump.setTransportProbe(isWiFiConnected);
+  if (kEnableMqttByDefault) {
+    mqttConfig.stateTopicKey = kMqttStateTopic;
+    g_mqttPump.begin(ZeroKernel,
+                     mqttLinkProbe,
+                     mqttConnectStep,
+                     mqttLoopStep,
+                     mqttPublishStep,
+                     mqttConfig);
+    g_mqttPump.setTransportProbe(isWiFiConnected);
+  }
 
 #if defined(ARDUINO_ARCH_ESP8266)
-  ZeroKernel.addTask("Sample", sampleTask, ZeroNetProfileEsp8266::kSampleTaskIntervalMs, 0);
-  ZeroKernel.addTask("WiFiMaint", wifiMaintainerTask, ZeroNetProfileEsp8266::kWiFiTaskIntervalMs,
-                     ZeroNetProfileEsp8266::kWiFiTaskStartDelayMs);
+  ZeroKernel.addTask("Sample", sampleTask, ZeroNetActiveEsp8266Profile::kSampleTaskIntervalMs, 0);
+  ZeroKernel.addTask("WiFiMaint", wifiMaintainerTask, ZeroNetActiveEsp8266Profile::kWiFiTaskIntervalMs,
+                     ZeroNetActiveEsp8266Profile::kWiFiTaskStartDelayMs);
   if (kEnableHttpByDefault) {
-    ZeroKernel.addTask("HttpPump", httpPumpTask, ZeroNetProfileEsp8266::kHttpTaskIntervalMs,
-                       ZeroNetProfileEsp8266::kHttpTaskStartDelayMs);
+    ZeroKernel.addTask("HttpPump", httpPumpTask, ZeroNetActiveEsp8266Profile::kHttpTaskIntervalMs,
+                       ZeroNetActiveEsp8266Profile::kHttpTaskStartDelayMs);
   }
-  ZeroKernel.addTask("MqttPump", mqttPumpTask, ZeroNetProfileEsp8266::kMqttTaskIntervalMs,
-                     ZeroNetProfileEsp8266::kMqttTaskStartDelayMs);
-  ZeroKernel.addTask("Dispatch", dispatchTask, ZeroNetProfileEsp8266::kDispatchTaskIntervalMs,
-                     ZeroNetProfileEsp8266::kDispatchTaskStartDelayMs);
+  if (kEnableMqttByDefault) {
+    ZeroKernel.addTask("MqttPump", mqttPumpTask, ZeroNetActiveEsp8266Profile::kMqttTaskIntervalMs,
+                       ZeroNetActiveEsp8266Profile::kMqttTaskStartDelayMs);
+  }
+  ZeroKernel.addTask("Dispatch", dispatchTask, ZeroNetActiveEsp8266Profile::kDispatchTaskIntervalMs,
+                     ZeroNetActiveEsp8266Profile::kDispatchTaskStartDelayMs);
 #else
   ZeroKernel.addTask("Sample", sampleTask, kSampleTaskIntervalMs, 0);
   ZeroKernel.addTask("WiFiMaint", wifiMaintainerTask, 100, kWiFiMaintStartDelayMs);
@@ -468,7 +481,7 @@ void setup() {
 #endif
   ZeroKernel.addTask("Report", reportTask,
 #if defined(ARDUINO_ARCH_ESP8266)
-                     ZeroNetProfileEsp8266::kReportTaskIntervalMs,
+                     ZeroNetActiveEsp8266Profile::kReportTaskIntervalMs,
 #else
                      250,
 #endif
@@ -480,7 +493,9 @@ void setup() {
     ZeroKernel.setTaskPriority("HttpPump", Kernel::kPriorityNormal);
   }
 #if defined(ARDUINO_ARCH_ESP8266)
-  ZeroKernel.setTaskPriority("MqttPump", Kernel::kPriorityLow);
+  if (kEnableMqttByDefault) {
+    ZeroKernel.setTaskPriority("MqttPump", Kernel::kPriorityLow);
+  }
   ZeroKernel.setTaskPriority("Dispatch", Kernel::kPriorityLow);
 #else
   ZeroKernel.setTaskPriority("MqttPump", Kernel::kPriorityNormal);

scripts/run_live_network_compare.sh

@@ -5,6 +5,7 @@ ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 ARDUINO_CLI="${ROOT_DIR}/bin/arduino-cli"
 BOARD="${1:-esp32}"
 PORT_OVERRIDE="${2:-}"
+ESP8266_NET_PROFILE="${ESP8266_NET_PROFILE:-mqtt}"
 CAPTURE_HELPER="${ROOT_DIR}/scripts/capture_esp32_serial.py"
 WORK_DIR="${ROOT_DIR}/scripts/.live-network"
 HTTP_STATUS_FILE="${WORK_DIR}/http-status.json"
@@ -127,9 +128,23 @@ MQTT_SUB_PID=$!
 compile_and_upload() {
   local sketch_path="$1"
   local build_log="$2"
+  local extra_flags="-DZEROKERNEL_PROFILE_NETWORK_NODE"
+  if [[ "${BOARD}" == "esp8266" && "${sketch_path}" == "${ROOT_DIR}/examples/LiveNetworkNode" ]]; then
+    case "${ESP8266_NET_PROFILE}" in
+      mqtt|"")
+        ;;
+      http)
+        extra_flags="${extra_flags} -DZEROKERNEL_LIVE_ESP8266_HTTP_FIRST=1"
+        ;;
+      *)
+        echo "Unsupported ESP8266 profile: ${ESP8266_NET_PROFILE}" >&2
+        exit 1
+        ;;
+    esac
+  fi
   "${ARDUINO_CLI}" compile --fqbn "${FQBN}" "${BOARD_OPTIONS[@]}" \
     --library "${ROOT_DIR}" \
-    --build-property "build.extra_flags=-DZEROKERNEL_PROFILE_NETWORK_NODE" \
+    --build-property "build.extra_flags=${extra_flags}" \
     --upload -p "${PORT}" \
     "${sketch_path}" 2>&1 | tee "${build_log}"
 }

src/modules/net/ZeroNetProfileEsp8266.h

@@ -14,6 +14,7 @@ namespace net {
 struct ZeroNetProfileEsp8266 {
   static const uint8_t kRecommendedIdleStrategy = Kernel::kIdleYield;
   static const bool kEnableHttpByDefault = false;
+  static const bool kEnableMqttByDefault = true;
   static const unsigned long kSampleTaskIntervalMs = 100UL;
   static const unsigned long kWiFiTaskIntervalMs = 250UL;
   static const unsigned long kHttpTaskIntervalMs = 250UL;

src/modules/net/ZeroNetProfileEsp8266Http.h

@@ -0,0 +1,75 @@
+#ifndef ZEROKERNEL_MODULES_NET_ZERONETPROFILEESP8266HTTP_H
+#define ZEROKERNEL_MODULES_NET_ZERONETPROFILEESP8266HTTP_H
+
+#include "ZeroHttpPump.h"
+#include "ZeroMqttPump.h"
+#include "ZeroWiFiMaintainer.h"
+
+namespace zerokernel {
+namespace modules {
+namespace net {
+
+// Recommended constrained HTTP-first preset for ESP8266-class boards.
+// This profile keeps HTTP alive without forcing MQTT churn on a board that is
+// already sensitive to transport wake-ups.
+struct ZeroNetProfileEsp8266Http {
+  static const uint8_t kRecommendedIdleStrategy = Kernel::kIdleYield;
+  static const bool kEnableHttpByDefault = true;
+  static const bool kEnableMqttByDefault = false;
+  static const unsigned long kSampleTaskIntervalMs = 100UL;
+  static const unsigned long kWiFiTaskIntervalMs = 250UL;
+  static const unsigned long kHttpTaskIntervalMs = 250UL;
+  static const unsigned long kMqttTaskIntervalMs = 500UL;
+  static const unsigned long kDispatchTaskIntervalMs = 250UL;
+  static const unsigned long kReportTaskIntervalMs = 1000UL;
+
+  static const unsigned long kWiFiTaskStartDelayMs = 25UL;
+  static const unsigned long kHttpTaskStartDelayMs = 75UL;
+  static const unsigned long kMqttTaskStartDelayMs = 125UL;
+  static const unsigned long kDispatchTaskStartDelayMs = 175UL;
+
+  static const unsigned long kHttpDispatchPeriodMs = 1500UL;
+  static const unsigned long kMqttDispatchPeriodMs = 0UL;
+  static const unsigned long kHttpIoTimeoutMs = 200UL;
+
+  static ZeroWiFiMaintainer::Config wifiConfig() {
+    ZeroWiFiMaintainer::Config config;
+    config.pollIntervalMs = 500UL;
+    config.retryBaseMs = 2000UL;
+    config.retryMaxMs = 8000UL;
+    config.retryJitterMs = 250UL;
+    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 = 1;
+    config.queueWhenLinkDown = false;
+    return config;
+  }
+
+  static ZeroMqttPump::Config mqttConfig() {
+    ZeroMqttPump::Config config;
+    config.pollIntervalMs = 100UL;
+    config.retryBaseMs = 600UL;
+    config.retryMaxMs = 3000UL;
+    config.retryJitterMs = 180UL;
+    config.idleLoopIntervalMs = 500UL;
+    config.maxRetries = 2;
+    config.queueWhenTransportDown = false;
+    return config;
+  }
+};
+
+}  // namespace net
+}  // namespace modules
+}  // namespace zerokernel
+
+#endif