esphome/esphome/components/api/api.proto

syntax = "proto3";


// ==================== BASE PACKETS ====================

// The Home Assistant protocol is structured as a simple
// TCP socket with short binary messages encoded in the protocol buffers format
// First, a message in this protocol has a specific format:
//  * VarInt denoting the size of the message object. (type is not part of this)
//  * VarInt denoting the type of message.
//  * The message object encoded as a ProtoBuf message

// The connection is established in 4 steps:
//  * First, the client connects to the server and sends a "Hello Request" identifying itself
//  * The server responds with a "Hello Response" and selects the protocol version
//  * After receiving this message, the client attempts to authenticate itself using
//    the password and a "Connect Request"
//  * The server responds with a "Connect Response" and notifies of invalid password.
// If anything in this initial process fails, the connection must immediately closed
// by both sides and _no_ disconnection message is to be sent.

// Message sent at the beginning of each connection
// Can only be sent by the client and only at the beginning of the connection
// ID: 1
message HelloRequest {
  // Description of client (like User Agent)
  // For example "Home Assistant"
  // Not strictly necessary to send but nice for debugging
  // purposes.
  string client_info = 1;
}

// Confirmation of successful connection request.
// Can only be sent by the server and only at the beginning of the connection
// ID: 2
message HelloResponse {
  // The version of the API to use. The _client_ (for example Home Assistant) needs to check
  // for compatibility and if necessary adopt to an older API.
  // Major is for breaking changes in the base protocol - a mismatch will lead to immediate disconnect_client_
  // Minor is for breaking changes in individual messages - a mismatch will lead to a warning message
  uint32 api_version_major = 1;
  uint32 api_version_minor = 2;

  // A string identifying the server (ESP); like client info this may be empty
  // and only exists for debugging/logging purposes.
  // For example "ESPHome v1.10.0 on ESP8266"
  string server_info = 3;
}

// Message sent at the beginning of each connection to authenticate the client
// Can only be sent by the client and only at the beginning of the connection
// ID: 3
message ConnectRequest {
  // The password to log in with
  string password = 1;
}

// Confirmation of successful connection. After this the connection is available for all traffic.
// Can only be sent by the server and only at the beginning of the connection
// ID: 4
message ConnectResponse {
  bool invalid_password = 1;
}

// Request to close the connection.
// Can be sent by both the client and server
// ID: 5
message DisconnectRequest {
  // Do not close the connection before the acknowledgement arrives
}

// ID: 6
message DisconnectResponse {
  // Empty - Both parties are required to close the connection after this
  // message has been received.
}

// ID: 7
message PingRequest {
  // Empty
}

// ID: 8
message PingResponse {
  // Empty
}

// ID: 9
message DeviceInfoRequest {
  // Empty
}

// ID: 10
message DeviceInfoResponse {
  bool uses_password = 1;

  // The name of the node, given by "App.set_name()"
  string name = 2;

  // The mac address of the device. For example "AC:BC:32:89:0E:A9"
  string mac_address = 3;

  // A string describing the ESPHome version. For example "1.10.0"
  string esphome_core_version = 4;

  // A string describing the date of compilation, this is generated by the compiler
  // and therefore may not be in the same format all the time.
  // If the user isn't using ESPHome, this will also not be set.
  string compilation_time = 5;

  // The model of the board. For example NodeMCU
  string model = 6;

  bool has_deep_sleep = 7;
}

// ID: 11
message ListEntitiesRequest {
  // Empty
}
// ID: 19
message ListEntitiesDoneResponse {
  // Empty
}
// ID: 20
message SubscribeStatesRequest {
  // Empty
}

// ==================== BINARY SENSOR ====================
// ID: 12
message ListEntitiesBinarySensorResponse {
  string object_id = 1;
  fixed32 key = 2;
  string name = 3;
  string unique_id = 4;

  string device_class = 5;
  bool is_status_binary_sensor = 6;
}
// ID: 21
message BinarySensorStateResponse {
  fixed32 key = 1;
  bool state = 2;
}

// ==================== COVER ====================
// ID: 13
message ListEntitiesCoverResponse {
  string object_id = 1;
  fixed32 key = 2;
  string name = 3;
  string unique_id = 4;

  bool assumed_state = 5;
  bool supports_position = 6;
  bool supports_tilt = 7;
  string device_class = 8;
}
// ID: 22
message CoverStateResponse {
  fixed32 key = 1;

  // legacy: state has been removed in 1.13
  // clients/servers must still send/accept it until the next protocol change
  enum LegacyCoverState {
    OPEN = 0;
    CLOSED = 1;
  }
  LegacyCoverState legacy_state = 2;

  float position = 3;
  float tilt = 4;
  enum CoverOperation {
    IDLE = 0;
    IS_OPENING = 1;
    IS_CLOSING = 2;
  }
  CoverOperation current_operation = 5;
}
// ID: 30
message CoverCommandRequest {
  fixed32 key = 1;

  // legacy: command has been removed in 1.13
  // clients/servers must still send/accept it until the next protocol change
  enum LegacyCoverCommand {
    OPEN = 0;
    CLOSE = 1;
    STOP = 2;
  }
  bool has_legacy_command = 2;
  LegacyCoverCommand legacy_command = 3;

  bool has_position = 4;
  float position = 5;
  bool has_tilt = 6;
  float tilt = 7;
  bool stop = 8;
}

// ==================== FAN ====================
// ID: 14
message ListEntitiesFanResponse {
  string object_id = 1;
  fixed32 key = 2;
  string name = 3;
  string unique_id = 4;

  bool supports_oscillation = 5;
  bool supports_speed = 6;
}
enum FanSpeed {
  LOW = 0;
  MEDIUM = 1;
  HIGH = 2;
}
// ID: 23
message FanStateResponse {
  fixed32 key = 1;
  bool state = 2;
  bool oscillating = 3;
  FanSpeed speed = 4;
}
// ID: 31
message FanCommandRequest {
  fixed32 key = 1;
  bool has_state = 2;
  bool state = 3;
  bool has_speed = 4;
  FanSpeed speed = 5;
  bool has_oscillating = 6;
  bool oscillating = 7;
}

// ==================== LIGHT ====================
// ID: 15
message ListEntitiesLightResponse {
  string object_id = 1;
  fixed32 key = 2;
  string name = 3;
  string unique_id = 4;

  bool supports_brightness = 5;
  bool supports_rgb = 6;
  bool supports_white_value = 7;
  bool supports_color_temperature = 8;
  float min_mireds = 9;
  float max_mireds = 10;
  repeated string effects = 11;
}
// ID: 24
message LightStateResponse {
  fixed32 key = 1;
  bool state = 2;
  float brightness = 3;
  float red = 4;
  float green = 5;
  float blue = 6;
  float white = 7;
  float color_temperature = 8;
  string effect = 9;
}
// ID: 32
message LightCommandRequest {
  fixed32 key = 1;
  bool has_state = 2;
  bool state = 3;
  bool has_brightness = 4;
  float brightness = 5;
  bool has_rgb = 6;
  float red = 7;
  float green = 8;
  float blue = 9;
  bool has_white = 10;
  float white = 11;
  bool has_color_temperature = 12;
  float color_temperature = 13;
  bool has_transition_length = 14;
  uint32 transition_length = 15;
  bool has_flash_length = 16;
  uint32 flash_length = 17;
  bool has_effect = 18;
  string effect = 19;
}

// ==================== SENSOR ====================
// ID: 16
message ListEntitiesSensorResponse {
  string object_id = 1;
  fixed32 key = 2;
  string name = 3;
  string unique_id = 4;

  string icon = 5;
  string unit_of_measurement = 6;
  int32 accuracy_decimals = 7;
}
// ID: 25
message SensorStateResponse {
  fixed32 key = 1;
  float state = 2;
}

// ==================== SWITCH ====================
// ID: 17
message ListEntitiesSwitchResponse {
  string object_id = 1;
  fixed32 key = 2;
  string name = 3;
  string unique_id = 4;

  string icon = 5;
  bool assumed_state = 6;
}
// ID: 26
message SwitchStateResponse {
  fixed32 key = 1;
  bool state = 2;
}
// ID: 33
message SwitchCommandRequest {
  fixed32 key = 1;
  bool state = 2;
}

// ==================== TEXT SENSOR ====================
// ID: 18
message ListEntitiesTextSensorResponse {
  string object_id = 1;
  fixed32 key = 2;
  string name = 3;
  string unique_id = 4;

  string icon = 5;
}
// ID: 27
message TextSensorStateResponse {
  fixed32 key = 1;
  string state = 2;
}

// ==================== SUBSCRIBE LOGS ====================
enum LogLevel {
  NONE = 0;
  ERROR = 1;
  WARN = 2;
  INFO = 3;
  DEBUG = 4;
  VERBOSE = 5;
  VERY_VERBOSE = 6;
}
// ID: 28
message SubscribeLogsRequest {
  LogLevel level = 1;
  bool dump_config = 2;
}
// ID: 29
message SubscribeLogsResponse {
  LogLevel level = 1;
  string tag = 2;
  string message = 3;
  bool send_failed = 4;
}

// ==================== HOMEASSISTANT.SERVICE ====================
// ID: 34
message SubscribeServiceCallsRequest {

}

// ID: 35
message ServiceCallResponse {
  string service = 1;
  map<string, string> data = 2;
  map<string, string> data_template = 3;
  map<string, string> variables = 4;
}

// ==================== IMPORT HOME ASSISTANT STATES ====================
// 1. Client sends SubscribeHomeAssistantStatesRequest
// 2. Server responds with zero or more SubscribeHomeAssistantStateResponse (async)
// 3. Client sends HomeAssistantStateResponse for state changes.
// ID: 38
message SubscribeHomeAssistantStatesRequest {

}

// ID: 39
message SubscribeHomeAssistantStateResponse {
  string entity_id = 1;
}

// ID: 40
message HomeAssistantStateResponse {
  string entity_id = 1;
  string state = 2;
}

// ==================== IMPORT TIME ====================
// ID: 36
message GetTimeRequest {

}

// ID: 37
message GetTimeResponse {
  fixed32 epoch_seconds = 1;
}

// ==================== USER-DEFINES SERVICES ====================
message ListEntitiesServicesArgument {
  string name = 1;
  enum Type {
    BOOL = 0;
    INT = 1;
    FLOAT = 2;
    STRING = 3;
  }
  Type type = 2;
}
// ID: 41
message ListEntitiesServicesResponse {
  string name = 1;
  fixed32 key = 2;
  repeated ListEntitiesServicesArgument args = 3;
}
message ExecuteServiceArgument {
  bool bool_ = 1;
  int32 int_ = 2;
  float float_ = 3;
  string string_ = 4;
}
// ID: 42
message ExecuteServiceRequest {
  fixed32 key = 1;
  repeated ExecuteServiceArgument args = 2;
}

// ==================== CAMERA ====================
// ID: 43
message ListEntitiesCameraResponse {
  string object_id = 1;
  fixed32 key = 2;
  string name = 3;
  string unique_id = 4;
}

// ID: 44
message CameraImageResponse {
  fixed32 key = 1;
  bytes data = 2;
  bool done = 3;
}
// ID: 45
message CameraImageRequest {
  bool single = 1;
  bool stream = 2;
}

// ==================== CLIMATE ====================
enum ClimateMode {
  OFF = 0;
  AUTO = 1;
  COOL = 2;
  HEAT = 3;
}
// ID: 46
message ListEntitiesClimateResponse {
  string object_id = 1;
  fixed32 key = 2;
  string name = 3;
  string unique_id = 4;

  bool supports_current_temperature = 5;
  bool supports_two_point_target_temperature = 6;
  repeated ClimateMode supported_modes = 7;
  float visual_min_temperature = 8;
  float visual_max_temperature = 9;
  float visual_temperature_step = 10;
  bool supports_away = 11;
}
// ID: 47
message ClimateStateResponse {
  fixed32 key = 1;
  ClimateMode mode = 2;
  float current_temperature = 3;
  float target_temperature = 4;
  float target_temperature_low = 5;
  float target_temperature_high = 6;
  bool away = 7;
}
// ID: 48
message ClimateCommandRequest {
  fixed32 key = 1;
  bool has_mode = 2;
  ClimateMode mode = 3;
  bool has_target_temperature = 4;
  float target_temperature = 5;
  bool has_target_temperature_low = 6;
  float target_temperature_low = 7;
  bool has_target_temperature_high = 8;
  float target_temperature_high = 9;
  bool has_away = 10;
  bool away = 11;
}