Create

Flash it

What idf.py flash writes onto a Kode Dot over USB-C, what it leaves alone, how to read a failure, and how to know the image landed.

What it is

idf.py flash is the one command that puts your build on the Kode Dot. It writes three things over the USB-C cable: the bootloader, the partition table and your app, each at its own place in the 32 MB flash. It erases only the sectors it writes, so settings stored in NVS, Wi-Fi credentials among them, survive a flash.

A Kode Dot ships with kodeOS, and the bootloader and the partition table are part of it. A flash replaces both, so kodeOS stops starting and your app is what the Kode Dot runs from then on.

The same cable is the console. idf.py monitor shows the boot log and then your own log lines, and flash monitor does both in one go, which is how you will run it most of the time.

How it works

flowchart LR
pc["idf.py flash"] -- "USB-C, USB-Serial-JTAG" --> p4["ESP32-P4"]
p4 --> bl["0x2000 bootloader"]
p4 --> pt["0x8000 partition table"]
p4 --> app["0x10000 app"]
p4 -. "untouched" .-> nvs["NVS, settings"]

Three regions written over the cable; the rest of the flash is left alone

The P4 speaks to the computer through its built-in USB-Serial-JTAG, so no adapter is needed and the same port carries JTAG for a debugger. The play buttons on this site write the same three regions through the browser's Web Serial, with the offsets read from a manifest next to the binaries.

Specifications

Thing	Value
Command	`idf.py -p <port> flash`, or `flash monitor` to stay on the log
Transport	USB-C, the only one there is
Writes	Bootloader at `0x2000`, partition table at `0x8000`, app at `0x10000`
Leaves	Everything else, NVS included
Speed	`idf.py -b <baud> flash` raises it; a flaky cable is the usual reason to lower it
Port on macOS	`/dev/cu.usbmodem*`. It changes on every reconnect and between bootloader and app
Erase everything	`idf.py erase-flash`, a separate command, on purpose
Other ways on	The marketplace over the same cable from Chrome or Edge, the Kode app over Bluetooth, or the marketplace over Wi-Fi to a Kode Dot that is on your account and online

Gotchas

Example code

The commands, in the order you run them, with what each one prints when it worked.

# flash.sh - 2026-09-18 - from Kode with love
#
# Build, find the port, flash, and stay on the log. The flash ends with one
# "Hash of data verified" per region; the monitor then shows the bootloader,
# the app's name and version, and your own log lines.
idf.py build
ls /dev/cu.usbmodem*
idf.py -p /dev/cu.usbmodem2101 flash monitor

In the SDK

tools: Kode's flashing and bench scripts in kode-sdk.