ESP32 Platform Guide
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
AtomVM provides a specialized port for the Espressif ESP32 platform, enabling the execution of Erlang and Elixir applications on microcontrollers. The ESP32 port is implemented as an Espressif IoT Development Framework (IDF) application, leveraging the IDF's CMake-based build system to integrate virtual machine code with low-level hardware drivers and system libraries. Sources: doc/src/getting-started-guide.md:27-28, src/platforms/esp32/README.md:9-11
The platform supports a wide range of ESP32 variants, including the original ESP32, S-series (S2, S3), C-series (C2, C3, C5, C6, C61), and H2 modules. By providing a pre-emptive multitasking environment, AtomVM allows developers to write concurrent IoT applications using lightweight processes and message passing, abstracting away the complexities of manual thread management and locking typically found in C-based embedded development. Sources: doc/src/getting-started-guide.md:46-48, doc/src/welcome-to-atomvm.md:42-50
Architecture and System Integration
The ESP32 port of AtomVM is structured as an IDF application where the core virtual machine is integrated as a component. The entry point of the application is responsible for booting the device and initializing the virtual machine environment.
Flash Memory Layout
The ESP32 flash is divided into specific regions to accommodate the bootloader, partition map, the AtomVM binary (the VM itself), and the application data.
The diagram shows the logical segments of the ESP32 flash module and the starting addresses for data partitions depending on the image type (thin vs. Elixir-enabled). Sources: doc/src/getting-started-guide.md:65-85
Component Integration
AtomVM integrates with various ESP32 peripherals through two primary mechanisms:
- NIFs (Native Implemented Functions): Stateless C functions called directly from Erlang/Elixir code.
- Ports: Stateful Erlang processes implemented in C that manage peripheral state and communication.
Sources: src/platforms/esp32/README.md:29-33
Supported Peripherals
The ESP32 port provides interfaces for several hardware protocols and features:
| Feature Category | Supported Interfaces |
|---|---|
| I/O & Peripherals | GPIO, UART, I2C, SPI, LEDC |
| Storage | Non-volatile storage (NVS) |
| Networking | WiFi, UDP, TCP/IP |
Sources: src/platforms/esp32/README.md:17-27, doc/src/index.rst:19-21
Deployment and Tooling
Deploying to the ESP32 involves provisioning the VM and then flashing the application bytecode.
Deployment Workflow
The deployment process generally follows these steps:
- Environment Setup: Connect the ESP32 via USB and ensure
esptool.pyis installed. - VM Provisioning: Flash the pre-built AtomVM binary image (e.g.,
Atomvm-esp32-v0.6.0.img) to the device. - Application Flashing: Use tooling to pack BEAM files into an
.avmfile and flash it to the data partition.
The sequence shows the standard iterative cycle of preparing the hardware and deploying the application code. Sources: doc/src/getting-started-guide.md:104-124, doc/src/atomvm-tooling.md:83-95
Bootloader Offsets
The starting address for the bootloader varies by the specific ESP32 chipset:
| Chipset | Bootloader Offset |
|---|---|
| ESP32, ESP32-S2 | 0x1000 |
| ESP32-S3, C2, C3, C6, C61, H2 | 0x0 |
| ESP32-C5, P4 | 0x2000 |
Sources: doc/src/getting-started-guide.md:148-160
Configuration and Optimization
Build-time Configuration
Because the ESP32 is a resource-constrained environment, AtomVM allows for modular builds. Developers can use menuconfig within the ESP-IDF environment to disable specific built-in components (NIFs and Ports) that are not required for a particular application. This reduces the final binary size, which in turn:
- Reduces flash time during development.
- Decreases RAM usage at runtime.
Sources: src/platforms/esp32/README.md:35-42
Application Partitions
Application code is flashed to the main data partition. The specific address depends on the image flavor:
- Thin Images:
0x210000 - Elixir-supported Images:
0x250000
Upon startup, the VM searches this partition for the first module exporting a start/0 function to begin execution. Sources: doc/src/getting-started-guide.md:167-172, doc/src/atomvm-tooling.md:95-115
Conclusion
The ESP32 platform support in AtomVM transforms the microcontroller into a robust environment for functional programming. By integrating tightly with the ESP-IDF and providing high-level abstractions for concurrency and networking, it allows developers to focus on application logic while maintaining the efficiency required for embedded systems. Sources: doc/src/welcome-to-atomvm.md:52-58, src/platforms/esp32/README.md:1-5