videohubctrl - Blackmagic Videohub control application

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

Configuration of Videohub's network settings can be made using Blackmagic's Windows program when the device is connected via USB.

Configuration of processing units and frames is probably not working properly because the support was added by just following the very minimal documentation and with no testing on a real device, so don't expect miracles in this department. The other stuff is solid but please see the TODO section of this document and help.

License

videohubctrl is released under MIT license. See LICENSE-MIT.txt for full license terms.

Command line parameters

videohubctrl is controlled using command line parameters. Here is a list of supported command line parameters:

Main options: -h --host | Set device host name. -p --port <port_number> | Set device port (default: 9990). -t --timeout | Set connect/read timeout. Default: 15

Commands: -i --info | Show full device info (default command). . This command is shows the equivalent of . running all --list-XXX commands. -m --monitor | Display real-time config changes monitor. -b --backup | Show the command line that will restore . the device to the current configuration.

--list-device | Display device info. --list-inputs | List device input ports. --list-outputs | List device output ports. --list-monitor | List device monitoring outputs. --list-serial | List device serial ports. --list-proc-units | List device processing units. --list-frames | List device frame buffers. --list-alarms | List device alarms.

--set-name | Set the device "friendly name".

Inputs configuration: --in-name <in_X> | Set input port X name. --in-output <in_X> <out_Y> | Route input X to output Y. --in-monitor <in_X> <mout_Y> | Route input X to monitor port Y.

Outputs configuration: --out-name <out_X> | Set output port X name. --out-input <out_X> <in_Y> | Connect output X to input Y. --out-lock <out_X> | Lock output port X. --out-unlock <out_X> | Unlock output port X.

Monitoring outputs configuration: --mon-name <mout_X> | Set monitoring port X name. --mon-input <mout_X> <in_Y> | Connect monitoring X to input Y. --mon-lock <mout_X> | Lock monitoring port X. --mon-unlock <mout_X> | Unlock monitoring port X.

Serial ports configuration: --ser-name <ser_X> | Set serial port X name. --ser-connect <ser_X> <ser_Y> | Connect serial X to serial Y. --ser-clear <ser_X> | Disconnect serial port X from serial Y. --ser-lock <ser_X> | Lock serial port X. --ser-unlock <ser_X> | Unlock serial port X. --ser-dir <ser_X>

Processing units configuration: --pu-input <pu_X> <in_Y> | Connect processing unit X to input Y. --pu-clear <pu_X> | Disconnect unit X from input Y. --pu-lock <pu_X> | Lock processing unit X. --pu-unlock <pu_X> | Unlock processing unit X.

Frames configuration: --fr-name <fr_X> | Set frame X name. --fr-output <fr_X> <out_Y> | Output frame X to output Y. --fr-clear <fr_X> | Stop outputing frame X to the output. --fr-lock <fr_X> | Lock frame X. --fr-unlock <rf_X> | Unlock frame X.

Misc options: -T --test-input | Read commands from . -d --debug | Increase logging verbosity. -q --quiet | Suppress warnings. -H --help | Show help screen. -V --version | Show program version.

Environment variables

The following environment variables are checked and used by the program if they are set:

VIDEOHUB_HOST Sets the device host name. It is equivalent to using -h / --host command line parameter.

VIDEOHUB_PORT Sets the device port. It is equivalent to using -p / --port command line parameter.

Example usage

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"

Example output

Here is how videohubctrl output looks like using the commands recorded in test/input-00.txt file.

|----------------------------------------------------------------------| $ videohubctrl --test test/input-00.txt Device info

| Device address | sdi-matrix | | Device port | 9990 | | Model name | Blackmagic Micro Videohub | | Unique ID | 7c2e0d021714 | | Protocol | 2.4 | | Video inputs | 16 | | Video outputs | 16 | | Serial ports | 8 | | Video processing units | 4 | | Video monitoring outputs | 4 |

Video inputs

| ### | Video input name | nn | Routed to output | s |

| 1 | Windows 1 | 2 | Enc1 3 | B | | | | | Enc1 4 | | | 2 | Windows 2 | 1 | Enc1 2 | B | | 3 | Windows 3 | 1 | Enc1 1 | B | | 4 | Windows 4 HD | 2 | Output 8 | B | | | | | Enc2 1 | | | 5 | Input 5 | 1 | Output 5 | o | | 6 | Input 6 | 1 | Output 6 | o | | 7 | Input 7 | 1 | Output 7 | o | | 8 | Input 8 | 0 | - | o | | 9 | Input 9 | 0 | - | | | 10 | Input 10 | 1 | Output 10 | | | 11 | Input 11 | 1 | Output 11 | | | 12 | DPlay1 | 1 | Output 13 | | | 13 | DPlay2 | 1 | Denc | | | 14 | Input 14 | 1 | Output 14 | x | | 15 | Input 15 | 1 | Output 15 | x | | 16 | Loopback | 1 | Loopback | |

Video outputs

| ### | x | Video output name | Connected video input | s |

| 1 | L | Enc1 1 | Windows 3 | | | 2 | L | Enc1 2 | Windows 2 | | | 3 | L | Enc1 3 | Windows 1 | | | 4 | L | Enc1 4 | Windows 1 | | | 5 | | Output 5 | Input 5 | x | | 6 | | Output 6 | Input 6 | x | | 7 | | Output 7 | Input 7 | x | | 8 | | Output 8 | Windows 4 HD | | | 9 | L | Enc2 1 | Windows 4 HD | B | | 10 | | Output 10 | Input 10 | B | | 11 | | Output 11 | Input 11 | B | | 12 | L | Denc | DPlay2 | B | | 13 | O | Output 13 | DPlay1 | o | | 14 | | Output 14 | Input 14 | o | | 15 | | Output 15 | Input 15 | o | | 16 | O | Loopback | Loopback | o |

Monitoring outputs

| ### | x | Monitoring output name | Connected video input |

| 1 | | Monitor 1 | Windows 1 | | 2 | O | Monitor 2 | Windows 2 | | 3 | L | Monitor 3 | Windows 3 | | 4 | | Monitor 4 | Windows 4 HD |

Serial ports

| ### | x | Dir | Serial port | Connected serial | s |

| 1 | O | in | Serial Ctrl 1 | Deck 3 | 4 | | 2 | | auto | Serial Ctrl 2 | Deck 4 | 4 | | 3 | L | out | Deck 3 | | 4 | | 4 | | auto | Deck 4 | | 4 | | 5 | | auto | Serial 5 | | | | 6 | | auto | Serial 6 | | | | 7 | | in | Serial 7 | | x | | 8 | | out | Serial 8 | | x |

Processing units

| Proc Unit | x | Connected video input |

| 1 | L | Windows 4 HD | | 2 | | Windows 2 | | 3 | O | | | 4 | | Windows 3 |

Frames

| ### | x | Frame name | Connected output |

| 1 | | Frame 1 | Output 13 | | 2 | L | Frame 2 | Output 14 | | 3 | O | Frame 3 | Output 15 | | 4 | | Frame 4 | | | 5 | | Frame 5 | | | 6 | | Frame 6 | | | 7 | | Frame 7 | | | 8 | | Frame 8 | |

|----------------------------------------------------------------------|

Video inputs Legend

Column 1 (###) - Input port number Column 2 - Input port names Column 3 (nn) - To how much outputs this input is routed. Column 4 - List of output ports which are connected to this input. Column 5 (s) - Port status /type/. Universal Videohub's support BNC/Optical ports and this column shows the port type. - Empty means that the device do not support port status. x - The port type is "None". This means that the port is not installed. B - The port type is "BNC". o - The port type is "Optical". T - The port type is "Thunderbolt".

Video outputs Legend

Column 1 (###) - Output port number Column 2 (x) - Output port lock status L - The port is locked by another IP address (user) O - The port is locked by me (from my IP address) Column 3 - Output port names Column 4 - Which input port is routed to this output Column 5 (s) - Port status /type/. Same format as in input ports.

Serial ports Legend

Column 1 (###) - Serial port number Column 2 (x) - Serial port lock status Column 3 (Dir) - Serial port direction. in - Input/Control (Workstation) port out - Output/Slave (Deck) port auto - Automatic in/out Column 4 - Serial port name Column 5 - Which serial port is connected here. Column 5 (s) - Port status /type/. Same format as in input ports. - Empty means that the device do not support port status. x - The port type is "None". This means that the port is not installed. 4 - The port type is "RS422".

Development

The development is done using git. videohubctrl repository is hosted at

https://georgi.unixsol.org/git/gfto/videohubctrl

To clone the repository issue the following commands:

git clone https://georgi.unixsol.org/git/gfto/videohubctrl.git cd videohubctrl git submodule init git submodule update make

The code is developed and tested under modern Linux. It's also compiled from time to time under OS X but it's not tested there.

Updating the code

To update cloned videohubctrl, go to the directory where the repository is cloned and run the following commands:

git fetch origin git merge origin/master git submodule update make clean all

videohubctrl's master branch should always be useful so it is safe to use it instead of official release. The master branch will always be better than any released version.

Reporting bugs

If you think you have found bug in videohubctrl, please report it to the e-mail listed in Contact section (see below) of this README file.

When reporting bugs, run 'videohubctrl' with debugging enabled by adding several --debug (-d) options on the command line, for example:

videohubctrl -d -d -d --host 192.168.0.1

Please add the full command line that you are using and describe what you think the 'videohubctrl' does wrong.

Also it is very useful to report what VideoHub device reports by running:

telnet your_videohub_ip 9990

save the output and attach it to your bug report.

TODO list

Help is very much welcome for these tasks:

• Find out what these undocumented commands do: END PRELUDE: ENGINEERING:

• Find out what these device options do: Debug mode: Power:

• Test the program with Universal Videohub (statuses, serial ports, monitoring) and Workgroup Videohub (Frames, Processing).

Releases

Official releases can be downloaded from videohubctrl home page which is

https://georgi.unixsol.org/programs/videohubctrl/

Contact

For requests, patches, bug reports, complaints and so on send e-mail to

Georgi Chorbadzhiyski [email protected]