Embedded Bridge

NDI Embedded Bridge is a command-line utility designed for Linux platforms, enabling users to effectively advertise and transmit local NDI sources to remote endpoints via WAN connections. It functions as a Bridge client application that operates in Join mode.

Access to remote endpoints is provided by connecting NDI Embedded Bridge to an independent external NDI Bridge Host. Once the connection is successfully established, users can view and request streaming of remote sources over the WAN facilitated by tools like NDI Studio Monitor.

NDI Embedded Bridge is primarily meant for deployment on embedded devices (such as PTZ cameras) that can use it to transmit NDI output to remote receivers across WAN connections and, conversely, to receive metadata or control instructions from a remote sender.

It's important to note that NDI Embedded Bridge does not support any transcoding, instead providing straightforward passthrough over the WAN to the remote endpoint and seamless forwarding of all metadata from NDI clients, such as Studio Monitor. For instance, when users avail themselves of Studio Monitor’s integrated PTZ controls, NDI Embedded Bridge delivers those PTZ commands across the WAN to the connected camera. (Note that some metadata functionality may depend on capabilities granted by the vendor ID.)

Lastly, it's worth mentioning that all communication over the Bridge is encrypted for enhanced security.

Lastly, it's worth mentioning that all communication over the Bridge is encrypted for enhanced security.

Minimum requirements

• A minimum Linux kernel version of 4.18 or higher is required.

• The Linux kernel must have support for dual-stack IPv4 and IPv6.

• To achieve optimal performance, support for Generic Segmentation Offload (GSO) for UDP is essential. This requirement aligns with the UDP_SEGMENT socket option. Without GSO support, UDP transmission may lead to a notable increase in CPU usage.

Command Line Arguments

This process operates as a command-line application and offers support for command-line options. Additionally, it is compatible with a JSON configuration file, where each individual entry aligns with a specific command-line option. Users of this application are required to provide a vendor ID as input; failure to do so will result in the application halting after the specified timeout period.

Command Line Options

Usage:

./ndi-embedded-bridge [OPTIONS] [JSON CONFIG FILENAME]

Command Line Option	Description
-help	Displays available command line arguments with short descriptions.
-help COMMAND	Displays extended help for the given command line argument (e.g. -help address).
-address "[ID@]ADDRESS[:PORT]"	Target Host for the Join instance. (Default: "127.0.0.1:5990").
-diag "[info|warn|error]"	Set the diagnostic level of log output. (Default: "warn").
-id "ID"	The identity of the Bridge process. (Default: "MACHINE_NAME.PROCESS_ID"). If an identifier is not explicitly provided (either here or optionally through the address) then one will be automatically generated which will be the name of the machine on which the application is run.
-logfile "FILE"	Capture log output to a file (highly recommended in 'quiet' mode!).
-machine "ID"	Accept NDI sources only from the specified machine ID. (default: "").
-port PORT	Port number to use with the Host. (Default: 5990).
-reportstats MILLISECONDS	Enable reporting connection statistics every given millisecond. (Default: 500). The bandwidth data measured is in bytes per second (Bps).
-retry SECONDS	Amount of time to wait between attempts to connect to the Host. (Default: 5).
-secure "KEY"	Secure communications using the provided key.
-source "NAME"	Limit NDI discovery to just the NDI source name specified. The source name should match the device name and channel name on that device in the form of DEVICE_NAME (CHANNEL_NAME).
-srcgroups "GROUP[,GROUP]"	Limit the Join's NDI source discovery to just the specified groups.
-vendor_id "ID"	NDI Vendor ID. (default: "").
-vendor_name "NAME"	NDI Vendor name. (Default: "").
-nolocal	Exclude NDI sources local to the Join. (Default: false).
-overwrite	When enabled, any existing log output file will be overwritten. (Default: false).
-quiet	Suppress all console output and hide the console window. (Default: false).
-bridge_name "ID"	Alias for the "-id" option.
-source_name "NAME"	Alias for the "-source" option.
-reportbps "MILLISECONDS"	Alias for the "-reportstats" option.

Examples

./ndi-embedded-bridge -address "[email protected]:5990"
./ndi-embedded-bridge -bridge_name "NiceCamera" -address "192.168.0.42" -port 5990
./ndi-embedded-bridge -address "[email protected]:5990" -source_name "PTZCamera (Channel 1)"
./ndi-embedded-bridge -address "[email protected]:5990" -secure "123abc" -source "PTZCamera (Channel 1)"
./ndi-embedded-bridge -address "[email protected]:5990" -secure "123abc" -source "PTZCamera (Channel 1)" -vendor_name "XXX" -vendor_id "YYY"

JSON Configuration Options

The application can be started by supplying the filename of a JSON file containing the settings. The filename must have a (.json) extension.

The top-level object can contain two members:

• "ndi" object containing NDI configuration settings.

• "bridge" object whose members are equivalent to the command line arguments.

Examples

./ndi-bridge "/etc/config/bridge.json"

{
	"ndi": {
		"machinename": " Hello World",
		"groups": {
			"recv": "Public"
		},
		"networks": {
			"discovery": "192.168.20.2:5959"
		},
		"vendor": {
			"name": "XXX",
			"id": "YYY"
		}
	},
	
	"bridge": {
		"address": "192.168.0.42",
		"port": 5990,
		"secure": "123abc",
		"diag": "info",
		"id": "NiceCamera"
	}
}

To gracefully exit the application, use the CTRL+C key combination. This will terminate the current bridge process and close the application gracefully.

Connection Statistics

Rtt : Round-Trip Time is the duration in microseconds for a packet to travel from the sender to the receiver and back again. This metric is crucial for assessing network latency and performance.

MinRtt, MaxRtt : Minimum and Maximum Round-trip-time in microseconds represent the shortest and longest round-trip times observed during the connection's lifespan. These metrics offer insights into the range of network latency experienced by the connection.

SendLostPackets : The Number of packets that the sender believes are permanently lost, as no acknowledgment (ACK) of their transmission was received . This metric helps gauge the sender's perception of packet loss within the network.

SendCongestionCount : Number of congestion events experienced by the sender, signaling instances where the congestion window is full and required bandwidth is unavailable, thus impacting connection performance.

SendCongestionWindow : Size of the sender's congestion window in bytes, which limits the data transmission rate to prevent network overload. This window adjusts dynamically based on network conditions to ensure the sender operates within the available bandwidth.

RecvDroppedPackets : Number of packets that were locally dropped on receive, indicating the count of packets not successfully received by the application on the receiving end (possibly due to exceeding a receiver's buffer capacity or receiving invalid packets).

RecvReorderedPackets : Number of packets received out of order (which can happen due to network congestion or routing changes).

Control Statistics

Scheduling : Total time in microseconds that the connection was blocked due to packet transmission scheduling issues such as delays caused by congestion control algorithms or prioritization mechanisms.

Pacing : Total time in microseconds that the connection was blocked by pacing, which regulates the packet transmission rate to avoid congestion.

AmplificationProt : Total time in microseconds that the connection was blocked by amplification protection mechanisms, which guard against potential amplification attacks by limiting or blocking certain types of traffic.

CongestionControl : Total time in microseconds that the connection was unable to send data at its desired rate due to network congestion.

FlowControl : Total time in microseconds that the connection was blocked by flow control, which limits the amount of data a sender can transmit before receiving acknowledgment from the receiver.

Stream Statistics

IdFlowControl : Total time in microseconds that a specific stream was blocked by its own flow control limit, which is separate from the overall connection-level flow control limit.

FlowControl : Total time in microseconds that a stream was blocked by flow control, indicating the cumulative duration during which the stream was unable to send data because it had reached the flow control limit set by the receiver.

App : Total time in microseconds that a stream was blocked by the application, indicating the cumulative duration during which the application prevented the stream from sending data, potentially due to application-specific reasons such as flow control or buffer constraints.