esphome-docs/esphomeyaml/guides/configuration-types.rst

Configuration Types
===================

.. seo::
    :description: Documentation of different configuration types in esphomelib
    :image: settings.png

esphomeyaml’s configuration files have several configuration types. This
page describes them.

.. _config-id:

ID
--

Quite an important aspect of esphomeyaml are “ids”. They are used to
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
configuration and esphomeyaml will warn you if you try to use the same
ID twice.

Because esphomeyaml converts your configuration into C++ code and the
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>`__
…

-  … 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.

.. _config-pin:

Pin
---

esphomeyaml always uses the **chip-internal GPIO numbers**. These
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
pin numbers. Each board (defined in :doc:`esphomeyaml section </esphomeyaml/components/esphomeyaml>`)
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

    some_config_option:
      pin: GPIO16

    some_config_option:
      # alias on the NodeMCU ESP8266:
      pin: D0

.. _config-pin_schema:

Pin Schema
----------

In some places, esphomeyaml also supports a more advanced “pin schema”.

.. code-block:: yaml

    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 Arduino’s ``pinMode`` call.

Available Pin Modes:

-  ``INPUT``
-  ``OUTPUT``
-  ``OUTPUT_OPEN_DRAIN``
-  ``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:

-  ``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)

.. _config-time:

Time
----

In lots of places in esphomeyaml you need to define time periods.
There are several ways of doing this. See below examples to see how you can specify time periods:

.. code-block:: yaml

    some_config_option:
      some_time_option: 1000us  # 1000 microseconds = 1ms
      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

      # 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

      # 10ms + 30s + 25min + 3h
      some_time_option:
        milliseconds: 10
        seconds: 30
        minutes: 25
        hours: 3
        days: 0

      # for all 'update_interval' options, also
      update_interval: never  # never update
      update_interval: 0ms  # update in every loop() iteration

.. _config-substitutions:

Substitutions
-------------

If you're using many ESPs in your home and have many similar configuration files, it can
be cumbersome to keep all files up to date. There are already some ways to minimize
repeating yourself in the configuration using the ``!include`` and ``!secret`` YAML
directives.

If you want to go one step further and reduce duplication even further, you can use
``substitutions`` in esphomeyaml's config. Substitutions allow you define top-level
variables which are then replaced everywhere in your configuration which are then
substituted with their value using the bash-style ``${}`` syntax.

.. code-block:: yaml

    substitutions:
      devicename: livingroom

    esphomeyaml:
      name: $devicename
      # ...

    switch:
    - platform: ...
      name: ${devicename} switch

See Also
--------

- :doc:`esphomeyaml index </esphomeyaml/index>`
- :doc:`getting_started_command_line`
- :doc:`faq`
- `Edit this page on GitHub <https://github.com/OttoWinter/esphomedocs/blob/current/esphomeyaml/guides/configuration-types.rst>`__

.. disqus::