Application Programming Interface (API) Reference Guide

173 Pages·2016·4.46 MB·English

Cisco TelePresence DX70 and DX80 API Reference Guide
Collaboration Endpoint Software 8.2
SEPTEMBER 2016
Application Programming Interface (API)
Reference Guide
Cisco TelePresence DX70 and DX80
D15363.02 Cisco TelePresence DX70 and DX80 API Reference Guide CE8.2, SEPTEMBER 2016. 1 Copyright © 2016 Cisco Systems, Inc. All rights reserved.
Cisco TelePresence DX70 and DX80 API Reference Guide
What’s in this guide? Table of Contents
The top menu bar and the entries in the table of contents are
all hyperlinks, just click on them to go to the topic. Introduction ..........................................................................3 Commands ...........................................................................32
We recommend you visit our web site regularly for updated About this guide ......................................................................4 Configurations ......................................................................32
versions of the user documentation. Downloading the user documentation .................................4
Status ....................................................................................32
Go to:http://www.cisco.com/go/dx-docs What’s new in CE8.2...............................................................5
Events ...................................................................................33
New features and improvements .........................................5
xConfiguration changes in CE8.2 .........................................7 Feedback mechanism...........................................................34
xCommand changes in CE8.2..............................................9 Feedback expressions .......................................................34
xStatus changes in CE8.2 ..................................................10 Terminal connections .........................................................35
What’s new in CE8.1 .............................................................11 Using HTTP ...........................................................................36
New features and improvements .......................................11 HTTP XMLAPI Authentication ............................................36
xConfiguration changes in CE8.1 .......................................12 HTTP XMLAPI Session Authentication ...............................36
xCommand changes in CE8.2............................................13 Getting status and configurations ......................................37
xStatus changes in CE8.2 ..................................................14 Sending commands and configurations.............................37
Using HTTP POST ..............................................................37
What’s new in CE8.0 .............................................................15
New features and improvements .......................................15 Feedback from codec over HTTP ........................................38
xConfiguration changes in CE8.0 .......................................17 Registering for feedback ....................................................38
xCommand changes in CE8.0............................................20 Translating from terminal mode to XML..............................39
xStatus changes in CE8.0 ..................................................23
Dos and don’ts ......................................................................40
About the API ......................................................................26
xConfiguration commands ..................................................41
API fundamentals ..................................................................27
Connecting to the API ........................................................27
xCommand commands .......................................................86
Password ...........................................................................27
Telnet ..................................................................................27
SSH ....................................................................................27 xStatus commands ...........................................................121
HTTP/HTTPS ......................................................................28
API output .............................................................................29 Appendices.......................................................................167
The output modes ..............................................................29
About startup scripts ..........................................................168
Using the command line .......................................................30
The SystemTools commands ..............................................169
API commands ...................................................................30
Other commands ...............................................................30 About disconnect cause types ...........................................171
Command line shortcuts ....................................................31
User documentation on the Cisco web site .......................172
Searching ...........................................................................31
Value types and formats ....................................................31
D15363.02 Cisco TelePresence DX70 and DX80 API Reference Guide CE8.2, SEPTEMBER 2016. 2 Copyright © 2016 Cisco Systems, Inc. All rights reserved.
Cisco TelePresence DX70 and DX80 API Reference Guide
Chapter 1
Introduction
D15363.02 Cisco TelePresence DX70 and DX80 API Reference Guide CE8.2, SEPTEMBER 2016. 3 Copyright © 2016 Cisco Systems, Inc. All rights reserved.
Cisco TelePresence DX70 and DX80 API Reference Guide
About this guide
This guide introduces you to the Application Programmer Downloading the user documentation
Interface (API) for the Collaboration Endpoint software, and
You can download the user documentation from the Cisco
serves as a reference guide for the command line commands
web site, go to:http://www.cisco.com/go/dx-docs
for the following product:
Guidelines for how to find the documentation on the Cisco
• Cisco TelePresence DX70 and DX80
web site are included in theUser documentation on the
Cisco web site appendix.
D15363.02 Cisco TelePresence DX70 and DX80 API Reference Guide CE8.2, SEPTEMBER 2016. 4 Copyright © 2016 Cisco Systems, Inc. All rights reserved.
Cisco TelePresence DX70 and DX80 API Reference Guide
What’s new in CE8.2
New features and improvements Cisco Spark support
This section provides an overview of the new and
CE8.2 introduces support for Cisco Spark activation for
changed system settings, and the new features and
LDAP user management SX10 (CTS-SX10-K9), SX20, SX80, MX200 G2, MX300 G2,
improvements in the Cisco Collaboration Endpoint
MX700, MX800, MX800D, DX70 and DX80. A video system
software version 8.2 (CE8.2) compared to CE8.0. In CE8.2, you can register users with ADMIN role from an
registered to the Cisco Spark service can be used together
external LDAP service to grant them access to the video
The list of new commands includes all changes from with Cisco Spark mobile and desktop applications.
system’s web interface and API. This allows for central-
CE8.0 to CE8.2.
ized management of ADMIN users. The LDAP server can To register to Cisco Spark:
As CE software is based on TC7, the structure and main be configured from the web interface. Authenticating users
• Touch 10 must be directly paired (Touch 10 is not
functionality remains the same as in TC software. with the USER role using LDAP is not supported.
supported for Spark registered SX10N, SX10, SX20,
For more details, we recommend reading the Software LDAP configuration can be set from CUCM. If the video DX70 and DX80)
release notes: system requires a certificate for login from LDAP, it must • Encryption Option key must be installed (Does not
be uploaded to the codec manually as CUCM is unable to apply to DX70 and DX80)
http://www.cisco.com/c/en/us/support/
provision certificates.
collaboration-endpoints/desktop-collaboration-experi- When the video system is activated on Cisco Spark, it
ence-dx600-series/products-release-notes-list.html downloads the newest version of Cisco Spark Room OS.
Administrator credentials not needed for remote pairing to
It is important to consider the upgrade a Touch 10 Cisco Spark Room OS does not have the same manage-
requirements of CE8 before upgrading; other- ment capabilities as Collaboration Endpoint Software as its
wise upgrading to CE8 can leave you with a You no longer need to enter administrator credentials web and command line interfaces are locked. The Room
non-functioning deployment that requires you to when you remote pair a Touch 10 controller to a video System is managed by Cisco and if there are any issues,
downgrade. system. All user credentials can be used for this purpose. contact Cisco Technical Assistance center through the
The administrator doesn’t have to visit the site or provide Cisco Spark mobile application or from the management
administrator credentials in order to pair or re-pair a touch portal.
controller to a video system.
For more information on the Cisco Spark Room OS and its
Un-pairing the Touch 10 controller and changing advanced features see: https://help.webex.com/
settings still require admin credentials.
Cisco Proximity updates
Additional entry points for in-room controls
The application name has changed from Proximity to Cisco
In-room controls now have an option for multiple panels Proximity.
that are available depending on the context. This provides
more flexibility to add multiple panels for various tasks The latest release includes the following improvements:
instead of putting all actions into one panel. • First time use tutorial for desktop application
There are now three entry points available for in-room • Updated look for the user interface
controls: Global (introduced in CE8.1), Homescreen and • Improved pairing experience
In-Call. The Homescreen entry point is located on the
• Increased visibility on the user’s desktop
home screen icon tray, next to the Dial, Contacts, and
Share buttons. The In-Call entry point is located in the icon • Better information and handling of failure scenarios
tray, and is accessible when the video system is in a call. • Link to support forums on the client
New panel icons have been added. The Cisco Proximity clients for smartphones and tablets
(Android and iOS), and laptops (Windows and OS X) can be
D15363.02 Cisco TelePresence DX70 and DX80 API Reference Guide CE8.2, SEPTEMBER 2016. 5 Copyright © 2016 Cisco Systems, Inc. All rights reserved.
Cisco TelePresence DX70 and DX80 API Reference Guide
downloaded from http://proximity.cisco.com. Clients for Added language support
smartphones and tablets are also available through Google
We have added support for Canadian French (Français
Play (Android) and Apple App Store (iOS).
– Canada) to the on-screen display and Touch controller
menus.
Touch 10 user interface changes
A visual update has been applied to the Setup and Pairing
Wizard on the Touch 10. The Touch 10 has a new GUI
when registered to Cisco Spark, which is similar to the
Cisco TelePresence SX10 on-screen user interface. If the
endpoint is registered to on-premise infrastructure, the
Touch 10 controller has the same user interface as CE8.1.
Default option keys removed
Option keys for features that have become default on all
Cisco TelePresence video systems are now removed. The
functionalities provided by these options are still present,
but the keys are no longer needed.
Removed option keys:
• PremiumResolution
• NaturalPresenter
• DualDisplay
• HighDefinition
Option keys that are still available:
• Encryption
• MultiSite
• RemoteMonitoring
New user role: “RoomControl”
The “RoomControl” user role is added to provide
non-admin users or integrators access to the In-Room
control editor. The “RoomControl” role can be assigned
when a new non-admin user is created from the codec’s
web interface.
D15363.02 Cisco TelePresence DX70 and DX80 API Reference Guide CE8.2, SEPTEMBER 2016. 6 Copyright © 2016 Cisco Systems, Inc. All rights reserved.
Cisco TelePresence DX70 and DX80 API Reference Guide
xConfiguration changes in CE8.2 Provisioning ExternalManager Domain
OLD: User Role: ADMIN
New configurations NEW: User Role: ADMIN, USER
Peripherals Profile Cameras Provisioning ExternalManager Path
UserManagement LDAP Mode OLD: User Role: ADMIN
NEW: User Role: ADMIN, USER
UserManagement LDAP Server Address
Provisioning ExternalManager Protocol
UserManagement LDAP Server Port
OLD: User Role: ADMIN
UserManagement LDAP Encryption
NEW: User Role: ADMIN, USER
UserManagement LDAP MinimumTLSVersion
Provisioning HttpMethod
UserManagement LDAP VerifyServerCertificate OLD: User Role: ADMIN
UserManagement LDAP Admin Filter NEW: User Role: ADMIN, USER
UserManagement LDAP Admin Group Provisioning LoginName
OLD: User Role: ADMIN
UserManagement LDAP Attribute
NEW: User Role: ADMIN, USER
UserManagement LDAP BaseDN
Provisioning Mode
Configurations that are modified OLD: User Role: ADMIN
NEW: User Role: ADMIN, USER
NetworkServices NTP Server [1..3] Address
OLD: String (0, 64) Proximity Mode
NEW: String (0, 255) OLD: User Role: ADMIN
NEW: User Role: ADMIN, USER
NetworkServices SNMP Host [1..3] Address
OLD: String (0, 64) Proximity Services CallControl
NEW: String (0, 255) OLD: User Role: ADMIN
NEW: User Role: ADMIN, USER
Provisioning Connectivity
OLD: User Role: ADMIN Proximity Services ContentShare FromClients
NEW: User Role: ADMIN, USER OLD: User Role: ADMIN
NEW: User Role: ADMIN, USER
Provisioning ExternalManager Address
OLD: User Role: ADMIN Proximity Services ContentShare ToClients
NEW: User Role: ADMIN, USER OLD: User Role: ADMIN
NEW: User Role: ADMIN, USER
Provisioning ExternalManager AlternateAddress
OLD: User Role: ADMIN Time Zone
NEW: User Role: ADMIN, USER Change: The list of time zones is updated. The information in the value space is from the tz
database, also called the IANA Time Zone Database.
D15363.02 Cisco TelePresence DX70 and DX80 API Reference Guide CE8.2, SEPTEMBER 2016. 7 Copyright © 2016 Cisco Systems, Inc. All rights reserved.
Cisco TelePresence DX70 and DX80 API Reference Guide
UserInterface Language
OLD: Arabic / Catalan / ChineseSimplified / ChineseTraditional / Czech / Danish / Dutch /
English / Finnish / French / German / Hebrew / Hungarian / Italian / Japanese / Korean /
Norwegian / Polish / PortugueseBrazilian / Russian / Spanish / Swedish / Turkish
NEW: Arabic / Catalan / ChineseSimplified / ChineseTraditional / Czech / Danish / Dutch
/ English / Finnish / French / FrenchCanadian / German / Hebrew / Hungarian / Italian
/ Japanese / Korean / Norwegian / Polish / PortugueseBrazilian / Russian / Spanish /
Swedish / Turkish
Video Input Connector [n] InputSourceType
OLD: PC / camera / document_camera / mediaplayer / other / whiteboard
NEW: PC / camera / desktop / document_camera / mediaplayer / other / whiteboard
Video Input Connector [n] PresentationSelection
OLD: AutoShare / Manual / OnConnect
NEW: AutoShare / Desktop / Manual / OnConnect
D15363.02 Cisco TelePresence DX70 and DX80 API Reference Guide CE8.2, SEPTEMBER 2016. 8 Copyright © 2016 Cisco Systems, Inc. All rights reserved.
Cisco TelePresence DX70 and DX80 API Reference Guide
xCommand changes in CE8.2 Time DateTime Set
OLD: Role: <Admin>
New commands NEW: Role: <User;Admin>
Audio Select UserInterface Extensions Clear
Audio VuMeter Start OLD: Role: <Admin>
NEW: Role: <Admin;RoomControl>
Audio VuMeter Stop
UserInterface Extensions List
Audio VuMeter StopAll
OLD: Role: <User;Admin>
Security Session List
NEW: Role: <User;Admin;RoomControl>
Security Session Terminate
UserInterface Extensions Widget SetValue
OLD: Role: <Admin>
Commands that are modified
NEW: Role: <Admin;RoomControl>
Audio Volume Decrease
UserInterface Extensions Widget UnsetValue
NEW: Device: <Internal / HeadsetUSB / HandsetUSB>
OLD: Role: <Admin>
Audio Volume Set
NEW: Role: <Admin;RoomControl>
NEW: Device: <Internal / HeadsetUSB / HandsetUSB>
Audio Volume SetToDefault
NEW: Device: <Internal / HeadsetUSB / HandsetUSB>
Dial
OLD: Protocol: <H320 / Sip>
NEW: Protocol: <H320 / H323 / Sip / Spark>
Peripherals Connect
OLD: Role: <User;Admin>
NEW: Role: <User;Admin;RoomControl>
Peripherals HeartBeat
OLD: Role: <User;Admin>
NEW: Role: <User;Admin;RoomControl>
Peripherals Pairing Unpair
OLD: Role: <Admin>
NEW: Role: <User;Admin>
SystemUnit FactoryReset
OLD: Role: <Admin>
NEW: Role: <User;Admin>
D15363.02 Cisco TelePresence DX70 and DX80 API Reference Guide CE8.2, SEPTEMBER 2016. 9 Copyright © 2016 Cisco Systems, Inc. All rights reserved.
Cisco TelePresence DX70 and DX80 API Reference Guide
xStatus changes in CE8.2 H320GatewayStatus / H323GatekeeperStatus / HasValidReleaseKey / IpCameraStatus /
IPv4Assignment / IPv6Assignment / IPv6Mtu / ISDNLinkCompatibility / ISDNLinkIpStack
/ ITLinstallation / InvalidSIPTransportConfig / LockDown / RoomControl /
New statuses
MediaBlockingDetected / NetLinkStatus / NetSpeedAutoNegotiated / NetworkQuality
Audio Devices HandsetUSB ConnectionStatus / NTPStatus / OSDVideoOutput / OutputConnectorLocations / ProvisioningStatus /
SIPEncryption / SIPListenPortAndOutboundMode / SIPProfileRegistration / SIPProfileType
Audio Devices HandsetUSB Cradle
/ SelectedVideoInputSourceConnected / SipIceAndAnatConflict / TCPMediaFallback /
Audio Devices HeadsetAnalog ConnectionStatus TemperatureCheck / TLSVerifyRequiredCerts / TouchPanelConnection / TurnBandwidth
/ UdpPortRangeViolation / UltrasoundSpeakerAvailability / ValidPasswords /
Audio Devices HeadsetAnalog HasMicrophone VideoFromInternalCamera / VideoInputStability / SparkSoftwareCompatibility
/ SparkConnectivity / SpeakerTrackFrontPanelMountedCorrectly /
Audio Devices HeadsetUSB ConnectionStatus
SpeakerTrackMicrophoneConnection / SpeakerTrackVideoInputs /
Audio Devices HeadsetUSB Description SpeakerTrackEthernetConnection / ANATOnVCS / ECReferenceDelay / AudioPairingNoise /
AudioPairingRate / AudioPairingSNR / AudioPairingInterference / AudioPairingTokenDecode
Audio Devices HeadsetUSB Manufacturer
/ AudioInternalSpeakerDisabled / AbnormalCallTermination / HasActiveCallProtocol /
Audio SelectedDevice SipOrH323ButNotBothEnabled / PresentationSourceSelection / SoftwareUpgrade /
PlatformSanity / ContactInfoMismatch / ProximityContentShareToClientsWithMultistream>
Audio VolumeHandsetUsb
NEW: <CAPFOperationState / CTLinstallation / CUCMVendorConfigurationFile
Audio VolumeHeadsetAnalog / CallProtocolDualStackConfig / CallProtocolIPStackPlatformCompatibility /
CallProtocolVcsProvisioningCompatibility / CameraId / CameraPairing / CameraSerial
Audio VolumeHeadsetUsb
/ CameraSoftwareVersion / CameraStatus / CamerasDetected / ConfigurationFile /
Audio VolumeInternal DefaultCallProtocolRegistered / EthernetDuplexMatches / FanStatus / PresenterTrack /
H320GatewayStatus / H323GatekeeperStatus / HasValidReleaseKey / IpCameraStatus /
SystemUnit Hardware Module CompatibilityLevel
IPv4Assignment / IPv6Assignment / IPv6Mtu / ISDNLinkCompatibility / ISDNLinkIpStack
Video Layout LayoutFamily Local / ITLinstallation / InvalidSIPTransportConfig / LockDown / RoomControl /
MediaBlockingDetected / NetLinkStatus / NetSpeedAutoNegotiated / NetworkQuality
Video Layout LayoutFamily Remote / NTPStatus / OSDVideoOutput / OutputConnectorLocations / ProvisioningStatus /
SIPEncryption / SIPListenPortAndOutboundMode / SIPProfileRegistration / SIPProfileType
Statuses that are removed / SelectedVideoInputSourceConnected / SipIceAndAnatConflict / TCPMediaFallback /
TemperatureCheck / TLSVerifyRequiredCerts / TouchPanelConnection / TurnBandwidth
SystemUnit Software OptionKeys PremiumResolution / UdpPortRangeViolation / UltrasoundSpeakerAvailability / ValidPasswords /
VideoFromInternalCamera / VideoInputStability / SparkSoftwareCompatibility
Statuses that are modified / SparkConnectivity / SpeakerTrackFrontPanelMountedCorrectly /
SpeakerTrackMicrophoneConnection / SpeakerTrackVideoInputs /
Call [n] Protocol
SpeakerTrackEthernetConnection / ANATOnVCS / ECReferenceDelay / AudioPairingNoise /
OLD: <H320 / H323 / SIP / Spark> AudioPairingRate / AudioPairingSNR / AudioPairingInterference / AudioPairingTokenDecode
NEW: <Unknown / H320 / H323 / SIP / Spark> / AudioInternalSpeakerDisabled / AbnormalCallTermination / HasActiveCallProtocol /
SipOrH323ButNotBothEnabled / PresentationSourceSelection / SoftwareUpgrade /
Diagnostics Message [n] Type PlatformSanity / ContactInfoMismatch / MicrophoneReinforcement>NetworkServices NTP
OLD: <CAPFOperationState / CTLinstallation / CUCMVendorConfigurationFile Status
/ CallProtocolDualStackConfig / CallProtocolIPStackPlatformCompatibility / OLD: <Discarded / Synced / Unknown>
CallProtocolVcsProvisioningCompatibility / CameraId / CameraPairing / CameraSerial
NEW: <Discarded / Synced / NotSynced / Unknown>
/ CameraSoftwareVersion / CameraStatus / CamerasDetected / ConfigurationFile /
DefaultCallProtocolRegistered / EthernetDuplexMatches / FanStatus / PresenterTrack /
D15363.02 Cisco TelePresence DX70 and DX80 API Reference Guide CE8.2, SEPTEMBER 2016. 10 Copyright © 2016 Cisco Systems, Inc. All rights reserved.