Integrator C Series API

Connecting to the API

There are several ways of accessing the codec API. Regardless of which method you choose, the structure of the API stays the same. Choose the connection method that suites your application the best. Before you start using your preferred connection method, please read below about the different methods as some methods may require some additional configuration changes before being enabled.

Common for all connection methods

The user name to use when logging in is admin. By default this user does not ship with a password. This password can be changed by issuing the following command.

xcommand SystemUnit AdminPassword Set Password: password

RS-232/serial connection

This is probably still the most used connection to our products for integrators, as it does away with any hassle regarding IP addresses, DNS and other network related issues.

Codec configurations

There are two different configurations 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 the settings to take place.

xConfiguration SerialPort BaudRate: <9600/19200/38400/57600/115200>
xConfiguration SerialPort LoginRequired: <Off/On>

Connecting

Connect a standard 9-pin serial cable <38400, N, 8, 1> to the COM1 port on the codec.

Notes

• For security reasons the password prompting is turned on by default, but may be turned off if preferred.
• The default baud rate is set to 38400. The reason for this is that unlike for example a projector, the codec can give quite a lot of feedback. When using 9600 baud it may cause your integration to appear sluggish. We therefore recommend keeping the connection at this speed.
• During the initial boot sequence, the codec will be using a baud rate of 38400 no matter what you set the application baud rate to.

For details regarding the RS-232 pin-out and more, please refer to the Physical Interface Guide in the Other resources section of this document.

Telnet

Telnet can be viewed as the equivalent of the serial protocol in the TCP/IP world. By default it's turned off on the device and requires a codec configuration to be switched on. This can be done using SSH, RS-232, the web interface or the on-screen menu.

Codec configuration

In order to enable or disable the telnet service, please 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>

Connecting

Windows

Windows comes with a built-in telnet client. Run cmd.exe:

c:\> telnet <ip>

Linux 2.6.25-1-117 (hostname.domain) (3)

login: admin
Password: <password>
Welcome to hostname
TANDBERG Codec Release TC3.0.0.210465
SW Release Date: 2010-03-02

OK

Linux

Most linux distributions ships with a telnet client. Open a terminal:

# telnet <ip>

Linux 2.6.25-1-117 (hostname.domain) (3)

login: admin
Password: <password>
Welcome to hostname
TANDBERG Codec Release TC3.0.0.210465
SW Release Date: 2010-03-02

OK

Java

There are many libraries to choose from. Select one that fits into your project.

Python

The built-in telnetlib should suffice.

from telnetlib import Telnet
telnet = Telnet(ip, 23)
telnet.read_until('login:')
telnet.write('admin\n')
telnet.read_until('Password:')
telnet.write(password + '\n')
telnet.read_until('OK')

SSH

SSH is a secure TCP/IP connection and is always available on the codec. You will need an SSH client like Putty to access the API over SSH.

Connecting

Windows

Download and start putty.exe. Select SSH as Connection Type and enter the hostname or IP address of codec and press Open.

Linux

Open your terminal and execute:

# ssh admin@hostname
admin@hostname's password: <password>
Welcome to IntegratorHQ
TANDBERG Codec Release TC3.0.0.210465
SW Release Date: 2010-03-02

OK

Java

Same as with telnet libraries, there are many to choose from. Select one which suites your project.

Python

Currently the most used library is called paramiko.

AMX and Crestron

Currently, neither AMX nor Crestron has built-in support for SSH. With AMX it should be possible to create a Duet module in Java with SSH support.

HTTP/HTTPS

As HTTP/HTTPS are connection-less protocols there is no actual persistent connection to talk about. There are several ways of communicating with the API over HTTP.

Codec configuration

In order to enable or disable the HTTP and HTTPS services, please configure the following settings on the codec. Changing these settings will require a reboot of the device.

xconfiguration NetworkServices HTTP Mode: <Off/On>
xconfiguration NetworkServices HTTPS Mode: <Off/On>

Connecting

You can inspect the API by entering the IP-address or host name of codec in your favorite web browser. Under the menu section XML files you will find the API documents. The HTTP POST and GET methods are used to execute commands and get feedback from the codec. This is described in a separate section later in this document.