11
D1535805 User Guide In-Room Control for Touch10. Produced June 2017 for CE9.0. © 2015–2017 Cisco Systems, Inc. All rights reserved
API for Programming In-Room Controls
API
Connect to the Video System
The video system’s API (also known as the xAPI) allows
bidirectional 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 to get 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
Then, click
Reference Guides
>
Command References
to find the
API guides.
Communicate over the API
The video system and the control system exchange messages
through the xAPI to make sure that the Touch10/DX In-Room
Control panel always reflects the actual status of the room.
The video system sends one or more events when someone
uses one of the controls on the Touch10/DX In-Room Control
panel, and the control system should send a command to the
video system when there is a change in the room settings.
Video system
xAPI
Control system
Touch 10
Commands
Events
The video system and the control system exchange messages
through the xAPI.
Examples:
•
When someone taps a
Lights On
button on Touch10/DX, 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 Touch10/DX In-Room Control
panel to reflect that the light is on.
See the Command reference chapter for an overview of all
relevant events, commands and statuses for in-room control.
Pairing Video System and Control System
You can register the control system as a peripheral connected to
the video system:
xCommand Peripherals Connect ID: “ID” Type: ControlSystem
where ID is the unique ID for the control system, typically the
MAC address.
See the API guide for more details about this command, and its
options.
Heartbeats.
The control system must send heartbeats to the
video system to let the video system know that the control
system is connected. The control system stays on the connected
devices list (refer to xStatus Peripherals ConnectedDevice) as
long as the video system receives these heartbeats from the
control system.
xCommand Peripherals HeartBeat ID: “ID” [Timeout: Timeout]
where ID is the unique ID for the control system, typically the
MAC address, and Timeout is the number of seconds between
each heartbeat. If Timeout is unspecified, it is assumed to be 60
seconds.
Note.
If a connected unit ceases to send heartbeats, some
time will elapse until the video system detects the absence of
heartbeats — as long as up to a couple of minutes.
This works the other way around as well, up to a couple of
minutes may elapse until new heartbeats are detected by the
codec.
