Thinklogical Configuring the TLX ASCII Interface User Manual

®
®
Copyright Notice
Copyright © 2015. All rights reserved. Printed in the U.S.A.
Thinklogical, LLC® 100 Washington Street Milford, Connecticut 06460 U.S.A. Telephone: 1-203-647-8700
All trademarks and service marks are property of their respective owners.
Subject: Configuring the TLX ASCII Interface Revision: A, July 2015
Website: www.thinklogical.com Facebook: www.facebook.com/ThinklogicalUSA LinkedIn: www.linkedin.com/company/thinklogical Google+: http://plus.google.com/u/0/109273605590791763795/about YouTube: www.youtube.com/user/thinklogicalNA Twitter: @thinklogical
Configuring the TLX ASCII Interface ii Rev. A - July, 2015
®
Table of Contents
MADE IN USA
PREFACE................................................................................................................................................ 1
About Thinklogical® ...................................................................................................................... 1
About This Manual ....................................................................................................................... 2
Note and Warning Symbols ...................................................................................................... 2
Font Conventions Used in this Manual ..................................................................................... 2
CONFIGURING THE TLX ASCII INTERFACE ........................................................................................ 3
Accessing the TLX ASCII Interface............................................................................................... 3
API Command Options ................................................................................................................. 4
Changing Command Line Options ................................................................................................ 5
DEBUGGING AIDS ................................................................................................................................. 6
USING 'PuTTY' TO COMMUNICATE TO THE API ................................................................................. 7
Log File Debugging Entries .......................................................................................................... 8
Note to Telnet Users ................................................................................................................ 8
DISABLING 'BROADCAST' ON SWITCH INPUT PORTS ...................................................................... 9
Using 'Multicast' to Send Switching Status Instead of 'Broadcast' ............................................... 10
REGULATORY & SAFETY REQUIREMENTS ...................................................................................... 11
Symbols Found on Our Products ................................................................................................ 11
Regulatory Compliance .............................................................................................................. 11
North America ........................................................................................................................ 11
Australia & New Zealand ........................................................................................................ 11
European Union ..................................................................................................................... 11
Declaration of Conformity ................................................................................................... 11
Standards with Which Our Products Comply .............................................................................. 11
Supplementary Information ........................................................................................................ 12
Product Serial Number ........................................................................................................... 12
Connection to the Product ...................................................................................................... 12
THINKLOGICAL® SUPPORT ................................................................................................................ 13
Customer Support ...................................................................................................................... 13
Website .................................................................................................................................. 13
Email ...................................................................................................................................... 13
Telephone .............................................................................................................................. 14
Fax ......................................................................................................................................... 14
Product Support ......................................................................................................................... 14
Warranty ................................................................................................................................. 14
Return Authorization ............................................................................................................... 15
Our Addresses ....................................................................................................................... 15
Configuring the TLX ASCII Interface iii Rev. 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 1 Rev. 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:
ftp://ftp.thinklogical.com/TLxSwitch/Documentation/
or on our web site:
http://www.thinklogical.com/user_manuals
Configuring the TLX ASCII Interface 2 Rev. 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 3 Rev. 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:
~ # tlxapi --help Version: V5.00 (build: 81) Usage: tlxapi [options]
---- network options ----
-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 local7 see 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 addresses send to socket 27567 at 127.0.0.1 accept commands from the RS232 port broadcast 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 4 Rev. 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 5 Rev. 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 6 Rev. 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 7 Rev. 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.
Ci0150o0151
Si0150
So0151
Do0151
Ci0312o0001
imxs tlxapi[1851]: caught signal SIGUSR1 (10), turn on api debugging imxs tlxapi[1851]: command: Ci0150o0151 response: R0000OK#Ci0150o0151 imxs tlxapi[1851]: command: Si0150 response: R0000OKI0150O0151#Si0150 imxs tlxapi[1851]: command: So0151 response: R0000OKI0150O0151#So0151 imxs tlxapi[1851]: command: Do0151 response: R0000OK#Do0151 imxs tlxapi[1851]: command: Ci0312o0001 response: R0000OK#Ci0312o0001
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 8 Rev. 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 9 Rev. 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 10 Rev. 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):
North America
Safety
ANSI/UL60950-1: 1st Edition (2003) CAN/CSA C22.2 No. 60950-1-03 CENELEC EN 60950-1, 1st Edition (2001)
LASER Safety
CDRH 21CFR 1040.10
Class 1 LASER Product
IEC60825:2001 Parts 1 and 2
Class 1 LASER Product
Electromagnetic Interference
FCC CFR47, Part 15, Class A
Industry Canada ICES-003 Issue 2, Revision 1
Australia & New Zealand
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 11 Rev. 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 12 Rev. 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 13 Rev. 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 14 Rev. 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®
Attn: RMA# 100 Washington Street
Milford, CT 06460 USA
Website: www.thinklogical.com Facebook: www.facebook.com/ThinklogicalUSA LinkedIn: www.linkedin.com/company/thinklogical Google+: http://plus.google.com/u/0/109273605590791763795/about YouTube: www.youtube.com/user/thinklogicalNA Twitter: @thinklogical
Configuring the TLX ASCII Interface 15 Rev. A - July, 2015
Loading...