Blackmagic Ultimatte12 User Manual Developer Information

Controlling Ultimatte using Telnet

The Blackmagic Ultimatte 12 Ethernet Protocol gives you the freedom to build your own custom control solutions for your Ultimatte 12. For example, you can create your own software application and control your Ultimatte via Ethernet from your computer.

The first step is to connect your Ultimatte to your computer via Ethernet. You can do this by connecting Ultimatte to the same network your computer is connected to, or you can connect Ultimatte directly to your computer.

📘

NOTE If your Blackmagic Ultimatte is connected directly to your computer, set your computer to a manual static IP address. Set the first three blocks of numbers in the IP address to match your Ultimatte and set the subnet mask to 255.255.255.0. You can leave the gateway or router setting blank as it will not be used in a direct connection between your computer and Ultimatte.

If your network settings are set correctly, you can now open the Terminal application on Mac OS, or enable Telnet command line utilities on Windows and enter Ultimatte control protocol commands. These commands can be programmed into your application and triggered by related items on a custom user interface of your own design.

Below is a basic example of using Telnet to change the backing color, restore to factory defaults, and adjust the matte density control.

1. In the Terminal application, type the following:

   telnet (IP address of main unit (space) port number)(enter)
   For example: telnet 192.168.10.220 9998
   Press ‘enter’.

   A list of status information will appear and you are ready to control your Ultimatte.

2. Now type the following:

   control: (press enter)
   backing color: blue (press enter twice)

   Terminal will acknowledge the action with ‘ack’ and confirm it so you know your setting has been performed.

   You have now changed Ultimatte’s backing color to blue.

3. To restore to factory defaults, type the following:

   control: (press enter)
   factory defaults: yes (press enter twice)

   This restores your Ultimatte to factory default settings and performs an automatic composite.

4. To adjust the matte density setting, type the following:

   control: (press enter)
   matte density: 273 (press enter twice)

   Terminal will acknowledge and confirm the action.

   You have now adjusted the matte density setting.

5. To exit Telnet:
   Hold down the control button and press the ‘]’ key. The Telnet prompt will appear.
   Type the following:
   quit(press enter)

A status message will appear confirming the connection is closed.

Blackmagic Ultimatte 12 Ethernet Protocol

Version 2.0

If you are a software developer you can use Ultimatte Ethernet Protocol to construct devices that integrate with our products. Here at Blackmagic Design our approach is to open up our protocols and we eagerly look forward to seeing what you come up with!

Overview

The Blackmagic Ultimatte Ethernet Protocol is a text based protocol that is accessed by connecting to TCP port 9998 on an Ultimatte.

Ultimatte sends information in blocks. Each block has an identifying header in all caps, followed by a full colon. A block spans multiple lines and is terminated by a blank line. Each line in the protocol is terminated by a newline character.

Upon connection, the Ultimatte device sends a complete update of its status. After the initial status transmission, status updates are sent every time the Ultimatte device’s status changes.

To be resilient to future protocol changes, clients should ignore blocks they do not recognize, up to the trailing blank line. Within existing blocks, clients should ignore lines that they do not recognize.

Protocol Preamble

The first block sent by Ultimatte is always the protocol preamble:

PROTOCOL PREAMBLE:↵
Version: 2.0↵
↵

The version field indicates the protocol version. When the protocol is changed in a backwards compatible way, the minor version number will be updated. If incompatible changes are made, the major version number will be updated.

Identity

The next block contains information about the device identity.

IDENTITY:↵
Model: Ultimatte 12 8K↵
Label: Ultimatte 12 8K↵
Unique ID: 12345678↵
↵

Network Information

There are two network blocks. The first describes the general network information and the second describes the network interface details.

NETWORK:↵
Interface count: 1↵
Default Interface: 0↵
Static DNS Servers: 8.8.8.8, 8.8.4.4↵
Current DNS Servers: 8.8.8.8, 8.8.4.4↵
↵

NETWORK INTERFACE 0:↵
Name: Cadence GigE Ethernet MAC↵
Priority: 0↵
MAC Address: xx.xx.xx.xx.xx.xx↵
DynamicIP: false↵
Current Addresses: 10.0.0.2/255.255.255.0↵
Current Gateway: 10.0.0.1↵
Static Addresses: 10.0.0.2/255.255.255.0↵
Static Gateway: 10.0.0.1↵
↵

Version Information

The version information describes the hardware and software version numbers and identifiers of the device. For example, the “Product ID” field contains the hexadecimal USB Product Identifier.

VERSION:↵
Product ID: BE84↵
Hardware Version: 0100↵
Software Version: 09A89B7A↵
Software Release: 2.0↵
↵

Device Information

The next block contains general information about the connected Ultimatte device.

DEVICE:↵
Video Format: 1080p60↵
Reference Source: Foreground↵
FG In: Locked↵
BG In: Locked↵
MONITOR In: Locked↵
G MATTE In: Locked↵
H MATTE In: Locked↵
REFIn: Locked↵
BG MATTE In: Locked↵
LAYER In: Locked↵
LAYER MATTE In: Locked↵
↵

📘

NOTE Some Ultimatte models will only have a subset of the above-mentioned inputs.

For example, the Ultimatte 12 HD Mini only has the following inputs:

• Foreground input (FG In), and

• Background input (BG In).

Similarly, the Ultimatte 12 HD only has the following inputs:

• Foreground input (FG In),

• Background input (BG In),

• Garbage Matte input (G MATTE In),

• Holdout Matte input (H MATTE In),

• Monitor Input (MONITOR In), and

• Reference Input (REF In).

Video Formats Information

The Video Formats blocks lists the video formats supported by the device. See the Video Format Control list to find the formats supported by each device.

VIDEO FORMATS:↵
auto detect↵
525.59.94 NTSC 4:3↵
625i50 PAL 4:3↵
720p60↵
...
↵

Initial Status Dump

The next eleven blocks provide the control values, control default values, current file, file list, the GPI lists, the Frame Buffer Image List and Frame Buffer State.

CONTROL:↵
Matte Density: 0↵
Red Density: 0↵
Green Density: 0↵
...(Full list in Controls section)
↵

CONTROL DEFAULT:↵
Matte Density: 0↵
Red Density: 0↵
Green Density: 0↵
...(Full list in Controls section)
↵

CURRENT FILE:↵
Filename↵
↵

FILE LIST:↵
File 1↵
File 2↵
↵

GPI LIST: ↵
ID: 1↵
Index: 0↵
File 1↵
File 2↵
↵

📘

NOTE The Ultimatte 12 HD Mini does not have GPI inputs, so this block is not available on that device.

The IMAGE LIST block contains the filenames of images that are currently stored on the device. These images can be assigned to Frame Buffer inputs.

IMAGE LIST:↵
Image 1↵
Image 2↵
↵

The FRAME BUFFER block contains the status of the Frame Buffers on the device. This information will show:

• How many image buffers are available,

• whether a frame buffer is enabled and has an image buffer assigned to it, and

• how frame buffer transitions are set up for those frame buffers that support transitions.

📘

NOTE Frame Buffer Duration time is in milliseconds.

FRAME BUFFER:↵
Number Of Frame Buffers: 46↵
BG 1 Frame Buffer Enable: off↵
BG 1 Frame Buffer Index: 0↵
LY 1 Frame Buffer Enable: off↵
LY 1 Frame Buffer Index: 0↵
BG 2 Frame Buffer Enable: off↵
BG 2 Frame Buffer Index: 0↵
LY 2 Frame Buffer Enable: off↵
LY 2 Frame Buffer Index: 0↵
GM Frame Buffer Enable: off↵
GM Frame Buffer Index: 0↵
HM Frame Buffer Enable: off↵
HM Frame Buffer Index: 0↵
BG Frame Buffer Mix: 0↵
LY Frame Buffer Mix: 0↵
BG Transition Duration: 0↵
LY Transition Duration: 0↵
Frame Buffer 1: Image 1↵
Frame Buffer 2: Image 2↵
...
↵

End Prelude

The final block of the status dump sent by Ultimatte is always end prelude:

END PRELUDE:↵
↵

Status Updates

When any Control is changed on an Ultimatte device, the Ultimatte device replies with the applicable status block to all connected clients, containing only the items that have changed. For example, if Matte Density has been changed, the following block will be sent:

CONTROL:↵
Matte Density: 0↵
↵

If multiple items are changed, multiple items may be present in the update:

CONTROL:↵
Matte Density: 0↵
Red Density: 0↵
↵

These notifications are sent whether the change originated from the front panel, or from any other connected client.

Requesting Changes

To update a Control the client should send a block of the same form Ultimatte sends when its status changes. For example, to change Matte Density to 100, the client should send the following block:

CONTROL:↵
Matte Density: 100↵
↵

The block must be terminated by a blank line. On receipt of a blank line, Ultimatte will either acknowledge the request by responding:

ACK↵
↵

or indicate that the request was not understood by responding:

NAK↵
↵

After a positive response, the client should expect to see a status update from Ultimatte showing the status change. This is likely to be the same as the command that was sent, but if the request could not be performed, or other changes were made simultaneously by other clients, there may be more updates in the block, or more blocks. Simultaneous updates could cancel each other out, leading to a response that is different to that expected.

In the absence of simultaneous updates, a simple control change will result in the following protocol exchange:

CONTROL:↵
Matte Density: 0↵
↵

ACK↵
↵

CONTROL:↵
Matte Density: 0↵
↵

The asynchronous nature of the responses means that a client should never rely on the desired update actually occurring and must simply watch for status updates from Ultimatte and use only these to update its local representation of Ultimatte’s state.

A client may also request Ultimatte to change a control by a relative amount. For example, to change Matte Density by 10, the client should send the following block:

CONTROL:↵
Offset Matte Density: 10↵
↵

Only controls with numerical ranges support this relative mode.

Requesting a Status Dump

The client may request that Ultimatte resend the complete state of any status block by sending the header of the block, followed by a blank line. In the following example, the client requests Ultimatte resend the control status:

CONTROL:↵
↵

ACK↵
↵

CONTROL:↵
Matte Density: 0↵
Red Density: 0↵
Green Density: 0↵
...(Full list in Controls section)
↵

File System

The client may request that Ultimatte load, save, delete, or rename a file. To load a file the client should send the following block:

FILE:↵
Load: <filename>↵
↵

Ultimatte will respond with an ACK followed by a Current File block or a Message block.

To save, delete, or rename a file the client should send one of the following blocks:

FILE:↵
Save: <filename>↵
↵

FILE:↵
Delete: <filename>↵
↵

FILE:↵
Rename: <filename>↵
To: <filename>↵
↵

In each case Ultimatte will respond with an ACK followed by a File List block or a Message block.

GPI Event List

The client may request that Ultimatte add, insert or remove an event to a GPI Event List by sending an Insert GPI Event or Remove GPI Event command, followed by a blank line. For example, to insert an event, the client should send the following block:

GPI:↵
ID: 1↵
Insert: <filename>↵
At: -1↵ {The insertion index. A ‘-1’ represents the end of the list}
↵

To remove an event a client would send the following block:

GPI:↵
ID: 1↵
Remove: 1 ↵ {Event index to remove. A ‘0’ will delete all events}
↵

To set the current event index a client would send the following block:

GPI:↵
ID: 1↵
Index: 1↵
↵

Ultimatte will respond with an ACK message followed by either a GPI List Block or a Message Block.

GPI LIST:↵
ID: 1↵
Index: 0↵
File 1↵
File 2↵
...
↵

or

MESSAGE:↵
Warning: Event limit exceeded↵
↵

Frame Buffer

The client may request that the Ultimatte device assign a pre-loaded image from its Media Pool into a particular frame buffer and enable/disable the frame buffer. To assign and enable an image to the BG frame buffer the following commands are required:

FRAME BUFFER:↵
BG 1 Frame Buffer Index: 1↵
BG 1 Frame Buffer Enable: on↵
↵

To disable the frame buffer only the enable command is required:

FRAME BUFFER:↵
BG 1 Frame Buffer Enable: on↵
↵

📘

NOTE The Telnet interface does not currently provide loading or removing images in the Media Pool. This has to be done from either a Smart Remote 4, or using the Software Control application. Refer to the ‘using the media pool’ section of this manual for more information.

Camera Control

Ultimatte 12 HD Mini can be used to control an attached camera via SDI or HDMI, please refer to the ‘Camera Control via Ultimatte 12 HD Mini’ section for more information. For SDI Camera Control, the Ultimatte device’s Camera ID may be changed using the CAMERACONTROL block:

CAMERACONTROL:↵
Camera Id:↵
↵

📘

NOTE This control block is only available on the Ultimatte 12 HD Mini.

1. These ranges are Ultimatte device dependent. For Ultimate 12 8K running protocol 2.0, the range is 0-6. For Ultimatte 12 running version 1.2, the range is 0-3.

2. These controls are only available in protocol version 2.0 and up.

3. Loop outputs for ‘garbage matte’ and ‘holdout matte’ inputs are available for Ultimatte 12, not Ultimatte 12 8K.

4. Supported video formats are Ultimatte device dependent. 4320p formats are available for Ultimatte 12 8K. Ultimatte 12 HD Mini does not support PsF video formats.

5. These controls represent functions. Send ‘Yes’ to execute the function. Ultimatte will respond with a ‘Yes’ to indicate the function is complete.

* These controls are not available on the Ultimatte 12 HD Mini

** These controls are not available of the Ultimatte 12 HD or HD Mini