RP2040 (Pico) Platform Guide

Relevant source files

The following files were used as context for generating this wiki page:

• doc/src/getting-started-guide.md
• doc/src/atomvm-tooling.md
• src/platforms/rp2/tests/CMakeLists.txt
• doc/src/index.rst
• doc/src/welcome-to-atomvm.md

AtomVM supports deployment on boards based on the Raspberry Pi RP2 series System-on-Chips (SoCs), specifically the RP2040 and RP2350. This includes popular hardware such as the Raspberry Pi Pico, Pico W, Pico 2, and Pico 2 W. The platform allows developers to execute Erlang and Elixir bytecode on these microcontrollers, leveraging the BEAM's concurrency model for IoT applications.

The guide covers the requirements, deployment process for the Virtual Machine (VM) and core libraries, and the tooling necessary to flash Erlang/Elixir applications. AtomVM on the RP2 platform provides a managed environment with features like pre-emptive scheduling and hardware interface support (GPIO, I2C, SPI, UART).
Sources: doc/src/getting-started-guide.md:315-321, doc/src/welcome-to-atomvm.md:15-30

System Requirements

Deployment on the Raspberry Pi Pico or Pico 2 requires a specific set of hardware and software components.

Component	Requirement
Host PC	Computer running macOS or Linux (Windows not currently supported)
Hardware	Raspberry Pi Pico or Pico 2 board
Connection	USB cable for power and data transfer
Console	Serial console program (e.g., minicom, screen)
Tooling	Erlang/OTP, Elixir (optional), rebar3 (Erlang), mix (Elixir)
Utility	picotool (recommended for software resets and device management)

Sources: doc/src/getting-started-guide.md:323-333

Provisioning the Virtual Machine

Provisioning the RP2 platform involves flashing two primary components: the AtomVM Virtual Machine image and the AtomVM core libraries.

Flashing Binary Images

For most users, flashing pre-built .uf2 binary images is the recommended path. This requires the device to be in BOOTSEL mode, where it mounts as a USB mass storage device.

1. Enter BOOTSEL Mode: Press and hold the BOOTSEL button while connecting the device to the USB port.
2. Mounting: The device appears as a volume named RPI-RP2 (for Pico) or RP2350 (for Pico 2).
3. Deployment: Copy the VM image and the core library file to the volume. Note that the device auto-unmounts after each file copy, requiring the procedure to be repeated for the second file.

Platform-Specific File Names

Binary images follow a specific naming convention based on the board and version:

• VM Image: Atomvm-<board>-<version>.uf2 (e.g., Atomvm-pico-v0.7.0.uf2)
• Core Library: atomvmlib-<board>-<version>.uf2 (e.g., atomvmlib-pico-v0.7.0.uf2)

Sources: doc/src/getting-started-guide.md:347-359

Application Deployment and Tooling

Applications are compiled into PackBEAM (.avm) files and then converted to .uf2 format for flashing.

Using atomvm_rebar3_plugin

For Erlang developers, the atomvm_rebar3_plugin provides a streamlined workflow via the pico_flash target.

$ rebar3 atomvm pico_flash

This command automates the following sequence:

1. Compiles the Erlang source code.
2. Generates a .avm file.
3. Resets the Pico device (using picotool if available).
4. Copies the generated .uf2 file to the mounted device.
   Sources: doc/src/atomvm-tooling.md:144-154

Serial Console and Debugging

AtomVM on the RP2 platform defaults to using the USB UART for console output.

• Boot Delay: By default, the VM waits 20 seconds for a serial connection to be established before starting the application.
• Logging: If a connection is established, the console displays the AtomVM revision, the found startup beam, and application output.
• Software Reset: picotool reboot -f can be used to force the device back into application mode to re-attempt a serial connection.

Build Configuration for RP2

When building AtomVM or tests from source for the RP2 platform, specific CMake configurations are used to integrate with the Raspberry Pi Pico SDK.

• Headers: The platform requires platform_smp.h and platform_atomic.h.
• Standard I/O: The build system allows enabling/disabling USB or UART stdio. For example, tests often disable USB stdio in favor of UART to maintain stability with certain JS-based runners.
• Extra Outputs: The pico_add_extra_outputs command is used to generate the .uf2 files from the ELF binary.

Sources: src/platforms/rp2/tests/CMakeLists.txt:33-47

Summary

The RP2 platform support in AtomVM enables Erlang and Elixir development on Raspberry Pi Pico series hardware. By utilizing .uf2 images for the VM and core libraries, and rebar3 or mix plugins for application deployment, developers can maintain a standard Erlang/Elixir workflow while targeting resource-constrained microcontrollers. Key features include support for both RP2040 and RP2350 SoCs and integrated tooling for automated flashing and serial debugging.
Sources: doc/src/getting-started-guide.md:315-333, doc/src/atomvm-tooling.md:144-154