Contas e planos

Testes de simulação em CI

Rode seu sketch de Arduino, ESP32 ou Pico no simulador a cada push e faça a compilação falhar quando a saída ou um pino estiver errado. Grátis para repositórios públicos.

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.