Configuring the TLX ASCII Interface iiiRev. A - July, 2015
®
PREFACE
Thinklogical, LLC®
100 Washington St.
Milford, CT 06460
2014
2013
We, the Thinklogical team, are committed to understanding and
exceeding our customers’ requirements, the first time and every time.
About Thinklogical
Thinklogical is the leading manufacturer and provider of fiber optic KVM, video, audio, and
peripheral extension and switching solutions used in video-rich, big-data computing
environments.
Thinklogical offers the only fiber-optic KVM matrix switches in the world that are accredited
to the Common Criteria EAL4, TEMPEST Level B, and NATO NIAPC Evaluation Scheme: GREEN
information assurance standards. And Thinklogical Velocity products are the first system with
both KVM and video matrix switching capabilities to be placed on the Unified Capabilities
Approved Product List (UC APL) under the Video Distribution System (VDS) category.
Governments, entertainment, scientific and industrial customers worldwide rely on
Thinklogical’s products and solutions for security, high performance, continuous operation
and ease of integration. Thinklogical products are designed and manufactured in the USA
and are certified to the ISO 9001-2008 standard.
Thinklogical is headquartered in Milford, Connecticut and is privately held by Riverside
Partners, LLC, Boston, MA (http://www.riversidepartners.com). For more information about
Thinklogical products and services, please visit www.thinklogical.com.
Follow Thinklogical on LinkedIn at http://www.linkedin.com/company/thinklogical and on
Facebook at http://www.facebook.com/ThinklogicalUSA
Configuring the TLX ASCII Interface 1Rev. A - July, 2015
®
About this Manual
BEFORE STARTING ANY PROCEDURE, IT IS RECOMMENDED
THAT YOU READ THE INSTRUCTIONS THOROUGHLY!
This manual lists the step-by-step instructions for configuring the ACII Interface on a
Thinklogical® TLX Series KVM Matrix Switch. The TLX KVM Matrix Switch is controlled via
an ASCII interface.
Note and Warning Symbols
Throughout this manual you will notice certain symbols that bring your attention to important
information. These are Notes and Warnings. Examples are shown below.
Note: Important Notes appear in blue text preceded by a yellow exclamation point
symbol, as shown here.
A note is meant to call the reader’s attention to helpful or important information at a point in
the text that is relevant to the subject being discussed.
Warning! All Warnings appear in red text, followed by blue text, and preceded by a
red stop sign, as shown here.
A warning is meant to call the reader’s attention to critical information at a point in the text that
is relevant to the subject being discussed.
Font Conventions Used in this Document
The following fonts and colors are used throughout this document to help differentiate between
file names, commands, outputs and document names (lower & upper case letter o and zero,
shown right):
Filenames Font: Courier New - 35-35-22 oO0
Linux Command Entered by the User Font: Consolas - 196-89-17 oO0
Output from a Command Font: Consolas – 0-128-128 oO0
Document_Name* Font: Georgia – 83-129-53 oO0
* These and other documents may be found on our ftp site:
Configuring the TLX ASCII Interface 2Rev. A - July, 2015
®
Configuring the TLX ASCII Interface
Accessing the ASCII Interface
The ASCII Interface is accessible via the serial RS-232 port located on the TLX Matrix
Switch’s Controller Card or over the network via a TCP connection. Both connections use
the same syntax. The command syntax is defined in the document: Switch_ASCII_API.
The serial port is configured for 9600 baud, 1 stop bit, no parity, and software flow
control. Each line contains only one command and must end with a carriage return (CR) and
line feed (LF), or just a line feed (LF). The characters are not echoed.
The network interface listens on TCP port 17567. It accepts the same commands as the serial
interface. You may use telnet to manually open a connection to control the Matrix Switch.
Configuring the TLX ASCII Interface 3Rev. A - July, 2015
®
API Command Line Options
Each Matrix Switch model has its own API program. Examples are: tlx48api, tlx320api
and tlx640api. The generic name that is used in place of the actual name is: tlxapi.
The interface program has several options to control its operation. These options can be listed
by running the API program with the option '--help'. See the example below:
-L|--listen[=]port listen on this port, all addresses (default: 17567)
-N|--connections[=]n set the maximum number of open connections allowed (default: 12)
--mcast[=IP address] replace broadcasts with multicast to this IP address (default: 239.255.13.9)
---- serial options ----
-S|--serial[=device] use this serial device (default: /dev/ttymxc1)
--serial=none disables the API serial port /dev/ttymxc1
-B|--baud[=]speed sets serial baud rate (default: 9600)
---- generic options ----
--CR output CRLF instead of just LF
--facility[=]name syslog facility reporting level (default is local4)
valid names: auth, daemon, user, local0 through local7see the man page for rsyslog.conf for more information
-D|--debug write debug messages to the log file (multiple options increase the debug
level)
--api write API messages received to the log file (level: NOTICE)
--avr write control commands to the log file (level: NOTICE)
--clog write connection status changes to the log file (level: NOTICE)
--delay[=]delay in ms, how long an output must remain off, default is 300 ms.
minimum is 50ms, maximum is 1000ms, 0 will disable the delay
-b|--bcast[=]period in ms, how long between port status broadcasts, default is 4000 ms.
minimum is 500, maximum is 15000, 0 will disable the broadcast
if multicast is enabled, it will use this time setting
--bcast=0 will disable BOTH broadcasts and multicasts
-V|--verbose enable error text in responses
-h|--help display this help and exit
-v|--version output version information and exit
Default (no options) is to listen on socket 17567 at all IP addressessend to socket 27567 at 127.0.0.1accept commands from the RS232 portbroadcast switch status every 4000 milliseconds
signal SIGUSR1 will toggle api debug logging (--api)
signal SIGUSR2 will toggle control debug logging (--avr)
signal SIGHUP will force the API to reread the P2P csv files located in /var/local/router/p2p/
Configuring the TLX ASCII Interface 4Rev. A - July, 2015
®
Changing the Command Line Options
The command line options are stored in the file: /etc/default/tlxapi.
The default file contents are:
# Defaults for tlxrapi initscript
# sourced by /etc/init.d/tlxrapi
# installed at /etc/default/tlxrapi by the maintainer scripts
#
# This is a POSIX shell fragment
#
## set this to no and the daemon will not run
APIRUN=yes
# Command line options that are passed to tlxrapi.
TLXAPI_ARGS="--verbose –api"
Command line options are added to the TLXAPI_ARGS line.
For example, to change the serial port baud rate to 115200 and send a CRLF at the end of each
line, the TLXAPI_ARGS line will be:
TLXAPI_ARGS="--verbose --api --baud=115200 --CR"
After the file is modified and saved, the following command will restart the API with the new
settings:
service tlxapi restart
Note: Any changes you make to the switch firmware will be lost if you install a new
SD card from Thinklogical.
Configuring the TLX ASCII Interface 5Rev. A - July, 2015
®
Debugging Aids
The API program has several options to aid in setup and debugging. These include logging the
incoming ASCII commands, logging the communications to the internal control process (aka
AVR or Control) and appending a comment to the response message that is returned after each
command. This comment will contain details about any errors.
These messages are written to the system log file: /var/log/api located on the Switch's
internal SD card.
Command line options to enable the API debug aids:
--debug log extensive detailed data
--api log the API commands received
--avr log the commands to the internal control process
--clog log connection make/break status
--verbose append a comment to each command response
The '--api' and '--avr' settings may be toggled by sending a system signal to the running API
program. As shown in the help text on page 1, SIGUSR1 will toggle the 'api' setting and
SIGUSR2 will toggle the 'avr' setting. (See the example below for the syntax of the 'killall'
command.)
You may use the 'killall'command to send a signal to a running program. The syntax is:
killall -USR1 tlxapi
or
killall -USR2 tlxapi
Configuring the TLX ASCII Interface 6Rev. A - July, 2015
®
Using ‘PuTTY’ to Communicate to the API
1
2 3 4
5
6
Upon opening PuTTY (a Windows communication program) to communicate to a switch, you
must first set the following:
1. Under ‘Category,’ click on Session
2. Under ‘Connection type,’ select 'Raw' mode
3. Change the port to 17567
4. Under ‘Category,’ click on Terminal
5. Under ‘Set various terminal options,’ check the 'Implicit CR in every LF' box.
6. Click Open.
You may also use telnet to access the ASCII control port. The command syntax is:
telnet IPaddress 17567
Replace IPaddress with the actual IP address of the switch.
Configuring the TLX ASCII Interface 7Rev. A - July, 2015
®
Log File Debugging Entries
When debugging is turned on, several types of messages are written to the system log file:
/var/log/api.
For example, below are listed five commands that were sent to a TLX320 Matrix Switch. Below
those commands is a snippet of the log file showing the corresponding log entries. The first line
in the log file records the event that enabled logging.
These log entries list the command that was received and the response that was sent back to
the sender.
The log files contain other system related messages and are a valuable aid in troubleshooting.
Linux offers the means to send these log file entries over the network to another system. Further
information may be found in the document: Switch_Interfaces.
A Note to Telnet Users
By default, tlxapi does not send a CR on each line. This is inherent in the Windows telnet client
software. The API, however, has a command to enable the sending of CR's. This command is
XCRON. If your telnet output from tlxapi is displayed incorrectly on the screen, Thinklogical
recommends using the XCRON command.
Configuring the TLX ASCII Interface 8Rev. A - July, 2015
®
Disabling ‘Broadcast’ on Switch Input Ports
The API may be configured so that input ports are restricted to one output port at a time.
If input X is first connected to output A, then connected to output B, X will be disconnected from
A and moved to B. This mode is referred to as Point-to-Point mode, or P2P for short.
The P2P definitions are stored on the Controller SD card in the following file:
/var/local/router/p2p/upstream.csv
P2P mode is disabled when the definition file does not exist. By default, when there is no
file, input ports may connect simultaneously to any number of output ports. All Matrix Switches
are shipped without a P2P file.
These files are in the form of a comma separated value (csv) file. Each entry in the file is the
input port to be restricted to P2P mode. There may be 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 and 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.
If you make changes to either of these files, you can 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.
imxs tlxapi[9389]: parsing P2P csv file /var/local/router/p2p/upstream.csv
imxs tlxapi[9389]: parse_api_csv_file.c@133: line 1 of csv file /var/local/router/p2p/upstream.csv '1,2,3,4#012'
imxs tlxapi[9389]: parse_api_csv_file.c@133: line 2 of csv file /var/local/router/p2p/upstream.csv '9#012'
imxs tlxapi[9389]: parse_api_csv_file.c@133: line 3 of csv file /var/local/router/p2p/upstream.csv '11, 15#012'
imxs tlxapi[9389]: point-to-point mode enabled
Configuring the TLX ASCII Interface 9Rev. A - July, 2015
®
Using ‘Multicast’ to Send Switch Status Instead of ‘Broadcast’
The API has a command line option for using a network multicast address instead of a
broadcast address to deliver switch status messages. The default mode of the API will
broadcast its status over the network. The use of a multicast address allows these
messages to be routed to other network segments.
The command line option to enable multicast is '--mcast'. Without additional options, it will
enable multicast using the default IP address of 239.255.13.9. When multicasting is enabled,
the API will create a log entry showing the IP address it is using.
imxs tlxapi[9389]: Using multicast IP address 239.255.13.9
imxs tlxapi[9389]: multicast mode enabled
If broadcast is in effect, the log file will record that information.
imxs tlxapi[9389]: Using broadcast IP address 192.168.13.255
If you prefer to not use the default multicast address, you can specify the preferred address on
the command line by adding an equal sign '=' and the IP address to the '--mcast' option. For
example: '--mcast=239.255.13.105'.
Warning! The selection of a multicast address is beyond the scope of this
document, in which case, you may need to contact your IT / Networking department.
The address you use may have some effect on your network infrastructure, so be
sure to contact the appropriate, qualified personnel.
The API will attempt to use the specified multicast IP address. If it cannot connect to that
address, the API will fall back to using broadcast. This is also logged.
The example below shows an attempt to use the IP address of 1.2.3.4. The API was not able to
connect to that address, so it went back to using broadcast.
imxs tlxapi[9389]: broadcast_setup() vxASCIIapi.c@5193: Error: (Cannot assign requested address)
in bind [IP address = 1.2.3.4], switching to broadcast
imxs tlxapi[9389]: Using broadcast IP address 192.168.13.255
Both broadcast and multicast will use UDP port 17564 to transmit the status.
Configuring the TLX ASCII Interface 10Rev. A - July, 2015
®
Regulatory & Safety Compliance
Symbols found on the product
Markings and labels on Thinklogical products follow industry-standard conventions. Regulatory
markings found on the products comply with domestic and many international requirements.
Regulatory Compliance
Thinklogical’s products are designed and made in the U.S.A. These products have been tested
by a certified testing laboratory and found to be compliant with the following standards (both
domestic USA and many international locations):
This is a Class A product. In a domestic environment this product may cause radio interference,
in which case the user may be required to take adequate measures.
European Union
Declaration of Conformity
Manufacturer’s Name & Address: Thinklogical, LLC®
100 Washington Street
Milford, Connecticut 06460 USA
These products comply with the requirements of the Low Voltage Directive 72/23/EEC and the
EMC Directive 89/336/EEC.
Standards with Which Our Products Comply
Safety
CENELEC
Electromagnetic Emissions
EN55022: 1994 (IEC/CSPIR22: 1993)
EN61000-3-2/A14: 2000
EN61000-3-3: 1994
Electromagnetic Immunity
EN55024: 1998 Information Technology Equipment-Immunity Characteristics
IEC 60950-1 2nd Ed. 2005
Configuring the TLX ASCII Interface 11Rev. A - July, 2015
®
EN61000-4-2: 1995 Electro-Static Discharge Test
EN61000-4-3: 1996 Radiated Immunity Field Test
EN61000-4-4: 1995 Electrical Fast Transient Test
EN61000-4-5: 1995 Power Supply Surge Test
EN61000-4-6: 1996 Conducted Immunity Test
EN61000-4-8: 1993 Magnetic Field Test
EN61000-4-11: 1994 Voltage Dips & Interrupts Test
Supplementary Information
The following statements may be appropriate for certain geographical regions and might not
apply to your location.
This Class A digital apparatus meets all requirements of the Canadian Interference-Causing
Equipment Regulations.
Cet appareil numérique de la classe A respecte toutes les exigencies du Règlement sur le
matérial brouilleur du Canada.
Warning!This is a Class A product. In a domestic environment, this product
may cause radio interference, in which case the user may be required to take
corrective measures.
Note: This equipment has been tested and found to comply with the limits for a
Class A digital device, pursuant to part 15 of the FCC Rules. These limits are
designed to provide reasonable protection against harmful interference when the
equipment is operated in a commercial environment. This equipment generates,
uses and can radiate radio frequency energy and, if not installed and used in
accordance with the instruction manual, may cause harmful interference to radio
communications in which case the user may be required to take adequate
corrective measures at their own expense.
Note: This Class A digital apparatus complies with Canadian ICES-003 and has
been verified as being compliant within the Class A limits of the FCC Radio
Frequency Device Rules (FCC Title 47, Part 15, Subpart B CLASS A), measured to
CISPR 22: 1993 limits and methods of measurement of Radio Disturbance
Characteristics of Information Technology Equipment.
Note:
electro-magnetic fields
The user may notice degraded audio performance in the presence of
.
Product Serial Number
Thinklogical products have a unique serial number, which includes a date-code, printed on an
adhesive label that is affixed to the unit. The format for the date-code is 2 digits for the month,
dash, 2 digits for the year, plus at least four digits for a unique unit number. For example:
05-150127 indicates the unit was built in the 5th month of 2015, and is unit number 127.
Connection to the Product
Connections and installation hardware for our products use industry-standard devices
and methods. All wiring connections to the customer equipment are designed to minimize
proprietary or customized connectors and cabling. Power connections are made with regionally
appropriate power cords and approved methods.
Configuring the TLX ASCII Interface 12Rev. A - July, 2015
®
Thinklogical Support
How to Contact Us
Thank you for choosing Thinklogical® products for your application.
We appreciate your business and are dedicated to helping you successfully use our products.
is always here to help you.
To contact us, please use the following telephone numbers and internet-based methods:
®
Customer Support
Thinklogical® is an engineering company and you will receive the information you require
directly from our most knowledgeable engineers.
We believe that the first line of support comes from the design
engineers that developed each particular product.
Therefore, your questions or issues will be handled promptly by our in-house engineers who are
most familiar with your products.
Website
Check out our website for current product offerings, support information and general information
about all of the products we offer.
Our internet website offers product information on all current systems, including technical
specification sheets and installation guides (for viewing online or for download), product
diagrams showing physical connections and other information you might need.
Internet: www.thinklogical.com
Note: Most online documents are stored as Adobe Acrobat “PDF” files. If you do
not have the Adobe Acrobat reader needed to view PDF files, visit www.adobe.com
for a download.
Email
Thinklogical® is staffed Monday through Friday from 8:30am to 5:00pm, Eastern Time Zone.
We will do our best to respond to your email inquiries promptly. Please use the following email
addresses:
info@thinklogical.com – Information on Thinklogical® and our products.
sales@thinklogical.com – Sales Department - orders, questions or issues.
support@thinklogical.com – Product support, technical issues or questions, product
repairs and request for Return Authorization.
Configuring the TLX ASCII Interface 13Rev. A - July, 2015
®
Telephone
Product & Customer Support: 1-203-647-8798
US Commercial & Canada Sales: 1-203-647-8715
US Federal Government Sales: 1-203-647-8716
Toll Free in the Continental US: 1-800-291-3211
International Sales (Europe, Middle East, Africa): 1-203-647-8704
International Sales (Asia Pacific, Central & Latin America): 1-203-647-8734
Please contact our expert sales staff in Milford, CT. We are here Monday through Friday from
8:30am to 5:00pm, Eastern Time Zone. We’ll provide a representative’s direct dial phone
number when you call.
If leaving a voice message, please provide a preferred time to call back so we may reach you at
your convenience.
Our switchboard attendant will direct your call during regular business hours. We have an
automated attendant answering our main telephone switchboard after regular business hours
and holidays. Please leave voice messages for individuals at any time.
Fax
Our company facsimile number is 1-203-783-9949. Please indicate the nature of the fax on your
cover sheet and provide return contact information.
Product Support
Thinklogical’s® support personnel are available Monday through Friday from 8:30am to
5:00pm, Eastern Time Zone. If your application requires assistance at some time outside of our
normal business hours, please contact us beforehand and we will do our best to make
arrangements to help you with your Thinklogical® products.
Warranty
Thinklogical, LLC® warrants this product against defects in materials and workmanship for a
period of one year from the date of delivery. Thinklogical, LLC® and its suppliers disclaim any
and all other warranties.
Note: Thinklogical, LLC® products carry a one year warranty, with longer term
available at time of purchase on most products. Please refer to your product
invoice for your products Warranty Terms & Conditions.
Defect remedy shall be the repair or replacement of the product, provided that the defective
product is returned to the authorized dealer within a year from the date of delivery.
If you wish to return your device, contact the Thinklogical, LLC® authorized dealer where you
purchased the device, or if you purchased directly, call Thinklogical, LLC® at 1-800-291-3211
(USA).
Configuring the TLX ASCII Interface 14Rev. A - July, 2015
®
Return Authorization
If you need to return your Thinklogical® product to us for any reason, please get a
Return Merchandise Authorization Number (RMA#)
from Thinklogical’s Product Support Department (1-203-647-8798) before sending the unit in.
MADE IN USA
In the event you must return a product to Thinklogical® directly, please contact Customer
Support at 1-800-291-3211 or 1-203-647-8798. Customer Support will ask you to describe the
problem and will issue you a Return Merchandise Authorization number (RMA#). Pack the
device in its original box, if possible, and return it with the RMA# printed on the outside of the
box.
Note: DO NOT return a product to Thinklogical® without a Return Material
Authorization.
Our Addresses
If you have any product issues or questions or need technical assistance with your Thinklogical®
system, please call us at 1-800-291-3211 (USA only) or 1-203-647-8798 and let us help. If you
need to write us or return a product, please use the following address: Return address for
products with Return Material Authorization:Thinklogical, LLC®