breadboard
documentación

10 · Pruebas de hardware en tu pipeline

Breadboard CI

Prueba tus circuitos en cada push: hardware emulado determinista en servidores alojados, fallos anotados en GitHub y grabaciones reproducibles.

Breadboard CI ejecuta un circuito y una pequeña especificación de pruebas en los servidores de Breadboard (el mismo motor y placas emuladas, sin interfaz) y genera un resultado de éxito o fallo que tu pipeline puede usar para detenerse o continuar. Los plazos de la especificación son de tiempo simulado, nunca de reloj real: el motor es determinista en su cuadrícula de 5 ms y las comprobaciones siguen el tiempo del circuito. Un presupuesto de tiempo real independiente puede detener una ejecución demasiado larga. Si una especificación falla, recibes una grabación de la sesión que puedes reproducir bit a bit en tu banco. CI forma parte del plan CI (£9.99, $12 o €12 al mes, más impuestos: todo lo de Pro y los ejecutores alojados).

CI alojado aún no está habilitado en producción. Estas instrucciones describen un despliegue con CI habilitado; un token o suscripción por sí solos no activan el servicio.

Inicio rápido: GitHub Actions

  1. 1Crea un token: en una cuenta con CI habilitado, abre el menú de cuenta → CI tokens… (o Account → Developer → Manage CI tokens), ponle nombre y pulsa Create token. El secreto ci_… se muestra una sola vez; cópialo a un secreto del repositorio llamado BREADBOARD_CI_TOKEN. Puedes revocarlo en el mismo cuadro de diálogo.
  2. 2Guarda el circuito en el repositorio: exporta el montaje a JSON (File → Export → Project, por ejemplo circuit.bb.json).
  3. 3Escribe una especificación: un archivo .bbtest.json (formato abajo) junto al circuito, por ejemplo en tests/.
  4. 4Añade el pipeline:
# .github/workflows/breadboard.yml
name: circuit-tests
on: [push, pull_request]
jobs:
  breadboard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Dollis-Hill/breadboard-ci-action@v1
        with:
          token: ${{ secrets.BREADBOARD_CI_TOKEN }}
          doc: circuit.bb.json
          specs: tests/
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: breadboard-ci-recordings
          path: breadboard-ci-recordings/

Los fallos aparecen como anotaciones de error sobre la especificación, con el paso que falló, el tiempo simulado en que venció el plazo y las últimas líneas de la salida serial. La acción usa una pequeña CLI, breadboard-ci: breadboard-ci run --doc circuit.bb.json tests/ envía y consulta la ejecución (token en BREADBOARD_CI_TOKEN); breadboard-ci ping comprueba el token. Códigos de salida: 0, todas las especificaciones pasaron; 1, una falló; 2, problema de configuración o servicio (token incorrecto, falta de plan o minutos agotados).

Formato de especificación .bbtest.json

{
  "version": 1,
  "name": "thermostat kicks in",
  "boot": { "bootTimeoutSimS": 20, "settleSimS": 5 },
  "wallBudgetMs": 120000,
  "steps": [
    { "type": "expect-serial", "component": "esp1",
      "pattern": "ready", "withinSimS": 10 },
    { "type": "set-param", "component": "tmp1", "params": { "temperatureC": 41 } },
    { "type": "expect-visual", "component": "led1",
      "brightness": { "min": 0.5 }, "withinSimS": 5 }
  ]
}

Una especificación arranca el documento (mensaje inicial MicroPython → REPL en cada placa → inyección del script de Code), ejecuta los pasos en orden y deja transcurrir settleSimS segundos simulados más. Cada ejecución comprueba además que nunca aparezca un error de firmware ni un diagnóstico de nivel error: un programa que falla hace fallar la prueba aunque pasen todos los pasos explícitos. Debe haber al menos un paso expect-* u observe; los pasos identifican los componentes por su id (selecciona uno en el banco para verlo en el Inspector).

  • expect-serial: una expresión regular debe coincidir con la salida serial dentro de withinSimS segundos simulados (salida posterior al inicio del script y al último estímulo). Añade "capture": true para obtener el texto y sus grupos en el resultado (hasta 8 grupos de 256 caracteres; los demás se descartan y se marca truncated), por ejemplo "pattern": "temp=([0-9.]+)\\r?\\n". Con captura solo se analizan líneas completas, para no leer un valor a medio imprimir. expect-serial-absent comprueba la ausencia al final.
  • interact: acciona el hardware: buttonDown/buttonUp, switchSet, dialChange, toggleDip, keypadDown/keypadUp, pirTrigger, joystickMove, joystickButtonDown/joystickButtonUp, irKeyDown/irKeyUp (control remoto del receptor IR), turn (codificador giratorio).
  • set-param: fija parámetros directamente (valores de sensor y posiciones de controles): { "params": { "temperatureC": 41 } }.
  • write-serial: escribe en la consola serial de una placa (omite component para enviar a todas las placas con puerto serial).
  • wait: avanza la simulación simS segundos.
  • expect-visual: consulta el estado visible hasta que se cumplan todos los criterios: brightness (mínimo/máximo de 0..1; un LED que conmuta a más de unos 50 Hz, como PWM, muestra el promedio percibido), textContains (pantallas de caracteres), pixelsLit (tiras LED), rpm, toneHz, fault, angle (grados del servo), reading (instrumentos y sensores), power (vatios), rgb (límites de 0..1 por canal, por ejemplo { "r": { "min": 0.5 }, "b": { "max": 0.1 } }), pinLevel ({ "pin": "d13", "level": 1 } en una placa o circuito integrado) y textMatches (expresión regular sobre filas unidas por saltos de línea, { "pattern": "^T=\\d+", "flags": "m" }).
  • expect-signal: frecuencia y ciclo de trabajo en un pin durante una ventana simulada, por ejemplo { "component": "nano1", "pin": "d13", "windowSimS": 3, "frequencyHz": { "min": 0.9, "max": 1.1 }, "dutyCycle": { "min": 0.4, "max": 0.6 } }. Se compara el voltaje con thresholdV (1.5 V por defecto) cada 5 ms simulados: admite hasta 50 Hz, con fases alta y baja de al menos 10 ms. Una señal más rápida falla por superar la capacidad de medida (una fase inferior a 5 ms puede pasar inadvertida); para PWM usa brightness. Un nivel constante mide 0 Hz con ciclo de trabajo 0 o 1.
  • observe: registra el estado en ese instante sin comprobarlo. fields elige entre pinLevels, brightness, rgb, text, angle, rpm, toneHz, reading, power, fault, activity, segments (siete segmentos), matrix, pixels, joystick y display (píxeles de la pantalla, hasta 32 KiB; las pantallas a color se reducen para caber); voltages enumera los pines cuyo voltaje registrar. Los valores aparecen en el resultado; un campo inexistente vale null y las listas largas se recortan a su límite y se indican en truncated.
  • expect-voltage: el voltaje del nodo en el pin de un componente, por ejemplo { "component": "esp1", "pin": "g4", "min": 3.0 }.
Alcance del firmware: MicroPython en la familia ESP32 y Pico, circuitos analógicos/digitales e imágenes precompiladas referenciadas en el documento. Un ejecutor alojado no puede obtener firmware local idb:; usa una imagen integrada admitida o un recurso disponible.

Arduino: compilar antes de simular

Para probar una compilación Arduino nueva, pasa --code arduino-code.json a la CLI o code: arduino-code.json a la Action. Este JSON independiente usa la entrada de compilación de la API alojada:

{
  "lang": "arduino",
  "board": "uno",
  "component": "uno1",
  "source": "void setup() { Serial.begin(9600); Serial.println(\"ready\"); }\nvoid loop() {}"
}

Cada especificación compila primero el sketch y ejecuta el firmware resultante en el componente indicado. Omite component solo si una única placa del documento coincide con el destino de compilación. Los errores aparecen como compile_failed con diagnósticos. Los minutos de compilación usan la bolsa de la cuenta, independiente de los minutos de simulación CI. Los destinos compatibles dependen del despliegue; los perfiles que necesitan un paquete privado de reenlazado rechazan actualmente el encadenamiento antes de cobrar. Sin code, se simula el firmware del documento; un archivo fuente Arduino en el documento exportado no solicita compilación.

Grabaciones de fallos

Una ejecución fallida devuelve toda la sesión como grabación .bbrec.json: cada entrada de simulación en su instante exacto. La acción escribe las grabaciones en breadboard-ci-recordings/ (consérvalas con un paso upload-artifact, como en el inicio rápido). Para depurar, descarga el archivo y abre breadboard.build/app/?open-recording=1, elige la grabación y el fallo se reproduce en el banco con los controles de tiempo: pausa, busca el instante del fallo, avanza paso a paso o reanuda en vivo desde cualquier punto para tomar el control.

Cuotas y límites

  • El plan CI incluye 1500 minutos mensuales de simulación CI (240 al día) y 2 ejecuciones en paralelo. Los minutos CI miden el tiempo real del ejecutor, redondeado a minutos enteros, no la duración simulada del circuito. Los fallos de infraestructura devuelven la reserva CI.
  • Una ejecución es un documento más una especificación y entrada de compilación opcional, hasta 2 MiB de JSON UTF-8 en conjunto; hasta 100 pasos por especificación; los resultados (veredicto y grabación) se conservan 24 horas.
  • wallBudgetMs (120 s por defecto, máximo 600 s) limita programas lentos o descontrolados en tiempo real. Es independiente de los plazos simulados y de --poll-timeout-s del cliente o poll-timeout-s de la Action (900 s por defecto). Agotar la espera del cliente no cancela la ejecución alojada ni devuelve su consumo. El mensaje incluye la URL de consulta de la ejecución.
Informar de un problema de traducción