STM32 Platform Guide
Relevant source files
The following files were used as context for generating this wiki page:
The STM32 platform support in AtomVM allows the Erlang virtual machine to run on a variety of 32-bit ARM Cortex-M microcontrollers from STMicroelectronics. AtomVM implements a subset of the Bogdan Erlang Abstract Machine (BEAM), optimized for memory-constrained environments like the STM32, which typically feature limited RAM and flash storage compared to traditional computing platforms.
On the STM32, AtomVM provides a preemptive multitasking environment that executes BEAM bytecode compiled from Erlang or Elixir. It interfaces with hardware peripherals such as GPIO and USART, enabling the development of functional, concurrency-oriented IoT applications on small, low-cost embedded devices. Sources: doc/src/welcome-to-atomvm.md, doc/src/getting-started-guide.md:213-219
Platform Requirements and Capabilities
AtomVM support for STM32 is focused on devices with a minimum of 128KB of RAM and 512KB of flash (1MB is recommended). The platform utilizes the libAtomVM core library along with platform-specific drivers.
Hardware Requirements
| Requirement | Minimum Specification | Recommended |
|---|---|---|
| RAM | ~128 KB | >128 KB |
| Flash | 512 KB | 1 MB |
| Connectivity | USB/UART Connector | Integrated ST-LINK |
| Debugging | ST-LINK v2/v3 | ST-LINK v3 |
Sources: doc/src/getting-started-guide.md:220-238
Software Components
The STM32 build integrates the core virtual machine with the following platform-specific components:
- OpenCM3: Used for low-level hardware abstraction.
- libAtomVMPlatformSTM32: Contains STM32-specific implementations of system functions, GPIO drivers, and JIT flash streaming.
- Packbeam: Tooling used to assemble compiled
.beamfiles into.avmimages for flashing.
Sources: src/platforms/stm32/src/lib/CMakeLists.txt:24-41, doc/src/getting-started-guide.md:280-285
Architecture and Memory Layout
The STM32 platform utilizes a specific memory map to separate the virtual machine binary from the Erlang/Elixir application data. The virtual machine looks for an exported start/0 function within the data partition to begin execution.
On a 1MB flash device, the flash is typically split into 512KB for the VM and 512KB for the application. On 512KB devices, the application offset is adjusted to 0x8060000, leaving 128KB for the application. Sources: doc/src/getting-started-guide.md:255-263
Build and Deployment Flow
Because of the diversity of STM32 chipsets, users must build AtomVM from source using CMake to ensure compatibility with their specific board configuration.
Deployment Sequence
- Compilation: Compile Erlang/Elixir code into
.beamfiles. - Packing: Use
packbeamto create a.avmfile. - Flashing VM: Write the
AtomVM-stm32.binto0x8000000usingst-flash. - Flashing App: Write the
.avmfile to the designated application offset (0x8080000or0x8060000).
Console and Debugging
By default, the STM32 platform redirects standard output (stdout) and standard error (stderr) to USART2.
- Configuration: 115200 Baud, 8N1, no flow control.
- Wiring: On Discovery boards, TX is usually PA2. A TTL-USB adapter is required to view output on a host machine.
- Customization: The console can be reconfigured using
BOARDparameters during the CMake build process.
Sources: doc/src/getting-started-guide.md:265-275
Native Execution and JIT
AtomVM supports "Native" and "JIT" (Just-In-Time) execution modes on ARMv6M devices like certain STM32 chips.
- Native Mode: Code is precompiled on a desktop using the JIT compiler and executed natively on the device. This avoids the need to bundle the JIT compiler on the microcontroller.
- JIT Mode: The VM includes a JIT compiler that translates BEAM bytecode to machine code at runtime.
- JIT Stream: For STM32/ARMv6M, machine code is handled via backends like
jit_armv6m.
Sources: doc/src/atomvm-internals.md:129-148, doc/src/atomvm-internals.md:162-175
Technical Summary
The STM32 platform implementation within AtomVM provides a robust environment for running Erlang-style concurrency on ARM Cortex-M hardware. By utilizing a split-flash architecture and USART-based console output, it allows developers to deploy complex functional applications that remain easy to debug and maintain. The reliance on st-flash and CMake ensures a flexible workflow compatible with various development boards including the Nucleo and Discovery lines. Sources: doc/src/getting-started-guide.md:213-225, src/platforms/stm32/src/lib/CMakeLists.txt