ASCII / XML External Control

This guide covers the ASCII / XML protocol of external control introduced with the original Juggler pixel processor.

Download this guide as PDF

Principle

Every element of a Compere Project (the branching tree you see in the Project panel) has a unique identifier (UUID) and a common text name that you give to it. The same is true for every parameter that you can see, and may want to change, in the Properties panel for that element.

TCP and UDP ports are defined in Settings > Preferences.

•Use a remote terminal client e.g. PuTTY, or Tera Term, on a raw (or raw ASCII over TCP) connection, to address Compere on the server for a project group.

•The IP of a target Juggler can be found in Configuration > Network Configuration > [Discovery].

•For TCP, use Port 2300.

•For UDP, first enable ‘Use UDP Console Connection’ in Settings > Juggler. UDP receive port is 8001, UDP Remote Transmit port is 8002.

Expressions in this guide

Elements shown in [SquareBrackets] indicate that the string is replaced by a user string, e.g. \[JugglerName]\ might typically be the serial name, \Juggler5678\.

Similarly, C:\[Compere Root Path]\ is almost always C:\Users\[UserName]\AppData\Local\compere\.

Protocol

In the Project Panel you see the structure of the Project file that contains all the instructions for the entire setup of a Juggler system.

From this information you can see that there is a route to the value of everything. In the same way as we use paths to files in folders on devices on a network, you can send commands, to find or change any value. As an example we might want, in rough terms, to do this:

set the value to ‘10’ for the x-axis position of a projector in this project

which as a command would look something like this:

set path="/GroupSet/Group/Projector 1/position/x" value="10" (in plain text)

<command cmd="set" path="/GroupSet/Group/Projector 1/position/x" value="10"/> (in xml)

The message format (plain text or xml) is detected and the response is returned in the same format. All recognised commands respond immediately with: success=true/false.

For commands that do not have an instant response (e.g. open, or "Import MPCDI") the command must be followed by a system status request.

These commands or controls can be sent in either plain text or XML to the IP address of the server Juggler in a project group, or to a Windows control PC as client or server.

Compere supports commands sent via TCP. Use the Compere Preferences Panel to configure IP addresses and transmit/receive ports, including the connection timeout.

Commands and their parameters are case insensitive. Each parameter’s actual value is case sensitive. Individual commands are activated in text strings by line ending characters \n, or in xml, by opening and closing tags <command> </command> or, for empty tags, <command />.

Grouping Commands

It can be more efficient to encapsulate many SET commands in a single group using the <commands></commands> tag.

For example to position two projectors in a single control message:

</commands>

The reply would be:

Note: ‘atomic’ in this reply indicates that the commands group was not to be distributed to the other members of the Compere Project Group until all commands had been received by the instance of Compere addressed.

In this example, projector movement will therefore be smoother. The attribute atomic="true" is implicit, but atomic="false" can be used if you want commands to be distributed one at a time as received, i.e. while other commands are still being received.

Explicit example:

...

</commands>

The plain text equivalent would be like this:

group commands="GroupSet/Group/proj1/position/x=0.2;[...];GroupSet/Group/proj2/heading/roll=0.2"

Scope of external control

With complex multi-Juggler systems, External Control is the route to both systems management, and dynamic interaction with all the elements. Whether used directly or through show controllers, it removes the need to use Compere for complex daily interaction with devices, models, projectors, sources, processes and interconnections.

Static and Dynamic commands

There are two types of external control commands, static and dynamic.

Static, or core, commands interact with a Compere Project, load and save Project files, and request specific notifications (registers). For example to set a value of an object property.

➢The full list of core commands is available within Compere, Help > External Control Protocol.

➢For the latest version, on this Portal, see ExternalControlHelp.html

Dynamic (action) commands are less generic and go beyond changing properties in the Project in order to do something. These are detailed with examples in the following pages of this guide.

Available actions

Type "actions" to list all actions available for the target instance of Compere in its current state. This will return a series of actions of name type= under headings of command:

To use an action:

actions type="[name]" enacts a specific action of this name

Example

Import an MPCDI file from a given location:

actions type="import MPCDI" file="C:\[MyPath]\MPCDI\example.mpcdi"

Real use case example:

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

Options

Any of the commands below could be used to set the x position of a Canvas Window value to 800:

Using names

Using class names (i.e. non-specific)

The element path="juggler", for example, addresses all objects of type ‘juggler’.

Using a mixture of wildcards (*), names (specific) and class names (non-specific)

Page edited [d/m/y]: 06/01/2023