Mar 10, 2025

Using Ioto WebSockets

WebSockets represent a critical protocol for modern IoT applications, enabling fast, efficient, real-time, bi-directional communication between devices and clients. This technology moves beyond traditional request-response paradigms of HTTP by maintaining persistent connections, dramatically improving communication efficiency, reducing latency, and simplifying real-time application architectures.

Ioto fully supports WebSockets for both client and server sides. It also supports Server-Sent Events (SSE) and HTTP/1.1 streaming.

Understanding WebSockets

WebSockets is a network communication protocol designed to facilitate full-duplex, real-time communication between a client and server over a single, long-lived TCP connection. Unlike traditional HTTP, where each interaction typically involves a separate request and response, WebSockets maintain a continuous connection, allowing instantaneous data transfer in both directions. This makes WebSockets particularly suitable for interactive IoT applications, live dashboards, real-time device monitoring, and immediate control scenarios. Conveniently, WebSocket connections can be established over normal HTTP connections and that works effectively with firewalls and existing network infrastructure.

Why Use WebSockets?

WebSockets are ideal for scenarios requiring low latency and real-time interactions, such as:

Real-time IoT device monitoring
Interactive web applications
Instant notifications and alerts
Real-time dashboards

WebSockets in Ioto

Embedthis Ioto provides comprehensive support for WebSockets, enabling easy integration for both client-side and server-side scenarios. Ioto’s WebSockets support includes:

Full duplex streaming: Enables continuous two-way communication for one or more connections.
Lightweight, efficient and high-performance implementation ideal for embedded devices
Simple APIs that are easy to implement and debug.
Easy Integration: Seamless integration within existing Ioto embedded applications.

Server WebSockets

Ioto can act as a WebSockets server, seamlessly integrating with its embedded web server component.

To respond to WebSocket requests, implement an Action handler using Ioto’s C API. The Action handler is invoked when a request is received that matches the given URL path.

webAddAction(host, "/chat", chatHandler);

static void chatHandler(Web *web) {
    webAsync(web, (WebSocketProc) onEvent, web);
    if (webWait(web) < 0) {
        webError(web, 400, "Cannot wait for WebSocket");
        return;
    }
}

Ioto will invoke your action routine when a request is received after validating the WebSocket connection.

Your action routine then calls webAsync to define the callback function to run when messages are received, and upon other connection events. Calling webWait will then block until the connection is closed. Other requests and fibers continue to run.

When an incoming WebSocket message is received, your onEvent callback will be invoked. This is where you can do your custom processing.

static void onEvent(WebSocket *ws, int event cchar *buf, ssize len)
{
    if (event == WS_EVENT_MESSAGE) {
        printf("Received message %s\n", buf);
    }
}

To send a message, use the webSocketSend API:

void onEvent(WebSocket *ws, int event, char *buf, ssize len, void *arg)
{
    webSocketSend(ws, "%s", "Response message");
}

Client WebSockets

To start a WebSocket client session, use the urlWebSocket API.

int status = urlWebSocket("wss://my.com/post", onEvent, NULL, NULL);

This API will block and service incoming and outgoing WebSocket messages until the connection is closed. While blocked, other Fibers will continue to run. The return status will be zero for an orderly close and a negative status for an abortive close.

The urlWebSocket API takes a callback function onEvent argument that is invoked to receive incoming WebSocket messages.

void onEvent(WebSocket *ws, int event char *buf, ssize len, void *arg)
{
    if (event == WS_EVENT_MESSAGE) {
        printf("Received %s\n", buf);
        webSocketSend(ws, "%s", "Response message");
    }
}

WebSockets with the Url Command

Ioto also provides a HTTP client test app called url. This can be used to issue test WebSocket requesets.

To initiate a WebSocket connection as a client:

url ws://localhost/chat

This opens a WebSocket connection to a WebSockets-enabled endpoint. You can then receive messages over this channel.

To send WebSockets test messages, use:

url --webSocketSize 1k ws://localhost/chat

Read about the Url Command in the man page.

Optimizations

WebSockets by default validates all messages to ensure the transmission of only valid UTF-8 strings. If you control both ends of the WebSocket communication channel, you can skip UTF validation and significantly optimize communications by setting the validateUTF option to false.

{
    web: {
        webSockets: {
            validateUTF: false
        }
    }
}

Conclusion

Embedthis Ioto provides efficient WebSocket support, enabling developers to build responsive, real-time embedded IoT applications. With Ioto’s streamlined architecture, integrating real-time functionality becomes straightforward, simplifying development tasks and improving device apps and the end-user experience.