Cisco TelePresence SX10 User manual

D15333.07 Cisco TelePresence SX10 API Reference Guide CE9.1, JUNE 2017. Copyright © 2017 Cisco Systems, Inc. All rights reserved.1
Cisco TelePresence SX10 API Reference Guide
Collaboration Endpoint Software 9.1
JUNE 2017
Application Programming Interface (API)
Reference Guide
Cisco TelePresence SX10
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus


D15333.07 Cisco TelePresence SX10 API Reference Guide CE9.1, JUNE 2017. Copyright © 2017 Cisco Systems, Inc. All rights reserved.2
Cisco TelePresence SX10 API Reference Guide
Table of ContentsWhat’s in this guide?
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/sx-docs
Introduction........................................................................... 3
About this guide......................................................................4
Downloading the user documentation .................................4
What’s new in CE9.1 ...............................................................5
What’s new in CE9.0...............................................................9
About the API...................................................................... 14
API fundamentals.................................................................. 15
Connecting to the API ........................................................ 15
Password............................................................................ 15
Telnet .................................................................................. 15
SSH .................................................................................... 15
HTTP/HTTPS ...................................................................... 15
Serial connection over micro USB ..................................... 16
API output ............................................................................. 17
The output modes.............................................................. 17
Using the command line ....................................................... 18
API commands ................................................................... 18
Other commands................................................................ 18
Command line shortcuts .................................................... 19
Searching ........................................................................... 19
Value types and formats..................................................... 19
Commands............................................................................20
Configurations.......................................................................20
Status....................................................................................20
Events ................................................................................... 21
Feedback mechanism...........................................................22
Feedback expressions .......................................................22
Terminal connections .........................................................23
Using HTTP...........................................................................24
HTTP XMLAPI Authentication.............................................24
HTTP XMLAPI Session Authentication...............................24
Getting status and configurations ......................................25
Sending commands and configurations.............................25
Using HTTP POST ..............................................................25
Feedback from codec over HTTP.........................................26
Registering for feedback ....................................................26
Translating from terminal mode to XML .............................27
Dos and don’ts......................................................................28
xConfiguration commands.................................................. 29
Description of the xConfiguration commands ......................30
xCommand commands .......................................................83
Description of the xCommand commands ...........................84
xStatus commands ........................................................... 127
Description of the xStatus commands................................ 128
Appendices....................................................................... 182
About startup scripts ..........................................................183
The SystemTools commands..............................................184
About disconnect cause types ...........................................186
User documentation on the Cisco web site........................ 187
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus


D15333.07 Cisco TelePresence SX10 API Reference Guide CE9.1, JUNE 2017. Copyright © 2017 Cisco Systems, Inc. All rights reserved.3
Cisco TelePresence SX10 API Reference Guide
Chapter 1
Introduction
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus

Introduction

D15333.07 Cisco TelePresence SX10 API Reference Guide CE9.1, JUNE 2017. Copyright © 2017 Cisco Systems, Inc. All rights reserved.4
Cisco TelePresence SX10 API Reference Guide
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 SX10 Quick Set
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.
Downloading the user documentation
You can download the user documentation from the Cisco
web site, go to: http://www.cisco.com/go/sx-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 theUser documentation on the
Cisco web site appendix.
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus

Introduction

D15333.07 Cisco TelePresence SX10 API Reference Guide CE9.1, JUNE 2017. Copyright © 2017 Cisco Systems, Inc. All rights reserved.5
Cisco TelePresence SX10 API Reference Guide
New features and improvements
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.
The system will wake to the Halfwake state when a user pairs
a Cisco Proximity client to the system.
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/collabo-
ration-endpoints/telepresence-quick-set-series/
products-release-notes-list.html
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus

Introduction

D15333.07 Cisco TelePresence SX10 API Reference Guide CE9.1, JUNE 2017. Copyright © 2017 Cisco Systems, Inc. All rights reserved.6
Cisco TelePresence SX10 API Reference Guide
System configuration changes in CE9.1
New configurations
None.
Configurations that are removed
None.
Configurations that are modified
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
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus

Introduction

D15333.07 Cisco TelePresence SX10 API Reference Guide CE9.1, JUNE 2017. Copyright © 2017 Cisco Systems, Inc. All rights reserved.7
Cisco TelePresence SX10 API Reference Guide
System command changes in CE9.1
New commands
SystemUnit FirstTimeWizard Stop
UserInterface Extensions Set
Commands that are removed
None.
Commands that are modified
SystemUnit FactoryReset (All products)
OLD: Keep: LocalSetup/Network/Spark/Provisioning
NEW: Keep: LocalSetup/Network/Spark/Provisioning/SerialPort/Certificates (not in use)
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus

Introduction

D15333.07 Cisco TelePresence SX10 API Reference Guide CE9.1, JUNE 2017. Copyright © 2017 Cisco Systems, Inc. All rights reserved.8
Cisco TelePresence SX10 API Reference Guide
System status changes in CE9.1
New statuses
None
Statuses that are removed
None
Statuses that are modified
Diagnostics Message Type
OLD: Value space: CAPFOperationState / CTLinstallation / CUCMVendorConfigurationFile
/ CallProtocolDualStackConfig / CallProtocolIPStackPlatformCompatibility /
CallProtocolVcsProvisioningCompatibility / 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 / SelectedVideoInputSourceConnected
/ SipIceAndAnatConflict / SIPListenPortAndRegistration / TCPMediaFallback
/ TemperatureCheck / TLSVerifyRequiredCerts / TouchPanelConnection
/ ControlSystemConnection / TurnBandwidth / UdpPortRangeViolation /
UltrasoundSpeakerAvailability / ValidPasswords / VideoFromInternalCamera
/ VideoInputStability / VideoInputSignalQuality / SparkConnectivity /
SpeakerTrackFrontPanelMountedCorrectly / 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 /
CallProtocolVcsProvisioningCompatibility / 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 / SelectedVideoInputSourceConnected / SipIceAndAnatConflict
/ SIPListenPortAndRegistration / TCPMediaFallback / TemperatureCheck /
TLSVerifyRequiredCerts / TouchPanelConnection / ControlSystemConnection
/ TurnBandwidth / UdpPortRangeViolation / UltrasoundSpeakerAvailability
/ ValidPasswords / VideoFromInternalCamera / VideoInputStability /
VideoInputSignalQuality / SparkConnectivity / SpeakerTrackFrontPanelMountedCorrectly
/ 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
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus

Introduction

D15333.07 Cisco TelePresence SX10 API Reference Guide CE9.1, JUNE 2017. Copyright © 2017 Cisco Systems, Inc. All rights reserved.9
Cisco TelePresence SX10 API Reference Guide
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 automati-
cally. 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.
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/collabo-
ration-endpoints/telepresence-quick-set-series/
products-release-notes-list.html
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus

Introduction

D15333.07 Cisco TelePresence SX10 API Reference Guide CE9.1, JUNE 2017. Copyright © 2017 Cisco Systems, Inc. All rights reserved.10
Cisco TelePresence SX10 API Reference Guide
System configuration changes in CE9.0
New configurations
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
UserInterface Language
NEW: Portuguese added to value space
xConfigurations with INTERATOR user role
A new user role - INTEGRATOR - is introduced in CE9.0. It has been added to the following
configurations:
Audio DefaultVolume
Audio Input Microphone [n] *
Audio Microphones Mute Enabled
Audio Output Line [n] *
Audio SoundsAndAlerts *
Cameras Camera [n] *
Conference DefaultCall Rate
Conference DoNotDisturb DefaultTimeout
Peripherals Profile *
SerialPort Mode
Standby *
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] Resolution
Video Presentation DefaultPIPPosition
Video Selfview Default *
Video Selfview OnCall *
<path> * means that the change applies to all configurations starting with <path>.
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus

Introduction

D15333.07 Cisco TelePresence SX10 API Reference Guide CE9.1, JUNE 2017. Copyright © 2017 Cisco Systems, Inc. All rights reserved.11
Cisco TelePresence SX10 API Reference Guide
System command changes in CE9.0
New commands
Audio Microphones ToggleMute
Audio Volume ToggleMute
Audio Sound Play
Audio Sound Stop
SystemUnit SignInBanner Clear
SystemUnit SignInBanner Get
SystemUnit SignInBanner 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
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
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus

Introduction

D15333.07 Cisco TelePresence SX10 API Reference Guide CE9.1, JUNE 2017. Copyright © 2017 Cisco Systems, Inc. All rights reserved.12
Cisco TelePresence SX10 API Reference Guide
System status changes in CE9.0
New statuses
Video Output Connector [n] ConnectedDevice CEC [n] Name
Video Output Connector [n] ConnectedDevice CEC [n] VendorId
Statuses that are modified
Diagnostics Message [n] Type
OLD: CAPFOperationState, CTLinstallation, CUCMVendorConfigurationFile,
CallProtocolDualStackConfig, CallProtocolIPStackPlatformCompatibility,
CallProtocolVcsProvisioningCompatibility, 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, SelectedVideoInputSourceConnected, SipIceAndAnatConflict,
TCPMediaFallback, TemperatureCheck, TLSVerifyRequiredCerts, TouchPanelConnection,
ControlSystemConnection, TurnBandwidth, UdpPortRangeViolation,
UltrasoundSpeakerAvailability, ValidPasswords, VideoFromInternalCamera,
VideoInputStability, SparkConnectivity, SpeakerTrackFrontPanelMountedCorrectly,
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,
CallProtocolVcsProvisioningCompatibility, 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, SelectedVideoInputSourceConnected, SipIceAndAnatConflict,
SIPListenPortAndRegistration, TCPMediaFallback, TemperatureCheck,
TLSVerifyRequiredCerts, TouchPanelConnection, ControlSystemConnection,
TurnBandwidth, UdpPortRangeViolation, UltrasoundSpeakerAvailability, ValidPasswords,
VideoFromInternalCamera, VideoInputStability, VideoInputSignalQuality, SparkConnectivity,
SpeakerTrackFrontPanelMountedCorrectly, 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 Input Connectors Microphone[n] ConnectionStatus
Audio Microphones Mute
Audio Output Connectors Line[n] DelayMs
Audio Volume
Call[n] FacilityServiceId
Call[n] ReceiveCallRate
Call[n] TransmitCallRate
Cameras 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
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus

Introduction

D15333.07 Cisco TelePresence SX10 API Reference Guide CE9.1, JUNE 2017. Copyright © 2017 Cisco Systems, Inc. All rights reserved.13
Cisco TelePresence SX10 API Reference Guide
Cameras Camera[n] SerialNumber
Cameras Camera[n] SoftwareIDConference DoNotDisturb
Conference Presentation CallId
Conference Presentation LocalInstance[n] SendingMode
Conference Presentation LocalInstance[n] Source
Conference Presentation Mode
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
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus

Introduction

D15333.07 Cisco TelePresence SX10 API Reference Guide CE9.1, JUNE 2017. Copyright © 2017 Cisco Systems, Inc. All rights reserved.14
Cisco TelePresence SX10 API Reference Guide
Chapter 2
About the API
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus

About the API

D15333.07 Cisco TelePresence SX10 API Reference Guide CE9.1, JUNE 2017. Copyright © 2017 Cisco Systems, Inc. All rights reserved.15
Cisco TelePresence SX10 API Reference Guide
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.
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:
<Off,On>
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:
<Off,On>
HTTP/HTTPS
As HTTP/HTTPS are connectionless protocols, there is no
persistent connection. There are several ways of communi-
cating with the API over HTTP.
In order to enable or disable the HTTP and HTTPS services,
configure the following setting on the codec.
xConfiguration NetworkServices HTTP Mode:
<Off, HTTP+HTTPS, HTTPS>
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 24 in this document.
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus

About the API

D15333.07 Cisco TelePresence SX10 API Reference Guide CE9.1, JUNE 2017. Copyright © 2017 Cisco Systems, Inc. All rights reserved.16
Cisco TelePresence SX10 API Reference Guide
Serial connection over micro USB
You can use the micro USB connector for direct communica-
tion with the video system. You may need to install a serial
port driver on your computer manually.
The serial connection can be used without an IP address,
DNS or a network. Serial connection is allowed by default.
xConfiguration SerialPort Mode: <Off/On>
Baud-rate and other serial port parameters
The serial port uses 115200 bps, 8 data bits, no parity and 1
stop bit.
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 LoginRequired: <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.
INTEGRATOR: 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 INTEGRATOR and
ROOMCONTROL user roles are available.
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus

About the API

D15333.07 Cisco TelePresence SX10 API Reference Guide CE9.1, JUNE 2017. Copyright © 2017 Cisco Systems, Inc. All rights reserved.17
Cisco TelePresence SX10 API Reference Guide
Example: Layout command in terminal mode
xCommand Audio Volume Set Level: 50
API output
The xPreferences is used to set preferences for the RS-232,
Telnet and SSH sessions.
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
Example: Layout command in XML mode
<Command>
<Audio>
<Volume>
<Set command=”True”>
<Level>50</Level>
</Set>
</Volume>
</Audio>
</Command>
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus

About the API

D15333.07 Cisco TelePresence SX10 API Reference Guide CE9.1, JUNE 2017. Copyright © 2017 Cisco Systems, Inc. All rights reserved.18
Cisco TelePresence SX10 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.
Example 1:
?
- User Commands -
help xcommand xconfiguration xevent xfeedback
xgetx
ml xdocument xpreferences xtransaction xstatus
bye echo log systemtools
OK
API commands
xConfiguration
Configurations are system settings, such as system name
and network settings. These are persistent across boots.
Refer to ”Configurations” on page 20.
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 20.
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 20.
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 22.
xPreferences
The xPreferences command is used to set preferences for
the RS-232, Telnet and SSH sessions.
Refer to ”API output” on page 17.
Echo <on/off>
If echo is set to On the key inputs are displayed when enter-
ing 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 21.
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 22.
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 184.
Log
The log command is used to enable advanced logs. It is only
used for debugging the system.
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus

About the API

D15333.07 Cisco TelePresence SX10 API Reference Guide CE9.1, JUNE 2017. Copyright © 2017 Cisco Systems, Inc. All rights reserved.19
Cisco TelePresence SX10 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 fig u r a t io n //o ut// 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 at 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 neces-
sary for values without spaces.
Example:
Correct: xCommand dial number: “my number contains
spaces”
Correct: xCommand dial number: 12345
Incorrect: xCommand dial number: my number contains
spaces
Case sensitivity
All commands are case-insensitive. All of the following
commands will work.
XCOMMAND DIAL NUMBER: [e-mail]
xcommand dial number: [e-mail]
xCommand Dial Number: [e-mail]
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus

About the API

D15333.07 Cisco TelePresence SX10 API Reference Guide CE9.1, JUNE 2017. Copyright © 2017 Cisco Systems, Inc. All rights reserved.20
Cisco TelePresence SX10 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 configu-
ration paths.
Example: Set the H323 Alias ID
Write in:
xConfiguration H323 Profile 1 H323Alias ID:
“[e-mail]”
Example: Get the H323 Alias ID
Write in:
xConfiguration H323 Profile 1 H323Alias ID
Result:
*c xConfiguration H323 Profile 1 H323Alias ID:
“[e-mail]”
**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>
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus

About the API