Introduction to AtomVM
Relevant source files
The following files were used as context for generating this wiki page:
AtomVM is a lightweight, ground-up implementation of the Bogdan Erlang Abstract Machine (BEAM) designed specifically for resource-constrained IoT devices and micro-controllers. It enables developers to execute bytecode compiled from Erlang, Elixir, or Gleam source code on hardware that typically lacks the resources for a full Erlang/OTP distribution. By providing a functional programming environment with an actor-based concurrency model, AtomVM simplifies the development of complex, simultaneous tasks on devices costing as little as $2.
The project encompasses a virtual machine written in C, core libraries, and specialized ports for various hardware platforms and environments, including ESP32, STM32, Raspberry Pi RP2, and WebAssembly. Its primary goal is to offer a memory-managed, concurrency-oriented platform while maintaining a small footprint suitable for systems with as little as 128KB of addressable RAM.
Sources: doc/src/index.rst:11-23, doc/src/welcome-to-atomvm.md:11-19, doc/src/welcome-to-atomvm.md:68-75
Key Features and Capabilities
AtomVM provides a robust subset of the BEAM's functionality, optimized for embedded environments.
| Feature | Description |
|---|---|
| Bytecode Execution | Executes standard compiled .beam files using a specialized runtime. |
| Concurrency | Supports lightweight "processes" with pre-emptive scheduling and message passing. |
| Memory Management | Includes efficient per-process garbage collection and shared data where permissible. |
| Hardware Interfacing | Native APIs for GPIO, I2C, SPI, UART, and ADC. |
| Networking | Supports WiFi and Bluetooth on compatible hardware (e.g., ESP32). |
| SMP Support | Leverages multi-core processors (e.g., ESP32) without code changes. |
| Cross-Platform | Runs on micro-controllers and full OSs like Linux, FreeBSD, and MacOS for testing. |
Sources: doc/src/index.rst:16-23, doc/src/welcome-to-atomvm.md:21-34, doc/src/welcome-to-atomvm.md:59-66
High-Level Architecture
The AtomVM architecture is centered around a virtual machine (VM) that translates BEAM opcodes into actions on the host hardware. The system is designed to be as "lean" as possible, prioritizing memory conservation and heap fragmentation prevention over raw performance.
Software Stack and Execution Flow
The following diagram illustrates how Erlang/Elixir source code is transformed and executed within the AtomVM environment.
AtomVM uses existing Erlang/Elixir compilers. The resulting bytecode is packaged into .avm (Packbeam) files, which are then flashed to the device.
Sources: doc/src/welcome-to-atomvm.md:71-77, doc/src/getting-started-guide.md:65-72, doc/src/atomvm-internals.md:110-117
Core Components
- GlobalContext: A singleton object representing the root of all data structures in the VM. It manages process tables, atom storage, and module loading.
- Context: Encapsulates a single lightweight Erlang process, including its stack, heap, and mailbox.
- Scheduler: Manages the execution of processes. In SMP builds, it runs one scheduler thread per CPU core.
- Module: Represents a loaded BEAM module containing code and metadata.
Sources: doc/src/atomvm-internals.md:43-51, doc/src/atomvm-internals.md:83-93, doc/src/atomvm-internals.md:188-193
Runtime Environment
AtomVM simulates a physical machine by executing instructions in software. It handles process spawning, monitoring, and inter-process communication (IPC) via message passing.
Process Lifecycle and Scheduling
Processes in AtomVM are pre-emptively scheduled. Each process is assigned "reductions" (an instruction budget). Once the budget is exhausted or the process waits for a message, the scheduler yields control to the next ready process.
The GlobalContext maintains separate lists for waiting_processes, running_processes, and ready_processes to manage this flow.
Sources: doc/src/atomvm-internals.md:84-106, doc/src/atomvm-internals.md:195-201
Memory Management
AtomVM employs a per-process heap allocation model. Garbage collection is performed independently for each process, which prevents "stop-the-world" pauses across the entire system. Shared data (Reference Counted Binaries) is managed in the GlobalContext to save memory.
Sources: doc/src/welcome-to-atomvm.md:52-58, doc/src/atomvm-internals.md:112-117
Platform Support
AtomVM provides specialized ports for different hardware targets.
| Platform | Features/Support |
|---|---|
| ESP32 | Mature support, includes WiFi, Bluetooth, and multi-core SMP. |
| STM32 | Supports various chipsets with at least 128KB RAM and 512KB Flash. |
| Raspberry Pi RP2 | Supports RP2040 and RP2350 (Pico, Pico 2). Uses flash for JIT. |
| Generic UNIX | Linux, MacOS, FreeBSD. Primarily used for development and testing. |
| WebAssembly | Runs in browsers and NodeJS via Emscripten. |
Sources: doc/src/getting-started-guide.md:27-31, doc/src/getting-started-guide.md:154-159, doc/src/getting-started-guide.md:213-217, doc/src/getting-started-guide.md:387-393
The Boot Process (ESP32 Example)
On the ESP32, the flash module is partitioned to accommodate both the VM and the user application.
The VM searches the data partition for the first module exporting start/0 to begin execution.
Sources: doc/src/getting-started-guide.md:65-80
Implementation Flavors
AtomVM supports different execution modes depending on the platform and configuration:
- Emulated (Default): The VM interprets BEAM bytecode directly.
- JIT (Just-In-Time): Compiles BEAM bytecode to native machine code at runtime (available on x86_64, aarch64, armv6m, riscv32).
- Native/AOT: Code is precompiled on a desktop and executed natively on the device.
- Hybrid: Combines native code for performance-critical libraries with emulated code for user applications.
Sources: doc/src/atomvm-internals.md:144-162
Summary
AtomVM bridges the gap between high-level functional programming and low-level embedded systems. By implementing a resource-efficient BEAM, it brings Erlang and Elixir's powerful concurrency and reliability features to the IoT domain. Its modular architecture and support for various execution modes (Emulated, JIT, Native) make it a flexible platform for developing modern networked applications on minimal hardware.
Sources: doc/src/welcome-to-atomvm.md:36-40, doc/src/atomvm-internals.md:17-30