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
Example: http://127.0.0.1:21463
The actual command must be placed in the content section of the HTTP message.
Command Format
Commands are written in XML format.
Using Module Path
The most important command is ComposerSetPinValueAction, which allows you to set the value of any pins of any modules within your compound. The syntax is as follows:
<action type="ComposerSetPinValueAction" Module="module_path" Pin="pin_name" Value="pin_value" />Attribute breakdown:
- type: The command, which is ComposerSetPinValueAction in this case. For the list of all available commands, refer to the Available Commands section.
- Module: Specifies the path to the module. The path format is structured as Root\Subcompound's name (if any)\Module's name.
- Pin: The specific input pin of the module.
- Value: The new value you wish to set to the pin.
Suppose you want to switch between several texts displayed on a screen.
In the following setup you can do so by changing the Selected pin of the Switch Text module:
To set it to number 7 you have to send the following:
<action type="ComposerSetPinValueAction" Module="Root\Switch Text" Pin="Selected" Value="7" />Using the Copy Full Path Option
To easily obtain a pin's path, right-click on any pin and select Copy Fully Path:
NOTE: This option is available in both the Pin Values panel of the Flow Editor and the Control Board. Additionally, you can access it by right-clicking directly on a pin in the Flow Editor.
In the above scenario, the path returned would be: "Root\Switch Text:Selected"
Where "Root\Switch Text" is the Module path and "Selected" is the pin.
Exposing to Root
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:
NOTE: Pins exposed to the Root will also appear on the Dashboard panel, providing easy access within Aximmetry Composer.
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" />Using Panel Path
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, which 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" />
or
<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 + '" />';
or
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}" />`;
