Command dan Script

Kenapa halaman ini penting

Halaman ini menjelaskan bagaimana Command dan Script 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 Command dan Script 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

Kenapa lapisan command itu penting

ZeroKernel membawa klaim yang spesifik: timing yang stabil, queue yang bounded, dan tradeoff yang bisa dijelaskan. Klaim seperti itu tidak boleh hanya hidup di README. Ia harus punya jalur validasi yang bisa diulang. Karena itu, script di repo ini harus diperlakukan sebagai alat kerja engineering, bukan sekadar helper kecil yang opsional.

Setiap kelompok script menjawab pertanyaan yang berbeda. Desktop scripts menjawab pertanyaan logic dan performa lokal. Resource scripts menjawab pertanyaan footprint. Hardware scripts menjawab pertanyaan "apakah ini benar-benar masih hidup di board?" Kalau peran-peran ini dicampur, hasil yang terlihat hijau sering memberikan rasa aman yang salah.

Lapisan command juga penting untuk disiplin rilis. Kalau satu tim tidak bisa menjalankan script yang sama dan mendapatkan hasil yang bisa dibandingkan, maka tabel benchmark, changelog, dan klaim produk menjadi jauh lebih lemah. Itulah kenapa halaman ini dibuat detail dan tidak hanya menyebut nama file script.

Command validasi inti

    # Sanity check inti
bash scripts/run_desktop_tests.sh

# Perubahan sensitif performa
bash scripts/run_desktop_benchmark.sh --enforce-performance

# Preflight siap-rilis
bash scripts/run_desktop_tests.sh
bash scripts/run_desktop_benchmark.sh --enforce-performance
bash scripts/run_resource_matrix.sh --enforce-budget
  

Script compare ESP32

Script hardware adalah titik di mana klaim lokal bertemu batas fisik board. Script ini compile, flash, menangkap output runtime, lalu mengembalikan board ke firmware identitas yang aman setelah selesai. Langkah restore itu penting agar board tidak ditinggal di stress loop atau demo yang berat setelah validasi selesai.

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

Gunakan script ini saat hasil desktop saja belum cukup. Misalnya queue terlihat sehat di benchmark lokal, tapi setelah di-flash bisa saja perilakunya berubah karena serial, upload flow, atau constraint board yang hanya muncul saat test nyata.

    # Tuning transport yang fokus
bash scripts/run_esp32_gateway_compare.sh /dev/ttyUSB1

# Pass yang lebih realistis
bash scripts/run_esp32_real_project_demo.sh /dev/ttyUSB1
  

Apa yang harus dibuktikan tiap script

Script yang pass belum tentu menjawab pertanyaan yang benar. Setiap script harus meninggalkan bukti yang berguna: angka timing, pass budget, ringkasan queue, atau output board yang bisa dibaca ulang. Kalau command hanya sukses tanpa mengungkap sesuatu yang konkret, maka nilainya masih kurang.

• Determinism: fast miss harus tetap nol di compare yang sudah dituning.
• Kesehatan queue: pressure harus bounded, bukan naik tanpa kendali.
• Kejelasan tradeoff: biaya memori harus punya payoff runtime yang nyata.

    Output compare yang baik harus menjawab:
- Apakah sample_runs tetap atau naik?
- Apakah fast_miss tetap nol?
- Apakah queue_max tetap bounded?
- Apakah kenaikan footprint dibayar dengan payoff nyata?
  

Tiga resep command yang praktis

Sebagian besar perubahan bisa dipetakan ke beberapa resep command yang berulang. Pakai resep seperti ini membuat validasi lebih cepat, lebih konsisten, dan lebih mudah dibaca ulang nanti.

    # Resep 1: ubah scheduler saja
bash scripts/run_desktop_tests.sh
bash scripts/run_desktop_benchmark.sh --enforce-performance
  

    # Resep 2: perubahan yang sensitif size
bash scripts/run_desktop_tests.sh
bash scripts/run_resource_matrix.sh --enforce-budget
  

    # Resep 3: hasil yang mau dipublikasikan
bash scripts/run_desktop_tests.sh
bash scripts/run_resource_matrix.sh --enforce-budget
bash scripts/run_esp32_modules_compare.sh /dev/ttyUSB1
  

FAQ command