Cuttlefish용 기본 WebRTC 브라우저 인터페이스에는 가상 기기와 상호작용할 다양한 방법을 제공하는 제어판이 포함됩니다.
제어판에는 기기 회전뿐만 아니라 일반적인 실제 기기 동작을 시뮬레이션하는 기본 버튼(예: 전원 버튼 또는 볼륨 버튼)이 있습니다.
맞춤 작업
제어판을 맞춤설정하여 가상 기기에서 실제 기기를 더 정확하게 에뮬레이션할 수 있는 버튼을 추가할 수 있습니다. 이 기능은 OS에서 고유한 동작을 트리거하는 하드웨어 버튼 또는 특수 동작과 같이 기기 고유의 기능을 테스트하는 데 유용합니다. 또한, 기기의 배터리가 부족할 때 맞춤 버튼을 사용하여 OS 동작과 같은 QA 중심의 기능 테스트를 더 많이 할 수 있습니다.
기본 Cuttlefish 제어판은 기본 Cuttlefish AOSP 프로젝트를 수정할 필요 없이 맞춤 작업을 '연결'할 수 있도록 지원합니다. 맞춤 작업을 사용하여 시작하려면 가상 기기에서 최소 구성 파일만 포함해야 합니다. 맞춤 작업 구성 파일의 예를 참고하세요.
기기의 맞춤 작업을 정의하는 JSON 파일을 만듭니다. 소유한 모든 디렉터리에 이 파일을 넣을 수 있습니다. 이 파일의 구조는 ADB 셸 및 작업 서버 섹션에서 설명합니다.
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+=cvdSOONG_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
맞춤 작업을 구현하는 방법에는 두 가지가 있습니다.
ADB 셸 명령어
작업 서버
JSON 구성 파일은 각 구현 유형의 여러 인스턴스를 정의할 수 있습니다.
ADB 셸 명령어
adb
shell 단일 명령어를 실행하여 구현되는 하나의 버튼을 정의할 수 있습니다. 예를 들어, 다음 JSON 스니펫은 웹페이지를 실행하는 하나의 버튼을 정의합니다.
작업 서버를 사용하면 작업의 동작을 더 세부적으로 제어할 수 있습니다. 작업 서버는 소켓 쌍을 사용하여 WebRTC의 버튼 누르기 이벤트를 수신 대기하는 호스트 바이너리입니다. WebRTC에서 작업 서버로 이벤트를 전달하면 작업 서버에서 작업 구현 방법을 결정합니다.
작업 서버를 사용하면 상태 유지(예: 전환 가능 이벤트) 또는 '메타 작업' 실행(예: 현재 기기 종료, 더 많은 기기 실행 또는 화면 녹화 브라우저 확장 프로그램 시작)과 같은 더 강력한 제어가 가능합니다. 이러한 가능성은 호스트 바이너리 내에서 구현하려는 내용에 의해서만 제한됩니다.
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)입니다.
수신된 이벤트에 맞게 작동하여 맞춤 작업을 시뮬레이션합니다.
이 페이지에 나와 있는 콘텐츠와 코드 샘플에는 콘텐츠 라이선스에서 설명하는 라이선스가 적용됩니다. 자바 및 OpenJDK는 Oracle 및 Oracle 계열사의 상표 또는 등록 상표입니다.
최종 업데이트: 2025-08-30(UTC)
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["필요한 정보가 없음","missingTheInformationINeed","thumb-down"],["너무 복잡함/단계 수가 너무 많음","tooComplicatedTooManySteps","thumb-down"],["오래됨","outOfDate","thumb-down"],["번역 문제","translationIssue","thumb-down"],["샘플/코드 문제","samplesCodeIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-08-30(UTC)"],[],[],null,["The default WebRTC browser interface for Cuttlefish includes a control panel\nthat enables more ways to interact with the virtual device.\n\nThe control panel features default buttons to simulate common physical device\nactions such as power button or volume buttons, as well as device rotation.\n\nCustom actions\n\nYou can customize the control panel to add more buttons that allow your virtual\ndevice to more closely emulate your physical device. This is useful for testing\nfeatures unique to your device, such as a hardware button or special gesture\nthat triggers a unique action in the OS. You can also use custom buttons to\nenable testing more QA-focused features such as the behavior of your OS when the\ndevice is low battery.\n\nThe default Cuttlefish control panel includes support to \"plug in\" custom\nactions *without needing to modify the main Cuttlefish AOSP project* . Your\nvirtual device needs to include only a minimal configuration file to start using\ncustom actions. See this\n[example custom action config file](https://cs.android.com/android/platform/superproject/+/android-latest-release:device/google/cuttlefish/host/example_custom_actions/custom_action_config.json).\n\n1. Create a JSON file that defines your device's custom actions. You can put\n this file in any directory you own. The structure of this file is described\n in the [ADB shell](#adb-shell) and [Action server](#action-server) sections.\n\n2. Create a `prebuilt_etc_host` module for your JSON config. Ensure that the\n `sub_dir` is equal to `cvd_custom_action_config`.\n\n prebuilt_etc_host {\n // Use any name you choose.\n name: \"my_custom_action_config.json\",\n src: \"my_custom_action_config.json\",\n // Always use this sub_dir.\n sub_dir: \"cvd_custom_action_config\",\n }\n\n3. Set Soong config build variables in your device's product makefile to\n configure the virtual device host package to include your custom action\n config file.\n\n # Set these variables exactly as shown here to enable the host package to see\n # your custom config module name.\n SOONG_CONFIG_NAMESPACES += cvd\n SOONG_CONFIG_cvd += custom_action_config\n\n # Set this value to the name of your JSON module.\n SOONG_CONFIG_cvd_custom_action_config := my_custom_action_config.json\n\n| **Note:** If you want to remove custom actions from a local build, or change the name of the custom action config module, remove your old config by deleting `${ANDROID_SOONG_HOST_OUT}/etc/cvd_custom_action_config`.\n\nThere are two supported methods to implement a custom action:\n\n- ADB shell command\n- Action server\n\nYour JSON config file can define multiple instances of each type of\nimplementation.\n\nADB shell command\n\nYou can define a single button that is implemented by executing a single `adb\nshell` command. For example, the following JSON snippet defines a single button\nthat launches a web page: \n\n {\n \"shell_command\":\"am start -a android.intent.action.VIEW -d https://www.android.com/\",\n \"button\":{\n \"command\":\"web\",\n \";title\":\"Web Page\",\n \"icon_name\":\"language\"\n }\n }\n\nThe fields are:\n\n- `shell_command`: The command to execute in `adb shell` when the button is pressed\n- `button`: A single button object with the following subfields:\n - `command`: A unique name for this button\n - `title`: An alt-text title for this button\n - `icon_name`: The name of an icon from \u003chttps://material.io/resources/icons\u003e\n\nAction server\n\nAction servers allow more control over the behavior of your actions. An action\nserver is a host binary that listens for button press events from WebRTC using a\nsocket pair. WebRTC forwards the events to the action server, and then the\naction server decides how to implement the action.\n\nAction servers allow more powerful control, such as maintaining state (such as\nfor a toggleable event) or even running \"meta-actions\" such as killing the\ncurrent device, launching more devices, or starting a screen-recording browser\nextension. The possibilities are limited only by what you decide to implement\ninside the host binary.\n\nThe following JSON snippet defines an action server that listens for events on\ntwo buttons: \n\n {\n \"server\":\"cuttlefish_example_action_server\",\n \"buttons\":[\n {\n \"command\":\"settings\",\n \"title\":\"Quick Settings\",\n \"icon_name\":\"settings\"\n },\n {\n \"command":\"alert\",\n \"title\":\"Do Not Disturb\",\n \"icon_name\":\"notifications_paused\"\n }\n ]\n }\n\nThe fields are:\n\n- `server`: The name of your host binary module\n- `buttons`: An array of buttons, with the same subfields as above\n\nAfter updating the JSON config, append the name of the action server module to\nthe Soong config build variable `cvd_custom_action_servers`. For example: \n\n # Append to this variable exactly as shown here.\n SOONG_CONFIG_cvd += custom_action_servers\n\n # Append the name of your action server(s) to this variable.\n SOONG_CONFIG_cvd_custom_action_servers += cuttlefish_example_action_server\n\nEach action server host binary should perform the following steps:\n\n1. Accept a socket file descriptor number as the first and only program\n argument.\n\n This socket is created by `launch_cvd` using `socketpair` with domain\n `AF_LOCAL`, type `SOCK_STREAM`, and protocol 0.\n2. In a loop, attempt to read 128 bytes from the socket. These bytes\n contain button press events sent by the WebRTC client in the format\n `command:state`. `command` is as provided in the JSON config, and `state` is\n the button press state (`down` or `up`).\n\n3. Act on the incoming events to simulate the custom action.\n\n| **Warning:** You should implement any action servers in projects that you own, **not** in the main AOSP Cuttlefish project. This prevents conflicts with future AOSP changes in that project."]]
