Protocol-OSC

Open Sound Control (OSC) is a widely used protocol for controlling all sorts of devices. This is a generic protocol implementation, so you have to know the exact commands your device reacts to, and how to connect to it.

OSC works by sending commands with an address and often also an argument. An example: To control 'level' on a device, the command could look like this:
• Address: '/level/1'
• Argument: '1.5'

Most OSC commands uses slashes in the address to divide the address into fields. The address above '/level/1', could specifies that we want to control the level parameter, on channel number 1.
These addresses needs to be known before hand, and can often be found in the manual or the OSC specifications for the device.

At the moment our OSC device core only works via UDP. This is the standard for most OSC devices, but a few uses TCP.

Configuration

To configure the device you need to set some device specific information.

• IP
  Set the IP address of the device to control 
  
• Send Port
  Set the port to send OSC commands to. This can either be set on the device or found in the manual.
  
  
• Receive Port
  Set the port to listen for OSC commands. Some devices sends the return commands on the port it receives commands from. If this is the case, then leave it empty, otherwise set the port specified on the device or found in the manual.
  
  
• Ping Command
  To check if the device is connected and active, you can specify a command to send once in a while. If we receive a response, we expect the device to be connected. This is often something like "/Ping" or "/KeepAlive".
  If the Ping Command is not set, the device status will always be connected, since there is no way of knowing if there is a device listening.
  
  
• Pong Command
  On some devices, the response to the Ping Command are different from the command send. For instance, some devices will respond with "/Pong" when a "/Ping" is sent. Specify it here, or leave it empty to use the Ping Command.
  
• Sync Command
  Some devices needs to receive a sync command once in a while, to keep sending feedback. This can be left empty.
  
  
• Sync Rate
  Set how often the Sync Command should be send. In seconds.

Models

The OSC core provides 3 different models to use:

1. Simple model
This model includes parameters for very simple one way OSC control.

A control parameter has to be specified with a few meta parameters.

• Address: This is the address to send the command to.

Type specific meta parameters.

• New Max: This specifies the max of the range for float and integer parameters.
• New Min: This specifies the min of the range for float and integer parameters.
• Float64: OSC can send both Float32 and Float64 arguments. The default is Float32 but set this to use Float64.
• Factor: Float commands can have a factor set before being send. For instance some faders go between -90 to 10, but the argument send needs to be between 0-1. A factor can be specified to do this. Set 'x' as the value and write the math needed. For instance '(x+90)/100'.
• As Integer: For Bool commands it can either send it with an argument of 'true' or 'false', or as an integer with value 1 or 0.
• Invert: Bool commands can be inverted when sent.

2. Dynamic model
This model includes everything from the simple model, but also a way to receive feedback on parameters.
Each parameter have a number of dimensions. These dimensions is assigned different commands, that then can be controlled, or could listen to feedback.

For each control type, there are 3 parameters. The control parameter itself, a command parameter and a config parameter. Each of these have the same amount of dimensions.

• The control parameter.
  This is the main parameter, where you can control what you want.
  
• The command parameter.
  This is a very simple parameter that shows the current address.
• The config parameter.
  This offers one way to setup all the info needed for the control parameter to work.

The other way to setup the control parameters, is through the webui. This offers a easier way to make multiple parameters ready to use. To open the webui, a dynamic or advanced model needs to be configured. Open reactor, and navigate to the 'Packages' menu. Here you can find the osc package, and a button to open the UI.

At the top of the page, there are a dropdown menu to select what device to configure, along with a row of tabs for each type of parameter available. If a dynamic model has been configured, 4 tabs with the datatypes 'Integers', 'Floats', 'Bools' and 'Strings' are available.

Each tab contains a row of parameter entries to set. Here it is possible to setup everything needed to setup each command to control.

The dynamic config parameter includes many of the same things as the simple parameter. The new things are:

• Ask For Feedback: Some devices won't reply to a command, but needs to receive a command without an argument to return the current value.
• Feedback: Some devices have a different address for feedback compared to the control address. Specify that here or leave it blank.
• Feedback Factor: If a Command Factor has been set, the opposite Feedback Factor is also needed. If the Command Factor is 'x*10' the Feedback Factor needs to be 'x/10'.
• No Feedback: If the device does not return feedback for this parameter, the No Feedback parameter can be enabled.

3. Advanced model
This model includes everything from the both the simple and dynamic model, but also a way to setup multiple dimensions of a parameter. For instance if you have many faders to control, you only have to configure it one time, and it will auto populate the second dimension of control.

The Advance parameters have the same 3 parameters for each type as the dynamic parameters. The main difference is , that when setting the address or feedback, a string formatter can be used. For instance if you have 20 level commands ('/Level/1', '/Level/2', '/Level/n'...). Instead of setting them up one by one, the Address can be set to '/Level/%d', and then the Count meta parameter set to 20. Now the parameter will be populated with 20 sub dimensions to control, one for each level control.
Some parameters will need leading zeros, for instance '/Level/01'. To set this, use '/Level/%02d'. That will make it a width of 2 and pad it with zeros.