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 on 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_A-B_Preview_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 have to be written like this:
<action type="ComposerCtrBoardPressButtonAction" Module="Root\VirtualCam_A-B_Preview_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_A-B_Preview_3-Cam\CAMERAS\STREAMING" Button="On" State="True" />
(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 with 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"/>
ComposerOpenAndRunDocument
- Path
<action type="ComposerOpenAndRunDocument" 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>
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
and then 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
