Why this page matters
This page explains how Requirements 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 Requirements 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
Use this when you want a clean local source of truth and explicit control over updates.
git clone git@github.com:ZeroBitsTech/ZeroKernel.git
cd ZeroKernel
bash scripts/run_desktop_tests.sh
Start from one bounded task and a visible board clock before you add queue work or network modules.
ZeroKernel.begin(boardMillis);
ZeroKernel.addTask("Sample", sampleTask, 100, 0, true);
ZeroKernel.tick();
Pin the profile in build flags so footprint drift is intentional instead of accidental.
[env:esp32]
platform = espressif32
board = esp32dev
framework = arduino
build_flags =
-DZEROKERNEL_PROFILE_LEAN_NET
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.
Supported targets
| Family | Status | Typical use |
|---|---|---|
| ESP8266 | Validated | Direct AP nodes, lightweight gateways |
| ESP32 | Validated | Mixed workloads, WiFi transport, richer telemetry |
| RP2040 | Compile matrix | Control loops, monitoring nodes |
| STM32 | Compile matrix | Industrial and deterministic control firmware |
Runtime rules
- Tasks must stay bounded. A blocking task can still stall a cooperative runtime.
- The core uses fixed-capacity storage; there is no active-path heap allocation inside the runtime.
- Default timing is based on a millisecond clock source unless a workload-specific high-resolution path is added later.
- Optional network modules are stable enough on ESP32 for production-style evaluation, but they still remain BETA on ESP8266 and should be revalidated on your actual hardware.
Tooling
- Node 20.x is recommended for the docs site and web tooling around the project.
- Arduino CLI or PlatformIO is required for board validation.
- Use the compare scripts exactly as documented so the generated output stays comparable across runs.
Requirements FAQ
Does compile-matrix validation mean the board is fully field-tested?
No. Compile validation proves the build path. Hardware validation still matters for timing and transport behavior.
Is the cooperative model always enough?
No. It is a good fit when bounded tasks are realistic and a full RTOS would be unnecessary overhead.
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.