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

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).

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

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)

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
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

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
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
enum lwip_netif_service_status_t

Values:

enumerator LWIP_NETIF_SERVICE_UP
enumerator LWIP_NETIF_SERVICE_FAILED
enumerator LWIP_NETIF_SERVICE_TIMEOUT

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 flags is currently up on netif (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:
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)
struct netif *lwip_socket_get_netif(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.

Public Members

ip4_addr_t ip
ip4_addr_t netmask
ip4_addr_t gateway
struct lwip_socket_error_data_t
#include <lwip.h>

ev_data for LWIP_SOCKET_EV_ERROR events.

Public Members

uint16_t component

lwip_socket_error_component_t

uint16_t operation

lwip_socket_error_operation_t

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

struct lwip_socket_state_data_t
#include <lwip.h>

ev_data for LWIP_SOCKET_EV_STATE_CHANGE events.

Public Members

lwip_status_t previous
lwip_status_t current
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)

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)

Public Members

uint8_t service_id
lwip_netif_service_status_t status
uint8_t ready_bitmap
struct lwip_netif_info_t
#include <lwip.h>

Snapshot of the default lwIP netif.

Public Members

bool has_netif
bool up
bool dhcp_running
uint8_t dhcp_state
bool has_ipv4
bool has_ipv4_gateway
uint8_t ipv4_addr[4]
uint8_t ipv4_netmask[4]
uint8_t ipv4_gateway[4]

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.