android/android-grpc/android/emulation/control/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 = "android.emulation.control";
option java_outer_classname = "";
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 sendTouch(TouchEvent) returns (google.protobuf.Empty) {}
    rpc sendKey(KeyboardEvent) returns (google.protobuf.Empty) {}
    rpc sendMouse(MouseEvent) returns (google.protobuf.Empty) {}
    rpc sendRotary(RotaryEvent) returns (google.protobuf.Empty) {}

    rpc getVmConfiguration(google.protobuf.Empty) returns (VmConfiguration) {}

    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;
}

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

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

message RotaryEvent {
    int32 delta = 1;
}

message MouseEvent {
    int32 x = 1;
    int32 y = 2;
    int32 buttons = 3;
}

// 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 TouchEvent {
    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;
}