Quickstart

Why this page matters

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

1. Install the library

1. Clone or download the ZeroKernel repo from github.com/ZeroBitsTech/ZeroKernel.
2. For Arduino IDE, place the library in your sketchbook libraries folder.
3. For PlatformIO, link or vendor the library and set a build profile flag.

    git clone git@github.com:ZeroBitsTech/ZeroKernel.git
cd ZeroKernel
  

    [env:esp32]
platform = espressif32
board = esp32dev
framework = arduino
lib_deps =
  symlink://../ZeroKernel
build_flags =
  -DZEROKERNEL_PROFILE_LEAN_NET
  

2. Start the runtime

Always pass a board clock function. That keeps the scheduler deterministic and makes the runtime portable across supported boards.

    #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();
}
  

3. Validate before adding complexity

• Run the desktop tests first to confirm the local toolchain is clean.
• Use one compare script on hardware before adding your own network stack or sensor logic.
• Keep every task bounded and non-blocking. Move heavy work into queues or module pumps.

4. Grow safely

• Start with a small profile such as POWER_SAVE or LEAN_NET.
• Add modules only when their measured payoff is worth the extra footprint.
• Use the benchmark and compare scripts as regression gates, not as one-time demos.

Quickstart FAQ