Installation and Repo Setup

Why this page matters

This page explains how Installation and Repo Setup 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 Installation and Repo Setup 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

Clone or download the repo

ZeroKernel is distributed from the GitHub repository first. That keeps examples, scripts, manifest, and docs aligned to the same revision.

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

Arduino IDE layout

1. Copy the repository folder, or the release archive contents, into your sketchbook libraries directory.
2. Restart Arduino IDE so the library index refreshes.
3. Open one of the examples first, compile, and only then move to your own firmware.

    Documents/Arduino/libraries/ZeroKernel/
  library.properties
  src/
  examples/
  

PlatformIO layout

For PlatformIO, the simplest controlled approach is linking the repo locally and setting an explicit profile in build_flags.

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

First compile rule

• Compile an existing example before you write your own task code.
• Keep profile flags explicit from the first build so you know what footprint you are measuring.
• Treat scripts and docs as part of the product, not optional extras.

Installation FAQ