Sending messages with the Roomware Socket Server

Posted on May 8, 2010


By Peter Kaptein

The Roomware Socket Server Message Protocol is a medium-weight protocol to send messages from one thing to another.

Medium weight?

Light weight messages are devoid of fluff. They are optimized to send data from “A” to “B” in the most compact form. Heavy weight messages contain a lot of extra meta-data. XML is an example of a heavy-weight message. The XML-structure itself is usually counting more bytes than the actual data it carries.

Medium weight messages are a compromise between the two. They can be read by humans and contain only a minimum of “irrelevant” data.

The basic setup

Each device that is connected to the Roomware Server communicates via a Mediator.

Roomware Socket Message Server

The Roomware Socket Message Server has one single purpose: to distribute messages with specific subjects from a Mediator to all subscribers.


Neither the Roomware Socket Message Server, nor the devices understand how to communicate with each other.

The role of the Mediator is to bridge that gap. It understands the device and it understands the Roomware Socket Server environment.

Events and Proxies

An Event in a device called “Something A” is translated by the Mediator into clear instructions and clear data. When it is received by a Proxy, the instructions and data are translated into something that can be used by “Something B” (represented by it’s own Mediator). About Proxies more later.

Types of messages

There are four types of messages:

  1. An Event – this is sent from a “Something” and pushed to anyone subscribed to the topic list of that message. An event does not expect an answer.
  2. A Request – A request is sent by a “Something” and pushed to anyone subscribed to the topic list of that message. A Request  does expect an answer.
  3. A Response – A Response is sent by a “Something” as a reply to a Request. A Request  does expect an answer.
  4. A message – A message follows the same pattern as a Request. Difference is that it can recieve an answer, but does not necessarely has to.

The Roomware Connector

Before you can do anything, you need to connect to a Roomware Server.

This is done via a Roomware Connector.

The Roomware Connector states:

  1. IP and Port – To which Roomware Server to connect (IP-address and Port Number)
  2. Sandbox – To which Sandbox the Roomware client should connect.
  3. Listeners – A list of the events you want to receive


One Roomware Server can host many different Application Clusters. Each Application Cluster (a collection of sensors, applications and devices interacting with each other) is a closed sandbox. The concept of Sandboxes is used to avoid “Event leaks”.


When a Roomware Message is sent, we expect there to be “people” listening. We define the listeners when opening the Roomware Connection. The Roomware Server separates the comma-separeted items and matches the items in the Message “broadcast to” list with the items in the “Listens to” list stated by the Roomware Connector. If both “listens to” and “broadcast to” contain for instance the word “door open event”, the message will be sent to the Roomware Client that created that connection.

Event leaks?

Event leaks occur when “Device A” is using the same event name as “Device B” for totally different type of data.

Event leaks between Application Clusters

Let us assume that “Application Cluster A” is monitoring your house and “Cluster B” the house of your neighbor. Based on the events in the clusters a tracking system is keeping tabs on all events. When event “toilet is flushed” is fired, you very likely want to keep this private.

Connecting to the Roomware Server

As stated: when you connect to the Roomware Server, you need three items of data:

  1. The IP-number and port number of your Roomware Server
  2. The Sandbox name of your specific Application Cluster
  3. The events you want to receive

A code-example

// Instatiate the object
var rC = new RoomwareConnector()

// Tell the connector where the server is running

// Set the sandbox name

// Tell the server which messages to send through

// connect to the Roomware Server

The Roomware message structure


The Roomware Message Header contains two items:

  1. “Broadcast to” – which is the “topic list” of that message.
  2. “Type” – the type of the message (Event, Request, Response, Message). By default the type is “Event” and the sender does not expect a reply.


The separator (not shown in the diagram) is an ASCII code: Chr(02) which – according to the ACII standard – indicates the “start of text”. Items are separated by a semi-colon.


The Roomware Message Body is anything to your liking. This can be XML, a comma-separated list or any standard you made up.

Just be careful it does not contain the Ascii 02 and Ascii 04 values.

Example 1: a Roomware Message containing XML

// Roomware Header
chr(02) // Separator
// Roomware message
      <device id="0f-00-1E-AE-F0" name="Paul de Wit"/>
      <device id="0f-BA-00-1E-A1" name="Joost van Dullem"/>
chr(04) // Terminator

Example 2: a Roomware Message containing a list with separators

// Roomware header
chr(02) // Separator
// Roomware message
deviceID=0f-00-1E-AE-F0,name=Paul de Wit;
deviceID=0f-BA-00-1E-A1,name=Joost van Dullem;
chr(04) // Terminator

Example 3: the short version of Example 2

// Roomware header
chr(02) // Separator
// Roomware message
0f-00-1E-AE-F0,Paul de Wit;0f-BA-00-1E-A1,Joost van Dullem;
chr(04) // Terminator

Code example

Will follow

Understanding Mediators, Proxies and Application Clusters

Application Clusters

A “Roomware Application” is actually a cluster of different “devices” and applications. Each of these devices and applications is capable of broadcasting messages and receiving messaged broadcasted by others.

Mediator Proxy or Remote Proxy

Each Mediator also has a Proxy. The Proxy is the virtual representation of the “Device” handled by the Mediator. So if anything changes at the side of the Mediator, the (Remote) Proxy will automatically change as well. This Proxy also reveals the API to the device it represents. So if you change a setting on the (Remote) Proxy, it will immediately update the Mediator and – via the Mediator – the real device.

Connected via Sockets and the Roomware Socket Server

The Mediator and the Remote Proxy are connected via Sockets. So any change happening on either side is immediately pushed to the other.

Real time system

This create a real time message system.

Many proxies, one mediator

The relationship between Remote Proxies and Mediator is a many to one. You can instantiate many Remote Proxies on many places, listening to one Mediator and also setting data on that one Mediator.

Why mediators and messages?
No intelligence in the Roomware Server

We want to have a scalable model without limits to it’s size or possible interconnections. To do this, all logic regarding the handling of instructions and data sent in a Roomware Message is handled OUTSIDE the Roomware Server.

“Mediator A” understands “Mediator B” and “Mediator B” understands “Mediator A”

When you write modules for the Roomware Application Cluster, you use Mediators. You either write these yourself, or use Mediators available.

A smart heating system

Mediator A: The temperature sensors: Lets say “Mediator A” is connected to a set of sensors, registering temperature in a room. This temperature is given in a number between zero and 1023.

Mediator B: The thermostat: “Mediator B” is connected to a thermostat, regulating the temperature in the room

Mediator C: The website to control the thermostat: “Mediator C” is connected to the user interface of a website, connecting to the Roomware Server using Sockets. With this interface the temperature can be read and the thermostat can be manipulated by a person.

Thermostat – using a Proxy of A: “Mediator B” uses a Proxy from “Mediator A”. The Proxy creates Proxy Objects for each sensor and makes that data available for the program running “Mediator B”. So when the temperature in the room changes, the software using “Mediator B” is capable of changing the settings for the heater.

Website – using a Proxy of A and B: The website uses a Proxy from “Mediator A” and “Mediator B”: each giving real time access to controls and to what is happening.

Website – manipulating Mediator B: the thermostat: When the user is logged in on the website, he or she gets a visual representation of the thermostat and the temperature, with the following options:

  1. Set the automatic temperature range for the thermostat – based on the readings. So when the temperature drops below a specific point on a specific sensor, the thermostat will react, or stay mute
  2. Override the temperature settings – and set a specific temperature for the thermostat. For instance – to heat-boost the room

System intelligence / smartness – “Mediator B”: “Mediator B” contains a rich set of features (exposed and reachable via the Mediator Proxy of “B”). So all the settings as stated above are handled by the software of “Mediator B”

Proxies and Remote Proxy Driven Systems

We described a Remote Proxy Driven system in the example above. In this system, the programmer creates two elements:

  1. The Mediator – reading the sensors, communicating with local systems, setting values on local items.
  2. The Remote Proxy or Mediator Proxy – representing the Mediator and the device the Mediator represents, offering a direct (remote) interface to the “Something” the Mediator represents

Handling Roomware Messages

The Mediator and the Remote Proxy are bound objects. Each knows exactly what messages to expect from the other and what to do with the content.

Remote Proxies

As stated before: the Proxy is the virtual representation of the “Device” handled by the Mediator. So if anything changes at the side of the Mediator, the (Remote) Proxy will automatically change as well. This Proxy also reveals the API to the device it represents. So if you change a setting on the (Remote) Proxy, it will immediately update the Mediator and – via the Mediator – the real device.

Abstract layer over the Roomware Message System to make life easier

As the Mediator and the Remote Proxy deal with the communication, the programmer can focus on the API made available via the Remote Proxy.

Instruction Driven Systems

Originally the Roomware Message System was designed to be an Instruction Driven system. And this is what it still is when you dissect the Remote Proxy and the Mediator.

Events and subscribers

Each event a device sends is received by any Roomware Connector subscribing to the event name.

Reading the message body – instructions

As a Roomware Message can contain anything, this includes instructions. How these instructions are shaped is between the Mediator and the application communicating to that Mediator:

  1. XML
  2. Comma-seperated
  3. Code dumps
  4. Anything you can come up with

Up to you

So it is up to you how you shape the instructions

Recommended to build Mediator Proxies

When you build a system, we recommend you to stick with the model of Mediators and Mediator Proxies. They form a closed system you can release to any programmer using your system and devices to easily build their own stuff in a clear and clean manner.