Cuttlefish: Environment control

This page describes how to control the environment in a Cuttlefish device using the REST API or the command line interface. For example, you can modify the Wi-Fi signal or update the GPS location of the Cuttlefish device.

Services

The cvd env command provides the following services for controlling the Cuttlefish environment:

Services	Description
GnssGrpcProxy	Controls GNSS for the Cuttlefish geolocation feature.
OpenwrtControlService	Controls Openwrt, a virtualized Wi-Fi AP provider for the Cuttlefish Wi-Fi feature.
WmediumdService	Controls Wmediumd, a wireless medium simulator for the Cuttlefish Wi-Fi feature.
CasimirControlService	Controls Casimir, a simulator for external NFC devices.

Control the environment using the REST API

This section describes how to control the environment using the Rest API through the <https://localhost:1443> service endpoint.

List available services or methods

To get a list of all services, send a GET request to the following URL with a device ID.

https://localhost:1443/devices/DEVICE_ID/services

To get a list of all the methods for a service, send a GET request to the following URL with a device ID and the service name.

https://localhost:1443/devices/DEVICE_ID/services/SERVICE_NAME

To get detailed information for a method, such as the request or response message types, send a GET request to the following URL with a device ID, a service name, and the method name.

https://localhost:1443/devices/DEVICE_ID/services/SERVICE_NAME/METHOD_NAME

Get detailed information on request and response types

To get detailed information of a request or response message type, send a GET request to the following URL with a device ID, a service name, and the request or response message type. This prints all the names and types of each field in the message. You can then use this information to write a JSON-formatted proto message for sending a RPC request.

https://localhost:1443/devices/DEVICE_ID/services/SERVICE_NAME/REQUEST_OR_RESPONSE_TYPE_NAME/type

Send RPC request to make changes to the environment

To send a RPC request to call a method of a service with a JSON-formatted proto, send a POST request to the following URL with a device ID, a service name, and the method name. The JSON-formatted proto must be included in the body.

https://localhost:1443/devices/DEVICE_ID/services/SERVICE_NAME/METHOD_NAME

Example use case

The following is an example use case of the Rest API for modifying the Wi-Fi signal strength by calling SetTxpower.

1. Determine the service name, method name, and the request message type name for modifying the Wi-Fi signal strength.

   1. Get a list of all available services by sending a GET request to the following URL.

      https://localhost:1443/devices/cvd-1/services
      

      This is an example response.

      {"services":["OpenwrtControlService","EchoService","GnssGrpcProxy","WmediumdService"]}
      

   2. Get a list of methods for WmediumdService by sending a GET request to the following URL.

      https://localhost:1443/devices/cvd-1/services/WmediumdService
      

      This is an example response.

      {"methods":["ListStations","LoadConfig","ReloadConfig","SetCivicloc","SetLci","SetPosition","SetSnr","SetTxpower","StartPcap","StopPcap"]}
      

   3. Get information on the request and response message types for the SetTxpower method by sending a GET request to the following URL.

      https://localhost:1443/devices/cvd-1/services/WmediumdService/SetTxpower
      

      This is an example response.

      {"request_type_name":"wmediumdserver.SetTxpowerRequest","response_type_name":"google.protobuf.Empty"}
      

2. Get detailed information for the wmediumdserver.SetTxpowerRequest request message type by sending a GET request to the following URL.

   https://localhost:1443/devices/cvd-1/services/WmediumdService/wmediumdserver.SetTxpowerRequest/type
   

   This is an example response.

   message SetTxpowerRequest {
     string mac_address = 1;
     int32 tx_power = 2;
   }
   

3. Send a RPC request to the WmediumdService service to modify the Wi-Fi signal strength to the desired level by sending a POST request to this URL with the following request body.

   https://localhost:1443/devices/cvd-1/services/WmediumdService/SetTxpower
   

   {"mac_address":"42:00:00:00:00:00", "tx_power":1}
   

   This is an example response.

   {}
   

Control the environment using the command line

This section describes the subcommands available for the cvd env CLI command. For further details, print the help message using cvd help env.

List available services or methods

To get a list of all services, use cvd env ls without any arguments.

cvd env ls

To get a list of all the methods for a service, include the name of the service as an argument.

cvd env ls SERVICE_NAME

To get detailed information such as the request or response message types of a method, include the service name and method name.

cvd env ls SERVICE_NAME METHOD_NAME

Get detailed information on request and response types

To get detailed information of a request or response message type, use the cvd env type command. This command prints all names and types of each field in the message. You can then use this information to write a JSON-formatted proto message for sending a RPC request.

cvd env type SERVICE_NAME REQUEST_OR_RESPONSE_TYPE_NAME

Send RPC request to make changes to the environment

To send a RPC request to call a method of a service with a JSON-formatted proto, use the cvd enc call command. When the RPC request terminates, the interface prints the message Rpc succeeded with OK status and, if available, a response message including values.

cvd env call SERVICE_NAME METHOD_NAME JSON_FORMATTED_PROTO

Example use case

The following is an example use case of the cvd env CLI command for modifying the Wi-Fi signal strength by calling SetTxpower.

1. Determine the service name, method name, and the request message type name for modifying the Wi-Fi signal strength.

   Get a list of all available services.

   cvd env ls
   (Omitted)
   {
     "services" :
     [
       "OpenwrtControlService",
       "EchoService",
       "GnssGrpcProxy",
       "WmediumdService"
     ]
   }

   Get a list of methods for WmediumdService.

   cvd env ls WmediumdService
   (Omitted)
   {
     "methods" :
     [
       "ListStations",
       "LoadConfig",
       "ReloadConfig",
       "SetCivicloc",
       "SetLci",
       "SetPosition",
       "SetSnr",
       "SetTxpower",
       "StartPcap",
       "StopPcap"
     ]
   }

   Get information on the request and response message types for the SetTxpower method.

   cvd env ls WmediumdService SetTxpower
   (Omitted)
   {
     "request_type" : "wmediumdserver.SetTxpowerRequest",
     "response_type" : "google.protobuf.Empty"
   }

2. Get detailed information for the wmediumdserver.SetTxpowerRequest request message type.

   cvd env type WmediumdService wmediumdserver.SetTxpowerRequest
   (Omitted)
   message SetTxpowerRequest {
     string mac_address = 1;
     int32 tx_power = 2;
   }

3. Send RPC request to the WmediumdService service to modify the Wi-Fi signal strength to the desired level.

   cvd env call WmediumdService SetTxpower "{mac_address:'42:00:00:00:00:00', tx_power:1}"
   (Omitted)
   Rpc succeeded with OK status
   {}