Upstream/esphome-docs
1
0
Fork 0
mirror of https://github.com/esphome/esphome-docs.git synced 2025-04-08 19:05:59 +02:00
Code Issues Projects Releases Wiki Activity

Docs update

Browse Source
This commit is contained in:
Otto Winter 2019-05-12 22:44:59 +02:00
parent b2fe7220f3
commit 87147619c0
No known key found for this signature in database
GPG Key ID: DB66C0BE6013F97E
145 changed files with 1342 additions and 629 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.github/PULL_REQUEST_TEMPLATE.md vendored
View File

@ -4,7 +4,6 @@
**Related issue (if applicable):** fixes <link to issue>
**Pull request in [esphome](https://github.com/esphome/esphome) with YAML changes (if applicable):** esphome/esphome#<esphome PR number goes here>
**Pull request in [esphome-core](https://github.com/esphome/esphome-core) with C++ framework changes (if applicable):** esphome/esphome-core#<esphome-core PR number goes here>
## Checklist:

47
Doxygen
View File

@ -791,7 +791,7 @@ WARN_LOGFILE =
# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
# Note: If this tag is empty the current directory is searched.
INPUT = $(ESPHOME_CORE_PATH)/src
INPUT = $(ESPHOME_PATH)/esphome
# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@ -817,50 +817,9 @@ INPUT_ENCODING = UTF-8
# *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf and *.qsf.
FILE_PATTERNS = *.c \
*.cc \
*.cxx \
*.cpp \
*.c++ \
*.tcc \
*.java \
*.ii \
*.ixx \
*.ipp \
*.i++ \
*.inl \
*.idl \
*.ddl \
*.odl \
*.h \
*.hh \
*.hxx \
*.hpp \
*.h++ \
*.cs \
*.d \
*.php \
*.php4 \
*.php5 \
*.phtml \
*.inc \
*.m \
*.markdown \
*.md \
*.mm \
*.dox \
*.py \
*.pyw \
*.f90 \
*.f95 \
*.f03 \
*.f08 \
*.f \
*.for \
*.tcl \
*.vhd \
*.vhdl \
*.ucf \
*.qsf
*.h
# The RECURSIVE tag can be used to specify whether or not subdirectories should
# be searched for input files as well.
@ -908,7 +867,7 @@ EXCLUDE_SYMBOLS =
# that contain example code fragments that are included (see the \include
# command).
EXAMPLE_PATH = $(ESPHOME_CORE_PATH)/examples
EXAMPLE_PATH =
# If the value of the EXAMPLE_PATH tag contains directories, you can use the
# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and

16
Makefile
View File

@ -1,5 +1,5 @@
ESPHOME_CORE_PATH = ../esphome-core
ESPHOME_CORE_TAG = v1.12.2
ESPHOME_PATH = ../esphome
ESPHOME_REF = dev
.PHONY: html cleanhtml deploy help webserver Makefile netlify netlify-api api netlify-dependencies svg2png copy-svg2png
@ -17,17 +17,17 @@ help:
api:
mkdir -p _build/html/api
@if [ ! -d "$(ESPHOME_CORE_PATH)" ]; then \
git clone --branch $(ESPHOME_CORE_TAG) https://github.com/esphome/esphome-core.git $(ESPHOME_CORE_PATH); \
@if [ ! -d "$(ESPHOME_PATH)" ]; then \
git clone --branch $(ESPHOME_REF) https://github.com/esphome/esphome.git $(ESPHOME_PATH); \
fi
ESPHOME_CORE_PATH=$(ESPHOME_CORE_PATH) doxygen Doxygen
ESPHOME_PATH=$(ESPHOME_PATH) doxygen Doxygen
netlify-api: netlify-dependencies
mkdir -p _build/html/api
@if [ ! -d "$(ESPHOME_CORE_PATH)" ]; then \
git clone --branch $(ESPHOME_CORE_TAG) https://github.com/esphome/esphome-core.git $(ESPHOME_CORE_PATH); \
@if [ ! -d "$(ESPHOME_PATH)" ]; then \
git clone --branch $(ESPHOME_REF) https://github.com/esphome/esphome.git $(ESPHOME_PATH); \
fi
ESPHOME_CORE_PATH=$(ESPHOME_CORE_PATH) ../doxybin/doxygen Doxygen
ESPHOME_PATH=$(ESPHOME_PATH) ../doxybin/doxygen Doxygen
netlify-dependencies:
mkdir -p ../doxybin

20
components/api.rst
View File

@ -16,7 +16,7 @@ the device manually by clicking "CONFIGURE" on the ESPHome integration and enter
"<NODE_NAME>.local" as the address.
The ESPHome native API is based on a custom TCP protocol using protocol buffers. You can find
the protocol data structure definitions here: https://github.com/esphome/esphome-core/blob/dev/src/esphome/api/api.proto.
the protocol data structure definitions here: https://github.com/esphome/esphome/blob/dev/src/esphome/components/api/api.proto
A python library that implements this protocol can be found `here <https://github.com/esphome/aioesphomeapi>`__.
.. code-block:: yaml
@ -157,7 +157,6 @@ Configuration options:
- **variables** (*Optional*, mapping): Optional variables that can be used in the ``data_template``.
Values are :ref:`lambdas <config-lambda>` and will be evaluated before sending the request.
.. _api-services:
User-defined Services
@ -221,6 +220,23 @@ There are currently 4 types of variables:
- float: A floating point number. C++ type: ``float``
- string: A string. C++ type: ``std::string``
.. _api.connected_condition:
``api.connected`` Condition
---------------------------
This :ref:`Condition <config-condition>` checks if at least one client is connected to the ESPHome
native API.
.. code-block:: yaml
on_...:
if:
condition:
api.connected:
then:
- logger.log: API is connected!
Advantages over MQTT
--------------------

6
components/binary_sensor/esp32_ble_tracker.rst → components/binary_sensor/ble_presence.rst
View File

@ -5,7 +5,7 @@ ESP32 Bluetooth Low Energy Device
:description: Instructions for setting up BLE binary sensors for the ESP32.
:image: bluetooth.png
The ``esp32_ble_tracker`` binary sensor platform lets you track the presence of a
The ``ble_presence`` binary sensor platform lets you track the presence of a
bluetooth low energy device.
.. figure:: images/esp32_ble-ui.png
@ -19,7 +19,7 @@ bluetooth low energy device.
scan_interval: 300s
binary_sensor:
- platform: esp32_ble_tracker
- platform: ble_presence
mac_address: AC:37:43:77:5F:4C
name: "ESP32 BLE Tracker Google Home Mini"
@ -62,6 +62,6 @@ See Also
- :doc:`/components/esp32_ble_tracker`
- :doc:`/components/binary_sensor/index`
- :apiref:`esp32_ble_tracker.h`
- :apiref:`ble_presence/ble_presence.h`
- `ESP32 BLE for Arduino <https://github.com/nkolban/ESP32_BLE_Arduino>`__ by `Neil Kolban <https://github.com/nkolban>`__.
- :ghedit:`Edit`

5
components/binary_sensor/custom.rst
View File

@ -14,9 +14,8 @@ same as the gpio binary sensor.
.. code-block:: cpp
#include "esphome.h"
using namespace esphome;
class MyCustomBinarySensor : public PollingComponent, public binary_sensor::BinarySensor {
class MyCustomBinarySensor : public PollingComponent, public BinarySensor {
public:
// constructor
MyCustomBinarySensor() : PollingComponent(15000) {}
@ -64,7 +63,7 @@ Configuration variables:
- All options from :ref:`Binary Sensor <config-binary_sensor>`.
See :cpp:class:`binary_sensor::BinarySensor`
See :apiclass:`BinarySensor <binary_sensor::BinarySensor>`
See Also
--------

2
components/binary_sensor/esp32_touch.rst
View File

@ -155,6 +155,6 @@ See Also
--------
- :doc:`/components/binary_sensor/index`
- :apiref:`binary_sensor/esp32_touch_binary_sensor.h`
- :apiref:`esp32_touch/esp32_touch.h`
- `esp-idf Touch Sensor API <https://esp-idf.readthedocs.io/en/latest/api-reference/peripherals/touch_pad.html>`__
- :ghedit:`Edit`

2
components/binary_sensor/gpio.rst
View File

@ -98,5 +98,5 @@ See Also
- :doc:`/components/binary_sensor/index`
- :ref:`config-pin_schema`
- :apiref:`binary_sensor/gpio_binary_sensor.h`
- :apiref:`gpio/binary_sensor/gpio_binary_sensor.h`
- :ghedit:`Edit`

2
components/binary_sensor/homeassistant.rst
View File

@ -28,5 +28,5 @@ See Also
--------
- :ref:`automation`
- :apiref:`binary_sensor/homeassistant_binary_sensor.h`
- :apiref:`homeassistant/binary_sensor/homeassistant_binary_sensor.h`
- :ghedit:`Edit`

5
components/binary_sensor/index.rst
View File

@ -300,11 +300,6 @@ This :ref:`Condition <config-condition>` checks if the given binary sensor is ON
# Same syntax for is_off
binary_sensor.is_on: my_binary_sensor
# With duration, true if has been on for at least 5s
binary_sensor.is_on:
id: my_binary_sensor
for: 5s
.. _binary_sensor-lambda_calls:
lambda calls

2
components/binary_sensor/mpr121.rst
View File

@ -53,6 +53,6 @@ See Also
--------
- :ref:`sensor-filters`
- :apiref:`sensor/mpr121_sensor.h`
- :apiref:`mpr121/mpr121.h`
- `Adafruit MPR121 Library <https://github.com/adafruit/Adafruit_MPR121_Library>`__ by `Adafruit <https://www.adafruit.com/>`__
- :ghedit:`Edit`

2
components/binary_sensor/nextion.rst
View File

@ -38,5 +38,5 @@ See Also
- :doc:`/components/display/nextion`
- :doc:`index`
- :apiref:`display/nextion.h`
- :apiref:`nextion/nextion.h`
- :ghedit:`Edit`

2
components/binary_sensor/pn532.rst
View File

@ -142,5 +142,5 @@ See Also
- :doc:`index`
- :doc:`rdm6300`
- :apiref:`binary_sensor/pn532_component.h`
- :apiref:`pn532/pn532.h`
- :ghedit:`Edit`

24
components/binary_sensor/rdm6300.rst
View File

@ -46,8 +46,30 @@ Configuration variables:
- **uart_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`UART Component <uart>` if you want
to use multiple UART buses.
- **on_tag** (*Optional*, :ref:`Automation <automation>`): An automation to perform
when a tag is read. See :ref:`rdm6300-on_tag`.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID for this component.
.. _rdm6300-on_tag:
``on_tag``
----------
This automation will be triggered when the RDM6300 module responds with a tag.
The parameter ``x`` this trigger provides is of type ``uint32_t`` and is the tag UID as a 32-bit
unsigned integer.
.. code-block:: yaml
rdm6300:
# ...
on_tag:
then:
- mqtt.publish:
topic: rdm6300/tag
payload: !lambda 'return x;'
.. _rdm6300-tag:
NFC/RFID Tag
@ -104,5 +126,5 @@ See Also
- :doc:`pn532`
- :doc:`/components/binary_sensor/index`
- :apiref:`binary_sensor/rdm6300_component.h`
- :apiref:`rdm6300/rdm6300.h`
- :ghedit:`Edit`

2
components/binary_sensor/status.rst
View File

@ -31,5 +31,5 @@ See Also
- :doc:`/components/binary_sensor/index`
- :doc:`/components/mqtt`
- :apiref:`binary_sensor/status_binary_sensor.h`
- :apiref:`status/status_binary_sensor.h`
- :ghedit:`Edit`

2
components/binary_sensor/template.rst
View File

@ -90,5 +90,5 @@ See Also
- :doc:`/components/binary_sensor/index`
- :doc:`/components/sensor/template`
- :ref:`automation`
- :apiref:`binary_sensor/template_binary_sensor.h`
- :apiref:`template/binary_sensor/template_binary_sensor.h`
- :ghedit:`Edit`

5
components/binary_sensor/ttp229.rst
View File

@ -6,7 +6,7 @@ TTP229 Capacitive Touch Sensor
:image: ttp229.jpg
:keywords: TTP229
The ``ttp229`` sensor platform allows you to use your TTP229 `datasheet <https://www.tontek.com.tw/uploads/product/106/TTP229-LSF_V1.0_EN.pdf>`__
The ``ttp229_lsf`` sensor platform allows you to use your TTP229 `datasheet <https://www.tontek.com.tw/uploads/product/106/TTP229-LSF_V1.0_EN.pdf>`__
Capacitive Touch Sensor with ESPHome. The :ref:`I²C <i2c>` is required to be set up in your configuration for this sensor to work.
.. figure:: images/ttp229-full.jpg
@ -21,7 +21,6 @@ Capacitive Touch Sensor with ESPHome. The :ref:`I²C <i2c>` is required to be se
# Example configuration entry
ttp229_lsf:
id: ttp229_device
binary_sensor:
- platform: ttp229_lsf
@ -48,5 +47,5 @@ See Also
--------
- :ref:`sensor-filters`
- :apiref:`sensor/ttp229_sensor.h`
- :apiref:`ttp229_lsf/ttp229_lsf.h`
- :ghedit:`Edit`

97
components/climate/bang_bang.rst Normal file
View File

@ -0,0 +1,97 @@
Bang Bang Climate Controller
============================
.. seo::
:description: Instructions for setting up Bang Bang climate controllers with ESPHome.
:image: TODO.png
The ``bang_bang`` climate platform allows you to regulate a value with a
`bang-bang controller <https://en.wikipedia.org/wiki/Bang%E2%80%93bang_control>`__ (also called hysteresis controller).
The operation principle of a bang_bang controller is quite simple. First, you specify an observable
value (for example the temperature of a room). The controller will try to keep this observed value
in a defined range. To do this, the controller can activate objects like a heating unit to change
the observed value.
The range that the controller will try to keep the observed value in can be controlled through the
front-end with the ``target_temperature_low`` and ``target_temperature_high`` values (see screenshot below).
As soon as the observed temperature dips below or above this range it will activate one of the
defined actions ``cool_action``, ``heat_action`` and ``idle_action``.
There are three types of bang bang controllers this platform can represent:
- **Heaters**: For devices where the observed temperature can only be increased.
- As soon as the temperature goes below the lower target temperature, ``heat_action`` will be called.
- When the temperature goes above the higher temperature, ``idle_action`` will be called.
- **Coolers**: For devices where the observed temperature can only be decreased.
- As soon as the temperature goes above the higher target temperature, ``cool_action`` will be called.
- When the temperature goes below the lower temperature, ``idle_action`` will be called.
- **Heater+Cooler**: For devices where the temperature can both actively be increased and decreased.
- When the current temperature is below the lower target temperature, ``heat_action`` is called.
- When the current temperature is within the target temperature range, ``idle_action`` is called.
- When the current temperature is above the higher target temperature, ``cool_action`` is called.
Do note that the actions are only called when the current temperature leaves the target temperature range.
.. figure:: images/climate-ui.png
:align: center
:width: 60.0%
.. code-block:: yaml
# Example configuration entry
climate:
- platform: bang_bang
sensor: my_temperature_sensor
default_target_temperature_low: 20 °C
default_target_temperature_high: 22 °C
heat_action:
- switch.turn_on: heater
idle_action:
- switch.turn_off: heater
Configuration variables:
------------------------
- **sensor** (**Required**, :ref:`config-id`): The sensor that is used to measure the current temperature.
- **default_target_temperature_low** (**Required**, float): The default low target temperature for
the control algorithm. This can be dynamically set in the frontend later.
- **default_target_temperature_high** (**Required**, float): The default high target temperature for
the control algorithm. This can be dynamically set in the frontend later.
- **idle_action** (**Required**, :ref:`Action <config-action>`): The action to call when
the climate device wants to enter idle mode.
- **heat_action** (*Optional*, :ref:`Action <config-action>`): The action to call when
the climate device wants to heating mode and increase the current temperature. At least one
of ``heat_action`` and ``cool_action`` need to be specified.
- **cool_action** (*Optional*, :ref:`Action <config-action>`): The action to call when
the climate device wants to cooling mode and decrease the current temperature.
Advanced options:
- **away_config** (*Optional*): Additionally specify target temperature range settings for away mode.
Away mode can be used to have a second set of target temperatures (for example while the user is
away or during nighttime)
- **default_target_temperature_low** (**Required**, float): The default low target temperature for
the control algorithm during away mode.
- **default_target_temperature_high** (**Required**, float): The default high target temperature for
the control algorithm during away mode.
.. note::
While this platform uses the term temperature everywhere, it can also be used for other values.
For example, controlling humidity is also possible with this platform.
See Also
--------
- :doc:`/components/binary_sensor/index`
- :ref:`config-pin_schema`
- :apiref:`gpio/binary_sensor/gpio_binary_sensor.h`
- :ghedit:`Edit`

BIN
components/climate/images/climate-ui.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 12 KiB

130
components/climate/index.rst Normal file
View File

@ -0,0 +1,130 @@
Climate Component
=================
.. seo::
:description: Information about the base representation of all climate devices.
:image: folder-open.png
ESPHome has support for climate devices. Climate devices can represent different types of
hardware, but the defining factor is that climate devices have a settable target temperature
and can be put in different modes like HEAT, COOL, AUTO or OFF.
.. figure:: images/climate-ui.png
:align: center
:width: 60.0%
Climate Device UI in Home Assistant.
.. _config-climate:
Base Climate Configuration
--------------------------
All climate platforms in ESPHome inherit from the climate configuration schema.
.. code-block:: yaml
climate:
- platform: ...
visual:
min_temperature: 18 °C
max_temperature: 25 °C
temperature_step: 0.1 °C
Configuration variables:
- **visual** (*Optional*): Visual settings for the climate device - these do not
affect operation and are solely for controlling how the climate device shows up in the
frontend.
- **min_temperature** (*Optional*, float): The minimum temperature the climate device can reach.
Used to set the range of the frontend gauge.
- **max_temperature** (*Optional*, float): The maximum temperature the climate device can reach.
Used to set the range of the frontend gauge.
- **temperature_step** (*Optional*, float): The granularity with which the target temperature
can be controlled.
Advanced options:
- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will
not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without
a ``name`` will implicitly set this to true.
- If MQTT enabled, all other options from :ref:`MQTT Component <config-mqtt-component>`.
Climate Automation
------------------
.. _climate-control_action:
``climate.control`` Action
**************************
This is an :ref:`Action <config-action>` for setting parameters for climate devices.
.. code-block:: yaml
- climate.control:
id: my_climate
mode: AUTO
target_temperature: 25°C
Configuration variables:
- **id** (**Required**, :ref:`config-id`): The ID of the climate device to control.
- **mode** (*Optional*, string, :ref:`templatable <config-templatable>`): Put the climate device
in a specific mode. One of ``OFF``, ``AUTO``, ``COOL`` and ``HEAT``.
- **target_temperature** (*Optional*, float, :ref:`templatable <config-templatable>`): Set the
target temperature of a climate device.
- **target_temperature_low** (*Optional*, float, :ref:`templatable <config-templatable>`): Set the
lower target temperature of a climate device with a two-point target temperature.
- **target_temperature_high** (*Optional*, float, :ref:`templatable <config-templatable>`): Set the
higher target temperature of a climate device with a two-point target temperature.
- **away** (*Optional*, boolean, :ref:`templatable <config-templatable>`): Set the away mode
of the climate device.
.. _climate-lambda_calls:
lambda calls
************
From :ref:`lambdas <config-lambda>`, you can call several methods on all binary sensors to do some
advanced stuff.
- Attributes: All climate devices have read-only attributes to get the current state of the device.
.. code-block:: yaml
// Current mode, type: ClimateMode (enum)
id(my_climate).mode
// Current temperature, type: float (degrees)
id(my_climate).current_temperature
// Target temperature, type: float (degrees)
id(my_climate).target_temperature
// Lower Target temperature, type: float (degrees)
id(my_climate).target_temperature_low
// High Target temperature, type: float (degrees)
id(my_climate).target_temperature_high
// Away mode, type: bool
id(my_climate).away
- ``.make_call``: Control the climate device
.. code-block:: yaml
auto call = id(my_climate).make_call();
call.set_mode("OFF");
// etc. see API reference
call.perform();
See Also
--------
- :apiref:`climate/climate.h`
- :ghedit:`Edit`
.. toctree::
:maxdepth: 1
:glob:
*

72
components/cover/endstop.rst Normal file
View File

@ -0,0 +1,72 @@
Endstop Cover
=============
.. seo::
:description: Instructions for setting up time-based covers in ESPHome.
:image: TODO.png
The ``endstop`` cover platform allows you to create covers with position control that have
endstops at both ends of the cover to detect the fully-open and fully-closed states.
When any of these endstops are reached, the cover stops and sends out the corresponding state.
Additionally, open and close durations can be specified to allow ESPHome to approximate the
current position of the cover.
.. figure:: images/more-info-ui.png
:align: center
:width: 75.0%
.. code-block:: yaml
# Example configuration entry
cover:
- platform: endstop
name: "Endstop Cover"
open_action:
- switch.turn_on: open_cover_switch
open_duration: 2.1min
open_endstop: open_endstop_binary_sensor
close_action:
- switch.turn_on: close_cover_switch
close_duration: 2min
close_endstop: close_endstop_binary_sensor
stop_action:
- switch.turn_off: open_cover_switch
- switch.turn_off: close_cover_switch
Configuration variables:
------------------------
- **name** (**Required**, string): The name of the cover.
- **open_action** (**Required**, :ref:`Action <config-action>`): The action that should
be performed when the remote requests the cover to be opened.
- **open_duration** (**Required**, :ref:`config-time`): The amount of time it takes the cover
to open up from the fully-closed state.
- **open_endstop** (**Required**, :ref:`config-id`): The ID of the
:ref:`Binary Sensor <config-binary_sensor>` that turns on when the open position is reached.
- **close_action** (*Optional*, :ref:`Action <config-action>`): The action that should
be performed when the remote requests the cover to be closed.
- **close_duration** (**Required**, :ref:`config-time`): The amount of time it takes the cover
to close from the fully-open state.
- **close_endstop** (**Required**, :ref:`config-id`): The ID of the
:ref:`Binary Sensor <config-binary_sensor>` that turns on when the closed position is reached.
- **stop_action** (**Required**, :ref:`Action <config-action>`): The action that should
be performed when the remote requests the cover to be closed or an endstop is reached.
- **max_duration** (*Optional*, :ref:`config-time`): The maximum duration the cover should be opening
or closing. Useful for protecting from dysfunctional endstops.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- All other options from :ref:`Cover <config-cover>`.
See Also
--------
- :doc:`index`
- :ref:`automation`
- :apiref:`endstop/endstop_cover.h`
- :ghedit:`Edit`

BIN
components/cover/images/more-info-ui.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 10 KiB

93
components/cover/index.rst
View File

@ -9,12 +9,41 @@ The ``cover`` component is a generic representation of covers in ESPHome.
A cover can (currently) either be *closed* or *open* and supports three types of
commands: *open*, *close* and *stop*.
.. figure:: images/cover-ui.png
:align: center
:width: 75.0%
.. _config-cover:
Base Cover Configuration
------------------------
All cover config schemas inherit from this schema - you can set these keys for covers.
.. code-block:: yaml
cover:
- platform: ...
device_class: garage
Configuration variables:
- **device_class** (*Optional*, string): The device class for the
sensor. See https://www.home-assistant.io/components/cover/ for a list of available options.
Advanced options:
- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will
not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without
a ``name`` will implicitly set this to true.
- If MQTT enabled, all other options from :ref:`MQTT Component <config-mqtt-component>`.
.. _cover-open_action:
``cover.open`` Action
---------------------
This action opens the cover with the given ID when executed.
This :ref:`action <config-action>` opens the cover with the given ID when executed.
.. code-block:: yaml
@ -28,14 +57,16 @@ This action opens the cover with the given ID when executed.
.. code-block:: cpp
id(cover_1).open();
auto call = id(cover_1).make_call();
call.set_command_open();
call.perform();
.. _cover-close_action:
``cover.close`` Action
----------------------
This action closes the cover with the given ID when executed.
This :ref:`action <config-action>` closes the cover with the given ID when executed.
.. code-block:: yaml
@ -49,14 +80,16 @@ This action closes the cover with the given ID when executed.
.. code-block:: cpp
id(cover_1).close();
auto call = id(cover_1).make_call();
call.set_command_close();
call.perform();
.. _cover-stop_action:
``cover.stop`` Action
---------------------
This action stops the cover with the given ID when executed.
This :ref:`action <config-action>` stops the cover with the given ID when executed.
.. code-block:: yaml
@ -70,7 +103,49 @@ This action stops the cover with the given ID when executed.
.. code-block:: cpp
id(cover_1).stop();
auto call = id(cover_1).make_call();
call.set_command_stop();
call.perform();
.. _cover-control_action:
``cover.control`` Action
------------------------
This :ref:`action <config-action>` is a more generic version of the other cover actions and
allows all cover attributes to be set.
.. code-block:: yaml
on_...:
then:
- cover.control:
id: cover_1
position: 50%
tilt: 50%
Configuration variables:
- **id** (**Required**, :ref:`config-id`): The cover to control.
- **stop** (*Optional*, boolean): Whether to stop the cover.
- **state** (*Optional*, string): The state to set the cover to - one of ``OPEN`` or ``CLOSE``.
- **position** (*Optional*, float): The cover position to set.
- ``0.0`` = ``0%`` = ``CLOSED``
- ``1.0`` = ``100%`` = ``OPEN``
- **tilt** (*Optional*, float): The tilt position to set. In range 0% - 100%.
.. note::
This action can also be expressed in :ref:`lambdas <config-lambda>`:
.. code-block:: cpp
auto call = id(cover_1).make_call();
// set attributes
call.set_position(0.5);
call.perform();
.. _cover-lambda_calls:
@ -86,14 +161,14 @@ advanced stuff.
.. code-block:: yaml
// Within lambda, make the cover report a specific state
id(my_cover).publish_state(cover::COVER_OPEN);
id(my_cover).publish_state(cover::COVER_CLOSED);
id(my_cover).publish_state(COVER_OPEN);
id(my_cover).publish_state(COVER_CLOSED);
- ``state``: Retrieve the current state of the cover.
.. code-block:: yaml
if (id(my_cover).state == cover::COVER_OPEN) {
if (id(my_cover).state == COVER_OPEN) {
// Cover is open
} else {
// Cover is closed

32
components/cover/template.rst
View File

@ -21,9 +21,9 @@ as a cover and can be controlled through the frontend.
name: "Template Cover"
lambda: |-
if (id(top_end_stop).state) {
return cover::COVER_OPEN;
return COVER_OPEN;
} else {
return cover::COVER_CLOSED;
return COVER_CLOSED;
}
open_action:
- switch.turn_on: open_cover_switch
@ -36,8 +36,8 @@ as a cover and can be controlled through the frontend.
Possible return values for the optional lambda:
- ``return cover::COVER_OPEN;`` if the cover should be reported as OPEN.
- ``return cover::COVER_CLOSED;`` if the cover should be reported as CLOSED.
- ``return COVER_OPEN;`` if the cover should be reported as OPEN.
- ``return COVER_CLOSED;`` if the cover should be reported as CLOSED.
- ``return {};`` if the last state should be repeated.
Configuration variables:
@ -50,7 +50,8 @@ Configuration variables:
be performed when the remote (like Home Assistant's frontend) requests the cover to be opened.
- **close_action** (*Optional*, :ref:`Action <config-action>`): The action that should
be performed when the remote requests the cover to be closed.
- **stop_action** (*Optional*, :ref:`Action <config-action>`):
- **stop_action** (*Optional*, :ref:`Action <config-action>`): The action that should
be performed when the remote requests the cover to be stopped.
- **optimistic** (*Optional*, boolean): Whether to operate in optimistic mode - when in this mode,
any command sent to the template cover will immediately update the reported state and no lambda
needs to be used. Defaults to ``false``.
@ -58,13 +59,7 @@ Configuration variables:
This will make the Home Assistant frontend show buttons for both OPEN and CLOSE actions, instead
of hiding one of them. Defaults to ``false``.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
Advanced options:
- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will
not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without
a ``name`` will implicitly set this to true.
- If MQTT enabled, all other options from :ref:`MQTT Component <config-mqtt-component>`.
- All other options from :ref:`Cover <config-cover>`.
.. _cover-template-publish_action:
@ -91,13 +86,17 @@ with the ``cover.template.publish`` action.
# Templated
- cover.template.publish:
id: template_cov
state: !lambda 'return cover::COVER_OPEN;'
state: !lambda 'return COVER_OPEN;'
Configuration options:
- **id** (**Required**, :ref:`config-id`): The ID of the template cover.
- **state** (**Required**, :ref:`templatable <config-templatable>`):
- **state** (*Optional*, :ref:`templatable <config-templatable>`):
The state to publish. One of ``OPEN``, ``CLOSED``.
- **position** (*Optional*, :ref:`templatable <config-templatable>`, float):
The position to publish, from 0 (CLOSED) to 1.0 (OPEN)
- **current_operation** (*Optional*, :ref:`templatable <config-templatable>`, string):
The current operation mode to publish. One of ``IDLE``, ``OPENING`` and ``CLOSING``.
.. note::
@ -105,7 +104,8 @@ Configuration options:
.. code-block:: cpp
id(template_cov).publish_state(cover::COVER_OPEN);
id(template_cov).position = COVER_OPEN;
id(template_cov).publish_state();
See Also
--------
@ -113,5 +113,5 @@ See Also
- :doc:`/components/cover/index`
- :ref:`automation`
- :doc:`/cookbook/garage-door`
- :apiref:`cover/template_cover.h`
- :apiref:`template/cover/template_cover.h`
- :ghedit:`Edit`

60
components/cover/time_based.rst Normal file
View File

@ -0,0 +1,60 @@
Time-Based Cover
================
.. seo::
:description: Instructions for setting up time-based covers in ESPHome.
:image: TODO.png
The ``time_based`` cover platform allows you to create covers with position control that do not
have any position feedback. The state of the cover is thus always an assumed one, the current
position is approximated with the time the cover has been moving in a direction.
.. figure:: images/more-info-ui.png
:align: center
:width: 75.0%
.. code-block:: yaml
# Example configuration entry
cover:
- platform: time_based
name: "Time-Based Cover"
open_action:
- switch.turn_on: open_cover_switch
open_duration: 2.1min
close_action:
- switch.turn_on: close_cover_switch
close_duration: 2min
stop_action:
- switch.turn_off: open_cover_switch
- switch.turn_off: close_cover_switch
Configuration variables:
------------------------
- **name** (**Required**, string): The name of the cover.
- **open_action** (**Required**, :ref:`Action <config-action>`): The action that should
be performed when the remote requests the cover to be opened.
- **open_duration** (**Required**, :ref:`config-time`): The amount of time it takes the cover
to open up from the fully-closed state.
- **close_action** (*Optional*, :ref:`Action <config-action>`): The action that should
be performed when the remote requests the cover to be closed.
- **close_duration** (**Required**, :ref:`config-time`): The amount of time it takes the cover
to close from the fully-open state.
- **stop_action** (**Required**, :ref:`Action <config-action>`): The action that should
be performed when the remote requests the cover to be closed or the cover has been opening/closing
for the given durations.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- All other options from :ref:`Cover <config-cover>`.
See Also
--------
- :doc:`index`
- :ref:`automation`
- :apiref:`time_based/time_based_cover.h`
- :ghedit:`Edit`

2
components/debug.rst
View File

@ -28,5 +28,5 @@ See Also
--------
- :doc:`logger`
- :apiref:`debug_component.h`
- :apiref:`debug/debug_component.h`
- :ghedit:`Edit`

2
components/deep_sleep.rst
View File

@ -128,5 +128,5 @@ See Also
- :doc:`switch/shutdown`
- :ref:`automation`
- :apiref:`deep_sleep_component.h`
- :apiref:`deep_sleep/deep_sleep_component.h`
- :ghedit:`Edit`

2
components/display/index.rst
View File

@ -421,7 +421,7 @@ You can then switch between these with three different actions:
See Also
--------
- :apiref:`display/display.h`
- :apiref:`display/display_buffer.h`
- :ghedit:`Edit`
.. toctree::

2
components/display/lcd_display.rst
View File

@ -164,6 +164,6 @@ See Also
- :doc:`/components/switch/gpio`
- :doc:`/components/binary_sensor/gpio`
- :doc:`/components/pcf8574`
- :apiref:`display/lcd_display.h`
- :apiref:`lcd_base/lcd_display.h`
- `Arduino LiquidCrystal Library <https://www.arduino.cc/en/Reference/LiquidCrystal>`__
- :ghedit:`Edit`

2
components/display/max7219.rst
View File

@ -330,6 +330,6 @@ See Also
--------
- :doc:`index`
- :apiref:`display/max7219.h`
- :apiref:`max7219/max7219.h`
- `MAX7219 Library <https://github.com/nickgammon/MAX7219>`__ by `Nick Gammon <https://github.com/nickgammon>`__
- :ghedit:`Edit`

2
components/display/nextion.rst
View File

@ -82,7 +82,7 @@ See Also
--------
- :doc:`index`
- :apiref:`display/nextion.h`
- :apiref:`nextion/nextion.h`
- `Simple Nextion Library <https://github.com/bborncr/nextion>`__ by `Bentley Born <https://github.com/bborncr>`__
- `Official Nextion Library <https://github.com/itead/ITEADLIB_Arduino_Nextion>`__ by `iTead <https://www.itead.cc/>`__
- :ghedit:`Edit`

2
components/display/ssd1306.rst
View File

@ -145,6 +145,6 @@ See Also
--------
- :doc:`index`
- :apiref:`display/ssd1306.h`
- :apiref:`ssd1306_base/ssd1306_base.h`
- `SSD1306 Library <https://github.com/adafruit/Adafruit_SSD1306>`__ by `Adafruit <https://www.adafruit.com/>`__
- :ghedit:`Edit`

2
components/display/waveshare_epaper.rst
View File

@ -99,6 +99,6 @@ See Also
--------
- :doc:`index`
- :apiref:`display/waveshare_epaper.h`
- :apiref:`waveshare_epaper/waveshare_epaper.h`
- `Arduino Waveshare E-Paper library <https://github.com/soonuse/epd-library-arduino>`__ by `Yehui (@soonuse) <https://github.com/soonuse>`__
- :ghedit:`Edit`

4
components/esp32_ble_beacon.rst
View File

@ -72,7 +72,7 @@ know when I'm home or away.
See Also
--------
- :doc:`binary_sensor/esp32_ble_tracker`
- :apiref:`esp32_ble_beacon.h`
- :doc:`esp32_ble_tracker`
- :apiref:`esp32_ble_beacon/esp32_ble_beacon.h`
- `ESP32 BLE for Arduino <https://github.com/nkolban/ESP32_BLE_Arduino>`__ by `Neil Kolban <https://github.com/nkolban>`__.
- :ghedit:`Edit`

4
components/esp32_ble_tracker.rst
View File

@ -64,7 +64,7 @@ Configuration variables:
See Also
--------
- :doc:`binary_sensor/esp32_ble_tracker`
- :apiref:`esp32_ble_tracker.h`
- :doc:`binary_sensor/ble_presence`
- :apiref:`esp32_ble_tracker/esp32_ble_tracker.h`
- `ESP32 BLE for Arduino <https://github.com/nkolban/ESP32_BLE_Arduino>`__ by `Neil Kolban <https://github.com/nkolban>`__.
- :ghedit:`Edit`

2
components/esp32_camera.rst
View File

@ -197,5 +197,5 @@ Configuration for TTGO T-Camera
See Also
--------
- :apiref:`wifi_component.h`
- :apiref:`esp32_camera/esp32_camera.h`
- :ghedit:`Edit`

68
components/esphome.rst
View File

@ -31,12 +31,11 @@ Configuration variables:
specify for platformio. For the ESP32, choose the appropriate one
from `this list <http://docs.platformio.org/en/latest/platforms/espressif32.html#boards>`__
and use `this list <http://docs.platformio.org/en/latest/platforms/espressif8266.html#boards>`__
for ESP8266-based boards.
for ESP8266-based boards. *This only affects pin aliases and some internal settings*, if unsure
choose the generic board option!
Advanced options:
- **esphome_core_version** (*Optional*): The version of the C++ `ESPHome-Core framework <https://github.com/esphome/esphome-core>`__
to use. See :ref:`esphome-esphome_core_version`.
- **arduino_version** (*Optional*): The version of the arduino framework to link the project against.
See :ref:`esphome-arduino_version`.
- **build_path** (*Optional*, string): Customize where ESPHome will store the build files
@ -54,8 +53,6 @@ Advanced options:
ESP8266 Options:
- **board_flash_mode** (*Optional*, string): The `SPI flash mode <https://github.com/espressif/esptool/wiki/SPI-Flash-Modes>`__
to use for the board. One of ``qio``, ``qout``, ``dio`` and ``dout``. Defaults to ``dout``.
- **esp8266_restore_from_flash** (*Optional*, boolean): Whether to save & restore data from flash on ESP8266s.
Defaults to ``no``. See :ref:`esphome-esp8266_restore_from_flash` for more info
@ -68,67 +65,6 @@ Automations:
- **on_loop** (*Optional*, :ref:`Automation <automation>`): An automation to perform
on each ``loop()`` iteration. See :ref:`esphome-on_loop`.
.. _esphome-esphome_core_version:
``esphome_core_version``
------------------------
With the ``esphome_core_version`` parameter you can tell ESPHome which version of the C++ framework
to use when compiling code. For example, you can configure using the most recent (potentially unstable)
version of ESPHome straight from github. Or you can configure the use of a local copy of esphome-core
using this configuration option.
First, you can configure the use of either the latest esphome-core stable release (``latest``),
the latest development code from GitHub (``dev``), or a specific version number (``1.8.0``).
.. code-block:: yaml
# Example configuration entry
esphome:
# ...
# Use the latest ESPHome stable release
esphome_core_version: latest
# Or use the latest code from github
esphome_core_version: dev
# Use a specific version number
esphome_core_version: 1.8.0
Alternatively, if you want to develop for ESPHome, you can download the
`latest code from GitHub <https://github.com/esphome/esphome-core/archive/dev.zip>`__, extract the contents,
and point ESPHome to your local copy. Then you can modify the ESPHome to your needs or to fix bugs.
.. code-block:: yaml
# Example configuration entry
esphome:
# ...
# Use a local copy of ESPHome
esphome_core_version:
local: path/to/esphome-core
And last, you can make ESPHome use a specific branch/commit/tag from a remote git repository:
.. code-block:: yaml
# Example configuration entry
esphome:
# ...
# Use a specific commit/branch/tag from a remote repository
esphome_core_version:
# Repository defaults to https://github.com/esphome/esphome-core.git
repository: https://github.com/esphome/esphome-core.git
branch: master
esphome_core_version:
repository: https://github.com/somebody/esphome-core.git
commit: d27bac9263e8a0a5a00672245b38db3078f8992c
esphome_core_version:
repository: https://github.com/esphome/esphome-core.git
tag: v1.8.0
.. _esphome-arduino_version:
``arduino_version``

2
components/ethernet.rst
View File

@ -87,5 +87,5 @@ Configuration for Olimex ESP32-POE
See Also
--------
- :apiref:`wifi_component.h`
- :apiref:`ethernet/ethernet_component.h`
- :ghedit:`Edit`

2
components/fan/index.rst
View File

@ -95,7 +95,7 @@ Configuration options:
Set the oscillation state of the fan. Defaults to not affecting oscillation.
- **speed** (*Optional*, string, :ref:`templatable <config-templatable>`):
Set the speed setting of the fan. One of ``OFF``, ``LOW``, ``MEDIUM``, ``HIGH``.
If you template this value, return ``fan::FAN_SPEED_...``, for example ``fan::FAN_SPEED_HIGH``.
If you template this value, return ``FAN_SPEED_...``, for example ``FAN_SPEED_HIGH``.
Full Fan Index
--------------

2
components/i2c.rst
View File

@ -37,5 +37,5 @@ Configuration variables:
See Also
--------
- :apiref:`i2c_component.h`
- :apiref:`i2c/i2c.h`
- :ghedit:`Edit`

BIN
components/images/sun-sensor-ui.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.1 KiB

BIN
components/images/sun-text_sensor-ui.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 8.4 KiB

1
components/index.rst
View File

@ -5,6 +5,7 @@ Components
:glob:
binary_sensor/index
climate/index
cover/index
fan/index
light/index

8
components/light/binary.rst
View File

@ -29,11 +29,7 @@ Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **effects** (*Optional*, list): A list of :ref:`light effects <light-effects>` to use for this light, though binary lights
only support very few of them.
- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will
not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without
a ``name`` will implicitly set this to true.
- If MQTT enabled, all other options from :ref:`MQTT Component <config-mqtt-component>`.
- All other options from :ref:`Light <config-light>`.
See Also
--------
@ -42,5 +38,5 @@ See Also
- :doc:`/components/light/index`
- :doc:`/components/output/gpio`
- :doc:`/components/power_supply`
- :apiref:`light/light_state.h`
- :apiref:`binary/light/binary_light_output.h`
- :ghedit:`Edit`

13
components/light/cwww.rst
View File

@ -30,18 +30,9 @@ Configuration variables:
of the cold white channel.
- **warm_white_color_temperature** (**Required**, float): The color temperate (in `mireds <https://en.wikipedia.org/wiki/Mired>`__ or Kelvin)
of the warm white channel.
- **gamma_correct** (*Optional*, float): The `gamma correction
factor <https://en.wikipedia.org/wiki/Gamma_correction>`__ for the light. Defaults to ``2.8``.
- **default_transition_length** (*Optional*, :ref:`config-time`): The length of
the transition if no transition parameter is provided by Home Assistant. Defaults to ``1s``.
- **effects** (*Optional*, list): A list of :ref:`light effects <light-effects>` to use for this light.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will
not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without
a ``name`` will implicitly set this to true.
- If MQTT enabled, all other options from :ref:`MQTT Component <config-mqtt-component>`.
- All other options from :ref:`Light <config-light>`.
See Also
--------
@ -54,5 +45,5 @@ See Also
- :doc:`/components/output/ledc`
- :doc:`/components/output/esp8266_pwm`
- :doc:`/components/output/pca9685`
- :apiref:`light/light_state.h`
- :apiref:`cwww/cww_light_output.h`
- :ghedit:`Edit`

32
components/light/fastled.rst
View File

@ -46,23 +46,9 @@ Configuration variables:
- **max_refresh_rate** (*Optional*, :ref:`config-time`):
A time interval used to limit the number of commands a light can handle per second. For example
16ms will limit the light to a refresh rate of about 60Hz. Defaults to the default value for the used chipset.
- **gamma_correct** (*Optional*, float): The `gamma correction
factor <https://en.wikipedia.org/wiki/Gamma_correction>`__ for the
light. Defaults to ``2.8``.
- **color_correct** (*Optional*, list of percentages): The color correction for each channel. This denotes
the maximum brightness of the red, green and blue channel. Defaults to ``color_correct: [100%, 100%, 100%]``.
- **default_transition_length** (*Optional*, :ref:`config-time`): The length of
the transition if no transition parameter is provided by Home
Assistant. Defaults to ``1s``.
- **power_supply** (*Optional*, :ref:`config-id`): The :doc:`/components/power_supply` to connect to
this light. When the light is turned on, the power supply will automatically be switched on too.
- **effects** (*Optional*, list): A list of :ref:`light effects <light-effects>` to use for this light.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will
not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without
a ``name`` will implicitly set this to true.
- If MQTT enabled, all other options from :ref:`MQTT Component <config-mqtt-component>`.
- All other options from :ref:`Light <config-light>`.
.. _fastled_clockless-chipsets:
@ -137,21 +123,9 @@ Configuration variables:
- **max_refresh_rate** (*Optional*, :ref:`config-time`):
A time interval used to limit the number of commands a light can handle per second. For example
16ms will limit the light to a refresh rate of about 60Hz. Defaults to the default value for the used chipset.
- **gamma_correct** (*Optional*, float): The `gamma correction
factor <https://en.wikipedia.org/wiki/Gamma_correction>`__ for the light. Defaults to ``2.8``.
- **color_correct** (*Optional*, list of percentages): The color correction for each channel. This denotes
the maximum brightness of the red, green and blue channel. Defaults to ``color_correct: [100%, 100%, 100%]``.
- **default_transition_length** (*Optional*, :ref:`config-time`): The length of
the transition if no transition parameter is provided by Home Assistant. Defaults to ``1s``.
- **power_supply** (*Optional*, :ref:`config-id`): The :doc:`/components/power_supply` to connect to
this light. When the light is turned on, the power supply will automatically be switched on too.
- **effects** (*Optional*, list): A list of :ref:`light effects <light-effects>` to use for this light.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will
not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without
a ``name`` will implicitly set this to true.
- If MQTT enabled, all other options from :ref:`MQTT Component <config-mqtt-component>`.
- All other options from :ref:`Light <config-light>`.
.. _fastled_spi-chipsets:
@ -172,6 +146,6 @@ See Also
- :doc:`/components/light/index`
- :doc:`/components/power_supply`
- :apiref:`light/fastled_light_output.h`
- :apiref:`fastled_base/fastled_light.h`
- `Arduino FastLED library <https://github.com/FastLED/FastLED>`__
- :ghedit:`Edit`

151
components/light/index.rst
View File

@ -11,6 +11,43 @@ features such as RGB colors, transitions, flashing and effects.
This component restores its state on reboot/reset.
.. _config-light:
Base Light Configuration
------------------------
All light configuration schemas inherit these options.
.. code-block:: yaml
light:
- platform: ...
Configuration variables:
- **effects** (*Optional*, list): A list of :ref:`light effects <light-effects>` to use for this light.
- **gamma_correct** (*Optional*, float): Apply a `gamma correction
factor <https://en.wikipedia.org/wiki/Gamma_correction>`__ to the light channels.
Defaults to ``2.8``.
- **default_transition_length** (*Optional*, :ref:`config-time`): The default transition length
to use when no transition length is set in the light call. Defaults to ``1s``.
Additional Configuration variables for addressable lights:
- **color_correct** (*Optional*, list of float): Apply a color correction to each color channel.
This defines the maximum brightness of each channel. For example ``[100%, 50%, 100%]`` would set the
green channel to be at most at 50% brightness.
- **power_supply** (*Optional*, :ref:`config-id`): The :doc:`/components/power_supply` to connect to
this light. When the light is turned on, the power supply will automatically be switched on too.
Advanced options:
- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will
not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without
a ``name`` will implicitly set this to true.
- If MQTT enabled, all other options from :ref:`MQTT Component <config-mqtt-component>`.
.. _light-toggle_action:
``light.toggle`` Action
@ -147,6 +184,109 @@ Configuration options:
// perform action:
call.perform();
.. _light-control_action:
``light.control`` Action
------------------------
This :ref:`Action <config-action>` is a generic call to change the state of a light - it
is essentially just a combination of the turn_on and turn_off calls.
.. code-block:: yaml
on_...:
then:
- light.control:
id: light_1
state: on
Configuration options:
- **id** (**Required**, :ref:`config-id`): The ID of the light.
- **state** (*Optional*, :ref:`templatable <config-templatable>`, boolean): Change the ON/OFF
state of the light.
- All other options from :ref:`light.turn_on <light-turn_on_action>`.
.. _light-dim_relative_action:
``light.dim_relative`` Action
-----------------------------
This :ref:`Action <config-action>` allows you to dim a light that supports brightness
by a relative amount.
.. code-block:: yaml
on_...:
then:
# Increases the brightness by 5%
- light.dim_relative:
id: light_1
relative_brightness: 5%
Configuration options:
- **id** (**Required**, :ref:`config-id`): The ID of the light.
- **relative_brightness** (**Required***, :ref:`templatable <config-templatable>`, percentage):
The relative brightness to dim the light by.
- **transition_length** (*Optional*, :ref:`config-time`, :ref:`templatable <config-templatable>`): The length of the transition.
.. note::
Example: dimming a light with a button press
.. code-block:: yaml
binary_sensor:
- platform: gpio
# ...
id: my_binary_sensor
on_press:
- while:
condition:
binary_sensor.is_on: my_binary_sensor
then:
- light.dim_relative:
id: light_1
relative_brightness: 5%
transition_length: 0.1s
- delay: 0.1s
.. _light-addressable_set_action:
``light.addressable_set`` Action
--------------------------------
This :ref:`Action <config-action>` allows you to manually set a range of LEDs on an addressable light
to a specific color.
.. code-block:: yaml
on_...:
- light.addressable_set:
id: my_light
range_from: 1
range_to: 50
red: 100%
green: 0%
blue: 0%
Configuration variables:
- **id** (**Required**, :ref:`config-id`): The ID of the addressable light to control.
- **range_from** (*Optional*, :ref:`templatable <config-templatable>`, int): The beginning
of the range of LEDs to control. 1-based indexing. Defaults to 1 (the beginning of the strip).
- **range_to** (*Optional*, :ref:`templatable <config-templatable>`, int): The end of the
range of LEDs to control. 1-based indexing. Defaults to the end of the strip.
- **red** (*Optional*, :ref:`templatable <config-templatable>`, percentage): The value to
set the red channel to.
- **green** (*Optional*, :ref:`templatable <config-templatable>`, percentage): The value to
set the green channel to.
- **blue** (*Optional*, :ref:`templatable <config-templatable>`, percentage): The value to
set the blue channel to.
- **white** (*Optional*, :ref:`templatable <config-templatable>`, percentage): The value to
set the white channel to.
.. _light-effects:
Light Effects
@ -520,7 +660,7 @@ Addressable Lambda Effect
This effect allows you to access each LED individually in a custom light effect.
You're passed in one variable: ``it`` - an `AddressableLight </api/classlight_1_1_addressable_light>`__
You're passed in one variable: ``it`` - an :apiclass:`AddressableLight <light::AddressableLight>`
instance (see API reference for more info).
.. code-block:: yaml
@ -535,7 +675,7 @@ instance (see API reference for more info).
// it.size() - Number of LEDs
// it[num] - Access the LED at index num.
// Set the LED at num to the given r, g, b values
// it[num] = light::ESPColor(r, g, b);
// it[num] = ESPColor(r, g, b);
// Get the color at index num (ESPColor instance)
// it[num].get();
@ -543,11 +683,14 @@ instance (see API reference for more info).
for (int i = 1; i < it.size(); i++) {
it[i] = it[i - 1].get();
}
it[0] = light::ESPColor::random_color();
it[0] = ESPColor::random_color();
// Bonus: use .range() and .all() to set many LEDs without having to write a loop.
it.range(0, 50) = ESPColor::BLACK;
it.all().fade_to_black(10);
Examples of this API can be found here:
https://github.com/esphome/esphome-core/blob/dev/src/esphome/light/addressable_light_effect.cpp
https://github.com/esphome/esphome/blob/dev/esphome/components/light/addressable_light_effect.h
(the built-in addressable light effects).
See Also

13
components/light/monochromatic.rst
View File

@ -37,18 +37,9 @@ Configuration variables:
- **name** (**Required**, string): The name of the light.
- **output** (**Required**, :ref:`config-id`): The id of the float :ref:`output` to use for this light.
- **gamma_correct** (*Optional*, float): The `gamma correction
factor <https://en.wikipedia.org/wiki/Gamma_correction>`__ for the light. Defaults to ``2.8``.
- **default_transition_length** (*Optional*, :ref:`config-time`): The length of
the transition if no transition parameter is provided by Home
Assistant. Defaults to ``1s``.
- **effects** (*Optional*, list): A list of :ref:`light effects <light-effects>` to use for this light.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will
not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without
a ``name`` will implicitly set this to true.
- If MQTT enabled, all other options from :ref:`MQTT Component <config-mqtt-component>`.
- All other options from :ref:`Light <config-light>`.
See Also
--------
@ -65,5 +56,5 @@ See Also
- :doc:`/components/output/esp8266_pwm`
- :doc:`/components/output/pca9685`
- :doc:`/components/output/my9231`
- :apiref:`light/light_state.h`
- :apiref:`monochromatic/monochromatic_light_output.h`
- :ghedit:`Edit`

17
components/light/neopixelbus.rst
View File

@ -30,17 +30,7 @@ Configuration variables:
**Base Options:**
- **name** (**Required**, string): The name of the light.
- **gamma_correct** (*Optional*, float): The `gamma correction
factor <https://en.wikipedia.org/wiki/Gamma_correction>`__ for the
light. Defaults to ``2.8``.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **color_correct** (*Optional*, list of percentages): The color correction for each channel. This denotes
the maximum brightness of the red, green, blue[, white] channel. Defaults to ``color_correct: [100%, 100%, 100%]``.
- **default_transition_length** (*Optional*, :ref:`config-time`): The length of
the transition if no transition parameter is provided by Home
Assistant. Defaults to ``1s``.
- **power_supply** (*Optional*, :ref:`config-id`): The :doc:`/components/power_supply` to connect to
this light. When the light is turned on, the power supply will automatically be switched on too.
- **effects** (*Optional*, list): A list of :ref:`light effects <light-effects>` to use for this light.
**Type Options:**
@ -85,10 +75,7 @@ If you have one line, only specify ``pin``, otherwise specify both ``clock_pin``
**Advanced Options:**
- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will
not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without
a ``name`` will implicitly set this to true.
- If MQTT enabled, all other options from :ref:`MQTT Component <config-mqtt-component>`.
- All other options from :ref:`Light <config-light>`.
See Also
--------
@ -96,6 +83,6 @@ See Also
- :doc:`/components/light/index`
- :doc:`/components/light/fastled`
- :doc:`/components/power_supply`
- :apiref:`light/neo_pixel_light_output.h`
- :apiref:`neopixelbus/neopixelbus_light.h`
- `NeoPixelBus library <https://github.com/Makuna/NeoPixelBus/wiki/ESP8266-NeoMethods>`__
- :ghedit:`Edit`

12
components/light/partition.rst
View File

@ -46,14 +46,8 @@ Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **effects** (*Optional*, list): A list of :ref:`light effects <light-effects>` to use for this light.
- **gamma_correct** (*Optional*, float): The `gamma correction
factor <https://en.wikipedia.org/wiki/Gamma_correction>`__ for the
light. Defaults to ``2.8``.
- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will
not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without
a ``name`` will implicitly set this to true.
- If MQTT enabled, all other options from :ref:`MQTT Component <config-mqtt-component>`.
- All other options from :ref:`Light <config-light>`.
.. note::
@ -61,11 +55,13 @@ Configuration variables:
objects have a moderate overhead and if you try to create many lights you will run out
of memory quickly.
See :ref:`light-addressable_set_action` for that.
See Also
--------
- :doc:`/components/light/index`
- :doc:`/components/light/fastled`
- :doc:`/components/light/neopixelbus`
- :apiref:`light/addressable_light.h`
- :apiref:`partition/light_partition.h`
- :ghedit:`Edit`

11
components/light/rgb.rst
View File

@ -42,16 +42,9 @@ Configuration variables:
- **red** (**Required**, :ref:`config-id`): The id of the float :ref:`output` to use for the red channel.
- **green** (**Required**, :ref:`config-id`): The id of the float :ref:`output` to use for the green channel.
- **blue** (**Required**, :ref:`config-id`): The id of the float :ref:`output` to use for the blue channel.
- **gamma_correct** (*Optional*, float): The `gamma correction
factor <https://en.wikipedia.org/wiki/Gamma_correction>`__ for the light. Defaults to ``2.8``.
- **default_transition_length** (*Optional*, :ref:`config-time`): The length of
the transition if no transition parameter is provided by Home Assistant. Defaults to ``1s``.
- **effects** (*Optional*, list): A list of :ref:`light effects <light-effects>` to use for this light.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will
not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without
a ``name`` will implicitly set this to true.
- If MQTT enabled, all other options from :ref:`MQTT Component <config-mqtt-component>`.
- All other options from :ref:`Light <config-light>`.
See Also
--------
@ -68,5 +61,5 @@ See Also
- :doc:`/components/output/esp8266_pwm`
- :doc:`/components/output/pca9685`
- :doc:`/components/output/my9231`
- :apiref:`light/light_state.h`
- :apiref:`rgb/rgb_light_output.h`
- :ghedit:`Edit`

11
components/light/rgbw.rst
View File

@ -26,16 +26,9 @@ Configuration variables:
- **green** (**Required**, :ref:`config-id`): The id of the float :ref:`output` to use for the green channel.
- **blue** (**Required**, :ref:`config-id`): The id of the float :ref:`output` to use for the blue channel.
- **white** (**Required**, :ref:`config-id`): The id of the float :ref:`output` to use for the white channel.
- **gamma_correct** (*Optional*, float): The `gamma correction
factor <https://en.wikipedia.org/wiki/Gamma_correction>`__ for the light. Defaults to ``2.8``.
- **default_transition_length** (*Optional*, :ref:`config-time`): The length of
the transition if no transition parameter is provided by Home Assistant. Defaults to ``1s``.
- **effects** (*Optional*, list): A list of :ref:`light effects <light-effects>` to use for this light.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will
not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without
a ``name`` will implicitly set this to true.
- If MQTT enabled, all other options from :ref:`MQTT Component <config-mqtt-component>`.
- All other options from :ref:`Light <config-light>`.
See Also
--------
@ -48,5 +41,5 @@ See Also
- :doc:`/components/output/esp8266_pwm`
- :doc:`/components/output/pca9685`
- :doc:`/components/output/my9231`
- :apiref:`light/light_state.h`
- :apiref:`rgbw/rgb_light_output.h`
- :ghedit:`Edit`

11
components/light/rgbww.rst
View File

@ -36,16 +36,9 @@ Configuration variables:
of the cold white channel.
- **warm_white_color_temperature** (**Required**, float): The color temperate (in `mireds <https://en.wikipedia.org/wiki/Mired>`__ or Kelvin)
of the warm white channel.
- **gamma_correct** (*Optional*, float): The `gamma correction
factor <https://en.wikipedia.org/wiki/Gamma_correction>`__ for the light. Defaults to ``2.8``.
- **default_transition_length** (*Optional*, :ref:`config-time`): The length of
the transition if no transition parameter is provided by Home Assistant. Defaults to ``1s``.
- **effects** (*Optional*, list): A list of :ref:`light effects <light-effects>` to use for this light.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will
not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without
a ``name`` will implicitly set this to true.
- If MQTT enabled, all other options from :ref:`MQTT Component <config-mqtt-component>`.
- All other options from :ref:`Light <config-light>`.
See Also
--------
@ -59,5 +52,5 @@ See Also
- :doc:`/components/output/esp8266_pwm`
- :doc:`/components/output/pca9685`
- :doc:`/components/output/my9231`
- :apiref:`light/light_state.h`
- :apiref:`rgbww/rgbww_light_output.h`
- :ghedit:`Edit`

20
components/logger.rst
View File

@ -21,11 +21,6 @@ Configuration variables:
- **baud_rate** (*Optional*, int): The baud rate to use for the serial
UART port. Defaults to ``115200``. Set to ``0`` to disable logging via UART.
- **tx_buffer_size** (*Optional*, int): The size of the buffer used
for log messages. Decrease this if you’re having memory problems.
Defaults to ``512``.
- **hardware_uart** (*Optional*, string): The Hardware UART to use for logging.
Defaults to ``UART0``.
- **level** (*Optional*, string): The global log level. Any log message
with a lower severity will not be shown. Defaults to ``DEBUG``.
- **logs** (*Optional*, mapping): Manually set the log level for a
@ -33,6 +28,16 @@ Configuration variables:
information <logger-manual_tag_specific_levels>`.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
Advanced settings:
- **tx_buffer_size** (*Optional*, int): The size of the buffer used
for log messages. Decrease this if you’re having memory problems.
Defaults to ``512``.
- **hardware_uart** (*Optional*, string): The Hardware UART to use for logging.
Defaults to ``UART0``.
- **esp8266_store_log_strings_in_flash** (*Optional*, boolean): If set to false, disables storing
log strings in the flash section of the device (uses more memory). Defaults to true.
.. _logger-hardware_uarts:
Hardware UARTs
@ -89,7 +94,8 @@ Possible log levels are (sorted by severity):
- ``VERY_VERBOSE``
- All internal messages are logged. Including all the data flowing through data buses like
i2c, spi or uart. Color: white
i2c, spi or uart. Warning: May cause the device to slow down and have trouble staying
connecting due to amount of generated messages. Color: white
.. _logger-manual_tag_specific_levels:
@ -157,5 +163,5 @@ See Also
--------
- :doc:`/components/uart`
- :apiref:`log_component.h`
- :apiref:`logger/logger.h`
- :ghedit:`Edit`

2
components/mcp23017.rst
View File

@ -47,5 +47,5 @@ See Also
- :ref:`i2c`
- :doc:`switch/gpio`
- :doc:`binary_sensor/gpio`
- :apiref:`io/mcp23017.h`
- :apiref:`mcp23017/mcp23017.h`
- :ghedit:`Edit`

18
components/mqtt.rst
View File

@ -505,9 +505,25 @@ Configuration options:
root["something"] = id(my_sensor).state;
});
.. _mqtt.connected_condition:
``mqtt.connected`` Condition
----------------------------
This :ref:`Condition <config-condition>` checks if the MQTT client is currently connected to
the MQTT broker.
.. code-block:: yaml
on_...:
if:
condition:
mqtt.connected:
then:
- logger.log: MQTT is connected!
See Also
--------
- :apiref:`mqtt/mqtt_client_component.h`
- :apiref:`mqtt/mqtt_client.h`
- :ghedit:`Edit`

2
components/ota.rst
View File

@ -63,5 +63,5 @@ through a ``on_boot`` trigger:
See Also
--------
- :apiref:`ota_component.h`
- :apiref:`ota/ota_component.h`
- :ghedit:`Edit`

6
components/output/custom.rst
View File

@ -14,7 +14,7 @@ same as the :doc:`ESP8266 software PWM output </components/output/esp8266_pwm>`.
#include "esphome.h"
using namespace esphome;
class MyCustomFloatOutput : public Component, public output::FloatOutput {
class MyCustomFloatOutput : public Component, public FloatOutput {
public:
void setup() override {
// This will be called by App.setup()
@ -30,7 +30,7 @@ same as the :doc:`ESP8266 software PWM output </components/output/esp8266_pwm>`.
};
// Custom binary output, for exposing binary states
class MyCustomBinaryOutput : public Component, public output::BinaryOutput {
class MyCustomBinaryOutput : public Component, public BinaryOutput {
public:
void setup() override {
// This will be called by App.setup()
@ -84,7 +84,7 @@ Configuration variables:
- All options from :ref:`Output <config-output>`.
See :cpp:class:`output::BinaryOutput` and :cpp:class`output::FloatOutput`.
See :apiclass:`output::BinaryOutput` and :apiclass:`output::FloatOutput`.
See Also
--------

23
components/output/esp8266_pwm.rst
View File

@ -34,6 +34,27 @@ Configuration variables:
have more visual artifacts, but can represent much more colors. Defaults to ``1000 Hz``.
- All other options from :ref:`Output <config-output>`.
.. _output-esp8266_pwm-set_frequency_action:
``output.esp8266_pwm.set_frequency`` Action
-------------------------------------------
This :ref:`Action <config-action>` allows you to manually change the frequency of an ESP8266 PWM
channel at runtime. Use cases include controlling a passive buzzer (for pitch control).
.. code-block:: yaml
on_...:
- output.esp8266_pwm.set_frequency:
id: pwm_output
frequency: 100Hz
Configuration variables:
- **id** (**Required**, :ref:`config-id`): The ID of the PWM output to change.
- **frequency** (**Required**, :ref:`templatable <config-templatable>`, float): The frequency
to set in hertz.
See Also
--------
@ -42,5 +63,5 @@ See Also
- :doc:`/components/light/monochromatic`
- :doc:`/components/fan/speed`
- :doc:`/components/power_supply`
- :apiref:`output/esp8266_pwm_output.h`
- :apiref:`esp8266_pwm/esp8266_pwm.h`
- :ghedit:`Edit`

2
components/output/gpio.rst
View File

@ -40,5 +40,5 @@ See Also
- :doc:`/components/light/binary`
- :doc:`/components/fan/binary`
- :doc:`/components/power_supply`
- :apiref:`output/gpio_binary_output_component.h`
- :apiref:`gpio/output/gpio_binary_output.h`
- :ghedit:`Edit`

3
components/output/index.rst
View File

@ -124,7 +124,8 @@ Full Output Index
- :doc:`/components/light/rgb`
- :doc:`/components/fan/binary`
- :doc:`/components/fan/speed`
- :apiref:`output/binary_output.h`, :apiref:`output/float_output.h`
- :apiref:`binary_output.h <output/binary_output.h>`,
:apiref:`float_output.h <output/float_output.h>`
- :ghedit:`Edit`
.. toctree::

11
components/output/ledc.rst
View File

@ -9,6 +9,9 @@ The LEDC output component exposes a `LEDC PWM
channel <https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/peripherals/ledc.html>`__
of the ESP32 as an output component.
The frequency range of LEDC is from 10Hz to 40MHz - however, higher frequencies require a smaller
bit_depth which means the output is not that accurate for frequencies above ~300kHz.
.. code-block:: yaml
# Example configuration entry
@ -29,9 +32,9 @@ Configuration variables:
- **pin** (**Required**, :ref:`config-pin`): The pin to use LEDC on. Can only be GPIO0-GPIO33.
- **id** (**Required**, :ref:`config-id`): The id to use for this output component.
- **frequency** (*Optional*, float): At which frequency to run the LEDC
channel’s timer. Two LEDC channels always share the same timer and
therefore also the same frequency. Defaults to 1000Hz.
- **bit_depth** (*Optional*, int): The bit depth to use for the LEDC channel. Defaults to 12.
channel’s timer. Defaults to 1000Hz.
- **bit_depth** (*Optional*, int): The bit depth to use for the LEDC channel. Defaults to the
highest possible for the configured frequency.
- All other options from :ref:`Output <config-output>`.
Advanced options:
@ -48,6 +51,6 @@ See Also
- :doc:`/components/light/monochromatic`
- :doc:`/components/fan/speed`
- :doc:`/components/power_supply`
- :apiref:`output/ledc_output_component.h`
- :apiref:`ledc/ledc_output.h`
- `esp-idf LEDC API docs <https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/peripherals/ledc.html>`__
- :ghedit:`Edit`

2
components/output/my9231.rst
View File

@ -181,6 +181,6 @@ See Also
- :doc:`/components/light/monochromatic`
- :doc:`/components/fan/speed`
- :doc:`/components/power_supply`
- :apiref:`output/my9231_output_component.h`
- :apiref:`my9231/my9231.h`
- `MY92XX LED driver library for Arduino AVR and ESP8266 <https://github.com/xoseperez/my92xx>`__ by `@xoseperez <https://github.com/xoseperez>`__
- :ghedit:`Edit`

2
components/output/pca9685.rst
View File

@ -90,6 +90,6 @@ See Also
- :doc:`/components/light/monochromatic`
- :doc:`/components/fan/speed`
- :doc:`/components/power_supply`
- :apiref:`output/pca9685_output_component.h`
- :apiref:`pca9685/pca9685_output.h`
- `PCA9685 Arduino Library <https://github.com/NachtRaveVL/PCA9685-Arduino>`__ by `@NachtRaveVL <https://github.com/NachtRaveVL>`__
- :ghedit:`Edit`

2
components/pcf8574.rst
View File

@ -61,5 +61,5 @@ See Also
- :doc:`switch/gpio`
- :doc:`binary_sensor/gpio`
- `PCF8574 Arduino Library <https://github.com/skywodd/pcf8574_arduino_library>`__ by `Fabien Batteix <https://github.com/skywodd>`__
- :apiref:`io/pcf8574_component.h`
- :apiref:`pcf8574/pcf8574.h`
- :ghedit:`Edit`

2
components/power_supply.rst
View File

@ -69,5 +69,5 @@ See Also
--------
- :doc:`output/index`
- :apiref:`power_supply_component.h`
- :apiref:`power_supply/power_supply.h`
- :ghedit:`Edit`

2
components/sensor/adc.rst
View File

@ -90,5 +90,5 @@ See Also
- :ref:`sensor-filters`
- :doc:`ads1115`
- :doc:`max6675`
- :apiref:`sensor/adc.h`
- :apiref:`adc/adc_sensor.h`
- :ghedit:`Edit`

2
components/sensor/ads1115.rst
View File

@ -119,6 +119,6 @@ See Also
- :ref:`sensor-filters`
- :doc:`adc`
- :doc:`max6675`
- :apiref:`sensor/ads1115_component.h`
- :apiref:`ads1115/ads1115.h`
- `i2cdevlib <https://github.com/jrowberg/i2cdevlib>`__ by `Jeff Rowberg <https://github.com/jrowberg>`__
- :ghedit:`Edit`

2
components/sensor/apds9960.rst
View File

@ -80,5 +80,5 @@ See Also
--------
- :ref:`sensor-filters`
- :apiref:`sensor/apds9960.h`
- :apiref:`apds9960/apds9960.h`
- :ghedit:`Edit`

2
components/sensor/bh1750.rst
View File

@ -53,6 +53,6 @@ See Also
- :ref:`sensor-filters`
- :doc:`tsl2561`
- :apiref:`sensor/bh7150_sensor.h`
- :apiref:`bh7150/bh7150.h`
- `BH1750 Library <https://github.com/claws/BH1750>`__ by `@claws <https://github.com/claws>`__
- :ghedit:`Edit`

2
components/sensor/ble_rssi.rst
View File

@ -35,5 +35,5 @@ See Also
- :doc:`/components/esp32_ble_tracker`
- :doc:`/components/sensor/index`
- :apiref:`esp32_ble_tracker.h`
- :apiref:`ble_rssi/ble_rssi_sensor.h`
- :ghedit:`Edit`

2
components/sensor/bme280.rst
View File

@ -91,7 +91,7 @@ See Also
- :ref:`sensor-filters`
- :doc:`bme680`
- :doc:`bmp085`
- :apiref:`sensor/bme280_component.h`
- :apiref:`bme280/bme280.h`
- `Adafruit BME280 Library <https://github.com/adafruit/Adafruit_BME280_Library>`__ by `Adafruit <https://www.adafruit.com/>`__
- `Sparkfun BME280 Library <https://github.com/sparkfun/SparkFun_BME280_Arduino_Library>`__ by `Sparkfun <https://www.sparkfun.com/>`__
- :ghedit:`Edit`

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 3.5 KiB

After

Width:  |  Height:  |  Size: 3.5 KiB

2
components/sensor/bme680.rst
View File

@ -109,6 +109,6 @@ See Also
- :ref:`sensor-filters`
- :doc:`bme280`
- :doc:`bmp085`
- :apiref:`sensor/bme680_component.h`
- :apiref:`bme680/bme680.h`
- `BME680 Sensor API <https://github.com/BoschSensortec/BME680_driver>`__ by `Bosch Sensortec <https://www.bosch-sensortec.com/>`__
- :ghedit:`Edit`

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 4.1 KiB

After

Width:  |  Height:  |  Size: 4.1 KiB

2
components/sensor/bmp085.rst
View File

@ -62,6 +62,6 @@ See Also
- :ref:`sensor-filters`
- :doc:`bme280`
- :doc:`bme680`
- :apiref:`sensor/bmp085_component.h`
- :apiref:`bmp085/bmp085.h`
- `i2cdevlib <https://github.com/jrowberg/i2cdevlib>`__ by `Jeff Rowberg <https://github.com/jrowberg>`__
- :ghedit:`Edit`

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 2.2 KiB

After

Width:  |  Height:  |  Size: 2.2 KiB

2
components/sensor/bmp280.rst
View File

@ -88,6 +88,6 @@ See Also
- :doc:`bme280`
- :doc:`bme680`
- :doc:`bmp085`
- :apiref:`sensor/bmp280_component.h`
- :apiref:`bmp280/bmp280.h`
- `BMP280 Library <https://github.com/adafruit/Adafruit_BMP280_Library>`__ by `Adafruit <https://www.adafruit.com/>`__
- :ghedit:`Edit`

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 3.0 KiB

After

Width:  |  Height:  |  Size: 3.0 KiB

2
components/sensor/cse7766.rst
View File

@ -56,5 +56,5 @@ See Also
--------
- :ref:`sensor-filters`
- :apiref:`sensor/cse7766.h`
- :apiref:`cse7766/cse7766.h`
- :ghedit:`Edit`

78
components/sensor/custom.rst
View File

@ -45,7 +45,7 @@ In ESPHome, a **sensor** is some hardware device (like a BMP180) that periodical
sends out numbers, for example a temperature sensor that periodically publishes its temperature **state**.
Another important abstraction in ESPHome is the concept of a **component**. In ESPHome,
a **component** is an object with a *lifecycle* managed by the :cpp:class:`Application` class.
a **component** is an object with a *lifecycle* managed by the :apiclass:`Application` class.
What does this mean? Well if you've coded in Arduino before you might know the two special methods
``setup()`` and ``loop()``. ``setup()`` is called one time when the node boots up and ``loop()`` is called
very often and this is where you can do things like read out sensors etc.
@ -59,9 +59,7 @@ So, let's now take a look at some code: This is an example of a custom component
#include "esphome.h"
using namespace esphome;
class MyCustomSensor : public Component, public sensor::Sensor {
class MyCustomSensor : public Component, public Sensor {
public:
void setup() override {
// This will be called by App.setup()
@ -71,37 +69,34 @@ So, let's now take a look at some code: This is an example of a custom component
}
};
In the first two lines, we're importing ESPHome so you can use the APIs and telling the compiler that
we want to use the esphome "namespace" (you don't need to know what this is now, it's basically just
there to have a clean, well-structured codebase).
In the first two lines, we're importing ESPHome so you can use the APIs via the ``#include``
statement.
Let's now also take a closer look at this line, which you might not be too used to when writing Arduino code:
.. code-block:: cpp
class MyCustomSensor : public Component, public sensor::Sensor {
class MyCustomSensor : public Component, public Sensor {
What this line is essentially saying is that we're defining our own class that's called ``MyCustomSensor``
which is also a subclass of :cpp:class:`Component` and :cpp:class:`sensor::Sensor`
(in the namespace ``sensor::``). As described before, these two "parent" classes have
special semantics that we will make use of.
which is also a subclass of :apiclass:`Component` and :apiclass:`Sensor <sensor::Sensor>`.
As described before, these two "parent" classes have special semantics that we will make use of.
We *could* go implement our own sensor code now by replacing the contents of ``setup()`` and ``loop()``.
In ``setup()`` we would initialize the sensor and in ``loop()`` we would read out the sensor and publish
the latest values.
However, there's a small problem with that approach: ``loop()`` gets called very often (about 60 times per second).
If we would publish a new state each time that method is called we would quickly make the node unresponsive
since the MQTT protocol wasn't really designed for 60 messages per second.
If we would publish a new state each time that method is called we would quickly make the node unresponsive.
So this fix this, we will use an alternative class to :cpp:class:`Component`: :cpp:class`PollingComponent`.
So this fix this, we will use an alternative class to :apiclass:`Component`: :apiclass:`PollingComponent`.
This class is for situations where you have something that should get called repeatedly with some **update interval**.
In the code above, we can simply replace :cpp:class:`Component` by :cpp:class:`PollingComponent` and
In the code above, we can simply replace :apiclass:`Component` by :apiclass:`PollingComponent` and
``loop()`` by a special method ``update()`` which will be called with an interval we can specify.
.. code-block:: cpp
class MyCustomSensor : public PollingComponent, public sensor::Sensor {
class MyCustomSensor : public PollingComponent, public Sensor {
public:
// constructor
MyCustomSensor() : PollingComponent(15000) {}
@ -115,11 +110,11 @@ In the code above, we can simply replace :cpp:class:`Component` by :cpp:class:`P
};
Our code has slightly changed, as explained above we're now inheriting from :cpp:class:`PollingComponent` instead of
just :cpp:class:`Component`. Additionally, we now have a new line: the constructor. You also don't really need to
Our code has slightly changed, as explained above we're now inheriting from :apiclass:`PollingComponent` instead of
just :apiclass:`Component`. Additionally, we now have a new line: the constructor. You also don't really need to
know much about constructors here, so to simplify let's just say this is where we "initialize" the custom sensor.
In this constructor we're telling the compiler that we want :cpp:class:`PollingComponent` to be instantiated with an
In this constructor we're telling the compiler that we want :apiclass:`PollingComponent` to be instantiated with an
*update interval* of 15s, or 15000 milliseconds (ESPHome uses milliseconds internally).
Let's also now make our sensor actually publish values in the ``update()`` method:
@ -220,8 +215,6 @@ Next, include the library at the top of your custom sensor file you created prev
#include "esphome.h"
#include "Adafruit_BMP085.h"
using namespace esphome;
// ...
Then update the sensor for BMP180 support:
@ -230,7 +223,7 @@ Then update the sensor for BMP180 support:
// ...
class MyCustomSensor : public PollingComponent, public sensor::Sensor {
class MyCustomSensor : public PollingComponent, public Sensor {
public:
Adafruit_BMP085 bmp;
@ -301,8 +294,8 @@ Let's look at what that could look like in code:
class MyCustomSensor : public PollingComponent {
public:
Adafruit_BMP085 bmp;
sensor::Sensor *temperature_sensor = new sensor::Sensor();
sensor::Sensor *pressure_sensor = new sensor::Sensor();
Sensor *temperature_sensor = new Sensor();
Sensor *pressure_sensor = new Sensor();
MyCustomSensor() : PollingComponent(15000) { }
@ -367,6 +360,43 @@ Configuration variables:
- All options from :ref:`Sensor <config-sensor>`.
.. note::
The ``id()`` wrapper for ESPHome-lambdas is not available in custom code. However, in most
cases you can drop the ``id()`` wrapper and use the ID directly: ``id(my_var).state`` ->
``my_var->state``
Logging in Custom Components
----------------------------
It is possible to log inside of custom components too. You can use the provided ``ESP_LOGx``
functions for this.
.. code-block:: cpp
ESP_LOGD("custom", "This is a custom debug message");
// Levels:
// - ERROR: ESP_LOGE
// - WARNING: ESP_LOGW
// - INFO: ESP_LOGI
// - DEBUG: ESP_LOGD
// - VERBOSE: ESP_LOGV
// - VERY_VERBOSE: ESP_LOGVV
ESP_LOGD("custom", "The value of sensor is: %f", this->state);
See :ref:`display-printf` for learning about how to use formatting in log strings.
.. note::
On ESP8266s you need to disable storing strings in flash to use logging in custom code.
.. code-block:: yaml
logger:
level: DEBUG
esp8266_store_log_strings_in_flash: False
See Also
--------

2
components/sensor/dallas.rst
View File

@ -151,5 +151,5 @@ See Also
- :doc:`max6675`
- `Arduino DallasTemperature library <https://github.com/milesburton/Arduino-Temperature-Control-Library>`__
by `Miles Burton <https://github.com/milesburton>`__
- :apiref:`sensor/dallas_component.h`
- :apiref:`dallas/dallas_component.h`
- :ghedit:`Edit`

2
components/sensor/dht.rst
View File

@ -83,6 +83,6 @@ See Also
- :doc:`hdc1080`
- :doc:`htu21d`
- :doc:`sht3xd`
- :apiref:`sensor/dht_component.h`
- :apiref:`dht/dht.h`
- `Arduino DHTLib <https://playground.arduino.cc/Main/DHTLib>`__
- :ghedit:`Edit`

2
components/sensor/dht12.rst
View File

@ -59,6 +59,6 @@ See Also
- :doc:`hdc1080`
- :doc:`htu21d`
- :doc:`sht3xd`
- :apiref:`sensor/dht12_component.h`
- :apiref:`dht12/dht12.h`
- `DHT12 Library <https://github.com/dplasa/dht>`__ by `Daniel Plasa <https://github.com/dplasa>`__
- :ghedit:`Edit`

2
components/sensor/duty_cycle.rst
View File

@ -37,5 +37,5 @@ See Also
--------
- :ref:`sensor-filters`
- :apiref:`sensor/duty_cycle_sensor.h`
- :apiref:`duty_cycle/duty_cycle_sensor.h`
- :ghedit:`Edit`

2
components/sensor/esp32_hall.rst
View File

@ -51,5 +51,5 @@ See Also
- :ref:`sensor-filters`
- :doc:`adc`
- :doc:`/devices/esp32`
- :apiref:`sensor/esp32_hall_sensor.h`
- :apiref:`esp32_hall/esp32_hall.h`
- :ghedit:`Edit`

2
components/sensor/hdc1080.rst
View File

@ -66,6 +66,6 @@ See Also
- :doc:`dht12`
- :doc:`htu21d`
- :doc:`sht3xd`
- :apiref:`sensor/hdc1080_component.h`
- :apiref:`hdc1080/hdc1080.h`
- `HDC1080 Library <https://github.com/closedcube/ClosedCube_HDC1080_Arduino>`__ by `ClosedCube <https://www.tindie.com/stores/closedcube/>`__
- :ghedit:`Edit`

2
components/sensor/hlw8012.rst
View File

@ -62,6 +62,6 @@ See Also
--------
- :ref:`sensor-filters`
- :apiref:`sensor/hlw8012.h`
- :apiref:`hlw8012/hlw8012.h`
- `HLW8012 Library <https://github.com/xoseperez/hlw8012>`__ by `Xose Pérez <https://github.com/xoseperez>`__
- :ghedit:`Edit`

3
components/sensor/hmc5883l.rst
View File

@ -52,7 +52,6 @@ See Also
- :ref:`sensor-filters`
- :doc:`template`
- :doc:`ultrasonic`
- :apiref:`sensor/hmc5883l.h`
- :apiref:`hmc5883l/hmc5883l.h`
- `HMC5883L Library <https://github.com/jarzebski/Arduino-HMC5883L>`__ by `Korneliusz Jarzębski <https://github.com/jarzebski>`__
- :ghedit:`Edit`

2
components/sensor/homeassistant.rst
View File

@ -37,5 +37,5 @@ See Also
- :ref:`sensor-filters`
- :ref:`automation`
- :apiref:`sensor/homeassistant_sensor.h`
- :apiref:`homeassistant/sensor/homeassistant_sensor.h`
- :ghedit:`Edit`

2
components/sensor/htu21d.rst
View File

@ -64,6 +64,6 @@ See Also
- :doc:`dht12`
- :doc:`hdc1080`
- :doc:`sht3xd`
- :apiref:`sensor/htu21d_component.h`
- :apiref:`htu21d/htu21d.h`
- `i2cdevlib <https://github.com/jrowberg/i2cdevlib>`__ by `Jeff Rowberg <https://github.com/jrowberg>`__
- :ghedit:`Edit`

17
components/sensor/hx711.rst
View File

@ -51,12 +51,13 @@ Converting Units
As the HX711 does not have any calibration data, you have to convert the measurement to units yourself.
To calibrate the sensor:
1. Place nothing or a known mass on the sensor, for example ``0kg``
1. Place a zero load or a known mass on the sensor, for example ``0kg``
2. Wait for the data to arrive in the logs and write down the value. For example ``120``.
3. Place another (different) known mass on the sensor, for example ``1kg``
4. Again wait for the data to arrive and note the value, for example ``810``.
Once you've done those steps, you can use the ``map`` function to map the incoming value to the calibrated one:
Once you've done those steps, you can use the ``calibrate_linear`` filter to map the incoming value
to the calibrated one:
.. code-block:: yaml
@ -65,13 +66,9 @@ Once you've done those steps, you can use the ``map`` function to map the incomi
- platform: hx711
# ... Other HX711 options
filters:
- lambda: |-
auto first_mass = 0.0; // first known mass was 0kg
auto first_value = 120.0; // value for the first known mass was 120
auto second_mass = 1.0; // second mass was 1kg
auto second_value = 810.0; // second value was 810
return map(x, first_value, second_value, first_mass, second_mass);
- calibrate_linear:
- 120 -> 0
- 810 -> 1
unit_of_measurement: kg
Replace the masses and values ``120.0``, ``810.0``, etc with your values.
@ -81,6 +78,6 @@ See Also
- :ref:`sensor-filters`
- :doc:`adc`
- :apiref:`sensor/hx711.h`
- :apiref:`hx711/hx711.h`
- `HX711 Library <https://github.com/bogde/HX711>`__ by `@bogde <https://github.com/bogde>`__
- :ghedit:`Edit`

2
components/sensor/ina219.rst
View File

@ -70,6 +70,6 @@ See Also
- :ref:`sensor-filters`
- :doc:`ina3221`
- :apiref:`sensor/ina219.h`
- :apiref:`ina219/ina219.h`
- `INA291 Arduino Library <https://github.com/adafruit/Adafruit_INA219>`__ by `Adafruit <https://www.adafruit.com/>`__
- :ghedit:`Edit`

2
components/sensor/ina3221.rst
View File

@ -81,6 +81,6 @@ See Also
- :ref:`sensor-filters`
- :doc:`ina219`
- :apiref:`sensor/ina3221.h`
- :apiref:`ina3221/ina3221.h`
- `INA3221 Arduino Library <https://github.com/switchdoclabs/SDL_Arduino_INA3221>`__ by `SwitchDoc Labs <https://github.com/switchdoclabs>`__
- :ghedit:`Edit`

64
components/sensor/integration.rst Normal file
View File

@ -0,0 +1,64 @@
Integration Sensor
==================
.. seo::
:description: Instructions for setting up sensors that integrate values over time.
:image: sigma.png
The ``integration`` sensor is a helper sensor that can integrate values from other sensors over
time. This can for example be useful to integrate the values of a water flow sensor (in m^2/s) over
time (result is in m^2).
This component can be considered a more-generic version of the :doc:`total_daily_energy`.
.. code-block:: yaml
# Example configuration entry
sensor:
- platform: integration
name: "Total Daily Energy"
sensor: my_flow_meter
time_unit: min
# The sensor to integrate, can be any power sensor
- platform: pulse_counter
# ...
id: my_flow_meter
Configuration variables:
------------------------
- **sensor** (**Required**, :ref:`config-id`): The ID of the sensor to integrate over time.
- **name** (**Required**, string): The name of the integration sensor.
- **time_unit** (**Required**, string): The time unit to integrate with, one of
``ms``, ``s``, ``min``, ``h`` or ``d``.
- **integration_method** (*Optional*, string): The integration method to use. One of
``trapezoid``, ``left`` or ``right``. Defaults to ``trapezoid``.
- **restore** (*Optional*, boolean): Whether to store the intermediate result on the device so
that the value can be restored upon power cycle or reboot.
Warning: this option can wear out your flash. Defaults to ``false``.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- All other options from :ref:`Sensor <config-sensor>`.
.. _sensor-integration-reset_action:
``sensor.integration.reset`` Action
-----------------------------------
This :ref:`Action <config-action>` allows you to reset the value of the integration sensor
to zero. For example this can be used to reset the integration sensor to zero at midnight with
a time-based automation.
.. code-block:: yaml
on_...:
- sensor.integration.reset: my_integration_sensor
See Also
--------
- :ref:`sensor-filters`
- :doc:`total_daily_energy`
- :doc:`/cookbook/power_meter`
- :apiref:`integration/integration_sensor.h`
- :ghedit:`Edit`

2
components/sensor/max31855.rst
View File

@ -53,5 +53,5 @@ See Also
- :doc:`sht3xd`
- :doc:`max6675`
- `MAX31855 Library <https://github.com/adafruit/Adafruit-MAX31855-library>`__ by `Adafruit <https://www.adafruit.com/>`__
- :apiref:`sensor/max31855_sensor.h`
- :apiref:`max31855/max31855.h`
- :ghedit:`Edit`

2
components/sensor/max6675.rst
View File

@ -60,5 +60,5 @@ See Also
- :doc:`adc`
- :doc:`sht3xd`
- `MAX6675 Library <https://github.com/adafruit/MAX6675-library>`__ by `Adafruit <https://www.adafruit.com/>`__
- :apiref:`sensor/max6675_sensor.h`
- :apiref:`max6675/max6675.h`
- :ghedit:`Edit`

2
components/sensor/mhz19.rst
View File

@ -72,5 +72,5 @@ See Also
- :ref:`sensor-filters`
- `MH-Z19 library <https://github.com/nara256/mhz19_uart>`__ by `@nara356 <https://github.com/nara256>`__
- :apiref:`sensor/mhz19_component.h`
- :apiref:`mhz19/mhz19.h`
- :ghedit:`Edit`

2
components/sensor/misc/custom-empty.h
View File

@ -2,7 +2,7 @@
using namespace esphome;
class MyCustomSensor : public PollingComponent, public sensor::Sensor {
class MyCustomSensor : public PollingComponent, public Sensor {
public:
MyCustomSensor() : PollingComponent(15000) {}

2
components/sensor/mpu6050.rst
View File

@ -78,6 +78,6 @@ See Also
- :ref:`sensor-filters`
- :doc:`template`
- :doc:`ultrasonic`
- :apiref:`sensor/mpu6050_component.h`
- :apiref:`mpu6050/mpu6050.h`
- `i2cdevlib <https://github.com/jrowberg/i2cdevlib>`__ by `Jeff Rowberg <https://github.com/jrowberg>`__
- :ghedit:`Edit`

2
components/sensor/mqtt_subscribe.rst
View File

@ -36,5 +36,5 @@ See Also
--------
- :ref:`sensor-filters`
- :apiref:`sensor/mqtt_subscribe_sensor.h`
- :apiref:`mqtt_subscribe/sensor/mqtt_subscribe_sensor.h`
- :ghedit:`Edit`

2
components/sensor/ms5611.rst
View File

@ -64,5 +64,5 @@ See Also
- :doc:`bme280`
- :doc:`bmp085`
- `Arduino MS5611 Library <https://github.com/jarzebski/Arduino-MS5611>`__ by `Korneliusz Jarzębski <https://github.com/jarzebski>`__
- :apiref:`sensor/ms5611.h`
- :apiref:`ms5611/ms5611.h`
- :ghedit:`Edit`

2
components/sensor/pmsx003.rst
View File

@ -60,5 +60,5 @@ See Also
- :doc:`/components/sensor/sds011`
- :ref:`sensor-filters`
- :apiref:`sensor/pmsx003.h`
- :apiref:`pmsx003/pmsx003.h`
- :ghedit:`Edit`

2
components/sensor/pulse_counter.rst
View File

@ -74,5 +74,5 @@ See Also
- :ref:`sensor-filters`
- :doc:`rotary_encoder`
- `esp-idf Pulse Counter API <https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/peripherals/pcnt.html>`__.
- :apiref:`sensor/pulse_counter.h`
- :apiref:`pulse_counter/pulse_counter_sensor.h`
- :ghedit:`Edit`

Some files were not shown because too many files have changed in this diff Show More