From 57c9493b1b5c692b36577f0002e3b8837b573a92 Mon Sep 17 00:00:00 2001 From: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Date: Fri, 26 Apr 2024 09:19:56 +1200 Subject: [PATCH] Add DateTime datetime type entities to docs (#3784) Co-authored-by: Keith Burzinski --- components/datetime/index.rst | 97 ++++++++++++++++++++++++++++++-- components/datetime/template.rst | 24 ++++++++ 2 files changed, 115 insertions(+), 6 deletions(-) diff --git a/components/datetime/index.rst b/components/datetime/index.rst index 57636918e..c13c979a5 100644 --- a/components/datetime/index.rst +++ b/components/datetime/index.rst @@ -47,17 +47,22 @@ Configuration variables: 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. MQTT Options: - All other options from :ref:`MQTT Component `. -Datetime Automation -------------------- +Time and DateTime Options: -You can access the most recent state as a string of the datetime in :ref:`lambdas ` using -``id(datetime_id).state``. -You can also access it as a ``ESPTime`` object by ``id(datetime_id).state_as_time`` +- **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: @@ -225,14 +230,94 @@ advanced stuff (see the full API Reference for more info). ESP_LOGI("main", "Value of my datetime: %0d:%02d:%02d", id(my_time).hour, id(my_time).minute, id(my_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:`TimeeEntity ` +- :apiref:`TimeEntity ` - :apiref:`TimeCall ` +- :apiref:`DateTimeEntity ` +- :apiref:`DateTimeCall ` - :ghedit:`Edit` .. toctree:: diff --git a/components/datetime/template.rst b/components/datetime/template.rst index 3619db27e..e99161908 100644 --- a/components/datetime/template.rst +++ b/components/datetime/template.rst @@ -29,6 +29,15 @@ using :ref:`lambdas `. initial_value: "12:34:56" restore_value: true + # Example DateTime + - platform: template + id: my_datetime + type: datetime + name: Pick a DateTime + optimistic: yes + initial_value: "2024-12-31 12:34:56" + restore_value: true + Configuration variables: ------------------------ @@ -72,6 +81,21 @@ Configuration variables: minute: 34 second: 56 + - For ``type: datetime``: + + - A string in the format ``%Y-%m-%d %H:%M:%S`` , eg: ``"2023-12-04 12:34:56"``. + - An object including ``year``, ``month``, ``day``, ``hour``, ``minute``, ``second``. + + .. code-block:: yaml + + initial_value: + year: 2023 + month: 12 + day: 4 + hour: 12 + minute: 34 + second: 56 + - All other options from :ref:`Datetime `. See Also