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 qual plano o CI precisa); no seu próprio computador ele não precisa de conta nenhuma. Ele lê projetos do Wokwi e arquivos de cenário do Wokwi como são, então sair do Wokwi CI é uma mudança de uma linha.
Início rápido
Em uma pasta com um sketch (e, se ele tiver mais que uma placa sozinha, um diagram.json do Mokxi ou do Wokwi):
npx @mokxi/cli run --timeout 10s --expect-serial "Ready" --fail-on "panic"
Isso compila o sketch, roda, imprime a saída serial conforme ela chega e sai assim que Ready aparece (código de saída 0). Ele falha com código de saída 1 no momento em que o sketch imprime panic, quando passam 10 segundos de tempo simulado sem Ready, ou quando o sketch não compila. Node.js 18 ou mais novo é tudo de que ele precisa.
Para mais de uma linha de saída, escreva um cenário. Coloque isto em mokxi.test.yaml ao lado do 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
e rode todos os testes dele, com um relatório JUnit para o painel do seu CI:
npx @mokxi/cli test --junit mokxi-junit.xml
Cada teste é uma execução nova do sketch, e cada um é um caso de teste no relatório.
No 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
A action roda o mokxi.test.yaml quando a pasta tem um e, caso contrário, verifica se o sketch inicializa e imprime o texto esperado. Ela mantém o compilador no cache do Actions, então ele é baixado uma vez, escreve mokxi-junit.xml, coloca uma tabela dos resultados no resumo do job e anota a execução com cada falha, um erro de compilação em sua própria linha. Toda entrada está listada na action.yml da action: path, scenario, timeout, expect-serial, fail-on, board, firmware, junit, serial-log, screenshot, args, version e token (um token de CI, necessário apenas para um repositório privado).
Em qualquer outro CI
A linha de comando é o produto inteiro, então qualquer coisa que rode Node funciona do mesmo jeito. GitLab CI, por exemplo:
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
Mantenha a pasta de cache entre os jobs (MOKXI_CACHE_DIR, ou ~/.cache/mokxi por padrão). Sem ela, cada job baixa o compilador de novo, e o mokxi.com limita com que frequência um endereço pode fazer isso.
O que ele roda
mokxi run e mokxi test aceitam uma pasta, um arquivo ou um link:
| O quê | Como ele é lido |
|---|---|
Uma pasta do mokxi pull ou de Save to GitHub |
diagram.mokxi.json e a pasta do sketch ao lado |
| Uma pasta de projeto do Wokwi | diagram.json, o sketch e suas abas, libraries.txt e wokwi.toml |
| Uma pasta de sketch comum do Arduino | uma placa sozinha para o sketch: uma Uno, ou diga qual com --board esp32 |
Um arquivo .mokxi.json |
o arquivo que o Download JSON do editor grava |
https://mokxi.com/p/<id> |
um projeto público, ou seu próprio com mokxi login ou MOKXI_TOKEN |
https://wokwi.com/projects/<id> |
um projeto público do Wokwi, buscado do Wokwi |
O sketch é compilado para a placa do diagrama, com as bibliotecas do próprio projeto e as bibliotecas comuns do Arduino que o Mokxi traz. Para rodar uma compilação sua (do PlatformIO ou do arduino-cli), passe-a: --firmware build/sketch.ino.elf, ou --firmware uno1=build/a.elf para uma placa entre várias. Quando o wokwi.toml de um projeto do Wokwi indica um arquivo de firmware que existe, essa compilação é rodada, como o Wokwi faz; --compile compila o sketch em vez disso.
Toda placa que o Mokxi simula roda aqui: a Uno, Nano, Mega, Leonardo, Pro Mini e ATtiny85, a ESP32, ESP32-S3, ESP32-C3, ESP32-C6 e ESP8266, a Pico e a Pico W, a UNO R4, as placas STM32, a XIAO e a micro:bit. mokxi boards lista todas.
Referência de comandos
| Opção | O que faz |
|---|---|
--timeout 10s |
tempo simulado que a execução (ou cada cenário) pode levar. Um número sozinho é milissegundos, como na CLI do Wokwi |
--expect-serial TEXT |
passa assim que cada um desses textos foi impresso. Repita para vários. --expect-text é o mesmo |
--fail-on TEXT |
falha no momento em que este texto é impresso. --fail-text é o mesmo |
--scenario FILE |
roda este arquivo de cenário (mokxi run --scenario é mokxi test) |
--junit FILE |
grava um relatório XML JUnit |
--serial-log-file FILE |
grava tudo o que as placas imprimiram |
--screenshot FILE |
para o mokxi run: uma imagem quando a execução termina. --screenshot-part oled1 fotografa um componente: um display (OLED, TFT, LCD, e-paper, matriz de LEDs) como um PNG dos próprios pixels dele, qualquer outro como um desenho SVG. --screenshot-time 2s tira a imagem naquele momento. --screenshot-file é o mesmo; com apenas --screenshot-part, o arquivo é screenshot.png, como no Wokwi |
--vcd-file FILE |
grava o que os analisadores lógicos do circuito registraram como um arquivo VCD (GTKWave, PulseView), cada borda em seu nanossegundo. Um arquivo por cenário no mokxi test |
--shard 2/3 |
para o mokxi test: roda o segundo de três partes iguais dos cenários, então uma matriz de CI com três jobs os roda em paralelo |
--firmware [board=]FILE, --elf FILE |
roda esta compilação em vez de compilar |
--board TYPE |
a placa para um sketch sem diagrama |
--diagram-file FILE |
lê este diagrama em vez do diagram.json da pasta |
--compile |
compila o sketch mesmo quando o wokwi.toml indica um arquivo de firmware |
--timeout-exit-code N |
o código de saída para um timeout (padrão 1; a CLI do Wokwi usa 42) |
--offline |
nunca acessa a rede; falha se o compilador não estiver em cache |
--quiet |
não imprime a saída serial (mokxi run) |
--verbose |
imprime a saída serial e cada passo (mokxi test) |
mokxi lint [dir] lê o projeto do jeito que uma execução faz e lista o que está errado no circuito sem compilar nem rodar: um componente que o Mokxi não simula, um fio ligado a um pino que não existe. Ele sai com 1 em um erro, ou em um aviso com --warnings-as-errors; --ignore-warnings imprime apenas os erros.
Toda execução imprime quanto tempo simulado ela cobriu, quanto tempo isso levou e quantas vezes mais rápido que o tempo real ela rodou; o relatório JUnit e o resumo do job trazem os mesmos números.
Códigos de saída: 0 quando tudo passou, 1 quando algo falhou (uma verificação, um timeout, uma linha --fail-on, um erro de compilação), 2 para um erro no comando ou no arquivo de cenário, e 3 quando um download falhou ou o CI precisa de um plano. Uma opção da CLI do Wokwi que o Mokxi ainda não tem (--heap-min-free, --coverage-file, --sdcard, --interactive, --gdb-server-port) é saída 2, então uma execução nunca passa sem uma verificação que foi pedida.
No GitHub Actions, cada cenário que falha é uma anotação na linha do passo que falhou, com as últimas linhas que a placa imprimiu, e o resumo do job tem uma tabela com todos os cenários, com um trecho do serial recolhido sob cada falha.
O tempo em uma execução é tempo simulado, não tempo real, então um teste se comporta igual num notebook rápido e numa máquina de CI lenta. Uma execução que demora muito mais em tempo real do que deveria (30 vezes o seu timeout, ou pelo menos dois minutos) é interrompida por estar travada.
Referência de cenários
Um arquivo de cenário é YAML. Ele contém um cenário (steps: no topo) ou vários (tests:, uma lista de name e steps):
| Tecla | O que é |
|---|---|
name |
o nome do arquivo no relatório |
project |
o projeto a rodar, relativo ao arquivo: uma pasta, um arquivo ou um link. Padrão: a própria pasta do arquivo |
board |
a placa para um sketch sem diagrama |
firmware |
uma compilação para rodar em vez de compilar: um caminho, ou { board: path } |
timeout |
tempo simulado que cada cenário pode levar (padrão de 30 s para o mokxi test) |
fail-on |
texto que faz o cenário falhar no momento em que é impresso: um, ou uma lista |
steps |
os passos de um cenário |
tests |
vários cenários, cada um { name, steps, timeout?, fail-on? } |
Os passos rodam em ordem, e um cenário para no primeiro que falha. Qualquer passo pode ter um name: para o relatório.
| Passo | O que faz |
|---|---|
wait-serial: Ready |
roda até esse texto ser impresso depois do que as esperas anteriores encontraram. /pattern/ é uma expressão regular. { text, timeout, board } limita quanto tempo ele espera, e em qual placa |
expect-serial: Ready |
verifica se o texto já foi impresso até agora, sem esperar |
expect-no-serial: error |
verifica que não foi |
write-serial: "hello\n" |
digita no monitor serial (exatamente este texto: adicione \n para Enter). Uma lista de números, [104, 105, 10], envia esses bytes, como no Wokwi |
delay: 500ms |
deixa a simulação rodar por este tempo |
press: btn1 / release: btn1 |
segura um botão pressionado, ou solta |
click: btn1 |
pressiona, segura por 100 ms ({ part, hold } para mudar), solta |
set: { part: dht1, temperature: 30 } |
ajusta um sensor ou um controle; veja a tabela abaixo |
expect-pin: { pin: uno:13, level: high } |
verifica o nível de um pino agora. uno:13=high é a mesma coisa. Um 13 sozinho é o pino da única placa |
wait-pin: { pin: uno:2, level: low, timeout: 1s } |
roda até o pino atingir esse nível |
expect-toggles: { pin: uno:13, during: 1s, min: 3, max: 5 } |
roda por during e conta as mudanças do pino: count, min e max. É assim que o tempo é verificado: um blink de 2 Hz são quatro mudanças por segundo |
expect-led: led1 |
verifica que um LED está aceso; expect-led-off: led1 verifica que está apagado |
expect-probe: { part: servo1, min: 85, max: 95 } |
verifica a leitura de qualquer componente (o ângulo de um servo, os segmentos acesos de um display, a velocidade de um motor) |
screenshot: build/circuit.svg |
salva uma imagem do circuito, com cada componente desenhado como está agora. { part: led1, file } desenha um componente. Um componente de display ({ part: oled1, file: build/oled.png }) é salvo como um PNG dos próprios pixels do painel. O take-screenshot do Wokwi com part-id e save-to é a mesma coisa |
take-screenshot: { part-id: oled1, compare-with: ref/oled.png } |
verifica que um display mostra exatamente a imagem de referência. max-diff-pixels: 4 permite que alguns pixels difiram, tolerance: 8 uma pequena diferença de cor. Num erro, a rodada escreve ref/oled.diff.png (as diferenças em vermelho) e ref/oled.actual.png. Sem arquivo de referência ainda, a rodada salva sua imagem lá e falha uma vez, para você conferir e fazer commit |
expect-display: { part: oled1, lit-min: 200 } |
verifica o que um display mostra agora: lit-min e lit-max contam pixels acesos, region: [x, y, width, height] olha parte do painel, pixel: { x, y, lit: true } ou pixel: { x, y, color: "#ff8000" } verifica um pixel, blank: true verifica que o painel está desligado, matches: ref.png compara com uma imagem. Aceso significa a tinta do painel num painel de uma cor, e qualquer coisa mais clara que quase preto num painel colorido |
wait-display: { part: oled1, lit-min: 200, timeout: 2s } |
roda até o display mostrar isso, do mesmo jeito que wait-serial espera um texto |
touch: { part-id: tft1, x: 120, y: 160 } |
toca num painel touch por 50 ms (duration para mudar); touch-press, touch-move e touch-release seguram, arrastam e levantam. No ILI9341 capacitivo as coordenadas são as do controlador de touch, como no Wokwi; no resistivo são pixels da imagem a partir do canto superior esquerdo |
poke: { part, code } |
envia a um componente um código de estímulo bruto, para qualquer coisa que a tabela abaixo não mencione |
O brilho de um LED no simulador é o que o olho vê: ele apaga ao longo de alguns milissegundos, como na bancada. Então o expect-led dá ao LED até 50 ms de tempo simulado para chegar lá antes de falhar.
Os pinos são nomeados como no editor (uno1:13, esp1:D2, pico1:GP15); 13, D13, GP13 e GPIO13 são todos tentados. Os componentes são nomeados pelo seu id no diagrama, ou pelo seu id do Wokwi quando o projeto veio do Wokwi.
Sensores e controles
| Peça | Controles (set: { part, <control>: <value> }) |
|---|---|
| Botão de pressão, botão de fliperama, microswitch | pressed: 1 ou 0 |
| Chave deslizante | value: 0 ou 1 |
| Potenciômetro, potenciômetro deslizante | position: 0 a 1 (ou 0 a 1023) |
| DHT11, DHT22, AHT20 | temperature em C, humidity em % |
| DS18B20, LM35, TMP36, módulo NTC | temperature em C |
| BMP180, BMP280, BME280 | temperature em C, pressure em hPa, humidity em % (BME280) |
| HC-SR04 | distance em cm |
| Sensor de obstáculo FC-51 | distance em cm |
| LDR, módulo LDR, fototransistor, BH1750 | lux |
| PIR | movimento: 1 ou 0 |
| Umidade do solo | umidade em % |
| MQ-2 | gás em ppm |
| DIP switches, teclados | value ou keys: uma bitmask |
Migrando do Wokwi CI
Sua pasta de projeto do Wokwi funciona como está: diagram.json, wokwi.toml, o sketch, libraries.txt e seus arquivos de cenário são lidos sem alterações. No GitHub Actions, mude a linha uses: e o secret que a entrada token lê. A action passa o token para a CLI como MOKXI_TOKEN, que verifica seu plano com ele.
# 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
Migrar do Wokwi CI tem o resto: as opções do wokwi-cli, quais passos de cenário são mantidos, as três coisas que se comportam de forma diferente e uma comparação lado a lado com preços.
Qual plano o CI precisa
Repositórios públicos rodam CI de graça, sem token e sem conta. No GitHub Actions e no gitlab.com, a CLI pega o nome do repositório do próprio runner (GITHUB_REPOSITORY, CI_PROJECT_PATH), e o Mokxi pergunta ao GitHub ou ao GitLab, sem nenhuma credencial, se ele é público. Um repositório privado parece inexistente para esse tipo de requisição, então ele não pode passar por público. O GitHub Enterprise e o GitLab auto-hospedado não podem ser verificados de fora, então precisam de um 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.
Rodar um sketch no seu próprio computador com mokxi run continua grátis, sem conta.
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 e uso 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.
Em uma máquina sem rede, copie uma pasta de cache já preenchida para lá e passe --offline (ou defina MOKXI_OFFLINE=1): nada é baixado, e um arquivo faltando é um erro em vez de um download.