This little tutorial describes how to control an Arduino with TouchOSC.

Prerequisites:

• Hardware:
  1. Arduino Board. This was tested with an Arduino Uno, and  a Teensy 3
  2. Arduino Ethernet Shield. There are several clones of the original shield available in different price ranges. As long as these host a W5100 or W5200 Ethernet chip it should work.  A word of caution: the standard Arduino Ethernet library does not support the W5200 Ethernet Chip so if you want to use a clone with a W5200, make sure it’s supported with a version of the Ethernet library. The Seeed Studio Ethernet Shield  V2.0 for example  hosts the W5200 Ethernet Chip and comes with it’s own version of the Ethernet Library that supports the W5200 chip. This has been tested with an original Arduino Ethernet Shield on an Arduino Uno and with the WIZ820io Ethernet Module in conjunction with a Teensy 3
  3. Optional:
     If a WiFi solution is desired the simplest solution is to connect a little pocket WiFi router such as the TP-Link TL-WR702n or TL-MR3020  to the Ethernet shield or module. The web interface that is used to configure these routers is in English. The TL-WR703n that is also available cheaply on eBay has a more capable processor and is popular amongst people that want to run the Linux based Open-WRT router software on the little router. However, out-of-the-box the interface is in Chinese. I’ve persevered through the Chinese and have worked successfully with the 703n as well as the 702n.
     A note of caution: In the section below “What’s left to do” I mention that this setup also can be made work nicely in conjunction with Apple’s Bonjour. This only works with these two little routers with the original firmware. Open-WRT is Linux based and does not support Bonjour out-of-the-box. Installing Avahi – the Linux implementation of ZeroConf Networking requires more memory than these small routers have. It may be possible to get this to work, but I have decided to use my limited time for something else 😉
  4. Optional:
     This should also work nicely with a Sparkcore. I did some quick and admittedly sloppy research and I believe based on this Sparkcore Forum post that the Oscuino library has been successfully ported to also run on the Sparkcore. However, the Texas instruments CC3000 WiFi Chip/Module that is utilized the Sparkcore only implements a very rudimentary subset of multicast DNS (mDNS). This does not allow for service registration. As such Bonjour also will not work with this setup. OSC messages OTOH should work fine and this would be a physically very small solution!
• Software:
  1. Oscuino, the Arduino OSC library. This is recommended over any other Arduino OSC implementations such as ArdOSC Z-OSC etc. Oscuino is the most complete implementation of the OSC protocol and is written and actively maintained by the inventors of the OSC protocol at the CNMAT | The Center for New Musik and Audio technology and the University of California at Berkley
  2. Arduino 1.0.5 IDE or higher. Tested with Arduino 1.0.5.
  3. Teensyduino if you are working with a Teensy.
  4. TouchOSC and the TouchOSC editor for your operating system. Tested on Mac OSX and iPhone 4 & 6. It’s available for Android as well.

The complete Arduino sketch and TouchOSC layout can be downloaded from the GitHub repository.

Lets start with the TouchOSC layout.

The first thing that needs to be done is to move the layout from your file explorer to your mobile device. There are two ways to achieve this. One includes transfer over WiFi while the other involves iTunes.

We’ll use the Layout transfer over WiFi, which requires the TouchOSC editor to be installed on your computer. This is an application written in Java and needs a Java run time engine on your computer. Mac OSX comes pre-installed with one  so this will not be discussed here. Follow the  online instructions and transfer the layout that you downloaded from the Github repository to your mobile device.

The layout has two pages, one with a simple button and one with a fader. Both of these controls will send OSC messages to the Arduino. The Arduino will send a message back to the controls and the  Controls will respond to these messages.

The Button

When the button is pressed it will send an OSC message to the Arduino Sketch to turn on the LED on the Arduino board and to print a message in the Arduino IDE  Serial Monitor. The sketch will then send a message back to the control that turns the inside field on the button red to indicate that indeed the message has been received, a message has been printed and the LED is on. When designing your own controls it is important to note that for this toggle button to respond to OSC messages “Local feedback off” bust be checked in the editing properties in the TouchOSC Editor.

The Fader

When the Fader is moved it sends OSC messages corresponding to its position to the Arduino Sketch. The Arduino Sketch will receive the message and will print the value received with the message in the Serial Monitor. It wl also send an OSC message to the little label in the upper right corner above the fader. The label will display the value to which the slider has moved.

Arduino Sketch

Before we continue the Arduino Sketch a few details about the OSC protocol and TouchOSC need to be discussed. The OSC protocol communicates through OSC bundles and OSC messages. In simple terms a OSC bundle combines one, or more OSC messages and a time tag. Each OSC message can contain several values of different data types, such as integer, float, string and blob.

1. TouchOSC only sends and receives OSC messages, not OSC bundles.
2. TouchOSC only sends and receives values of the data type float

The complete sketch is listed in the scroll box at the very bottom of this page and can be copy/pasted into the Arduino IDE editor. The sketch uses DHCP to receive an IP address form a router, however by uncommenting a few lines a static IP can be assigned to the Arduino as well. For more details on how to create an Ethernet connection with the Arduino please refer to the Arduino online documentation.

Other than the

#include <OSCBundle.h>

There is nothing OSC specific in the Sketch until we come to :

void loop(){
  //process received messages
  OSCMsgReceive();
} 

This runs only one function that receives UDP packets and parses these for OSC messages.

void OSCMsgReceive(){
  OSCMessage msgIN;
  int size;
  if((size = Udp.parsePacket())>0){
    while(size--)
      msgIN.fill(Udp.read());
    if(!msgIN.hasError()){
      msgIN.route("/OnOff/toggle1",toggleOnOff);
      msgIN.route("/Fader/Value",funcValue);
    }
  }
}

In detail it fills the inMsg instance of the OSCMessage object until the received UDP packet is empty. If the message has no error and matches one of the OSC addresses

"/OnOff/toggle1" or "/Fader/Value"

it routes to (executes) the assigned functions. So lets look at one of these:

void toggleOnOff(OSCMessage &msg, int addrOffset){
  ledState = (boolean) msg.getFloat(0);
  OSCMessage msgOUT("/OnOff/toggle1");

  digitalWrite(ledPin, ledState);

  msgOUT.add(ledState);
  if (ledState) {
    Serial.println("LED on");
  }
  else {
    Serial.println("LED off");
  }

  ledState = !ledState;		 // toggle the state from HIGH to LOW to HIGH to LOW ...

  //send osc message back to control object in TouchOSC
  //Local feedback is turned off in the TouchOSC interface.
  //The button is turned on in TouchOSC interface whe the conrol receives this message.
  Udp.beginPacket(Udp.remoteIP(), destPort);
  msgOUT.send(Udp); // send the bytes
  Udp.endPacket(); // mark the end of the OSC Packet
  msgOUT.empty(); // free space occupied by message
}

1.  First we read the value on position zero and assign it to the boolean variable ledState
2. Then we create another OSCMessage object instance for an  outgoing OSC message. This message only has an OSC address assigned but is otherwise empty.
3. Then we turn the LED “on” on the Arduino.
4. The next step fills the msgOUT object with the value of the LED state to be sent back to the TouchOSC button
5. and then a few equivalent messages are printed to the Serial monitor.
6. Then we toggle the LED state for the next go-around.
7. The last 4 lines send the OSC message per UDP to the TouchOSC button.

The second OSC function is very similar and it should be easy to understand now.

Last steps before operating the TouchOSC controls

1. After compiling and uploading the Sketch to your Arduino, turn on the Serial Monitor and wait until it prints the assigned IP
2. Enter that IP address into the “Host” field in the Touch OSC connection configuration screen.

What’s left  to do ?

The last steps exhibit one weakness. This works OK for a breadboard project, but once you have the project installed permanently and not connected to the Arduino IDE and its Serial Monitor it will be rather cumbersome to retrieve the IP address assigned to it, not to speak about it’s port settings . You can assign a static IP but that is also not such a great solution, particularly if you have more than one Arduino project. So what is a nice solution?

On iOS devices TouchOSC supports Apples implementation of ZeroConf configuration networking called Bonjour. If a device advertises/registers for example an OSC service, TouchOSC will discover that service and show it in its configuration screen. This will allow a device to receive an IP per DHCP and whatever IP and port setting the device advertises will be auto-configured by one touch on the TouchOSC interface. Now THAT is a nice solution!

It’s also relatively simple to do with the Arduino Ethernet Bonjour library. However, as that library consumes too much memory on an Arduino Uno it is recommended for boards with larger memory footprints such as the Teensy ++2 or Teensy 3. It should also work nicely on Arduino Mega’s etc. But we’l leave that for another tutorial…

//DHCP-based OSC server test code
//for use with IDE 1.0.5
//for use with W5100 or W5200 based ethernet shields

#include <SPI.h>
#include <Ethernet.h>
#include <EthernetUdp.h>
#include <OSCBundle.h>

// you can find this written on the board of some Arduino Ethernets or shields
byte mac[] = { 
  0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED }; 

// NOTE: Alternatively, you can assign a fixed IP to configure your
//       Ethernet shield.
//       byte ip[] = { 192, 168, 0, 154 };


int serverPort  = 8000; //TouchOSC (incoming port)
int destPort = 9000;    //TouchOSC (outgoing port)
int ledPin =  13;       //pin 13 on Arduino Uno. Pin 6 on a Teensy++2
int ledState = LOW;

//Create UDP message object
EthernetUDP Udp;

void setup(){
  Serial.begin(9600); //9600 for a "normal" Arduino board (Uno for example). 115200 for a Teensy ++2 
  Serial.println("OSC test");

  // start the Ethernet connection:
  // NOTE: Alternatively, you can assign a fixed IP to configure your
  //       Ethernet shield.
  //       Ethernet.begin(mac, ip);   
  if (Ethernet.begin(mac) == 0) {
    Serial.println("Failed to configure Ethernet using DHCP");
    // no point in carrying on, so do nothing forevermore:
    while(true);
  }
  // print your local IP address:
  Serial.print("Arduino IP address: ");
  for (byte thisByte = 0; thisByte < 4; thisByte++) {
    // print the value of each byte of the IP address:
    Serial.print(Ethernet.localIP()[thisByte], DEC);
    Serial.print("."); 
  }

  Udp.begin(serverPort);
}

void loop(){
  //process received messages
  OSCMsgReceive();
} 

void OSCMsgReceive(){
  OSCMessage msgIN;
  int size;
  if((size = Udp.parsePacket())>0){
    while(size--)
      msgIN.fill(Udp.read());
    if(!msgIN.hasError()){
      msgIN.route("/OnOff/toggle1",toggleOnOff);
      msgIN.route("/Fader/Value",funcValue);
    }
  }
}

void toggleOnOff(OSCMessage &msg, int addrOffset){
  ledState = (boolean) msg.getFloat(0);
  OSCMessage msgOUT("/OnOff/toggle1");

  digitalWrite(ledPin, ledState);

  msgOUT.add(ledState);
  if (ledState) {
    Serial.println("LED on");
  }
  else {
    Serial.println("LED off");
  }

  ledState = !ledState;		 // toggle the state from HIGH to LOW to HIGH to LOW ...

  //send osc message back to controll object in TouchOSC
  //Local feedback is turned off in the TouchOSC interface.
  //The button is turned on in TouchOSC interface whe the conrol receives this message.
  Udp.beginPacket(Udp.remoteIP(), destPort);
  msgOUT.send(Udp); // send the bytes
  Udp.endPacket(); // mark the end of the OSC Packet
  msgOUT.empty(); // free space occupied by message
}

void funcValue(OSCMessage &msg, int addrOffset ){

  int value = msg.getFloat(0);
  OSCMessage msgOUT("/Fader/Value");

  Serial.print("Value = : ");
  Serial.println(value);

  msgOUT.add(value);

  Udp.beginPacket(Udp.remoteIP(), destPort);
  msgOUT.send(Udp); // send the bytes
  Udp.endPacket(); // mark the end of the OSC Packet
  msgOUT.empty(); // free space occupied by message
}