Quantel Device Interface

CONTENTS

  1. INTRODUCTION
  2. ADVANTAGES
  3. FUNCTIONALITY
  4. PREREQUISITES
  5. CONFIGURATION
  6. PROCESS ARCHITECTURE
  7. LOGS/DEBUGGING
  8. LIMITATIONS
  9. Appendix 1

1. INTRODUCTION

This document describes the Thomson Multimedia Quantel LAN library interface. This interface allows Thomson automation systems to perform library and clip management functions for selected Quantel video servers, such as the Power and Studio, using a LAN connection. The LAN connection is a TCP/IP connection and uses the Quantel RCP protocol.

The interface is written in C++ and executes on the main MSL processor.

This interface is an enhanced alternate to the prom-based RS-422 serial interfaces. The serial interfaces must still be used for real-time control of play and record ports.

2. ADVANTAGES

The Quantel LAN library interface provides several advantages over the traditional serial interface.

Automation obtains clip list much faster (at LAN speeds rather than RS-422 speeds). This allows automation records to begin sooner after an automation login.

Library and clip management are performed on a separate Quantel LAN connection and are not commingled with RS-422 real-time play/record functions.

In a multiple-automation system, the load on the Quantel server is reduced as there is just a single "database user" (The LAN library interface) maintaining the clip list in the MSL, rather than each automation having its own dedicated connection.

The Quantel IKNOWN command is utilized, in addition to the INEW command, to take advantage of the Quantel ability to remember clip registrations.

Backup automation computers are able to have a pgmid list, so a takeover does not have to wait for getting a pgmid list.

3. FUNCTIONALITY

At startup, the interface attempts to connect to the Quantel server on a private LAN. During this time, the status reported to automation is "interface online" but "NO COMM" motion to the Quantel. When connected, it first performs some initialization functions, including:

Identifying the Device (Power or Studio)
Resetting the filter (FILTER RESET)

Because the Studio supports a broader RCP protocol, the interface will also perform the following when a Studio is detected:

Obtaining the server clip count obtains the clip list (DIR COUNT)
Obtaining the server free space (SPACE COM)*

The interface then obtains the clip list, using the configured database user ID, using the following sequence of commands:

Request registered clip FID (IKNOWN DBID) [DEFAULT]
       (or)
Unregister ALL (if getting list for first time or enabled by env var**)
Request clip attributes (GET TITLE, GET NUMBER, GET DURATION)

An "info" message is sent to all connected automations when the unregister command starts and completes. The unregister command may take several minutes on a server with thousands of clips.

 

*) Because the Power does not support this command, the interface will always report the maximum space.

 

**) QUANTEL_SOCKET_NO_IKNOWN Force an unregister all and use INEW command to obtain a new list (TRUE/FALSE); default FALSE (use IKNOWN)

SEE CAVEATS FOR THE POWER INTERFACE IN APPENDIX 1!

As the list is being obtained, additional "info" messages are sent toAutomations as every 100 clips are obtained. This gives some feedback to the automation operator that the MSL is connecting to the server. Getting the list may take several minutes on a server with thousands of clips. So if an MSL is rebooted, or if a master reset is performed, the Quantel library module and clip list may not be available for several minutes as the MSL gathers the list.

Once the initial clip list is obtained, the interface then enters a polling mode to maintain the list as changes occur, using the following sequence of commands: 

  1. Request deleted clips (IDELETED DBID)
  2. Request modified clips (IMODIFIED DBID)
  3. Request server free space (SPACE COM)* If new or deleted, request clip count (DIR COUNT)** 

 

*  STUDIO only

 

** STUDIO only

For any clip addition, deletion or modification, the interface requests new clip attributes and volunteers the new data to all connected automations. For any change in the clip count or server free space, the interface volunteers the new data to all connected automations. While maintaining the list, the interface does an internal delay of two seconds between the INEW response and asking for clip attributes. This is to prevent any timing race conditions between a new clip recording that may be occurring on an RS-422 serial port. In particular, an automation secondary record that is terminated early results in some special prom interface operations that create a truncated copy of the clip and transfer the clip attributes to the copied clip. The two-second delay allows time for the prom interface to complete its sequence of operations before the LAN interface obtains clip attributes. Without this delay, it would be possible to encounter clips with no title or number. If the library process clip count becomes different from the Quantel provided clip count, an error message is reported to automation and the library process obtains a new clip list from the Quantel server. While this is occurring, the interface processes will temporarily report NO COMM to the Quantel server. The LAN library interface supports the following functions from automation:

  1. Open (flags byte controls options) 
  2. Close Request new clip list
  3. Request new clip list with flow control
  4. Abort sending clip list Lookup clip by name (title)
  5. Lookup clip by number
  6. Lookup clip by FID
  7. Delete clip by number
  8. Delete clip by FID
  9. Request interface status
  10. Request system status
  11. Request identification string
  12. Master reset

The following flag bytes are supported for the open command:

  1. COMPRESSION controlled by automation environment variable DVS_COMPRESSION
  2. DIR COUNT controlled by automation environment variable DVSn_HAS_COUNT

Requesting a list is done using a flow-control mechanism that prevents the automation from being overrun with clips. The default is 20 clips per "chunk", overrideable with automation environment variable DVS_LIST_CHUNK_SIZE. The interface returns clips at the rate of 3 per frame, up to the chunk size, and then waits for a "continue" command from automation. For NTSC, this is 90 clips/second, 5400 clips/minute. For PAL, this is 75 clips/second, 4500 clips/minute. These are theoretical maximum values, assuming no transmission time to automations and an infinitely fast and responsive automation computer. While actual clip upload rates are more like 3000-4000 clips/minute on a "normal" automation computer, version 2.010 includes a significant speedup (about 2X) in the response time of the interface to automation requests.

The clip lookups are performed on the internal MSL clip list. The lookups are not passed on the Quantel server as the Quantel prom interface did.

The master interface reset function (actually performed by the DRM device resource manager) can be used to force the library interface to obtain a new clip list from the Quantel server. If the MSL and Quantel clip lists ever become out of sync, the master reset will get them back in sync. The master reset slays the interface processes for ALL connected automations (presumably all automation and MSL clip lists have the same problem), slays the library process, and then restarts the library process and all interface processes. The interface processes will temporarily report NO COMM to the Quantel while the library processes obtains the clip list.

4. PREREQUISITES

MSL software version 4.01 or newer is required. An additional PCI LAN card is required for the Quantel server connection.

Automation software version 6.80a or newer is required. Each automation computer must have one DVS port configured as a system-only port. The following automation environment variables should be set:

  1. DVS_LIST_IN_CHUNKS=TRUE
  2. DVSn_HAS_COUNT=TRUE
  3. DVSn_REQUIRE_SYSTEM_ONLY_PORT=TRUE
  4. DVS_COMPRESSION=TRUE

Quantel Studio software (version C4.05/001 or newer) and/or Quantel Power Protocol Manager software (version C8-23/001 or newer) with Clipnet (version X1.32.0101 or newer) is required (X1.35.014 is prefered). The LAN RCP application software is included in this release and is automatically started. The LAN card is present and active in a standard Studio system.

5. CONFIGURATION

The following steps are required to configure the library interface.

  1. Find out the IP address of the Quantel server. This can be obtained in several ways using the RMON console and the studio window. If the Quantel has recently booted up, do a "log 0" and using control-S, control-Q find the startup section where the IP address is displayed. A typical value is 10.10.10.2. Otherwise, go to the config prompt by typing CONFIG. Then type BOOT to list the boot parameters, which include the IP address. 

    If it is necessary to change the Quantel IP address or netmask, you also use the BOOT command from the Config prompt:

                      BOOT [FLAGS | IP ] 

    The BOOT command is used to print or set the vxWorks boot parameters. With no parameters it prints the current boot parameters. With the FLAGS parameter it sets the boot flags. The number entered can be hex if preceded by a $. With the IP parameter, the IP address and netmask can be set. This should be of the form nnn.nnn.nnn.nnn:xxxxxxxx Where nnn are the four parts of the IP address and xxxxxxxx is the optional netmask as a hexadecimal number with no leading $.
  2. Enter the IP address in the MSL /etc/hosts file with a name of the server, such as quantel1. The default name is clipbox.
  3. Enter an IP address to be used for the LAN card in the MSL. A typical value is 10.10.10.10 and the default name is quantellan.
  4. Edit the MSL environment variable file /usr/alamar/msl/bin/msl_env and make the following entries:

ENV VAR

Default

QUANTEL_SERVER_NAME

clipbox

QUANTEL_SERVER_PORT

5000

QUANTEL_LIBRARY_PORT

91

QUANTEL_LIBRARY_DID

31

QUANTEL_COMPRESSION_ENABLED

FALSE

QUANTEL_SOCKET_IGNORE_CLIPCOUNT

FALSE

QUANTEL_SOCKET_NO_DIRCOUNT

FALSE

QUANTEL_SOCKET_VERBOSE

FALSE

  1. The Quantel server name value must match the /etc/hosts name. The Quantel server port is the TCP port number used to connect to the Quantel. The Quantel library port is the pseudo-port number used in the RCP commands for the Studio (such as P91). If there are more than one MSL connecting to the Studio, each MSL must have its own library port value. The Power RCP does not include the port ID. The Quantel library database ID is the database ID used in the INEW, IDELETED, IMODIFIED, etc commands. If there are more than one MSL connecting to the Quantel, each MSL must have its own library database ID value. The Quantel compression enabled flag should be set TRUE so that the COM argument is added to the SPACE command to obtained compressed space.
  2. There are additional configuration items in the file /usr/alamar/msl/config/system/devif.xml in XML format. This file configures ALL MSLs and ALL devices in ALL MSLS. This file is most easily viewed using a web browser editor, but the browser cannot perform editing. Editing must be done with normal text editors, such as vi. Someday, there will be a GUI-based configuration editor. The devif.xml file contains a section for the library interface in general, and then there are sections for each automation interface. This file is explained in more detail in the "MSL 4.01 Configuration Guide", Part #04-052552-001.

The device should be configured as follows:

Device Interface Specification:

  Device Type:

DVS

  Manufacturer: 

quantel

  Model: 

AUTO_ID

  Device I/O Model: 

Shared Device I/O

Shared Device I/O Specification

 Comm Type: 

ETH

 Port Number:

any

 Argument List:

none

The following is a sample devif.xml file. It configures a Quantel library module on an MSL named lab401, node 4. It specifies the startup command line of "quanteldvseth p13". It then specifies five interfaces using MSL Ids 16-20, named Studio16-Studio20.

<?xml version="1.0" standalone="no"?>
<?xml-stylesheet type="text/xsl" href="devif.xsl"?>
<!DOCTYPE MachineControl SYSTEM "devif.dtd">
    <MachineControl>
        <UNIT UnitName="lab401" UnitNo="0">
            <NodeId>4</NodeId>
            <AUX Id="QuantelLib">
                <ExecName>quanteldvseth
                <ArgList>-p13</ArgList>
          </AUX>
          <DEVICE SmpteId="16">
              <Name>Studio16</Name>
              <Type>DVS</Type>
              <Manuf&gtquantel</Manuf>
              <Model&gtAUTO_ID</Model>
              <CommType&gtQuantelLib</CommType>
              <PortNumber&gt9</PortNumber>
              <AutoRestart&gtYES</AutoRestart>
              <RestartDelay>1</RestartDelay>
        </DEVICE>
        <DEVICE SmpteId="17">
            <Name>Studio17<Name>
            <Type>DVS</Type>
            <Manuf&gtquantel</Manuf>
            <Model&gtAUTO_ID</Model>
            <CommType&gtQuantelLib</CommType>
            <PortNumber&gt9</PortNumber>
            <AutoRestart&gtYES</AutoRestart>
            <RestartDelay>1</RestartDelay>
        </DEVICE>
        <DEVICE SmpteId="18">
            <Name>Studio18<Name>
            <Type>DVS</Type>
            <Manuf&gtquantel</Manuf>
            <Model&gtAUTO_ID</Model>
            <CommType&gtQuantelLib</CommType>
            <PortNumber&gt9</PortNumber>
            <AutoRestart&gtYES</AutoRestart>
            <RestartDelay>1</RestartDelay>
        </DEVICE>
        <DEVICE SmpteId="19">
            <Name>Studio19<Name>
            <Type>DVS</Type>
            <Manuf&gtquantel</Manuf>
            <Model&gtAUTO_ID</Model>
            <CommType&gtQuantelLib</CommType>
            <PortNumber&gt9</PortNumber>.
            <AutoRestart&gtYES</AutoRestart>
            <RestartDelay>1</RestartDelay>
        </DEVICE>
        <DEVICE SmpteId="20">
            <Name>Studio20<Name>
            <Type>DVS</Type>
            <Manuf&gtquantel</Manuf>
            <Model&gtAUTO_ID</Model>
            <CommType&gtQuantelLib</CommType>
            <PortNumber&gt9</PortNumber>
            <AutoRestart&gtYES</AutoRestart>
            <RestartDelay>1</RestartDelay>
        </DEVICE>
    </UNIT>
</MachineControl>

The following is a browser view of the devif.xml file. To get the MSL to serve up the html, you must enable the http server in the env_sysinit.

6. PROCESS ARCHITECTURE

In /usr/alamar/msl/bin/Interfaces there is an executable quanteldvs that handles the automation interface. Its usage line is:

quanteldvs -I Assigned ID
                -m Model Name (e.g. "CLIPBOX", or "AUTO_ID")
                -n Name (e.g. "JoeBob" or "VTR_1")
                -p Port Id
               [-d] [-L] [-P] [-S] [-v] [-x]

Start a Device Driver

Options:

-d 

Enable debug logging

-L

Dump the machine list and exit

-P

Process priority

-S

Scheduling policy

-v

Just display version and exit

-x

Wait for debug

Environmental variables:

QUANTEL_SERVER_NAME

Specify the quantel host name

QUANTEL_SERVER_PORT

Specify the service port

QUANTEL_LIBRARY_PORT

Specify the library port number

QUANTEL_LIBRARY_DID

Specify a unique ID between 1 and 32

QUANTEL_COMPRESSION_ENABLED

TRUE or FALSE (required for Studio)

In /usr/alamar/msl/binInterfaces/DevIo there is an executable quanteldvseth that handles the library maintainence.
Its usage line is:

quanteldvseth [-a] [-d] [-P] [-S] [-v] -p port

     where -p port         A port number used to form a port ID and a logfile name

Start a Quantel DevIo

Options:

-a

Do not send empty (ACK) message to parent

-P

Run at this priority

-S

Run with this Schedule policy

-d

Enable debug mode

-v

Just print version and exit

Environmental variables:

QUANTEL_SERVER_NAME

Network name of capture computer

QUANTEL_SERVER_PORT

Service (port) number for socket

 

In /usr/alamar/msl/binInterfaces/DevIo there is an executable QuantelSocket that handles communication to the Quantel Ethernet port. It forks itself to create a reader and write. Its usage line is:

QuantelSocket -a -d -v -x -P [priority] -S [sched algorithm] -h server -l logname -s service -p proxy

QuantelSocket is an I/O driver for a Socket type DevIo Process

You must provide at lease the following arguments:

-h

server name The name of the SocketPort Capture Station

-l

logname The name of the logfile to attach to.

-s

number The port number for the service on the host machine.

-p

proxy Data proxy to fire when messages are received

Options:

-a

send ACK to parent

-d

set debug flag

-v

print version information and quit

-x

hold for debugger

-P

set priority (0..29)

-S

set scheduling method (0=FIFO, 1=RR, 2=OTHER)

Example:

QuantelSocket -h SocketPort0 -l SocketPort -s 3000 -p 1532

7. LOGS/DEBUGGING

Logs may be generated in the normal fashion via an automation F1 log save. Logs may also be generated by executing the msl_F1 script via a telnet login.

All logs are saved in the /usr/alamar/msl/mslx.hd directory, where x is the MSL node number. There are the standard MSL logs for cfgmgr, dcm, drm, mslserver, pgmclk, rs422, etc. There are subdirectories for the month. There are .lg and .er log files for each log save.

There are log files in the .../devio/devio.edev.QuantelPort91 directory for the library I/O module that is shared by each automation interface.

There are log files in the .../devices/ directory for each automation interface process.

There is a directory of the form thomson.devices.Studio16 for each process. The name of the directory corresponds to the name in the devif.xml configuration file.

The normal MSL environment variables, such as HISTORY_LOG_SIZE, are supported. These variables, and any Quantel specific variables should be set in the file /usr/alamar/msl/bin/msl_env.

The following are environment variables of interest for debugging problems:

QUANTEL_SERVER_NAME

Specify the quantel server name (from hosts file);default of clipbox

QUANTEL_SERVER_PORT

Specify the service port (5001 - 5008); default 5001 

QUANTEL_LIBRARY_PORT

Specify the library port number (91 - 98); default 91

QUANTEL_LIBRARY_DID

Specify a unique DID (1 - 32); default 31

QUANTEL_COMPRESSION_ENABLED

Add COM to SPACE command (TRUE or FALSE); default FALSE

QUANTEL_SOCKET_VERBOSE 

Log LAN communications (TRUE/FALSE); default FALSE 

QUANTEL_SOCKET_IGNORE_CLIPCOUNT 

Don't get new list when counts don't match (TRUE/FALSE); default FALSE

QUANTEL_SOCKET_NO_DIRCOUNT 

Don't do a request for number of clips (TRUE/FALSE); default FALSE

QUANTEL_SOCKET_NO_IKNOWN 

Force an unregister all and use INEW command to obtain a new list (TRUE/FALSE); default FALSE (use IKNOWN) 8.

      

 

8. TEST PLAN

This section describes a wide range of tests that can be performed at installation time to verify proper operation of the automation and interface.

Test Setup

Advanced Functionality

This section consists mostly of invoking each relevant option in the automation pgmid list menu and then checking for the proper result. The mirrored DVS compare function should be invoked after each test.

This section does additional testing:

Exception Conditions

This section tests various unusual and exception conditions:

9. LIMITATIONS

The interface does not support the automation commands to protect or unprotect a clip from deletion (Neither does Quantel). 

The interface does not support the automation commands to save/restore clips to/from a tape archive (Neither does Quantel). 

The interface does not support the automation commands to copy clips from one server to another over the Quantel LAN. This feature is supported by Quantel and could be a future enhancement to the interface. 

The interface does not perform pgmid to clip number mapping. If desired, this function must be enabled in automation using environment variable DVS_CLIPBOX_PGMID_MAPPING=TRUE.

10. Appendix 1

When a Quantel Power (with the software versions earlier than X1.35.014) is loaded with thousands of clips, an unregister command over the LAN will often time out. Once that occurs, there is only one way to restart the Library module successfully:

1. Stop the MSL. - At a console, login as root and execute "msl_stop"
2. Wait for the Power rmon to show the unregister complete.
3. Reboot the power and wait for it to become active.
4. Restart the MSL . - At a console, login as root and execute "msl_start"

Seeing any of the following entries in the devio.edev.XXX log file is an indication of this problem.

04:44:25:27: 11690: Received ERR message from Quantel

============================================================

We sent:

Logging 11 bytes of data at 0x42475E:

Data[000]: 49 55 4E 20 33 31 20 41 4C 4C IUN 31 ALL

Data[010]: 0D .

Quantel replied:

Logging 17 bytes of data at 0x42485D:

Data[000]: 3E 45 52 52 20 34 20 4E 6F 20 >ERR 4 No

Data[010]: 52 65 70 6C 79 0D 0A Reply..

============================================================

04:44:25:27: 11690: Unregister Cmd Returned Error Message!

Data[000]: C8 50 39 31 23 2F 53 54 53 0D .P91#/STS.

03:36:00:02: 8664: Received 2 byte message from Quantel

Logging 2 bytes of data at 0x42485D:

Data[000]: 3E 0A >.

NOTE: Do not confuse the following message (which is expected and normal) with the error above.

04:21:11:17: 10601: Received ERR message from Quantel
 =========================================================

We sent:

Logging 10 bytes of data at 0x42475E:

Data[000]: C8 50 39 31 23 2F 53 54 53 0D .P91#/STS.

Quantel replied:

Logging 27 bytes of data at 0x42485D:

Data[000]: 3E 45 52 52 20 35 20 6C 65 74 >ERR 5 let

Data[010]: 74 65 72 20 65 78 70 65 63 74 ter expect

Data[020]: 65 64 20 40 31 0D 0A ed @1.. 
=========================================================