kodeOS internals

Building and flashing

How kodeOS builds into an image, where the board settings come from, and the two ways to flash a Kode Dot: esptool or OpenOCD.

What it is

kodeOS is an ESP-IDF project. idf.py build at the root of the repository produces build/kodeos.bin, and idf.py flash writes it to a Kode Dot over the USB-C cable. The first build of any project, and the generic flash, are on build/setup, build/first-build and build/flash. This page covers what is particular to the kodeOS tree: how the root build file is wired, which file holds which setting, the storage image, and the JTAG route.

There are two independent ways to write the flash. One is esptool over the serial port. The other is OpenOCD over JTAG. Both use the same USB-C cable, because the ESP32-P4 has a USB-Serial/JTAG peripheral that presents a serial port and a JTAG interface together. Use the serial way unless your editor is set to flash through JTAG.

How it is connected

The root CMakeLists.txt does four jobs before ESP-IDF takes over. It adds the SDK's components, reads two default files, sets the version and the chip, and stages the FAT image that goes into the storage partition.

flowchart LR
subgraph settings["Settings"]
  board["kbsp<br/>sdkconfig.board"] --> cfg["sdkconfig<br/>generated"]
  defaults["sdkconfig.defaults"] --> cfg
end
subgraph firmware["Firmware"]
  comps["sdk/components"] -- "EXTRA_COMPONENT_DIRS" --> bin["build/kodeos.bin"]
end
subgraph fatimg["FAT image"]
  pack["kui/kody/pack"] --> stage["build/storage_stage"]
  img["storage_image"] --> stage
  stage -- "fatfs_create_<br/>spiflash_image" --> fat["build/storage.bin"]
end
cfg --> bin
class bin,fat store

The SDK is a git submodule at sdk/, with the ESP32-C5's firmware nested inside it. Fresh clones need git submodule update --init --recursive. components/ in the kodeOS tree holds only kgui, the screens that sit on top of the SDK.

The board facts (flash size, PSRAM mode, cache, console, the SDIO wiring to the C5) live in sdkconfig.board next to the partition table in sdk/components/kbsp, so every project reads one copy. See sdk/kbsp.

Specifications

The commands

PORT is the serial port of the Kode Dot. On macOS it looks like /dev/cu.usbmodem*. idf.py flash compares each image with the *_flashed.bin files that the previous flash left in the build directory, verifies the result, and falls back to a full write when the check fails.

The root build file

A changed pack or image file configures again by itself. A pack regenerated by kodygen.py reaches the image on the next configure.

The settings files

A value already in the generated sdkconfig beats a new default, every time. A project spells out two board facts itself, because ESP-IDF needs them before it can fetch the shared file:

The storage image

A new kodeOS reaches a board in one of four ways:

• kcli.py -p PORT install build/kodeos.bin --dst os.
• install src="sd:kodeos.bin" dst=os.
• An https:// source.
• install src="pending" dst=os, after a computer wrote the image into the mailbox.

See internals/bench-tools and internals/command-set.

Flashing over JTAG

tools/jtag_flash.sh does three things, in order.

Exit codes:

• 0: flashed and verified.
• 1: nothing to flash (no flasher_args.json, or openocd is not on the path).
• 2: the adapter stayed busy.

A real flash of a 1.25 MB image takes about 13 s, and a no-op verify about 1 s. JTAG and serial are separate paths: one can work while the other fails.

The serial port

Gotchas

Example code

The commands in the order you run them, from the root of the kodeOS repository. Each step ends in something you can see.

1. Load ESP-IDF v6.1 in the shell, for example . ~/.espressif/v6.1/esp-idf/export.sh. The path depends on how you installed it.
2. Fetch the SDK and the C5 firmware once: git submodule update --init --recursive. sdk/c5/CMakeLists.txt now exists.
3. Build: idf.py build. It ends with the size of build/kodeos.bin.
4. Find the port with ls /dev/cu.usbmodem*, then flash: idf.py -p PORT flash. It ends with one Hash of data verified per image.
5. Seed the storage volume when you need Kody's pack and the C5 image on the board: idf.py -p PORT storage-flash.
6. To use JTAG instead of the serial steps, run tools/jtag_flash.sh. It prints flashed over JTAG; nothing left listening.
7. Check the layers before you call a change done: tools/check_layers.sh exits 0.

In the SDK

• CMakeLists.txt: the root build file, in the kodeOS repository.
• tools/jtag_flash.sh: the JTAG flash script.
• components/kbsp: sdkconfig.board and partitions.csv, the files every project reads.