WebSocket API Reference

Real-time event streaming for responsive applications

Table of contents

1. Connection
2. Message Format
3. Event Types
4. Example Payloads
   1. Node Added to Cluster
   2. GPIO State Changed

---

The Pi-Controller provides a WebSocket endpoint for clients (like the Web UI) to receive real-time event notifications from the control plane. This allows for a dynamic and responsive user experience without the need for constant polling.

Connection

Clients can establish a WebSocket connection to the /ws endpoint of the Pi-Controller server.

Message Format

All messages sent from the server to the client are JSON objects with a consistent structure:

• type (string): A dot-separated string indicating the event category and action (e.g., cluster.node.added).
• timestamp (string): An ISO 8601 timestamp indicating when the event occurred.
• data (object): A JSON object containing the payload specific to the event type.

---

Event Types

The following are examples of events that the system can emit.

Event Type	Description	Data Payload Example
node.discovered	A new Raspberry Pi has been discovered on the network.	{ "node_id": "pi-new", "ip_address": "192.168.1.110" }
node.status.changed	The status of a node has changed.	{ "node_id": "pi-worker-01", "status": "ready" }
cluster.node.added	A node has been successfully added to a cluster.	{ "cluster_id": "cluster-1", "node_id": "pi-worker-03" }
cluster.node.removed	A node has been removed from a cluster.	{ "cluster_id": "cluster-1", "node_id": "pi-worker-02" }
gpio.state.changed	The state of a GPIO resource has been updated.	{ "resource": "led-1", "pin": 18, "state": "high" }
system.log.created	A new system-level log entry has been generated.	{ "level": "error", "message": "Failed to provision node" }

Example Payloads

Node Added to Cluster

This event is sent when the provisioner successfully joins a new node to a K3s cluster.

{
    "type": "cluster.node.added",
    "timestamp": "2025-01-15T10:30:00Z",
    "cluster_id": "cluster-1",
    "data": {
        "node_id": "pi-worker-03",
        "ip_address": "192.168.1.103",
        "status": "provisioning"
    }
}

GPIO State Changed

This event is sent when a GPIOPin CRD is updated, and the node agent successfully changes the physical pin’s state.

{
    "type": "gpio.state.changed",
    "timestamp": "2025-01-15T10:30:15Z",
    "resource": "led-controller",
    "data": {
        "pin": 18,
        "state": "high",
        "pwm_duty": 75
    }
}