android/android-grpc/emulator_controller.proto

// Copyright (C) 2018 The Android Open Source Project
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
syntax = "proto3";

option java_multiple_files = true;
option java_package = "com.android.emulator";
option objc_class_prefix = "AEC";

package android.emulation.control;

import "google/protobuf/empty.proto";

// An EmulatorController service lets you control the emulator.
service EmulatorController {
    rpc setRotation(Rotation) returns (Rotation) {}
    rpc getRotation(google.protobuf.Empty) returns (Rotation) {}

    rpc setBattery(BatteryState) returns (BatteryState) {}
    rpc getBattery(google.protobuf.Empty) returns (BatteryState) {}

    rpc getGps(google.protobuf.Empty) returns (GpsState) {}
    rpc setGps(GpsState) returns (GpsState) {}

    rpc sendFingerprint(FingerprintEvent) returns (google.protobuf.Empty) {}
    rpc sendKey(KeyboardEvent) returns (google.protobuf.Empty) {}

    // Note that touch events can be used instead of mouse events if desired.
    rpc sendTouch(TouchEvent) returns (google.protobuf.Empty) {}
    rpc sendMouse(MouseEvent) returns (google.protobuf.Empty) {}
    rpc sendRotary(RotaryEvent) returns (google.protobuf.Empty) {}

    rpc getStatus(google.protobuf.Empty) returns (EmulatorStatus) {}

    rpc getScreenshot(ImageFormat) returns (Image) {}

    // Returns the last 128Kb of logcat output from the emulator
    rpc getLogcat(LogMessage) returns (LogMessage) {}

    // Streams the logcat output from the emulator. The first call
    // can retrieve up to 128Kb. This call will not return.
    rpc streamLogcat(LogMessage) returns (stream LogMessage) {}

    rpc usePhone(TelephoneOperation) returns (TelephoneResponse) {}

    // The following endpoints are needed to establish the webrtc protocol
    // Due to limitiations in Javascript we cannot make use of bidirectional
    // endpoints See this [blog](https://grpc.io/blog/state-of-grpc-web) for
    // details.

    // This function will generate a new identifier that the client
    // should use for further interaction. It will initiate the
    // JSEP protocol on the server side.
    rpc requestRtcStream(google.protobuf.Empty) returns (RtcId) {}

    // Sends the given JsepMsg to the server. The RtcId in the
    // message should point to an active stream negotiation in
    // progress, otherwise the message will be ignored.
    rpc sendJsepMessage(JsepMsg) returns (google.protobuf.Empty) {}

    // Reads an available jsep messages for the given client id,
    // blocking at most 5 seconds, or until one becomes available.
    //
    // The ice candidates for example will trickle in on this callback,
    // as will the SDP negotation.
    rpc receiveJsepMessage(RtcId) returns (JsepMsg) {}
}


message RtcId {
    // The unique identifier of this connection. You will have to use the same
    // identifier when sending/receiving messages. The server will generate a
    // guid when receiving the start message.
    string guid = 1;
}

message JsepMsg {
    // The unique identifier of this connection. You will have to use the same
    // identifier when sending/receiving messages. The server will generate a
    // guid when receiving the start message.
    RtcId id = 1;
    // The JSON payload. This usually can be directly handled by the Javascript
    // The dictionary can contain the following properties
    //
    // - bye:
    //        You can hang up now. No new message expected for you.
    //        The server has stopped the RTC stream.
    //
    // - start:
    //        An RTCConfiguration dictionary providing options to
    //        configure the new connection. This can include the
    //        turn configuration the serve is using. This dictionary can be
    //        passed in directly to the
    //        [RTCPeerConnection](https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection)
    //        object.
    //
    // - candidate:
    //        The WebRTC API's RTCIceCandidateInit dictionary, which
    //        contains the information needed to fundamentally describe an
    //        RTCIceCandidate. See
    //        [RTCIceCandidate](https://developer.mozilla.org/en-US/docs/Web/API/RTCIceCandidate)
    //        and [Session
    //        Lifetime](https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API/Session_lifetime)
    //        for more details.
    //
    // - sdp:
    //        RTCSessionDescriptionInit dictionary containing the values
    //        to that can be assigned to a
    //        [RTCSessionDescription](https://developer.mozilla.org/en-US/docs/Web/API/RTCSessionDescription)
    string message = 2;
}

message LogMessage {
    // [Output Only] The contents of the log output.
    string contents = 1;
    // 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 start = 2;
    //[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.
    int64 next = 3;

    // 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.
    LogType sort = 4;

    // [Output Only] The parsed logcat entries so far. Only set if sort is set
    // to Parsed
    repeated LogcatEntry entries = 5;

    enum LogType {
        Text = 0;
        Parsed = 1;
    }
}

message LogcatEntry {
    enum LogLevel {
        UNKNOWN = 0;
        DEFAULT = 1;
        VERBOSE = 2;
        DEBUG = 3;
        INFO = 4;
        WARN = 5;
        ERROR = 6;
        FATAL = 7;
        SILENT = 8;
    };

    uint64 timestamp = 1;
    uint32 pid = 2;
    uint32 tid = 3;
    LogLevel level = 4;
    string tag = 5;
    string msg = 6;
}

message VmConfiguration {
    enum VmHypervisorType {
        HV_UNKNOWN = 0;
        HV_NONE = 1;
        HV_KVM = 2;
        HV_HAXM = 3;
        HV_HVF = 4;
        HV_WHPX = 5;
        HV_GVM = 6;
    };

    VmHypervisorType hypervisorType = 1;
    int32 numberOfCpuCores = 2;
    int64 ramSizeBytes = 3;
}

message RotaryEvent {
    int32 delta = 1;
}

// The 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.
message Touch {
    // The horizontal coordinate. This is the physical location on the screen
    // For example 0 indicates the leftmost coordinate.
    int32 x = 1;

    // The vertical coordinate. This is the physical location on the screen
    // For example 0 indicates the top left coordinate.
    int32 y = 2;

    // 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 identifier = 3;

    // 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 pressure = 4;

    // Optionally reports the cross-sectional area of the touch contact, or the
    // length of the longer dimension of the touch contact.
    int32 touch_major = 5;

    // 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.
    int32 touch_minor = 6;
}

// A 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)
message TouchEvent {
    // The list of Touch objects, note that these do not need to be unique
    repeated Touch touches = 1;

    // The display device where the touch event occurred.
    // Omitting or using the value 0 indicates the main display.
    int32 device = 2;
}

// The MouseEvent interface represents events that occur due to the user
// interacting with a pointing device (such as a mouse).
message MouseEvent {
    // The horizontal coordinate. This is the physical location on the screen
    // For example 0 indicates the leftmost coordinate.
    int32 x = 1;

    // The vertical coordinate. This is the physical location on the screen
    // For example 0 indicates the top left coordinate.
    int32 y = 2;

    // Indicates which buttons are pressed.
    // 0: No button was pressed
    // 1: Primary button (left)
    // 2: Secondary button (right)
    int32 buttons = 3;

    // The display device where the mouse event occurred.
    // Omitting or using the value 0 indicates the main display.
    int32 device = 4;
}

// KeyboardEvent 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.
message KeyboardEvent {
    // 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
    // https://chromium.googlesource.com/chromium/src/+/lkgr/ui/events/keycodes/dom/keycode_converter_data.inc
    // for details on the translation.
    enum KeyCodeType {
        Usb = 0;
        Evdev = 1;
        XKB = 2;
        Win = 3;
        Mac = 4;
    };

    enum KeyEventType {
        // 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.
        keydown = 0;

        // 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.
        keyup = 1;

        // Indicates that the keyevent will be send to the emulator
        // as e key down event and immediately followed by a keyup event.
        keypress = 2;
    };

    // Type of keycode contained in the keyCode field.
    KeyCodeType codeType = 1;

    // The type of keyboard event that should be sent to the emulator
    KeyEventType eventType = 2;

    // 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.
    int32 keyCode = 3;

    // 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]
    // The values in text, keyCode, eventType and codeType will be ignored and a
    // keypress event will be delivered to the emulator.
    string key = 4;

    // Series of utf8 encoded characters to send to the emulator. Every
    // character will be translated to an EvDev event type and send to the
    // emulator as a keypress event. The values in keyCode, eventType, codeType
    // and key will be ignored.
    string text = 5;
}

message FingerprintEvent {
    bool isTouching = 1;
    int32 touchId = 2;
}

message GpsState {
    bool passiveUpdate = 1;
    double latitude = 2;
    double longitude = 3;
    double speed = 4;
    double heading = 5;
    double elevation = 6;
    int32 satellites = 7;
}

message BatteryState {
    enum BatteryStatus {
        BATTERY_STATUS_UNKNOWN = 0;
        BATTERY_STATUS_CHARGING = 1;
        BATTERY_STATUS_DISCHARGING = 2;
        BATTERY_STATUS_NOT_CHARGING = 3;
        BATTERY_STATUS_FULL = 4;
    };
    enum BatteryCharger {
        BATTERY_CHARGER_NONE = 0;
        BATTERY_CHARGER_AC = 1;
        BATTERY_CHARGER_USB = 2;
        BATTERY_CHARGER_WIRELESS = 3;
    };

    enum BatteryHealth {
        BATTERY_HEALTH_GOOD = 0;
        BATTERY_HEALTH_FAILED = 1;
        BATTERY_HEALTH_DEAD = 2;
        BATTERY_HEALTH_OVERVOLTAGE = 3;
        BATTERY_HEALTH_OVERHEATED = 4;
    };
    bool hasBattery = 1;
    bool isPresent = 2;
    BatteryCharger charger = 3;
    int32 chargeLevel = 4;
    BatteryHealth health = 5;
    BatteryStatus status = 6;
}

message ImageStream {
    uint32 framerate = 1;
    ImageFormat format = 2;
}

message ImageFormat {
    enum ImgFormat {
        PNG = 0;
        RAW = 1;
        RGB888 = 2;
        RGBA8888 = 3;
    }
    ImgFormat format = 1;
    Rotation rotation = 2;
}

message Image {
    ImageFormat format = 1;
    uint32 width = 2;
    uint32 height = 3;

    // The organization of the pixels in the image buffer is from left to
    // right and bottom up.
    bytes image = 4;
}

message Rotation {
    enum SkinRotation {
        SKIN_ROTATION_0 = 0;
        SKIN_ROTATION_90 = 1;
        SKIN_ROTATION_180 = 2;
        SKIN_ROTATION_270 = 3;
    }
    SkinRotation rotation = 1;
}

message TelephoneOperation {
    enum Operation {
        InitCall = 0;
        AcceptCall = 1;
        RejectCallExplicit = 2;
        RejectCallBusy = 3;
        DisconnectCall = 4;
        PlaceCallOnHold = 5;
        TakeCallOffHold = 6;
    }
    Operation operation = 1;
    string number = 2;
}

message TelephoneResponse {
    enum Response {
        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
    }
    Response response = 1;
}

message Entry {
    string key = 1;
    string value = 2;
}

message EntryList {
    repeated Entry entry = 1;
}

message EmulatorStatus {
    // The emulator version string.
    string version = 1;

    // The time the emulator has been active in .ms
    uint64 uptime = 2;

    // True if the device has completed booting.
    // For P and later this information will accurate,
    // for older images we rely on adb.
    bool booted = 3;

    // The current vm configuration
    VmConfiguration vmConfig = 4;

    // The hardware configuration of the running emulator as
    // key valure pairs.
    EntryList hardwareConfig = 5;
};