State Machine and Panic Flow

Why this page matters

This page explains how State Machine and Panic Flow 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 State Machine and Panic Flow 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

    ZeroKernel.begin(boardMillis);
ZeroKernel.addTask("Fast", fastTask, 10, 0, true);
ZeroKernel.tick();
  

    const auto key = ZeroKernel.makeTopicKey("telemetry.sample");
ZeroKernel.publishDeferredFast(key, sampleValue);
ZeroKernel.flushEvents();
  

    const auto stats = ZeroKernel.getStats();
const auto timing = ZeroKernel.getTimingReport();
Serial.println(timing.maxTickMs);
  

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

Kernel state model

    BOOT -> NORMAL -> DEGRADED -> SAFE_MODE -> RECOVERY
                             \-> PANIC
  

Not every firmware uses every state, but the model gives the runtime a consistent contract for escalation and recovery.

Panic path

triggerPanic() is the explicit hard stop for conditions that should not be silently tolerated. The panic path is useful for unrecoverable runtime corruption, repeated critical task failure, or test-mode verification.

Safe mode vs panic

• Safe mode keeps the firmware alive with reduced behavior.
• Panic prioritizes visibility and containment over feature continuity.
• Use safe mode first if the system can still provide value in a reduced state.

State and panic FAQ