esphome-docs/components/substitutions.rst

163 lines
4.0 KiB
ReStructuredText
Raw Normal View History

Substitutions
=============
.. seo::
:description: How to use substitutions in ESPHome
:image: settings.svg
ESPHome has a powerful way to reduce repetition in configuration files: substitutions.
With substitutions, you can have a single generic source file for all nodes of one kind and
substitute expressions in as required.
.. code-block:: yaml
substitutions:
bme280_temperature_offset: "-1.0"
sensor:
- platform: bme280_i2c
temperature:
name: BME280 Temperature
filters:
- offset: ${bme280_temperature_offset}
In the top-level ``substitutions`` section, you can put as many key-value pairs as you want. Before
validating your configuration, ESPHome will automatically replace all occurrences of substitutions
by their value. The syntax for a substitution is based on bash and is case-sensitive: ``$substitution_key`` or
``${substitution_key}`` (same).
Two substitution passes are performed allowing compound replacements.
.. code-block:: yaml
substitutions:
foo: yellow
bar_yellow_value: !secret yellow_secret
bar_green_value: !secret green_secret
something:
test: ${bar_${foo}_value}
.. _substitute-include-variables:
Substitute !include variables
-----------------------------
ESPHome's ``!include`` accepts a list of variables that can be substituted within the included file.
.. code-block:: yaml
binary_sensor:
- platform: gpio
id: button1
pin: GPIOXX
on_multi_click: !include { file: on-multi-click.yaml, vars: { id: 1 } } # inline syntax
- platform: gpio
id: button2
pin: GPIOXX
on_multi_click: !include
# multi-line syntax
file: on-multi-click.yaml
vars:
id: 2
``on-multi-click.yaml``:
.. code-block:: yaml
- timing: !include click-single.yaml
then:
- mqtt.publish:
topic: ${device_name}/button${id}/status
payload: single
- timing: !include click-double.yaml
then:
- mqtt.publish:
topic: ${device_name}/button${id}/status
payload: double
.. _command-line-substitutions:
Command line substitutions
--------------------------
You can define or override substitutions from the command line by adding the ``-s`` switch with arguments ``KEY`` and
``VALUE``. This will override the substitution ``KEY`` and assign it the value ``VALUE``. This switch can be included
multiple times. Consider the following ``example.yaml`` file:
.. code-block:: yaml
substitutions:
name: my_default_name
esphome:
name: $name
...and the following command:
.. code-block:: bash
esphome -s name my_device01 config example.yaml
You will get something like the following output:
.. code-block:: yaml
substitutions:
name: my_device01
esphome:
name: my_device01
# ...
Command line substitutions take precedence over those in your configuration file. This can be used to create generic
"template" configuration files (like ``example.yaml`` above) which can be used by multiple devices, leveraging
substitutions which are provided on the command line.
.. _YAML-insertion-operator:
Bonus: YAML insertion operator
------------------------------
Additionally, you can use the YAML insertion operator ``<<`` syntax to create a single YAML file from which a number
of nodes inherit:
.. code-block:: yaml
# In common.yaml
esphome:
name: $devicename
# ...
sensor:
- platform: dht
# ...
temperature:
name: Temperature
humidity:
name: Humidity
.. code-block:: yaml
# In nodemcu1.yaml
substitutions:
devicename: nodemcu1
<<: !include common.yaml
.. tip::
To hide these base files from the dashboard, you can
- Place them in a subdirectory (dashboard only shows files in top-level directory)
- Prepend a dot to the filename, like ``.base.yaml``
See Also
--------
- :doc:`ESPHome index </index>`
- :doc:`/guides/getting_started_command_line`
- :doc:`/guides/faq`
- :ghedit:`Edit`