Вы находитесь на странице: 1из 11

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:
Technical Note P14-04A
Page 2 of 11 Custom Panel to Control Yamaha 01V96 Audio Deck
DashBoard App. StereoScope Yamaha Deck
OSC over
UDP
MIDI 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 Loopback
OSC over
UDP
Emulated
MIDI
DashBoards view of The Deck
Yamaha Studio
Manager
Emulated
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.
Technical Note P14-04A
Page 3 of 11 Custom Panel to Control Yamaha 01V96 Audio Deck

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.
Technical Note P14-04A
Page 4 of 11 Custom Panel to Control Yamaha 01V96 Audio Deck

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.
Technical Note P14-04A
Page 5 of 11 Custom Panel to Control Yamaha 01V96 Audio Deck

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:
Technical Note P14-04A
Page 6 of 11 Custom Panel to Control Yamaha 01V96 Audio Deck

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 <Add another> icon. This brings up a wizard that tries (and will fail) to automatically detect
DashBoard, so click the <Next> 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.
Technical Note P14-04A
Page 7 of 11 Custom Panel to Control Yamaha 01V96 Audio Deck
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.
Technical Note P14-04A
Page 8 of 11 Custom Panel to Control Yamaha 01V96 Audio Deck
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
padding
Parameter value,
1.0 shown in
IEEE 754 format

Figure 11 - OSC Example Protocol Data Unit
Technical Note P14-04A
Page 9 of 11 Custom Panel to Control Yamaha 01V96 Audio Deck
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
Technical Note P14-04A
Page 10 of 11 Custom Panel to Control Yamaha 01V96 Audio Deck
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 jnaylor@rossvideo.com

Technical Note P14-04A
Page 11 of 11 Custom Panel to Control Yamaha 01V96 Audio Deck
4 Acknowledgements
Id like to thank Roland Jensen of StereoKrauts for creating Stereoscope, and helping me get this
integration working.

Вам также может понравиться