<< Click to Display Table of Contents >> Navigation:  ASCII / XML External Control > Message Formats

Message formats: core and extended

Messages may be sent in either plain text or XML format – see below for the plain text summary – and Compere will respond in the same format as the incoming message. All XML attributes must be quoted.

Messages are defined by a ‘command’ tag with various attributes depending on the message. Typical attributes include: cmd, path, type, value, makeactive and fullpath.

The core message set – as described in the HTML API – must have at a minimum a ‘cmd’ attribute.

<command cmd="status" />

The extended message set is accessible via the ‘action’ command. The availability of these commands depends on the current system configuration: e.g., adding a Juggler to the system will make additional commands available to the external control user.

Example (Windows o/s):

<command cmd="actions" type="Import MPCDI" file="C:\Users\[UserName]\Downloads\mpcdi-file-name.mpcdi"/>

and in plain text:

actions type="Import MPCDI" file="C:\Users\[UserName]\Downloads\mpcdi-file-name.mpcdi"

Response format

All valid messages are acknowledged immediately with ‘success=true/false’. The XML response is a well-formed XML document which may be parsed by any established third-party library.

Note: the Compere version example below includes a date string and a build hash which can be used for build tracking/reporting.

Request

<command cmd="get" path="compereversion" />

Response

<replies success="true" path="compereversion" numberofreplies="1" commandDuration="123us">
<compereversion value="1.0.0.1 (20200924 50473f3)" fullpath="GroupSet/Group/JugglerName/atom/compereversion"/>
</replies>

Replies include the number of replies (relative paths especially are likely to elicit multiple responses) and how long the reply took (commandDuration), in microseconds.

System configuration

The complete system configuration can be read using the ‘get’ command with an additional ‘path’ (keyword) attribute.

Get current project and default project

<command cmd="status" />

Get info for all Jugglers in a project

<command cmd="get" path="juggler" />

Get info for a specific Juggler

<command cmd="get" path="[JugglerName]" />

Get all versions from all Jugglers in a system

<command cmd="get" path="fwversion" />
<command cmd="get" path="swversion" />
<command cmd="get" path="compereversion" />

Get versions for a specific Juggler

<command cmd="get" path="[JugglerName]/atom/fwversion" />
<command cmd="get" path="[JugglerName]/atom/swversion" />
<command cmd="get" path="[JugglerName]/atom/compereversion" />

Unsolicited notifications: registers

Typically, commands elicit an immediate response, but an external control user can add callbacks via registers to be notified asynchronously when a parameter changes: e.g., when the status of an interface is updated.

Get all CPU temperatures in the system

<command cmd="get" path="temperatureCPU" />

Receive a notification when any CPU temperature changes

<command cmd="register" path="temperatureCPU" />

Plain text messages

For convenience, when typing at a console, all XML messages have a shorter, plain text equivalent. This can be constructed by removing the outer command tag and dropping the quotes on the ‘cmd’ attribute.

Example: get all IP addresses in the system

XML

<command cmd="get" path="externalipaddress" />

Plain text

get path="externalipaddress"

Example: MPCDI import

XML

<command cmd="actions" type="Import MPCDI" file="C:\\path\\to\\system.mpcdi" />

Plain text

actions type="Import MPCDI" file="C:\\path\\to\\system.mpcdi"

Further examples

Get all temperatures for all Jugglers in a system

<command cmd="get" path="temperaturePL" />
<command cmd="get" path="temperatureCPU" />

Get CPU temperature for a specific Juggler

<command cmd="get" path="/GroupSet/Group/[JugglerName]/SystemMonitor/temperatureCPU" />

Disable red beams system-wide

<command cmd="actions" type="Red Beam Off" />

Enable blue beams for a specific Juggler

<command cmd="actions" type="Blue Beam On" path="/GroupSet/Group/Juggler4540" />

Get active pixels and lines for a specific Juggler’s video input

<command cmd="get" path="/GroupSet/Group/[JugglerName]/DpRx:2/VideoTiming/activepixels" />
<command cmd="get" path="/GroupSet/Group/[JugglerName]/DpRx:2/VideoTiming/activelines" />

Heartbeats

A heartbeat could be implemented by periodically requesting ‘status’ from each Juggler.