# Set up the toolchain

Install ESP-IDF, point a project at the ESP32-P4, and get to a build that compiles. No Kode Dot needed until the last step.

## What it is

Software for the Kode Dot is an ESP-IDF project: C on FreeRTOS, built with
Espressif's `idf.py` command, the same toolchain every ESP32 uses. There is
no Kode toolchain, no account and no runtime in between. What Kode adds is a
component, `kode`, that knows the board: it brings the screen, the touch and
the I2C bus up and gives you one call per part.

This page gets you to a project that compiles. That takes a computer and
half an hour; the Kode Dot comes in on `build/first-build`.

## How it is set up

1. Install **ESP-IDF v6.1** following Espressif's guide for your system, and source its `export.sh`. It sets up the shell you run it in and nothing else, so every new terminal needs it again.
2. Get the `kode` component. **TBD**: where it is published; today it lives inside Kode's monorepo.
3. Start from the template: a `main/app_main.c`, a `CMakeLists.txt` that names the component's folder in `EXTRA_COMPONENT_DIRS`, and an `sdkconfig.defaults` for the ESP32-P4.
4. Point the project at the chip, once: `idf.py set-target esp32p4`.
5. Build: `idf.py build`. The image lands under `build/`.

## Specifications

| Thing | Value |
| --- | --- |
| Toolchain | ESP-IDF v6.1, the version the hardware is validated against. Older than 6.0 does not fully support the ESP32-P4 |
| Target | `esp32p4`, set once per project. `idf.py fullclean` forgets it |
| Language | C on FreeRTOS, with the ESP-IDF drivers underneath |
| Entry point | `app_main()` in the project's `main/` component |
| The board | The `kode` component: `kode_bsp_init()` and one `kode_<part>_*` call per part. `#include "kode.h"` |
| Screen UI | LVGL 9, started by `kode_bsp_init` |
| Build output | `build/`, including the `.bin` you flash |
| Hardware needed | None, up to and including a successful build |

## Gotchas

> **WARNING**
>
> **It builds fine for another ESP32 and fails here with errors that are not
> in your code.** The toolchain is older than 6.0 and predates full ESP32-P4
> support. Install 6.1.

> **WARNING**
>
> **`EXTRA_COMPONENT_DIRS` finds nothing.** It takes the parent folder, not
> the component's own. Point it at `components/` and ESP-IDF scans the
> children; point it at `components/kode/` and it finds nothing.

> **NOTE**
>
> **You changed `sdkconfig.defaults` and nothing changed.** `sdkconfig` was
> generated from it once and is now the one that counts. Delete `sdkconfig`
> and build again.

## Example code

The project files the template gives you. The three together are a project
that compiles to an image which brings the board up and does nothing else.

```cmake
# CMakeLists.txt - 2026-09-18 - from Kode with love
#
# The project's root file. ESP-IDF's own build system does the work; the one
# line that is Kode's names the folder the kode component lives in.
cmake_minimum_required(VERSION 3.16)
set(EXTRA_COMPONENT_DIRS "${CMAKE_CURRENT_LIST_DIR}/../../components")
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(my_app)
```

```cmake
# main/CMakeLists.txt - 2026-09-18 - from Kode with love
#
# The app's own component: one source file, and it requires kode.
idf_component_register(SRCS "app_main.c" INCLUDE_DIRS "." REQUIRES kode)
```

```c
/*
 * main/app_main.c - 2026-09-18 - from Kode with love
 *
 * The smallest Kode Dot app: brings the board up, which powers the screen,
 * starts LVGL and finds the touch controller, then logs that it is there.
 * The screen turns on and stays black; the log says "board up".
 */
#include "esp_log.h"
#include "kode.h"

/* Board up, one line in the log. */
void app_main(void)
{
    ESP_ERROR_CHECK(kode_bsp_init());
    ESP_LOGI("app", "board up, screen %dx%d", KODE_PANEL_H_RES, KODE_PANEL_V_RES);
}
```

The `sdkconfig.defaults` sets the target, the 32 MB flash and the console
on USB; copy it from the template rather than typing it. Compiled on the
date in the headers with ESP-IDF v6.1.

## In the SDK

- [`templates`](https://github.com/kodediy/kode-sdk/tree/main/templates): the project templates in `kode-sdk`.
- [`kode`](https://github.com/kodediy/kode-sdk/tree/main/components/kode): the facade component and its `kode.h`.