connect

The connect command routes a signal of any type between devices. If the source stream is not currently running, connect starts it before routing it to the destination. As part of the DisplayNet API, connect consolidates multiple SDVoE commands into one, enabling simplified signal routing.

Command Type	DisplayNet
Minimum Version	2.x.x

Usage

connect <stream_type> <source> <destination>[,<destination>...] [<mode>] [size <width> <height>] [fps <rate>] [quantization <range>] [nokvm|withkvm]

mode, size, fps, and quantization apply only to HDMI and SCALER connections. All other stream types take no options:

connect <stream_type> <source> <destination>[,<destination>...]

Arguments

Argument	Required	Description
stream_type	Yes	The signal layer to route. See Stream types.
source	Yes	Hostname or MAC address of the transmitting device.
destination	Yes	Hostname(s) or MAC address(es) of the receiving device(s). See Destinations.
mode	No	Display mode for HDMI/SCALER connections. Defaults to the receiver's preferred display mode. See Display modes.
size, fps, quantization	No	Custom output format for HDMI/SCALER connections. See Video parameters.
nokvm, withkvm	No	Override the destination seat's keyboard-and-mouse policy for this one route. See KVM follows video.

Device names are case-insensitive. For hostnames, replace any spaces in the device name with underscores: a source named "Blu-ray Player" in DisplayNet Manager is referenced as blu-ray_player.

Stream types

Value	Signal
HDMI	The primary HDMI video stream
SCALER	The scaled HDMI video stream (used in multiviews)
AUDIO	The analog stereo audio stream
HDMI_AUDIO	The HDMI audio stream
MULTICH_AUDIO	The multichannel audio stream
RS232	RS-232 serial connections
INFRARED	Infrared connections
CEC	CEC connections
USB	USB pairing between one source and one destination
USB_HID	HID-only (keyboard/mouse) pairing between two devices
USBHUB	USB pairing from one source to multiple destination devices

KVM follows video

5.0

A connect routes video. Whether it also hands the destination keyboard and mouse is a property of the destination seat, set with kvm workstation follow and off by default.

Two options override that policy for a single route:

Option	Effect
nokvm	Route video only, even to a seat with follow on.
withkvm	Carry keyboard and mouse, even to a seat with follow off.

Giving both is an error — they are opposite instructions for the same route.

The options are accepted on every stream type but only mean anything for HDMI and SCALER; there is no keyboard to follow an audio or serial route. They are also ignored when there is nothing to hand over: a source with no USB host of its own, or a destination that is a plain display rather than a seat. Neither case is an error.

A KVM failure never fails the route. Video is dispatched first and control settles afterwards, so a locked device or an absent receiver leaves the picture exactly where the operator put it and reports the problem as a kvm_autoconnect_warning notification.

Destinations

A destination is a single device, a comma-separated list of devices (no spaces), or one of the group macros below. For AV signals, the source must be a TX device and each destination must be an RX device.

Value	Valid for	Routes to
<device>	All stream types	A single device, by hostname or MAC address
<device>,<device>,...	All except USB, USB_HID	Each listed device
ALL_RX	HDMI, SCALER, audio, serial	All receivers in the system
ALL_TX	RS232, INFRARED	All transmitters in the system
ALL	RS232, INFRARED	All other devices in the system
API	RS232, INFRARED	The API, for ingestion by connected clients

RS-232 and Infrared direction

To establish a bidirectional serial connection between two units, send a command for each direction: connect rs232 device1 device2 and connect rs232 device2 device1.

USB pairing uses hostnames

For USB connections, use device hostnames rather than MAC addresses. The USB chipset has its own MAC address, which is not the MAC address used for AV routing.

Display modes

Applies to HDMI and SCALER connections only. If no mode is given, the connection uses the receiver's configured preferred display mode (fast switched by default).

Mode	Behavior
fastswitch	Fast-switched signal, scaled through the receiver's frame buffer
fastswitch crop	Fast-switched, cropping the image to preserve the source aspect ratio
fastswitch stretch	Fast-switched, stretching the image to fill the display
genlock	Genlocked signal at source resolution (no scaling, lowest latency)
genlock_scaling	Scaled signal with genlocked timing, without frame buffer delay

Receivers without a frame buffer always connect genlocked, regardless of the requested mode.

Video parameters

For HDMI and SCALER connections in genlock_scaling or fastswitch modes, a custom output format may be specified. When omitted, the output format is derived from the display's EDID.

Parameter	Value	Description
size	<width> <height>	Output resolution in pixels, e.g. size 1920 1080
fps	<rate>	Output frame rate, e.g. fps 60
quantization	See below	Output color quantization range. Defaults to STANDARD

Quantization value	Description
STANDARD	Appropriate quantization range for the video format, as defined by the CEA-861-F standard
AUTO	Same as STANDARD, but explicitly states FULL or LIMITED in the AVI InfoFrame. Works around some monitor issues
LIMITED	Force limited quantization range
FULL	Force full quantization range

Examples

Route HDMI video from a Blu-ray player to a display
connect HDMI blu-ray_player lg_4ktv

Route one source to several displays at once
connect HDMI media_pc lobby_left,lobby_right,lobby_center

Route the scaled stream, genlocked
connect SCALER workstation projector genlock

Fast-switch with a custom output format
connect HDMI roku4k monitor fastswitch size 3840 2160 fps 60

Show a source at a workstation without taking its keyboard
connect HDMI camera_1 trading_desk_1 nokvm

Broadcast infrared from a source to every receiver
connect INFRARED stage_laptop ALL_RX

Pair USB from a desktop to a seat
connect USB desktop front_desk

Return value

On success, connect returns the same payload as calling get settings on the destination immediately after the new settings were applied:

connect HDMI blu-ray_player lg_4ktv
{
  "status": "SUCCESS",
  "request_id": null,
  "result": { "...": "device settings for lg_4ktv" },
  "error": null
}

Errors

On failure, no routing changes are applied and status is "ERROR":

connect HDMI office_rx lg_4ktv
{
  "status": "ERROR",
  "request_id": null,
  "result": null,
  "error": {
    "message": "office_rx is not a valid transmitter",
    "reason": "CONNECT API ERROR"
  }
}

Message	Cause
<name> is not a valid transmitter	The source did not match any device, or is not a TX device
<name> is not a valid receiver	A destination is not an RX device
Unknown subcommand '<name>'	The stream type is not one of the values above
Cannot join stream to locked device	The destination is locked
Cannot join to SCALER: <name> has no SCALER stream	The source does not expose a scaled stream

State and side effects

• DisplayNet records the route. That record is what disconnect tears down, what DisplayNet Manager displays, and what a snapshot preset captures. An SDVoE join or switch moves the same signal without creating the record.
• The source stream is started for you if it is not already running. You do not need start before connecting.
• MultiView bookkeeping is kept consistent. A session already running on the affected devices is updated rather than left describing a route that no longer exists.
• A locked device is refused, whether it is the source or a destination. See lock.

Notifications

Connecting devices generally results in one or more NOTIFICATION or DN_NOTIFICATION replies reflecting the updated state of the devices. See Notifications.

REST API

Endpoint type	DisplayNet API command
Address	POST /api/displaynet/<operation>, or name the operation in the body of a POST /api/displaynet. See Sending commands.
Role	User

Subcommand	Operation	Parameters
cec	connect_cec	source destinations [options]*
hdmi	connect_hdmi	source destinations [options]*
hdmi_audio	connect_hdmi_audio	source destinations [options]*
infrared	connect_infrared	source destinations [options]*
multich_audio	connect_multich_audio	source destinations [options]*
rs232	connect_rs232	source destinations [options]*
scaler	connect_scaler	source destinations [options]*
stereo_audio	connect_stereo_audio	source destinations [options]*
usb	connect_usb	source destination
usb_hid	connect_usb_hid	source destination
usbhub	connect_usbhub	source destinations

A parameter in brackets is optional. A parameter marked * takes the remainder of the command line as one string. Pass the text exactly as you would type it on the TCI interface.

See also

• disconnect: tear down a routed connection
• start / stop: control source streams directly
• get: inspect the resulting device settings
• kvm workstation: the seat policy behind nokvm / withkvm