Cuttlefish コントロールパネル

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

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

カスタムアクション

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

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

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

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",
}

デバイスのプロダクトの 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

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

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

このソケットは、ドメイン AF_LOCAL、タイプ SOCK_STREAM、プロトコル 0 の socketpair を使用して launch_cvd によって作成されます。
ループで、ソケットから 128 バイトの読み取りを試みます。このバイトには、WebRTC クライアントによって command:state 形式で送信されるボタン押下イベントが含まれます。command は JSON 構成での指定どおり、state はボタンの押下状態（down または up）です。
受信イベントに基づいて動作し、カスタムアクションをシミュレートします。

Cuttlefish コントロール パネル

カスタム アクション

ADB シェルコマンド

アクション サーバー

Cuttlefish コントロールパネル

カスタムアクション

アクションサーバー