Message in the OOCSI system

OOCSI is built on messages. All data in the OOCSI system is packaged conveniently into messages. Here you can find out all about sending and receiving messages in the system, from one-to-one communication to send-receive sequences and braodcasting to a whole group of OOCSI clients.

What’s in a message

Message contain standard data items like the sender, recipient, timestamp, and channel, and then variable data items that form the “payload”, the actual content of a message. While the standard items are filled in and handled by the platform, the variable data items are completely left to the user. You can choose to transmit very simple data, like yes/no (true/false) boolean values, numbers or text strings. You can also send composite data objects that contain lists of similar items or collections of diverse data.

Keys and values

Every piece of data in a message has a key, a name, and then the value, the actual data. We use keys in OOCSI messages to make clear what the transmitted data is about. If a client is sending 145 the recipient should immediately know that this is, for instance, a color component value or a distance measurement. The key would in this case say “color_R” for the value of the red color component, or “distance_mm” for a distance value with the unit millimeter. Naming keys and adding units and other meaning is completely left to the user, but we have found that being consistent about transmitted data helps enormously in creating systems with OOCSI.

Keys and values always come in pairs and you need the key to extract the value (for the key) from the message. If you don’t know the key, all client libraries have a way to list all keys in a message. There is not really more to understand about messages: sender and recipient are given, the message has a timestamp when it was processed by the server or broker, and then there are key-value pairs that contain the actual data.

Message features

Sending and receiving of messages is the basic interface for OOCSI. All clients support this functionality and that makes a message also a great interface for higher-level features that the server adds on top of the basic communication.

Delayed messages

The message feature is the message delay, which allows to delay the dispatch of a message by n seconds. This means that a client sends a message with the _DELAY attribute to the server, the server temporarily stores the message and sends it out after the delay has passed. You can delay any message by adding the _DELAY key with a number of seconds as the value. See the two examples in Java and Python below:

// example for delaying a message in Java/Processing
oocsi.channel("some_channel").data("some data", true).data("_DELAY", 30).submit();

Here we create a message to the channel some_channel and add a piece of data some data plus the key _DELAY and the number of seconds that the message should be delayed on the server. For example, if you want to delay a message for one hour, you would use 3600 or a day with 86400. The Python example is very similar, with the same result.

# example for delaying a message in Python
oocsi.send("some_channel", { "some data": True, "_DELAY": 30 })

What could you do with this? You could hand over data to another client on the channel that only becomes active at night. Or you could use the server to temporarily store a message for a day, and pick it up again tomorrow. You could use this feature for a timeout or reminder, be creative!

Retained messages

Another message feature is about retaining messages. This means that a message is kept on the server (in a channel) and it is sent to all clients that connect to the channel – until a timeout passes. You can think of this as “pinning” a message to a channel, which is useful for clients on embedded platforms that go into “deep sleep” most of the time to save battery. Here is how you do it:

# example for retaining a message in Python
oocsi.send("some_channel", { "some data": True, "_RETAIN": 600 })

In this example, we “pin” the meesage to the channel some_channel until the timeout of 600 seconds, 10 minutes, has passed. Similar to the delayed message feature, you can use really long timeouts, up to 7 days.