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”.

Channel presence

the more devices you want to design with, the more you need to know which devices are actually online at a given moment and can respond to messages or requests. Likewise, it can be important to know that a devices is not (anymore) subscribed to a channel. OOCSI has a special feature for these types of use-cases: channel presence. An OOCSI client can subscribe to presence information for a specific channel. It will receive messages about devices subscribing and unsubscribing / leaving the channel. Also there is a regular ping being sent, so device information on a channel can be kept up-to-date. Subscribing to presence information works like this:

oocsi.subscribe("presence(some_channel)", "presenceHandler");
//...

void presenceHandler(OOCSIEvent event) {
	// do something with the presence event
}

How do presence messages look like? Let’s say a new client webclient_1641637024636 subscribes to testchannel, the resulting presence message would be:

{
	"channel":"testchannel",
	"join":"webclient_1641637024636"
}

When the client unsubscribes from testchannel the presence message is:

{
	"channel":"testchannel",
	"leave":"webclient_1641637024636"
}

The channel attribute is always given and denotes the channel that presence tracking applies to. The second key provides the type of presence event and possibly indicates from which clients on the channel this event originats. We have seen the join and leave key above already. Other keys are created and closed (without clients names) that indicate that the channel was created (with the first subscriber) or closed (with the unsubscribe of the last subscriber). The refresh key with client name indicates that the client just pinged the server. This event will only raised once every 10 seconds at most. Finally, there is a timeout key that is generated when a client on the channel does not respond anymore to server pings.