Ipsoncompact OpenSoundControl explained    

  OSC communication setup [explains how the commincation between IpSon and computer works]
  IpSonCompact OSC strings explained [explanation of the OSC messages (strings)]
  UDP Versus Open Sound Control (OSC) [difference between UDP and OSC]

Max/Msp / Pure Data and IpSonCompact OSC explained

  Max/Msp and OSC read from IpSonCompact [basics of reading compact OSC information into your computer]
  Max/Msp and OSC write to IpSonCompact [How to write to your IpSonCompact
  IpSonCompact Max test-patch Max4.6 [explanation of the in's and out's of the IpSonCompact test-patch Max 4.6]
  Ipsoncompact Test patch Max5/Max6 [explanation of the in's and out's of the IpSonCompact test-patch Max 5/Max6]
  IpSonCompact PureData (PD) test patch [explanation of the in's and out's of the Pure Data test patch]
  IpSonCompact Super Collider example [getting started with SC]

How to Configure / Drive the IpSonCompact

  Switching on/off the distance measurement [example]
  Switching and configuring the timing [example]
  Setting the Thresholds [example]
  Driving the Ouputs [example]


IpSonCompact OSC Communication setup

The IpSonLab and IpSonCompact both use Open Sound Control for communication. In this chapter we explain how this works for the Compact. For more detailed information (general protocol) about Open Sound Control (OSC), check out the website of Berkely. http://www.cnmat.berkeley.edu/OpenSoundControl


Both the IpSonlab and the IpSoncompact do send high speed data to the net; when travelling over the net, the UDP protocol is used. Both inside the computer and the IpSonLab, the OpenSoundControl (OSC) protocol is used to exchange data. The 10 bit sensor values (13 times), distance (3 times) and digital inputs (4 times), are all packed together into one OpenSoundControl message, which starts always with /ic (slash ic, short for IpsonCompact).
The string looks like this:
The OpenSoundControl protocol uses 32 bit comminucation. This means that the data packages send to and from port to port, are always 32 bit wide and can be divided into 4 packages of 8 bit (= 4 x 1 byte ). The IpSoncompact sends 10 (or 12) bit sensor values. For sending and receiving at a high rate, two sensor values are being packed into one 32 bit OSC integer; as can be seen in the figure above.
For extracting the data and getting the right readings within the computer (Max/Msp, Super Collider), it is nessecary to unstuff the incoming string. First by using the [osc-route /ic] object, to rertrieve the right string.(the lIpSonCompact is sending much more data!). The last databyte (FF) is for internal use.

The two 10 bits sensor values, packed into one OSC integer, have to be unpacked: When shifting the total string 16 bits to the left, anding (logic) with 1023 , gives the right value for (for example) an0. For getting value an1, anding with 1023 will do fine (left figure). When you want to unpack the 8 bit values (e.a. time0, time1, time2 and digital input) you have to unstuff it into 4 values; right figure.
unstuff_1_2 unstuff
The unstuffing is actually bit-shifting (place the bits in the right position). Incoming data (osc integer) is been triggered four times (t i i i i). The outputs are bitshifted. The outlets generate four independent 8 bit numbers.


IpSonCompact OSC strings explained

The IpSonCompact sends and receives OSC data from/to your computer. The IpSonCompact can also be configured (adjusted) to work at the right speed and with the right input thresholds. To drive the 14 outputs, the IpSonCompact can convert incoming OSC data into Pulse Width Modulation (PWM) or just on / off information (0V /5V). Here an explenation of the different OSC string setups used. All messages from and to the IpSonCompact do have the same length (standard OSC header information with 9 osc integers, so 36 variables).
/ic ,iii iiii ii00 [an0, an1]...[an12,[digital,time0]] [time1, time2, 30,31] [ 32,33,34,FF]
As shown above, this is the main data stream, sending the 12 bits sensor information, 4 digital inputs and the three distance measurement values.
an0 -an12 Analog input [adresH adresL] 10 bits right adjusted
4 x digital input (1 byte): bit 0-3: bit 0 = in0, bit1 = in1, bit2 = in2, bit3 = in3
3 x time (distance) information time0, time1 time2
rest is still emty (future use)

Configuration string setup
/cf ,iii iiii ii00 [th0,th1,th2,th3]..[th12, timer, distance , 15] [pwma, pwmb, 18, 19] [20..23]..[32 ..35]
The /cf string sends the configuration to the IpSonCompact. It consists of the 13 threshold values, the timer settings, distance measurement on/off and the pulse width modulation settings. The numbers indicate that these bytes are not in use (yet) and should be set to zero (0).
th0-th12: Threshold is a 8 bit value(0-254) adjusting the threshold per analog input.
timer: Sets the sample time used for all inputs. Bit3 turns the timer on/off.
The sample-time is set with bit0, bit1 and bit2. Check the values below:
000 17.8 msec = 0.0178 sec  <> 56Hz
001 35.5 msec = 0.0355 sec <> 28Hz
010 71.1 msec = 0.0711 sec <> 14Hz
011 142.2 msec = 0.1422 sec <> 7Hz
100 284.4 msec = 0.2844 sec <> 3.5Hz
101 589.9 msec = 0.5899 sec <> 1.7Hz
110 1137.8 msec = 1.1378 sec <> 0.88Hz
111 2275.0 msec = 2.275 sec <> 0.43Hz
distance: sets the distance measurement on in0, in1 and in2. So the SRF05 distance measurement can be directly connected to the input of the processor.
bit 0 bit0 = 0 distance measurement is Off. Bit0 = 1, measurement in On
bit 1 not in use
bit 2 not in use
bit 3 not in use
bit 4 not in use
bit 5 bit5 = 1 :input 0 (in0) is used for distance measurement
bit 6 bit6 = 1 :input 0 (in1) is used for distance measurement
bit 7 bit7 = 1 :input 0 (in2) is used for distance measurement
pwma pwmb:
pwma bit 0-6 sets which ouput has Pulse Width Modulation (bit=1, pwm is on, bit = 0, pwm is off)
pwmb bit 0-6 sets which ouput has Pulse Width Modulation (bit=1, pwm is on, bit = 0, pwm is off)
Both pwma and pwmb bit 7 have to be 0 (pwma.7=0 and pwmb.7=0)
Status request string
/st ,iii iiii ii00 [0,0,0,0] ...[0,0,0,0] ... should be exactly 36 variables
When the /st string is sent to the IpSonCompact, the actual status of the interface will be sent back in the /cr string. This string has the same setup as the /cf string. In this way you can check the settings of the threshold, and switches when the device was turned on/off.
Configuration return string
/cr ,iii iiii ii00 [th0,th1,th2,th3]..[th12, timer, distance , 15] [pwma, pwmb, 18, 19] [20..23]..[32 ..36]
The /cr string (configuration return) does give the acutal status of the IpSonCompact return. The /cr string is identical to the /cf (configuration) string
Data output string
/ut ,iii iiii ii00 [out0, out1, 2, 3] [pwm0,pwm1 pwm2,pwm4] ..[pwm12 pwm13,18,19] [20-23] [32-35]
When sending this string to the IpSonCompact, the values will be used to adjust the outputs (pulse width modulation and/or the digital ouputs). When pwm is active on an output, the digital value on this output will be ignored.
out1, bit 0 out 0 (on pcb) pwm0 [pwma, bit 0 in configuration string (/cf)]
out1, bit 1 out 1 pwm1 [pwma, bit 1 in configuration string (/cf)]
out1, bit 2 out 2 pwm2 [pwma, bit 2 in configuration string (/cf)]
out1, bit 3 out 3 pwm3 [pwma, bit 3 in configuration string (/cf)]
out1, bit 4 out 4 pwm4 [pwma, bit 4 in configuration string (/cf)]
out1, bit 5 out 5 pwm5 [pwma, bit 5 in configuration string (/cf)]
out1, bit 6 out 6 pwm6 [pwma, bit 6 in configuration string (/cf)]
out2, bit 0 out 7 pwm7 [pwmb, bit 0 in configuration string (/cf)]
out2, bit 1 out 8 pwm8 [pwmb, bit 1 in configuration string (/cf)]
out2, bit 2 out 9 pwm9 [pwmb, bit 2 in configuration string (/cf)]
out2, bit 3 out 10 pwm10 [pwmb, bit 3 in configuration string (/cf)]
out2, bit 4 out 11 pwm11 [pwmb, bit 4 in configuration string (/cf)]
out2, bit 5 out 12 pwm12 [pwmb, bit 5 in configuration string (/cf)]
out2, bit 6 out 13 pwm13 [pwmb, bit 6 in configuration string (/cf)]


UDP Versus OSC

UDP, the "User Datagram Protocol," is the Internet Protocol for sending packets (a.k.a. "datagrams") between machines without establishing a connection between the machines and without any expensive mechanism for detecting lost packets and retrying them. UDP is used for streaming video and audio and many other applications on the Internet.OpenSound Control is an application-level protocol. OSC defines only the bit format and interpretation of those bits; you could transmit OpenSound Control messages via UDP, TCP, shared memory, compact disc, or any other digital protocol.Because UDP can be used to transmit many kinds of data besides OSC, and because OSC can be transmitted by many kinds of networking technology besides UDP, our implementation puts the UDP part and the OSC part in separate objects. People have used the OTUDP object without the OpenSoundControl object to send and receive data in formats other than OSC. (This requires writing a max external to translate between Max data and binary data in the non-OSC format.) People have used OpenSoundControl without UDP as a sort of super pack/unpack, to be able to pass entire OSC bundles as single Max messages.Nevertheless, the main use of both the OTUDP and OpenSoundControl Max objects is to use them together, as shown by the help patches


Max/Msp OSC explained.

To make it easier to create your own patch for reading the IpSonCompact values and writing to the IpsonCompact, the patches are explained here step by step. The patches as shown here below, can be downloaded from this website
Reading the sensors  

Assuming that you configured your IpSonCompact to send the OSC strings to port 8000, you start your patch with reading port 8000. In the example on the right, I used the otudp read object. There are more udp objects around, depending on which Max/Msp version you work with and what kind of computer you have (Intel / PowerPC). I still work with Max/Msp version 4.5.4. on a powermac G4. You can download all the objects from the Berkely website. Check it out. For checking the communication, you can connect a print object to the output of the udp read object and see wether data is flowing in.

The output of the otudpread object is connected to the opensoundcontrol object. The osc-route object is used to filter the data. On the left outlet all data with /ic in the header will be put out. The middle output for /cr. The right outlet is not used for the IpSonCompact.

Below the complete patch to read all 13 analog input values of the IpSonCompact. The sensor values are packed into one OSC string, with /ic in the header. The /ic output of the osc-route object has to be fully unpacked, as shown below. The 9 outlets of the unpack object represent the 9 times 32bit OSC integers (9 times an i). From that point the actual OSC string has to be 'bit-shifted'.First it has to be triggerd twice (one OSC string consists of 2 sensor values). This is done with the "trigger object" (t i i). The 16 bits on the left have to be shifted to the right and 'anded' with 1023. The 16 bits on the right only have to be 'anded' with 1023. Anding means that you filter out all unused bits of the string. Now we have the acual analog value of the connected sensor.

In case of using the newer chip, the PIC18F4523, the sensor values will have a 12 bit resolution. This means that the actual values have to be anded with 4095 instead of 1023.


Reading the distance and the switches
For reading the distance values (srf05) and the switch values, the other osc integers have to be unpacked. These values do have a resolution of 8 bit. So within a 32 bit OSC integer, 4 values can be packed and unpacked. In this case 8 bit 'bit-shifing' is used. When the values are 8 bit wide, they have to be anded with 255. sw_dist


Reading the configuration  
Reading the configuration of the IpSonCompact is done through reading out the /cf string. The contents of this string is a representation of the settings within the IpSonComacp processor (flash memory). The values are 8 bit, thus anding with 255 is sufficient to get the right value.


Writing to the IpSonCompact
When you write values to the IpSonCompact, these values will be converted into switch on/off (+5v or 0V on an output) or Pulse Width Modulation (PWM). From wtihin Max/Msp you have to send your strings to the 'udpwrite' object. Also the use of this object depends on the version of Max/Msp that is being used and the machine you work with (intel or powermac).
Within this object you have to define the IP address and port number of the IpSonCompact (the device you send your data to). Be aware that you send to the right ip address and port number.


Writing the IpSonCompact Switches and Pulsewidth Modulation
Writing data to the IpSonCompact is done with the patch below. The 8 bit values (0-255) have to be packed into an OSC string, which the IpSonCompact can understand and convert to switch On/Of or PWM. This string has /ut in the header. As explained in the OSC string setup, the string consists of 13 pwm values and two 8 bit words, out0 and out1.

The seperate 8 bit words have to be packed into nine 32 bit words (the OSC integers). By shifting the bits in the right position and anding them togehter, a 32 bit word can be created. In the patch below only 5 integers are created and packed together in one OSC string, with a /ut header. With a trigger object, the whole /ut string is send out to the opensoundcontrol object.

Writing the Configuration to the IpSonCompact
If you want to configure or adjust the IpSonCompact, you have to send the configuration string.  From left to right the first 13 inputs are the threshold values (an0..an12). These values are 8 bit wide. Again this is realised with bit shifting the byte into the right place, making one 32 bit integer. All nine 32 bit integers (not all of them are in use in this string) are packed into one OSC string, with a header /cf.
When this string in send to the IpSonCompact, the values will be stored within the processor and it will reply with a confirmation string (/cr).

IpSonCompact test Patch (Max version 4.5)

With this patch you can fully control the IpSonCompact interface (Max version 4.x). Newer version, check below.

OSC communication
In the left upper corner, you can see the [otudp-read 8000] object. This max-object (part of max 4.5.x] reads the incoming data on local port 8000 (the port where the IpSonCompact is streaming it's data to.

In the corner left down, the [otudp-write 10001] max-object is placed. This object sends all streaming data coming from the patch to ip address, port 10001. This is ofcourse the port of the IpSonCompact.

Analog sensor input
The darkgrey block in the middle represents the microcontroller (pic18f4420) chip on the printed circuit board; it actualy has the same pinout. The yellow numberboxes represent the incoming sensor data (0-1024). The 'gray boxes above can be changed; it represents the threshold of that input. When this values is changed, it should be 'SET' by pressing (clicking) the SET button on the left.

Distance measurement
The green number boxes represent the distance measurement values (only in0, in1 and in2) and the digital input (4 switch values of 0/1). In case of switch in/out, the little yellow led indicators, will light up when a switch is pushed. When the configuration is made active for using three distance sensors, the green number boxes will show the 8 bit value.

IpSonCompact configuration
In the little gray block in the left corner, adjustments can be made for the timing of the sample rate and switching on/off the distance measurment on in0, in1 and in2. For the values, check the tables on this page. Every change made, should be followed by a click on the SET button. This sends the /cf string to the IpSonCompact. By sending the /cf string, the IpsonCompact always responds with the values set within the eeprom. The values are displayed within the 'pink' number boxes. In this way you can always verify whether the processor does have the right values set.

Driving Ouputs On/Off or Pulse Width Miodulation
With the 14 faders, 8bit values can be send to the IpSonCompact which will be converted into pulse width modulation signals. Now, the outputs can drive all kind of processes (like light, dc engines and lots more). Whether the output is on/off or pwm, is determined by the settings of the button right underneath the faders. By clicking on the red 'switches' the outputs can be set 'high (=5V) or 'low' (=0V).

The little gray block in the middle does have 3 buttons. With status, the acual status can be 'requested' of the IpSonCompact. The mute all button, does 'mute' all the outputs to zero. With the recall button, the status of the IpSonCompact can be requested; you can use this feature right after you switch on the IpSonCompact and you do want to restore the latest values used.

Connecting Inputs and Outputs
We are working on a version where the inputs can be connected to the outputs within a matrix. In this way you can easily drive processes and make nice feedback.


Testing the Ipsoncompact.

The patch shown below can be downloaded from this website. With this patch you can test all the different features of the Ipsoncompact. It will also run as stand alone application; so if you do not have Max/Msp installed, you still can test your Ipsoncompact.
The button UDPOSC in the middle switches between an older and newer version of the compact firmware. In the old version (OSC mode) the firmware is configured to work with the 'opensound control object' that was needed in the older versions of Max/Msp (Version 4 and older).  From Max/Msp version 5, the opensoundcontrol object was not needed anymore and the OSC string buildup as changed.

On the right side the 13 sensor inputs can be monitored and the threshold values per input can be set. On the left side the outpuyts can be activated. The button DIG/PWM switches between the PMS and Digital  mode. The small fader underneath is only activated in the PWM mode. In the right corner below, the distance measurement can be switched On/Off. In the middle the timer can be activated. The three small buttons below the "timer off" set different values for the timer.



Pure Data Test patch
To make it easier to create your own patch for reading and writing to the IpSonCompact with PureData freeware, there are some examples of the setup used within the pd-patch explained here.

Assuming that you configured your IpSonCompact (xport) to send the OSC strings to port 8000, you start your patch with reading port 8000. On the right a example of how to read port 8000 with PD. The output of the dumpOSC object is filtered with OSCroute /ic and OSCroute/cr. The ouputs of the route objects are sent to the right location within the patch, to extract all data.

For the first initial read, the connection has to be made with the IpSonCompact. When the object 'connect' is pushed, the connection will be made. The IP-address within the object is the address of the IpSonCompact.

Sending output- or configuration information to the IpSonCompact, should be down as shown on the right. The IpSonCompact expects an OSC Bundle. This can be realised with the brackets [] on the beginning and the end of the message, with the comma's as separation. We found out that we have to send the strings this way, otherwise the IpSonCompact can not understand the incoming OSC data. The object underneath is the PD send object: used to send the string information to the sendOSC object.

Check out the testpatch which can be downloaded at the


OSC from Ipson to SC / Getting sensor input in to SuperCollider


// check and configur the network connection between computer and Ipson

follow instructions in the Ipson manual.

Make sure that your computer (remote host) is in the same IP range as the Ipson.
Go to System Preference -> network check the Ethernet is connected.

SC listens to port number 57120 by default,
use the web browser to set the output port (remote port) of the Ipson to 57120

// Boot internal Server
Server.default = Server.internal;

// enter IP and local port of the Ipson
~ipson = NetAddr("", 10001);

// Create control busses to write the sensor data to:
~firstInputBus  = Bus.new('control', 1, 1);
~secondInputBus  = Bus.new('control', 2, 1);

// Create GUI to view the input
var window = SCWindow.new("inputGUI",Rect(655, 431, 200, 300)).front;
~firstInputSlider = SCSlider.new(window,Rect(10, 20, 38, 194))
.action_{|v| };
~secondInputNumber = SCNumberBox.new(window,Rect(75, 200, 100, 20))
.action_{|v| };

// The OSCresponder bellow listens to incoming OSC messeges from ~ipson, unpacks, and sends data to control bus and gui.
// use & 1023 for the 10bit chip, use & 4095 for the 12bit chip
a = OSCresponder(~ipson ,'/ic', {arg time, r, msg;  // change ~ipson to nil to recive OSC from any IP address
var analog0, analog1, analog2, analog3;

// msg.postln ; // post the raw OSC massage as recived from the Ipson

analog0 = (msg[1] >> 16)  & 4095; // data from first analog input
analog1 = msg[1] & 4095 ; // data from second analog input
analog2 = (msg[2] >> 16) & 4095;
analog3 = msg[2] & 4095 ;

analog0.postln;  // post the first sensor data 

~firstInputBus.value_(analog0); // write data 1 to bus 1

~firstInputSlider.value_(analog0/4095); ~firstInputSlider.refresh;
~secondInputNumber.value_(analog1.round(0.001)); ~secondInputNumber.refresh;
}.defer;  // defer to GUI


a.remove; // remove OSCresponder

Switching On/Off distance measurement 
When you want to switch On/Off the distance measurement, you have to send the /cf string to the IpSonCompact. The example above shows the setup of the total string and the setting of the distance byte. In the example above, distance on in0 and in2 is active; in1 is not active. Check the table below:
  b0 b0 = 0 distance measurement is Off. Bit0 = 1, measurement is On ... This is the Master switch!
  b1 not in use
  b2 not in use
  b3 not in use
  b4 not in use
  b5 bit5 = 1 :input 0 (in0) is used for distance measurement ;bit5=0, in0 is NOT in use for distance
  b6 bit6 = 1 :input 0 (in1) is used for distance measurement ;bit6=0, in0 is NOT in use for distance
  b7 bit7 = 1 :input 0 (in2) is used for distance measurement ;bit7=0, in0 is NOT in use for distance

Switching On/Off timer

The speed of sampling the inputs and the distance measurement, can be set by a timer within the IpSonCompact. The string above shows an example of how to switch on the timer, and adjust the time to 35,5mS (so every 35,5mS all inputs are sampled and sent to the remote host). When you want to adjust the values to a lower speed, or switch of the timer (highest speed!), you only have to change these 4 bits. Bit 3 switches the timer On/Off. In the example above, the timer is set ON, with a timing of 35,2 mS. Check also the table below:


b3 switches timer On/Off b2 b1 b0 time
  000 17,8 msec
  001 35,5 msec
  010 71,1 msec
  011 142,2 msec
  100 284,4 msec
  101 589,9 msec
  110 1137,8 msec
  111 2,275 msec


Setting the thresholds

As shown in the example above: just put the values you want to use for your threshold on the right location within the string and send it to the IpSonCompact. In the example the threshold value 12 will be stored for analog input 0 and the value 20 for analog input 1.


Driving the Outputs

When you want to drive one or more outputs, you have to send the /ut string. The bits within the two bytes out1 and out2 represent the outputs on the IpSonCompact. Sending a '1' means +5V on the output, sending a '0' means 0V on the ouptut. In the example above, the outputs 1-6 are driven 'high' and the outputs 7-13 are driven low. These settings will be overruled when the outputs are configured as Pulse Width Modulation out. This is done in the /cf string, through the bytes pwma and pwmb.