videohubctrl.1

.TH VIDEOHUBCTRL "1" "October 2020" "videohubctrl 3.1" "User Commands"
.SH NAME
videohubctrl - Blackmagic Design Videohub SDI router control
.SH SYNOPSIS
.B videohubctrl --host <host> \fI..other options..\fR
.SH DESCRIPTION
videohubctrl implements the simple text based network protocol for
controlling Blackmagic Design Videohub SDI router devices. The
program is tested with Blackmagic Design Micro Videohub and
probably works with other Videohub models.

videohubctrl currently displays and can configure:
  - Video input port names
  - Video output port names, routing and locking
  - Input/Output port statuses
  - Monitoring video output port names, routing and locking
  - Serial ports names, routing, locking and directions
  - Processing units
  - Frames
  - Alarms status
.SH MAIN OPTIONS
.PP
.TP
\fB\-h\fR, \fB\-\-host\fR <host>
Set the device host name. It can be an IP address or host name. You
can set \fBVIDEOHUB_HOST\fR environment variable instead of using
this option.
.TP
\fB\-p\fR, \fB\-\-port\fR <port>
Set the device port. You can set \fBVIDEOHUB_PORT\fR environment
variable instead of using this option. The default port is \fB9990\fR.
.TP
\fB\-t\fR, \fB\-\-timeout <seconds>\fR
Set the timeout in seconds for connect and read. The default is 15 seconds,
min vlue is 1 and max value is 60
.SH COMMANDS
.PP
.TP
\fB\-i\fR, \fB\-\-info\fR
Show full device info. This is the default command if none is set.
The command shows the equivalent of running all \-\-list-XXX commands.
.TP
\fB\-m\fR, \fB\-\-monitor\fR
Display the Videohub configuration and updates it in real-time as it
is changed. The monitor shows config changes immediately as they happen.
The device is not being polled, instead the videohub protocol is designed
in such way that every client receives changes on the fly.
.TP
\fB\-b\fR, \fB\-\-backup\fR
Show the command line that will restore the device to it's configuration.
.TP
\fB\-\-list\-device\fR
Display main device info including model, number of ports, etc.
.TP
\fB\-\-list\-vinputs\fR
Display device video inputs. Port numbers, names, how many outputs an
input is being routed to, the list of the outputs and the port status
(type).

The port statuses (type) are reported by Universal Videohub and can be
these:
.nf
     - Empty means that the device do not support port status.
  x  - The port type is "None". This means that the port is not
       installed in the device.
  B  - The port type is "BNC".
  o  - The port type is "Optical".
  T  - The port type is "Thunderbolt".
.fi
.TP
\fB\-\-list\-voutputs\fR
Display device video outputs. Port numbers, names, locking status, which
input is routed to a given output and the port status (type).

There are two locking statuses:
.nf
  L - The port is locked by another IP address (user)
  O - The port is locked by me (from my IP address)
.fi

The port status field (s) have the same format as input ports (described
in \fB\-\-list\-vinputs\fR option).
.TP
\fB\-\-list\-moutputs\fR
Display device monitoring outputs. Port numbers, names, locking status and
which input is routed to a given output. The locking statuses are the
same as video input and output ports.
.TP
\fB\-\-list\-serial\fR
Display device serial ports. Port numbers, names, locking status, directions
and how serial ports are routed. The locking statuses are the same as video
input, output ports and monitoring ports.
.TP
\fB\-\-list\-proc-units\fR
Display device procesing units. Unit numbers, locking status and connected
video inputs.
.TP
\fB\-\-list\-frames\fR
Display stored frame buffers.
.TP
\fB\-\-list\-alarms\fR
Display current alarms status.
.TP
\fB\-\-set\-name\fR <name>
Set the device "friendly name". This name can be used as a device identifier.
Only some Videohub models support this functionality.
.SH CONFIGURATION COMMANDS
.PP
Everywhere where port needs to be set, you can use the port number or the
port name. You can use only port names that were already configured in
previous session. Trying to set a name and then reference it in the next
command will fail. Using port numbers always works.
.SH INPUTS CONFIGURATION
.PP
.TP
\fB\-\-in\-name\fR <in_X> <name>
Set video input port X name.
.TP
\fB\-\-in\-output\fR <in_X> <out_Y>
Set video input X to be outputted via output Y.
.TP
\fB\-\-in\-monitor\fR <in_X> <mout_Y>
Set video input X to be outputted via monitoring port Y.
.SH OUTPUTS CONFIGURATION
.PP
.TP
\fB\-\-out\-name\fR <out_X> <name>
Set video output port X name.
.TP
\fB\-\-out\-input\fR <out_X> <in_Y>
Connect video output X to video input Y.
.TP
\fB\-\-out\-lock\fR <out_X>
Lock output port X.
.TP
\fB\-\-out\-unlock\fR <out_X>
Unlock output port X. If the port is locked by somebody else the
port would be forcefully unlocked.
.SH MONITORING OUTPUTS CONFIGURATION
.PP
.TP
\fB\-\-mon\-name\fR <mout_X> <name>
Set monitoring output port X name.
.TP
\fB\-\-mon\-input\fR <mout_X> <in_Y>
Connect monitoring output X to video input Y.
.TP
\fB\-\-mon\-lock\fR <mout_X>
Lock monitoring output port X.
.TP
\fB\-\-mon\-unlock\fR <mout_X>
Unlock monitoring output port X. If the port is locked by somebody
else the port would be forcefully unlocked.
.SH SERIAL PORTS CONFIGURATION
.PP
.TP
\fB\-\-ser\-name\fR <ser_X> <name>
Set serial port X name.
.TP
\fB\-\-ser\-connect\fR <ser_X> <ser_Y>
Connect serial port X to serial port Y. This option have two aliases \fB\-\-ser\-input\fR
and \fB\-\-ser\-route\fR.
.TP
\fB\-\-ser\-clear\fR <ser_X>
Disconnect serial port X from the connected serial port.
.TP
\fB\-\-ser\-lock\fR <ser_X>
Lock serial port X.
.TP
\fB\-\-ser\-unlock\fR <ser_X>
Unlock serial port X. If the port is locked by somebody else the
port would be forcefully unlocked.
.TP
\fB\-\-ser\-dir\fR <ser_X> <in|out|auto>
Set serial port X direction. There are three possible settings for
each port:
 \fBin\fR   - input/control/Workstation
 \fBout\fR  - output/slave/Deck
 \fBauto\fR - Automatic in/out
.SH PROCESSING UNITS CONFIGURATION
.PP
.TP
\fB\-\-pu\-input\fR <pu_X> <in_Y>
Connect processing unit X to video input port Y.
.TP
\fB\-\-pu\-clear\fR <pu_X>
Disconnect processing unit X from the connected input port.
.TP
\fB\-\-pu\-lock\fR <pu_X>
Lock processing unit port X.
.TP
\fB\-\-pu\-unlock\fR <pu_X>
Unlock processing unit port X. If the processing unit is locked by somebody
else the port would be forcefully unlocked.
.SH FRAMES CONFIGURATION
.PP
.TP
\fB\-\-fr\-name\fR <fr_X> <name>
Set frame X name.
.TP
\fB\-\-fr\-output\fR <fr_X> <out_Y>
Output frame X to video output port Y.
.TP
\fB\-\-fr\-clear\fR <fr_X>
Disconnect frame X from the connected output port.
.TP
\fB\-\-fr\-lock\fR <fr_X>
Lock frame X.
.TP
\fB\-\-fr\-unlock\fR <fr_X>
Unlock frame X. If the frame is locked by somebody else the port would be
forcefully unlocked.
.SH MISC OPTIONS
.PP
.TP
\fB\-T\fR, \fB\-\-test\fR <file>
Read commands from the <file> instead of connecting to a real
device. This allows testing the program without having access
to a device.
.TP
\fB\-d\fR, \fB\-\-debug\fR
Enable debugging output. Use this option more times to increase
the verbosity.
.TP
\fB\-q\fR, \fB\-\-quiet\fR
Suppress warnings about unsupported commands.
.TP
\fB\-V\fR, \fB\-\-version\fR
Show program name and version.
.TP
\fB\-H\fR, \fB\-\-help\fR
Show program usage text.
.SH ENVIRONMENT VARIABLES
.PP
.TP
\fBVIDEOHUB_HOST\fR
Set the device host name.
.TP
\fBVIDEOHUB_PORT\fR
Set the device port.
.SH EXAMPLES
.PP
To get a quick start here are some example command lines.

.nf
 # Rename video output
   videohubctrl -h sdi --out-name 8 "Output 8 - test"
   videohubctrl -h sdi --out-name "Output 8 - test" "Output 8"

 # Rename video input
   videohubctrl -h sdi --in-name 4 "Windows 4 HD"
   videohubctrl -h sdi --in-name "Windows 4 HD" "CPlay4"

 # Lock and then unlock output 16 (unlock assumes that the port is
 # named Output 16). The host name is set via env variable.
   export VIDEOHUB_HOST=sdi
   videohubctrl --out-lock 16
   videohubctrl --out-unlock "Output 16"

 # Set two outputs to receive from the same input using port names
   videohubctrl -h sdi --out-input "Output 8" "Windows 4 HD"
   videohubctrl -h sdi --out-input "Output 7" "Windows 4 HD"

 # Set one input to go out two outputs and two monitoring ports
   videohubctrl -h sdi --in-output  "Windows 4 HD" "Output 8" \\
                       --in-output  "Windows 4 HD" "Output 7" \\
                       --in-monitor "Windows 4 HD" "Monitor 1" \\
                       --in-monitor "Windows 4 HD" "Monitor 2"

 # Run several commands at once
 # Rename video input 11 and 12
 # Rename video output 5,
 # Set output 5 to receive from input 12
 # Lock output 5
   videohubctrl --host sdi \\
                --in-name 11 "Test input" \\
                --in-name 12 "Playout input" \\
                --out-name 5 "Encoder h264" \\
                --out-input 5 12 \\
                --out-lock 5

 # This fails. It tries to use name that is not previously configured.
   videohubctrl -h sdi --out-name 1 "Test output" \\
                       --out-name "Test output" "Other name"

.fi
.SH SEE ALSO
See the README file for more information. If you have questions,
remarks, problems or you just want to contact the developer, write
to:
  \fIgeorgi@unixsol.org\fP
.TP
For more info, see the website at
.I http://georgi.unixsol.org/programs/videohubctrl/
.SH AUTHORS
Written by Georgi Chorbadzhiyski <\fBgeorgi@unixsol.org\fR>
.SH LICENSE
videohubctrl is released under MIT license.