Add support for time entities (#6399)

* Add time entities

* Add tests

* Add myself to datetime codeowners

* Fix publishing times with 0 values

* Log performing TimeCall

* Implement `on_time` trigger

* Rename var

* Fix initial value for time

* Add arg name for clarity

* Remove useless checks

esphome/components/api/api.proto

@@ -45,6 +45,7 @@ service APIConnection {
   rpc lock_command (LockCommandRequest) returns (void) {}
   rpc media_player_command (MediaPlayerCommandRequest) returns (void) {}
   rpc date_command (DateCommandRequest) returns (void) {}
+  rpc time_command (TimeCommandRequest) returns (void) {}
 
   rpc subscribe_bluetooth_le_advertisements(SubscribeBluetoothLEAdvertisementsRequest) returns (void) {}
   rpc bluetooth_device_request(BluetoothDeviceRequest) returns (void) {}
@@ -1658,3 +1659,44 @@ message DateCommandRequest {
   uint32 month = 3;
   uint32 day = 4;
 }
+
+// ==================== DATETIME TIME ====================
+message ListEntitiesTimeResponse {
+  option (id) = 103;
+  option (source) = SOURCE_SERVER;
+  option (ifdef) = "USE_DATETIME_TIME";
+
+  string object_id = 1;
+  fixed32 key = 2;
+  string name = 3;
+  string unique_id = 4;
+
+  string icon = 5;
+  bool disabled_by_default = 6;
+  EntityCategory entity_category = 7;
+}
+message TimeStateResponse {
+  option (id) = 104;
+  option (source) = SOURCE_SERVER;
+  option (ifdef) = "USE_DATETIME_TIME";
+  option (no_delay) = true;
+
+  fixed32 key = 1;
+  // If the time does not have a valid state yet.
+  // Equivalent to `!obj->has_state()` - inverse logic to make state packets smaller
+  bool missing_state = 2;
+  uint32 hour = 3;
+  uint32 minute = 4;
+  uint32 second = 5;
+}
+message TimeCommandRequest {
+  option (id) = 105;
+  option (source) = SOURCE_CLIENT;
+  option (ifdef) = "USE_DATETIME_TIME";
+  option (no_delay) = true;
+
+  fixed32 key = 1;
+  uint32 hour = 2;
+  uint32 minute = 3;
+  uint32 second = 4;
+}

esphome/components/api/api_connection.cpp

@@ -735,6 +735,43 @@ void APIConnection::date_command(const DateCommandRequest &msg) {
 }
 #endif
 
+#ifdef USE_DATETIME_TIME
+bool APIConnection::send_time_state(datetime::TimeEntity *time) {
+  if (!this->state_subscription_)
+    return false;
+
+  TimeStateResponse resp{};
+  resp.key = time->get_object_id_hash();
+  resp.missing_state = !time->has_state();
+  resp.hour = time->hour;
+  resp.minute = time->minute;
+  resp.second = time->second;
+  return this->send_time_state_response(resp);
+}
+bool APIConnection::send_time_info(datetime::TimeEntity *time) {
+  ListEntitiesTimeResponse msg;
+  msg.key = time->get_object_id_hash();
+  msg.object_id = time->get_object_id();
+  if (time->has_own_name())
+    msg.name = time->get_name();
+  msg.unique_id = get_default_unique_id("time", time);
+  msg.icon = time->get_icon();
+  msg.disabled_by_default = time->is_disabled_by_default();
+  msg.entity_category = static_cast<enums::EntityCategory>(time->get_entity_category());
+
+  return this->send_list_entities_time_response(msg);
+}
+void APIConnection::time_command(const TimeCommandRequest &msg) {
+  datetime::TimeEntity *time = App.get_time_by_key(msg.key);
+  if (time == nullptr)
+    return;
+
+  auto call = time->make_call();
+  call.set_time(msg.hour, msg.minute, msg.second);
+  call.perform();
+}
+#endif
+
 #ifdef USE_TEXT
 bool APIConnection::send_text_state(text::Text *text, std::string state) {
   if (!this->state_subscription_)

esphome/components/api/api_connection.h

@@ -77,6 +77,11 @@ class APIConnection : public APIServerConnection {
   bool send_date_info(datetime::DateEntity *date);
   void date_command(const DateCommandRequest &msg) override;
 #endif
+#ifdef USE_DATETIME_TIME
+  bool send_time_state(datetime::TimeEntity *time);
+  bool send_time_info(datetime::TimeEntity *time);
+  void time_command(const TimeCommandRequest &msg) override;
+#endif
 #ifdef USE_TEXT
   bool send_text_state(text::Text *text, std::string state);
   bool send_text_info(text::Text *text);

esphome/components/api/api_pb2.cpp

@@ -7476,6 +7476,225 @@ void DateCommandRequest::dump_to(std::string &out) const {
   out.append("}");
 }
 #endif
+bool ListEntitiesTimeResponse::decode_varint(uint32_t field_id, ProtoVarInt value) {
+  switch (field_id) {
+    case 6: {
+      this->disabled_by_default = value.as_bool();
+      return true;
+    }
+    case 7: {
+      this->entity_category = value.as_enum<enums::EntityCategory>();
+      return true;
+    }
+    default:
+      return false;
+  }
+}
+bool ListEntitiesTimeResponse::decode_length(uint32_t field_id, ProtoLengthDelimited value) {
+  switch (field_id) {
+    case 1: {
+      this->object_id = value.as_string();
+      return true;
+    }
+    case 3: {
+      this->name = value.as_string();
+      return true;
+    }
+    case 4: {
+      this->unique_id = value.as_string();
+      return true;
+    }
+    case 5: {
+      this->icon = value.as_string();
+      return true;
+    }
+    default:
+      return false;
+  }
+}
+bool ListEntitiesTimeResponse::decode_32bit(uint32_t field_id, Proto32Bit value) {
+  switch (field_id) {
+    case 2: {
+      this->key = value.as_fixed32();
+      return true;
+    }
+    default:
+      return false;
+  }
+}
+void ListEntitiesTimeResponse::encode(ProtoWriteBuffer buffer) const {
+  buffer.encode_string(1, this->object_id);
+  buffer.encode_fixed32(2, this->key);
+  buffer.encode_string(3, this->name);
+  buffer.encode_string(4, this->unique_id);
+  buffer.encode_string(5, this->icon);
+  buffer.encode_bool(6, this->disabled_by_default);
+  buffer.encode_enum<enums::EntityCategory>(7, this->entity_category);
+}
+#ifdef HAS_PROTO_MESSAGE_DUMP
+void ListEntitiesTimeResponse::dump_to(std::string &out) const {
+  __attribute__((unused)) char buffer[64];
+  out.append("ListEntitiesTimeResponse {\n");
+  out.append("  object_id: ");
+  out.append("'").append(this->object_id).append("'");
+  out.append("\n");
+
+  out.append("  key: ");
+  sprintf(buffer, "%" PRIu32, this->key);
+  out.append(buffer);
+  out.append("\n");
+
+  out.append("  name: ");
+  out.append("'").append(this->name).append("'");
+  out.append("\n");
+
+  out.append("  unique_id: ");
+  out.append("'").append(this->unique_id).append("'");
+  out.append("\n");
+
+  out.append("  icon: ");
+  out.append("'").append(this->icon).append("'");
+  out.append("\n");
+
+  out.append("  disabled_by_default: ");
+  out.append(YESNO(this->disabled_by_default));
+  out.append("\n");
+
+  out.append("  entity_category: ");
+  out.append(proto_enum_to_string<enums::EntityCategory>(this->entity_category));
+  out.append("\n");
+  out.append("}");
+}
+#endif
+bool TimeStateResponse::decode_varint(uint32_t field_id, ProtoVarInt value) {
+  switch (field_id) {
+    case 2: {
+      this->missing_state = value.as_bool();
+      return true;
+    }
+    case 3: {
+      this->hour = value.as_uint32();
+      return true;
+    }
+    case 4: {
+      this->minute = value.as_uint32();
+      return true;
+    }
+    case 5: {
+      this->second = value.as_uint32();
+      return true;
+    }
+    default:
+      return false;
+  }
+}
+bool TimeStateResponse::decode_32bit(uint32_t field_id, Proto32Bit value) {
+  switch (field_id) {
+    case 1: {
+      this->key = value.as_fixed32();
+      return true;
+    }
+    default:
+      return false;
+  }
+}
+void TimeStateResponse::encode(ProtoWriteBuffer buffer) const {
+  buffer.encode_fixed32(1, this->key);
+  buffer.encode_bool(2, this->missing_state);
+  buffer.encode_uint32(3, this->hour);
+  buffer.encode_uint32(4, this->minute);
+  buffer.encode_uint32(5, this->second);
+}
+#ifdef HAS_PROTO_MESSAGE_DUMP
+void TimeStateResponse::dump_to(std::string &out) const {
+  __attribute__((unused)) char buffer[64];
+  out.append("TimeStateResponse {\n");
+  out.append("  key: ");
+  sprintf(buffer, "%" PRIu32, this->key);
+  out.append(buffer);
+  out.append("\n");
+
+  out.append("  missing_state: ");
+  out.append(YESNO(this->missing_state));
+  out.append("\n");
+
+  out.append("  hour: ");
+  sprintf(buffer, "%" PRIu32, this->hour);
+  out.append(buffer);
+  out.append("\n");
+
+  out.append("  minute: ");
+  sprintf(buffer, "%" PRIu32, this->minute);
+  out.append(buffer);
+  out.append("\n");
+
+  out.append("  second: ");
+  sprintf(buffer, "%" PRIu32, this->second);
+  out.append(buffer);
+  out.append("\n");
+  out.append("}");
+}
+#endif
+bool TimeCommandRequest::decode_varint(uint32_t field_id, ProtoVarInt value) {
+  switch (field_id) {
+    case 2: {
+      this->hour = value.as_uint32();
+      return true;
+    }
+    case 3: {
+      this->minute = value.as_uint32();
+      return true;
+    }
+    case 4: {
+      this->second = value.as_uint32();
+      return true;
+    }
+    default:
+      return false;
+  }
+}
+bool TimeCommandRequest::decode_32bit(uint32_t field_id, Proto32Bit value) {
+  switch (field_id) {
+    case 1: {
+      this->key = value.as_fixed32();
+      return true;
+    }
+    default:
+      return false;
+  }
+}
+void TimeCommandRequest::encode(ProtoWriteBuffer buffer) const {
+  buffer.encode_fixed32(1, this->key);
+  buffer.encode_uint32(2, this->hour);
+  buffer.encode_uint32(3, this->minute);
+  buffer.encode_uint32(4, this->second);
+}
+#ifdef HAS_PROTO_MESSAGE_DUMP
+void TimeCommandRequest::dump_to(std::string &out) const {
+  __attribute__((unused)) char buffer[64];
+  out.append("TimeCommandRequest {\n");
+  out.append("  key: ");
+  sprintf(buffer, "%" PRIu32, this->key);
+  out.append(buffer);
+  out.append("\n");
+
+  out.append("  hour: ");
+  sprintf(buffer, "%" PRIu32, this->hour);
+  out.append(buffer);
+  out.append("\n");
+
+  out.append("  minute: ");
+  sprintf(buffer, "%" PRIu32, this->minute);
+  out.append(buffer);
+  out.append("\n");
+
+  out.append("  second: ");
+  sprintf(buffer, "%" PRIu32, this->second);
+  out.append(buffer);
+  out.append("\n");
+  out.append("}");
+}
+#endif
 
 }  // namespace api
 }  // namespace esphome

esphome/components/api/api_pb2.h

@@ -1919,6 +1919,56 @@ class DateCommandRequest : public ProtoMessage {
   bool decode_32bit(uint32_t field_id, Proto32Bit value) override;
   bool decode_varint(uint32_t field_id, ProtoVarInt value) override;
 };
+class ListEntitiesTimeResponse : public ProtoMessage {
+ public:
+  std::string object_id{};
+  uint32_t key{0};
+  std::string name{};
+  std::string unique_id{};
+  std::string icon{};
+  bool disabled_by_default{false};
+  enums::EntityCategory entity_category{};
+  void encode(ProtoWriteBuffer buffer) const override;
+#ifdef HAS_PROTO_MESSAGE_DUMP
+  void dump_to(std::string &out) const override;
+#endif
+
+ protected:
+  bool decode_32bit(uint32_t field_id, Proto32Bit value) override;
+  bool decode_length(uint32_t field_id, ProtoLengthDelimited value) override;
+  bool decode_varint(uint32_t field_id, ProtoVarInt value) override;
+};
+class TimeStateResponse : public ProtoMessage {
+ public:
+  uint32_t key{0};
+  bool missing_state{false};
+  uint32_t hour{0};
+  uint32_t minute{0};
+  uint32_t second{0};
+  void encode(ProtoWriteBuffer buffer) const override;
+#ifdef HAS_PROTO_MESSAGE_DUMP
+  void dump_to(std::string &out) const override;
+#endif
+
+ protected:
+  bool decode_32bit(uint32_t field_id, Proto32Bit value) override;
+  bool decode_varint(uint32_t field_id, ProtoVarInt value) override;
+};
+class TimeCommandRequest : public ProtoMessage {
+ public:
+  uint32_t key{0};
+  uint32_t hour{0};
+  uint32_t minute{0};
+  uint32_t second{0};
+  void encode(ProtoWriteBuffer buffer) const override;
+#ifdef HAS_PROTO_MESSAGE_DUMP
+  void dump_to(std::string &out) const override;
+#endif
+
+ protected:
+  bool decode_32bit(uint32_t field_id, Proto32Bit value) override;
+  bool decode_varint(uint32_t field_id, ProtoVarInt value) override;
+};
 
 }  // namespace api
 }  // namespace esphome

esphome/components/api/api_pb2_service.cpp

@@ -539,6 +539,24 @@ bool APIServerConnectionBase::send_date_state_response(const DateStateResponse &
 #endif
 #ifdef USE_DATETIME_DATE
 #endif
+#ifdef USE_DATETIME_TIME
+bool APIServerConnectionBase::send_list_entities_time_response(const ListEntitiesTimeResponse &msg) {
+#ifdef HAS_PROTO_MESSAGE_DUMP
+  ESP_LOGVV(TAG, "send_list_entities_time_response: %s", msg.dump().c_str());
+#endif
+  return this->send_message_<ListEntitiesTimeResponse>(msg, 103);
+}
+#endif
+#ifdef USE_DATETIME_TIME
+bool APIServerConnectionBase::send_time_state_response(const TimeStateResponse &msg) {
+#ifdef HAS_PROTO_MESSAGE_DUMP
+  ESP_LOGVV(TAG, "send_time_state_response: %s", msg.dump().c_str());
+#endif
+  return this->send_message_<TimeStateResponse>(msg, 104);
+}
+#endif
+#ifdef USE_DATETIME_TIME
+#endif
 bool APIServerConnectionBase::read_message(uint32_t msg_size, uint32_t msg_type, uint8_t *msg_data) {
   switch (msg_type) {
     case 1: {
@@ -979,6 +997,17 @@ bool APIServerConnectionBase::read_message(uint32_t msg_size, uint32_t msg_type,
       ESP_LOGVV(TAG, "on_date_command_request: %s", msg.dump().c_str());
 #endif
       this->on_date_command_request(msg);
+#endif
+      break;
+    }
+    case 105: {
+#ifdef USE_DATETIME_TIME
+      TimeCommandRequest msg;
+      msg.decode(msg_data, msg_size);
+#ifdef HAS_PROTO_MESSAGE_DUMP
+      ESP_LOGVV(TAG, "on_time_command_request: %s", msg.dump().c_str());
+#endif
+      this->on_time_command_request(msg);
 #endif
       break;
     }
@@ -1279,6 +1308,19 @@ void APIServerConnection::on_date_command_request(const DateCommandRequest &msg)
   this->date_command(msg);
 }
 #endif
+#ifdef USE_DATETIME_TIME
+void APIServerConnection::on_time_command_request(const TimeCommandRequest &msg) {
+  if (!this->is_connection_setup()) {
+    this->on_no_setup_connection();
+    return;
+  }
+  if (!this->is_authenticated()) {
+    this->on_unauthenticated_access();
+    return;
+  }
+  this->time_command(msg);
+}
+#endif
 #ifdef USE_BLUETOOTH_PROXY
 void APIServerConnection::on_subscribe_bluetooth_le_advertisements_request(
     const SubscribeBluetoothLEAdvertisementsRequest &msg) {

esphome/components/api/api_pb2_service.h

@@ -270,6 +270,15 @@ class APIServerConnectionBase : public ProtoService {
 #endif
 #ifdef USE_DATETIME_DATE
   virtual void on_date_command_request(const DateCommandRequest &value){};
+#endif
+#ifdef USE_DATETIME_TIME
+  bool send_list_entities_time_response(const ListEntitiesTimeResponse &msg);
+#endif
+#ifdef USE_DATETIME_TIME
+  bool send_time_state_response(const TimeStateResponse &msg);
+#endif
+#ifdef USE_DATETIME_TIME
+  virtual void on_time_command_request(const TimeCommandRequest &value){};
 #endif
  protected:
   bool read_message(uint32_t msg_size, uint32_t msg_type, uint8_t *msg_data) override;
@@ -328,6 +337,9 @@ class APIServerConnection : public APIServerConnectionBase {
 #ifdef USE_DATETIME_DATE
   virtual void date_command(const DateCommandRequest &msg) = 0;
 #endif
+#ifdef USE_DATETIME_TIME
+  virtual void time_command(const TimeCommandRequest &msg) = 0;
+#endif
 #ifdef USE_BLUETOOTH_PROXY
   virtual void subscribe_bluetooth_le_advertisements(const SubscribeBluetoothLEAdvertisementsRequest &msg) = 0;
 #endif
@@ -417,6 +429,9 @@ class APIServerConnection : public APIServerConnectionBase {
 #ifdef USE_DATETIME_DATE
   void on_date_command_request(const DateCommandRequest &msg) override;
 #endif
+#ifdef USE_DATETIME_TIME
+  void on_time_command_request(const TimeCommandRequest &msg) override;
+#endif
 #ifdef USE_BLUETOOTH_PROXY
   void on_subscribe_bluetooth_le_advertisements_request(const SubscribeBluetoothLEAdvertisementsRequest &msg) override;
 #endif

esphome/components/api/api_server.cpp

@@ -264,6 +264,15 @@ void APIServer::on_date_update(datetime::DateEntity *obj) {
 }
 #endif
 
+#ifdef USE_DATETIME_TIME
+void APIServer::on_time_update(datetime::TimeEntity *obj) {
+  if (obj->is_internal())
+    return;
+  for (auto &c : this->clients_)
+    c->send_time_state(obj);
+}
+#endif
+
 #ifdef USE_TEXT
 void APIServer::on_text_update(text::Text *obj, const std::string &state) {
   if (obj->is_internal())

esphome/components/api/api_server.h

@@ -69,6 +69,9 @@ class APIServer : public Component, public Controller {
 #ifdef USE_DATETIME_DATE
   void on_date_update(datetime::DateEntity *obj) override;
 #endif
+#ifdef USE_DATETIME_TIME
+  void on_time_update(datetime::TimeEntity *obj) override;
+#endif
 #ifdef USE_TEXT
   void on_text_update(text::Text *obj, const std::string &state) override;
 #endif

esphome/components/api/list_entities.cpp

@@ -64,6 +64,10 @@ bool ListEntitiesIterator::on_number(number::Number *number) { return this->clie
 bool ListEntitiesIterator::on_date(datetime::DateEntity *date) { return this->client_->send_date_info(date); }
 #endif
 
+#ifdef USE_DATETIME_TIME
+bool ListEntitiesIterator::on_time(datetime::TimeEntity *time) { return this->client_->send_time_info(time); }
+#endif
+
 #ifdef USE_TEXT
 bool ListEntitiesIterator::on_text(text::Text *text) { return this->client_->send_text_info(text); }
 #endif

esphome/components/api/list_entities.h

@@ -49,6 +49,9 @@ class ListEntitiesIterator : public ComponentIterator {
 #ifdef USE_DATETIME_DATE
   bool on_date(datetime::DateEntity *date) override;
 #endif
+#ifdef USE_DATETIME_TIME
+  bool on_time(datetime::TimeEntity *time) override;
+#endif
 #ifdef USE_TEXT
   bool on_text(text::Text *text) override;
 #endif

esphome/components/api/subscribe_state.cpp

@@ -45,6 +45,9 @@ bool InitialStateIterator::on_number(number::Number *number) {
 #ifdef USE_DATETIME_DATE
 bool InitialStateIterator::on_date(datetime::DateEntity *date) { return this->client_->send_date_state(date); }
 #endif
+#ifdef USE_DATETIME_TIME
+bool InitialStateIterator::on_time(datetime::TimeEntity *time) { return this->client_->send_time_state(time); }
+#endif
 #ifdef USE_TEXT
 bool InitialStateIterator::on_text(text::Text *text) { return this->client_->send_text_state(text, text->state); }
 #endif

esphome/components/api/subscribe_state.h

@@ -46,6 +46,9 @@ class InitialStateIterator : public ComponentIterator {
 #ifdef USE_DATETIME_DATE
   bool on_date(datetime::DateEntity *date) override;
 #endif
+#ifdef USE_DATETIME_TIME
+  bool on_time(datetime::TimeEntity *time) override;
+#endif
 #ifdef USE_TEXT
   bool on_text(text::Text *text) override;
 #endif