Matrix Switch MSC-HD42L User Manual

Matrix Switch Corporation

Mascot Control Protocol

Document revision: 1.2

Protocol version: 2.1

Date: Jan 1, 2012

Legal Disclaimers

All material in this document is the legal property of Matrix Switch Corporation.

Information contained in this publication regarding device applications and the like is provided only for your convenience and may be superseded by updates. It is your responsibility to ensure that your application meets with your specifications. MATRIX SWITCH CORPORATION MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WHETHER EXPRESS OR IMPLIED, WRITTEN OR ORAL, STATUTORY OR OTHERWISE, RELATED TO THE INFORMATION, INCLUDING BUT NOT LIMITED TO ITS CONDITION, QUALITY, PERFORMANCE, MERCHANTABILITY OR FITNESS FOR PURPOSE. Matrix Switch Corporation disclaims all liability arising from this information and its use. Use of Matrix Switch Corporation devices in life support and/or safety applications is entirely at the buyer’s risk, and the buyer agrees to defend, indemnify and hold harmless Matrix Switch Corporation from any and all damages, claims, suits, or expenses resulting from such use. No licenses are conveyed, implicitly or otherwise, under any Matrix Switch Corporation intellectual property rights.

* Other names and brands may be claimed as the property of others.

Contacting Matrix Switch Corporation

Website

Phone

http://www.matrix-switch.tv

(530) 477-9122

info@matrix-switch.tv

1 Mascot Control Protocol

The MASCOT (MAtrix Switch COrporaTion ) protocol provides an ASCII text based command interface via several different transports to control and get status from Matrix Switch Corporation devices. This command protocol can be utilized for manual control or for integration with automation control systems.

Mascot command interface options

• Web Page Command Tab – The most convenient interface, which can be accessed using a

Web Browser from a Computer system on the same network connected via the device's Ethernet port.

• TCP/IP port 40 – A telnet interface is provided on TCP/IP port 40 which uses the device's Ethernet connector as a physical transport.

• RS-232 Serial Port (Router devices and MSC-GCP2U32 LCD Control Panel) ◦ Router serial config: 9600 baud, 8 data bits, 1 stop bit, No Parity, No flow control ◦ MSC-GCP2U32 serial config: 115200, 8 data bits, 1 stop bit, No Parity, No flow control

3rd Party support

This protocol is currently supported by Crestron controllers. For information about other third party control system manufacturers who support this protocol, contact Matrix Switch Corporation.

1.1 Protocol changes

As new commands are added or other changes occur, the MASCOT protocol version is incremented. The protocol revision can be obtained using the MascotVer command.

Protocol revision history.

Mascot version 2.1 (Carina Series Firmware 5.3.0)

• New commands: PairIO – for paired I/O 3D support, PanelOfs – for defining remote panel I/O regions to control, PanelRate – to set remote panel refresh rate, ReclkDis – for disabling SDI reclockers and

RemoteSync – for synchronizing two video router systems for 3D use.

• Added E12 “Unsupported command” error which is returned when a command is not supported by the current system or settings.

• Added support for Line Feed character as a command terminator (to be compatible with older firmware). Carriage Return should normally be used.

• Added “lock” (0x02) and “reclk” (0x04) to MtxCfg Command “flags” field.

1.2 Telnet access

A telnet client can be used to access the command interface on TCP/IP port 40. Many operating systems come with a Telnet client or one can be easily obtained. To control a device using Telnet the IP address and TCP/IP port number will need to be supplied. This is typically added as arguments when executing the “telnet” command via your operating system's command prompt or run dialog. Here is an example for a device on the IP address 192.168.2.60:

telnet 192.168.2.60 40

Press the Enter key which should display the command “>” prompt character, confirming that the device is connected.

1.3 Serial access

Matrix Switch router systems come equipped with a serial port which can be used as another means

of sending Mascot commands. Connect a Computer system to the router device using a 9 pin RS232 serial cable. Using this interface requires a serial terminal program, such as HyperTerminal on Windows. Configure the terminal software for 9600 Baud, 8 Data Bits, 1 Stop Bit, No Parity and No Flow Control. In addition Local Echo should be on in order to see what is typed. Pressing the Enter key once connected should yield the “>” prompt character.

1.4 Command format

Commands consist of a command name, zero or more arguments separated by commas and a carriage return (CR, ASCII 13 - the Enter key on a keyboard). Optionally multiple commands can be combined by separating them with a '#' character and the command chain is terminated with a CR character. Spaces are not required between arguments, but can be optionally supplied for readability. A space is also not required between command names and their first argument, if the argument is numeric.

Special command characters

# Multiple command separator, for chaining commands.

<CR> Carriage Return (ASCII 13), indicates the end of a command or chain of commands, Enter key.

<BS> Backspace character (ASCII 11), can be used to backspace characters in interactive command shells.

“ Used for double quoting string arguments.

' Used for single quoting string arguments.

Command example

X1,1#X2,2#S<CR>

Connects Source 1 to Destination1 and Source 2 to Destination 2, followed by displaying the Active Routing matrix status. The <CR> is the Carriage Return character.

1.4.1 Command names

Command names consist of one or more alphabetical characters and are case insensitive. For convenience with manual command entry they can also be matched using partial names. The first matching alphabetically sorted command is used (for example: 'H', 'He', 'hEL' or 'Help' can be used to execute the Help command). This feature, however, should not be relied on with automation systems, since a given partial command may execute a different command as new ones are added to the protocol.

1.4.2 Command arguments

Command arguments are separated into two categories: numeric and string arguments. These are further explained in the table below:

Command argument types

Numeric String

Decimal (123) 1 to 3 decimal digits Unquoted Commands with string arguments

automatically interpret argument as string (spaces and commas not allowed).

Hex (0x3D) 0xNN where NN are 2 hex digits Double quoted One or more characters surrounded

by double quotes (“An Argument”).

Single quoted One or more characters surrounded

by single quotes ('An Argument').

1.5 Response format

Most command responses consist of one or more values separated by newlines and ending with the ‘>’ prompt character. Newlines follow the “DOS” Carriage Return/New Line (CR LF) pair of characters (ASCII 13 followed by ASCII 10).

The Prompt ‘>’

A prompt character ‘>’ is displayed each time a command or chain of commands is entered, to indicate readiness to receive additional commands. If an error occurs in response to a command, an error will be displayed prior to the prompt with the following format:

E00: Error message >

00 will contain a 2 digit decimal error code.

1.6 Command argument values

Command arguments are shown in the Help command output surrounded by square brackets '[ARG]' or parenthesis '(ARG)'. Square brackets indicate an optional argument and parenthesis indicate a required argument. Any optional argument specified requires that all prior optional arguments are also specified.

Argument Valid Range Meaning DEST 1-N Destination number (N = Count of destinations) SRC 1-N or 0 Source number (N = Count of sources), 0 acts as mute

(if supported). LEVEL 1-N Level number (N = Count of system levels) PRESET 0-9 Preset number (preset 0 is special Startup preset) IP D.D.D.D IP address string argument, specified as 4 decimal

digits from 0 to 255 separated by periods. NETMASK D.D.D.D Network mask string argument, specified as 4 decimal

digits from 0 to 255. Must be a valid IPv4 netmask. LABEL string A string label argument, max of 8 characters. STR string A generic string argument (max length depends on

command).

1.7 Error codes

This following table shows possible error codes which may be returned in response to commands.

Error # Message Description

E01 Token too long A command name or string argument was too long. E02 Invalid command Invalid command name. E03 Invalid argument One or more invalid argument values. E04 Invalid destination Invalid matrix destination number. E05 Invalid source Invalid matrix source number. E06 Invalid level Invalid matrix level number. E07 Invalid preset Invalid preset number. E08 Unterminated string Double or single quoted string not terminated.

E09 Backspace limit reached Devices have a limited backspace buffer size, if too many

characters are backspaced and then more characters are appended, this error will occur.

E10 HTTP buffer overflow Only applicable to the web page command interface.

Unlimited command input or output can be handled, but

not both. E11 Serial receive overrun One or more characters were lost on the serial interface. E12 Unsupported command Command is not supported by the system or current

configuration. Firmware 5.3.0 and newer.

1.8 Basic command reference

Basic commands consist of those commands which are used for modifying the state of the matrix routing and other simple commands.

Command Arguments Description

Help Display command help reference. P * [PRESET] Recall a preset. PAdd * (PRESET)(DEST)(SRC)

[LEVEL] PClr * (PRESET) Clear a preset to “No Change” values. PSub * (PRESET)(DEST)[LEVEL] Subtract a connection from a preset. PView * [PRESET] View preset contents. S * [1] Matrix routing status (supplying 1 will display

W * [PRESET] Store current matrix routing to a preset. X * [DEST][SRC][LEVEL] Perform a matrix connect operation.

* - Router systems only

Add a connection to a preset.

labels).

1.9 Advanced command reference

These additional commands consist of those which are not as commonly used as the basic commands, such as system configuration commands.

Command Arguments Description

B (0 | 1) Reboot system into Bootloader, typically used

for software update. A 0 or 1 value is required and selects the Bootloader IP address. A value of 0 uses 192.168.2.59 and 1 uses configured system IP.

C * Query system matrix info, which is displayed in

the format DESTS,SRCS,LEVELS,FLAGS1,FLAGS2. MtxCfg command supersedes this one.

DestNames * DHCP [0 | 1] Query or assign DHCP enable. E * Firmware Query system firmware version. FrameIP [IP] Remote router IP address the panel will control. Gateway [IP] Query or assign network gateway IP address.

[DEST][LEVEL][LABEL] Query or assign destination names.

[0 | 1] Query or assign matrix connection echo enable.

IP [IP] Query or assign device system IP address. LockStatus *

MAC Query system MAC address MascotVer Query Mascot protocol version. MtxCfg *+ NetMask [NETMASK] Query or assign network mask. PairIO *@

PanelOfs @

PanelRate @ PsetNames * Reboot Reboot the system. ReclkDis *@

RemoteSync *@

SrcNames * SysName [STR] Query or assign system name. WebPass (STR) Assign web password.

* Router systems only. + Added with protocol version 2.0 (Carina Series firmware version 5.2.1). @ Added with protocol version 2.1 (Carina Series firmware version 5.3.0).

[0-7] Query current matrix config.

[0 | 1] Query or assign I/O pairing enable (3D

[DEST][SRC][LVL1] [LVL2]

[RATE] Set remote panel refresh rate in seconds. [PRESET][LABEL] Query or assign preset names.

[0 | 1] Disable HD reclockers (not all HD router

[0 | 1] Query or assign remote router syncing. Useful

[SRC][LEVEL][LABEL] Query or assign source names.

Get video lock status and rate detection information (not all HD router systems are supported).

support). Query or assign button panel destination/source offsets and levels to control. Useful for configuring multiple panels to control different I/O regions of a router.

systems are supported).

for creating a 3D system out of 2 routers.

+ 15 hidden pages