esphome/esphome/api/api.proto

syntax = "proto3";

// 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
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
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
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
message ConnectResponse {
  bool invalid_password = 1;
}

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

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

message PingRequest {
  // Empty
}

message PingResponse {
  // Empty
}

message DeviceInfoRequest {
  // Empty
}

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

message ListEntitiesRequest {
  // Empty
}

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;
}
message ListEntitiesCoverResponse {
  string object_id = 1;
  fixed32 key = 2;
  string name = 3;
  string unique_id = 4;

  bool is_optimistic = 5;
}
message ListEntitiesFanResponse {
  string object_id = 1;
  fixed32 key = 2;
  string name = 3;
  string unique_id = 4;

  bool supports_oscillation = 5;
  bool supports_speed = 6;
}
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;
}
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;
}
message ListEntitiesSwitchResponse {
  string object_id = 1;
  fixed32 key = 2;
  string name = 3;
  string unique_id = 4;

  string icon = 5;
  bool optimistic = 6;
}
message ListEntitiesTextSensorResponse {
  string object_id = 1;
  fixed32 key = 2;
  string name = 3;
  string unique_id = 4;

  string icon = 5;
}
message ListEntitiesDoneResponse {
  // Empty
}

message SubscribeStatesRequest {
  // Empty
}
message BinarySensorStateResponse {
  fixed32 key = 1;
  bool state = 2;
}
message CoverStateResponse {
  fixed32 key = 1;
  enum CoverState {
    OPEN = 0;
    CLOSED = 1;
  }
  CoverState state = 2;
}
enum FanSpeed {
  LOW = 0;
  MEDIUM = 1;
  HIGH = 2;
}
message FanStateResponse {
  fixed32 key = 1;
  bool state = 2;
  bool oscillating = 3;
  FanSpeed speed = 4;
}
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;
}
message SensorStateResponse {
  fixed32 key = 1;
  float state = 2;
}
message SwitchStateResponse {
  fixed32 key = 1;
  bool state = 2;
}
message TextSensorStateResponse {
  fixed32 key = 1;
  string state = 2;
}

message CoverCommandRequest {
  fixed32 key = 1;
  enum CoverCommand {
    OPEN = 0;
    CLOSE = 1;
    STOP = 2;
  }
  bool has_state = 2;
  CoverCommand command = 3;
}
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;
}
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;
}
message SwitchCommandRequest {
  fixed32 key = 1;
  bool state = 2;
}

enum LogLevel {
  NONE = 0;
  ERROR = 1;
  WARN = 2;
  INFO = 3;
  DEBUG = 4;
  VERBOSE = 5;
  VERY_VERBOSE = 6;
}

message SubscribeLogsRequest {
  LogLevel level = 1;
  bool dump_config = 2;
}

message SubscribeLogsResponse {
  LogLevel level = 1;
  string tag = 2;
  string message = 3;
  bool send_failed = 4;
}

message SubscribeServiceCallsRequest {

}

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

// 1. Client sends SubscribeHomeAssistantStatesRequest
// 2. Server responds with zero or more SubscribeHomeAssistantStateResponse (async)
// 3. Client sends HomeAssistantStateResponse for state changes.
message SubscribeHomeAssistantStatesRequest {

}

message SubscribeHomeAssistantStateResponse {
  string entity_id = 1;
}

message HomeAssistantStateResponse {
  string entity_id = 1;
  string state = 2;
}

message GetTimeRequest {

}

message GetTimeResponse {
  fixed32 epoch_seconds = 1;
}