Clients and channels

Clients and channels are important to understand because that’s what you need when you send your first messages: there needs to be a recipient for a message. The following explains the client and channel concepts, and how you can use them to build your first OOCSI system.

Clients

Any OOCSI system is driven by its clients, so connected devices, scripts and software programs, that connect to OOCSI and transmit data to other clients. Without any clients, an OOCSI server would be idle. Every client in an OOCSI system needs to have a unique name. This is a textual identifier that exists only once in the system. This identifier can be used to send messages directly to a single client and no one else. Sending messages to clients is a one-to-one transmission; one client A sends a message to another client B.

Usually, OOCSI systems are not really crowded, so creating a unique identifier is easy. Just try a name for your device or script, append a number or try the trusted combination of firstname-favorite animal-favorite color-favorite drink. If a name is already taken, the connection to the OOCSI server will fail, just try another one.

Channels

Client-to-client communication has its limits: there are many cases where one client A would like to send data to multiple clients (B, C, D, and E). Of course, this could be done with multiple cloned messages from A to all individual recipients in the list, but that would be tedious and also create more network traffic than necessary. The smart alternative is to use a channel. If client A send the message to a channel X and all other clients B, C, D, and E subscribe to this channel X, then the OOCSI system will reliably deliver the message from A to the subscribed clients. This way of sending messages is also called “broadcasting”, similar to a radio station sending out the radio program to many listeners.

You can create as many channels as you need in the OOCSI system. Just ensure that the spelling is consistent: channels “kitchen” and “Kitchen” are two different channels in the OOCSI system, and this could be the reason that messages (to “Kitchen”) are not received by clients subscribing to “kitchen”.

Password-protected channels

sequenceDiagram
    autonumber
    actor Alice as Client A (Creator)
    participant Server as OOCSI Server
    actor Bob as Client B (Authorized)
    actor Eve as Client C (Unauthorized)

    Alice->>Server: subscribe secret_lab:pass123
    Server-->>Alice: Channel created with password 'pass123'

    Bob->>Server: subscribe secret_lab:pass123
    Server-->>Bob: Accepted (Authorized)

    Eve->>Server: subscribe secret_lab:wrongPass
    Server--xEve: Rejected (Invalid password, 0 messages forwarded)

    Alice->>Server: send secret_lab:pass123 {"msg": "classified"}
    Server->>Bob: Forward message {"msg": "classified"}

By default, OOCSI channels are public: any client connected to the server can discover and subscribe to them. When building prototypes that handle confidential data, private device interactions, or multi-team workshop environments, you can create a password-protected channel by appending a colon and a secret password to the channel name: channelName:password.

Key security and privacy characteristics:

• Creation and authorization: The first client to subscribe using channelName:password defines the password for that channel. Any other client wishing to join must provide the identical password.
• Automatic rejection: Subscriptions without a password or with an invalid password are automatically rejected by the server; the unauthorized client will receive no messages from the channel.
• Hidden from discovery: Password-protected channels are marked as private and do not appear in the server’s public channel directory (the channels command).
• Presence shielding: To prevent eavesdropping on channel membership or client handles, presence events (join, leave, timeout) are suppressed for private channels and private clients.
• Querying private channel status: If you need to query subscriber information for a private channel, you can subscribe to channelName:password/?.

Subscribing to a password-protected channel

// Java / Processing
oocsi.subscribe("secret_lab:superSecret123", "handleSecretMessages");

# Python
oocsi.subscribe("secret_lab:superSecret123", handle_secret_messages)

// JavaScript (oocsi-web.js)
OOCSI.subscribe("secret_lab:superSecret123", (msg) => {
  console.log("Secret payload:", msg.data);
});

// ESP32 (Embedded C++ / Arduino)
oocsi.subscribe("secret_lab:superSecret123", handleSecretMessages);

Sending to a password-protected channel

When sending a message to a password-protected channel, address the message using the full token (including the password):

// Java / Processing
oocsi.channel("secret_lab:superSecret123").data("command", "unlock_door").submit();

# Python
oocsi.send("secret_lab:superSecret123", { "command": "unlock_door" })

// JavaScript (oocsi-web.js)
OOCSI.send("secret_lab:superSecret123", { command: "unlock_door" });

// ESP32 (Embedded C++ / Arduino)
oocsi.newMessage("secret_lab:superSecret123");
oocsi.addString("command", "unlock_door");
oocsi.sendMessage();

Channel presence

stateDiagram-v2
    [*] --> Closed: Initial State
    Closed --> Created: First Client Subscribes
    Created --> Active: Channel Online
    
    state Active {
        [*] --> Idle
        Idle --> ClientJoined: Client Subscribes
        ClientJoined --> Idle: Emit join event
        Idle --> ClientLeft: Client Unsubscribes / quit
        ClientLeft --> Idle: Emit leave event
        Idle --> Timeout: Inactive for 120s
        Timeout --> Idle: Emit timeout event
        Idle --> Refresh: Periodic Roster Sweep
        Refresh --> Idle: Emit refresh list
    }

    Active --> Closed: Last Client Leaves
    Closed --> [*]

The more devices you design with, the more important it becomes to know which devices are currently online and able to respond to commands. Likewise, it is critical to detect when an interactive device drops off the network. OOCSI includes a built-in channel presence tracking service.

An OOCSI client can subscribe to presence updates for any channel by prefixing the channel name with presence(...):

// Java / Processing
oocsi.subscribe("presence(meeting_room)", "handlePresence");

# Python
oocsi.subscribe("presence(meeting_room)", handle_presence)

// JavaScript (oocsi-web.js)
OOCSI.subscribe("presence(meeting_room)", (msg) => {
  console.log("Presence event:", msg.data);
});

// ESP32 (Embedded C++ / Arduino)
oocsi.subscribe("presence(meeting_room)", handlePresence);

Presence events and payloads

Presence messages contain a channel attribute indicating the tracked channel, accompanied by an action key:

1. join: A client has subscribed to the channel.

   { "channel": "meeting_room", "client": "meeting_room", "join": "display_device_1" }
   

2. leave: A client has cleanly unsubscribed from the channel.

   { "channel": "meeting_room", "client": "meeting_room", "leave": "display_device_1" }
   

3. timeout: A client stopped responding or abruptly lost its network connection (triggered after 120 seconds of inactivity).

   { "channel": "meeting_room", "client": "meeting_room", "timeout": "display_device_1" }
   

4. created / closed: The channel was opened (first subscriber joined) or closed (last subscriber departed).

   { "channel": "meeting_room", "created": "" }
   

5. refresh: Periodically broadcasts the complete list of active client handles subscribed to the channel:

   { "channel": "meeting_room", "refresh": ["display_device_1", "sensor_node_a"] }
   

Subscribing to channel status (/?)

You can also subscribe to channelName/? to receive periodic status reports and subscriber lists broadcast by the server. For private channels, use channelName:password/?.