Datetime Component ================== .. seo:: :description: Instructions for setting up datetime components in ESPHome. :image: folder-open.svg ESPHome has support for components to create a datetime entity. A datetime entity currently represents a date that can be set by the user/frontend. .. note:: Requires Home Assistant 2024.4 or newer. .. _config-datetime: Base Datetime Configuration --------------------------- All datetime in ESPHome have a name and an optional icon. .. code-block:: yaml # Example datetime configuration name: Date to check # Optional variables: icon: "mdi:calendar-alert" Configuration variables: - **id** (*Optional*, string): Manually specify the ID for code generation. At least one of **id** and **name** must be specified. - **name** (*Optional*, string): The name for the datetime. At least one of **id** and **name** must be specified. .. note:: If you have a :ref:`friendly_name ` set for your device and you want the datetime to use that name, you can set ``name: None``. - **icon** (*Optional*, icon): Manually set the icon to use for the datetime in the frontend. - **internal** (*Optional*, boolean): Mark this component as internal. Internal components will not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without a ``name`` will implicitly set this to true. - **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend, (usually Home Assistant) without the user manually enabling it (via the Home Assistant UI). Defaults to ``false``. - **entity_category** (*Optional*, string): The category of the entity. See https://developers.home-assistant.io/docs/core/entity/#generic-properties for a list of available options. Set to ``""`` to remove the default entity category. - **time_id** (**Required**, :ref:`config-id`): The ID of the time entity. Automatically set to the ID of a time component if only a single one is defined. - If Webserver enabled, ``web_server_sorting_weight`` can be set. See :ref:`Webserver Entity Sorting `. MQTT Options: - All other options from :ref:`MQTT Component `. Time and DateTime Options: - **on_time** (*Optional*, :ref:`automation`): Automation to run when the current datetime or time matches the current state. Only valid on ``time`` or ``datetime`` types. Automation ---------- You can access the most recent state as a ``ESPTime`` object by ``id(datetime_id).state_as_esptime()`` .. _datetime-on_value: ``on_value`` ************ This automation will be triggered when a new value is published. In :ref:`Lambdas ` you can get the value as a ESPTime object from the trigger with ``x``. .. code-block:: yaml datetime: - platform: template # ... on_value: then: - lambda: |- if(x.hour >= 12) { ESP_LOGD("main", "Updated hour is later or equal to 12"); } else { ESP_LOGD("main", "Updated hour is earlier than 12"); } Configuration variables: See :ref:`Automation `. Date Automation --------------- .. _datetime-date_set_action: ``datetime.date.set`` Action **************************** This is an :ref:`Action ` for setting a datetime date state. The ``date`` provided can be in one of 3 formats: .. code-block:: yaml # String date - datetime.date.set: id: my_datetime_date date: "2023-12-04" # Individual date parts - datetime.date.set: id: my_datetime_date date: year: 2023 month: 12 day: 4 # Using a lambda - datetime.date.set: id: my_datetime_date date: !lambda |- // Return an ESPTime struct return {.day_of_month = 4, .month = 12, .year = 2023}; Configuration variables: - **id** (**Required**, :ref:`config-id`): The ID of the datetime to set. - **date** (**Required**, string, date parts, :ref:`templatable `): The value to set the datetime to. .. _datetime-lambda_calls: lambda calls ************ From :ref:`lambdas `, you can call several methods on all datetimes to do some advanced stuff (see the full API Reference for more info). - ``.make_call()``: Make a call for updating the datetime value. .. code-block:: cpp // Within lambda, set the date to 2024-02-25 auto call = id(my_datetime_date).make_call(); call.set_date("2024-02-25"); call.perform(); Check the API reference for information on the methods that are available for the ``DateCall`` object. - ``.year``: Retrieve the current year of the ``date``. It will be ``0`` if no value has been set. - ``.month``: Retrieve the current month of the ``date``. It will be ``0`` if no value has been set. - ``.day``: Retrieve the current day of the ``date``. It will be ``0`` if no value has been set. - ``.state_as_esptime()``: Retrieve the current value of the datetime as a :apistruct:`ESPTime` object. .. code-block:: cpp // For example, create a custom log message when a value is received: ESP_LOGI("main", "Value of my datetime: %04d-%02d-%02d", id(my_date).year, id(my_date).month, id(my_date).day); Time Automation --------------- .. _datetime-time_set_action: ``datetime.time.set`` Action **************************** This is an :ref:`Action ` for setting a datetime time state. The ``time`` provided can be in one of 3 formats: .. code-block:: yaml # String time - datetime.time.set: id: my_datetime_time time: "12:34:56" # Individual time parts - datetime.time.set: id: my_datetime_time time: hour: 12 minute: 34 second: 56 # Using a lambda - datetime.time.set: id: my_datetime_time time: !lambda |- // Return an ESPTime struct return {.second = 56, .minute = 34, .hour = 12}; Configuration variables: - **id** (**Required**, :ref:`config-id`): The ID of the datetime to set. - **time** (**Required**, string, time parts, :ref:`templatable `): The value to set the datetime to. .. _datetime-time-lambda_calls: lambda calls ************ From :ref:`lambdas `, you can call several methods on all datetimes to do some advanced stuff (see the full API Reference for more info). - ``.make_call()``: Make a call for updating the datetime value. .. code-block:: cpp // Within lambda, set the time to 12:34:56 auto call = id(my_datetime_time).make_call(); call.set_time("12:34:56"); call.perform(); Check the API reference for information on the methods that are available for the ``TimeCall`` object. - ``.hour``: Retrieve the current hour of the ``time``. It will be ``0`` if no value has been set. - ``.minute``: Retrieve the current minute of the ``time``. It will be ``0`` if no value has been set. - ``.second``: Retrieve the current second of the ``time``. It will be ``0`` if no value has been set. - ``.state_as_esptime()``: Retrieve the current value of the datetime as a :apistruct:`ESPTime` object. .. code-block:: cpp // For example, create a custom log message when a value is received: ESP_LOGI("main", "Value of my datetime: %0d:%02d:%02d", id(my_datetime_time).hour, id(my_datetime_time).minute, id(my_datetime_time).second); DateTime Automation ------------------- .. _datetime-datetime_set_action: ``datetime.datetime.set`` Action ******************************** This is an :ref:`Action ` for setting a datetime datetime state. The ``datetime`` provided can be in one of 3 formats: .. code-block:: yaml # String datetime - datetime.time.set: id: my_datetime datetime: "2024-12-31 12:34:56" # Individual datetime parts - datetime.datetime.set: id: my_datetime datetime: year: 2024 month: 12 day: 31 hour: 12 minute: 34 second: 56 # Using a lambda - datetime.datetime.set: id: my_datetime datetime: !lambda |- // Return an ESPTime struct return {.second = 56, .minute = 34, .hour = 12, .day_of_month = 31, .month = 12, .year = 2024}; Configuration variables: - **id** (**Required**, :ref:`config-id`): The ID of the datetime to set. - **datetime** (**Required**, string, datetime parts, :ref:`templatable `): The value to set the datetime to. .. _datetime-datetime-lambda_calls: Lambda calls ************ For more complex use cases, several methods are available for use on datetimes from within :ref:`lambdas `. See the full API Reference for more information. - ``.make_call()``: Make a call for updating the datetime value. .. code-block:: cpp // Within lambda, set the datetime to 2024-12-31 12:34:56 auto call = id(my_datetime).make_call(); call.set_date("2024-12-31 12:34:56"); call.perform(); Check the API reference for information on the methods that are available for the ``DateTimeCall`` object. - ``.year``: Retrieve the current year of the ``datetime``. It will be ``0`` if no value has been set. - ``.month``: Retrieve the current month of the ``datetime``. It will be ``0`` if no value has been set. - ``.day``: Retrieve the current day of the ``datetime``. It will be ``0`` if no value has been set. - ``.hour``: Retrieve the current hour of the ``datetime``. It will be ``0`` if no value has been set. - ``.minute``: Retrieve the current minute of the ``datetime``. It will be ``0`` if no value has been set. - ``.second``: Retrieve the current second of the ``datetime``. It will be ``0`` if no value has been set. - ``.state_as_esptime()``: Retrieve the current value of the datetime as a :apistruct:`ESPTime` object. .. code-block:: cpp // For example, create a custom log message when a value is received: ESP_LOGI("main", "Value of my datetime: %04d-%02d-%02d %0d:%02d:%02d", id(my_datetime).year, id(my_datetime).month, id(my_datetime).day, id(my_datetime).hour, id(my_datetime).minute, id(my_datetime).second); See Also -------- - :apiref:`DateTimeBase ` - :apiref:`DateEntity ` - :apiref:`DateCall ` - :apiref:`TimeEntity ` - :apiref:`TimeCall ` - :apiref:`DateTimeEntity ` - :apiref:`DateTimeCall ` - :ghedit:`Edit` .. toctree:: :maxdepth: 1 :glob: *