Cisco TelePresence MX700 and MX800
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus
Collaboration Endpoint Software 9.2
NOVEMBER 2017
API Reference Guide
Application Programming Interface (API)
Reference Guide
Cisco TelePresence MX700 and MX800
D15335.08 Cisco TelePresence MX700 and MX800 API Reference Guide CE9.2, NOVEMBER 2017.
Copyright © 2017 Cisco Systems, Inc. All rights reserved. 1
Cisco TelePresence MX700 and MX800
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus
The top menu bar and the entries in the table of contents are
all hyperlinks, just click on them to go to the topic.
We recommend you visit our web site regularly for updated
versions of the user documentation.
Go to:http://www.cisco.com/go/mx-docs
Table of ContentsWhat’s in this guide?
Introduction ........................................................................... 3
About this guide
Downloading the user documentation ................................. 4
What’s new in CE9.2
What’s new in CE9.1
What’s new in CE9.0
About the API
API fundamentals
Connecting to the API ........................................................22
Password ............................................................................22
SSH ....................................................................................22
Tel n et ..................................................................................22
HTTP/HTTPS ......................................................................22
RS-232 / serial connection ................................................23
User roles ...........................................................................23
API output
The output modes ..............................................................24
Using the command line
API commands ...................................................................25
Other commands................................................................25
Command line shortcuts ....................................................26
Searching ...........................................................................26
Value types and formats.....................................................26
Commands
Configurations
.................................................................................... 27
Status
Multiline commands
Synchronous API calls
...................................................................................30
Events
...................................................................... 4
............................................................... 5
............................................................. 12
............................................................. 16
...................................................................... 21
.................................................................. 22
.............................................................................24
....................................................... 25
............................................................................27
....................................................................... 27
.............................................................. 28
..........................................................29
API Reference Guide
Feedback mechanism
Feedback expressions ....................................................... 31
Terminal connections .........................................................32
HTTP XMLAPI Authentication .............................................33
HTTP XMLAPI Session Authentication ...............................33
Getting status and configurations ...................................... 34
Sending commands and configurations .............................34
Feedback from codec over HTTP
Registering for feedback ....................................................35
Translating from terminal mode to XML .............................36
Dos and don’ts
xConfiguration commands
Description of the xConfiguration commands
xCommand commands
Description of the xCommand commands
xStatus commands
Description of the xStatus commands
Appendices
About startup scripts
The SystemTools commands
About disconnect cause types
User documentation on the Cisco web site
.......................................................................235
........................................................... 31
.........................................35
...................................................................... 37
.................................................. 38
......................39
..................................................... 108
......................... 109
........................................................... 172
................................ 173
..........................................................236
..............................................237
...........................................239
........................240
D15335.08 Cisco TelePresence MX700 and MX800 API Reference Guide CE9.2, NOVEMBER 2017.
Copyright © 2017 Cisco Systems, Inc. All rights reserved. 2
Cisco TelePresence MX700 and MX800
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus
Introduction
API Reference Guide
D15335.08 Cisco TelePresence MX700 and MX800 API Reference Guide CE9.2, NOVEMBER 2017.
Chapter 1
Introduction
Copyright © 2017 Cisco Systems, Inc. All rights reserved. 3
Cisco TelePresence MX700 and MX800
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus
Introduction
About this guide
This guide introduces you to the Application Programmer
Interface (API) for the Collaboration Endpoint software, and
serves as a reference guide for the command line commands
for the following product:
• Cisco TelePresence MX700 and MX800
The guide describes the API for on-premise registered video
systems (CUCM, VCS) as well as video systems registered
to Cisco’s cloud service (Cisco Spark). For Cisco Spark
registered systems only a subset of the API is available, and
the user role (integrator and roomcontrol) of the local user
determines which commands are available.
API Reference Guide
Downloading the user documentation
You can download the user documentation from the Cisco
web site, go to: http://www.cisco.com/go/mx-docs
For Spark registred systems, go to:
https://support.ciscospark.com
Guidelines for how to find the documentation on the Cisco
web site are included in theUser documentation on the
Cisco web site appendix.
D15335.08 Cisco TelePresence MX700 and MX800 API Reference Guide CE9.2, NOVEMBER 2017.
Copyright © 2017 Cisco Systems, Inc. All rights reserved. 4
Cisco TelePresence MX700 and MX800
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus
Introduction
API Reference Guide
What’s new in CE9.2
This section provides an overview of the new and
changed system settings, and the new features and
improvements in the Cisco Collaboration Endpoint
software version 9.2 (CE9.2) compared to CE9.1.
For more details, we recommend reading the Software
release notes:
http://www.cisco.com/c/en/us/support/collaboration-endpoints/telepresence-quick-set-series/
products-release-notes-list.html
New features and improvements
Macro framework
The macro framework allows users and integrators to write
JavaScript macros in order to automate scenarios and
customize endpoint behavior so that it suites an individual
customer’s requirements.
The combination of macros and powerful features such as
listening for events/status changes, automating execution of
commands and configurations, and providing local control
functionality for the In-Room control feature, provides many
possibilities for custom setups.
Minor behavioral changes, such as having the video system
in Do Not Disturb for an infinite amount of time, can be
easily realized by macros. Some other examples are: Reset
configurations automatically, make a call at a certain time
of the day, and issue alert or help messages depending on
status changes.
The macro editor, which also provides several example
macros, is available from the video system’s web interface.
Branding and halfwake customization
You can upload your own text and images to customize the
appearance of the screen and user interface in both the
halfwake state and the awake state.
In the Halfwake state you can:
• Add a background brand image to the screen and user
interface.
• Add a small logo in the bottom right corner of the screen
and user interface.
In the Awake state you can:
• Add a small logo in the bottom right corner of the screen
and user interface.
• Add a label or message in the bottom left corner of the
screen (not the user interface).
Source composition
You can compose up to four input sources (depending on
how many input sources are available on the codec) into one
image. This is the image that will be sent in the main video
stream to the far end in a call. Source composition can only
be enabled via the API, so we recommend creating a user
interface extension combined with a macro to control the
compositions on demand.
This feature replaces some of the functionality that was
provided by the TC Console application for TC software.
HTTP Proxy support
You can set up the video system to go through a HTTP Proxy
when registering it to Cisco’s cloud service, Cisco Spark.
User interface features
• The Settings panel is restructured.
• The Settings panel in the user interface (To u ch 10) can
be protected by the video system’s admin password. If
the password is blank, anyone can access the Settings
and factory reset the system.
• If you select the Russian language on the user interface,
you can choose between a Russian keyboard and a
keyboard with a Latin character set.
• Arabic and Hebrew languages are added to the user
interface. Also localized keyboards are included.
• Basic IEEE 802.1x settings are added to the Settings
panel in the user interface.
Support for the Snap to Whiteboard feature
The Snap to Whiteboard feature is now available for all
products that have a camera with speaker track functionality:
SX80 with Cisco TelePresence Speaker Track 60 camera or
Cisco Spark Quad camera, MX700/MX800 with dual camera,
RoomKit, RoomKit Plus, Room 55 and Room70.
When the video system detects a person that is speaking
close to the whiteboard, the camera view will switch to the
whiteboard area. The wizard in the Settings panel on the
Touch 10 user interface helps you to set up the feature and
define where the whiteboard area is.
D15335.08 Cisco TelePresence MX700 and MX800 API Reference Guide CE9.2, NOVEMBER 2017.
Copyright © 2017 Cisco Systems, Inc. All rights reserved. 5
Cisco TelePresence MX700 and MX800
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus
Introduction
API Reference Guide
Briefing Room mode
The Briefing Room feature, which was introduced already
in TC software, has been reworked. The in-room control
framework is used for creating the associated user interface
elements.
As before, Briefing Room is suppor ted only for dual camera
systems. Also, you need a Precision 60 camera, and a total of
three screens.
Mute and unmute remote participants in a CMS hosted
conference (Active Control)
When a video system is enabled for Active Control in a CMS
(2.1 or later) conference you can mute and unmute remote
participants from the participant list on the user interface (the
feature must also be enabled on the CMS).
A video system that is running software version CE9.2 will
not be unmuted directly. When you try to unmute such a
video system remotely, a message will show up on its screen
requesting the user to unmute the audio locally.
API commands for Custom input prompt
API commands are introduced to allow for an input prompt
in the user interface:
TextInput *
with your custom text, a text input field for the user, and a
submit button, shows up on the user interface. For example,
you can prompt a user to leave feedback after an ended call.
You can specify what type of input you want from the user:
single line text, numeric, password, or PIN code.
The prompt can only be enabled via the API, so it is recommended to combine it with macros and either a custom user
interface panel or an auto-triggered event.
Certificate upload via API
ASCII PEM formatted certificates can be installed directly
using multiline API commands (
. When issuing the display command a prompt
Ceritifcates CA Add
Services Add
system from its web interface, as before.
xCommand UserInterface Message
xCommand Security
, or
xCommand Security Ceritifcates
). You can also upload certificates to a video
API commands for user management
You can create and manage user accounts directly using API
commands (
you can also do this from the video system’s user interface.
Preview mode for In-Room Controls
The In-Room Control editor has a new preview mode. A
virtual Touch 10 user interface shows how the design looks
on the user interface. The user interface is interactive so
that you can test the functionality. It produces real events
on the video system, which can trigger any functionality
you have created with a third-party control system or with a
macro. A console in the right pane displays both the widget
values when interacted with, and control system feedback
messages.
Intelligent Proximity changes
A Proximity indicator is displayed on the screen (middle right)
to inform that one or more clients are paired to the system
with Cisco Proximity. The old indicator (top left), which
was always shown when Proximity was enabled, has been
removed.
You can no longer disable the Proximity services from the
user interface.
The ultrasound settings have moved from Peripherals Pairing
Ultrasound to Audio Ultrasound.
Automatic factory reset when changing the call service
(device activation)
The video system will automatically factory reset and restart
when using the user interface to change the device activation method, for example from VCS to Cisco UCM. This will
prevent conflicting configurations when provisioning the video
system to a new service.
Changing the provisioning from the API will not automatically
factory reset the video system.
xCommand UserManagement User *
). As before,
Support for separate RTP port ranges for audio and other
media
You can configure the video system so that audio uses a
different RTP port range than other media. The two ranges
cannot overlap. As default, all media use the same RTP port
range.
D15335.08 Cisco TelePresence MX700 and MX800 API Reference Guide CE9.2, NOVEMBER 2017.
Copyright © 2017 Cisco Systems, Inc. All rights reserved. 6
Cisco TelePresence MX700 and MX800
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus
Introduction
API Reference Guide
Configuration changes in CE9.2
New configurations
Audio Ultrasound MaxVolume
Cameras Camera[1..2] Focus Mode
Added for the integrated cameras
Macros AutoStart
Macros Mode
NetworkServices HTTP Proxy Allowed
NetworkServices HTTP Proxy LoginName
NetworkServices HTTP Proxy Mode
NetworkServices HTTP Proxy Password
NetworkServices HTTP Proxy Url
Standby WakeupOnMotionDetection
UserInterface CustomMessage
UserInterface OSD HalfwakeMessage
UserInterface SettingsMenu Mode
Configurations that are removed
None
Cameras SpeakerTrack Whiteboard Mode
OLD: User role: ADMIN, INTEGRATOR
NEW: User role: ADMIN, INTEGRATOR, USER
UserInterface Language
NEW: Arabic and Hebrew added to valuespace
Configurations that are modified
Cameras Camera[n] Focus Mode
OLD: Value space: Auto/Manual
NEW: Value space: Auto/AutoLimited/Manual
Cameras SpeakerTrack Closeup
OLD: User role: ADMIN, INTEGRATOR
NEW: User role: ADMIN, INTEGRATOR, USER
D15335.08 Cisco TelePresence MX700 and MX800 API Reference Guide CE9.2, NOVEMBER 2017.
Copyright © 2017 Cisco Systems, Inc. All rights reserved. 7
Cisco TelePresence MX700 and MX800
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus
Introduction
API Reference Guide
Command changes in CE9.2
New commands
Macros Log Clear
Macros Log Get
Macros Macro Activate
Macros Macro Deactivate
Macros Macro Get
Macros Macro Remove
Macros Macro Rename
Macros Macro Roles Set
Macros Macro Save
Macros Runtime Restart
Macros Runtime Start
Macros Runtime Status
Macros Runtime Stop
Message Send
Security Certificates CA Add
Security Certificates CA Delete
Security Certificates CA Show
Security Certificates Services Activate
Security Certificates Services Add
Security Certificates Services Deactivate
Security Certificates Services Delete
Security Certificates Services Show
Standby Halfwake
SystemUnit ProductPlatform Set
UserInterface Branding Delete
UserInterface Branding Get
UserInterface Branding Updated
UserInterface Branding Upload
UserInterface Extensions Widget Action
UserInterface Message TextInput Clear
UserInterface Message TextInput Display
UserManagement User Add
UserManagement User Delete
UserManagement User Get
UserManagement User List
UserManagement User Modify
Commands that are removed
None
Commands that are modified
Audio Microphones Mute
OLD: User role: INTEGRATOR, USER
NEW: User role: ADMIN, INTEGRATOR, USER
D15335.08 Cisco TelePresence MX700 and MX800 API Reference Guide CE9.2, NOVEMBER 2017.
Copyright © 2017 Cisco Systems, Inc. All rights reserved. 8
Cisco TelePresence MX700 and MX800
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus
Introduction
API Reference Guide
Audio Microphones ToggleMute
OLD: User role: INTEGRATOR, USER
NEW: User role: ADMIN, INTEGRATOR, USER
Audio Microphones Unmute
OLD: User role: INTEGRATOR, USER
NEW: User role: ADMIN, INTEGRATOR, USER
Audio Sound Play
OLD: Sound: Alert / Bump / Busy / CallDisconnect / CallInitiate / CallWaiting / Dial / KeyInput
/ KeyInputDelete / KeyTone / Nav / NavBack / Notification / OK / PresentationConnect /
Ringing / SignIn / SpecialInfo / TelephoneCall / VideoCall / VolumeAdjust / WakeUp
NEW: Sound: Alert / Bump / Busy / CallDisconnect / CallInitiate / CallWaiting / Dial
/ KeyInput / KeyInputDelete / KeyTone / Nav / NavBack / Notification / OK / Pairing
/ PresentationConnect / Ringing / SignIn / SpecialInfo / TelephoneCall / VideoCall /
VolumeAdjust / WakeUp
OLD: User role: INTEGRATOR, USER
NEW: User role: ADMIN, INTEGRATOR, USER
Audio Sound Stop
OLD: User role: INTEGRATOR, USER
NEW: User role: ADMIN, INTEGRATOR, USER
Audio SoundsAndAlerts Ringtone List
OLD: User role: INTEGRATOR, USER
NEW: User role: ADMIN, INTEGRATOR, USER
Audio SoundsAndAlerts Ringtone Play
OLD: User role: INTEGRATOR, USER
NEW: User role: ADMIN, INTEGRATOR, USER
Audio SpeakerCheck
OLD: Volume: Integer(1..10)
NEW: Volume: Integer(1..30)
Call Disconnect
OLD: User role: ADMIN, USER
NEW: User role: ADMIN, INTEGRATOR, USER
Camera PositionReset
OLD: User role: ADMIN, USER
NEW: User role: ADMIN, INTEGRATOR, USER
Camera PositionSet
OLD: User role: ADMIN, USER
NEW: User role: ADMIN, INTEGRATOR, USER
Added: Lens: Wide / Center / Left / Right
Camera Ramp
OLD: User role: ADMIN, USER
NEW: User role: ADMIN, INTEGRATOR, USER
Cameras PresenterTrack ClearPosition
OLD: User role: INTEGRATOR, USER
NEW: User role: ADMIN, INTEGRATOR, USER
Cameras PresenterTrack Set
OLD: User role: INTEGRATOR, USER
NEW: User role: ADMIN, INTEGRATOR, USER
Cameras PresenterTrack StorePosition
OLD: User role: INTEGRATOR, USER
NEW: User role: ADMIN, INTEGRATOR, USER
Cameras SpeakerTrack Diagnostics Start
OLD: User role: ADMIN, USER
NEW: User role: ADMIN, INTEGRATOR, USER
Cameras SpeakerTrack Diagnostics Stop
OLD: User role: ADMIN, USER
NEW: User role: ADMIN, INTEGRATOR, USER
Cameras SpeakerTrack Whiteboard ActivatePosition
Removed: Camera
Added: CameraId: Integer (1..7)
Cameras SpeakerTrack Whiteboard AlignPosition
Removed: Camera
Added: CameraId: Integer (1..7)
Cameras SpeakerTrack Whiteboard StorePosition
Removed: Camera
Added: CameraId: Integer (1..7)
D15335.08 Cisco TelePresence MX700 and MX800 API Reference Guide CE9.2, NOVEMBER 2017.
Copyright © 2017 Cisco Systems, Inc. All rights reserved. 9
Cisco TelePresence MX700 and MX800
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus
Introduction
Dial
OLD: User role: ADMIN, USER
NEW: User role: ADMIN, INTEGRATOR, USER
Peripherals HeartBeat
OLD: User role: ADMIN, ROOMCONTROL, USER
NEW: User role: ADMIN, INTEGRATOR, ROOMCONTROL, USER
SystemUnit Boot
OLD: User role: INTEGRATOR, USER
NEW: User role: ADMIN, INTEGRATOR, USER
SystemUnit FirstTimeWizard Stop
OLD: User role: INTEGRATOR, USER
NEW: User role: ADMIN, INTEGRATOR, USER
UserInterface Extensions List
OLD: User role: INTEGRATOR, ROOMCONTROL, USER
NEW: User role: ADMIN, INTEGRATOR, ROOMCONTROL, USER
UserInterface Message Prompt Display
Added: Duration: Integer(0..3600)
Video Input SetMainVideoSource
Added: Layout: Equal / PIP
OLD: User role: INTEGRATOR, USER
NEW: User role: ADMIN, INTEGRATOR, USER
API Reference Guide
D15335.08 Cisco TelePresence MX700 and MX800 API Reference Guide CE9.2, NOVEMBER 2017.
Copyright © 2017 Cisco Systems, Inc. All rights reserved. 10
Cisco TelePresence MX700 and MX800
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus
Introduction
Status changes in CE9.2
New statuses
Cameras Camera[n] DetectedConnector
Cameras Camera[n] Position Lens
Cameras SpeakerTrack ActiveConnector
Video Output Connector[n] ConnectedDevice CEC[n] LogicalAddress
Video Output Connector[n] ConnectedDevice ScreenSize
Statuses that are removed
Cameras SpeakerTrack LeftCamera VideoInputConnector
Cameras SpeakerTrack RightCamera VideoInputConnector
Statuses that are modified
Diagnostics Message[n] Type
Removed from valuespace: CamerasDetectedNoIr / UdpPortRangeViolation
Added to valuespace: CameraDetected / CertificateExpiry / MacrosRuntimeStatus /
MediaPortRangeNegative / MediaPortRangeOdd / MediaPortRangeOverlap /
MediaPortRangeTooSmall / MediaPortRangeValueSpace / MicrophonesConnected
/ SparkActivationRequired / VideoPortRangeNegative / VideoPortRangeOdd /
VideoPortRangeTooSmall / VideoPortRangeValueSpace / UltrasoundConfigSettings
Video Input MainVideoSource
OLD: Value space: Integer
NEW: Value space: 1 / 2 / 3 / 4 / Composed
API Reference Guide
D15335.08 Cisco TelePresence MX700 and MX800 API Reference Guide CE9.2, NOVEMBER 2017.
Copyright © 2017 Cisco Systems, Inc. All rights reserved. 11
Cisco TelePresence MX700 and MX800
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus
Introduction
API Reference Guide
What’s new in CE9.1
This section provides an overview of the new and changed
system settings, and the new features and improvements
in the Cisco Collaboration Endpoint software version 9.1
(CE9.1) compared to CE9.0.
For more details, we recommend reading the Software
release notes:
http://www.cisco.com/c/en/us/support/
collaboration-endpoints/telepresence-mx-series/
products-release-notes-list.html
New features and improvements
Dual Screen experience and Active Control for CMS based
meetings
Dual screen video systems can utilize both screens for video
in a CMS based meeting. The video system receives two
transcoded video streams and one content stream from the
CMS, and utilizes both screens to render the streams.
With Active Control enabled, you get a participant list that
shows all meeting participants and their current activity
status, such as mute, sharing and active speaker indication.
You can change the layout seamlessly from the touch
interface by using the layout selection panels.
New wake-up experience
The new wake-up experience introduces a Halfwake state,
which leads to a calmer wake-up of the system, and gives
users better guidance on how to get started.
When wake-up on motion detection is enabled the system
will automatically wake to the Halfwake state when people
enter the room. It will also wake to this state when a user
pairs a Cisco Proximity client to the system.
Additions for Room Analytics
Detect people presence in the room: The video system has
the capability to find whether there are people present in the
room. The feature is based on ultrasound, and it does not
keep record of who was in the room, only whether or not the
room is in use.
D15335.08 Cisco TelePresence MX700 and MX800 API Reference Guide CE9.2, NOVEMBER 2017.
Copyright © 2017 Cisco Systems, Inc. All rights reserved. 12
Cisco TelePresence MX700 and MX800
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus
Introduction
System configuration changes in CE9.1
New configurations
RoomAnalytics PeoplePresenceDetector
Configurations that are removed
None.
Configurations that are modified
Conference DefaultCal Rate
OLD: Default value: 3072
NEW: Default value: 6000
Conference MultiStream Mode
OLD: Valuespace: Off; Default value: Off
NEW: Valuespace: Auto/Off; Default value: Auto
Network[ 1] IEEE8021X Password
OLD: Valuespace: String(0, 32)
NEW: Valuespace: String(0, 50)
Video Input Connector [n] PresentationSelection
OLD: Valuespace: AutoShare/Manual/OnConnect
NEW: Valuespace: AutoShare/Desktop/Manual/OnConnect
API Reference Guide
D15335.08 Cisco TelePresence MX700 and MX800 API Reference Guide CE9.2, NOVEMBER 2017.
Copyright © 2017 Cisco Systems, Inc. All rights reserved. 13
Cisco TelePresence MX700 and MX800
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus
Introduction
System command changes in CE9.1
New commands
SystemUnit FirstTimeWizard Stop
UserInterface Extensions Set
Commands that are removed
None.
Commands that are modified
Cameras SpeakerTrack Diagnostics Start
OLD: User role: ADMIN, INTEGRATOR
NEW: User role: ADMIN, USER
Cameras SpeakerTrack Diagnostics Stop
OLD: User role: ADMIN, INTEGRATOR
NEW: User role: ADMIN, USER
SystemUnit FactoryReset (All products)
OLD: Keep: LocalSetup/Network/Spark/Provisioning
NEW: Keep: LocalSetup/Network/Spark/Provisioning/
SerialPort/Certificates (not in use)
API Reference Guide
D15335.08 Cisco TelePresence MX700 and MX800 API Reference Guide CE9.2, NOVEMBER 2017.
Copyright © 2017 Cisco Systems, Inc. All rights reserved. 14
Cisco TelePresence MX700 and MX800
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus
Introduction
API Reference Guide
System status changes in CE9.1
New statuses
RoomAnalytics PeoplePresence
Statuses that are removed
None
Statuses that are modified
Diagnostics Message Type
OLD: Value space: CAPFOperationState / CTLinstallation / CUCMVendorConfigurationFile
/ CallProtocolDualStackConfig / CallProtocolIPStackPlatformCompatibility / CallPr
otocolVcsProvisioningCompatibility / CameraId / CameraPairing / CameraSerial /
CameraSoftwareVersion / CameraStatus / CamerasDetected / ConfigurationFile /
DefaultCallProtocolRegistered / EthernetDuplexMatches / FanStatus / PresenterTrack
/ H320GatewayStatus / H323GatekeeperStatus / HasValidReleaseKey /
IpCameraStatus / IPv4Assignment / IPv6Assignment / IPv6Mtu / ISDNLinkCompatibility
/ ISDNLinkIpStack / ITLinstallation / InvalidSIPTransportConfig / LockDown /
RoomControl / MediaBlockingDetected / NetLinkStatus / NetSpeedAutoNegotiated
/ NetworkQuality / NTPStatus / OSDVideoOutput / OutputConnectorLocations
/ ProvisioningDeveloperOptions / ProvisioningStatus / SIPEncryption /
SIPListenPortAndOutboundMode / SIPProfileRegistration / SIPProfileType / SelectedV
ideoInputSourceConnected / SipIceAndAnatConflict / SIPListenPortAndRegistration /
TCPMediaFallback / TemperatureCheck / TLSVerifyRequiredCerts / TouchPanelConnection
/ ControlSystemConnection / TurnBandwidth / UdpPortRangeViolation /
UltrasoundSpeakerAvailability / ValidPasswords / VideoFromInternalCamera /
VideoInputStability / VideoInputSignalQuality / SparkConnectivity / SpeakerTrackFrontPa
nelMountedCorrectly / SpeakerTrackMicrophoneConnection / SpeakerTrackVideoInputs /
SpeakerTrackEthernetConnection / ANATOnVCS / ECReferenceDelay / AudioECRefDelay
/ AudioPairingNoise / AudioPairingRate / AudioPairingSNR / AudioPairingInterference /
AudioPairingTokenDecode / AudioInternalSpeakerDisabled / AbnormalCallTermination /
HasActiveCallProtocol / SipOrH323ButNotBothEnabled / PresentationSourceSelection /
SoftwareUpgrade / PlatformSanity / ContactInfoMismatch / MicrophoneReinforcement /
FirstTimeWizardNotCompleted / CaptivePortalDetected / MonitorDelay
NEW: Value space: : CAPFOperationState / CTLinstallation / CUCMVendorConfigurationFile
/ CallProtocolDualStackConfig / CallProtocolIPStackPlatformCompatibility / CallPr
otocolVcsProvisioningCompatibility / CameraId / CameraPairing / CameraSerial /
CameraSoftwareVersion / CameraStatus / CamerasDetected / CamerasDetectedNoIr /
ConfigurationFile / DefaultCallProtocolRegistered / EthernetDuplexMatches / FanStatus
/ PresenterTrack / H320GatewayStatus / H323GatekeeperStatus / HasValidReleaseKey /
IpCameraStatus / IPv4Assignment / IPv6Assignment / IPv6Mtu / ISDNLinkCompatibility
/ ISDNLinkIpStack / ITLinstallation / InvalidSIPTransportConfig / LockDown /
RoomControl / MediaBlockingDetected / NetLinkStatus / NetSpeedAutoNegotiated
/ NetworkQuality / NTPStatus / OSDVideoOutput / OutputConnectorLocations
/ ProvisioningDeveloperOptions / ProvisioningStatus / SIPEncryption /
SIPListenPortAndOutboundMode / SIPProfileRegistration / SIPProfileType / SelectedV
ideoInputSourceConnected / SipIceAndAnatConflict / SIPListenPortAndRegistration /
TCPMediaFallback / TemperatureCheck / TLSVerifyRequiredCerts / TouchPanelConnection
/ ControlSystemConnection / TurnBandwidth / UdpPortRangeViolation /
UltrasoundSpeakerAvailability / ValidPasswords / VideoFromInternalCamera /
VideoInputStability / VideoInputSignalQuality / SparkConnectivity / SpeakerTrackFrontPa
nelMountedCorrectly / SpeakerTrackMicrophoneConnection / SpeakerTrackVideoInputs /
SpeakerTrackEthernetConnection / ANATOnVCS / ECReferenceDelay / AudioECRefDelay
/ AudioPairingNoise / AudioPairingRate / AudioPairingSNR / AudioPairingInterference /
AudioPairingTokenDecode / AudioInternalSpeakerDisabled / AbnormalCallTermination /
HasActiveCallProtocol / SipOrH323ButNotBothEnabled / PresentationSourceSelection /
SoftwareUpgrade / PlatformSanity / ContactInfoMismatch / MicrophoneReinforcement /
FirstTimeWizardNotCompleted / CaptivePortalDetected / MonitorDelay / WifiCARequired
Standby State
OLD: Value space: Standby/EnteringStandby/Off
NEW: Value space: Standby/EnteringStandby/Halfwake/Off
D15335.08 Cisco TelePresence MX700 and MX800 API Reference Guide CE9.2, NOVEMBER 2017.
Copyright © 2017 Cisco Systems, Inc. All rights reserved. 15
Cisco TelePresence MX700 and MX800
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus
Introduction
API Reference Guide
What’s new in CE9.0
This section provides an overview of the new and changed
system settings, and the new features and improvements
in the Cisco Collaboration Endpoint software version 9.0
(CE9.0) compared to CE8.3.
For more details, we recommend reading the Software
release notes:
http://www.cisco.com/c/en/us/support/
collaboration-endpoints/telepresence-mx-series/
products-release-notes-list.html
New features and improvements
Updated user interface
The user interfaces on the Touch 10, on screen, and on the
integrated touch screen have been updated. The main menu
items on the home screen have been replaced with more
prominent activities.
Some of the setting have been removed from the Touch 10
advanced settings menu to align with the on-screen display
menu.
Wakeup on motion detection
Wakeup on motion detection senses when a person
walks into the conference room and the system wakes up
automatically. You need to enable the following setting for this
feature to work:
xConfiguration Standby WakeupOnMotionDetection
You can’t manually place the system in standby when this
feature is enabled.
Updated In-Room Control Editor
The In-Room Control editor is updated with a new look,
improved logic and usability for producing a control interface
more efficiently. In addition, a new directional pad widget and
an In-Room Control simulator is added.
Added language support
We have added support for Potuguese (Portugal) to the
on-screen display and Touch controller menus.
Other changes
• Support for HTTPS client certificates has been added.
• Unplugging the presentation cable instantly stops the
presentation sharing.
D15335.08 Cisco TelePresence MX700 and MX800 API Reference Guide CE9.2, NOVEMBER 2017.
Copyright © 2017 Cisco Systems, Inc. All rights reserved. 16
Cisco TelePresence MX700 and MX800
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus
Introduction
API Reference Guide
System configuration changes in CE9.0
New configurations
Cameras SpeakerTrack Closeup
NetworkServices HTTPS Server MinimumTLSVersion
NetworkServices HTTPS StrictTransportSecurity
NetworkServices UPnP Mode
Configurations that are removed
None
Configurations that are modified
Cameras Camera [n] *
OLD: User role: ADMIN, USER
NEW: User role: ADMIN, INTEGRATOR
Cameras SpeakerTrack *
OLD: User role: ADMIN, USER
NEW: User role: ADMIN, INTEGRATOR
Conference MultiStream Mode
OLD: Value space: Auto/Off
NEW: Value space: Off
UserInterface Language
NEW: Portuguese added to value space
xConfigurations with INTEGRATOR user role
A new user role - INTEGR ATOR - is introduced in CE9.0. It
has been added to the following configurations:
Audio DefaultVolume
Audio Input HDMI [n] *
Audio Input Line [n] *
Audio Input Microphone [n] *
Audio MicrophoneReinforcement *
Audio Microphones Mute Enabled
Audio Output Line [n] *
Audio SoundsAndAlerts *
Cameras Camera [n] *
Cameras SpeakerTrack *
Conference DefaultCall Rate
Conference DoNotDisturb DefaultTimeout
GPIO Pin [n] Mode
Peripherals Profile *
SerialPort BaudRate
SerialPort Mode
Standby BootAction
Standby Control
Standby Delay
Standby StandbyAction
Standby WakeupAction
SystemUnit Name
Time Zone
UserInterface OSD Output
Video Input Connector [n] CameraControl CameraId
Video Input Connector [n] CameraControl Mode
Video Input Connector [n] InputSourceType
Video Input Connector [n] Name
Video Input Connector [n] PresentationSelection
Video Input Connector [n] Quality
Video Input Connector [n] Visibility
Video Monitors
Video Output Connector [n] CEC Mode
Video Output Connector [n] MonitorRole
Video Output Connector [n] Resolution
Video Presentation DefaultPIPPosition
Video Selfview Default *
Video Selfview OnCall *
<path> * means that the change applies to all configurations starting
with <path>.
D15335.08 Cisco TelePresence MX700 and MX800 API Reference Guide CE9.2, NOVEMBER 2017.
Copyright © 2017 Cisco Systems, Inc. All rights reserved. 17
Cisco TelePresence MX700 and MX800
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus
Introduction
API Reference Guide
System command changes in CE9.0
New commands
Audio Microphones ToggleMute
Audio Volume ToggleMute
Audio Sound Play
Audio Sound Stop
Cameras AutoFocus Diagnostics Start
Cameras AutoFocus Diagnostics Stop
SystemUnit SignInBanner Clear
SystemUnit SignInBanner Get
SystemUnit SignInBanner Set
Video Output Monitor Backlight Set
Video Output Monitor Brightness Set
Video Output Monitor Color Blue Set
Video Output Monitor Color Green Set
Video Output Monitor Color Red Set
Video Output Monitor Color Select
Video Output Monitor Contrast Set
Video Output Monitor CSC Select
Video Output Monitor Gamma Set
Video Output Monitor Reset
Video Output Monitor Sharpness Set
Commands that are modified
SystemUnit FactoryReset
NEW: Keep: LocalSetup, Network, Spark, Provisioning
xCommand with INTEGRATOR user role
Audio Microphones Mute
Audio Microphones ToggleMute
Audio Microphones Unmute
Audio Sound Play
Audio SoundsAndAlerts Ringtone List
Audio SoundsAndAlerts Ringtone Play
Audio Sound Stop
Cameras AutoFocus Diagnostics Start
Cameras AutoFocus Diagnostics Stop
Cameras PresenterTrack ClearPosition
Cameras PresenterTrack Set
Cameras PresenterTrack StorePosition
Cameras SpeakerTrack Diagnostics Start
Peripherals Connect
Peripherals List
Standby Activate
Standby Deactivate
SystemUnit Boot
UserInterface Extensions Clear
UserInterface Extensions List
UserInterface Extensions Widget SetValue
UserInterface Extensions Widget UnsetValue
UserInterface Message Alert Clear
UserInterface Message Alert Display
UserInterface Message Prompt Clear
UserInterface Message Prompt Display
UserInterface Message Prompt Response
UserInterface Message TextLine Clear
UserInterface Message TextLine Display
UserInterface Presentation ExternalSource Add
UserInterface Presentation ExternalSource List
UserInterface Presentation ExternalSource Remove
UserInterface Presentation ExternalSource RemoveAll
UserInterface Presentation ExternalSource Select
UserInterface Presentation ExternalSource State Set
UserManagement User Passphrase Change
Video Input SetMainVideoSource
D15335.08 Cisco TelePresence MX700 and MX800 API Reference Guide CE9.2, NOVEMBER 2017.
Copyright © 2017 Cisco Systems, Inc. All rights reserved. 18
Cisco TelePresence MX700 and MX800
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus
Introduction
API Reference Guide
System status changes in CE9.0
New statuses
Cameras PresenterTrack Availability
Cameras PresenterTrack PresenterDetected
Cameras PresenterTrack Status
Video Output Connector [n] ConnectedDevice CEC [n] Name
Video Output Connector [n] ConnectedDevice CEC [n] VendorId
Video Output Monitor [n] Backlight
Video Output Monitor [n] Brightness
Video Output Monitor [n] ColorTemperature Blue
Video Output Monitor [n] ColorTemperature Green
Video Output Monitor [n] ColorTemperature Red
Video Output Monitor [n] ColorTemperature Selected
Video Output Monitor [n] Contrast
Video Output Monitor [n] CSCYUV
Video Output Monitor [n] Gamma
Video Output Monitor [n] Position
Video Output Monitor [n] Sharpness
Statuses that are modified
Diagnostics Message [n] Type
OLD: CAPFOperationState, CTLinstallation, CUCMVendorConfigurationFile,
CallProtocolDualStackConfig, CallProtocolIPStackPlatformCompatibility, CallProtocolVcsPr
ovisioningCompatibility, CameraId, CameraPairing, CameraSerial, CameraSoftwareVersion,
CameraStatus, CamerasDetected, ConfigurationFile, DefaultCallProtocolRegistered,
EthernetDuplexMatches, FanStatus, PresenterTrack, H320GatewayStatus,
H323GatekeeperStatus, HasValidReleaseKey, IpCameraStatus, IPv4Assignment,
IPv6Assignment, IPv6Mtu, ISDNLinkCompatibility, ISDNLinkIpStack, ITLinstallation,
InvalidSIPTransportConfig, LockDown, RoomControl, MediaBlockingDetected,
NetLinkStatus, NetSpeedAutoNegotiated, NetworkQuality, NTPStatus,
OSDVideoOutput, OutputConnectorLocations, ProvisioningStatus, SIPEncryption,
SIPListenPortAndOutboundMode, SIPProfileRegistration, SIPProfileType, SelectedVideo
InputSourceConnected, SipIceAndAnatConflict, TCPMediaFallback, TemperatureCheck,
TLSVerifyRequiredCerts, TouchPanelConnection, ControlSystemConnection,
TurnBandwidth, UdpPortRangeViolation, UltrasoundSpeakerAvailability, ValidPasswords,
VideoFromInternalCamera, VideoInputStability, SparkConnectivity, SpeakerTrackFrontP
anelMountedCorrectly, SpeakerTrackMicrophoneConnection, SpeakerTrackVideoInputs,
SpeakerTrackEthernetConnection, ANATOnVCS, ECReferenceDelay, AudioECRefDelay,
AudioPairingNoise, AudioPairingRate, AudioPairingSNR, AudioPairingInterference,
AudioPairingTokenDecode, AudioInternalSpeakerDisabled, AbnormalCallTermination,
HasActiveCallProtocol, SipOrH323ButNotBothEnabled, PresentationSourceSelection,
SoftwareUpgrade, PlatformSanity, ContactInfoMismatch, MicrophoneReinforcement
NEW: CAPFOperationState, CTLinstallation, CUCMVendorConfigurationFile,
CallProtocolDualStackConfig, CallProtocolIPStackPlatformCompatibility, CallP
rotocolVcsProvisioningCompatibility, CameraId, CameraPairing, CameraSerial,
CameraSoftwareVersion, CameraStatus, CamerasDetected, ConfigurationFile,
DefaultCallProtocolRegistered, EthernetDuplexMatches, FanStatus, PresenterTrack,
H320GatewayStatus, H323GatekeeperStatus, HasValidReleaseKey, IpCameraStatus,
IPv4Assignment, IPv6Assignment, IPv6Mtu, ISDNLinkCompatibility, ISDNLinkIpStack,
ITLinstallation, InvalidSIPTransportConfig, LockDown, RoomControl,
MediaBlockingDetected, NetLinkStatus, NetSpeedAutoNegotiated, NetworkQuality,
NTPStatus, OSDVideoOutput, OutputConnectorLocations, ProvisioningDeveloperOptions,
ProvisioningStatus, SIPEncryption, SIPListenPortAndOutboundMode,
SIPProfileRegistration, SIPProfileType, SelectedVideoInputSourceConnec
ted, SipIceAndAnatConflict, SIPListenPortAndRegistration, TCPMediaFallback,
TemperatureCheck, TLSVerifyRequiredCerts, TouchPanelConnection,
ControlSystemConnection, TurnBandwidth, UdpPortRangeViolation,
UltrasoundSpeakerAvailability, ValidPasswords, VideoFromInternalCamera,
VideoInputStability, VideoInputSignalQuality, SparkConnectivity, SpeakerTrackFrontPa
nelMountedCorrectly, SpeakerTrackMicrophoneConnection, SpeakerTrackVideoInputs,
SpeakerTrackEthernetConnection, ANATOnVCS, ECReferenceDelay, AudioECRefDelay,
AudioPairingNoise, AudioPairingRate, AudioPairingSNR, AudioPairingInterference,
AudioPairingTokenDecode, AudioInternalSpeakerDisabled, AbnormalCallTermination,
HasActiveCallProtocol, SipOrH323ButNotBothEnabled, PresentationSourceSelection,
SoftwareUpgrade, PlatformSanity, ContactInfoMismatch, MicrophoneReinforcement,
FirstTimeWizardNotCompleted, CaptivePortalDetected, MonitorDelay
xStatus with INTEGRATOR user role
Audio Microphones Mute
Audio Output Connectors Line[n] DelayMs
Audio Volume
Call[n] FacilityServiceId
Call[n] ReceiveCallRate
D15335.08 Cisco TelePresence MX700 and MX800 API Reference Guide CE9.2, NOVEMBER 2017.
Copyright © 2017 Cisco Systems, Inc. All rights reserved. 19
Cisco TelePresence MX700 and MX800
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus
Introduction
API Reference Guide
Call[n] TransmitCallRateCameras Camera[n] Capabilities
Options
Cameras Camera[n] Connected
Cameras Camera[n] Flip
Cameras Camera[n] HardwareID
Cameras Camera[n] MacAddress
Cameras Camera[n] Manufacturer
Cameras Camera[n] Model
Cameras Camera[n] Position Focus
Cameras Camera[n] Position Pan
Cameras Camera[n] Position Tilt
Cameras Camera[n] Position Zoom
Cameras Camera[n] SerialNumber
Cameras Camera[n] SoftwareID
Cameras PresenterTrack Availability
Cameras PresenterTrack PresenterDetected
Cameras PresenterTrack Status
Cameras SpeakerTrack Availability
Cameras SpeakerTrack LeftCamera VideoInputConnector
Cameras SpeakerTrack RightCamera VideoInputConnector
Cameras SpeakerTrack Status
Conference DoNotDisturb
Conference Presentation CallId
Conference Presentation LocalInstance[n] SendingMode
Conference Presentation LocalInstance[n] Source
Conference Presentation Mode
GPIO Pin[n] State
Peripherals ConnectedDevice[n] HardwareInfo
Peripherals ConnectedDevice[n] ID
Peripherals ConnectedDevice[n] Name
Peripherals ConnectedDevice[n] SoftwareInfo
Peripherals ConnectedDevice[n] Status
Peripherals ConnectedDevice[n] Type
Peripherals ConnectedDevice[n] UpgradeStatus
Standby State
SystemUnit State NumberOfActiveCalls
SystemUnit State NumberOfInProgressCalls
Time SystemTime
UserInterface Extensions Widget[n] Value
UserInterface Extensions Widget[n] WidgetId
Video ActiveSpeaker PIPPosition
Video Input Connector[n] Connected
Video Input Connector[n] SignalState
Video Input Connector[n] SourceId
Video Input Connector[n] Type
Video Input Source[n] ConnectorId
Video Input Source[n] FormatStatus
Video Input Source[n] FormatType
Video Input Source[n] Resolution Height
Video Input Source[n] Resolution RefreshRate
Video Input Source[n] Resolution Width
Video Output Connector[n] Connected
Video Output Connector[n] ConnectedDevice CEC[n]
DeviceType
Video Output Connector[n] ConnectedDevice CEC[n] Name
Video Output Connector[n] ConnectedDevice CEC[n]
PowerControl
Video Output Connector[n] ConnectedDevice CEC[n]
PowerStatus
Video Output Connector[n] ConnectedDevice CEC[n]
VendorId
Video Output Connector[n] ConnectedDevice Name
Video Output Connector[n] ConnectedDevice
PreferredFormat
Video Selfview FullscreenMode
Video Selfview Mode
Video Selfview OnMonitorRole
Video Selfview PIPPosition
D15335.08 Cisco TelePresence MX700 and MX800 API Reference Guide CE9.2, NOVEMBER 2017.
Copyright © 2017 Cisco Systems, Inc. All rights reserved. 20
Cisco TelePresence MX700 and MX800
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus
About the API
API Reference Guide
D15335.08 Cisco TelePresence MX700 and MX800 API Reference Guide CE9.2, NOVEMBER 2017.
Chapter 2
About the API
Copyright © 2017 Cisco Systems, Inc. All rights reserved. 21
Cisco TelePresence MX700 and MX800
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus
About the API
API fundamentals
This chapter contains a top-level view of the mechanisms
supported by the codec API.
Here you can read about how to access the API, how to use
the command line and what the different parts of the API
can be used for. This chapter also describes how to use the
feedback functions that are available for the codec.
The API consists of four major groups:
• Commands
• Configurations
• Status
• Events
These four groups are hierarchically organized, which
makes it easier to find related functionality. You can find the
complete lists of all commands, configurations and statuses
in the following chapters.
Connecting to the API
There are several ways to access the codec API. Regardless
of which method you choose, the structure of the API stays
the same. Choose the connection method that suits your
application best. Before you start, please read this section
about the different methods, as some of those may require
additional configuration changes before being enabled.
The following configurations, apart from password, can be set
from the System configuration menu on the web interface or
from the command line interface. All of the examples are for
the command line interface.
Password
The video system is delivered with a default user account
with full credentials. The user name is admin, and initially, no
password is set for the default user.
It is mandatory to set a password for the admin user in
order to restrict access to system configuration. You should
in addition set a password for any other user with similar
credentials.
You can set the password on the codec’s web interface.
Open a web browser and enter the IP address of the video
system in the address bar and log in. Click your user name in
the upper right corner and choose Change password in the
drop down menu.
API Reference Guide
SSH
SSH is a secure TCP/IP connection and it is enabled by
default on the codec. It can be disabled. You need a SSH
client, such as PuTTY, to access the API over SSH.
xConfiguration NetworkServices SSH Mode:
<O f f,O n>
Telnet
Telnet can be viewed as the equivalent of the serial protocol
in the TCP/IP world. Telnet is disabled by default. Before
connecting to the codec with Telnet you have to enable it.
To enable Telnet service, configure the following setting on
the codec. Changing this setting does not require a reboot of
the device, but it may take some time to take effect.
xConfiguration NetworkServices Telnet Mode:
<O f f,O n>
HTTP/HTTPS
As HTTP/HTTPS are connectionless protocols, there
is no persistent connection. There are several ways of
communicating with the API over HTTP.
In order to enable or disable the HT TP and HTTPS services,
configure the following setting on the codec.
xConfiguration NetworkServices HTTP Mode:
<Off, HTTP+HTTPS, HTTPS>
D15335.08 Cisco TelePresence MX700 and MX800 API Reference Guide CE9.2, NOVEMBER 2017.
Connecting
You can inspect the API by entering the IP address or host
name of the codec in your favorite web browser. In the
web interface, you can find the API documents under the
menu section Integration > Developer API. The HTTP POST
and GET methods are used to execute commands and get
feedback from the codec. This is described in ”Using HTTP”
on page 33 in this document.
Copyright © 2017 Cisco Systems, Inc. All rights reserved. 22
Cisco TelePresence MX700 and MX800
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus
About the API
API Reference Guide
RS-232 / serial connection
The video system has a standard COM-port for serial
communication. It can be used without an IP address, DNS or
a network. Serial connection is allowed by default.
xConfiguration SerialPort Mode: <Off/On>
Connect a standard 9-pin serial cable <115200, N, 8, 1> to
the COM port on the codec.
Baud-rate and other serial port parameters
The serial port uses 8 data bits, no parity and 1 stop bit. The
default baud rate is set to 11520 0 bps.
The codec can give very much feedback. We therefore
recommend keeping the connection at this speed to avoid
sluggishness.
You can change the baud rate if required.
xConfiguration SerialPort BaudRate:
<9600/19200/38400/57600/115200>
Login and password
You can choose whether login is required or not for serial
connections. For security reasons the password prompting is
turned on by default, but it can be turned off if preferred.
xConfiguration SerialPort LoginReq uired: <Off/On>
User roles
A user account may hold one or a combination of user roles.
A user account with full access rights, like the default admin
user, should possess the ADMIN, USER and AUDIT roles.
These are the user roles:
ADMIN: A user with this role can create new users, change
most settings, make calls, and search the contact lists. The
user cannot upload audit certificates and change the security
audit settings.
USER: A user with this role can make calls and search the
contact lists. The user can modify a few settings, for example
adjust the ringtone volume and set the time and date format.
AUDIT: A user with this role can change the security audit
settings and upload audit certificates.
ROOMCONTROL: A user with this role can create in-room
controls. The user has access to the In-room control editor
and corresponding developement tools.
INTEGR ATOR: A user with this role has access to settings,
commands and status that are required to set up advanced
AV scenarios, and to integrate our video systems with 3rd
party equipment. Such a user can also create in-room
controls.
Cisco Spark registered systems
If a video system is registered to Cisco’s cloud service
(Cisco Spark), only local users with the INTEGR ATOR and
ROOMCONTROL user roles are available.
D15335.08 Cisco TelePresence MX700 and MX800 API Reference Guide CE9.2, NOVEMBER 2017.
Copyright © 2017 Cisco Systems, Inc. All rights reserved. 23
Cisco TelePresence MX700 and MX800
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus
About the API
API output
The xPreferences is used to set preferences for the RS-232,
Telnet and SSH sessions.
API Reference Guide
Example: Layout command in terminal mode
The output modes
• Terminal: Line based output for use with line based
control systems
• XML: XML output for use with control systems that
understand XML.
• JSON: JSON format is convenient when integrating with
web based systems.
The default output mode is terminal. To change this you
have to define your preferences for each session individually.
Examples in this guide are in terminal mode.
To set output mode to XML, issue the command:
xPreferences outputmode xml
To revert to terminal mode, issue the command:
xPreferences outputmode terminal
xCom mand Audio Volume Set Level: 50
Example: Layout command in XML mode
<Command>
<Audio>
<Volu m e>
<Set command=”True”>
<Level>50</Level>
</Set>
</Volu m e>
</Au d io>
</Command>
D15335.08 Cisco TelePresence MX700 and MX800 API Reference Guide CE9.2, NOVEMBER 2017.
Copyright © 2017 Cisco Systems, Inc. All rights reserved. 24
Cisco TelePresence MX700 and MX800
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus
About the API
API Reference Guide
Using the command line
Help
To get a list of all supported top level commands you can
type ? or help after connecting to the TelePresence System
using RS-232, Telnet or SSH (Example 1).
Bye
Typing the bye command closes the command line interface.
API commands
xConfiguration
Configurations are system settings, such as system name
and network settings. These are persistent across boots.
Refer to ”Configurations” on page 27.
xCommand
Commands instruct the codec to execute actions, such as to
dial a number or to search the phone book.
Refer to ”Commands” on page 27.
xStatus
A status contains the current state of the codec, such as
connected calls, the status of the gatekeeper registration,
connected inputs and output sources.
Refer to ”Status” on page 27.
xFeedback
The Feedback commands are used to specify what parts of
the configuration and status hierarchies to monitor. Feedback
is only issued on the RS-232, Telnet or SSH session for
which it is specified. If you are connecting to the codec with
multiple sessions, you have to define feedback individually
for each session. Refer to ”Feedback mechanism” on page
31.
Example 1:
?
- User Commands -
help
xgetxml xdocument xpreferences xtransaction xstatus
bye echo log systemtools
OK
xPreferences
The xPreferences command is used to set preferences for
the RS-232, Telnet and SSH sessions.
Refer to ”API output” on page 24.
Echo <on/off>
If echo is set to On the key inputs are displayed when
entering text in a command line interface.
If echo is set to Off user input is not displayed when entering
text in a command line interface.
xEvent
The xEvent command returns information on which events are
available for feedback. Refer to ”Events” on page 30.
xGetxml
The xGetxml request returns an XML document based on the
location parameter attached to the request. The elements
(or a complete document) matching the expression will be
returned. Refer to ”Feedback mechanism” on page 31.
xcom mand xconfiguration xevent xfeedback
Other commands
Systemtools
The systemtools commands are a set of command line tools
for administrative control and diagnostics. The commands
can be used for advanced troubleshooting together with
Cisco technical support. Systemtools are not a part of the
programming API. Refer to ”The SystemTools commands”
on page 237.
Log
The log command is used to enable advanced logs. It is only
used for debugging the system.
D15335.08 Cisco TelePresence MX700 and MX800 API Reference Guide CE9.2, NOVEMBER 2017.
Copyright © 2017 Cisco Systems, Inc. All rights reserved. 25
Cisco TelePresence MX700 and MX800
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus
About the API
API Reference Guide
Command line shortcuts
If your client supports it, there are some timesaving shortcuts
you can use:
• Tab-completion to complete the commands and
arguments.
• Arrow up and arrow down keys to navigate your
command history.
• <CTRL-a>: Jump to the beginning of the line.
• <CTRL-e>: Jump to the end of the line.
• <CTRL-r>: Incremental command history search.
• <CTRL-w>: Erase the current line.
Searching
You can use // to search for elements anywhere in the status
or configuration hierarchy (Example 1).
You can also combine multiple //’s (Example 2).
NOTE: The search shortcuts work well for inspecting the
API, but should not be used in applications. We recommend
that you always use the complete paths to avoid command
ambiguity when upgrading to newer firmware releases.
Example 1:
List all configurations that include words that starts with OUT
and HDMI:
x c o n f i g u r a t i o n // o u t // h d m i
*c xConfiguration Audio Output HDMI 1 Level: 0
*c xConfiguration Audio Output HDMI 1 Mode: On
*c xConfiguration Audio Output HDMI 2 Level: 0
*c xConfiguration Audio Output HDMI 2 Mode: Off
** end
Example 2:
Get the resolution width of all connected sources for both
inputs and outputs:
x S t a t u s // v i d // r e s // w i d
*s Video Input Source 1 Resolution Width: 1920
*s Video Input Source 2 Resolution Width: 0
*s Video Input Source 3 Resolution Width: 0
*s Video Input Source 4 Resolution Width: 0
*s Video Output Connector 1 Resolution Width: 1920
*s Video Output Connector 2 Resolution Width: 1280
*s Video Output Connector 3 Resolution Width: 1280
** end
Value types and formats
The system supports the following value types:
• Integer values: <x..y>
Defines the valid range for an integer input. x = min value,
y = max value.
• Literal values: <X/Y/../Z>
Defines the possible values for a given configuration.
• String values: <S: x, y>
Defines that the valid input for this configuration is a
string with minimum length of x and maximum length of
y characters. Strings can have rules that further specify
their format and length.
Input values that contain spaces need to be quoted
Any values for configurations and commands containing
spaces must be enclosed in quotes. Quotes are not
necessary for values without spaces.
Example:
Correct:
contains spaces”
Correct:
Incorrect:
contains spaces
Case sensitivity
All commands are case-insensitive. All of the following
commands will work.
XCOMMAND DIAL NUMBER: foo@bar.org
xcom mand dial nu mber: foo@bar.org
xCom mand Dial Number: foo@bar.org
xCommand dial number: “my number
xCommand dial number: 12345
xCommand dial number: my number
D15335.08 Cisco TelePresence MX700 and MX800 API Reference Guide CE9.2, NOVEMBER 2017.
Copyright © 2017 Cisco Systems, Inc. All rights reserved. 26
Cisco TelePresence MX700 and MX800
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus
About the API
API Reference Guide
Commands
Commands instruct the codec to execute actions, such as
to dial a number or to search the phone book. All commands
start with the prefix xCommand followed by a command path.
Writing xCommand ? on the command line will list all the top
level commands.
To view the complete list of commands and their parameters,
write xCommand ?? on the command line.
Command arguments are key-value pairs.
When issuing a xCommand, the command consists of one
argument and one required parameter. In this document the
command usage is described for all xCommands, with both
required and optional parameters. The optional parameters
are in brackets.
Example: xCommand Dial Number: 123
• xCommand is the command prefix. The command to be
executed is Dial.
• The example contains one argument, Number: 123.
Number is the key and 123 is its value. The key/value pair
is separated with ‘:’.
Configurations
Configurations are system settings that are persistent across
boots. Like commands, also configurations are structured in
a hierarchy.
Writing xConfiguration ? on the command line lists all the top
level configurations.
Writing xConfiguration ?? lists all configurations and their
value spaces.
Writing xConfiguration lists all configurations and their
current values. To list out only some of the configurations,
write xConfiguration followed by one or more parts of the
configuration paths.
Example: Set the H323 Alias ID
Write in:
xConfiguration H323 Profile 1 H323Alias ID:
“changed@company.com”
Example: Get the H323 Alias ID
Write in:
xConfiguration H323 Profile 1 H323Alias ID
Result:
*c xConfiguration H323 Profile 1 H323Alias ID:
“changed@company.com”
**end
Status
A status contains the current state of the codec, such as
connected calls, the status of the gatekeeper registration,
connected inputs and output sources.
Writing xStatus ? on the command line lists all top level
statuses.
Writing xStatus lists all statuses and their current values.
To list out only some of the statuses, write xstatus followed by
the relevant part of the status path (address expression):
xStatus <address expression>
D15335.08 Cisco TelePresence MX700 and MX800 API Reference Guide CE9.2, NOVEMBER 2017.
Copyright © 2017 Cisco Systems, Inc. All rights reserved. 27
Cisco TelePresence MX700 and MX800
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus
About the API
Multiline commands
Multiline commands are commands that support larger
amounts of data as input than the single line commands.
Typical use for these commands is to allow for provi-
sioning of in-room control definitions, branding images
(base64 encoded), macros, welcome banners, and security
certificates.
To issue a multiline command, you start issuing it like
any other XAPI command. However, once you enter the
command, you have set the API into an input mode where
anything you issue on the API after this is treated as input
to that command, including line breaks. You now enter the
payload for this command in accordance to the input format
expected by this command
When done, finish with a line break(“\n”) and a separate line
containing just a period ending with a line break (“.\n”). The
command will now be executed, and you will get a command
result with an OK or ERROR depending on the command
being executed successfully or not.
The commands that require multiline input format are marked
as such in the command descriptions in this guide.
The multiline commands are marked as multiline in
xCommand overview section in this guide.
API Reference Guide
Example: Set up welcome banner text
xCommand SystemUnit SignInBanner Set
Hell o!
This is the second line of text.
This is the third.
Thank yo u!
.
OK
*r SignInBannerSetResult (status=OK):
** end
D15335.08 Cisco TelePresence MX700 and MX800 API Reference Guide CE9.2, NOVEMBER 2017.
Copyright © 2017 Cisco Systems, Inc. All rights reserved. 28
Cisco TelePresence MX700 and MX800
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus
About the API
API Reference Guide
Synchronous API calls
The API works asynchronously. This means that there is no
guarantee that command responses arrive in the same order
as the commands were issued. The codec may also respond
with feedback between your request and the response, in
form of status changes or events, due to changes on the
system.
For some applications it might be crucial to match requests
with responses. The API therefore supports a responsetagging mechanism.
This mechanism works with all command types: xcommand,
xconfiguration, and xstatus. A typical use of this would be
to create a command queue in your application and assign
unique IDs to every command sent to the codec. A listener
then listens to all feedback from the codec and matches
the ID on the response with the corresponding ID in the
command queue. This enables matching the original request
with the specific response.
Example:
xcommand Video Layout Add | resultId=”mytag _ 1”
OK
*r VideoLayoutAddResult (status=OK):
LayoutId: 1
** resultId: “mytag _ 1”
** end
In XML mode the resultId is added as an attribute to the top-level XmlDoc tag:
xget x ml /Configuration/Video/Layout/Scali ng | resultId=”mytag _ 2”
<X mlDoc resultId=”my tag _ 2”>
<Configuration item=”1”>
< Vid e o ite m = ”1”>
<L a y o ut ite m = ” 1”>
<Scaling item=”1” valueSpaceRef=”...”>Off</Scaling>
</Layout>
</Vid eo>
</Configuration>
</XmlD oc>
D15335.08 Cisco TelePresence MX700 and MX800 API Reference Guide CE9.2, NOVEMBER 2017.
Copyright © 2017 Cisco Systems, Inc. All rights reserved. 29
Cisco TelePresence MX700 and MX800
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus
About the API
API Reference Guide
Events
Event returns information about the events that are available
for feedback. This overview presents examples of some the
events that are available on the API.
To get an overview of the supported events type ?, ?? or help
after xEvent:
• xEvent ? Lists the top level events
• xEvent ?? List all of the available events
• xEvent help Lists the top level events
The result for events depends on the state of the codec.
Example 1: Outgoing Call Indication
Outgoing Call Indication is an event reported when an
outgoing call is about to be dialled. Returns the CallId the
call has been assigned.
*e OutgoingCallIndication CallId: x
** end
Example 2: Call Disconnect
Call Disconnect is an event reported when a call is
disconnected. Returns the CallId of the disconnected call
and reason for the call’s disconnection.
*e CallDisconnect CallId: x CauseValue: 0
CauseString: “” CauseType: LocalDisconnect
OrigCallDirection: “outgoing”
** end
Example 3: Call Successful
Call Succesful is an event reported when a call is
connected successfully, that is when all channels are up
and established.
*e CallSuccessful CallId: 132 Protocol: “h223”
Direction: “outgoing” CallRate: 768 RemoteURI:
“h223:integratorHQ@company.com” EncryptionIn:
“Off” Encry ptionOut: “Off”
** end
Example 4: FECC Action request
FECC Action request is an event reported when far end is
sending FECC commands.
*e FeccActionInd Id: 132 Req: 1 Pan: 1 PanRight:
1 Tilt: 0 TiltUp: 0 Zoom: 0 ZoomIn: 0 Focus: 0
FocusIn: 0 Timeout: 300 VideoSrc: 0 m: 0
** end
Example 5: TString message received
TString message received is an event reported when far
end has sent a TString message.
*e TString CallId: 132 Message: “ee”
** end
Example 6: SString message received
SString message received is an event reported when far
end has sent a SString message.
*e SString String: “ee” Id: 132
** end
D15335.08 Cisco TelePresence MX700 and MX800 API Reference Guide CE9.2, NOVEMBER 2017.
Copyright © 2017 Cisco Systems, Inc. All rights reserved. 30
Loading...