Upstream
/
esphome-docs
mirror of https://github.com/esphome/esphome-docs.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge branch 'current' into beta

This commit is contained in:
Jesse Hills 2021-09-14 23:05:54 +12:00
parent 29c2c57a62 0dac942a9f
commit da3a55f7db
No known key found for this signature in database
GPG Key ID: BEAAE804EFD8E83A
15 changed files with 152 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
components/display/index.rst
View File

@ -89,8 +89,7 @@ and circles:
it.filled_circle(25, 25, 10);
All the above methods can optionally also be called with an argument at the end which specifies in which
color to draw. Currently, only ``COLOR_ON`` (the default if color is not given) and ``COLOR_OFF`` are supported because
ESPHome only has implemented binary displays.
color to draw. For monochrome displays, only ``COLOR_ON`` (the default if color is not given) and ``COLOR_OFF`` are supported.
.. code-block:: yaml
@ -109,6 +108,23 @@ ESPHome only has implemented binary displays.
// Turn off a whole display portion.
it.rectangle(50, 50, 30, 42, COLOR_OFF);
For color displays (e.g. TFT displays), you can use the Color class.
.. code-block:: yaml
display:
- platform: ...
# ...
lambda: |-
auto red = Color(255, 0, 0);
auto green = Color(0, 255, 0);
auto blue = Color(0, 0, 255);
auto white = Color(255, 255, 255);
it.rectangle(20, 50, 30, 30, white);
it.rectangle(25, 55, 30, 30, red);
it.rectangle(30, 60, 30, 30, green);
it.rectangle(35, 65, 30, 30, blue);
Additionally, you have access to two helper methods which will fetch the width and height of the display:
.. code-block:: yaml

2
components/display/ssd1351.rst
View File

@ -89,7 +89,7 @@ To bring in color images:
- file: "image.jpg"
id: my_image
resize: 120x120
type: RGB
type: RGB24
...

15
components/esphome.rst
View File

@ -45,9 +45,9 @@ Advanced options:
but you can customize this behavior using this option.
- **platformio_options** (*Optional*, mapping): Additional options to pass over to PlatformIO in the
platformio.ini file. See :ref:`esphome-platformio_options`.
- **includes** (*Optional*, list of files): A list of C[++] files to include in the main (auto-generated) sketch file
- **includes** (*Optional*, list of files): A list of C/C++ files to include in the main (auto-generated) sketch file
for custom components. The paths in this list are relative to the directory where the YAML configuration file
is in. Should have file extension ``.h`` - See :ref:`esphome-includes` for more info.
is in. See :ref:`esphome-includes` for more info.
- **libraries** (*Optional*, list of libraries): A list of `platformio libraries <https://platformio.org/lib>`__
to include in the project. See `platformio lib install <https://docs.platformio.org/en/latest/userguide/lib/cmd_install.html>`__.
- **comment** (*Optional*, string): Additional text information about this node. Only for display in UI.
@ -267,10 +267,13 @@ The ``includes`` option is only a helper option that does that for you.
This option behaves differently depending on what the included file is pointing at:
- If the include string is pointing at a directory, the entire directory tree is copied over
to the src/ folder.
- If the include string is point at a header file (.h, .hpp, .tcc) - it is copied in the src/ folder
AND included in the main.cpp. This way the lambda code can access it.
- If the include string is pointing at a directory, the entire directory tree is copied into the
src/ folder.
- If the include string points to a header file (.h, .hpp, .tcc), it is copied in the src/ folder
AND included in the ``main.cpp`` file. This way the lambda code can access it.
- If the include string points to a regular source file (.c, .cpp), it is copied in the src/ folder
AND compiled into the binary. This way implementation of classes and functions in header files can
be provided.
.. _esphome-changing_node_name:

79
components/fan/index.rst
View File

@ -113,7 +113,7 @@ Configuration options:
.. _fan-is_off_condition:
``fan.is_on`` / ``fan.is_off`` Condition
**********************************************
----------------------------------------
This :ref:`condition <config-condition>` passes if the given fan is on/off.
@ -131,7 +131,7 @@ This :ref:`condition <config-condition>` passes if the given fan is on/off.
.. _fan-on_turn_on_off_trigger:
``fan.on_turn_on`` / ``fan.on_turn_off`` Trigger
****************************************************
------------------------------------------------
This trigger is activated each time the fan is turned on or off. It does not fire
if a command to turn the fan on or off already matches the current state.
@ -149,9 +149,9 @@ if a command to turn the fan on or off already matches the current state.
.. _fan-on_speed_set_trigger:
``fan.on_speed_set`` Trigger
****************************************************
----------------------------
This trigger is activated each time the fan speed is changed. It will fire when the speed is either set via API e.g. in Home Assistant or locally by an automation or a lambda function.
This trigger is activated each time the fan speed is changed. It will fire when the speed is either set via API e.g. in Home Assistant or locally by an automation or a lambda function.
.. code-block:: yaml
@ -161,6 +161,77 @@ This trigger is activated each time the fan speed is changed. It will fire when
on_speed_set:
- logger.log: "Fan Speed was changed!"
Lambda calls
------------
From :ref:`lambdas <config-lambda>`, you can call several methods on all fans to do some
advanced stuff (see the full API Reference for more info).
- ``state``: Retrieve the current state (on/off) of the fan.
.. code-block:: yaml
// Within lambda, get the fan state and conditionally do something
if (id(my_fan).state) {
// Fan is ON, do something here
} else {
// Fan is OFF, do something else here
}
- ``speed``: Retrieve the current speed of the fan.
.. code-block:: yaml
// Within lambda, get the fan speed and conditionally do something
if (id(my_fan).speed == 2) {
// Fan speed is 2, do something here
} else {
// Fan speed is not 2, do something else here
}
- ``oscillating``: Retrieve the current oscillating state of the fan.
.. code-block:: yaml
// Within lambda, get the fan oscillating state and conditionally do something
if (id(my_fan).oscillating) {
// Fan is oscillating, do something here
} else {
// Fan is not oscillating, do something else here
}
- ``direction``: Retrieve the current direction of the fan.
.. code-block:: yaml
// Within lambda, get the fan direction and conditionally do something
if (id(my_fan).direction == FanDirection::FAN_DIRECTION_FORWARD) {
// Fan direction is forward, do something here
} else {
// Fan direction is reverse, do something else here
}
- ``turn_off()``/``turn_on()``/``toggle()``: Manually turn the fan ON/OFF from code.
Similar to the ``fan.turn_on``, ``fan.turn_off``, and ``fan.toggle`` actions,
but can be used in complex lambda expressions.
.. code-block:: yaml
// Turn the fan off
auto call = id(my_fan).turn_off();
call.perform();
// Turn the fan on and set the speed, oscillating, and direction
auto call = id(my_fan).turn_on();
call.set_speed(2);
call.set_oscillating(true);
call.set_direction(FanDirection::FAN_DIRECTION_REVERSE);
call.perform();
// Toggle the fan on/off
auto call = id(my_fan).toggle();
call.perform();
Full Fan Index
--------------

2
components/i2c.rst
View File

@ -36,7 +36,7 @@ Configuration variables:
- **scan** (*Optional*, boolean): If ESPHome should do a search of the I²C address space on startup.
Defaults to ``true``.
- **frequency** (*Optional*, float): Set the frequency the I²C bus should operate on.
Defaults to ``50kHz``. Values are ``50kHz``, ``100kHz``, ``200kHz``, ... ``800kHz``
Defaults to ``50kHz``. Values are ``10kHz``, ``50kHz``, ``100kHz``, ``200kHz``, ... ``800kHz``
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID for this I²C bus if you need multiple I²C buses.
.. note::

2
components/pipsolar.rst
View File

@ -32,7 +32,7 @@ This component will poll the needed polling commands in a loop. If there is a co
There is a buffer to buffer up to 10 commands.
.. |here| replace:: ``here``
.. _here: https://github.com/jblance/mpp-solar/raw/master/docs/PI30_PIP-GK_MK-Protocol.pdf
.. _here: https://github.com/jblance/mpp-solar/tree/master/docs
.. code-block:: yaml

8
components/sensor/as3935.rst
View File

@ -83,7 +83,7 @@ Configuration variables:
- **noise_level** (*Optional*, integer): Noise floor level is compared to known reference voltage.
If this level is exceeded the chip will issue an interrupt to the IRQ pin, broadcasting that it can not
operate properly due to noise (INT_NH). Defaults to ``2``.
- **spike_rejection** (*Optional*, integer): Helps to differentiate between real events and actual lightning.
- **spike_rejection** (*Optional*, integer): Helps to differentiate between false events and actual lightning.
Increasing this value increases robustness at the cost of sensitivity to distant events. Defaults to ``2``.
- **lightning_threshold** (*Optional*, integer): The number of lightnings that must appear in a 15-minute time
window before a lightning storm is detected.
@ -129,14 +129,14 @@ Configuration variables:
- **address** (*Optional*, int): Manually specify the I²C address of
the sensor. Defaults to ``0x03`` (``A0` and ``A1`` pins pulled low).
Another address can be ``0x02``.
the sensor. Defaults to ``0x03`` (``A0`` and ``A1`` pins pulled high).
The address is made up using the state of ``A0`` as bit 1 and the state of ``A1`` as bit 2, so a total of four addresses is possible.
- **irq_pin** (**Required**, :ref:`config-pin`): The IRQ pin, which indicates if a lightning strike has been detected.
- **indoor** (*Optional*, boolean): Indicates if the sensor is used indoor. Defaults to ``true``.
- **noise_level** (*Optional*, integer): Noise floor level is compared to known reference voltage.
If this level is exceeded the chip will issue an interrupt to the IRQ pin, broadcasting that it can not
operate properly due to noise (INT_NH). Defaults to ``2``.
- **spike_rejection** (*Optional*, integer): Helps to differentiate between real events and actual lightning.
- **spike_rejection** (*Optional*, integer): Helps to differentiate between false events and actual lightning.
Increasing this value increases robustness at the cost of sensitivity to distant events. Defaults to ``2``.
- **lightning_threshold** (*Optional*, integer): The number of lightnings that must appear in a 15-minute time
window before a lightning storm is detected.

3
components/sensor/atm90e32.rst
View File

@ -125,6 +125,9 @@ It is possible that the two identical CT current sensors will have different
small. The current calibration can be done once and used on all sensors or
repeated for each one.
Here are common current calibration values for the **Split Single Phase Energy Meter** when **gain_pga** is set to ``4X``:
- 200A/100mA SCT-024: 12597
Here are common current calibration values for the **Split Single Phase Energy Meter** when **gain_pga** is set to ``2X``:
- 20A/25mA SCT-006: 10170
- 100A/50mA SCT-013-000: 25498

2
components/sensor/dsmr.rst
View File

@ -223,7 +223,7 @@ Configuration variables:
Belgium
- **p1_version_be** (*Optional*): DSMR Version Beligum
- **p1_version_be** (*Optional*): DSMR Version Belgium
- **name** (**Required**, string): The name for the p1_version_be text sensor.
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.

1
components/sensor/mhz19.rst
View File

@ -8,6 +8,7 @@ MH-Z19 CO_2 and Temperature Sensor
The ``mhz19`` sensor platform allows you to use MH-Z19 CO_2 and temperature sensors
(`refspace`_) with ESPHome.
The CO_2 measurement also works with the MH-Z16 sensor.
.. figure:: images/mhz19-full.jpg
:align: center

4
components/sensor/sgp40.rst
View File

@ -48,8 +48,8 @@ Example With Compensation
name: "Workshop VOC"
update_interval: 5s
compensation:
humidity_source: dht1_temp
temperature_source: dht1_hum
humidity_source: dht1_hum
temperature_source: dht1_temp
See Also
--------

2
components/sensor/tsl2591.rst
View File

@ -168,7 +168,7 @@ there is a delay for the ADC to go through an integration cycle before a reliabl
The delay is appoximately the configured integration time.
The implementation uses asynchronous delays to wait for the ADC readings to become available.
This avoids slowing down the overall ESPHome update loop,
but it means that the publishing of state updates for the TSL2561 might come slightly later.
but it means that the publishing of state updates for the TSL2591 might come slightly later.
If you use the TSL2591 API to change the gain or integration time value,
the device is internally disabled and re-enabled.

20
components/switch/index.rst
View File

@ -101,7 +101,7 @@ This :ref:`Condition <config-condition>` checks if the given switch is ON (or OF
lambda calls
************
From :ref:`lambdas <config-lambda>`, you can call several methods on all covers to do some
From :ref:`lambdas <config-lambda>`, you can call several methods on all switches to do some
advanced stuff (see the full API Reference for more info).
- ``publish_state()``: Manually cause the switch to publish a new state and store it internally.
@ -135,24 +135,6 @@ advanced stuff (see the full API Reference for more info).
// Toggle the switch
id(my_switch).toggle();
.. _switch-is_on_off_condition:
``switch.is_on`` / ``switch.is_off`` Condition
**********************************************
This :ref:`condition <config-condition>` passes if the given switch is on/off.
.. code-block:: yaml
# in a trigger:
on_...:
if:
condition:
switch.is_on: my_switch
# same goes for is_off
then:
- script.execute: my_script
.. _switch-on_turn_on_off_trigger:
``switch.on_turn_on`` / ``switch.on_turn_off`` Trigger

42
cookbook/leak-detector-m5stickC.rst
View File

@ -15,11 +15,11 @@ Using the ESP32's capacitive touch GPIOs, it's relatively easy to build a water
Things you'll need
==================
- M5Stick esphome components
https://github.com/airy10/esphome-m5stickC/issues/4
- `M5Stick axp192 custom component <https://github.com/airy10/esphome-m5stickC>`__
This is needed to power up the display. You don't need the st7735 display driver, as it is already included with ESPHome >1.16.0.
- M5StickC ESP32 development kit
`M5Stack Link <https://m5stack.com/collections/m5-core/products/stick-c>`__
`M5Stack Link <https://m5stack.com/collections/m5-core/products/stick-c>`__
.. figure:: images/leak-detector-m5stickC-m5stickC.png
:align: center
@ -74,7 +74,7 @@ Flashing
I initially had trouble flashing the M5StickC; this is the procedure that I've found to work well with these devices.
You must provide the ESP32 bootloader during the initial flash over USB. Compile your ESPHome binary, and flash it along with the required bootloader (bootloader_dio_80m.bin), `available here <https://github.com/espressif/arduino-esp32/tree/master/tools/sdk/bin>`__, from the commandline (example under macos):
You must provide the ESP32 bootloader during the initial flash over USB. Compile your ESPHome binary, and flash it along with the required bootloader (bootloader_dio_80m.bin), `available here <https://github.com/espressif/arduino-esp32/tree/master/tools/sdk/esp32/bin>`__, from the commandline (example under macos):
``cd /Applications/ESPHome-Flasher-1.2.0-macOS.app/Contents/MacOS``
@ -252,25 +252,44 @@ ESPHome configuration
id: font1
size: 66
# wonky color fix, in lieu of finding a way to invert the display
color:
- id: color_wet
red: 100%
green: 100%
blue: 0%
- id: color_dry
red: 100%
green: 0%
blue: 100%
# built-in 80x160 TFT
display:
- platform: st7735
model: "INITR_MINI160X80"
device_height: 160
device_width: 82
col_start: 0
row_start: 0
eight_bit_color: false
cs_pin: GPIO5
dc_pin: GPIO23
reset_pin: GPIO18
rotation: 180
lambda: |-
if (id(leak).state) {
it.print(38, -24, id(font1), ST77XX_RED, TextAlign::TOP_CENTER, "W");
it.print(38, 32, id(font1), ST77XX_RED, TextAlign::TOP_CENTER, "E");
it.print(38, 85, id(font1), ST77XX_RED, TextAlign::TOP_CENTER, "T");
it.fill(COLOR_ON);
it.print(42, -24, id(font1), id(color_wet), TextAlign::TOP_CENTER, "W");
it.print(42, 32, id(font1), id(color_wet), TextAlign::TOP_CENTER, "E");
it.print(42, 85, id(font1), id(color_wet), TextAlign::TOP_CENTER, "T");
} else {
it.print(38, -24, id(font1), ST77XX_GREEN, TextAlign::TOP_CENTER, "D");
it.print(38, 32, id(font1), ST77XX_GREEN, TextAlign::TOP_CENTER, "R");
it.print(38, 85, id(font1), ST77XX_GREEN, TextAlign::TOP_CENTER, "Y");
it.fill(COLOR_ON);
it.print(42, -24, id(font1), id(color_dry), TextAlign::TOP_CENTER, "D");
it.print(42, 32, id(font1), id(color_dry), TextAlign::TOP_CENTER, "R");
it.print(42, 85, id(font1), id(color_dry), TextAlign::TOP_CENTER, "Y");
}
HomeAssistant configuration
===========================
@ -314,5 +333,6 @@ See Also
========
- :doc:`/components/display/index`
- :doc:`/components/display/st7735`
- :doc:`/components/binary_sensor/esp32_touch`
- :ghedit:`Edit`

5
index.rst
View File

@ -179,6 +179,7 @@ Air Quality
PMSX003, components/sensor/pmsx003, pmsx003.svg, Particulate
SDS011 Sensor, components/sensor/sds011, sds011.jpg, Particulate
SenseAir, components/sensor/senseair, senseair_s8.jpg, CO2
SCD30, components/sensor/scd30, scd30.jpg, CO2 & Temperature & Humidity
SGP30, components/sensor/sgp30, sgp30.jpg, CO2 & Volatile organics
SGP40, components/sensor/sgp40, sgp40.jpg, Volatile organics
SM300D2, components/sensor/sm300d2, sm300d2.jpg, Air quality
@ -264,7 +265,7 @@ Environmental
BME680, components/sensor/bme680, bme680.jpg, Temperature & Humidity & Pressure & Gas
BME680 via BSEC, components/sensor/bme680_bsec, bme680.jpg, Temperature & Humidity & Pressure & Gas
BMP085, components/sensor/bmp085, bmp180.jpg, Temperature & Pressure
BMP280, components/sensor/bmp280, bmp280.jpg, Temperature & Humidity & Pressure
BMP280, components/sensor/bmp280, bmp280.jpg, Temperature & Pressure
b-parasite, components/sensor/b_parasite, b_parasite.jpg, Moisture & Temperature & Humidity
Dallas DS18B20, components/sensor/dallas, dallas.jpg, Temperature
DHT, components/sensor/dht, dht.jpg, Temperature & Humidity
@ -277,7 +278,7 @@ Environmental
MS5611, components/sensor/ms5611, ms5611.jpg, Pressure
NTC Thermistor, components/sensor/ntc, ntc.jpg, Temperature
RuuviTag, components/sensor/ruuvitag, ruuvitag.jpg, Temperature & Humidity & Accelerometer
SCD30, components/sensor/scd30, scd30.jpg, Temperature & Humidity
SCD30, components/sensor/scd30, scd30.jpg, CO2 & Temperature & Humidity
SDP3x, components/sensor/sdp3x, sdp31.jpg, Pressure
SHT3X-D, components/sensor/sht3xd, sht3xd.jpg, Temperature & Humidity
SHT4X, components/sensor/sht4x, sht4x.jpg, Temperature & Humidity