Cisco Quick Set C20 User manual

D14869.05 Codec C20 API Reference Guide TC6.0 February 2013. Copyright © 2010–2013 Cisco Systems, Inc. All rights reserved. 1
Cisco TelePresence System Codec C20 API Reference Guide
Software version TC6.0
Februar y 2013
Application Programmer Interface (API)
Reference Guide
Cisco TelePresence System Codec C20
Contents
Introduction
About the API
xConguration
Appendices
xCommand
xStatus

D14869.05 Codec C20 API Reference Guide TC6.0 February 2013. Copyright © 2010–2013 Cisco Systems, Inc. All rights reserved. 2
Cisco TelePresence System Codec C20 API Reference Guide
TA - ToC - Hidden
text anchor
Table of Contents
Introduction
About this guide .................................................................. 4
User documentation ........................................................ 4
What’s new in this version .................................................. 5
Software release notes ................................................... 5
Software download ......................................................... 5
New features and improvements .................................... 5
xCommand changes ....................................................... 7
xStatus changes.............................................................. 8
About the API
API fundamentals .............................................................. 10
Connecting to the API ................................................... 10
Password....................................................................... 10
RS-232/serial connection.............................................. 10
Telnet ............................................................................. 10
SSH................................................................................ 10
HTTP/HTTPS ................................................................. 10
API output...........................................................................11
The output modes ..........................................................11
Using the command line ....................................................12
API commands ...............................................................12
Other commands............................................................12
Command line shortcuts ................................................12
Searching .......................................................................13
Value types and formats.................................................13
Commands.........................................................................14
Congurations................................................................... 15
Status ................................................................................ 16
Events.................................................................................17
Example 1: Outgoing Call Indication ..............................17
Example 2: Call Disconnect ...........................................17
Example 3: Call Successful ............................................17
Example 4: FECC Action request ...................................17
Call history......................................................................... 18
Feedback mechanism ....................................................... 19
Feedback expressions .................................................. 19
Terminal connections .................................................... 20
Using HTTP ....................................................................... 21
Getting status and congurations ................................. 21
Sending commands and congurations........................ 21
Using HTTP POST ......................................................... 21
Feedback from codec over HTTP..................................... 22
Registering for feedback ............................................... 22
Translating from terminal mode to XML ........................ 23
Dos and don’ts .................................................................. 24
Description of the xConguration commands
Description of the xConguration commands .................. 26
Description of the xCommand commands
Description of the xCommands commands...................... 69
Description of the xStatus commands
Description of the xStatus commands ............................ 103
Appendices
Startup script................................................................... 164
Adding a startup script ................................................ 164
Cisco TelePresence Remote Control .............................. 165
Remote control key map ................................................. 166
The SystemTools commands .......................................... 167
About disconnect cause types ....................................... 169
What’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/telepresence/docs
Contents
Introduction
About the API
xConguration
Appendices
xCommand
xStatus
ContentsContents

D14869.05 Codec C20 API Reference Guide TC6.0 February 2013. Copyright © 2010–2013 Cisco Systems, Inc. All rights reserved. 3
Cisco TelePresence System Codec C20 API Reference Guide
Chapter 1
Introduction
Contents
Introduction
About the API
xConguration
Appendices
xCommand
xStatus
Introduction

D14869.05 Codec C20 API Reference Guide TC6.0 February 2013. Copyright © 2010–2013 Cisco Systems, Inc. All rights reserved. 4
Cisco TelePresence System Codec C20 API Reference Guide
About this guide
This guide introduces you to the Application Programmer Interface
(API) for the TC software in general, and serve as a reference
guide for the command line commands for the Codec C Series
listed below:
• Cisco TelePresence System Codec C20
User documentation
The user documentation for the Cisco TelePresence systems,
running the TC software, have several guides suitable to vari-
ous user groups.
• Video conference room primer
• Video conference room acoustics guidelines
• Installation guides for the TelePresence systems
• Software release notes for the TC software
• Getting started guide for the TelePresence systems
• User guide for the TelePresence systems (Touch controller)
• User guide for the TelePresence systems (Remote Control)
• Quick reference guides for the TelePresence systems
• Administrator guides for the TelePresence systems
• Camera user guide for the PrecisionHD cameras
• API reference guides for the Codec C Series
• TC Console user guide for the Codec C Series
• Physical interfaces guides for the Codec C Series
• Regulatory compliance and safety information guides
• Legal & license information for the TC software
To download the user documentation go to:
http://www.cisco.com/go/quickset-docs
Contents
Introduction
About the API
xConguration
Appendices
xCommand
xStatus
Introduction

D14869.05 Codec C20 API Reference Guide TC6.0 February 2013. Copyright © 2010–2013 Cisco Systems, Inc. All rights reserved. 5
Cisco TelePresence System Codec C20 API Reference Guide
What’s new in this version
This section provides an overview of the new and changed advanced
settings and new features in the TC6.0 software version.
Software release notes
For a complete overview of the news and changes, we recom-
mend reading the Software Release Notes (TC6).
Go to: http://www.cisco.com/en/US/products/ps11424/prod_
release_notes_list.html
Software download
For software download go to:
http://www.cisco.com/cisco/software/navigator.html
New features and improvements
Administrator password not set warning on OSD
If the administrator password is not set, there is an on screen
warning in the lower right corner indicating this. The warning
disappears when the password is set.
Improved video layout
Improved local layout control when using the Touch controller
Improved local layout control when using the Touch controller.
You can easily choose between the layout options using the
Touch controller. Each option is illustrated by an icon reecting
the actual layout.
You can choose between the predened layout options as well as
any custom layouts that have been created for this TelePresence
system (for example created with the TC Console application).
Picture-in-Picture support
There is support for showing Picture-in-Picture (PIP), for example
showing full-screen presentation with both remote video and
self-view as PIP.
The PIPs can be moved to predened drop zones, typically upper
right, upper left, lower right etc. When using a Touch controller
you can see the drop zones as you start moving the PIP.
Full screen self-view
Full screen self-view while in call is supported on dual monitor
systems.
ISDN Link support
You can pair a TelePresence system with a Cisco TelePresence
ISDN Link. As from software versions TC6.0 and IL1.1 automatic
pairing mode is supported.
When making a call via ISDN Link, choose H320 (ISDN) as the
call protocol.
Secure communication in a CUCM environment
As from version TC5 endpoints running TC software can register
to a Cisco Unied Communications Manager (CUCM) version
8.6.2 or newer. In TC6.0 this feature is extended to also include
secure (encrypted) connections. The encryption indicator is
shown on the on-screen interface during a call.
This feature requires that security mode is installed and cong-
ured on CUCM. Read the Administering TC Endpoints on CUCM
9.0 guide to nd how to set up this feature.
Support for SIP URI dialing when registered to CUCM
As from Cisco Unied Communications Manager (CUCM) version
9.0, endpoints registered to CUCM support URI dialing. A URI is
an alias for a directory number (DN). A call to the URI behaves
as if the call was made directly to the directory number.
URI example: [e-mail]. The user name
(left side) is case sensitive in CUCM 9.0, while the domain (right
side) is not.
Support for encrypted Cisco TelePresence Multipoint Switch
(CTMS) calls
Video systems running software TC5.0 or later are able to initi-
ate or join non-encrypted multiparty conferences controlled by
CTMS version 1.8 or later. Encrypted conferences are supported
as from software versions TC6.0 and CTMS 1.9.1.
The TelePresence system must have a secure registration to
VCS or CUCM to allow encrypted calls.
Contents
Introduction
About the API
xConguration
Appendices
xCommand
xStatus
Introduction

D14869.05 Codec C20 API Reference Guide TC6.0 February 2013. Copyright © 2010–2013 Cisco Systems, Inc. All rights reserved. 6
Cisco TelePresence System Codec C20 API Reference Guide
Localization
The following new languages are supported on the Cisco
TelePresence Touch:
• Traditional Chinese
• Portuguese Brazilian
• Turkish
• Czech
• Polish
• Dutch
• Hungarian
• Italian
• Korean
Troubleshooting and diagnostics
A new troubleshooting feature introduced. The TelePresence
system runs a set of tests to detect possible problems and
provides links on the web interface to resolve the issues.
The Mediatrace diagnostics tool
Mediatrace is a diagnostic tool that discovers the routers and
switches (layer 2 and 3 devices) long the path of an IP ow.
It collects critical information hop by hop on specic media
streams as they traverse the network. Mediatrace should be
enabled on each network node you want to collect informa-
tion from. Because the path of video data packets from the
endpoints is traced, troubleshooting is facilitated and network
performance can be optimized.
Advanced configuration changes
New settings
xConfiguration Conference DoNotDisturb DefaultTimeout
xConfiguration Conference MaxTotalTransmitCallRate
xConfiguration Conference MaxTotalReceiveCallRate
xConfiguration Conference Presentation OnPlacedOnHold
xConfiguration Network QoS Diffserv ICMPv6
xConfiguration Network QoS Diffserv NTP
xConfiguration NetworkServices CTMS Mode
xConfiguration NetworkServices CTMS Encryption
xConfiguration NetworkServices XMLAPI Mode
xConfiguration SIP ListenPort
xConfiguration Video SelfviewDefault Mode
xConfiguration Video SelfviewDefault FullscreenMode
xConfiguration Video SelfviewDefault PIPPosition
xConfiguration Video SelfviewDefault OnMonitorRole
xConfiguration Video PIP ActiveSpeaker DefaultValue Position
xConfiguration Video PIP Presentation DefaultValue Position
xConfiguration Video Input Source[1..n] PresentationSelection
xConfiguration Video Input HDMI[1..n] RGBQuantizationRange
xConfiguration Video Input DVI[x, y] RGBQuantizationRange
xConfiguration Video Output HDMI[x, y] RGBQuantizationRange
xConfiguration Video OSD MenuStartupMode
xConfiguration Video OSD VirtualKeyboard
xConfiguration Video OSD EncryptionIndicator
xConfiguration Video OSD MissedCallsNotification
Settings that are removed
xConfiguration Network DNS Server[4, 5] Address
xConfiguration SystemUnit Type
Settings that are modified
xConfiguration Cameras PowerLine Frequency
OLD: <Auto/50Hz/60Hz>
NEW: <50Hz/60Hz>
xConfiguration Conference DefaultCall Protocol
OLD: <H323/Sip>
NEW: <H323/Sip/H320>
xConfiguration Network IPv6 Assignment
OLD: <Static/Autoconf>
NEW: <Static/DHCPv6/Autoconf>
xConfiguration SystemUnit ContactInfo Type
OLD: <Auto/None/IPv4/IPv6/H323Id/E164Alias/SipUri/
SystemName>
NEW: <Auto/None/IPv4/IPv6/H323Id/E164Alias/
H320Number/SipUri/SystemName/DisplayName>
xConfiguration UserInterface TouchPanel DefaultPanel
OLD: <ContactList/MeetingList>
NEW: <ContactList/MeetingList/Dialpad>
xConfiguration Video SelfviewPosition
OLD: <UpperLeft/UpperRight/CenterRight/LowerLeft/
LowerRight>
NEW: <UpperLeft/UpperCenter/UpperRight/CenterLeft/
CenterRight/LowerLeft/LowerRight>
xConfiguration Video Layout LocalLayoutFamily
OLD: <Auto/FullScreen/Equal/PresentationSmallSpeaker/
PresentationLargeSpeaker>
NEW: <Auto/FullScreen/Equal/PresentationSmallSpeaker/
PresentationLargeSpeaker/Prominent/Overlay/Single>
Contents
Introduction
About the API
xConguration
Appendices
xCommand
xStatus
Introduction

D14869.05 Codec C20 API Reference Guide TC6.0 February 2013. Copyright © 2010–2013 Cisco Systems, Inc. All rights reserved. 7
Cisco TelePresence System Codec C20 API Reference Guide
xConfiguration Video Layout RemoteLayoutFamily
OLD: <Auto/FullScreen/Equal/PresentationSmallSpeaker/
PresentationLargeSpeaker>
NEW: <Auto/FullScreen/Equal/PresentationSmallSpeaker/
PresentationLargeSpeaker/Prominent/Overlay/Single>
xConfiguration Video Input Source[1..n] OptimalDefinition
Threshold60fps
OLD: <512_288/768 _448/1024_576/1280_720/Never>
NEW: <512_288/768 _448/1024_576/1280_720/
1920_1080/Never>
xCommand changes
New commands
xCommand Call UnattendedTransfer
xCommand Conference ActiveSpeaker Reset
xCommand Conference ActiveSpeaker Set
xCommand Provisioning CUCM CAPF OperationStart
xCommand Provisioning CUCM CTL Delete
xCommand SystemUnit Diagnostics Run
xCommand SystemUnit OptionKey RemoveAll
xCommand SystemUnit ReleaseKey RemoveAll
xCommand Video OSD Close
xCommand Video PIP ActiveSpeaker Set
xCommand Video PIP Presentation Set
xCommand Video Selfview Set
Commands that are modied
xCommand Audio VUMeter Start
OLD: xCommand Audio VUMETER Start
NEW: xCommand Audio VUMeter Start
xCommand Audio VUMeter Stop
OLD: xCommand Audio VUMETER Stop
NEW: xCommand Audio VUMeter Stop
xCommand Audio VUMeter StopAll
OLD: xCommand Audio VUMETER StopAll
NEW: xCommand Audio VUMeter StopAll
XCommand Call Accept
ADDED: CallType(o): <Audio/Video>
xCommand CamCtrlPip
ADDED: Duration: <0..60>
xCommand Dial
OLD: Protocol: <H323/SIP>
NEW: Protocol: <SIP/H323/H320>
xCommand Phonebook Contact Add
OLD: Protocol: <H323/SIP>
NEW: Protocol: <SIP/H323/H320>
xCommand Phonebook ContactMethod Add
OLD: Protocol: <H323/SIP>
NEW: Protocol: <SIP/H323/H320>
xCommand Phonebook ContactMethod Modify
OLD: Protocol: <H323/SIP>
NEW: Protocol: <SIP/H323/H320>
xCommand Presentation Start
ADDED: SendingMode: <LocalRemote/LocalOnly>
xCommand Video Layout Frame Add
OLD: PositionX (r)<0..10000>, PositionY (r)<0..10000>,
Layer (r)<1..5>, Height (r)<1..10000>, Width (r)<1..10000>
VideoSourceType (r)<graphic/localInput/localMain/localPre-
sentation/mostSpeaking/otherMain/ownMain/presentation/
remoteMain/remotePresentation/videoFile>
NEW: PositionX (o)<0..10000>, PositionY (o)<0..10000>,
Layer (o)<1..5>, Height (o)<1..10000>, Width (o)<1..10000>
VideoSourceType (o)<graphic/localInput/localMain/localPre-
sentation/mostSpeaking/otherMain/ownMain/presentation/
remoteMain/remotePresentation/videoFile>
xCommand Video PictureLayoutSet
OLD: LayoutFamily(r): <auto/custom/equal/fullscreen/
presentationlargespeaker/presentationsmallspeaker/
speaker_full>
NEW: LayoutFamily(r): <auto/custom/equal/fullscreen/
overlay/presentationlargespeaker/presentationsmallspeaker/
prominent/single/speaker_full>
Contents
Introduction
About the API
xConguration
Appendices
xCommand
xStatus
Introduction

D14869.05 Codec C20 API Reference Guide TC6.0 February 2013. Copyright © 2010–2013 Cisco Systems, Inc. All rights reserved. 8
Cisco TelePresence System Codec C20 API Reference Guide
xStatus changes
New commands
xStatus Call SecurityStatus
xStatus Conference ActiveSpeaker Mode
xStatus Conference ActiveSpeaker SiteId
xStatus Conference Presentation LocalSendingMode
xStatus Conference Presentation LastLocalSource
xStatus Conference Site SecurityStatus
xStatus H320 Gateway Status
xStatus H320 Gateway Address
xStatus H320 Gateway Number
xStatus H320 Gateway Mode
xStatus H320 Gateway Reason
xStatus H320 Gateway Id
xStatus Network VLAN Native VlanId
xStatus Network CDP Platform
xStatus Network CDP Version
xStatus Network CDP Capabilities
xStatus Network CDP DeviceId
xStatus Network CDP PortID
xStatus Network CDP Duplex
xStatus Network CDP VTPMgmtDomain
xStatus Network CDP Address
xStatus Network CDP PrimaryMgmtAddress
xStatus Network CDP SysName
xStatus Network CDP SysObjectID
xStatus Network CDP VoIPApplianceVlanID
xStatus NetworkServices NTP Address
xStatus Provisioning CUCM CAPF Mode
xStatus Provisioning CUCM CAPF ServerName
xStatus Provisioning CUCM CAPF ServerPort
xStatus Provisioning CUCM CAPF LSC
xStatus Provisioning CUCM CAPF OperationState
xStatus Provisioning CUCM CAPF OperationResult
xStatus Provisioning CUCM ProvisionSecurity
xStatus Provisioning CUCM CTL State
xStatus SystemUnit Hardware TemperatureThreshold
xStatus SystemUnit Diagnostics LastRun
xStatus SystemUnit Diagnostics Message Type
xStatus SystemUnit Diagnostics Message Level
xStatus Video Layout Site Output Frame VideoSourceContent
xStatus Video Selfview Mode
xStatus Video Selfview FullscreenMode
xStatus Video Selfview PIPPosition
xStatus Video Selfview OnMonitorRole
xStatus Video PIP ActiveSpeaker Position
xStatus Video PIP Presentation Position
Commands that are modied
xStatus Conference Multipoint Mode
OLD: Valuespace: <O/MultiWay/MultiSite>
NEW: Valuespace: <O/MultiWay/MultiSite/Auto>
Contents
Introduction
About the API
xConguration
Appendices
xCommand
xStatus

D14869.05 Codec C20 API Reference Guide TC6.0 February 2013. Copyright © 2010–2013 Cisco Systems, Inc. All rights reserved. 9
Cisco TelePresence System Codec C20 API Reference Guide
Chapter 2
About the API
Contents
Introduction
About the API
xConguration
Appendices
xCommand
xStatus
About the API

D14869.05 Codec C20 API Reference Guide TC6.0 February 2013. Copyright © 2010–2013 Cisco Systems, Inc. All rights reserved. 10
Cisco TelePresence System Codec C20 API Reference Guide
API fundamentals
This chapter contains a top-level view of the mechanisms
supported by the codec API. You can use the API to manage
all parts of the TelePresence system.
Here you can read about how to access the API, how to use
the command line and what the dierent parts of the API can
be used for. Information on how to use the feedback functions
that are available for the codec is included in this chapter.
The API consists of four major groups:
• Commands
• Congurations
• Status
• Events
These four groups are hierarchically organized, which makes it
easier to nd related functionality. You can nd the complete
lists of all commands, congurations and statuses in the follow-
ing 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 suites your applica-
tion best. Before you start, please read this section about the
dierent methods, as some of those may require additional
conguration changes before being enabled.
The following commands can be set from the System congura-
tion menu in the web interface or on the on-screen-diplay, or
from the command line interface. All of the examples are for
the command line interface.
Password
Initially, no password is set for the default admin user. We
strongly recommend that you set a password for this user, and
any other users possessing an ADMIN role, to restrict access
to system conguration. The password can be changed by
issuing the following command:
xCommand SystemUnit AdminPassword Set Password:
<password>
RS-232/serial connection
This is one of the most used connections to our products for
integrators, as it can be used without an IP-address, DNS or
a network.
Codec congurations
There are two dierent congurations that can be changed for
serial connections; the baud-rate and whether login is required
or not. A reboot of the codec is required for these settings to
take eect.
xConguration SerialPort BaudRate:
<9600/19200/38400/57600/115200>
xConguration SerialPort LoginRequired: <Off/
On>
Connecting
For the C20 codec you need to use a Y-cable to connect to
the Camera port.
NOTE:
• For security reasons the password prompting is turned on
by default, but it can be turned o if preferred.
•
The default baud rate is set to 38400. The reason for this is
that the codec can give very much feedback. When using
9600 baud it may cause your integration to appear sluggish.
We therefore recommend keeping the connection at this
speed or higher.
•
During the initial boot sequence, the codec uses a baud rate
of 38400 regardless of the application baud rate you have set.
For details regarding the RS-232 pin-out and more, please
refer to theAdministrator Guide.
Telnet
Telnet can be viewed as the equivalent of the serial protocol in
the TCP/IP world. Telnet is disabled by default. Before connect-
ing to the codec with Telnet you have to enable it.
Codec conguration
To enable Telnet service, congure 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 eect.
xConguration NetworkServices Telnet Mode: 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.
HTTP/HTTPS
As HTTP/HTTPS are connectionless protocols, there is no
persistent connection. There are several ways of communicating
with the API over HTTP.
Codec conguration
In order to enable or disable the HTTP and HTTPS services,
congure the following settings on the codec. Changing these
settings requires a reboot of the device.
xConguration NetworkServices HTTP Mode:
<Off/On>
xConguration NetworkServices HTTPS Mode:
<Off/On>
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 inter-
face, you can nd the API documents under the menu section
System Conguration > API > XML API. The HTTP POST and
GET methods are used to execute commands and get feedback
from the codec. This is described in the “Using HTTP” section
later in this document.
Contents
Introduction
About the API
xConguration
Appendices
xCommand
xStatus
About the API

D14869.05 Codec C20 API Reference Guide TC6.0 February 2013. Copyright © 2010–2013 Cisco Systems, Inc. All rights reserved. 11
Cisco TelePresence System Codec C20 API Reference Guide
Example: Layout command in terminal mode
xCommand Video Layout AssignCall CallId: 2 LayoutId: 1
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 under-
stand XML.
The default output mode is terminal. To change this you have to
dene your preferences for each session individually. Examples
in this guide are in terminal mode.
To set ouput 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
<Command>
<Video>
<Layout>
<AssignCall command=”True”>
<CallId>2</CallId>
< Lay outId >1</L ay outId >
</AssignCall>
</Layout>
</Video>
</Command>
Contents
Introduction
About the API
xConguration
Appendices
xCommand
xStatus
About the API

D14869.05 Codec C20 API Reference Guide TC6.0 February 2013. Copyright © 2010–2013 Cisco Systems, Inc. All rights reserved. 12
Cisco TelePresence System Codec C20 API Reference Guide
Using the command line
Help
To get a list of all supported root commands you can type ?
or help after connecting to the TelePresence System using
RS-232, Telnet or SSH.
Bye
Typing the bye command closes the command line interface.
API commands
xConguration
Congurations are system settings, such as system name and
network settings. These are persistent across boots. For more
information see ”Congurations”.
xCommand
Commands instruct the codec to execute actions, such as to
dial a number or to search the phone book. For more informa-
tion see ”Commands”.
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. For more information
see ”Status”.
xFeedback
The Feedback commands are used to specify what parts of
the conguration and status hierarchies to monitor. Feedback
is only issued on the RS-232, Telnet or SSH session for which
it is specied. If you are connecting to the codec with multiple
sessions, you have to dene feedback individually for each
session. For more information see ”Feedback mechanism”.
xPreferences
The xPreferences command is used to set preferences for the
RS-232, Telnet and SSH sessions. For more information see
”API output”.
Echo <on/o>
If echo is set to On the key inputs are displayed when entering
text in a command line interface.
If echo is set to O no user input is displayed when entering
text in a command line interface.
xEvent
the xEvent command returns information on which events are
available for feedback. For more information see ”Events”.
xHistory
The xHistory command returns the call log.
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.
For more information see ”Using HTTP”.
Other commands
Systemtools
The systemtools commands are used for administrative control
of the codec and are only available from the command line
interface. Systemtools are not a part of the programming API.
For more information see ”The SystemTools commands” in
the Appendices chapter.
Log
The log command is used to enable advanced logs. It is only
used for debugging the system.
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.
• < C T R L- a > :Jump to the beginning of the line.
• < C T R L- e > :Jump to the end of the line.
• < C T R L- r > :Incremental command history search.
• < C T R L- w > : Erase the current line.
?
- User Commands -
help
xstatus
bye
xconguration
xevent
log
xfeedback
xpreferences
echo
xgetxml
xcommand
xhistory
systemtools
OK
Contents
Introduction
About the API
xConguration
Appendices
xCommand
xStatus
About the API

D14869.05 Codec C20 API Reference Guide TC6.0 February 2013. Copyright © 2010–2013 Cisco Systems, Inc. All rights reserved. 13
Cisco TelePresence System Codec C20 API Reference Guide
Searching
You can use // to search for elements anywhere in the status
or conguration hierarchy (Example 1).
You can also combine multiple //’s (Example 2).
WARNING: 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 rmware releases.
Value types and formats
The system supports the following value types (Example 3):
• Integer values: <x..y>
Denes the valid range for an integer input. x = min value,
y = max value.
• Literal values: <X/Y/../Z>
Denes the possible values for a given conguration.
• String values: <S: x, y>
Denes that the valid input for this conguration 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 congurations and commands containing spaces
must be enclosed in quotes. Quotes are not necessary for
values without spaces.
Examples:
Correct: xCom mand dial num b er: “my num ber contains
spaces”
Correct: xCommand dial number: 12345
Incorrect: xCom m and dial num ber: my num ber 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]
Example 1: List all congurations that include a word that starts with DVI:
xConguration //dvi
*c xConguration Video Input DVI 3 Type: AutoDetect
*c xConguration Video Input DVI 5 Type: AutoDetect
*c xConguration Video Output DVI 2 Resolution: 1366 _ 768 _ 60
*c xConguration Video Output DVI 2 OverscanLevel: None
*c xConguration Video Output DVI 2 MonitorRole: Second
*c xConguration Video Output DVI 4 Resolution: Auto
*c xConguration Video Output DVI 4 OverscanLevel: None
*c xConguration Video Output DVI 4 MonitorRole: Fourth
** 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 Input Source 5 Resolution Width: 0
*s Video Output HDMI 1 Resolution Width: 1366
*s Video Output HDMI 3 Resolution Width: 1366
*s Video Output DVI 2 Resolution Width: 1366
*s Video Output DVI 4 Resolution Width: 1024
*s Video Output Legacy 5 Resolution Width: 720
** end
Example 3: Value types and formats
xConguration ??
*? xConguration Audio Microphones Mute Enabled: <True/InCallOnly>
*? xConguration Audio Volume: <0..100>
.
.
.
*? xConguration SystemUnit Name: <S: 0, 50>
Contents
Introduction
About the API
xConguration
Appendices
xCommand
xStatus
About the API

D14869.05 Codec C20 API Reference Guide TC6.0 February 2013. Copyright © 2010–2013 Cisco Systems, Inc. All rights reserved. 14
Cisco TelePresence System Codec C20 API Reference Guide
xCommand ??
xCommand Audio Microphones Mute
xCommand Audio Microphones Unmute
xCommand Audio Sound Play
Sound(r): <Busy/CallWaiting/Dial/KeyTone/Ringing/SpecialInfo/TelephoneCall/VideoCall>
Loop: <On/Off>
xCommand Audio Sound Stop
xCommand Bookings List
Days: <1..365>
DayOffset: <0..365>
Limit: <1..65534>
Offset: <0..65534>
xCommand Bookings Clear
xCommand Boot
Action: <Restart/Shutdown>
.
.
.
OK
xCommand ?
– User Commands –
Audio
Bookings
Boot
Call
CallLog
CamCtrlPip
Camera
Conference
Dial
DTMFSend
Experimental
FacilityService
FarEndControl
HttpFeedback
Key
Message
Phonebook
Presentation
Preset
Provisioning
Security
Standby
SystemUnit
Video
OK
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 prex 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. The (r) behind the
argument name indicates that the argument is required for the
command.
When issuing a xCommand, the command consists of one
argument and one required parameter:
Example: xCommand Dial Number: 123
1.
xCommand is the command prex. The command to be
executed is Dial.
2.
The example contains one argument, Number: 123. Number
is the key and 123 is its value. The key/value pair is sepa-
rated with ‘:’.
Contents
Introduction
About the API
xConguration
Appendices
xCommand
xStatus
About the API

D14869.05 Codec C20 API Reference Guide TC6.0 February 2013. Copyright © 2010–2013 Cisco Systems, Inc. All rights reserved. 15
Cisco TelePresence System Codec C20 API Reference Guide
xConguration ??
*? xConguration Audio Microphones Mute Enabled: <True/InCallOnly>
*? xConguration Audio Volume: <0..100>
*? xConguration Audio SoundsAndAlerts RingVolume: <0..100>
*? xConguration Audio SoundsAndAlerts RingTone: <Marbles/IceCrystals/Polaris/Alert/Discreet/Fantasy/
Jazz/Nordic/Echo/Rhythmic>
*? xConguration Audio SoundsAndAlerts KeyTones Mode: <Off/On>
*? xConguration Cameras PowerLine Frequency: <Auto/50Hz/60Hz>
*? xConguration Cameras Camera [1..1] Brightness Mode: <Auto/Manual>
*? xConguration Cameras Camera [1..1] Brightness Level: <1..31>
*? xConguration Cameras Camera [1..1] Whitebalance Mode: <Auto/Manual>
.
.
.
OK
xConguration ?
– User Congurations –
Audio
Cameras
Conference
Experimental
FacilityService
H323
Network
NetworkServices
Phonebook
Provisioning
RTP
Security
SerialPort
SIP
Standby
SystemUnit
Time
UserInterface
Video
OK
Congurations
Congurations are system settings that are persistent across
boots. Like commands, also congurations are structured in
a hierarchy.
Writing xConguration ? on the command line lists all the top
level congurations.
Writing xConguration ?? lists all congurations and their value
spaces.
Writing xConguration lists all congurations and their current
values. To list out only parts of the conguration, write xCongu-
ration followed by one or more parts of the conguration paths.
Example: Set the H323 Alias ID
Write in:
xConguration H323 Prole 1 H323Alias ID:
“[e-mail]”
Example: Get the H323 Alias ID
Write in:
xConguration H323 Prole 1 H323Alias ID
Result:
*c xConguration H323 Prole 1 H323Alias ID:
“[e-mail]”
**end
Contents
Introduction
About the API
xConguration
Appendices
xCommand
xStatus
About the API

D14869.05 Codec C20 API Reference Guide TC6.0 February 2013. Copyright © 2010–2013 Cisco Systems, Inc. All rights reserved. 16
Cisco TelePresence System Codec C20 API Reference Guide
Addressing status information with xStatus
To read the status from the system type the root command (xStatus) followed by a path (address expression):
xStatus <address expression>
Example 1: Query all ongoing Call information:
xStatus Call
*s Call 3 Status: Connected
*s Call 3 Direction: Outgoing
*s Call 3 Protocol: “sip”
*s Call 3 RemoteNumber: “[e-mail]”
*s Call 3 CallbackNumber: “sip:[e-mail]”
*s Call 3 DisplayName: “[e-mail]”
*s Call 3 TransmitCallRate: 768
*s Call 3 ReceiveCallRate: 768
*s Call 3 FacilityServiceId: 0
*s Call 3 Encryption Type: “None”
*s Call 3 PlacedOnHold: False
*s Call 3 Duration: 9
** end
OK
Example 2: Query the protocol for a call:
xStatus Call Protocol
*s Call 3 Protocol: “sip”
OK
xStatus ?
– Status –
Audio
C a l l[...]
Camera
Conference
Diagnostics
Experimental
H320
H323
HttpFe ed b ack[1..4]
MediaChannels
Network
Preset[1..15]
Provisioning
Security
SIP
Standby
SystemUnit
Time
Video
OK
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.
Contents
Introduction
About the API
xConguration
Appendices
xCommand
xStatus
About the API

D14869.05 Codec C20 API Reference Guide TC6.0 February 2013. Copyright © 2010–2013 Cisco Systems, Inc. All rights reserved. 17
Cisco TelePresence System Codec C20 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 outgo-
ing 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:[e-mail]” EncryptionIn:
“Off” EncryptionOut: “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
Contents
Introduction
About the API
xConguration
Appendices
xCommand
xStatus
About the API

D14869.05 Codec C20 API Reference Guide TC6.0 February 2013. Copyright © 2010–2013 Cisco Systems, Inc. All rights reserved. 18
Cisco TelePresence System Codec C20 API Reference Guide
Call history
The xHistory command returns the call logs.
Example with xHistory CallLogs
xHistory
*h xHistory CallLogs Call 1 CallId: 13
*h xHistory CallLogs Call 1 Protocol: “h323”
*h xHistory CallLogs Call 1 Direction: Incoming
*h xHistory CallLogs Call 1 CallType: Video
*h xHistory CallLogs Call 1 RemoteNumber: "h323:rstname.lastname.of[e-mail]"
*h xHistory CallLogs Call 1 CallbackNumber: "h323:rstname.lastname.of[e-mail]"
*h xHistory CallLogs Call 1 DisplayName: "[e-mail]"
*h xHistory CallLogs Call 1 CallRate: 768
*h xHistory CallLogs Call 1 DisconnectCauseValue: 2
*h xHistory CallLogs Call 1 DisconnectCause: “Normal”
*h xHistory CallLogs Call 1 DisconnectCauseType: RemoteDisconnenct
*h xHistory CallLogs Call 1 DisconnectCauseCode: 16
*h xHistory CallLogs Call 1 DisconnectCauseOrigin: Q850
*h xHistory CallLogs Call 1 StartTime: “2012/02/14 11:04:14”
*h xHistory CallLogs Call 1 Duration: 184
*h xHistory CallLogs Call 1 Encryption: “None”
*h xHistory CallLogs Call 1 BookingId: “”
...
*h xHistory CallLogs Recent 6 CounterMissed: 0
*h xHistory CallLogs Recent 6 Counter: 3
...
*h xHistory CallLogs Outgoing 30 Counter: 1
...
*h xHistory CallLogs Received 40 Counter: 1
...
*h xHistory CallLogs Missed 50 Counter: 2
*h xHistory CallLogs Missed 50 NewCounter: 0
** end
Contents
Introduction
About the API
xConguration
Appendices
xCommand
xStatus
About the API

D14869.05 Codec C20 API Reference Guide TC6.0 February 2013. Copyright © 2010–2013 Cisco Systems, Inc. All rights reserved. 19
Cisco TelePresence System Codec C20 API Reference Guide
Example 1: Microphones Mute status.
Terminal query
xStatus Audio Microphones Mute
*s Audio Microphones Mute: Off
** end
Equivalent feedback expression
xFeedback register /Status/Audio/Microphones/Mute
Example 2: All video input connectors.
Terminal query
xConguration Video Input Source Connector
*c xConguration Video Input Source 1
Connector: HDMI
*c xConguration Video Input Source 2
Connector: HDMI
*c xConguration Video Input Source 3
Connector: HDMI
*c xConguration Video Input Source 4
Connector: HDMI
*c xConguration Video Input Source 5
Connector: Composite
** end
Equivalent feedback expression
xFeedback register /Conguration/Video/Input/
Source/Connector
Example 3: Video input connector for source 3.
Terminal query
xConguration Video Input Source 3 Connector
*c xConguration Video Input Source 3
Connector: HDMI
** end
Equivalent feedback expression
xFeedback register /Conguration/Video/Input/
Source[@item=’3’]/Connector
Feedback mechanism
To build solutions that can reliably keep the state between the
application and the codec synchronized; you need to set up a
notication system to report the changes in the state of the codec.
The API supports notications on the following:
• Conguration changes
• Status changes
• Event notications
These notications will not be sent unless the user has explicitly
told the codec to do so. The user is required to subscribe to
all the feedback the application needs. This is done by regis-
tering feedback expressions. The way of registering feedback
expressions varies according to the connection method used.
When using HTTP, the method of handling feedback diers
slightly from what is presented in this section. See the
”Feedback from codec over HTTP” section for more information.
Feedback expressions
The expression used when registering for feedback is a vari-
ant of the XPath language. This language describes a way to
select nodes from an XML document. TC software contains
three main feedback documents:
The syntax for feedback registering is: xFeedback register <path>
Never register for all status feedback by issuing
xFeedback register /Status.
It is safe to register for all configuration changes using
xFeedback register /Conguration, as conguration changes
will most likely not occur that often.
By going through some examples, we can see how this
information can be used to build feedback expressions. A
good way to verify the expressions is to point your browser
to http://<ip-address>/getxml?location=path or to execute
xgetxml <path> from the terminal, and check that the output
matches the nodes you want feedback on.
WARNING: A codec may give very much feedback, especially
when calls are connected and disconnected. Therefore, you
should only subscribe to the feedback that you need.
Never register for all status feedback by issuing
xFeedback register /Status. This may give the control appli-
cation too much data to handle, which may lead to sluggish
or unpredictable behavior.
Document API command Path
Status xStatus /Status
Conguration xConguration /Conguration
Event xEvent /Event
Contents
Introduction
About the API
xConguration
Appendices
xCommand
xStatus
About the API

D14869.05 Codec C20 API Reference Guide TC6.0 February 2013. Copyright © 2010–2013 Cisco Systems, Inc. All rights reserved. 20
Cisco TelePresence System Codec C20 API Reference Guide
Terminal connections
Managing feedback subscriptions
To register, list and deregister feedback expressions you use
the command xFeedback and its corresponding sub commands.
The registered expressions are only valid for the currently
active connection. If you open two Telnet sessions and register
to get feedback in one session, you do not receive feedback
in the other serssion. This also means that if you disconnect
from a session, you have to re-register all expressions after
reconnecting.
You can register up to 38 expressions.
Feedback output
The feedback output is exactly the same as you get when query-
ing the system using the xConguration and xStatus commands.
E.g., if you issue the command xStatus Standby Active
on the command line the result is:
*s Standby Active: On
** end
If you have registered for feedback on status changes the
feedback you get when the system goes to standby-mode
will be exactly the same:
*s Standby Active: On
** end
This means that when you are programming against the device
you only need to handle one format.
Example: Managing feedback subscriptions
A: Register feedback expressions.
Write in: xFeedback register /Status/Audio
Result: ** end
OK
Write in: xFeedback register /Event/CallDisconnect
Result: ** end
OK
Write in: xFeedback register /Conguration/Video/
MainVideoSource
Result: ** end
OK
B: List out currently registered expressions.
Write in: xFeedback list
Result: /Conguration/Video/MainVideoSource
/Event/CallDisconnect
/Status/Audio
** end
OK
C: Deregister feedback expressions.
Write in: xFeedback deregister /Event/CallDisconnect
Result: ** end
OK
Write in: xFeedback deregister /Status/Audio
Result: ** end
OK
D: List the new feedback expressions.
Write in: xFeedback list
Result: /Conguration/Video/MainVideoSource
** end
OK
Contents
Introduction
About the API
xConguration
Appendices
xCommand
xStatus
About the API