Cisco TelePresence MX300G2 User manual

D15358.01 APRIL 2016
Collaboration Endpoint software
version 8.1
© 2016 Cisco Systems, Inc.
All rights reserved.
1
D15358.01 APRIL 2016
Collaboration Endpoint software
version 8.1
© 2016 Cisco Systems, Inc.
All rights reserved.
In-Room Control
on Touch10
User Interface Extensions
Cisco TelePresence
MX200 G2, MX300G2, MX700, MX800,
SX10, SX20, SX80
CE8.1
APRIL 2016
Table of contents
Introduction
Create a user interface
API for in-room control
Widgets
Command reference
Troubleshooting
Tips and tricks
Examples
Table of contents
Introduction
Create a user interface
API for in-room control
Widgets
Command reference
Troubleshooting
Tips and tricks
Examples

D15358.01 APRIL 2016
Collaboration Endpoint software
version 8.1
© 2016 Cisco Systems, Inc.
All rights reserved.
2
Table of contents
Introduction .....................................................................................................4
Definition of terms.........................................................................................4
In-room controls ...........................................................................................5
Create a user interface for the Touch 10 .........................................................7
Launch the in-room control editor.................................................................8
Create the in-room control panel ..................................................................9
API for programming in-room controls ..........................................................14
Connect to the video system ......................................................................14
Communicate over the API .........................................................................15
Widgets.........................................................................................................20
The widget identifier ...................................................................................20
Toggle button ..............................................................................................21
Slider ..........................................................................................................22
Spinner .......................................................................................................23
Button with custom text ..............................................................................24
Button with symbol .....................................................................................25
Group button...............................................................................................26
Text box ......................................................................................................27
Command reference .....................................................................................29
Events ........................................................................................................ 30
Commands .................................................................................................32
Statuses..................................................................................................... 33
Troubleshooting............................................................................................ 35
Development tools on the web interface.................................................... 35
Tips and tricks .............................................................................................. 38
Examples.......................................................................................................41
How to use this guide
The left menu bar and the entries in the table of contents are all
hyperlinks. You can click on them to go to the topic.
Product documentation
User guides and compliance and safety information
for Cisco TelePresence systems are available at
http://www.cisco.com/go/telepresence/docs
We recommend that you visit the Cisco web site regularly for
updated versions of this guide.
Table of contents
Introduction
Create a user interface
API for in-room control
Widgets
Command reference
Troubleshooting
Tips and tricks
Examples
Table of contents

D15358.01 APRIL 2016
Collaboration Endpoint software
version 8.1
© 2016 Cisco Systems, Inc.
All rights reserved.
3
Introduction
Table of contents
Introduction
Create a user interface
API for in-room control
Widgets
Command reference
Troubleshooting
Tips and tricks
Examples
IntroductionIntroduction

D15358.01 APRIL 2016
Collaboration Endpoint software
version 8.1
© 2016 Cisco Systems, Inc.
All rights reserved.
4
Introduction
With In-Room Control you can add custom elements to our Touch10 user
interface. Such user interface extensions may be controls for lights or blinds, or
other peripherals controlled by external control systems.
Since both the Cisco video system and the other peripherals are controlled from
the Touch 10 user interface, you get a consistent user experience throughout
the meeting room.
The in-room control feature is available for the SX Series and MX Series video
systems running Collaboration Endpoint Software, version CE8.1 or later.
Definition of terms
Video system - Video system or codec in the Cisco TelePresence MXSeries
or SXSeries that runs Collaboration Endpoint Software, version CE8.1 or later.
Sometimes referred to as video device.
Control system - Third-party control system with hardware drivers for
peripherals, for example Crestron, AMX, Apple HomeKit, or Android.
Touch10 - Out touch-based control device for the MXSeries and SXSeries
video systems. Full product name: Cisco TelePresence Touch10. Also known as
Touch10 controller, or Touch10 user interface.
In-room control panel - Panel with controls for third-party peripherals in the
room. The panel opens when you tap the in-room control icon in the status bar
on Touch10. Refer to the Create a user interface chapter.
In-room control editor - Our easy to use drag-and-drop editor for making in-
room control panels.
xAPI - The bi-directional API of the video system. The xAPI allows third-party
applications to interface with and interact with the video system, and vice versa.
Widget - User interface element, for example buttons, sliders, and text fields,
that you can use to build an in-room control panel for Touch 10.
Table of contents
Introduction
Create a user interface
API for in-room control
Widgets
Command reference
Troubleshooting
Tips and tricks
Examples
Introduction

D15358.01 APRIL 2016
Collaboration Endpoint software
version 8.1
© 2016 Cisco Systems, Inc.
All rights reserved.
5
In-room controls
Example of an in-room control panel on Touch 10
In-room control panel
In-room control icon
(entry icon)
You can customize our Touch10 user interface to allow control of peripherals in
a meeting room, for example lights and blinds.
You need a Cisco video system with a Touch10 user interface, and a third-
party control system, for example Crestron, AMX, Apple HomeKit, or Android.
The video system's API, referred to as the xAPI, is the link between the video
system and the control system. Use the events and commands exposed by the
xAPI when you program the control system.
The simple drag-and-drop in-room control editor offers a library of user
interface elements, referred to as widgets. You can use these widgets to create
your own in-room control panel for the Touch10 user interface.
Together, all of this allows for the powerful combination of the control system's
functionality and the user-friendly Touch10 user interface.
In-room control schematics
Video system
Blinds
Climate
Lights
Other...
Touch10
In-room
control
editor
xAPI
Control system
Table of contents
Introduction
Create a user interface
API for in-room control
Widgets
Command reference
Troubleshooting
Tips and tricks
Examples
Introduction

D15358.01 APRIL 2016
Collaboration Endpoint software
version 8.1
© 2016 Cisco Systems, Inc.
All rights reserved.
6
Create a user interface
Use the in-room control editor to create the user interface
and to apply it to the video system
Table of contents
Introduction
Create a user interface
API for in-room control
Widgets
Command reference
Troubleshooting
Tips and tricks
Examples
Create a user interfaceCreate a user interface

D15358.01 APRIL 2016
Collaboration Endpoint software
version 8.1
© 2016 Cisco Systems, Inc.
All rights reserved.
7
Create a user interface for the Touch 10
Offline
There are two places from which you can download the offline editor:
• Download from http://www.cisco.com/go/in-room-control-docs
• Or, sign in to a video system's web interface with administrator credentials,
navigate to Integration > In-Room Control, and click Download Editor.
Extract the files from the downloaded zip-file. Keep the folder structure as is.
With the offline editor you have to work with files, rather than communicating
directly with the video system and Touch10. Apart from this, the offline editor
has full functionality.
The editor that you launch from the video system's web interface and the offline
editor share the same file format, so files created in one version can be opened
and modified in the other.
Offline in-room control editor
Export new
in-room control
panel to file
Import an
in-room control
panel from file Offline
in-room
control
editor
Use our in-room control editor to create customized panels for peripheral
controls on the video system’s Touch10 user interface.
Connected to video system
If you have access to the video system, you can launch the editor from the
video system's web interface. Then you have immediate access to the video
system and its Touch10 user interface.
If there is already an in-room control panel on the Touch10, it will automatically
load into the editor, and you can use it as a starting point for your design.
When you push a new panel to the video system, you will immediately see the
result on the Touch10.
In-room control editor launched from the video system's web interface
Video system
Touch10
Push new in-room control
panel to video system
Import existing in-room control
panel from video system
In-room
control
editor
Export new
in-room control
panel to file
Import an
in-room control
panel from file
Table of contents
Introduction
Create a user interface
API for in-room control
Widgets
Command reference
Troubleshooting
Tips and tricks
Examples
Create a user interface

D15358.01 APRIL 2016
Collaboration Endpoint software
version 8.1
© 2016 Cisco Systems, Inc.
All rights reserved.
8
Launch the in-room control editor
Sign in to the video system's web interface with administrator credentials,
navigate to Integration > In-Room Control, and click Launch Editor.
If there is an in-room control panel on the video system already, it will
automatically load into the editor.
Offline version
If you are using the offline version of the editor, open the index.html file that you
find in the rceditor folder.
Create a new panel
Import the current panel from the
video system (codec), or import a
panel that has been exported to a
file on an earlier occasion
Export your panel to the video
system (codec), or export it to a
file that can be imported back into
the editor at a later stage
Choose an in-room control icon;
delete the panel from the video
system (codec)
Tutorial on how to use the editor
Link to online guides
Widget library
The in-room control editor
Table of contents
Introduction
Create a user interface
API for in-room control
Widgets
Command reference
Troubleshooting
Tips and tricks
Examples
Create a user interface

D15358.01 APRIL 2016
Collaboration Endpoint software
version 8.1
© 2016 Cisco Systems, Inc.
All rights reserved.
9
Create the in-room control panel
Start the design of the in-room control panel
If an in-room control panel was not automatically loaded when you launced the
editor, choose one of these alternatives:
• New creates a blank in-room control panel in the editor.
• Import> From file loads an in-room control panel, which has been exported
to a local file on an earlier occasion, into the editor.
• Import> From codec loads the current in-room control panel from the video
system into the editor. Not available in the offline editor.
All alternatives erase any unsaved data in the editor, but the existing in-room
control panel on the video system is neither overwritten nor deleted until a new
panel is exported to the video system.
Start or continue the design of an in-room control panel
Table of contents
Introduction
Create a user interface
API for in-room control
Widgets
Command reference
Troubleshooting
Tips and tricks
Examples
Create a user interface

D15358.01 APRIL 2016
Collaboration Endpoint software
version 8.1
© 2016 Cisco Systems, Inc.
All rights reserved.
10
Design the in-room control panel
What you see in the editor's design panel is similar to how the in-room control
panel will appear on the Touch10.
An in-room control panel is arranged in pages, which will appear as separate
tabs in the in-room control panel on Touch 10. Each page consists of one
or more rows, which you can populate with text and user interface elements
known as widgets.
Widgets are arranged in a four-column grid. The widgets are placed into the
grid according to the following rules:
• A widget fills between one and four columns depending on its size.
• A row is populated from right to left.
• If you add more widgets than fits in one line, widgets wrap to a new line
within the same row.
How you use the user interface elements for your meeting room is up to you.
You can, for example, create panels with preset buttons for lights and blinds, or
support for more complex scenarios such as controls for many microphones
in a large meeting room. You can find some examples for inspiration in the
Examples chapter.
Refer to the next page on how to create the panel.
The in-room control editor. Widgets from the widget library are placed in a four-column grid.
Design panel
Widget library
Four-column grid
Buttons with familiar
symbols like home,
power, arrows, camera
and loudspeaker controls,
media player controls
Buttons with custom text,
group buttons, toggle
button, sliders, spinners,
and other elements
Table of contents
Introduction
Create a user interface
API for in-room control
Widgets
Command reference
Troubleshooting
Tips and tricks
Examples
Create a user interface

D15358.01 APRIL 2016
Collaboration Endpoint software
version 8.1
© 2016 Cisco Systems, Inc.
All rights reserved.
11
1Give the page a name
Click the page text, and enter a name.
2Give the row a name
Click the row text, and enter a name.
3Add widgets from the library
Drag and drop as many widgets as you need
from the widget library onto a row.
4Enter custom text on widgets
Click the dummy-text on a button, group
button, or text field, and enter the appropriate
text.
5Define unique identifiers
Click the widget, and type unique identifiers in
the input fields that pops up below the design
panel. You can either use the pre-assigned
identifiers or define your own.
All widgets have a unique WidgetID. Only
Group buttons have GroupIDs.
Read more about the identifiers in the Widgets
chapter.
6Add more rows
Click +to add a new row.
Repeat steps 2-5 for each row.
7Add more pages
Click +to add a new page.
Repeat steps 1-6 for each page.
8Choose an in-room control icon
Click Settings in the menu, and choose an in-
room control icon (entry icon).
The in-room control icon appears in the status
bar on Touch10. When you tap the icon, the
in-room control panel opens.
Re-arrange elements
Drag a page, row, or widget, and drop it in its new
position. Drop it outside the design panel to delete it.
8
1
2
3
6
74
5
Table of contents
Introduction
Create a user interface
API for in-room control
Widgets
Command reference
Troubleshooting
Tips and tricks
Examples
Create a user interface

D15358.01 APRIL 2016
Collaboration Endpoint software
version 8.1
© 2016 Cisco Systems, Inc.
All rights reserved.
12
Apply the in-room control panel to the video system
(Not available when using the offline editor. Instead, you should export the in-
room control panel to a file in order to save your work for later.)
Apply the in-room control panel to the video system. You will see the results
immediately on the Touch10.
• Choose Export > To codec
Check the result on Touch10
(Not available when using the offline editor.)
Tap the in-room control icon (light bulb or generic utility icon) in the Touch10
status bar to open the in-room control panel.
In-room control icon
Which in-room control icon to display is defined under Settings in the editor. If
you change to the other icon, you have to export the in-room control panel to
the video system again.
Export the in-room control panel to file
Export the in-room control panel to a file, which can be imported back into the
editor at a later stage.
• Choose Export > To file
If you are using the offline editor, this is the only way you can save your work for
later.
Exporting to file may also be useful as a way of creating a design template if you
are going to push the same in-room control panel to multiple video systems.
Files exported while connected to a video system are in the same format as
files exported from an offline editor. This means that any of these files can be
imported into an editor launched from a video system's web interface, and then
pushed to the video system's Touch10.
Table of contents
Introduction
Create a user interface
API for in-room control
Widgets
Command reference
Troubleshooting
Tips and tricks
Examples
Create a user interface

D15358.01 APRIL 2016
Collaboration Endpoint software
version 8.1
© 2016 Cisco Systems, Inc.
All rights reserved.
13
API for in-room control
Table of contents
Introduction
Create a user interface
API for in-room control
Widgets
Command reference
Troubleshooting
Tips and tricks
Examples
API for in-room controlAPI for in-room control

D15358.01 APRIL 2016
Collaboration Endpoint software
version 8.1
© 2016 Cisco Systems, Inc.
All rights reserved.
14
API for programming in-room controls
Connect to the video system
The video system's API (also known as the xAPI) allows bi-directional
communication with third-party control systems, such as those from AMX or
Crestron. There are multiple ways to access the xAPI:
• Telnet
• SSH
• HTTP/HTTPS
• Ethernet port
• RS-232 / serial connection
Regardless of the method you choose, the structure of the xAPI is the same.
Choose the access method that suits your application and video system the
best.
Consult the API guide for your video system for a full description of available
access methods and how to use the xAPI. Go to
http://www.cisco.com/go/sx-docs for SX Series, or
http://www.cisco.com/go/mx-docs for MX Series
Then, click Reference Guides > Command References to find the API guides.
Table of contents
Introduction
Create a user interface
API for in-room control
Widgets
Command reference
Troubleshooting
Tips and tricks
Examples
API for in-room control

D15358.01 APRIL 2016
Collaboration Endpoint software
version 8.1
© 2016 Cisco Systems, Inc.
All rights reserved.
15
Communicate over the API
The video system and the control system exchange messages through the xAPI
to make sure that the Touch10 in-room control panel truly reflects the status of
the room.
The video system sends one or more events when someone uses one of the
controls on the Touch10 in-room control panel, and the control system should
send a command to the video system when there is a change in the room.
The video system and the control system exchange messages through the xAPI.
xAPI
Commands
Events
Video system
Touch10
Control system
Examples:
• When someone taps a Lights On button on Touch10, the video system
sends the associated events. The control system should respond to these
events by switching on the lights in the room and send the corresponding
command back to the video system.
• When someone switch on the lights in the room, the control system should
send a command to the video system, so that the video system can update
the Touch10 in-room control panel to reflect that the light is on.
Consult the Command reference chapter for an overview of all relevant events,
commands and statuses for in-room control.
Table of contents
Introduction
Create a user interface
API for in-room control
Widgets
Command reference
Troubleshooting
Tips and tricks
Examples
API for in-room control

D15358.01 APRIL 2016
Collaboration Endpoint software
version 8.1
© 2016 Cisco Systems, Inc.
All rights reserved.
16
Events for widget actions
The video system sends one or more of the following events when someone
uses the controls on the Touch10 in-room control panel:
• Pressed - sent when a widget is first pressed
• Changed - sent when changing a widget's value
(applies only to toggle buttons and sliders)
• Released - sent when a widget is released
(also when moving out of the widget before releasing)
• Clicked - sent when a widget is clicked
(pressed and released without moving out of the widget)
These events are sent in two versions.
• UserInterface Extensions Event - suited for terminal output mode
• UserInterface Extensions Widget - suited for XML output mode
Refer to the table below to find out which version is best suited for your control
system to register to.
When, and by which widgets (user interface elements), these events are
triggered, are described in the Widgets chapter.
UserInterface Extensions Event (suited for terminal output mode) UserInterface Extensions Widget (suited for XML output mode)
One single string contains information about the type of action, which widget
triggered the event (identified by the WidgetID), and the widget value.
The type of action, which widget triggered the event (identified by the
WidgetID), and the widget value are included as separate elements in the
XML tree.
How to register:
xfeedback register event/UserInterface/Extensions/Event
How to register:
xfeedback register event/UserInterface/Extensions/Widget
Example:
*e UserInterface Extensions Event Pressed Signal: "WidgetId:Value"
** end
*e UserInterface Extensions Event Changed Signal: "WidgetId:Value"
** end
*e UserInterface Extensions Event Released Signal: "WidgetId:Value"
** end
*e UserInterface Extensions Event Clicked Signal: "WidgetId:Value"
** end
Example:
<Event>
<UserInterface item="1">
<Extensions item="1">
<Widget item="1">
<Action item="1">
<WidgetId item="1">WidgetId</WidgetId>
<Value item="1">Value</Value>
<Type item="1">Type</Type>
</Action>
</Widget>
</Extensions>
</UserInterface>
</Event>
Two event versions that a control system can register to: one suited for terminal output mode, the other for XML output mode
Type of action
Type of action
Table of contents
Introduction
Create a user interface
API for in-room control
Widgets
Command reference
Troubleshooting
Tips and tricks
Examples
API for in-room control

D15358.01 APRIL 2016
Collaboration Endpoint software
version 8.1
© 2016 Cisco Systems, Inc.
All rights reserved.
17
Event for panel update
The video system sends the following event when a new in-room control
panel is applied:
• LayoutUpdated - sent when a new in-room control panel for
Touch10 is exported to the video system
As a response to this event, the control system should send commands
to initialize all widgets so that they reflect the true status of the room.
How to register:
xfeedback register event/UserInterface/Extensions/Widget/
LayoutUpdated
Example:
Terminal output mode:
*e UserInterface Extensions Widget LayoutUpdated
** end
XML output mode:
<Event>
<UserInterface item="1">
<Extensions item="1">
<Widget item="1">
<LayoutUpdated item="1"/>
</Widget>
</Extensions>
</UserInterface>
</Event>
Table of contents
Introduction
Create a user interface
API for in-room control
Widgets
Command reference
Troubleshooting
Tips and tricks
Examples
API for in-room control

D15358.01 APRIL 2016
Collaboration Endpoint software
version 8.1
© 2016 Cisco Systems, Inc.
All rights reserved.
18
Commands and statuses
The SetValue command, which sets the value of a widget, is essential when
working with in-room controls:
xCommand UserInterface Extensions Widget SetValue Value: Value
WidgetId: WidgetId
When the video system receives a SetValue command, the video system's
status and the Touch10 in-room control panel are updated accordingly.
It is important that the control system sends
SetValue commands in the
following situations, so that the Touch10 in-room control panel truly reflects the
status of the room:
• When the control system initially connects to the video system.
• When the video system restarts.
• When the control system restarts.
• When a new in-room control panel is exported to the video system from the
in-room control editor (as response to the LayoutUpdated event).
• When someone physically changes something in the room, for example turns
on the lights using a wall control.
• As a response to an event, for example when someone has tapped the
Lights On button on the Touch10 in-room control panel.
The control system must also do all that is necessary in the room to reflect
the action on the Touch10 in-room control panel, for example switch on the
light.
Consult the Widgets chapter for more details about which commands apply to
the different widgets (user interface elements).
Examples
User
Control
system Lights
Video system
with Touch 10
Tap Lights On
Pressed and
Released events for
Lights On widget
Turn lights on
Set the value of the
Lights On widget to
active
The appearance of
the light widget has
changed to match
what the user can
see in the room
Message flow - turn on the lights using the controls on Touch 10
User
Control
system Lights
Video system
with Touch 10
Set the value of
the Lights On
widget to active
The appearance
of the light
widget has
changed to
match what the
user can see in
the room
User
Turn lights on
with wall control
Signal that lights
are on
Message flow - turn on the lights using the wall control
Table of contents
Introduction
Create a user interface
API for in-room control
Widgets
Command reference
Troubleshooting
Tips and tricks
Examples
API for in-room control

D15358.01 APRIL 2016
Collaboration Endpoint software
version 8.1
© 2016 Cisco Systems, Inc.
All rights reserved.
19
Widgets
Description of the user interface elements and
their associated events and commands
Table of contents
Introduction
Create a user interface
API for in-room control
Widgets
Command reference
Troubleshooting
Tips and tricks
Examples
WidgetsWidgets

D15358.01 APRIL 2016
Collaboration Endpoint software
version 8.1
© 2016 Cisco Systems, Inc.
All rights reserved.
20
The widget identifier
All widgets on a Touch10 in-room control panel need a unique identifier,
a WidgetID. The WidgetID may either be defined by you, or assigned
automatically. The WidgetID can be any name or number; we recommend
using a descriptive name without special characters. The maximum number of
characters is 40.
The WidgetID is the programming link between Touch10, the video system,
and the control system. The WidgetID will be included in all events that are
associated with a widget, and you must use the same identifier when you send
commands to that widget via the code that you write for your control system.
Group identifiers
One of the widgets, the Group button, has two types of identifiers: The
WidgetID refers to the complete group of buttons, while GroupIDs are unique
identifiers for the individual buttons within the group.
Option 1 Option 2 Option 3
Widget_ID_groupbutton
Group_ID_one Group_ID_two Group_ID_three
A GroupID is assigned automatically, but can be defined by you instead. A
GroupID can be any name or number; we recommend using a descriptive
name without special characters. The maximum number of characters is 255.
Widgets
The Touch10 in-room control panel is composed of user interface elements
called widgets. You can find the complete widget library in the right pane of the
in-room control editor.
• General tab: Buttons with custom text, group buttons, toggle button, sliders,
text fields and more.
• Icons tab: Buttons with familiar symbols for Home, Power, Arrow up/down/
left/right, Camera controls, Loudspeaker controls, Microphone control, Media
player controls, and more.
The content of the next few pages describes each widget type, with emphasis
on:
• Commands that change the value of the widget
• Events that are sent (pressed, changed, released, clicked) and which actions
trigger these events
• Examples of commands and events, both in terminal output mode and XML
output mode
Syntax and semantics for all events, commands and statuses that are
related to in-room controls (user interface extensions) are included in the
Commandreference chapter.
Table of contents
Introduction
Create a user interface
API for in-room control
Widgets
Command reference
Troubleshooting
Tips and tricks
Examples
Widgets