06. PRIME VSAR: CAMIO INTEGRATION

Integration Overview

The integration of PRIME VSAR into the CAMIO universe relies on the native Data Engine’s Request/Reply messaging system and implements the Bluenet Device API.

4 types of services are involved when CAMIO/iSQ commands are sent to PRIME VSAR:

Data Engine
Endpoint
Endpoint Handler
Request Dispatcher (optional in case of a single playout device)

Example of installation with a pool of 3 playout devices and 1 Render

Camio Components

Data Engine

The Data Engine is the communication layer of all CAMIO commands with PRIME VSAR.

⚠️ You should install at least one Data Engine for the playout device (or pool of playouts devices) and one for the preview device (cf. Data Flow diagram). The Data Engine on the CAMIO server should be already installed.

⚠️ The Data Engine is bundled with Chyron Panels(LAP), so it should be already installed.

Once installed, a Windows service is started automatically and running in the background.

Download link: https://da.chyronhego.com/da/download-area.php?proID=36

Endpoint

The Endpoint is responsible for managing requests and template asset files from CAMIO. Therefore this service must have access to a shared folder in order to save the files, see the ”Cache directory (Assets folder)” section for more details.

The Endpoint could be installed on a dedicated machine or on a playout/preview machine.

⚠️ There should be a single Endpoint running for all the playouts and a single one for the preview (cf. Data Flow diagram).

Once installed, a Windows service is started automatically and running in the background.

Download link: https://da.chyronhego.com/da/download-area.php?proID=55

Endpoint Handler

This service handles requests from the Endpoint and manages the states of on-air/cued items. The requests are then forwarded to the final device or to the Request Dispatcher in case of multiple devices (i.e. a pool).

The Endpoint Handler executable is included in the PRIME VSAR Tools installer.

⚠️ If PRIME VSAR Tools has been previously installed, the services may need to be stopped manually (Win+R -> services.msc) in before proceeding to the upgrade.

Once PRIME VSAR Tools is installed, you can choose to register the service when asked

⚠️ The service reads by default its configuration on the local Data Engine, make sure the bucket and key exist before starting the service (see the Configuration section) or it will fail to start.

Request Dispatcher

This service dispatches a request to a pool of devices, for example in case of multiple playouts devices. In the case of a single device, this service is not required.

The Request Dispatcher executable is included in the PRIME VSAR Tools installer.

⚠️ If PRIME VSAR Tools has been previously installed, the services may need to be stopped before proceeding to the upgrade.

Once PRIME VSAR Tools is installed, you can choose to register the service when asked.

‎

Camio Configuration

Data Engine

⚠️ Make sure the port 4300 is open on all machine were it is installed. You should be able to access http://hostname:4300 (example http://DESKTOP-MF15G8M:4300 ) from the other machines.

For more information, please refer to the CAMIO Data Engine documentation.

Endpoint

Config key or config.json

The Endpoint could be configured either by a config.json file located by default in

C:\Program Files\ChyronHego\ChyronHego CAMIO Endpoint Beta, or by a config key in the bucket bn.endpoint

⚠️ The config.json file takes precedence over the config key, so delete or rename config.json if you want to use the config key method.

⚠️ The config.json file is recreated when reinstalling the service

Example

"isqHostName":"ip"

"camioExternal":"camio4"

"isqHostName": If set, Endpoint will use this to find items in running order belonging to this host name instead of its own.

⚠️ The hostname must match the hostname visible in the rundown's JSON.

"camioExternal": It must be set to “camio4” (lower case) for backward compatibility with CAMIO 4.11.2
‎⚠️ If not set, the Endpoint will fail to upload previews on CAMIO.

For more information, please refer to the CAMIO Endpoint documentation

Or in its folder installation:
‎e.g. C:\Program Files\ChyronHego\ChyronHego CAMIO Endpoint Beta\doc\config.md

Cache directory (Assets folder)

In order to share the assets between multiple playout devices, the Endpoint cache directory must be shared.

These steps can be done manually or can be handled by the tool platinum-reconfigure.

Create a folder and set it up as a Windows shared folder
Create a symbolic link on each playout device pointing to the shared folder
‎This step provides a solution to map UNC paths to “Drive Letter” paths, e.g. with cmd:
‎mklink /d c:\sharedfolder \\COMPUTER\sharedfolder
Set the Endpoint config key or config.json accordingly e.g.:
‎"tempPath": "c:/sharedfolder"

Endpoint Handler

The Endpoint Handler could be configured either by arguments on the command line or by a config key in the bucket hybrid.endpointhandler

Command line arguments

-d, --dst <ARG1>

Destination device where requests should go (e.g. MyPoolId|localhost|192.168.1.42). Mandatory

-t, --type <ARG1>

Destination device's type (playout|render). Mandatory

-f, --shared_folder <ARG1>

Shared folder of the CAMIO device. Fallback if I disk can not be found

-h, --host <ARG1>

IPv4 address|host of this service's DataEngine. DEF: localhost

-s, --src_host <ARG1>

IPv4 address|host of the Endpoint's DataEngine. DEF: localhost

-c, --channel <ARG1>

Device's number of channels. DEF: 1

-o, --timeout <ARG1>

Requests timeout in ms. DEF: 5000

-l, --log <ARG1>

-v, --version

Print version number

--svc_args <ARG1>

IPv4 address|host of the DataEngine with the service args (svc mode)

Config key

In order to use the config key, the argument --svc_args must be specified.

⚠️ The config key takes precedence over the command line arguments when the argument --svc_args is specified and cannot be mixed.

The key is a JSON object with attributes similar to the command line arguments.

{

"dst": "localhost",

"type": "playout",

}

📝Logs are written to c:/log/ChyronHego/endpoint-handler

Request Dispatcher

Pool of playout devices

In AR/VR, a virtual set or AR graphics could be viewed from different camera angles.

Thus the concept of a pool of playout devices has been introduced to define multiple devices working together while still being seen as a single device from the CAMIO side.

Request Dispatcher needs to run only on “master” VSAR.

Make sure the bucket hybrid.pools exists otherwise create it.

Example

Key pool.Pool1 in the bucket hybrid.pools :

{

"name": "Pool1",

"master": "Pt2",

"slaves": [

"Pt1",

"Pt3"

"share": {

"folder": "camio-endpoint",

"type": "smb"

}

Pt1, Pt2, Pt3 = are Hostnames but it can be also ip address

The Request Dispatcher could be configured either by arguments on the command line or by a config key in the bucket hybrid.requestdispatcher

Command line arguments

-p, --pool <ARG1>

Pool Id where requests will be dispatched (e.g. 'MyPoolId'). Mandatory

-c, --cfg_host <ARG1>

IPv4 address|host of the DataEngine with the Pool config. DEF: localhost

-s, --src_host <ARG1>

IPv4 address|host of the Endpoint Handler's DataEngine. DEF: localhost

-h, --host <ARG1>

IPv4 address|host of this service's DataEngine. DEF: localhost

-r, --resolve <ARG1>

Request resolution policy. DEF: all (all|any|race)
‎all: A request is resolved if all devices reply successfully

any: A request is resolved if at least one device reply successfully

race: The request resolution is determined by the first (fastest) device to reply successfully or not.

-x, --exclusive

Exclude the master from the pool DEF: not exclusive

-o, --timeout <ARG1>

Requests timeout in ms. DEF: 2000

-l, --log <ARG1>

-v, --version

Print version number

--svc_args <ARG1>

IPv4 address|host of the DataEngine with the service args (svc mode)

Config key

In order to use the config key, the argument --svc_args must be specified.

⚠️ The config key takes precedence over the command line arguments when the argument --svc_args is specified and cannot be mixed.

The key is a JSON object with attributes similar to the command line arguments.

{

"pool": "Pool1"

}

📝Logs are written to c:/log/ChyronHego/request-dispatcher
‎

Platinum Reconfigure

platinum-reconfigure.js listens to the data engine to change the system configuration accordingly.
‎

Prerequisites

VSAR Tools (2.0.0+) installed on each playout. It includes the service platinum-reconfigure
ISQ service installed on each playout. Only one service is needed at a time running on the master device but we prepare the other devices in advance in case of a pool reconfiguration
‎The Playout Endpoint Host is set to localhost (i.e. iSQ Service and Endpoint will be running on the master device)
‎

Reconfigure

USAGE: node `platinum-reconfigure.js` [OPTION1] [OPTION2]...

The following options are supported:

--de <ARG1\> IP address of the dataengine on which the script will listen.

ex: node platinum-reconfigure.js --de=localhost

Pool

This tool can receive events to reconfigure the machine in a master/slave environment pool. A pool is a group of machines with 1 master and several slaves. In this use case, all machines of the pool are expected to run the service platinum-reconfigure, working with the same data engine.

This tool works with hostnames. So hostnames and IP correspondences are expected to be filled in the system.

On Windows:

C:\Windows\System32\drivers\etc\hosts

On the dataengine hybrid.pools bucket, each pool is described in a Key: pool.poolname This key needs to be created manually the first time regarding the needs.
‎Create in bucket hybrid.pools, the key pool.myPoolName (replace myPoolName by the pool’s name, e.g. pool.Pool1) with the following content (example with FRESH3 as master and FRESH4 as slave):

Ex: pool.Pool1 Master on Windows (smb)

{

"name": "Pool1",

"master": "Pt2",

"slaves": [

"Pt1",

"Pt3"

"share": {

"type": "smb",

"name": "camio-endpoint",

"drive": "S"

}

In hybrid.pools bucket, each machine listen a Key that tell to which pool it belongs: device.hostname

Pt1, Pt2, Pt3 = are Hostnames but it can be also ip address

Ex: device.Pt2

{

"pool": "pool.Pool1"

}

To re-arrange a pool, modify the pool description. Then overwrite the key of the new master. It will receive an event and configure itself as master. Then, when ready, it will write the keys of its slaves so they will reconfigure themselves as slaves.

For reconfiguration, external scripts are called:

releaseMe.[sh-bat]
masterMe.[sh-bat]
slaveMe.[sh-bat]
patchconfig.js

During the reconfiguration:

The script will read on the local data engine to get the share folder path in bn.endpoint bucket, config key, tempPath field. That's where the shared folder is. All machines are expected to have this field on the same value. Default is C:\Users\ChyronHego\AppData\Local\Temp

For the master VSAR device, it will modify hybrid.endpointhandler and hybrid.requestdispatcher buckets, config keys. endpointhandler and requestdispatcher services have to be installed and those keys have to exist.

For all VSAR devices, it will modify HOME\AppData\Local\Chyronhego\Fresh\Mithril.ini to update [/Script/Mithril.MtDataEngineHandler] section, Ip field to the master VSAR hostname.

‎

PRIME VSAR - CAMIO Integration Troubleshooting

Notes

iSQ web interface (experimental) is located at http://localhost:8087/isq

Bluenet (Endpoint) log web interface (experimental) is located at http://localhost:8087/log

Data Engine web interface is located at http://localhost:4300

📝Data Engine logs are written to c:/log/ChyronHego/dataengine

📝Endpoint logs are written to c:/log/ChyronHego/camio-endpoint

📝Endpoint handler logs are written to c:/log/ChyronHego/endpoint-handler

📝Request dispatcher logs are written to c:/log/ChyronHego/request-dispatcher

Check list

All the machines can ping each other
Endpoint config file is either config.json or a config key in the bucket bn.endpoint
Port 4300 is open on every machine hosting a Data Engine
All services are running: Data Engine, Endpoint, Endpoint Handler, Request Dispatcher (optional, only needed for pool of playouts)
All MOS/CAMIO server related services are running (e.g. External Render Service)
All PRIME VSAR are connected to their respective Data Engine

Symptoms

A service is failing to read its config key on the Data Engine

(Failed to read args on the Data Engine, exiting...)

Verify the Data Engine is running
Verify the bucket and config key are existing and named accordingly without heading or trailing spaces
Verify the config key’s content is a valid JSON object

The rundown is selectable in iSQ web interface but is empty,
‎iSQ Viewer displays the rundown but commands have no effect
‎("item not found" or "0/0 assets" in the Endpoint logs)

Verify Endpoint config file is either config.json or a config key in the bucket bn.endpoint
Verify the Endpoint configuration key "isqHostName": If set, Endpoint will use this to find items in running order belonging to this host name instead of its own.
Restart the Endpoint service, and republish the rundown (e.g. in ENPS toggle ‘MOS Control Active’)

It should display in the log "Looking for items routed to XXX", XXX being the isqHostname

"X/X assets" with X not equal to 0

⚠️ The hostname must match the hostname visible in the rundown's JSON.

The Request dispatcher is not able to see a slave machine
‎(“Device 'xxx' is unreachable” in the logs)

Check the Request dispatcher is pinging the slave machine
Check the port 4300 is open on the slave machine (on the slave machine you should be able to access in a web browser the page located at http://localhost:4300)

You might need to disable/reconfigure the firewall on Windows

The context is not visible in LUCI 4 / 5

Check the Context Permission in the CAMIO Admin tool (cf. CAMIO documentation)

The playout/preview fails

Check there is no ID clash between the PRIME VSAR instances. For example 2 previews having the same ID and running at the same time will cause issues.
Check PRIME VSAR is running in PLAY mode