1152 lines
54 KiB
HTML
1152 lines
54 KiB
HTML
|
|
||
|
|
<!doctype HTML public "-//W3C//DTD HTML 4.0 Frameset//EN">
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
|
||
|
|
|
||
|
|
<meta name="generator" content="Adobe RoboHelp 9">
|
||
|
|
<title>Third-party Control Protocol</title>
|
||
|
|
<link rel="StyleSheet" href="HtmlHelp.css" type="text/css">
|
||
|
|
<style title="hcp" type="text/css">
|
||
|
|
<!--
|
||
|
|
span.hcp1 { font-weight:bold; }
|
||
|
|
table.hcp2 { margin-top:14pt; }
|
||
|
|
td.hcp3 { vertical-align:TOP;
|
||
|
|
padding-left:1px;
|
||
|
|
padding-top:1px;
|
||
|
|
padding-right:1px;
|
||
|
|
padding-bottom:1px; }
|
||
|
|
p.hcp4 { text-align:center;
|
||
|
|
margin-bottom:0; }
|
||
|
|
img.hcp5 { border-width:2px;
|
||
|
|
border-style:solid;
|
||
|
|
margin-top:0px;
|
||
|
|
margin-bottom:0px;
|
||
|
|
margin-left:0px;
|
||
|
|
margin-right:0px; }
|
||
|
|
td.hcp6 { vertical-align:middle;
|
||
|
|
padding-left:1px;
|
||
|
|
padding-top:1px;
|
||
|
|
padding-right:1px;
|
||
|
|
padding-bottom:1px; }
|
||
|
|
td.hcp7 { vertical-align:middle;
|
||
|
|
padding:1px 8px;
|
||
|
|
padding-left:1px;
|
||
|
|
padding-top:1px;
|
||
|
|
padding-right:1px;
|
||
|
|
padding-bottom:1px; }
|
||
|
|
p.hcp8 { margin-bottom:0; }
|
||
|
|
span.hcp9 { font-family:monospace; }
|
||
|
|
span.hcp10 { font-style:italic; }
|
||
|
|
td.hcp11 { vertical-align:TOP;
|
||
|
|
padding:1px 4px;
|
||
|
|
padding-left:1px;
|
||
|
|
padding-top:1px;
|
||
|
|
padding-right:1px;
|
||
|
|
padding-bottom:1px; }
|
||
|
|
td.hcp12 { vertical-align:middle;
|
||
|
|
padding:1px 15px;
|
||
|
|
padding-left:1px;
|
||
|
|
padding-top:1px;
|
||
|
|
padding-right:1px;
|
||
|
|
padding-bottom:1px; }
|
||
|
|
td.hcp13 { vertical-align:middle;
|
||
|
|
padding:0px;
|
||
|
|
padding-left:1px;
|
||
|
|
padding-top:1px;
|
||
|
|
padding-right:1px;
|
||
|
|
padding-bottom:1px; }
|
||
|
|
td.hcp14 { vertical-align:BOTTOM;
|
||
|
|
padding-left:1px;
|
||
|
|
padding-top:1px;
|
||
|
|
padding-right:1px;
|
||
|
|
padding-bottom:1px; }
|
||
|
|
td.hcp15 { vertical-align:TOP;
|
||
|
|
padding:1px 8px;
|
||
|
|
padding-left:1px;
|
||
|
|
padding-top:1px;
|
||
|
|
padding-right:1px;
|
||
|
|
padding-bottom:1px; }
|
||
|
|
td.hcp16 { vertical-align:middle;
|
||
|
|
padding:1px 20px 1px 10px;
|
||
|
|
padding-left:1px;
|
||
|
|
padding-top:1px;
|
||
|
|
padding-right:1px;
|
||
|
|
padding-bottom:1px; }
|
||
|
|
td.hcp17 { vertical-align:middle;
|
||
|
|
padding:1px 4px;
|
||
|
|
padding-left:1px;
|
||
|
|
padding-top:1px;
|
||
|
|
padding-right:1px;
|
||
|
|
padding-bottom:1px; }
|
||
|
|
td.hcp18 { vertical-align:middle;
|
||
|
|
text-align:center;
|
||
|
|
-moz-background-clip:-moz-initial;
|
||
|
|
-moz-background-origin:-moz-initial;
|
||
|
|
-moz-background-inline-policy:-moz-initial;
|
||
|
|
color:#000000;
|
||
|
|
padding-left:1px;
|
||
|
|
padding-top:1px;
|
||
|
|
padding-right:1px;
|
||
|
|
padding-bottom:1px;
|
||
|
|
background-repeat:repeat;
|
||
|
|
background-position:0% 0%;
|
||
|
|
background-attachment:scroll; }
|
||
|
|
td.hcp19 { vertical-align:middle;
|
||
|
|
text-align:center;
|
||
|
|
-moz-background-clip:-moz-initial;
|
||
|
|
-moz-background-origin:-moz-initial;
|
||
|
|
-moz-background-inline-policy:-moz-initial;
|
||
|
|
color:#ffffff;
|
||
|
|
padding-left:1px;
|
||
|
|
padding-top:1px;
|
||
|
|
padding-right:1px;
|
||
|
|
padding-bottom:1px;
|
||
|
|
background-repeat:repeat;
|
||
|
|
background-position:0% 0%;
|
||
|
|
background-attachment:scroll; }
|
||
|
|
div.hcp20 { border:1px dashed rgb(47, 111, 171);
|
||
|
|
padding:1em;
|
||
|
|
color:#000000;
|
||
|
|
background-color:rgb(249, 249, 249);
|
||
|
|
line-height:1.1em;
|
||
|
|
font-family:"Lucida Console" , "Bitstream Vera Sans Mono" , Courier, monospace; }
|
||
|
|
span.hcp21 { color:seagreen; }
|
||
|
|
span.hcp22 { color:#E0302E; }
|
||
|
|
span.hcp23 { font-style:italic;
|
||
|
|
color:#6680CF; }
|
||
|
|
span.hcp24 { color:#804040; }
|
||
|
|
-->
|
||
|
|
</style>
|
||
|
|
</head>
|
||
|
|
|
||
|
|
<body class="ns-0 ltr">
|
||
|
|
<div id="globalWrapper">
|
||
|
|
<div id="column-content">
|
||
|
|
<div id="content">
|
||
|
|
<p><a name="top" id="top"></a></p>
|
||
|
|
<h1 class="firstHeading">Third-party Control Protocol</h1>
|
||
|
|
<div id="bodyContent">
|
||
|
|
<p id="siteSub"> <script type="text/javascript" language="JavaScript1.2">//<![CDATA[
|
||
|
|
if (window.showTocToggle) { var tocShowText = "show"; var tocHideText = "hide"; showTocToggle(); }
|
||
|
|
//]]></script></p>
|
||
|
|
<div class="editsection" style="float: right; margin-left: 5px;">
|
||
|
|
<p> </p>
|
||
|
|
</div>
|
||
|
|
<p><a name="Introduction" id="Introduction"></a></p>
|
||
|
|
<h1>Introduction</h1>
|
||
|
|
<p>This section is provided for Soundweb London users who
|
||
|
|
wish to provide their own user interface or control system
|
||
|
|
for a Soundweb London system. The user interface or control
|
||
|
|
system can be based on a PC running a custom application,
|
||
|
|
a dedicated show controller, a proprietary control system
|
||
|
|
such as Crestron or AMX, or even a custom piece of hardware.</p>
|
||
|
|
<p>The Soundweb London third-party control protocol builds
|
||
|
|
on the flexibility of the <span class="hcp1">RAW_MSG</span>
|
||
|
|
extension protocol introduced with Soundweb Original and
|
||
|
|
gives almost complete control of a Soundweb London network
|
||
|
|
via RS-232 or TCP/IP.</p>
|
||
|
|
<p> </p>
|
||
|
|
<div class="editsection" style="float: right; margin-left: 5px;">
|
||
|
|
<p> </p>
|
||
|
|
</div>
|
||
|
|
<p><a name="Interface_Options" id="Interface_Options"></a></p>
|
||
|
|
<h1>Interface Options</h1>
|
||
|
|
<p>Soundweb London devices accept third-party control commands
|
||
|
|
via RS-232 or TCP/IP. It is only necessary to connect
|
||
|
|
to a single device in a Soundweb London network. That
|
||
|
|
device will forward control messages to other devices
|
||
|
|
as necessary.</p>
|
||
|
|
<p> </p>
|
||
|
|
<div class="editsection" style="float: right; margin-left: 5px;">
|
||
|
|
<p> </p>
|
||
|
|
</div>
|
||
|
|
<p><a name="Serial.2FRS-232" id="Serial.2FRS-232"></a></p>
|
||
|
|
<h2>Serial/RS-232</h2>
|
||
|
|
<ul>
|
||
|
|
<li class="p"><p>The connection from the controller
|
||
|
|
to the Soundweb London device should be made using
|
||
|
|
a 3-wire null modem cable. In most cases it is fine
|
||
|
|
if the other pins are connected, but some controllers
|
||
|
|
will only work with 3-wire cables.<span style="display: none;">RS232</span></p></li>
|
||
|
|
</ul>
|
||
|
|
<table wrapperparagraphselector="P" cellspacing="1" class="hcp2">
|
||
|
|
<tr>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td rowspan="7" style="vertical-align: middle;
|
||
|
|
padding: 8px 60px 8px 20px; padding-left: 1px;
|
||
|
|
padding-top: 1px; padding-right: 1px; padding-bottom: 1px;"><p class="hcp4"><img src="Nullmodem.jpg" alt="Image:nullmodem.png" title="Image:nullmodem.png" border="2" class="hcp5"></p></td>
|
||
|
|
<td colspan="4" height="4" class="hcp6"> </td>
|
||
|
|
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td colspan="2" width="15" bgcolor="#E0E0E0" class="hcp7"><p class="hcp4"><span class="hcp1">PC or Controller</span></p></td>
|
||
|
|
<td colspan="2" width="15" bgcolor="#E0E0E0" class="hcp7"><p class="hcp4"><span class="hcp1">Soundweb London</span></p></td>
|
||
|
|
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td width="7" class="hcp6"><p class="hcp4"><span class="hcp1">RX</span></p></td>
|
||
|
|
<td width="7" class="hcp6"><p class="hcp4">Pin
|
||
|
|
2</p></td>
|
||
|
|
<td width="7" class="hcp6"><p class="hcp4"><span class="hcp1">TX</span></p></td>
|
||
|
|
<td width="7" class="hcp6"><p class="hcp4">Pin
|
||
|
|
3</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td width="7" class="hcp6"><p class="hcp4"><span class="hcp1">TX</span></p></td>
|
||
|
|
<td width="7" class="hcp6"><p class="hcp4">Pin
|
||
|
|
3</p></td>
|
||
|
|
<td width="7" class="hcp6"><p class="hcp4"><span class="hcp1">RX</span></p></td>
|
||
|
|
<td width="7" class="hcp6"><p class="hcp4">Pin
|
||
|
|
2</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td width="7" class="hcp6"><p class="hcp4"><span class="hcp1">GND</span></p></td>
|
||
|
|
<td width="7" class="hcp6"><p class="hcp4">Pin
|
||
|
|
5</p></td>
|
||
|
|
<td width="7" class="hcp6"><p class="hcp4"><span class="hcp1">GND</span></p></td>
|
||
|
|
<td width="7" class="hcp6"><p class="hcp4">Pin
|
||
|
|
5</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td colspan="4" height="2" bgcolor="#E0E0E0" class="hcp6"> </td>
|
||
|
|
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td colspan="4" height="4" class="hcp6"> </td>
|
||
|
|
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
<ul>
|
||
|
|
<li class="p"><p class="hcp8">Soundweb
|
||
|
|
London devices use 8-bit data bytes, no parity, and
|
||
|
|
one stop bit (i.e. '8N1').<br>
|
||
|
|
</p></li>
|
||
|
|
<li>The default bit rate is 115,200 bps. This can be
|
||
|
|
changed in <a href="MAINIntroduction.htm">HiQnet London
|
||
|
|
Architect</a> by clicking on the desired device in
|
||
|
|
the system layout, opening the Properties window,
|
||
|
|
and selecting the desired data rate. Other parameters,
|
||
|
|
such as whether the device will expect messages to
|
||
|
|
be acknowledged, can also be adjusted here.</li>
|
||
|
|
</ul>
|
||
|
|
<p><img src="Blu_serial_properties.jpg" alt="Image:blu_serial_properties.png" title="Image:blu_serial_properties.png" border="2" class="hcp5"></p>
|
||
|
|
<p> </p>
|
||
|
|
<div class="editsection" style="float: right; margin-left: 5px;">
|
||
|
|
<p> </p>
|
||
|
|
</div>
|
||
|
|
<p><a name="TCP.2FIP" id="TCP.2FIP"></a></p>
|
||
|
|
<h2>TCP/IP</h2>
|
||
|
|
<ul>
|
||
|
|
<li class="p"><p>Soundweb London devices also accept
|
||
|
|
third-party control messages via TCP/IP connections
|
||
|
|
on port 1023. Refer to your controller's documentation
|
||
|
|
for more information on connecting to a device via
|
||
|
|
TCP/IP.</p></li>
|
||
|
|
</ul>
|
||
|
|
<p> </p>
|
||
|
|
<div class="editsection" style="float: right; margin-left: 5px;">
|
||
|
|
<p> </p>
|
||
|
|
</div>
|
||
|
|
<p><a name="Protocol_Description" id="Protocol_Description"></a></p>
|
||
|
|
<h1>Protocol Description</h1>
|
||
|
|
<p>The Soundweb London third-party control protocol (also
|
||
|
|
called the 'Direct Inject' protocol) is a simple message-based
|
||
|
|
protocol. Each message consists of a start byte, a message
|
||
|
|
type ID byte, the message payload (which depends on the
|
||
|
|
message type), a checksum byte, and an end byte. On serial
|
||
|
|
connections, messages with a valid checksum are acknowledged
|
||
|
|
with an ACK byte, while messages with an invalid checksum
|
||
|
|
trigger a NAK response.</p>
|
||
|
|
<p>In a typical scenario, a controller might first send
|
||
|
|
a series of SUBSCRIBE messages to learn the current state
|
||
|
|
of the Soundweb London system. The Soundweb London device
|
||
|
|
would respond with a SET message corresponding to each
|
||
|
|
valid SUBSCRIBE message. The Soundweb London device will
|
||
|
|
also notify the controller with a SET message each time
|
||
|
|
a subscribed control parameter changes (unless the change
|
||
|
|
is made by the controller itself). The controller could
|
||
|
|
then send SET messages each time a control parameter should
|
||
|
|
be changed based on user interaction or controller automation.
|
||
|
|
When the controller is done controlling the Soundweb London
|
||
|
|
system, it sends UNSUBSCRIBE messages corresponding to
|
||
|
|
each SUBSCRIBE sent previously.</p>
|
||
|
|
<p> </p>
|
||
|
|
<div class="editsection" style="float: right; margin-left: 5px;">
|
||
|
|
<p> </p>
|
||
|
|
</div>
|
||
|
|
<p><a name="Message_Format" id="Message_Format"></a></p>
|
||
|
|
<h2>Message Format</h2>
|
||
|
|
<p>Soundweb London third-party control messages have the
|
||
|
|
following format:</p>
|
||
|
|
<table wrapperparagraphselector="P" cellspacing="1" class="hcp2">
|
||
|
|
<tr>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td width="8" bgcolor="#C0F0D8" class="hcp6"><p class="hcp4">STX</p></td>
|
||
|
|
<td width="8" bgcolor="#C0D8F0" class="hcp6"><p class="hcp4">ID</p></td>
|
||
|
|
<td width="21" bgcolor="#E0C0F8" class="hcp6"><p class="hcp4">Payload</p></td>
|
||
|
|
<td width="8" bgcolor="#F0EEC0" class="hcp6"><p class="hcp4">Checksum</p></td>
|
||
|
|
<td width="8" bgcolor="#F0C0C0" class="hcp6"><p class="hcp4">ETX</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td bgcolor="#C0F0D8" class="hcp6"><p class="hcp4"><span class="hcp9">0x02</span></p></td>
|
||
|
|
<td colspan="3" bgcolor="#E0E0E0" class="hcp6"><p class="hcp4"><span class="hcp10">Message body - see
|
||
|
|
below</span></p></td>
|
||
|
|
<td bgcolor="#F0C0C0" class="hcp6"><p class="hcp4"><span class="hcp9">0x03</span></p></td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
<p>The message body is constructed in three steps:</p>
|
||
|
|
<ol>
|
||
|
|
<li class="p"><p class="hcp8">The ID and
|
||
|
|
Payload are assembled according to the appropriate
|
||
|
|
format for the given message type.<br>
|
||
|
|
</p></li>
|
||
|
|
<li><p class="hcp8">An XOR checksum of
|
||
|
|
the ID and Payload is appended.<br>
|
||
|
|
</p></li>
|
||
|
|
<li>Any control codes are escaped.</li>
|
||
|
|
</ol>
|
||
|
|
<p> </p>
|
||
|
|
<div class="editsection" style="float: right; margin-left: 5px;">
|
||
|
|
<p> </p>
|
||
|
|
</div>
|
||
|
|
<p><a name="Message_ID" id="Message_ID"></a></p>
|
||
|
|
<h3>Message ID</h3>
|
||
|
|
<p>There are nine message types. The behavior of each is
|
||
|
|
described in the following table:</p>
|
||
|
|
<table wrapperparagraphselector="P" cellspacing="1" class="hcp2">
|
||
|
|
<tr>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td width="7" bgcolor="#E0E0E0" class="hcp6"><p class="hcp4">ID</p></td>
|
||
|
|
<td bgcolor="#E0E0E0" class="hcp6"><p class="hcp4">Message
|
||
|
|
Type</p></td>
|
||
|
|
<td bgcolor="#E0E0E0" class="hcp6"><p class="hcp4">Description</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td class="hcp3"><p class="hcp4"><span class="hcp9">0x88</span></p></td>
|
||
|
|
<td class="hcp3"><p class="hcp8"><span class="hcp1">DI_SETSV</span></p></td>
|
||
|
|
<td class="hcp3"><p class="hcp8">Set a control parameter.</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td class="hcp3"><p class="hcp4"><span class="hcp9">0x89</span></p></td>
|
||
|
|
<td class="hcp3"><p class="hcp8"><span class="hcp1">DI_SUBSCRIBESV</span></p></td>
|
||
|
|
<td class="hcp3"><p class="hcp8">Return the current
|
||
|
|
value of and subscribe to a control parameter.</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td class="hcp3"><p class="hcp4"><span class="hcp9">0x8A</span></p></td>
|
||
|
|
<td class="hcp3"><p class="hcp8"><span class="hcp1">DI_UNSUBSCRIBESV*</span></p></td>
|
||
|
|
<td class="hcp3"><p class="hcp8">Unsubscribe from
|
||
|
|
a control parameter.</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td class="hcp3"><p class="hcp4"><span class="hcp9">0x8B</span></p></td>
|
||
|
|
<td class="hcp3"><p class="hcp8"><span class="hcp1">DI_VENUE_PRESET_RECALL</span></p></td>
|
||
|
|
<td class="hcp3"><p class="hcp8">Recall a Venue Preset.</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td class="hcp3"><p class="hcp4"><span class="hcp9">0x8C</span></p></td>
|
||
|
|
<td class="hcp3"><p class="hcp8"><span class="hcp1">DI_PARAM_PRESET_RECALL</span></p></td>
|
||
|
|
<td class="hcp3"><p class="hcp8">Recall a Parameter
|
||
|
|
Preset.</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td class="hcp3"><p class="hcp4"><span class="hcp9">0x8D</span></p></td>
|
||
|
|
<td class="hcp3"><p class="hcp8"><span class="hcp1">DI_SETSVPERCENT</span></p></td>
|
||
|
|
<td class="hcp3"><p class="hcp8">Set a control parameter
|
||
|
|
by percentage.</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td class="hcp3"><p class="hcp4"><span class="hcp9">0x8E</span></p></td>
|
||
|
|
<td class="hcp3"><p class="hcp8"><span class="hcp1">DI_SUBSCRIBESVPERCENT</span></p></td>
|
||
|
|
<td class="hcp3"><p class="hcp8">Return the current
|
||
|
|
value of and subscribe to a control parameter
|
||
|
|
as a percentage of its total range.</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td class="hcp3"><p class="hcp4"><span class="hcp9">0x8F</span></p></td>
|
||
|
|
<td class="hcp3"><p class="hcp8"><span class="hcp1">DI_UNSUBSCRIBESVPERCENT*</span>
|
||
|
|
 </p></td>
|
||
|
|
<td class="hcp3"><p class="hcp8">Unsubscribe from
|
||
|
|
a state variable previously subscribed as a percentage
|
||
|
|
of its total range.</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td class="hcp3"><p class="hcp4"><span class="hcp9">0x90</span></p></td>
|
||
|
|
<td class="hcp3"><p class="hcp8"><span class="hcp1">DI_BUMPSVPERCENT</span>
|
||
|
|
 </p></td>
|
||
|
|
<td class="hcp3"><p class="hcp8">Increment a control
|
||
|
|
parameter by the given signed percentage of its
|
||
|
|
total range.</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td colspan="3" height="2" bgcolor="#E0E0E0" class="hcp6"> </td>
|
||
|
|
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td colspan="3" class="hcp6"><p style="text-align: right;
|
||
|
|
margin-bottom: 0;"><span class="hcp10"><span class="hcp1">*DI_UNSUBSCRIBESV</span>
|
||
|
|
and <span class="hcp1">DI_UNSUBSCRIBESVPERCENT</span>
|
||
|
|
are not interchangeable.</span></p></td>
|
||
|
|
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
<div class="editsection" style="float: right; margin-left: 5px;">
|
||
|
|
<p> </p>
|
||
|
|
</div>
|
||
|
|
<p><a name="Payload" id="Payload"></a></p>
|
||
|
|
<h3>Payload</h3>
|
||
|
|
<p>The payload varies slightly with each message type.
|
||
|
|
The message ID and payload together are 5 bytes for preset
|
||
|
|
messages, 13 bytes for all other messages (before any
|
||
|
|
control codes are escaped).</p>
|
||
|
|
<table wrapperparagraphselector="P" cellspacing="1" class="hcp2">
|
||
|
|
<tr>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td colspan="2" bgcolor="#E0E0E0" class="hcp6"><p class="hcp4">Message
|
||
|
|
Type</p></td>
|
||
|
|
<td bgcolor="#E0E0E0" class="hcp6"><p class="hcp4">Payload
|
||
|
|
Format</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td width="7" class="hcp3"><p class="hcp4"><span class="hcp9">0x88</span></p></td>
|
||
|
|
<td class="hcp11"><p class="hcp8"><span class="hcp1">DI_SETSV</span></p></td>
|
||
|
|
<td rowspan="7" class="hcp12"><p class="hcp8"><img src="Payload_format.jpg" alt="Image:payload_format.png" title="Image:payload_format.png" border="2" class="hcp5"></p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td width="7" class="hcp3"><p class="hcp4"><span class="hcp9">0x89</span></p></td>
|
||
|
|
<td class="hcp11"><p class="hcp8"><span class="hcp1">DI_SUBSCRIBESV</span></p></td>
|
||
|
|
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td width="7" class="hcp3"><p class="hcp4"><span class="hcp9">0x8A</span></p></td>
|
||
|
|
<td class="hcp11"><p class="hcp8"><span class="hcp1">DI_UNSUBSCRIBESV</span></p></td>
|
||
|
|
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td width="7" class="hcp3"><p class="hcp4"><span class="hcp9">0x8D</span></p></td>
|
||
|
|
<td class="hcp11"><p class="hcp8"><span class="hcp1">DI_SETSVPERCENT</span></p></td>
|
||
|
|
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td width="7" class="hcp3"><p class="hcp4"><span class="hcp9">0x8E</span></p></td>
|
||
|
|
<td class="hcp11"><p class="hcp8"><span class="hcp1">DI_SUBSCRIBESVPERCENT</span></p></td>
|
||
|
|
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td width="7" class="hcp3"><p class="hcp4"><span class="hcp9">0x8F</span></p></td>
|
||
|
|
<td class="hcp11"><p class="hcp8"><span class="hcp1">DI_UNSUBSCRIBESVPERCENT</span></p></td>
|
||
|
|
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td width="7" class="hcp3"><p class="hcp4"><span class="hcp9">0x90</span></p></td>
|
||
|
|
<td class="hcp11"><p class="hcp8"><span class="hcp1">DI_BUMPSVPERCENT</span></p></td>
|
||
|
|
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td colspan="3" height="1" bgcolor="#E0E0E0" class="hcp13"> </td>
|
||
|
|
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td colspan="2" class="hcp6"> </td>
|
||
|
|
<td rowspan="4" class="hcp12"><p class="hcp8"><img src="Payload_preset.jpg" alt="Image:payload_preset.png" title="Image:payload_preset.png" border="2" class="hcp5"></p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td width="7" class="hcp14"><p class="hcp4"><span class="hcp9">0x8B</span></p></td>
|
||
|
|
<td style="vertical-align: BOTTOM; padding: 1px 4px;
|
||
|
|
padding-left: 1px; padding-top: 1px; padding-right: 1px;
|
||
|
|
padding-bottom: 1px;" height="1"><p class="hcp8"><span class="hcp1">DI_VENUE_PRESET_RECALL</span></p></td>
|
||
|
|
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td width="7" class="hcp3"><p class="hcp4"><span class="hcp9">0x8C</span></p></td>
|
||
|
|
<td height="1" class="hcp11"><p class="hcp8"><span class="hcp1">DI_PARAM_PRESET_RECALL</span></p></td>
|
||
|
|
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td colspan="2" class="hcp6"> </td>
|
||
|
|
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td colspan="3" height="2" bgcolor="#E0E0E0" class="hcp6"> </td>
|
||
|
|
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
<div class="editsection" style="float: right; margin-left: 5px;">
|
||
|
|
<p> </p>
|
||
|
|
</div>
|
||
|
|
<p><a name="Address" id="Address"></a></p>
|
||
|
|
<h4>Address</h4>
|
||
|
|
<p>Control parameters (also called 'State Variables') on
|
||
|
|
a Soundweb London device are logically grouped into Virtual
|
||
|
|
Devices (corresponding to categories of objects, such
|
||
|
|
as Audio and Logic) and Objects (corresponding to individual
|
||
|
|
processing objects). Each Object is uniquely identified
|
||
|
|
on the Soundweb London network by its HiQnet address.
|
||
|
|
HiQnet addresses are typically represented in hexadecimal
|
||
|
|
and have the following format: <span class="hcp9">0x<span class="hcp10"><span style="color: #452BC5;">Node</span><span
|
||
|
|
style="color: #049A40;">VD</span><span style="color: #921880;">Object</span></span></span>.</p>
|
||
|
|
<table wrapperparagraphselector="P" cellspacing="1" class="hcp2">
|
||
|
|
<tr>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td bgcolor="#E0E0E0" class="hcp6"><p class="hcp4">Field</p></td>
|
||
|
|
<td width="5" bgcolor="#E0E0E0" class="hcp6"><p class="hcp4">Size</p></td>
|
||
|
|
<td bgcolor="#E0E0E0" class="hcp6"><p class="hcp4">Name</p></td>
|
||
|
|
<td bgcolor="#E0E0E0" class="hcp6"><p class="hcp4">Description</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td nowrap="nowrap" class="hcp15"><p class="hcp8"><span class="hcp1">Node</span></p></td>
|
||
|
|
<td class="hcp3"><p class="hcp4">2</p></td>
|
||
|
|
<td nowrap="nowrap" class="hcp3"><p class="hcp8">HiQnet
|
||
|
|
Node Address</p></td>
|
||
|
|
<td class="hcp3"><p class="hcp8">The HiQnet node
|
||
|
|
address of the targeted Soundweb London device.
|
||
|
|
Each physical Soundweb London device has a unique
|
||
|
|
HiQnet node address assigned to it using the HiQnet
|
||
|
|
London Architect software. If the node field is
|
||
|
|
zero, the message will be sent to the device that
|
||
|
|
is directly connected to the controller via RS-232
|
||
|
|
or TCP/IP. Otherwise the message will be forwarded
|
||
|
|
to the corresponding device.</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td colspan="4" height="1" bgcolor="#E0E0E0" class="hcp13"> </td>
|
||
|
|
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td nowrap="nowrap" class="hcp15"><p class="hcp8"><span class="hcp1">VD</span></p></td>
|
||
|
|
<td class="hcp3"><p class="hcp4">1</p></td>
|
||
|
|
<td nowrap="nowrap" class="hcp3"><p class="hcp8">Virtual
|
||
|
|
Device ID</p></td>
|
||
|
|
<td class="hcp3"><p class="hcp8">The ID of the targeted
|
||
|
|
virtual device. Objects (such as gains, mixer,
|
||
|
|
logic elements, etc.) within the Soundweb London
|
||
|
|
system are organized into Virtual Devices. A list
|
||
|
|
of the Virtual Devices in a Soundweb London DSP
|
||
|
|
device follows below.</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td colspan="4" height="1" bgcolor="#E0E0E0" class="hcp13"> </td>
|
||
|
|
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td nowrap="nowrap" class="hcp15"><p class="hcp8"><span class="hcp1">Object</span></p></td>
|
||
|
|
<td class="hcp3"><p class="hcp4">3</p></td>
|
||
|
|
<td nowrap="nowrap" class="hcp3"><p class="hcp8">Object
|
||
|
|
ID</p></td>
|
||
|
|
<td class="hcp3"><p class="hcp8">The ID of the targeted
|
||
|
|
processing object. Each processing object, logic
|
||
|
|
object, etc. has a unique object ID.</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td colspan="4" height="2" bgcolor="#E0E0E0" class="hcp6"> </td>
|
||
|
|
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
<div class="editsection" style="float: right; margin-left: 5px;">
|
||
|
|
<p> </p>
|
||
|
|
</div>
|
||
|
|
<p><a name="Node" id="Node"></a></p>
|
||
|
|
<h5>Node</h5>
|
||
|
|
<p>The node address of a Soundweb London device is shown
|
||
|
|
in the Properties window when the device is selected in
|
||
|
|
the system layout. It is also shown in the Network window
|
||
|
|
when a device is selected in the network tree. See <a
|
||
|
|
href="Connecting to a Soundweb London network.html">Connecting
|
||
|
|
to a Soundweb London network</a> for more information
|
||
|
|
on changing a device's node address. The node address
|
||
|
|
is the first four hexadecimal digits of the HiQnet address.</p>
|
||
|
|
<p><img src="http://web.media.mit.edu/~benb/statics/bssmanual/MAIN/Network_view_node_address.jpg" alt="Image:Network_view_node_address.png" title="Image:Network_view_node_address.png" border="2" class="hcp5"></p>
|
||
|
|
<p> </p>
|
||
|
|
<div class="editsection" style="float: right; margin-left: 5px;">
|
||
|
|
<p> </p>
|
||
|
|
</div>
|
||
|
|
<p><a name="Virtual_Device" id="Virtual_Device"></a></p>
|
||
|
|
<h5>Virtual Device</h5>
|
||
|
|
<p>Each Soundweb London DSP device contains four virtual
|
||
|
|
devices. The Virtual Device ID is the third byte of the
|
||
|
|
HiQnet address, or the fifth and sixth hexadecimal digits.</p>
|
||
|
|
<table wrapperparagraphselector="P" cellspacing="1" class="hcp2">
|
||
|
|
<tr>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td width="7" bgcolor="#E0E0E0" class="hcp6"><p class="hcp4">VD</p></td>
|
||
|
|
<td bgcolor="#E0E0E0" class="hcp6"><p class="hcp4">Description</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td class="hcp6"><p class="hcp4"><span class="hcp9">0x00</span></p></td>
|
||
|
|
<td class="hcp16"><p class="hcp8">Basic
|
||
|
|
settings</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td class="hcp6"><p class="hcp4"><span class="hcp9">0x01</span></p></td>
|
||
|
|
<td class="hcp16"><p class="hcp8">Links</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td class="hcp6"><p class="hcp4"><span class="hcp9">0x02</span></p></td>
|
||
|
|
<td class="hcp16"><p class="hcp8">Logic
|
||
|
|
objects</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td class="hcp6"><p class="hcp4"><span class="hcp9">0x03</span></p></td>
|
||
|
|
<td class="hcp16"><p class="hcp8">Audio
|
||
|
|
processing objects</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td colspan="2" height="2" bgcolor="#E0E0E0" class="hcp6"> </td>
|
||
|
|
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
<div class="editsection" style="float: right; margin-left: 5px;">
|
||
|
|
<p> </p>
|
||
|
|
</div>
|
||
|
|
<p><a name="Object" id="Object"></a></p>
|
||
|
|
<h5>Object</h5>
|
||
|
|
<p>The Object ID is the last six hexadecimal digits of
|
||
|
|
the HiQnet address shown in the Properties window when
|
||
|
|
a processing object is selected in the device's audio
|
||
|
|
configuration.</p>
|
||
|
|
<p><img src="Object_id.jpg" alt="Image:Object_id.png" title="Image:Object_id.png" border="2" class="hcp5"></p>
|
||
|
|
<p> </p>
|
||
|
|
<div class="editsection" style="float: right; margin-left: 5px;">
|
||
|
|
<p> </p>
|
||
|
|
</div>
|
||
|
|
<p><a name="State_Variable" id="State_Variable"></a></p>
|
||
|
|
<h4>State Variable</h4>
|
||
|
|
<p>Each control parameter of an Object is identified by
|
||
|
|
a State Variable ID. State Variable IDs are consistently
|
||
|
|
defined for each object type. For example, the mute control
|
||
|
|
of every Gain object always has State Variable ID <span class="hcp9">0x01</span>. If an object
|
||
|
|
has a large number of control parameters, it is possible
|
||
|
|
to use a formula to calculate the State Variable ID based
|
||
|
|
on input and/or output channels, rather than hard-coding
|
||
|
|
each control parameter ID. See <a href="Common Object and State Variable IDs.html">Common
|
||
|
|
Object and State Variable IDs</a> for a list of objects
|
||
|
|
and their corresponding State Variable IDs, including
|
||
|
|
formulas for calculating State Variable IDs for some objects.
|
||
|
|
The State Variable ID for a control parameter can be discovered
|
||
|
|
by selecting the desired object, opening the Properties
|
||
|
|
window, and clicking the desired control parameter in
|
||
|
|
the Parameters list of the Properties window:</p>
|
||
|
|
<table wrapperparagraphselector="P" cellspacing="0" class="hcp2">
|
||
|
|
<tr>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td class="hcp6"><p class="hcp4"><img src="Gain_svid_from_properties.jpg" alt="Gain Object: Gain SV ID is 0x00" title="Gain Object: Gain SV ID is 0x00" border="2" class="hcp5"></p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td nowrap="nowrap" class="hcp3"><p class="hcp4"><span
|
||
|
|
style="font-size: smaller;">Gain Object: Gain
|
||
|
|
SV ID is 0x00</span></p></td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
<p>The two-byte State Variable ID is always an unsigned
|
||
|
|
16-bit big-endian integer.</p>
|
||
|
|
<p> </p>
|
||
|
|
<div class="editsection" style="float: right; margin-left: 5px;">
|
||
|
|
<p> </p>
|
||
|
|
</div>
|
||
|
|
<p><a name="Data" id="Data"></a></p>
|
||
|
|
<h4>Data</h4>
|
||
|
|
<p>The four-byte data section is always a signed 32-bit
|
||
|
|
big-endian integer (i.e. the most significant byte is
|
||
|
|
transmitted first). The contents of the data section are
|
||
|
|
determined by the message type.</p>
|
||
|
|
<table wrapperparagraphselector="P" cellspacing="1" class="hcp2">
|
||
|
|
<tr>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td colspan="2" bgcolor="#E0E0E0" class="hcp6"><p class="hcp4">Message
|
||
|
|
Type</p></td>
|
||
|
|
<td bgcolor="#E0E0E0" class="hcp6"><p class="hcp4">Data
|
||
|
|
Type</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td width="7" class="hcp3"><p class="hcp4"><span class="hcp9">0x88</span></p></td>
|
||
|
|
<td class="hcp11"><p class="hcp8"><span class="hcp1">DI_SETSV</span></p></td>
|
||
|
|
<td class="hcp12"><p class="hcp8">Raw
|
||
|
|
control value</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td colspan="3" height="1" bgcolor="#E0E0E0" class="hcp13"> </td>
|
||
|
|
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td width="7" class="hcp3"><p class="hcp4"><span class="hcp9">0x8D</span></p></td>
|
||
|
|
<td class="hcp11"><p class="hcp8"><span class="hcp1">DI_SETSVPERCENT</span></p></td>
|
||
|
|
<td rowspan="2" class="hcp12"><p class="hcp8">Percentage of control
|
||
|
|
range</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td width="7" class="hcp3"><p class="hcp4"><span class="hcp9">0x90</span></p></td>
|
||
|
|
<td class="hcp11"><p class="hcp8"><span class="hcp1">DI_BUMPSVPERCENT</span></p></td>
|
||
|
|
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td colspan="3" height="1" bgcolor="#E0E0E0" class="hcp13"> </td>
|
||
|
|
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td width="7" class="hcp3"><p class="hcp4"><span class="hcp9">0x89</span></p></td>
|
||
|
|
<td class="hcp11"><p class="hcp8"><span class="hcp1">DI_SUBSCRIBESV</span></p></td>
|
||
|
|
<td rowspan="2" class="hcp12"><p class="hcp8">Zero for non-meter
|
||
|
|
SVs, subscription rate for meter SVs</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td width="7" class="hcp3"><p class="hcp4"><span class="hcp9">0x8E</span></p></td>
|
||
|
|
<td class="hcp11"><p class="hcp8"><span class="hcp1">DI_SUBSCRIBESVPERCENT</span></p></td>
|
||
|
|
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td colspan="3" height="1" bgcolor="#E0E0E0" class="hcp13"> </td>
|
||
|
|
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td width="7" class="hcp3"><p class="hcp4"><span class="hcp9">0x8A</span></p></td>
|
||
|
|
<td class="hcp11"><p class="hcp8"><span class="hcp1">DI_UNSUBSCRIBESV</span></p></td>
|
||
|
|
<td rowspan="2" class="hcp12"><p class="hcp8">Zero</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td width="7" class="hcp3"><p class="hcp4"><span class="hcp9">0x8F</span></p></td>
|
||
|
|
<td class="hcp11"><p class="hcp8"><span class="hcp1">DI_UNSUBSCRIBESVPERCENT</span></p></td>
|
||
|
|
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td colspan="3" height="1" bgcolor="#E0E0E0" class="hcp13"> </td>
|
||
|
|
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td width="7" class="hcp3"><p class="hcp4"><span class="hcp9">0x8B</span></p></td>
|
||
|
|
<td class="hcp11"><p class="hcp8"><span class="hcp1">DI_VENUE_PRESET_RECALL</span></p></td>
|
||
|
|
<td rowspan="2" class="hcp12"><p class="hcp8">Preset ID</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td width="7" class="hcp3"><p class="hcp4"><span class="hcp9">0x8C</span></p></td>
|
||
|
|
<td class="hcp11"><p class="hcp8"><span class="hcp1">DI_PARAM_PRESET_RECALL</span></p></td>
|
||
|
|
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td colspan="3" height="2" bgcolor="#E0E0E0" class="hcp6"> </td>
|
||
|
|
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
<div class="editsection" style="float: right; margin-left: 5px;">
|
||
|
|
<p> </p>
|
||
|
|
</div>
|
||
|
|
<p><a name="Raw_Value" id="Raw_Value"></a></p>
|
||
|
|
<h5>Raw Value</h5>
|
||
|
|
<p>Each type of control parameter (i.e. gain, mute, frequency,
|
||
|
|
time, etc.) has its own encoded format for raw values.
|
||
|
|
See Appendix A for information on calculating raw values.</p>
|
||
|
|
<p> </p>
|
||
|
|
<div class="editsection" style="float: right; margin-left: 5px;">
|
||
|
|
<p> </p>
|
||
|
|
</div>
|
||
|
|
<p><a name="Percentage" id="Percentage"></a></p>
|
||
|
|
<h5>Percentage</h5>
|
||
|
|
<p>The value of the control as a percentage of its total
|
||
|
|
range (i.e. 0 to 100) multiplied by 65536 to allow for
|
||
|
|
fractions of a percent. The accepted range of values is
|
||
|
|
0 to 6553600 for <span class="hcp1">DI_SETSVPERCENT</span>,
|
||
|
|
-6553600 to 6553600 for <span class="hcp1">DI_BUMPSVPERCENT</span>.</p>
|
||
|
|
<p> </p>
|
||
|
|
<div class="editsection" style="float: right; margin-left: 5px;">
|
||
|
|
<p> </p>
|
||
|
|
</div>
|
||
|
|
<p><a name="Subscription_Rate" id="Subscription_Rate"></a></p>
|
||
|
|
<h5>Subscription Rate</h5>
|
||
|
|
<p>The delay in milliseconds between updates sent by a
|
||
|
|
meter. The Soundweb London device will round this value
|
||
|
|
to 50ms increments. The rate must be zero when subscribing
|
||
|
|
to a non-meter control parameter. Control system and logic
|
||
|
|
performance may suffer if this value is too low.</p>
|
||
|
|
<p> </p>
|
||
|
|
<div class="editsection" style="float: right; margin-left: 5px;">
|
||
|
|
<p> </p>
|
||
|
|
</div>
|
||
|
|
<p><a name="Preset_ID" id="Preset_ID"></a></p>
|
||
|
|
<h5>Preset ID</h5>
|
||
|
|
<p>Each preset on a Soundweb London network is assigned
|
||
|
|
a unique ID when it is created. Once assigned, the Preset
|
||
|
|
ID will not change when other presets are added or deleted.
|
||
|
|
The message type corresponding to the preset's type (<span class="hcp1">DI_VENUE_PRESET_RECALL</span>
|
||
|
|
for venue presets, <span class="hcp1">DI_PARAM_PRESET_RECALL</span>
|
||
|
|
for parameter presets) must be used, as venue presets
|
||
|
|
and parameter presets may have the same ID.</p>
|
||
|
|
<p>Preset IDs are shown in square brackets next to each
|
||
|
|
preset in the design tree:</p>
|
||
|
|
<p><img src="Presets_in_design_tree.jpg" alt="Image:Presets_in_design_tree.png" title="Image:Presets_in_design_tree.png" border="2" class="hcp5"></p>
|
||
|
|
<p><span class="hcp10"><span class="hcp1">Note:</span>
|
||
|
|
Preset recall messages are broadcast across the network,
|
||
|
|
so unexpected results may occur if presets are recalled
|
||
|
|
with two separate HiQnet London Architect designs running
|
||
|
|
on the same physical network.</span></p>
|
||
|
|
<p> </p>
|
||
|
|
<div class="editsection" style="float: right; margin-left: 5px;">
|
||
|
|
<p> </p>
|
||
|
|
</div>
|
||
|
|
<p><a name="Checksum" id="Checksum"></a></p>
|
||
|
|
<h3>Checksum</h3>
|
||
|
|
<p>The checksum is a single-byte exclusive OR (XOR) of
|
||
|
|
all the bytes in the message body, computed <span class="hcp10">before</span>
|
||
|
|
control codes are escaped and <span class="hcp10">before</span>
|
||
|
|
<span class="hcp1">STX</span> and <span class="hcp1">ETX</span> are added.</p>
|
||
|
|
<p><span class="hcp10"><span class="hcp1">Note:</span>
|
||
|
|
If the checksum is a reserved control code it must be
|
||
|
|
escaped in the same way as bytes in the body of the message.
|
||
|
|
See Control Codes below.</span></p>
|
||
|
|
<p> </p>
|
||
|
|
<div class="editsection" style="float: right; margin-left: 5px;">
|
||
|
|
<p> </p>
|
||
|
|
</div>
|
||
|
|
<p><a name="Control_Codes" id="Control_Codes"></a></p>
|
||
|
|
<h3>Control Codes</h3>
|
||
|
|
<p>The following byte values have special meanings and
|
||
|
|
must be escaped if they occur within the message body.
|
||
|
|
If a byte in the message body is one of the control codes,
|
||
|
|
insert <span class="hcp1">ESC</span> (<span class="hcp9">0x1B</span>) before the
|
||
|
|
byte and add <span class="hcp9">0x80</span>
|
||
|
|
(decimal 128) to its value. Any other byte can be used
|
||
|
|
within the message body. Note that substitution must be
|
||
|
|
performed on the message body <span class="hcp10">after</span>
|
||
|
|
the checksum has been calculated and appended and <span class="hcp10">before</span> <span class="hcp1">STX</span>
|
||
|
|
and <span class="hcp1">ETX</span> are added
|
||
|
|
to the message, as the checksum itself may be a control
|
||
|
|
code in need of substitution.</p>
|
||
|
|
<table wrapperparagraphselector="P" cellspacing="2" class="hcp2">
|
||
|
|
<tr>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td width="7" bgcolor="#E0E0E0" class="hcp6"><p class="hcp4">Code</p></td>
|
||
|
|
<td width="12" bgcolor="#E0E0E0" class="hcp6"><p class="hcp4">Substitution</p></td>
|
||
|
|
<td width="7" bgcolor="#E0E0E0" class="hcp6"><p class="hcp4">Name</p></td>
|
||
|
|
<td bgcolor="#E0E0E0" class="hcp6"><p class="hcp4">Description</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td class="hcp6"><p class="hcp4"><span class="hcp9">0x02</span></p></td>
|
||
|
|
<td class="hcp6"><p class="hcp4"><span class="hcp9">0x1B 0x82</span></p></td>
|
||
|
|
<td class="hcp6"><p class="hcp4"><span class="hcp1">STX</span></p></td>
|
||
|
|
<td class="hcp17"><p class="hcp8">ASCII
|
||
|
|
Start of Text</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td class="hcp6"><p class="hcp4"><span class="hcp9">0x03</span></p></td>
|
||
|
|
<td class="hcp6"><p class="hcp4"><span class="hcp9">0x1B 0x83</span></p></td>
|
||
|
|
<td class="hcp6"><p class="hcp4"><span class="hcp1">ETX</span></p></td>
|
||
|
|
<td class="hcp17"><p class="hcp8">ASCII
|
||
|
|
End of Text</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td class="hcp6"><p class="hcp4"><span class="hcp9">0x06</span></p></td>
|
||
|
|
<td class="hcp6"><p class="hcp4"><span class="hcp9">0x1B 0x86</span></p></td>
|
||
|
|
<td class="hcp6"><p class="hcp4"><span class="hcp1">ACK</span></p></td>
|
||
|
|
<td class="hcp17"><p class="hcp8">ASCII
|
||
|
|
Acknowledge</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td class="hcp6"><p class="hcp4"><span class="hcp9">0x15</span></p></td>
|
||
|
|
<td class="hcp6"><p class="hcp4"><span class="hcp9">0x1B 0x95</span></p></td>
|
||
|
|
<td class="hcp6"><p class="hcp4"><span class="hcp1">NAK</span></p></td>
|
||
|
|
<td class="hcp17"><p class="hcp8">ASCII
|
||
|
|
No-acknowledge</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td class="hcp6"><p class="hcp4"><span class="hcp9">0x1B</span></p></td>
|
||
|
|
<td class="hcp6"><p class="hcp4"><span class="hcp9">0x1B 0x9B</span></p></td>
|
||
|
|
<td class="hcp6"><p class="hcp4"><span class="hcp1">ESC</span></p></td>
|
||
|
|
<td class="hcp17"><p class="hcp8">ASCII
|
||
|
|
Escape</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td colspan="4" height="2" bgcolor="#E0E0E0" class="hcp6"> </td>
|
||
|
|
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
<div class="editsection" style="float: right; margin-left: 5px;">
|
||
|
|
<p> </p>
|
||
|
|
</div>
|
||
|
|
<p><a name="Examples" id="Examples"></a></p>
|
||
|
|
<h1>Examples</h1>
|
||
|
|
<p>The following examples display the complete structure
|
||
|
|
of an actual control message and demonstrate a possible
|
||
|
|
approach to sending and receiving control messages.</p>
|
||
|
|
<p> </p>
|
||
|
|
<div class="editsection" style="float: right; margin-left: 5px;">
|
||
|
|
<p> </p>
|
||
|
|
</div>
|
||
|
|
<p><a name="A_Sample_Message" id="A_Sample_Message"></a></p>
|
||
|
|
<h2>A Sample Message</h2>
|
||
|
|
<p>This sample direct inject message will flash the locate
|
||
|
|
light on the device indicated by the address.</p>
|
||
|
|
<table wrapperparagraphselector="P" cellspacing="1" class="hcp2">
|
||
|
|
<tr>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
<td class="hcp3"> </td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td rowspan="2" bgcolor="#E0E0E0" class="hcp14"><p class="hcp4">Start</p></td>
|
||
|
|
<td rowspan="2" bgcolor="#E0E0E0" class="hcp14"><p class="hcp4">Type</p></td>
|
||
|
|
<td colspan="6" bgcolor="#E0E0E0" class="hcp14"><p class="hcp4">Address</p></td>
|
||
|
|
<td colspan="2" rowspan="2" bgcolor="#E0E0E0" class="hcp14"><p class="hcp4">State
|
||
|
|
Variable</p></td>
|
||
|
|
<td colspan="4" rowspan="2" bgcolor="#E0E0E0" class="hcp14"><p class="hcp4">Data</p></td>
|
||
|
|
<td rowspan="2" bgcolor="#E0E0E0" class="hcp14"><p class="hcp4">Check-<br>
|
||
|
|
sum</p></td>
|
||
|
|
<td rowspan="2" bgcolor="#E0E0E0" class="hcp14"><p class="hcp4">End</p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td colspan="2" bgcolor="#E0E0E0" class="hcp14"><p class="hcp4">Node</p></td>
|
||
|
|
<td bgcolor="#E0E0E0" class="hcp14"><p class="hcp4">VD</p></td>
|
||
|
|
<td colspan="3" bgcolor="#E0E0E0" class="hcp14"><p class="hcp4">Object</p></td>
|
||
|
|
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td width="5" bgcolor="#C0F0D8" class="hcp18"><p class="hcp8"><span class="hcp9">02</span></p></td>
|
||
|
|
<td width="5" bgcolor="#C0D8F0" class="hcp18"><p class="hcp8"><span class="hcp9">88</span></p></td>
|
||
|
|
<td width="5" bgcolor="#452BC5" class="hcp19"><p class="hcp8"><span class="hcp9">00</span></p></td>
|
||
|
|
<td width="5" bgcolor="#452BC5" class="hcp19"><p class="hcp8"><span class="hcp9">00</span></p></td>
|
||
|
|
<td width="5" bgcolor="#049A40" class="hcp19"><p class="hcp8"><span class="hcp9">00</span></p></td>
|
||
|
|
<td width="5" bgcolor="#921880" class="hcp19"><p class="hcp8"><span class="hcp9">00</span></p></td>
|
||
|
|
<td width="5" bgcolor="#921880" class="hcp19"><p class="hcp8"><span class="hcp9">00</span></p></td>
|
||
|
|
<td width="5" bgcolor="#921880" class="hcp19"><p class="hcp8"><span class="hcp9">00</span></p></td>
|
||
|
|
<td width="5" bgcolor="#FCEECD" class="hcp18"><p class="hcp8"><span class="hcp9">00</span></p></td>
|
||
|
|
<td width="5" bgcolor="#FCEECD" class="hcp18"><p class="hcp8"><span class="hcp9">04</span></p></td>
|
||
|
|
<td width="5" bgcolor="#E8FBDD" class="hcp18"><p class="hcp8"><span class="hcp9">00</span></p></td>
|
||
|
|
<td width="5" bgcolor="#E8FBDD" class="hcp18"><p class="hcp8"><span class="hcp9">00</span></p></td>
|
||
|
|
<td width="5" bgcolor="#E8FBDD" class="hcp18"><p class="hcp8"><span class="hcp9">00</span></p></td>
|
||
|
|
<td width="5" bgcolor="#E8FBDD" class="hcp18"><p class="hcp8"><span class="hcp9">00</span></p></td>
|
||
|
|
<td width="5" bgcolor="#F0EEC0" class="hcp18"><p class="hcp8"><span class="hcp9">8C</span></p></td>
|
||
|
|
<td width="5" bgcolor="#F0C0C0" class="hcp18"><p class="hcp8"><span class="hcp9">03</span></p></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td class="hcp6"> </td>
|
||
|
|
<td colspan="13" bgcolor="#E0C0F8" class="hcp6"><p class="hcp4">The
|
||
|
|
bytes in the message body used to calculate the
|
||
|
|
checksum.</p></td>
|
||
|
|
<td colspan="2" class="hcp6"> </td>
|
||
|
|
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td colspan="16" height="2" bgcolor="#E0E0E0" class="hcp6"> </td>
|
||
|
|
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
<div class="editsection" style="float: right; margin-left: 5px;">
|
||
|
|
<p> </p>
|
||
|
|
</div>
|
||
|
|
<p><a name="Sending_Messages" id="Sending_Messages"></a></p>
|
||
|
|
<h2>Sending Messages</h2>
|
||
|
|
<p>The following pseudocode procedure sends a correctly
|
||
|
|
formatted message by computing the checksum, escaping
|
||
|
|
control characters, and adding <span class="hcp1">STX</span>
|
||
|
|
and <span class="hcp1">ETX</span>.</p>
|
||
|
|
<div class="hcp20">
|
||
|
|
<p><span class="hcp21">char</span> checksum
|
||
|
|
= <span class="hcp22">0</span>                          <span class="hcp23"> /* Stores
|
||
|
|
the running checksum */</span><br>
|
||
|
|
<br>
|
||
|
|
send (<span class="hcp1">STX</span>)                                  <span class="hcp23">/* Send
|
||
|
|
the start-of-text character */</span><br>
|
||
|
|
<br>
|
||
|
|
<span class="hcp24">for</span> each
|
||
|
|
character in message body          <span class="hcp23">/* Loop
|
||
|
|
through each character of the message */</span><br>
|
||
|
|
{<br>
|
||
|
|
        checksum
|
||
|
|
= checksum XOR character   <span class="hcp23">/* Add the current character
|
||
|
|
to the checksum */</span><br>
|
||
|
|
<br>
|
||
|
|
        <span class="hcp24">if</span> (is_special
|
||
|
|
(character))<br>
|
||
|
|
        {<br>
|
||
|
|
                send
|
||
|
|
(<span class="hcp1">ESC</span>)<br>
|
||
|
|
                send
|
||
|
|
(character + <span class="hcp22">128</span>)      <span class="hcp23">/* Escape
|
||
|
|
special characters */</span><br>
|
||
|
|
        }<br>
|
||
|
|
        <span class="hcp24">else</span><br>
|
||
|
|
        {<br>
|
||
|
|
                send
|
||
|
|
(character)            <span class="hcp23">/* Send
|
||
|
|
non-special characters normally */</span><br>
|
||
|
|
        }<br>
|
||
|
|
}<br>
|
||
|
|
<br>
|
||
|
|
<span class="hcp24">if</span> (is_special
|
||
|
|
(checksum))                  <span class="hcp23">/* Escape
|
||
|
|
the checksum if needed */</span><br>
|
||
|
|
{<br>
|
||
|
|
        send
|
||
|
|
(<span class="hcp1">ESC</span>)<br>
|
||
|
|
        send
|
||
|
|
(checksum + <span class="hcp22">128</span>)<br>
|
||
|
|
}<br>
|
||
|
|
<span class="hcp24">else</span><br>
|
||
|
|
{<br>
|
||
|
|
        send
|
||
|
|
(checksum)<br>
|
||
|
|
}<br>
|
||
|
|
<br>
|
||
|
|
send (<span class="hcp1">ETX</span>)                                  <span class="hcp23">/* Send
|
||
|
|
the end-of-text character */</span><br>
|
||
|
|
<br>
|
||
|
|
<span class="hcp24">if</span> (connected
|
||
|
|
via RS-232)                  <span class="hcp23"> /* Wait
|
||
|
|
for the device to get the message */</span><br>
|
||
|
|
{<br>
|
||
|
|
        waitfor
|
||
|
|
(<span class="hcp1">ACK</span> or <span class="hcp1">NAK</span>)<br>
|
||
|
|
}<br>
|
||
|
|
</p>
|
||
|
|
</div>
|
||
|
|
<p> </p>
|
||
|
|
<div class="editsection" style="float: right; margin-left: 5px;">
|
||
|
|
<p> </p>
|
||
|
|
</div>
|
||
|
|
<p><a name="Receiving_Messages" id="Receiving_Messages"></a></p>
|
||
|
|
<h2>Receiving Messages</h2>
|
||
|
|
<p>The following pseudocode procedure receives a message,
|
||
|
|
processes escaped control characters, and makes sure the
|
||
|
|
message is valid by verifying the checksum.</p>
|
||
|
|
<div class="hcp20">
|
||
|
|
<p><span class="hcp21">bool</span> got_escape                        <span class="hcp23"> /* Indicates
|
||
|
|
whether the previous character was <span class="hcp1">ESC</span>
|
||
|
|
*/</span><br>
|
||
|
|
<span class="hcp21">char</span> checksum
|
||
|
|
= <span class="hcp22">0</span>                      <span class="hcp23"> /* Stores
|
||
|
|
the running checksum */</span><br>
|
||
|
|
<br>
|
||
|
|
on received character<br>
|
||
|
|
{<br>
|
||
|
|
        <span class="hcp24">if</span> (character
|
||
|
|
equals <span class="hcp1">STX</span>)<br>
|
||
|
|
        {<br>
|
||
|
|
                <span class="hcp23">/* This
|
||
|
|
is the start of a new message */</span><br>
|
||
|
|
                checksum
|
||
|
|
= <span class="hcp22">0</span>            <span class="hcp23">/* Clear
|
||
|
|
the checksum */</span><br>
|
||
|
|
                clear_message_buffer()  <span class="hcp23">/* Clear
|
||
|
|
the message buffer */</span><br>
|
||
|
|
                got_escape
|
||
|
|
= <span class="hcp22">false</span>      <span class="hcp23">/* Clear
|
||
|
|
the "escape received" status */</span><br>
|
||
|
|
        }<br>
|
||
|
|
        <span class="hcp24">else</span> <span class="hcp24">if</span> (character
|
||
|
|
equals <span class="hcp1">ETX</span>)<br>
|
||
|
|
        {<br>
|
||
|
|
                <span class="hcp23">/* This
|
||
|
|
is the end of a message, verify the checksum */</span><br>
|
||
|
|
                <span class="hcp24">if</span> (get_last_byte_in_message_buffer()
|
||
|
|
equals checksum)<br>
|
||
|
|
                {<br>
|
||
|
|
                        send
|
||
|
|
(<span class="hcp1">ACK</span>)      <span class="hcp23">/* The
|
||
|
|
received checksum matched the computed checksum */</span><br>
|
||
|
|
                }<br>
|
||
|
|
                <span class="hcp24">else</span><br>
|
||
|
|
                {<br>
|
||
|
|
                        send
|
||
|
|
(<span class="hcp1">NAK</span>)      <span class="hcp23">/* The
|
||
|
|
received checksum was invalid */</span><br>
|
||
|
|
                }<br>
|
||
|
|
                got_escape
|
||
|
|
= <span class="hcp22">false</span>      <span class="hcp23">/* Clear
|
||
|
|
the "escape received" status */</span><br>
|
||
|
|
        }<br>
|
||
|
|
        <span class="hcp24">else</span> <span class="hcp24">if</span> (character
|
||
|
|
= <span class="hcp1">ESC</span>)<br>
|
||
|
|
        {<br>
|
||
|
|
                got_escape
|
||
|
|
= <span class="hcp22">true</span>       <span class="hcp23">/* Set
|
||
|
|
the "escape received" status */</span><br>
|
||
|
|
        }<br>
|
||
|
|
        <span class="hcp24">else</span><br>
|
||
|
|
        {<br>
|
||
|
|
                <span class="hcp24">if</span> (got_escape
|
||
|
|
= <span class="hcp22">true</span>)<br>
|
||
|
|
                {<br>
|
||
|
|
                        <span class="hcp23">/* The
|
||
|
|
last character was <span class="hcp1">ESC</span>
|
||
|
|
- this must be an escaped control code */</span><br>
|
||
|
|
                        add_byte_to_message_buffer
|
||
|
|
(character - <span class="hcp22">128</span>)<br>
|
||
|
|
                        checksum
|
||
|
|
= checksum XOR (character - <span class="hcp22">128</span>)<br>
|
||
|
|
                }<br>
|
||
|
|
                <span class="hcp24">else</span><br>
|
||
|
|
                {<br>
|
||
|
|
                        <span class="hcp23">/* The
|
||
|
|
last character was not <span class="hcp1">ESC</span>
|
||
|
|
- this must be an ordinary byte */</span><br>
|
||
|
|
                        add_byte_to_message_buffer
|
||
|
|
(character)<br>
|
||
|
|
                        checksum
|
||
|
|
= checksum XOR character<br>
|
||
|
|
                }<br>
|
||
|
|
                got_escape
|
||
|
|
= <span class="hcp22">false</span>      <span class="hcp23">/* Clear
|
||
|
|
the "escape received" status */</span><br>
|
||
|
|
        }<br>
|
||
|
|
}<br>
|
||
|
|
</p>
|
||
|
|
</div>
|
||
|
|
<p><!-- Saved in parser cache with key bugs:pcache:idhash:2753-0!1!0!0!!en!2 and timestamp 20080206161223 --></p>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<p class="hcp8"> </p>
|
||
|
|
</body>
|
||
|
|
</html>
|