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]|
|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.
|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.|
|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:
|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.|
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.|
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
|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.
|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.|
|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 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.
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.
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.
|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|
|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|
|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.|
|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.|