自 2025 年 3 月 27 日起，我們建議您使用 android-latest-release 而非 aosp-main 建構及貢獻 AOSP。詳情請參閱「Android 開放原始碼計畫變更」。
Cuttlefish：環境控制
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
本頁說明如何使用 REST API 或指令列介面，控制 Cuttlefish 裝置中的環境。例如修改 Wi-Fi 訊號或更新 Cuttlefish 裝置的 GPS 位置。
服務
cvd env 指令提供下列服務，用於控制 Cuttlefish 環境：
使用 REST API 控管環境
本節說明如何透過 <https://localhost:1443> 服務端點使用 Rest API 控制環境。
列出可用的服務或方法
如要取得所有服務的清單，請將 GET 要求傳送至下列網址，並附上裝置 ID。
https://localhost:1443/devices/DEVICE_ID/services
如要取得服務的所有方法清單，請將 GET 要求傳送至下列網址，並附上裝置 ID 和服務名稱。
https://localhost:1443/devices/DEVICE_ID/services/SERVICE_NAME
如要取得方法的詳細資訊 (例如要求或回應訊息類型)，請將 GET 要求傳送至下列網址，並附上裝置 ID、服務名稱和方法名稱。
https://localhost:1443/devices/DEVICE_ID/services/SERVICE_NAME/METHOD_NAME
取得要求和回應類型的詳細資訊
如要取得要求或回應訊息類型的詳細資訊，請將 GET 要求傳送至下列網址，並附上裝置 ID、服務名稱和要求或回應訊息類型。這會列印訊息中每個欄位的所有名稱和類型。接著，您可以使用這些資訊編寫 JSON 格式的 Protobuf 訊息，以便傳送 RPC 要求。
https://localhost:1443/devices/DEVICE_ID/services/SERVICE_NAME/REQUEST_OR_RESPONSE_TYPE_NAME/type
傳送 RPC 要求以變更環境
如要傳送 RPC 要求，以 JSON 格式的 proto 呼叫服務的方法，請傳送 POST 要求至下列網址，並附上裝置 ID、服務名稱和方法名稱。內文中必須包含 JSON 格式的 proto。
https://localhost:1443/devices/DEVICE_ID/services/SERVICE_NAME/METHOD_NAME
用途範例
以下是 Rest API 的用途範例，可透過呼叫 SetTxpower 修改 Wi-Fi 訊號強度。
決定用於修改 Wi-Fi 訊號強度的服務名稱、方法名稱和要求訊息類型名稱。
如要取得所有可用服務的清單，請將 GET 要求傳送至下列網址。
https://localhost:1443/devices/cvd-1/services
以下是回覆範例。
{"services":["OpenwrtControlService","EchoService","GnssGrpcProxy","WmediumdService"]}
請將 GET 要求傳送至下列網址，取得 WmediumdService 的方法清單。
https://localhost:1443/devices/cvd-1/services/WmediumdService
以下是回覆範例。
{"methods":["ListStations","LoadConfig","ReloadConfig","SetCivicloc","SetLci","SetPosition","SetSnr","SetTxpower","StartPcap","StopPcap"]}
如要取得 SetTxpower 方法的要求和回應訊息類型資訊，請將 GET 要求傳送至下列網址。
https://localhost:1443/devices/cvd-1/services/WmediumdService/SetTxpower
以下是回覆範例。
{"request_type_name":"wmediumdserver.SetTxpowerRequest","response_type_name":"google.protobuf.Empty"}
將 GET 要求傳送至下列網址，即可取得 wmediumdserver.SetTxpowerRequest 要求訊息類型的詳細資訊。
https://localhost:1443/devices/cvd-1/services/WmediumdService/wmediumdserver.SetTxpowerRequest/type
以下是回覆範例。
message SetTxpowerRequest {
string mac_address = 1;
int32 tx_power = 2;
}
將 RPC 要求傳送至 WmediumdService 服務，藉由傳送 POST 要求至此網址，並使用以下要求主體，將 Wi-Fi 訊號強度修改為所需等級。
https://localhost:1443/devices/cvd-1/services/WmediumdService/SetTxpower
{"mac_address":"42:00:00:00:00:00", "tx_power":1}
以下是回覆範例。
{}
使用指令列控管環境
本節說明 cvd env CLI 指令可用的子指令。如需更多詳細資訊，請使用 cvd help env 列印說明訊息。
列出可用的服務或方法
如要取得所有服務的清單，請使用 cvd env ls 而不含任何引數。
cvd env ls
如要取得服務的所有方法清單，請將服務名稱做為引數。
cvd env ls SERVICE_NAME
如要取得詳細資訊 (例如方法的要求或回應訊息類型)，請加入服務名稱和方法名稱。
cvd env ls SERVICE_NAME METHOD_NAME
取得要求和回應類型的詳細資訊
如要取得要求或回應訊息類型的詳細資訊，請使用 cvd env type 指令。這個指令會列印訊息中每個欄位的所有名稱和類型。接著，您可以使用這些資訊來撰寫 JSON 格式的 Proto 訊息，以便傳送 RPC 要求。
cvd env type SERVICE_NAME REQUEST_OR_RESPONSE_TYPE_NAME
傳送 RPC 要求以變更環境
如要傳送 RPC 要求，以 JSON 格式的 proto 呼叫服務的方法，請使用 cvd enc call 指令。RPC 要求終止時，介面會列印訊息 Rpc succeeded with OK status，如果可用，還會列印包含值的回應訊息。
cvd env call SERVICE_NAME METHOD_NAME JSON_FORMATTED_PROTO
用途範例
以下是 cvd env CLI 指令的用途範例，可透過呼叫 SetTxpower 修改 Wi-Fi 訊號強度。
決定用於修改 Wi-Fi 訊號強度的服務名稱、方法名稱和要求訊息類型名稱。
取得所有可用服務的清單。
cvd env ls
(Omitted)
{
"services" :
[
"OpenwrtControlService",
"EchoService",
"GnssGrpcProxy",
"WmediumdService"
]
}
取得 WmediumdService 的相關方法清單。
cvd env ls WmediumdService
(Omitted)
{
"methods" :
[
"ListStations",
"LoadConfig",
"ReloadConfig",
"SetCivicloc",
"SetLci",
"SetPosition",
"SetSnr",
"SetTxpower",
"StartPcap",
"StopPcap"
]
}
取得 SetTxpower 方法的請求和回應訊息類型相關資訊。
cvd env ls WmediumdService SetTxpower
(Omitted)
{
"request_type" : "wmediumdserver.SetTxpowerRequest",
"response_type" : "google.protobuf.Empty"
}
取得 wmediumdserver.SetTxpowerRequest 要求訊息類型的詳細資訊。
cvd env type WmediumdService wmediumdserver.SetTxpowerRequest
(Omitted)
message SetTxpowerRequest {
string mac_address = 1;
int32 tx_power = 2;
}
將 RPC 要求傳送至 WmediumdService 服務，將 Wi-Fi 訊號強度修改為所需等級。
cvd env call WmediumdService SetTxpower "{mac_address:'42:00:00:00:00:00', tx_power:1}"
(Omitted)
Rpc succeeded with OK status
{}
這個頁面中的內容和程式碼範例均受《內容授權》中的授權所規範。Java 與 OpenJDK 是 Oracle 和/或其關係企業的商標或註冊商標。
上次更新時間：2025-07-27 (世界標準時間)。
[[["容易理解","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-07-27 (世界標準時間)。"],[],[],null,["# Cuttlefish: Environment control\n\nThis page describes how to control the environment in a Cuttlefish device\nusing the REST API or the command line interface. For example, you can modify the\nWi-Fi signal or update the GPS location of the Cuttlefish device.\n\nServices\n--------\n\nThe `cvd env` command provides the following services for controlling the\nCuttlefish environment:\n\n| Services | Description |\n|----------------------------------------------------------------------------------|---------------------------------------------------------------------------------------|\n| `GnssGrpcProxy` | Controls GNSS for the Cuttlefish geolocation feature. |\n| [`OpenwrtControlService`](/docs/devices/cuttlefish/wifi#openwrt_control_service) | Controls `Openwrt`, a virtualized Wi-Fi AP provider for the Cuttlefish Wi-Fi feature. |\n| [`WmediumdService`](/docs/devices/cuttlefish/wifi#wmediumd_service) | Controls `Wmediumd`, a wireless medium simulator for the Cuttlefish Wi-Fi feature. |\n| [`CasimirControlService`](/docs/devices/cuttlefish/nfc#casimir_control_service) | Controls `Casimir`, a simulator for external NFC devices. |\n\nControl the environment using the REST API\n------------------------------------------\n\nThis section describes how to control the environment using the Rest API\nthrough the `\u003chttps://localhost:1443\u003e` service endpoint.\n\n### List available services or methods\n\nTo get a list of all services, send a `GET` request to the following URL with\na device ID. \n\n https://localhost:1443/devices/\u003cvar translate=\"no\"\u003eDEVICE_ID\u003c/var\u003e/services\n\nTo get a list of all the methods for a service, send a `GET` request to the\nfollowing URL with a device ID and the service name. \n\n https://localhost:1443/devices/\u003cvar translate=\"no\"\u003eDEVICE_ID\u003c/var\u003e/services/\u003cvar translate=\"no\"\u003eSERVICE_NAME\u003c/var\u003e\n\nTo get detailed information for a method, such as the request or response\nmessage types, send a `GET` request to the following URL with a device ID,\na service name, and the method name. \n\n https://localhost:1443/devices/\u003cvar translate=\"no\"\u003eDEVICE_ID\u003c/var\u003e/services/\u003cvar translate=\"no\"\u003eSERVICE_NAME\u003c/var\u003e/\u003cvar translate=\"no\"\u003eMETHOD_NAME\u003c/var\u003e\n\n### Get detailed information on request and response types\n\nTo get detailed information of a request or response message type, send a `GET`\nrequest to the following URL with a device ID, a service name, and the\nrequest or response message type. This prints all the names and types of each\nfield in the message. You can then use this information to write a\nJSON-formatted proto message for sending a RPC request. \n\n https://localhost:1443/devices/\u003cvar translate=\"no\"\u003eDEVICE_ID\u003c/var\u003e/services/\u003cvar translate=\"no\"\u003eSERVICE_NAME\u003c/var\u003e/\u003cvar translate=\"no\"\u003eREQUEST_OR_RESPONSE_TYPE_NAME\u003c/var\u003e/type\n\n### Send RPC request to make changes to the environment\n\nTo send a RPC request to call a method of a service with a JSON-formatted proto,\nsend a `POST` request to the following URL with a device ID, a service\nname, and the method name. The JSON-formatted proto must be included in the\nbody. \n\n https://localhost:1443/devices/\u003cvar translate=\"no\"\u003eDEVICE_ID\u003c/var\u003e/services/\u003cvar translate=\"no\"\u003eSERVICE_NAME\u003c/var\u003e/\u003cvar translate=\"no\"\u003eMETHOD_NAME\u003c/var\u003e\n\n### Example use case\n\nThe following is an example use case of the Rest API for modifying the Wi-Fi\nsignal strength by calling `SetTxpower`.\n\n1. Determine the service name, method name, and the request message type\n name for modifying the Wi-Fi signal strength.\n\n 1. Get a list of all available services by sending a `GET` request to the\n following URL.\n\n https://localhost:1443/devices/cvd-1/services\n\n This is an example response. \n\n {\"services\":[\"OpenwrtControlService\",\"EchoService\",\"GnssGrpcProxy\",\"WmediumdService\"]}\n\n 2. Get a list of methods for `WmediumdService` by sending a `GET` request\n to the following URL.\n\n https://localhost:1443/devices/cvd-1/services/WmediumdService\n\n This is an example response. \n\n {\"methods\":[\"ListStations\",\"LoadConfig\",\"ReloadConfig\",\"SetCivicloc\",\"SetLci\",\"SetPosition\",\"SetSnr\",\"SetTxpower\",\"StartPcap\",\"StopPcap\"]}\n\n 3. Get information on the request and response message types for the\n `SetTxpower` method by sending a `GET` request to the following URL.\n\n https://localhost:1443/devices/cvd-1/services/WmediumdService/SetTxpower\n\n This is an example response. \n\n {\"request_type_name\":\"wmediumdserver.SetTxpowerRequest\",\"response_type_name\":\"google.protobuf.Empty\"}\n\n2. Get detailed information for the `wmediumdserver.SetTxpowerRequest` request\n message type by sending a `GET` request to the following URL.\n\n https://localhost:1443/devices/cvd-1/services/WmediumdService/wmediumdserver.SetTxpowerRequest/type\n\n This is an example response. \n\n message SetTxpowerRequest {\n string mac_address = 1;\n int32 tx_power = 2;\n }\n\n3. Send a RPC request to the `WmediumdService` service to modify the Wi-Fi\n signal strength to the desired level by sending a `POST` request to this URL\n with the following request body.\n\n https://localhost:1443/devices/cvd-1/services/WmediumdService/SetTxpower\n\n {\"mac_address\":\"42:00:00:00:00:00\", \"tx_power\":1}\n\n This is an example response. \n\n {}\n\nControl the environment using the command line\n----------------------------------------------\n\nThis section describes the subcommands available for the `cvd env` CLI command.\nFor further details, print the help message using `cvd help env`.\n\n### List available services or methods\n\nTo get a list of all services, use `cvd env ls` without any arguments. \n\n cvd env ls\n\nTo get a list of all the methods for a service, include the name of the\nservice as an argument. \n\n cvd env ls \u003cvar translate=\"no\"\u003eSERVICE_NAME\u003c/var\u003e\n\nTo get detailed information such as the request or response message types of a\nmethod, include the service name and method name. \n\n cvd env ls \u003cvar translate=\"no\"\u003eSERVICE_NAME\u003c/var\u003e \u003cvar translate=\"no\"\u003eMETHOD_NAME\u003c/var\u003e\n\n### Get detailed information on request and response types\n\nTo get detailed information of a request or response message type, use the\n`cvd env type` command. This command prints all names and types of each field\nin the message. You can then use this information to write a JSON-formatted\nproto message for sending a RPC request. \n\n cvd env type \u003cvar translate=\"no\"\u003eSERVICE_NAME\u003c/var\u003e \u003cvar translate=\"no\"\u003eREQUEST_OR_RESPONSE_TYPE_NAME\u003c/var\u003e\n\n### Send RPC request to make changes to the environment\n\nTo send a RPC request to call a method of a service with a JSON-formatted proto,\nuse the `cvd enc call` command. When the RPC request terminates, the interface\nprints the message `Rpc succeeded with OK status` and, if available, a response\nmessage including values. \n\n cvd env call \u003cvar translate=\"no\"\u003eSERVICE_NAME\u003c/var\u003e \u003cvar translate=\"no\"\u003eMETHOD_NAME\u003c/var\u003e \u003cvar translate=\"no\"\u003eJSON_FORMATTED_PROTO\u003c/var\u003e\n\n### Example use case\n\nThe following is an example use case of the `cvd env` CLI command for modifying\nthe Wi-Fi signal strength by calling `SetTxpower`.\n\n1. Determine the service name, method name, and the request message type\n name for modifying the Wi-Fi signal strength.\n\n Get a list of all available services. \n\n cvd env ls\n (Omitted)\n {\n \"services\" :\n [\n \"OpenwrtControlService\",\n \"EchoService\",\n \"GnssGrpcProxy\",\n \"WmediumdService\"\n ]\n }\n\n Get a list of methods for `WmediumdService`. \n\n cvd env ls WmediumdService\n (Omitted)\n {\n \"methods\" :\n [\n \"ListStations\",\n \"LoadConfig\",\n \"ReloadConfig\",\n \"SetCivicloc\",\n \"SetLci\",\n \"SetPosition\",\n \"SetSnr\",\n \"SetTxpower\",\n \"StartPcap\",\n \"StopPcap\"\n ]\n }\n\n Get information on the request and response message types for the\n `SetTxpower` method. \n\n cvd env ls WmediumdService SetTxpower\n (Omitted)\n {\n \"request_type\" : \"wmediumdserver.SetTxpowerRequest\",\n \"response_type\" : \"google.protobuf.Empty\"\n }\n\n2. Get detailed information for the `wmediumdserver.SetTxpowerRequest` request\n message type.\n\n cvd env type WmediumdService wmediumdserver.SetTxpowerRequest\n (Omitted)\n message SetTxpowerRequest {\n string mac_address = 1;\n int32 tx_power = 2;\n }\n\n3. Send RPC request to the `WmediumdService` service to modify the Wi-Fi\n signal strength to the desired level.\n\n cvd env call WmediumdService SetTxpower \"{mac_address:'42:00:00:00:00:00', tx_power:1}\"\n (Omitted)\n Rpc succeeded with OK status\n {}"]]
