الحسابات والباقات

اختبارات المحاكاة في CI

شغّل كود Arduino أو ESP32 أو Pico الخاص بك في المحاكي مع كل push، وأفشل البناء عندما يكون المخرج أو أحد الأطراف خاطئًا. مجاني للمستودعات العامة.

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): لن يُنزَّل أي شيء، ويُعدّ الملف المفقود خطأً لا عملية تنزيل.