Thinklogical ASCII-API User Manual

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
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
Related documents:
Conguring-the-ASCII-Interface.pdf Router_Interfaces.pdf Router_SNMP_Traps.pdf
These documents may be found on our ftp site: ftp://ftp.thinklogical.com/VxRouter/Documentation/ or on our web site:
http://www.thinklogical.com/user_manuals.
This symbol is used to mark important information that will be needed to effectively use this API with the VxRouter matrix switch.
This document (Router-ASCII-API.pdf) is valid for XVERSION V4.X. If XVERSION returns V3.0, V3.1, or V3.2, you need DCS-ASCII-API-V3.pdf. If XVERSION returns V3.5, you need Router-ASCII-API-V3.5.pdf.
Jun 12, 2014 Router ASCII API: V4.5-1 2/33

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 VX320­video)
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
Loading...
+ 23 hidden pages