• Home
• Research
• Courses
• Publications
• People
• Affiliations
• Software

The Nexus Data Exchange Format Specification

The Nexus Data Exchange Format (NDEF) is an Open Sound Control (OSC) namespace specification that, when implemented, makes connection and message management tasks easier for developers of OSC-based systems. The NDEF specification can be implemented by any system that can handle standard OSC messages.

Author

Lawrence Fyfe

Basic Message Structure

One of the central features of NDEF is node identification. All NDEF messages have the IP address and port of the message source (OSC server or client) as the first two arguments. The generalized form of NDEF messages is:

This kind of identification is particularly useful for cases where there are multiple nodes in a one-to-many or many-to-many relationship.

Connection Management

Requesting

To begin an NDEF exchange, nodes send out connection request messages. The type tag for the request is "si" where the IP address is the string and the port is the integer.

When a connection request is received (and accepted), an accept message is sent to the request sender:

This exchange allow nodes to determine whether another node has NDEF capabilities and whether it is available for connections. Another important element of the exchange is that both nodes then can identify each other using IP address and port as unique identifiers. When multiple nodes may be involved in a network, this identification is essential.

Labelling

All NDEF messages provide an IP address and port number (the "si" in all type tags) that identify the source of the message. This helps clients and servers identify each other. However, IP addresses and port numbers might be harder to remember for people looking at that information. Being able to identify a node with a human-readable name can be helpful.

A label can be set when a connection is requested by adding an optional string argument to the request:

The following is an example using the string "laptop1" as a label for the node at address 192.168.1.1 and port 7000:

Labels can also be set on connection replies:

Including the label string in the connection /request or /accept message makes it easy to set labels during node setup. In other situations, it may be necessary to change the name of a connection label after a connection has been established. The /label command does this:

The last argument in the /label command is the label string to set on the receiver as with the previous example.

When a label has been accepted, the responder can send a /mark message to the requester. The term mark is used for this message in both the sense of taking notice and as another word for a label.

The mark message has an optional string for a label to return to the requester in case the responding node already has a label and wants to provide that to the requester. The handling of label conflicts is implementation dependent to allow for flexibility.

Pinging

Once a connection is established, it is useful to be able to test that connection. The /ping command does this:

If the node receiving the /ping message is available, it will send an /echo message to the originating node:

The /ping and /echo exchange can be used to determine both availability and round-trip time (latency) though timing is entirely implementation dependent. NDEF implementations also are free to determine how frequently /ping messages are sent and what sort of time-out mechanism is in place when /echo messages have not been received.

Message Management

Requesting

Once a connection has been established between two or more nodes, each node can send a message request to the other nodes. A message request has a form similar to a connection request:

The reply message has a slightly different form than the other messages in the namespace since, besides the IP address and port of the message source, it has the OSC message encoded as a string as the last argument.

An example reply message containing the OSC message /foo:

Type tags should be included in the message string. Each message in the namespace is sent back to the requester in its own /reply message.

Counting

When exchanging messages between nodes, it can be useful to know the number of messages that should be exchanged. By getting the number of messages, a node can know whether it has all of the messages contained in another node. The /count command gets number of messages from a node:

The receiving node can then send a /tally message with the number of messages it contains. The last integer argument in /tally is the message count.

With a /count and /tally exchange, a node can check the message count from another node to validate the number of messages it has received from a message request and to resend the request if necessary.

Editing

Editing messages enable nodes to add, remove and replace the messages of other nodes.

The /add message allows a node to add a message to another node.

The following example adds a new message called "/foo/bar" to the receiving node's namesapce:

Each /add contains a single message.

Messages can also be removed from a node with the /remove message:

This message removes "/foo/bar" from the receiving node:

The /add and /remove messages have the following basic structure:

The OSC message argument should include the address pattern and the type tag, formatted as a standard OSC message. Arguments should not be included.

A message can be replaced with another message using /replace:

The following /replace command replaces "/foo/bar" with "/bar/foo":

The /replace command has four arguments with the last two arguments being the old message string and the new message string that will replace it. The general structure of /replace messages: