Restructure time docs into its own folder and split (#2566)

This commit is contained in:
Jesse Hills 2022-12-23 11:57:01 +13:00 committed by GitHub
parent 22d9e6c4bc
commit 150d149d60
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12 changed files with 210 additions and 160 deletions

View File

@ -142,7 +142,7 @@ Other notable changes:
``esphomeyaml.includes`` and ``esphomeyaml.platformio_options`` (:doc:`/components/esphome`) ``esphomeyaml.includes`` and ``esphomeyaml.platformio_options`` (:doc:`/components/esphome`)
- Saved a lot of flash space on ESP8266 boards. Previously, platformio would allocate about 1/4 of flash for SPIFFS, - Saved a lot of flash space on ESP8266 boards. Previously, platformio would allocate about 1/4 of flash for SPIFFS,
but esphomelib doesn't use that so now you have that as extra storage. Thanks `@brandond <http://github.com/brandond>` but esphomelib doesn't use that so now you have that as extra storage. Thanks `@brandond <http://github.com/brandond>`
- You can now use Home Assistant to get time in ESPHome, so no more need for SNTP. See :ref:`time`. - You can now use Home Assistant to get time in ESPHome, so no more need for SNTP. See :doc:`/components/time/index`.
Release 1.10.1 - January 13 Release 1.10.1 - January 13
--------------------------- ---------------------------

View File

@ -43,7 +43,7 @@ Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **ble_client_id** (**Required**, :ref:`config-id`): The ID of the BLE Client. - **ble_client_id** (**Required**, :ref:`config-id`): The ID of the BLE Client.
- **time_id** (*Optional*, :ref:`config-id`): The ID of a :ref:`Time Component <time>` which - **time_id** (*Optional*, :ref:`config-id`): The ID of a :doc:`/components/time/index` which
can be used to set the time on the BedJet device. can be used to set the time on the BedJet device.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to dispatch status - **update_interval** (*Optional*, :ref:`config-time`): The interval to dispatch status
changes to child components. Defaults to ``5s``. Each child component can decide whether to changes to child components. Defaults to ``5s``. Each child component can decide whether to

View File

@ -48,7 +48,7 @@ Configuration variables:
------------------------ ------------------------
- **ble_client_id** (**Required**, :ref:`config-id`): ID of the associated BLE client. - **ble_client_id** (**Required**, :ref:`config-id`): ID of the associated BLE client.
- **time_id** (*Optional*, :ref:`config-id`): ID of a :doc:`/components/time` component. If set, the time will be synchronized with every connection. - **time_id** (*Optional*, :ref:`config-id`): ID of a :doc:`/components/time/index`. If set, the time will be synchronized with every connection.
- **disconnect_delay** (*Optional*, :ref:`config-time`): The amount of time the BLE connection is maintained before being disconnected again. Defaults to ``5s``. - **disconnect_delay** (*Optional*, :ref:`config-time`): The amount of time the BLE connection is maintained before being disconnected again. Defaults to ``5s``.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to transmit the display data. Defaults to ``60s``. - **update_interval** (*Optional*, :ref:`config-time`): The interval to transmit the display data. Defaults to ``60s``.
- **validity_period** (*Optional*, :ref:`config-time`): The time periode for which the pvvx device should display the information. Defaults to ``5min``. - **validity_period** (*Optional*, :ref:`config-time`): The time periode for which the pvvx device should display the information. Defaults to ``5min``.

View File

@ -40,13 +40,13 @@ in your configuration - only the RX pin should be necessary.
- platform: gps - platform: gps
The component is split up in platforms, by defining the GPS module The component is split up in platforms, by defining the GPS module
(as seen above). (as seen above).
In addition to retrieving GPS position data, the module can also be used as a In addition to retrieving GPS position data, the module can also be used as a
time platform to get the current date and time via the very accurate GPS clocks time platform to get the current date and time via the very accurate GPS clocks
without a network connection. without a network connection.
See :doc:`time` for config options for the GPS time source. See :doc:`time/gps` for config options for the GPS time source.
Configuration variables: Configuration variables:
------------------------ ------------------------

View File

@ -2,6 +2,7 @@ Components
========== ==========
.. toctree:: .. toctree::
:maxdepth: 3
:glob: :glob:
binary_sensor/index binary_sensor/index
@ -22,4 +23,5 @@ Components
lock/index lock/index
display_menu/index display_menu/index
media_player/index media_player/index
time/index
* *

View File

@ -0,0 +1,99 @@
DS1307 Time Source
==================
You first need to set up the :doc:`I2C </components/i2c>` component.
.. code-block:: yaml
# Example configuration entry
time:
- platform: ds1307
id: ds1307_time
Configuration variables
-----------------------
- **address** (*Optional*, int): Manually specify the I²C address of the RTC. Defaults to ``0x68``.
- All other options from :ref:`base_time_config`.
.. _ds1307-write_time_action:
``ds1307.write_time`` Action
----------------------------
This :ref:`Action <config-action>` triggers a synchronization of the current system time to the RTC hardware.
.. note::
The DS1307 component will *not* write the RTC clock if not triggered *explicitly* by this action.
.. code-block:: yaml
on_...:
- ds1307.write_time
# in case you need to specify the DS1307 id
- ds1307.write_time:
id: ds1307_time
.. _ds1307-read_time_action:
``ds1307.read_time`` Action
---------------------------
This :ref:`Action <config-action>` triggers a synchronization of the current system time from the RTC hardware.
.. note::
The DS1307 component will automatically read the RTC clock every 15 minutes by default and synchronize the
system clock when a valid timestamp was read from the RTC. (The ``update_interval`` can be changed.)
This action can be used to trigger *additional* synchronizations.
.. code-block:: yaml
on_...:
- ds1307.read_time
# in case you need to specify the DS1307 id
- ds1307.read_time:
id: ds1307_time
.. _ds1307-config_example:
Full Configuration Example
--------------------------
In a typical setup, you will have at least one additional time source to synchronize the RTC with. Such an
external time source might not always be available e.g. due to a limited network connection.
In order to have a valid, reliable system time, the system should read the RTC once at start and then try to
synchronize with an external reliable time source.
When a synchronization to another time source was successful, the RTC can be resynchronized.
.. code-block:: yaml
esphome:
on_boot:
then:
# read the RTC time once when the system boots
ds1307.read_time:
time:
- platform: ds1307
# repeated synchronization is not necessary unless the external RTC
# is much more accurate than the internal clock
update_interval: never
- platform: homeassistant
# instead try to synchronize via network repeatedly ...
on_time_sync:
then:
# ... and update the RTC when the synchronization was successful
ds1307.write_time:
See Also
--------
- :ghedit:`Edit`

23
components/time/gps.rst Normal file
View File

@ -0,0 +1,23 @@
GPS Time Source
===============
You first need to set up the :doc:`GPS </components/gps>` component.
.. code-block:: yaml
# Example configuration entry
time:
- platform: gps
id: gps_time
Configuration variables
-----------------------
- All options from :ref:`base_time_config`.
See Also
--------
- :ghedit:`Edit`

View File

@ -0,0 +1,24 @@
Home Assistant Time Source
==========================
The preferred way to get time in ESPHome is using Home Assistant.
With the ``homeassistant`` time platform, the :doc:`native API </components/api>` connection
to Home Assistant will be used to periodically synchronize the current time.
.. code-block:: yaml
# Example configuration entry
time:
- platform: homeassistant
id: homeassistant_time
Configuration variables
-----------------------
- All options from :ref:`base_time_config`.
See Also
--------
- :ghedit:`Edit`

View File

@ -1,7 +1,5 @@
.. _time: Time Component
==============
Time
====
.. seo:: .. seo::
:description: Instructions for setting up real time clock sources in ESPHome like network based time. :description: Instructions for setting up real time clock sources in ESPHome like network based time.
@ -57,7 +55,7 @@ This powerful automation can be used to run automations at specific intervals at
specific times of day. The syntax is a subset of the `crontab <https://crontab.guru/>`__ syntax. specific times of day. The syntax is a subset of the `crontab <https://crontab.guru/>`__ syntax.
There are two ways to specify time intervals: Either with using the ``seconds:``, ``minutes:``, ... There are two ways to specify time intervals: Either with using the ``seconds:``, ``minutes:``, ...
keys as seen below or using a cron alike expression like ``* /5 * * * *``. keys as seen below or using a cron alike expression like ``* /5 * * * *``.
Be aware normal cron implementations does not know about seconds like this esphome implementation, therefore you got 6 fields (seconds,minutes,hours,dayofmonth,month,dayofweek). Be aware normal cron implementations does not know about seconds like this esphome implementation, therefore you got 6 fields (seconds,minutes,hours,dayofmonth,month,dayofweek).
@ -199,156 +197,10 @@ to an external hardware real time clock chip.
the system time. Some (such as SNTP) could even trigger when another real time component is responsible for the the system time. Some (such as SNTP) could even trigger when another real time component is responsible for the
change in time. change in time.
Home Assistant Time Source
--------------------------
The preferred way to get time in ESPHome is using Home Assistant.
With the ``homeassistant`` time platform, the :doc:`native API </components/api>` connection
to Home Assistant will be used to periodically synchronize the current time.
.. code-block:: yaml
# Example configuration entry
time:
- platform: homeassistant
id: homeassistant_time
Configuration variables:
- All other from :ref:`base_time_config`.
SNTP Time Source
----------------
.. code-block:: yaml
# Example configuration entry
time:
- platform: sntp
id: sntp_time
Configuration variables:
- **servers** (*Optional*, list of strings): Choose up to 3 NTP servers that are used for the clock source.
Defaults to ``0.pool.ntp.org``, ``1.pool.ntp.org`` and ``2.pool.ntp.org``
- All other options from :ref:`base_time_config`.
.. note::
If your are using :ref:`wifi-manual_ip` make sure to configure a DNS Server (dns1, dns2) or use only IP addresses for the NTP servers.
.. warning::
Due to limitations of the SNTP implementation, this component will trigger ``on_time_sync`` only once when it detects that the
system clock has been set, even if the update was not done by the SNTP implementation!
This must be taken into consideration when SNTP is used together with other real time components, where another time source could
update the time before SNTP synchronizes.
GPS Time Source
---------------
You first need to set up the :doc:`GPS </components/gps>` component.
.. code-block:: yaml
# Example configuration entry
time:
- platform: gps
id: gps_time
Configuration variables:
- All other from :ref:`base_time_config`.
DS1307 Time Source
------------------
You first need to set up the :doc:`I2C </components/i2c>` component.
.. code-block:: yaml
# Example configuration entry
time:
- platform: ds1307
id: ds1307_time
Configuration variables:
- **address** (*Optional*, int): Manually specify the I²C address of the RTC. Defaults to ``0x68``.
- All other options from :ref:`base_time_config`.
.. _ds1307-write_time_action:
``ds1307.write_time`` Action
****************************
This :ref:`Action <config-action>` triggers a synchronization of the current system time to the RTC hardware.
.. note::
The DS1307 component will *not* write the RTC clock if not triggered *explicitly* by this action.
.. code-block:: yaml
on_...:
- ds1307.write_time
# in case you need to specify the DS1307 id
- ds1307.write_time:
id: ds1307_time
.. _ds1307-read_time_action:
``ds1307.read_time`` Action
***************************
This :ref:`Action <config-action>` triggers a synchronization of the current system time from the RTC hardware.
.. note::
The DS1307 component will automatically read the RTC clock every 15 minutes by default and synchronize the
system clock when a valid timestamp was read from the RTC. (The ``update_interval`` can be changed.)
This action can be used to trigger *additional* synchronizations.
.. code-block:: yaml
on_...:
- ds1307.read_time
# in case you need to specify the DS1307 id
- ds1307.read_time:
id: ds1307_time
.. _ds1307-config_example:
Configuration Example
*********************
In a typical setup, you will have at least one additional time source to synchronize the RTC with. Such an
external time source might not always be available e.g. due to a limited network connection.
In order to have a valid, reliable system time, the system should read the RTC once at start and then try to
synchronize with an external reliable time source.
When a synchronization to another time source was successful, the RTC can be resynchronized.
.. code-block:: yaml
esphome:
on_boot:
then:
# read the RTC time once when the system boots
ds1307.read_time:
time:
- platform: ds1307
# repeated synchronization is not necessary unless the external RTC
# is much more accurate than the internal clock
update_interval: never
- platform: homeassistant
# instead try to synchronize via network repeatedly ...
on_time_sync:
then:
# ... and update the RTC when the synchronization was successful
ds1307.write_time:
Use In Lambdas Use In Lambdas
-------------- --------------
@ -475,3 +327,9 @@ See Also
- :apiref:`time/real_time_clock.h` - :apiref:`time/real_time_clock.h`
- :ghedit:`Edit` - :ghedit:`Edit`
.. toctree::
:maxdepth: 1
:glob:
*

34
components/time/sntp.rst Normal file
View File

@ -0,0 +1,34 @@
SNTP Time Source
================
.. code-block:: yaml
# Example configuration entry
time:
- platform: sntp
id: sntp_time
Configuration variables
-----------------------
- **servers** (*Optional*, list of strings): Choose up to 3 NTP servers that are used for the clock source.
Defaults to ``0.pool.ntp.org``, ``1.pool.ntp.org`` and ``2.pool.ntp.org``
- All other options from :ref:`base_time_config`.
.. note::
If your are using :ref:`wifi-manual_ip` make sure to configure a DNS Server (dns1, dns2) or use only IP addresses for the NTP servers.
.. warning::
Due to limitations of the SNTP implementation, this component will trigger ``on_time_sync`` only once when it detects that the
system clock has been set, even if the update was not done by the SNTP implementation!
This must be taken into consideration when SNTP is used together with other real time components, where another time source could
update the time before SNTP synchronizes.
See Also
--------
- :ghedit:`Edit`

View File

@ -66,7 +66,7 @@ Configuration variables:
------------------------ ------------------------
- **time_id** (*Optional*, :ref:`config-id`): Some Tuya devices support obtaining local time from ESPHome. - **time_id** (*Optional*, :ref:`config-id`): Some Tuya devices support obtaining local time from ESPHome.
Specify the ID of the :ref:`Time Component <time>` which will be used. Specify the ID of the :doc:`time/index` which will be used.
- **status_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): Some Tuya devices support WiFi status reporting ONLY through gpio pin. - **status_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): Some Tuya devices support WiFi status reporting ONLY through gpio pin.
Specify the pin reported in the config dump or leave empty otherwise. Specify the pin reported in the config dump or leave empty otherwise.

View File

@ -645,6 +645,17 @@ Media Player Components
Media Player Core, components/media_player/index, folder-open.svg Media Player Core, components/media_player/index, folder-open.svg
I2S Audio, components/media_player/i2s_audio, i2s_audio.svg I2S Audio, components/media_player/i2s_audio, i2s_audio.svg
Time Components
---------------
.. imgtable::
Time Core, components/time/index, clock-outline.svg
Home Assistant Time, components/time/homeassistant, home-assistant.svg
SNTP, components/time/sntp, clock-outline.svg
GPS Time, components/time/gps, crosshairs-gps.svg
DS1307 RTC, components/time/ds1307, clock-outline.svg
Misc Components Misc Components
--------------- ---------------
@ -658,7 +669,6 @@ Misc Components
HTTP Request, components/http_request, connection.svg HTTP Request, components/http_request, connection.svg
mDNS, components/mdns, radio-tower.svg mDNS, components/mdns, radio-tower.svg
Time, components/time, clock-outline.svg
Sun, components/sun, weather-sunny.svg Sun, components/sun, weather-sunny.svg
GPS, components/gps, crosshairs-gps.svg GPS, components/gps, crosshairs-gps.svg