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 qué plan necesita el CI); en tu propia computadora no necesita ninguna cuenta. Lee los proyectos de Wokwi y los archivos de escenario de Wokwi tal como son, así que mudarte desde el CI de Wokwi es un cambio de una sola línea.
Inicio rápido
En una carpeta con un sketch (y, si tiene algo más que una placa sola, un diagram.json de Mokxi o de Wokwi):
npx @mokxi/cli run --timeout 10s --expect-serial "Ready" --fail-on "panic"
Eso compila el sketch, lo ejecuta, imprime la salida serie conforme llega, y termina en cuanto aparece Ready (código de salida 0). Falla con el código de salida 1 en el momento en que el sketch imprime panic, cuando pasan 10 segundos de tiempo simulado sin que aparezca Ready, o cuando el sketch no compila. Solo necesita Node.js 18 o más reciente.
Para más de una línea de salida, escribe un escenario. Pon esto en mokxi.test.yaml junto al 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
y ejecuta todas las pruebas que contiene, con un reporte JUnit para tu panel de CI:
npx @mokxi/cli test --junit mokxi-junit.xml
Cada prueba es una ejecución nueva del sketch, y cada una es un caso de prueba en el reporte.
En 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
La acción ejecuta mokxi.test.yaml cuando la carpeta tiene uno, y de lo contrario comprueba que el sketch arranque e imprima el texto esperado. Mantiene el compilador en la caché de Actions, así que se descarga una sola vez, escribe mokxi-junit.xml, pone una tabla de resultados en el resumen del trabajo, y anota la ejecución con cada fallo, un error de compilación en su propia línea. Cada entrada está listada en el action.yml de la acción: path, scenario, timeout, expect-serial, fail-on, board, firmware, junit, serial-log, screenshot, args, version y token (un token de CI, necesario solo para un repositorio privado).
En cualquier otro CI
La línea de comandos es el producto completo, así que cualquier cosa que ejecute Node funciona igual. GitLab CI, por ejemplo:
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
Conserva la carpeta de caché entre trabajos (MOKXI_CACHE_DIR, o ~/.cache/mokxi por omisión). Sin ella, cada trabajo descarga el compilador de nuevo, y mokxi.com limita la frecuencia con la que una misma dirección puede hacerlo.
Qué ejecuta
mokxi run y mokxi test aceptan una carpeta, un archivo o un enlace:
| Qué | Cómo se lee |
|---|---|
Una carpeta de mokxi pull o de Guardar en GitHub |
diagram.mokxi.json y la carpeta del sketch junto a él |
| Una carpeta de proyecto de Wokwi | diagram.json, el sketch y sus pestañas, libraries.txt y wokwi.toml |
| Una carpeta de sketch de Arduino simple | una placa sola para el sketch: una Uno, o indica cuál con --board esp32 |
Un archivo .mokxi.json |
el archivo que escribe la opción Descargar JSON del editor |
https://mokxi.com/p/<id> |
un proyecto público, o uno tuyo con mokxi login o MOKXI_TOKEN |
https://wokwi.com/projects/<id> |
un proyecto público de Wokwi, descargado desde Wokwi |
El sketch se compila para la placa del diagrama, con las bibliotecas propias del proyecto y las bibliotecas comunes de Arduino que Mokxi trae. Para ejecutar en cambio una compilación tuya (de PlatformIO o de arduino-cli), pásala: --firmware build/sketch.ino.elf, o --firmware uno1=build/a.elf para una placa entre varias. Cuando el wokwi.toml de un proyecto de Wokwi nombra un archivo de firmware que existe, se ejecuta esa compilación, como hace Wokwi; --compile compila el sketch en su lugar.
Aquí funciona toda placa que Mokxi simula: la Uno, Nano, Mega, Leonardo, Pro Mini y ATtiny85, la ESP32, ESP32-S3, ESP32-C3, ESP32-C6 y ESP8266, la Pico y la Pico W, la UNO R4, las placas STM32, la XIAO y la micro:bit. mokxi boards las lista.
Referencia de comandos
| Opción | Qué hace |
|---|---|
--timeout 10s |
tiempo simulado que puede tomar la ejecución (o cada escenario). Un número solo son milisegundos, como en la CLI de Wokwi |
--expect-serial TEXT |
pasar en cuanto se haya impreso cada uno de esos textos. Repítelo para varios. --expect-text es lo mismo |
--fail-on TEXT |
fallar en el momento en que se imprima este texto. --fail-text es lo mismo |
--scenario FILE |
ejecutar este archivo de escenario (mokxi run --scenario es mokxi test) |
--junit FILE |
escribir un reporte XML de JUnit |
--serial-log-file FILE |
escribir todo lo que imprimieron las placas |
--screenshot FILE |
para mokxi run: una imagen cuando termina la ejecución. --screenshot-part oled1 fotografía un componente: una pantalla (OLED, TFT, LCD, tinta electrónica, matriz de LED) como PNG de sus propios píxeles, cualquier otra cosa como dibujo SVG. --screenshot-time 2s la toma en ese momento en lugar de al final. --screenshot-file es lo mismo; con solo --screenshot-part, el archivo es screenshot.png, como en Wokwi |
--vcd-file FILE |
escribir lo que registraron los analizadores lógicos del circuito como archivo VCD (GTKWave, PulseView), cada flanco en su nanosegundo. Un archivo por escenario en mokxi test |
--shard 2/3 |
para mokxi test: ejecutar el segundo de tres partes iguales de los escenarios, de modo que una matriz de CI de tres trabajos los ejecute en paralelo |
--firmware [board=]FILE, --elf FILE |
ejecutar esta compilación en lugar de compilar |
--board TYPE |
la placa para un sketch sin diagrama |
--diagram-file FILE |
leer este diagrama en lugar del diagram.json de la carpeta |
--compile |
compilar el sketch aunque wokwi.toml nombre un archivo de firmware |
--timeout-exit-code N |
el código de salida para un timeout (1 por omisión; la CLI de Wokwi usa 42) |
--offline |
no tocar la red; fallar si el compilador no está en caché |
--quiet |
no imprimir la salida serie (mokxi run) |
--verbose |
imprimir la salida serie y cada paso (mokxi test) |
mokxi lint [dir] lee el proyecto como lo hace una ejecución y lista qué está mal en el circuito sin compilarlo ni ejecutarlo: un componente que Mokxi no simula, un cable a un pin que no existe. Termina con 1 ante un error, o ante una advertencia con --warnings-as-errors; --ignore-warnings imprime solo los errores.
Cada ejecución imprime cuánto tiempo simulado cubrió, cuánto tardó eso y cuántas veces más rápido que el tiempo real corrió; el reporte JUnit y el resumen del trabajo llevan los mismos números.
Códigos de salida: 0 cuando todo pasó, 1 cuando algo falló (una comprobación, un timeout, una línea --fail-on, un error de compilación), 2 por un error en el comando o en el archivo de escenario, y 3 cuando falló una descarga o el CI necesita un plan. Una opción de la CLI de Wokwi que Mokxi aún no tiene (--heap-min-free, --coverage-file, --sdcard, --interactive, --gdb-server-port) da salida 2, de modo que una ejecución nunca pasa sin una comprobación que se le pidió.
En GitHub Actions, cada escenario que falla es una anotación en la línea del paso que falló, con las últimas líneas que imprimió la placa, y el resumen del trabajo tiene una tabla con todos los escenarios y un fragmento plegado de la salida serie bajo cada falla.
El tiempo en una ejecución es tiempo simulado, no tiempo de reloj, así que una prueba se comporta igual en una computadora rápida y en una máquina lenta de CI. Una ejecución que tarda mucho más de lo que debería en tiempo real (30 veces su tiempo de espera, o al menos dos minutos) se detiene por estar atascada.
Referencia de escenarios
Un archivo de escenario es YAML. Contiene un escenario (steps: al inicio) o varios (tests:, una lista de name y steps):
| Tecla | Qué es |
|---|---|
name |
el nombre del archivo en el reporte |
project |
el proyecto a ejecutar, relativo al archivo: una carpeta, un archivo o un enlace. Por defecto: la carpeta del propio archivo |
board |
la placa para un sketch sin diagrama |
firmware |
una compilación para ejecutar en vez de compilar: una ruta, o { board: path } |
timeout |
tiempo simulado que puede tomar cada escenario (por defecto 30 s para mokxi test) |
fail-on |
texto que hace fallar el escenario en cuanto se imprime: uno, o una lista |
steps |
los pasos de un escenario |
tests |
varios escenarios, cada uno { name, steps, timeout?, fail-on? } |
Los pasos se ejecutan en orden, y un escenario se detiene en el primero que falle. Cualquier paso puede llevar un name: para el reporte.
| Paso | Qué hace |
|---|---|
wait-serial: Ready |
ejecutar hasta que se imprima este texto después de lo que coincidieron las esperas anteriores. /pattern/ es una expresión regular. { text, timeout, board } limita cuánto espera y en qué placa |
expect-serial: Ready |
comprobar que el texto ya se imprimió, sin esperar |
expect-no-serial: error |
comprobar que no se imprimió |
write-serial: "hello\n" |
escribir en el monitor serie (exactamente este texto: agrega \n para Enter). Una lista de números, [104, 105, 10], envía esos bytes, como en Wokwi |
delay: 500ms |
dejar que la simulación avance este tiempo |
press: btn1 / release: btn1 |
mantener presionado un botón, o soltarlo |
click: btn1 |
presionar, mantener 100 ms ({ part, hold } para cambiarlo), soltar |
set: { part: dht1, temperature: 30 } |
ajustar un sensor o un control; consulta la tabla de abajo |
expect-pin: { pin: uno:13, level: high } |
comprobar el nivel de un pin ahora. uno:13=high es lo mismo. Un 13 solo es el pin de la única placa |
wait-pin: { pin: uno:2, level: low, timeout: 1s } |
ejecutar hasta que el pin alcance ese nivel |
expect-toggles: { pin: uno:13, during: 1s, min: 3, max: 5 } |
ejecutar durante during y contar los cambios del pin: count, min y max. Así se comprueba el tiempo: un parpadeo de 2 Hz son cuatro cambios por segundo |
expect-led: led1 |
comprobar que un LED está encendido; expect-led-off: led1 que está apagado |
expect-probe: { part: servo1, min: 85, max: 95 } |
comprobar la lectura de cualquier componente (el ángulo de un servomotor, los segmentos encendidos de una pantalla, la velocidad de un motor) |
screenshot: build/circuit.svg |
guardar una imagen del circuito, con cada componente dibujado tal como está ahora. { part: led1, file } dibuja un componente. Un componente de pantalla ({ part: oled1, file: build/oled.png }) se guarda como PNG de los píxeles del propio panel. El take-screenshot de Wokwi con part-id y save-to es lo mismo |
take-screenshot: { part-id: oled1, compare-with: ref/oled.png } |
comprobar que una pantalla muestra exactamente la imagen de referencia. max-diff-pixels: 4 permite que difieran algunos píxeles, tolerance: 8 una pequeña diferencia de color. Si no coinciden, la ejecución escribe ref/oled.diff.png (las diferencias en rojo) y ref/oled.actual.png. Si aún no hay archivo de referencia, la ejecución guarda su imagen ahí y falla una vez, para que puedas revisarla y confirmarla |
expect-display: { part: oled1, lit-min: 200 } |
comprobar qué muestra una pantalla ahora: lit-min y lit-max cuentan píxeles encendidos, region: [x, y, width, height] mira una parte del panel, pixel: { x, y, lit: true } o pixel: { x, y, color: "#ff8000" } comprueba un píxel, blank: true comprueba que el panel está apagado, matches: ref.png compara con una imagen. Encendido significa la tinta del panel en un panel de un color, y cualquier cosa más brillante que casi negro en uno a color |
wait-display: { part: oled1, lit-min: 200, timeout: 2s } |
ejecutar hasta que la pantalla muestre eso, igual que wait-serial espera texto |
touch: { part-id: tft1, x: 120, y: 160 } |
tocar una pantalla táctil durante 50 ms (duration para cambiarlo); touch-press, touch-move y touch-release mantienen, arrastran y sueltan. En el ILI9341 capacitivo las coordenadas son las del controlador táctil, como en Wokwi; en el resistivo son píxeles de la imagen desde la esquina superior izquierda |
poke: { part, code } |
enviar a un componente un código de estímulo sin procesar, para lo que la tabla de abajo no cubra |
El brillo de un LED en el simulador es lo que el ojo ve: se atenúa en unos milisegundos, como en el banco de trabajo. Así que expect-led le da al LED hasta 50 ms de tiempo simulado para llegar ahí antes de fallar.
Los pines se nombran como en el editor (uno1:13, esp1:D2, pico1:GP15); se prueba cada uno de 13, D13, GP13 y GPIO13. Los componentes se nombran por su id en el diagrama, o por su id de Wokwi cuando el proyecto viene de Wokwi.
Sensores y controles
| Pieza | Controles (set: { part, <control>: <value> }) |
|---|---|
| Botón pulsador, botón de arcade, microinterruptor | pressed: 1 o 0 |
| Interruptor deslizable | value: 0 o 1 |
| Potenciómetro, potenciómetro deslizante | position: de 0 a 1 (o de 0 a 1023) |
| DHT11, DHT22, AHT20 | temperature en C, humidity en % |
| DS18B20, LM35, TMP36, módulo NTC | temperature en C |
| BMP180, BMP280, BME280 | temperature en C, pressure en hPa, humidity en % (BME280) |
| HC-SR04 | distance en cm |
| Sensor de obstáculos FC-51 | distance en cm |
| LDR, módulo LDR, fototransistor, BH1750 | lux |
| PIR | movimiento: 1 o 0 |
| Humedad del suelo | humedad en % |
| MQ-2 | gas en ppm |
| Interruptores DIP, teclados | value o keys: una máscara de bits |
Cambiar desde Wokwi CI
Tu carpeta de proyecto de Wokwi funciona tal cual: diagram.json, wokwi.toml, el sketch, libraries.txt y tus archivos de escenario se leen sin cambios. En GitHub Actions, cambia la línea uses: y el secreto que lee la entrada token. La acción pasa el token a la CLI como MOKXI_TOKEN, con el cual se verifica tu plan.
# 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
Cambiar desde Wokwi CI tiene el resto: las opciones de wokwi-cli, qué pasos del escenario se conservan, las tres cosas que se comportan diferente, y una comparación lado a lado con precios.
Qué plan necesita la CI
Los repositorios públicos ejecutan la CI gratis, sin token y sin cuenta. En GitHub Actions y en gitlab.com, la CLI toma el nombre del repositorio del propio runner (GITHUB_REPOSITORY, CI_PROJECT_PATH), y Mokxi pregunta a GitHub o GitLab, sin credenciales, si es público. Un repositorio privado parece inexistente para esa petición, así que no puede pasar por público. GitHub Enterprise y GitLab autoadministrado no se pueden verificar desde fuera, así que necesitan un 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.
Ejecutar un sketch en tu propia computadora con mokxi run sigue siendo gratis, sin cuenta.
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.
Caché y uso sin conexió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.
En una máquina sin red, copia ahí una carpeta de caché ya poblada y pasa --offline (o define MOKXI_OFFLINE=1): no se descarga nada, y un archivo faltante es un error en lugar de una descarga.