Distributed Erlang
Relevant source files
The following files were used as context for generating this wiki page:
Distributed Erlang in AtomVM allows multiple AtomVM nodes, or a mix of AtomVM and standard Erlang/OTP BEAM nodes, to form a cluster for remote communication. This system provides a partial implementation of the Erlang distribution protocol, optimized for the resource-constrained environments of micro-controllers while maintaining compatibility with Erlang/OTP 24 and higher.
The distribution feature is available on platforms supporting TCP/IP, including Generic Unix, ESP32, and Raspberry Pi Pico (RP2). It enables core Erlang capabilities such as remote message passing, process monitoring, and distributed I/O across distinct physical or virtual devices. Sources: doc/src/distributed-erlang.md:10-16, doc/src/distributed-erlang.md:37
Architecture and Components
The architecture of Distributed Erlang in AtomVM relies on a combination of programmatic startup, a node registration daemon (epmd), and specialized distribution modules.
System Startup and Node Naming
Distribution is not active by default and must be started programmatically using the net_kernel module. Nodes are identified by long names (e.g., atomvm@127.0.0.1) and use cookie-based authentication for security.
The diagram above shows the typical sequence required to transition an AtomVM node into a distributed state. Sources: doc/src/distributed-erlang.md:20-27, doc/src/distributed-erlang.md:34
EPMD (Erlang Port Mapper Daemon)
AtomVM can interface with the standard Erlang/OTP epmd on Unix systems or use its own pure Erlang implementation of the epmd module. This module serves as a name service that allows nodes to locate each other on the network. Sources: doc/src/distributed-erlang.md:29-35
Functional Capabilities
While the implementation is described as "partial," it covers the essential primitives required for functional Erlang clustering.
Supported Features
| Feature | Description |
|---|---|
| Serialization | Full serialization of all Erlang types via External Term Format. |
| Message Passing | Sending and receiving terms between processes on different nodes. |
| Monitoring | Capability to monitor processes across node boundaries. |
| I/O Distribution | Support for "group leader" functionality across nodes. |
| RPC | Remote Procedure Calls from Erlang/OTP to AtomVM nodes. |
Sources: doc/src/distributed-erlang.md:58-64, src/libAtomVM/externalterm.c
Alternative Carriers
AtomVM supports alternative distribution carriers through distribution modules, similar to Erlang/OTP. However, for efficiency in memory-constrained environments, the handlers (f_send and f_recv) exchange data as binaries rather than lists of integers. Sources: doc/src/distributed-erlang.md:41-47
This sequence illustrates the data flow through alternative carriers using binary packets. Sources: doc/src/distributed-erlang.md:48-56
Internal Implementation
External Term Format (ETF)
The core of distribution logic lies in the serialization of Erlang terms into a byte stream. The externalterm.c file provides the implementation for encoding and decoding terms. This ensures that an AtomVM GlobalContext can translate internal heap-allocated terms (like atoms, small integers, or maps) into a format compatible with other BEAM nodes. Sources: src/libAtomVM/externalterm.c, doc/src/atomvm-internals.md:31-35
Distribution NIFs
Native functions (NIFs) implemented in dist_nifs.c provide the interface between the Erlang-level net_kernel and the underlying C runtime. These NIFs handle the low-level socket management and integration with the AtomVM scheduler. Sources: src/libAtomVM/dist_nifs.c
Security and Compatibility
AtomVM distribution is compatible with Erlang/OTP 24 and newer versions. For security, it supports standard cookie-based authentication to prevent unauthorized nodes from joining a cluster. However, the current implementation does not support distribution over TLS (Transport Layer Security). Sources: doc/src/distributed-erlang.md:37-40
Conclusion
Distributed Erlang in AtomVM extends the actor model across network boundaries, allowing micro-controllers like the ESP32 and RP2 to participate in Erlang clusters. By implementing essential features like process monitoring, RPC support, and the External Term Format, AtomVM enables the creation of decentralized IoT systems that can interact seamlessly with powerful cloud-based BEAM instances. Sources: doc/src/distributed-erlang.md:10-16, doc/src/getting-started-guide.md:275-280