Using Matrox ConvertIP with Crestron Controller Devices

Version: 20342-401-0100 - June 16, 2023

IntroductionOverview of Matrox ConvertIPSupported applications and appliancesConnecting your Matrox ConvertIPInitial setup overviewLogging in to ConvertIPControlling ConvertIP with Crestron Touch PanelsWorkflow diagramConvertIP REST API callsUsing Postman to test your REST APIImplementing the ConvertIP REST API with CrestronMatrox ConvertIP Crestron Module DemoContact usDisclaimer

Introduction

This document serves as a supplement to the Matrox ConvertIP Installation and User Guide. It supplies Crestron users with the necessary information for integrating the ConvertIP REST API with a Crestron media controller device. This integration allows Crestron clients to utilize ConvertIP devices in conjunction with various Crestron touch panels and similar products.

While this document provides an overview of ConvertIP and the tasks needed for initial setup, you can find more detailed information on any of the topics in the official documentation available at: https://video.matrox.com/en/support/resources.

Overview of Matrox ConvertIP

The Matrox ConvertIP family of products are standards-based transmitters and receivers that enable interoperable, cost-efficient, and scalable networks in Broadcast and Pro AV environments.

Broadcast and media applications: Switching from SDI to IP broadcast networks can be costly and complex. Matrox ConvertIP is a stand-alone SMPTE ST 2110 converter engineered to help you easily transition to IP. Supporting multiple input/output connectivity options, ConvertIP is designed to effortlessly convert ST 2110 IP signals to or from SDI or HDMI. ConvertIP devices also support up to 25 Gbps connectivity allowing for the delivery of uncompressed 4K video over ST 2110.
Professional AV/IT applications: Matrox ConvertIP is a series of standards-based, IPMX-ready encoders and decoders designed for maximum flexibility, scalability, and interoperability. ConvertIP provides multiple input/output connectivity options for converting SMPTE ST 2110 IP signals between HDMI, HDBaseT, or SDI. ConvertIP also supports compressed and uncompressed 4K over IP signal transmission, perfect for a variety of workflows—all from a single standalone device. For more information on the Matrox ConvertIP family of products, see our website for a full description of the benefits and features.

Supported applications and appliances

The Matrox ConvertIP devices are a series of stand-alone transmitter and receiver devices, but they are also designed to work with other Matrox Video applications, and third-party appliances such as Crestron's media controllers:

Matrox ConvertIP Manager: Matrox ConvertIP Manager is an executable utility application that allows you to manage multiple ConvertIP devices over your network. You can connect transmitters and receivers, update multiple ConvertIP devices simultaneously, and more. You can use Matrox ConvertIP without these added applications but using them will unlock a greater range of functionality for your transmitter/receiver workflow.
Crestron media controllers: You can integrate a Crestron media controller with the ConvertIP REST API to achieve the same functionality as provided by the Matrox ConvertIP Manager. This integration allows you to perform tasks such as switching streams, rebooting devices, locating devices, and more.

Connecting your Matrox ConvertIP

This section shows the basic button functions and connections for the Matrox ConvertIP SRH device. For more information on the other ConvertIP models, see the Matrox ConvertIP Installation and User Guide.

Image callout	LEDs / Buttons	Description
1	Main LEDs	TX: When green, indicates the ConvertIP is in Transmitter (TX) mode. Status: When flashing green, the device is encoding or decoding depending on what mode it is in. When solid green, the device is powered on, but idle. RX: When green, indicates the ConvertIP is in Receiver (RX) mode. When ConvertIP is powered up for the first time, it will be in RX mode.
2	Test	In TX mode, press and hold for 5 seconds and release to output a valid multicast stream at the settings specified in the ConvertIP user interface. An input does not need to be connected. In RX mode, press and hold for 5 seconds and release to ensure the HDMI or SDI cable is good and the connection between ConvertIP and the monitor or downstream device is valid. A valid network connection is not needed to use this. When finished, press the button for one second to return to standard operation.
3	Mode	Press and hold simultaneously with the Reset button for one second to switch the ConvertIP from transmitter to receiver and vice-versa. ConvertIP will reboot to switch modes.
4	Reset	Reboots the ConvertIP with a short press, or resets to factory default settings with a long press of about five seconds (until the Status light flashes green).

Image callout	Connections	Description
1	MEDIA / CONTROL LAN PoE+	Connect to your media network. You can also power the ConvertIP from this port (Power over Ethernet).
2	HDMI IN	In TX mode: Connect an HDMI video source to this connector when in transmitter mode. In RX mode: Connection is not used in receiver mode.
3	HDMI OUT	In TX mode: Not used. In RX mode: Connect an HDMI monitor to show the received ST 2110 or IPMX video signal.
4	Power	If you do not want your ConvertIP to be powered over the Ethernet connection, connect your 12V DC power supply to this port (sold separately).

Initial setup overview

The following list is an overview of the tasks you’ll need to perform to get started with Matrox ConvertIP. When needed, links to other topics are provided for more information. Although this list is shown as a series of steps, you do not necessarily need to do all these tasks in the order described. For example, you can connect your video source before powering up the ConvertIP.

To get started with Matrox ConvertIP:

Connect the Matrox ConvertIP to a power source: Matrox ConvertIP can be powered by an external power supply (sold separately) or by using PoE+ (Power Over Ethernet).
Connect your control network: Use the network control port (Control LAN) or first media control port (e.g. MEDIA / CONTROL LAN 1 or MEDIA / CONTROL SFP 1) to access your device’s web interface for configuration and for NMOS support and control.
Connect your media network: Depending on the ConvertIP model you have, use the MEDIA / CONTROL LAN 1 or MEDIA / CONTROL SFP 1 ports for your media content. The second LAN and SFP ports are used for redundancy. If your ConvertIP has only one network connector available, you can use MEDIA / CONTROL LAN 1 for both control and media transport operations.
Access the Web interface: When ConvertIP is connected to your network, it will boot in DHCP and broadcast in mDNS. This allows you to connect to the ConvertIP Command Center with your web browser (Google Chrome is recommended).
You can connect with your ConvertIP’s IP address or, if your computer and ConvertIP are on the same subnet, go to https://mtxcip-ConvertIP_serial, where “ConvertIP_serial” is the serial number found on your device label (e.g. https://mtxcip-ab12345/). More info: To find the IP address, you can use Matrox ConvertIP Manager, or initiate the ConvertIP’s test signal feature to display the address on a connected monitor.
Log in and create an initial user account: When you first log in to the ConvertIP Command Center, you will need to create the Administrator account (username and password).
Verify the status of your device: Go to the Status page of the ConvertIP Command Center to display the device status. Make sure everything is working as needed.
Configure settings: Configure your ConvertIP devices as transmitters or receivers according to your streaming workflow. You can switch between modes easily from the Maintenance page.
Start your streams: Once you have configured your ConvertIP receiver and transmitter devices, you are ready to begin streaming. You can establish a single connection from one ConvertIP to another from the ConvertIP Command Center, or you can use the Matrox ConductIP and ConvertIP Manager applications to connect sender and receiver flows.

Logging in to ConvertIP

To access the ConvertIP user interface from a web browser:

Open your web browser (Google Chrome is recommended).
Do one of the following:
- Go to the IP address of your ConvertIP (e.g. https://192.168.12.345).
- Go to https://mtxcip-ConvertIP_serial, where “ConvertIP_serial” is the serial number found on your device label (your computer and ConvertIP must be on the same subnet). If your network is set up to use mDNS, this will take you to the ConvertIP login page.
- Use the Matrox ConvertIP Manager application to access one or more ConvertIP devices and log in to them. For more information, see the Matrox ConvertIP Manager embedded HTML help.
Log in to the ConvertIP with your username and password.
Note: If this is the first time you are logging in to this ConvertIP you will instead be prompted to create a username and password to continue with initial setup.

You are successfully logged in to ConvertIP.

Controlling ConvertIP with Crestron Touch Panels

This section described the calls and the steps required to control the ConvertIP with Crestron controller devices, particularly the touch panel devices. We use a simple workflow to simulate a real-life control scenario, providing the ConvertIP REST API calls available and how to implement them.

Workflow diagram

The following diagram shows the setup we will use as a workflow example.

In this example:

The setup consists of four ConvertIP devices, two transmitters (TX) and two receivers (RX).
The transmitters connected to the network have two HDMI sources.
The receivers connected to the network have two monitors connected to them.
There is a Matrox ConductIP connected to the network. The ConductIP detects the devices on the network and is used to switch the streams (e.g. from TX1 to RX2 or from TX1 to RX1). For more information on the ConductIP, see https://video.matrox.com/en/products/infrastructure/convertip-series/conductip.
The ConvertIP REST API was used to program the Crestron touch panel to switch the streams and reboot the ConvertIP devices.

ConvertIP REST API calls

The ConvertIP REST API offers a broad array of functionalities for managing and interacting with devices. With the ConvertIP REST API, you can perform various tasks such as stream switching, rebooting, locating, and updating devices.

This section describes the different calls available to control the Matrox ConvertIP:

Log in to ConvertIP: Before sending any POST request, you must first log in to the ConvertIP.

To log in, send a request using https:IPADDRESS/user/login with the following JSON payload:


x
https:IPADDRESS/user/login

{ 
"username": "username", 
"password": "password", 
"closeExistingSessions”: true 
}

Note: To send a Post request using the ConvertIP REST API, you must be logged in to get the access token.

Reboot the ConvertIP: To reboot the ConvertIP unit, send a POST request to:


xxxxxxxxxx
https:IPADDRESS/api/command/reboot

Update the ConvertIP: To update the ConvertIP unit, send a POST request to:


xxxxxxxxxx
https:IPADDRESS/api/command/update

Get the ConvertIP's data: To get the ConvertIPs data, send a GET request to:


xxxxxxxxxx
 https:IPaddress/device/caps

An example of the response would be:


xxxxxxxxxx
{

  "hostname"          : "CE18683 DSS-TX",

  "isGolden"           : false,

  "isSafeMode"          : false,

  "isRX"             : false,

  "isMultiviewLicenseInstalled"  : false,

  .

  .

  .

}

Get the connection method: To get the connection method, send a GET request using the following command:


xxxxxxxxxx
https:IPADDRESS/device/settings/streams/master

Set the connection method: To set the connection method, send a POST request to: https:IPADDRESS/device/settings/streams/master with the following JSON payload:


xxxxxxxxxx
{

 "enable": true,

 "isRedundancyEnabled": false,

 "connectionMode": "sdp"

}

Switch between streams: To switch between streams on the ConvertIP devices on your network:

Send a GET request to get the data of the TX which you want to switch to. The response body contains the SDP URL of the TX stream.
Send a POST request to switch to the new stream using the SDP URL that was returned in step 1.

Example:

GET request:


xxxxxxxxxx
https://IDaddress/device/settings/streams/video/:index

Response body:


xxxxxxxxxx
{

  "enable" : true,

  "nmosId": "ce186830-0002-102b-bb00-000000000000",

  "sdpUrl": "http://192.168.153.121:5050/x-manufacturer/senders/ce186830-0002-102b-bb00-000000000000/stream.sdp",

  "selectResolution": "input",

  "resolution": 

   {

•     "width": 1920,

•     "height": 1080,

•     "refreshRateNum": "60",

•     "refreshRateDen": "1",

•     "scan": "progressive"

   },

   "selectPixelFormat": "input",

   "pixelFormat": "yuv_10_422",

   "colorSpace": "yuv_709",

   "isCompressionEnabled": false,

   "bitRateUHD": 820.00,

   "bitRateHD": 205.00

}

POST request:


xxxxxxxxxx
https://idaddress/device/settings/streams/video/:index

With the following JSON payload:


xxxxxxxxxx
{

  "enable”: true,

  "nmosId": "ce186830-0002-102b-bb00-000000000000",

  "sdpUrl": "http://192.168.153.121:5050/x-manufacturer/senders/ce186830-0002-102b-bb00-000000000000/stream.sdp",

  "selectResolution": "input",

  "resolution": 

   {

•     "width": 1920,

•     "height": 1080,

•     "refreshRateNum": "60",

•     "refreshRateDen": "1",

•     "scan": "progressive"

   },

   "selectPixelFormat": "input",

   "pixelFormat": "yuv_10_422",

   "colorSpace": "yuv_709",

   "isCompressionEnabled": false,

   "bitRateUHD": 820.00,

   "bitRateHD": 205.00

}

Using Postman to test your REST API

You can use the Postman platform (https://www.postman.com/product/tools/) to test the REST API. Postman is a widely used tool for testing REST APIs. It provides a user-friendly interface that enables you to send HTTP requests to an API and observe the responses.

The following is an example of the test performed by Matrox for logging in to and rebooting a ConvertIP unit.

Login test: Here is a request to log in using the IP address and the authorization of the of the unit.

Reboot test: Here is a request to log in using the IP address and the authorization of the of the unit.

To access a comprehensive list of available commands and their usage, refer to the link below. It provides additional information and details on the Convert IP REST API, enabling you to explore its full capabilities.

Furthermore, you can download the convert IP 2.0.postman_collection to test the API and gain a better understanding of its functionality.

Implementing the ConvertIP REST API with Crestron

In this section, we will provide a simplified explanation of how to implement the ConvertIP REST API with a Crestron touch panel. By integrating the ConvertIP REST API with a Crestron touch panel, you can achieve seamless control and management of Convert IP devices.

This diagram represents the sample workflow we are using:

The diagram shows a Crestron touch panel, which performs stream switching between the two transmitters (TX). If RX1 is presently connected to TX1, an operator can use the touch panel to switch the stream from TX1 to TX2 or vice versa.

Through the touch panel interface, users have the ability to initiate the stream switching operation by selecting the appropriate options. This interaction triggers the transmission of necessary commands via the ConvertIP REST API.

Matrox ConvertIP Crestron Module Demo

The Matrox ConvertIP Crestron Module is designed for use with two receivers and two transmitters.

With this module, you can easily switch the stream between TX1 and TX2 in both directions. Additionally, you have the ability to power off the receivers. The buttons below the screens allow for convenient unit rebooting. Based on customer requirements, the module can be enhanced with features such as unit location or updates.

Download the module file here: Text environment and Convert IP(SimpleSharp)

In the module file, you have the following files:

ConvertIP-SimpleSharp: This file includes the source code. It's important to note that Crestron utilities lack a built-in method for sending HTTPS requests, which are required for sending REST API commands to ConvertIP Units. To enable these requests, an S# library is necessary for the SIMPL+ and SIMPL Windows compiler to execute these operations.
MatroxCIP Test Environment: The CIP (ConvertIP) test environment file consists of the touch panel interface, the Simple Windows file, and the necessary dependency files.

Before uploading the Simple Windows file to the controller, ensure that you enter the correct IP addresses, username, and password for the units. Refer to the picture below for the input fields.

Contact us

The Matrox Video web site has product literature, press releases, technical material, a sales office list, trade show information, and other relevant material. Visit us at https://video.matrox.com.

If you have any questions or comments about our products or solutions, contact us at https://video.matrox.com/contact.

Matrox Video values your business and offers professional support for your Matrox Video product.

For more information, contact your Matrox Video representative or our technical support at support@matrox.com.

Disclaimer

Information in this document may contain technical inaccuracies or typographical errors. Information may be changed or updated without notice. Matrox Video reserves the right to make improvements and/or changes in the products, programs and/or specifications described in this information at any time without notice.

All trademarks and trade names, service marks and logos referenced herein belong to their respective owners.