Flash hardware from Workshop¶

In this tutorial, you’ll flash a Zephyr application to a physical board from a Zephyr 26.04 LTS Workshop.

Flashing is an inherently unsafe process because it must interface with the host machine and the real world. To gain the benefits of Workshop and to be able to flash hardware, first identify the host device that the board’s flash runner uses. Then grant Workshop access to that host device and install the runner tool in the Workshop container. This configuration preserves the security hygiene that Workshop provides, allows flashing without udev rules or sudo, and creates a reproducible and sandboxed working environment.

Prerequisites¶

A launched zephyr-26-04 Workshop with a synced workspace, as created in Get started with Workshop.
A board from the supported boards list, connected to the host over USB.

Identify the board device class¶

The flash runner decides which host device the board needs, but the device class varies between boards. To find the runner for your board, open the page for your board in the supported boards list and go to its Programming and Debugging section. If the page has no such section, search the page for mentions of flash, flashing, or debug. Find the names of the default runner and the tool that the runner calls, then read the matching row in this table.

Board name	Default flash runner	Board device class	Host device
ESP32-C3-DevKitM (`esp32c3_devkitm/esp32c3`)	`esp32`	USB serial bootloader	Serial node, such as `/dev/ttyUSB0`
Nordic nRF52840 DK (`nrf52840dk/nrf52840`)	`nrfjprog`	On-board J-Link probe	USB probe
BBC micro:bit v2 (`bbc_microbit_v2/nrf52833`)	`pyocd`	On-board CMSIS-DAP probe	USB probe
STM32 Nucleo-144 H753ZI (`nucleo_h753zi/stm32h753xx`)	`stm32cubeprogrammer`	On-board ST-Link probe	USB probe
NXP FRDM-RW612 (`frdm_rw612/rw612`)	`jlink`	On-board MCU-Link probe (J-Link firmware)	USB probe
Renesas EK-RA8M1 (`ek_ra8m1/r7fa8m1ahecbd`)	`jlink`	On-board J-Link probe	USB probe
ESP32-S3-DevKitC (`esp32s3_devkitc/esp32s3/procpu`)	`esp32`	USB serial bootloader	Serial node, such as `/dev/ttyUSB0`

For example, the page for the ESP32-C3-DevKitM (esp32c3_devkitm) uses the esp32 runner, which flashes over the USB serial bootloader with esptool.py. The board therefore needs a serial host device, such as /dev/ttyUSB0.

Find the device identifiers¶

Run these commands on the host.

Workshop uses device identifiers to grant access to the flashing interface of the board. The board device class determines which device that interface uses. When you connect the board, the Linux host exposes the interface as a device. A USB serial bootloader appears as a serial device node. An on-board debug probe, such as a J-Link, appears as a USB device.

USB serial bootloader¶

A board with a serial bootloader exposes a USB serial adapter. First, find the device node:

$ ls /dev/ttyUSB* /dev/ttyACM*
ls: cannot access '/dev/ttyACM*': No such file or directory
/dev/ttyUSB0

Here the board is /dev/ttyUSB0. The error for /dev/ttyACM* means that no device of that type is present. Boards that use a different adapter chip or the USB controller built into the SoC can expose /dev/ttyACM0 instead. Use the node reported for your device.

If you connected several serial devices, unplug the board and run the command again: the node that disappears belongs to the board. You can also watch the node appear as you plug the board in:

$ udevadm monitor --udev --subsystem-match=tty

Now query its subsystem, vendor ID, and product ID:

$ udevadm info --query=property \
    --property=SUBSYSTEM \
    --property=ID_VENDOR_ID \
    --property=ID_MODEL_ID \
    /dev/ttyUSB0
SUBSYSTEM=tty
ID_MODEL_ID=ea60
ID_VENDOR_ID=10c4

This output is from a CP2102 adapter, common on ESP32 kits. Record the ID_VENDOR_ID and ID_MODEL_ID values reported for your device. We will need them for the rest of the tutorial.

USB probe¶

A board with an on-board debug probe registers as a raw USB device, rather than a serial node. List the USB devices:

$ lsusb
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 002 Device 002: ID 0bda:0487 Realtek Semiconductor Corp. Dell dock
...
Bus 003 Device 015: ID 10c4:ea60 Silicon Labs CP210x UART Bridge
...

The output shows one line per device. The last line above is the CP2102 serial adapter of an ESP32-C3-DevKitM. A board with a J-Link probe shows a line such as ID 1366:1061 SEGGER J-Link instead. The first hexadecimal value after ID is the vendor ID, here 10c4. The second value is the product ID, here ea60. Record the values that correspond to your board. We will need them for the rest of the tutorial.

If you connected several boards, unplug the target board and run the command again: the line that disappears belongs to the board.

Some debug probes also expose a serial console. If you need console access in the Workshop, identify the additional serial device and declare a separate tty plug for it.

Create a device SDK¶

Make these edits and run these commands on the host.

Now that we have the VENDOR_ID and PRODUCT_ID values, we can create a Workshop SDK. We’ll create an in-project SDK that declares one custom-device plug for each device your boards need:

$ mkdir -p .workshop/board-devices
$ editor .workshop/board-devices/sdk.yaml

The sdk.yaml file defines the interfaces to your hardware and will be imported by the .workshop/zephyr-26-04.yaml for the project. Each plug requires a name, the custom-device interface, and at least one device filter. The subsystem filter selects the device class:

.workshop/board-devices/sdk.yaml¶

name: board-devices
plugs:
  <BOARD>-serial:              # USB serial adapter
    interface: custom-device
    subsystem: tty
    vendorid: "<VENDOR ID>"
    productid: "<PRODUCT ID>"
  <BOARD>-probe:               # on-board debug probe
    interface: custom-device
    subsystem: usb
    vendorid: "<VENDOR ID>"
    productid: "<PRODUCT ID>"

If you