Integrator C Series API: Connecting to the API
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
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.
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>
Connect a standard 9-pin serial cable <38400, N, 8, 1> to the COM1 port on the codec.
- 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 or higher.
- 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 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.
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>
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 TC188.8.131.52465 SW Release Date: 2010-03-02 OK
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 TC184.108.40.206465 SW Release Date: 2010-03-02 OK
There are many libraries to choose from. Select one that fits into your project.
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 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.
Download and start putty.exe. Select SSH as Connection Type and enter the hostname or IP address of codec and press Open.
Open your terminal and execute:
# ssh admin@hostname admin@hostname's password: <password> Welcome to IntegratorHQ TANDBERG Codec Release TC220.127.116.11465 SW Release Date: 2010-03-02 OK
Same as with telnet libraries, there are many to choose from. Select one which suites your project.
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.
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.
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>
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.
Integrator C Series API
- Connecting to the API
- Using the command line
- API fundamentals
- Feedback mechanism
- Synchronous API calls
- Experimental sections
- Using HTTP
- Programming the video compositor
- Programming the phone book
- Programming the video switcher
- Using GPIO
- Frequently asked questions
- Other resources
- The link between Calls and Channels
- Do's and don'ts