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)؛ أما على حاسوبك الخاص فلا يحتاج إلى حساب إطلاقًا. يقرأ مشاريع Wokwi وملفات سيناريو Wokwi كما هي، لذا الانتقال من Wokwi CI لا يتطلب سوى تغيير سطر واحد.
بداية سريعة
في مجلد يحتوي على كود (وإذا كان فيه أكثر من لوحة فارغة، ملف diagram.json من Mokxi أو Wokwi):
npx @mokxi/cli run --timeout 10s --expect-serial "Ready" --fail-on "panic"
يقوم ذلك بترجمة الكود وتشغيله، ويطبع المخرج التسلسلي فور وروده، وينتهي بمجرد ظهور Ready (رمز خروج 0). ويفشل برمز خروج 1 لحظة طباعة الكود لـ panic، أو عند مرور 10 ثوانٍ من وقت المحاكاة دون ظهور Ready، أو عندما لا تتم ترجمة الكود. كل ما يحتاجه هو Node.js 18 أو أحدث.
لمخرج يتجاوز سطرًا واحدًا، اكتب سيناريو. ضع هذا في mokxi.test.yaml بجوار الكود:
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
وشغّل كل اختبار فيه، مع تقرير JUnit للوحة معلومات CI لديك:
npx @mokxi/cli test --junit mokxi-junit.xml
كل اختبار هو تشغيل جديد للكود، وكل واحد يمثل حالة اختبار في التقرير.
على 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 ملف mokxi.test.yaml إذا وُجد في المجلد، وإلا تتحقق من أن الكود يقلع ويطبع النص المتوقع. تحتفظ بالمترجم في ذاكرة Actions المؤقتة، فيُنزَّل مرة واحدة فقط، وتكتب mokxi-junit.xml، وتضع جدولًا بالنتائج في ملخص المهمة، وتضيف تعليقًا على التشغيل عند كل فشل، مع خطأ الترجمة في سطر مستقل. كل المدخلات مدرجة في ملف action.yml الخاص بالـ action: path وscenario وtimeout وexpect-serial وfail-on وboard وfirmware وjunit وserial-log وscreenshot وargs وversion وtoken (رمز CI، يلزم فقط للمستودعات الخاصة).
على أي CI آخر
سطر الأوامر هو المنتج بأكمله، لذا أي شيء يشغّل Node يعمل بالطريقة نفسها. 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
احتفظ بمجلد الذاكرة المؤقتة بين المهام (MOKXI_CACHE_DIR، أو ~/.cache/mokxi افتراضيًا). بدونه تُنزّل كل مهمة المترجم من جديد، وmokxi.com يحدّ من عدد مرات ذلك لكل عنوان واحد.
ما الذي يشغّله
يأخذ mokxi run وmokxi test مجلدًا أو ملفًا أو رابطًا:
| ما هي؟ | كيف تُقرأ |
|---|---|
مجلد من mokxi pull أو حفظ على GitHub |
diagram.mokxi.json ومجلد الكود بجانبه |
| مجلد مشروع Wokwi | diagram.json والكود وتبويباته وlibraries.txt وwokwi.toml |
| مجلد كود Arduino عادي | لوحة فارغة للكود: Uno، أو حدّدها بـ --board esp32 |
ملف .mokxi.json |
الملف الذي يكتبه زر تنزيل JSON في المحرر |
https://mokxi.com/p/<id> |
مشروع عام، أو مشروعك الخاص مع mokxi login أو MOKXI_TOKEN |
https://wokwi.com/projects/<id> |
مشروع Wokwi عام، يُجلب من Wokwi |
يُترجم الكود للوحة الموجودة في المخطط، مع مكتبات المشروع نفسه ومكتبات Arduino الشائعة التي يضمّها Mokxi. ولتشغيل بناء خاص بك بدلًا من ذلك (من PlatformIO أو arduino-cli)، مرّره: --firmware build/sketch.ino.elf، أو --firmware uno1=build/a.elf للوحة واحدة من عدة لوحات. وعندما يذكر ملف wokwi.toml في مشروع Wokwi ملف بناء موجودًا، يُشغَّل ذلك البناء، كما يفعل Wokwi؛ و--compile يبني الكود بدلًا منه.
كل لوحة يحاكيها Mokxi تعمل هنا: Uno وNano وMega وLeonardo وPro Mini وATtiny85، وESP32 وESP32-S3 وESP32-C3 وESP32-C6 وESP8266، وPico وPico W، وUNO R4، ولوحات STM32، وXIAO وmicro:bit. يعرضها mokxi boards.
مرجع الأوامر
| الخيار | ماذا تفعل |
|---|---|
--timeout 10s |
أقصى وقت محاكاة قد يستغرقه التشغيل (أو كل سيناريو). الرقم المجرد يعني ميلي ثانية، كما في واجهة Wokwi السطرية |
--expect-serial TEXT |
ينجح بمجرد طباعة كل نص من هذه النصوص. كرّره لعدة نصوص. --expect-text يفعل الشيء نفسه |
--fail-on TEXT |
يفشل لحظة طباعة هذا النص. --fail-text يفعل الشيء نفسه |
--scenario FILE |
شغّل ملف السيناريو هذا (mokxi run --scenario هو نفسه mokxi test) |
--junit FILE |
اكتب تقرير JUnit بصيغة XML |
--serial-log-file FILE |
اكتب كل ما طبعته اللوحات |
--screenshot FILE |
لـ mokxi run: صورة عند انتهاء التشغيل. --screenshot-part oled1 يصوّر قطعة واحدة: شاشة (OLED أو TFT أو LCD أو ورق إلكتروني أو مصفوفة LED) كملف PNG من بكسلاتها نفسها، وأي شيء آخر كرسم SVG. --screenshot-time 2s يلتقطها في تلك اللحظة بدلًا من ذلك. --screenshot-file يفعل الشيء نفسه؛ ومع --screenshot-part وحده يكون الملف screenshot.png، كما في Wokwi |
--vcd-file FILE |
اكتب ما سجّلته محللات الإشارة المنطقية في الدائرة كملف VCD (لـ GTKWave وPulseView)، مع كل حافة إشارة بدقة النانو ثانية. ملف واحد لكل سيناريو في mokxi test |
--shard 2/3 |
لـ mokxi test: شغّل الجزء الثاني من ثلاثة أجزاء متساوية من السيناريوهات، بحيث تشغّلها مصفوفة CI من ثلاث مهام بالتوازي |
--firmware [board=]FILE و--elf FILE |
شغّل هذا البناء بدلًا من الترجمة |
--board TYPE |
اللوحة المستخدمة لكود بلا مخطط |
--diagram-file FILE |
اقرأ هذا المخطط بدلًا من diagram.json الموجود في المجلد |
--compile |
ابنِ الكود حتى عندما يذكر wokwi.toml ملف بناء |
--timeout-exit-code N |
رمز الخروج عند انتهاء المهلة (الافتراضي 1؛ واجهة Wokwi السطرية تستخدم 42) |
--offline |
لا تتصل بالشبكة إطلاقًا؛ افشل إذا لم يكن المترجم في الذاكرة المؤقتة |
--quiet |
لا تطبع المخرج التسلسلي (mokxi run) |
--verbose |
اطبع المخرج التسلسلي وكل خطوة (mokxi test) |
يقرأ mokxi lint [dir] المشروع بالطريقة نفسها التي يقرأ بها التشغيل، ويسرد ما هو خطأ في الدائرة دون ترجمة أو تشغيل: قطعة لا يحاكيها Mokxi، أو سلك موصول بطرف غير موجود. يخرج برمز 1 عند خطأ، أو عند تحذير مع --warnings-as-errors؛ و--ignore-warnings يطبع الأخطاء فقط.
يطبع كل تشغيل مقدار وقت المحاكاة الذي غطّاه، وكم استغرق ذلك فعليًا، وكم مرة كان أسرع من الوقت الحقيقي؛ ويحمل تقرير JUnit وملخص المهمة الأرقام نفسها.
رموز الخروج: 0 عند نجاح كل شيء، و1 عند فشل شيء ما (فحص، أو انتهاء مهلة، أو سطر --fail-on، أو خطأ ترجمة)، و2 لخطأ في الأمر أو ملف السيناريو، و3 عند فشل تنزيل أو عندما يحتاج CI إلى باقة. أي خيار من واجهة Wokwi السطرية لا يدعمه Mokxi بعد (--heap-min-free و--coverage-file و--sdcard و--interactive و--gdb-server-port) يعطي الخروج 2، فلا ينجح تشغيل أبدًا دون فحص طُلب منه.
في GitHub Actions، يظهر كل سيناريو فاشل كتعليق توضيحي على سطر الخطوة التي فشلت، مع آخر الأسطر التي طبعتها اللوحة، ويتضمن ملخص المهمة جدولاً بكل سيناريو مع مقتطف تسلسلي مطوي تحت كل فشل.
الوقت أثناء التشغيل هو وقت محاكى وليس وقت الساعة الحقيقية، لذا يتصرف الاختبار بالطريقة نفسها على حاسوب سريع وآلة CI بطيئة. أما التشغيل الذي يستغرق في الواقع وقتاً أطول بكثير مما يجب (30 ضعف مهلته، أو دقيقتين على الأقل) فيتم إيقافه باعتباره عالقاً.
مرجع السيناريوهات
ملف السيناريو بصيغة YAML. يحتوي على سيناريو واحد (steps: في الأعلى) أو عدة سيناريوهات (tests:، وهي قائمة من name وsteps):
| مفتاح | ما هي |
|---|---|
name |
اسم الملف في التقرير |
project |
المشروع الذي سيُشغَّل، بشكل نسبي إلى الملف: مجلد أو ملف أو رابط. الافتراضي: مجلد الملف نفسه |
board |
اللوحة المستخدمة لكود بلا مخطط |
firmware |
بناء جاهز يُشغَّل بدلاً من الترجمة: مسار، أو { board: path } |
timeout |
الوقت المحاكى الذي قد يستغرقه كل سيناريو (الافتراضي 30 ثانية لأمر mokxi test) |
fail-on |
نص يجعل السيناريو يفشل فور طباعته: نص واحد أو قائمة |
steps |
خطوات سيناريو واحد |
tests |
عدة سيناريوهات، كل واحد { name, steps, timeout?, fail-on? } |
تُنفَّذ الخطوات بالترتيب، ويتوقف السيناريو عند أول خطوة تفشل. يمكن لأي خطوة أن تحمل name: ليُستخدم في التقرير.
| الخطوة | ماذا تفعل |
|---|---|
wait-serial: Ready |
شغِّل حتى يُطبع هذا النص بعد ما تطابقت معه الانتظارات السابقة. الصيغة /pattern/ هي تعبير نمطي. و{ text, timeout, board } تحدّد مدة الانتظار وعلى أي لوحة |
expect-serial: Ready |
تحقق أن النص قد طُبع حتى الآن، دون انتظار |
expect-no-serial: error |
تحقق أنه لم يُطبع |
write-serial: "hello\n" |
اكتب في الشاشة التسلسلية (هذا النص بالضبط: أضف \n لـ Enter). قائمة أرقام، مثل [104, 105, 10]، ترسل تلك البايتات كما في Wokwi |
delay: 500ms |
اترك المحاكاة تعمل لهذه المدة |
press: btn1 / release: btn1 |
اضغط زراً باستمرار أو اتركه |
click: btn1 |
اضغط، واستمر 100 ms ({ part, hold } لتغيير المدة)، ثم ارفع |
set: { part: dht1, temperature: 30 } |
اضبط حساساً أو عنصر تحكم، راجع الجدول أدناه |
expect-pin: { pin: uno:13, level: high } |
تحقق من مستوى طرف الآن. uno:13=high تعني الشيء نفسه. الرقم المجرد 13 هو طرف اللوحة الوحيدة |
wait-pin: { pin: uno:2, level: low, timeout: 1s } |
شغِّل حتى يصل الطرف إلى ذلك المستوى |
expect-toggles: { pin: uno:13, during: 1s, min: 3, max: 5 } |
شغِّل مدة during واحسب تغيّرات الطرف: count وmin وmax. هكذا يُفحص التوقيت: وميض بتردد 2 Hz يعني أربع تغيّرات في الثانية |
expect-led: led1 |
تحقق أن LED مضاءة، وexpect-led-off: led1 تتحقق أنها مطفأة |
expect-probe: { part: servo1, min: 85, max: 95 } |
تحقق من قراءة أي قطعة (زاوية محرك سيرفو، أو المقاطع المضاءة في شاشة، أو سرعة محرك) |
screenshot: build/circuit.svg |
احفظ صورة للدائرة، كل قطعة مرسومة كما هي الآن. الصيغة { part: led1, file } ترسم قطعة واحدة. قطعة شاشة ({ part: oled1, file: build/oled.png }) تُحفظ كصورة PNG من بكسلات اللوحة نفسها. أمر Wokwi take-screenshot مع part-id وsave-to يؤدي الشيء نفسه |
take-screenshot: { part-id: oled1, compare-with: ref/oled.png } |
تحقق أن الشاشة تعرض الصورة المرجعية بالضبط. max-diff-pixels: 4 يسمح باختلاف بضعة بكسلات، وtolerance: 8 بفرق لوني بسيط. عند عدم التطابق يكتب التشغيل ref/oled.diff.png (الاختلافات باللون الأحمر) وref/oled.actual.png. وإذا لم يوجد ملف مرجعي بعد، يحفظ التشغيل صورته هناك ويفشل مرة واحدة، لتتمكن من مراجعته وتثبيته |
expect-display: { part: oled1, lit-min: 200 } |
تحقق مما تعرضه الشاشة الآن: lit-min وlit-max تحسبان البكسلات المضاءة، وregion: [x, y, width, height] تنظر إلى جزء من اللوحة، وpixel: { x, y, lit: true } أو pixel: { x, y, color: "#ff8000" } تفحصان بكسلاً واحداً، وblank: true تتحقق أن اللوحة مطفأة، وmatches: ref.png تقارن بصورة. المضاء يعني حبر اللوحة في اللوحات أحادية اللون، وأي شيء أسطع من شبه الأسود في اللوحات الملونة |
wait-display: { part: oled1, lit-min: 200, timeout: 2s } |
شغِّل حتى تعرض الشاشة ذلك، بالطريقة التي ينتظر بها wait-serial نصاً |
touch: { part-id: tft1, x: 120, y: 160 } |
اضغط على لوحة اللمس لمدة 50 ميلي ثانية (duration لتغييرها)؛ touch-press وtouch-move وtouch-release تعني الضغط والسحب ورفع الإصبع. في لوحة ILI9341 السعوية تكون الإحداثيات تابعة لمتحكم اللمس كما في Wokwi؛ وفي اللوحة المقاومة تكون إحداثيات بكسلات الصورة تبدأ من الزاوية العلوية اليسرى |
poke: { part, code } |
أرسل إلى قطعة رمز تحفيز خام، لأي شيء لا يذكره الجدول أدناه |
سطوع LED في المحاكي هو ما تراه العين: يتلاشى خلال بضعة أجزاء من الثانية، كما على المنضدة. لذا يمنح expect-led الـ LED حتى 50 ms من الوقت المحاكى للوصول إلى الحالة قبل أن تفشل.
تُسمى الأطراف كما في المحرر (uno1:13، esp1:D2، pico1:GP15)، ويجرب كل صيغة من 13 وD13 وGP13 وGPIO13. أما القطع فتسمى بمعرّفها في المخطط، أو بمعرّف Wokwi إذا كان المشروع قادماً من Wokwi.
الحساسات وعناصر التحكم
| قطعة | عناصر التحكم (set: { part, <control>: <value> }) |
|---|---|
| زر ضغط، زر ألعاب، مفتاح دقيق | pressed: 1 أو 0 |
| مفتاح انزلاقي | value: 0 أو 1 |
| مقاومة متغيرة، مقاومة متغيرة منزلقة | position: من 0 إلى 1 (أو من 0 إلى 1023) |
| DHT11, DHT22, AHT20 | temperature بالدرجة المئوية، وhumidity بـ % |
| DS18B20, LM35, TMP36, وحدة NTC | temperature بالدرجة المئوية |
| BMP180, BMP280, BME280 | temperature بالدرجة المئوية، وpressure بـ hPa، وhumidity بـ % (BME280) |
| HC-SR04 | distance بالسنتيمتر |
| حساس العوائق FC-51 | distance بالسنتيمتر |
| LDR، وحدة LDR، ترانزستور ضوئي، BH1750 | lux |
| PIR | الحركة: 1 أو 0 |
| رطوبة التربة | الرطوبة بالنسبة المئوية % |
| MQ-2 | الغاز بوحدة ppm |
| مفاتيح DIP، لوحات المفاتيح | value أو keys: قناع بتات |
الانتقال من Wokwi CI
يعمل مجلد مشروع Wokwi لديك كما هو: يُقرأ diagram.json وwokwi.toml والكود وlibraries.txt وملفات السيناريو دون أي تغيير. على GitHub Actions، غيّر سطر uses: والسرّ الذي يقرأه مُدخل token. يمرّر الإجراء الرمز إلى أداة سطر الأوامر بصيغة MOKXI_TOKEN، وهي تتحقق من باقتك بواسطته.
# 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
يحتوي الانتقال من Wokwi CI على البقية: خيارات wokwi-cli، وأي خطوات سيناريو تُنقل كما هي، والأمور الثلاثة التي تختلف في سلوكها، ومقارنة جنباً إلى جنب مع الأسعار.
أي باقة يحتاجها CI
تعمل المستودعات العامة على CI مجاناً، دون رمز ودون حساب. على GitHub Actions وعلى gitlab.com، تأخذ أداة سطر الأوامر اسم المستودع من المشغّل نفسه (GITHUB_REPOSITORY، CI_PROJECT_PATH)، ويسأل Mokxi خدمة GitHub أو GitLab، دون أي بيانات دخول، إن كان المستودع عاماً. يبدو المستودع الخاص مفقوداً لمثل هذا الطلب، فلا يمكن أن يُحسب عاماً. أما GitHub Enterprise وGitLab المُدار ذاتياً فلا يمكن التحقق منهما من الخارج، لذا يحتاجان إلى رمز.
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.
يبقى تشغيل الكود على حاسوبك الخاص باستخدام mokxi run مجانياً، دون حساب.
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.
التخزين المؤقت والعمل دون اتصال
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.
على جهاز بلا شبكة، انسخ إليه مجلد تخزين مؤقت ممتلئاً ومرّر --offline (أو اضبط MOKXI_OFFLINE=1): لن يُنزَّل أي شيء، ويُعدّ الملف المفقود خطأً لا عملية تنزيل.