Skip to main content
Ask Embedder to flash after a successful build, in Act or Debug mode. Embedder runs your project’s flash command, then captures boot output from the port you name, so you can confirm the new firmware started. Flashing replaces the firmware on the board and usually resets it. If a debugger session holds the probe, Embedder closes that session before the flash command runs.

​
Before you flash

  1. Connect and power the intended board and probe.
  2. Build firmware for the exact MCU and board revision.
  3. Record the flash command, serial port, and baud rate in EMBEDDER.md (flash_command, serial_port, and serial_baudrate).
  4. Install the flash utility, drivers, and USB permissions on the machine connected to the board.
Embedder runs the command your project already uses, such as pio run -t upload, idf.py flash, west flash, nrfjprog, or a J-Link command file. It doesn’t supply those utilities or their board configuration.

​
Flash a local board

Adjust the port, baud rate, and expected message to your firmware. If you don’t name a port, Embedder flashes and reports the command output without capturing boot output. Embedder asks you to approve the flash command before it runs, unless your approval settings already allow it. Choosing Allow always on a flash request also approves later flash requests in the same chat. While the command runs, Embedder pauses open serial connections in the Monitor and reconnects them afterward. It doesn’t reset the target itself: the flash utility’s own reset starts the application.

​
Catch the first boot lines

When you give the baud rate, or Embedder already knows it for that port, Embedder opens the port before the flash command runs. Output is captured from the first byte after reset. Without a known baud rate, Embedder detects it after flashing and starts capturing then, so early lines can be missed. If the port disappears during flashing, Embedder waits about 5 seconds for it to return. An empty log on its own doesn’t prove the firmware failed to boot.

​
Read the result

Embedder reports programming and boot capture separately: For SWO output, flash first and then follow ITM/SWO.

​
Flash through a bridge

Use this when the board and probe are attached to another machine running a hardware bridge. You provide a built artifact instead of a flash command, and the bridge host needs probe-rs or OpenOCD installed.
  1. Run /bridge and choose the bridge connected to the board.
  2. Build the firmware and note the artifact path, such as an ELF, BIN, or HEX file.
  3. Ask Embedder to flash it:
Embedder uploads the artifact to the bridge host and programs the target there. It picks the flasher from the chip you name, or from the board saved on the bridge:
  • If the bridge has several saved boards, name the board or chip you mean.
  • If no target can be detected, give the chip name, such as nRF52832_xxAA, and Embedder programs it with probe-rs.
  • If several probes on the bridge can program that chip, Embedder lists them. Name the one to use as VID:PID:Serial.
  • Programming through a bridge times out after 5 minutes.
  • An artifact without a selected bridge can’t be flashed. For a local board, use a flash command.
Serial output stays routed through the bridge. Ask Embedder to read the boot output as a separate step, and keep programming success and boot verification as separate checks.

​
Program XMOS hardware

Use XMOS xTAG and xgdb for .xe artifacts and XTC Tools setup. Embedder writes the image to boot flash with xflash, which replaces the image the board boots from, including a dev kit’s factory firmware. Capturing xSCOPE output after flashing runs the image again from RAM. Use the power-cycle check in that guide to confirm the board boots from flash. xsim reloads the simulator instead of programming a board.

​
Prepare an AURIX project

For the supported Windows ADS and iLLD workflow, follow AURIX ADS and Flasher. Project setup creates command-line build files. Programming is a separate step that uses AURIX Flasher and the generated HEX file.

​
Share a board with other chats

One chat uses a board at a time. If another chat holds it, run /hardware-queue to see which one. /hardware-force-release --confirm frees the board, but it can interrupt that chat’s work. If another chat flashed the same board after your last flash, Embedder re-runs your last flash command before your next debugger, hardware-script, or serial operation on that board, and tells you it did. If that re-flash fails, the operation doesn’t run. Flash the board again yourself, then retry.

​
Troubleshoot

  • Wrong or missing artifact: rebuild for the selected board and use the actual output path.
  • Flash command times out: check the probe connection, then ask for a longer timeout of up to 10 minutes.
  • Probe busy: stop conflicting captures or debugger connections, and run /hardware-queue to check for another chat.
  • Flash succeeds but the expected message is absent: check the output transport, baud rate, capture timing, and the flash utility’s reset behavior. Ask Embedder to read the port again before reflashing.
  • Port missing after flashing: USB serial boards can take a moment to reappear. Ask Embedder to read the port again once it’s listed.
  • Bridge reports no target or several targets: give the chip name, or name the board you mean.
  • probe-rs or OpenOCD not found on the bridge host: install probe-rs or OpenOCD on the bridge host as your normal user, then run embedder bridge doctor.
  • Board no longer detected: check power, cable, boot mode, and the board’s recovery instructions before retrying.
To observe an existing failure without replacing the firmware, start with Monitor and debug.
Last modified on October 13, 2026