mirror of
https://github.com/esphome/esphome-docs.git
synced 2024-12-24 17:08:15 +01:00
Restructure time docs into its own folder and split (#2566)
This commit is contained in:
Jesse Hills
GitHub
parent
22d9e6c4bc
commit
150d149d60
@ -142,7 +142,7 @@ Other notable changes:
|
||||
``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,
|
||||
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
|
||||
---------------------------
|
||||
|
||||
@ -43,7 +43,7 @@ Configuration variables:
|
||||
|
||||
- **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.
|
||||
- **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.
|
||||
- **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
|
||||
|
||||
@ -48,7 +48,7 @@ Configuration variables:
|
||||
------------------------
|
||||
|
||||
- **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``.
|
||||
- **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``.
|
||||
|
||||
@ -40,13 +40,13 @@ in your configuration - only the RX pin should be necessary.
|
||||
- platform: gps
|
||||
|
||||
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
|
||||
time platform to get the current date and time via the very accurate GPS clocks
|
||||
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
|
||||
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:
|
||||
------------------------
|
||||
|
||||
@ -2,6 +2,7 @@ Components
|
||||
==========
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 3
|
||||
:glob:
|
||||
|
||||
binary_sensor/index
|
||||
@ -22,4 +23,5 @@ Components
|
||||
lock/index
|
||||
display_menu/index
|
||||
media_player/index
|
||||
time/index
|
||||
*
|
||||
|
||||
99
components/time/ds1307.rst
Normal file
99
components/time/ds1307.rst
Normal 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
23
components/time/gps.rst
Normal 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`
|
||||
24
components/time/homeassistant.rst
Normal file
24
components/time/homeassistant.rst
Normal 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`
|
||||
@ -1,7 +1,5 @@
|
||||
.. _time:
|
||||
|
||||
Time
|
||||
====
|
||||
Time Component
|
||||
==============
|
||||
|
||||
.. seo::
|
||||
: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.
|
||||
|
||||
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).
|
||||
|
||||
@ -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
|
||||
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
|
||||
--------------
|
||||
@ -475,3 +327,9 @@ See Also
|
||||
|
||||
- :apiref:`time/real_time_clock.h`
|
||||
- :ghedit:`Edit`
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:glob:
|
||||
|
||||
*
|
||||
34
components/time/sntp.rst
Normal file
34
components/time/sntp.rst
Normal 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`
|
||||
@ -66,7 +66,7 @@ Configuration variables:
|
||||
------------------------
|
||||
|
||||
- **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.
|
||||
Specify the pin reported in the config dump or leave empty otherwise.
|
||||
|
||||
12
index.rst
12
index.rst
@ -645,6 +645,17 @@ Media Player Components
|
||||
Media Player Core, components/media_player/index, folder-open.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
|
||||
---------------
|
||||
|
||||
@ -658,7 +669,6 @@ Misc Components
|
||||
HTTP Request, components/http_request, connection.svg
|
||||
mDNS, components/mdns, radio-tower.svg
|
||||
|
||||
Time, components/time, clock-outline.svg
|
||||
Sun, components/sun, weather-sunny.svg
|
||||
GPS, components/gps, crosshairs-gps.svg
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user