Tài khoản và các gói

Kiểm thử mô phỏng trong CI

Chạy sketch Arduino, ESP32 hoặc Pico của bạn trong trình mô phỏng ở mỗi lần đẩy mã, và báo lỗi biên dịch khi đầu ra hoặc một chân sai. Miễn phí cho kho mã công khai.

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 gói nào cần cho CI); trên chính máy tính của bạn thì không cần tài khoản nào cả. Nó đọc các dự án Wokwi và các tệp kịch bản Wokwi đúng như nguyên gốc, nên chuyển từ Wokwi CI chỉ cần đổi một dòng.

Bắt đầu nhanh

Trong một thư mục có sketch (và, nếu có nhiều hơn một bo mạch trơn, một tệp diagram.json từ Mokxi hoặc Wokwi):

npx @mokxi/cli run --timeout 10s --expect-serial "Ready" --fail-on "panic"

Lệnh đó biên dịch sketch, chạy nó, in ra đầu ra serial khi có, và thoát ngay khi Ready xuất hiện (mã thoát 0). Nó thất bại với mã thoát 1 ngay khi sketch in ra panic, khi 10 giây thời gian mô phỏng trôi qua mà chưa thấy Ready, hoặc khi sketch không biên dịch được. Chỉ cần Node.js 18 trở lên.

Khi cần nhiều hơn một dòng đầu ra, hãy viết một kịch bản. Đặt đoạn này vào mokxi.test.yaml cạnh 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

và chạy mọi bài kiểm tra trong đó, kèm báo cáo JUnit cho bảng điều khiển CI của bạn:

npx @mokxi/cli test --junit mokxi-junit.xml

Mỗi bài kiểm tra là một lần chạy sketch mới hoàn toàn, và mỗi bài là một test case trong báo cáo.

Trên 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 chạy mokxi.test.yaml nếu thư mục có tệp này, nếu không thì kiểm tra sketch khởi động và in ra đúng đoạn chữ mong đợi. Nó giữ trình biên dịch trong cache của Actions nên chỉ cần tải xuống một lần, ghi mokxi-junit.xml, đưa bảng kết quả vào tóm tắt job, và chú thích mỗi lỗi vào lượt chạy, lỗi biên dịch nằm trên dòng riêng. Mọi input đều được liệt kê trong action.yml của action: path, scenario, timeout, expect-serial, fail-on, board, firmware, junit, serial-log, screenshot, args, version và token (một CI token, chỉ cần cho kho lưu trữ riêng tư).

Trên CI khác

Dòng lệnh chính là toàn bộ sản phẩm, nên bất cứ đâu chạy được Node đều hoạt động giống hệt. Ví dụ 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

Giữ thư mục cache giữa các job (MOKXI_CACHE_DIR, hoặc ~/.cache/mokxi theo mặc định). Nếu không, mỗi job lại tải trình biên dịch một lần nữa, và mokxi.com giới hạn tần suất một địa chỉ được làm vậy.

Nó chạy những gì

mokxi run và mokxi test nhận một thư mục, một tệp hoặc một liên kết:

Những gì Nó được đọc thế nào
Một thư mục từ mokxi pull hoặc Lưu lên GitHub diagram.mokxi.json và thư mục sketch bên cạnh nó
Một thư mục dự án Wokwi diagram.json, sketch cùng các tab của nó, libraries.txt, và wokwi.toml
Một thư mục sketch Arduino thông thường một bo mạch trơn cho sketch: một Uno, hoặc ghi rõ bằng --board esp32
Một tệp .mokxi.json tệp mà nút Download JSON của trình soạn thảo ghi ra
https://mokxi.com/p/<id> một dự án công khai, hoặc của chính bạn với mokxi login hoặc MOKXI_TOKEN
https://wokwi.com/projects/<id> một dự án Wokwi công khai, được lấy từ Wokwi

Sketch được biên dịch cho bo mạch trong sơ đồ, với thư viện riêng của dự án và các thư viện Arduino phổ biến mà Mokxi mang sẵn. Để chạy bản build của riêng bạn thay vào đó (của PlatformIO hoặc arduino-cli), hãy truyền vào: --firmware build/sketch.ino.elf, hoặc --firmware uno1=build/a.elf cho một trong nhiều bo mạch. Khi wokwi.toml của một dự án Wokwi chỉ định một tệp firmware tồn tại, bản build đó sẽ được chạy, như Wokwi vẫn làm; --compile sẽ biên dịch sketch thay vào đó.

Mọi bo mạch mà Mokxi mô phỏng đều chạy được ở đây: Uno, Nano, Mega, Leonardo, Pro Mini và ATtiny85, ESP32, ESP32-S3, ESP32-C3, ESP32-C6 và ESP8266, Pico và Pico W, UNO R4, các bo mạch STM32, XIAO và micro:bit. mokxi boards liệt kê tất cả.

Tham chiếu lệnh

Tùy chọn Công dụng
--timeout 10s thời gian mô phỏng tối đa mà lượt chạy (hoặc mỗi kịch bản) được phép. Một số trơn tính bằng mili giây, giống CLI của Wokwi
--expect-serial TEXT đạt ngay khi mọi đoạn chữ như vậy đã được in ra. Lặp lại tùy chọn cho nhiều đoạn. --expect-text cũng tương tự
--fail-on TEXT thất bại ngay khi đoạn chữ này được in ra. --fail-text cũng tương tự
--scenario FILE chạy tệp kịch bản này (mokxi run --scenario chính là mokxi test)
--junit FILE ghi một báo cáo JUnit XML
--serial-log-file FILE ghi lại mọi thứ các bo mạch đã in ra
--screenshot FILE cho mokxi run: một ảnh chụp khi lượt chạy kết thúc. --screenshot-part oled1 chụp một linh kiện: một màn hình (OLED, TFT, LCD, e-paper, LED matrix) thành tệp PNG theo đúng điểm ảnh của nó, còn lại là bản vẽ SVG. --screenshot-time 2s chụp vào thời điểm đó thay vì cuối. --screenshot-file cũng tương tự; nếu chỉ có --screenshot-part, tệp là screenshot.png, giống Wokwi
--vcd-file FILE ghi những gì các máy phân tích logic trong mạch đã ghi lại thành tệp VCD (GTKWave, PulseView), mỗi cạnh tín hiệu đúng đến nanô giây. Một tệp cho mỗi kịch bản trong mokxi test
--shard 2/3 cho mokxi test: chạy phần thứ hai trong ba phần bằng nhau của các kịch bản, để một ma trận CI ba job chạy chúng song song
--firmware [board=]FILE, --elf FILE chạy bản build này thay vì biên dịch
--board TYPE bo mạch dùng cho sketch không có sơ đồ
--diagram-file FILE đọc sơ đồ này thay vì diagram.json của thư mục
--compile biên dịch sketch ngay cả khi wokwi.toml chỉ định một tệp firmware
--timeout-exit-code N mã thoát khi hết thời gian chờ (mặc định 1; CLI của Wokwi dùng 42)
--offline không bao giờ truy cập mạng; thất bại nếu trình biên dịch chưa có trong cache
--quiet không in serial output (mokxi run)
--verbose in serial output và từng bước (mokxi test)

mokxi lint [dir] đọc dự án theo cách một lượt chạy vẫn đọc và liệt kê những gì sai trong mạch mà không cần biên dịch hay chạy: một linh kiện Mokxi không mô phỏng, một dây nối vào chân không tồn tại. Nó thoát với mã 1 khi có lỗi, hoặc khi có cảnh báo kèm --warnings-as-errors; --ignore-warnings chỉ in lỗi ra.

Mỗi lượt chạy in ra thời gian mô phỏng đã trải qua, việc đó mất bao lâu, và chạy nhanh gấp bao nhiêu lần so với thời gian thực; báo cáo JUnit và tóm tắt job mang cùng các con số đó.

Mã thoát: 0 khi mọi thứ đạt, 1 khi có gì đó thất bại (một phép kiểm tra, hết thời gian chờ, một dòng --fail-on, lỗi biên dịch), 2 khi có lỗi trong lệnh hoặc tệp kịch bản, và 3 khi tải xuống thất bại hoặc CI cần một gói. Một tùy chọn CLI của Wokwi mà Mokxi chưa có (--heap-min-free, --coverage-file, --sdcard, --interactive, --gdb-server-port) cho mã thoát 2, nên một lượt chạy không bao giờ đạt khi thiếu phép kiểm tra nó được yêu cầu.

Trong GitHub Actions, mỗi kịch bản bị lỗi hiện thành một ghi chú trên dòng của bước bị lỗi, kèm các dòng cuối cùng mà bo mạch in ra, và phần tóm tắt job có một bảng mọi kịch bản, mỗi lỗi kèm một đoạn serial được gấp lại.

Thời gian trong một lần chạy là thời gian mô phỏng, không phải thời gian thực, nên bài kiểm tra chạy giống nhau trên laptop nhanh hay máy CI chậm. Một lần chạy lâu hơn nhiều so với mức đáng lẽ (30 lần thời gian chờ của nó, hoặc ít nhất hai phút) sẽ bị dừng vì bị coi là kẹt.

Tham chiếu kịch bản

Tệp kịch bản là YAML. Nó chứa một kịch bản (steps: ở đầu) hoặc nhiều kịch bản (tests:, một danh sách gồm name và steps):

Phím Đây là gì
name tên tệp trong báo cáo
project dự án cần chạy, tính theo đường dẫn tương đối so với tệp: một thư mục, một tệp hoặc một liên kết. Mặc định: thư mục chứa chính tệp đó
board bo mạch dùng cho sketch không có sơ đồ
firmware một bản biên dịch cần chạy thay vì biên dịch lại: một đường dẫn, hoặc { board: path }
timeout thời gian mô phỏng mà mỗi kịch bản được phép chạy (mặc định 30 s với mokxi test)
fail-on đoạn văn bản khiến kịch bản bị lỗi ngay khi được in ra: một đoạn hoặc một danh sách
steps các bước của một kịch bản
tests một vài kịch bản, mỗi cái { name, steps, timeout?, fail-on? }

Các bước chạy theo thứ tự, và kịch bản dừng ở bước đầu tiên bị lỗi. Bất kỳ bước nào cũng có thể có name: để hiển thị trong báo cáo.

Bước Công dụng
wait-serial: Ready chạy cho đến khi văn bản này được in ra sau những gì các lần chờ trước đó đã khớp. /pattern/ là một biểu thức chính quy. { text, timeout, board } giới hạn thời gian chờ và bo mạch nào được chờ
expect-serial: Ready kiểm tra văn bản đã được in ra cho đến thời điểm này, không chờ đợi
expect-no-serial: error kiểm tra rằng nó chưa được in ra
write-serial: "hello\n" gõ vào Serial Monitor (đúng nguyên văn bản này: thêm \n cho phím Enter). Một danh sách số, [104, 105, 10], gửi đúng các byte đó, giống như Wokwi
delay: 500ms để mô phỏng chạy trong khoảng thời gian này
press: btn1 / release: btn1 giữ một nút nhấn ở trạng thái nhấn, hoặc thả ra
click: btn1 nhấn, giữ 100 ms ({ part, hold } để thay đổi), thả ra
set: { part: dht1, temperature: 30 } đặt giá trị cho một cảm biến hoặc một điều khiển; xem bảng dưới đây
expect-pin: { pin: uno:13, level: high } kiểm tra mức của một chân vào lúc này. uno:13=high cũng giống vậy. Một 13 đứng riêng là chân của bo mạch duy nhất
wait-pin: { pin: uno:2, level: low, timeout: 1s } chạy cho đến khi chân đạt mức đó
expect-toggles: { pin: uno:13, during: 1s, min: 3, max: 5 } chạy trong during và đếm số lần chân đổi mức: count, min và max. Đây là cách kiểm tra thời gian: nhấp nháy 2 Hz là bốn lần đổi mỗi giây
expect-led: led1 kiểm tra một LED sáng; expect-led-off: led1 để kiểm tra nó tắt
expect-probe: { part: servo1, min: 85, max: 95 } kiểm tra số đọc của bất kỳ linh kiện nào (góc của servo, các đoạn sáng của màn hình, tốc độ của động cơ)
screenshot: build/circuit.svg lưu một ảnh chụp của mạch, mọi linh kiện được vẽ đúng như hiện tại. { part: led1, file } vẽ một linh kiện. Một linh kiện màn hình ({ part: oled1, file: build/oled.png }) được lưu thành PNG từ chính các điểm ảnh của bảng điều khiển. Lệnh take-screenshot của Wokwi với part-id và save-to cũng giống vậy
take-screenshot: { part-id: oled1, compare-with: ref/oled.png } kiểm tra một màn hình hiển thị đúng như ảnh tham chiếu. max-diff-pixels: 4 cho phép một vài điểm ảnh khác nhau, tolerance: 8 cho một chênh lệch màu nhỏ. Khi không khớp, lần chạy ghi ra ref/oled.diff.png (các khác biệt màu đỏ) và ref/oled.actual.png. Nếu chưa có tệp tham chiếu, lần chạy sẽ lưu ảnh của nó vào đó và lỗi một lần, để bạn kiểm tra rồi commit
expect-display: { part: oled1, lit-min: 200 } kiểm tra màn hình đang hiển thị gì: lit-min và lit-max đếm điểm ảnh sáng, region: [x, y, width, height] xem một phần của bảng, pixel: { x, y, lit: true } hoặc pixel: { x, y, color: "#ff8000" } kiểm tra một điểm ảnh, blank: true kiểm tra bảng tắt, matches: ref.png so sánh với một ảnh. Sáng nghĩa là mực hiển thị của bảng trên bảng đơn sắc, và bất cứ gì sáng hơn gần đen trên bảng màu
wait-display: { part: oled1, lit-min: 200, timeout: 2s } chạy cho đến khi màn hình hiển thị điều đó, giống cách wait-serial chờ văn bản
touch: { part-id: tft1, x: 120, y: 160 } chạm vào màn hình cảm ứng trong 50 ms (duration để thay đổi); touch-press, touch-move và touch-release để giữ, kéo và nhấc lên. Trên ILI9341 điện dung, tọa độ là của bộ điều khiển cảm ứng, giống như Wokwi; trên loại điện trở, tọa độ là điểm ảnh tính từ góc trên bên trái
poke: { part, code } gửi cho một linh kiện một mã kích thích thô, cho bất kỳ thứ gì bảng dưới đây không nêu

Độ sáng của LED trong trình mô phỏng là những gì mắt thấy: nó mờ dần trong vài mili giây, như ngoài thực tế. Vì vậy expect-led cho LED tối đa 50 ms thời gian mô phỏng để đạt mức đó trước khi báo lỗi.

Chân được đặt tên như trong trình soạn thảo (uno1:13, esp1:D2, pico1:GP15); 13, D13, GP13 và GPIO13 đều được thử lần lượt. Linh kiện được đặt tên theo id của nó trong sơ đồ, hoặc theo id Wokwi nếu dự án đến từ Wokwi.

Cảm biến và điều khiển

Linh kiện Điều khiển (set: { part, <control>: <value> })
Nút nhấn, nút arcade, công tắc nhỏ pressed: 1 hoặc 0
Công tắc gạt value: 0 hoặc 1
Biến trở, biến trở trượt position: từ 0 đến 1 (hoặc từ 0 đến 1023)
DHT11, DHT22, AHT20 temperature theo độ C, humidity theo %
DS18B20, LM35, TMP36, mô-đun NTC temperature theo độ C
BMP180, BMP280, BME280 temperature theo độ C, pressure theo hPa, humidity theo % (BME280)
HC-SR04 distance theo cm
Cảm biến vật cản FC-51 distance theo cm
LDR, mô-đun LDR, phototransistor, BH1750 lux
PIR chuyển động: 1 hoặc 0
Độ ẩm đất độ ẩm theo %
MQ-2 khí gas theo ppm
DIP switch, bàn phím ma trận value hoặc keys: một bitmask

Chuyển từ Wokwi CI

Thư mục dự án Wokwi của bạn chạy nguyên trạng: diagram.json, wokwi.toml, sketch, libraries.txt và các tệp scenario được đọc không thay đổi. Trên GitHub Actions, đổi dòng uses: và secret mà đầu vào token đọc. Action truyền token cho CLI dưới dạng MOKXI_TOKEN, nó dùng token đó để kiểm tra gói của bạn.

# 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

Chuyển từ Wokwi CI có phần còn lại: các tùy chọn của wokwi-cli, những bước scenario nào được giữ lại, ba điểm khác biệt, và bảng so sánh kèm bảng giá.

CI cần gói nào

Kho lưu trữ công khai chạy CI miễn phí, không cần token hay tài khoản. Trên GitHub Actions và gitlab.com, CLI lấy tên kho lưu trữ từ chính runner (GITHUB_REPOSITORY, CI_PROJECT_PATH), và Mokxi hỏi GitHub hoặc GitLab, không cần bất kỳ thông tin đăng nhập nào, xem kho đó có công khai không. Một kho riêng tư sẽ như không tồn tại với kiểu yêu cầu này, nên không thể bị coi là công khai. GitHub Enterprise và GitLab tự quản không thể kiểm tra từ bên ngoài, nên chúng cần 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.

Chạy sketch trên máy của bạn với mokxi run vẫn miễn phí, không cần tài khoản.

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 và dùng ngoại tuyến

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.

Trên máy không có mạng, hãy chép thư mục cache đã sẵn sàng sang đó và truyền --offline (hoặc đặt MOKXI_OFFLINE=1): không tải gì thêm, và một tệp bị thiếu sẽ là lỗi thay vì được tải xuống.