esphome-docs/guides/configuration-types.rst

217 lines
5.9 KiB
ReStructuredText
Raw Normal View History

2018-05-13 11:37:02 +02:00
Configuration Types
===================
2018-11-14 22:12:27 +01:00
.. seo::
2019-02-16 23:25:23 +01:00
:description: Documentation of different configuration types in ESPHome
:image: settings.png
2018-11-14 22:12:27 +01:00
2019-02-16 23:25:23 +01:00
ESPHomes configuration files have several configuration types. This
2018-05-13 11:37:02 +02:00
page describes them.
2018-06-01 18:10:00 +02:00
.. _config-id:
2018-05-13 11:37:02 +02:00
ID
2018-10-12 16:33:22 +02:00
--
2018-05-13 11:37:02 +02:00
2019-02-16 23:25:23 +01:00
Quite an important aspect of ESPHome are “ids”. They are used to
2018-05-13 11:37:02 +02:00
connect components from different domains. For example, you define an
output component together with an id and then later specify that same id
in the light component. IDs should always be unique within a
2019-02-16 23:25:23 +01:00
configuration and ESPHome will warn you if you try to use the same
2018-05-13 11:37:02 +02:00
ID twice.
2019-02-16 23:25:23 +01:00
Because ESPHome converts your configuration into C++ code and the
2018-05-13 11:37:02 +02:00
ids are in reality just C++ variable names, they must also adhere to
C++s naming conventions. `C++ Variable
names <https://venus.cs.qc.cuny.edu/~krishna/cs111/lectures/D3_C++_Variables.pdf>`__
2018-05-13 11:37:02 +02:00
- … must start with a letter and can end with numbers.
- … must not have a space in the name.
- … can not have special characters except the underscore (“_“).
- … must not be a keyword.
2018-06-01 18:10:00 +02:00
.. _config-pin:
2018-05-13 11:37:02 +02:00
Pin
2018-10-12 16:33:22 +02:00
---
2018-05-13 11:37:02 +02:00
2019-02-16 23:25:23 +01:00
ESPHome always uses the **chip-internal GPIO numbers**. These
2018-05-13 11:37:02 +02:00
internal numbers are always integers like ``16`` and can be prefixed by
``GPIO``. For example to use the pin with the **internal** GPIO number 16,
you could type ``GPIO16`` or just ``16``.
Most boards however have aliases for certain pins. For example the NodeMCU
ESP8266 uses pin names ``D0`` through ``D8`` as aliases for the internal GPIO
2019-02-16 23:25:23 +01:00
pin numbers. Each board (defined in :doc:`ESPHome section </components/esphome>`)
2018-05-13 11:37:02 +02:00
has their own aliases and so not all of them are supported yet. For example,
for the ``D0`` (as printed on the PCB silkscreen) pin on the NodeMCU ESP8266
has the internal GPIO name ``GPIO16``, but also has an alias ``D0``. So using
either one of these names in your configuration will lead to the same result.
.. code-block:: yaml
2018-05-13 11:37:02 +02:00
some_config_option:
pin: GPIO16
some_config_option:
# alias on the NodeMCU ESP8266:
pin: D0
2018-06-01 18:10:00 +02:00
.. _config-pin_schema:
2018-05-13 11:37:02 +02:00
Pin Schema
2018-10-12 16:33:22 +02:00
----------
2018-05-13 11:37:02 +02:00
2019-02-16 23:25:23 +01:00
In some places, ESPHome also supports a more advanced “pin schema”.
2018-05-13 11:37:02 +02:00
.. code-block:: yaml
2018-05-13 11:37:02 +02:00
some_config_option:
# Basic:
pin: D0
# Advanced:
pin:
number: D0
inverted: True
mode: INPUT_PULLUP
Configuration variables:
- **number** (**Required**, pin): The pin number.
- **inverted** (*Optional*, boolean): If all read and written values
should be treated as inverted. Defaults to ``False``.
- **mode** (*Optional*, string): A pin mode to set for the pin at
startup, corresponds to Arduinos ``pinMode`` call.
Available Pin Modes:
- ``INPUT``
- ``OUTPUT``
- ``OUTPUT_OPEN_DRAIN``
2018-05-14 21:15:49 +02:00
- ``ANALOG`` (only on ESP32)
- ``INPUT_PULLUP``
- ``INPUT_PULLDOWN`` (only on ESP32)
- ``INPUT_PULLDOWN_16`` (only on ESP8266 and only on GPIO16)
More exotic Pin Modes are also supported, but rarely used:
2018-05-13 11:37:02 +02:00
- ``WAKEUP_PULLUP`` (only on ESP8266)
- ``WAKEUP_PULLDOWN`` (only on ESP8266)
- ``SPECIAL``
- ``FUNCTION_0`` (only on ESP8266)
- ``FUNCTION_1``
- ``FUNCTION_2``
- ``FUNCTION_3``
- ``FUNCTION_4``
- ``FUNCTION_5`` (only on ESP32)
- ``FUNCTION_6`` (only on ESP32)
2018-06-01 18:10:00 +02:00
.. _config-time:
2018-05-13 11:37:02 +02:00
Time
2018-10-12 16:33:22 +02:00
----
2018-05-13 11:37:02 +02:00
2019-02-16 23:25:23 +01:00
In lots of places in ESPHome you need to define time periods.
2018-05-14 21:15:49 +02:00
There are several ways of doing this. See below examples to see how you can specify time periods:
2018-05-13 11:37:02 +02:00
.. code-block:: yaml
2018-05-13 11:37:02 +02:00
some_config_option:
2018-05-14 21:15:49 +02:00
some_time_option: 1000us # 1000 microseconds = 1ms
2018-05-13 11:37:02 +02:00
some_time_option: 1000ms # 1000 milliseconds
some_time_option: 1.5s # 1.5 seconds
some_time_option: 0.5min # half a minute
some_time_option: 2h # 2 hours
2018-06-07 23:12:51 +02:00
# Make sure you wrap these in quotes
some_time_option: '2:01' # 2 hours 1 minute
some_time_option: '2:01:30' # 2 hours 1 minute 30 seconds
2018-05-14 21:15:49 +02:00
# 10ms + 30s + 25min + 3h
some_time_option:
2018-05-13 11:37:02 +02:00
milliseconds: 10
seconds: 30
minutes: 25
hours: 3
days: 0
2018-06-01 18:10:00 +02:00
2018-08-24 22:44:01 +02:00
# for all 'update_interval' options, also
update_interval: never # never update
update_interval: 0ms # update in every loop() iteration
2018-12-01 09:46:37 +01:00
.. _config-substitutions:
Substitutions
-------------
2019-02-16 23:25:23 +01:00
Starting with version 1.10.0, ESPHome has a powerful new way to reduce repetition in configuration files:
2019-01-06 18:56:14 +01:00
Substitutions. With substitutions, you can have a single generic source file for all nodes of one kind and
substitute expressions in.
2018-12-01 09:46:37 +01:00
.. code-block:: yaml
substitutions:
devicename: livingroom
2019-01-06 18:56:14 +01:00
upper_devicename: Livingroom
2018-12-01 09:46:37 +01:00
2019-02-16 23:25:23 +01:00
esphome:
name: $devicename
2018-12-01 09:46:37 +01:00
# ...
2019-01-06 18:56:14 +01:00
sensor:
- platform: dht
# ...
temperature:
name: ${upper_devicename} Temperature
humidity:
name: ${upper_devicename} Humidity
In the top-level ``substitutions`` section, you can put as many key-value pairs as you want. Before
2019-02-16 23:25:23 +01:00
validating your configuration, ESPHome will automatically replace all occurrences of substitutions
2019-01-06 18:56:14 +01:00
by their value. The syntax for a substitution is based on bash and is case-sensitive: ``$substitution_key`` or
2019-02-16 23:25:23 +01:00
``${substitution_key}`` (same).
Additionally, you can use the YAML ``<<`` 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: ${upper_devicename} Temperature
humidity:
name: ${upper_devicename} Humidity
.. code-block:: yaml
# In nodemcu1.yaml
substitutions:
devicename: nodemcu1
upper_devicename: NodeMCU 1
<<: !include common.yaml
2018-12-01 09:46:37 +01:00
2019-03-17 20:45:03 +01:00
.. tip::
To hide these base files from the dashboard, you can
- Place them in a subdirectory (dashboard only shows files in top-level dir)
- Prepend a dot to the filename, like ``.base.yaml``
2018-06-01 18:10:00 +02:00
See Also
2018-10-12 16:33:22 +02:00
--------
2018-06-01 18:10:00 +02:00
- :doc:`ESPHome index </index>`
2018-06-01 18:10:00 +02:00
- :doc:`getting_started_command_line`
- :doc:`faq`
- :ghedit:`Edit`