Datetime Component¶
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.
Base Datetime Configuration¶
All datetime in ESPHome have a name and an optional icon.
# Example datetime configuration
name: Date to check
# Optional variables:
icon: "mdi:calendar-alert"
Configuration variables:
name (Required, string): The name for the datetime.
Note
If you have a 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 aname
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.
MQTT Options:
All other options from MQTT Component.
Datetime Automation¶
You can access the most recent state as a string of the datetime in lambdas using
id(datetime_id).state
.
You can also access it as a ESPTime
object by id(datetime_id).state_as_time
on_value
¶
This automation will be triggered when a new value is published. In Lambdas
you can get the value as a ESPTime object from the trigger with x
.
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 Automation.
Date Automation¶
datetime.date.set
Action¶
This is an Action for setting a datetime date state.
The date
provided can be in one of 3 formats:
# String date
- datetime.date.set:
id: my_date
date: "2023-12-04"
# Individual date parts
- datetime.date.set:
id: my_date
date:
year: 2023
month: 12
day: 4
# Using a lambda
- datetime.date.set:
id: my_date
date: !lambda |-
// Return an ESPTime struct
return {.day_of_month: 4, .month: 12, .year: 2023};
Configuration variables:
id (Required, ID): The ID of the datetime to set.
date (Required, string, date parts, templatable): The value to set the datetime to.
lambda calls¶
From 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.// Within lambda, set the date to 2024-02-25 auto call = id(my_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 thedate
. It will be0
if no value has been set..month
: Retrieve the current month of thedate
. It will be0
if no value has been set..day
: Retrieve the current day of thedate
. It will be0
if no value has been set..state_as_esptime()
: Retrieve the current value of the datetime as a ESPTime object.// 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¶
This is an Action for setting a datetime time state.
The time
provided can be in one of 3 formats:
# String time
- datetime.time.set:
id: my_time
time: "12:34:56"
# Individual time parts
- datetime.time.set:
id: my_time
time:
hour: 12
minute: 34
second: 56
# Using a lambda
- datetime.time.set:
id: my_time
time: !lambda |-
// Return an ESPTime struct
return {.second: 56, .minute: 34, .hour: 12};
Configuration variables:
id (Required, ID): The ID of the datetime to set.
time (Required, string, time parts, templatable): The value to set the datetime to.
lambda calls¶
From 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.// Within lambda, set the time to 12:34:56 auto call = id(my_time).make_call(); call.set_date("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 thetime
. It will be0
if no value has been set..minute
: Retrieve the current minute of thetime
. It will be0
if no value has been set..second
: Retrieve the current second of thetime
. It will be0
if no value has been set..state_as_esptime()
: Retrieve the current value of the datetime as a ESPTime object.// For example, create a custom log message when a value is received: ESP_LOGI("main", "Value of my datetime: %0d:%02d:%02d", id(my_time).hour, id(my_time).minute, id(my_time).second);