Kaleido Remote Control Protocol (Gateway) User’s Guide€¦ · To disable the Kaleido-K2 MT-Gateway 1 On the Kaleido-K2, display the desktop (use the desktop icon on the menu bar)

User’s GuideM770-0900-117

2015-05-28

Kaleido Remote Control Protocol (Gateway)

ii

Notices

Copyright & Trademark NoticeCopyright © 2006–2015, Grass Valley USA, LLC. All rights reserved.

Belden, Belden Sending All The Right Signals, and the Belden logo are trademarks or registered trademarks of Belden Inc. or its affiliated companies in the United States and other jurisdictions. Kaleido, Kaleido-X, Kaleido-X16, KMV-3901/3911, Kaleido-IP, Kaleido-MX, Kaleido-MX 4K, Kaleido-Modular-X, and iControl are trademarks or registered trademarks of Grass Valley USA, LLC. Belden Inc., Grass Valley USA, LLC, and other parties may also have trademark rights in other terms used herein.

Terms and ConditionsPlease read the following terms and conditions carefully. By using Kaleido multiviewer documentation, you agree to the following terms and conditions.

Grass Valley hereby grants permission and license to owners of Kaleido multiviewers to use their product manuals for their own internal business use. Manuals for Grass Valley products may not be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording, for any purpose unless specifically authorized in writing by Grass Valley.

A Grass Valley manual may have been revised to reflect changes made to the product during its manufacturing life. Thus, different versions of a manual may exist for any given product. Care should be taken to ensure that one obtains the proper manual version for a specific product serial number.

Information in this document is subject to change without notice and does not represent a commitment on the part of Grass Valley.

Warranty information is available in the Support section of the Grass Valley Web site (www.grassvalley.com).

Title Kaleido Remote Control Protocol (Gateway) User’s Guide

Part Number M770-0900-117

Revision 28 May 2015, 5:54 pm

Table of Contents

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Software Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Remote Operation of a Multiviewer via TCP/IP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

2 Gateway Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Index of Gateway Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Gateway Command Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

3 A Typical Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Opening an HyperTerminal Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25Opening a Gateway Session With a Multiviewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28Sending Commands to the Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28Closing a Gateway Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28

Appendix: Kaleido-X Series Support History. . . . . . . . . . . . . . . . 29

Contact Us . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

iii

Introduction

Grass Valley multiviewers can execute commands received via a gateway, allowing third-party developers and individual users remote access to some functions of the multiviewer'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, Kaleido-Alto/Quad/Quad-Dual, and Kaleido-X series of multiviewers. The term Kaleido-X series refers to the Kaleido-X, Kaleido-X16, KMV-3901/3911, Kaleido-XQUAD, Kaleido-IP, Kaleido-MX, Kaleido-MX 4K and Kaleido-Modular-X multiviewer models. Features exclusive to any one of these products will be described using the full product name (e.g., Kaleido-K2, Kaleido-X, Kaleido-IP, etc.).

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

Remote Operation of a Multiviewer via TCP/IPTo send commands to your multiviewer’s Gateway, you can use a Terminal Emulation (telnet) program or create your own application using the language of your choice (e.g., C++, Visual Basic, Java). Refer to A Typical Session, on page 25, for a sample scenario using HyperTerminal. The commands are described in the next chapter (see Gateway Commands, on page 5).

• Kaleido-Alto/Quad/Quad-Dual and Kaleido-X series multiviewer systems can execute commands received on port 13000 via TCP/IP (Transmission Control Protocol/Internet Protocol). On these multiviewers, the port 13000 is always ON, and no configuration is required.

• Kaleido-K2 multiviewers can execute commands received via either the multiviewer’s internal gateway (preferred), or via its MT-gateway (deprecated). The internal gateway supports all Kaleido-K2 Gateway commands when connected via port 13000. When connected via port 10001, it supports the <listnodes/> command only. (This command is exclusive to the Kaleido-K2.)

Kaleido-X series Kaleido-X Software version 3.00 or later (see Kaleido-X Series Support History, on page 29, for a detailed breakdown by command and multiviewer model)

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

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

Kaleido-K2 Kaleido Software version 5.30 or later

1

IntroductionGateway Options for the Kaleido-K2

In an environment containing many Kaleido-K2 multiviewers, 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 (refer to How to configure the Kaleido-K2 in systems including more than two units and application servers? in the Kaleido-K2 documentation, for more information).

Gateway Options for the Kaleido-K2Two gateways are available for use with the Kaleido-K2:

• The internal gateway is implemented within the Kaleido-K2 software. See Kaleido-K2 Internal Gateway below.

• The MT-Gateway runs as a Windows service on the Kaleido-K2's operating system. See Kaleido-K2 MT-Gateway on page 3.

Kaleido-K2 Internal GatewayThe internal gateway is implemented in the Kaleido-K2 software itself, and is therefore internal to and exclusively functional with a specific Kaleido-K2 frame. It is configured through the Kaleido.properties file, and is turned on or off by editing that file.

The internal gateway and the MT-Gateway must not be running concurrently: refer to Disabling the Kaleido-K2’s MT-Gateway, on page 3, to verify that the MT-Gateway is turned off.

Enabling or Disabling the Kaleido-K2’s Internal Gateway

To enable or disable the Kaleido-K2’s internal gateway1 On your Kaleido-K2’s desktop, double-click 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.

IMPORTANT

The internal gateway is the preferred gateway, and Grass Valley 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, or in specific situations based on design considerations, but its use is deprecated.

Only one gateway can be operating at a time: you must manage the gateway resources to ensure that this is the case.

2

Kaleido Remote Control Protocol (Gateway)User’s Guide

4 On the File menu, click Save to save your changes.5 Close Notepad.6 Restart the Kaleido-K2.

Kaleido-K2 MT-GatewayThe MT-Gateway is shipped with current versions of the Kaleido-K2 in support of legacy applications (the internal gateway was not available in early versions of the software), but its use is not recommended.

Disabling the Kaleido-K2’s MT-Gateway

To disable the Kaleido-K2 MT-Gateway1 On the Kaleido-K2, display the desktop (use the desktop icon on the menu bar).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 Kaleido-K2 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.

3

Gateway Commands

Kaleido multiviewers support the following commands through the Gateway access. Most of these apply to all Kaleido multiviewer 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.

Index of Gateway CommandsThe applicable Kaleido systems are indicated as follows:

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

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

Code System Multiviewer Models

KX Kaleido-X Software Kaleido-X, Kaleido-X16, KMV-3901/3911, Kaleido-XQUAD, Kaleido-IP, Kaleido-MX, Kaleido-MX 4K, Kaleido-Modular-X

K2 Kaleido-K2 Software Kaleido-K2

AQ Kaleido-Alto/Quad/Quad-Dual Kaleido-Alto, Kaleido-Quad, Kaleido-Quad-Dual

Command Applies to Description Page

openID KX K2 AQ Opens a session with the specified Kaleido 7

closeID KX K2 AQ Closes a previously opened session 8

getParameterInfo KX Gets the system name, or its software version 8

getKCurrentLayout KX K2 AQ Gets the name of the current layout 8

setKCurrentLayout KX K2 AQ Loads a specific layout 9

getKLayoutList KX K2 AQ Gets the list of available layouts 10

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

10

getKRoomList KX Gets the list of available rooms 11

setKStatusMessage KX K2 AQ Sets a Gateway alarm to the specified state 11

setKUnlatch KX Acknowledges the global alarm for the specified source (channel)

12

getKChannel KX Gets the source (channel) currently assigned to the specified monitor

13

5

Gateway CommandsDocument Conventions

Document ConventionsEach 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 commandb For an unsuccessful execution of the command

Special notes for the command or specific platform

setKChannel KX K2 AQ Associates a source (channel) to the specified monitor

13

setKDynamicText KX K2 AQ Sends text to the specified layout element 14

getKDynamicText KX Retrieves text from the specified layout element 14

getKMetaData K2 Gets metadata from a MultiData component 15

setKTimer KX K2 AQ Configures the specified countdown timer 16

setKTimer2 KX K2 Configures the specified timer 16

setKTimerTrigger KX K2 AQ Starts, stops or resets a countdown timer 17

setKFireAction KX K2 AQ Fires the specified action 17

getKActionList KX Gets the list of available actions 18

setKEnableAlarmGroup KX K2 Enables an alarm group 18

setKDisableAlarmGroup KX K2 Disables an alarm group 18

setKSaveLayout K2 AQ Saves the current layout 19

getKAudioOut KX K2 AQ Identifies the current audio output 19

setKAudioOut KX K2 AQ Selects the audio to be monitored 20

getKAudioOutVolume KX K2 AQ Gets the current audio monitoring output volume

21

setKAudioOutVolume KX K2 AQ Sets the volume of the audio monitoring output 22

getKAudioOutMode KX K2 AQ Gets the current audio monitoring output mode 22

setKAudioOutMode KX K2 AQ Sets the audio monitoring output mode 23

setKVerticalOffset AQ Offsets the graphic from display 23

setKIcontrolMode AQ Enables/Disables mouse color keying over video 23

setKMouseColorA AQ Sets the mouse color to be keyed over the video 23

setKMouseColorB AQ Sets the mouse color to be keyed over the video 24

setKMouseColorC AQ Sets the mouse color to be keyed over the video 24

Command Applies to Description Page

6


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

openIDKX K2 AQ This command opens a session with the specified Kaleido multiviewer.

• On a Kaleido-K2 or Kaleido-Alto/Quad/Quad-Dual multiviewer:<openID>IP_ADDRESS_0_4_0_0</openID>

• On a Kaleido-X series multiviewer:• To open a session without room context:

<openID/>

• To open a session with a room context:<openID>ROOM_NAME</openID>

• To open a session with user privilege validation with MD5 password hash:<openID>mirandagateway://USERNAME:PASSWORD_MD5_HASH@SYSTEM_NAME/ROOM_NAME</openID>

• To open a session with user privilege validation without MD5 password hash:<openID>mirandagateway://USERNAME:CLEAR_PASSWORD @SYSTEM_NAME/ROOM_NAME</openID>

Where:IP_ADDRESS is the IP address of your destination Kaleido frame.ROOM_NAME is the room context for the session (see getKCurrentLayout, setKCurrentLayout and getKLayoutList).USERNAME is the user name of the RCP user (authorized for the room) that will be used to validate permissions.PASSWORD_MD5_HASH is the md5 hash of the user password, encoded in base 64.1 CLEAR_PASSWORD is the user password.SYSTEM_NAME is the system name as specified in XAdmin.

Gateway response:• <ack/>: The command was recognized by the Gateway.• <nack/>:

• The Gateway was not able to recognize the command.• The room name was invalid.• The user name did not match the password provided.

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.

1.For information on md5 see http://www.ietf.org/rfc/rfc1321.txt; for information on base 64 see RFC 3548.

7

Gateway CommandscloseID

• The system name was invalid.• The IP address was wrong.

closeIDKX K2 AQ This command closes a session with the specified Kaleido.

• On a Kaleido-X series multiviewer:<closeID/>

• On a Kaleido-K2 or Kaleido-Alto/Quad/Quad-Dual multiviewer:<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.• <nack/>: The Gateway was not able to recognize the command.

getParameterInfoKX This command serves two purposes: it can retrieve the current system’s name, or the

version of the Kaleido-X Software installed on this system.• To obtain the software version, the command is:

<getParameterInfo>get key="softwareVersion"</getParameterInfo>

Gateway response:• <kParameterInfo>softwareVersion="Software Version"</kParameterInfo>

Example: <kParameterInfo>softwareVersion="7.20 build 5407"</kParameterInfo>

• <nack/>: The Gateway was not able to recognize the command.• To obtain the system name, the command is:

<getParameterInfo>get key="systemName"</getParameterInfo>

Gateway response:• <kParameterInfo>systemName="System Name"</kParameterInfo>

Example: <kParameterInfo>systemName="Cougar-X"</kParameterInfo>• <nack/>: The Gateway was not able to recognize the command.

getKCurrentLayoutKX K2 AQ This command retrieves the name of the current layout.

Note: This command closes the current connection on port 13000. This connection must be re-established before another session can be opened. If you are using HyperTerminal, it will automatically re-establish the previous connection if you begin typing new commands, but other clients may require you to manually reconnect.

8


<getKCurrentLayout/>

Gateway response:• For a Kaleido-Alto/Quad/Quad-Dual multiviewer:

<kCurrentLayout>Currentlayout.xml</kCurrentLayout>

Where CurrentLayout.xml is the name of the layout currently loaded to the monitor wall

• For a Kaleido-K2 or a Kaleido-X series multiviewer:<kCurrentLayout>name="CurrentLayout.kg2"</kCurrentLayout>

Where CurrentLayout.kg2 is the name of the layout currently loaded to the monitor wall

• <nack/>: The Gateway was not able to recognize the command.

setKCurrentLayoutKX K2 AQ This command loads the specified layout.

• For a Kaleido-K2 or a Kaleido-X series multiviewer:<setKCurrentLayout>set LayoutToLoad.kg2</setKCurrentLayout>

• For a Kaleido-Alto/Quad/Quad-Dual multiviewer:<setKCurrentLayout>set LayoutToLoad.xml</setKCurrentLayout>

Where LayoutToLoad is the name of the layout to load.

Gateway response:• <ack/>: The command was recognized by the Gateway, and the layout has been fully

loaded.• <nack/>: The Gateway was not able to recognize the command, or the layout could not

be found.

Note: On a Kaleido-X series multiviewer, the session must have a room context for the command to be used. If the session was opened using the <openID/> command the gateway will return <nack/>.

Notes

• This Layout must be available on the multiviewer prior to executing this command.

• You can use getKLayoutList to retrieve the names of the available layouts before sending this command.

• For a Kaleido-Alto/Quad/Quad-Dual multiviewer, the layout suffix is .xml instead of .kg2.

• For a Kaleido-X series multiviewer, if the session does not have a room context, the layout name must be prefixed with the room name and a “/”.Example: <setKCurrentLayout>set Room1/Layout1.kg2</setKCurrentLayout>

9

Gateway CommandsgetKLayoutList

getKLayoutListKX K2 AQ This command returns the list of layouts that are available on the multiviewer.

<getKLayoutList/>

Gateway response:• <kLayoutList> Layout1.kg2 Layout2.kg2 … AnAvailableLayout.kg2</

kLayoutList>

Where: Layout1, Layout2 and AnAvailableLayout are the names of the layouts that are available on the multiviewer.


getKRoomKX This command is used to obtain information on how the heads are positioned relatively to

each other within the specified room.• For a session without room context, the command is:

<getKRoom>ROOM_NAME</getKRoom>

• For a session with a room context, the command is:<getKRoom/>

Gateway response:• The response is the specified room exactly as it is stored in the database but without

the XML header. Example:<room UUID="4afa6407-a753-11dc-9fb9-e3bbad2712e5" beanType="monako.data.rooms" createdTime="1197313709663" currentLayoutUrl="miranda.data.access:MultiHeadLayoutBean/d8b14b99-8321-11dd-8648-49f166ea7203" friendlyName="Room1" lastModifiedTime="1228233770264" path="/" readOnly="false" version="824" xmlVersion="273114">

<defaultRoomPreferences>

<preferences>

<preference editable="true" editablePerUser="true" type="audioOut" uid="audioOut" value="miranda.monako.daq://local/data/master/9/card/head:0/port:Analog%20AES%20Audio%20Out"/>

<preference editable="true" editablePerUser="true" type="Preset" uid="MultiHeadLayoutBean.10" value="miranda.data.access:MultiHeadLayoutBean/3aadaaff-df2b-11dc-86c6-b5c2f6a72665"/>

Notes

• For a Kaleido-X series multiviewer:• If the session does not have a room context, the layout names will be

prefixed with the room name and a “/”. Example:<kLayoutList>Room1/MAIN.kg2 Room1/BACKUP1.kg2 Room2/MAIN.kg2</kLayoutList>

• If the session has a room context, only layouts for that room will be returned and the layout names will not be prefixed with the room name.

• For Kaleido-Alto/Quad/Quad-Dual multiviewers, the layout suffix is .xml instead of .kg2.

10


<preference editable="false" editablePerUser="true" type="useLargeCursor" uid="useLargeCursor" value="true"/>

<preference editable="true" editablePerUser="true" type="Preset" uid="MultiHeadLayoutBean.9" value="miranda.data.access:MultiHeadLayoutBean/5a475f81-df1b-11dc-a920-9d4ecc32cf8e"/>

...

</preferences>

</defaultRoomPreferences>

<heads>

<head allowDashboard="true" frameName="Cougar-X" friendlyName="Default Display" headID="23" headNumber="1" id="Cougar-X.23" logicalID="2" resolutionSettingsUuid="8af91a81-0af1-11dd-a25a-f534b3d6b0d3" rotated="false" rotation="normal" slotNumber="11">

<dimension x="1398" y="874"/>

<position x="4408" y="32"/>

<resolution height="1200" width="1920"/>

<rotDimension x="1398" y="874"/>

<rotResolution height="1200" width="1920"/>

</head>

<head allowDashboard="true" frameName="Cougar-X" friendlyName="Default Display" headID="21" headNumber="1" id="Cougar-X.21" logicalID="1" resolutionSettingsUuid="9016b92b-cdbe-11db-ae68-a122768fdba0" rotated="false" rotation="normal" slotNumber="10">

<dimension x="1400" y="875"/>

...

</head>

...

</heads>

</room>


getKRoomListKX This command is used to obtain the list of rooms known to your multiviewer system.

<getKRoomList/>

Gateway response:• <kRoomList><room>Room A</room><room>Room B</room></kRoomList>• <nack/>: The Gateway was not able to recognize the command.

setKStatusMessageKX K2 AQ This command associates an alarm state with an ID. The multiviewer can be configured to

listen to alarm status messages from the Gateway, and thus report the state it receives. This is a convenient way of reporting alarms to multiviewers.

11

Gateway CommandssetKUnlatch

<setKStatusMessage>set id="ID" status="Status" message="Message" </setKStatusMessage>

Where:• ID is the identifier that will receive the new state.

• Status is any of the available statuses:

• Message is reserved for future use, and is ignored.


setKUnlatchKX This command is used to acknowledge the global alarm for a given logical source (channel).

It can also be used to acknowledge specific alarms.

The command supports three parameter types: channelName, id or uri.• Use channelName to acknowledge the global alarm associated with the specified

source:<setKUnlatch>set channelName="ChannelName"</setKUnlatch>

Example: <setKUnlatch>set channelName="/Input A/Channel 01"</setKUnlatch>

• Use uri to acknowledge the alarm with the specified URI:<setKUnlatch> set uri="AlarmURI"</setKUnlatch>

Example: <setKUnlatch>set uri="miranda.monako.daq://local/data/master/3/card/av1/DTVCCData#dtvccService1Presence"</setKUnlatch>

• Use id to acknowledge the gateway alarm with the specified name:<setKUnlatch>set id="AlarmName"</setKUnlatch>

Note: Kaleido-Alto/Quad/Quad-Dual will only accept numeric values for this parameter, in the range 0 to 1024. The Kaleido-K2 and Kaleido-X series do not have this limitation.

Status Alternate statusa

a. Legacy

Kaleido-X series Kaleido-K2/Alto/Quad/Quad-Dual

DISABLE DISABLE Disabled Disabled

NORMAL OK Normal OK

MINOR WARNING Minor Warning

MAJOR MAJOR Major (not supported)

CRITICAL ERROR Critical Error

12


Example: <setKUnlatch>set id="my_gateway_alarm_1"</setKUnlatch>


getKChannelKX

This command is used to obtain the logical source (channel) currently assigned to the specified monitor in the current layout.

<getKChannel>set monitor="MonitorName"</getKChannel>

Where MonitorName is the name of the monitor whose source you wish to obtain. The monitor name must be prefixed with the room name and a “/” if the session does not have a room context. Example: Room1/composite42. To find the monitor name, open the layout in XEdit (see Name, under Assignments in the Properties tab).

Gateway response:• <kChannel>channelname="ChannelName"</kChannel>

Where ChannelName is the full path to the source (channel) currently assigned to the specified monitor. Example: /Input A/Channel 1.

• <nack/>: The Gateway was not able to recognize the command, or a parameter could not be resolved.

setKChannelKX K2 AQ This command is used to assign a logical source (channel) to the specified monitor in the

current layout.<setKChannel>set channelname="ChannelName" monitor="MonitorNumber" </setKChannel>

Where:• ChannelName is the name of the logical source you wish to assign to the specified

monitor. On a Kaleido-X series multiviewer this is the full path to the source (channel). Example: /Input A/Channel 1.

• MonitorNumber is the identifier of the monitor to which the source is to be assigned. On a Kaleido-X series multiviewer the monitor number must be prefixed with the room name and a “/” if the session does not have a room context. Example: Room1/

Note: Only one parameter can be specified, otherwise the Gateway will return <nack/>.

Note: This command is currently supported on the Kaleido-IP multiviewer models only.

13

Gateway CommandssetKDynamicText

composite42. The monitor name is the name you see (under Assignments in the Properties tab) when you open the layout in XEdit and select this monitor.

Gateway response:• <ack/>: The command was recognized by the Gateway.• <nack/>: The Gateway was not able to recognize the command, or a parameter could

not be resolved.

setKDynamicTextKX K2 AQ This command is used to set the text of a UMD or text label component that is configured

to use dynamic text. Note that the Service ID for this component must be set to “Gateway” when the layout is created in KEdit/XEdit in order for this command to work.

<setKDynamicText>set address="Address" text="NewText"</setKDynamicText>

Where:• Address is the configured text address of the UMD or text label component.

• NewText is the text to display.


getKDynamicTextKX This command is used to retrieve dynamic text previously sent to a multiviewer by a

peripheral device (e.g., a router or tally interface device).<getKDynamicText>set address="Address"</getKDynamicText>

Where Address is the configured text address of the UMD or text label component whose text you wish to retrieve.

Gateway response:• <kDynamicText>RetrievedText</kDynamicText>


Note: On the Kaleido-K2, to get the monitors’ identifiers for your current layout press the Tab key on the keyboard, or the select key on the Kaleido-RCP.

Note: The Kaleido-Alto/Quad/Quad-Dual systems require a numeric value in the range 0-1024. The Kaleido-K2 and Kaleido-X series do not have this limitation.

Note: This command will only return text that was previously set via the <setKDynamicText> command.

14


getKMetaDataK2 This command is used to get metadata that is assigned to a MultiData component assigned

to a text label in the Kaleido-K2. The Kaleido-K2 will return XDS, Dolby-E and video format data in response to this command.

<getKMetaData>get dataname=MultiDataName</getKMetaData>

Where MultiDataName is the name of the MultiData source, as defined in the MultiData Configuration panel.

Gateway response:• <kMetaData><error>MultiDataName not found</error></kMetaData>: The

MultiData entity does not exist in the Kaleido-K2.• <kMetaData><input id="1" stationID="1234" channelNumber="12"/> <input id="2" stationID="RDS" channelNumber="25"/></kMetaData>

Where the returned information (shown in italics above) is the data contents of the MultiData element. This example shows a typical return of data; the actual data returned will depend upon the configuration and definition of the MultiData component on the Kaleido-K2.The response is grouped by input, and the inputs sorted in ascending order (from input 1 to 32).For each input, all the data is presented as attributes.The data legends is mapped to valid XML attribute names, which are listed here:

• inputFormat• WSS• scansys• AFD• AFD3Bits• AFDANC• SID• programConfig• dialogLevel• networkName• stationID• channelNumber• TSID• programName• programType• vChipRating• programDescription• programLength• elapsedTime• programID• timeOfDay

15

Gateway CommandssetKTimer

• timeZoneThe value field is escaped as defined in the XML protocol for an attribute value. For example, ABC"DEF\GHI<JKL>MNO/PQR&STU;VWX'YZ becomes ABC"DEF\GHI<JKL>MNO/PQR&STU;VWX'YZ

The attributes order is not guaranteed and may change for two consecutive calls to the same command.

• <nack/>: There is a syntax error in the XML command.

setKTimerKX K2 AQ This command is used to configure the specified countdown timer component.

<setKTimer>set id="TimerID" preset="hh:mm:ss" direction="Direction" loop="Loop" </setKTimer>

Where:• TimerID is the ID of the countdown timer component to modify.• hh:mm:ss is the preset value for the countdown timer component.• Direction is the direction to count, either UP or DOWN.• Loop indicates if the counter must count continuously. This value can be either ON or

OFF.


setKTimer2KX K2 This command is used to configure a timer in a Kaleido-K2 or Kaleido-X series multiviewer

system.<setKTimer2>set TimerName="NAME" StartTime="HH:MM:SS:FF" PresetTime="HH:MM:SS:FF" TimerMode="Timer mode" EndMode="End mode" </setKTimer2>

Where:• NAME is the name assigned to the timer in the Timer configuration panel accessed from

the Timer Browser window in KEdit, or in the Timer Editor window in XEdit.• StartTime may be one of the following:

• HH:MM:SS:FF – time in hours:minutes:seconds:frames at which this timer will start its count, depending on its configuration and presence of triggers. Note that if the hour value is 00, the start time is deemed to be the previous midnight, whereas 24 is considered to be the next midnight. This allows the timer to decide whether it

Note: If the MultiData component is not assigned to a text component, no values will be included in the information returned to the user from the gateway. Make sure to assign the MultiData component to a text label component.

16


should be counting or waiting to start when it compares the start time to the current time.

• NOW – the timer will start counting immediately upon receiving the command.• WAIT – the timer will not start until it receives a setKTimerTrigger gateway

command with the argument START.• PresetTime may be one of the following:

• Count duration (hours:minutes:seconds:frames) for UP and DOWN timer modes.• End time (hours:minutes:seconds:frames) for the REMAINING timer mode.

• TimerMode is the operating mode of the timer. Possible values are: up, down, remaining.

• EndMode defines what is to happen when the timer reaches the end of its count. Possible values are: LOOP, STOP, and OVERRUN.


setKTimerTriggerKX K2 AQ This command is used to control the specified countdown timer component. The

countdown timer can be started, stopped or reset.<setKTimerTrigger>set id="TimerID" trigger="Trigger" </setKTimerTrigger>

Where:• TimerID is the ID of the countdown timer component to control.• Trigger is the action that the countdown timer must do. This value can either be

START, STOP, or RESET.


setKFireActionKX K2 AQ This command is used to fire the specified Action (for example, by an external third-party

system that is unable to use the GPI in as a trigger).<setKFireAction>set name="NameOfTheActionToFire"</setKFireAction>

Note: Although the current implementation of this command allows you to specify frame values, they are not used by the timer, which will start on the exact second.

Note: Although the current implementation of this command allows you to specify frame values, they are not used by the timer, which will start on the exact second.

17

Gateway CommandsgetKActionList

Where NameOfTheActionToFire is the friendly name of the action to be executed.

Gateway response:• <ack/>: The command was recognized by the Gateway.• <nack/>: The Gateway was not able to recognize the command, or the command could

not be executed.

getKActionListKX This command is used to obtain the list of actions known to your multiviewer system.

<getKActionList/>

Gateway response:• <kActionList><action>Action1</action><action>Action2 </action><action>Action3</action></kActionList>


setKEnableAlarmGroupKX K2 This command enables the specified alarm group or virtual alarm.

<setKEnableAlarmGroup>set name="NameOfTheGroupToEnable" </setKEnableAlarmGroup>

Where NameOfTheGroupToEnable is the name of the alarm group (for a Kaleido-K2 multiviewer), or virtual alarm (for a Kaleido-X series multiviewer model) you wish to enable. In the case of a Kaleido-X series multiviewer model, this parameter can be the path/friendlyName of the virtual alarm, or its URI.


setKDisableAlarmGroupKX K2 This command is used to disable the specified alarm group or virtual alarm.

<setKDisableAlarmGroup>set name="NameOfTheGroupToDisable" </setKDisableAlarmGroup>

Notes

• For a Kaleido-X series multiviewer, the friendly name is specified under the Properties tab in XEdit.

• The action must be available on the multiviewer in order to be executed.

• On a Kaleido-X series multiviewer, background actions listed in the On Change/Gateway column under XEdit’s Actions tab will be executed when the action is fired by the Gateway command.

Note: On a Kaleido-X series multiviewer, an action that consists of multiple action items will stop as soon as one of the action items cannot be executed. The Gateway would then return <nack/>.

18


Where NameOfTheGroupToDisable is the name of the alarm group (for a Kaleido-K2 multiviewer), or virtual alarm (for a Kaleido-X series multiviewer model) you wish to disable. In the case of a Kaleido-X series multiviewer model, this parameter can be the path/friendlyName of the virtual alarm, or its URI. The virtual alarm will be set to OFFLINE.


setKSaveLayoutK2 AQ This command allows the user to save the currently displayed layout to a file.

<setKSaveLayout>set name="FileName"</setKSaveLayout>

Where FileName is the name of the file that will contain the layout. Do not specify an extension to the file name. The file extension .kg2 (for Kaleido-K2 layouts) or .xml (for Kaleido-Alto/Quad/Quad-Dual layouts) will be automatically added by the system.

Gateway response:• <ack/>: The command was correctly interpreted and executed.• <nack/>: The command was not executed, due to wrong spelling or invalid parameter.

getKAudioOutKX K2 AQ

This command allows the user to get information on the current source at the analog audio monitoring output.

<getKAudioOut/>

Gateway response:• <kAudioOut>DETAILS</kAudioOut>: The command was executed.DETAILS will vary depending on the type of audio output detected.

• When no audio is currently being monitored: <kAudioOut>Type="NONE"</kAudioOut>

• For a streaming source, the returned value indicates the IP address and the Feed ID of the source using the following syntax:

<kAudioOut>Type="STREAMING" IP="999.999.999.999" FeedID="XX" </kAudioOut>

Where:• 999.999.999.999 is the IP address of the device from where the stream

originates.• XX is the identifier of the feed to use.

Notes

• To use this command with a Kaleido-X series multiviewer, you must first open a session with user privilege validation (see openID), otherwise the gateway will return <nack/>.

• The KMV-3901/3911, and Kaleido-IP do not support this command.

19

Gateway CommandssetKAudioOut

• For an Audio Bridge Terminal (ABT) source, the returned value indicates which ABT input is being monitored:

<kAudioOut> Type="AUDIOCARD" Input="999"</kAudioOut>

Where 999 represents the ABT input number. ABT input numbers 1–64 are associated with the SDTI IN (or ABT/MADI) connector on your multiviewer’s INPUT A card; numbers 65-128 to the connector on INPUT B, etc.

• For an embedded source, the returned value will contain the video input, the group and the AES used. The syntax will be:

<kAudioOut>Type="EMBEDDED" Input="AAA" Group="BB" AES="X" </kAudioOut>

Where:• AAA indicates the video input.• BB indicates the group. Valid values are from 1 to 4.• X indicates the AES. Valid value can be either 1 or 2.

• <nack/>: The command was not executed.

setKAudioOutKX K2 AQ

You can select the audio source to be monitored at the analog audio output by using this Gateway command. The syntax of the command depends on whether you wish to monitor audio from a stream, from an Audio Bridge Terminal device, from an embedded source, or no audio at all.

<setKAudioOut>DETAILS</setKAudioOut>

Where DETAILS will differ depending on the type of audio source being selected for monitoring, as shown below.

• To select a streaming source, format the command as follows:<setKAudioOut>set Type="STREAMING" IP="999.999.999.999" FeedID="XX"</setKAudioOut>

Where:

Notes



• The Kaleido-Alto, Kaleido-Quad, and Kaleido-Quad-Dual do not support streaming sources.

• You may select any audio source for monitoring, independent of whether it is being metered in the current layout, with the exception that a streaming source must be part of the current layout.

• If the source is included in the layout, the meter assigned to it will be highlighted.

• If the source is not included in the layout, the sound will be routed to the audio monitors, but there will be no indication of the source, in the layout.

20


• 999.999.999.999 is the IP address of the device from where the stream occurs.• XX is the identifier of the feed to use.

• To select an Audio Bridge Terminal (ABT) source, format the command as follows:<setKAudioOut>set Type="AUDIOCARD" Input="999"</setKAudioOut>

Where 999 represents the ABT input number. ABT input numbers 1–64 are associated with the SDTI IN (or ABT/MADI) connector on your multiviewer’s INPUT A card; numbers 65-128 to the connector on INPUT B, etc.

• To select an embedded source, format the command as follows:<setKAudioOut>set Type="EMBEDDED" Input="AAA" Group="BB" AES="X"</setKAudioOut>

Where:• AAA indicates the video input.• BB indicates the group. Valid values range from 1 to 4.• X indicates the AES. Value can be either 1 or 2.

• To stop audio monitoring and mute the audio output:<setKAudioOut>set Type="NONE"</setKAudioOut>

Gateway response: • <ack/>: The command was correctly interpreted.• <nack/>: The command was not executed, due to wrong spelling or an invalid

parameter.

getKAudioOutVolumeKX K2 AQ

This command retrieves the current volume at the analog audio monitoring output.<getKAudioOutVolume/>

Gateway response:• <kAudioOutVolume>volume="XX"</kAudioOutVolume>

Where XX is the value, expressed in dB, at which the audio monitoring volume is set. This value ranges between 96 dB and +24 dB for a Kaleido-X series multiviewer, and between 90 dB and 0 dB for a Kaleido-K2/Alto/Quad/Quad-Dual. Fractions of dB are supported on the Kaleido-X series multiviewers only.

• <nack/>: The command was not recognized.

Notes



21

Gateway CommandssetKAudioOutVolume

setKAudioOutVolumeKX K2 AQ

This command sets the volume at the analog audio monitoring output.<setKAudioOutVolume>set volume="XX"</setKAudioOutVolume>

Where XX is the value, expressed in dB, at which the volume will be set. Valid values range between 96 dB and +24 dB for a Kaleido-X series multiviewer, and between 90 dB and 0 dB for a Kaleido-K2/Alto/Quad/Quad-Dual. Fractions of dB are supported on the Kaleido-X series multiviewers only.

Gateway response:• <ack/>: The command was correctly interpreted. The volume was set to the new value.• <nack/>: The command was not executed, due to a spelling error or invalid parameter.

The volume remains unchanged.

getKAudioOutModeKX K2 AQ

This command retrieves the audio monitoring mode currently used at the analog audio monitoring output.

<getKAudioOutMode/>

Gateway response:• <kAudioOutMode>mode="XXXXX"</kAudioOutMode>

Where XXXXX is the mode, which can be any of NORMAL, MUTE or –20 dB.• <nack/>: The command was not executed, due to a spelling error or invalid parameter.

Notes



• If the audio signal is muted, executing this command will unmute the signal.

Notes



22


setKAudioOutModeKX K2 AQ

To set the audio monitoring mode at the analog audio monitoring output, the following command is used:

<setKAudioOutMode>set mode="XXXXX"</setKAudioOutMode>

Where XXXXX is the value at which the mode must be set. Valid values are NORMAL, MUTE and –20 dB.

Gateway response:• <ack/>: The command was correctly interpreted. The Audio Monitoring Mode was set

to the specified value. • <nack/>: The command was not executed, due to bad spelling or invalid parameter.

The audio monitoring mode remains unchanged.

setKVerticalOffsetAQ This command is used to position the CPU’s graphic output vertically within the final DVI

output on the display. The Kaleido-Alto/Quad’s CPU includes up to 1024 lines, whereas the final output includes up to 1200 lines.

<setKVerticalOffset>set offset="NN"</setKVerticalOffset>

Where NN is the number of lines (between 0 and 175) by which to offset the CPU’s graphic output, from the top of the final DVI output.


setKIcontrolModeAQ This command is used to enable the Kaleido-Alto/Quad to key the detected mouse pointer

colors on video.<setKIcontrolMode>set mode="N"</setKIcontrolMode>

Where N is either 0 (color not keyed), or 1 (color key enabled).


setKMouseColorAAQ This command is used to set a color to key.

Notes


• The KMV-3901/3911, and Kaleido-IP do not yet support this command.

23

Gateway CommandssetKMouseColorB

<setKMouseColorA>set mouseColorA="FFBBGGRR"</setKMouseColorA>

Where FFBBGGRR is the hexadecimal triplet for mouseColorA prefixed with the hexadecimal value FF.

• BB represents the blue component.• GG represents the green component.• RR represents the red component.

For example FFFF00FF would set magenta as the key color.


setKMouseColorBAQ This command is used to set a color to key.

<setKMouseColorB>set mouseColorB="FFBBGGRR"</setKMouseColorB>

Where FFBBGGRR is the hexadecimal triplet for mouseColorB prefixed with the hexadecimal value FF.




setKMouseColorCAQ This command is used to set a color to key.

<setKMouseColorC>set mouseColorC="FFBBGGRR"</setKMouseColorC>

Where FFBBGGRR is the hexadecimal triplet for mouseColorC prefixed with the hexadecimal value FF.




24

A Typical Session

Here is a description of how to open and close a typical session during which you will use the Gateway commands to operate a Kaleido multiviewer. You can open concurrent sessions with multiple Kaleido systems; each session will have its own window on your desktop.

• If you are using a Kaleido-K2, make sure the internal gateway is turned ON, and the MT-gateway is turned OFF (see Remote Operation of a Multiviewer via TCP/IP, on page 1).

• If your environment includes a Grass Valley iControl Application Server, refer to the Application Server's user guide for a discussion of appropriate network configurations.

There is no limit to the number of commands that can be sent in a session, and it is recommended to keep a session open as long as there are commands to send, since opening a session takes a few seconds. Here is a simplified example of a session:

Open a session

send command

send command

…

send command

Close the session.

Opening an HyperTerminal SessionHyperTerminal is a Windows application that was typically installed on every Windows computer, up until Windows XP.2 This application can communicate with the machine on which the gateway is running using communications port 13000.

To open HyperTerminal from your PC or laptop• Windows XP and earlier: On the Start menu, point to All Programs, Accessories,

Communications, and then click HyperTerminal.• Windows 7 and later: Navigate to the folder where you installed the HyperTerminal files

(typically under C:\Program Files\Windows NT\HyperTerminal), and then open hypertrm.exe.

2. , A number of HyperTerminal replacement applications for Windows 7 and later are available (e.g. Hilgraeve’s HyperTerminal Private Edition). It is also possible to just copy the files that make up HyperTerminal, from a Windows XP computer, if you still have one available, or to download them from the Web. To install HyperTerminal on Windows 7, copy hypertrm.exe, and htrn_jis.dll from C:\Program Files\Windows NT\, and hypertrm.dll, and hticons.dll, from C:\Windows\System32\, from Windows XP to a folder in your Windows 7 file system (e.g., C:\Program Files\Windows NT\HyperTerminal).

25

A Typical SessionOpening an HyperTerminal Session

To establish the HyperTerminal session with the multiviewer1 In Connection Description, type a name for the connection, select an icon from the list,

and then click OK.

The Connect To window appears.2 In Connect To, select TCP/IP (Winsock), from the Connect using list.

Two new boxes appear in the window.3 In Host address, type the IP address of the multiviewer system.4 In Port number, type 13000. This indicates that the connection to the Kaleido will be

established via port 13000.

26


5 Click OK.

To be able to see the characters you type in the HyperTerminal console1 On the File menu, click Properties.

The [connection name] Properties window appears.2 Click the Settings tab.

3 On the Settings tab, click ASCII Setup.The ASCII Setup window appears.

4 In ASCII Setup, select the Echo typed characters locally check box.

5 Click OK to close ASCII Setup, and then click OK again to close the Properties window.The next characters you type will appear in the console. Commands can now be sent to the Gateway, while the session remains open.

27

A Typical SessionOpening a Gateway Session With a Multiviewer

Opening a Gateway Session With a MultiviewerTo open a Gateway session with a multiviewer

1 Enter the openID command using the IP address of the multiviewer with which the connection has to be established.

2 If the Gateway receives the command and recognizes it, it will respond with the following:

3 If the command cannot be recognized the following message will appear:The multiviewer is ready to receive commands.

Sending Commands to the GatewayTo send a command

• Type it in the console, and then press the Enter key.

Closing a Gateway SessionTo close the Gateway session

1 Enter the closeID command, to close the link to the multiviewer.

2 To end the communication session, click the Disconnect button on the toolbar.

28

Kaleido-X Series Support History

For each Kaleido Remote Control Protocol (Gateway) command, the following table indicates, for each Kaleido-X series multiviewer model, the version number of the Kaleido-X Software that first supported the command.

Command Kaleido-X Kaleido-X16 KMV-3911a Kaleido-IP Kaleido-MXb

openID 1.00 4.10 5.00 6.00 7.00

closeID 1.00 4.10 5.00 6.00 7.00

getParameterInfo 4.00 4.10 5.00 6.00 7.00

getKCurrentLayout 1.00 4.10 5.00 6.00 7.00

setKCurrentLayout 1.00 4.10 5.00 6.00 7.00

getKLayoutList 1.00 4.10 5.00 6.00 7.00

getKRoom 4.00 4.10 5.00 6.00 7.00

getKRoomList 4.00 4.10 5.00 6.00 7.00

setKStatusMessage 4.00 4.10 5.00 6.00 7.00

setKUnlatch 4.00 4.10 5.00 6.00 7.00

getKChannel — — — 6.00 —

setKChannel 1.00 4.10 5.00 6.00 7.00

setKDynamicText 1.00 4.10 5.00 6.00 7.00

getKDynamicText 4.00 4.10 5.00 6.00 7.00

getKMetaData N.A. N.A. N.A. N.A. N.A.

setKTimer 3.00 4.10 5.00 6.00 7.00

setKTimer2 3.00 4.10 5.00 6.00 7.00

setKTimerTrigger 3.00 4.10 5.00 6.00 7.00

setKFireAction 3.00 4.10 5.00 6.00 7.00

getKActionList 5.00 5.00 5.00 6.00 7.00

setKEnableAlarmGroup 5.10 5.10 5.10 6.00 7.00

setKDisableAlarmGroup 5.10 5.10 5.10 6.00 7.00

setKSaveLayout N.A. N.A. N.A. N.A. N.A.

getKAudioOut 2.00 4.10 — — 7.00

setKAudioOut 2.00 4.10 — — 7.00

getKAudioOutVolume 3.00 4.10 — — 7.00

setKAudioOutVolume 3.00 4.10 — — 7.00

29

Kaleido-X Series Support History

getKAudioOutMode 3.00 4.10 — — 7.00

setKAudioOutMode 3.00 4.10 — — 7.00

setKVerticalOffset N.A. N.A. N.A. N.A. N.A.

setKIcontrolMode N.A. N.A. N.A. N.A. N.A.

setKMouseColorA N.A. N.A. N.A. N.A. N.A.

setKMouseColorB N.A. N.A. N.A. N.A. N.A.

setKMouseColorC N.A. N.A. N.A. N.A. N.A.

a. Also KMV-3901, and Kaleido-XQUAD.b.Also Kaleido-MX 4K and Kaleido-Modular-X.

Command Kaleido-X Kaleido-X16 KMV-3911a Kaleido-IP Kaleido-MXb

30

Contact Us

Grass Valley Technical SupportFor technical assistance, contact our international support center, at 1-800-547-8949 (US and Canada) or +1 530 478 4148.

To obtain a local phone number for the support center nearest you, please consult the Contact Us section of Grass Valley’s website (www.grassvalley.com).

An online form for e-mail contact is also available from the website.

Corporate Head OfficeGrass Valley3499 Douglas-B.-FloreaniSt-Laurent, Quebec H4S 2C6CanadaTelephone: +1 514 333 1772Fax: +1 514 333 9828www.grassvalley.com

Documents

Kaleido Remote Control Protocol (Gateway) User’s Guide€¦ · To disable the Kaleido-K2 MT-Gateway 1 On the Kaleido-K2, display the desktop (use the desktop icon on the menu bar)