Release name: OSC
Release summary: Enhancements, fixes & new tests to support bundles, intensive input & the Tuio protocol for Reactivision
Automatic version: 5
Manual version: 5.1
Published by: Simon Holland (SimonHolland)
Created: 3 October 2007 11:56:20 am
Last updated: 3 October 2007 7:58:24 pm
Release note:

Fixes and Enhancements
OSC has been enhanced to deal with bundles, intensive input, and the Tuio protocol. Various bug fixes and new unit tests have been added. OSC now supports tangible user interfaces such as Reactivision. No changes are required for clients. New features are as follows.

1 Bundles processed fully
When several incoming messages arrive in a single bundle, or more than one bundle arrives at once, all messages are now parsed. This involved changes to the OSCParser method parse: and to the OSCServer message receive: This necessitated changes to three parser unit tests, and one new unit test.

2 Word boundaries treated correctly in string arguments.
The method parseString in OSCParser now only consumes trailing nulls (after the null that terminates the string) if this is needed to reach a 32-bit word boundary, as per the OSC specification. This avoids problems where subsequent integers, floats etc in messages could be corrupted. A second new unit test was added.

3 Incoming OSC buffers resized to cope with high volume input. Incoming OSC packets of 940 bytes and larger are routinely sent by Reactivision. The incoming String and RWBinaryOrTextStream buffers in OSCServer listenOnPort: have been resized to cope with high volume incoming traffic.

4 OSCServer processing balanced.
In some circumstances, the looping background UDP read thread in OSCServer listenOnPort: can monopolise the processor, preventing other threads from processing the input in timely fashion. The method receive: in OSCServer has been given a delay to allow upstream processes to get adequate processor time. An instance variable responsePeriod measured in milliseconds has been added to OSCServer, and initialised in initialize to allow this delay to be tuned conveniently for different applications. In the case of applications of Reactivision, a 10 millisecond delay is a suggested starting point. This delay can be set to zero where not needed.

5 Bug fix to prevent exception in parseHeader in OSCParser
OSCParser was erroneously testing for a character in a binary stream and throwing an exception. The method parseHeader in OSCParser has been amended to put the stream into ascii mode at the crucial point.

6 Minimal measure to ignore blobs more gracefully.
A dummy method has been added to ignore blobs, rather than throwing an exception. If a blob message is spuriously recognised as a result of a glitch (which occasionally happens), it is very likely to be the last or only message in the bundle, so that this rudimentary measure will allow it to be discarded without causing an exception. A future version could be coded to handle blobs properly, or raise and handle an appropriate custom-designed exception.

Summary of changes
a) One new, and two revised, instance methods for OSCParser

b) One revised class method for the OSCParser

c) Three revised instance methods for OSCServer.

d) Five revised unit tests
OSCParserTest testParseIncreaseVolumeMessage
OSCParserTest testParseExampleBerkely3Message
OSCParserTest testParse
OSCMessageTest testByteArrayDecreaseVolume
OSCServerTest testSendAndReceive

The first three tests are required by the representation change introduced by (1) above. In the fourth test, the literal array used to represent 0.2 using an IEEE32Bit Float representation has been corrected. In the fifth test (which fails only intermittently as it involves a timing delay), the wait period before reading has been changed from 1 millisecond to 30 milliseconds.

e) Two new unit tests OSCParserTest2 and OSCParserTest3 test the integrity of enhancements/fixes 1-3 and 5. These tests would benefit from being split into several smaller tests, but they are adequate to identify the presence or absence of the relevant behaviours.

Simon Holland
23 Sept 2007

Release homepage:
Download: http://www.squeaksource.com/OSCClient/OSC-SimonHolland.14.mcz
SHA checksum: 618981355350033663658265414444234964477511577794