Grabar el firmware y ejecutar

Para ejecutar tus programas, la placa necesita dos cosas: la VM de JARU, que se graba con Flash Firmware una vez por cada versión de JARU IDE, y los ficheros del programa, que graba Run cada vez que lo ejecutas.

En la memoria flash de la placa	Lo graba
El arranque	Flash Firmware
La tabla de particiones, que dice dónde va cada cosa	Flash Firmware, Run y Upload Program
La VM de JARU	Flash Firmware
La memoria de ficheros (LittleFS): el programa, sus recursos y el boot.cfg	Run y Upload Program

El IDE graba las placas con esptool, por el puerto de la placa del proyecto. Antes de cada grabación, lee de la placa el tamaño de su flash y hace con él la tabla de particiones: la memoria de ficheros va desde el final del sitio de la VM hasta el final de la flash. Lo que cabe en ella, en Memoria y límites.

El recorrido de la primera vez está en Tu programa en una placa. Esta página cuenta cada paso entero.

La página Deploy

Flash Firmware y Upload Program están en la página Deploy de ESP32 Tools (Build › Target › Manage boards..., y Deploy, bajo Actions).

Arriba, Deploy Summary resume con qué se va a grabar la placa activa del proyecto:

Campo	Qué es
Chip, COM Port, Baud Rate, Bootloader y Flash Size	Con qué se graba: el chip, el puerto, la velocidad, el arranque (Flash Mode) y el tamaño de la flash.
JARU App	El programa que arrancará la placa: el .jxr del fichero principal del proyecto.
LittleFS	Image built si ya se ha preparado alguna vez la imagen de los ficheros, con el tamaño de la memoria de ficheros, o Not built.
Device y Config	La placa del proyecto, y si tiene cambios sin guardar (Modified) o no (Saved).
Device ID	El nombre del dispositivo (Device Name).
Display, Audio, SD Card, WiFi, MQTT y NTP	Lo que lleva la placa.

Debajo, en naranja, los avisos: lo que falta o no cuadra, como un puerto sin elegir, un pin de la pantalla sin poner, o MQTT o NTP sin WiFi. Sin avisos, dice «Configuration looks ready for deployment.». Los avisos no impiden grabar.

Flash Firmware

Flash Firmware graba en la placa la VM de JARU para su chip, la que trae tu instalación de JARU IDE, con su arranque y su tabla de particiones. No graba los ficheros: el programa y el boot.cfg los graba Run.

1. Pulsa Flash Firmware. Si el monitor serie está abierto en el puerto de la placa, el IDE lo aparta mientras graba («Serial monitor paused: the IDE is using COM5.», con tu puerto).
2. El IDE lee la placa («Validating flash configuration...»): escribe en el Output su chip, su flash y su MAC, y pone en Flash Size el tamaño que ha leído. Si no consigue leerlo, usa el de Flash Size; si este es Auto detect, se para («Flash operation cancelled.»).
3. Hace la tabla de particiones para ese tamaño («Partition table generated»).
4. Graba con esptool el arranque de Flash Mode, la tabla y la VM. El Output cuenta cómo va («Flashing in progress... 45%») y, al final, comprueba lo grabado («Verifying flash contents, please wait...»).
5. Si todo va bien, dice «JARU VM firmware successfully saved.»; si no, «Error: failed to save JARU VM firmware.», y las líneas de encima, de esptool, dicen por qué.
6. La placa se reinicia, y el monitor serie vuelve a abrirse si lo apartó.

La VM sale de la carpeta Compiler\ESP32 de JARU IDE, que tiene una carpeta por chip (ESP32, ESP32S3, ESP32P4 y ESP32S31) con la VM en firmware\firmware.bin. Esa carpeta se cambia en Settings, en ESP32 VM (ver Las rutas).

Flash Firmware sustituye el firmware de la placa

Si tu placa trae un programa de fábrica, o uno tuyo grabado con otra herramienta, Flash Firmware lo sustituye por la VM de JARU. JARU IDE no guarda una copia de lo que había.

• MCU model tiene que ser el chip de tu placa: con otro, esptool no la graba.
• Flash Firmware no pregunta por los cambios sin guardar de ESP32 Tools: graba con lo que ves en la ventana.
• Si la grabación falla, prueba con una velocidad menor en Baud.

Upload Program

Upload Program graba en la placa los ficheros del proyecto, como el paso 3 de Run, pero:

• No compila: envía lo que haya en Build/flash, tal cual. Si el programa compilado no casa con la casilla Line numbers, solo lo avisa («Press Compile to rebuild it.»).
• No mira si la placa lleva la VM. Sobre una placa sin ella, la deja reiniciándose.
• No aparta el monitor serie. Si está abierto en ese puerto, esptool no puede usarlo: ciérralo antes.

Por lo demás, hace lo mismo que Run: pregunta si guardas los cambios de ESP32 Tools, genera el boot.cfg, lee el tamaño de la flash, prepara la imagen de los ficheros y la graba. Al acabar dice «PROCESS COMPLETED: LittleFS successfully built and saved.».

Usa Run: compila lo que haga falta y comprueba la placa. Upload Program sirve para enviar Build/flash sin compilar.

Run en la placa

Con una placa en Build › Target, Run compila el programa si hace falta y se lo envía a la placa, que lo arranca. El Output empieza con «[ESP32] Sending the program to», el nombre de la placa y «(interpreted)».

Antes de enviar nada:

• Compila si el programa no está compilado, si has guardado código, imágenes, sprites, mapas o música después de compilarlo, o si no está compilado como pide Line numbers.
• Si ESP32 Tools tiene cambios sin guardar, pregunta («The ESP32 configuration has unsaved changes»). Contesta Yes: con No, el boot.cfg sale de la placa tal como la guardaste la última vez, no de lo que enseña la ventana. Pasa casi siempre con Flash Size en Auto detect, porque el IDE escribe en él el tamaño que lee de la placa.
• Necesita un puerto. Sin él: «Error: No COM port configured. Please open ESP32 Tools and select a port.».
• Genera el boot.cfg de la placa activa (ver El boot.cfg).
• Aparta el monitor serie si está abierto en ese puerto, y lo vuelve a abrir al terminar.

Después, el Output cuenta los tres pasos.

Paso 1: los ficheros

«Step 1 of 3: building the files for the board». El IDE:

1. Lee la placa: su chip, su flash y su MAC, y el tamaño de la flash («Flash size detected: 16 MB», por ejemplo). Si no consigue leerla, avisa («Warning: Could not auto-detect flash size.») y usa Flash Size; si este es Auto detect, se para («Error: Cannot determine flash size»).
2. Hace la tabla de particiones para ese tamaño.
3. Borra de Build/flash los ficheros de depuración (.jxd) y los programas del Play del editor de escenas (_Play_*.jxr): en la placa solo gastarían sitio.
4. Junta todo lo que hay en Build/flash en una imagen de la memoria de ficheros: el programa compilado, sus recursos y el boot.cfg. Si no cabe, se para aquí.

La tabla y la imagen quedan en Build/Deploy, en el proyecto.

Paso 2: la comprobación de la placa

«Step 2 of 3: checking that the board carries the JARU VM». El IDE lee el principio de la flash de la placa, el arranque y la tabla de particiones, y lo compara con lo que va a grabar. Si cuadra, dice «The board carries the JARU VM.».

Si no cuadra, la placa no lleva la VM: está vacía, lleva otro programa, su tabla de particiones no es la de la VM o su arranque es para otro tamaño de flash. Entonces Run pregunta qué hacer antes de grabar nada, en la ventana Run on the board, que dice por qué:

Botón	Qué hace
Yes	Graba antes la VM, como Flash Firmware, y después el programa. Es lo que quieres.
No	Graba el programa igualmente. Sin la VM, la placa se queda reiniciándose.
Cancel	No graba nada («Run cancelled: nothing was written to the board.»).

Si no consigue leer la placa, no la comprueba y sigue: «Could not read the board to check it: sending the program anyway.».

Esta comprobación no mira la versión de la VM: da por buena una placa con la VM de una versión anterior (ver Al cambiar de versión).

Paso 3: la grabación

«Step 3 of 3: writing the program and its files to the board». El IDE graba la tabla de particiones y la imagen de los ficheros. Borrar el sitio de los ficheros tarda un rato: mientras, el Output escribe una línea cada 10 segundos («... still working, 20 s so far»).

Al acabar dice «DEPLOYMENT COMPLETED: LittleFS successfully built and flashed.». La placa se reinicia y arranca tu programa. Lo que imprime no sale en el Output: para verlo, abre el monitor serie (Open Serial).

Run sustituye los ficheros de la placa

El paso 3 graba de nuevo toda la memoria de ficheros de la placa, no solo el programa. Lo que tu programa haya guardado en ella se pierde con cada Run, y también con Upload Program.

Además:

• El programa se queda en la placa hasta que le envíes otro, y arranca solo cada vez que la placa se enciende. Cuando acaba, la VM lo vuelve a empezar.
• Stop no lo para: solo para los programas que corren en Windows.
• Debug no va a la placa: depura siempre en la VM de Windows.

Open Serial

Lo que tu programa imprime en la placa sale por su puerto serie. Para verlo, abre el monitor serie: Open Serial, en la barra del Output. Run no lo abre.

• El puerto: si Target es una placa y no has elegido otro en Port, Open Serial usa el de la placa.
• La velocidad: Speed tiene que ser 115200, a la que escribe la VM en todas las placas. Baud, en ESP32 Tools, es otra cosa: la velocidad a la que esptool graba la placa.
• Si la placa se reinicia y su puerto desaparece, el monitor lo dice («COM5 is gone (the board is restarting?)…») y lo vuelve a abrir cuando vuelve.
• Mientras el IDE graba la placa, con Run o Flash Firmware, el monitor se aparta y vuelve al terminar.
• Solo recibe: no envía a la placa lo que escribes. Un programa que espera a readLine() se queda esperando (ver Memoria y límites).
• Si el puerto lo tiene otro programa, no se abre: «Error opening COM port:», con el motivo.

Para cerrarlo, pulsa Close Serial, que es el mismo botón. La barra entera, en El Output y el monitor serie.

Cada vez que arranca, la VM escribe unas líneas suyas antes de las de tu programa. Algunas te dicen en qué punto está:

Línea	Qué quiere decir
«** Copyright (c) 2026 JARU Project.»	La VM de JARU arranca.
«Boot config file loaded.»	Ha leído el boot.cfg.
«> Loading program: SpaceIntruders.jxr», con tu programa	Carga el programa que dice el boot.cfg.
«Valid JARU program, version 0.9.7»	El programa es de JARU, y de esa versión.
«ESP32 0.9.7…», en el rótulo de JARU VM	La versión de la VM de la placa. Empieza por «ESP32» con cualquier chip.

Si el programa da un error, el monitor lo enseña y, si Line numbers está encendida, dice en qué línea.

Al cambiar de versión

Cada versión de JARU IDE trae su VM, y un programa compilado con una versión nueva necesita la VM de esa versión. Después de actualizar JARU IDE, pulsa Flash Firmware en cada placa antes de enviarle programas, y vuelve a compilar tus proyectos (ver Actualizar desde la 0.9.6).

Run no mira la versión de la VM

Su paso 2 solo comprueba que la placa lleve la VM de JARU, de la versión que sea. En una placa con la VM de la 0.9.6, un programa compilado con la 0.9.7 empieza y se para en la primera instrucción nueva, con el error «Unknown Opcode encountered». Graba antes el firmware.

Para saber qué VM lleva una placa, abre el monitor serie: el rótulo de JARU VM dice su versión en la línea que empieza por «ESP32» («ESP32 0.9.7…» en la 0.9.7), y «Valid JARU program, version …» dice la del programa.

La placa lleva	El programa es de	Lo que pasa
La VM de la 0.9.6	La 0.9.7	Empieza y se para con «Unknown Opcode encountered».
La VM de la 0.9.7	Una versión más nueva	No lo carga: «Error: Program version … uses bytecode newer than this VM», que pide «Update the firmware from the IDE».

En los dos casos, el arreglo es el mismo: Flash Firmware con el JARU IDE que compiló el programa, y después Run.

Si la placa no arranca

Mira primero el Output y, si el IDE llegó a grabar, el monitor serie.

Lo que dice el Output:

• «Error: No COM port configured. Please open ESP32 Tools and select a port.», con Run, o «No COM port has been selected. Please select a valid COM port to proceed.», con los botones de ESP32 Tools. La placa no tiene puerto. En ESP32 Tools, pulsa Scan Ports, elige el de tu placa en Port y pulsa Save Device.
• «Error: no active ESP32 device profile selected.» El proyecto no tiene placa activa, por ejemplo después de quitarla con Forget. Elige una en Build › Target, o guarda una con Save Device.
• La ventana «Target not available». La placa de Target ya no está en el proyecto. Elige otra en Build › Target.
• «Error: Cannot determine flash size», o «Warning: Could not auto-detect flash size.» y «Could not read the board to check it». El IDE no ha podido leer la placa. Comprueba que está conectada y que Port es su puerto: vuelve a pulsar Scan Ports. Si el monitor serie está abierto en ese puerto, ciérralo.
• «DEPLOYMENT FAILED: Error during LittleFS build.» No se ha podido hacer la imagen de los ficheros. Si es porque no caben, Check Storage, en la página Storage, te dice cuánto ocupan (ver Memoria y límites).
• «DEPLOYMENT FAILED: Error while flashing LittleFS.», «Error: failed to save JARU VM firmware.» o «PROCESS FAILED». esptool no ha podido grabar la placa, y sus líneas, encima, dicen por qué. Comprueba el puerto y el cable, y que ningún otro programa, ni el monitor serie con Upload Program, tenga abierto el puerto.

Lo que dice el monitor serie:

• «File "boot.cfg" not found. System halted.» La placa lleva la VM, pero todavía ningún programa: pulsa Run.
• «Boot config format fail. System halted.» El boot.cfg de la placa está mal escrito. Run lo vuelve a generar.
• «boot.cfg has no "jaru_app" in its "jaru" section…», cada 5 segundos. El proyecto no tiene fichero principal, así que el boot.cfg no dice qué programa arrancar. Elígelo en la lista Main File, arriba del explorador (ver El archivo principal), y pulsa Run.
• «Please insert an SD card to boot.», cada 2 segundos. La placa tiene la tarjeta SD encendida (Storage › SD Card) y la VM no la encuentra: mete la tarjeta, comprueba sus pines o apágala, y pulsa Run.
• «> Error: The file … could not be found.» y «> Halted, press enter to reboot !!!». La placa no tiene el programa que pide su boot.cfg, por ejemplo después de un Upload Program sin compilar. El monitor serie no envía teclas: pulsa Run, que compila y envía el programa.
• «Unknown Opcode encountered» o «Update the firmware from the IDE». La VM de la placa es de otra versión: ver Al cambiar de versión.
• «Display: Invalid panel/bus configuration from boot.cfg.» La pantalla de la placa no cuadra con el perfil: el controlador o el bus no son de los que maneja la VM de su chip. Revisa el perfil (ver Una placa que no está en la lista).

Si se queda reiniciándose

Abre el monitor serie y mira qué se repite antes de cada reinicio.

• No sale ninguna línea de JARU, ni «** Copyright (c) 2026 JARU Project.»: la placa no lleva la VM. Pasa, por ejemplo, si contestas No en Run on the board, o con Upload Program en una placa sin VM. Pulsa Flash Firmware y después Run.
• La VM arranca, empieza tu programa y la placa se reinicia: algo en tu programa hace caer la VM. Un error normal de JARU no reinicia la placa: la VM lo enseña y vuelve a empezar el programa. Corrige el programa y envíaselo con Run. En el ESP32-P4 y el ESP32-S31, un fallo así no reinicia la placa: la deja parada, con el error en el monitor serie.
• Si el IDE no consigue abrir el puerto, porque aparece y desaparece con cada reinicio, arranca la placa en modo de descarga: con su botón BOOT pulsado mientras la reinicias. Después pulsa Run o Flash Firmware.

En la Waveshare ESP32-S3-Touch-LCD-2.8 y la JaruCade, Power.sleep() deja la placa sin USB: ver Placas soportadas.

Problemas conocidos

• Upload Program no aparta el monitor serie. Si está abierto en el puerto de la placa, esptool no puede abrirlo y la grabación falla. Ciérralo antes con Close Serial, o usa Run, que sí lo aparta. Les pasa lo mismo a Check Storage, Get Info, Generate y Get MAC.
• Run pregunta casi siempre por cambios sin guardar. Con Flash Size en Auto detect, que es lo de serie y lo que traen los ejemplos, Run y Flash Firmware escriben en él el tamaño que leen de la placa, sin guardarlo. El siguiente Run pregunta entonces «…unsaved changes… Save changes before closing?», aunque no se cierre nada. Contesta Yes.
• Cancel, en esa pregunta, para Run sin decir nada. El Output no escribe nada más: no se ha grabado nada.
• El paso 2 dice «Flashing in progress…» mientras lee la placa. No graba nada: es la lectura.

Todos los problemas conocidos de JARU, juntos, están en Problemas conocidos.