Dissertation: BiLE Networking White Paper

This document describes the networking
infrastructure in use by BiLE.

The goal of the infrastructure design
has been flexibility for real time changes in sharing network data
and calling remote methods for users of languages like supercollider.
While this flexibility is somewhat lost to users of inflexible
languages like MAX, they, nevertheless, can benefit from having a
structure for data sharing.

Network
Models

If there is a good reason, for
example, a remote user, we support OSCGroups as a means of sharing
data.

If all users are located together on
the same subnet, then we use broadcast on port 57120.

OSC
Prefix

By convention, all OSC messages start
with ‘/bile/’

Data
Restrictions

Strings must all be ASCII. Non ASCII
characters will be ignored.

Establishing
Communication
Identity
ID
Upon joining the network, users
should announce their identity:

/bile/API/ID
nickname ipaddress port

nicknames must be ASCII only.

Example:

/bile/API/ID
Nick 192.168.1.66 57120

Note that because broadcast
echoes back, users may see their own ID arrive as an announcement.

IDQuery

Users should also send out their
ID in response to an IDQuery:

/bile/API/IDQery

Users can send this message at
any time, in order to compile a list of everyone on the network.

API
Query
Users can enquire what methods
they can remotely invoke and what data they can request.

/bile/API/Query

In
reply to this, users should send /bile/API/Key and /bile/API/Shared
(see below)

Key
Keys represent remote methods.
The user should report their accessible methods in response to a
Query

/bile/API/Key
symbol desc nickname

The symbol is an OSC message
that the user is listening for.
The desc is a text based
description of what this message does. It should include a usage
example.
The nickname is the name of the
user that accepts this message.

Example

/bile/API/Key
/bile/msg "For chatting. Usage: msg, nick, text" Nick
Shared
Shared represents available
data streams. Sources may include input devices, control data sent
to running audio processes or analysis. The user should report their
shared data response to a Query
/bile/API/Shared
symbol desc
The symbol is an OSC message
that the user sends with. The format of this should be

/bile/nickname/symbol
The desc is a text based
description of the data. If the range is not between 0-1, it should
mention this.
The nickname is the name of the
user that accepts this message.

Example
/bile/API/Shared
/bile/Nick/freq "Frequency. Not scaled."

Listening
RegisterListener
Shared data will not be sent out if no one has requested
it and it may be sent either directly to interested users or to the
entire group, at the sender’s discretion. In order to ensure
receiving the data stream, a user must register as a listener.
/bile/API/registerListener
symbol nickname ip port
The symbol is an OSC message
that the user will listening for. It should correspond with a
previously advertised shared item. If the receiver of this message
recognises their own nickname in in the symbol (which is formatted
/bile/nickname/symbol),
they should return an error:
/bileAPI/Error/noSuchSymbol

The nickname is the name of the
user that will accept the symbol as a message.
The ip is the ip address of the
user that will accept the symbol as a message.
The port is the port of the
user that will accept the symbol as a message.
Example
/bile/API/registerListener
/bile/Nick/freq Shelly 192.168.1.67 57120

Error

noSuchSymbol
In the case that a user receives a request to register a
listener or to remove a listener for data that they are not sharing,
they can reply with

/bile/API/Error/noSuchSymbol
OSCsymbol
The symbol is an OSC message
that the user tried to start or stop listening to. It is formatted
/bile/nickname/symbol.
Users should not reply with an error unless they recognise their own
nickname as the middle element of the OSC message. This message may
be sent directly to the confused user.

Example

/bile/API/Error/noSuchSymbol
/bile/Nick/freq
De-listening
RemoveListener
To announce an intention to ignore subsequent data, a
user can ask to be removed.
/bile/API/removeListener
symbol nickname ip
The symbol is an OSC message
that the user will no longer be listening for. If the receiver of
this message sees their nickname in the symbol which is formatted

/bile/nickname/symbol),
they can reply with /bile/API/Error/noSuchSymbol
symbol
The nickname is the name of the
user that will no longer accept the symbol as a message.
The ip is the ip address of the
user that will no longer accept the symbol as a message.
Example
/bile/API/removeListener
/bile/Nick/freq Shelly 192.168.1.67
RemoveAll

Users who are quitting the network can asked to be
removed from everything that they were listening to.
/bile/API/removeAll
nickname ip

The nickname is the name of the
user that will no longer accept any shared data.
The ip is the ip address of the
user that will no longer accept any shared data.
Example
/bile/API/removeAll
Nick 192.168.1.66

Commonly
Used Messages
Chatting
Msg
This is used for chatting.
/bile/msg
nickname text
The nickname is the name of the
user who is sending the message.
The text is the text that the
user wishes to send to the group.

Clock
This is for a shared stopwatch and not for serious
timing applications
Clock start or
stop
/bile/clock/clock
symbol
The symbol is either start or
stop.
Reset

Reset the clock to zero.
/bile/clock/reset
Set
Set the clock time
/bile/clock/set
minutes seconds
Minutes is the number of minutes past zero.

Seconds is the number of seconds past zero.

Proposed
Additions
Because users can silently join, leave
and re-join the network, it could be a good idea to have users time
out after a period of silence, maybe around 30 seconds or so. To
stay active, they would need to send I’m-still-here messages.

There should possibly also be a way
for a user to announce that they have just arrived, so, for example,
if a SuperCollider user recompiles, her connection will think of
itself as new and other users will need to delete or recreate
connections depending on that user.