Why this page matters

This page explains how Examples 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 Examples 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

Full validation sequence

Use this when you need a credible regression pass before publishing numbers or changing docs.

    bash scripts/run_desktop_tests.sh
bash scripts/run_desktop_benchmark.sh --enforce-performance
bash scripts/run_resource_matrix.sh --enforce-budget

Hardware compare pass

Run a focused hardware compare instead of guessing whether a change helped or hurt.

    bash scripts/run_esp32_modules_compare.sh /dev/ttyUSB1
bash scripts/run_esp32_real_project_demo.sh /dev/ttyUSB1

Lean build guard

Lock the build into the intended profile before treating a benchmark or compare as authoritative.

    -DZEROKERNEL_PROFILE_LEAN_NET
-DZEROKERNEL_ENABLE_DIAGNOSTICS=0
-DZEROKERNEL_ENABLE_LEGACY_LABEL_API=0

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

Start from the smallest valid path

Boot the runtime, register the minimum useful task set, and prove that the baseline timing is clean before adding optional layers.

Add one layer, then measure it

Introduce routing, diagnostics, or transport one layer at a time so the cost and payoff remain obvious.

Publish only repeatable results

Update docs, charts, or public claims only after the same workload survives the same validation path more than once.

Reference matrix

Name	What it proves	Output focus
`EnvMonitorNode`	Sampling + filtering + threshold alarm	Lag, misses, alarm trips
`TelemetryGatewayNode`	Queue-heavy HTTP and MQTT style transport flow	Success rate, queue depth, reconnect cadence
`IndustrialLoopNode`	Fast control loop + commands + diagnostics	Lag, safe mode, recoveries
`RealProjectNode`	Mixed network node under realistic cadence	HTTP/MQTT rate, queue health, timing
`8266_zerokernel project`	Sensor + buzzer + direct AP + queued HTTP	Field timing and successful local delivery

How to read the examples

Baseline examples are not “worse on purpose”; they represent manual patterns or blocking loops.
ZeroKernel examples should be compared on the same board, same clock, and same window length.
Transport examples may be synthetic. Use RealProjectNode when you need a more realistic mixed workload.

Examples FAQ

Which example should I copy first?

Pick the example that matches your bottleneck: sensor cadence, gateway throughput, or mixed control behavior.

Why keep both baseline and ZeroKernel examples?

They make the tradeoff measurable and keep claims grounded in an apples-to-apples compare.

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.