375 lines
15 KiB
ReStructuredText
375 lines
15 KiB
ReStructuredText
ESPHome Core Configuration
|
|
==========================
|
|
|
|
.. seo::
|
|
:description: Instructions for setting up the core ESPHome configuration.
|
|
:image: cloud-circle.svg
|
|
|
|
Here you specify some core information that ESPHome needs to create
|
|
firmwares. Most importantly, this is the section of the configuration
|
|
where you specify the **name** of the node.
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration entry
|
|
esphome:
|
|
name: livingroom
|
|
comment: Living room ESP32 controller
|
|
area: Living Room
|
|
|
|
esp32:
|
|
board: nodemcu-32s
|
|
|
|
.. _esphome-configuration_variables:
|
|
|
|
Configuration variables:
|
|
------------------------
|
|
|
|
- **name** (**Required**, string): This is the name of the node. It
|
|
should always be unique in your ESPHome network. May only contain lowercase
|
|
characters, digits and hyphens, and can be at most 24 characters long by default, or 31
|
|
characters long if ``name_add_mac_suffix`` is ``false``.
|
|
See :ref:`esphome-changing_node_name`.
|
|
- **friendly_name** (*Optional*, string): This is the name sent to the frontend. It is used
|
|
by Home Assistant as the integration name, device name, and is automatically prefixed to entities
|
|
where necessary.
|
|
- **area** (*Optional*, string): This is the area sent to the frontend. It is used
|
|
by Home Assistant as the area / zone which the node belongs to.
|
|
|
|
Advanced options:
|
|
|
|
- **build_path** (*Optional*, string): Customize where ESPHome will store the build files
|
|
for your node. By default, ESPHome puts the PlatformIO project it uses to build the
|
|
firmware in the ``.esphome/build/<NODE>`` (or into path from ``ESPHOME_BUILD_PATH`` environment variable if specified) directory,
|
|
but you can customize this behavior using this option. Official docker image automatically use `/build` folder
|
|
as default one in case it is mounted to it.
|
|
- **platformio_options** (*Optional*, mapping): Additional options to pass over to PlatformIO in the
|
|
platformio.ini file. See :ref:`esphome-platformio_options`.
|
|
- **includes** (*Optional*, list of files): A list of C/C++ files to include in the main (auto-generated) sketch file
|
|
for custom components. The paths in this list are relative to the directory where the YAML configuration file
|
|
is in. See :ref:`esphome-includes`.
|
|
- **libraries** (*Optional*, list of libraries): A list of libraries to include in the project. See
|
|
:ref:`esphome-libraries`.
|
|
- **comment** (*Optional*, string): Additional text information about this node. Only for display in UI.
|
|
- **name_add_mac_suffix** (*Optional*, boolean): Appends the last 3 bytes of the mac address of the device to
|
|
the name in the form ``<name>-aabbcc``. Defaults to ``false``.
|
|
See :ref:`esphome-mac_suffix`.
|
|
- **project** (*Optional*): ESPHome Creator's Project information. See :ref:`esphome-creators_project`.
|
|
|
|
- **name** (**Required**, string): Name of the project
|
|
- **version** (**Required**, string): Version of the project
|
|
- **on_update** (*Optional*, :ref:`Automation <automation>`): An automation to perform when the device firmware is updated.
|
|
This compares the above ``version`` field with the ``version`` that was in the previous firmware
|
|
as long as the ``name`` matches.
|
|
The ``version`` is stored in flash memory when the firmware is first run for future comparisons.
|
|
- **min_version** (*Optional*, string): The minimum ESPHome version required to compile this configuration.
|
|
See :ref:`esphome-min_version`.
|
|
- **compile_process_limit** (*Optional*, int): The maximum number of simultaneous compile processes to run.
|
|
Defaults to the number of cores of the CPU which is also the maximum you can set.
|
|
|
|
Old-style platform options, which have been moved to the platform-specific :doc:`esp32 </components/esp32>` and
|
|
:doc:`esp8266 </components/esp8266>` sections but are still accepted here for compatibility reasons (usage not
|
|
recommended for new projects):
|
|
|
|
- **platform** (**Required**, string): The platform used, either ``esp8266`` or ``esp32``.
|
|
- **board** (**Required**, string): The board used, see
|
|
:doc:`esp32 </components/esp32>` and :doc:`esp8266 </components/esp8266>` for more information.
|
|
- **arduino_version** (*Optional*, string): The version of the Arduino framework to compile the project against.
|
|
- **esp8266_restore_from_flash** (*Optional*, boolean): For ESP8266s, whether to store some persistent preferences in flash
|
|
memory.
|
|
|
|
Automations:
|
|
|
|
- **on_boot** (*Optional*, :ref:`Automation <automation>`): An automation to perform
|
|
when the node starts. See :ref:`esphome-on_boot`.
|
|
- **on_shutdown** (*Optional*, :ref:`Automation <automation>`): An automation to perform
|
|
right before the node shuts down. See :ref:`esphome-on_shutdown`.
|
|
- **on_loop** (*Optional*, :ref:`Automation <automation>`): An automation to perform
|
|
on each ``loop()`` iteration. See :ref:`esphome-on_loop`.
|
|
|
|
.. _esphome-on_boot:
|
|
|
|
``on_boot``
|
|
-----------
|
|
|
|
This automation will be triggered when the ESP boots up. By default, it is executed after everything else
|
|
is already set up. You can however change this using the ``priority`` parameter.
|
|
|
|
.. code-block:: yaml
|
|
|
|
esphome:
|
|
# ...
|
|
on_boot:
|
|
priority: 600
|
|
# ...
|
|
then:
|
|
- switch.turn_off: switch_1
|
|
|
|
Configuration variables:
|
|
|
|
- **priority** (*Optional*, float): The priority to execute your custom initialization code. A higher value
|
|
means a high priority and thus also your code being executed earlier. Please note this is an ESPHome-internal
|
|
value and any change will not be marked as a breaking change. Defaults to ``600``. Priorities (you can use any value between them too):
|
|
|
|
- ``800.0``: This is where all hardware initialization of vital components is executed. For example setting switches
|
|
to their initial state.
|
|
- ``600.0``: This is where most sensors are set up.
|
|
- ``250.0``: At this priority, WiFi is initialized.
|
|
- ``200.0``: Network connections like MQTT/native API are set up at this priority.
|
|
- ``-100.0``: At this priority, pretty much everything should already be initialized.
|
|
|
|
- See :ref:`Automation <automation>`.
|
|
|
|
.. _esphome-on_shutdown:
|
|
|
|
``on_shutdown``
|
|
---------------
|
|
|
|
This automation will be triggered when the ESP is about to shut down. Shutting down is usually caused by
|
|
too many WiFi/MQTT connection attempts, Over-The-Air updates being applied or through the :doc:`deep_sleep`.
|
|
|
|
.. note::
|
|
|
|
It's not guaranteed that all components are in a connected state when this automation is triggered. For
|
|
example, the MQTT client may have already disconnected. For use-cases that require specific shutdown ordering, look at the ``priority`` parameter.
|
|
|
|
.. code-block:: yaml
|
|
|
|
esphome:
|
|
# ...
|
|
on_shutdown:
|
|
priority: 700
|
|
then:
|
|
- switch.turn_off: switch_1
|
|
|
|
Configuration variables:
|
|
|
|
- **priority** (*Optional*, float): The priority to execute your custom shutdown code. A higher value
|
|
means a high priority and in case of shutdown triggers that the code is executed **later**.
|
|
Priority is used primarily for the initialization order of components. Shutdowns for these components are handled in *reverse* order, such that e.g. sensors (600) are shutdown before the hardware components (800) they depend on.
|
|
Please note this is an ESPHome-internal value and any change will not be marked as a breaking change.
|
|
Defaults to ``600``. For priority values refer to the list in the :ref:`esphome-on_boot` section.
|
|
|
|
- See :ref:`Automation <automation>`.
|
|
|
|
.. _esphome-on_loop:
|
|
|
|
``on_loop``
|
|
-----------
|
|
|
|
This automation will be triggered on every ``loop()`` iteration (usually around every 16 milliseconds).
|
|
|
|
.. code-block:: yaml
|
|
|
|
esphome:
|
|
# ...
|
|
on_loop:
|
|
then:
|
|
# do something
|
|
|
|
.. _esphome-platformio_options:
|
|
|
|
``platformio_options``
|
|
----------------------
|
|
|
|
PlatformIO supports a number of options in its ``platformio.ini`` file. With the ``platformio_options``
|
|
parameter you can tell ESPHome what options to pass into the ``env`` section of the PlatformIO file
|
|
(note you can also do this by editing the ``platformio.ini`` file manually).
|
|
|
|
You can view a full list of PlatformIO options here: https://docs.platformio.org/en/latest/projectconf/section_env.html
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration entry
|
|
esphome:
|
|
# ...
|
|
platformio_options:
|
|
upload_speed: 115200
|
|
board_build.f_flash: 80000000L
|
|
|
|
.. _esphome-includes:
|
|
|
|
``includes``
|
|
------------
|
|
|
|
With ``includes`` you can include source files in the generated PlatformIO project.
|
|
All files declared with this option are copied to the project each time it is compiled.
|
|
|
|
You can always look at the generated PlatformIO project (``.esphome/build/<NODE>``) to see what
|
|
is happening - and if you want you can even copy the include files directly into the ``src/`` folder.
|
|
The ``includes`` option is only a helper option that does that for you.
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration entry
|
|
esphome:
|
|
# ...
|
|
includes:
|
|
- my_switch.h
|
|
|
|
This option behaves differently depending on what the included file is pointing at:
|
|
|
|
- If the include string is pointing at a directory, the entire directory tree is copied into the
|
|
src/ folder.
|
|
- If the include string points to a header file (.h, .hpp, .tcc), it is copied in the src/ folder
|
|
AND included in the ``main.cpp`` file. This way the lambda code can access it.
|
|
- If the include string points to a regular source file (.c, .cpp), it is copied in the src/ folder
|
|
AND compiled into the binary. This way implementation of classes and functions in header files can
|
|
be provided.
|
|
|
|
.. _esphome-libraries:
|
|
|
|
``libraries``
|
|
-------------
|
|
|
|
With the ``libraries`` option it is possible to include libraries in the PlatformIO project. These libraries will then
|
|
be compiled into the resulting firmware, and can be used in code from :ref:`lambdas <config-lambda>` and from
|
|
custom components.
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration entry
|
|
esphome:
|
|
# ...
|
|
libraries:
|
|
# a library from PlatformIO
|
|
- espressif/esp32-camera
|
|
|
|
# a library bundled with Arduino
|
|
- Wire
|
|
|
|
# use the git version of a library used by a component
|
|
- esphome/Improv=https://github.com/improv-wifi/sdk-cpp.git#v1.0.0
|
|
|
|
The most common usage of this option is to include third-party libraries that are available in the `PlatformIO registry
|
|
<https://platformio.org/lib>`__. They can be added by listing their name under this option. It is also possible to use
|
|
specific versions, or to fetch libraries from a file or git repository. ESPHome accepts the same syntax as the
|
|
`pio lib install <https://docs.platformio.org/en/latest/userguide/lib/cmd_install.html>`__ command.
|
|
|
|
Using ``<name>=<source>`` syntax, it is possible to override the version used for libraries that are automatically added
|
|
by one of ESPHome's components. This can be useful during development to make ESPHome use a custom fork of a library.
|
|
|
|
By default, ESPHome does not include any libraries into the project. This means that libraries that are bundled with
|
|
Arduino, such as ``Wire`` or ``EEPROM``, aren't available. If you need to use them, you should list them manually under
|
|
this option. If they are used by another library, they should be listed before the library that uses them.
|
|
|
|
.. _preferences-flash_write_interval:
|
|
|
|
Adjusting flash writes
|
|
------------------------
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration entry
|
|
preferences:
|
|
flash_write_interval: 1min
|
|
|
|
- **flash_write_interval** (*Optional*, :ref:`config-time`): Customize the frequency in which data is
|
|
flushed to the flash. This setting helps to prevent rapid changes to a component from being quickly
|
|
written to the flash and wearing it out. Defaults to ``1min``.
|
|
|
|
As all devices have a limited number of flash write cycles, this setting helps to reduce the number of flash writes
|
|
due to quickly changing components. In the past, when components such as ``light``, ``switch``, ``fan`` and ``globals``
|
|
were changed, the state was immediately committed to flash. The result of this was that the last state of these
|
|
components would always restore to its last state on power loss, however, this has the cost of potentially quickly
|
|
damaging the flash if these components are quickly changed.
|
|
|
|
A safety feature has thus been implemented to mitigate issues resulting from the limited number of flash write cycles,
|
|
the state is first stored in memory before being flushed to flash after the ``flash_write_interval`` has passed. This
|
|
results in fewer flash writes, preserving the flash health.
|
|
|
|
This behavior can be disabled by setting ``flash_write_interval`` to ``0s`` to immediately commit the state to flash,
|
|
however, be aware that this may lead to increased flash wearing and a shortened device lifespan!
|
|
|
|
For :doc:`ESP8266 </components/esp8266>`, ``restore_from_flash`` must also be set to ``true`` for states to be written to flash.
|
|
|
|
.. _esphome-changing_node_name:
|
|
|
|
Changing ESPHome Node Name
|
|
--------------------------
|
|
|
|
Trying to change the name of a node or its address in the network?
|
|
You can do so with the ``use_address`` option of the :doc:`WiFi configuration <wifi>`.
|
|
|
|
Change the device name or address in your YAML to the new value and additionally
|
|
set ``use_address`` to point to the old address like so:
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Step 1. Changing name from test8266 to kitchen
|
|
esphome:
|
|
name: kitchen
|
|
# ...
|
|
|
|
wifi:
|
|
# ...
|
|
use_address: test8266.local
|
|
|
|
Now upload the updated config to the device. As a second step, you now need to remove the
|
|
``use_address`` option from your configuration again so that subsequent uploads will work again
|
|
(otherwise it will try to upload to the old address).
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Step 2
|
|
esphome:
|
|
name: kitchen
|
|
# ...
|
|
|
|
wifi:
|
|
# ...
|
|
# Remove or comment out use_address
|
|
# use_address: test8266.local
|
|
|
|
The same procedure can be done for changing the static IP of a device.
|
|
|
|
|
|
.. _esphome-mac_suffix:
|
|
|
|
Adding the MAC address as a suffix to the device name
|
|
-----------------------------------------------------
|
|
|
|
Using ``name_add_mac_suffix`` allows :doc:`creators </guides/creators>` to
|
|
provision multiple devices at the factory with a single firmware and still
|
|
have unique identification for customer installs.
|
|
|
|
.. note::
|
|
|
|
End users will need to create an individual YAML config file if they want to OTA update the
|
|
devices in the future. Creators can facilitate this process by providing ``dashboard_import`` URL
|
|
for end users. This allows them to easily update their devices as new features are made available
|
|
upstream.
|
|
|
|
|
|
.. _esphome-creators_project:
|
|
|
|
Project information
|
|
-------------------
|
|
|
|
This allows creators to add the project name and version to the compiled code. It is currently only
|
|
exposed via the logger, mDNS and the device_info response via the native API. The format of the name
|
|
should be ``author_name.project_name``.
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration
|
|
esphome:
|
|
...
|
|
project:
|
|
name: "jesse.leds_party"
|
|
version: "1.0.0"
|
|
|
|
.. _esphome-min_version:
|
|
|
|
Minimum ESPHome version
|
|
-----------------------
|
|
|
|
This allows YAML files to specify the minimum version of ESPHome required to compile.
|
|
This is useful in the case of packages where a published package might use features only
|
|
available in a newer version of ESPHome. This allows for a more friendly error message.
|
|
|
|
See Also
|
|
--------
|
|
|
|
- :ghedit:`Edit`
|