Getting started with XRF modules and LLAP

Months ago I picked up some radio modules – specifically the XRF radio modules from Ciseco. They’re about £10 a pop and are in theory very simple to use. This is… almost true. In the end my modules sat dormant in my component store, and the OpenKontrol gateway I got from them at the same time was never assembled, owing to some missing parts for the ethernet module and abysmal documentation for the entire project – it’s still sat on my desk and will probably migrate to the bin eventually. This theme of abysmal documentation is unfortunately consistent across all of the Cisceo product lines, which is a real shame since they make great bits and pieces in theory. I really do hope they’ll pull their finger out and fix their documentation.

All that aside, last week at work, we had a two-day event for physical prototyping and I decided that I’d try and get the things working – and after a day or so, succeeded. This post is a brief introduction to how to get the modules working as advertised.

Ciseco ship a series of sensor boards designed to have an XRF module plugged into them, with a coin cell battery on the reverse. Most of my woes stemmed from this – I still haven’t gotten them working and suspect you need to do some setup on the board before you can use them in this lower-power environment. Being unable to solder anything and lacking a Slice of Pi or other breakout board I eventually clipped my logic analyser probes onto the XRF module directly and stuffed M-M jumpers in to expose the required pins on a breadboard, then powered it from a 3xAA battery pack.

There are a few ways you can use the XRF modules – by default they ship with a transparent serial bridge firmware, but you can program them with a range of firmware (downloadable here) from Linux or Windows. The uploader for Linux (found here, with usage instructions) works great once you apply the slight hack required to work around their packaging format on Linux – you have to run, for instance:
awk 'BEGIN {RS="\n";ORS="\r\n"} {print $0}' llapThermistor-V0.56-24MHz.bin > llapThermistor-V0.56-24MHz-ok.bin to convert the line endings to the right format for the uploader. Bit of a faff but not that much work.

My basic “Hello world!” idea was to have a button I could press on this XRF and have it register on another XRF connected via an FTDI bridge to a Raspberry Pi. To achieve this I would upload the LLAP Button firmware to the XRF on the breadboard (which then had a button attached to the appropriate pins with pull-up resistors) and upload the latest XRF serial gateway firmware to the XRF in the FTDI bridge. LLAP is a lightweight protocol for talking to devices, and we’ll talk more about that in a second.

Programming is simple – just drop the XRF into the FTDI converter (and it’ll show up as /dev/ttyUSB0 or whatnot in your OS) then run the uploader with the (line-converted) firmware file passed to -f and the path to /dev/ttyUSB0 passed to -d. It should upload the firmware, check it was a success, and finish.

Once you’ve done this it’s good to talk to your XRF and check it is okay. The easiest way I’ve found is to use miniterm.py, shipped with python-serial/pySerial. Install with pip install pyserial or apt-get install python-serial and then run the following: miniterm.py -p /dev/ttyUSB0 -e. You should get dropped into a terminal – enter +++ and no carriage return, and after a second you should get an OK back. You’re now in command mode, and after doing nothing for 5 seconds you’ll be (silently) dropped out of command mode again. Quickly enter ATVR followed by a carriage return, and you should get a version string back. If so, all is well!

Now we’ve programmed both we can do a test to see if they can talk to each other. Insert the XRF into your FTDI bridge and power it up, then open a miniterm.py session to it. Then power on the other XRF; you should see a bunch of messages along the lines of this:

a--STARTED--a--STARTED--a--STARTED--a--STARTED--a--STARTED--

Congratulations, you’ve got your first LLAP device talking to you! Let’s just talk about LLAP for a moment. LLAP messages (some docs here) always start with a lowercase a, followed by two letters – the device identifier. After that is a message, with padding in the form of – characters to a fixed length of 12 characters.

The STARTED message is intended to announce the arrival of the device on the network to a hub controller. We need to make our other XRF act like a hub, which is happily all software. Note the — device ID in those messages; this is a default ID and should be changed. We can do that over the air, though.

The first thing the LLAP device expects back on sending STARTED is an ACK back, otherwise it repeats itself a maximum of 5 times. Our ACK message, with padding, will look like a--ACK------. After that we can change the device identifier with a--CHDEVIDAA (to change the ID to AA) and ask the device to reboot once we get an identical message back to confirm the device ID change by sending it a a--REBOOT--- message – note the ID hasn’t changed yet – and we should get a new STARTED message that contains our new ID – our device coming back with our new setting. Congratulations, you’re talking over the air! If I now pull the button pin to ground on my LLAP device, it sends a message: aAABUTTONA–. I can tweak this button behaviour to record on/off, or act as a toggle, on the module by using over-the-air configuration options documented here.

The trick with all this is that you want to be responding rapidly and automatically. This is something where you want to be programming your interactions rather than doing initial setup by typing things into a terminal. There’s no easy fix for this; my solution was to hack together some Python with some if statements (this was an 11th hour moment in the hack day) to automate the responses, which did work okay, but a more OO approach is certainly the best approach. I’m going to start putting something slightly more sorted together in Ruby.

Obviously an even simpler approach is to simply use a transparent serial bridge and something to drive the bridge on each end, but this requires you to have constant power on each end. This isn’t always what you have – while base stations probably are powered from utility power sources, constantly powering a device for a few hundred mA (for a RPi and a radio) isn’t easy – possible, but fiddly, with a combination of solar charging and sealed lead acid batteries being the only real approach for external sensors. The advantage of the LLAP devices are that you can get them to go to sleep and wake up on an interrupt, making them very low power devices suitable for battery power. Once I figure out how to set the boards up for use with the Ciseco battery boards, I’ll do a follow-up post.

I really like the hardware Ciseco put out – the XRF is a great board at a great price point – but they really need someone to sit down for a week, set up a new site, and fill it with error-checked, up to date (and maintained) information, organized in a manner that lets you actually find things. And it really needs to be complete, with worked examples for their products and how to use them together. This would absolutely seal the deal in terms of using their kit for prototyping – as it is, it’s damn fiddly to get anything working ‘out of the box’!