Black Box | KVP4000A-R3 | Use DCP to control the ServSwitch 4site.

KVP4000A-R3
ServSwitch™ 4site II Device Control Protocol (DCP-XML)
Use DCP to control the ServSwitch 4site.
BLACK BOX
®
• Control the ServSwitch 4site via a computer or other device, using the
RS-232 serial port.
• Control the ServSwitch 4site remotely in large-scale KVM systems.
• Query and change all important ServSwitch 4site settings.
Customer
Support
Information
KVP4000A-R3 DCP-XML
Order toll-free in the U.S.: Call 877-877-BBOX (outside U.S. call 724-746-5500)
FREE technical support 24 hours a day, 7 days a week: Call 724-746-5500 or fax 724-746-0746
Mailing address: Black Box Corporation, 1000 Park Drive, Lawrence, PA 15055-1018
Web site: www.blackbox.com • E-mail: info@blackbox.com
Table of Contents
Table of Contents
1. Introduction .................................................................................................................................................................................3
2
Settings
.................................................................................................................................................................................5
2.1
Changing Settings.................................................................................................................................................................5
2.2
Querying Settings..................................................................................................................................................................6
2.3
Error Messages......................................................................................................................................................................7
3.
Simple Elements................................................................................................................................................................................8
3.1
Device Type...........................................................................................................................................................................8
3.2
Version Information...............................................................................................................................................................9
3.3
Console Channel...................................................................................................................................................................9
3.4
Video Channel.......................................................................................................................................................................9
3.5
Video Layout....................................................................................................................................................................... 10
3.6
PiP Layout............................................................................................................................................................................ 10
3.7
PiP Size............................................................................................................................................................................... 11
3.8
PiP Offset............................................................................................................................................................................ 11
3.9
PiP Zoom............................................................................................................................................................................. 12
3.10 PiP Channel......................................................................................................................................................................... 12
3.11 Dual Channels..................................................................................................................................................................... 13
3.12 PiP Scan Time...................................................................................................................................................................... 13
3.13 Security Levels..................................................................................................................................................................... 14
Page 2
724-746-5500 | blackbox.com
KVP4000A-R3 DCP-XML
Chapter 1: Introduction
Device Control Protocol (DCP)
1. Introduction
DCP-XML permits control of the ServSwitch 4site by a computer or other device, using the RS-232 serial port.
DCP-XML allows remote control of the ServSwitch 4site to facilitate its deployment in large-scale KVM systems.
DCP is an XML-based protocol. Using DCP, all important settings of the ServSwitch 4site can be queried and changed.
A description of XML can be found at http://www.w3.org/XML/
The XML Schema for DCP can be found on the enclosed CD, under the name “DCP.xsd”
DCP Modes
DCP has two modes of operation.
Control
This mode is intended for direct control of a ServSwitch 4site, for example using a computer.
Synchronize
This mode is used to synchronize multiple, linked devices.
In Synchronize mode, the ServSwitch 4site sends all settings changes as DCP messages.
Thus, a chain of linked ServSwitch 4site units can be controlled synchronously.
Important:
When Synchronize mode is first activated, and on startup (in Synchronize mode), a ServSwitch 4site sends all its settings as a DCP
message to synchronize all connected devices. Thus, it is recommended to switch on all connected ServSwitch 4site starting with
the last device in the chain, and proceeding backwards to the first ServSwitch 4site. This ensures that all devices have the same
settings.
When connecting a chain of linked ServSwitch 4sites, do not connect the last device in the chain to the first device (i.e. it is not
possible to make a ring).
NOTE: In the descriptions in this manual, XML has been formatted using indentation to make it easier to read. This type of
formatting is not needed when communicating with the device.
Using DCP, it is possible to create inconsistent settings. For example, you could set single PiP mode, with fullscreen Channel 1 and
PiP Channel 2, with mouse/keyboard control of Channel 2 (i.e. the PiP), or even mouse/keyboard control of another, non-visible
channel.
In DCP, settings data is contained inside XML elements. An XML element consists of an opening tag—the element name in angle
brackets—the element contents, and finally a closing tag—a slash followed by the element name.
Example: <tag>contents</tag>.
A element with no contents is referred to as an empty element.
An empty element may be abbreviated as <tag/>.
Elements containing sub-elements are referred to as complex elements. Elements with values are called simple elements. The
sub-elements of complex elements may be arranged in any order.
The message on the next page includes all elements supported in DCP V 1.2. Not all elements must be used in a message.
KVP4000A-R3 DCP-XML
724-746-5500 | blackbox.com
Page 3
Chapter 1: Introduction
Example of a DCP-XML message containing all elements
<dcp-xml>
<device>
<type>VSQ</type>
<version>
<dcp-protocol>1.2</dcp-protocol>
<hardware>34</hardware>
<software>1.31c</software>
</version>
<mode>
<console>
<channel>0</channel>
</console>
<video>
<channel>0</channel>
<layout>pip</layout>
<pip>
<layout>single-fixed</layout>
<size>25</size>
<offset>0</offset>
<zoom>100</zoom>
<channel>0</channel>
<direct>
<channel>0</channel>
</direct>
<fixed>
<channel>0</channel>
</fixed>
<dual>
<left-channel>0</left-channel>
<right-channel>1</right-channel>
</dual>
<scan-time>5</scan-time>
</pip>
</video>
</mode>
</device>
</dcp-xml>
To change settings, send a DCP message containing the desired settings.
Page 4
724-746-5500 | blackbox.com
KVP4000A-R3 DCP-XML
Chapter 1: Introduction/Chapter 2: Settings
Example:
Set console and video channel to Channel 1 (internal number 0).
<dcp-xml>
<device>
<mode>
<console>
<channel>0</channel>
</console>
<video>
<channel>0</channel>
</video>
</mode>
</device>
</dcp-xml>
In DCP control mode, a reply to this message containing the actually adopted settings is sent after configuration has been
completed.
<dcp-xml>
<device>
<mode>
<console>
<channel>0</channel>
</console>
<video>
<channel>0</channel>
</video>
</mode>
</device>
</dcp-xml>
2. Settings
2.1 Changing Settings
The example below is a DCP message containing illegal values.
The message attempts to modify the device type (read-only), and to change PiP size to an invalid value (200%):
<dcp-xml>
<device>
<version>
<dcp-protocol>1.0</dcp-protocol>
</version>
<mode>
<video>
<pip>
<size>200</size>
</pip>
</video>
</mode>
</device>
</dcp-xml>
KVP4000A-R3 DCP-XML
724-746-5500 | blackbox.com
Page 5
Chapter 2: Settings
In DCP control mode, the ServSwitch 4site reply to this message contains the invariable version number “1.2“ and the maximum
valid value for PiP size, i.e. 50:
<dcp-xml>
<device>
<version>
<dcp-protocol>1.2</dcp-protocol>
</version>
<mode>
<video>
<pip>
<size>50</size>
</pip>
</video>
</mode>
</device>
</dcp-xml>
The size parameter may vary depending on PiP number and display mode.
In cases involving invalid numeric values, the device will convert the value to the nearest valid value and include this value in its
reply.
PiP size, for example cannot be set in steps of 1%.
2.2 Querying Settings
Empty elements are interpreted as queries. Empty complex elements are considered as a query of the entire contents, i.e. the
sub-tree of the element in question. Queries are only replied to in DCP control mode.
Example of a query for the entire device status:
<dcp-xml/>
You can of course also query individual values or sub-trees.
You can query and set values in one DCP message.
In the following example, the console and video channel settings are queried:
<dcp-xml>
<device>
<mode>
<console/>
<video>
<channel/>
</video>
</mode>
</device>
</dcp-xml>
Page 6
724-746-5500 | blackbox.com
KVP4000A-R3 DCP-XML
Chapter 2: Settings
A ServSwitch 4site will reply to this command by sending the following message:
<dcp-xml>
<device>
<mode>
<console>
<channel>0</channel>
</console>
<video>
<channel>0</channel>
</video>
</mode>
</device>
</dcp-xml>
2.3 Error Settings
Error messages have the following format:
<dcp-xml>
<error>text</error>
</dcp-xml>
Here also, indentation is used to make the error message easier to read. In reality, error messages look as follows:
<dcp-xml>[CR][LF]
<error>text</error>[CR][LF]
</dcp-xml>[CR][LF]
DCP V1.2 contains the following error messages:
• malformed xml Malformed XML.
• tag mismatch Opening and closing tags do not match.
• tag not closed Opening tag without matching closing tag. Only occurs with simple
elements. In the case of complex elements, a timeout error is reported.
• subtag in simple element A simple element contains a subtag.
• tag name too long Tag name exceeding 16 characters.
• wrong data type Incorrect data type. For list types, such as device name, this error
message also refers to values not included in the list.
• content too long Contents of a simple element exceeding 30 characters.
• timeout Receive timeout. This error message is displayed if a DCP message is
not complete after expiry of the timeout, but no other error has occurred.
• parser stack overflow This error occurs when unknown elements are nested too deeply, or in
the case of an internal error.
• internal parser error Internal error parser error.
• unknown error Unknown error.
DCP-XML messages exceeding 38 characters must be divided into individual lines before being sent to a device.
Replies sent by a device are also divided into lines.
KVP4000A-R3 DCP-XML
724-746-5500 | blackbox.com
Page 7
Chapter 2: Settings/Chapter 3: Simple Elements
When sending a DCP message, the following constraints apply:
Serial Port Settings: 57600 baud, 8-N-1
Configure the serial port with the following settings:
Speed: 57600 bps
Data Bits: 8
Parity: none
Stop Bits: 1
Flow Control: none
Linefeed: LF
Linefeed (0x0A) is used as terminating character of each line.
Whitespace: TAB, SPACE, CR
Whitespace characters are Tab (0x09), Space (0x20) and Carriage Return (0x0D).
Whitespace may occur anywhere between two tags, except at the start of a line and inside simple elements
Whitespace is ignored.
Line length: maximum 38 characters
The line length may not exceed 38 characters. (Not including the terminating LF.)
Timeout: 750 ms
Timeout for DCP messages is 750 milliseconds.
DCP messages containing errors are not regarded as completed until the timeout period has elapsed.
Therefore, it is recommended to wait for this time between DCP messages to allow the parser to handle possible errors.
Correct messages are processed immediately upon completion.
Unknown elements
Unknown tags in a DCP message are ignored for the sake of upwards compatibility of the protocol.
Messages containing unknown elements must still be syntactically correct.
Unknown tags may not be nested deeper than 5 levels.
3. Simple Elements
The valid values of simple elements are specified below:
3.1 Device Type
DEVICE TYPE
<dcp-xml>
<device>
<type>VSQ</type>
</device>
</dcp-xml>
Type of connected device.
read-only
Valid values: Page 8
VSQ ServSwitch 4site
724-746-5500 | blackbox.com
KVP4000A-R3 DCP-XML
Chapter 3: Simple Elements
3.2 Version Information
<dcp-xml>
<dcp-xml>
<device>
<version>
<dcp-protocol>1.2</dcp-protocol>
<hardware>34</hardware>
<software>1.31c</software>
</version>
</device>
</dcp-xml>
DCP, hardware, and software version. These tags may also be used individually.
NOTE: Numerical settings in DCP start off numbered at “0“. Thus, the first channel is channel 0, and the last channel is channel 3.
3.3 Console Channel
<dcp-xml>
<device>
<mode>
<console>
<channel>0</channel>
</console>
</mode>
</device>
</dcp-xml>
Active console channel, i.e. the channel that receives keyboard/mouse input.
Valid values: 0–3
3.4 Video Channel
<dcp-xml>
<device>
<mode>
<video>
<channel>0</channel>
</video>
</mode>
</device>
</dcp-xml>
Active video channel, i.e. the channel displayed in full-screen mode.
Valid values: 0–3
KVP4000A-R3 DCP-XML
724-746-5500 | blackbox.com
Page 9
Chapter 3: Simple Elements
3.5 Video Layout
<dcp-xml>
<device>
<mode>
<video>
<layout>full</layout>
</video>
</mode>
</device>
</dcp-xml>
Video layout
Valid values: full Fullscreen mode
quad Quad mode
pip Fullscreen mode with PiP function
3.6 PiP Layout
<dcp-xml>
<device>
<mode>
<video>
<pip>
<layout>triple-gap</layout>
</pip>
</video>
</mode>
</device>
</dcp-xml>
PiP mode
Valid values: triple-gap triple PiP with gap
triple-no-gap triple PiP without gap
single-fixed single PiP, fixed channel selection
single-direct single PiP, direct channel selection
single-scan single PiP, channel scanning
Page 10
724-746-5500 | blackbox.com
KVP4000A-R3 DCP-XML
Chapter 3: Simple Elements
3.7 PiP Size
<dcp-xml>
<device>
<mode>
<video>
<pip>
<size>15</size>
</pip>
</video>
</mode>
</device>
</dcp-xml>
PiP size in percentage of full-screen height.
Valid values: 0–50 for single PiP
0–33
0–25 for triple PiP with gap
for triple PiP without gap
Actual valid values for ServSwitch 4site: 3, 5, 7, 10, 15, 20, 25, 28, 33, 38, 44, 50
3.8 PiP Offset
<dcp-xml>
<device>
<mode>
<video>
<pip>
<offset>5</offset>
</pip>
</video>
</mode>
</device>
</dcp-xml>
PiP offset from the top screen edge in percentage of full-screen height.
Valid values: 0–97, depending on PiP size and mode
KVP4000A-R3 DCP-XML
724-746-5500 | blackbox.com
Page 11
Chapter 3: Simple Elements
3.9 PiP Zoom
<dcp-xml>
<device>
<mode>
<video>
<pip>
<zoom>100</zoom>
</pip>
</video>
</mode>
</device>
</dcp-xml>
PIP zoom factor in percentage.
Valid values:
100 no zoom
200 2x zoom
3.10 PiP Channel
<dcp-xml>
<device>
<mode>
<video>
<pip>
<direct>
<channel>0</channel>
</direct>
</pip>
</video>
</mode>
</device>
</dcp-xml>
PiP channel in single, direct PiP mode.
Valid values: 0–3
Page 12
724-746-5500 | blackbox.com
KVP4000A-R3 DCP-XML
Chapter 3: Simple Elements
3.11 Dual Channels
<dcp-xml>
<device>
<mode>
<video>
<pip>
<dual>
<left-channel>0</left-channel>
<right-channel>1</right-channel>
</dual>
</pip>
</video>
</mode>
</device>
</dcp-xml>
PiP channel in single, fixed PiP mode.
Set the active channel using the setting for console channel.
Valid values: 0–3
3.12 PiP Scan Time
<dcp-xml>
<device>
<mode>
<video>
<pip>
<scan-time>1</scan-time>
</pip>
</video>
</mode>
</device>
</dcp-xml>
PiP scan time in seconds in single, scan PiP mode.
Valid values: 1–9
KVP4000A-R3 DCP-XML
724-746-5500 | blackbox.com
Page 13
Chapter 3: Simple Elements
3.13 Security Levels
The security level settings in the OSD menu described on page 28 of the user’s manual also apply to control via DCP messages.
Queries are possible up to security level 7.
The table below shows the maximum security levels for simple element settings. These settings may be changed via DCP up to
the specified protection level.
Maximum security level for:
CONSOLE CHANNEL 6
VIDEO CHANNEL
6
VIDEO LAYOUT 5
PiP LAYOUT
4
PiP SIZE 4
PiP OFFSET 4
PiP ZOOM 4
PiP CHANNEL 4
DUAL CHANNELS (L/R) 6
PiP SCAN TIME
Page 14
4
724-746-5500 | blackbox.com
KVP4000A-R3 DCP-XML
NOTES
KVP4000A-R3 DCP-XML
724-746-5500 | blackbox.com
Page 15
Black Box Tech Support: FREE! Live. 24/7.
Tech support the
way it should be.
Great tech support is just 30 seconds away at 724-746-5500 or blackbox.com.
About Black Box
Black Box Network Services is your source for an extensive range of networking and infrastructure products. You’ll find everything
from cabinets and racks and power and surge protection products to media converters and Ethernet switches all supported by
free, live 24/7 Tech support available in 30 seconds or less.
© Copyright 2012. Black Box Corporation. All rights reserved. Black Box® and the Double Diamond logo are registered trademarks, and ServSwitch is a
trademark, of BB Technologies, Inc. Any third-party trademarks appearing in this manual are acknowledged to be the property of their respective owners.
KVP4000A-R3, version 2, Device Control Protocol (DCP-XML)
724-746-5500 | blackbox.com
KVP4000A-R3 DCP-XML
Download PDF

advertising