lwip.h
lwip.h is the root-level application header. It exposes stack lifecycle,
socket creation, socket I/O, service requests, event callbacks, and memory
accounting.
App-facing socket API.
Hides the altcp / altcp_tls_ce / raw tcp / udp factoring behind a single socket handle and a fixed verb set. Intended for application code that just wants to open a socket-like endpoint, attach a single event callback, and send/recv bytes. The TLS and altcp layers are still directly usable for anyone who needs them — this is an additive convenience layer.
Lifecycle: lwip_start() — once at load time (libload bootstrap + stack memory/timers/RNG; no network yet). Sufficient on its own for crypto/memory primitives (every unit test under tests/unit/ relies on this). lwip_network_up() — bring up USB/netif; call once before networking lwip_service_events() — every main-loop iteration (drives callbacks) lwip_socket_create() — allocate handle, bind netif, kick DHCP lwip_socket_on_event() — register single event callback + arg lwip_socket_connect() — initiate connect; completion fires STATE_CHANGE lwip_socket_available() / lwip_socket_read() — data path in main loop lwip_socket_write() — send data (from CONNECTED callback or loop) lwip_socket_shutdown() / close / abort — teardown lwip_socket_destroy() — free handle lwip_stop() — stack shutdown
Typical main loop: while (lwip_socket_is_active(sock) && !done) { lwip_service_events(); size_t n = lwip_socket_available(sock); if (n) lwip_socket_read(sock, buf, n); }
Defines
-
LWIP_HDR_LWIP_APP_H
-
LWIP_CE_VERSION_MAJOR
lwIP-CE release version (distinct from the vendored upstream lwIP version).
-
LWIP_CE_VERSION_MINOR
-
LWIP_CE_VERSION_PATCH
-
LWIP_CE_VERSION_STRING
-
LWIP_SOCKET_EVENTF_ERROR
-
LWIP_SOCKET_EVENTF_STATE_CHANGE
-
LWIP_SOCKET_EVENTF_IO
-
LWIP_SOCKET_EVENTF_ALL
-
LWIP_SOCKET_SVC_DHCP
Service wait flags.
-
LWIP_SOCKET_SVC_SNTP
-
LWIP_SOCKET_SVC_DNS
-
LWIP_SOCKET_RX_RING_INIT_SIZE
Timing constants.
-
LWIP_SOCKET_RX_RING_STEP_SIZE
-
LWIP_SOCKET_RX_RING_MAX_SIZE
-
lwip_start()
Typedefs
-
typedef void (*lwip_socket_event_cb)(struct lwip_socket *sock, lwip_socket_event_type_t type, const void *ev_data, void *arg)
Single typed event callback.
sock — the socket that generated the event. type — LWIP_SOCKET_EV_ERROR / STATE_CHANGE / IO. ev_data — typed payload (cast to the matching _data_t* for the event type). Valid only for the duration of the callback. arg — user pointer supplied to lwip_socket_on_event().
-
typedef char *(*lwip_tty_input_fn)(void)
Application-supplied text input used for secrets such as an encrypted private-key password.
Return a writable, NUL-terminated buffer that remains valid until the invoking lwIP operation returns; lwIP wipes its password bytes immediately after use. Return NULL to cancel/fail.
-
typedef void (*lwip_netif_service_cb)(struct netif *netif, const lwip_netif_service_event_t *ev, void *arg)
Enums
-
enum lwip_error_t
API result codes.
Values:
-
enumerator LWIP_OK
-
enumerator LWIP_ERR_ARG
NULL / out-of-range argument.
-
enumerator LWIP_ERR_STATE
called in wrong lifecycle state
-
enumerator LWIP_ERR_MEM
allocation failed
-
enumerator LWIP_ERR_NETIF
no netif available / not up
-
enumerator LWIP_ERR_DNS
DNS resolution failed / unavailable.
-
enumerator LWIP_ERR_CONNECT
connect() failed at transport layer
-
enumerator LWIP_ERR_PROTO
unsupported protocol for this op
-
enumerator LWIP_ERR_CLOSED
peer has closed (or local close pending)
-
enumerator LWIP_ERR_INTERNAL
lwIP returned an unexpected err_t
-
enumerator LWIP_ERR_SERVICES
required network services (DHCP/DNS/SNTP) not yet ready
-
enumerator LWIP_OK
-
enum lwip_socket_type_t
Transport selector for lwip_socket_create.
Values:
-
enumerator LWIP_SOCKET_TCP
raw TCP via tcp_*
-
enumerator LWIP_SOCKET_UDP
UDP via udp_*.
-
enumerator LWIP_SOCKET_ALTCP
altcp (default TCP allocator)
-
enumerator LWIP_SOCKET_ALTCP_TLS
altcp wrapped in TLS 1.3 (altcp_tls_ce)
-
enumerator LWIP_SOCKET_ALTCP_WS
WebSocket over plain TCP (RFC 6455).
-
enumerator LWIP_SOCKET_ALTCP_WSS
WebSocket over TLS (WSS).
-
enumerator LWIP_SOCKET_TCP
-
enum lwip_socket_bind_descriptor_t
Which netif a socket attaches to at create().
Values:
-
enumerator LWIP_NETIF_ANY
first usable netif (loopback or external)
-
enumerator LWIP_NETIF_LOOP
loopback only
-
enumerator LWIP_NETIF_EXT
external Ethernet only
-
enumerator LWIP_NETIF_ANY
-
enum lwip_status_t
Socket lifecycle status.
Poll via socket->status or STATE_CHANGE events.
Values:
-
enumerator LWIP_STATUS_INIT
handle created, not connecting yet
-
enumerator LWIP_STATUS_WAITING_SERVICES
waiting for DHCP/DNS/SNTP before connect
-
enumerator LWIP_STATUS_RESOLVING
DNS lookup in flight.
-
enumerator LWIP_STATUS_CONNECTING
TCP / TLS handshake in flight.
-
enumerator LWIP_STATUS_CONNECTED
ready for write/read
-
enumerator LWIP_STATUS_CLOSING
local shutdown / close issued
-
enumerator LWIP_STATUS_CLOSED
peer sent FIN, clean close
-
enumerator LWIP_STATUS_RESET
peer sent RST, connection immediately gone
-
enumerator LWIP_STATUS_ERROR
stack error (timeout, OOM, abort)
-
enumerator LWIP_STATUS_INIT
-
enum lwip_socket_event_type_t
Socket event types delivered to the event callback.
ERROR is always delivered if a callback is registered, regardless of flags. For STATE_CHANGE, ev_data is lwip_socket_state_data_t* (previous + current status). For IO, ev_data is lwip_socket_io_data_t*. For ERROR, ev_data is lwip_socket_error_data_t* with the full component/operation/raw breakdown. All ev_data pointers are valid only for the duration of the callback.
Values:
-
enumerator LWIP_SOCKET_EV_ERROR
-
enumerator LWIP_SOCKET_EV_STATE_CHANGE
-
enumerator LWIP_SOCKET_EV_IO
-
enumerator LWIP_SOCKET_EV_ERROR
-
enum lwip_socket_io_flags_t
IO event flags within lwip_socket_io_data_t.flags.
Values:
-
enumerator LWIP_SOCKET_IO_READABLE
data in ring; call lwip_socket_read
-
enumerator LWIP_SOCKET_IO_WRITABLE
peer ACKed sent data
-
enumerator LWIP_SOCKET_IO_POLL
periodic poll tick
-
enumerator LWIP_SOCKET_IO_READABLE
-
enum lwip_socket_error_component_t
Error component — which subsystem reported the error.
Values:
-
enumerator LWIP_SOCKET_ERR_COMP_SOCKET
-
enumerator LWIP_SOCKET_ERR_COMP_NETIF
-
enumerator LWIP_SOCKET_ERR_COMP_SERVICES
-
enumerator LWIP_SOCKET_ERR_COMP_DNS
-
enumerator LWIP_SOCKET_ERR_COMP_TCP
-
enumerator LWIP_SOCKET_ERR_COMP_UDP
-
enumerator LWIP_SOCKET_ERR_COMP_ALTCP
-
enumerator LWIP_SOCKET_ERR_COMP_TLS
-
enumerator LWIP_SOCKET_ERR_COMP_MEM
-
enumerator LWIP_SOCKET_ERR_COMP_SOCKET
-
enum lwip_socket_error_operation_t
Error operation — what was being attempted when the error occurred.
Values:
-
enumerator LWIP_SOCKET_ERR_OP_NONE
-
enumerator LWIP_SOCKET_ERR_OP_CREATE
-
enumerator LWIP_SOCKET_ERR_OP_CONNECT
-
enumerator LWIP_SOCKET_ERR_OP_DNS_LOOKUP
-
enumerator LWIP_SOCKET_ERR_OP_RECV
-
enumerator LWIP_SOCKET_ERR_OP_SEND
-
enumerator LWIP_SOCKET_ERR_OP_WRITE
-
enumerator LWIP_SOCKET_ERR_OP_CLOSE
-
enumerator LWIP_SOCKET_ERR_OP_SHUTDOWN
-
enumerator LWIP_SOCKET_ERR_OP_TLS_INIT
-
enumerator LWIP_SOCKET_ERR_OP_TLS_CONFIG
-
enumerator LWIP_SOCKET_ERR_OP_ALLOC
-
enumerator LWIP_SOCKET_ERR_OP_NONE
Functions
-
uint8_t lwip_start_last_error(void)
-
const char *lwip_version_string(void)
Returns the NUL-terminated lwIP-CE release version string.
-
void lwip_stop(void)
-
void lwip_set_tty(lwip_tty_input_fn input)
Install the application’s secret-input callback, or NULL to remove it.
lwIP provides no built-in terminal or UI. Operations that need input fail closed when no callback is installed or the callback returns NULL. The callback is single-use and is removed before lwIP invokes it; lwip_stop() also removes an unused callback.
-
bool lwip_network_up(void)
-
void lwip_service_events(void)
-
uint32_t lwip_now_ms(void)
-
bool lwip_tls_rng_wait_for_ready(uint16_t security_strength, uint32_t timeout_ms)
-
bool lwip_default_netif_info(lwip_netif_info_t *info)
-
lwip_error_t lwip_request_services(uint8_t flags, uint32_t timeout_ms)
-
lwip_error_t lwip_netif_request_services(struct netif *netif, uint8_t flags, uint32_t timeout_ms, lwip_netif_service_cb cb, void *cb_data)
-
bool lwip_are_services_ready(struct netif *netif, uint8_t flags)
Returns true iff every service bit set in
flagsis currently up onnetif(NULL = default netif).Pure synchronous poll — no side effects, no timer involvement. Useful as the main-loop readiness gate after calling lwip_netif_request_services().
-
struct lwip_socket *lwip_socket_create(lwip_socket_type_t type, lwip_socket_bind_descriptor_t bind, const lwip_socket_addrinfo_t *addrinfo, uint32_t timeout_ms)
Create a socket handle.
Non-blocking: returns immediately after binding the netif preference and kicking DHCP/static-IP. Readiness is awaited asynchronously by lwip_socket_connect.
- Parameters:
type – Transport selector (lwip_socket_type_t).
bind – Netif preference (lwip_socket_bind_descriptor_t).
addrinfo – NULL for DHCP; non-NULL for static IPv4.
timeout_ms – Inactivity watchdog window (ms) applied across all socket states — connect, handshake, and data transfer. 0 = no inactivity timeout (app manages lifetime).
- Returns:
Heap-allocated socket handle, or NULL on hard failure (OOM or invalid arguments).
-
struct lwip_socket *lwip_socket_create_ex(lwip_socket_type_t type, lwip_socket_bind_descriptor_t bind, const lwip_socket_addrinfo_t *addrinfo, uint32_t timeout_ms, size_t rx_ring_max)
Like lwip_socket_create but with an explicit RX ring maximum.
rx_ring_max == 0 uses LWIP_SOCKET_RX_RING_MAX_SIZE.
-
lwip_error_t lwip_socket_destroy(struct lwip_socket *socket)
-
lwip_error_t lwip_socket_connect(struct lwip_socket *socket, const char *host, uint16_t port)
-
lwip_error_t lwip_socket_listen(struct lwip_socket *socket, uint16_t port)
Bind a TCP socket to a local port and begin listening for connections.
Only valid on a LWIP_SOCKET_TCP socket in LWIP_STATUS_INIT state. After this call the socket is a passive listener; do not call lwip_socket_connect() on it. Accepted peers arrive via lwip_socket_accept().
- Parameters:
socket – Caller-created TCP socket handle.
port – Local port number (host byte order).
- Returns:
LWIP_OK on success, LWIP_ERR_STATE / LWIP_ERR_PROTO / LWIP_ERR_MEM on failure.
-
struct lwip_socket *lwip_socket_accept(struct lwip_socket *socket)
Dequeue one accepted peer socket from a listening socket.
Non-blocking: returns NULL if no peer is ready yet. On success returns a heap-allocated socket in LWIP_STATUS_CONNECTED state; the caller owns it and must call lwip_socket_destroy() when done.
- Parameters:
socket – Listening socket (must have called lwip_socket_listen()).
- Returns:
Heap-allocated peer socket, or NULL if queue is empty.
-
void lwip_socket_on_event(struct lwip_socket *socket, uint8_t event_flags, lwip_socket_event_cb cb, void *arg)
Register the single event callback.
flags — bitwise OR of LWIP_SOCKET_EVENTF_* to subscribe to; ERROR is always delivered regardless. cb — callback: void cb(sock, type, ev_data, arg) arg — user pointer passed as the last argument to cb.
Call before lwip_socket_connect. Only one callback is supported per socket; calling again replaces the previous registration.
-
bool lwip_socket_is_active(const struct lwip_socket *socket)
True while the socket is in a pre-terminal lifecycle state (INIT / WAITING / RESOLVING / CONNECTING / CONNECTED / CLOSING).
Returns false once the socket reaches CLOSED, RESET, or ERROR — use this as the main-loop exit condition.
-
lwip_error_t lwip_socket_set_timeout(struct lwip_socket *socket, uint32_t timeout_ms)
Set (or update) the socket’s timeout window.
Applies to all socket states — service wait, connect/handshake, and data transfer. The deadline is extended by any inbound or outbound wire activity, so a socket making progress never times out. 0 = disable the timeout.
-
lwip_error_t lwip_socket_write(struct lwip_socket *socket, const uint8_t *buf, size_t len)
Write one transport chunk.
len must fit in lwIP’s 16-bit pbuf/TCP length fields; values above UINT16_MAX fail with LWIP_ERR_ARG.
-
size_t lwip_socket_available(const struct lwip_socket *socket)
-
size_t lwip_socket_read(struct lwip_socket *socket, uint8_t *buf, size_t len)
Read up to len bytes from the socket ring.
Returns bytes actually read (clamped to available); never blocks.
-
lwip_status_t lwip_socket_status(const struct lwip_socket *socket)
-
lwip_error_t lwip_socket_last_error(const struct lwip_socket *socket)
-
lwip_error_t lwip_socket_shutdown(struct lwip_socket *socket)
-
lwip_error_t lwip_socket_close(struct lwip_socket *socket)
-
lwip_error_t lwip_socket_abort(struct lwip_socket *socket)
-
lwip_error_t lwip_socket_resize_rx_max(struct lwip_socket *socket, size_t new_max)
Resize the socket’s RX ring ceiling immediately (grow or shrink); the initial size set at socket creation is never changed by this call.
Data already in the ring is preserved — this fails only if there isn’t enough heap to grow, or there’s more data in the ring than the new max could hold when shrinking. Safe to call at any time, with any amount of data already buffered.
-
lwip_error_t lwip_socket_set_ws_config(struct lwip_socket *socket, const char *path, const char *subprotocol)
Set the WebSocket path and optional subprotocol for a WS/WSS socket.
Must be called after lwip_socket_create() and before lwip_socket_connect(). The strings are copied; the caller does not need to keep them alive. The host field is filled in automatically at connect time.
-
lwip_error_t lwip_socket_set_tls_cert(struct lwip_socket *socket, const char *privkey_appvar, const char *chain_appvar)
Configure an LWIP_SOCKET_ALTCP_TLS socket with a local certificate identity.
Must be called after lwip_socket_create() and before connect or listen. connect() presents it when the server requests mutual TLS; listen() uses it as the TLS server identity. Certificate configuration takes precedence over PSK fields if both were set.
- Parameters:
socket – ALTCP_TLS socket handle in LWIP_STATUS_INIT state.
privkey_appvar – Name of the on-calc appvar holding the PEM EC private key (≤8 chars).
chain_appvar – Name of the on-calc appvar holding the PEM cert chain (≤8 chars).
- Returns:
LWIP_OK, LWIP_ERR_ARG (wrong type/NULL/name too long), or LWIP_ERR_STATE.
-
lwip_error_t lwip_socket_set_tls_psk(struct lwip_socket *socket, const uint8_t psk[32], const uint8_t *identity, size_t identity_len)
Configure an LWIP_SOCKET_ALTCP_TLS socket for external PSK mode.
Must be called after lwip_socket_create() and before lwip_socket_connect() or lwip_socket_listen(). Connect uses a PSK client configuration; listen uses a PSK server configuration unless certificate AppVars were set.
- Parameters:
socket – ALTCP_TLS socket handle in LWIP_STATUS_INIT state.
psk – 32-byte pre-shared key.
identity – PSK identity bytes (label).
identity_len – Length of identity in bytes (1 to TLS_PSK_IDENTITY_MAX_LEN).
- Returns:
LWIP_OK, LWIP_ERR_ARG (wrong type/bad params), or LWIP_ERR_STATE.
-
bool lwip_start_with_crt(void *malloc_fn, void *free_fn, void *realloc_fn)
-
char *lwip_get_start_errstring(void)
-
uint8_t lwip_get_start_errno(void)
-
bool lwip_is_newer(void)
-
struct lwip_socket_addrinfo_t
- #include <lwip.h>
Optional static IPv4 configuration.
Pass NULL for DHCP.
-
struct lwip_socket_error_data_t
- #include <lwip.h>
ev_data for LWIP_SOCKET_EV_ERROR events.
Public Members
-
uint16_t component
-
uint16_t operation
-
int raw_error
raw err_t / module code
-
lwip_error_t err
mapped app-facing result
-
lwip_status_t status
socket status at time of error
-
uint16_t component
-
struct lwip_socket_state_data_t
- #include <lwip.h>
ev_data for LWIP_SOCKET_EV_STATE_CHANGE events.
-
struct lwip_socket_io_data_t
- #include <lwip.h>
ev_data for LWIP_SOCKET_EV_IO events.
Public Members
-
uint8_t flags
lwip_socket_io_flags_t bitmap
-
size_t readable
bytes in ring for lwip_socket_read
-
uint16_t written
bytes peer ACKed (WRITABLE flag set)
-
uint8_t flags
-
struct lwip_netif_service_event_t
- #include <lwip.h>
Event payload delivered to lwip_netif_service_cb on each per-service transition.
The callback fires once per service as it becomes ready, fails, or times out — never batched.
service_id — the single service that just fired (LWIP_SOCKET_SVC_*) status — UP / FAILED / TIMEOUT for that service ready_bitmap — bitmask of ALL services currently up on this netif (same bits as LWIP_SOCKET_SVC_*; useful to check “are all the services I care about up?” inline)
-
struct lwip_netif_info_t
- #include <lwip.h>
Snapshot of the default lwIP netif.
Connection readiness
lwip_socket_connect() waits asynchronously for a matching interface,
administrative up state, link, and usable address. DHCP is required for dynamic
external sockets, DNS for hostnames, and SNTP for TLS/WSS. Static sockets do not
start DHCP; numeric destinations do not require DNS. Loopback sockets require
no external services.
lwIP extended netif callbacks signal registration, link/address changes, and
removal. The socket layer processes these signals after USB events and lwIP
timeouts, outside the netif callback. A 100 ms dispatcher also checks service
completion and connection deadlines. Applications must keep calling
lwip_service_events() while a connection is waiting; the timer does not run
independently of this NO_SYS event loop.