Add datetime date entities (#6191)

Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>

CODEOWNERS

@@ -84,6 +84,7 @@ esphome/components/dac7678/* @NickB1
 esphome/components/daikin_brc/* @hagak
 esphome/components/daly_bms/* @s1lvi0
 esphome/components/dashboard_import/* @esphome/core
+esphome/components/datetime/* @rfdarter
 esphome/components/debug/* @OttoWinter
 esphome/components/delonghi/* @grob6000
 esphome/components/dfplayer/* @glmnet
@@ -338,6 +339,7 @@ esphome/components/tcl112/* @glmnet
 esphome/components/tee501/* @Stock-M
 esphome/components/teleinfo/* @0hax
 esphome/components/template/alarm_control_panel/* @grahambrown11 @hwstar
+esphome/components/template/datetime/* @rfdarter
 esphome/components/text/* @mauritskorse
 esphome/components/thermostat/* @kbx81
 esphome/components/time/* @OttoWinter

esphome/codegen.py

@@ -87,4 +87,5 @@ from esphome.cpp_types import (  # noqa
     gpio_Flags,
     EntityCategory,
     Parented,
+    ESPTime,
 )

esphome/components/api/api.proto

@@ -44,6 +44,7 @@ service APIConnection {
   rpc button_command (ButtonCommandRequest) returns (void) {}
   rpc lock_command (LockCommandRequest) returns (void) {}
   rpc media_player_command (MediaPlayerCommandRequest) returns (void) {}
+  rpc date_command (DateCommandRequest) returns (void) {}
 
   rpc subscribe_bluetooth_le_advertisements(SubscribeBluetoothLEAdvertisementsRequest) returns (void) {}
   rpc bluetooth_device_request(BluetoothDeviceRequest) returns (void) {}
@@ -1598,3 +1599,45 @@ message TextCommandRequest {
   fixed32 key = 1;
   string state = 2;
 }
+
+
+// ==================== DATETIME DATE ====================
+message ListEntitiesDateResponse {
+  option (id) = 100;
+  option (source) = SOURCE_SERVER;
+  option (ifdef) = "USE_DATETIME_DATE";
+
+  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 DateStateResponse {
+  option (id) = 101;
+  option (source) = SOURCE_SERVER;
+  option (ifdef) = "USE_DATETIME_DATE";
+  option (no_delay) = true;
+
+  fixed32 key = 1;
+  // If the date does not have a valid state yet.
+  // Equivalent to `!obj->has_state()` - inverse logic to make state packets smaller
+  bool missing_state = 2;
+  uint32 year = 3;
+  uint32 month = 4;
+  uint32 day = 5;
+}
+message DateCommandRequest {
+  option (id) = 102;
+  option (source) = SOURCE_CLIENT;
+  option (ifdef) = "USE_DATETIME_DATE";
+  option (no_delay) = true;
+
+  fixed32 key = 1;
+  uint32 year = 2;
+  uint32 month = 3;
+  uint32 day = 4;
+}

esphome/components/api/api_connection.cpp

@@ -698,6 +698,43 @@ void APIConnection::number_command(const NumberCommandRequest &msg) {
 }
 #endif
 
+#ifdef USE_DATETIME_DATE
+bool APIConnection::send_date_state(datetime::DateEntity *date) {
+  if (!this->state_subscription_)
+    return false;
+
+  DateStateResponse resp{};
+  resp.key = date->get_object_id_hash();
+  resp.missing_state = !date->has_state();
+  resp.year = date->year;
+  resp.month = date->month;
+  resp.day = date->day;
+  return this->send_date_state_response(resp);
+}
+bool APIConnection::send_date_info(datetime::DateEntity *date) {
+  ListEntitiesDateResponse msg;
+  msg.key = date->get_object_id_hash();
+  msg.object_id = date->get_object_id();
+  if (date->has_own_name())
+    msg.name = date->get_name();
+  msg.unique_id = get_default_unique_id("date", date);
+  msg.icon = date->get_icon();
+  msg.disabled_by_default = date->is_disabled_by_default();
+  msg.entity_category = static_cast<enums::EntityCategory>(date->get_entity_category());
+
+  return this->send_list_entities_date_response(msg);
+}
+void APIConnection::date_command(const DateCommandRequest &msg) {
+  datetime::DateEntity *date = App.get_date_by_key(msg.key);
+  if (date == nullptr)
+    return;
+
+  auto call = date->make_call();
+  call.set_date(msg.year, msg.month, msg.day);
+  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

@@ -72,6 +72,11 @@ class APIConnection : public APIServerConnection {
   bool send_number_info(number::Number *number);
   void number_command(const NumberCommandRequest &msg) override;
 #endif
+#ifdef USE_DATETIME_DATE
+  bool send_date_state(datetime::DateEntity *date);
+  bool send_date_info(datetime::DateEntity *date);
+  void date_command(const DateCommandRequest &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

@@ -7184,6 +7184,225 @@ void TextCommandRequest::dump_to(std::string &out) const {
   out.append("}");
 }
 #endif
+bool ListEntitiesDateResponse::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 ListEntitiesDateResponse::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 ListEntitiesDateResponse::decode_32bit(uint32_t field_id, Proto32Bit value) {
+  switch (field_id) {
+    case 2: {
+      this->key = value.as_fixed32();
+      return true;
+    }
+    default:
+      return false;
+  }
+}
+void ListEntitiesDateResponse::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 ListEntitiesDateResponse::dump_to(std::string &out) const {
+  __attribute__((unused)) char buffer[64];
+  out.append("ListEntitiesDateResponse {\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 DateStateResponse::decode_varint(uint32_t field_id, ProtoVarInt value) {
+  switch (field_id) {
+    case 2: {
+      this->missing_state = value.as_bool();
+      return true;
+    }
+    case 3: {
+      this->year = value.as_uint32();
+      return true;
+    }
+    case 4: {
+      this->month = value.as_uint32();
+      return true;
+    }
+    case 5: {
+      this->day = value.as_uint32();
+      return true;
+    }
+    default:
+      return false;
+  }
+}
+bool DateStateResponse::decode_32bit(uint32_t field_id, Proto32Bit value) {
+  switch (field_id) {
+    case 1: {
+      this->key = value.as_fixed32();
+      return true;
+    }
+    default:
+      return false;
+  }
+}
+void DateStateResponse::encode(ProtoWriteBuffer buffer) const {
+  buffer.encode_fixed32(1, this->key);
+  buffer.encode_bool(2, this->missing_state);
+  buffer.encode_uint32(3, this->year);
+  buffer.encode_uint32(4, this->month);
+  buffer.encode_uint32(5, this->day);
+}
+#ifdef HAS_PROTO_MESSAGE_DUMP
+void DateStateResponse::dump_to(std::string &out) const {
+  __attribute__((unused)) char buffer[64];
+  out.append("DateStateResponse {\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("  year: ");
+  sprintf(buffer, "%" PRIu32, this->year);
+  out.append(buffer);
+  out.append("\n");
+
+  out.append("  month: ");
+  sprintf(buffer, "%" PRIu32, this->month);
+  out.append(buffer);
+  out.append("\n");
+
+  out.append("  day: ");
+  sprintf(buffer, "%" PRIu32, this->day);
+  out.append(buffer);
+  out.append("\n");
+  out.append("}");
+}
+#endif
+bool DateCommandRequest::decode_varint(uint32_t field_id, ProtoVarInt value) {
+  switch (field_id) {
+    case 2: {
+      this->year = value.as_uint32();
+      return true;
+    }
+    case 3: {
+      this->month = value.as_uint32();
+      return true;
+    }
+    case 4: {
+      this->day = value.as_uint32();
+      return true;
+    }
+    default:
+      return false;
+  }
+}
+bool DateCommandRequest::decode_32bit(uint32_t field_id, Proto32Bit value) {
+  switch (field_id) {
+    case 1: {
+      this->key = value.as_fixed32();
+      return true;
+    }
+    default:
+      return false;
+  }
+}
+void DateCommandRequest::encode(ProtoWriteBuffer buffer) const {
+  buffer.encode_fixed32(1, this->key);
+  buffer.encode_uint32(2, this->year);
+  buffer.encode_uint32(3, this->month);
+  buffer.encode_uint32(4, this->day);
+}
+#ifdef HAS_PROTO_MESSAGE_DUMP
+void DateCommandRequest::dump_to(std::string &out) const {
+  __attribute__((unused)) char buffer[64];
+  out.append("DateCommandRequest {\n");
+  out.append("  key: ");
+  sprintf(buffer, "%" PRIu32, this->key);
+  out.append(buffer);
+  out.append("\n");
+
+  out.append("  year: ");
+  sprintf(buffer, "%" PRIu32, this->year);
+  out.append(buffer);
+  out.append("\n");
+
+  out.append("  month: ");
+  sprintf(buffer, "%" PRIu32, this->month);
+  out.append(buffer);
+  out.append("\n");
+
+  out.append("  day: ");
+  sprintf(buffer, "%" PRIu32, this->day);
+  out.append(buffer);
+  out.append("\n");
+  out.append("}");
+}
+#endif
 
 }  // namespace api
 }  // namespace esphome

esphome/components/api/api_pb2.h

@@ -1850,6 +1850,56 @@ class TextCommandRequest : public ProtoMessage {
   bool decode_32bit(uint32_t field_id, Proto32Bit value) override;
   bool decode_length(uint32_t field_id, ProtoLengthDelimited value) override;
 };
+class ListEntitiesDateResponse : 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 DateStateResponse : public ProtoMessage {
+ public:
+  uint32_t key{0};
+  bool missing_state{false};
+  uint32_t year{0};
+  uint32_t month{0};
+  uint32_t day{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 DateCommandRequest : public ProtoMessage {
+ public:
+  uint32_t key{0};
+  uint32_t year{0};
+  uint32_t month{0};
+  uint32_t day{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

@@ -513,6 +513,24 @@ bool APIServerConnectionBase::send_text_state_response(const TextStateResponse &
 #endif
 #ifdef USE_TEXT
 #endif
+#ifdef USE_DATETIME_DATE
+bool APIServerConnectionBase::send_list_entities_date_response(const ListEntitiesDateResponse &msg) {
+#ifdef HAS_PROTO_MESSAGE_DUMP
+  ESP_LOGVV(TAG, "send_list_entities_date_response: %s", msg.dump().c_str());
+#endif
+  return this->send_message_<ListEntitiesDateResponse>(msg, 100);
+}
+#endif
+#ifdef USE_DATETIME_DATE
+bool APIServerConnectionBase::send_date_state_response(const DateStateResponse &msg) {
+#ifdef HAS_PROTO_MESSAGE_DUMP
+  ESP_LOGVV(TAG, "send_date_state_response: %s", msg.dump().c_str());
+#endif
+  return this->send_message_<DateStateResponse>(msg, 101);
+}
+#endif
+#ifdef USE_DATETIME_DATE
+#endif
 bool APIServerConnectionBase::read_message(uint32_t msg_size, uint32_t msg_type, uint8_t *msg_data) {
   switch (msg_type) {
     case 1: {
@@ -942,6 +960,17 @@ bool APIServerConnectionBase::read_message(uint32_t msg_size, uint32_t msg_type,
       ESP_LOGVV(TAG, "on_text_command_request: %s", msg.dump().c_str());
 #endif
       this->on_text_command_request(msg);
+#endif
+      break;
+    }
+    case 102: {
+#ifdef USE_DATETIME_DATE
+      DateCommandRequest msg;
+      msg.decode(msg_data, msg_size);
+#ifdef HAS_PROTO_MESSAGE_DUMP
+      ESP_LOGVV(TAG, "on_date_command_request: %s", msg.dump().c_str());
+#endif
+      this->on_date_command_request(msg);
 #endif
       break;
     }
@@ -1218,6 +1247,19 @@ void APIServerConnection::on_media_player_command_request(const MediaPlayerComma
   this->media_player_command(msg);
 }
 #endif
+#ifdef USE_DATETIME_DATE
+void APIServerConnection::on_date_command_request(const DateCommandRequest &msg) {
+  if (!this->is_connection_setup()) {
+    this->on_no_setup_connection();
+    return;
+  }
+  if (!this->is_authenticated()) {
+    this->on_unauthenticated_access();
+    return;
+  }
+  this->date_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

@@ -257,6 +257,15 @@ class APIServerConnectionBase : public ProtoService {
 #endif
 #ifdef USE_TEXT
   virtual void on_text_command_request(const TextCommandRequest &value){};
+#endif
+#ifdef USE_DATETIME_DATE
+  bool send_list_entities_date_response(const ListEntitiesDateResponse &msg);
+#endif
+#ifdef USE_DATETIME_DATE
+  bool send_date_state_response(const DateStateResponse &msg);
+#endif
+#ifdef USE_DATETIME_DATE
+  virtual void on_date_command_request(const DateCommandRequest &value){};
 #endif
  protected:
   bool read_message(uint32_t msg_size, uint32_t msg_type, uint8_t *msg_data) override;
@@ -312,6 +321,9 @@ class APIServerConnection : public APIServerConnectionBase {
 #ifdef USE_MEDIA_PLAYER
   virtual void media_player_command(const MediaPlayerCommandRequest &msg) = 0;
 #endif
+#ifdef USE_DATETIME_DATE
+  virtual void date_command(const DateCommandRequest &msg) = 0;
+#endif
 #ifdef USE_BLUETOOTH_PROXY
   virtual void subscribe_bluetooth_le_advertisements(const SubscribeBluetoothLEAdvertisementsRequest &msg) = 0;
 #endif
@@ -398,6 +410,9 @@ class APIServerConnection : public APIServerConnectionBase {
 #ifdef USE_MEDIA_PLAYER
   void on_media_player_command_request(const MediaPlayerCommandRequest &msg) override;
 #endif
+#ifdef USE_DATETIME_DATE
+  void on_date_command_request(const DateCommandRequest &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

@@ -255,6 +255,15 @@ void APIServer::on_number_update(number::Number *obj, float state) {
 }
 #endif
 
+#ifdef USE_DATETIME_DATE
+void APIServer::on_date_update(datetime::DateEntity *obj) {
+  if (obj->is_internal())
+    return;
+  for (auto &c : this->clients_)
+    c->send_date_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

@@ -66,6 +66,9 @@ class APIServer : public Component, public Controller {
 #ifdef USE_NUMBER
   void on_number_update(number::Number *obj, float state) override;
 #endif
+#ifdef USE_DATETIME_DATE
+  void on_date_update(datetime::DateEntity *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

@@ -1,8 +1,8 @@
 #include "list_entities.h"
-#include "esphome/core/util.h"
-#include "esphome/core/log.h"
-#include "esphome/core/application.h"
 #include "api_connection.h"
+#include "esphome/core/application.h"
+#include "esphome/core/log.h"
+#include "esphome/core/util.h"
 
 namespace esphome {
 namespace api {
@@ -60,6 +60,10 @@ bool ListEntitiesIterator::on_climate(climate::Climate *climate) { return this->
 bool ListEntitiesIterator::on_number(number::Number *number) { return this->client_->send_number_info(number); }
 #endif
 
+#ifdef USE_DATETIME_DATE
+bool ListEntitiesIterator::on_date(datetime::DateEntity *date) { return this->client_->send_date_info(date); }
+#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

@@ -46,6 +46,9 @@ class ListEntitiesIterator : public ComponentIterator {
 #ifdef USE_NUMBER
   bool on_number(number::Number *number) override;
 #endif
+#ifdef USE_DATETIME_DATE
+  bool on_date(datetime::DateEntity *date) override;
+#endif
 #ifdef USE_TEXT
   bool on_text(text::Text *text) override;
 #endif

esphome/components/api/subscribe_state.cpp

@@ -42,6 +42,9 @@ bool InitialStateIterator::on_number(number::Number *number) {
   return this->client_->send_number_state(number, number->state);
 }
 #endif
+#ifdef USE_DATETIME_DATE
+bool InitialStateIterator::on_date(datetime::DateEntity *date) { return this->client_->send_date_state(date); }
+#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

@@ -43,6 +43,9 @@ class InitialStateIterator : public ComponentIterator {
 #ifdef USE_NUMBER
   bool on_number(number::Number *number) override;
 #endif
+#ifdef USE_DATETIME_DATE
+  bool on_date(datetime::DateEntity *date) override;
+#endif
 #ifdef USE_TEXT
   bool on_text(text::Text *text) override;
 #endif

esphome/components/datetime/__init__.py

@@ -0,0 +1,146 @@
+import esphome.codegen as cg
+
+# import cpp_generator as cpp
+import esphome.config_validation as cv
+from esphome import automation
+from esphome.components import mqtt
+from esphome.const import (
+    CONF_ID,
+    CONF_ON_VALUE,
+    CONF_TRIGGER_ID,
+    CONF_TYPE,
+    CONF_MQTT_ID,
+    CONF_DATE,
+    CONF_YEAR,
+    CONF_MONTH,
+    CONF_DAY,
+)
+from esphome.core import CORE, coroutine_with_priority
+from esphome.cpp_generator import MockObjClass
+from esphome.cpp_helpers import setup_entity
+
+
+CODEOWNERS = ["@rfdarter"]
+
+IS_PLATFORM_COMPONENT = True
+
+datetime_ns = cg.esphome_ns.namespace("datetime")
+DateTimeBase = datetime_ns.class_("DateTimeBase", cg.EntityBase)
+DateEntity = datetime_ns.class_("DateEntity", DateTimeBase)
+
+# Actions
+DateSetAction = datetime_ns.class_("DateSetAction", automation.Action)
+
+DateTimeStateTrigger = datetime_ns.class_(
+    "DateTimeStateTrigger", automation.Trigger.template(cg.ESPTime)
+)
+
+DATETIME_MODES = [
+    "DATE",
+    "TIME",
+    "DATETIME",
+]
+
+
+_DATETIME_SCHEMA = cv.Schema(
+    {
+        cv.OnlyWith(CONF_MQTT_ID, "mqtt"): cv.declare_id(mqtt.MQTTDatetimeComponent),
+        cv.Optional(CONF_ON_VALUE): automation.validate_automation(
+            {
+                cv.GenerateID(CONF_TRIGGER_ID): cv.declare_id(DateTimeStateTrigger),
+            }
+        ),
+    }
+).extend(cv.ENTITY_BASE_SCHEMA.extend(cv.MQTT_COMMAND_COMPONENT_SCHEMA))
+
+
+def date_schema(class_: MockObjClass) -> cv.Schema:
+    schema = {
+        cv.GenerateID(): cv.declare_id(class_),
+        cv.Optional(CONF_TYPE, default="DATE"): cv.one_of("DATE", upper=True),
+    }
+    return _DATETIME_SCHEMA.extend(schema)
+
+
+def time_schema(class_: MockObjClass) -> cv.Schema:
+    schema = {
+        cv.GenerateID(): cv.declare_id(class_),
+        cv.Optional(CONF_TYPE, default="TIME"): cv.one_of("TIME", upper=True),
+    }
+    return _DATETIME_SCHEMA.extend(schema)
+
+
+def datetime_schema(class_: MockObjClass) -> cv.Schema:
+    schema = {
+        cv.GenerateID(): cv.declare_id(class_),
+        cv.Optional(CONF_TYPE, default="DATETIME"): cv.one_of("DATETIME", upper=True),
+    }
+    return _DATETIME_SCHEMA.extend(schema)
+
+
+async def setup_datetime_core_(var, config):
+    await setup_entity(var, config)
+
+    if CONF_MQTT_ID in config:
+        mqtt_ = cg.new_Pvariable(config[CONF_MQTT_ID], var)
+        await mqtt.register_mqtt_component(mqtt_, config)
+    for conf in config.get(CONF_ON_VALUE, []):
+        trigger = cg.new_Pvariable(conf[CONF_TRIGGER_ID], var)
+        await automation.build_automation(trigger, [(cg.ESPTime, "x")], conf)
+
+
+async def register_datetime(var, config):
+    if not CORE.has_id(config[CONF_ID]):
+        var = cg.Pvariable(config[CONF_ID], var)
+    cg.add(getattr(cg.App, f"register_{config[CONF_TYPE].lower()}")(var))
+    await setup_datetime_core_(var, config)
+    cg.add_define(f"USE_DATETIME_{config[CONF_TYPE]}")
+
+
+async def new_datetime(config, *args):
+    var = cg.new_Pvariable(config[CONF_ID], *args)
+    await register_datetime(var, config)
+    return var
+
+
+@coroutine_with_priority(40.0)
+async def to_code(config):
+    cg.add_define("USE_DATETIME")
+    cg.add_global(datetime_ns.using)
+
+
+OPERATION_BASE_SCHEMA = cv.Schema(
+    {
+        cv.Required(CONF_ID): cv.use_id(DateEntity),
+    }
+)
+
+
+@automation.register_action(
+    "datetime.date.set",
+    DateSetAction,
+    OPERATION_BASE_SCHEMA.extend(
+        {
+            cv.Required(CONF_DATE): cv.Any(
+                cv.returning_lambda, cv.date_time(allowed_time=False)
+            ),
+        }
+    ),
+)
+async def datetime_date_set_to_code(config, action_id, template_arg, args):
+    action_var = cg.new_Pvariable(action_id, template_arg)
+    await cg.register_parented(action_var, config[CONF_ID])
+
+    date = config[CONF_DATE]
+    if cg.is_template(date):
+        template_ = await cg.templatable(config[CONF_DATE], [], cg.ESPTime)
+        cg.add(action_var.set_date(template_))
+    else:
+        date_struct = cg.StructInitializer(
+            cg.ESPTime,
+            ("day_of_month", date[CONF_DAY]),
+            ("month", date[CONF_MONTH]),
+            ("year", date[CONF_YEAR]),
+        )
+        cg.add(action_var.set_date(date_struct))
+    return action_var

esphome/components/datetime/date_entity.cpp

@@ -0,0 +1,117 @@
+#include "date_entity.h"
+
+#ifdef USE_DATETIME_DATE
+
+#include "esphome/core/log.h"
+
+namespace esphome {
+namespace datetime {
+
+static const char *const TAG = "datetime.date_entity";
+
+void DateEntity::publish_state() {
+  if (this->year_ == 0 || this->month_ == 0 || this->day_ == 0) {
+    this->has_state_ = false;
+    return;
+  }
+  if (this->year_ < 1970 || this->year_ > 3000) {
+    this->has_state_ = false;
+    ESP_LOGE(TAG, "Year must be between 1970 and 3000");
+    return;
+  }
+  if (this->month_ < 1 || this->month_ > 12) {
+    this->has_state_ = false;
+    ESP_LOGE(TAG, "Month must be between 1 and 12");
+    return;
+  }
+  if (this->day_ > days_in_month(this->month_, this->year_)) {
+    this->has_state_ = false;
+    ESP_LOGE(TAG, "Day must be between 1 and %d for month %d", days_in_month(this->month_, this->year_), this->month_);
+    return;
+  }
+  this->has_state_ = true;
+  ESP_LOGD(TAG, "'%s': Sending date %d-%d-%d", this->get_name().c_str(), this->year_, this->month_, this->day_);
+  this->state_callback_.call();
+}
+
+DateCall DateEntity::make_call() { return DateCall(this); }
+
+void DateCall::validate_() {
+  if (this->year_.has_value() && (this->year_ < 1970 || this->year_ > 3000)) {
+    ESP_LOGE(TAG, "Year must be between 1970 and 3000");
+    this->year_.reset();
+  }
+  if (this->month_.has_value() && (this->month_ < 1 || this->month_ > 12)) {
+    ESP_LOGE(TAG, "Month must be between 1 and 12");
+    this->month_.reset();
+  }
+  if (this->day_.has_value()) {
+    uint16_t year = 0;
+    uint8_t month = 0;
+    if (this->month_.has_value()) {
+      month = *this->month_;
+    } else {
+      if (this->parent_->month != 0) {
+        month = this->parent_->month;
+      } else {
+        ESP_LOGE(TAG, "Month must be set to validate day");
+        this->day_.reset();
+      }
+    }
+    if (this->year_.has_value()) {
+      year = *this->year_;
+    } else {
+      if (this->parent_->year != 0) {
+        year = this->parent_->year;
+      } else {
+        ESP_LOGE(TAG, "Year must be set to validate day");
+        this->day_.reset();
+      }
+    }
+    if (this->day_.has_value() && *this->day_ > days_in_month(month, year)) {
+      ESP_LOGE(TAG, "Day must be between 1 and %d for month %d", days_in_month(month, year), month);
+      this->day_.reset();
+    }
+  }
+}
+
+void DateCall::perform() {
+  this->validate_();
+  this->parent_->control(*this);
+}
+
+DateCall &DateCall::set_date(uint16_t year, uint8_t month, uint8_t day) {
+  this->year_ = year;
+  this->month_ = month;
+  this->day_ = day;
+  return *this;
+};
+
+DateCall &DateCall::set_date(ESPTime time) { return this->set_date(time.year, time.month, time.day_of_month); };
+
+DateCall &DateCall::set_date(const std::string &date) {
+  ESPTime val{};
+  if (!ESPTime::strptime(date, val)) {
+    ESP_LOGE(TAG, "Could not convert the date string to an ESPTime object");
+    return *this;
+  }
+  return this->set_date(val);
+}
+
+DateCall DateEntityRestoreState::to_call(DateEntity *date) {
+  DateCall call = date->make_call();
+  call.set_date(this->year, this->month, this->day);
+  return call;
+}
+
+void DateEntityRestoreState::apply(DateEntity *date) {
+  date->year_ = this->year;
+  date->month_ = this->month;
+  date->day_ = this->day;
+  date->publish_state();
+}
+
+}  // namespace datetime
+}  // namespace esphome
+
+#endif  // USE_DATETIME_DATE

esphome/components/datetime/date_entity.h

@@ -0,0 +1,117 @@
+#pragma once
+
+#include "esphome/core/defines.h"
+
+#ifdef USE_DATETIME_DATE
+
+#include "esphome/core/automation.h"
+#include "esphome/core/helpers.h"
+#include "esphome/core/time.h"
+
+#include "datetime_base.h"
+
+namespace esphome {
+namespace datetime {
+
+#define LOG_DATETIME_DATE(prefix, type, obj) \
+  if ((obj) != nullptr) { \
+    ESP_LOGCONFIG(TAG, "%s%s '%s'", prefix, LOG_STR_LITERAL(type), (obj)->get_name().c_str()); \
+    if (!(obj)->get_icon().empty()) { \
+      ESP_LOGCONFIG(TAG, "%s  Icon: '%s'", prefix, (obj)->get_icon().c_str()); \
+    } \
+  }
+
+class DateCall;
+class DateEntity;
+
+struct DateEntityRestoreState {
+  uint16_t year;
+  uint8_t month;
+  uint8_t day;
+
+  DateCall to_call(DateEntity *date);
+  void apply(DateEntity *date);
+} __attribute__((packed));
+
+class DateEntity : public DateTimeBase {
+ protected:
+  uint16_t year_;
+  uint8_t month_;
+  uint8_t day_;
+
+ public:
+  void publish_state();
+  DateCall make_call();
+
+  ESPTime state_as_esptime() const override {
+    ESPTime obj;
+    obj.year = this->year_;
+    obj.month = this->month_;
+    obj.day_of_month = this->day_;
+    return obj;
+  }
+
+  const uint16_t &year = year_;
+  const uint8_t &month = month_;
+  const uint8_t &day = day_;
+
+ protected:
+  friend class DateCall;
+  friend struct DateEntityRestoreState;
+
+  virtual void control(const DateCall &call) = 0;
+};
+
+class DateCall {
+ public:
+  explicit DateCall(DateEntity *parent) : parent_(parent) {}
+  void perform();
+  DateCall &set_date(uint16_t year, uint8_t month, uint8_t day);
+  DateCall &set_date(ESPTime time);
+  DateCall &set_date(const std::string &date);
+
+  DateCall &set_year(uint16_t year) {
+    this->year_ = year;
+    return *this;
+  }
+  DateCall &set_month(uint8_t month) {
+    this->month_ = month;
+    return *this;
+  }
+  DateCall &set_day(uint8_t day) {
+    this->day_ = day;
+    return *this;
+  }
+
+  optional<uint16_t> get_year() const { return this->year_; }
+  optional<uint8_t> get_month() const { return this->month_; }
+  optional<uint8_t> get_day() const { return this->day_; }
+
+ protected:
+  void validate_();
+
+  DateEntity *parent_;
+
+  optional<int16_t> year_;
+  optional<uint8_t> month_;
+  optional<uint8_t> day_;
+};
+
+template<typename... Ts> class DateSetAction : public Action<Ts...>, public Parented<DateEntity> {
+ public:
+  TEMPLATABLE_VALUE(ESPTime, date)
+
+  void play(Ts... x) override {
+    auto call = this->parent_->make_call();
+
+    if (this->date_.has_value()) {
+      call.set_date(this->date_.value(x...));
+    }
+    call.perform();
+  }
+};
+
+}  // namespace datetime
+}  // namespace esphome
+
+#endif  // USE_DATETIME_DATE

esphome/components/datetime/datetime_base.h

@@ -0,0 +1,34 @@
+#pragma once
+
+#include "esphome/core/automation.h"
+#include "esphome/core/component.h"
+#include "esphome/core/entity_base.h"
+#include "esphome/core/time.h"
+
+namespace esphome {
+namespace datetime {
+
+class DateTimeBase : public EntityBase {
+ public:
+  /// Return whether this Datetime has gotten a full state yet.
+  bool has_state() const { return this->has_state_; }
+
+  virtual ESPTime state_as_esptime() const = 0;
+
+  void add_on_state_callback(std::function<void()> &&callback) { this->state_callback_.add(std::move(callback)); }
+
+ protected:
+  CallbackManager<void()> state_callback_;
+
+  bool has_state_{false};
+};
+
+class DateTimeStateTrigger : public Trigger<ESPTime> {
+ public:
+  explicit DateTimeStateTrigger(DateTimeBase *parent) {
+    parent->add_on_state_callback([this, parent]() { this->trigger(parent->state_as_esptime()); });
+  }
+};
+
+}  // namespace datetime
+}  // namespace esphome

esphome/components/mqtt/__init__.py

@@ -113,6 +113,7 @@ MQTTSensorComponent = mqtt_ns.class_("MQTTSensorComponent", MQTTComponent)
 MQTTSwitchComponent = mqtt_ns.class_("MQTTSwitchComponent", MQTTComponent)
 MQTTTextSensor = mqtt_ns.class_("MQTTTextSensor", MQTTComponent)
 MQTTNumberComponent = mqtt_ns.class_("MQTTNumberComponent", MQTTComponent)
+MQTTDatetimeComponent = mqtt_ns.class_("MQTTDatetimeComponent", MQTTComponent)
 MQTTTextComponent = mqtt_ns.class_("MQTTTextComponent", MQTTComponent)
 MQTTSelectComponent = mqtt_ns.class_("MQTTSelectComponent", MQTTComponent)
 MQTTButtonComponent = mqtt_ns.class_("MQTTButtonComponent", MQTTComponent)

esphome/components/mqtt/mqtt_date.cpp

@@ -0,0 +1,68 @@
+#include "mqtt_date.h"
+
+#include <utility>
+#include "esphome/core/log.h"
+
+#include "mqtt_const.h"
+
+#ifdef USE_MQTT
+#ifdef USE_DATETIME_DATE
+
+namespace esphome {
+namespace mqtt {
+
+static const char *const TAG = "mqtt.datetime";
+
+using namespace esphome::datetime;
+
+MQTTDateComponent::MQTTDateComponent(DateEntity *date) : date_(date) {}
+
+void MQTTDateComponent::setup() {
+  this->subscribe_json(this->get_command_topic_(), [this](const std::string &topic, JsonObject root) {
+    auto call = this->date_->make_call();
+    if (root.containsKey("year")) {
+      call.set_year(root["year"]);
+    }
+    if (root.containsKey("month")) {
+      call.set_month(root["month"]);
+    }
+    if (root.containsKey("day")) {
+      call.set_day(root["day"]);
+    }
+    call.perform();
+  });
+  this->date_->add_on_state_callback(
+      [this]() { this->publish_state(this->date_->year, this->date_->month, this->date_->day); });
+}
+
+void MQTTDateComponent::dump_config() {
+  ESP_LOGCONFIG(TAG, "MQTT Date '%s':", this->date_->get_name().c_str());
+  LOG_MQTT_COMPONENT(true, true)
+}
+
+std::string MQTTDateComponent::component_type() const { return "date"; }
+const EntityBase *MQTTDateComponent::get_entity() const { return this->date_; }
+
+void MQTTDateComponent::send_discovery(JsonObject root, mqtt::SendDiscoveryConfig &config) {
+  // Nothing extra to add here
+}
+bool MQTTDateComponent::send_initial_state() {
+  if (this->date_->has_state()) {
+    return this->publish_state(this->date_->year, this->date_->month, this->date_->day);
+  } else {
+    return true;
+  }
+}
+bool MQTTDateComponent::publish_state(uint16_t year, uint8_t month, uint8_t day) {
+  return this->publish_json(this->get_state_topic_(), [year, month, day](JsonObject root) {
+    root["year"] = year;
+    root["month"] = month;
+    root["day"] = day;
+  });
+}
+
+}  // namespace mqtt
+}  // namespace esphome
+
+#endif  // USE_DATETIME_DATE
+#endif  // USE_MQTT

esphome/components/mqtt/mqtt_date.h

@@ -0,0 +1,45 @@
+#pragma once
+
+#include "esphome/core/defines.h"
+
+#ifdef USE_MQTT
+#ifdef USE_DATETIME_DATE
+
+#include "esphome/components/datetime/date_entity.h"
+#include "mqtt_component.h"
+
+namespace esphome {
+namespace mqtt {
+
+class MQTTDateComponent : public mqtt::MQTTComponent {
+ public:
+  /** Construct this MQTTDatetimeComponent instance with the provided friendly_name and datetime
+   *
+   * @param datetime The datetime component.
+   */
+  explicit MQTTDateComponent(datetime::DateEntity *date);
+
+  // ========== INTERNAL METHODS ==========
+  // (In most use cases you won't need these)
+  /// Override setup.
+  void setup() override;
+  void dump_config() override;
+
+  void send_discovery(JsonObject root, mqtt::SendDiscoveryConfig &config) override;
+
+  bool send_initial_state() override;
+
+  bool publish_state(uint16_t year, uint8_t month, uint8_t day);
+
+ protected:
+  std::string component_type() const override;
+  const EntityBase *get_entity() const override;
+
+  datetime::DateEntity *date_;
+};
+
+}  // namespace mqtt
+}  // namespace esphome
+
+#endif  // USE_DATETIME_DATE
+#endif  // USE_MQTT

esphome/components/template/datetime/__init__.py

@@ -0,0 +1,94 @@
+from esphome import automation
+import esphome.codegen as cg
+import esphome.config_validation as cv
+from esphome.components import datetime
+from esphome.const import (
+    CONF_INITIAL_VALUE,
+    CONF_LAMBDA,
+    CONF_OPTIMISTIC,
+    CONF_RESTORE_VALUE,
+    CONF_SET_ACTION,
+)
+
+from esphome.core import coroutine_with_priority
+from .. import template_ns
+
+CODEOWNERS = ["@rfdarter"]
+
+
+TemplateDate = template_ns.class_(
+    "TemplateDate", datetime.DateEntity, cg.PollingComponent
+)
+
+
+def validate(config):
+    config = config.copy()
+    if CONF_LAMBDA in config:
+        if config[CONF_OPTIMISTIC]:
+            raise cv.Invalid("optimistic cannot be used with lambda")
+        if CONF_INITIAL_VALUE in config:
+            raise cv.Invalid("initial_value cannot be used with lambda")
+        if CONF_RESTORE_VALUE in config:
+            raise cv.Invalid("restore_value cannot be used with lambda")
+    else:
+        if CONF_RESTORE_VALUE not in config:
+            config[CONF_RESTORE_VALUE] = False
+
+    if not config[CONF_OPTIMISTIC] and CONF_SET_ACTION not in config:
+        raise cv.Invalid(
+            "Either optimistic mode must be enabled, or set_action must be set, to handle the date and time being set."
+        )
+    return config
+
+
+_BASE_SCHEMA = cv.Schema(
+    {
+        cv.Optional(CONF_LAMBDA): cv.returning_lambda,
+        cv.Optional(CONF_OPTIMISTIC, default=False): cv.boolean,
+        cv.Optional(CONF_SET_ACTION): automation.validate_automation(single=True),
+        cv.Optional(CONF_RESTORE_VALUE): cv.boolean,
+    }
+).extend(cv.polling_component_schema("60s"))
+
+CONFIG_SCHEMA = cv.All(
+    cv.typed_schema(
+        {
+            "DATE": datetime.date_schema(TemplateDate)
+            .extend(_BASE_SCHEMA)
+            .extend(
+                {
+                    cv.Optional(CONF_INITIAL_VALUE): cv.date_time(allowed_time=False),
+                }
+            ),
+        },
+        upper=True,
+    ),
+    validate,
+)
+
+
+@coroutine_with_priority(-100.0)
+async def to_code(config):
+    var = await datetime.new_datetime(config)
+
+    if CONF_LAMBDA in config:
+        template_ = await cg.process_lambda(
+            config[CONF_LAMBDA], [], return_type=cg.optional.template(cg.ESPTime)
+        )
+        cg.add(var.set_template(template_))
+
+    else:
+        cg.add(var.set_optimistic(config[CONF_OPTIMISTIC]))
+        cg.add(var.set_restore_value(config[CONF_RESTORE_VALUE]))
+
+        if initial_value := config.get(CONF_INITIAL_VALUE):
+            cg.add(var.set_initial_value(initial_value))
+
+    if CONF_SET_ACTION in config:
+        await automation.build_automation(
+            var.get_set_trigger(),
+            [(cg.ESPTime, "x")],
+            config[CONF_SET_ACTION],
+        )
+
+    await cg.register_component(var, config)

esphome/components/template/datetime/template_date.cpp

@@ -0,0 +1,111 @@
+#include "template_date.h"
+
+#ifdef USE_DATETIME_DATE
+
+#include "esphome/core/log.h"
+
+namespace esphome {
+namespace template_ {
+
+static const char *const TAG = "template.date";
+
+void TemplateDate::setup() {
+  if (this->f_.has_value())
+    return;
+
+  ESPTime state{};
+
+  if (!this->restore_value_) {
+    state = this->initial_value_;
+  } else {
+    datetime::DateEntityRestoreState temp;
+    this->pref_ =
+        global_preferences->make_preference<datetime::DateEntityRestoreState>(194434030U ^ this->get_object_id_hash());
+    if (this->pref_.load(&temp)) {
+      temp.apply(this);
+      return;
+    } else {
+      // set to inital value if loading from pref failed
+      state = this->initial_value_;
+    }
+  }
+
+  this->year_ = state.year;
+  this->month_ = state.month;
+  this->day_ = state.day_of_month;
+  this->publish_state();
+}
+
+void TemplateDate::update() {
+  if (!this->f_.has_value())
+    return;
+
+  auto val = (*this->f_)();
+  if (!val.has_value())
+    return;
+
+  this->year_ = val->year;
+  this->month_ = val->month;
+  this->day_ = val->day_of_month;
+  this->publish_state();
+}
+
+void TemplateDate::control(const datetime::DateCall &call) {
+  bool has_year = call.get_year().has_value();
+  bool has_month = call.get_month().has_value();
+  bool has_day = call.get_day().has_value();
+
+  ESPTime value = {};
+  if (has_year)
+    value.year = *call.get_year();
+
+  if (has_month)
+    value.month = *call.get_month();
+
+  if (has_day)
+    value.day_of_month = *call.get_day();
+
+  this->set_trigger_->trigger(value);
+
+  if (this->optimistic_) {
+    if (has_year)
+      this->year_ = *call.get_year();
+    if (has_month)
+      this->month_ = *call.get_month();
+    if (has_day)
+      this->day_ = *call.get_day();
+    this->publish_state();
+  }
+
+  if (this->restore_value_) {
+    datetime::DateEntityRestoreState temp = {};
+    if (has_year) {
+      temp.year = *call.get_year();
+    } else {
+      temp.year = this->year_;
+    }
+    if (has_month) {
+      temp.month = *call.get_month();
+    } else {
+      temp.month = this->month_;
+    }
+    if (has_day) {
+      temp.day = *call.get_day();
+    } else {
+      temp.day = this->day_;
+    }
+
+    this->pref_.save(&temp);
+  }
+}
+
+void TemplateDate::dump_config() {
+  LOG_DATETIME_DATE("", "Template Date", this);
+  ESP_LOGCONFIG(TAG, "  Optimistic: %s", YESNO(this->optimistic_));
+  LOG_UPDATE_INTERVAL(this);
+}
+
+}  // namespace template_
+}  // namespace esphome
+
+#endif  // USE_DATETIME_DATE

esphome/components/template/datetime/template_date.h

@@ -0,0 +1,46 @@
+#pragma once
+
+#include "esphome/core/defines.h"
+
+#ifdef USE_DATETIME_DATE
+
+#include "esphome/components/datetime/date_entity.h"
+#include "esphome/core/automation.h"
+#include "esphome/core/component.h"
+#include "esphome/core/preferences.h"
+#include "esphome/core/time.h"
+
+namespace esphome {
+namespace template_ {
+
+class TemplateDate : public datetime::DateEntity, public PollingComponent {
+ public:
+  void set_template(std::function<optional<ESPTime>()> &&f) { this->f_ = f; }
+
+  void setup() override;
+  void update() override;
+  void dump_config() override;
+  float get_setup_priority() const override { return setup_priority::HARDWARE; }
+
+  Trigger<ESPTime> *get_set_trigger() const { return this->set_trigger_; }
+  void set_optimistic(bool optimistic) { this->optimistic_ = optimistic; }
+
+  void set_initial_value(ESPTime initial_value) { this->initial_value_ = initial_value; }
+  void set_restore_value(bool restore_value) { this->restore_value_ = restore_value; }
+
+ protected:
+  void control(const datetime::DateCall &call) override;
+
+  bool optimistic_{false};
+  ESPTime initial_value_{};
+  bool restore_value_{false};
+  Trigger<ESPTime> *set_trigger_ = new Trigger<ESPTime>();
+  optional<std::function<optional<ESPTime>()>> f_;
+
+  ESPPreferenceObject pref_;
+};
+
+}  // namespace template_
+}  // namespace esphome
+
+#endif  // USE_DATETIME_DATE

esphome/components/time/__init__.py

@@ -37,7 +37,6 @@ time_ns = cg.esphome_ns.namespace("time")
 RealTimeClock = time_ns.class_("RealTimeClock", cg.PollingComponent)
 CronTrigger = time_ns.class_("CronTrigger", automation.Trigger.template(), cg.Component)
 SyncTrigger = time_ns.class_("SyncTrigger", automation.Trigger.template(), cg.Component)
-ESPTime = time_ns.struct("ESPTime")
 TimeHasTimeCondition = time_ns.class_("TimeHasTimeCondition", Condition)
 
 

esphome/components/web_server/list_entities.cpp

@@ -82,6 +82,13 @@ bool ListEntitiesIterator::on_number(number::Number *number) {
 }
 #endif
 
+#ifdef USE_DATETIME_DATE
+bool ListEntitiesIterator::on_date(datetime::DateEntity *date) {
+  this->web_server_->events_.send(this->web_server_->date_json(date, DETAIL_ALL).c_str(), "state");
+  return true;
+}
+#endif
+
 #ifdef USE_TEXT
 bool ListEntitiesIterator::on_text(text::Text *text) {
   this->web_server_->events_.send(this->web_server_->text_json(text, text->state, DETAIL_ALL).c_str(), "state");

esphome/components/web_server/list_entities.h

@@ -41,6 +41,9 @@ class ListEntitiesIterator : public ComponentIterator {
 #ifdef USE_NUMBER
   bool on_number(number::Number *number) override;
 #endif
+#ifdef USE_DATETIME_DATE
+  bool on_date(datetime::DateEntity *date) override;
+#endif
 #ifdef USE_TEXT
   bool on_text(text::Text *text) override;
 #endif

esphome/components/web_server/web_server.cpp

@@ -4,6 +4,7 @@
 #include "esphome/components/network/util.h"
 #include "esphome/core/application.h"
 #include "esphome/core/entity_base.h"
+#include "esphome/core/helpers.h"
 #include "esphome/core/log.h"
 #include "esphome/core/util.h"
 
@@ -853,6 +854,53 @@ std::string WebServer::number_json(number::Number *obj, float value, JsonDetail
 }
 #endif
 
+#ifdef USE_DATETIME_DATE
+void WebServer::on_date_update(datetime::DateEntity *obj) {
+  this->events_.send(this->date_json(obj, DETAIL_STATE).c_str(), "state");
+}
+void WebServer::handle_date_request(AsyncWebServerRequest *request, const UrlMatch &match) {
+  for (auto *obj : App.get_dates()) {
+    if (obj->get_object_id() != match.id)
+      continue;
+    if (request->method() == HTTP_GET) {
+      std::string data = this->date_json(obj, DETAIL_STATE);
+      request->send(200, "application/json", data.c_str());
+      return;
+    }
+    if (match.method != "set") {
+      request->send(404);
+      return;
+    }
+
+    auto call = obj->make_call();
+
+    if (!request->hasParam("value")) {
+      request->send(409);
+      return;
+    }
+
+    if (request->hasParam("value")) {
+      std::string value = request->getParam("value")->value().c_str();
+      call.set_date(value);
+    }
+
+    this->schedule_([call]() mutable { call.perform(); });
+    request->send(200);
+    return;
+  }
+  request->send(404);
+}
+
+std::string WebServer::date_json(datetime::DateEntity *obj, JsonDetail start_config) {
+  return json::build_json([obj, start_config](JsonObject root) {
+    set_json_id(root, obj, "date-" + obj->get_object_id(), start_config);
+    std::string value = str_sprintf("%d-%d-%d", obj->year, obj->month, obj->day);
+    root["value"] = value;
+    root["state"] = value;
+  });
+}
+#endif  // USE_DATETIME_DATE
+
 #ifdef USE_TEXT
 void WebServer::on_text_update(text::Text *obj, const std::string &state) {
   this->events_.send(this->text_json(obj, state, DETAIL_STATE).c_str(), "state");
@@ -1237,6 +1285,11 @@ bool WebServer::canHandle(AsyncWebServerRequest *request) {
     return true;
 #endif
 
+#ifdef USE_DATETIME_DATE
+  if ((request->method() == HTTP_POST || request->method() == HTTP_GET) && match.domain == "date")
+    return true;
+#endif
+
 #ifdef USE_TEXT
   if ((request->method() == HTTP_POST || request->method() == HTTP_GET) && match.domain == "text")
     return true;
@@ -1355,6 +1408,13 @@ void WebServer::handleRequest(AsyncWebServerRequest *request) {
   }
 #endif
 
+#ifdef USE_DATETIME_DATE
+  if (match.domain == "date") {
+    this->handle_date_request(request, match);
+    return;
+  }
+#endif
+
 #ifdef USE_TEXT
   if (match.domain == "text") {
     this->handle_text_request(request, match);

esphome/components/web_server/web_server.h

@@ -221,6 +221,15 @@ class WebServer : public Controller, public Component, public AsyncWebHandler {
   std::string number_json(number::Number *obj, float value, JsonDetail start_config);
 #endif
 
+#ifdef USE_DATETIME_DATE
+  void on_date_update(datetime::DateEntity *obj) override;
+  /// Handle a date request under '/date/<id>'.
+  void handle_date_request(AsyncWebServerRequest *request, const UrlMatch &match);
+
+  /// Dump the date state with its value as a JSON string.
+  std::string date_json(datetime::DateEntity *obj, JsonDetail start_config);
+#endif
+
 #ifdef USE_TEXT
   void on_text_update(text::Text *obj, const std::string &state) override;
   /// Handle a text input request under '/text/<id>'.

esphome/config_validation.py

@@ -32,6 +32,9 @@ from esphome.const import (
     CONF_SETUP_PRIORITY,
     CONF_STATE_TOPIC,
     CONF_TOPIC,
+    CONF_YEAR,
+    CONF_MONTH,
+    CONF_DAY,
     CONF_HOUR,
     CONF_MINUTE,
     CONF_SECOND,
@@ -817,21 +820,112 @@ positive_not_null_time_period = All(
 
 
 def time_of_day(value):
-    value = string(value)
+    return date_time(allowed_date=False, allowed_time=True)(value)
-    try:
-        date = datetime.strptime(value, "%H:%M:%S")
-    except ValueError as err:
-        try:
-            date = datetime.strptime(value, "%H:%M:%S %p")
-        except ValueError:
-            # pylint: disable=raise-missing-from
-            raise Invalid(f"Invalid time of day: {err}")
 
-    return {
+
-        CONF_HOUR: date.hour,
+def date_time(allowed_date: bool = True, allowed_time: bool = True):
-        CONF_MINUTE: date.minute,
+
-        CONF_SECOND: date.second,
+    pattern_str = r"^"  # Start of string
+    if allowed_date:
+        pattern_str += (
+            r"("  # 1. Optional Date group
+            r"\d{4}-\d{1,2}-\d{1,2}"  # Date
+            r"(?:\s(?=.+))?"  # Space after date only if time is following
+            r")?"  # End optional Date group
+        )
+    if allowed_time:
+        pattern_str += (
+            r"("  # 2. Optional Time group
+            r"(\d{1,2}:\d{2})"  # 3. Hour/Minute
+            r"(:\d{2})?"  # 4. Seconds
+            r"("  # 5. Optional AM/PM group
+            r"(\s)?"  # 6. Optional Space
+            r"(?:AM|PM|am|pm)"  # AM/PM string matching
+            r")?"  # End optional AM/PM group
+            r")?"  # End optional Time group
+        )
+    pattern_str += r"$"  # End of string
+
+    pattern = re.compile(pattern_str)
+
+    exc_message = ""
+    if allowed_date:
+        exc_message += "date"
+        if allowed_time:
+            exc_message += "/"
+    if allowed_time:
+        exc_message += "time"
+
+    schema = Schema({})
+    if allowed_date:
+        schema = schema.extend(
+            {
+                Optional(CONF_YEAR): int_range(min=1970, max=3000),
+                Optional(CONF_MONTH): int_range(min=1, max=12),
+                Optional(CONF_DAY): int_range(min=1, max=31),
             }
+        )
+    if allowed_time:
+        schema = schema.extend(
+            {
+                Optional(CONF_HOUR): int_range(min=0, max=23),
+                Optional(CONF_MINUTE): int_range(min=0, max=59),
+                Optional(CONF_SECOND): int_range(min=0, max=59),
+            }
+        )
+
+    def validator(value):
+        if isinstance(value, dict):
+            return schema(value)
+        value = string(value)
+
+        match = pattern.match(value)
+        if match is None:
+            # pylint: disable=raise-missing-from
+            raise Invalid(f"Invalid {exc_message}: {value}")
+
+        if allowed_date:
+            has_date = match[1] is not None
+        if allowed_time:
+            has_time = match[2] is not None
+            has_seconds = match[3] is not None
+            has_ampm = match[4] is not None
+            has_ampm_space = match[5] is not None
+
+        format = ""
+        if allowed_date and has_date:
+            format += "%Y-%m-%d"
+            if allowed_time and has_time:
+                format += " "
+        if allowed_time and has_time:
+            format += "%H:%M"
+            if has_seconds:
+                format += ":%S"
+            if has_ampm_space:
+                format += " "
+            if has_ampm:
+                format += "%p"
+
+        try:
+            date_obj = datetime.strptime(value, format)
+        except ValueError as err:
+            # pylint: disable=raise-missing-from
+            raise Invalid(f"Invalid {exc_message}: {err}")
+
+        return_value = {}
+        if allowed_date and has_date:
+            return_value[CONF_YEAR] = date_obj.year
+            return_value[CONF_MONTH] = date_obj.month
+            return_value[CONF_DAY] = date_obj.day
+
+        if allowed_time and has_time:
+            return_value[CONF_HOUR] = date_obj.hour
+            return_value[CONF_MINUTE] = date_obj.minute
+            return_value[CONF_SECOND] = date_obj.second if has_seconds else 0
+
+        return schema(return_value)
+
+    return validator
 
 
 def mac_address(value):

esphome/const.py

@@ -176,6 +176,8 @@ CONF_DATA_PIN = "data_pin"
 CONF_DATA_PINS = "data_pins"
 CONF_DATA_RATE = "data_rate"
 CONF_DATA_TEMPLATE = "data_template"
+CONF_DATE = "date"
+CONF_DAY = "day"
 CONF_DAYS_OF_MONTH = "days_of_month"
 CONF_DAYS_OF_WEEK = "days_of_week"
 CONF_DC_PIN = "dc_pin"
@@ -468,6 +470,7 @@ CONF_MODE_COMMAND_TOPIC = "mode_command_topic"
 CONF_MODE_STATE_TOPIC = "mode_state_topic"
 CONF_MODEL = "model"
 CONF_MOISTURE = "moisture"
+CONF_MONTH = "month"
 CONF_MONTHS = "months"
 CONF_MOSI_PIN = "mosi_pin"
 CONF_MOTION = "motion"
@@ -871,6 +874,7 @@ CONF_WINDOW_SIZE = "window_size"
 CONF_WRITE_PIN = "write_pin"
 CONF_X_GRID = "x_grid"
 CONF_Y_GRID = "y_grid"
+CONF_YEAR = "year"
 CONF_ZERO = "zero"
 
 TYPE_GIT = "git"

esphome/core/application.h

@@ -39,6 +39,9 @@
 #ifdef USE_NUMBER
 #include "esphome/components/number/number.h"
 #endif
+#ifdef USE_DATETIME_DATE
+#include "esphome/components/datetime/date_entity.h"
+#endif
 #ifdef USE_TEXT
 #include "esphome/components/text/text.h"
 #endif
@@ -121,6 +124,10 @@ class Application {
   void register_number(number::Number *number) { this->numbers_.push_back(number); }
 #endif
 
+#ifdef USE_DATETIME_DATE
+  void register_date(datetime::DateEntity *date) { this->dates_.push_back(date); }
+#endif
+
 #ifdef USE_TEXT
   void register_text(text::Text *text) { this->texts_.push_back(text); }
 #endif
@@ -289,6 +296,15 @@ class Application {
     return nullptr;
   }
 #endif
+#ifdef USE_DATETIME_DATE
+  const std::vector<datetime::DateEntity *> &get_dates() { return this->dates_; }
+  datetime::DateEntity *get_date_by_key(uint32_t key, bool include_internal = false) {
+    for (auto *obj : this->dates_)
+      if (obj->get_object_id_hash() == key && (include_internal || !obj->is_internal()))
+        return obj;
+    return nullptr;
+  }
+#endif
 #ifdef USE_TEXT
   const std::vector<text::Text *> &get_texts() { return this->texts_; }
   text::Text *get_text_by_key(uint32_t key, bool include_internal = false) {
@@ -382,6 +398,9 @@ class Application {
 #ifdef USE_NUMBER
   std::vector<number::Number *> numbers_{};
 #endif
+#ifdef USE_DATETIME_DATE
+  std::vector<datetime::DateEntity *> dates_{};
+#endif
 #ifdef USE_SELECT
   std::vector<select::Select *> selects_{};
 #endif

esphome/core/component_iterator.cpp

@@ -202,6 +202,21 @@ void ComponentIterator::advance() {
       }
       break;
 #endif
+#ifdef USE_DATETIME_DATE
+    case IteratorState::DATETIME_DATE:
+      if (this->at_ >= App.get_dates().size()) {
+        advance_platform = true;
+      } else {
+        auto *date = App.get_dates()[this->at_];
+        if (date->is_internal() && !this->include_internal_) {
+          success = true;
+          break;
+        } else {
+          success = this->on_date(date);
+        }
+      }
+      break;
+#endif
 #ifdef USE_TEXT
     case IteratorState::TEXT:
       if (this->at_ >= App.get_texts().size()) {

esphome/core/component_iterator.h

@@ -57,6 +57,9 @@ class ComponentIterator {
 #ifdef USE_NUMBER
   virtual bool on_number(number::Number *number) = 0;
 #endif
+#ifdef USE_DATETIME_DATE
+  virtual bool on_date(datetime::DateEntity *date) = 0;
+#endif
 #ifdef USE_TEXT
   virtual bool on_text(text::Text *text) = 0;
 #endif
@@ -114,6 +117,9 @@ class ComponentIterator {
 #ifdef USE_NUMBER
     NUMBER,
 #endif
+#ifdef USE_DATETIME_DATE
+    DATETIME_DATE,
+#endif
 #ifdef USE_TEXT
     TEXT,
 #endif

esphome/core/controller.cpp

@@ -1,6 +1,6 @@
 #include "controller.h"
-#include "esphome/core/log.h"
 #include "esphome/core/application.h"
+#include "esphome/core/log.h"
 
 namespace esphome {
 
@@ -59,6 +59,12 @@ void Controller::setup_controller(bool include_internal) {
       obj->add_on_state_callback([this, obj](float state) { this->on_number_update(obj, state); });
   }
 #endif
+#ifdef USE_DATETIME_DATE
+  for (auto *obj : App.get_dates()) {
+    if (include_internal || !obj->is_internal())
+      obj->add_on_state_callback([this, obj]() { this->on_date_update(obj); });
+  }
+#endif
 #ifdef USE_TEXT
   for (auto *obj : App.get_texts()) {
     if (include_internal || !obj->is_internal())

esphome/core/controller.h

@@ -31,6 +31,9 @@
 #ifdef USE_NUMBER
 #include "esphome/components/number/number.h"
 #endif
+#ifdef USE_DATETIME_DATE
+#include "esphome/components/datetime/date_entity.h"
+#endif
 #ifdef USE_TEXT
 #include "esphome/components/text/text.h"
 #endif
@@ -79,6 +82,9 @@ class Controller {
 #ifdef USE_NUMBER
   virtual void on_number_update(number::Number *obj, float state){};
 #endif
+#ifdef USE_DATETIME_DATE
+  virtual void on_date_update(datetime::DateEntity *obj){};
+#endif
 #ifdef USE_TEXT
   virtual void on_text_update(text::Text *obj, const std::string &state){};
 #endif

esphome/core/defines.h

@@ -34,6 +34,8 @@
 #define USE_MEDIA_PLAYER
 #define USE_MQTT
 #define USE_NUMBER
+#define USE_DATETIME
+#define USE_DATETIME_DATE
 #define USE_OTA
 #define USE_OTA_PASSWORD
 #define USE_OTA_STATE_CALLBACK

esphome/core/time.cpp

@@ -1,10 +1,13 @@
+#include <regex>
+
+#include "helpers.h"
 #include "time.h"  // NOLINT
 
 namespace esphome {
 
-static bool is_leap_year(uint32_t year) { return (year % 4) == 0 && ((year % 100) != 0 || (year % 400) == 0); }
+bool is_leap_year(uint32_t year) { return (year % 4) == 0 && ((year % 100) != 0 || (year % 400) == 0); }
 
-static uint8_t days_in_month(uint8_t month, uint16_t year) {
+uint8_t days_in_month(uint8_t month, uint16_t year) {
   static const uint8_t DAYS_IN_MONTH[] = {0, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31};
   uint8_t days = DAYS_IN_MONTH[month];
   if (month == 2 && is_leap_year(year))
@@ -61,6 +64,44 @@ std::string ESPTime::strftime(const std::string &format) {
   return timestr;
 }
 
+bool ESPTime::strptime(const std::string &time_to_parse, ESPTime &esp_time) {
+  // clang-format off
+  std::regex dt_regex(R"(^
+    (
+      (\d{4})-(\d{1,2})-(\d{1,2})
+      (?:\s(?=.+))
+    )?
+    (
+      (\d{1,2}):(\d{2})
+      (?::(\d{2}))?
+    )?
+  $)");
+  // clang-format on
+
+  std::smatch match;
+  if (std::regex_match(time_to_parse, match, dt_regex) == 0)
+    return false;
+
+  if (match[1].matched) {  // Has date parts
+
+    esp_time.year = parse_number<uint16_t>(match[2].str()).value_or(0);
+    esp_time.month = parse_number<uint8_t>(match[3].str()).value_or(0);
+    esp_time.day_of_month = parse_number<uint8_t>(match[4].str()).value_or(0);
+  }
+  if (match[5].matched) {  // Has time parts
+
+    esp_time.hour = parse_number<uint8_t>(match[6].str()).value_or(0);
+    esp_time.minute = parse_number<uint8_t>(match[7].str()).value_or(0);
+    if (match[8].matched) {
+      esp_time.second = parse_number<uint8_t>(match[8].str()).value_or(0);
+    } else {
+      esp_time.second = 0;
+    }
+  }
+
+  return true;
+}
+
 void ESPTime::increment_second() {
   this->timestamp++;
   if (!increment_time_value(this->second, 0, 60))

esphome/core/time.h

@@ -9,6 +9,10 @@ namespace esphome {
 
 template<typename T> bool increment_time_value(T &current, uint16_t begin, uint16_t end);
 
+bool is_leap_year(uint32_t year);
+
+uint8_t days_in_month(uint8_t month, uint16_t year);
+
 /// A more user-friendly version of struct tm from time.h
 struct ESPTime {
   /** seconds after the minute [0-60]
@@ -63,6 +67,13 @@ struct ESPTime {
            this->day_of_year < 367 && this->month > 0 && this->month < 13;
   }
 
+  /** Convert a string to ESPTime struct as specified by the format argument.
+   * @param time_to_parse null-terminated c string formatet like this: 2020-08-25 05:30:00.
+   * @param esp_time an instance of a ESPTime struct
+   * @return the success sate of the parsing
+   */
+  static bool strptime(const std::string &time_to_parse, ESPTime &esp_time);
+
   /// Convert a C tm struct instance with a C unix epoch timestamp to an ESPTime instance.
   static ESPTime from_c_tm(struct tm *c_tm, time_t c_time);
 

esphome/cpp_types.py

@@ -38,3 +38,4 @@ gpio_ns = esphome_ns.namespace("gpio")
 gpio_Flags = gpio_ns.enum("Flags", is_class=True)
 EntityCategory = esphome_ns.enum("EntityCategory")
 Parented = esphome_ns.class_("Parented")
+ESPTime = esphome_ns.struct("ESPTime")

script/ci-custom.py

@@ -609,6 +609,7 @@ def lint_trailing_whitespace(fname, match):
         "esphome/components/button/button.h",
         "esphome/components/climate/climate.h",
         "esphome/components/cover/cover.h",
+        "esphome/components/datetime/date_entity.h",
         "esphome/components/display/display.h",
         "esphome/components/fan/fan.h",
         "esphome/components/i2c/i2c.h",

tests/components/datetime/date.all.yaml

@@ -0,0 +1 @@
+datetime:

tests/components/template/test.all.yaml

@@ -19,7 +19,20 @@ esphome:
     # Templated
     - sensor.template.publish:
         id: template_sens
-        state: !lambda 'return 42.0;'
+        state: !lambda "return 42.0;"
+
+    - datetime.date.set:
+        id: test_date
+        date:
+          year: 2021
+          month: 1
+          day: 1
+    - datetime.date.set:
+        id: test_date
+        date: !lambda "return {.day_of_month = 1, .month = 1, .year = 2021};"
+    - datetime.date.set:
+        id: test_date
+        date: "2021-01-01"
 
 binary_sensor:
   - platform: template
@@ -125,3 +138,18 @@ alarm_control_panel:
     name: Alarm Panel
     codes:
       - "1234"
+
+datetime:
+  - platform: template
+    name: Date
+    id: test_date
+    type: date
+    set_action:
+      - logger.log: "set_value"
+    on_value:
+      - logger.log:
+          format: "Date: %04d-%02d-%02d"
+          args:
+            - x.year
+            - x.month
+            - x.day_of_month