導入
このドキュメントでは、HTTP プロトコルを使用して Aximmetry を外部から制御する方法について説明します。
ネットワーク設定
Aximmetry は、POST メソッドで送信される HTTP コマンドを使用して制御できます。
この機能を有効にするには、編集 / 設定 へ移動し、HTTP 制御を有効にする をチェックします。
AximmetryがHTTPメッセージを受信するポートを指定することもできます。ほとんどのケースでは、デフォルト設定のままにしておいてください。
コマンドは、以下のURLに送信する必要があります：http://ip_of_the_Aximmetry_machine:Port
例：http://127.0.0.1:21463
実際のコマンドは、HTTPメッセージのコンテンツセクションに配置する必要があります。
コマンド形式
コマンドはXML形式で記述されます。
モジュールパスを使用する
最も重要なコマンドはComposerSetPinValueActionで、複合体内の任意のモジュールの任意のピンの値を設定できます。構文は次のとおりです：
<action type="ComposerSetPinValueAction"
Module="module_path" Pin="pin_name"
Value="pin_value" />属性解説：
- type: コマンドの名前です。この例では ComposerSetPinValueAction です。すべての利用可能なコマンドのリストは、利用可能なコマンド セクションを参照してください。
- Module: モジュールのパスを指定します。パス形式は Root\Subcompound『s name (if any)\Module』s name の構造です。
- Pin: モジュールの特定の入力ピンを指定します。
- Value: ピンに設定する新しい値を指定します。
画面に表示される複数のテキストを切り替えたい場合。
以下の設定では、Switch TextモジュールのSelectedピンを変更することで実現できます:
番号7に設定するには、以下のコマンドを送信します:
<action type="ComposerSetPinValueAction"
Module="Root\Switch Text" Pin="Selected" Value="7" />コピーフルパスオプションの使用
ピンのパスを簡単に取得するには、任意のピンを右クリックし、コピーフルパスを選択します：
NOTE: このオプションは、フローエディターのピン値パネルとコントロールボードの両方で利用可能です。また、フローエディターでピンを直接右クリックしてもアクセスできます。
上記のシナリオでは、返されるパスは次のようにになります： 「Root\Switch Text:Selected」
ここで「Root\Switch Text」はモジュールパス、「Selected」はピンです。
ルートへの露出
実践では、制御したいすべてのピンをRootレベルに露出させる方が簡単です。これにより、モジュールパスを扱う必要がなくなります。例：
注：ルートに露出されたピンはダッシュボードパネルにも表示され、Aximmetry Composer内でのアクセスが容易になります。
この場合、以下のコマンドを使用できます:
<action type="ComposerSetPinValueAction"
Module="Root" Pin="TextNo" Value="7" />もちろん、テキスト自体を直接設定することもできます:
<action type="ComposerSetPinValueAction"
Module="Root" Pin="Display Text" Value="表示したいテキスト" />パネルパスを使用する
コントロールボードのボタンを直接指定することもできます。
その場合、ComposerCtrBoardPressButtonAction コマンドを使用します:
<action type="ComposerCtrBoardPressButtonAction"
Module="panel_path" Button="button_name" />これはパネル上のボタンを押す動作をシミュレートします。
例えば、標準のVirtualCamコントロールボード内でカメラを切り替えたい場合。
panel_pathはmodule_pathと非常に似ていますが、複合名だけでなくコントロールボード名も参照できます。
この場合、VirtualCam_3-Camという複合名があり、その中にCAMERASコントロールボード、さらにその中にSELECT CAMERAパネルがあります。
例えば、CAM 2 ボタンを押したい場合、次のように記述します：
<action type="ComposerCtrBoardPressButtonAction"
Module="Root\VirtualCam_3-Cam\CAMERAS\SELECT CAMERA" Button="CAM 2" />論理的な ON/OFF ボタンがある場合、押すと常に ON と OFF の間で切り替わります。しかし、明示的にどの状態にするかを指定したい場合もあります。そのために、ComposerCtrBoardSetButtonActionという別のコマンドが用意されています。
<action type="ComposerCtrBoardPressButtonAction"
Module="panel_path" Button="button_name"
State="True/False" />例えば、同じコントロールボードでストリーミングをオンにする場合：
<action type="ComposerCtrBoardSetButtonAction"
Module="Root\VirtualCam_3-Cam\CAMERAS\STREAMING"
Button="On" State="True" />NOTE: この場合、ボタンにはアイコンが表示されていますが、これは特殊な名前 On を使用しているためです。この名前をコマンドで指定する必要があります。
返り値
返される文字列は、次の形式のXMLです:
<response Code="code" Message="message" />Code=「0」 は、すべて正常に実行されたことを意味します。それ以外の場合は、エラーコードとエラーメッセージが伴います。
クエリアクションの場合、応答にはReturnValueセクションも含まれます。以下を参照してください。
<response Code="0" Message="OK"> <ReturnValue ...... ></response>利用可能なコマンド
ComposerCloseAllDocumentsAction
Composerで開いているすべてのドキュメントを保存を確認せずに閉じます。
<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="xcomp_ファイルのパス" />ComposerSetPinValueAction
- モジュール
- ピン
- 値
<action type="ComposerSetPinValueAction" Module="モジュールパス" Pin="ピン名" Value="ピン値" />ComposerGetPinValueAction
- Module
- Pin
<action type="ComposerGetPinValueAction" Module="module_path" Pin="pin_name" />応答形式:
<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
- 名前パターン
- 再帰的 (true/false)
指定されたルート複合体の下にある名前がパターンに一致するすべてのモジュールのリストを返します。
<action type="ComposerFindModulesAction" Module="root_module_path" NamePattern="wildcard_pattern" Recursive="True/False" />応答形式:
<response Code="0" Message="OK"><ReturnValue> <item value="module_1_path" /> <item value="module_2_path" />................... </ReturnValue></response>ComposerEnumPinsAction
- Module
指定されたモジュールの利用可能な入力ピンとそのタイプの一覧を返します。
<action type="ComposerEnumPinsAction" Module="module_path" />応答形式:
<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
- 再帰的 (true/false)
指定されたルートコンパウンド下のすべてのコントロールボードのリストを返します。
<action type="ComposerEnumCtrBoardsAction" Module="root_module_path" Recursive="True/False" />応答形式:
<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
指定されたコントロールボード下のすべてのパネルのリストを返します。
<action type="ComposerEnumCtrBoardPanelsAction" Module="control_board_path" />応答形式:
<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
指定されたコントロールボードパネルのボタン一覧とそのタイプを返します。
<action type="ComposerEnumCtrBoardButtonsAction" Module="panel_path" />応答形式:
<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>- タイプが 「Trigger」 の場合、ボタンはトリガーピンに属し、クリックごとにトリガー信号を発信します。
- タイプが 「Switch」 の場合、ボタンは論理ピンに属し、クリックでオン/オフを切り替えることができます。
- タイプが 「Enum」 の場合、ボタンは整数ピンに属する複数のボタンのグループの一部です。グループは group 属性で識別されます。同じグループ番号を持つボタンは同じ整数ピンに属します。グループ内では、クリックで一度に1つのボタンしか選択できません。index属性は、ボタンが選択された際にピンに割り当てられる整数値を表します。
- タイプが「Flags」の場合、動作は「Enum」と類似していますが、ボタンは整数値内の個々のビットのオン/オフ状態を表します。各ボタンはクリックで個別にオン/オフできます。index属性は、0から始まるビットのインデックスを表します。
gap は、UI上のボタン前に挿入される空白の数を表します。
ComposerEnumCtrBoardPropertiesAction
- Module
指定されたコントロールボードパネルの可用なプロパティ一覧とそのタイプを返します。
<action type="ComposerEnumCtrBoardPropertiesAction" Module="panel_path" />応答形式:
<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>グループ化コマンド
複数のプロパティ/ボタンを一度に変更したい場合、またはすべてのコマンドを単一のHTTPリクエストで送信したい場合は、ComposerGroupAction コマンドを使用できます。
<action type="ComposerGroupAction"> <action type=........ /> <action type=........ /> <action type=........ /> .....</action>リスト内の各アクションは、上記で説明したコマンドのいずれかです。各アクションはComposerGroupActionとしても指定可能であり、階層的なグループ化を実現できます。
コマンドの送信
HTTP POSTコマンドを送信する方法は複数存在するため、可能な操作は無限です。
このガイドの例では、コマンドの送信にreqbinを使用します。
まず、アドレスを指定します:
これはガイドの冒頭で使用したのと同じものです。
次に、ヘッダー タブに移動し、次のように入力します:
Content-Type: application/xml
その後、コンテンツ タブに移動し、XML コマンドを記述します:
最後に、送信をクリックすると、コマンドが Aximmetry に適用されます:
JavaScript 使用時の注意点
一般的なシナリオは、Aximmetry用のカスタムインターフェースを実装したウェブサイトからJavaScriptでHTTPインターフェースを呼び出す場合です。
NOTE 1: JavaScript XMLHttpRequestを含む一部の送信APIは、Content-Typeが「text/plain」でない場合、実際のPOSTメッセージ送信前にOPTIONSリクエストを送信します。AximmetryはOPTIONSリクエストを処理しません。この場合、Content-Typeを設定しないか、「text/plain」に設定してください。
NOTE 2: JavaScriptでファイルやモジュールパスを文字列として指定する際は、バックスラッシュ (\) 文字がエスケープシーケンスを表す点に注意してください。したがって、実際のバックスラッシュを追加するには、ダブルバックスラッシュを記述する必要があります。例:
「Root\\VirtualCam_3-Cam\\CAMERAS\\SELECT CAMERA」
NOTE 3: JavaScript で XML コマンドを文字列として構築する際、文字列自体または XML 内の属性にシングルクォートを使用できます。例:
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 + 「』 />」;
もちろん、テンプレートリテラルを使用することもできます:
cmd = `<action type="ComposerCtrBoardSetButtonAction" Module="Root\\VirtualCam_3-Cam\\CAMERAS\\STREAMING" Button="On" State="${state}" />`;
