Start here

Bare-Metal Ada on the ESP32-S3

A step-by-step guide to running Ada on the ESP32-S3 with no ESP-IDF, no FreeRTOS, and no Python. Thirteen short steps, one aspect each, from a blank machine to your own Ada application running on both cores.

The ESP32-S3 is normally programmed through Espressif's ESP-IDF: a large C SDK, a Python build front end, and FreeRTOS underneath everything. This guide takes a different route. The runtime here owns both cores — the context switch, the interrupt vectors, the clock tick, the SMP scheduler and the inter-core interrupt are all its own, written in Ada and a little Xtensa assembly. FreeRTOS never runs; its scheduler is not even linked. The toolchain you install is one package manager.

Each page below covers exactly one thing, and each links to the next. Steps 1 to 5 get an LED blinking. Steps 6 to 9 explain what you just did and how to configure it. Steps 10 to 13 are your own project, the driver library, the debugger, and what to do when something goes wrong.

Begin with step 01 →

What you need (and what you don't)
The board, the cable, the one package manager — and the four things you are not installing.
Installing Alire and the toolchains
Installing Alire and selecting the cross, native and build toolchains.
Getting the code (submodules are not optional)
Cloning the repository with its two submodules, and what is in the tree.
Plugging in the board and finding the port
The native USB port, the device node, serial permissions, and forcing download mode.
Your first blink
One command builds, flashes and monitors a pure-Ada GPIO driver at 2 Hz.
What happens between reset and Main
Every layer between the mask ROM and your first line of Ada, and why Main can be empty.
What a build actually does
The five build steps, and the two Ada host tools that replace esptool.
Choosing a runtime profile
light-tasking, embedded, full — what each gives you and which to pick.
Board configuration: board.ads
Flash and PSRAM size in board.ads, and why PSRAM size rebuilds the bootloader.
Your own project, outside the repo
Scaffolding a standalone project anywhere on disk with export.sh and esp32-ada.
Talking to the hardware: the HAL
Using the peripheral drivers, how they are shaped, and what still needs verifying on your board.
Debugging: GDB over the same cable
OpenOCD and GDB over the same USB cable, editor integration, and decoding a Guru Meditation.
Troubleshooting, and where to go next
The failure modes worth recognising on sight, a cheat sheet, and where to read next.

Start here

Bare-Metal Ada on the ESP32-S3

A step-by-step guide to running Ada on the ESP32-S3 with no ESP-IDF, no FreeRTOS, and no Python. Thirteen short steps, one aspect each, from a blank machine to your own Ada application running on both cores.

The ESP32-S3 is normally programmed through Espressif's ESP-IDF: a large C SDK, a Python build front end, and FreeRTOS underneath everything. This guide takes a different route. The runtime here owns both cores — the context switch, the interrupt vectors, the clock tick, the SMP scheduler and the inter-core interrupt are all its own, written in Ada and a little Xtensa assembly. FreeRTOS never runs; its scheduler is not even linked. The toolchain you install is one package manager.

Each page below covers exactly one thing, and each links to the next. Steps 1 to 5 get an LED blinking. Steps 6 to 9 explain what you just did and how to configure it. Steps 10 to 13 are your own project, the driver library, the debugger, and what to do when something goes wrong.

Begin with step 01 →

What you need (and what you don't)
The board, the cable, the one package manager — and the four things you are not installing.
Installing Alire and the toolchains
Installing Alire and selecting the cross, native and build toolchains.
Getting the code (submodules are not optional)
Cloning the repository with its two submodules, and what is in the tree.
Plugging in the board and finding the port
The native USB port, the device node, serial permissions, and forcing download mode.
Your first blink
One command builds, flashes and monitors a pure-Ada GPIO driver at 2 Hz.
What happens between reset and Main
Every layer between the mask ROM and your first line of Ada, and why Main can be empty.
What a build actually does
The five build steps, and the two Ada host tools that replace esptool.
Choosing a runtime profile
light-tasking, embedded, full — what each gives you and which to pick.
Board configuration: board.ads
Flash and PSRAM size in board.ads, and why PSRAM size rebuilds the bootloader.
Your own project, outside the repo
Scaffolding a standalone project anywhere on disk with export.sh and esp32-ada.
Talking to the hardware: the HAL
Using the peripheral drivers, how they are shaped, and what still needs verifying on your board.
Debugging: GDB over the same cable
OpenOCD and GDB over the same USB cable, editor integration, and decoding a Guru Meditation.
Troubleshooting, and where to go next
The failure modes worth recognising on sight, a cheat sheet, and where to read next.

Start here

Bare-Metal Ada on the ESP32-S3

A step-by-step guide to running Ada on the ESP32-S3 with no ESP-IDF, no FreeRTOS, and no Python. Thirteen short steps, one aspect each, from a blank machine to your own Ada application running on both cores.

The ESP32-S3 is normally programmed through Espressif's ESP-IDF: a large C SDK, a Python build front end, and FreeRTOS underneath everything. This guide takes a different route. The runtime here owns both cores — the context switch, the interrupt vectors, the clock tick, the SMP scheduler and the inter-core interrupt are all its own, written in Ada and a little Xtensa assembly. FreeRTOS never runs; its scheduler is not even linked. The toolchain you install is one package manager.

Each page below covers exactly one thing, and each links to the next. Steps 1 to 5 get an LED blinking. Steps 6 to 9 explain what you just did and how to configure it. Steps 10 to 13 are your own project, the driver library, the debugger, and what to do when something goes wrong.

Begin with step 01 →

What you need (and what you don't)
The board, the cable, the one package manager — and the four things you are not installing.
Installing Alire and the toolchains
Installing Alire and selecting the cross, native and build toolchains.
Getting the code (submodules are not optional)
Cloning the repository with its two submodules, and what is in the tree.
Plugging in the board and finding the port
The native USB port, the device node, serial permissions, and forcing download mode.
Your first blink
One command builds, flashes and monitors a pure-Ada GPIO driver at 2 Hz.
What happens between reset and Main
Every layer between the mask ROM and your first line of Ada, and why Main can be empty.
What a build actually does
The five build steps, and the two Ada host tools that replace esptool.
Choosing a runtime profile
light-tasking, embedded, full — what each gives you and which to pick.
Board configuration: board.ads
Flash and PSRAM size in board.ads, and why PSRAM size rebuilds the bootloader.
Your own project, outside the repo
Scaffolding a standalone project anywhere on disk with export.sh and esp32-ada.
Talking to the hardware: the HAL
Using the peripheral drivers, how they are shaped, and what still needs verifying on your board.
Debugging: GDB over the same cable
OpenOCD and GDB over the same USB cable, editor integration, and decoding a Guru Meditation.
Troubleshooting, and where to go next
The failure modes worth recognising on sight, a cheat sheet, and where to read next.

Start here

Bare-Metal Ada on the ESP32-S3

A step-by-step guide to running Ada on the ESP32-S3 with no ESP-IDF, no FreeRTOS, and no Python. Thirteen short steps, one aspect each, from a blank machine to your own Ada application running on both cores.

The ESP32-S3 is normally programmed through Espressif's ESP-IDF: a large C SDK, a Python build front end, and FreeRTOS underneath everything. This guide takes a different route. The runtime here owns both cores — the context switch, the interrupt vectors, the clock tick, the SMP scheduler and the inter-core interrupt are all its own, written in Ada and a little Xtensa assembly. FreeRTOS never runs; its scheduler is not even linked. The toolchain you install is one package manager.

Each page below covers exactly one thing, and each links to the next. Steps 1 to 5 get an LED blinking. Steps 6 to 9 explain what you just did and how to configure it. Steps 10 to 13 are your own project, the driver library, the debugger, and what to do when something goes wrong.

Begin with step 01 →

What you need (and what you don't)
The board, the cable, the one package manager — and the four things you are not installing.
Installing Alire and the toolchains
Installing Alire and selecting the cross, native and build toolchains.
Getting the code (submodules are not optional)
Cloning the repository with its two submodules, and what is in the tree.
Plugging in the board and finding the port
The native USB port, the device node, serial permissions, and forcing download mode.
Your first blink
One command builds, flashes and monitors a pure-Ada GPIO driver at 2 Hz.
What happens between reset and Main
Every layer between the mask ROM and your first line of Ada, and why Main can be empty.
What a build actually does
The five build steps, and the two Ada host tools that replace esptool.
Choosing a runtime profile
light-tasking, embedded, full — what each gives you and which to pick.
Board configuration: board.ads
Flash and PSRAM size in board.ads, and why PSRAM size rebuilds the bootloader.
Your own project, outside the repo
Scaffolding a standalone project anywhere on disk with export.sh and esp32-ada.
Talking to the hardware: the HAL
Using the peripheral drivers, how they are shaped, and what still needs verifying on your board.
Debugging: GDB over the same cable
OpenOCD and GDB over the same USB cable, editor integration, and decoding a Guru Meditation.
Troubleshooting, and where to go next
The failure modes worth recognising on sight, a cheat sheet, and where to read next.

Start here

Bare-Metal Ada on the ESP32-S3

A step-by-step guide to running Ada on the ESP32-S3 with no ESP-IDF, no FreeRTOS, and no Python. Thirteen short steps, one aspect each, from a blank machine to your own Ada application running on both cores.

The ESP32-S3 is normally programmed through Espressif's ESP-IDF: a large C SDK, a Python build front end, and FreeRTOS underneath everything. This guide takes a different route. The runtime here owns both cores — the context switch, the interrupt vectors, the clock tick, the SMP scheduler and the inter-core interrupt are all its own, written in Ada and a little Xtensa assembly. FreeRTOS never runs; its scheduler is not even linked. The toolchain you install is one package manager.

Each page below covers exactly one thing, and each links to the next. Steps 1 to 5 get an LED blinking. Steps 6 to 9 explain what you just did and how to configure it. Steps 10 to 13 are your own project, the driver library, the debugger, and what to do when something goes wrong.

Begin with step 01 →

What you need (and what you don't)
The board, the cable, the one package manager — and the four things you are not installing.
Installing Alire and the toolchains
Installing Alire and selecting the cross, native and build toolchains.
Getting the code (submodules are not optional)
Cloning the repository with its two submodules, and what is in the tree.
Plugging in the board and finding the port
The native USB port, the device node, serial permissions, and forcing download mode.
Your first blink
One command builds, flashes and monitors a pure-Ada GPIO driver at 2 Hz.
What happens between reset and Main
Every layer between the mask ROM and your first line of Ada, and why Main can be empty.
What a build actually does
The five build steps, and the two Ada host tools that replace esptool.
Choosing a runtime profile
light-tasking, embedded, full — what each gives you and which to pick.
Board configuration: board.ads
Flash and PSRAM size in board.ads, and why PSRAM size rebuilds the bootloader.
Your own project, outside the repo
Scaffolding a standalone project anywhere on disk with export.sh and esp32-ada.
Talking to the hardware: the HAL
Using the peripheral drivers, how they are shaped, and what still needs verifying on your board.
Debugging: GDB over the same cable
OpenOCD and GDB over the same USB cable, editor integration, and decoding a Guru Meditation.
Troubleshooting, and where to go next
The failure modes worth recognising on sight, a cheat sheet, and where to read next.

Start here

Bare-Metal Ada on the ESP32-S3

A step-by-step guide to running Ada on the ESP32-S3 with no ESP-IDF, no FreeRTOS, and no Python. Thirteen short steps, one aspect each, from a blank machine to your own Ada application running on both cores.

The ESP32-S3 is normally programmed through Espressif's ESP-IDF: a large C SDK, a Python build front end, and FreeRTOS underneath everything. This guide takes a different route. The runtime here owns both cores — the context switch, the interrupt vectors, the clock tick, the SMP scheduler and the inter-core interrupt are all its own, written in Ada and a little Xtensa assembly. FreeRTOS never runs; its scheduler is not even linked. The toolchain you install is one package manager.

Each page below covers exactly one thing, and each links to the next. Steps 1 to 5 get an LED blinking. Steps 6 to 9 explain what you just did and how to configure it. Steps 10 to 13 are your own project, the driver library, the debugger, and what to do when something goes wrong.

Begin with step 01 →

What you need (and what you don't)
The board, the cable, the one package manager — and the four things you are not installing.
Installing Alire and the toolchains
Installing Alire and selecting the cross, native and build toolchains.
Getting the code (submodules are not optional)
Cloning the repository with its two submodules, and what is in the tree.
Plugging in the board and finding the port
The native USB port, the device node, serial permissions, and forcing download mode.
Your first blink
One command builds, flashes and monitors a pure-Ada GPIO driver at 2 Hz.
What happens between reset and Main
Every layer between the mask ROM and your first line of Ada, and why Main can be empty.
What a build actually does
The five build steps, and the two Ada host tools that replace esptool.
Choosing a runtime profile
light-tasking, embedded, full — what each gives you and which to pick.
Board configuration: board.ads
Flash and PSRAM size in board.ads, and why PSRAM size rebuilds the bootloader.
Your own project, outside the repo
Scaffolding a standalone project anywhere on disk with export.sh and esp32-ada.
Talking to the hardware: the HAL
Using the peripheral drivers, how they are shaped, and what still needs verifying on your board.
Debugging: GDB over the same cable
OpenOCD and GDB over the same USB cable, editor integration, and decoding a Guru Meditation.
Troubleshooting, and where to go next
The failure modes worth recognising on sight, a cheat sheet, and where to read next.

Bare-Metal Ada on the ESP32-S3

Contents

Bare-Metal Ada on the ESP32-S3

Contents

Bare-Metal Ada on the ESP32-S3

Contents

Bare-Metal Ada on the ESP32-S3

Contents

Bare-Metal Ada on the ESP32-S3

Contents

Bare-Metal Ada on the ESP32-S3

Contents