Flashing & Bootloaders
Relevant source files
The following files were used as context for generating this wiki page:
Flashing and bootloaders in AtomVM represent the critical initial steps for provisioning microcontrollers with the virtual machine and executing Erlang/Elixir applications. The process typically involves deploying a pre-compiled AtomVM binary image, which includes the platform-specific bootloader and partition map, followed by the deployment of compiled BEAM bytecode bundled into AtomVM "packbeam" (.avm) files.
Sources: doc/src/getting-started-guide.md:14-18, doc/src/getting-started-guide.md:66-70
Architecture and Memory Layout
The memory layout of an AtomVM-enabled device is divided into functional partitions. The bootloader occupies the initial sectors of the flash memory, followed by the partition map and the AtomVM Virtual Machine executable. Application data, provided as AVM files, is stored in designated data partitions.
ESP32 Flash Layout
On the ESP32 platform, the AtomVM image contains the ESP bootloader and the partition map. The application code resides at specific offsets depending on whether Elixir support is required.
The diagram shows the logical vertical structure of the ESP32 flash module.
Sources: doc/src/getting-started-guide.md:73-89
Device Bootloader Offsets
Different chipsets require the bootloader to be flashed at specific memory offsets.
| Chipset | Bootloader Offset |
|---|---|
| ESP32 / ESP32-S2 | 0x1000 |
| ESP32-S3 / C2 / C3 / C6 / C61 / H2 | 0x0 |
| ESP32-C5 / P4 | 0x2000 |
| STM32 (General) | 0x8000000 |
Sources: doc/src/getting-started-guide.md:144-155, doc/src/getting-started-guide.md:200-204
Tooling and Deployment
Flash Tools
AtomVM utilizes platform-specific industry-standard tools for the flashing process.
- ESP32: Uses
esptool.pyfor erasing and writing flash. - STM32: Uses
st-flashfrom thestlinksuite. - Raspberry Pi Pico (RP2): Uses UF2 files copied via USB or
picotoolfor software resets.
Sources: doc/src/atomvm-tooling.md:21-28, doc/src/getting-started-guide.md:118-125
Deployment Workflow
The deployment follows a sequence of erasing existing flash, writing the VM image, and finally flashing the application AVM.
This sequence illustrates the standard procedure for provisioning a new device.
Sources: doc/src/getting-started-guide.md:104-108, doc/src/getting-started-guide.md:167-172, tools/test/smoke-test/README.md:104-118
Application Entry Point Discovery
Upon booting, the AtomVM Virtual Machine initializes and mounts the BEAM partitions. It specifically searches the main data partition for a module that exports a start/0 function. Once identified, the VM commences execution of the BEAM bytecode at that entry point.
ESP32 Partitioning
On ESP32, the main.avm is typically loaded at address 0x210000 (for thin images) or 0x250000 (for Elixir-enabled images).
The VM boot logic for application discovery.
Sources: doc/src/getting-started-guide.md:167-172, doc/src/atomvm-tooling.md:110-125
Platform Specifics
Raspberry Pi Pico (RP2040/RP2350)
The Pico platform uses the UF2 (USB Flashing Format). Deploying AtomVM requires two distinct UF2 files:
- VM Image: e.g.,
Atomvm-pico-v0.7.0.uf2 - Core Libraries: e.g.,
atomvmlib-pico-v0.7.0.uf2
Users must enter BOOTSEL mode to mount the device as a USB mass storage volume before copying files.
Sources: doc/src/getting-started-guide.md:244-255, doc/src/getting-started-guide.md:268-272
STM32
STM32 deployment often requires manual building from source due to the variety of board configurations. The default application address is 0x8080000 for 1MB flash devices and 0x8060000 for 512KB devices.
Sources: doc/src/getting-started-guide.md:200-208, doc/src/atomvm-tooling.md:167-172
Summary
The flashing and bootloading system in AtomVM ensures that the lightweight BEAM implementation is correctly positioned in memory to manage hardware resources. By using standard tools like esptool.py and st-flash, AtomVM integrates into existing embedded development workflows while providing a specialized discovery mechanism for Erlang/Elixir application entry points within the flash memory partitions.
Sources: doc/src/welcome-to-atomvm.md:65-72, doc/src/getting-started-guide.md:14-18