kodeOS internals

Arduino

Run a sketch from the Arduino IDE on a Kode Dot as a kodeOS app: the Kode Dot board entry, what Upload does, the pin names and what a sketch can use.

What it is

A sketch built for the Kode Dot is a complete ESP-IDF image, the same kind of file as any other kodeOS app, so kodeOS needs no special code for Arduino. The Kode Dot board entry makes the IDE build it for the right chip and upload it to the right place. You pick the board, write setup() and loop(), press Upload and open the Serial Monitor.

The entry is not in the Boards Manager. The upstream Arduino-ESP32 core has its own kodedot entry, for an ESP32-S3 board. The entry for the Kode Dot comes from a git clone of arduino-esp32 in your sketchbook, with the kodedot block of boards.txt and the folder variants/kodedot/ (the pin map and the code specific to the Kode Dot). The board's FQBN, which only arduino-cli needs, is espressif:esp32:kodedot: the vendor espressif is the name of the directory that holds the clone.

While a sketch runs it owns every peripheral. kodeOS does not run beside it. To return to kodeOS, hold BOT and LEFT together for about one second.

How it is connected

flowchart LR
subgraph pc["On your computer"]
  ide["Arduino IDE<br/>Upload"] --> es["esptool_py_app_only"]
end
subgraph board["On the Kode Dot"]
  mb["app_pending<br/>0x1A00000"]
  am["AO_AppMgr<br/>adopts at boot"]
  reg["apps region"]
  boot["AO_Boot<br/>ALWAYS request"]
  bl["Bootloader<br/>ARMED, jump"]
  mb --> am
  am -- "install" --> reg
  am -- "request" --> boot
  boot --> bl
end
es -- "one write" --> mb
class ide ext
class mb,reg store
class am,boot ao

Upload writes the sketch and nothing else upload.tool=esptool_py_app_only and build.flash_offset=0x1A00000 give one esptool call that writes one file at one address with --flash-size 32MB. There is no bootloader at 0x2000, no partition table at 0x8000 and no boot_app0.bin, so Upload cannot touch kodeOS, and the entry has no EraseFlash menu.

What happens at the next boot

At the next boot AO_AppMgr installs the image into the apps region and verifies the copy. A sketch with the name of an installed app replaces it. If the region is full it verifies the image in the mailbox first and then evicts: the old copy of that sketch first, then the oldest apps. Then AO_AppMgr launches the sketch with a sticky request (internals/boot-model).

The sticky request is why the sketch survives the Serial Monitor: opening the port is a reset on the bootloader's keep list.

The sketch keeps running after:

• the Serial Monitor opening the port;
• the debugger's reset halt;
• a software restart;
• a panic's reboot;
• a deep-sleep wake.

The Kode Dot returns to kodeOS after:

• a power-on (BOT and LEFT);
• a hardware watchdog;
• a hardware brownout reset;
• the next Upload.

A sketch that crashes in setup() restarts again and again until Upload or BOT and LEFT, because the system does not tell a deliberate restart from a crash. A second Upload while a sketch runs works with no button: the bootloader finds the mailbox full and starts kodeOS, which adopts the new image.

Back in kodeOS the sketch is an installed app. Apps shows it as a loose row at the root, with no folder, named after the sketch. Starting it from its row is a one-shot run like any other app, so the Serial Monitor opening the port returns to kodeOS then. Only mailbox adoption writes a sticky request.

The launcher names a sketch by its .ino

kodeOS identifies an app by the project_name in esp_app_desc_t, and the core's prebuilt libraries give every sketch the same one, arduino-lib-builder. Without a fix, two sketches would be one app.

variants/kodedot/kode_app_desc.cpp defines a strong esp_app_desc that overrides the libraries' weak one. project_name is the sketch name without the extension (the entry passes -DKODE_SKETCH_NAME="{build.project_name}"), version is the core's, and date and time are those of the first build in that sketch's build folder, which kodeOS never compares.

All other fields are copied from the libraries' descriptor, because the bootloader checks some of them. The manifest stays empty, since a sketch cannot declare KODE_APP_MANIFEST.

A flash guard lets the sketch write its own data

The sketch runs from the apps region, a data partition. ESP-IDF aborts every flash write when esp_ota_get_running_partition() finds no app partition. The entry adds three link wraps in compiler.c.elf.extra_flags, implemented in variants/kodedot/kode_flash_guard.cpp:

Specifications

The board entry

Pin names

These come from variants/kodedot/pins_arduino.h and match the board's pin map (sdk/kbsp).

The I2C addresses are defined as names:

What works and what does not

Debugging

Start Debugging works as on any board the core supports. OpenOCD attaches over the built-in USB-JTAG and GDB stops on the first line of setup(). Stop and a plain detach leave the sketch running. A JTAG reset returns to the sketch only while a sticky request is in force, and Upload arms one.

Gotchas

Example code

Set up the core once, then upload a sketch.

1. Clone the core into the sketchbook and fetch its tools (about 9 GB): mkdir -p ~/Documents/Arduino/hardware/espressif && cd ~/Documents/Arduino/hardware/espressif && git clone https://github.com/espressif/arduino-esp32.git esp32 && cd esp32/tools && python3 get.py. TBD: the repository and branch that carry the kodedot entry and variant.
2. Restart the Arduino IDE. Open Tools → Board → ESP32 Arduino (in sketchbook) and choose Kode Dot.
3. Connect the Kode Dot over USB-C. In Tools → Port choose the port shown as ESP32 Family Device (the USB numbers 0x303A:0x1001 belong to Espressif's USB-Serial/JTAG), and pick Kode Dot for it once.
4. Open the sketch below and press Upload. The board resets, kodeOS adopts the sketch and it starts.
5. Open Tools → Serial Monitor. One line arrives every 500 ms and the sketch keeps running.
6. Hold BOT and LEFT together for about one second. kodeOS counts the boot as the return from an app, so Apps is on the glass with the sketch in focus.

The sketch prints the uptime, the top button and whether the battery gauge answers, over the real internal bus.

/*
 * arduino_status.ino - 2026-10-28 - from Kode with love
 *
 * Runs on the Kode Dot as an app, with the board set to Kode Dot in the
 * Arduino IDE. Twice a second it prints the uptime, the state of the top
 * button and whether the battery gauge answers on the internal I2C bus.
 * In the Serial Monitor you see one line every 500 ms, and the button value
 * changes while you hold the top button.
 */
#include <Wire.h>
 
/* The battery gauge sits on the internal bus; 1 means it acknowledged. */
static int gaugeAnswers()
{
  Wire.beginTransmission(KODE_I2C_GAUGE);
  if ( Wire.endTransmission() == 0 )
  {
    return 1;
  }
  return 0;
}
 
/* Serial is the USB-C port; Wire uses the board's own SDA and SCL. */
void setup()
{
  Serial.begin(115200);
  Wire.begin(SDA, SCL, 400000);
  pinMode(BUTTON_TOP, INPUT_PULLUP);
}
 
/* Print one status line every half second. */
void loop()
{
  Serial.printf("uptime=%lu ms top_button=%d gauge=%d\n",
                (unsigned long)millis(), digitalRead(BUTTON_TOP), gaugeAnswers());
  delay(500);
}

TBD: this example has not been compiled or run on a Kode Dot yet.

In the SDK

• examples/arduino_hello: the example sketch, which blinks the LED over Wire.
• components/kdrv/apps/include/kapps_fmt.h: the mailbox, the intent word and the request states the upload relies on.
• bootloader_components/main/bootloader_start.c: the closed list of resets that keep a sketch running.