Thinklogical ASCII-API User Manual

Download

Router ASCII API V4

Thinklogical, LLC

100 Washington Street

Milford, Connecticut 06460 U.S.A.

Telephone : 1-203-647-8700

Fax : 1-203-783-0049

www.thinklogical.com

Revision: E

Table of Contents

Overview.................................................................................................................................................................. 3

HDX switch support............................................................................................................................................. 3

MX switch support............................................................................................................................................... 3

XOPTIONS command......................................................................................................................................... 3

Conventions............................................................................................................................................................. 4

Port numbers...................................................................................................................................................... 4

Results................................................................................................................................................................ 4

Upper vs. Lower case.......................................................................................................................................... 5

Commands.............................................................................................................................................................. 6

Connection commands........................................................................................................................................ 6

Connect.......................................................................................................................................................... 6

Disconnect..................................................................................................................................................... 6

Frame Synchronize........................................................................................................................................ 6

Status............................................................................................................................................................. 7

XGET............................................................................................................................................................. 7

XPUT............................................................................................................................................................. 7

Macro............................................................................................................................................................. 8

XSTATUSIO and XSTATUSOI........................................................................................................................ 8

System Information commands........................................................................................................................... 9

XVERSION..................................................................................................................................................... 9

XINSTALLED.................................................................................................................................................. 9

XDCSTYPE.................................................................................................................................................... 9

XMAXPORTS................................................................................................................................................. 9

XLASTEVENT.............................................................................................................................................. 10

XPORTCONFIG........................................................................................................................................... 10

XALARM...................................................................................................................................................... 10

XRESET....................................................................................................................................................... 10

XCRON and XCROFF.................................................................................................................................. 11

XMAXCARDS............................................................................................................................................... 11

XQUIT.......................................................................................................................................................... 11

XOPTIONS................................................................................................................................................... 12

XHELP......................................................................................................................................................... 12

XSYNCSTATUS........................................................................................................................................... 13

VxRouter Port Numbering...................................................................................................................................... 14

Error and Status Codes.......................................................................................................................................... 26

API V3 Commands Removed from Version 4......................................................................................................... 27

Changing from V3 to V4 API commands................................................................................................................ 28

Appendix A: Switch Status Broadcast..................................................................................................................... 29

Appendix B: Sample Commands............................................................................................................................ 29

Appendix C: Connecting Extenders........................................................................................................................30

A) VEL-24DH through a VX80........................................................................................................................... 30

B) VEL-4 and VEL-24 through a VX160............................................................................................................. 31

Appendix D: Point-to-Point Connection mode......................................................................................................... 32

API Manual Revision History..................................................................................................................................33

Index of Tables

Table 1: Upper vs. Lower case................................................................................................................................. 5

Table 2: XMAXCARDS return values...................................................................................................................... 11

Table 3: V3 vs. V4 commands................................................................................................................................ 28

Jun 12, 2014 Router ASCII API: V4.5-1 1/33

Illustration Index

Illustration 1: Vx40 Port Numbering........................................................................................................................15

Illustration 2: Vx40 / Vx80 Connections.................................................................................................................. 16

Illustration 3: Vx160 Port Numbering...................................................................................................................... 17

Illustration 4: Vx160 Connections........................................................................................................................... 18

Illustration 5: Vx320 Port Numbering...................................................................................................................... 19

Illustration 6: Vx320 Port Connections.................................................................................................................... 20

Illustration 7: Vx320-Video Port Numbering............................................................................................................ 21

Illustration 8: Hx80 / Vx80 Port Numbering............................................................................................................. 22

Illustration 9: Hx576 Port Numbering......................................................................................................................23

Illustration 10: Mx48 Port Numbering..................................................................................................................... 24

Illustration 11: VX640 Port Numbering.................................................................................................................... 25

Overview

Unless stated otherwise, references to a VxRouter also apply to a MxRouter and a HdxRouter.

This document describes the command set used to control Thinklogical's VxRouter series of matrix switches. The commands are all ASCII based and are terminated with either a linefeed character or a carriage-return / linefeed pair. Port numbers are all 4 digits in length and filled with leading zeros (Example: port 12 is encoded as 0012).

The VxRouter commands are based on the command set used by our DCS product line. Some DCS commands were removed because they did not apply to the VxRouter system. New commands were added to accommodate features in the VxRouters that were not in the DCS.

This release of API version 4.x marks a radical departure in the procedure used to make or break connections. Previously, the VxRouter was treated as having 'N' number of bidirectional ports. When a connection command was received, in most cases two connection paths were created. One path allowed information to flow from a transmitter to a receiver, and the second path allowed information to flow from the receiver to the transmitter. The second path was sometimes referred to as the 'low speed channel' or the 'back-channel'.

Automatic path creation required only one connection command to create two connection paths. The software took care of maintaining the second path. The drawback from this feature is that none of the ports used by the second path were available for any other use. This could lead to half or more of the ports on a VxRouter being unusable.

The API commands have been modified in this version of the interface (Version 4.x). These commands give the user complete control over every input and output port of the VxRouter switch matrix. The drawback is the need to issue two commands to connect or disconnect bidirectional data instead of one command. You still need only one command to connect or disconnect video data.

The ability to make any possible connection means that it is now possible to have one keyboard/mouse connected to multiple CPU’s. The user can be watching the video from, and interacting with, CPU A while simultaneously sending keystrokes to CPU’s A, B, C, D,...

HDX switch support.

The HDX series of switches uses the same API as the VxRouters. Because the HDX implements synchronized switching, a method to cause a sync'd switch event to occur was needed. The HDX API will synchronize switching when it receives a line feed (LF) at the end of a switch command. These switch commands are: Connect, Disconnect, XPUT and Macro.

MX switch support.

The MX series of switches uses the same API as the VxRouters. The one difference is the XMAXCARDS command. It returns the actual maximum number of I/O cards allowed, not one-half the total. Refer to the XMAXCARDS section on page 11.

Unless otherwise indicated, references to VxRouters also apply to the HDX and MX models.

XOPTIONS command.

The new command XOPTIONS can be used to determine which command options are available in the api.

Jun 12, 2014 Router ASCII API: V4.5-1 3/33

Conventions

Port numbers

▪ All port numbers are four places long, start counting at 1 and have leading zeros. For example, port 15 is encoded

as 0015.

▪ A port number of 4 zeros is used in response to a status command to signify that no port is in use. A zero port

number is not valid in a command string.

▪ A port number of four 9s (9999) in used to signify ALL ports. It is not valid in a response.

For example, if you wanted to encode all output ports, you would use: O9999

▪ In the following sections, xxxx is used as a generic input port place holder; yyyy is used as the output port place

holder. Do not use xxxx or yyyy in a command, but replace each with the appropriate input or output port number.

Results

Results from commands are ASCII strings terminated with a newline (linefeed). The first character is an 'R', followed by a 4 digit, zero-filled length. The length includes the trailing newline. Following the length will be either 'OK', or 'ERnnnn'. OK signifies the command was successful, while ERnnnn is an error code. After the OK or ERnnnn, a comment may appear giving more detailed information.

In the case of a status command, the OK is followed by the status response.

You must wait for a result response before sending another command.

There are several options to control the output from the API. These options are described in detail in the document

Conguring-the-ASCII-Interface.pdf. Two of the options are:

1. [--CR] Include a carriage return on each line output. (Useful for Windows)

2. [--verbose] Append a comment to each response with more information about an error code, or repeat the successful command. Comments will start with the '#' character.

Examples of verbose output

Command: CI0004O0007

normal: R0003OK verbose: R0015OK#CI0004O0007

Command: CI0004O0087

normal: R0007ER0007 verbose: R0072ER0007#Output port number 87 is out of range (1 thru 80):

'CI0004O0087'

Jun 12, 2014 Router ASCII API: V4.5-1 4/33

Upper vs. Lower case

The upper case single letter commands (C,D,S) affect the upper shelf of a Vx320, the upstream to downstream paths of a Vx160, and all the paths on a Vx40, Vx80, Vx320v, Vx640, Hx80, Hx576, Mx48.

The lower case single letter commands (c,d,s) affect the lower shelf of a Vx320, the downstream to upstream paths of a Vx160, and are NOT valid on a Vx40.

All other commands may be in either case.

Vx40 Upper case only

Vx80 Upper case only

Vx160 Upper and Lower case required

Vx320 Upper and Lower case required

Vx320-Video Upper case only

Hx80 Upper case only

Hx576 Upper case only

Mx48 Upper case only

Vx640 Upper case only

Table 1: Upper vs. Lower case

Jun 12, 2014 Router ASCII API: V4.5-1 5/33

Commands

Connection commands

Connect

Connect one input port to one or more output ports. Connections are additive.

For example, connecting input 5 to output 7 will result in 7 being added to any existing connections to input 5. The 'i' and 'o' may be of either case.

Format: CixxxxOyyyyO....

cixxxxoyyyyo....

 xxxx of all 9's is illegal.  yyyy of all 9's will connect xxxx to all outputs.  Connections will be made in the order specified.

Example Results:

 R0003OK or R0007ERnnnn

When switching keyboard/mouse channels it is now possible to connect one keyboard/mouse to multiple computers. Unless the appropriate video connections are also made, you will be sending commands to computers that you are not currently viewing. This could have disastrous results!

Disconnect

Disconnect one or more input or output ports. Disconnecting outputs only affects that port, but disconnecting inputs will affect every output connected to that input. The 'i' and 'o' may be of either case.

Format: Dixxxx... or Doyyyy.....

dixxxx... or dOyyyy.....

 This will disconnect all outputs connected to input port xxxx or will disconnect output

port yyyy only.

 DI9999 or DO9999 will disconnect all the Upstream/Upper ports.  di9999 or do9999 will disconnect all the Downstream/Lower ports  It is not an error to disconnect a port that is not connected.

Example Results:

 R0003OK or R0007ERnnnn

Note: If you want to disconnect ALL the ports (Up and Down), you may use the XPUT command without listing any ports.

Frame Synchronize

On the HDX family of routers, configure the Sync card to use sync format N. N ranges from 0 to 63. Refer to the HDX manuals for the correct usage of the command. This command in not allowed in the Vx family of routers and it will return an error.

Format: F00nn

Jun 12, 2014 Router ASCII API: V4.5-1 6/33

Status

Return the connection status of an input or output port. Format: Sixxxx

sixxxx

 Return the list of output ports that are connected to input port xxxx.  If nothing is connected to port xxxx, 0000 will be returned.

Format: Soyyyy

soyyyy

 Return the input port number that is connected to output port yyyy.  If nothing is connected to port xxxx, 0000 will be returned.

Example Results (SI):

 RnnnnOKIxxxxOyyyyOyyyyOyyyy... or R0007ERnnnn

 xxxx is connected to output(s) yyyy.

 0000 means not connected.

Example Results (SO):

 RnnnnOKIxxxxOyyyy or R0007ERnnnn

 xxxx is connected to output yyyy.  0000 means not connected.

XGET

Return the entire switch connection state. The output from this command is used by the XPUT command. Format: XGET

 This will return a (very) long string listing every connection. The connection list consists

of a series of input port numbers, followed by output port numbers.

 The XPUT command requires all the characters in the response that come after the

'OK'.

Example Results:

 R0037OKI00010003I00020004i0010001000110012  R0029OKI00010003I0010001000110012  R0012OKI01230145  R0003OK or R0007ERnnnn

XPUT

Restore the entire switch connection state. The output from XGET is used by this command. Format: XPUTstr

 The XPUT command will turn off all outputs and then make the connections that are

listed in 'str'. 'str' is the response that was returned from a XGET command.

 XPUT without any ports is valid and is interpreted as a command to disconnect all

ports.

 Example: XPUTI00010003I00020004i0010001000110012

Example Results:

 R0003OK or R0007ERnnnn

Jun 12, 2014 Router ASCII API: V4.5-1 7/33

Macro

Sends a sequence of connect and disconnect commands as one command line. The syntax of this command is different from the other commands. This command combines connects and disconnects in one string and also combines upper and lower case commands. While the connect and disconnect have upper and lower case versions, there is only an upper case 'M'. The break between the two chassis is done with a semi-colon (;). All commands before the semi-colon affect the Upstream/Upper ports, and the command after the semi-colon affect the Downstream/Lower ports. If a router only has one set of ports (such as the Vx40), then the semi-colon may be omitted.

Format: MiiiiOOOOiiiiOOOO...[;iiiiOOOOiiiiOOOO...]

 iiii - input port number  oooo - output port number  an input number of 0000 (all zeros) will disconnect the listed output port (same as the

DO command)

 an output number of 0000 (all zeros) will disconnect the listed input port from all

connected outputs (same as the DI command)

 an output number of 9999 will broadcast the input port to all outputs  unlike the XPUT command, the router is not reset before the command is executed

To turn off all the ports, set the input to all zeros and the output to 9999.

 a 'M' without inputs or outputs is valid. This allows external systems to determine if the

API version supports the macro command.

 Example: M0000001101230000;00230008

• disconnect (upper) output 11

• disconnect (upper) input 123

• connect (lower) input 23 to output 8

 Example: M00009999;00009999

• disconnect all ports (the semi-colon section is not needed if

the router only has one chassis – such as the VX80 or VX320video)

Example Results:

 R0003OK or R0007ERnnnn

XSTATUSIO and XSTATUSOI

Similar to the XGET command, these commands return the current switch connection state. The switch state is returned as pairs of ports, input port and output port for the 'IO' command and output port and input port for the 'OI' command. A data pair is returned for each active connection. For bi-directional switches (example: Vx160 and Vx320), the upper chassis pairs are listed first, then a semi-colon (;), then the lower chassis pairs. The semi-colon is always present in an 'OK' response.

The XGET command encodes the port information as hexadecimal values, these commands use four digit, zero filled decimal values. For example: the value 12 is encoded as: 0012. Unlike the XGET, there is only one 'I' or 'O' in the response. It is immediately after the 'OK' and is there to identify which port (input or output) appears first in the data pair.

Format: XSTATUSIO

Format: XSTATUSOI

 This will return a (very) long string listing every connection. The connection list consists

of pairs of port numbers.

Example Results:

 XSTATUSIO: R0027OKI0010012300120015;00030005  XSTATUSOI: R0027OKO0015001201230010;00050003  XSTATUSOI: R0011OKO;00050003  XSTATUSOI: R0019OKO0015001201230010;  R0005OKI; or R0005OKO; or R0007ERnnnn

Jun 12, 2014 Router ASCII API: V4.5-1 8/33

System Information commands

XVERSION

Returns the API program version number.

Format: XVERSION

Example Results:

 R0009OKV4.0-3

XINSTALLED

Returns an inventory of installed I/O cards. A zero means the card is not installed and a one means the card is installed. The number of cards determines the number of zeros and ones returned and the number of cards varies for each VxRouter model. Some models have I/O cards designated as 'UpStream' or 'DownStream' (Vx40, Vx160) or have two independent shelves (Vx320). Other models have only one type of I/O card (Vx80, Mx48, Vx320Video). In the examples below, UpStream cards are highlighted with a green background. No background color will designate either DownStream cards or the router has only one type of card. The cards are listed from left to right, with the leftmost digit used for the card that has port 1.

Format: XINSTALLED

Example Results:

▪ (Vx40) R0019OK1111000011110000

▪ (Vx80) R0019OK1110000000000000

▪ (Vx160) R0019OK1100000011000000

 (Vx320) R0043OK0000000000000000000000000000000100000000

XDCSTYPE

Returns a string containing the VxRouter model. This command is a (DCS) legacy command and the name reflects its usage as a DCS command though it is still valid for VxRouters.

Format: XDCSTYPE

Example Results:

 (Vx40) R0013OKVx40Router

 (Vx160) R0014OKVx160Router

 (Vx320) R0014OKVx320Router

XMAXPORTS

Returns the maximum number of non-blocking ports in the switch. This may also be interpreted as the maximum port number allowed in a command.

Format: XMAXPORTS

Example Results:

 (Vx40) R0007OK0080

 (Vx160) R0007OK0160

 (Vx320) R0007OK0320

Jun 12, 2014 Router ASCII API: V4.5-1 9/33

XLASTEVENT

Returns a time-stamp string that was set the last time a connection was made or broken. This can be used to determine if the switch status has changed since the last XLASTEVENT command was issued.

Format: XLASTEVENT

Example Results:

 R0027OKThu Jul 1 11:23:52 2010

XPORTCONFIG

Returns a comma delimited list of three numbers: NU, NB, OFF.

The first number (NU) is the maximum number of uni-directional paths in the system. The second (NB) is the maximum number of bi-directional paths and the third is currently defined as zero.

Format: XPORTCONFIG

Example Results:

 R0017OK0080,0000,0000 Vx40  R0017OK0000,0160,0000 Vx160  R0017OK0000,0320,0000 Vx320  R0017OK0576,0000,0000 Hx576

XALARM

Returns the VxRouter hardware alarm status.

The return value is a decimal number that represents a bit-map of the actual alarm bits. For example, if 19 is returned, the binary format will be: 10011. This shows that 3 alarms are active (3 bits are '1'). The leftmost bit in the example is bit 4, followed by bits 3, 2, 1 and 0 (the rightmost bit). Bit 0 corresponds to alarm 1, bit 1 to alarm 2, etc.

The alarm bits are defined in the VxRouter manual and vary depending on the model. Format: XALARM

Example Results:

 (Vx320) R0007OK0522

Decimal 522 is 1000001010 in binary (bits 9, 3 and 1 are 'on')

XRESET

Resets the internal switch hardware to its power on state. Format: XRESET

Example Results:

 R0003OK or R0007ERnnnn

Jun 12, 2014 Router ASCII API: V4.5-1 10/33

XCRON and XCROFF

Enables or disables sending CR's on each line. XCRON is typically used when a (Windows) telnet client connecting to the VxRouter requires each line to end with a CR/LF pair.

Format: XCRON or XCROFF

Example Results:

 R0003OK

XMAXCARDS

Returns the maximum number of either upstream or downstream cards in the switch. The total number of cards in the system is twice the value returned. The Vx160 has 8 upstream and 8 downstream cards for a total of 16 cards. To maintain consistency, the VxRouters that are uni-directional (the Vx80 and Vx320-Video) also return half the number of cards.

• The Mx family of Routers are uni-directional. However, the Mx48 only has 3 I/O cards, so it is not possible to return ½ the number of cards. So, the Mx family will return the maximum number of cards.

Bit 3 of XOPTIONS may be used to determine if XMAXCARDS returns ½ the number of cards (default) or the actual number of cards (i.e. for the Mx family).

UpStream Cards DownStream Cards Total cards Returned value XOPTIONS bit 3

Vx40 8 8 16 8 0

Vx80 16 0 16 8 0

Vx160 8 8 16 8 0

Vx320 20 20 40 20 0

Vx320-Video 20 0 20 10 0

Hx80 16 0 16 8 0

Hx576 36 0 36 18 0

Mx48 3 0 3 3 1

Vx640 32 0 32 16 0

Table 2: XMAXCARDS return values

The Vx160 example shows the message returned when the 'verbose' API command line option is enabled. In this case, the API command is returned at the end of the response message.

Format: XMAXCARDS

Example Results:

 (Vx40) R0007OK0008

 (Vx160) R0017OK0008#XMAXCARDS

 (Vx320) R0007OK0020

XQUIT

Ends the network connection.

Jun 12, 2014 Router ASCII API: V4.5-1 11/33

XOPTIONS

This command returns a numeric response that is a bit map of options available in the version of the api. The value returned is a four digit decimal number of the binary bit map. For example if the value returned was 0015, then bits 0, 1, 2, and 3 would be on (bit 0 is the lsb).

The following bits are defined:

0 HDX Sync card may be installed. This is set for the HDXRouters.

1 XTEST2 command is allowed. This is set for the Vx320 Router.

2 only upper case commands are allowed.

3 XMAXCARDS returns the total number of cards allowed in the router, not ½ the number. This is set for the Mx family of routers.

4 Router supports point-to-point connection mode.

Format: XOPTIONS

Example Results:

 R0007OK0007

XHELP

Print a list of valid commands.

This is a multi-line response that does NOT start with OK or ER or end with a length. It is intended as a debugging aid and not for use in a production environment. It does not follow the format rules for command responses.

Sample response:

C,D,S - upstream to downstream or upper shelf path c,d,s - downstream to upstream or lower shelf path

{C|c}IxxxxOyyyyO... - Connect Input O9999 broadcasts port xxxx {D|d}Ixxxx... - Disconnect Input(s) I9999 disconnects all {D|d}Oyyyy... - Disconnect Output(s) O9999 disconnects all {S|s}Ixxxx - return list of output ports {S|s}Oyyyy - return input port XGET - return switch status of all the ports XPUT{I|i}xxxxyyyy... - restore switch status (from XGET) I - upstream to downstream or upper shelf path i - downstream to upstream or lower shelf path MiiiiOOOO...[;iiiiOOOO...] - Macro command ports after the 'M' are the upper ports, after the ';' are the lower ports iiii equal to zero means disconnect the output oooo equal to zero means disconnect the input XVERSION - return software version XINSTALLED - return list of installed cards XMAXCARDS - return max. num of cards XMAXPORTS - return max. num of ports XDCSTYPE - return Vx160Router XLASTEVENT - return timestamp of when VxRouter status last changed XPORTCONFIG - returns a string with 3 numeric values: NU,NB,OFF NU = number of uni-directional paths NB = number of bi-directional paths OFF = is not used and returns 0 A VxRouter contains 1*NU or 2*NB paths XRESET - resets the switch hardware to the initial poweron state XALARM - returns an alarm bit mask (0 means no alarms), bits are system dependant XTEST1 - diagnostic test 1 - connect 1 to 1, 2 to 2, ... n to n XCRON - turn on CR's XCROFF - turn off CR's

Jun 12, 2014 Router ASCII API: V4.5-1 12/33

XSTATUSIO - return switch status as pairs of ports, input first upper chassis ports listed first, then a ';', then lower

chassis ports Iiiiiooooiiiioooo...;iiiiooooiiiioooo... XSTATUSOI - return switch status as pairs of ports, output first upper chassis ports listed first, then a ';', then lower

chassis ports Oooooiiiiooooiiii...;ooooiiiiooooiiii... XOPTIONS - returns a bit mask of installed options bit 0 HDX Sync card compatable (lsb) bit 1 XTEST2 allowed bit 2 upper case commands only bit 3 XMAXCARDS returns the total number of cards allowed,

not one-half the number bit 4 Router supports point-to-point connection mode XQUIT - end this session XHELP - this text

XSYNCSTATUS

Valid in the HDX family of routers, it returns the status of the sync card. This command is not allowed in the Vx family of routers and it will return an error.

Format: XSYNCSTATUS

Example Results:

 R0007ERnnnn

 R0032OKi,r,l,a,format,reference (Ex: R0020OK1,0,0,0,0063,0003)

i = 1: sync card is installed r = 1: reference detected l = 1: locked a = 1: auto, = 0: manual format = output sync format index reference = input reference format index

Jun 12, 2014 Router ASCII API: V4.5-1 13/33

VxRouter Port Numbering

When making or breaking connections, it is important to identify the 'direction' of the connection. In this context, connection direction refers to data flow from the extender transmitter to the extender receiver, or receiver to transmitter. Transmitter to receiver data flow is called an 'upstream to downstream' connection and a receiver to transmitter data flow is a 'downstream to upstream' connection.

The Vx40 is actually an 80 port switch. It can be thought of as having 80 upstream ports (similar in design to the upper half of the Vx320).

The Vx160 has I/O cards labeled Upstream and Downstream. The Vx320 has two cards shelves. The upper shelf holds the upstream ports and the lower holds the downstream ports.

The Vx160 only allows connections between upstream and downstream ports. You may not connect an upstream port to an upstream port or a downstream port to a downstream port.

The Vx320 only allows connections within a card shelf. You may not connect an upper shelf port to a lower shelf port.

The illustrations below show the port number assignments.

Vx40 / Vx80

Connections may be made between any port on any card. The labels of 'upstream' or 'downstream' are not relevant. Vx40 ports are numbered from 1 to 80, the same as the .

Vx160

Connections may only be made between upstream input ports and downstream output ports, or downstream input ports and upstream output ports.

Vx320

Connections may only be made between input ports and output ports on either shelf. You may not make connections between shelves.

Vx320 Video / Hx80 / MX48 / Vx640

Connections may be made between any port on any card.

Hx576

• With one Switch card installed: connections may be made between port 1 and 288.

• With two Switch cards installed: connections may be made between ports 1 and 288 (the left side of the

switch) or ports 289 and 576 (the right side of the switch). It is not possible to connect between ports <= 288 and ports >288.

• With four Switch cards installed: connections may be made any port on any card.

Jun 12, 2014 Router ASCII API: V4.5-1 14/33

Port 1

Port 80

Uppercase Connect, Disconnect, Status are valid (C,D,S)

1 to 80

Illustration 1: Vx40 Port Numbering

Early models of the Vx40 have 1 - 40 silk screened in blue and green on the back of the unit (see illustration above). Later models have 1 - 80 silk screened in black. The black 1 – 80 is the accurate port numbering. Refer to Illustration 8: Hx80 / Vx80 Port Numbering to see a picture of the back of the unit.

Jun 12, 2014 Router ASCII API: V4.5-1 15/33

Path 1

1. Ci0003o0004o0005 (Red) Connect input 3 to output 4 and 5

2. Ci0080o0075 (Orange) Connect input 80 to output 75

Illustration 2: Vx40 / Vx80 Connections

Path 2

Jun 12, 2014 Router ASCII API: V4.5-1 16/33

You may connect

green (upstream)

ports to blue (downstream) ports or blue to green. You may NOT connect blue to blue or green to green.

Upstream Port 1

Upstream Port 160

Downstream Port 160

Downstream Port 1

1 to 80

1 to 160 1 to 160

Upstream input to Downstream output use UPPER CASE commands

Downstream input to Upstream output use lower case commands

Illustration 3: Vx160 Port Numbering

Jun 12, 2014 Router ASCII API: V4.5-1 17/33

▼ Path 2

Path 1 ▲

1. Ci0003o0141o0145 (Red) Connect input 3 to outputs 141 and 145

2. ci0145o0003 (Orange)Connect input 145 to output 3

Illustration 4: Vx160 Connections

Path 1 ▼

Path 2 ▲

Path 1 ▲

Jun 12, 2014 Router ASCII API: V4.5-1 18/33

Uppercase

Connect,

Disconnect,

Status are

valid

(C,D,S)

Upper Port 1

lowercase

connect,

disconnect,

status are

valid

(c,d,s)

1 to 320

Upper Port 320

Lower Port 320

Lower Port 1

1 to 320

Illustration 5: Vx320 Port Numbering

Jun 12, 2014 Router ASCII API: V4.5-1 19/33

Path 1

Path 2

1. Ci0003o0320o0319 (Red) Connect input 3 to outputs 320 and 319

2. ci0319o0003 (Orange) Connect input 319 to output 3

Illustration 6: Vx320 Port Connections

Jun 12, 2014 Router ASCII API: V4.5-1 20/33

Port 16

Port 1

Port 320

Illustration 7: Vx320-Video Port Numbering

Jun 12, 2014 Router ASCII API: V4.5-1 21/33

Port 1

Illustration 8: Hx80 / Vx80 Port Numbering

Port 80

Jun 12, 2014 Router ASCII API: V4.5-1 22/33

Port 288

Port 32

Port 576

Port 1

Port 289

1 to 288

289 to 576

Illustration 9: Hx576 Port Numbering

Jun 12, 2014 Router ASCII API: V4.5-1 23/33

Port 48

Port 16

Port 1

Illustration 10: Mx48 Port Numbering

Jun 12, 2014 Router ASCII API: V4.5-1 24/33

Port 40 Port 640

Port 21

Port 20

Port 1

Card 2

Card 1

Card 32

Card 31

Illustration 11: VX640 Port Numbering

Jun 12, 2014 Router ASCII API: V4.5-1 25/33

Error and Status Codes

1.1 0001 – Syntax error.

1.2 0002 – The command is missing an input port field.

1.3 0003 – The command is missing an output port field.

1.4 0004 – The command has multiple input fields, but only 1 is allowed.

1.5 0005 – The command has multiple output fields, but only 1 is allowed.

1.6 0006 – The input port value is out of range.

1.7 0007 – The output port value is out of range.

1.8 0008 – The command contains an invalid character.

1.9 0009 – A port value of 9999 is not allowed in this command.

1.10 0010 – A SNMP error occurred (only a DCS switch will generate this error).

1.11 0011 – An error occurred while attempting an internal fork command.

1.12 0012 – API received a command that is not allowed.

1.13 0013 – Not enough memory to process the command

1.14 0014 – File I/O error; an error occurred while reading or writing a file.

1.15 0015 – The VxRouter control process is not responding.

1.16 0016 – The command references multiple chassis, but the router only has one.

1.17 0017 – A macro was sent with a semi-colon ';', but the router is uni-directional. Uni-directional routers

do not allow port numbers after a semi-colon.

1.18 0018 – Partition or Restrictive port failure.

1.19 0019 – The connection can not be made because of a blocking condition in the internal switch matrix.

Error 10: This is only generated by a DCS switch.

Error 11, 13, 14, 15: An internal program error: Contact Thinklogical if you get this message.

Error 12: API V4 does not use this error code.

Jun 12, 2014 Router ASCII API: V4.5-1 26/33

API V3 Commands Removed from Version 4

The following commands were useful in the DCS switch, but are not appropriate for the VxRouter switches and have been eliminated in Version 4.

• XGOTOBLACK

• XFROMBLACK

• XFILESAVE

• XFILELOAD

• XFILEDIR

• XFILEDEL

• XPOWEROFF

• XSAVE (replaced with XGET)

• XLOAD (replaced with XPUT)

• XMVKYBD

Jun 12, 2014 Router ASCII API: V4.5-1 27/33

Changing from V3 to V4 API commands

The basic V3 commands (connect, disconnect, status) still exist in V4 of the API. The V3 connect command automatically creates an active keyboard (backchannel) connection. This no longer happens in V4. The user must send the second connect command to create this connection. Because the user must explicitly create the active keyboard connection, the XMVKYBD command is no longer necessary. In its place, use the 'c' connect command.

The port numbers used below are for these examples only and they may not be valid for all VxRouter models. In the V4 API, the 'I' and 'O' in the commands may be either upper or lower case, except in the XPUT command. In XPUT, the case of the letter 'I' determines the direction of the connection. A lower case 'i' would correspond to a lower case 'c', and an upper case 'I' to an upper case 'C'.

Command(s) V3 V4

connect video input 7 to output 12

connect data input 9 to output 15 and the active keyboard is on port 15

broadcast video input 66

broadcast data input 66 and have the active keyboard on port 13

disconnect output 54

disconnect input 18

save switch settings

load switch settings

connect data input 3 to data outputs 4 & 5 (active keyboard is at output 4)

then move the keyboard to output 5 (from the example on page 6) *

connect input 54 to outputs 1,2,3,4

disconnect all outputs

Ci0007o0012 Ci0007o0012

Ci0009o0015

Bi0066 Ci0066o9999

Bi0066o0013

Do0054 Do0054

Di0018 Di0018

XSAVE xget

XLOAD....... xput.......

Ci0003o0004o0005

XMVKYBDI0005O0003

Ci0054o0001o0002o0003o0 004

Do9999

Ci0009o0015 ci0015o0009

Ci0066o9999 ci0013o0066

CI0003o0004o0005 ci0004o0003

di0004 di0005 ci0005o0003

Ci0054o0001o0002o0003o0004

do9999 (breaks lower paths) Do9999 (breaks upper paths)

or you may use

xput

Table 3: V3 vs. V4 commands

* the 'di' commands will break any back-channel connections that might be in place from the keyboards at 0004 and 0005. This is done to prevent the accidental connection of a keyboard to more than one CPU.

Jun 12, 2014 Router ASCII API: V4.5-1 28/33

Appendix A: Switch Status Broadcast

The API program will periodically broadcast over the network the current switch connection map. This data may be used to keep external systems in sync with the switch. Previously, either the XGET or XSAVE command was needed to obtain the connection map. In systems with many external controls trying to stay synchronized to the router, the router would spend a lot of it resources trying to answer these status requests.

It is now possible to replace the use of broadcast with the use of multicast. The advantage of using multicast over broadcast is that multicast packets will be routed past the local subnet, whereas broadcast packets are not routed.

You may configure the frequency of these messages or disable them altogether.

More information about this feature can be found in the manuals Router_Interfaces.pdf and

Conguring-the-ASCII-Interface.pdf .

Appendix B: Sample Commands

Ci0005o0010 Connect Input 5 to Output 10

ci0005o0010 Connect Input 5 to Output 10

Si0004 Get the connection status of Input 4

xputi00010003i00020004 Turn off all outputs, connect Input 1 to Output 3, Input 2 to Output 4

Jun 12, 2014 Router ASCII API: V4.5-1 29/33

Appendix C: Connecting Extenders

The following are sample commands needed to connect selected transmitters and receivers through a VxRouter. These examples will reference the appropriate Quick Start Guide.

A) VEL-24DH through a VX80

Quick Start Guide: VX80_VEL-24DH_Quick_Start_Rev_B.pdf

Number of fibers: 4, L1, L3, K1, K2

Backchannel fiber: K2 (data flows from receiver to transmitter)

Tx fiber connections Rx fiber connections

• L1 -> 5R L1 -> 70T

• L3 -> 4R L3 -> 69T

• K1 -> 3R K1 -> 68T

• K2 -> 3T K2 -> 68R

Commands: (all upper case)

CI0005O0070 connects L1 video to RX CI0004O0069 connects L3 video to RX CI0003O0068 connects K1 TX data to RX CI0068O0003 connects K2 RX data to TX (backchannel)

Now, let's assume a second receiver connected as follows:

• L1 -> 40T

• L3 -> 39T

• K1 -> 38T

• K2 -> 38R

The commands to connect this receiver to the transmitter are:

CI0005O0070 connects L1 video to RX CI0004O0039 connects L3 video tx RX CI0003O0038 connects K1 TX data to RX

Note: receiver 2 K2 data is NOT connected (backchannel).

Receiver 1 has full keyboard/mouse/USB/speaker access. Receiver 2 has sound (speakers) but no keyboard/mouse/USB.

To move the keyboard/mouse/USB from receiver 1 to receiver 2, issue the following commands:

DI0068 disconnects RX 1 K2 (backchannel) DI0038 disconnects RX 2 K2 (backchannel) CI0038O0003 connects RX 2 K2 data to TX 1 (backchannel)

M006800000038000000380003 Macro command that combines all three commands

The two 'DI' commands are sent to insure that the keyboard/mouse data only goes to a single transmitter. If you are certain that there are no other K2 connections in place, you may eliminate them. Eliminating them will open the possibility of sending keystrokes and/or mouse commands to multiple servers at the same time – a situation that will lead to disaster.

Jun 12, 2014 Router ASCII API: V4.5-1 30/33

B) VEL-4 and VEL-24 through a VX160

Quick Start Guide: VX160_VEL-4_VEL-24_Quick_Start_Rev_D.pdf

Number of fibers: TX24 - 3, L1, L2, L3 RX24 – 3, L1, L2, L3

TX4 - 2, L1, L2 RX4 – 2, L1, L2

Backchannel fiber: L2 (data flows from receiver to transmitter)

Tx24 fiber connections (green) Rx24 fiber connections (blue)

• L1 -> 20R L1 -> 20T

• L2 -> 20T L2 -> 20R

• L3 -> 19R L3 -> 19T

Tx4 fiber connections (green) Rx4 fiber connections (blue)

• L1 -> 4R L1 -> 1T

• L2 -> 4T L2 -> 1R

Commands (24 to 24, 4 to 4): (upper and lower case)

CI0020O0020 connects L1 video & data to RX24 (green to blue) CI0019O0019 connects L3 video to RX24 (green to blue) cI0020O0020 connects L2 data to TX24 (blue to green -

backchannel)

CI0004O0001 connects L1 video & data to RX4 (green to blue) cI0001O0004 connects L2 RX4 data to TX4 (blue to green)

Now, let's connect the TX24 to the RX4:

dI0001 disconnects RX4 L2 (blue - backchannel) CI0020O0001 connects TX24 L1 video & data to RX4 (green to

blue)

Note: RX4 L2 video is NOT connected. (blue - backchannel)

RX24 has full keyboard/mouse/USB/speaker access. RX4 has sound (speakers) but no keyboard/mouse/USB.

To move the keyboard/mouse/USB from receiver 24 to receiver 4, issue the following commands:

dI0020 disconnects RX24 L2 data to TX (blue - backchannel) dI0001 disconnects RX4 L2 data to TX (blue - backchannel) cI0001O0020 connects RX4 L2 data to TX24 (blue to green -

backchannel) or

M;00200000000100000010020 Macro command that combines all three commands

The two 'dI' commands are sent to insure that the keyboard/mouse data only goes to a single transmitter. If you are certain that there are no other K2 connections in place, you may eliminate them. Eliminating them will open the possibility of sending keystrokes and/or mouse commands to multiple servers at the same time – a situation that will lead to disaster.

Jun 12, 2014 Router ASCII API: V4.5-1 31/33

Appendix D: Point-to-Point Connection mode

Version 4.4 of the API will allow input ports to be restricted to just one output port at a time. If input X is routed to output A and then connected to output B, X will be disconnected from A and then moved to B. This mode is referred to as Point-to-Point mode, or P2P for short.

The P2P definition files are stored on the Controller Card in the following files:

• /var/local/router/restrict/upstream.csv

• /var/local/router/restrict/downstream.csv

P2P mode is disabled when the definition files do not exist. By default, when there are no files, input ports may connect simultaneously to any number of output ports. All VX Routers are shipped without any P2P files stored on the Controller card.

These files are in the form of a comma separated value (csv) file. Each entry in the file is the input port that you want to restrict to P2P mode. You may have one or more entries per line in the file. The only characters allowed in the file are the digits 0 thru 9, commas, and spaces. Blank lines are allowed.

An example that set ports 1,2,3,4,9,11,15 to P2P mode is:

1,2,3,4 9 11, 15

As a shortcut, you may use the value 9999 to indicate ALL input ports.

The upstream.csv file is read by all router models. The downstream.csv file is only read by the VX160 and VX320 models. Downstream on the VX160 controls connections between the Blue card inputs and Green card outputs; on the VX320 it controls the cards on the lower shelf.

If you make changes to either of these files, you may force the API to reread them by issuing the command:

killall -HUP vxrapi

If P2P files are found at startup, the API will log this to the file: /var/log/api. An example is shown below.

Mar 11 17:51:59 vxrouter vxrapi[508]: starting Vx80Router ASCII API Version: V4.4-0 (build: 20) Mar 11 17:51:59 vxrouter vxrapi[508]: parsing P2P csv file /var/local/router/p2p/upstream.csv Mar 11 17:51:59 vxrouter vxrapi[508]: parse_api_csv_file.c@133: line 1 of csv file

Mar 11 17:51:59 vxrouter vxrapi[508]: point-to-point mode enabled

/var/local/router/p2p/upstream.csv '1,2,3,4 '

Jun 12, 2014 Router ASCII API: V4.5-1 32/33

API Manual Revision History

• 4.0-0 Initial release

• 4.0-1 added the XCRON and XCROFF commands

• 4.0-2 added examples of verbose responses to commands

• 4.0-3 modified the disconnect all description

• 4.1-0 added the macro command 'M'

added the XSTATUSIO and XSTATUSOI commands

added Hx80 and Hx576 routers

added Appendix A – Switch Status Broadcast

• 4.1-2 added the 'F' and 'XSYNCSTATUS' commands for the Hx routers

• 4.1-3 added the Mx family of routers (Mx48)

changed the picture of the VX80, the port numbers are on the bottom added the XOPTIONS command added Appendix C

• 4.1-4 The XQUIT description had text from another section of the manual. This text has been removed.

• 4.1-5 (Rev C3) added Vx640 support

error codes 17, 18 and 19 were added to page 26

• 4.4-0 (Rev D) added port point-to-point mode section: Appendix D

• 4.5-1 (Rev E) updated Appendix A to include multicast as an option to replace broadcast.

Jun 12, 2014 Router ASCII API: V4.5-1 33/33

Thinklogical ASCII-API User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Overview

HDX switch support.

MX switch support.

XOPTIONS command.

Conventions

Port numbers

Results

Upper vs. Lower case

Commands

Connection commands

Connect

Disconnect

Frame Synchronize

Status

XGET

XPUT

Macro

XSTATUSIO and XSTATUSOI

System Information commands

XVERSION

XINSTALLED

XDCSTYPE

XMAXPORTS

XLASTEVENT

XPORTCONFIG

XALARM

XRESET

XCRON and XCROFF

XMAXCARDS

XQUIT

XOPTIONS

XHELP

XSYNCSTATUS

VxRouter Port Numbering

Error and Status Codes

API V3 Commands Removed from Version 4

Changing from V3 to V4 API commands

Appendix A: Switch Status Broadcast

Appendix B: Sample Commands

Appendix C: Connecting Extenders

A) VEL-24DH through a VX80

B) VEL-4 and VEL-24 through a VX160

Appendix D: Point-to-Point Connection mode

API Manual Revision History