Saturday, November 21, 2009

Remote control of Reciva-based radios

- Controlling your Reciva radio without touching it

Many, but not all, internet radios come with a remote control. Sometimes they are very simple credit-card sized devices, sometimes they can be big dedicated boxes needing two hands to use with all sorts in between.

Basic models tend to use infrared and more sophisticated use TCP/IP over Wi-Fi - with a proprietary application protocol on top.

The underlying firmware in the Reiva-based radios generally have infrared control enabled even if there is no infrared hardware included in the radio. This fact has been exploited by a few people who have opened up their radios and inserted a supported infrared detector (one directly wired to the Barracuda board and another simply using the USB connection ... but I cannot find it while writing this).
Some other Reciva users have gone down a software route by using the unofficial Sharpfin patch to run a small web server on the radio and have it present a simple web interface that in turn performs some radio management commands. An example of this is documented in the Sharpfin mailing list.

However, Reciva have been working away quietly in the background and have implemented a way to achieve almost complete control of the radio (including managing the alarms, examining presets, tuning to radio stations and even browing the menu).
The initial implementation of UPnP-AV (aka DLNA) within the Reciva software performed the basic minimum - allowing it to access a media server and allowing the user to browse the music then select and play tracks.
This was extended to all external control points to send music to it - but the big addition was to add a Reciva specific service (RecivaRadio:0.0) that opened up much more of the proprietary capabilities of the radios.

A regular UPnP-AV controller will not know how to use these functions - so using them requires custom software. But the open nature of this (standard protocols and self-documenting web services calls) means that building something is relatively straight-forward ... using existing tools I was reading presets, searching the database and changing stations in less than 15 minutes.

This service is what I presume is being used by the Grace Digital remote control for the iPhone & iPod Touch.

If you plan to build something then here are some pointers - and let me know via a comment here or direct via other routes:
Check the power-on status - since some commands will not work if the radio is (soft) powered off.
Some of the calls require the use of a NavigatorId - obtain one with RegisterNavigator. This can then be used for the session - and should be released at the end with ReleaseNavigator (otherwise, I presume, the radio will eventually run out of memory).
The local controls at the radio appear to be disabled while controlling from remote - which may well be the most important reason to ReleaseNavigator.

There can be more presets supported in the software than are accessible via the buttons on the device itself. Plus - the number available can be different on each radio. So use GetNumberOfPresets to determine how many there can be.
GetPreset returns the data of a single preset. Preset0 is a special case - it is automatically set to be the last station played.
Presets can be set in 2 ways - one is via SetPreset (see the return from a GetPreset to better understand the data required) and the other is to set the current playing station to a preset via SaveCurrentStationAsPreset
Tune to a given preset with PlayPreset.

The station database can be searched (SearchForStationByName) and browsed (GetMenu).
It is also possible to get the station logo.
Here is an example of the return from one of these (GetPlaybackDetails):

<station id="9256" custommenuid="0">
<stream id="fa3be23929b7339f9d2ce90f2c84ec37">
<title>Dandelion Radio</title>

Take care here - some devices have an analogue volume control. So if the volume is turned down at the radio then you will not be able to adjust it from remote.

I have not yet managed to navgate the sub-menus - the item ids do not seem to work when I try them ... work in progress.

Some of the commands return an error (for example GetIsUpgradeAvailable) and there may well be differences between firmware versions (GetCurrentServicePack) - plus it returns all possible source types even if the hardware is not installed - so try to make your code flexible and extensible.

There is a lot more in there - such as:

  • Volume controls (up / down / mute)

  • Playlists (view list, change order, remove item)

  • Soft Power (on / off)

  • Alarms (view, set, delete)

  • Reply (equivalent to hitting the reply buttton)

  • Device (hardware id, upgrade, language)

For those who do not know how to examine the available services - but who are simply interested in knowing what is there ... I have uploaded a dump of the available set from firmware v257-a-865-a-400 (very recent beta) to the very useful "UPnP/AV Device Capability Database" being run as part of a research project at Institut für Pervasive Computing of Johannes Kepler Universität, Linz, Austria.

The specific entry for the recent firmware is at:

You could help developers who do not have access to all radios/firmware by making your own upload of data by downloading the Magpie tool from their site. It would be particularly interesting to see the output from a Reciva-based Grace radio to check if there are any extra capabilities that are being used by their remote ... but I suspect that they have no more than is in the current firmware. If you do download and run the tool then make sure that it is not blocked by your firewall - and let it sit listening for a few minutes while waiting for a radio to advertise itself. Powering the radio off and on is likely to make it broadcast immediately. The radio should then appear on the left. Click on it - and it should start analysing. Once complete you can upload via the "Submit Data" button in the top left. After you finish the process you can view you new data on the site.
Note - there is not much point uploading data for a device/firmware combination that is already there so do browse the device list first (some of the names might not be obvious - and there a devices from all sorts of suppliers not just Reciva of course).


digitaltoast said...

Thank you so much - some great research there and just what was looking for!

Florian Albat said...

Thank you for the information.

I'm additional interested in sending only TCP or UDP commands from a home automation server in my house to the radio to adjust volume or change presets.

Should this be possible for the Reciva radios?

Paul Webster said...


As far as I know, the only official way in is via full UPnP-AV.

However, you might be able to make a tool by starting from one of the existing open source control point applications

Another route could be to use Sharpfin to open up the device and then install your own listener or as a script from Sharpfin web server ... and potentially control volume that way (e.g. by sending lirc commands)

JohnW said...

I am interested in getting a script or possibly a VB app that would pull the GetPlaybackDetails from my Grace Digital Internet Radio. Currently I use Girder which uses LUA but at this point any information as to where to start would be appreciated. Thanks

Paul Webster said...


Here are some more examples - but note - everything has to be wrapped by proper UPnP-AV protocol.

I have replaced the less-than and greater-than with curly brackets to get it through the blog commenting system.

Note: old firmware does not have these commands available - so any application trying to do this should first query the device to get the set of available commands.

Call RegisterNavigator
Returns RetNavigatorId (example e1234abc-3333-4444-9999-ca3265a1b2c3)

GetAudioSource (example values: Internet radio,Media player,Buzzer)
GetPlaybackDetails (takes NavigatorId as parameter)

Example returns:
GetAudioSource = "Internet radio"
(of a station which has metadata showing track info on screen ... but not in return from radio)

{station id="9256" custommenuid="0"}{logo}{/logo}
{stream id="fa3be23929b7339f9d2ce90f2c84ec37"}{url}{/url}
{title}Dandelion Radio{/title}

Here it is playing from local server using UPnP (GetAudioSource = "Media player")

{title}#1121: Pranks, Painting and Personal Problems{/title}
{album}NPR: Car Talk Podcast{/album}
{stream type="MediaStream"}{url}fasthttp://[eeff::1234:5678:2356:dada%253]:10243/WMPNSSv4/2698446669/0_e0E1ODg3Qsdlkjfsdf0978sdfkjdsf097sdfQyRTUzOUM4Mn0.mp3{/url}
{title}#1121: Pranks, Painting and Personal Problems{/title}

When finished call ReleaseNavigator - perhaps radio will run out of memory if you leave too many hanging around

Paul Webster said...

Also @JohnW

I guess this ( ) is a related thread that you started.
Looks promising - have bookmarked it and will try to find some time over coming weeks to see if it helps.

JohnW said...

Not familiar with UPnP at all. So what should I use to try these scripts out in a Windows environment? I guess I need baby steps to get started. Thanks

Paul Webster said...

Was the post that I referred to above one of yours?
If yes - then there is a community of people there who seem to have some tools to help.

My examples above were not scripts to run. The UPnP-AV sets of operations is relatively complex and the Reciva extensions complicate it further.
There are a small number of opensource UPnP-AV Control Point implementations that could be used as a starting point - but will require software development skills to add in the necessary parts to do the device-specific things.

JohnW said...

Well Grace put out a beta firmware that has fixed the UPnP so now Windows UPnP Tools like DeviceSpy can see and control it. I have since got my home automation project controlling it through UPnP

Paul Webster said...

Well done. Will you be publishing your results? I can imagine that others will be interested in doing something similar.