JavaScript OOCSI Client

The OOCSI JavaScript client connects to an OOCSI server over WebSockets (default endpoint /ws on port 9000). It enables interactive web applications, dashboards, mobile webviews, and Node.js services to exchange data in real time with hardware prototypes, Python scripts, and Processing sketches.

Setup & Installation

In Web Browsers

Include the client library directly in your HTML <head> or <body>:

<!-- Hosted directly from your OOCSI-web server -->
<script src="http://localhost:9000/assets/js/oocsi-web.min.js"></script>

Or download oocsi-web.js directly from the oocsi-web GitHub repository.

In Node.js

Install the package via npm:

npm install oocsi

Then require it in your script:

const OOCSI = require('oocsi');

Connecting to OOCSI

To connect, call OOCSI.connect() with the WebSocket URL and your desired client handle.

Tip: Include #### in your client name. The server will replace these hash marks with random numbers, ensuring your client never suffers a name collision when connecting or refreshing the page.

// Connect to local or remote OOCSI server
// Format: ws://<host>:<port>/ws (or wss:// for HTTPS domains)
OOCSI.connect("ws://localhost:9000/ws", "web_dashboard_####", function() {
    console.log("Connected to OOCSI server!");
});

Important (HTTPS / WSS): If your web application is hosted on an HTTPS domain (e.g. https://myproject.com), modern browsers block insecure WebSocket connections (ws://). You must use wss:// (secure WebSocket) when connecting from an HTTPS page.

Sending Messages

Use OOCSI.send() to dispatch JSON data objects to channels or individual clients:

// Send data to a channel
OOCSI.send("livingroom_lights", {
    power: true,
    brightness: 80,
    color: "#00FFCC"
});

// Send a direct message to a specific client
OOCSI.send("display_device_1", {
    notification: "Download completed"
});

Receiving Messages

Use OOCSI.subscribe() to join a channel and register an event callback function:

OOCSI.subscribe("livingroom_lights", function(msg) {
    console.log("Sender:", msg.sender);
    console.log("Timestamp:", msg.timestamp);
    console.log("Data payload:", msg.data);

    if (msg.data.power !== undefined) {
        updateUI(msg.data.power, msg.data.brightness);
    }
});

To leave a channel:

OOCSI.unsubscribe("livingroom_lights");

OOCSI Variables (State Synchronization)

OOCSI variables allow multiple clients to share a synchronized state across the network automatically.

// Create or link a synchronized variable on channel 'settings', with a 200ms throttle
let volume = OOCSI.variable("settings", "volume", 200);

// Read current value
console.log("Current volume:", volume());

// Set value (automatically broadcasts the new value to all clients subscribing to this variable)
volume(75);

Call-Response (RPC Services)

Registering a Responder (Service Provider)

OOCSI.register("calculator", function(data, response) {
    let a = data.a || 0;
    let b = data.b || 0;
    response.result = a + b;
});

Calling a Service (Client)

// Call 'calculator' with payload, 2000ms timeout, and reply callback
OOCSI.call("calculator", { a: 15, b: 27 }, 2000, function(result) {
    console.log("Sum result:", result.result); // 42
});

Complete Browser Example

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>OOCSI Web Client Demo</title>
    <script src="http://localhost:9000/assets/js/oocsi-web.min.js"></script>
</head>
<body>
    <h1>OOCSI Live Controller</h1>
    <button id="toggleBtn">Toggle Light</button>
    <p id="status">Status: Waiting...</p>

    <script>
        let isPowerOn = false;

        // Connect with randomized handle
        OOCSI.connect("ws://localhost:9000/ws", "browser_ui_####", function() {
            document.getElementById("status").textContent = "Status: Connected";

            // Subscribe to status channel
            OOCSI.subscribe("room_controls", function(msg) {
                if (msg.data.power !== undefined) {
                    isPowerOn = msg.data.power;
                    document.getElementById("status").textContent = "Power: " + (isPowerOn ? "ON" : "OFF");
                }
            });
        });

        document.getElementById("toggleBtn").addEventListener("click", function() {
            isPowerOn = !isPowerOn;
            OOCSI.send("room_controls", { power: isPowerOn, timestamp: Date.now() });
        });
    </script>
</body>
</html>