Grass Valley Kaleido Remote Control Protocol Gateway User Manual

Kaleido Remote Control

Protocol (Gateway)

User’s Guide

M770-0900-114

Specications may be subject to change

Printed in Canada

May 2011

Multi-Image Display

Processor

Miranda

Technologies Inc.

3499 Douglas-B.-Floreani

St-Laurent, Québec, Canada H4S 2C6

Tel. 514-333-1772

Fax. 514-333-9828 www.miranda.com

Kaleido Remote Control

Protocol (Gateway)

USER’S GUIDE

Table of Contents

1 Introduction ......................................................................................................................................... 1

1.1 Software Versions ........................................................................................................................ 1

1.2 Remote Operation of the Kaleido-X Series or Kaleido-Alto/Quad/Quad-Dual Multi-Viewers ..... 1

1.3 Gateway Options for the Kaleido-K2 ........................................................................................... 1

1.3.1 Internal Gateway ................................................................................................................. 2

1.3.2 MT-Gateway ........................................................................................................................ 2

1.4 Remote Operation of the Kaleido-K2 via the Gateway ................................................................ 3

2 Gateway Commands .......................................................................................................................... 4

2.1 Index of Gateway Commands ..................................................................................................... 4

2.2 Document Conventions ............................................................................................................... 6

2.3 Gateway Command Descriptions ................................................................................................ 6

3 A Typical Session ............................................................................................................................. 26

4 Appendix: Kaleido-X Series Support History ................................................................................ 30

Kaleido Remote Control Protocol (Gateway)

USER’S GUIDE

Kaleido-X series:

Kaleido-X Software version 3.00 or later (see Appendix: Kaleido-X Series Support History on page 30 for a detailed breakdown by command and multi-viewer model)

Kaleido-Alto/Quad/Quad-Dual:

Kaleido-Alto/Quad/Quad-Dual Software version 3.01 or later

Kaleido-K2:

Kaleido Software version 5.30 or later

Kaleido Remote Control Protocol (Gateway) 1 Introduction

Kaleido-K2, Kaleido Alto/Quad/Quad-Dual, Kaleido-X, Kaleido-X16, and KMV-3901/3911 multi-viewers can execute commands received via a gateway, allowing third-party developers and individual users remote access to some functions of the multi-viewer’s operating system. This document describes the Gateway functionality, and defines the commands that are available.

In this document, the term Kaleido is used to describe features common to the Kaleido-K2, KaleidoAlto/Quad/Quad-Dual, and Kaleido-X series of multi-viewers. The term Kaleido-X series refers to the Kaleido-X, Kaleido-X16, and KMV-3901/3911 multi-viewer models. Features exclusive to any one of these products will be described using the full product name (e.g. Kaleido-K2, Kaleido-Alto/Quad/QuadDual, Kaleido-X, Kaleido-X16, or KMV-3901/3911).

1.1 Software Versions

The information in this document applies to software released up to the date of publication, beginning with the versions given here for each Kaleido product:

1.2 Remote Operation of the Kaleido-X Series or KaleidoAlto/Quad/Quad-Dual Multi-Viewers

For remote operation, the Ethernet port of the Kaleido-Alto/Quad/Quad-Dual and Kaleido-X series is continuously available to communicate with a remote computer. The functionality is similar to the internal gateway on the Kaleido-K2, but on a Kaleido-Alto/Quad/Quad-Dual or Kaleido-X series multi-viewer, the Ethernet port is always ON and no configuration is required.

Kaleido-Alto/Quad/Quad-Dual and Kaleido-X series multi-viewer systems can execute XML commands received via TCP/IP (Transmission Control Protocol/Internet Protocol). To send commands, you can use a Terminal Emulation (telnet) program or create your own application using the language of your choice (C++, Visual Basic, Java…). In Section 3 below, the use of HyperTerminal software will be described. HyperTerminal is a Windows application that is typically installed on every Windows computer. (From the Start menu, point to All Programs > Accessories > Communications, and then click HyperTerminal.) This program will communicate with the multi-viewer system using communications port 13000.

1.3 Gateway Options for the Kaleido-K2

Two gateways are available for use with the Kaleido-K2:

 The internal gateway is implemented within the Kaleido-K2 software

Kaleido Remote Control Protocol (Gateway) | 1

USER’S GUIDE

 The MT-Gateway runs as a Windows service on the Kaleido-K2’s operating system

Note: The internal gateway is the preferred gateway, and Miranda strongly recommends that it be used instead of the MT-Gateway, as it is more robust. The MT-Gateway might be used for legacy applications (the internal gateway was not available in early versions of the software), or in specific situations based on design considerations, but its use is deprecated.

It is important to note that only one gateway can be operating at a time, and the user must manage the gateway resources to ensure that this is the case.

1.3.1 Internal Gateway

The internal gateway is implemented in the Kaleido-K2 software itself, and is therefore internal to and exclusively functional with a specific Kaleido-K2 frame.

The internal gateway is configured through the Kaleido.properties file, and is turned on or off by editing that file. Here is how to do it:

1. From your Kaleido-K2’s desktop, double-click the icon My Computer.

2. Navigate to C:\iControl\Startup\ and open the file Kaleido.properties using Notepad

(right-click the Kaleido.properties file, and then select Notepad from the Open With menu).

3. Search the file for either of the following lines:

 activateInternalGateway=TRUE  activateInternalGateway=FALSE

If activateInternalGateway is TRUE, the internal gateway is ON by default at startup. Disable the

internal gateway at startup by replacing TRUE with FALSE in this line.

If activateInternalGateway is FALSE, the internal gateway is OFF by default at startup. Enable the

internal gateway at startup by replacing FALSE with TRUE in this line.

4. On the File menu, click Save to save your changes.

5. Close the Notepad editor.

6. Restart the Kaleido-K2.

The internal gateway supports all Kaleido/Gateway commands when connected via port 13000, and supports only the <listnodes/> command when connected via port 10001. (The <listnodes/> command is available on the Kaleido-K2 systems only.)

1.3.2 MT-Gateway

The MT-Gateway is shipped with current versions of the Kaleido-K2 in support of legacy applications, but its use is not recommended.

As the MT-Gateway must not be running when you are using the internal gateway, verify that it is turned off as follows:

1. On the Kaleido-K2, display the desktop (use the desktop icon on the menu bar).

2 | Kaleido Remote Control Protocol (Gateway)

USER’S GUIDE

2. Double-click the Services icon. The Services management console will appear. You can see if the

MT-Gateway service is running, and whether it is configured to start automatically when the KaleidoK2 is booted.

3. Right-click MT_Gateway and then click Properties on the shortcut menu.

4. Select Manual as the startup type, and then click OK.

5. Click the Stop Service button on the toolbar to turn the gateway off.

1.4 Remote Operation of the Kaleido-K2 via the Gateway

Kaleido-K2 can execute XML commands received via either the internal gateway (preferred) or the MTgateway (deprecated). In an environment containing many Kaleido-K2s, there is a gateway running on each Kaleido-K2. Remember that in such an environment you should configure your system to have at most two lookups running (please refer to the ―How to configure the Kaleido-K2 in systems including more than two units and application servers?‖ section of the Kaleido-K2 documentation for more information).

Commands are sent to the gateway via TCP/IP (Transmission Control Protocol/Internet Protocol), so you can use a Terminal Emulation (telnet) program or create your own application using the language of your choice (C++, Visual Basic, Java …). In section 3 below, the use of HyperTerminal software will be described. HyperTerminal is a Windows application that is typically installed on every Windows computer. (From the Start menu, point to All Programs > Accessories > Communications, and then click HyperTerminal.) This program will communicate with the machine on which the gateway is running using communications port 13000.

Kaleido Remote Control Protocol (Gateway) | 3

USER’S GUIDE

Code

System

Multi-Viewer Models

Kaleido-X Software

Kaleido-X, Kaleido-X16, KMV-3901/3911

Kaleido-K2 Software

Kaleido-K2

Kaleido-Alto/Quad/Quad-Dual

Kaleido-Alto, Kaleido-Quad, Kaleido-Quad-Dual

Command

Applies to

Description

Page

openID

Opens a session with the specified Kaleido

closeID

Closes a previously opened session

getParameterInfo

Gets the system name, or its software version

getKCurrentLayout

Gets the name of the current layout

setKCurrentLayout

Loads a specific layout

getKLayoutList

Gets the list of available layouts

getKRoom

Gets information on how the heads are positioned within the specified room

getKRoomList

Gets the list of available rooms

setKStatusMessage

Sets a Gateway alarm to the specified state

setKUnlatch

Acknowledges the global alarm for the specified source (channel)

setKChannel

Associates a source (channel) to the specified monitor

2 Gateway Commands

Kaleido multi-viewers support the following commands through the Gateway access. Most of these apply to all Kaleido multi-viewer models, but some only apply to one platform, as indicated in the list. Furthermore, there may be differences in the use or syntax of some commands depending on the platform. All of these points are clarified in the detailed description of each command that follows.

Note: All gateway commands must be followed by a carriage return. In scripts, add \n at the end of each gateway command.

2.1 Index of Gateway Commands

The applicable Kaleido systems are indicated as follows:

The star () symbol indicates a new command, or a command with new parameters.

4 | Kaleido Remote Control Protocol (Gateway)

USER’S GUIDE

Command

Applies to

Description

Page

setKDynamicText

Sends text to the specified layout element

getKDynamicText

Retrieves text from the specified layout element

getKMetaData

K2 Gets metadata from a MultiData component

setKTimer

Configures the specified countdown timer

setKTimer2

K2 Configures the specified timer

setKTimerTrigger

Starts, stops or resets a countdown timer

setKFireAction

Fires the specified action

getKActionList

Gets the list of available actions

setKEnableAlarmGroup

K2 Enables an alarm group

setKDisableAlarmGroup

K2 Disables an alarm group

setKSaveLayout

Saves the current layout

getKAudioOut

Identifies the current audio output

setKAudioOut

Selects the audio to be monitored

getKAudioOutVolume

Gets the current audio monitoring output volume

setKAudioOutVolume

Sets the volume of the audio monitoring output

getKAudioOutMode

Gets the current audio monitoring output mode

setKAudioOutMode

Sets the audio monitoring output mode

setKVerticalOffset

Offsets the graphic from display

setKIcontrolMode

Enables/Disables mouse color keying over video

setKMouseColorA

Sets the mouse color to be keyed over the video

setKMouseColorB

Sets the mouse color to be keyed over the video

setKMouseColorC

Sets the mouse color to be keyed over the video

Kaleido Remote Control Protocol (Gateway) | 5

USER’S GUIDE

2.2 Document Conventions

Each command in this document is presented in the following format:

[Command Name] [Applicable Kaleido Systems]

Command description. The proper command syntax with variables. Gateway Response – a list of possible answers: a) For a successful execution of the command b) For an unsuccessful execution of the command Special notes for the command or specific platform.

2.3 Gateway Command Descriptions

Please note that the syntax must be exactly replicated when sending a command. Use the UTF-8 format to send Unicode text messages via the Gateway.

openID KX K2 AQ

This command opens a session with the specified Kaleido. Note: It is not necessary to open a session every time you want to send a command to the

Gateway. Since opening a session takes a few seconds, it is recommended that you keep a session open as long as commands need to be sent.

<openID>IP_ADDRESS_0_4_0_0</openID> On a Kaleido-X series multi-viewer: To open a session without room context:

OR to open a session with a room context: <openID>ROOM_NAME</openID> OR to open a session with user privilege validation with MD5 password hash:

<openID>mirandagateway://USERNAME:PASSWORD_MD5_HASH@SYSTEM_NAME/RO OM_NAME</openID>

6 | Kaleido Remote Control Protocol (Gateway)

USER’S GUIDE

OR to open a session with user privilege validation without MD5 password hash:

<openID>mirandagateway://USERNAME:CLEAR_PASSWORD @SYSTEM_NAME/ROOM_NAME</openID>

Where:

o IP_ADDRESS is the IP address of your destination Kaleido frame. o ROOM_NAME is the room context for the session (see getKCurrentLayout,

setKCurrentLayout and getKLayoutList).

o USERNAME is the username that will be used to validate permissions. o PASSWORD_MD5_HASH is the md5 hash of the user password, encoded in base 64. o For information on md5 see http://www.ietf.org/rfc/rfc1321.txt. o For information on base 64 see RFC 3548. o CLEAR_PASSWORD is the user password. o SYSTEM_NAME is the system name as specified in XAdmin.

Gateway response:

 <ack/>: The command was recognized by the Gateway.

 <nack/>:

o The Gateway was not able to recognize the command OR o The room name was invalid OR o The username does not match the provided password OR o The system name was invalid. o The IP_ADDRESS parameter is wrong.

closeID KX K2 AQ

This command closes a session with the specified Kaleido. On a Kaleido-X series multi-viewer: <closeID/> On a Kaleido-K2 or Kaleido-Alto/Quad/Quad-Dual multi-viewer: <closeID>IP_ADDRESS_0_4_0_0</closeID> Where IP_ADDRESS is the IP address of the Kaleido-K2 or Kaleido-Alto/Quad/Quad-Dual. Gateway response:

 <ack/>: The command was recognized by the Gateway.

Kaleido Remote Control Protocol (Gateway) | 7

+ 25 hidden pages