Add datetime date entities (#6191)

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

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