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 için hangi plan gerekir); kendi bilgisayarında hiç hesap gerektirmez. Wokwi projelerini ve Wokwi senaryo dosyalarını oldukları gibi okur, yani Wokwi CI'dan geçmek tek satırlık bir değişikliktir.
Hızlı başlangıç
İçinde bir kod bulunan klasörde (ve kodda yalnızca çıplak bir kart yoksa, Mokxi veya Wokwi'den bir diagram.json):
npx @mokxi/cli run --timeout 10s --expect-serial "Ready" --fail-on "panic"
Bu, kodu derler, çalıştırır, seri çıktıyı geldikçe yazdırır ve Ready göründüğü anda çıkar (çıkış kodu 0). Kod panic yazdığı anda çıkış kodu 1 ile başarısız olur, Ready olmadan 10 saniyelik simüle edilmiş zaman geçtiğinde veya kod derlenmediğinde de öyle. Yalnızca Node.js 18 veya daha yenisi gerekir.
Birden fazla satırlık çıktı için bir senaryo yaz. Bunu kodun yanındaki mokxi.test.yaml dosyasına koy:
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
ve içindeki her testi çalıştır, CI panelin için bir JUnit raporu ile:
npx @mokxi/cli test --junit mokxi-junit.xml
Her test kodun taze bir çalışmasıdır ve her biri raporda bir test durumu olur.
GitHub Actions'ta
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
Aksiyon, klasörde bir tane varsa mokxi.test.yaml dosyasını çalıştırır, yoksa kodun açılıp beklenen metni yazdırıp yazdırmadığını denetler. Derleyiciyi Actions önbelleğinde tutar, böylece yalnızca bir kez indirilir; mokxi-junit.xml dosyasını yazar, sonuçların bir tablosunu iş özetine koyar ve her hatayı, derleme hatası kendi satırında olacak şekilde, çalıştırmaya ek not olarak düşer. Her girdi aksiyonun action.yml dosyasında listelenir: path, scenario, timeout, expect-serial, fail-on, board, firmware, junit, serial-log, screenshot, args, version ve token (bir CI anahtarı, yalnızca gizli bir depo için gerekir).
Başka herhangi bir CI'da
Komut satırı ürünün tamamıdır, yani Node çalıştıran her şey aynı şekilde işler. Örneğin GitLab CI:
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
Önbellek klasörünü işler arasında tut (MOKXI_CACHE_DIR veya varsayılan olarak ~/.cache/mokxi). Olmazsa her iş derleyiciyi yeniden indirir ve mokxi.com tek bir adresin bunu ne sıklıkla yapabileceğini sınırlar.
Ne çalıştırır
mokxi run ve mokxi test bir klasör, dosya veya bağlantı alır:
| Ne | Nasıl okunur |
|---|---|
mokxi pull veya GitHub'a kaydet ile gelen bir klasör |
diagram.mokxi.json ve yanındaki kod klasörü |
| Bir Wokwi proje klasörü | diagram.json, kod ve sekmeleri, libraries.txt ve wokwi.toml |
| Düz bir Arduino kod klasörü | kod için çıplak bir kart: bir Uno, ya da --board esp32 ile hangi olduğunu söyle |
Bir .mokxi.json dosyası |
düzenleyicinin Download JSON düğmesinin yazdığı dosya |
https://mokxi.com/p/<id> |
herkese açık bir proje, ya da mokxi login veya MOKXI_TOKEN ile kendininkiler |
https://wokwi.com/projects/<id> |
Wokwi'den çekilmiş, herkese açık bir Wokwi projesi |
Kod, diyagramdaki kart için, projenin kendi kütüphaneleri ve Mokxi'nin taşıdığı yaygın Arduino kütüphaneleri ile derlenir. Bunun yerine kendi derlemenizi çalıştırmak için (PlatformIO'nun veya arduino-cli'ninkini) şöyle verin: --firmware build/sketch.ino.elf, ya da birkaç karttan biri için --firmware uno1=build/a.elf. Bir Wokwi projesinin wokwi.toml dosyası var olan bir firmware dosyası adlandırıyorsa, Wokwi'nin yaptığı gibi o derleme çalıştırılır; --compile bunun yerine kodu derler.
Mokxi'nin simüle ettiği her kart burada çalışır: Uno, Nano, Mega, Leonardo, Pro Mini ve ATtiny85; ESP32, ESP32-S3, ESP32-C3, ESP32-C6 ve ESP8266; Pico ve Pico W; UNO R4; STM32 kartları; XIAO ve micro:bit. mokxi boards bunları listeler.
Komut başvurusu
| Seçenek | Ne yapar |
|---|---|
--timeout 10s |
çalıştırmanın (veya her senaryonun) sürebileceği simüle edilmiş süre. Çıplak sayı milisaniyedir, Wokwi CLI'sinde olduğu gibi |
--expect-serial TEXT |
böyle her metin yazdırıldığında başarılı say. Birkaçı için tekrarla. --expect-text aynı şeydir |
--fail-on TEXT |
bu metin yazdırıldığı anda başarısız ol. --fail-text aynı şeydir |
--scenario FILE |
bu senaryo dosyasını çalıştır (mokxi run --scenario, mokxi test demektir) |
--junit FILE |
bir JUnit XML raporu yaz |
--serial-log-file FILE |
kartların yazdırdığı her şeyi yaz |
--screenshot FILE |
mokxi run için: çalıştırma bittiğinde bir resim. --screenshot-part oled1 tek bir parçayı resmeder: bir ekranı (OLED, TFT, LCD, e-paper, LED matrisi) kendi piksellerinden bir PNG olarak, başka her şeyi bir SVG çizimi olarak. --screenshot-time 2s onun yerine tam o anda alır. --screenshot-file aynı şeydir; yalnızca --screenshot-part ile dosya screenshot.png olur, Wokwi'deki gibi |
--vcd-file FILE |
devrenin mantık analizörlerinin kaydettiği her şeyi, her kenarı nanosaniyesiyle birlikte bir VCD dosyası olarak yaz (GTKWave, PulseView). mokxi test içinde her senaryo için bir dosya |
--shard 2/3 |
mokxi test için: senaryoların üç eşit parçasından ikincisini çalıştır, böylece üç işlik bir CI matrisi bunları paralel çalıştırır |
--firmware [board=]FILE, --elf FILE |
derlemek yerine bu derlemeyi çalıştır |
--board TYPE |
diyagramı olmayan bir kod için kart |
--diagram-file FILE |
klasörün diagram.json dosyası yerine bu diyagramı oku |
--compile |
wokwi.toml bir firmware dosyası adlandırsa bile kodu derle |
--timeout-exit-code N |
zaman aşımı için çıkış kodu (varsayılan 1; Wokwi CLI'si 42 kullanır) |
--offline |
asla ağa bağlanma; derleyici önbellekte değilse başarısız ol |
--quiet |
seri çıktıyı yazdırma (mokxi run) |
--verbose |
seri çıktıyı ve her adımı yazdır (mokxi test) |
mokxi lint [dir], projeyi bir çalıştırmanın okuduğu gibi okur ve devrede yanlış olanları derlemeden veya çalıştırmadan listeler: Mokxi'nin simüle etmediği bir parça, var olmayan bir pine giden bir kablo. Hata durumunda, ya da --warnings-as-errors ile uyarı durumunda 1 ile çıkar; --ignore-warnings yalnızca hataları yazdırır.
Her çalıştırma, ne kadar simüle edilmiş zaman kapsadığını, bunun ne kadar sürdüğünü ve gerçek zamandan kaç kat hızlı çalıştığını yazdırır; JUnit raporu ve iş özeti aynı sayıları taşır.
Çıkış kodları: her şey başarılıysa 0, bir şey başarısız olursa 1 (bir denetim, bir zaman aşımı, bir --fail-on satırı, bir derleme hatası), komutta veya senaryo dosyasında bir hata için 2, ve bir indirme başarısız olduğunda veya CI bir plan gerektirdiğinde 3. Mokxi'nin henüz sahip olmadığı bir Wokwi CLI seçeneği (--heap-min-free, --coverage-file, --sdcard, --interactive, --gdb-server-port) çıkış kodu 2'dir, böylece bir çalıştırma istenen bir denetim yapılmadan asla başarılı olmaz.
GitHub Actions'ta başarısız olan her senaryo, başarısız olan adımın satırında, kartın yazdırdığı son satırlarla birlikte bir ek not olarak görünür. İş özetinde ise her senaryoyu içeren bir tablo ve her başarısızlığın altında katlanmış bir seri çıktı alıntısı bulunur.
Bir çalıştırmadaki süre, simüle edilmiş süredir, duvar saati süresi değil. Böylece bir test hızlı bir dizüstü bilgisayarda da yavaş bir CI makinesinde de aynı davranır. Gerçekte olması gerekenden çok uzun süren bir çalıştırma (zaman aşımının 30 katı veya en az iki dakika) takılmış olarak durdurulur.
Senaryo başvurusu
Bir senaryo dosyası YAML'dır. Tek bir senaryo (en üstte steps:) veya birkaç senaryo (tests:, name ve steps listesi) içerir:
| Tuş | Nedir |
|---|---|
name |
rapordaki dosyanın adı |
project |
çalıştırılacak proje, dosyaya göreli: bir klasör, bir dosya veya bir bağlantı. Varsayılan: dosyanın kendi klasörü |
board |
diyagramı olmayan bir kod için kart |
firmware |
derlemek yerine çalıştırılacak bir derleme: bir yol veya { board: path } |
timeout |
her senaryonun sürebileceği simüle edilmiş süre (mokxi test için varsayılan 30 s) |
fail-on |
yazdırıldığı anda senaryoyu başarısız kılan metin: tek bir metin veya bir liste |
steps |
tek bir senaryonun adımları |
tests |
birkaç senaryo, her biri { name, steps, timeout?, fail-on? } |
Adımlar sırayla çalışır ve senaryo ilk başarısız adımda durur. Her adım, rapor için bir name: taşıyabilir.
| Adım | Ne yapar |
|---|---|
wait-serial: Ready |
önceki bekleme eşleşmelerinden sonra bu metin yazdırılana kadar çalıştır. /pattern/ bir düzenli ifadedir. { text, timeout, board } ne kadar bekleyeceğini ve hangi kartta bekleyeceğini sınırlar |
expect-serial: Ready |
beklemeden, metnin şu ana kadar yazdırılmış olduğunu denetle |
expect-no-serial: error |
yazdırılmamış olduğunu denetle |
write-serial: "hello\n" |
seri monitöre yaz (tam olarak bu metin: Enter için \n ekle). Sayı listesi [104, 105, 10] bu baytları gönderir, Wokwi'deki gibi |
delay: 500ms |
simülasyonun bu kadar süre çalışmasına izin ver |
press: btn1 / release: btn1 |
bir butonu basılı tut veya bırak |
click: btn1 |
bas, 100 ms basılı tut ({ part, hold } ile değiştirilebilir), bırak |
set: { part: dht1, temperature: 30 } |
bir sensörü veya bir kumandayı ayarla; aşağıdaki tabloya bak |
expect-pin: { pin: uno:13, level: high } |
bir pinin seviyesini şimdi denetle. uno:13=high aynı şeydir. Boş bir 13 tek kartın pinidir |
wait-pin: { pin: uno:2, level: low, timeout: 1s } |
pin o seviyeye ulaşana kadar çalıştır |
expect-toggles: { pin: uno:13, during: 1s, min: 3, max: 5 } |
during süresince çalıştır ve pinin değişimlerini say: count, min ve max. Zamanlama böyle denetlenir: 2 Hz'lik bir yanıp sönme saniyede dört değişimdir |
expect-led: led1 |
bir LED'in yandığını denetle; expect-led-off: led1 ise karanlık olduğunu |
expect-probe: { part: servo1, min: 85, max: 95 } |
herhangi bir parçanın okumasını denetle (servonun açısı, ekranın yanan bölümleri, motorun hızı) |
screenshot: build/circuit.svg |
devrenin bir resmini kaydet, her parça şu anki haliyle çizilir. { part: led1, file } tek bir parçayı çizer. Bir ekran parçası ({ part: oled1, file: build/oled.png }) panelin kendi piksellerinin PNG'si olarak kaydedilir. Wokwi'nin part-id ve save-to ile kullanılan take-screenshot özelliği de aynıdır |
take-screenshot: { part-id: oled1, compare-with: ref/oled.png } |
bir ekranın tam olarak referans resmi gösterdiğini denetle. max-diff-pixels: 4 birkaç pikselin farklı olmasına, tolerance: 8 küçük bir renk farkına izin verir. Uyuşmazlıkta çalıştırma ref/oled.diff.png (farklar kırmızıyla) ve ref/oled.actual.png dosyalarını yazar. Henüz referans dosyası yoksa, çalıştırma resmini oraya kaydeder ve bir kez başarısız olur, böylece sen kontrol edip onaylayabilirsin |
expect-display: { part: oled1, lit-min: 200 } |
bir ekranın şu an ne gösterdiğini denetle: lit-min ve lit-max yanan pikselleri sayar, region: [x, y, width, height] panelin bir bölümüne bakar, pixel: { x, y, lit: true } veya pixel: { x, y, color: "#ff8000" } tek bir pikseli denetler, blank: true panelin kapalı olduğunu denetler, matches: ref.png bir resimle karşılaştırır. Yanan, tek renkli panelde panelin mürekkebini, renkli panelde neredeyse siyahtan parlak her şeyi ifade eder |
wait-display: { part: oled1, lit-min: 200, timeout: 2s } |
ekran bunu gösterene kadar çalıştır, wait-serial metni beklediği şekilde |
touch: { part-id: tft1, x: 120, y: 160 } |
dokunmatik panele 50 ms boyunca dokun (duration ile değiştirilebilir); touch-press, touch-move ve touch-release basılı tutar, sürükler ve kaldırır. Kapasitif ILI9341'de koordinatlar Wokwi'deki gibi dokunmatik denetleyicinininkidir; dirençli olanda ise sol üstten itibaren resim pikselleridir |
poke: { part, code } |
aşağıdaki tabloda adı geçmeyen her şey için bir parçaya ham uyaran kodu gönder |
Simülatörde bir LED'in parlaklığı gözün gördüğüdür: tezgah üzerindeki gibi birkaç milisaniye içinde solar. Bu yüzden expect-led, başarısız olmadan önce LED'e ulaşması için 50 ms'ye kadar simüle edilmiş süre verir.
Pinler düzenleyicideki gibi adlandırılır (uno1:13, esp1:D2, pico1:GP15); 13, D13, GP13 ve GPIO13 sırayla denenir. Parçalar, şemadaki id'leriyle veya proje Wokwi'den geldiyse Wokwi id'leriyle adlandırılır.
Sensörler ve kumandalar
| Parça | Kumandalar (set: { part, <control>: <value> }) |
|---|---|
| Basmalı buton, arcade butonu, mikro anahtar | pressed: 1 veya 0 |
| Sürgülü anahtar | value: 0 veya 1 |
| Potansiyometre, sürgülü potansiyometre | position: 0 ile 1 arası (veya 0 ile 1023 arası) |
| DHT11, DHT22, AHT20 | Santigrat cinsinden temperature, % cinsinden humidity |
| DS18B20, LM35, TMP36, NTC modülü | Santigrat cinsinden temperature |
| BMP180, BMP280, BME280 | Santigrat cinsinden temperature, hPa cinsinden pressure, % cinsinden humidity (BME280) |
| HC-SR04 | cm cinsinden distance |
| FC-51 engel sensörü | cm cinsinden distance |
| LDR, LDR modülü, fototransistör, BH1750 | lux |
| PIR | hareket: 1 veya 0 |
| Toprak nemi | nem yüzde olarak |
| MQ-2 | gaz ppm olarak |
| DIP anahtarlar, tuş takımları | value veya keys: bir bit maskesi |
Wokwi CI'dan geçiş
Wokwi proje klasörün olduğu gibi çalışır: diagram.json, wokwi.toml, kod, libraries.txt ve senaryo dosyaların değiştirilmeden okunur. GitHub Actions üzerinde uses: satırını ve token girişinin okuduğu gizli anahtarı değiştir. Action, anahtarı CLI'ya MOKXI_TOKEN olarak geçirir; CLI da onunla planını kontrol eder.
# 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
Devamı Wokwi CI'dan geçiş sayfasında: wokwi-cli seçenekleri, hangi senaryo adımlarının taşındığı, farklı davranan üç şey ve fiyatlarla yan yana karşılaştırma.
CI için hangi plan gerekir
Herkese açık depolarda CI ücretsizdir, anahtar ve hesap gerekmez. GitHub Actions ve gitlab.com üzerinde CLI, deponun adını çalıştırıcının kendisinden alır (GITHUB_REPOSITORY, CI_PROJECT_PATH), Mokxi de herhangi bir kimlik bilgisi olmadan GitHub'a veya GitLab'a sorar: depo herkese açık mı? Böyle bir isteğe özel bir depo görünmez, bu yüzden herkese açık gibi geçemez. GitHub Enterprise ve kendi sunucunda barındırdığın GitLab dışarıdan kontrol edilemez, bu yüzden anahtar ister.
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.
Bir kodu kendi bilgisayarında mokxi run ile çalıştırmak, hesap gerektirmeden ücretsiz kalır.
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.
Önbellekleme ve çevrimdışı kullanım
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.
Ağı olmayan bir makinede, önceden doldurulmuş bir önbellek klasörünü oraya kopyala ve --offline geçir (veya MOKXI_OFFLINE=1 ayarla): hiçbir şey indirilmez ve eksik bir dosya indirme yerine hata olur.