API Reference

Kenapa halaman ini penting

Halaman ini menjelaskan bagaimana API Reference masuk ke model eksekusi ZeroKernel yang lebih besar, masalah apa yang sebenarnya diselesaikan, dan trade-off apa yang benar-benar Anda bayar saat fitur ini dipakai di firmware produksi. Tujuannya bukan melihat API Reference sebagai satu API terpisah, tetapi memahami posisinya di dalam bounded scheduling, disiplin queue, visibilitas fault, dan pemilihan profile.

Baca topik ini sebagai kontrak operasional. Mulai dari jalur paling kecil yang benar-benar jalan, pasang dulu di profile lean, lalu baru naik ke routing, diagnostics, atau state transport yang lebih kaya setelah Anda bisa membuktikan hasil timing-nya tetap layak dibanding tambahan flash dan RAM. Pola pikir ini yang menjaga ZeroKernel tetap berguna di board kecil dan tidak berubah jadi abstraksi yang gemuk.

Pola paling aman selalu sama: tentukan batas runtime-nya, jaga hot path tetap pendek, ukur efeknya dengan compare script, lalu baru naikkan kompleksitas. Contoh di bawah bukan pemanis; itu adalah pola minimum yang bisa Anda ambil ke firmware nyata saat Anda butuh integrasi yang rapi, bukan loop manual yang sulit dipertahankan.

Tiga pola yang langsung bisa dipakai

    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_esp32_modules_compare.sh /dev/ttyUSB1
bash scripts/run_esp32_real_project_demo.sh /dev/ttyUSB1
  

    -DZEROKERNEL_PROFILE_LEAN_NET
-DZEROKERNEL_ENABLE_DIAGNOSTICS=0
-DZEROKERNEL_ENABLE_LEGACY_LABEL_API=0
  

Apa yang perlu Anda cek saat memakainya

• Validasi timing lebih dulu, baru bentuk API. API yang terlihat rapi bukan kemenangan kalau fast miss justru naik.
• Pilih profile paling kecil yang masih cocok, lalu aktifkan modul opsional hanya saat payoff terukurnya benar-benar jelas.
• Jaga callback dan langkah transport tetap bounded supaya watchdog, panic flow, dan batas queue tetap punya arti.

Kesalahan umum yang membuat hasil jadi menyesatkan

• Jangan menyalin pola demo ke firmware produksi tanpa mengukurnya di board dan profile build yang benar-benar akan dipakai.
• Jangan membaca angka sukses tanpa membaca queue depth, timing, dan label workload di sampingnya.
• Jangan menyalakan diagnostics atau kompatibilitas berat di target lean hanya karena default-nya terasa nyaman.

Urutan kerja yang disarankan

Cara membaca halaman referensi ini

Halaman ini adalah referensi operasional untuk permukaan ZeroKernel yang paling sering dipakai. Ini bukan dump simbol otomatis. Tujuannya adalah membantu Anda memahami call mana yang seharusnya dipakai di setup, mana yang dipakai di loop utama, mana yang membentuk task, dan mana yang dipakai untuk observasi atau eskalasi runtime. Pemisahan ini penting karena firmware embedded jauh lebih mudah dipahami saat batas itu tetap rapi.

Dalam praktik, sebagian besar firmware hanya memakai subset kecil dari seluruh API. Node biasa cukup memakai begin, addTask, tick, routing, lalu membaca timing atau stats. Node yang lebih kompleks mungkin memakai signal, panic, capability, atau modul network. Halaman ini dibuat agar Anda punya peta mental untuk permukaan itu sebelum masuk ke halaman khusus yang menjelaskan satu fitur secara lebih mendalam.

Kalau Anda masih baru, baca halaman ini dari atas ke bawah sekali, lalu pakai sebagai lembar referensi saat menulis kode. Kalau Anda sudah mengintegrasikan ZeroKernel ke project, pakai halaman ini sebagai checklist: lifecycle dulu, task control kedua, routing ketiga, diagnostics terakhir. Urutan itu membantu runtime tetap jelas dan menghindari campur aduk antara setup dan jalur panas runtime.

Lifecycle dan urutan boot

Kesalahan lifecycle yang paling umum adalah menganggap begin() sebagai formalitas. Padahal tidak. Kalau runtime dimulai dengan clock yang salah atau implisit, semua klaim tentang cadence, jitter, dan compare hasil menjadi lebih lemah. Runtime hanya akan sebaik kontrak waktu yang Anda berikan.

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

void setup() {
  ZeroKernel.begin(boardMillis);
}

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

Kontrol task dan pembentukan task

Task di ZeroKernel tetaplah kode Anda. Runtime tidak otomatis membuatnya aman. Nilai tambahnya adalah setelah task dideklarasikan, runtime bisa menghitung, mengawasi, membandingkan, dan menampilkannya di diagnostics. Itu sebabnya pendaftaran task bukan cuma ganti gaya callback; ia mengubah alur firmware informal menjadi hal yang benar-benar bisa diamati oleh runtime.

Aturan praktisnya sederhana: jaga body task tetap singkat dan non-blocking, lalu gunakan metadata task untuk memberi tahu runtime bagaimana task itu harus diperlakukan. Priority, heartbeat, dan execution contract adalah bagian yang membuat task terlihat oleh sistem yang lebih besar.

    void sampleTask() {
  readSensor();
}

void setup() {
  ZeroKernel.begin(boardMillis);
  ZeroKernel.addTask("sample", sampleTask, 10);
  ZeroKernel.setTaskPriority("sample", ZeroKernel::kPriorityHigh);
  ZeroKernel.setTaskHeartbeatTimeout("sample", 50);
}
  

    void maintenanceTask() {
  flushLogs();
}

void onStateChange(ZeroKernel::KernelState state) {
  if (state == ZeroKernel::kStateSafeMode) {
    ZeroKernel.suspendTask("maintenance");
  }
}
  

Routing, command, dan signal

Untuk firmware baru, jalur normalnya adalah routing berbasis key. String-based routing masih ada, tapi fungsinya sebagai jembatan, bukan arah strategis. Semakin sering sebuah rute dipakai, semakin besar alasan untuk membuang kerja string berulang dari jalur tersebut.

    const auto telemetryKey = ZeroKernel.makeTopicKey("telemetry.sample");

void onTelemetry(long value) {
  latestSample = value;
}

void setup() {
  ZeroKernel.subscribeFast(telemetryKey, onTelemetry);
}

void sampleTask() {
  ZeroKernel.publishDeferredFast(telemetryKey, readSensor());
}
  

    const auto flushKey = ZeroKernel.makeTopicKey("transport.flush");

void triggerFlush() {
  ZeroKernel.enqueueCommandFast(flushKey, 0);
}
  

State, diagnostics, dan bukti yang bisa dipakai

Permukaan diagnostics inilah yang mengubah klaim engineering menjadi sesuatu yang bisa dibuktikan. Kalau tim bilang runtime ini deterministik, bukti nyatanya ada di timing report. Kalau tim bilang runtime ini resilient, bukti nyatanya ada di transisi state, recovery, dan eskalasi yang bounded.

    void reportTask() {
  auto stats = ZeroKernel.getStats();
  auto timing = ZeroKernel.getTimingReport();

  Serial.print("runs=");
  Serial.print(stats.taskRuns);
  Serial.print(" fast_miss=");
  Serial.print(timing.fastMissCount);
  Serial.print(" state=");
  Serial.println(ZeroKernel.state());
}
  

Tiga pola referensi yang paling umum

Mayoritas project jatuh ke pola pemakaian yang sama: node minimal, node berbasis routing, atau node yang disupervisi dengan ketat. Saat pola itu terlihat jelas, API jadi lebih mudah dibaca karena tidak lagi tampak seperti daftar function yang panjang, tetapi sebagai beberapa mode operasional yang berulang.

    // Pola 1: loop cooperative minimal
ZeroKernel.begin(boardMillis);
ZeroKernel.addTask("blink", blinkTask, 250);

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

    // Pola 2: node berbasis routing
const auto key = ZeroKernel.makeTopicKey("sensor.sample");
ZeroKernel.subscribeFast(key, onSample);
ZeroKernel.addTask("sample", sampleTask, 20);
  

    // Pola 3: node tersupervisi
ZeroKernel.setTaskHeartbeatTimeout("sample", 50);
ZeroKernel.onStateChange(onKernelStateChanged);
ZeroKernel.setSignalHandler(onKernelSignal);
  

FAQ API reference