RadioVIS Demo Application v0.1
==============================

Introduction
------------

RadioVISDemo is a demonstration application for RadioDNS and RadioVIS.
RadioVIS is the visualisation protocol that forms part of RadioDNS
(http://radiodns.org). The software follows the v0.6 RadioDNS specifications,
which are currently under development, so there is no guarantee that
RadioDNS services will be available or compatible with this software.

Please visit http://open.bbc.co.uk/rad/projects/radiodns to obtain the latest
release of this software.

Installation
------------

RadioVISDemo is a Python application and requires the following software to be
installed:

* Python v2.5
* wxPython v2.8 from http://www.wxpython.org
* ObjectListView v1.2 from http://objectlistview.sourceforge.net/python
* dnspython v1.6.0 from http://www.dnspython.org
* SocksiPy v1.00 from http://socksipy.sourceforge.net
* setuptools v0.6c9 from http://pypi.python.org/pypi/setuptools
* nose v0.10.4 from http://somethingaboutorange.com/mrl/projects/nose/

RadioVisDemo was developed on Windows using the ActiveState Python distribution
(http://www.activestate.com), and has been tested on Windows XP and Ubuntu
v8.10.

The source code includes a modified version of Jason R Briggs's stomp.py module,
which implements the STOMP protocol. Please visit
http://www.briggs.net.nz/log/projects/stomppy/ for more information.

Running RadioVISDemo
--------------------

To run the application, enter the following at a command prompt:

    python radiovis_demo.py

Select a RadioDNS hostname in the Hostname field. The Local Stomp Server entry
allows testing of a RadioVIS service running on the local machine (localhost,
port 61613).

Press the Resolve button to perform a DNS CNAME lookup on the selected hostname
and then an SRV record query for available RadioDNS services (RadioVIS, RadioTAG,
and RadioEPG). The results are shown in the CNAME and Services fields.

If a RadioVIS service is available, select this from the Services list and press
the Connect button. The options next to the Connect button allow HTTP requests
and the Stomp connection to be routed through an HTTP proxy. Proxy settings are
obtained from the urllib.getproxies() method, which returns the system proxy
settings (the http_proxy environment variable or Internet Explorer settings in
Windows). A proxy server should not be used if connecting to a service on the
local machine.

Once connected, the following fields show information received from the RadioVIS
service:

 * The Log field shows status messages and details of all Stomp messages
   received.

 * The Messages field shows the history of received RadioVIS TEXT messages.

 * The Image URL field shows the URL of the image from the last received
   RadioVIS SHOW message.

 * The Link URL field shows the hyperlink from the last received RadioVIS SHOW
   message.

 * The Image field shows the image from the last received RadioVIS SHOW message.

 * The Text field displays the last received RadioVIS TEXT message.

Configuration
-------------

The RadioVIS demo application uses three configuration files, in the conf
directory:

 * radio_stations.xml contains a list of radio stations and their associated
   broadcast parameters, which are shown in the Hostname field. Please read
   the RadioDNS documentation at http://radiodns.org/ for details of the
   broadcast parameters.

 * radiodns_services.xml contains a list of the RadioDNS services and SRV
   record names, which are queried when the Resolve button is pressed. At
   present these are RadioVIS, RadioTAG, and RadioEPG.

 * test_radiovis_services.xml contains a list of test RadioVIS services that
   the application can connect to. Each test_radiovis_service element should
   contain the following entries:
   
   - name: The name of the test service name, for display in the user interface.
   
   - hostname: The hostname of the computer that runs the RadioVIS Stomp
     service.
   
   - port: The port number of the RadioVIS Stomp service.
   
   - text_topic: The topic name for text message notifications.

   - image_topic: The topic name for slideshow image notifications.

Limitations
-----------

The software has a few limitations:

 * The software uses the system proxy server settings (the http_proxy
   environment variable or Internet Explorer settings in Windows), and these
   are not configurable within the program.

 * In the handling of RadioVIS SHOW messages, the trigger time is not used,
   and the image is always shown immediately.

 * Error and redirect statuses are not handled when retrieving images over HTTP.

Resources
---------

For more information, please visit the project page:
http://open.bbc.co.uk/rad/projects/radiodns

and the RadioDNS website:
http://radiodns.org/

Contact and Legal Information
-----------------------------
Copyright 2009 British Broadcasting Corporation

The RadioVIS Demo Application is free software; you can redistribute it and/or
modify it under the terms of the Apache License, Version 2.0.

The RadioVIS Demo Application is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE.  See the Apache License, Version 2.0 for
more details.

Your comments and suggestions are welcome. Please visit our website at
http://open.bbc.co.uk/rad or send email to rad@bbc.co.uk.