Networking Stack
Relevant source files
The following files were used as context for generating this wiki page:
The AtomVM Networking Stack provides a rich set of networking APIs designed for writing robust IoT applications that communicate over IP networks. It leverages Erlang and Elixir's natural affinity for telecommunications to enable wireless and networked capabilities on resource-constrained micro-controllers, such as the ESP32.
The stack bridges the high-level Erlang/OTP networking patterns (sockets, SSL/TLS, and WebSockets) with low-level platform-specific implementations. It supports standard device protocols and WiFi networking on supported hardware, ensuring that actor-based concurrency can be applied to network I/O.
Sources: doc/src/welcome-to-atomvm.md, doc/src/network-programming-guide.md
Architecture Overview
The networking stack in AtomVM is structured as a series of layers that translate BEAM bytecode operations into native system calls. This involves NIF (Native Implemented Function) interfaces for sockets and SSL, as well as platform-specific drivers.
Component Layers
| Layer | Component | Description |
|---|---|---|
| Erlang Layer | gen_tcp, ssl, socket | High-level OTP modules used by applications. |
| NIF Layer | otp_socket.c, otp_ssl.c, inet.c | C implementations providing the interface between BEAM and system networking. |
| System Layer | BSD Sockets / MbedTLS | The underlying platform network implementation (e.g., ESP-IDF, Posix). |
Sources: doc/src/network-programming-guide.md, src/libAtomVM/otp_socket.c, src/libAtomVM/otp_ssl.c
Networking Data Flow
The following diagram illustrates how an Erlang process interacts with the network through the AtomVM internal structures.
The GlobalContext manages these interactions by coordinating with the scheduler to handle non-blocking I/O. When a socket is not ready for reading or writing, the process is moved to the waiting_processes list until sys_poll_events detects activity.
Sources: doc/src/atomvm-internals.md, src/libAtomVM/otp_socket.c
Socket Implementation (otp_socket.c and inet.c)
AtomVM implements a subset of the Erlang socket and inet modules. These modules handle the lifecycle of network connections, including creation, binding, listening, and data transmission.
Key Internal Functions
socket_open_nif: Initializes a new network socket.socket_bind_nif: Assigns a local address to a socket.socket_recv_nif: Handles data reception, often involving trapping the process if data is not immediately available.socket_send_nif: Handles data transmission.inet_getaddr_nif: Resolves hostnames to IP addresses.
Sources: src/libAtomVM/otp_socket.c, src/libAtomVM/inet.c
Socket Lifecycle Sequence
This sequence shows the typical flow for establishing a connection and receiving data.
SSL and Security (otp_ssl.c)
Security is handled via the ssl module, which interfaces with native TLS libraries (such as MbedTLS on ESP32). This allows AtomVM to support encrypted communication required for modern IoT protocols like HTTPS or MQTT over TLS.
SSL Components
The otp_ssl.c file implements the bridge to the TLS provider. Key tasks include:
- Handshake Management: Coordinating the multi-step TLS handshake process.
- Certificate Verification: Validating peer certificates against trusted CAs.
- Encrypted I/O: Wrapping standard socket send/recv operations with encryption/decryption logic.
Sources: src/libAtomVM/otp_ssl.c, doc/src/welcome-to-atomvm.md
WebAssembly and Browser Networking
In WebAssembly (Wasm) environments, the networking stack behaves differently due to browser security restrictions.
- WebSockets: Used for real-time bidirectional communication.
- Fetch API: Used in the Emscripten port to load BEAM or AVM modules over HTTP/HTTPS.
- Proxying: Since Wasm cannot directly open raw TCP sockets, network calls are often proxied to the main thread or translated into WebSocket frames.
Sources: examples/emscripten/echo_websocket.html, doc/src/atomvm-internals.md
Summary
The AtomVM Networking Stack enables micro-controllers to participate in complex networked environments by providing a BEAM-compatible interface to IP protocols. By integrating with the virtual machine's scheduler and process management, it allows developers to build concurrent, networked applications using Erlang or Elixir while the underlying C implementation handles the complexities of non-blocking I/O and hardware-specific drivers.