Mokxi's command line tool compiles the sketch with the same compiler the editor uses and runs it on the same simulator, headlessly, on the CI machine itself. It needs no server time: the compiler is downloaded once from mokxi.com and cached, and everything else happens on your runner. In CI it is free for a public repository, and a private one needs a CI token in MOKXI_TOKEN from an account with private CI (see CI butuh paket apa); di komputermu sendiri tidak butuh akun sama sekali. Mokxi membaca proyek Wokwi dan file scenario Wokwi apa adanya, jadi pindah dari Wokwi CI hanya perlu perubahan satu baris.
Mulai cepat
Di sebuah folder dengan sketch (dan, jika berisi lebih dari sekadar board, sebuah diagram.json dari Mokxi atau Wokwi):
npx @mokxi/cli run --timeout 10s --expect-serial "Ready" --fail-on "panic"
Perintah itu mengompilasi sketch, menjalankannya, mencetak keluaran serial saat muncul, dan keluar begitu Ready muncul (exit code 0). Perintah gagal dengan exit code 1 begitu sketch mencetak panic, saat 10 detik waktu simulasi berlalu tanpa Ready, atau saat sketch gagal dikompilasi. Cukup butuh Node.js 18 atau lebih baru.
Untuk lebih dari satu baris keluaran, tulis sebuah scenario. Taruh ini di mokxi.test.yaml di samping sketch:
name: Blink and button
timeout: 10s
fail-on: [panic]
tests:
- name: boots and blinks at 2 Hz
steps:
- wait-serial: Ready
- expect-toggles: { pin: uno:13, during: 1s, min: 3, max: 5 }
- name: the button lights the LED
steps:
- wait-serial: Ready
- press: btn1
- expect-led: led2
- release: btn1
- expect-led-off: led2
dan jalankan semua test di dalamnya, dengan laporan JUnit untuk dashboard CI-mu:
npx @mokxi/cli test --junit mokxi-junit.xml
Setiap test menjalankan sketch dari awal, dan masing-masing menjadi satu test case di laporan.
Di GitHub Actions
name: Simulate
on: [push, pull_request]
jobs:
simulate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: mokxiorg/sim-action@v1
with:
timeout: 10s
expect-serial: Ready
fail-on: panic
Action menjalankan mokxi.test.yaml jika foldernya punya, kalau tidak hanya memeriksa sketch bisa boot dan mencetak teks yang diharapkan. Action menyimpan compiler di cache Actions, jadi hanya diunduh sekali, menulis mokxi-junit.xml, menaruh tabel hasilnya di job summary, dan menganotasi run dengan setiap kegagalan, error kompilasi di barisnya sendiri. Setiap input tercantum di action.yml milik action: path, scenario, timeout, expect-serial, fail-on, board, firmware, junit, serial-log, screenshot, args, version dan token (token CI, hanya dibutuhkan untuk repositori privat).
Di CI lain
Command line adalah produknya secara utuh, jadi apa pun yang menjalankan Node bekerja dengan cara yang sama. GitLab CI, misalnya:
simulate:
image: node:22
cache:
paths: [.mokxi-cache/]
variables:
MOKXI_CACHE_DIR: .mokxi-cache
script:
- npx @mokxi/cli test --junit mokxi-junit.xml
artifacts:
when: always
reports:
junit: mokxi-junit.xml
Simpan folder cache antar job (MOKXI_CACHE_DIR, atau ~/.cache/mokxi secara bawaan). Tanpa itu setiap job mengunduh compiler lagi, dan mokxi.com membatasi seberapa sering satu alamat boleh melakukannya.
Apa yang dijalankan
mokxi run dan mokxi test menerima folder, file, atau link:
| Apa saja | Cara dibacanya |
|---|---|
Folder dari mokxi pull atau Simpan ke GitHub |
diagram.mokxi.json dan folder sketch di sampingnya |
| Folder proyek Wokwi | diagram.json, sketch beserta tab-nya, libraries.txt, dan wokwi.toml |
| Folder sketch Arduino biasa | board polos untuk sketch: sebuah Uno, atau sebutkan dengan --board esp32 |
File .mokxi.json |
file yang ditulis oleh Download JSON di editor |
https://mokxi.com/p/<id> |
proyek publik, atau milikmu sendiri dengan mokxi login atau MOKXI_TOKEN |
https://wokwi.com/projects/<id> |
proyek Wokwi publik, diambil dari Wokwi |
Sketch dikompilasi untuk board di diagram, dengan library milik proyek dan library Arduino umum yang dibawa Mokxi. Untuk menjalankan build-mu sendiri (buatan PlatformIO atau arduino-cli), berikan: --firmware build/sketch.ino.elf, atau --firmware uno1=build/a.elf untuk satu board dari beberapa. Saat wokwi.toml proyek Wokwi menyebut file firmware yang ada, build itulah yang dijalankan, seperti Wokwi; --compile mengompilasi sketch sebagai gantinya.
Setiap board yang disimulasikan Mokxi bisa berjalan di sini: Uno, Nano, Mega, Leonardo, Pro Mini dan ATtiny85, ESP32, ESP32-S3, ESP32-C3, ESP32-C6 dan ESP8266, Pico dan Pico W, UNO R4, board STM32, XIAO dan micro:bit. mokxi boards mendaftarkannya.
Referensi perintah
| Opsi | Fungsinya |
|---|---|
--timeout 10s |
waktu simulasi maksimum yang boleh diambil run (atau setiap scenario). Angka polos berarti milidetik, seperti di CLI Wokwi |
--expect-serial TEXT |
berhasil begitu semua teks tersebut telah dicetak. Ulangi untuk beberapa teks. --expect-text sama saja |
--fail-on TEXT |
gagal begitu teks ini dicetak. --fail-text sama saja |
--scenario FILE |
jalankan file scenario ini (mokxi run --scenario sama dengan mokxi test) |
--junit FILE |
tulis laporan XML JUnit |
--serial-log-file FILE |
tulis semua yang dicetak board |
--screenshot FILE |
untuk mokxi run: gambar saat run berakhir. --screenshot-part oled1 memotret satu komponen: layar (OLED, TFT, LCD, e-paper, LED matrix) sebagai PNG dari pikselnya sendiri, selain itu sebagai gambar SVG. --screenshot-time 2s mengambilnya pada saat itu. --screenshot-file sama saja; dengan hanya --screenshot-part, filenya screenshot.png, seperti di Wokwi |
--vcd-file FILE |
tulis apa yang direkam logic analyzer di rangkaian sebagai file VCD (GTKWave, PulseView), setiap edge di nanodetiknya. Satu file per scenario di mokxi test |
--shard 2/3 |
untuk mokxi test: jalankan bagian kedua dari tiga bagian scenario yang sama, jadi matriks CI tiga job menjalankannya paralel |
--firmware [board=]FILE, --elf FILE |
jalankan build ini alih-alih mengompilasi |
--board TYPE |
board untuk sketch tanpa diagram |
--diagram-file FILE |
baca diagram ini alih-alih diagram.json di folder |
--compile |
mengompilasi sketch meski wokwi.toml menyebut file firmware |
--timeout-exit-code N |
exit code untuk timeout (bawaan 1; CLI Wokwi memakai 42) |
--offline |
jangan sentuh jaringan; gagal jika compiler tidak ada di cache |
--quiet |
jangan cetak keluaran serial (mokxi run) |
--verbose |
cetak keluaran serial dan setiap langkah (mokxi test) |
mokxi lint [dir] membaca proyek seperti yang dilakukan sebuah run dan mendaftar apa yang salah dengan rangkaian tanpa mengompilasi atau menjalankannya: komponen yang tidak disimulasikan Mokxi, kabel ke pin yang tidak ada. Perintah keluar dengan 1 saat ada error, atau saat ada warning dengan --warnings-as-errors; --ignore-warnings hanya mencetak error.
Setiap run mencetak berapa waktu simulasi yang dicakup, berapa lama itu berlangsung, dan berapa kali lebih cepat dari waktu nyata; laporan JUnit dan job summary membawa angka yang sama.
Exit code: 0 saat semua lulus, 1 saat ada yang gagal (sebuah check, timeout, baris --fail-on, error kompilasi), 2 untuk kesalahan di perintah atau file scenario, dan 3 saat unduhan gagal atau CI butuh sebuah paket. Opsi CLI Wokwi yang belum dimiliki Mokxi (--heap-min-free, --coverage-file, --sdcard, --interactive, --gdb-server-port) menghasilkan exit 2, jadi sebuah run tidak pernah lulus tanpa check yang diminta.
Di GitHub Actions, setiap skenario yang gagal menjadi anotasi pada baris step yang gagal, lengkap dengan baris terakhir yang dicetak board, dan ringkasan job berisi tabel setiap skenario dengan cuplikan serial yang dilipat di setiap kegagalan.
Waktu di dalam sebuah run adalah waktu simulasi, bukan waktu nyata, jadi sebuah tes berperilaku sama di laptop cepat maupun mesin CI yang lambat. Run yang memakan waktu nyata jauh lebih lama dari seharusnya (30 kali timeout-nya, atau minimal dua menit) dihentikan karena dianggap macet.
Referensi skenario
File skenario adalah YAML. Berisi satu skenario (steps: di bagian atas) atau beberapa (tests:, daftar name dan steps):
| Tombol | Apa ini |
|---|---|
name |
nama file di laporan |
project |
proyek yang dijalankan, relatif terhadap file: sebuah folder, file, atau link. Default: folder file itu sendiri |
board |
board untuk sketch tanpa diagram |
firmware |
build yang dijalankan alih-alih mengompilasi: sebuah path, atau { board: path } |
timeout |
waktu simulasi yang boleh dihabiskan tiap skenario (default 30 s untuk mokxi test) |
fail-on |
teks yang langsung menggagalkan skenario begitu dicetak: satu, atau sebuah daftar |
steps |
langkah-langkah satu skenario |
tests |
beberapa skenario, masing-masing { name, steps, timeout?, fail-on? } |
Langkah dijalankan berurutan, dan skenario berhenti di langkah pertama yang gagal. Setiap langkah bisa punya name: untuk laporan.
| Langkah | Fungsinya |
|---|---|
wait-serial: Ready |
jalankan sampai teks ini dicetak setelah yang dicocokkan oleh wait sebelumnya. /pattern/ adalah regular expression. { text, timeout, board } membatasi berapa lama menunggu, dan di board mana |
expect-serial: Ready |
periksa teks sudah dicetak sampai sekarang, tanpa menunggu |
expect-no-serial: error |
periksa belum dicetak |
write-serial: "hello\n" |
ketik ke serial monitor (tepat teks ini: tambahkan \n untuk Enter). Daftar angka, [104, 105, 10], mengirim byte tersebut, seperti di Wokwi |
delay: 500ms |
biarkan simulasi berjalan selama ini |
press: btn1 / release: btn1 |
tahan tombol, atau lepaskan |
click: btn1 |
tekan, tahan 100 ms ({ part, hold } untuk mengubahnya), lepas |
set: { part: dht1, temperature: 30 } |
atur sensor atau kontrol; lihat tabel di bawah |
expect-pin: { pin: uno:13, level: high } |
periksa level sebuah pin sekarang. uno:13=high artinya sama. 13 saja berarti pin satu-satunya board |
wait-pin: { pin: uno:2, level: low, timeout: 1s } |
jalankan sampai pin mencapai level itu |
expect-toggles: { pin: uno:13, during: 1s, min: 3, max: 5 } |
jalankan selama during dan hitung perubahan pin: count, min dan max. Beginilah timing diperiksa: kedipan 2 Hz adalah empat perubahan per detik |
expect-led: led1 |
periksa LED menyala; expect-led-off: led1 memeriksa mati |
expect-probe: { part: servo1, min: 85, max: 95 } |
periksa pembacaan komponen apa pun (sudut servo, segmen menyala di display, kecepatan motor) |
screenshot: build/circuit.svg |
simpan gambar rangkaian, semua komponen digambar seperti kondisinya sekarang. { part: led1, file } menggambar satu komponen. Komponen display ({ part: oled1, file: build/oled.png }) disimpan sebagai PNG dari piksel panel itu sendiri. take-screenshot milik Wokwi dengan part-id dan save-to fungsinya sama |
take-screenshot: { part-id: oled1, compare-with: ref/oled.png } |
periksa display menampilkan tepat gambar referensi. max-diff-pixels: 4 mengizinkan beberapa piksel berbeda, tolerance: 8 selisih warna kecil. Saat tidak cocok, run menulis ref/oled.diff.png (perbedaannya merah) dan ref/oled.actual.png. Bila file referensi belum ada, run menyimpan gambarnya di sana dan gagal sekali, supaya kamu bisa memeriksanya dan commit |
expect-display: { part: oled1, lit-min: 200 } |
periksa apa yang tampil di display sekarang: lit-min dan lit-max menghitung piksel menyala, region: [x, y, width, height] melihat sebagian panel, pixel: { x, y, lit: true } atau pixel: { x, y, color: "#ff8000" } memeriksa satu piksel, blank: true memeriksa panel mati, matches: ref.png membandingkan dengan sebuah gambar. Menyala berarti tinta panel pada panel satu warna, dan apa pun yang lebih terang dari mendekati hitam pada panel berwarna |
wait-display: { part: oled1, lit-min: 200, timeout: 2s } |
jalankan sampai display menampilkan itu, seperti wait-serial menunggu teks |
touch: { part-id: tft1, x: 120, y: 160 } |
ketuk panel sentuh selama 50 ms (duration untuk mengubahnya); touch-press, touch-move dan touch-release menahan, menyeret dan mengangkat. Di ILI9341 kapasitif, koordinatnya milik pengontrol sentuh, seperti di Wokwi; di yang resistif koordinatnya piksel gambar dari kiri atas |
poke: { part, code } |
kirim kode stimulus mentah ke sebuah komponen, untuk apa pun yang tidak disebut tabel di bawah |
Kecerahan LED di simulator adalah yang dilihat mata: meredup dalam beberapa milidetik, seperti di meja kerja. Jadi expect-led memberi LED hingga 50 ms waktu simulasi untuk mencapainya sebelum gagal.
Pin diberi nama seperti di editor (uno1:13, esp1:D2, pico1:GP15); 13, D13, GP13 dan GPIO13 masing-masing akan dicoba. Komponen dinamai berdasarkan id-nya di diagram, atau berdasarkan id Wokwi-nya jika proyeknya berasal dari Wokwi.
Sensor dan kontrol
| Komponen | Kontrol (set: { part, <control>: <value> }) |
|---|---|
| Tombol tekan, tombol arcade, microswitch | pressed: 1 atau 0 |
| Saklar geser | value: 0 atau 1 |
| Potensiometer, potensiometer geser | position: 0 sampai 1 (atau 0 sampai 1023) |
| DHT11, DHT22, AHT20 | temperature dalam C, humidity dalam % |
| DS18B20, LM35, TMP36, modul NTC | temperature dalam C |
| BMP180, BMP280, BME280 | temperature dalam C, pressure dalam hPa, humidity dalam % (BME280) |
| HC-SR04 | distance dalam cm |
| Sensor halangan FC-51 | distance dalam cm |
| LDR, modul LDR, fototransistor, BH1750 | lux |
| PIR | gerakan: 1 atau 0 |
| Kelembapan tanah | kelembapan dalam % |
| MQ-2 | gas dalam ppm |
| Saklar DIP, keypad | nilai atau tombol: bitmask |
Beralih dari Wokwi CI
Folder proyek Wokwi-mu berjalan apa adanya: diagram.json, wokwi.toml, sketch, libraries.txt, dan file scenario-mu dibaca tanpa perubahan. Di GitHub Actions, ubah baris uses: dan secret yang dibaca input token. Action meneruskan token ke CLI sebagai MOKXI_TOKEN, yang memeriksa paketmu dengannya.
# before
- uses: wokwi/wokwi-ci-action@v1
with:
token: ${{ secrets.WOKWI_CLI_TOKEN }}
path: .
timeout: 10000
scenario: test.scenario.yaml
# after
- uses: mokxiorg/sim-action@v1
with:
token: ${{ secrets.MOKXI_TOKEN }}
path: .
timeout: 10000
scenario: test.scenario.yaml
Beralih dari Wokwi CI berisi sisanya: opsi wokwi-cli, langkah scenario mana yang tetap berlaku, tiga hal yang berperilaku berbeda, dan perbandingan berdampingan beserta harganya.
Paket apa yang dibutuhkan CI
Repositori publik menjalankan CI gratis, tanpa token dan tanpa akun. Di GitHub Actions dan gitlab.com, CLI mengambil nama repositori dari runner itu sendiri (GITHUB_REPOSITORY, CI_PROJECT_PATH), dan Mokxi bertanya ke GitHub atau GitLab, tanpa kredensial apa pun, apakah repositorinya publik. Repositori privat terlihat tidak ada bagi permintaan seperti itu, jadi tidak bisa dianggap publik. GitHub Enterprise dan GitLab yang dikelola sendiri tidak bisa diperiksa dari luar, jadi keduanya butuh token.
Private repositories need Pro or above: Pro, the
student price, Lifetime, Classroom and the trial all include CI, and so do
Ultra and Pro for work, which are not sold any more (an account that has either
keeps CI). Pro includes 2,000 API minutes a month. In CI mode (CI=true,
GITHUB_ACTIONS=true, or --ci), mokxi run and mokxi test check your plan
with the token in MOKXI_TOKEN; make a CI token from Settings, Developer, and
keep it in a repository secret. mokxi simulate runs on Mokxi's servers and always
needs a plan. The license is cached for seven days, so a runner without network inside
that week still runs.
Menjalankan sketch di komputermu sendiri dengan mokxi run tetap gratis, tanpa akun.
If you used CI in the 60 days before the change, you keep it until December 11, 2026, and each run prints a notice saying so. An account that was paying for a plan then keeps CI while it keeps paying.
Cache dan penggunaan offline
The compiler (about 80 MB), each board family's runtime and its compiled objects are kept in ~/.cache/mokxi (or MOKXI_CACHE_DIR, or $XDG_CACHE_HOME/mokxi). The first build of a board family takes 10 to 20 seconds; later builds take a few. The ESP32, ESP32-S3 and ESP8266 compile with a second toolchain of the same size, downloaded the first time one of them is built. The compiler is checked against the published build's SHA-256 before it is used. mokxi cache shows the folder and its size, and mokxi cache clear empties it.
Di komputer tanpa jaringan, salin folder cache yang sudah terisi ke sana dan berikan --offline (atau set MOKXI_OFFLINE=1): tidak ada yang diunduh, dan file yang hilang menjadi error, bukan diunduh.