co2

/documentation/pd_plugin

index
about co2
overview
documentation
download

webinterfaces

using the pd plugin

if you're the impatient kind, skip down to examples at the bottom of this page. it is assumed you have a satellite with a working configuration (see satellite setup, if you don't).
and read the chapter 'starting it up' on this page!

some conventions

the pd plugin package comes with a module called


										bridge

. any references made here to 'the pd plugin' will actually mean that module. this [non-]distiction is irrelevant for users of the plugin, so we don't bother with the details here.

co2-home refers to the toplevel directory of this distribution. e.g. if you unpacked the archive version 0.5.7 in /home/terry/stuff/, then co2-home will be /home/terry/stuff/co2-0.5.7/.

plugin directory refers to the directory called plugins in co2-home. the pd package, like all other packages, is located there (the directory called pd). there you'll find bridge.py, our module of interest. each module can have its own config file, whose name must match the module's name, by convention <modulename>_config.py. so, the bridge module's config file (aka the plugin's config file) is called


					          bridge_config.py

overview

the pd plugin acts as a bridge between the satellite it runs within (and thus a co2 network) and pd, i.e. it passes on messages the satellite receives from the co2 network it is registered with to pd and vice versa.

the path of a message looks like this:
relay <-> satellite <-> plugin <-> bridge.pd <-> my_application.pd

communication between the plugin and pd is done over a tcp/ip connection using netsend and netreceive objects on the pd side. a pd patch (bridge.pd) that handles the communication with the plugin comes with this distribution, so you can concentrate on the 'actual' pd patch, my_application.pd in the above outline (subsequently referred to as pd-application), i.e. your pd-patch you want to hook up to a co2 network.

satellite configuration

in order for the satellite to load and initialize the plugin, it has to be included in the satellite's plugin list. edit the satellite's config file (usually config.py in co2-home) and change the variable plugin_list to include the pd package:

plugin_list = ['pd']

the square brackets and the quotes are important! if there are more plugins you want to use, append them to the list (like plugin_list = ['pd', 'shrubbery', 'nih'] - modules by those names must, of course, exist in the plugins-directory.)

plugin configuration

the two important variables to edit in the plugin's config file are:
address which is the address we want the plugin to listen for pd messages, and
pd_address which is the address pd is listening on.

pd settings

bridge.pd's netreceive object must listen to the address which is specified as pd_address in the plugin configuration. so, change this to the correct address.
there is no need to configure the 'connect <host> <port>' messagebox connected to the netsend object. that is taken care of by the plugin. when it first contacts the patch a message is sent that makes the patch connect back to the address specified in the plugin configuration.

starting it up

1. start pd and load bridge.pd. make sure the netreceive object creates OK.
2. start the satellite: cd to co2-home and type python2.3 co2.py
first, it will try to register with the relay specified in the main config file (config.py in


										co2-home

or the file given on the commandline).
if that fails, the process will exit, and you'll have to find out what went wrong. if it succeeds, the next thing is for the satellite's loader to load the plugin(s). look for messages tagged 'ERROR' or 'WARNING' in the log. otherwise the log should look something like this:


											Loader: initialized for "/home/lu/devel/co2/co2/plugins"

											Loader: loaded package pd

											Loader: loaded module pd.bridge

											Loader: registered exit_hook ...

											Co2SatelliteRegistry: receivers:

											     : pd.bridge.X_Bridge.receive

											pd.bridge.X_Bridge: --------------END RECEIVE CYCLE-------------------


											PdHandler: connect from 127.0.0.1:42401

now, when you look at the bridge.pd patch, you should see the toggles marked 'connected OUT' respectively 'connected IN' ticked, which means both connections are up.
3. open the patch exmaple.pd and click on some message boxes. in the co2 log you should see something like:


										  PdHandler: received 42

										  pd.bridge.X_Bridge: from pd: 42

											Co2SatelliteRegistry: calling relay ["relay.relay{'host_id': '193.171.120.22:2003', 'data': '42'}"]

that means you sent out a co2 message from pd!

examples

1. satellite and pd running on one machine

plugin config: address = ('localhost':3002), pd_address = ('localhost', 3003)
bridge.pd: 'netreceive 3003'

(nothing to edit. these are the default settings.)

2. satellite and pd running on different machines

the satellite host has the IP 1.2.3.4, the application host (running pd) has the IP 4.3.2.1, and for some reason cannot listen on port 3003:

plugin config: address = ('1.2.3.4':3002), pd_address = ('4.3.2.1', 20003)
bridge.pd: 'netreceive 20003'

see also 'network setups' in satellite_setup.