Integrator C Series API

Feedback mechanism

In order to build applications that can reliably keep the state synchronized between an application and the codec, one needs a notification mechanism for instructing listeners that the state of the codec has changed.

In TC software, the API supports notifications of the following changes:

• Configuration changes
• Status changes
• Event notifications

None of these notifications will be sent to the user unless the user has explicitly told the codec to do so. The user is thus required to subscribe to all the feedback the application needs. This is done by registering feedback expressions and the way of registering such expressions differs from the connection method used.

Feedback expressions

The expression used when registering for feedback is a variant of the XPath language. This language describes a way to select nodes from an XML document. When dealing with feedback, TC software contains three main documents:

By going through a couple of 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://codec/getxml?location=path or to execute xgetxml <path> from the terminal, and check that the output matches the nodes you want feedback on.

Example 1: Microphones Mute status.

Terminal query

xstatus Audio Microphones Mute
*s Audio Microphones Mute: Off
** end

Equivalent path

/Status/Audio/Microphones/Mute

Example 2: All video input connectors.

Terminal query

xconfiguration Video Input Source Connector
*c xConfiguration Video Input Source 1 Connector: HDMI
*c xConfiguration Video Input Source 2 Connector: HDMI
*c xConfiguration Video Input Source 3 Connector: HDMI
*c xConfiguration Video Input Source 4 Connector: HDMI
*c xConfiguration Video Input Source 5 Connector: Composite
** end

Equivalent path

/Configuration/Video/Input/Source/Connector

Example 3: Video input connector for source 3.

Terminal query

xconfiguration Video Input Source 3 Connector
*c xConfiguration Video Input Source 3 Connector: HDMI
** end

Equivalent path

/Configuration/Video/Input/Source[@item='3']/Connector

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, the other session will not receive any feedback. This also means that if you disconnect from a session, you will have to re-register all expressions after reconnecting.

For TC firmware versions up to and including TC 2.1 you can register a maximum of 13 feedback expressions. For TC 3.0 and higher you may register a maximum of 38 expressions.

Example 1: Register feedback expressions.

xfeedback register /Status/Audio
** end

OK
xfeedback register /Event/CallDisconnect
** end

OK
xfeedback register /Configuration/Video/MainVideoSource
** end

OK

Example 2: List out currently registered expressions.

xfeedback list
/Configuration/Video/MainVideoSource
/Event/CallDisconnect
/Status/Audio
** end

OK

Example 3: Deregister feedback expressions.

xfeedback deregister /Event/CallDisconnect
** end

OK
xfeedback deregister /Status/Audio
** end

OK

Example 4: List the new feedback expressions.

xfeedback list
/Configuration/Video/MainVideoSource
** end

OK

Feedback output

The feedback output is exactly the same as you get when querying the system using the xconfiguration and xstatus commands. E.g., if you issue 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 in to standby will be exactly the same:

*s Standby Active: On
** end

This means that when you are programming against the device you only have to handle the one format.

Notes

WARNING: A codec may give a lot more feedback than something like a projector, especially when calls are connected and disconnected. You should thus only subscribe to the feedback that you need; NEVER register for all status feedback by issuing xfeedback register /Status.

This will give the control application a lot of data to handle. Some control systems are unable to handle all this data, which may lead to sluggish or unpredictable behavior.

On the other hand, it should be safe to register for all configuration changes using xfeedback register /Configuration, as configuration changes will most likely not occur that often.

Crestron hints

To see what feedback expressions are registered for the current connection use Crestron Toolbox to send xFeedback list\n as signal stimulus on the To_Device signal.

HTTP

When using HTTP, the method of handling feedback differs slightly. See the Using HTTP section for more information.