Softlab Relay Server - Official Documentation

Welcome to the Softlab Relay Server API! This platform provides ultra-low latency, bidirectional WebSocket communication designed specifically for remote hardware automation (e.g., controlling a Raspberry Pi via a PC/Bot).

1. Connection Details

All clients (both Commanders and Workers) connect to the same central endpoint. The server handles routing messages between clients based on their API keys and target IDs.

• Protocol: Secure WebSockets (wss://)
• Endpoint: wss://relay.softlab.ee/ws/connect/
• Data Format: JSON only

2. Authentication Handshake

Security is enforced at the connection level. You cannot send commands until you complete the authentication handshake.

Step 1: Connect & Authenticate

Immediately upon opening the WebSocket connection, the client must send an authentication payload. You can use either a Master API Key (for controllers/bots) or a Device Token (for hardware).

Option A: Master API Key (Requires sender ID)

{
  "auth_key": "YOUR_RAW_MASTER_KEY",
  "sender": "my_controller_id"
}

Option B: Device Token (ID is pre-assigned)

{
  "device_token": "YOUR_DEVICE_TOKEN"
}

Step 2: Await Confirmation

The server verifies the credentials and assigns the socket to a secure, isolated room.

{
  "status": "authenticated",
  "client_id": "my_controller_id"
}

Note: Once authenticated, you do not need to include credentials in subsequent messages.

Step 3: Constraints & Error Handling

The following are default limits. Administrators can increase these on a per-user basis (e.g., for enterprise customers or specialized hardware).

• Payload Limit: Default 100KB.
• Heartbeat: Sending {"action": "ping"} will return {"status": "pong"}.
• Rate Limiting: 10 auth attempts/min per IP, 100 messages/min per client (default).
• Offline Queue: Default 50 messages capacity and 24-hour TTL (customizable).
• 4000: Invalid JSON format sent.
• 4001: auth_key, device_token, or sender (for Master Keys) was missing.
• 4003: Invalid or revoked credentials.
• 4009: Message too big (>100KB).
• 4029: Rate limit exceeded (too many auth attempts).

3. The Messaging Contract

Once authenticated, clients can freely pass messages to one another. The relay acts as a blind switchboard—it looks at the target field and forwards the entire JSON payload to that specific client ID.

A. Offline Messaging

If a message is sent to a target that is offline, the server queues it (default capacity is 50 messages and 24-hour TTL, but this can be increased per user). These are delivered upon the target's next login with a "_offline_queued": true flag added to the payload.

B. Sending a Command (Commander ➔ Worker)

{
  "target": "mouse_pi",
  "sender": "tkinter_bot",
  "priority": "highest",
  "speed": 100,
  "subtasks": "Mx1920y1080 / C"
}

• target: (Required) The ID of the device you are sending this to.
• sender: The ID of the device sending the message (useful so the receiver knows who to reply to).
• Other fields: (priority, speed, subtasks) are custom payload data that the relay simply passes through.

4. Presence API (HTTP)

While most communication happens via WebSockets, you can check the real-time status of multiple devices via a standard HTTP GET request. This is primarily used by the dashboard but is available for any authenticated session.

• Endpoint: https://relay.softlab.ee/api/presence/
• Method: GET
• Params: devices=device_id1,device_id2

{
  "mouse_pi": "online",
  "sensor_pi": "offline"
}

5. Implementation Best Practices

• Non-Blocking Listeners: Always run your WebSocket listener (run_forever) in a dedicated thread or asynchronous loop.
• State Management: Maintain a boolean flag (e.g., is_authenticated = False) in your client.
• Keep-Alive: Send a {"action": "ping"} every 30-60 seconds to keep the connection active.
• Auto-Reconnection: Hardware deployed in the real world experiences internet drops. Wrap your connection logic in a try/except block.

6. Client Implementation Examples

Choose your preferred programming language to see a minimal implementation for both Commanders and Workers.

from relay_client import SoftlabRelayClient

def on_data(data):
    print(f"Message received: {data}")

# Commander Example
client = SoftlabRelayClient(
    auth_key="YOUR_MASTER_KEY",
    sender="my_pc",
    on_message=on_data
)
client.start()

# Send a message
client.send_message("mouse_pi", {"command": "move", "x": 100})

const WebSocket = require('ws');
const ws = new WebSocket('wss://relay.softlab.ee/ws/connect/');

ws.on('open', () => {
  // Authentication
  ws.send(JSON.stringify({
    auth_key: 'YOUR_MASTER_KEY',
    sender: 'node_controller'
  }));
});

ws.on('message', data => {
  console.log('Received:', JSON.parse(data));
});

import javax.websocket.*;
import java.net.URI;

@ClientEndpoint
public class RelayClient {
    @OnOpen
    public void onOpen(Session session) throws Exception {
        session.getBasicRemote().sendText("{\"auth_key\": \"YOUR_KEY\", \"sender\": \"java_app\"}");
    }

    @OnMessage
    public void onMessage(String message) {
        System.out.println("Received: " + message);
    }

    public static void main(String[] args) throws Exception {
        WebSocketContainer container = ContainerProvider.getWebSocketContainer();
        container.connectToServer(RelayClient.class, new URI("wss://relay.softlab.ee/ws/connect/"));
        while(true) Thread.sleep(1000);
    }
}

#include 
#include 

WebSocketsClient webSocket;

void onWebsocketEvent(WStype_t type, uint8_t * payload, size_t length) {
  if(type == WStype_CONNECTED) {
    webSocket.sendTXT("{\"device_token\": \"YOUR_DEVICE_TOKEN\"}");
  }
}

void setup() {
  webSocket.begin("relay.softlab.ee", 443, "/ws/connect/");
  webSocket.onEvent(onWebsocketEvent);
}