Documentation, usage, and integration

Why this page matters

This page explains how Documentation, usage, and integration 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 Documentation, usage, and integration 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

    git clone git@github.com:ZeroBitsTech/ZeroKernel.git
cd ZeroKernel
bash scripts/run_desktop_tests.sh
  

    ZeroKernel.begin(boardMillis);
ZeroKernel.addTask("Sample", sampleTask, 100, 0, true);
ZeroKernel.tick();
  

    [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

Start here

This page condenses the main ZeroKernel docs into a practical setup guide: install, configure, wire tasks, choose profiles, and validate behavior with the included compare suites.

Quick start

    #include <ZeroKernel.h>

unsigned long boardMillis() {
  return millis();
}

void sampleTask() {
  // bounded sensor work
}

void setup() {
  ZeroKernel.begin(boardMillis);
  ZeroKernel.addTask("Sample", sampleTask, 100, 0, true);
}

void loop() {
  ZeroKernel.tick();
}
  

Module status

Validation commands

    bash scripts/run_desktop_tests.sh
  

    bash scripts/run_desktop_benchmark.sh --enforce-performance
  

    bash scripts/run_resource_matrix.sh --enforce-budget
  

    bash scripts/run_workload_matrix.sh
  

    bash scripts/run_esp32_env_monitor_compare.sh /dev/ttyUSB1
  

    bash scripts/run_esp32_gateway_compare.sh /dev/ttyUSB1
  

    bash scripts/run_esp32_industrial_compare.sh /dev/ttyUSB1
  

Overview FAQ