This page was generated from the source of RoboHub. Edit the source, not this page.
Networking
A program that speaks MQTT, HTTP or a websocket should not carry a vendor's
networking stack in its source. robohub-common declares the contract such a
program is written against — robohub/net.h — and each platform implements it.
A protocol built on this runs on a Pico W or a Linux host without a line
changed, and still links on a board that has no network port.
The contract
/* Interface */
RoboHubError robohub_net_wifi_connect(const RoboHubWiFiConfig* config);
RoboHubError robohub_net_wifi_disconnect(void);
RoboHubNetStatus robohub_net_status(void);
RoboHubError robohub_net_ip(char* out_ip, rh_size max_len);
/* Sockets */
RoboHubSocket robohub_socket_create(RoboHubSocketType type);
RoboHubError robohub_socket_connect(RoboHubSocket socket, const char* host, rh_u16 port);
int robohub_socket_send(RoboHubSocket socket, const void* data, rh_size len);
int robohub_socket_recv(RoboHubSocket socket, void* data, rh_size len, rh_u32 timeout_ms);
void robohub_socket_close(RoboHubSocket socket);
Every function has a weak default in robohub-common. A board with no network
links and runs: the default answers ROBOHUB_ERR_NOT_SUPPORTED, returns a null
socket, or reports a disconnected interface. A platform that implements the
contract defines these functions strongly and the linker prefers them — the same
mechanism the OSAL uses to choose an RTOS.
recv takes a timeout and must not block longer than it says. ROBOHUB_SOCKET_TIMEOUT
is returned when the time passed with nothing to read — a poll that came up empty,
not an error. A platform implements the wait as a non-blocking poll between OSAL
sleeps, so a network read never starves the control loop sharing its core.
How each platform supplies it
| Capability | Pico W (pico_net.c) | Linux (linux_net.c) | ESP32 |
|---|---|---|---|
| Interface control | cyw43_arch_wifi_connect_timeout_ms | none: the host is already on its network, and wifi_connect succeeds | not written yet (esp_wifi + esp_event) |
| IP stack | LwIP via the Pico SDK | the kernel's | LwIP via esp_netif |
| Sockets | LwIP RAW API (tcp/udp pcbs) | BSD sockets, non-blocking, the timeout as a select | the LwIP BSD wrapper |
| Name resolution | numeric IPv4 (ip4addr_aton) | numeric IPv4 (inet_pton) | — |
The Pico W column is not the BSD layer because its arch —
pico_cyw43_arch_lwip_threadsafe_background — runs LwIP bare-metal
(NO_SYS=1), and the BSD socket and netconn layers need an OS to block in. The
platform's pico_net.c therefore answers the socket contract over the RAW API,
with a single-producer/single-consumer ring the lwIP callbacks fill and a caller
drains; that is also what makes a receive the non-blocking poll the contract
asks for. Resolving a name would need dns_gethostbyname's asynchronous
callback, so connect takes a numeric address, as the POSIX reference does.
The POSIX test is the reference: robohub-common/tests/test_net_posix.c implements the
contract over <sys/socket.h> and drives it against a loopback socket, so the
contract itself is exercised without a board. A platform port follows the same
shape with its own stack beneath.
Enabling it
A project selects the contract with RH_NET; a platform's build then compiles
its implementation. A project that never opens a socket does not select it, and
pays nothing.