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.
No comments:
Post a Comment