Why this page matters
This page explains how Network Modules fits into the wider ZeroKernel execution model, what problem it is meant to solve, and what trade-off you are actually accepting when you use it in production firmware. The goal is not to treat Network Modules as an isolated API call, but to understand where it sits inside bounded scheduling, queue discipline, fault visibility, and profile selection.
Read this topic as an operational contract. Start from the smallest working path, wire it into a lean profile first, and only expand into richer routing, diagnostics, or transport state after you can prove that the timing outcome is still worth the extra flash and RAM. That mindset is what keeps ZeroKernel useful on small boards instead of turning it into another bloated abstraction.
The safest pattern is always the same: define the runtime boundary, keep the hot path short, measure the effect with compare scripts, and only then scale complexity. The examples below are not filler; they show the smallest repeatable patterns you can lift into real firmware when you need clean integration instead of ad-hoc loops.
Three practical patterns
Keep reconnect pacing separate from sensor cadence so link churn does not poison the hot path.
ZeroWiFiMaintainer wifi;
wifi.setBackoff(250, 2000);
wifi.tick(linkIsUp, attemptReconnect);
Queue the work first, then drain it cooperatively instead of letting one POST dominate the loop.
ZeroHttpPump pump;
pump.enqueue(payload);
pump.tick(connectStep, writeStep, finishStep);
Bound publish attempts per tick and read the success rate next to queue depth, not in isolation.
ZeroMqttPump mqtt;
mqtt.enqueue(topicKey, value);
mqtt.tick(connectBroker, publishStep);
What to verify while you use it
- Validate timing before you validate aesthetics. A cleaner API is not a win if fast misses rise.
- Prefer the smallest profile that still matches the workload, then add optional modules only when the measured payoff is obvious.
- Keep callbacks and transport steps bounded so watchdog, panic flow, and queue limits remain meaningful.
Common mistakes that make results misleading
- Do not copy a demo pattern into production firmware without measuring it on the real board and real build profile you plan to ship.
- Do not read success counters without reading queue depth, timing, and workload label next to them.
- Do not enable heavier diagnostics and compatibility flags in a lean target just because the defaults looked convenient.
Recommended working sequence
Boot the runtime, register the minimum useful task set, and prove that the baseline timing is clean before adding optional layers.
Introduce routing, diagnostics, or transport one layer at a time so the cost and payoff remain obvious.
Update docs, charts, or public claims only after the same workload survives the same validation path more than once.
Module map
| Module | Status | Role |
|---|---|---|
ZeroTransportMetrics | Stable enough on ESP32 / BETA on ESP8266 | Counts transport attempts, queue depth, and visible retries. |
ZeroHttpPump | Stable enough on ESP32 / BETA on ESP8266 | Runs HTTP send phases cooperatively instead of one large blocking step. |
ZeroMqttPump | Stable enough on ESP32 / BETA on ESP8266 | Queues and drains publish work with bounded retries. |
ZeroWiFiMaintainer | Stable enough on ESP32 / BETA on ESP8266 | Paces reconnect attempts and broadcasts link state cleanly. |
How to adopt them
- Prove the firmware is stable on core runtime alone first.
- Add the module that directly solves the next bottleneck, not all modules at once.
- Run the compare scripts again and check whether the resource cost is justified by the result.
Module pages
Read the counters, queue depth semantics, and what should stay enabled in lean builds.
ZeroHttpPumpSee the step pump flow, when to use it, and how to read throughput vs fail counts correctly.
ZeroMqttPumpUnderstand bounded publish draining, retries, and queue sizing for device-side brokers.
ZeroWiFiMaintainerSee reconnect pacing, state publication, and how to avoid noisy reconnect loops.
Current target maturity
Right now, the transport layer is strong enough on ESP32 to treat as a practical deployment target after validating against your real endpoint. The same modules still remain BETA on ESP8266 because live transport timing is not yet clean enough across repeated board runs.
BETA here does not mean toy. It means useful, tested, and measured, but still under active tuning for the boards and transport paths that have not yet reached the same consistency as ESP32.
Network modules FAQ
Should every project enable all network modules?
No. Each module is optional by design so the firmware only pays for the transport behavior it needs.
Why can success and fail counts both rise together in synthetic demos?
Because throughput rises and the synthetic workload intentionally injects failures. Read success together with attempts and rate.
What is the safest way to validate this page on real hardware?
Start from the leanest profile that still matches the topic, run the narrowest compare script for this behavior, and only then move to heavier mixed workloads. Do not jump straight to a fully loaded build if the base timing is not yet proven.