Upstream
/
esphome-docs
mirror of https://github.com/esphome/esphome-docs.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

add doc for datetime component (#3595) 

Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
This commit is contained in:
RFDarter 2024-03-10 19:52:24 +01:00 committed by GitHub
parent 49d194a538
commit d549160fc9
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 234 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

166
components/datetime/index.rst Normal file
View File

@ -0,0 +1,166 @@
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:
- **name** (**Required**, string): The name for the datetime.
.. note::
If you have a :ref:`friendly_name <esphome-configuration_variables>` 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).
Requires Home Assistant 2021.9 or newer. 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. Requires Home Assistant 2021.11 or newer.
Set to ``""`` to remove the default entity category.
MQTT Options:
- All other options from :ref:`MQTT Component <config-mqtt-component>`.
Datetime Automation
-------------------
You can access the most recent state as a string of the datetime in :ref:`lambdas <config-lambda>` using
``id(datetime_id).state``.
You can also access it as a ``ESPTime`` object by ``id(datetime_id).state_as_time``
.. _datetime-on_value:
``on_value``
************
This automation will be triggered when a new value is published. In :ref:`Lambdas <config-lambda>`
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 <automation>`.
.. _datetime-date_set_action:
``datetime.date.set`` Action
****************************
This is an :ref:`Action <config-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_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**, :ref:`config-id`): The ID of the datetime to set.
- **date** (**Required**, string, date parts, :ref:`templatable <config-templatable>`):
The value to set the datetime to.
.. _datetime-lambda_calls:
lambda calls
************
From :ref:`lambdas <config-lambda>`, 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_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);
See Also
--------
- :apiref:`DateTimeBase <datetime/datetime_base.h>`
- :apiref:`DateEntity <datetime/date_entity.h>`
- :apiref:`DateCall <datetime/date_entity.h>`
- :ghedit:`Edit`
.. toctree::
:maxdepth: 1
:glob:
*

59
components/datetime/template.rst Normal file
View File

@ -0,0 +1,59 @@
Template Datetime
=================
.. seo::
:description: Instructions for setting up template datetime with ESPHome.
:image: description.svg
The ``template`` datetime platform allows you to create a datetime with templated values
using :ref:`lambdas <config-lambda>`.
.. code-block:: yaml
# Example configuration entry
datetime:
- platform: template
id: my_date
type: date
name: Pick a Date
optimistic: yes
initial_value: "2024-01-30"
restore_value: true
Configuration variables:
------------------------
- **type** (*Required*, enum): The type of the datetime. Can only be ``date``.
- **lambda** (*Optional*, :ref:`lambda <config-lambda>`):
Lambda to be evaluated every update interval to get the current value of the datetime.
- **set_action** (*Optional*, :ref:`Action <config-action>`): The action that should
be performed when the remote (like Home Assistant's frontend) requests to set the
dateime value. The new value is available to lambdas in the ``x`` variable.
- **update_interval** (*Optional*, :ref:`config-time`): The interval on which to update the datetime
by executing the ``lambda``. Defaults to ``60s``.
- **optimistic** (*Optional*, boolean): Whether to operate in optimistic mode - when in this mode,
any command sent to the template datetime will immediately update the reported state.
Cannot be used with ``lambda``. Defaults to ``false``.
- **restore_value** (*Optional*, boolean): Saves and loads the state to RTC/Flash.
Cannot be used with ``lambda``. Defaults to ``false``.
- **initial_value** (*Optional*, string): The value to set the state to on setup if not
restored with ``restore_value``. Can be one of:
- A string in the format ``%Y-%m-%d``, eg: ``"2023-12-04"``.
- An object including ``year``, ``month``, ``day``.
.. code-block:: yaml
initial_value:
year: 2023
month: 12
day: 4
- All other options from :ref:`Datetime <config-datetime>`.
See Also
--------
- :ref:`automation`
- :apiref:`template/datetime/template_date.h`
- :ghedit:`Edit`

1
components/index.rst
View File

@ -11,6 +11,7 @@ Components
fan/index
light/index
number/index
datetime/index
output/index
select/index
sensor/index

8
index.rst
View File

@ -847,6 +847,14 @@ Alarm Control Panel Components
Alarm Control Panel Core, components/alarm_control_panel/index, alarm-panel.svg, dark-invert
Template Alarm Control Panel, components/alarm_control_panel/template, description.svg, dark-invert
Datetime Components
-------------------
.. imgtable::
Datetime Core, components/datetime/index, clock-outline.svg, dark-invert
Template Datetime, components/datetime/template, description.svg, dark-invert
Miscellaneous Components
------------------------