±«Óãtv

RadioTAG is a new protocol that enables you to share information with a broadcaster about what you're listening to by pushing a button on your radio.

This article is about RadioTAG and how, over the past few months, ±«Óãtv R&D has worked with a cross-industry team to design it.

We touch on use cases for RadioTAG, summarise how it works, look at the considerations we took into account and describe how we went about designing it.

For detailed technical information you can read a and download our from github.

Introduction

• You're engrossed in an interview on the Today programme but have to leave for work. No problem. Press the RadioTAG button on your radio to remember your place. When you get to work, you resume listening on iPlayer from the point you left off.
• On the beach, you hear a great song you'd like to share with your friends. You push the RadioTAG button on your mobile to tweet the track now playing and add it to your account.
• You hear an advert for a well-known fast-food chain on commercial radio. You press the RadioTAG button on your radio to get a coupon (in the form of a QR code) emailed to your phone. You show this at the counter and enjoy a tasty, cheaper burger.

These are just some of the scenarios made possible by RadioTAG. RadioTAG aims to be an open standard that enables internet-connected radios to send the current time and station to a broadcaster's internet service, optionally store that data and receive back relevant information.

The protocol has been developed by the consisting of Andy Buckingham of , Robin Cooksey of and, from ±«Óãtv Research and Development, Sean O'Halpin, Chris Lowis and Kat Sommers.

RadioTAG is an initiative under the umbrella of , an industry-wide initiative to "enable the convergence of radio broadcasting and IP-delivered services". RadioDNS is also the home of , a slideshow service specification we have discussed before on this blog and , an electronic programme guide that aims to enhance broadcast audio services with rich programme related metadata.

What is RadioTAG?

RadioTAG is a protocol that defines:

• how a client finds the tag service corresponding to the current station using RadioDNS
• the transport protocol used
• the format of a tag request
• how the service should respond to unauthenticated requests
• how you pair a client with your account at a broadcaster's web site

Our motivation in contributing to RadioTAG is that we want to explore the additional services we can offer alongside our broadcasts. We've done some work on this in the past and know that audiences are keen to get more information on what they're listening to and to interact with the studio.

Commercial stations are interested in the same things but also in the opportunities they can offer advertisers in terms of attention data and direct response advertising. Click-to-buy, where pressing the tag button while a song is playing immediately purchases it, is another obvious possibility.

Device manufacturers are keen for RadioTAG to provide a rich "out-of-the-box" experience that works without you having to go to a website and fill in some forms.

Having a standardised protocol, broadcasters and manufacturers can implement applications and clients that they know will work together. Both sides benefit from the greater number of collaborating participants, so our audiences can enjoy a richer radio experience.

Overview of the protocol

The idea behind RadioTAG is simple: a client sends a request to a broadcaster's tag service, specifying a time and station. The tag service responds by sending a tag entry containing relevant metadata, for example, the most recently played track or more information about an advertisement.

Depending on the level of service provided, the tag data may be stored on the server and may be viewed on the client or on the web or be used for another application.

There are three levels of service a tag service can make available:

• anonymous tagging
• unpaired tagging
• paired tagging

Pairing in this context means associating your radio with an authenticated user account on the broadcaster's web site.

The levels of service are distinguished by whether or not tags are retrievable on the device or on the web and by whether you need an account on the broadcaster's web service. The table below summarises the differences:

These services can be offered in a number of combinations. For example, a broadcaster may offer anonymous tagging by default which can be upgraded to paired tagging or it may support tagging out of the box (unpaired) with no option to pair the device to a web account.

To prevent casual spamming of services, the protocol mandates a series of "grant" exchanges on the way to getting an authorisation "token" (in a manner similar to the ) to allow access to the unpaired services or to pair the device with an authenticated account.

The approach we took to the work

Our approach was to strip RadioTAG down to its core function: enabling an internet-enabled radio to record a station and time on an internet-based service and to retrieve the information it has recorded.

We left out geotagging, text input, ratings, etc. as we felt they would be distracting and could be added in a later version of the spec if necessary.

Then, with frequent iterations of modelling and discussions with our partners, we gradually settled on the design.

Design constraints

One of the first outcomes of our collaboration was agreement as to what constraints we needed to recognise and accommodate in the design of the protocol:

It must work out of the box

We started with the position that no data was to be stored except against an authenticated user account. This unsurprisingly turned out to be too strict a position. During an open day with device manufacturers, it became clear that an unregistered "out-of-the-box/ Christmas Day" experience was essential to the adoption of RadioTAG.

User input is limited

We were also mindful of devices with limited input capabilities. Simple radios may have only a limited display and a jog-wheel for entering text. This makes entering your user name and password quite fiddly. At the same time we wanted to make the protocol as secure as possible so your tags, and any information they contain, are available only to you.

Input on the device is limited to numbers only and anything we ask the user to type in on a website must be no more than 8 characters. This means we can't ask the user to type in a 48 character UUID for example.

Resources are limited

Mass market consumer goods such as radios are designed to minimise the total cost of components. Hence, RadioTAG should strive to require as few resources as possible both on the client and the server:

• The protocol should require minimal persistent state on the device. Most devices are extremely limited in memory budget so we needed to be careful not to waste space. We ended up needing to store only the service name and current token for that service.
• The web service should be resistant to unauthenticated resource exhaustion attacks ('drive-by spamming').

Specify 'how' not 'what'

We agreed that RadioTAG should not specify what a tag means nor determine its content.

The protocol doesn't define the content of the tag data because it can be anything the broadcaster wants. However, the device needs to be able to display that data so we settled on the Atom format as the common way of structuring the returned data. As this is an extensible format, we can add radiotag namespaced attributes or elements as required.

It must be secure

We were particularly concerned to make sure that registration was secure. As a group we agreed the following:

• You must be able to revoke authentication both on the device and on your web account. This is to address the situation when a radio is lost, stolen or sold on without being unpaired.
• Data stored on the server must be secure.
• Don't rely on a manufacturer supplied client ID as they are not guaranteed to be unique and can be spoofed.

Separate authorisation from API

We must support the ability to use separate servers for issuing credentials and for serving API calls.

Design principles

With these considerations in mind, we developed a set of design principles for RadioTAG:

Follow standards where possible, e.g. OAuth, REST

Taking inspiration from the , we decided to base our authorisation around the concept of tokens, which are practically unguessable arbitrary sequences of letters and numbers. What you are allowed to do with a token depends on its scope. For example, if you have a token with the scope "unpaired", you are able to create tags and view them on your device but not on the internet. If you have a token with the scope "paired", you can create tags and store them against your web account.

Another concept we borrowed from is the issuing of grants, which confer the right to request something from the service. For example, in the RadioTAG protocol, you cannot request a token for creating unpaired tags unless you have received the "unpaired_grant" in a prior request.

This tells the device what options are available to it, for example whether unpaired tagging is available or whether it can register with the web service. This reduces the amount of state the device has to remember.

A useful side-effect is to introduce a little rigmarole into the acquisition of the unpaired token to dissuade casual hackers from swamping our tag service with token requests. It won't stop someone who has read the protocol and can implement it, but it will cut down on the "drive-by spamming".

Limit user input

Any entry on the client must be no more than 4 digits (i.e. a PIN) and entry on the web front end should be no more than 8 characters.

The API should be consistent

A clear and consistent API helps developers quickly get up to speed. For example, we decided against optional parameters for version 1.0 to avoid any ambiguity about what was required in an implementation.

Throughout, we use headers to return grants, tokens and service metadata from the tag service.

Also, we use form data for parameters rather than query parameters so we don't expose tokens in logs.

How we designed the protocol

Playing RadioTAG

We started by playing the "RadioTAG game". Chris and I pretended to be the client and the service. We wrote down API requests and responses on sticky notes and passed them back and forth. This seemed to amuse George no end and Vicky was pleased to see we were doing . The result was our first specification:

The RadioTAG game

Sadly, the world is not yet ready to accept such fragile constructions as valid specifications, so we converted it into a using the excellent .

To give you a flavour of how the actual protocol we designed looks like as a message sequence diagram, here is a diagram showing the exchanges between client and server from the point when you tune your radio and press the tag button to when you pair that radio with your web account:

The RadioTAG protocol in summary

Simulating RadioTAG

A common mistake in software design is considering only the 'happy path', i.e. what happens when everything works the way you hope it will. We wanted to make our protocol robust in the face of events such as entering the wrong PIN number, losing your radio or someone managing to steal the registration key before you finished registering. To study the ramifications of these situations, we decided to build a software model to simulate what would happen in those cases. This turned out to be key in the development of the protocol as it enabled us to quickly test various scenarios and try out variations of the protocol.

Our model consisted of a client, a tag service, an authorisation service and a web front end. We wrote this in Ruby using , a library designed to manage asynchronous network communication. We had originally tried to write the model using simple synchronous method calls but this soon became unwieldy. Using the allowed us to model each entity as an independently executing process, just as it would be in a real system.

We modelled the authorisation service separately for two reasons: the first is that we needed to ensure that our proposed specification for RadioTAG would work with system architectures which have separate authorisation services such as we have with ±«Óãtv Identity; the second is that we wanted to avoid what is , namely that it conflates the service API with authorisation.

It soon became apparent that with suitable instrumentation, the model could automatically generate the message sequence diagrams we had up to now been creating manually.

With the addition of a simple scripting capability, we were able to explore many different possible situations. The example below shows the script for the unpaired to paired scenario:

title Scenario 1: Unpaired then paired
Alice :tunes her Radio to "±«ÓãtvRadio4"
Alice pushes the :tag button on her Radio for the first time
Alice pushes the :ok button on her Radio
Alice pushes the :tag button on her Radio again (showing that unpaired tagging works)
Alice pushes the :register button on her Radio
Alice :logs_into ±«ÓãtvWFE with password "alice123"
Alice :registers her Radio
Alice enters the :pin into her Radio
Alice pushes the :tag button on her Radio to now tag directly to her account
Alice pushes the :ok button on her Radio

Here is an extract from the diagram generated from this scenario:

Extract from the RadioTAG model diagram

Reference implementation

Once we were happy that we'd covered the most important use cases and addressed possible attacks, we used the model as a basis for building a reference implementation consisting of three subsystems: a , an and a .

We built these in our usual stack of Ruby, Sinatra, DataMapper, MySQL and Passenger under Nginx using test-driven development and pair-programming.

Console radio

After building the web services, we needed something to try them out, so we wrote a that pretended to be a radio. With the addition of recording user actions, playback and HTTP tracing, this also proved to be a useful tool in generating documentation. The HTTP traces in the API document were generated from this client.

Collaboration

Armed with these tools for generating documentation from code, we were able to share our progress with our collaborators Andy and Robin, who provided us with invaluable feedback and guidance.

With regular visits from both Robin and Andy over the course of a number of weeks, we addressed many fine points, ironing out the last wrinkles in the protocol.

The high point was when Robin got a basic client working on a development system which could send a tag to our service. There's nothing like seeing a physical device doing what you'd only previously seen working in software. The idea become reality.

Draft specification

The result of this work is our . We are submitting this to the RadioTAG application team for discussion and ultimately ratification, before onward submission to the RadioDNS board with a view to adoption as version 1.0 of the protocol.

Source code availability

You can find all the source code we developed as part of the project on the .

What we've learnt

Designing protocols is hard! We've had to accept compromises to accommodate what the architect Christopher Alexander calls the at work and many times subtle points arose that caused us to scratch our heads.

Having a model we could easily adapt to test scenarios meant we were quickly able to probe the consequences of what was a major change to the protocol.

The outcome certainly wouldn't have been possible without the collaboration, input and scrutiny of all four of us, each coming from a different angle and each making essential contributions.