Step 01 of 13

What you need (and what you don't)

One board, one USB cable, and one package manager. No ESP-IDF, no idf.py, no esptool, no Python anywhere in the build or flash path.

Most ESP32 tutorials open by telling you to install a 400 MB SDK. This one does not. The whole toolchain here is Alire, the Ada package manager, which fetches a cross-compiler for you. Everything else — packaging the image, writing it to flash, reading the console — is done by tools that live in this repository and are themselves written in Ada.

Hardware

An ESP32-S3 devkit, using its native USB port — the one wired to the chip's built-in USB-Serial-JTAG controller. On most boards it is labelled USB, and the other one is labelled UART. Pick the native one: it carries the console and the debugger over a single cable.
A data-carrying USB cable. A charge-only cable will enumerate nothing and waste an hour of your life.

That is the minimum. An LED and a resistor on GPIO0 make the first example visible, but the console output alone proves it works.

Software

Alire (alr) — fetches three toolchains: the gnat_xtensa_esp32_elf cross-compiler for the chip, a native gnat_native for the host tools, and gprbuild.
git, with submodule support (the runtime lives partly in two submodules).
A host C compiler — used exactly once, to build the xtensa-dynconfig core-config plugin the toolchain needs.

What you do not install: ESP-IDF, idf.py, esptool, or Python. The build path uses none of them. (esptool remains an optional fallback if you happen to have it and prefer it — see what a build does.)

The big picture

Two commands drive everything. Here is what they set in motion:

  your Ada code  ─┐
  Ada RTS        ─┤  ./build.sh ─> gprbuild (Alire xtensa GNAT) ─> app_main.o
  (generated)     │             ─> link (vendored bootloader + boot glue)
  glue.c (boot)  ─┘             ─> esp_elf2image (Ada)           ─> app.bin
                     ./flash.sh ─> esp_flash (Ada, over USB ROM) ─> board runs it

The Ada runtime is generated on the first build and cached; you never build it by hand. The two host tools (esp_elf2image and esp_flash) are compiled once, also on the first build. That is why the first build is slow and every one after it is fast.

Time and platform

Budget about 15 minutes, most of it the one-time toolchain download. The commands below are shown for Linux (Ubuntu/Debian). macOS is similar but untested; on Windows, use WSL2.

Step 01 of 13

What you need (and what you don't)

One board, one USB cable, and one package manager. No ESP-IDF, no idf.py, no esptool, no Python anywhere in the build or flash path.

Most ESP32 tutorials open by telling you to install a 400 MB SDK. This one does not. The whole toolchain here is Alire, the Ada package manager, which fetches a cross-compiler for you. Everything else — packaging the image, writing it to flash, reading the console — is done by tools that live in this repository and are themselves written in Ada.

Hardware

An ESP32-S3 devkit, using its native USB port — the one wired to the chip's built-in USB-Serial-JTAG controller. On most boards it is labelled USB, and the other one is labelled UART. Pick the native one: it carries the console and the debugger over a single cable.
A data-carrying USB cable. A charge-only cable will enumerate nothing and waste an hour of your life.

That is the minimum. An LED and a resistor on GPIO0 make the first example visible, but the console output alone proves it works.

Software

Alire (alr) — fetches three toolchains: the gnat_xtensa_esp32_elf cross-compiler for the chip, a native gnat_native for the host tools, and gprbuild.
git, with submodule support (the runtime lives partly in two submodules).
A host C compiler — used exactly once, to build the xtensa-dynconfig core-config plugin the toolchain needs.

What you do not install: ESP-IDF, idf.py, esptool, or Python. The build path uses none of them. (esptool remains an optional fallback if you happen to have it and prefer it — see what a build does.)

The big picture

Two commands drive everything. Here is what they set in motion:

  your Ada code  ─┐
  Ada RTS        ─┤  ./build.sh ─> gprbuild (Alire xtensa GNAT) ─> app_main.o
  (generated)     │             ─> link (vendored bootloader + boot glue)
  glue.c (boot)  ─┘             ─> esp_elf2image (Ada)           ─> app.bin
                     ./flash.sh ─> esp_flash (Ada, over USB ROM) ─> board runs it

The Ada runtime is generated on the first build and cached; you never build it by hand. The two host tools (esp_elf2image and esp_flash) are compiled once, also on the first build. That is why the first build is slow and every one after it is fast.

Time and platform

Budget about 15 minutes, most of it the one-time toolchain download. The commands below are shown for Linux (Ubuntu/Debian). macOS is similar but untested; on Windows, use WSL2.

Step 01 of 13

What you need (and what you don't)

One board, one USB cable, and one package manager. No ESP-IDF, no idf.py, no esptool, no Python anywhere in the build or flash path.

Most ESP32 tutorials open by telling you to install a 400 MB SDK. This one does not. The whole toolchain here is Alire, the Ada package manager, which fetches a cross-compiler for you. Everything else — packaging the image, writing it to flash, reading the console — is done by tools that live in this repository and are themselves written in Ada.

Hardware

An ESP32-S3 devkit, using its native USB port — the one wired to the chip's built-in USB-Serial-JTAG controller. On most boards it is labelled USB, and the other one is labelled UART. Pick the native one: it carries the console and the debugger over a single cable.
A data-carrying USB cable. A charge-only cable will enumerate nothing and waste an hour of your life.

That is the minimum. An LED and a resistor on GPIO0 make the first example visible, but the console output alone proves it works.

Software

Alire (alr) — fetches three toolchains: the gnat_xtensa_esp32_elf cross-compiler for the chip, a native gnat_native for the host tools, and gprbuild.
git, with submodule support (the runtime lives partly in two submodules).
A host C compiler — used exactly once, to build the xtensa-dynconfig core-config plugin the toolchain needs.

What you do not install: ESP-IDF, idf.py, esptool, or Python. The build path uses none of them. (esptool remains an optional fallback if you happen to have it and prefer it — see what a build does.)

The big picture

Two commands drive everything. Here is what they set in motion:

  your Ada code  ─┐
  Ada RTS        ─┤  ./build.sh ─> gprbuild (Alire xtensa GNAT) ─> app_main.o
  (generated)     │             ─> link (vendored bootloader + boot glue)
  glue.c (boot)  ─┘             ─> esp_elf2image (Ada)           ─> app.bin
                     ./flash.sh ─> esp_flash (Ada, over USB ROM) ─> board runs it

The Ada runtime is generated on the first build and cached; you never build it by hand. The two host tools (esp_elf2image and esp_flash) are compiled once, also on the first build. That is why the first build is slow and every one after it is fast.

Time and platform

Budget about 15 minutes, most of it the one-time toolchain download. The commands below are shown for Linux (Ubuntu/Debian). macOS is similar but untested; on Windows, use WSL2.

Step 01 of 13

What you need (and what you don't)

One board, one USB cable, and one package manager. No ESP-IDF, no idf.py, no esptool, no Python anywhere in the build or flash path.

Most ESP32 tutorials open by telling you to install a 400 MB SDK. This one does not. The whole toolchain here is Alire, the Ada package manager, which fetches a cross-compiler for you. Everything else — packaging the image, writing it to flash, reading the console — is done by tools that live in this repository and are themselves written in Ada.

Hardware

An ESP32-S3 devkit, using its native USB port — the one wired to the chip's built-in USB-Serial-JTAG controller. On most boards it is labelled USB, and the other one is labelled UART. Pick the native one: it carries the console and the debugger over a single cable.
A data-carrying USB cable. A charge-only cable will enumerate nothing and waste an hour of your life.

That is the minimum. An LED and a resistor on GPIO0 make the first example visible, but the console output alone proves it works.

Software

Alire (alr) — fetches three toolchains: the gnat_xtensa_esp32_elf cross-compiler for the chip, a native gnat_native for the host tools, and gprbuild.
git, with submodule support (the runtime lives partly in two submodules).
A host C compiler — used exactly once, to build the xtensa-dynconfig core-config plugin the toolchain needs.

What you do not install: ESP-IDF, idf.py, esptool, or Python. The build path uses none of them. (esptool remains an optional fallback if you happen to have it and prefer it — see what a build does.)

The big picture

Two commands drive everything. Here is what they set in motion:

  your Ada code  ─┐
  Ada RTS        ─┤  ./build.sh ─> gprbuild (Alire xtensa GNAT) ─> app_main.o
  (generated)     │             ─> link (vendored bootloader + boot glue)
  glue.c (boot)  ─┘             ─> esp_elf2image (Ada)           ─> app.bin
                     ./flash.sh ─> esp_flash (Ada, over USB ROM) ─> board runs it

The Ada runtime is generated on the first build and cached; you never build it by hand. The two host tools (esp_elf2image and esp_flash) are compiled once, also on the first build. That is why the first build is slow and every one after it is fast.

Time and platform

Budget about 15 minutes, most of it the one-time toolchain download. The commands below are shown for Linux (Ubuntu/Debian). macOS is similar but untested; on Windows, use WSL2.

Step 01 of 13

What you need (and what you don't)

One board, one USB cable, and one package manager. No ESP-IDF, no idf.py, no esptool, no Python anywhere in the build or flash path.

Most ESP32 tutorials open by telling you to install a 400 MB SDK. This one does not. The whole toolchain here is Alire, the Ada package manager, which fetches a cross-compiler for you. Everything else — packaging the image, writing it to flash, reading the console — is done by tools that live in this repository and are themselves written in Ada.

Hardware

An ESP32-S3 devkit, using its native USB port — the one wired to the chip's built-in USB-Serial-JTAG controller. On most boards it is labelled USB, and the other one is labelled UART. Pick the native one: it carries the console and the debugger over a single cable.
A data-carrying USB cable. A charge-only cable will enumerate nothing and waste an hour of your life.

That is the minimum. An LED and a resistor on GPIO0 make the first example visible, but the console output alone proves it works.

Software

Alire (alr) — fetches three toolchains: the gnat_xtensa_esp32_elf cross-compiler for the chip, a native gnat_native for the host tools, and gprbuild.
git, with submodule support (the runtime lives partly in two submodules).
A host C compiler — used exactly once, to build the xtensa-dynconfig core-config plugin the toolchain needs.

What you do not install: ESP-IDF, idf.py, esptool, or Python. The build path uses none of them. (esptool remains an optional fallback if you happen to have it and prefer it — see what a build does.)

The big picture

Two commands drive everything. Here is what they set in motion:

  your Ada code  ─┐
  Ada RTS        ─┤  ./build.sh ─> gprbuild (Alire xtensa GNAT) ─> app_main.o
  (generated)     │             ─> link (vendored bootloader + boot glue)
  glue.c (boot)  ─┘             ─> esp_elf2image (Ada)           ─> app.bin
                     ./flash.sh ─> esp_flash (Ada, over USB ROM) ─> board runs it

The Ada runtime is generated on the first build and cached; you never build it by hand. The two host tools (esp_elf2image and esp_flash) are compiled once, also on the first build. That is why the first build is slow and every one after it is fast.

Time and platform

Budget about 15 minutes, most of it the one-time toolchain download. The commands below are shown for Linux (Ubuntu/Debian). macOS is similar but untested; on Windows, use WSL2.