Overview and Concepts

OSC - Open Sound Control - is the protocol, or format, that the Make Controller uses to communicate with other devices and applications.  Almost all modern programming languages/environments include support for OSC, which is great since that means the Make Controller can talk to all of them.  The list of languages and environments that support OSC includes, but is not limited to

OSC on the Make Controller Kit

OSC provides an intuitive way to organize the elements on the board, and specify which messages go to which parts of the board.  OSC messages for the Make Controller Kit all look similar - they specify an address, and then give the value that should be sent to that address. They adhere to the format of:

/subsystem/device/property argument

• Subsystems are different elements of the board - analog inputs, LEDs, digital outputs, servos are all examples of subsystems. Each of these subsystems has a number of
• Devices - 8 analog ins, 4 LEDs, 1 dipswitch. The device element of the address specifies which analog in we want to read, or which LED to turn on.  These devices each have different
• Properties - there are several different properties of the servo, for example, that we might want to set - the speed, the position, etc.  For the LEDs, this would be their on/off state, and for the analog ins it would be the value. Finally, the
• Argument is the value that should be sent to the address specified by the subsystem, device, and property.

Reading & Writing

Sending a message to the board is simple enough - you simply send it, and that's that.  For reading values, you have two options:

• Send a request message to the board for the value you want to read, and the board sends a message back, with the requested value.
• Configure the board to automatically send any new messages back to you as they are generated.  For this option, check this how-to.

We'll continue here to document the first method, sending a request message.  So how does the board know whether your message is a request or a write?  Write messages include an argument value, as in the example above.  If a message doesn't include an argument, then the board interprets it as a request. 

Example
So, to tell the board to turn on LED number one on the Application board, we would send the message

/appled/1/state 1

Notice that

• our subsystem here is appled (Application Board LED)
• our device index is 1
• the property is the state (whether it's on or off), and the value is 1, or on. 

If we wanted to read back the current value of the LED, we'd send the request message

/appled/1/state

Notice that we didn't send a value this time, so we expect the board to send back a message that looks like

/appled/1/state 0

if the LED is currently off, or

/appled/1/state 1

if the LED is currently turned on.

To continuously read values from the board, we simply continuously send request messages to the board.

Finding Out More About Your Make Controller

You can also send messages to the Make Controller Kit to find out what OSC devices it knows about using the same approach as with normal OSC reads.  For example, to see all the subsystems that the board knows about (the highest level of the address), send the message

/

Then when you see which subsystems the board knows about, you can ask that subsystem how many indexes it has.  For the analogin system, for example, send the message

/analogin

Lastly, to find out the properties for a given index within a subsystem, you can ask for those too by sending the message

/analogin/0

This way, you always know which OSC messages your board understands and knows how to respond to.

Bundles

Quite often, you'll have a situation in which you're reading or writing messages to several devices on the board.  It gets pretty inefficient pretty quickly to send a separate message for each of these devices.  The way around this is to use OSC bundles whenever possible.

An OSC bundle is simply a group of normal messages all wrapped up in a single bundle and sent at once.  Different programming environments deal with bundles in different ways, so you'll need to check out how to create and send them in the environment you're working in.  Information on how to do this should be included in the documentation for that environment.

More on Addressing

OSC also provides a nice, flexible way to send single messages to more than one address. 

One of the most frequently used methods of doing this is using the * character as a wildcard.  The wildcard matches all available entries for a given element in the OSC address.  So if we wanted to read all the analog ins using a single message, we would send the message

/analogin/*/value

and the board would return a bundle with messages giving us the values of each of the analog inputs.  Or, if we wanted to set all the servos to the same position, we could send the message

/servo/*/position 512

You can also specify a range of values, instead of just asking for all of them.  Do this by specifying the range as the lower limit followed by a hyphen, followed by the upper limit, and enclosing the range in square brackets.  So, to ask for analog ins 4 through 7, we'd send the message

/analogin/[4-7]/value

and to turn off LEDs 1 through 3, we'd send the message

/appled/[1-3]/state 0

This is a very handy feature of OSC and allows us to send messages to the board more efficiently - try to use these conventions whenever possible to reduce the number of messages to and form the board.  It's not too difficult to overwhelm the board with too much traffic, and these techniques help avoid that.

More Info

So where's the master list of all the OSC messages the Make Controller knows how to respond to?  You can browse the documentation here for info about each of the subsystems on the board that you can communicate with via OSC.