User's Guide | Miranda Kaleido-K2 User`s guide

Kaleido Remote Control

Protocol (Gateway)

User’s Guide

M770-0900-114

Multi-Image

Display

Processor

Copyright 2011 Miranda Technologies Inc.

Specifications may be subject to change

Printed in Canada

May 2011

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

1.3.1

Gateway Options for the Kaleido-K2 ........................................................................................... 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 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 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 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/Quad-

Dual, 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:

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

1.2 Remote Operation of the Kaleido-X Series or Kaleido-

Alto/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 KaleidoK2’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 KaleidoK2’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 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.

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.


USER’S GUIDE

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:

Code System Multi-Viewer Models

KX

K2

AQ

Kaleido-X Software

Kaleido-K2 Software

Kaleido-Alto/Quad/Quad-Dual

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

Kaleido-K2

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

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

Command Applies to Description openID closeID

KX

KX

K2

K2

AQ

AQ

Opens a session with the specified Kaleido

Closes a previously opened session getParameterInfo getKCurrentLayout setKCurrentLayout getKLayoutList getKRoom

KX

KX

KX

KX

KX

K2

K2

K2

AQ

AQ

AQ

Gets the system name, or its software version

Gets the name of the current layout

Loads a specific layout

Gets the list of available layouts

Gets information on how the heads are positioned within the specified room getKRoomList setKStatusMessage setKUnlatch setKChannel

KX

KX K2 AQ

Gets the list of available rooms

Sets a Gateway alarm to the specified state

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

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

Page

6

7

8

13

8

9

9

10

12

12

13


USER’S GUIDE

Command setKDynamicText getKDynamicText getKMetaData setKTimer setKTimer2 setKTimerTrigger setKFireAction

Applies to Description

KX K2 AQ Sends text to the specified layout element

KX

K2

Retrieves text from the specified layout element

Gets metadata from a MultiData component

Page

14

14

15

KX K2 AQ Configures the specified countdown timer

KX K2 Configures the specified timer

KX K2 AQ Starts, stops or resets a countdown timer

KX K2 AQ Fires the specified action

16

16

17

18

getKActionList setKEnableAlarmGroup

KX

KX K2

Gets the list of available actions

Enables an alarm group setKDisableAlarmGroup KX K2 setKSaveLayout K2 AQ

Disables an alarm group

Saves the current layout getKAudioOut setKAudioOut getKAudioOutVolume setKAudioOutVolume getKAudioOutMode setKAudioOutMode

KX

KX

KX

KX

K2

K2

K2

K2

AQ

AQ

AQ

AQ

Identifies the current audio output

Selects the audio to be monitored

Gets the current audio monitoring output mode

Sets the audio monitoring output mode

19

20

KX K2 AQ Gets the current audio monitoring output volume

22

KX K2 AQ Sets the volume of the audio monitoring output

22

22

23

18

18

19

19

setKVerticalOffset setKIcontrolMode

AQ

AQ

Offsets the graphic from display

Enables/Disables mouse color keying over video

23

23

setKMouseColorA setKMouseColorB setKMouseColorC

AQ Sets the mouse color to be keyed over the video

24


24


25


USER’S GUIDE

2.2 Document Conventions

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

[Command Name]

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.

[Applicable Kaleido Systems]

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:

<openID/>

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>


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:



USER’S GUIDE

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

Note: This command closes the current connection to the client via 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.

getParameterInfo KX

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="4.XX-build.102"</kParameterInfo>

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>

KX K2 AQ getKCurrentLayout

This command retrieves the name of the current layout.

<getKCurrentLayout/>

Gateway response:

For a Kaleido-Alto/Quad/Quad-Dual multi-viewer:

 <kCurrentLayout>Currentlayout.xml</kCurrentLayout>

For a Kaleido-K2 or a Kaleido-X series multi-viewer:


USER’S GUIDE

 <kCurrentLayout>name="CurrentLayout.kg2"</kCurrentLayout>


Where CurrentLayout.kg2 is the name of the Layout currently in use by the Kaleido-K2 or

Kaleido-X series multi-viewer. For a Kaleido-Alto/Quad/QuadDual, the layout suffix is ―.xml‖ instead of ―.kg2‖.

Note: On a Kaleido-X series multi-viewer, 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/>.

setKCurrentLayout KX K2 AQ

This command loads the specified layout.

<setKCurrentLayout>set LayoutToLoad.kg2</setKCurrentLayout>

Where LayoutToLoad is the name of the layout to load.

Notes:





This Layout must have been exported to the Kaleido prior to executing this command.

You can use the getKLayoutList command to retrieve 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 multi-viewer, if the session does not have a room context, the layout name must be prefixed with the room name and a ―/‖.

Ex: <setKCurrentLayout>set Room1/Layout1.kg2</setKCurrentLayout>

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.

getKLayoutList

This command returns the list of layouts that can be used on the Kaleido.

<getKLayoutList/>

KX K2 AQ

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 Kaleido system.


USER’S GUIDE


Notes:



For a Kaleido-X series multi-viewer, if the session does not have a room context, the layout names will be prefixed with the room name and a ―/‖. If the session has a room

 context, only layouts for that room will be returned and the layout names won't be prefixed with the room name.

Example:

<kLayoutList>Room1/MAIN.kg2 Room1/BACKUP1.kg2

Room2/MAIN.kg2</kLayoutList>

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

―.kg2‖.

getKRoom KX

This command is used to obtain information on how the heads are positioned relative 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:Ana log%20AES%20Audio%20Out"/>

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

86c6-b5c2f6a72665"/>

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


USER’S GUIDE

<preference editable="true" editablePerUser="true" type="Preset" uid="MultiHeadLayoutBean.9" value="miranda.data.access:MultiHeadLayoutBean/5a475f81-df1b-11dca920-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="9016b92bcdbe-11db-ae68-a122768fdba0" rotated="false" rotation="normal" slotNumber="10">

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

...

</head>

...

</heads>

</room>



USER’S GUIDE

getKRoomList

This command is used to obtain the list of rooms known to your multi-viewer system.

<getKRoomList/>

Gateway response:

 <kRoomList><room>Room A</room><room>Room B</room></kRoomList>


KX setKStatusMessage KX K2 AQ

This command associates an Alarm state with an ID. The Kaleido 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 the Kaleido.

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

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

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. o Status is any of the available statuses:

Status Alternate (legacy) status

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

DISABLE DISABLE

NORMAL OK

Disabled

Normal

Disabled

OK

MINOR WARNING

MAJOR MAJOR

Minor

Major

Warning

(not supported)

CRITICAL ERROR Critical Error o TheMessage is reserved for future use, and is ignored.

Gateway response:




USER’S GUIDE

KX setKUnlatch

This command is used to acknowledge the global alarm for a given source (channel). It can also be used to acknowledge specific alarms.

The command supports three parameter types: channelName, id or uri: o If channelName is specified, the global alarm associated with the specified source

(channel) will be acknowledged. o If uri is specified, the alarm with the specified URI will be acknowledged. o If id is specified then the gateway alarm with the specified ID will be acknowledged.

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

 <setKUnlatch>set channelName="ChannelName"</setKUnlatch>

 <setKUnlatch> set uri="AlarmURI"</setKUnlatch>

 <setKUnlatch>set id="AlarmName"</setKUnlatch>

Gateway response:



Examples: o <setKUnlatch>set channelName="/Input A/Channel 01"</setKUnlatch> o <setKUnlatch>set uri="miranda.monako.daq://local/data/master/3/card/av1/DTVCCData#dt vccService1Presence"</setKUnlatch> o <setKUnlatch>set id="my_gateway_alarm_1"</setKUnlatch>

setKChannel KX 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: o ChannelName is the name of the logical source you wish to assign to the specified monitor. On a Kaleido-X series multi-viewer this is the full path to the source (channel).

Ex.: /Input A/Channel 1. o MonitorNumber is the identifier of the monitor to which the source is to be assigned.

On a Kaleido-X series multi-viewer the monitor number must be prefixed with the room name and a ―/‖ if the session does not have a room context. Ex.:


USER’S GUIDE

Room1/composite42. The monitor name is available in the XEdit layout (Properties

> Assignments > Name).

Note: On the KaleidoK2, to get the monitors’ identifiers for your current layout press the Tab key on the keyboard, or the SELECT key on the RCP.

Gateway response:


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

setKDynamicText KX 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: o Address is the configured text address of the UMD or text label component.

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. o NewText is the text to display.

Gateway response:



getKDynamicText KX

This command is used to retrieve dynamic text previously sent to a multi-viewer by a third-party 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>



USER’S GUIDE

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

getKMetaData K2

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 bold type here) 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. o The response will be grouped by input, and the inputs sorted in ascending order (from input 1 to 32). o For each input, all the data will be presented as attributes. o The data legends will be mapped to valid XML attribute names, all of which are listed here: inputFormat

WSS scansys

AFD

AFD3Bits

AFDANC

SID programConfig dialogLevel networkName stationID channelNumber

TSID programName programType vChipRating programDescription programLength elapsedTime


USER’S GUIDE programID timeOfDay timeZone o The value field is escaped as defined in the XML protocol for an attribute value. o For instance, ABC"DEF\GHI<JKL>MNO/PQR&STU;VWX'YZ becomes ABC"DEF\GHI<JKL>MNO/PQR&STU;VWX'YZ o The attributes order is not guaranteed and may change for two consecutives calls to the same command.

 <nack/>: there is a syntax error in the XML command.

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.

setKTimer KX 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: o TimerID is the ID of the countdown timer component to modify. o

HH : MM : SS is the preset value for the countdown timer component. o Direction is the direction to count, either

UP

or

DOWN

. o Loop indicates if the counter must count continuously. This value can be either

ON or

OFF .

Gateway response:



setKTimer2 KX K2

This command is used to configure a timer in a Kaleido-K2 or Kaleido-X series multi-viewer system.

<setKTimer2>set TimerName="NAME" StartTime="HH:MM:SS:FF"

PresetTime="HH:MM:SS:FF" TimerMode="Timer mode" EndMode="End mode"

</setKTimer2>

Where:


USER’S GUIDE o 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. o 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 h our 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 should be counting or waiting to start when it compares the start time to the current time.

Note: The current implementation allows the user to specify frame values, but



 they are not used by the timer, which will start on the exact second.

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 . o 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.

Note: The current implementation allows the user to specify frame values, but they are not used by the timer, which will start on the exact second. o TimerMode is the operating mode of the timer. Possible values are:

UP , DOWN ,

REMAINING . o EndMode defines what is to happen when the timer reaches the end of its count.

Possible values are: LOOP , STOP , and OVERRUN .

Gateway response:



setKTimerTrigger KX 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: o TimerID is the ID of the countdown timer component to control. o Trigger is the action that the countdown timer must do. This value can either be

START ,

STOP or RESET .

Gateway response:




USER’S GUIDE

setKFireAction KX 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>

Where NameOfTheActionToFire is the Friendly name of the Action to be executed.

Notes:



For a Kaleido-X series multi-viewer, the Friendly name is specified under the Properties tab in XEdit.





The Action must have been exported to the multi-viewer in order to be executed.

On a Kaleido-X series multi-viewer, 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.

Gateway response:


 <nack/>: The Gateway was not able to recognize the command, or the command could not be executed.

Note: On a Kaleido-X series multi-viewer, 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/>.

getKActionList

This command is used to obtain the list of actions known to your multi-viewer system.

<getKActionList/>

Gateway response:

 <kActionList><action>Action1</action><action>Action2</action>

<action>Action3</action></kActionList>


KX setKEnableAlarmGroup KX 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 multi-viewer model) you wish to enable.

Note: In the case of a Kaleido-X Series multi-viewer model, this parameter can be the path/friendlyName of the virtual alarm or its URI.


USER’S GUIDE

Gateway response:



setKDisableAlarmGroup KX K2

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

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

Where NameOfTheGroupToDisable is the name of the alarm group (for a Kaleido-K2 multiviewer), or virtual alarm (for a Kaleido-X Series multi-viewer model) you wish to disable.

Note: In the case of a Kaleido-X Series multi-viewer model, this parameter can be the path/friendlyName of the virtual alarm or its URI. The virtual alarm will be set to OFFLINE.

Gateway response:



setKSaveLayout K2 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.

Note: 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.

getKAudioOut

This command allows the user to get the selected audio monitoring output.

<getKAudioOut/>

KX K2 AQ


USER’S GUIDE

Notes:



A session with user privileges must first be opened for this command to work on a

Kaleido-X or Kaleido-X16 multi-viewer.



This command is currently not supported on the KMV-3901/3911 models.

Returned value can be any of:

 <kAudioOut>DETAILS</kAudioOut>: The command was executed.

DETAILS will vary depending on the type of audio output detected.

When no audio output 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: o 999.999.999.999 is the IP address of the device from where the stream originates. o XX is the identifier of the feed to use.

For an audio card source, the returned value indicates which audio card input is being monitored:

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

Where 999 indicates the input from the card.

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: o AAA indicates the video input. o BB indicates the group. Valid values are from 1 to 4. o X indicates the AES. Valid value can be either 1 or 2.

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

setKAudioOut KX K2 AQ

The user can select the audio to be monitored by using this Gateway command. The syntax of the command will differ if the user indicates to monitor audio coming from a stream, from an audio card, from an embedded source or no audio at all. In general, you can select any audio source to be monitored, even if this source is not represented in an audio meter on the current layout.


USER’S GUIDE

Notes:



A session with user privileges must first be opened for this command to work on a

Kaleido-X or Kaleido-X16 multi-viewer.





This command is currently not supported on the KMV-3901/3911 models.

Streaming sources are not supported on the Kaleido-Alto/Quad/Quad-Dual.

<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: o 999.999.999.999 is the IP of the machine from where the stream occurs. o XX is the identifier of the feed to use.

To select an audio card source, format the command as follows:

<setKAudioOut>set Type="AUDIOCARD" Input="999"</setKAudioOut>

Where 999 indicates the input from the card.

To select an embedded source, format the command as follows:

<setKAudioOut>set Type="EMBEDDED" Input="AAA" Group="BB"

AES="X"</setKAudioOut>

Where: o AAA indicates the video input. o BB indicates the group. Valid values range from 1 to 4. o X indicates the AES. Valid 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.

Note: 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.


USER’S GUIDE



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.

getKAudioOutVolume KX K2 AQ

Note: This command is currently not supported on the KMV-3901/3911 models.

This command retrieves the audio monitoring volume currently used.

<getKAudioOutVolume/>

The returned value will have the form:

 <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 multi-viewer, 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 multi-viewers only.

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

setKAudioOutVolume


KX K2 AQ

This command sets the audio monitoring volume.

<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 multi-viewer, 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.

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

Returned value will be one of:

 <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.

getKAudioOutMode


This command retrieves the audio monitoring mode currently used.

KX K2 AQ


USER’S GUIDE

<getKAudioOutMode/>

Returned value will have the form:

 <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. In this case the audio monitoring mode remains unchanged.

setKAudioOutMode KX K2 AQ


To set the Audio Monitoring Mode 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.

Returned value will be any of:

 <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.

setKVerticalOffset AQ

This command is used to position the CPU’s graphic output vertically within the final DVI output on the display. The KaleidoAlto/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 line s (between 0 and 175) by which to offset the CPU’s graphic output, from the top of the final DVI output.

Gateway response:



setKIcontrolMode AQ

This command is used to enable the Kaleido-Alto/Quad to key the detected mouse pointer colors on video.


USER’S GUIDE

<setKIcontrolMode>set mode="N"</setKIcontrolMode>

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

Gateway response:



setKMouseColorA AQ

This command is used to set a color to key.

<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.

Gateway response:



setKMouseColorB AQ


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

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





Gateway response:


USER’S GUIDE



setKMouseColorC AQ


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

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





Gateway response:



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


USER’S GUIDE

3 A Typical Session

Here is a description of how to open and close a typical session during which you will use these commands to operate a Kaleido. You can open concurrent sessions with multiple Kaleido frames; 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 section 1.2).

 If your environment includes a Miranda iControl Application Server, see the Application Server’s manual for a discussion of appropriate network configurations.

Open the HyperTerminal software on another computer:

1. From the Start menu, point to All Programs > Accessories > Communications, and then click

HyperTerminal.

2. In Connection Description, type a name for the connection, and select an icon from the list.

3. In Connect To, select TCP/IP (Winsock) from the Connect using list.

Two new boxes appear in the window.

4. In Host address, type the IP address of the Kaleido frame.

5. In Port number , type ―13000‖. This indicates that the connection to the Kaleido will be established via port 13000.

6. Click OK.


USER’S GUIDE

To be able to see the characters you type in the HyperTerminal console:

1. On the File menu, click Properties.

The [connection name] Properties window appears.

2. On the Settings tab, click the ASCII Setup button.

3. Select the Echo typed characters locally check box.

4. Click OK to close ASCII Setup window, and then click OK again to close the Properties window.

The characters you type will appear in the console.


USER’S GUIDE

Commands can be sent to the Gateway while a session is open. To send a command, type it in the console and then press the Enter key.

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.

To open a session, enter the openID command using the IP address of the Kaleido with which the connection has to be established.

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

If the command cannot be recognized the following message will appear:

The Kaleido is now ready to receive commands.

When no more commands need to be sent to the Kaleido, close the link to the Kaleido using the closeID command.


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

USER’S GUIDE


USER’S GUIDE

4 Appendix: Kaleido-X Series Support History

For each Kaleido Remote Control Protocol (Gateway) command, the following table indicates, for each

Kaleido-X Series multi-viewer model, the version number of the Kaleido-X Software that first supported the command.

Command Kaleido-X Kaleido-X16 KMV-3901/3911 openID closeID getParameterInfo getKCurrentLayout setKCurrentLayout getKLayoutList getKRoom getKRoomList setKStatusMessage setKUnlatch setKChannel setKDynamicText getKDynamicText getKMetaData setKTimer setKTimer2 setKTimerTrigger setKFireAction

3.00

3.00 getKActionList 5.00 setKEnableAlarmGroup 5.10 setKDisableAlarmGroup 5.10 setKSaveLayout N.A.

4.00

N.A.

3.00

3.00

4.00

4.00

1.00

1.00

1.00

1.00

4.00

4.00

1.00

1.00

4.00

1.00

4.10

N.A.

4.10

4.10

4.10

4.10

4.10

4.10

4.10

4.10

4.10

4.10

4.10

4.10

4.10

4.10

4.10

4.10

5.00

5.10

5.10

N.A.

5.00

N.A.

5.00

5.00

5.00

5.00

5.00

5.00

5.00

5.00

5.00

5.00

5.00

5.00

5.00

5.00

5.00

5.00

5.00

5.10

5.10

N.A.


Command getKAudioOut setKAudioOut getKAudioOutVolume setKAudioOutVolume getKAudioOutMode setKAudioOutMode setKVerticalOffset setKIcontrolMode setKMouseColorA setKMouseColorB setKMouseColorC

N.A.

N.A.

N.A.

N.A.

3.00

3.00

3.00

N.A.

Kaleido-X

2.00

2.00

3.00

Kaleido-X16 KMV-3901/3911

4.10 —

4.10

4.10

—

—

4.10

4.10

4.10

—

—

—

N.A.

N.A.

N.A.

N.A.

N.A.

N.A.

N.A.

N.A.

N.A.

N.A.

USER’S GUIDE


Miranda Technical Support

For technical assistance, please contact the Miranda Technical Support center nearest you:

Americas

Office hours: 9:00 a.m. – 9:00 p.m. (EST)

Telephone:

Fax:

E-mail:

+1-800-224-7882

+1-514-335-1614

[email protected]

Europe, Middle East, Africa, UK

Office hours: 9:00 a.m. – 6:00 p.m. (GMT)

Telephone: +44 (0) 1491 820222

Fax:

E-mail:

+44 (0) 1491 820002

[email protected]

France

Office hours: 9:00 a.m. – 5:00 p.m. (GMT+1)

Telephone:

Fax:

E-mail:

+33 1 55 86 87 88

+33 1 55 86 00 29

[email protected]

Corporate Head Office

Asia

Office hours: 9:00 a.m. – 5:00 p.m. (GMT+8)

Telephone:

Fax:

E-mail:

+852-2539-6987

+852-2539-0804 [email protected]

China

Telephone:

E-mail:

+86-10-5873-1814

[email protected]

EMERGENCY After Hour (Global)

Toll Free (US and Canada):

Telephone:

+1-800-224-7882

+1-514-333-1772

Miranda Technologies Inc.

3499 Douglas-B.-Floreani, St-Laurent, Quebec, Canada H4S 2C6

Telephone:

Fax:

Web:

514-333-1772

514-333-9828

www.miranda.com

User's Guide | Miranda Kaleido-K2 User`s guide

Kaleido Remote Control

Protocol (Gateway)

User’s Guide

Multi-Image

Display

Processor

Kaleido Remote Control Protocol (Gateway)

Table of Contents

Kaleido Remote Control Protocol (Gateway)

1 Introduction

1.1 Software Versions

1.2 Remote Operation of the Kaleido-X Series or Kaleido-

Alto/Quad/Quad-Dual Multi-Viewers

1.3 Gateway Options for the Kaleido-K2

1.4 Remote Operation of the Kaleido-K2 via the Gateway

2 Gateway Commands

2.1 Index of Gateway Commands

2.2 Document Conventions

[Command Name]

[Applicable Kaleido Systems]

2.3 Gateway Command Descriptions

openID KX K2 AQ

closeID KX K2 AQ

getParameterInfo KX

KX K2 AQ getKCurrentLayout

setKCurrentLayout KX K2 AQ

getKLayoutList

KX K2 AQ

getKRoom KX

getKRoomList

KX setKStatusMessage KX K2 AQ

KX setKUnlatch

setKChannel KX K2 AQ

setKDynamicText KX K2 AQ

getKDynamicText KX

getKMetaData K2

setKTimer KX K2 AQ

setKTimer2 KX K2

setKTimerTrigger KX K2 AQ

setKFireAction KX K2 AQ

getKActionList

KX setKEnableAlarmGroup KX K2

setKDisableAlarmGroup KX K2

setKSaveLayout K2 AQ

getKAudioOut

KX K2 AQ

setKAudioOut KX K2 AQ

getKAudioOutVolume KX K2 AQ

setKAudioOutVolume

KX K2 AQ

getKAudioOutMode

KX K2 AQ

setKAudioOutMode KX K2 AQ

setKVerticalOffset AQ

setKIcontrolMode AQ

setKMouseColorA AQ

setKMouseColorB AQ

setKMouseColorC AQ

3 A Typical Session

4 Appendix: Kaleido-X Series Support History

Miranda Technical Support

For technical assistance, please contact the Miranda Technical Support center nearest you:

Americas

Europe, Middle East, Africa, UK

France

Corporate Head Office

Asia

China

EMERGENCY After Hour (Global)

Miranda Technologies Inc.

Related manuals

Miranda

Kaleido-K2

Alto

MAC 2.2

Kaleido-Solo

Miranda

KS-900

iControl