External Control of Aximmetry via HTTP

2021-DEC-03 Author: Aximmetry

Introduction

This document describes how to control Aximmetry externally using the HTTP protocol.

Network setup

You can control Aximmetry via HTTP commands sent with the POST method.

In order to turn on this function go to Edit / Preferences and check Enable HTTP Control.

You can also specify which Port Aximmetry listens for HTTP messages. In most cases, you can leave it on default.

The commands must be sent to the URL:

http://ip_of_the_Aximmetry_machine:Port

for example:

http://127.0.0.1:21463

The actual command must be placed in the content section of the HTTP message.

Command Format

The commands themselves are presented in XML format.

The most important command is ComposerSetPinValueAction with which you set the value of any pins of any modules within your compound. It looks like this:

<action type="ComposerSetPinValueAction" Module="module_path" Pin="pin_name" Value="pin_value" />

For example, suppose you want to switch between several texts displayed on the screen in a compound like this:

To select the text number 7 you have to send the following:

<action type="ComposerSetPinValueAction" Module="Root\Switch Text" Pin="Selected" Value="7" />

In practice it is easier to expose all the pins you want to control on the Root level, so that you don't have to deal with module paths, for example:

In this case, you can use the following command instead:

<action type="ComposerSetPinValueAction" Module="Root" Pin="TextNo" Value="7" />

Of course, you can choose to set the text itself directly:

<action type="ComposerSetPinValueAction" Module="Root" Pin="Display Text" Value="The text I want to display" />

You can also address control board buttons directly.

For that, you can use the ComposerCtrBoardPressButtonAction command:

<action type="ComposerCtrBoardPressButtonAction" Module="panel_path" Button="button_name" />

It simulates pressing a button on the panel.
For example, suppose you want to switch cameras within the standard VirtualCam control board.

panel_path is very similar to module_path, but besides compound names, it can also refer to control board names.
In this case, we have the VirtualCam_3-Cam compound, within that, we need the CAMERAS control board, and within that the SELECT CAMERA panel.
For example, we want to "press" the CAM 2 button. All of that has to be written like this:

<action type="ComposerCtrBoardPressButtonAction" Module="Root\VirtualCam_3-Cam\CAMERAS\SELECT CAMERA" Button="CAM 2" />

If you have a logical ON/OFF button, pressing it will always toggle between ON and OFF. But you might want to explicitly specify which state it should be in. For this purpose, there is another command named ComposerCtrBoardSetButtonAction.

<action type="ComposerCtrBoardPressButtonAction" Module="panel_path" Button="button_name" State="True/False" />

For example, let's turn the streaming on the same control board:

<action type="ComposerCtrBoardSetButtonAction" Module="Root\VirtualCam_3-Cam\CAMERAS\STREAMING" Button="On" State="True" />

NOTE: In this case, the button contains an icon, but that is achieved by using the special name On, and this is the name you have to specify for the command.

Return Values

The returned string is also an XML with the following format:

<response Code="code" Message="message" />

Code="0" means everything went well and the command has been executed. Otherwise, it is an error code accompanied by an error message.

In the case of query actions, the response also contains a ReturnValue section, see below.

<response Code="0" Message="OK">
<ReturnValue ...... >
</response>

Available Commands

ComposerCloseAllDocumentsAction

Closes all open documents in Composer without asking about unsaved ones.

<action type="ComposerCloseAllDocumentsAction"/>

ComposerOpenAndRunDocumentAction

CloseAll
Path

<action type="ComposerOpenAndRunDocument" CloseAll="True/False" Path="path_of_xcomp_file"/>

ComposerRestartApplicationAction

ReopenCurrentlyRunningDocument (true/false)
OpenDocument

<action type="ComposerRestartApplicationAction" ReopenCurrentlyRunningDocument="True" />

<action type="ComposerRestartApplicationAction" OpenDocument="path_of_xcomp_file" />

ComposerSetPinValueAction

Module
Pin
Value

<action type="ComposerSetPinValueAction" Module="module_path" Pin="pin_name" Value="pin_value" />

ComposerGetPinValueAction

Module
Pin

<action type="ComposerGetPinValueAction" Module="module_path" Pin="pin_name" />

Response format:

<response Code="0" Message="OK">
<ReturnValue type="value_Type" value="pin_value" />
</response>

ComposerCtrBoardPressButtonAction

Module
Button

<action type="ComposerCtrBoardPressButtonAction" Module="panel_path" Button="button_name" />

ComposerCtrBoardSetButtonAction

Module
Button
State (true/false)

<action type="ComposerCtrBoardPressButtonAction" Module="panel_path" Button="button_name" State="True/False" />

ComposerFindModulesAction

Module
NamePattern
Recursive (true/false)

Returns the list of all modules under the specified root compound whose name matches the pattern.

<action type="ComposerFindModulesAction" Module="root_module_path" NamePattern="wildcard_pattern" Recursive="True/False" />

Response format:

<response Code="0" Message="OK">
<ReturnValue>
<item value="module_1_path" />
<item value="module_2_path" />
...................
</ReturnValue>
</response>

ComposerEnumPinsAction

Module

Returns the list of the available input pins of the specified module along with their types.

<action type="ComposerEnumPinsAction" Module="module_path" />

Response format:

<response Code="0" Message="OK">
<ReturnValue>
<item name="pin_1_name" type="pin_1_type" />
<item name="pin_2_name" type="pin_2_type" /> ..............
</ReturnValue>
</response>

ComposerEnumCtrBoardsAction

Module
Recursive (true/false)

Returns the list of all control boards under the specified root compound.

<action type="ComposerEnumCtrBoardsAction" Module="root_module_path" Recursive="True/False" />

Response format:

<response Code="0" Message="OK">
<ReturnValue>
<item name="control_board_1_name" path="control_board_1_path" />
<item name="control_board_2_name" path="control_board_2_path" /> ...................
</ReturnValue>
</response>

ComposerEnumCtrBoardPanelsAction

Module

Returns the list of all panels under the specified control board.

<action type="ComposerEnumCtrBoardPanelsAction" Module="control_board_path" />

Response format:

<response Code="0" Message="OK">
<ReturnValue>
<item name="panel_1_name" path="panel_1_path" />
<item name="panel_2_name" path="panel_2_path" /> ...................
</ReturnValue>
</response>

ComposerEnumCtrBoardButtonsAction

Module

Returns the list of the buttons of the specified control board panel along with their types.

<action type="ComposerEnumCtrBoardButtonsAction" Module="panel_path" />

Response format:

<response Code="0" Message="OK">
<ReturnValue>
<item name="button_1_name" type="button_1_type" group="button_1_group" index="button_1_index" gap="button_1_gap" />
<item name="button_2_name" type="button_2_type" group="button_2_group" index="button_2_index" gap="button_2_gap" /> ..............
</ReturnValue>
</response>

If the type is "Trigger", the button belongs to a trigger pin, and each click on it emits a trigger signal.
If the type is "Switch", the button belongs to a logical pin, and it can be turned on and off by clicking.
If the type is "Enum", the button is part of a group of multiple buttons that belong to an integer pin. The groups are identified by the group attribute. Buttons with the same group number belong to the same integer pin. Within a group, only one button can be selected at a time by clicking. The index attribute represents the integer value that is assigned to the pin when the button is selected.
If the type is "Flags", the behavior is similar to "Enum", but the buttons represent the on/off state of individual bits within the integer value. Each button can be turned on and off individually by clicking. The index attribute represents the index of the bit, starting at zero.

gap means the number of gap spaces inserted before the button on the UI.

ComposerEnumCtrBoardPropertiesAction

Module

Returns the list of the available properties of the specified control board panel along with their types.

<action type="ComposerEnumCtrBoardPropertiesAction" Module="panel_path" />

Response format:

<response Code="0" Message="OK">
<ReturnValue>
<item name="property_1_name" type="property_1_type" />
<item name="property_2_name" type="property_2_type" /> ..............
</ReturnValue>
</response>

Grouping Commands

If you want to change multiple properties/buttons at once and you prefer sending all commands in a single HTTP request you can use the ComposerGroupAction command.

<action type="ComposerGroupAction">
<action type=........ />
<action type=........ />
<action type=........ />
.....
</action>

Each action in the list can be any of the commands described above. Note that each action can be a ComposerGroupAction as well, thus implementing a hierarchical grouping.

Sending Commands

There are multiple ways to send HTTP POST commands, so the options for what you can do are unlimited here.

As an example for this guide, we will use reqbin to send the commands.

First, we start by specifying the address:

It's the same one we used earlier in the guide.

Then we go to the Headers Tab and put:

Content-Type: application/xml

After that, we go to the Content tab, and there we can write our XML commands:

Finally, we press Send and our commands will be applied to Aximmetry

Notes for Using from Javascript

A typical scenario is calling the HTTP interface from Javascript within a website that implements a custom interface for Aximmetry.

NOTE 1: Some sending APIs, including Javascript XMLHttpRequest, send an OPTIONS request prior to sending the actual POST message if "Content-Type" is not "text/plain". Aximmetry does not handle the OPTIONS request. In this case either do not set the "Content-Type" or set it to "text/plain".

NOTE 2: When you are specifying a file or module path as a string in Javascript, remember that the backslash (\) character denotes an escape sequence. Therefore to add an actual backlash you have to write a double backlash, e.g.

"Root\\VirtualCam_3-Cam\\CAMERAS\\SELECT CAMERA"

NOTE 3: When building the XML command as a string in Javascript, you can use single quotation marks either for the string itself or for the attributes within the XML, e.g.

cmd = '<action type="ComposerCtrBoardSetButtonAction" Module="Root\\VirtualCam_3-Cam\\CAMERAS\\STREAMING" Button="On" State="' + state + '" />';

cmd = "<action type='ComposerCtrBoardSetButtonAction'Module='Root\\VirtualCam_3-Cam\\CAMERAS\\STREAMING'Button='On'State='" + state + "'/>";

Of course, you can use a template literal as well:

cmd = `<action type="ComposerCtrBoardSetButtonAction" Module="Root\\VirtualCam_3-Cam\\CAMERAS\\STREAMING" Button="On" State="${state}" />`;

Search

External Control of Aximmetry via HTTP

Introduction

Network setup

Command Format

Return Values