dashboard yamaha 01 v 96 tech note

Technical Note P14-04A

Page 1 of 11 Custom Panel to Control Yamaha 01V96 Audio Deck

Technical Note: Custom Panel to Control Yamaha 01V96 Audio Deck

Author: John R. Naylor

DashBoard Marketing Product Manager Date: April 28, 2014

1 Introduction One of the key features in DashBoards most recent release (version 6.1) is the ability to send and

receive messages over Ethernet. This means that we can say, with some poetic license, if a device has an

Ethernet port, its likely controllable from DashBoard. At Ross Video, we use the Yamaha 01V96 deck for

product demos, and, because I was able to get access to one, I decided to explore this new feature by

building the simple control panel described in this Tech Note.

Gaining control over devices via Ethernet requires the programmer to understand the devices control

protocol, and handle its responses and exceptions. Ross Video cannot provide support end user support

for integrations of this type, but will provide appropriate assistance to programmers engaged in creating

them via tutorial videos, and publications like this one.

The integration documented here shows how DashBoard can control the fader and channel on/off

settings of the decks first 16 channels. Extending it to control the decks other features is an exercise for

the reader but if you do this, please consider sharing it with the growing DashBoard Custom Panels

community.

2 Technical Details The deck I used actually doesnt have an Ethernet port, it has a USB port that a host PC can use for MIDI

integration. So I found and used an application called Stereoscope which flips USB MIDI to and from

messages in Open Sound Control (OSC) format to a user-nominated UDP port. A system diagram helps:



DashBoard App. StereoScope Yamaha DeckOSC over

UDPMIDI over

USB

DashBoards view of The Deck

Figure 1 - System Diagram

The neat thing about using the Stereoscope App is that multiple devices can be used to control the deck

by using different port numbers when communicating with Stereoscope. For example, theres an App

called TouchOSC that, via Stereoscope, turns a handheld device such as an iPhone into a deck

controller over WiFi.

If you dont have access to a real 01V96 deck, you can use Yamahas Studio Manager to emulate one on

your PC. The system diagram for this is only a little more complicated.

DashBoard App. StereoScope Midi LoopbackOSC over

UDPEmulated

MIDI

DashBoards view of The Deck

Yamaha Studio

ManagerEmulated

MIDI

Figure 2 - Alternate System Diagram Using Deck Emulator

Im going to cover both scenarios in this document, the tutorial video that accompanies it demonstrates

the emulated version.

2.1 You will need

Item Supplier Notes

DashBoard 6.2 Beta Ross Video, Ltd I got an earlier version of this working in 6.1,

but the message builder feature in 6.2 makes things so much easier.

StereoScope StereoKrauts GbR The app enables the first 4 channels in demo

mode. Version 2.

Loop MIDI Tobias Erichsen Only needed for the emulator mode

01V96 USB Driver Yamaha Version 3.0.4

01V96 Studio Manager Yamaha Version 2.3.1. Only needed for the emulator mode

Please follow the installation instructions for the packages listed above carefully.



2.2 You should know

Item Resources

Basic PanelBuilder Scripting PanelBuilder 105 at DashBoard-U

Using Functions in PanelBuilder PanelBuilder 203

Using Network Listeners in

PanelBuilder

PanelBuilder 204

JavaScript W3 Schools

Open Sound Control OpenSoundControl.org

Note that the integration documented has worked on Windows 7.1 Pro 64 bit, and Windows 8.1 64 Bit. It

should work on other supported platforms but Ive not done this and, regrettably, cannot offer support

should you encounter difficulties on Mac OS X or Linux.

2.3 Try the App First

2.3.1 Emulator Mode

2.3.1.1 Run and Configure Loop Midi

Launch the Loop Midi program, and set up two virtual MIDI ports thus:

Figure 3 - Configuring Loop MIDI

You can minimize this, or leave the window open and see the data counters update to get reassurance

that there is traffic crossing these interfaces.

2.3.1.2 Run Studio Manager, and Connect the Emulated Deck to the MIDI Ports

First launch Studio Manger.

If necessary, add the 01V96 to the workspace from the File->Setup menu.



Figure 4 - Adding the 01V96 to System Manager's Workspace

Studio Managers Workspace should now look like this:

Figure 5 - Studio Manager with 01V96 Installed

Now double-click the deck icon in Studio Manager and use the File->System Setup menu option to

bring up this dialog. Set the MIDI ports as shown.



Figure 6 - Setting up MIDI for Studio Manager

2.3.1.3 Launch and Configure Stereoscope

Launch the Stereoscope application and double click the picture of the Yamaha 01V96 deck in the pane

to the left of the window.

Figure 7 - Launch Stereoscope

Youll be prompted to set up the MIDI ports, make sure that they match the settings for the deck as

shown below:



Figure 8 - Setting up Stereoscope's MIDI Ports

Now that you have connected Stereoscope to the deck, you connect DashBoard to Stereoscope by

clicking the icon. This brings up a wizard that tries (and will fail) to automatically detect

DashBoard, so click the button to show the dialog shown below in which you provide the IP

address and port information as shown.

Figure 9 - Connecting DashBoard to Stereoscope

The demo panel assumes that its running on the same host as Stereoscope which is why the IP address shown here is the home

one of 127.0.0.1. Should you wish to run the DashBoard panel on a different machine, youll need to enter its IP address in this

dialog, and modify the custom panel to send messages to the IP address of the machine running Stereoscope, rather than

localhost.



Now launch DashBoard, and the custom panel called Sterescope.grid that is available for download

from www.rossvideo.com.

You should be able to update the emulated deck from DashBoard, and the Custom Panel from the deck.

Sometimes an initial nudge from the deck is required to establish bi-directional control.

You may also find that the fader positions and channel On states dont initially match. Pressing each

button and nudging each fader in turn will bring them into alignment.

Figure 10 - All Working Together

Above is a screengrab of my desktop with all four packages running. There is bi-directional control

between the emulated deck and the custom panel.

2.3.2 Using a Real Deck

Using a real deck is a little simpler than using the emulator as long as you have access to a deck!

Theres no need to run LoopMIDI, or Studio Manager.

Configure the deck to use MIDI channel 1 for input and output, and set up Stereoscope to do the same.

The set-up procedure can be accessed from the Help->Documentation menu option in the Stereoscope

App.

2.4 How the Custom Panel Works

To move faders, and turn channels on and off, the Custom Panel sends OSC messages via UDP to

Stereoscope.



Stereoscope relays status updates from the deck as OSC messages via UDP. The Custom Panel receives

these using a UDP listener on port 8001.

Sending and receiving messages is straightforward. Building and parsing OSC messages represents the

majority of the complexity in this panel, but is by no means difficult, mainly because only a fraction of

OSC is actually used.

2.4.1 Open Sound Control (OSC) Messages

Its beyond the scope of this note to explain the OSC protocol and whats documented here is simply an

example usage that has been found to work. It does not mean that this is the best or cleanest way to use

OSC.

2.4.1.1 Fader and Channel State Control

The status for fader 1 is represented in OSC by this UTF-8 string:

/stereoscope/input/1/level

And channel on/off status by this one:

/stereoscope/input/1/channelOn

These are null terminated, and padded with more nulls as needed to make the length of the string plus

nulls in divisible by four.

It is followed by a format specifier which is the comma character, and then f for float data, or s for string

data. There are other format specifiers covered by the OSC specification, and it is possible to

communicate, say, a pair of floats by using ,ff as the format specifier.

The format specifier is also null terminated, and padded out to a whole number of 4 bytes.

It is followed by the value of whatever state is being communicated.

Thirty-two bit floats are the only data type used by the Custom Panel. Although some string data is

received, it is not used.

s t e r e o s c o p e / i n p u t / 1 / l e v e l 0 0 0 , f 0 0 3f 80 00 00

Null terminator for command string, followed by padding

Format descriptor followed by null terminator and

paddingParameter value,

1.0 shown in IEEE 754 format

Figure 11 - OSC Example Protocol Data Unit



The programming task, then, is to create, and parse data that conforms to this protocol. This can be

pretty challenging in javascript which only has native support for 64 bit floating point numbers, and has

no support for arrays of bytes!

2.4.2 Building Messages with ogScript.messageBuilder

These shortcomings of JavaScript have been addressed by adding some new methods and objects to

DashBoards ogScript.

One of these is the messageBuilder object that provides these methods to append various types of data

to a byte array.

Table 1 - messageBuilder Methods

Method Description Bytes Added var messageBuilder = ogscript.createMessageBuilder();

Constructor

messageBuilder.writeByteArray(bytesArray); Appends an array of bytes Length of bytesArray messageBuilder.writeByteArray(bytesArray, offset, length);

Appends bytes from the array

passed from offset for length

length argument

messageBuilder.writeBoolean(boolVal); Appends 0x00 if true, 0x01 if false

One

messageBuilder.writeByte(byteVal); Appends a single byte One messageBuilder.writeShort(shortVal); Appends 16 bit integer as two

bytes

Two

messageBuilder.writeChar(charVal); Appends a Unicode character Two messageBuilder.writeInt(intVal); Appends a 32 bit integer Four messageBuilder.writeLong(longVal); Appends a 64 bit integer Eight messageBuilder.writeFloat(floatVal); Appends a 32 bit float Four messageBuilder.writeDouble(doubleVal); Appends a 64 bit float Eight messageBuilder.writeString(strVal); Appends string Length of string messageBuilder.writeUTF(strVal); Converts string to UTF-8 and

appends it to payload. Includes the 2 byte length

count.

Length of string x 2 + 2

var bytes = messageBuilder.toByteArray();

Used to pass the message that has been built to the client

app.

Look at the functions updateFader and updateChannelOn in the Custom Panel to see messageBuilder in

practical use.

2.4.3 Parsing Messages with JavaScript and ogScripts MessageParser

The UDP listener in the Custom Panel gets the UDP packet as both a JavaScript string, and an array of

bytes, which is an exact copy of what was actually received.

var bytes = event.getBytes(); // gets the literal contents of the UDP packet var parser = ogscript.createMessageParser(bytes); // constructs our message parser from the bytes var message = event.getBytesAsString(); // converts the UDP packet to a JavaScript string var osc = message.split('/'); // which we can now split into an array of strings



The reason for doing this is to use the split method that JavaScript strings provide. By splitting on the /

character, its pretty easy to parse the textual content of the message.

Table 2 - MessageParser Methods

Method Description var messageReader = ogscript.createMessageParser(messageBytes);

Constructor pass it the bytes to parse

var byteArray = messageReader.readBytes(length); Read a number of bytes from the message messageReader.skipBytes(length); Skip a number of bytes var boolVal = messageReader.readBoolean(); Interpret next byte as a Boolean var byteVal = messageReader.readByte(); Get value of next byte var byteVal = messageReader.readUnsignedByte(); As above, but byte is unsigned var shortVal = messageReader.readShort(); Read a 16 bit integer var shortVal = messageReader.readUnsignedShort(); As above, but unsigned var charVal = messageReader.readChar(); Read in a character var intVal = messageReader.readInt();

Read a 32 bit integer

var longVal = messageReader.readLong(); Read a 64 bit integer var floatVal = messageReader.readFloat(); Read a 32 bit float var doubleVal = messageReader.readDouble(); Read a 64 bit float var str = messageReader.readUTF(); Read a UTF 8 string, also consumes the 2

length bytes. var str = messageReader.readString(length); Read a regular string

Note that messageParse maintains a pointer to the next byte in the message array. This pointer is

incremented by one for every byte consumed by calls to the various read methods.

The Custom Panel illustrates a practical use of the skipBytes and readFloat methods.

2.4.4 deciBels and Normalized Position

In creating this panel, I discovered that the fader position is what gets reported as state, and is used to

control position of a fader. The position ranges between zero at the bottom and one at the top. The

mapping to deciBel values is NOT linear. So I created a couple of functions to convert between dB values

and fader position. This is necessary because the slider widgets supported in DashBoard are linear.

See the functions dBToPos, and posTodB in the source code. This is why, when you look at Figure 10

closely, the fader positions dont seem to match between the Yamaha deck emulator and the Control

Panel.

3 Further Reading Open Sound Control Protocol www.opensoundcontrol.org

You can also contact me, John R. Naylor, by email at [email protected]



4 Acknowledgements Id like to thank Roland Jensen of StereoKrauts for creating Stereoscope, and helping me get this

integration working.

dashboard yamaha 01 v 96 tech note

Documents