How an OpenKontrol Gateway gets data to Xively/Cosm/Pachube

Note – this is my understanding of how this works, though I must be doing something right because it does work now and I can design LLAP sensors that go to Xively/Cosm/Pachube whatever it’s called these days. If you want to understand LLAP you should read the LLAP documentation first, and the technical documentation for the OKG.

Note 2 – My initial enthusiasm for third-party IoT services faded seriously when in the short lifetime of my project there were three name changes Pachube became Cosm which became Xively and everything was pointing towards Xively becoming a freemium paid-for service if it was going to be useful. I’ve taken all this in house using a cheap Raspberry Pi. In the end if you don’t pay for SaaS you’re going to be monetized one way or another, and you become a hostage to fortune.  The principle still stands – if you want a quick, easy win for a couple of months Xively or any of the other IoT providers are a great quick win!

However, I found it helped me no end to stand back from the detail a bit and get an overview of how the system works. In particular I only need one OKG in any location, it can handle all the sensors I will have. 1

How sensor data gets to from a low-powered serial LLAP device to COSM

One of the problems PIC based sensors have is they are low-powered, both in computing power and electrical power supply, so they can’t run the overhead of TCP/IP stacks and the like. In years gone by we used to have all sorts of different data networks – many were serial networks. We now use TCP/IP for everything where we can, so we aren’t used to a lot of different types of networks, but there’s a good reason here – TCP/IP is just to much overhead for these simple sensor systems. What we need is a simple serial network for the sensors, preferably like a bus network without having to manage contention. We then want some sort of gateway that will take the simple data, and convert the protocol to whatever suits our IoT provider of choice.

This is what things like the Ciseco OpenKontrol Gateway is designed to solve, by acting as a protocol converter mapping the LLAP messages to a suitable http request to COSM. I’m a big fan of the OKG – it does a lot at a reasonable price, and can make a standalone logger too. The journey of the data across the system is one of moving from simplicity to complexity

The simple end – a LLAP sensor

The PIC (or micro in a LLAP sensor) converts the data into a simple serial format. There’s not much processing power here, but 12 characters is within the capability of any PIC or Arduino. All LLAP messages start with a lower-case a, that never appears elsewhere in the packet. There is then a two-letter address field.

I then use a type field, because I expect to have several sensors at one address, say one sensing humidity and temperature. The type field uses four upper case characters 2field can be, and after that is the numeric value, padded with – characters at the end to get to 12 bytes.

So I have eg


where a is the leading character, HN is the address, HUMI is the type, 67 is the value, and the — pads the message out to 12 characters. The corresponding temperature message is


getting more complex – mapping the simple serial messages to a Cosm feed

The OKG receives these messages, along with those of other sensors, because the duration of a RF packet is very short. The RF line rate is higher than the 9600 baud the serial wire interface runs at, and the onboard micro seems to group all the 12 bits into a packet and send it at the high line rate. At the OKG the received messages are sent out of the wire serial port of the XRF. I have never seen two packets mixed up, presumably a packet is either received OK or not at all.

The job of the Arduino is to map the aHNTMPA to a particular Xively feed ID (and the corresponding API key), attach a comma and the data, then send this to the Xivelyserver via TCPIP. To do this it sends the data via the WiFly board using the serial command port of that board. The WiFly turns it into TCP/IP and sends the data on its way. I also test for the return code of 200. I actually send this back out on the RF network of my OKG so I can simply bridge a SRF radio on my PC and watch what’s going on. Over time I see

Uploading it to Cosm
HTTP/1.1 200
Uploading it to Cosm
HTTP/1.1 200
Uploading it to Cosm
aHNHUMI64---HTTP/1.1 200
Uploading it to Cosm
HTTP/1.1 200
Uploading it to Cosm
HTTP/1.1 200
Uploading it to Cosm
HTTP/1.1 200

The signals from the sensors are highlighted in blue, the rest is diagnostic feedback from my OKG software.

In the OKG when it gets aGGCOUN00021 it strips off  the  aGGCOUN and knows to map that to a particular COSM feed and allocate the geiger descriptive name. It adds a comma, then attaches the count, which is leading 0 padded out to make the whole packet 12 characters long. In this case I hope there are always three leading zeros 😉

Even more complexity: Xively (or other IoT provider) do the heavy lifting of data processing

There is no memory in my system. The sensor and OKG simply map the data to a Xivelyfeed and send it – nothing is locally stored, and there is no datalogger function. Once it leaves the OKG the data is simply routed to Xively. At Xivelythey perform the timestamping function and data processing to display the chart. I therefore need no real time clocks anywhere, this is done by Xively, and storage is also done by Xively.

This can take the form of a chart like this temperature chart


Or this Geiger counter chart

Geiger counter in Ipswich, UK


You save a lot of trouble and some cost going to Internet of Things (IoT)

The main advantage you get using the IoT approach rather than displaying everything locally is that

  • many people can see the data at the same time on the Internet
  • you don’t have to store anything locally
  • you don’t have to write any local display routines
  • you don’t need a local display.
  • you can if you wish craft LCD displays and bridge them on the RF network to show the data in another room without stringing wires all over the place, and you can show it in multiple locations. It’s hard to beat the low cost of a smartphone that you already have, however 😉

If you want a local display, use a smartphone. Here’s the Geiger counter on a Ipod touch – instant display, without writing any code! Immediately there’s a whole world of hurt and cost you avoid

geiger counter on an Ipod – instant graphical display

and you can strip your sensor down to the bare metal

the whole things fits in a small box, though I will use a DIN extension lead in practice

Of course, you pick up some downsides

  • Startup cost – the OKG and your first sensor will set you back about £75. After that you get the services of the OKG for that location free, as one OKG can service many sensors
  • extra cost of about £12 a device added, though you save a bit on the LCD and some time on writing the display code
  • you lose data if your Internet connection or cosm goes down
  • Your sensor doesn’t work on an island site unconnected to the Internet. Sensors in the field, for instance may have an issue there, and for this you may need a display. I used my headless sensors with an OKG configured as a datalogger to save the data to a SD card. if you don’t need realtime display that is a good solution, you can use the same OKG you normally have at home, just flash different software to it.



  1. It is possible in the long run that on the farm I may need to segment the RF networks by network ID, in which case I will need one OKG per network ID.
  2. LLAP doesn’t specify how the remaining 9 characters are split between type, value and padding. But it makes writing the Arduino code of the OKG a lot easier to have a fixed length for each section, and I’ve chosen four chars for the type