package android.emulation.control
Get desktop application:
View/edit binary Protocol Buffers messages
An EmulatorController service lets you control the emulator. Note that this is currently an experimental feature, and that the service definition might change without notice. Use at your own risk! We use the following rough conventions: streamXXX --> streams values XXX (usually for emulator lifetime). Values are updated as soon as they become available. getXXX --> gets a single value XXX setXXX --> sets a single value XXX, does not returning state, these usually have an observable lasting side effect. sendXXX --> send a single event XXX, possibly returning state information. android usually responds to these events.
rpc streamSensor (, stream )
emulator_controller.proto:44set/get/stream the sensor data
set/get/stream the physical model, this is likely the one you are looking for when you wish to modify the device state.
rpc streamPhysicalModel (, stream )
emulator_controller.proto:51Atomically set/get the current primary clipboard data.
rpc streamClipboard (, stream )
emulator_controller.proto:62Streams the current data on the clipboard. This will immediately produce a result with the current state of the clipboard after which the stream will block and wait until a new clip event is available from the guest. Calling the setClipboard method above will not result in generating a clip event. It is possible to lose clipboard events if the clipboard updates very rapidly.
Set/get the battery to the given state.
rpc setGps (, )
emulator_controller.proto:76Set the state of the gps, gps support will only work properly if: - no location ui is active. That is the emulator is launched in headless mode (-no-window) or the location ui is disabled (-no-location-ui). - the passiveUpdate is set to false. Setting this to false will disable/break the LocationUI. Keep in mind that android usually only samples the gps at 1 hz.
rpc getGps (, )
emulator_controller.proto:82Gets the latest gps state as delivered by the setGps call, or location ui if active. Note: this is not necessarily the actual gps coordinate visible at the time, due to gps sample frequency (usually 1hz).
Simulate a touch event on the finger print sensor.
message
emulator_controller.proto:494bool isTouching = 1
True when the fingprint is touched.
int32 touchId = 2
The identifier of the registered fingerprint.
rpc sendKey (, )
emulator_controller.proto:86Send a keyboard event. Translating the event.
message
emulator_controller.proto:419KeyboardEvent objects describe a user interaction with the keyboard; each event describes a single interaction between the user and a key (or combination of a key with modifier keys) on the keyboard. This follows the pattern as set by (javascript)[https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent] Note: that only keyCode, key, or text can be set and that the semantics will slightly vary.
KeyboardEvent.KeyCodeType codeType = 1
Type of keycode contained in the keyCode field.
KeyboardEvent.KeyEventType eventType = 2
The type of keyboard event that should be sent to the emulator
int32 keyCode = 3
This property represents a physical key on the keyboard (as opposed to the character generated by pressing the key). In other words, this property is a value which isn't altered by keyboard layout or the state of the modifier keys. This value will be interpreted by the emulator depending on the KeyCodeType. The incoming key code will be translated to an evdev code type and send to the emulator. The values in key and text will be ignored.
string key = 4
The value of the key pressed by the user, taking into consideration the state of modifier keys such as Shift as well as the keyboard locale and layout. This follows the w3c standard used in browsers. You can find an accurate description of valid values [here](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values) Note that some keys can result in multiple evdev events that are delivered to the emulator. for example the Key "A" will result in a sequence: ["Shift", "a"] -> [0x2a, 0x1e] whereas "a" results in ["a"] -> [0x1e]. Not all documented keys are understood by android, and only printable ASCII [32-127) characters are properly translated. Keep in mind that there are a set of key values that result in android specific behavior [see](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values#Phone_keys): - "AppSwitch": Behaves as the "Overview" button in android. - "GoBack": The Back button. - "GoHome": The Home button, which takes the user to the phone's main screen (usually an application launcher). - "Power": The Power button.
string text = 5
Series of utf8 encoded characters to send to the emulator. An attempt will be made to translate every character will an EvDev event type and send to the emulator as a keypress event. The values in keyCode, eventType, codeType and key will be ignored. Note that most printable ASCII characters (range [32-127) can be send individually with the "key" param. Do not expect arbitrary UTF symbols to arrive in the emulator (most will be ignored).
Send touch/mouse events. Note that mouse events can be simulated by touch events.
message
emulator_controller.proto:383A TouchEvent contains a list of Touch objects that are in contact with the touch surface. Touch events are delivered in sequence as specified in the touchList. TouchEvents are delivered to the emulated devices using ["Protocol B"](https://www.kernel.org/doc/Documentation/input/multi-touch-protocol.txt)
repeated touches = 1
The list of Touch objects, note that these do not need to be unique
int32 device = 2
The display device where the touch event occurred. Omitting or using the value 0 indicates the main display. Touch events cannot be send to devices other than 0, due to https://issuetracker.google.com/issues/150699691
message
emulator_controller.proto:395The MouseEvent interface represents events that occur due to the user interacting with a pointing device (such as a mouse).
int32 x = 1
The horizontal coordinate. This is the physical location on the screen For example 0 indicates the leftmost coordinate.
int32 y = 2
The vertical coordinate. This is the physical location on the screen For example 0 indicates the top left coordinate.
int32 buttons = 3
Indicates which buttons are pressed. 0: No button was pressed 1: Primary button (left) 2: Secondary button (right)
int32 device = 4
The display device where the mouse event occurred. Omitting or using the value 0 indicates the main display.
Make a phone call.
message
emulator_controller.proto:640PhoneCall.Operation operation = 1
string number = 2
rpc sendSms (, )
emulator_controller.proto:94Sends an sms message to the emulator.
message
emulator_controller.proto:707string srcAddress = 1
The source address where this message came from. The address should be a valid GSM-formatted address as specified by 3GPP 23.040 Sec 9.1.2.5. For example: +3106225412 or (650) 555-1221
string text = 2
A utf8 encoded text message that should be delivered.
Retrieve the status of the emulator. This will contain general hardware information, and whether the device has booted or not.
message
emulator_controller.proto:669string version = 1
The emulator version string.
uint64 uptime = 2
The time the emulator has been active in .ms
bool booted = 3
True if the device has completed booting. For P and later this information will accurate, for older images we rely on adb.
optional vmConfig = 4
The current vm configuration
optional hardwareConfig = 5
The hardware configuration of the running emulator as key valure pairs.
Gets an individual screenshot in the desired format. The image will be scaled to the desired ImageFormat, while maintaining the aspect ratio. The returned image will never exceed the provided width and height. Not setting the width or height (i.e. they are 0) will result in using the device width and height. The resulting image will be properly oriented and can be displayed directly without post processing. For example, if the device has a 1080x1920 screen and is in landscape mode and called with no width or height parameter, it will return an 1920x1080 image. This method will return an empty image if the display is not visible.
rpc streamScreenshot (, stream )
emulator_controller.proto:120Streams a series of screenshots in the desired format. A new frame will be delivered whenever the device produces a new frame. (Beware that this can produce a significant amount of data, and that certain translations are (png transform) can be costly). If the requested display is not visible it will send a single empty image and wait start producing images once the display becomes active, again producing a single empty image when the display becomes inactive.
rpc streamAudio (, stream )
emulator_controller.proto:124Streams a series of audio packets in the desired format. A new frame will be delivered whenever the emulated device produces a new audio frame.
message
emulator_controller.proto:700optional format = 1
uint64 timestamp = 2
Unix epoch in us when this frame was captured.
bytes audio = 3
Contains a sample in the given audio format.
Returns the last 128Kb of logcat output from the emulator Note that parsed logcat messages are only available after L (Api >23). it is possible that the logcat buffer gets overwritten, or falls behind.
rpc streamLogcat (, stream )
emulator_controller.proto:133Streams the logcat output from the emulator. The first call can retrieve up to 128Kb. This call will not return. Note that parsed logcat messages are only available after L (Api >23) it is possible that the logcat buffer gets overwritten, or falls behind.
Transition the virtual machine to the desired state. Note that some states are only observable. For example you cannot transition to the error state.
Gets the state of the virtual machine.
message
emulator_controller.proto:684Used as request type in: EmulatorController.streamAudio
Used as field type in:
uint64 samplingRate = 1
Sampling rate to use, defaulting to 44100 if this is not set. Note, that android devices typically will not use a sampling rate higher than 48kHz. See https://developer.android.com/ndk/guides/audio.
AudioFormat.Channels channels = 2
AudioFormat.SampleFormat format = 3
Used in:
Mono = 0
Stereo = 1
Used in:
AUD_FMT_U8 = 0
Unsigned 8 bit
AUD_FMT_S16 = 1
Signed 16 bit (little endian)
message
emulator_controller.proto:526Used as request type in: EmulatorController.setBattery
Used as response type in: EmulatorController.getBattery
bool hasBattery = 1
bool isPresent = 2
BatteryState.BatteryCharger charger = 3
int32 chargeLevel = 4
BatteryState.BatteryHealth health = 5
BatteryState.BatteryStatus status = 6
Used in:
NONE = 0
AC = 1
USB = 2
WIRELESS = 3
Used in:
GOOD = 0
FAILED = 1
DEAD = 2
OVERVOLTAGE = 3
OVERHEATED = 4
Used in:
UNKNOWN = 0
CHARGING = 1
DISCHARGING = 2
NOT_CHARGING = 3
FULL = 4
message
emulator_controller.proto:333Representation of a clipped data object on the clipboard.
Used as request type in: EmulatorController.setClipboard
Used as response type in: EmulatorController.getClipboard, EmulatorController.streamClipboard
string text = 1
UTF-8 Encoded text.
message
emulator_controller.proto:664Used in:
string key = 1
string value = 2
message
emulator_controller.proto:668Used in:
repeated entry = 1
message
emulator_controller.proto:500Used as request type in: EmulatorController.setGps
Used as response type in: EmulatorController.getGps
bool passiveUpdate = 1
Setting this to false will disable auto updating from the LocationUI, otherwise the location UI will override the location at a frequency of 1hz. - This is unused if the emulator is launched with -no-window, or when he location ui is disabled. - This will BREAK the location ui experience if it is set to false. For example routing will no longer function.
double latitude = 2
The latitude, in degrees.
double longitude = 3
The longitude, in degrees.
double speed = 4
The speed if it is available, in meters/second over ground
double bearing = 5
gets the horizontal direction of travel of this device, and is not related to the device orientation. It is guaranteed to be in the range [0.0, 360.0] if the device has a bearing. 0=North, 90=East, 180=South, etc..
double altitude = 6
The altitude if available, in meters above the WGS 84 reference ellipsoid.
int32 satellites = 7
The number of satellites used to derive the fix
message
emulator_controller.proto:611Used as response type in: EmulatorController.getScreenshot, EmulatorController.streamScreenshot
optional format = 1
uint32 width = 2
width is contained in format.
uint32 height = 3
height is contained in format.
bytes image = 4
The organization of the pixels in the image buffer is from left to right and bottom up. This will be empty if an alternative image transport is requested in the image format. In that case the side channel should be used to obtain the image data.
uint32 seq = 5
[Output Only] Monotonically increasing sequence number in a stream of screenshots. The first screenshot will have a sequence of 0. A single screenshot will always have a sequence number of 0. The sequence is not necessarily contiguous, and can be used to detect how many frames were dropped. An example sequence could be: [0, 3, 5, 7, 9, 11].
message
emulator_controller.proto:573Used as request type in: EmulatorController.getScreenshot, EmulatorController.streamScreenshot
Used as field type in:
ImageFormat.ImgFormat format = 1
The (desired) format of the resulting bytes.
optional rotation = 2
[Output Only] The rotation of the image. The image will be rotated based upon the coarse grained orientation of the device.
uint32 width = 3
The (desired) width of the image. When passed as input the image will be scaled to match the given width, while maintaining the aspect ratio of the device. The returned image will never exceed the given width, but can be less. Omitting this value (or passing in 0) will result in no scaling, and the width of the actual device will be used.
uint32 height = 4
The (desired) height of the image. When passed as input the image will be scaled to match the given height, while maintaining the aspect ratio of the device. The returned image will never exceed the given height, but can be less. Omitting this value (or passing in 0) will result in no scaling, and the height of the actual device will be used.
uint32 display = 5
The (desired) display id of the device. Setting this to 0 (or omitting) indicates the main display.
optional transport = 6
Set this if you wish to use a different transport channel to deliver image frames.
Used in:
PNG = 0
Portable Network Graphics format (https://en.wikipedia.org/wiki/Portable_Network_Graphics)
RGBA8888 = 1
Three-channel RGB color model supplemented with a fourth alpha channel. https://en.wikipedia.org/wiki/RGBA_color_model Each pixel consists of 4 bytes.
RGB888 = 2
Three-channel RGB color model, each pixel consists of 3 bytes
message
emulator_controller.proto:557An ImageTransport allows for specifying a side channel for delivering image frames versus using the standard bytes array that is returned with the gRPC request.
Used in:
ImageTransport.TransportChannel channel = 1
The desired transport channel used for delivering image frames. Only relevant when streaming screenshots.
string handle = 2
Handle used for writing image frames if transport is mmap. The client sets and owns this handle. It can be either a shm region, or a mmap. A mmap should be a url that starts with `file:///` Note: the mmap can result in tearing.
Used in:
TRANSPORT_CHANNEL_UNSPECIFIED = 0
Return full frames over the gRPC transport
MMAP = 1
Write images to the a file/shared memory handle.
Code types that the emulator can receive. Note that the emulator will do its best to translate the code to an evdev value that will be send to the emulator. This translation is based on the chromium translation tables. See (this)[https://android.googlesource.com/platform/external/qemu/+/refs/heads/emu-master-dev/android/android-grpc/android/emulation/control/keyboard/keycode_converter_data.inc] for details on the translation.
Used in:
Usb = 0
Evdev = 1
XKB = 2
Win = 3
Mac = 4
Used in:
keydown = 0
Indicates that this keyevent should be send to the emulator as a key down event. Meaning that the key event will be translated to an EvDev event type and bit 11 (0x400) will be set before it is sent to the emulator.
keyup = 1
Indicates that the keyevent should be send to the emulator as a key up event. Meaning that the key event will be translated to an EvDev event type and sent to the emulator.
keypress = 2
Indicates that the keyevent will be send to the emulator as e key down event and immediately followed by a keyup event.
message
emulator_controller.proto:255Used as request type in: EmulatorController.getLogcat, EmulatorController.streamLogcat
Used as response type in: EmulatorController.getLogcat, EmulatorController.streamLogcat
string contents = 1
[Output Only] The contents of the log output.
int64 start = 2
The starting byte position of the output that was returned. This should match the start parameter sent with the request. If the serial console output exceeds the size of the buffer, older output will be overwritten by newer content and the start values will be mismatched.
int64 next = 3
[Output Only] The position of the next byte of content from the serial console output. Use this value in the next request as the start parameter.
LogMessage.LogType sort = 4
Set the sort of response you are interested it in. It the type is "Parsed" the entries field will contain the parsed results. otherwise the contents field will be set.
repeated entries = 5
[Output Only] The parsed logcat entries so far. Only set if sort is set to Parsed
Used in:
Text = 0
Parsed = 1
message
emulator_controller.proto:280A parsed logcat entry.
Used in:
uint64 timestamp = 1
A Unix timestamps in milliseconds (The number of milliseconds that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds)
uint32 pid = 2
Process id.
uint32 tid = 3
Thread id.
LogcatEntry.LogLevel level = 4
string tag = 5
string msg = 6
The possible log levels.
Used in:
UNKNOWN = 0
DEFAULT = 1
VERBOSE = 2
DEBUG = 3
INFO = 4
WARN = 5
ERR = 6
FATAL = 7
SILENT = 8
message
emulator_controller.proto:173Used in: ,
repeated float data = 1
Used in:
InitCall = 0
AcceptCall = 1
RejectCallExplicit = 2
RejectCallBusy = 3
DisconnectCall = 4
PlaceCallOnHold = 5
TakeCallOffHold = 6
message
emulator_controller.proto:653Used as response type in: EmulatorController.sendPhone, EmulatorController.sendSms
PhoneResponse.Response response = 1
Used in:
OK = 0
BadOperation = 1
Enum out of range
BadNumber = 2
Mal-formed telephone number
InvalidAction = 3
E.g., disconnect when no call is in progress
ActionFailed = 4
Internal error
RadioOff = 5
Radio power off
message
emulator_controller.proto:174Used as request type in: EmulatorController.getPhysicalModel, EmulatorController.setPhysicalModel, EmulatorController.streamPhysicalModel
Used as response type in: EmulatorController.getPhysicalModel, EmulatorController.streamPhysicalModel
PhysicalModelValue.PhysicalType target = 1
PhysicalModelValue.State status = 2
[Output Only]
optional value = 3
Value interpretation depends on sensor, will contain at most 3 values.
Details on the sensors documentation can be found here: https://developer.android.com/reference/android/hardware/Sensor.html#TYPE_
Used in:
POSITION = 0
ROTATION = 1
All values are angles in degrees. values = [x,y,z]
MAGNETIC_FIELD = 2
TEMPERATURE = 3
Temperature in °C
PROXIMITY = 4
Proximity sensor distance measured in centimeters
LIGHT = 5
Ambient light level in SI lux units
PRESSURE = 6
Atmospheric pressure in hPa (millibar)
HUMIDITY = 7
Relative ambient air humidity in percent
VELOCITY = 8
AMBIENT_MOTION = 9
Used in:
OK = 0
NO_SERVICE = -3
qemud service is not available/initiated.
DISABLED = -2
Sensor is disabled.
UNKNOWN = -1
Unknown sensor (should not happen)
message
emulator_controller.proto:627Used in:
Rotation.SkinRotation rotation = 1
Can be inferred from z-axis as well.
double xAxis = 2
Specifies the angle of rotation, in degrees [-180, 180]
double yAxis = 3
double zAxis = 4
Used in:
PORTRAIT = 0
0 degrees
LANDSCAPE = 1
90 degrees
REVERSE_PORTRAIT = 2
-180 degrees
REVERSE_LANDSCAPE = 3
-90 degrees
message
emulator_controller.proto:209A single sensor value.
Used as request type in: EmulatorController.getSensor, EmulatorController.setSensor, EmulatorController.streamSensor
Used as response type in: EmulatorController.getSensor, EmulatorController.streamSensor
SensorValue.SensorType target = 1
Type of sensor
SensorValue.State status = 2
[Output Only]
optional value = 3
Value interpretation depends on sensor enum, will contain at most 3 values.
These are the various sensors that can be available in an emulated devices.
Used in:
ACCELERATION = 0
Measures the acceleration force in m/s2 that is applied to a device on all three physical axes (x, y, and z), including the force of gravity.
GYROSCOPE = 1
Measures a device's rate of rotation in rad/s around each of the three physical axes (x, y, and z).
MAGNETIC_FIELD = 2
Measures the ambient geomagnetic field for all three physical axes (x, y, z) in μT.
ORIENTATION = 3
Measures degrees of rotation that a device makes around all three physical axes (x, y, z)
TEMPERATURE = 4
Measures the temperature of the device in degrees Celsius (°C).
PROXIMITY = 5
Measures the proximity of an object in cm relative to the view screen of a device. This sensor is typically used to determine whether a handset is being held up to a person's ear.
LIGHT = 6
Measures the ambient light level (illumination) in lx.
PRESSURE = 7
Measures the ambient air pressure in hPa or mbar.
HUMIDITY = 8
Measures the relative ambient humidity in percent (%).
MAGNETIC_FIELD_UNCALIBRATED = 9
GYROSCOPE_UNCALIBRATED = 10
Used in:
OK = 0
NO_SERVICE = -3
qemud service is not available/initiated.
DISABLED = -2
Sensor is disabled.
UNKNOWN = -1
Unknown sensor (should not happen)
message
emulator_controller.proto:340The Touch interface represents a single contact point on a touch-sensitive device. The contact point is commonly a finger or stylus and the device may be a touchscreen or trackpad.
Used in:
int32 x = 1
The horizontal coordinate. This is the physical location on the screen For example 0 indicates the leftmost coordinate.
int32 y = 2
The vertical coordinate. This is the physical location on the screen For example 0 indicates the top left coordinate.
int32 identifier = 3
The identifier is an arbitrary non-negative integer that is used to identify and track each tool independently when multiple tools are active. For example, when multiple fingers are touching the device, each finger should be assigned a distinct tracking id that is used as long as the finger remains in contact. Tracking ids may be reused when their associated tools move out of range. The emulator currently supports up to 10 concurrent touch events. The identifier should be a value from the set [0, 10]
int32 pressure = 4
Reports the physical pressure applied to the tip of the tool or the signal strength of the touch contact. The values reported must be non-zero when the tool is touching the device and zero otherwise to indicate that the touch event is completed. Make sure to deliver a pressure of 0 for the given identifier when the touch event is completed, otherwise the touch identifier will not be unregistered!
int32 touch_major = 5
Optionally reports the cross-sectional area of the touch contact, or the length of the longer dimension of the touch contact.
int32 touch_minor = 6
Optionally reports the length of the shorter dimension of the touch contact. This axis will be ignored if touch_major is reporting an area measurement greater than 0.
message
emulator_controller.proto:306Information about the hypervisor that is currently in use.
Used in:
VmConfiguration.VmHypervisorType hypervisorType = 1
int32 numberOfCpuCores = 2
int64 ramSizeBytes = 3
Used in:
UNKNOWN = 0
An unknown hypervisor
NONE = 1
No hypervisor is in use. This usually means that the guest is running on a different CPU than the host, or you are using a platform where no hypervisor is available.
KVM = 2
The Kernel based Virtual Machine (https://www.linux-kvm.org/page/Main_Page)
HAXM = 3
Intel® Hardware Accelerated Execution Manager (Intel® HAXM) https://github.com/intel/haxm
HVF = 4
Hypervisor Framework. https://developer.apple.com/documentation/hypervisor
WHPX = 5
Window Hypervisor Platform https://docs.microsoft.com/en-us/virtualization/api/
GVM = 6
message
emulator_controller.proto:142A Run State that describes the state of the Virtual Machine.
Used as request type in: EmulatorController.setVmState
Used as response type in: EmulatorController.getVmState
VmRunState.RunState state = 1
Used in:
UNKNOWN = 0
The emulator is in an unknown state. You cannot transition to this state.
RUNNING = 1
Guest is actively running. You can transition to this state from the paused state.
RESTORE_VM = 2
Guest is paused to load a snapshot. You cannot transition to this state.
PAUSED = 3
Guest has been paused. Transitioning to this state will pause the emulator the guest will not be consuming any cpu cycles.
SAVE_VM = 4
Guest is paused to take or export a snapshot. You cannot transition to this state.
SHUTDOWN = 5
System shutdown, note that it is similar to power off. It tries to set the system status and notify guest. The system is likely going to disappear soon and do proper cleanup of resources, possibly taking a snapshot. This is the same behavior as closing the emulator by clicking the X (close) in the user interface.
TERMINATE = 7
Immediately terminate the emulator. No resource cleanup will take place. There is a good change to corrupt the system.
RESET = 9
Will cause the emulator to reset. This is not a state you can observe.
INTERNAL_ERROR = 10
Guest experienced some error state, you cannot transition to this state.