Cuttlefish コントロール パネル

Cuttlefish のデフォルトの WebRTC ブラウザ インターフェースにあるコントロール パネルから、仮想デバイスをさまざまな方法で操作することができます。

コントロール パネルには、電源ボタンや音量ボタンなどの一般的な物理デバイスの操作や、デバイスの回転をシミュレートするデフォルトのボタンが用意されています。

カスタム アクション

コントロール パネルをカスタマイズして、仮想デバイスで物理デバイスをより厳密にエミュレートできるボタンを追加できます。これは、OS で固有のアクションをトリガーするハードウェア ボタンや特別な操作など、デバイス固有の機能をテストする場合に役立ちます。また、カスタムボタンを使用することで、デバイスの電池残量が少ないときの OS の動作など、QA に重点を置いた機能のテストも可能になります。

デフォルトの Cuttlefish コントロール パネルでは、メインの Cuttlefish AOSP プロジェクトを変更せずにカスタム アクションを「プラグイン」する（組み込む）ためのサポートも提供しています。仮想デバイスには、カスタム アクションの使用を開始するための最小限の構成ファイルのみを含める必要があります。こちらのカスタム アクション構成ファイルの例をご覧ください。

  1. デバイスのカスタム アクションを定義する JSON ファイルを作成します。このファイルは、ご自分が所有する任意のディレクトリに置くことができます。このファイルの構造については、ADB シェルとアクション サーバーのセクションをご覧ください。

  2. JSON 構成用の prebuilt_etc_host モジュールを作成します。sub_dir が cvd_custom_action_config と等しいことを確認します。

    prebuilt_etc_host {
    // Use any name you choose.
    name: "my_custom_action_config.json",
    src: "my_custom_action_config.json",
    // Always use this sub_dir.
    sub_dir: "cvd_custom_action_config",
}

  3. デバイスのプロダクトの makefile で Soong 構成ビルド変数を設定して、カスタム アクション構成ファイルを含むように仮想デバイスのホスト パッケージを構成します。

    # Set these variables exactly as shown here to enable the host package to see
# your custom config module name.
SOONG_CONFIG_NAMESPACES += cvd
SOONG_CONFIG_cvd += custom_action_config

# Set this value to the name of your JSON module.
SOONG_CONFIG_cvd_custom_action_config := my_custom_action_config.json

カスタム アクションを実装するためにサポートされている方法は 2 つあります。

  • ADB シェルコマンド
  • アクション サーバー

JSON 構成ファイルは、各タイプの実装のインスタンスを複数定義できます。

ADB シェルコマンド

単一の adb shell コマンドを実行することで実装されるボタンを 1 つ定義できます。たとえば、次の JSON スニペットは、ウェブページを起動する単一のボタンを定義します。

{
  "shell_command":"am start -a android.intent.action.VIEW -d https://www.android.com/",
  "button":{
      "command":"web",
      "title":"Web Page",
      "icon_name":"language"
  }
}

フィールドは次のとおりです。

  • shell_command: ボタンが押されたときに adb shell で実行するコマンド
  • button: 次のサブフィールドを持つ単一のボタン オブジェクト。
    • command: このボタンの固有の名前
    • title: このボタンの代替テキストのタイトル
    • icon_name: https://material.io/resources/icons のアイコンの名前

アクション サーバー

アクション サーバーを使用すると、アクションの動作をより細かく制御できます。アクション サーバーは、ソケットペアを使用して WebRTC からのボタン押下イベントをリッスンするホストバイナリです。WebRTC がイベントをアクション サーバーに転送すると、アクション サーバーがアクションの実装方法を決定します。

アクション サーバーを使用すると、状態の維持（切り替え可能なイベントの場合など）、「メタアクション」（現在のデバイスの強制終了、他のデバイスの起動、画面録画のブラウザ拡張機能の開始など）の実行など、より強力な制御が可能になります。ホストバイナリの内部に何を実装するかにもよりますが、可能性は無限にあります。

次の JSON スニペットは、2 つのボタンでイベントをリッスンするアクション サーバーを定義します。

{
  "server":"cuttlefish_example_action_server",
  "buttons":[
    {
      "command":"settings",
      "title":"Quick Settings",
      "icon_name":"settings"
    },
    {
      "command":"alert",
      "title":"Do Not Disturb",
      "icon_name":"notifications_paused"
    }
  ]
}

フィールドは次のとおりです。

  • server: ホストバイナリ モジュールの名前
  • buttons: 上記と同じサブフィールドを持つボタンの配列

JSON 構成を更新した後、Soong 構成ビルド変数 cvd_custom_action_servers にアクション サーバー モジュールの名前を追加します。次に例を示します。

# Append to this variable exactly as shown here.
SOONG_CONFIG_cvd += custom_action_servers

# Append the name of your action server(s) to this variable.
SOONG_CONFIG_cvd_custom_action_servers += cuttlefish_example_action_server

各アクション サーバー ホストバイナリは、次の手順を実行する必要があります。

  1. 最初で唯一のプログラム引数として、ソケットのファイル記述子番号を受け入れます。

    このソケットは、ドメイン AF_LOCAL、タイプ SOCK_STREAM、プロトコル 0 の socketpair を使用して launch_cvd によって作成されます。

  2. ループで、ソケットから 128 バイトの読み取りを試みます。このバイトには、WebRTC クライアントによって command:state 形式で送信されるボタン押下イベントが含まれます。command は JSON 構成での指定どおり、state はボタンの押下状態（down または up）です。

  3. 受信イベントに基づいて動作し、カスタム アクションをシミュレートします。