Giter Site home page Giter Site logo

gfto / videohubctrl Goto Github PK

View Code? Open in Web Editor NEW
25.0 5.0 9.0 182 KB

videohubctrl can be used to control Blackmagic Design Videohub SDI router device over the network.

License: MIT License

Makefile 3.62% C 72.97% Shell 11.52% C++ 0.44% Roff 11.45%

videohubctrl's Introduction

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 <host>           | Set device host name.
 -p --port <port_number>    | Set device port (default: 9990).
 -t --timeout <secs>        | 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 <name>          | Set the device "friendly name".

Inputs configuration:
 --in-name <in_X> <name>       | 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> <name>     | 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> <name>    | 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> <name>     | 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> <dir>       | Set serial port X direction.
                               . <dir> can be 'auto', 'in' or 'out'.

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> <name>       | 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 <file>     | Read commands from <file>.
 -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]>

videohubctrl's People

Contributors

gfto avatar jfpanisset avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar

videohubctrl's Issues

ALARM STATUS on Universal Videohub 288

Here's what the telnet interface reports on a Universal Videohub 288:

ALARM STATUS:
Fan 0: ok
Fan 1: ok
Fan 2: ok
Power Supply Slot 0: ok
Power Supply Slot 1: ok
Power Sufficient for Load: ok
Network Slot 0: ok
Network Slot 1: ok
Card Bus: ok
Card Firmware Version: ok
Logic Slot 0: ok
Logic Slot 1: ok
Logic Firmware Version Slot 0: ok
Logic Firmware Version Slot 1: ok
ProcessorLink: ok
Processor Firmware Version: ok
Crosspoint Slot 0: ok
Crosspoint Slot 1: ok
Bus Host Slot 0: ok
Bus Host Slot 1: ok
Bus Host Firmware Version Slot 0: ok
Bus Host Firmware Version Slot 1: ok

This appears to be informational only, there's not really anything actionable from an API perspective. But would be useful to present it to the caller / not error out on it.

Issues with Universal Videohub 288

When I point the code at a Universal Videohub 288 running firmware 2.3, although the code recognizes the device, it prints all empty listings for the inputs and outputs.

If I add a call to sleep(1); after calling connect_client(), that seems to leave enough time for the router network interface to "wake up" and return the information expected by the code. I then get mostly sensible output from --list-inputs for instance, but I also get some debugging output such as:

WARNING: Videohub sent unknown command!
...
WARNING: VIDEO OUTPUT STATUS command returned unknown status: 'N'

I'll try to dig a bit more into this and hopefully submit some PRs.

Incorrect units for timeout value

The -t / --timeout command line argument is defined as:

 -t --timeout <secs>        | Set connect/read timeout. Default: 15

This timeout value defaults to 15 and is clamped to between 0 and 60 in parse_args(), and is then passed to fdread_ex() which in turn passes it to poll(2), but poll(2) defines its timeout argument in milliseconds, not in seconds. This causes problems on larger routers such as the Universal Videohub 288, where the default timeout value of 15 msec is not enough to allow the router to send its complete response, causing read_device_stream() to fail to parse an incomplete response from the router.

Fortunately the current maximum timeout value of 60 msec (--timeout 60) seems to be sufficient in my environment to read the complete response from the Videohub 288, but that's not very robust.

A couple of possible approaches to resolving this:

  • change the documented definition of -t / --timeout to msec, increase the maximum accepted value to (say) 60,000 aka 60 seconds: this has the advantage of not changing the behavior of the application for existing scripts, while making it clear that the parameter is in msec rather than seconds
  • keep the definition of -t / --timeout in seconds, multiply timeout by 1000 either when calling fdread_ex() or when calling poll(2) inside fdread_ex(): this changes the behavior of the application for existing scripts, but presumably a working setup doesn't rely on timeouts being exceeded, so multiplying the timeout value by 1,000 shouldn't break anything?

All commands take too long to run

All commands take more than a minute to run. This is over an OpenVPN vpn but the ping time to systems on that network is only in the 20-50ms range. I'm going do some logging to see where the delays come from. I don't suppose there is an existing time logging feature?

For reference the device info as printed by the tool is below

  -------------------------------------------------------------------
  | Device address             | 192.168.137.3                      |
  | Device port                | 9990                               |
  | Model name                 | Blackmagic Smart Videohub 40 x     |
  | Friendly name              | Smart Videohub 40 x 40             |
  | Unique ID                  | 7C2E0DA63C9F                       |
  | Protocol                   | 2.8                                |
  | Video inputs               | 40                                 |
  | Video outputs              | 40                                 |
  -------------------------------------------------------------------

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.