Kramer KDS-USB2 Kit User manual

P/N: 2900-301454 Rev 1 www.kramerAV.com
USER MANUAL
MODEL:
SwitchableUSB
Device Configuration Network Protocol

Kramer Electronics Ltd.
SwitchableUSB –Contents
i
Contents
Introduction 1
1Overview 2
2General Information 3
2.1 Generic Packet Structure 4
2.2 Network Broadcast Notes 5
3Supported Messages 6
3.1 Request Device Information 7
3.2 Reply Device Information 8
3.3 Ping 9
3.4 Acknowledge 10
3.5 Request Extended Device Information 11
3.6 Reply Extended Device Information 12
3.7 Pair To Device 13
3.8 Remove Device Pairing 14
3.9 Request Device Topology 15
3.10 Reply Device Topology 16
3.11 Use DHCP 17
3.12 Use Static IP 18
3.13 Negative Acknowledge 19
3.14 Use Filtering Strategy 20
3.15 LED Locator On 21
3.16 Led Locator Off 22
3.17 Reset Device 23
3.18 Request Configuration Response Data 24
3.19 Reply Configuration Response Data 25
3.20 Request Link Status 27
3.21 Reply Link Status 28
3.22 Remove All Pairings 30
3.23 Force Pair To Device 31
4 Appendix A 32
4.1 Abbreviations 33
4.3 References 34

Kramer Electronics Ltd.
SwitchableUSB –Introduction
1
Introduction
Welcome to Kramer Electronics! Since 1981, Kramer Electronics has been providing a world
of unique, creative, and affordable solutions to the vast range of problems that confront the
video, audio, presentation, and broadcasting professional on a daily basis. In recent years, we
have redesigned and upgraded most of our line, making the best even better!

Kramer Electronics Ltd.
SwitchableUSB –1 Overview
2
1 Overview
SwitchableUSB™Device Configuration Network Protocol provides the ability to discover and
configure ExtremeUSB®extenders on a local ethernet network. The protocol works on top of UDP, so it
should be possible to write a configuration client for almost any platform. The devices will listen on
UDP port 6137 for incoming messages and replies will be sent back to the port that the request
originated from. The USB extenders will include a DHCP client that will enable them to obtain an IP
address from a DHCP server on the network. The devices may alternatively be assigned a static
network configuration using UDP broadcast packets in the form of a Use Static IP message described
later in this document.
Figure 1: USB extenders on a local network

Kramer Electronics Ltd.
SwitchableUSB –2 General Information
3
2 General Information

Kramer Electronics Ltd.
SwitchableUSB –2 General Information
4
2.1 Generic Packet Structure
All packets contain the following:
Magic Number
A value (0x2F03F4A2) which gives some confidence that the data
which follows is a configuration message.
Message ID
When the client sends a request, it chooses any value to insert in
this field. The device responding to the request will set this field in
the reply to the same value it received in the request.
Protocol Version
An integer from 0-255. All devices will support protocol 0 and one
other protocol version. The Reply Device Information message
will inform a client which version of the protocol it must speak in
order to communicate with the device.
Command
An integer from 0-255. This is the identifier of the command. The
combination of the protocol version and the command identify a
unique message type. In other words, command 5 in protocol 1 is
likely different from command 5 in protocol 3.
•All multi-byte fields are packed as big endian.
•Messages are at least 10 bytes and at most 136 bytes in length.
•Any string fields should be encoded using UTF-8.

Kramer Electronics Ltd.
SwitchableUSB –2 General Information
5
2.2 Network Broadcast Notes
Further information about Network Broadcast Notes can be found at the references section.
2.2.1 Subnet Broadcast
To broadcast a packet to a subnet you only have to use the broadcast IP of the subnet. For example to
broadcast to a network configured as an IP range of 192.168.5.xxx, and a netmask of 255.255.255.0,
the IP 192.168.5.255 is the broadcast IP address. For example to broadcast to a network
configured as an IP range of 10.xxx.xxx.xxx, and a netmask of 255.0.0.0, the IP
10.255.255.255 is the broadcast IP address.
Routers will drop broadcast IP packets, destined for an address outside of the source address
device’s network; which means that any broadcast packet must originate on the same
network as the target devices.
2.2.2 All Local Subnet Broadcast
By broadcasting to the IP address 255.255.255.255 a broadcast packet can be sent out,
without previously knowing what the local network is. Microsoft Windows will however only
send the packet out the first configured network interface, so on a computer with multiple
interfaces, each interface should sent a broadcast network packet separately.
2.2.3 Mismatched Network Configuration
When broadcasting to a subnet using the network broadcast address (for example
192.168.5.255), and the device is configured for a different network (for example
IP=10.0.9.23, netmask=255.0.0.0), then the device will not respond to the broadcast as it will
not recognize the IP address as a valid broadcast.
This shouldn’t happen with a proper DHCP server allocated addresses out of the same pool
for the network. It could potentially happen when assigning static IP addresses, and moving
units between networks. If this does happen the unit will need to be reset to DHCP by the
push button, as described in the user’s guide, and then the static IP address can be assigned
to the unit.

Kramer Electronics Ltd.
SwitchableUSB –3 Supported Messages
6
3 Supported Messages

Kramer Electronics Ltd.
SwitchableUSB –3 Supported Messages
7
3.1 Request Device Information
This message is sent from the client to a device in order to solicit a Reply Device Information message.
This message can be sent in a broadcast UDP message in order to discover all the configurable USB
extenders on the local network.
Byte Offset
+-----------------------------------------+-----------------------------------------+
0 | Magic Number |
+ +
2 | |
+-----------------------------------------+-----------------------------------------+
4 | Message ID |
+ +
6 | |
+-----------------------------------------+-----------------------------------------+
8 | Protocol Version = 0 | Command = 0 |
+-----------------------------------------+-----------------------------------------+

Kramer Electronics Ltd.
SwitchableUSB –3 Supported Messages
8
3.2 Reply Device Information
This message is sent from a device to a client in response to a Request Device Information
message.
3.2.1 Field Descriptions
MAC Address
The device's MAC address.
IP Address
The device's current IP address.
Network Acquisition Mode
0=DHCP, 1=Static
Supported Protocol Version
All devices must support protocol 0 and one other protocol number. This
value specifies which protocol version that is.
Vendor
A 32-byte NUL terminated string containing the device's vendor name.
Product
A 32-byte NUL terminated string containing the device's product name.
Revision
A 12-byte NUL terminated string containing the device's revision
number.
Byte Offset
+-----------------------------------------+-----------------------------------------+
0 | Magic Number |
+ +
2 | |
+-----------------------------------------+-----------------------------------------+
4 | Message ID |
+ +
6 | |
+-----------------------------------------+-----------------------------------------+
8 | Protocol Version = 0 | Command = 1 |
+-----------------------------------------+-----------------------------------------+
10 | MAC Address |
+ +
12 | |
+ +
14 | |
+-----------------------------------------+-----------------------------------------+
16 | IP Address |
+ +
18 | |
+-----------------------------------------+-----------------------------------------+
20 | Network Acquisition Mode | Supported Protocol Version |
+-----------------------------------------+-----------------------------------------+
22 | Vendor |
+ +
. . .
. . .
. . .
+ +
52 | |
+-----------------------------------------+-----------------------------------------+
54 | Product |
+ +
. . .
. . .
. . .
+ +
84 | |
+-----------------------------------------+-----------------------------------------+
86 | Revision |
+ +
. . .
. . .
. . .
+ +
96 | |
+-----------------------------------------+-----------------------------------------+

Kramer Electronics Ltd.
SwitchableUSB –3 Supported Messages
9
3.3 Ping
This message is sent from a client to a device. It is used to check if a device is active. An
Acknowledge message will be sent by the device in response.
Byte Offset
+-----------------------------------------+-----------------------------------------+
0 | Magic Number |
+ +
2 | |
+-----------------------------------------+-----------------------------------------+
4 | Message ID |
+ +
6 | |
+-----------------------------------------+-----------------------------------------+
8 | Protocol Version = 0 | Command = 2 |
+-----------------------------------------+-----------------------------------------+

Kramer Electronics Ltd.
SwitchableUSB –3 Supported Messages
10
3.4 Acknowledge
This message is a generic ACK message that will be sent in response to all requests made by clients
that do not require returning an additional data payload in the response. The Message ID field should
be sufficient to determine which message is being ACKed.
Byte Offset
+-----------------------------------------+-----------------------------------------+
0 | Magic Number |
+ +
2 | |
+-----------------------------------------+-----------------------------------------+
4 | Message ID |
+ +
6 | |
+-----------------------------------------+-----------------------------------------+
8 | Protocol Version = 0 | Command = 3 |
+-----------------------------------------+-----------------------------------------+

Kramer Electronics Ltd.
SwitchableUSB –3 Supported Messages
11
3.5 Request Extended Device Information
Sent by a client to a device in order to obtain additional information about the device that is
not included in the Reply Device Information message from protocol 0.
Byte Offset
+-----------------------------------------+-----------------------------------------+
0 | Magic Number |
+ +
2 | |
+-----------------------------------------+-----------------------------------------+
4 | Message ID |
+ +
6 | |
+-----------------------------------------+-----------------------------------------+
8 | Protocol Version = 3 | Command = 0 |
+-----------------------------------------+-----------------------------------------+

Kramer Electronics Ltd.
SwitchableUSB –3 Supported Messages
12
3.6 Reply Extended Device Information
Sent by a device to a client in response to a Request Extended Device Information message.
3.6.1 Field Descriptions
ENCODER/DECODER
0=Device is a ENCODER, 1=Device is a DECODER
Paired With MAC Address
MAC address of a device that this device is paired with. This field is
optional and may be repeated up to 7 times.
Byte Offset
+-----------------------------------------+-----------------------------------------+
0 | Magic Number |
+ +
2 | |
+-----------------------------------------+-----------------------------------------+
4 | Message ID |
+ +
6 | |
+-----------------------------------------+-----------------------------------------+
8 | Protocol Version = 3 | Command = 1 |
+-----------------------------------------+-----------------------------------------+
10 | ENCODER/DECODER| Paired With MAC Address
|
+--> +-----------------------------------------+ +
| 12 | |
| + +
| 14 | |
| + +-----------------------------------------+
|16 | |
+--> +-----------------------------------------+
|
+--- Repeated 0 or 1 times for a DECODER or a ENCODER in point-to-point mode or 0 to 7 times for
a ENCODER with virtual hub enabled

Kramer Electronics Ltd.
SwitchableUSB –3 Supported Messages
13
3.7 Pair To Device
Sent by a client to a device to instruct a device to try to pair with a different device specified in this
message. A client must send this message to a ENCODER and a DECODER to instruct them to pair
together, but the order of the two messages does not matter. The device will respond with an
Acknowledge message if it is able to pair with a new device or a Negative Acknowledge message
otherwise. The transmission of the Acknowledge message only indicates that an attempt will be made
to establish a link between the devices, not that a link is already established.
3.7.1 Field Descriptions
Pair To Device MAC Address
The MAC address that the client is telling the device to attempt to pair
with.
Byte Offset
+-----------------------------------------+-----------------------------------------+
0 | Magic Number |
+ +
2 | |
+-----------------------------------------+-----------------------------------------+
4 | Message ID |
+ +
6 | |
+-----------------------------------------+-----------------------------------------+
8 | Protocol Version = 3 | Command = 2 |
+-----------------------------------------+-----------------------------------------+
10 | Pair To Device MAC Address |
+ +
12 | |
+ +
14 | |
+-----------------------------------------+-----------------------------------------+

Kramer Electronics Ltd.
SwitchableUSB –3 Supported Messages
14
3.8 Remove Device Pairing
Sent by a client to a device to instruct a device to discard any existing pairing it has. This will
effectively disconnect any USB devices that were downstream of the remote extender. The client must
send a Remove Device Pairing message to each of the devices in the pairing. The device will send an
Acknowledge message in response to a Remove Device Pairing message or a Negative
Acknowledge if the device is already unpaired or paired to a different device than the one
specified.
3.8.1 Field Descriptions
Paired MAC Address
The MAC address that the client is telling the device to disassociate
from.
Byte Offset
+-----------------------------------------+-----------------------------------------+
0 | Magic Number |
+ +
2 | |
+-----------------------------------------+-----------------------------------------+
4 | Message ID |
+ +
6 | |
+-----------------------------------------+-----------------------------------------+
8 | Protocol Version = 3 | Command = 3 |
+-----------------------------------------+-----------------------------------------+
10 | Paired MAC Address |
+ +
12 | |
+ +
14 | |
+-----------------------------------------+-----------------------------------------+

Kramer Electronics Ltd.
SwitchableUSB –3 Supported Messages
15
3.9 Request Device Topology
Sent by a client to a ENCODER device in order to obtain the set of USB devices in the system. A
DECODER device will send a Negative Acknowledge message in response to this message.
Byte Offset
+-----------------------------------------+-----------------------------------------+
0 | Magic Number |
+ +
2 | |
+-----------------------------------------+-----------------------------------------+
4 | Message ID |
+ +
6 | |
+-----------------------------------------+-----------------------------------------+
8 | Protocol Version = 3 | Command = 4 |
+-----------------------------------------+-----------------------------------------+

Kramer Electronics Ltd.
SwitchableUSB –3 Supported Messages
16
3.10 Reply Device Topology
Sent by a ENCODER device in response to a Request Device Topology message. This message is of
variable length depending on the number of devices that are in the system. The combination of the
information is enough for a client to build and display a device tree.
3.10.1 Field Descriptions
USB Address
An integer from 0 to 127.
USB Address Of Parent
An integer from 1 to 127. If a USB Address is seen which is not listed as
the USB Address Of Parent for any of the devices, then that device is
the root of the device topology.
Port On Parent
An integer from 1 to 127. 0 is not a valid number for a port on a hub, so
this field will only be 0 if there is no USB device upstream before the
host.
Is Device A Hub
0=FALSE, 1=TRUE
USB Vendor Id
The USB vendor id from the device descriptor.
USB Product Id
The USB product id from the device descriptor.
Byte Offset
+-----------------------------------------+-----------------------------------------+
0 | Magic Number |
+ +
2 | |
+-----------------------------------------+-----------------------------------------+
4 | Message ID |
+ +
6 | |
+-----------------------------------------+-----------------------------------------+
8 | Protocol Version = 3 | Command = 5 |
+--> +-----------------------------------------+-----------------------------------------+
| 10 | USB Address | USB Address Of Parent |
| +-----------------------------------------+-----------------------------------------+
| 12 | Port On Parent | Is Device A Hub |
| +-----------------------------------------+-----------------------------------------+
| | USB Vendor Id |
| +-----------------------------------------------------------------------------------+
| | USB Product Id |
+--> +-----------------------------------------------------------------------------------+
|
+--- Repeated 0 to MAX_USB_DEVICES(= 32) times

Kramer Electronics Ltd.
SwitchableUSB –3 Supported Messages
17
3.11 Use DHCP
Sent by a client to a device to tell a device that it should use DHCP to obtain an IP. This message may
be sent as either as a UDP broadcast packet or a packet directed to a specific IP in the case that the
device has a valid, known static IP address already. Regardless of whether the message was sent as
a broadcast or not, the device will only switch into DHCP mode if the Target MAC Address field
matches the MAC address of the device. When a valid Use DHCP message is received the device will
send an Acknowledge message from its current IP address before discarding its static address
configuration and beginning acquisition of an IP address via DHCP. If a Use DHCP message is
received when the device is already in DHCP mode, the device will send an Acknowledge message,
but this will not trigger any other action on the device such as IP renewal. The client is able to tell
which mode a device is in by inspecting the Network Acquisition Mode field of the Reply Device
Information message.
3.11.1 Field Descriptions
Target MAC Address
The MAC address of the device which will be set to use DHCP to obtain
an IP address.
Byte Offset
+-----------------------------------------+-----------------------------------------+
0 | Magic Number |
+ +
2 | |
+-----------------------------------------+-----------------------------------------+
4 | Message ID |
+ +
6 | |
+-----------------------------------------+-----------------------------------------+
8 | Protocol Version = 3 | Command = 6 |
+-----------------------------------------+-----------------------------------------+
10 | Target MAC Address |
+ +
12 | |
+ +
14 | |
+-----------------------------------------+-----------------------------------------+

Kramer Electronics Ltd.
SwitchableUSB –3 Supported Messages
18
3.12 Use Static IP
Sent by a client to a device to tell a device that it should use the static network configuration contained
within this message. The IP, subnet mask and default gateway as well as the network configuration
are stored in permanent storage, so the device will keep the same network configuration after being
power cycled. Similarly to the Use DHCP message, this message may be broadcast or sent to a
specific device. An acknowledge message will always be sent back to the client when a Use Static IP
message is received by a device providing that the Target MAC Address parameter matches the MAC
address of the device. Sending a Use Static IP message to a device already in a static configuration
will enable a client to change the IP, subnet mask or default gateway of the device.
3.12.1 Field Descriptions
Target MAC Address
The MAC address of the device which will be set to use static network
configuration.
IPv4 Address
The IPv4 address being assigned to this device encoded as a 32 bit
integer.
Subnet Mask
The subnet mask of the network that this device is on.
Default Gateway
Sets the default gateway of the device.
Byte Offset
+-----------------------------------------+-----------------------------------------+
0 | Magic Number |
+ +
2 | |
+-----------------------------------------+-----------------------------------------+
4 | Message ID |
+ +
6 | |
+-----------------------------------------+-----------------------------------------+
8 | Protocol Version = 3 | Command = 7 |
+-----------------------------------------+-----------------------------------------+
10 | Target MAC Address |
+ +
12 | |
+ +
14 | |
+-----------------------------------------+-----------------------------------------+
16 | IPv4 Address |
+ +
18 | |
+-----------------------------------------+-----------------------------------------+
20 | Subnet Mask |
+ +
22 | |
+-----------------------------------------+-----------------------------------------+
24 | Default Gateway |
+ +
26 | |
+-----------------------------------------+-----------------------------------------+