HTTP経由でのAximmetryの外部制御

導入

このドキュメントでは、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}" />`;