Skip to main content

Connecting to the API

All three TCI transports carry the same API. Pick whichever suits the client; the commands and replies are identical.

Telnet connections​

The API listens on port 6980 of the DisplayNet Server. The server's default hostname is displaynet.local.

SSH connections​

SSH connects to the api account once RSA keys are set up on the client and server. Keys are configured with the server command, or in Settings > Security in DisplayNet Manager.

SSH encrypts the channel; the client still authenticates to the API separately. See Authentication and permissions.

WebSocket connections​

The TCI WebSocket carries a full API session from a web application: port 7000 plain, port 7010 TLS. Commands and responses are exactly as in a telnet session.

TCI WebSocket vs REST WebSocket

DisplayNet offers two WebSocket endpoints and they are not interchangeable.

The TCI WebSocket, on ports 7000 and 7010, is the one described here: a full API session carrying the same commands and responses as telnet, with the same initialization sequence below. DisplayNet Manager uses this endpoint.

The REST WebSocket is an upgrade on /api, on ports 80 and 443. It is compatible with the SDVoE REST API and adds DisplayNet notifications on the same connection. Events start flowing the moment it connects, with no setup commands. See WebSocket.

Establishing a client connection​

A new connection moves through a fixed sequence before it accepts commands; Connection State describes each reply in detail.

  1. Connection established via Telnet, SSH, or WebSocket.
  2. API sends an API_INITIALIZED response. This includes the API version, and whether authentication is required on the server.
  3. If authentication is required, the client must send a login command to continue. See login.
  4. The API sends a DN_AUTHENTICATION response once the user is authenticated, or immediately if authentication is not required. This marks the start of the session.
  5. The session is now established and can be initialized.

Starting an API session​

Send a carriage return, then initialize the session:

require api 3.5.0
mode async on

version works before initialization, so a client can read the server's API version and pass it to require rather than pinning one.

To reach the SDVoE API's own commands through the same session, load its module as well:

require blueriver_api 3.6.0.0

Without it, an SDVoE command such as get <device> settings is refused as Invalid command. With it, DisplayNet and SDVoE commands are interchangeable on the same connection.

Parsing responses​

Responses are JSON. mode human on re-formats them for reading at a terminal. Inside DisplayNet Manager's Console, use its Human Mode setting rather than sending the command.

See also​