Communication Between ISO and External Software/Devices Via OSC

Table of Contents:

Sending Control Messages
Receiving Single Parameter Values
Receiving Grouped Parameter Values

Sending Control Messages

The syntax structure of OSC makes it very easy for you to create messages, provided your software or device supports OSC (usually over UDP/IP, Ethernet). Our implementation of OSC provides you with access to almost all the internal features of a running ISO system, e.g. setting up new swarms, expanding and contracting their agent count, destroying them, changing agent, swarm and simulation parameters, add neighborhood relations and change their attributes.

Find here a listing of all OSC-Commands.

Of course, you need some sort of OSC sender in your external control entity. This is actually just a simple UDP socket. In MaxMSP for example the according object is called "udpsend". Here's a simple patch setup to demonstrate the mere triviality of using OSC inside of MaxMSP. This patch controls the mass of the agents of a swarm called "mySwarm" (make sure that this corresponds to the name of an existing swarm).

sending a simple parameter

Multi-dimensional parameters are expressed as arrays. Arrays in turn must be surrounded by square brackets in the OSC message. Below an example how to handle multi-dimensional parameter (e.g. position) in MaxMSP.

sending a multi-dimensional parameter

There are a couple of things worth pointing out here: we are sending to the IP address 127.0.0.1 which is to say, we are sending to the localhost. If the software that sends OSC control and ISO Flock don't reside on the same computer, you will have to change the address to the IP adress of the computer with ISOFlock running on it. We use different ports for sending OSC messages and receiving error reports. These ports are set to 7400 (messages) and 7800 (errors) in all stand-alone example swarms that are provided for download.

Sending OSC from a text-based programming environment is equally straightforward:

// SuperCollider:
x = NetAddr("127.0.0.1", 7400);
x.sendMsg("/SetParameter", "mySwarm", "mass",  0.5);
x.sendMsg("/SetParameter", "mySwarm", "position",  "[", 0.1, -2.9, 1.4, "]");

// CSound:
OSCsend 1, "127.0.0.1", 7400, "/SetParameter", "ssf", "mySwarm", "mass", 0.2
OSCsend 1, "127.0.0.1", 7400, "/SetParameter", "sssfffs", "mySwarm", "position", "[", 1.0,
1.0, 1.0, "]"

Receiving Single Parameter Values

In order to use the flock-generated data in your programming environment you can receive the positions of the agents on port 7500. In fact, all stand-alone example swarms are configured to send outbound OSC data on port 7500 using the syntax:

Address part:                             Value part:
/SWARM_NAME/AGENT_INDEX/PARAMETER_NAME    VALUE1 VALUE2 ...

Here an example how the position of the agent with the index 0 is transmitted (which is actually the first agent as the indices are zero-based). Again, we assume that the swarm is named "mySwarm".

/mySwarm/0/position 0.438 -0.872 0.012

To extract these values you have to match the address part of the OSC message:

// SuperCollider: *
x = NetAddr("localhost", 7400);
x.sendMsg("/AddSender", "scsender", "127.0.0.1", 57120, "UDP", "OSC");
x.sendMsg("/RegisterParameter", "scsender", "mySwarm", "position");
OSCdef(\key, {|msg| msg.postln; }, '/swarm/0/position');

// CSound:
ihandle OSCinit 7500
kans OSClisten ihandle, "/mySwarm/0/position", "fff", kf1, kf2, kf3

* SuperCollider does only receive on port 57120, you must therefore tell your stand-alone swarm to add a sender and to register the parameter "position".

Receiving Grouped Parameter Values

Grouping the parameter values of several agents minimizes the network traffic and thus increases the efficiency of data transmittion. To activate this feature you have to register the parameter accordingly (refer to the section about OSC-Commands).

The syntax for grouped parameters is identical. The index of the first agent of the group is given.

Address part:                                   Value part:
/SWARM_NAME/FIRST_AGENT_INDEX/PARAMETER_NAME    VALUE1 VALUE2 ...

In the following example there is a total of 9 values. Since we know that position is a 3-dimensional parameter, we have to divide the values in groups of 3.

/mySwarm/0/position -0.224 2.461 0.901 1.367 -2.115 4.123 0.529 -2.181 1.192

Agent(0): x = -0.224 y = 2.461 z = 0.901
Agent(1): x = 1.367 y = -2.115 z = 4.123
Agent(2): x = 0.529 y = -2.181 z = 1.192

Legal