SWDataNetwork

Base class for the Sense World Data Network.

Some nomenclature:

A DataNode, or a node, is a collection of data streams which somehow belong together.
For example, this can be representing:

An expected Node is a DataNode that is prepared to be added to the network, but may not be present yet.

A DataSlot, or a slot, is one datastream. So corresponding to the examples of nodes above a slot would represent:

A client: the programming environment of one collaborator hooked up to the network. E.g. Joe, using PureData, or Marije, using SuperCollider, or Vincent, using Processing, or Brett, using Max/MSP.

Subscription: a client can subscribe to a node to receive its data, or subscribe to a single slot of a node. These are called the client's subscriptions.

Setter: a client can provide data to the network by creating a DataNode. The client then becomes the "setter" of the node. Other clients can not set data to the same node.

- Example - 


// define the network
x = SWDataNetwork.new;

// get data input from incoming serial data
// (from an XBee network)
q = XBeeSMS.new( "/dev/ttyUSB0", 115200 );
// the action sets the data that comes in to the network:
q.action_({ |msg| x.setData( msg[0], msg.copyToEnd(1) ); });

// we expect floor pressure sensor data on node 2
x.addExpected( 2, \floor );

// we want to create a node with a measure of the
// sample variance on node 102
x.addExpected( 102, \floorVar );

// start the parsing of the input data:
q.start;

// the data comes in as 8bit integers, so we scale
// it here to a value between 0 and 1
x[\floor].scale = 1/255;

// we create a bus for the data (s is the audio server):
x[\floor].createBus( s );

// we create the sample variance node:
~floorVar = StdDevNode.new( 102, x, x.at( \floor ).bus, s );
~floorVar.start;

// now we have raw data available on node 2,
// and sample variance data on node 102

- Methods -

*new
Create an instance of SWDataNetwork

- Node Control -

setData ( id, data )
Set the data for a node. This registers a node if it does not yet exist. The size of the data array determines the amount of slots the node will have. Subsequent calls to this method for this same node ID will have to have the same size of the data array.
registerNode ( id, sz, type )
register a node in the network with a specific size and type (0: float, 1: string). If a node is not expected (see below), then it cannot be registered.
nodes ( )
returns an Array of the nodes of the network
removeNode ( id )
remove a node from the network.
checkDataType ( data )
Checks the data type (float: 0, string: 1) for the data, by looking at the first element in the array. Called by setData if a node is set for the first time.

- Expected nodes -

addExpected ( id, label, size, type )
add an expected node to the network. Label (the key the node will have in the spec) and size are optional. If size is specified, a node will be created with size number of slots, of type (default 0); the value of each slot will be initialized with 0.
isExpected ( id )
Answers whether the given node ID is expected or not.
expectedNodes ( )
returns an Array of the expected nodes (actually just their IDs) of the network
expectedNodes_ ( )
set the expected nodes of the network (should be an Array of ids)

- Spec -

spec ( )
returns the SWDataNetworkSpec
setSpec ( name )
Load an SWDataNetworkSpec from file.
add ( key, slot )
Add a key (node or slot label) to the spec. slot can be the node ID (one integer), or the slot ID (an Array of two integers).

- Named access to nodes, values and actions -

at ( key )
Returns the node or slot at key
value ( key )
Get the value of the node or slot at key
action_ ( key, action )
Set the action of the node or slot at key

- Node bus control -

bus ( key )
Get the bus of the node or slot at key
createBus ( key, server )
Create a control bus on the server for the node or slot at key. The data that comes into the slot is automatically mapped to this bus.
freeBus ( key )
Free the bus of the node or slot at key
createAllBuses ( server )
Creates buses for all nodes and slots that are named in the spec on the specified server
freeAllBuses ( )
Free all the buses that have been created.
createAllNodeBuses ( server )
create buses on the server for all nodes (Note difference with createAllBuses, which creates buses for all nodes that are named in the spec).

- Data input control -

worrytime ( )
worrytime_ ( wt )
time after which the network will perform an action to restart the network data inputs
watch ( onoff )
turn on or off whether to worry about data (not) coming in
watcher ( )
private - the task that performs the watching to regularly check when data was last set in the network

- Data logging and recording -

initRecord ( fn, dt, stamp, break )
initialize recording the data. This uses a MultiFileWriter to write to multiple files. Afterwards you can replay the log with SWDataNetworkLog.
fn (default "SWDataNetworkLog")
is the base filename. A date stamp gets automatically added to the filename. The MultiFileWriter will create a folder with that name, and temporarily store the data in that folder.
dt (default 0.025)
is the time interval at which to write lines of data.
stamp (default false)
determines whether or not to add a date stamp to the beginning of each line.
break (default 36000)
is the number of lines after which to start a new file. The defaults come down to a new file every 15 minutes.
record ( onoff )
turn recording on or off
closeRecord ( )
close the recorded file
recnodes ( )
private - The nodes which are being recorded.
writeHeader ( )
private - write the header into the logfile
writeLine ( dt, recordnodes )
private - write one line of data into the logfile
recTask ( )
private
recTask_ ( )
private - the task performing the file writing
logfile ( )
private - the file into which data is written

- Logging update times -

initTimeRecord ( fn, stamp )
initialize recording of the update times of the data. fn is the filename. stamp is whether or not to precede each line with a Date stamp (default is false).
closeTimeRecord ( )
close the update time recorded file
writeTimeUpdate ( id, time )
private - write one line of time update data to the log (format node id - update time)
recTime
private - whether currently recording update times or not
timelogfile ( )
private - the file into which update time data is written

- Graphical user interface -

makeGui ( )
Create a graphical user interface.
gui ( )
private returns the SWDataNetworkGui
gui_ ( )
private set the SWDataNetwork graphical interface (called internally when creating a new SWDataNetworkGui).

- OpenSoundControl interface (OSC) -

addOSCInterface ( )
Add the OSC interface to the network.
osc ( )
private returns the SWDataNetworkOSC
osc_ ( )
private set the SWDataNetworkOSC interface (called internally when creating a new SWDataNetworkOSC).

- Debugging and verbosity -

debug_ ( onoff )
turn debugging on for all slots. This will post all incoming data.
verbose ( )
posting of messages. There are various verbosity levels. 0 is no posts, 1 posts informational/warning messages, 2 posts all data coming in.
verbose_ ( )
Set the verbosity level.

Marije Baalman 2009-03-16