mcomm

mcomm.py is a small layer between Freevo and PyMbus to make usage of the mbus simpler. Warning: the interface itself may change in the future, but only on some minor details.

Freevo implements a wrapper for the important mbus functions for easier access inside helpers and plugins. By using the wrapper, the application will join the mbus with the following naming scheme: "app=freevo, type=home-theatre, module=name" with name being the name of the helper or 'core' for the main freevo application.

Let's start with an example how to communicate via Mbus using a client/server module. That's the only thing working right now in the wrapper, events will come later. PyMbus supports much more than the mcomm layer, so maybe it is necessary to import mbus in a plugin for special stuff.

Creating a server

To create a server you must inherit from mcomm.RPCServer. It is possible to have more than one server in an Mbus session. The RPCServer class is only a wrapper for easy access. Each function starting with __rpc_ and ending with __ will be registered as rpc to the mbus entity. So let's say you have a plugin listening to the RPC command home.theatre.play, you would create the following plugin:

class PluginInterface(plugin.Plugin, mcomm.RPCServer):
    def __init__(self):
        plugin.Plugin.__init__(self)
        mcomm.RPCServer.__init__(self)

    def __rpc_play__(self, addr, val):
        file = self.parse_parameter(val, ( str, ))

        if not eventhandler.is_menu():
            return mcomm.RPCError('freevo not in menu mode')

        menuw  = eventhandler.get()
        parent = menuw.menustack[-1].selected

        for p in plugin.mimetype(None):
            i = p.get(parent, [ file ] )
            if i and hasattr(i[0], 'play'):
                i[0].play(menuw=menuw)
                return mcomm.RPCReturn([])

        return mcomm.RPCError('no player found')

Simple, isn't it?

Client

Now, how does the client look like?

freevo = mcomm.find('freevo')

if not freevo:
    print 'freevo not running'
    sys.exit(0)

try:
    freevo.play('/my/file.mp3')
except mcomm.MException, e:
    print e

That's all. mcomm.find will wait on the Mbus until the freevo core entity comes up (timeout 10 sec). The method freevo.play will invoke the Mbus command home-theatre.play with the given argument. There are three possible returns:

1. (True, return values): The server sent mcomm.RPCReturn(return values). Everything worked as expected.

2. (False, reason): The server send mcomm.RPCError(reason). The parameters are ok, but it was not possible to do what expected.

3. mcomm.MException is raised. Something went wrong. Possible reasons are a crash on server side, a server not answering and so on.

freevo.play will block until the result is there. If you don't want to wait, you can specify a callback to the function:

freevo.play('/my/file.mp3', callback=my_function)

This callback will get the raw mbus return, no True, False or MException stuff.

PyMbus

PleaseUpdate: add basic PyMbus doc here