FIXME The last sections of this page contains outdated information.

====== OSC Routing ======

===== Some preliminary considerations =====

The OSC protocol is designed to send and receive messages that are sent over the network.

On a network a host is a computer or device((like an iPhone or a Lemur)), and a port is a number identifying an "input gate" to the host.  Such "input gate" that can listen to OSC messages is also called a //OSC Server//.

When OSCulator is launched and the main window is displayed, an //OSC Server// is running, enabling the reception of OSC messages.  On the other hand, anything that sends OSC messages is called a //OSC Client//.

Thus, when the ''OSC Routing'' event is used, OSCulator also acts as a //OSC Client//.


===== Hosts and ports =====

Like previously explained, the host is referring to a devices that runs a OSC Server.  It can either be the name or the computer (''mymacintosh.local.'') or an IP Address (''192.168.0.1'').

The computer which runs OSCulator has a special name ''localhost'' and a special IP address ''127.0.0.1''.  You can use either of these if you want to send messages to the current computer itself.  This is usually the case when you are running several OSC enabled software on the same computer.  For example, OSCulator could listen to OSC messages on port ''8000''((the //OSC Server// is running on port ''8000'')) and Max/MSP could listen on port ''9000'' with the ''udpreceive'' object.  They have different port numbers, but the host is the same: ''localhost''.

Note that a unique port number can't be shared by several OSC Servers.  This is a limitation of the underlying network protocol which states that a server has one only port that he owns exclusively.

If you need to send messages to another computer, you will need to know its host name.  To do this, open the **System Preferences** and click on the **Sharing** Preferences Pane item.  The computer name is written under //Computers on the local network can access your computer at: [...]//.


==== Control your software and devices ====

Software like Max/MSP or Reaktor can also receive OSC data.  This data is sent over the network, even if it is sent to the same computer that generates the messages.

If you want to control your third-party software, or make some special routing, you can use the ''OSC Routing'' event.  With this very useful event type, you can route anything to another host and port, even outside on the Internet((if you send OSC to a host that is on internet, you must make sure the destination port is properly routed and that there is no firewall blocking the packets.  You must also use either an IP Address or a fully qualified host name, that is a host name with the domain name)).

It is also possible to rewrite OSC messages in order to change their name and arguments during the routing. 


==== Basic steps ====

Perform these actions while in the main window:

  - Select the OSC message you wish to route, and choose the ''OSC Routing'' Event Type
  - In the Value menu, choose the host you want to send the messages to.
    * This is list is populated with the OSC Servers are automatically found on the local network, if you want to send the data to a specific port or host, you must configure it in the Parameters window((click the Parameters button in the toolbar, or choose Parameters in the View menu))


===== The Parameters window =====

Although the OSC Servers are automatically listed, you may need to manually configure them if you want to perform more complex routing.

With this panel, you can configure the hosts, ports and rewrite address of each destinations.

{{ :manual:osc-parameters.png |Parameters Window OSC tab}}

On this picture, we show five destinations.
Two of them will route the OSC data to the host ''computer2'' on port ''9000'' and two of them will route on the local computer.  The difference between the two destination is their rewrite address.

The last one has no rewrite address, because it has been left blank.


===== Advanced topics =====


==== OSC message or argument routing? ====

OSC messages are composed of OSC arguments.  You can choose to route the whole message with all its arguments, or you can choose to route only one argument.

=== Route an OSC message with all its arguments ===

{{ :manual:forward-context.png }}

This picture shows the configuration of a OSC message routing.  Here, the message ''/foo/freq'' has two arguments.

The destination((in this example, the message will be sent on the same computer, but on port ''9000'')) will receive the OSC message ''/foo/freq'' with its two arguments.


=== Route one OSC argument only ===

{{ :manual:forward-action.png }}

Here, we chose to route only the first argument of the OSC message.  In this case, the destination will receive a OSC message with a single argument at the address ''/foo/freq/0''.

As you notice, the index of the argument is appended to the destination address.  This is needed in order to avoid messages collisions.

==== Address rewriting ====

When a rewrite address is provided for a destination, its name will appear with an arrow in the Values list:

{{ :manual:forward-rewrite.png }}

This example shows that the message ''/methode.cc'' will be routed to host ''localhost'' on port ''9000'' and the address will be rewritten as ''/synth/cutoff''.

If a routing is given a rewrite address, it doesn't matter wether it is the whole OSC message or only an argument that is routed: it destination address will always be the same.


==== Example: Create a more complex OSC router ====

The goal here is to create a OSC router which receives OSC messages on port ''8000'' and routes the ''/foo/freq'' messages to port ''9000'' of the local host or port ''9000'' of the host ''computer2'', based on the state of a trigger OSC message, ''/methode.cc''.

{{ :manual:forward-complex.png }}

  - The ''/methode.cc'' message has been duplicated 3 times, in order to be able to trigger 4 actions when its value changes.  This message is bound to the ''Toggled Enable'' event which changes the "enable" state of an OSC message listed in the table.
  - The first two arguments of the message ''/foo/freq'' have been duplicated, in order to assign the two different destinations.  We also clicked on the Enable column of the two arguments, so that they will be enabled and disabled subsequently when ''/methode.cc'' is triggered.

===== Miscellaneous notes =====

==== Routing to the same document ====

OSCulator automatically publishes and discover the OSC port on which it is running.  This is why the Value menu, always show the OSC destination corresponding to your computer host name and port.

If you choose to route messages to the same document that is sending the messages, an infinite loop will occur.  This is not a bug, but a feature!  The decision was made to not restrict this feature, which can be used to demultiplex OSC messages and then re-route them to the same document.


==== Routing to another document ====

This is a special case of the routing to another host on the local network.

On the same scheme as the previous section, if you create a new document and work with two windows, you can route messages from one window to another.