API documentation

trunk API generated by pydoctor

Architectural Overview

Installation

Coherence is still a bit cumbersome to install, as there are a lot of dependencies.

If you are lucky, an apt-get install python-coherence is sufficient. ;-)

But if your system doesn't have them already on board, you (with the proper permissions) need to do something like this:

- on a recent Debian based OS

apt-get install python2.5
apt-get install python-twisted-core
apt-get install python-twisted-web
apt-get install python-configobj

If you need to use python2.4 you need to install additionally:

apt-get install python2.4-elementtree python2.4-celementtree
apt-get install python2.4-ctypes

- alternatively most of the Python related packages can be installed via the Cheeseshop:

easy_install ConfigObj 
easy_install ElementTree
easy_install celementtree
easy_install ctypes

- Twisted and Nevow don't work yet with easy_install, they have to be installed manually.

- plus the GStreamer related packages, plugins and Python bindings which will be used by the MediaRenderer backend.

After that and the successful download of Coherence you can continue with the configuration.

Installation on the Maemo platform

An installation guide for Gentoo - thx micxer

An installation guide for OpenSuse10.2 - thx ensonic

Installation on Windows - thx lightyear

Configuration

coherence looks for a configuration file named .coherence in the $HOME of the user it is running under. If $HOME can't be determined, fallback is the current directory. Alternatively with the option -c|--configfile the location of the configuration file can be passed.

An example configuration file looks like this:

logmode = warning               # none, critical, error, warning, info, debug
logfile = coherence.log
#interface = eth0
#serverport = 30020             # if not specified or set to 0
                                # coherence will let the OS choose the port

#controlpoint = yes             # if set to yes coherence will activate its
                                # internal ControlPoint

web-ui = no                     # set this to yes to enable some interactive
                                # Web-UI

[plugins]
    [[FSStore]]
        content = tests/content    # append more directories separated by commas
        name = Coherence Test Content
    [[GStreamerPlayer]]
        name = GStreamer Audio Player
    [[FlickrStore]]
        name = Flickr Images
        proxy = yes             # if set to yes coherence will fetch the images
                                #  from Flickr for your client
        refresh = 60            # check every 60 minutes with Flickr for new images in the set

This configures coherence with an overall log level 'warning', printing out only messages with that or an higher level.
The interface definition is necessary for systems with more than one physical interface.
The serverport tells coherence which port to listen on for control requests and event subscriptions, to serve xml files and media content, and to check every 60 minutes for new images.
Three plugins are activated, a MediaServer filesystem backend with its own configuration options, a MediaRenderer and a MediaServer with the Flickr backend.

Startup

For a quick test just populate the tests/content/audio with some mp3 files and call

/usr/bin/coherence  -c pathto/docs/coherence.conf.example

The MediaServer with the file-system backend should show up on your UPnP client and should be able to browse and access these files.

If you don't want to install Coherence into the Python module space, you can try it out in development mode.

python ./setup.py develop
/usr/bin/coherence -c docs/coherence.conf.example
python ./setup.py develop --uninstall     # in the unlikely event of a sudden loss of cabin pressure

And don' forget to setup a multicast route for UPnP messages, in this example with eth0 as the interface you want them to travel over.

route add -net 239.0.0.0 netmask 255.0.0.0 eth0

Backends

Backends are the places, where the device implementation within Coherence is interconnected with the outside world.

A backend has to provide information for Coherence about as what it tries to operate. As an example a backend which supplies a filesystem backend should label itself as most of the time as a MediaServer.

Hacking

Logging

Can be configured in the configuration file

logging can now be configured via the config file or through an environment variable COHERENCE_DEBUG, which overrides the config values.

Usage is like

• COHERENCE_DEBUG=*:3 emit INFO level messages from all modules
• COHERENCE_DEBUG=*:2,ssdp:4 WARNING level messages from all modules, plus debug level for the ssdp module