diff --git a/components/display/index.rst b/components/display/index.rst index a3264dfd1..fcf63d50b 100644 --- a/components/display/index.rst +++ b/components/display/index.rst @@ -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 diff --git a/components/display/ssd1351.rst b/components/display/ssd1351.rst index 64d46c112..0686ca264 100644 --- a/components/display/ssd1351.rst +++ b/components/display/ssd1351.rst @@ -89,7 +89,7 @@ To bring in color images: - file: "image.jpg" id: my_image resize: 120x120 - type: RGB + type: RGB24 ... diff --git a/components/esphome.rst b/components/esphome.rst index ec664a8dd..deac76f21 100644 --- a/components/esphome.rst +++ b/components/esphome.rst @@ -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 `__ to include in the project. See `platformio lib install `__. - **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: diff --git a/components/fan/index.rst b/components/fan/index.rst index d29fafe64..028d5a32d 100644 --- a/components/fan/index.rst +++ b/components/fan/index.rst @@ -113,7 +113,7 @@ Configuration options: .. _fan-is_off_condition: ``fan.is_on`` / ``fan.is_off`` Condition -********************************************** +---------------------------------------- This :ref:`condition ` passes if the given fan is on/off. @@ -131,7 +131,7 @@ This :ref:`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 `, 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 -------------- diff --git a/components/i2c.rst b/components/i2c.rst index 9b87908a9..5f1bfcb8c 100644 --- a/components/i2c.rst +++ b/components/i2c.rst @@ -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:: diff --git a/components/pipsolar.rst b/components/pipsolar.rst index 31b0b4e9c..5524cf0e7 100644 --- a/components/pipsolar.rst +++ b/components/pipsolar.rst @@ -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 diff --git a/components/sensor/as3935.rst b/components/sensor/as3935.rst index 98c62c90e..d4ade816a 100644 --- a/components/sensor/as3935.rst +++ b/components/sensor/as3935.rst @@ -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. diff --git a/components/sensor/atm90e32.rst b/components/sensor/atm90e32.rst index 2d9d4c27e..07509a624 100644 --- a/components/sensor/atm90e32.rst +++ b/components/sensor/atm90e32.rst @@ -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 diff --git a/components/sensor/dsmr.rst b/components/sensor/dsmr.rst index c7e90c644..211c6befc 100644 --- a/components/sensor/dsmr.rst +++ b/components/sensor/dsmr.rst @@ -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. diff --git a/components/sensor/mhz19.rst b/components/sensor/mhz19.rst index 1e821c757..5245f151d 100644 --- a/components/sensor/mhz19.rst +++ b/components/sensor/mhz19.rst @@ -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 diff --git a/components/sensor/sgp40.rst b/components/sensor/sgp40.rst index 3da638540..8ea7f92cc 100644 --- a/components/sensor/sgp40.rst +++ b/components/sensor/sgp40.rst @@ -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 -------- diff --git a/components/sensor/tsl2591.rst b/components/sensor/tsl2591.rst index acce84379..f03833604 100644 --- a/components/sensor/tsl2591.rst +++ b/components/sensor/tsl2591.rst @@ -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. diff --git a/components/switch/index.rst b/components/switch/index.rst index eb02ce442..35daf5834 100644 --- a/components/switch/index.rst +++ b/components/switch/index.rst @@ -101,7 +101,7 @@ This :ref:`Condition ` checks if the given switch is ON (or OF lambda calls ************ -From :ref:`lambdas `, you can call several methods on all covers to do some +From :ref:`lambdas `, 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 ` 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 diff --git a/cookbook/leak-detector-m5stickC.rst b/cookbook/leak-detector-m5stickC.rst index 5f1f03883..f42a737f3 100644 --- a/cookbook/leak-detector-m5stickC.rst +++ b/cookbook/leak-detector-m5stickC.rst @@ -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 `__ + 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 `__ + `M5Stack Link `__ .. 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 `__, 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 `__, 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` diff --git a/index.rst b/index.rst index 1a476f3ea..2f2720792 100644 --- a/index.rst +++ b/index.rst @@ -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