Upstream/esphome-docs
1
0
Fork 0
mirror of https://github.com/esphome/esphome-docs.git synced 2024-06-22 09:54:49 +02:00
Code Issues Projects Releases Wiki Activity

Merge pull request #712 from esphome/bump-1.15.0b1

Browse Source
This commit is contained in:
Otto Winter 2020-07-27 12:18:20 +02:00 committed by GitHub
commit e4b54d2b4b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
182 changed files with 6650 additions and 810 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
.gitignore vendored
View File

@ -1,8 +1,13 @@
_build
.DS_Store
.python-version
__pycache__/
*.py[cod]
*$py.class
venv
.vscode
*.DS_Store
/.idea/

3
.vscode/settings.json vendored
View File

@ -1,3 +0,0 @@
{
"restructuredtext.confPath": "${workspaceFolder}"
}

2
Doxygen
View File

@ -38,7 +38,7 @@ PROJECT_NAME = "ESPHome"
# could be handy for archiving the generated documentation or if some version
# control system is used.
PROJECT_NUMBER = 1.14.4
PROJECT_NUMBER = 1.15.0b1
# Using the PROJECT_BRIEF tag one can provide an optional one line description
# for a project that appears at the top of each page and should give viewer a

2
Makefile
View File

@ -1,5 +1,5 @@
ESPHOME_PATH = ../esphome
ESPHOME_REF = v1.14.4
ESPHOME_REF = v1.15.0b1
.PHONY: html html-strict cleanhtml deploy help webserver Makefile netlify netlify-api api netlify-dependencies svg2png copy-svg2png

2
_static/version
View File

@ -1 +1 @@
1.14.4
1.15.0b1

14
_static/webserver-v1.js
View File

@ -56,4 +56,18 @@ for (; row = states.rows[i]; i++) {
});
})(row.id);
}
if (row.classList.contains("cover")) {
(function(id) {
row.children[2].children[0].addEventListener('click', function () {
const xhr = new XMLHttpRequest();
xhr.open("POST", '/cover/' + id.substr(6) + '/open', true);
xhr.send();
});
row.children[2].children[1].addEventListener('click', function () {
const xhr = new XMLHttpRequest();
xhr.open("POST", '/cover/' + id.substr(6) + '/close', true);
xhr.send();
});
})(row.id);
}
}

2
_static/webserver-v1.min.js vendored
View File

@ -1 +1 @@
const source=new EventSource("/events");source.addEventListener("log",function(a){const b=document.getElementById("log");let c="";a.data.startsWith("\x1B[1;31m")?c="e":a.data.startsWith("\x1B[0;33m")?c="w":a.data.startsWith("\x1B[0;32m")?c="i":a.data.startsWith("\x1B[0;35m")?c="c":a.data.startsWith("\x1B[0;36m")?c="d":a.data.startsWith("\x1B[0;37m")?c="v":b.innerHTML+=a.data+"\n",b.innerHTML+="<span class=\""+c+"\">"+a.data.substr(7,a.data.length-10)+"</span>\n"}),source.addEventListener("state",function(a){const b=JSON.parse(a.data);document.getElementById(b.id).children[1].innerText=b.state});const states=document.getElementById("states");for(let a,b=0;a=states.rows[b];b++)a.classList.contains("switch")&&function(b){a.children[2].children[0].addEventListener("click",function(){const a=new XMLHttpRequest;a.open("POST","/switch/"+b.substr(7)+"/toggle",!0),a.send()})}(a.id),a.classList.contains("fan")&&function(b){a.children[2].children[0].addEventListener("click",function(){const a=new XMLHttpRequest;a.open("POST","/fan/"+b.substr(4)+"/toggle",!0),a.send()})}(a.id),a.classList.contains("light")&&function(b){a.children[2].children[0].addEventListener("click",function(){const a=new XMLHttpRequest;a.open("POST","/light/"+b.substr(6)+"/toggle",!0),a.send()})}(a.id);
const source=new EventSource("/events");source.addEventListener("log",function(a){const b=document.getElementById("log");let c="";a.data.startsWith("\x1B[1;31m")?c="e":a.data.startsWith("\x1B[0;33m")?c="w":a.data.startsWith("\x1B[0;32m")?c="i":a.data.startsWith("\x1B[0;35m")?c="c":a.data.startsWith("\x1B[0;36m")?c="d":a.data.startsWith("\x1B[0;37m")?c="v":b.innerHTML+=a.data+"\n",b.innerHTML+="<span class=\""+c+"\">"+a.data.substr(7,a.data.length-10)+"</span>\n"}),source.addEventListener("state",function(a){const b=JSON.parse(a.data);document.getElementById(b.id).children[1].innerText=b.state});const states=document.getElementById("states");for(let a,b=0;a=states.rows[b];b++)a.classList.contains("switch")&&function(b){a.children[2].children[0].addEventListener("click",function(){const a=new XMLHttpRequest;a.open("POST","/switch/"+b.substr(7)+"/toggle",!0),a.send()})}(a.id),a.classList.contains("fan")&&function(b){a.children[2].children[0].addEventListener("click",function(){const a=new XMLHttpRequest;a.open("POST","/fan/"+b.substr(4)+"/toggle",!0),a.send()})}(a.id),a.classList.contains("light")&&function(b){a.children[2].children[0].addEventListener("click",function(){const a=new XMLHttpRequest;a.open("POST","/light/"+b.substr(6)+"/toggle",!0),a.send()})}(a.id),a.classList.contains("cover")&&function(b){a.children[2].children[0].addEventListener("click",function(){const a=new XMLHttpRequest;a.open("POST","/cover/"+b.substr(6)+"/open",!0),a.send()}),a.children[2].children[1].addEventListener("click",function(){const a=new XMLHttpRequest;a.open("POST","/cover/"+b.substr(6)+"/close",!0),a.send()})}(a.id);

2
changelog/index.rst
View File

@ -2,7 +2,7 @@ Changelog
=========
.. redirect::
:url: /changelog/v1.14.0.html
:url: /changelog/v1.15.0.html
.. toctree::
:glob:

2
changelog/v1.14.0.rst
View File

@ -306,7 +306,7 @@ Notable Changes & New Features
- Add configurable ignore bits to rc_switch_raw codes (:esphomepr:`650` by :ghuser:`mtl010957`,
:doc:`docs </components/remote_receiver>`).
- New ``restore`` option has been added to :doc:`servos </components/servo>` (:esphomepr:`829`).
- Add IR receiver support for coolix climate devices (:esphomepr:`645` by :ghuser:`glmnet`, :doc:`docs </components/climate/coolix>`).
- Add IR receiver support for coolix climate devices (:esphomepr:`645` by :ghuser:`glmnet`, :doc:`docs </components/climate/ir_climate>`).
- Add :ref:`calibrate_polynomial <sensor-calibrate_polynomial>` sensor filter (:esphomepr:`642`).
- Allow setting the initial mode of HLW8012 sensors (:esphomepr:`611` by :ghuser:`brandond`, :doc:`docs </components/sensor/hlw8012>`).
- Add tilt actions to :doc:`template cover </components/cover/template>` (:esphomepr:`577` by :ghuser:`mtl010957`).

541
changelog/v1.15.0.rst Normal file
View File

@ -0,0 +1,541 @@
Changelog - Version 1.15.0 - Release Date TBD
=============================================
.. seo::
:description: Changelog for ESPHome version 1.15.0.
:image: /_static/changelog-1.15.0.png
:author: Otto Winter
:author_twitter: @OttoWinter_
.. imgtable::
:columns: 5
AHT10, components/sensor/aht10, aht10.jpg
QMC5883L, components/sensor/qmc5883l, qmc5883l.jpg
INA226, components/sensor/ina226, ina226.jpg
HM3301, components/sensor/hm3301, hm3301.jpg
MAX31856, components/sensor/max31856, max31856.jpg
MAX31865, components/sensor/max31865, max31865.jpg
RuuviTag, components/sensor/ruuvitag, ruuvitag.jpg
SPS30, components/sensor/sps30, sps30.jpg
TMP117, components/sensor/tmp117, tmp117.jpg
Xiaomi BLE, components/sensor/xiaomi_ble, xiaomi_mijia_logo.jpg
Slow PWM, components/output/slow_pwm, pwm.png
ESP32 DAC, components/output/esp32_dac, dac.svg
AC Dimmer, components/output/ac_dimmer, ac_dimmer.svg
Tuya Fan, components/fan/tuya, fan.svg
MAX7219 Dot Matrix, components/display/max7219digit, max7219digit.png
TM1637, components/display/tm1637, tm1637.jpg
ST7789V, components/display/st7789v, st7789v.jpg
PCD8544 (Nokia 5110/ 3310), components/display/pcd8544, pcd8544.jpg
BLE Scanner, components/text_sensor/ble_scanner, bluetooth.svg
Custom UART Text Sensor, components/text_sensor/uart, language-cpp.svg
Thermostat Controller, components/climate/thermostat, air-conditioner.svg
PID Controller, components/climate/pid, function.svg
IR Remote Climate, components/climate/ir_climate, air-conditioner-ir.svg
HTTP Request, components/http_request, connection.svg
MCP3008 8-Channel 10-Bit A/D Converter, components/mcp3008, mcp3008.png
SN74HC595 I/O Expander, components/sn74hc595, sn74hc595.jpg
TM1651 Battery Display, components/tm1651, tm1651_battery_display.jpg
RF Bridge, components/rf_bridge, rf_bridge.jpg
*This is currently a draft document.*
...Intro text...
New Components
**************
...Text...
Updated Components
******************
...More text...
Last but not least, thanks to all contributors, bug reporters and patrons! Without you this would not
be possible!
Breaking Changes
----------------
- Scripts
- ``script.stop: script_id`` now stops the script itself and next actions will not be executed.
`(#1004) <https://github.com/esphome/esphome/pull/1004>`__
- esphome: Fix SGP30 incorrect baseline reading/writing :esphomepr:`936` by :ghuser:`panuruj` (breaking-change)
- esphome: fix servo bug restoring state and starting servo detached :esphomepr:`1008` by :ghuser:`glmnet` (breaking-change)
- esphome: fix shunt voltage / current / power reading in INA3221 :esphomepr:`1101` by :ghuser:`Vxider` (breaking-change)
- esphome: Fix: Component script not stopped in certain situations :esphomepr:`1004` by :ghuser:`balrog-kun` (breaking-change)
- esphome: New script modes POC :esphomepr:`1168` (breaking-change)
Notable Changes & New Features
------------------------------
- Dashboard Interface Revamped
- New Thermostat Controller implements ESPHome actions for all available Home Assistant climate actions,
climate modes, fan modes, and fan swing modes (:esphomepr:`1105`)
- Color (and grayscale) display support! (#1050)
- SSD1325 component updated to facilitate use of grayscale
- esphome: Add AC Dimmer support :esphomepr:`880` (new-feature)
- esphome: Uart improvments :esphomepr:`1024` by :ghuser:`0hax` (notable-change)
- esphome: Add support for additional Xiaomi BLE sensors :esphomepr:`1027` by :ghuser:`ahpohl` (notable-change)
- esphome: Packages feature :esphomepr:`1052` by :ghuser:`corvis` (notable-change)
New Integrations
----------------
- esphome: Add HM3301 laser dust detection sensor :esphomepr:`963` by :ghuser:`freekode` (new-integration)
- esphome: Climate whirlpool :esphomepr:`1029` by :ghuser:`glmnet` (new-integration)
- esphome: Adding support for MAX31856 Thermocouple Temperature Sensor (feature #700) :esphomepr:`1039` by :ghuser:`declanshanaghy` (new-integration)
- esphome: Add E1.31 support :esphomepr:`950` by :ghuser:`ayufan` (new-integration)
- esphome: add support for SN74HC595 shift register :esphomepr:`1083` by :ghuser:`phjr` (new-integration)
TODO: Merge with below
New Features
------------
- esphome: Add AC Dimmer support :esphomepr:`880` (new-feature) (new-integration)
- esphome: add lights on off triggers :esphomepr:`1037` by :ghuser:`glmnet` (new-feature)
- esphome: Dashboard Updates :esphomepr:`1025` by :ghuser:`jonathanadams` (new-feature) (notable-change)
- esphome: Ble scanner :esphomepr:`976` by :ghuser:`TheKuko` (new-feature)
- esphome: Add Prometheus /metrics-Endpoint :esphomepr:`1032` by :ghuser:`margau` (new-feature)
- esphome: Add support for command-line substitutions :esphomepr:`1014` by :ghuser:`AlexMekkering` (new-feature)
- esphome: Packages feature :esphomepr:`1052` by :ghuser:`corvis` (new-feature) (notable-change)
- esphome: WPA2 Enterprise Attempt 2 :esphomepr:`1158` (new-feature)
- esphome: New script modes POC :esphomepr:`1168` (breaking-change) (new-feature)
New Integrations
----------------
- esphome: implemented ruuvi_ble and ruuvitag with RAWv1 and RAWv2 protocol :esphomepr:`810` by :ghuser:`Alex9779` (new-integration)
- esphome: http_request component :esphomepr:`719` by :ghuser:`Anonym-tsk` (new-integration)
- esphome: Add support for Sensirion SPS30 Particulate Matter sensors :esphomepr:`891` by :ghuser:`valordk` (new-integration)
- esphome: Add TM1561 support :esphomepr:`893` by :ghuser:`freekode` (new-integration)
- esphome: Add slow_pwm output component :esphomepr:`894` by :ghuser:`nickw444` (new-integration)
- esphome: Add RFBridge component :esphomepr:`896` by :ghuser:`jesserockz` (new-integration)
- esphome: Climate Mitsubishi :esphomepr:`725` by :ghuser:`glmnet` (new-integration)
- esphome: PID Climate :esphomepr:`885` (new-integration)
- esphome: Display tm1637 :esphomepr:`946` by :ghuser:`glmnet` (new-integration)
- esphome: Daikin climate ir component :esphomepr:`964` by :ghuser:`hectorgimenez` (new-integration)
- esphome: Add TMP117 component :esphomepr:`992` by :ghuser:`Azimath` (new-integration)
- esphome: Support for AHT10 temperature and humidity sensor :esphomepr:`949` by :ghuser:`gmasse` (new-integration)
- esphome: Add HM3301 laser dust detection sensor :esphomepr:`963` by :ghuser:`freekode` (new-integration)
- esphome: Add AC Dimmer support :esphomepr:`880` (new-feature) (new-integration)
- esphome: feat: Add support for MCP23016 IO Expander :esphomepr:`1012` by :ghuser:`reidprojects` (new-integration)
- esphome: Climate whirlpool :esphomepr:`1029` by :ghuser:`glmnet` (new-integration)
- esphome: Add support for ESP32 DAC :esphomepr:`1071` by :ghuser:`napieraj` (new-integration)
- esphome: Adding support for MAX31856 Thermocouple Temperature Sensor (feature #700) :esphomepr:`1039` by :ghuser:`declanshanaghy` (new-integration)
- esphome: Add support for additional Xiaomi BLE sensors :esphomepr:`1027` by :ghuser:`ahpohl` (new-integration) (notable-change)
- esphome: Add E1.31 support :esphomepr:`950` by :ghuser:`ayufan` (new-integration)
- esphome: Add `adalight` light effect :esphomepr:`956` by :ghuser:`ayufan` (new-integration)
- esphome: Add WLED support :esphomepr:`1092` by :ghuser:`ayufan` (new-integration)
- esphome: Add LG Climate IR :esphomepr:`1097` by :ghuser:`square99` (new-integration)
- esphome: add support for SN74HC595 shift register :esphomepr:`1083` by :ghuser:`phjr` (new-integration)
- esphome: Thermostat component :esphomepr:`1105` by :ghuser:`kbx81` (new-integration)
- esphome: Add SSD1351 OLED display support :esphomepr:`1100` by :ghuser:`kbx81` (new-integration)
- esphome: Add support for Tuya Switches :esphomepr:`1074` by :ghuser:`jesserockz` (new-integration)
- esphome: Add support for Tuya Climate devices :esphomepr:`1076` by :ghuser:`jesserockz` (new-integration)
- esphome: Add support for Tuya Sensors :esphomepr:`1088` by :ghuser:`jesserockz` (new-integration)
- esphome: Add support for Tuya Binary Sensors :esphomepr:`1089` by :ghuser:`jesserockz` (new-integration)
- esphome: Add support for Toshiba heat pumps :esphomepr:`1121` by :ghuser:`JoppyFurr` (new-integration)
- esphome: Add exposure notifications :esphomepr:`1135` (new-integration)
- esphome: rtttl player :esphomepr:`1171` by :ghuser:`glmnet` (new-integration)
Breaking Changes
----------------
- esphome: Drop Python 2 Support :esphomepr:`793` (breaking-change)
- esphome: Fix SGP30 incorrect baseline reading/writing :esphomepr:`936` by :ghuser:`panuruj` (breaking-change)
- esphome: fix servo bug restoring state and starting servo detached :esphomepr:`1008` by :ghuser:`glmnet` (breaking-change)
- esphome: fix shunt voltage / current / power reading in INA3221 :esphomepr:`1101` by :ghuser:`Vxider` (breaking-change)
- esphome: Fix: Component script not stopped in certain situations :esphomepr:`1004` by :ghuser:`balrog-kun` (breaking-change)
- esphome: New script modes POC :esphomepr:`1168` (breaking-change) (new-feature)
Notable Changes
---------------
- esphome: Dashboard Updates :esphomepr:`1025` by :ghuser:`jonathanadams` (new-feature) (notable-change)
- esphome: Uart improvments :esphomepr:`1024` by :ghuser:`0hax` (notable-change)
- esphome: Add support for additional Xiaomi BLE sensors :esphomepr:`1027` by :ghuser:`ahpohl` (new-integration) (notable-change)
- esphome: Packages feature :esphomepr:`1052` by :ghuser:`corvis` (new-feature) (notable-change)
All changes
-----------
- esphome: Add lint check for integer constants :esphomepr:`775`
- esphome: Wizard board name fixes :esphomepr:`787` by :ghuser:`scop`
- esphome: Logger on_message trigger :esphomepr:`729` by :ghuser:`Anonym-tsk`
- docs: Logger on_message trigger :docspr:`374` by :ghuser:`Anonym-tsk`
- docs: Add Fujitsu General Climate component docs :docspr:`307` by :ghuser:`31337Ghost`
- docs: fix logger.rst ref link :docspr:`379` by :ghuser:`glmnet`
- esphome: Added more power data to the atm90e32 component :esphomepr:`799` by :ghuser:`CircuitSetup`
- docs: added reactive power, power factor, chip temp... :docspr:`380` by :ghuser:`CircuitSetup`
- esphome: service uuid based ble tracking :esphomepr:`800` by :ghuser:`Lumpusz`
- docs: Ble rssi svc :docspr:`377` by :ghuser:`Lumpusz`
- docs: Typo fix pzemac :docspr:`388` by :ghuser:`Anonym-tsk`
- docs: Typo fix pzemdc :docspr:`389` by :ghuser:`Anonym-tsk`
- docs: Document UART stop_bits :docspr:`396`
- docs: Document missing servo restore option :docspr:`398`
- esphome: Fix stack trace decode for latest platformio :esphomepr:`830`
- esphome: Add MAX31865 sensor support, fix MAX31855 sensor :esphomepr:`832` by :ghuser:`DAVe3283`
- docs: Add MAX31865, update MAX31855 :docspr:`399` by :ghuser:`DAVe3283`
- esphome: Add support for INA226 Current/Power Monitor :esphomepr:`801` by :ghuser:`sergio303`
- docs: Add INA226 current/power monitor :docspr:`403` by :ghuser:`sergio303`
- esphome: implemented ruuvi_ble and ruuvitag with RAWv1 and RAWv2 protocol :esphomepr:`810` by :ghuser:`Alex9779` (new-integration)
- docs: added docs for ruuvitag :docspr:`383` by :ghuser:`Alex9779`
- esphome: http_request component :esphomepr:`719` by :ghuser:`Anonym-tsk` (new-integration)
- docs: http_request component :docspr:`392` by :ghuser:`Anonym-tsk`
- esphome: fix esphome better error out :esphomepr:`843` by :ghuser:`glmnet`
- esphome: Add climate dry fan :esphomepr:`845` by :ghuser:`glmnet`
- esphome: Decode DHT11 decimal part :esphomepr:`861` by :ghuser:`airy10`
- docs: add climate core docs fan, swing :docspr:`415` by :ghuser:`glmnet`
- esphome: fix chip_temperature for atm90e32 component :esphomepr:`865` by :ghuser:`CircuitSetup`
- esphome: add position action and lambda - tested :esphomepr:`877` by :ghuser:`KristopherMackowiak`
- esphome: added idle action for climate :esphomepr:`859` by :ghuser:`danielkucera`
- esphome: Fix MAX31865 edge case. :esphomepr:`882` by :ghuser:`DAVe3283`
- docs: Added Documentation for QMC5883L + HMC5883L Doc improvements :docspr:`301` by :ghuser:`timpur`
- esphome: Add QMC5883L Sensor + Improvements to HMC5883L :esphomepr:`671` by :ghuser:`timpur`
- esphome: Add B/W support for Waveshare 2.90in (B) screen :esphomepr:`889` by :ghuser:`akomelj`
- docs: Add B/W support for Waveshare 2.90in (B) screen :docspr:`426` by :ghuser:`akomelj`
- esphome: Add support for Sensirion SPS30 Particulate Matter sensors :esphomepr:`891` by :ghuser:`valordk` (new-integration)
- docs: Add documentation for Sensirion SPS30 Particulate Matter sensors :docspr:`424` by :ghuser:`valordk`
- docs: Add TM1651 docs :docspr:`429` by :ghuser:`freekode`
- esphome: Add TM1561 support :esphomepr:`893` by :ghuser:`freekode` (new-integration)
- esphome: Add magic value REPLACEME :esphomepr:`881`
- esphome: Pulse counter validate not both disabled :esphomepr:`902`
- esphome: Optimize application loop speed :esphomepr:`860`
- esphome: Better/stricter pin validation :esphomepr:`903`
- esphome: Disable default wait_time for rc_switch :esphomepr:`900`
- esphome: Update python dependencies :esphomepr:`906`
- esphome: Handle yaml merge keys correcly. :esphomepr:`888` by :ghuser:`edge90`
- esphome: Allow loading esphome version from a fork :esphomepr:`907` by :ghuser:`jesserockz`
- esphome: Clean up YAML Mapping construction :esphomepr:`910`
- docs: Add doc for slow_pwm output component :docspr:`427` by :ghuser:`nickw444`
- esphome: Add slow_pwm output component :esphomepr:`894` by :ghuser:`nickw444` (new-integration)
- esphome: ESP32 GPIOs 33 to 38 can be used for deep sleep wakeup :esphomepr:`911` by :ghuser:`adamgreg`
- esphome: Drop Python 2 Support :esphomepr:`793` (breaking-change)
- esphome: Add RFBridge component :esphomepr:`896` by :ghuser:`jesserockz` (new-integration)
- docs: Add docs for RF Bridge :docspr:`433` by :ghuser:`jesserockz`
- esphome: ct_clamp: Check sample() return value is not NaN :esphomepr:`921` by :ghuser:`balrog-kun`
- docs: merge all ir climates in a single doc :docspr:`385` by :ghuser:`glmnet`
- esphome: Climate Mitsubishi :esphomepr:`725` by :ghuser:`glmnet` (new-integration)
- esphome: fix: only decode when not str already :esphomepr:`923` by :ghuser:`wilmardo`
- esphome: fix climate-ir bad merge :esphomepr:`935` by :ghuser:`glmnet`
- esphome: http_request: fix memory allocation :esphomepr:`916` by :ghuser:`Anonym-tsk`
- esphome: http_request: version validation fix :esphomepr:`917` by :ghuser:`Anonym-tsk`
- esphome: PID Climate :esphomepr:`885` (new-integration)
- docs: not a display component :docspr:`462` by :ghuser:`glmnet`
- esphome: Fix for wizard via dashboard not decoding strings :esphomepr:`941` by :ghuser:`timsavage`
- esphome: Adding the espressif 2.6.3 :esphomepr:`944` by :ghuser:`Valcob`
- esphome: extract and use current version of python 3 :esphomepr:`938` by :ghuser:`gitolicious`
- esphome: Inverted output in neopixelbus :esphomepr:`895` by :ghuser:`voibit`
- docs: Added support for inverted output in neopixelbus :docspr:`441` by :ghuser:`voibit`
- esphome: Added degree symbol for MAX7219 7-segment display. :esphomepr:`764` by :ghuser:`cyberplant`
- esphome: Fix dump/tx of 64 bit codes :esphomepr:`940` by :ghuser:`andrasbiro`
- esphome: Update hdc1080.cpp :esphomepr:`887` by :ghuser:`dmkif`
- esphome: add tcl112 support for dry, fan and swing :esphomepr:`939` by :ghuser:`glmnet`
- esphome: Fix SGP30 incorrect baseline reading/writing :esphomepr:`936` by :ghuser:`panuruj` (breaking-change)
- docs: Update SGP30 for the correct eCO2 and TVOC baseline :docspr:`458` by :ghuser:`panuruj`
- docs: change docs to suggest logger config :docspr:`378` by :ghuser:`glmnet`
- esphome: Add register_*_effect to allow registering custom effects :esphomepr:`947` by :ghuser:`ayufan`
- esphome: Bugfix/normalize core comparisons (and Python 3 update fixes) :esphomepr:`952` by :ghuser:`timsavage`
- esphome: Add transmit pioneer :esphomepr:`922` by :ghuser:`kbx81`
- docs: Add transmit pioneer :docspr:`446` by :ghuser:`kbx81`
- docs: add tm1637 docs :docspr:`467` by :ghuser:`glmnet`
- esphome: Display tm1637 :esphomepr:`946` by :ghuser:`glmnet` (new-integration)
- esphome: Support a further variant of Xiaomi CGG1 :esphomepr:`930` by :ghuser:`mario-tux`
- docs: Add Daikin IR Climate documentation :docspr:`476` by :ghuser:`hectorgimenez`
- esphome: Daikin climate ir component :esphomepr:`964` by :ghuser:`hectorgimenez` (new-integration)
- esphome: fix tm1637 missing __init__.py :esphomepr:`975` by :ghuser:`glmnet`
- esphome: sim800l: Add support of roaming-registered SIM cards :esphomepr:`977` by :ghuser:`andriej`
- esphome: BME280: fix typos, use forced mode constant :esphomepr:`974` by :ghuser:`GMTA`
- esphome: MQTT climate features :esphomepr:`913` by :ghuser:`puuu`
- esphome: Revert default ESP32 upload baud rate :esphomepr:`978`
- esphome: Add TM1651 simple level, turn on, turn off actions :esphomepr:`920` by :ghuser:`freekode`
- esphome: Webserver - include css, js in index :esphomepr:`932` by :ghuser:`Elkropac`
- docs: web_server - css_include and js_include: add new options and example :docspr:`459` by :ghuser:`Elkropac`
- docs: Add new action for TM1651 :docspr:`442` by :ghuser:`freekode`
- docs: Added equal symbol for MAX7219 7-segment display :docspr:`503` by :ghuser:`egeltje`
- esphome: Added equal symbol for MAX7219 7-segment display :esphomepr:`986` by :ghuser:`egeltje`
- esphome: Output from platformio idedata command does not need to be decoded :esphomepr:`953` by :ghuser:`brandond`
- esphome: Allow custom lights to be addressable :esphomepr:`954` by :ghuser:`brandond`
- esphome: Fix esphome/issues#947 - RGBW(W) white brightness :esphomepr:`925` by :ghuser:`pauln`
- esphome: Add support for TTGO epaper boards with B73 revision :esphomepr:`928` by :ghuser:`thomasklingbeil`
- esphome: Fix OTA updates getting killed by task_wdt :esphomepr:`959` by :ghuser:`Skaronator`
- esphome: Bugfix/1077 decode called on str fetching platformio stacktrace :esphomepr:`991` by :ghuser:`timsavage`
- esphome: Add support for Tuya ceiling fan controllers :esphomepr:`989` by :ghuser:`buxtronix`
- esphome: Fixed iBeacon struct and major and minor parsing :esphomepr:`987` by :ghuser:`sekkr1`
- esphome: http_request http fix :esphomepr:`980` by :ghuser:`Anonym-tsk`
- esphome: Rgbww color fix :esphomepr:`967` by :ghuser:`quinnhosler`
- esphome: add time cover assumed_state option :esphomepr:`979` by :ghuser:`glmnet`
- esphome: Add on_rc_switch trigger :esphomepr:`983` by :ghuser:`escoand`
- esphome: SCD30 fixes and improvements :esphomepr:`962` by :ghuser:`Sizurka`
- docs: cover time based add assumed state option :docspr:`490` by :ghuser:`glmnet`
- esphome: pzemac total energy support :esphomepr:`933` by :ghuser:`yekm`
- docs: docs for Tuya fan, update tuya light :docspr:`502` by :ghuser:`buxtronix`
- docs: Next :docspr:`491` by :ghuser:`CircuitSetup`
- docs: add energy support to pzemac :docspr:`478` by :ghuser:`yekm`
- docs: Added examples for uart text sensor :docspr:`468` by :ghuser:`tomludd`
- docs: Add docs for TMP117 sensor :docspr:`505` by :ghuser:`Azimath`
- esphome: Add TMP117 component :esphomepr:`992` by :ghuser:`Azimath` (new-integration)
- esphome: Unittests for esphome python code :esphomepr:`931` by :ghuser:`timsavage`
- esphome: Corrections to default register values of ATM90E32 component :esphomepr:`982` by :ghuser:`CircuitSetup`
- esphome: Support for AHT10 temperature and humidity sensor :esphomepr:`949` by :ghuser:`gmasse` (new-integration)
- docs: Add documentation for AHT10 sensor :docspr:`466` by :ghuser:`gmasse`
- esphome: Retry connecting if the connection is not valid :esphomepr:`994` by :ghuser:`abmantis`
- esphome: Support for pcd8544 (nokia 5110 and 3310) screen :esphomepr:`973` by :ghuser:`pax0r`
- esphome: fix servo bug restoring state and starting servo detached :esphomepr:`1008` by :ghuser:`glmnet` (breaking-change)
- docs: Documentation for PCD8544 :docspr:`485` by :ghuser:`pax0r`
- esphome: VSCode devcontainer support :esphomepr:`914` by :ghuser:`Anonym-tsk`
- esphome: removes comments from lambda :esphomepr:`998` by :ghuser:`glmnet`
- esphome: Add HM3301 laser dust detection sensor :esphomepr:`963` by :ghuser:`freekode` (new-integration)
- docs: Add docs HM3301 :docspr:`529` by :ghuser:`freekode`
- esphome: Constant brightness :esphomepr:`1007` by :ghuser:`kroimon`
- docs: Add webserver-v1.js click handlers for Cover buttons :docspr:`521` by :ghuser:`balrog-kun`
- esphome: web_server: Add cover calls to REST API :esphomepr:`999` by :ghuser:`balrog-kun`
- esphome: Add AC Dimmer support :esphomepr:`880` (new-feature) (new-integration)
- docs: add ac_dimmer :docspr:`536` by :ghuser:`glmnet`
- docs: Add documentation for cwww and rgbww constant_brightness variables. (… :docspr:`540` by :ghuser:`glmnet`
- esphome: feat: Add support for MCP23016 IO Expander :esphomepr:`1012` by :ghuser:`reidprojects` (new-integration)
- docs: feat: Added documentation to support for MCP23016 :docspr:`537` by :ghuser:`reidprojects`
- docs: Kristopher mackowiak next :docspr:`544` by :ghuser:`glmnet`
- docs: fix copy paste void :docspr:`545` by :ghuser:`glmnet`
- esphome: Daikin climate receiver support :esphomepr:`1001` by :ghuser:`puuu`
- docs: ir_climate: describe daikin receive support :docspr:`522` by :ghuser:`puuu`
- esphome: Tests for CPP Code generation and some Python3 improvements :esphomepr:`961` by :ghuser:`timsavage`
- esphome: Climate whirlpool :esphomepr:`1029` by :ghuser:`glmnet` (new-integration)
- docs: add whirlpool climate :docspr:`552` by :ghuser:`glmnet`
- docs: add mac address info :docspr:`554` by :ghuser:`glmnet`
- esphome: add mac address to wifi info :esphomepr:`1030` by :ghuser:`glmnet`
- esphome: SHTC3: Wake up the sensor during setup :esphomepr:`993` by :ghuser:`Sizurka`
- esphome: Change buffer sending process for waveshare_epaper (2.70in) :esphomepr:`1031` by :ghuser:`ukewea`
- docs: add light on off triggers docs :docspr:`559` by :ghuser:`glmnet`
- esphome: add lights on off triggers :esphomepr:`1037` by :ghuser:`glmnet` (new-feature)
- docs: Bluetooth advertising automation :docspr:`512` by :ghuser:`puuu`
- esphome: Bluetooth advertising automation :esphomepr:`995` by :ghuser:`puuu`
- esphome: Fix missing yield in ESP32 UART timeout code causing watchdog resets when blocking for serial data. :esphomepr:`1016` by :ghuser:`fake-name`
- docs: Make initial run variable available to addressable_lambda :docspr:`558` by :ghuser:`Skaronator`
- esphome: Make initial run variable available to addressable_lambda :esphomepr:`1035` by :ghuser:`Skaronator`
- esphome: Dashboard Updates :esphomepr:`1025` by :ghuser:`jonathanadams` (new-feature) (notable-change)
- docs: remote_receiver: describe memory_block configuration :docspr:`523` by :ghuser:`puuu`
- esphome: esp32 remote: make RMT memory blocks configureable :esphomepr:`1002` by :ghuser:`puuu`
- esphome: test disable no delay :esphomepr:`1026` by :ghuser:`glmnet`
- esphome: http_request ESP32 insecure requests fix :esphomepr:`1041` by :ghuser:`Anonym-tsk`
- esphome: Update FastLED Library 3.3.3 :esphomepr:`1020` by :ghuser:`teamsuperpanda`
- docs: Max7219 intensity change update :docspr:`546` by :ghuser:`buxtronix`
- esphome: Some max7219 updates. :esphomepr:`1021` by :ghuser:`buxtronix`
- docs: 5.83in Waveshare add :docspr:`572` by :ghuser:`sredfern`
- esphome: Extending Support to 5.83in Waveshare eink B/W displays :esphomepr:`1009` by :ghuser:`sredfern`
- esphome: Allow tm1637 to use pins from IO expanders :esphomepr:`1058` by :ghuser:`jesserockz`
- esphome: Fix fan oscillation trait not being used :esphomepr:`1048` by :ghuser:`blejdfist`
- esphome: Update tm1637.cpp :esphomepr:`1044` by :ghuser:`nepozs`
- esphome: dht: Fix sensor reading from DHT22 :esphomepr:`926` by :ghuser:`robinsmidsrod`
- docs: dht: Add DHT22_TYPE2 model :docspr:`563` by :ghuser:`robinsmidsrod`
- esphome: Add lambda to devcontainer config :esphomepr:`1059` by :ghuser:`jesserockz`
- docs: Ble scanner doc :docspr:`611` by :ghuser:`TheKuko`
- esphome: Ble scanner :esphomepr:`976` by :ghuser:`TheKuko` (new-feature)
- docs: Update arduino framework versions :docspr:`575` by :ghuser:`Skaronator`
- docs: Fix pcf8574 mode :docspr:`616` by :ghuser:`glmnet`
- docs: Dallas autosetup :docspr:`551` by :ghuser:`krahabb`
- esphome: Expose mac address via discovery (mDNS) :esphomepr:`1038` by :ghuser:`ctalkington`
- docs: ESP32 DAC output documentation :docspr:`617` by :ghuser:`napieraj`
- esphome: Add support for ESP32 DAC :esphomepr:`1071` by :ghuser:`napieraj` (new-integration)
- esphome: Uart improvments :esphomepr:`1024` by :ghuser:`0hax` (notable-change)
- docs: Uart improvments :docspr:`571` by :ghuser:`0hax`
- esphome: Adding support for MAX31856 Thermocouple Temperature Sensor (feature #700) :esphomepr:`1039` by :ghuser:`declanshanaghy` (new-integration)
- esphome: Add support for additional Xiaomi BLE sensors :esphomepr:`1027` by :ghuser:`ahpohl` (new-integration) (notable-change)
- docs: Add support for additional Xiaomi BLE sensors :docspr:`576` by :ghuser:`ahpohl`
- esphome: Explicitly set language to English :esphomepr:`1073` by :ghuser:`gitolicious`
- docs: Added TTGO-Camera Plus PIN configuration :docspr:`510` by :ghuser:`rudgr`
- esphome: Added support for ssd1327 :esphomepr:`985` by :ghuser:`igg`
- docs: added energy in pzem004 documentation :docspr:`547` by :ghuser:`adriancuzman`
- esphome: added energy reading for pzem004 :esphomepr:`1022` by :ghuser:`adriancuzman`
- esphome: BH1750 Measurement time :esphomepr:`997` by :ghuser:`rradar`
- docs: BH1750 Measurement time doc updates :docspr:`515` by :ghuser:`rradar`
- esphome: Sort keys in dicts in output yaml for 'config' command :esphomepr:`1049` by :ghuser:`ivan4th`
- esphome: Extend uart: with rx_buffer_size: :esphomepr:`1006` by :ghuser:`ayufan`
- docs: Document `uart.rx_buffer_size` :docspr:`528` by :ghuser:`ayufan`
- esphome: Add Prometheus /metrics-Endpoint :esphomepr:`1032` by :ghuser:`margau` (new-feature)
- docs: Add Prometheus-Documentation :docspr:`556` by :ghuser:`margau`
- esphome: Turn off PN532 RF field when not expecting a tag :esphomepr:`1046` by :ghuser:`apeeters`
- docs: Docs for CS Optional :docspr:`644` by :ghuser:`igg`
- esphome: making SPI CS optional :esphomepr:`988` by :ghuser:`igg`
- esphome: AQI calculator for HM3301 :esphomepr:`1011` by :ghuser:`freekode`
- docs: AQI calculator for HM3301 :docspr:`535` by :ghuser:`freekode`
- esphome: Fix gamma_correct when using constant_brightness option :esphomepr:`1043` by :ghuser:`Skaronator`
- esphome: Add E1.31 support :esphomepr:`950` by :ghuser:`ayufan` (new-integration)
- esphome: Add `adalight` light effect :esphomepr:`956` by :ghuser:`ayufan` (new-integration)
- docs: Add documentation about E1.31, Adalight and WLED :docspr:`646` by :ghuser:`ayufan`
- esphome: Add WLED support :esphomepr:`1092` by :ghuser:`ayufan` (new-integration)
- docs: PID Climate Controller :docspr:`432`
- docs: Added Etekcity Voltson cookbook :docspr:`628` by :ghuser:`gitolicious`
- esphome: Update docker base image :esphomepr:`1093` by :ghuser:`Skaronator`
- esphome: SenseAir: flush input buffer on read error :esphomepr:`1017` by :ghuser:`ferbar`
- docs: Add documentation for fan direction :docspr:`580` by :ghuser:`blejdfist`
- esphome: Add support for controlling fan direction :esphomepr:`1051` by :ghuser:`blejdfist`
- esphome: Add API component to logging error message :esphomepr:`1062` by :ghuser:`JeffResc`
- docs: Added MCP3008 :docspr:`591` by :ghuser:`SenexCrenshaw`
- esphome: Add MCP3008 I/O Expander :esphomepr:`1057` by :ghuser:`SenexCrenshaw`
- esphome: ADE7953: Fix dereferencing of a null pointer :esphomepr:`1086` by :ghuser:`rnauber`
- esphome: sgp30 baseline write bug fix (#1157) :esphomepr:`1078` by :ghuser:`korellas`
- esphome: fix for ESP32 'Association Leave' :esphomepr:`1081` by :ghuser:`MasterTim17`
- esphome: Climate bang bang enhancements :esphomepr:`1061` by :ghuser:`kbx81`
- docs: Climate bang bang enhancements :docspr:`595` by :ghuser:`kbx81`
- esphome: Fix decode and encode for RC5-protocol :esphomepr:`1047` by :ghuser:`LukasK13`
- esphome: Add esp8266 huzzah gpio pins :esphomepr:`1096` by :ghuser:`halkeye`
- esphome: fix percentage handling :esphomepr:`1094` by :ghuser:`ssieb`
- docs: Add support for command-line-substitutions :docspr:`538` by :ghuser:`AlexMekkering`
- esphome: Add support for command-line substitutions :esphomepr:`1014` by :ghuser:`AlexMekkering` (new-feature)
- esphome: Add LG Climate IR :esphomepr:`1097` by :ghuser:`square99` (new-integration)
- docs: Add LG Climate IR :docspr:`655` by :ghuser:`square99`
- esphome: ESP32: Conditionally log on services to avoid OOM crashes :esphomepr:`1098` by :ghuser:`buxtronix`
- esphome: Release BT controller unused memory in the right place :esphomepr:`1095` by :ghuser:`buxtronix`
- docs: add documentation for component sn74hc595 :docspr:`637` by :ghuser:`phjr`
- esphome: add support for SN74HC595 shift register :esphomepr:`1083` by :ghuser:`phjr` (new-integration)
- esphome: Max7219 in Dot Matrix configuration :esphomepr:`1053` by :ghuser:`rspaargaren`
- docs: Max7219 new documentation :docspr:`585` by :ghuser:`rspaargaren`
- esphome: Add support for ST7789V display module (as on TTGO T-Display) :esphomepr:`1050` by :ghuser:`kbx81`
- docs: Add documentation for ST7789V display module (as on TTGO T-Display) :docspr:`594` by :ghuser:`kbx81`
- esphome: Vl53 long range :esphomepr:`1055` by :ghuser:`rspaargaren`
- docs: Update vl53l0x.rst :docspr:`592` by :ghuser:`rspaargaren`
- esphome: fix shunt voltage / current / power reading in INA3221 :esphomepr:`1101` by :ghuser:`Vxider` (breaking-change)
- esphome: Fix current / power reading in INA219 :esphomepr:`1103` by :ghuser:`Vxider`
- esphome: Fix: Component script not stopped in certain situations :esphomepr:`1004` by :ghuser:`balrog-kun` (breaking-change)
- docs: add script.stop breaking change :docspr:`659` by :ghuser:`glmnet`
- esphome: Fixes esphome/issues#1192 - Save on upload bug :esphomepr:`1107` by :ghuser:`jonathanadams`
- esphome: Revert "Climate bang bang enhancements" :esphomepr:`1106` by :ghuser:`glmnet`
- esphome: Use default average mode in INA3221 :esphomepr:`1102` by :ghuser:`Vxider`
- esphome: Thermostat component :esphomepr:`1105` by :ghuser:`kbx81` (new-integration)
- docs: Added thermostat component doc :docspr:`665` by :ghuser:`kbx81`
- esphome: unpin mbedtls version :esphomepr:`1114` by :ghuser:`glmnet`
- esphome: Fix ethernet logging too many warn messages :esphomepr:`1112` by :ghuser:`glmnet`
- esphome: add click dependency :esphomepr:`1111` by :ghuser:`glmnet`
- docs: Add documentation for climate.pid.reset_integral_term action :docspr:`660` by :ghuser:`carlos-sarmiento`
- esphome: Add Integral Reset Action to PIDClimate :esphomepr:`1104` by :ghuser:`carlos-sarmiento`
- docs: color interlock :docspr:`653` by :ghuser:`peq123`
- esphome: RGBWW - added channel interlock for RGB vs white :esphomepr:`1042` by :ghuser:`peq123`
- docs: Add documentation for new WPA2-EAP authentication. :docspr:`633` by :ghuser:`tomtom5152`
- docs: SSD1325 documentation update for grayscale support :docspr:`596` by :ghuser:`kbx81`
- esphome: SSD1325 grayscale support :esphomepr:`1064` by :ghuser:`kbx81`
- docs: Cleaned up ESP32 DAC docs :docspr:`618` by :ghuser:`napieraj`
- docs: Added SSD1351 doc :docspr:`663` by :ghuser:`kbx81`
- esphome: Add SSD1351 OLED display support :esphomepr:`1100` by :ghuser:`kbx81` (new-integration)
- esphome: Add cryptography requirement to the setup.py file :esphomepr:`1116` by :ghuser:`jesserockz`
- docs: Support ssd1327 docs :docspr:`664` by :ghuser:`igg`
- esphome: Revert "Add ESP32 support for WPA2-EAP Enterprise WiFi authentication" :esphomepr:`1117` by :ghuser:`glmnet`
- esphome: Revert "Add cryptography requirement to the setup.py file" :esphomepr:`1118` by :ghuser:`glmnet`
- esphome: Install updated git version in lint image :esphomepr:`1122` by :ghuser:`jesserockz`
- docs: documentation for version sensor hide timestamp option :docspr:`640` by :ghuser:`Wauter`
- esphome: fixes script wait not waiting :esphomepr:`1123` by :ghuser:`glmnet`
- docs: Split the Tuya component documentation :docspr:`631` by :ghuser:`jesserockz`
- esphome: Add support for Tuya Switches :esphomepr:`1074` by :ghuser:`jesserockz` (new-integration)
- docs: Add Tuya Switch docs :docspr:`625` by :ghuser:`jesserockz`
- esphome: fix script.wait action :esphomepr:`1120` by :ghuser:`ssieb`
- esphome: Add support for Tuya Climate devices :esphomepr:`1076` by :ghuser:`jesserockz` (new-integration)
- docs: Add Tuya Climate docs :docspr:`632` by :ghuser:`jesserockz`
- esphome: Add support for Tuya Sensors :esphomepr:`1088` by :ghuser:`jesserockz` (new-integration)
- docs: Add Tuya Sensor docs :docspr:`661` by :ghuser:`jesserockz`
- docs: Add Tuya Binary Sensor docs :docspr:`662` by :ghuser:`jesserockz`
- esphome: Add support for Tuya Binary Sensors :esphomepr:`1089` by :ghuser:`jesserockz` (new-integration)
- esphome: feature request 398 add 'hide timestamp' option for version text sensor :esphomepr:`1085` by :ghuser:`Wauter`
- esphome: Add 7.5inch v2 waveshare :esphomepr:`1077` by :ghuser:`PaulAntonDeen`
- docs: Added new version of 7.5inch waveshare epaper :docspr:`675` by :ghuser:`PaulAntonDeen`
- esphome: Move CI/CD to GitHub Actions :esphomepr:`1125` by :ghuser:`jesserockz`
- esphome: Add PR labels based on files changed :esphomepr:`1127` by :ghuser:`jesserockz`
- esphome: Brightness support for Nextion display :esphomepr:`1109` by :ghuser:`Vxider`
- docs: Brightness support for Nextion display :docspr:`668` by :ghuser:`Vxider`
- esphome: Revert "Add PR labels based on files changed" :esphomepr:`1128` by :ghuser:`jesserockz`
- docs: Add Toshiba climate :docspr:`681` by :ghuser:`JoppyFurr`
- esphome: Add support for Toshiba heat pumps :esphomepr:`1121` by :ghuser:`JoppyFurr` (new-integration)
- esphome: Packages feature :esphomepr:`1052` by :ghuser:`corvis` (new-feature) (notable-change)
- docs: Added documentation for packages feature :docspr:`582` by :ghuser:`corvis`
- esphome: Allow updating pid control params :esphomepr:`1115` by :ghuser:`carlos-sarmiento`
- esphome: Github actions repo :esphomepr:`1130` by :ghuser:`jesserockz`
- esphome: Feature/fix unit tests :esphomepr:`1129` by :ghuser:`pkuehne`
- esphome: GH Actions Update :esphomepr:`1134`
- esphome: Bug/fix internal flag in binary sensor :esphomepr:`1136` by :ghuser:`pkuehne`
- esphome: Use inclusive terminology :esphomepr:`1137`
- esphome: Add exposure notifications :esphomepr:`1135` (new-integration)
- esphome: Fix adding another mbedtls :esphomepr:`1131`
- esphome: Tuya Sensor remove commented out code (style guide) :esphomepr:`1132`
- docs: Add exposure notifications docs :docspr:`683`
- docs: Improve RGBW(W) docs :docspr:`682`
- esphome: add mqtt speed topics for fan :esphomepr:`1140` by :ghuser:`ssieb`
- esphome: Bump pytest from 5.4.1 to 5.4.3 :esphomepr:`1144` by :ghuser:`dependabot[bot]`
- esphome: Bump hypothesis from 5.10.4 to 5.19.3 :esphomepr:`1146` by :ghuser:`dependabot[bot]`
- esphome: Bump protobuf from 3.11.3 to 3.12.2 :esphomepr:`1147` by :ghuser:`dependabot[bot]`
- esphome: Bump ifaddr from 0.1.6 to 0.1.7 :esphomepr:`1148` by :ghuser:`dependabot[bot]`
- esphome: Bump pytest-cov from 2.8.1 to 2.10.0 :esphomepr:`1145` by :ghuser:`dependabot[bot]`
- esphome: Fix Waveshare 7.50inV2 :esphomepr:`1143`
- esphome: Load setup.py requirements from requirements.txt :esphomepr:`1149`
- esphome: Add pytest to CI :esphomepr:`1138`
- esphome: Feature/component test fixture :esphomepr:`1142` by :ghuser:`pkuehne`
- esphome: Use more layer caching for esphome/esphome Dockerfile :esphomepr:`1150`
- esphome: Don't remove location information for packages :esphomepr:`1133`
- esphome: Add tasmota magic bits to short circuit compat check :esphomepr:`1152`
- esphome: Fix executable bits on some hassio files :esphomepr:`1151`
- esphome: Don't run deploy job when repository is not esphome/esphome :esphomepr:`1157` by :ghuser:`jesserockz`
- docs: Docs for Setting control parameters on PID :docspr:`674` by :ghuser:`carlos-sarmiento`
- esphome: Bump pytest-mock from 1.13.0 to 3.2.0 :esphomepr:`1159` by :ghuser:`dependabot[bot]`
- esphome: Bump pylint from 2.5.0 to 2.5.3 :esphomepr:`1160` by :ghuser:`dependabot[bot]`
- esphome: Bump tzlocal from 2.0.0 to 2.1 :esphomepr:`1162` by :ghuser:`dependabot[bot]`
- esphome: Fix unit test warning for hypothesis deprecation :esphomepr:`1163` by :ghuser:`pkuehne`
- esphome: Bump flake8 from 3.7.9 to 3.8.3 :esphomepr:`1161` by :ghuser:`dependabot[bot]`
- esphome: Bump FastLED from 3.2.9 to 3.3.3 :esphomepr:`1164`
- esphome: Arduino dev branch changed :esphomepr:`1139` by :ghuser:`glmnet`
- esphome: Add bump version script :esphomepr:`1153`
- esphome: fix(cover yaml validation): adds gate to coincide with Home Assistant :esphomepr:`1175` by :ghuser:`erasmuswill`
- esphome: http_request fix urls caching :esphomepr:`1174` by :ghuser:`Anonym-tsk`
- esphome: Fix rf_bridge send and receive :esphomepr:`1180` by :ghuser:`vicfergar`
- esphome: mdi:timer icon replaced with mdi:timer-outline :esphomepr:`1181` by :ghuser:`Troon`
- esphome: Bump hypothesis from 5.19.3 to 5.20.3 :esphomepr:`1176` by :ghuser:`dependabot[bot]`
- esphome: Fix Home Assistant API disconnects when using st7789v display. :esphomepr:`1179` by :ghuser:`dr-oblivium`
- esphome: Fixed type mismatch between result field and preference of integration sensor :esphomepr:`1178` by :ghuser:`FrankBakkerNl`
- esphome: Feature/wizard tests :esphomepr:`1167` by :ghuser:`pkuehne`
- esphome: Add HassIO by-id serial port paths to serial ports listing :esphomepr:`1155`
- esphome: Bump NeoPixelBus from 2.5.2 to 2.5.7 :esphomepr:`1165`
- esphome: Bump colorlog from 4.1.0 to 4.2.1 :esphomepr:`1183` by :ghuser:`dependabot[bot]`
- esphome: Bump hypothesis from 5.20.3 to 5.21.0 :esphomepr:`1184` by :ghuser:`dependabot[bot]`
- esphome: ESP8266 Disable Pin Initialization on Boot to fix pin toggling :esphomepr:`1185`
- esphome: Fix dashboard logout button and py3.8 removed hmac.new digestmod :esphomepr:`1156`
- docs: WPA2 Enterprise Attempt 2 :docspr:`704`
- esphome: WPA2 Enterprise Attempt 2 :esphomepr:`1158` (new-feature)
- esphome: Remove symlink_ops.py :esphomepr:`1196`
- esphome: Fix senseair flush input buffer wrong log level :esphomepr:`1194`
- esphome: Fix WLED minor issues :esphomepr:`1193`
- esphome: Clean up UART Improvements code :esphomepr:`1190`
- esphome: Partially revert make SPI CS pin optional :esphomepr:`1187`
- esphome: New script modes POC :esphomepr:`1168` (breaking-change) (new-feature)
- docs: Add script modes and timers :docspr:`693` by :ghuser:`glmnet`
- esphome: Revert "Sort keys in dicts in output yaml for 'config' command (#1049)" :esphomepr:`1191`
- esphome: Fix SN74HC595 doesn't use ESPHome HAL and add lint checks for it :esphomepr:`1188`
- docs: Partially Revert make SPI CS pin optional :docspr:`706`
- esphome: Enlarge ESP32 app partitions :esphomepr:`1197`
- esphome: Add CODEOWNERS mechanism :esphomepr:`1199`
- esphome: rtttl player :esphomepr:`1171` by :ghuser:`glmnet` (new-integration)
- docs: add buzzer rtttl docs :docspr:`700` by :ghuser:`glmnet`
- esphome: Add @glmnet components :esphomepr:`1200` by :ghuser:`glmnet`
- docs: fix merge: climate devices moved to climate-ir :docspr:`710` by :ghuser:`glmnet`
- esphome: Add @jesserockz to codeowners :esphomepr:`1202` by :ghuser:`jesserockz`
- esphome: Fix set point logging issue :esphomepr:`1201` by :ghuser:`kbx81`
- docs: Revert "Dallas autosetup (#551)" :docspr:`709`
- esphome: Revert "Added auto discovery and setup to Dallas Platform (#1028)" :esphomepr:`1189`
Past Changelogs
---------------
.. toctree::
:maxdepth: 1
v1.14.0
v1.13.0
v1.12.0
v1.11.0
v1.10.0
v1.9.0
v1.8.0
v1.7.0

25
components/binary_sensor/ble_presence.rst
View File

@ -18,16 +18,31 @@ Bluetooth Low Energy device.
esp32_ble_tracker:
binary_sensor:
# Presence based on MAC address
- platform: ble_presence
mac_address: AC:37:43:77:5F:4C
name: "ESP32 BLE Tracker Google Home Mini"
# Presence based on BLE Service UUID
- platform: ble_presence
service_uuid: '11aa'
name: "ESP32 BLE Tracker Test Service 16 bit"
.. note::
Service UUID can be 16 bit long, as in the example, but it can also be 32 bit long
like ``1122aaff``, or 128 bit long like ``11223344-5566-7788-99aa-bbccddeeff00``.
Configuration variables:
------------------------
- **mac_address** (**Required**, MAC Address): The MAC address to track for this
binary sensor.
- **name** (**Required**, string): The name of the binary sensor.
- **mac_address** (*Optional*, MAC Address): The MAC address to track for this
binary sensor. Either this or ``service_uuid`` has to be present.
- **service_uuid** (*Optional*, string) 16 bit, 32 bit, or 128 bit BLE Service UUID
which can be tracked if the device randomizes the MAC address. Either
this or ``mac_address`` has to be present.
- **id** (*Optional*, :ref:`config-id`): Manually specify
the ID used for code generation.
- All other options from :ref:`Binary Sensor <config-binary_sensor>`.
@ -54,7 +69,11 @@ address type and advertised name. If you don't see these messages, your device i
currently not supported.
Please note that devices that show a ``RANDOM`` address type in the logs cannot be used for
tracking, since their MAC-address periodically changes.
MAC address based tracking, since their MAC-address periodically changes. Instead you can create
a BLE beacon, set a unique 16 bit, 32 bit or 128 bit Service UUID and track your device based on that.
Make sure you don't pick a `GATT Service UUID <https://www.bluetooth.com/specifications/gatt/services/>`__,
otherwise generic services might give you incorrect tracking results.
See Also
--------

34
components/binary_sensor/tuya.rst Normal file
View File

@ -0,0 +1,34 @@
Tuya Binary Sensor
==================
.. seo::
:description: Instructions for setting up a Tuya device binary sensor.
The ``tuya`` binary sensor platform creates a binary sensor from a
tuya component and requires :doc:`/components/tuya` to be configured.
You can create the binary sensor as follows:
.. code-block:: yaml
# Create a binary sensor
binary_sensor:
- platform: "tuya"
name: "MyBinarySensor"
sensor_datapoint: 1
Configuration variables:
------------------------
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **name** (**Required**, string): The name of the binary sensor.
- **sensor_datapoint** (**Required**, int): The datapoint id number of the binary sensor.
- All other options from :ref:`Binary Sensor <config-binary_sensor>`.
See Also
--------
- :doc:`/components/tuya`
- :doc:`/components/binary_sensor/index`
- :apiref:`tuya/binary_sensor/tuya_binary_sensor.h`
- :ghedit:`Edit`

100
components/climate/bang_bang.rst
View File

@ -8,7 +8,14 @@ Bang Bang Climate Controller
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
.. note::
A number of people have asked about the behavior of the bang-bang controller. In version 1.15, a
:doc:`thermostat <thermostat>` component was added which behaves more like a common thermostat; it is
essentially two bang-bang controllers in one. Please see the `Bang-bang vs. Thermostat`_ section below
if you are not sure which is appropriate for your application.
The bang-bang controller's principle of operation 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.
@ -47,6 +54,7 @@ Do note that the actions are only called when the current temperature leaves the
# Example configuration entry
climate:
- platform: bang_bang
name: "Bang Bang Climate Controller"
sensor: my_temperature_sensor
default_target_temperature_low: 20 °C
default_target_temperature_high: 22 °C
@ -56,8 +64,8 @@ Do note that the actions are only called when the current temperature leaves the
idle_action:
- switch.turn_off: heater
Configuration variables:
------------------------
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
@ -89,10 +97,90 @@ Advanced options:
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.
Bang-bang vs. Thermostat
------------------------
The behavior of the bang-bang controller is a topic that has surfaced on the ESPHome Discord server
countless times -- many people have been confused by what it does. While they are similar, there are
two key differences between the bang-bang component and the :doc:`thermostat <thermostat>` component:
- When actions are triggered
- How the set points are used by the controller
Now is a good time to ensure you understand exactly how a bang-bang controller should behave; if you do not have
a clear understanding of this, be sure to check out the
`Wikipedia article <https://en.wikipedia.org/wiki/Bang%E2%80%93bang_control>`__.
The Problem with Dual-Function Systems
**************************************
If you are not attempting to operate a system that can both heat and cool, you'll likely want to skip to the next
section about user interface.
As outlined above, in general:
- As soon as the temperature goes below the *lower* target temperature, ``heat_action`` is called to activate heating.
- Heating will continue until the temperature reaches the *upper* target temperature, at which point ``idle_action`` is called to stop heating.
- As soon as the temperature goes above the *upper* target temperature, ``cool_action`` is called to activate cooling.
- Cooling will continue until the temperature reaches the *lower* target temperature, at which point ``idle_action`` is called to stop cooling.
A single bang-bang controller may work well for systems that only heat or only cool; however, it begins to break down
when applied to systems that may both heat *and* cool. This is simply because both actions are tied to both set
points -- that is, the point at which heating stops *is also the point at which cooling begins*. The reverse is also
true: the point at which cooling stops *is also the point at which heating begins*. Let's look at an example:
Consider a system that both heats and cools. The ``target_temperature_low`` set point is 20 °C while the
``target_temperature_high`` set point is 22 °C. The sensor reports that the temperature is 19.75 °C, so the controller
calls ``heat_action`` to activate heating. Heating continues until the temperature reaches ``target_temperature_high``
(22 °C in this case). Once this temperature is achieved, ``idle_action`` is called to stop heating. *However*, should
temperature drift even slightly above ``target_temperature_high``--even just a fraction of a degree for a fraction of
a second--the controller will call ``cool_action`` to begin cooling. Now, cooling will continue until
``target_temperature_low`` is reached again, but, as before, should the temperature drift even slightly below
``target_temperature_low`` for even a fraction of a second, ``heat_action`` will be invoked again, and the cycle will
repeat. It will "ping-pong" between the two set points, potentially forever. Oscillation at the "edges" of the
hysteresis window, or going past the set point in either direction, should be expected; consider, for example, a heater
that is turned off after it reaches its set point. The heating element will remain hot (potentially for quite a while),
and as such will continue to heat the air until the element fully cools down to match the ambient air/room temperature.
The :doc:`thermostat <thermostat>` component differs in that there is hysteresis around *each* set point. For example,
if the ``target_temperature_low`` set point is 20 °C, and the (default) hysteresis value of 0.5 °C is used,
``heat_action`` is called at a temperature of 19.5 °C and ``idle_action`` is called at 20.5 °C. If cooling, as defined
by ``target_temperature_high``, is set to 22 °C, ``cool_action`` would be called at 22.5 °C and ``idle_action`` called
at 21.5 °C. Again, it is essentially two bang-bang controllers in one.
Behavioral differences aside, there is another important difference between these two components: user interface.
User Interface
**************
The interaction with this component via the Home Assistant user interface is also different than what is seen on most
common residential thermostats. Generally speaking, most thermostats allow either one or two set points -- one of them
is associated with heating while the other with cooling, and this is exactly how the :doc:`thermostat <thermostat>`
component uses them. If you set the "heat" set point to 20 °C, most people assume this means the heating system will
keep the temperature as close to 20 °C as possible. The same is true for the upper set point, for cooling: if you set
a temperature of 22 °C, most people assume the cooling system will keep the temperature as close to 22 °C as possible.
The bang-bang controller does not use the set points this way. If you set the lower set point to 20 °C and set the
upper set point to 22 °C, then *the temperature will be brought as high as 22 °C but go no lower than 20 °C.*
The behavior is not difficult to understand, but, as we've learned from many discussions on the Discord server, it
departs from what most people seem to expect.
Which is Right for Me?
**********************
It comes down to two points:
- If you have a dual-function system (both heating and cooling), you'll almost certainly want to use the
:doc:`thermostat <thermostat>` component.
- If you have a single-function system *and* have a specific need or desire to manually control both the upper and
lower bounds for hysteresis, use the bang-bang controller.
In all other situations, the :doc:`thermostat <thermostat>` component is probably best.
See Also
--------
- :doc:`/components/binary_sensor/index`
- :ref:`config-pin_schema`
- :apiref:`gpio/binary_sensor/gpio_binary_sensor.h`
- :doc:`/components/climate/index`
- :apiref:`bang_bang/bang_bang_climate.h`
- :ghedit:`Edit`

80
components/climate/coolix.rst
View File

@ -1,80 +0,0 @@
Coolix IR Remote Climate
========================
.. seo::
:description: Controls a Coolix compatible Climate via IR
:image: air-conditioner.png
The ``coolix`` climate platform allows you to control a Coolix compatible AC unit by sending IR signals
as your remote unit would do.
This component requires that you have setup a :doc:`/components/remote_transmitter`.
Due to the unidirectional nature of IR remote controllers, this component cannot determine the
actual state of the device, and will assume the state of the device is the latest state requested.
Optionally you can add a :doc:`/components/remote_receiver` component so the climate state will be
tracked when it is operated with the original remote controller unit.
.. figure:: images/climate-ui.png
:align: center
:width: 60.0%
.. code-block:: yaml
# Example configuration entry
remote_transmitter:
pin: GPIO32
carrier_duty_percent: 50%
climate:
- platform: coolix
name: "Living Room AC"
Configuration variables:
------------------------
- **name** (**Required**, string): The name for the climate.
- **supports_cool** (*Optional*, boolean): Enables setting cool mode for this climate device. Defaults to ``True``.
- **supports_heat** (*Optional*, boolean): Enables setting heat mode for this climate device. Defaults to ``True``.
- **sensor** (*Optional*, :ref:`config-id`): The sensor that is used to measure the ambient
temperature. This is only for reporting the current temperature in the frontend.
- **receiver_id** (*Optional*, :ref:`config-id`): The remote_receiver id, see: :ref:`coolix-receiver_id`.
- All other options from :ref:`Climate <config-climate>`.
Advanced options:
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **transmitter_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the remote transmitter.
.. _coolix-receiver_id:
Using a receiver
----------------
When using a receiver it is recommended to put the IR receiver as close as possible to the equipment's
IR receiver.
.. code-block:: yaml
# Example configuration entry
remote_receiver:
id: rcvr
pin:
number: GPIO14
inverted: True
mode: INPUT_PULLUP
tolerance: 55 # high tolerance required for some remote control units
climate:
- platform: coolix
name: "Living Room AC"
receiver_id: rcvr
See Also
--------
- :doc:`/components/climate/index`
- :doc:`/components/remote_transmitter`
- :apiref:`coolix/coolix.h`
- :ghedit:`Edit`

9
components/climate/index.rst
View File

@ -81,6 +81,11 @@ Configuration variables:
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.
- **fan_mode** (*Optional*, boolean, :ref:`templatable <config-templatable>`): Set the fan mode
of the climate device. One of ``ON``, ``OFF``, ``AUTO``, ``LOW``, ``MEDIUM``, ``HIGH``, ``MIDDLE``,
``FOCUS``, ``DIFFUSE``.
- **swing_mode** (*Optional*, boolean, :ref:`templatable <config-templatable>`): Set the swing mode
of the climate device. One of ``OFF``, ``BOTH``, ``VERTICAL``, ``HORIZONTAL``.
.. _climate-lambda_calls:
@ -106,6 +111,10 @@ advanced stuff.
id(my_climate).target_temperature_high
// Away mode, type: bool
id(my_climate).away
// Fan mode, type: FanMode (enum)
id(my_climate).fan_mode
// Swing mode, type: SwingMode (enum)
id(my_climate).swing_mode
- ``.make_call``: Control the climate device

137
components/climate/ir_climate.rst Normal file
View File

@ -0,0 +1,137 @@
IR Remote Climate
=================
.. seo::
:description: Controls a variety of compatible Climate via IR
:image: air-conditioner-ir.png
The climate component allows you to control a variety of compatible AC units by sending IR signals
as your remote unit would do.
.. figure:: images/climate-ui.png
:align: center
:width: 60.0%
There is a growing list of compatible units. If your unit is not listed below you can fill a feature
request so it will be added (see FAQ).
+------------------------+---------------------+----------------------+------------------------------------+
| Name | Platform name | Supports receiver | |
| | | | |
+========================+=====================+======================+====================================+
| Coolix | ``coolix`` | yes | |
+------------------------+---------------------+----------------------+------------------------------------+
| Daikin | ``daikin`` | yes | |
+------------------------+---------------------+----------------------+------------------------------------+
| Fujitsu General | ``fujitsu_general`` | | |
+------------------------+---------------------+----------------------+------------------------------------+
| Mitsubishi | ``mitsubishi`` | | |
+------------------------+---------------------+----------------------+------------------------------------+
| TCL112, Fuego | ``tcl112`` | yes | |
+------------------------+---------------------+----------------------+------------------------------------+
| Toshiba | ``toshiba`` | yes | |
+------------------------+---------------------+----------------------+------------------------------------+
| Yashima | ``yashima`` | | |
+------------------------+---------------------+----------------------+------------------------------------+
| Whirlpool | ``whirlpool`` | yes | :ref:`more info<model_whirlpool>` |
+------------------------+---------------------+----------------------+------------------------------------+
| LG | ``climate_ir_lg`` | yes | |
+------------------------+---------------------+----------------------+------------------------------------+
This component requires that you have setup a :doc:`/components/remote_transmitter`.
Due to the unidirectional nature of IR remote controllers, this component cannot determine the
actual state of the device, and will assume the state of the device is the latest state requested.
However, when receiver is supported, you can optionally add a :doc:`/components/remote_receiver`
component so the climate state will be tracked when it is operated with the original remote
controller unit.
.. code-block:: yaml
# Example configuration entry
remote_transmitter:
pin: GPIO32
carrier_duty_percent: 50%
climate:
- platform: coolix # adjust to match your AC unit!
name: "Living Room AC"
Configuration variables:
------------------------
- **name** (**Required**, string): The name for the climate device.
- **sensor** (*Optional*, :ref:`config-id`): The sensor that is used to measure the ambient
temperature. This is only for reporting the current temperature in the frontend.
- **supports_cool** (*Optional*, boolean): Enables setting cooling mode for this climate device. Defaults to ``True``.
- **supports_heat** (*Optional*, boolean): Enables setting heating mode for this climate device. Defaults to ``True``.
- **receiver_id** (*Optional*, :ref:`config-id`): The id of the remote_receiver if this platform supports
receiver. see: :ref:`ir-receiver_id`.
- All other options from :ref:`Climate <config-climate>`.
Advanced options:
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **transmitter_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the remote transmitter.
.. _ir-receiver_id:
Using a Receiver
----------------
.. note::
This is only supported with select climate devices, see "Supports receiver" in the table at the top of the page.
Optionally, some platforms can listen to data the climate device sends over infrared to update their state (
for example what mode the device is in). By setting up a :doc:`remote_receiver </components/remote_receiver>`
and passing its ID to the climate platform you can enable this mode.
When using a receiver it is recommended to put the IR receiver as close as possible to the equipment's
IR receiver.
.. code-block:: yaml
# Example configuration entry
remote_receiver:
id: rcvr
pin:
number: GPIO14
inverted: True
mode: INPUT_PULLUP
# high 55% tolerance is recommended for some remote control units
tolerance: 55%
climate:
- platform: coolix
name: "Living Room AC"
receiver_id: rcvr
.. _model_whirlpool:
Whirlpool
---------
Additional configuration is available for this model
- **model** (*Optional*, string): There are two valid models
* ``MODEL_DG11J1_3A``: Temperature range is from 18 to 32 (default)
* ``MODEL_DG11J1_91``: Temperature range is from 16 to 30
See Also
--------
- :doc:`/components/climate/index`
- :doc:`/components/remote_transmitter`
- :apiref:`coolix.h <coolix/coolix.h>`,
:apiref:`daikin.h <daikin/daikin.h>`
:apiref:`fujitsu_general.h <fujitsu_general/fujitsu_general.h>`,
:apiref:`mitsubishi.h <mitsubishi/mitsubishi.h>`,
:apiref:`tcl112.h <tcl112/tcl112.h>`,
:apiref:`yashima.h <yashima/yashima.h>`
:apiref:`whirlpool.h <whirlpool/whirlpool.h>`
:apiref:`climate_ir_lg.h <climate_ir_lg/climate_ir_lg.h>`
- :ghedit:`Edit`

299
components/climate/pid.rst Normal file
View File

@ -0,0 +1,299 @@
PID Climate
===========
.. seo::
:description: Instructions for setting up PID climate controllers with ESPHome.
:image: function.png
The ``pid`` climate platform allows you to regulate a value with a
`PID controller <https://en.wikipedia.org/wiki/PID_controller>`__.
PID controllers are good at modulating an output signal to get a sensor reading to a specified
setpoint. For example, it can be used to modulate the power of a heating unit to get the
temperature to a user-specified setpoint.
Explaining how PID controllers work in detail is out of scope of this documentation entry,
but there's a nice article explaining the function principle `here <https://blog.opticontrols.com/archives/344>`__.
.. code-block:: yaml
# Example configuration entry
climate:
- platform: pid
name: "PID Climate Controller"
sensor: temperature_sensor
default_target_temperature: 21°C
heat_output: heater
control_parameters:
kp: 0.49460
ki: 0.00487
kd: 12.56301
Configuration variables:
------------------------
- **sensor** (**Required**, :ref:`config-id`): The sensor that is used to measure the current
temperature.
- **default_target_temperature** (**Required**, float): The default target temperature (setpoint)
for the control algorithm. This can be dynamically set in the frontend later.
- **heat_output** (*Optional*, :ref:`config-id`): The ID of a :ref:`float output <config-output>`
that increases the current temperature. At least one of ``heat_output`` and ``cool_output`` must
be specified.
- **cool_output** (*Optional*, :ref:`config-id`): The ID of a :ref:`float output <config-output>`
that decreases the current temperature. At least one of ``heat_output`` and ``cool_output`` must
be specified.
- **control_parameters** (**Required**): Control parameters of the PID controller.
- **kp** (**Required**, float): The factor for the proportional term of the PID controller.
- **ki** (*Optional*, float): The factor for the integral term of the PID controller.
Defaults to ``0``.
- **kd** (*Optional*, float): The factor for the derivative term of the PID controller.
Defaults to ``0``.
- **min_integral** (*Optional*, float): The maximum value of the integral term multiplied by
``ki`` to prevent windup. Defaults to ``-1``.
- **max_integral** (*Optional*, float): The minimum value of the integral term multiplied by
``ki`` to prevent windup. Defaults to ``1``.
- All other options from :ref:`Climate <config-climate>`.
.. _pid-setup:
PID Controller Setup
--------------------
To set up a PID climate controller, you need a couple of components:
- A :ref:`Sensor <config-sensor>` to read the current temperature (``sensor``).
- At least one :ref:`float output <config-output>` to drive for heating or cooling (or both).
This could for example be a PWM output via ``slow_pwm`` (TODO) that drives a heating unit.
Please note the output *must* be controllable with continuous value (not only ON/OFF, but any state
in between for example 50% heating power).
.. note::
The sensor should have a short update interval. The PID update frequency is tied to the update
interval of the sensor. Set a short ``update_interval`` like ``1s`` on the sensor.
.. _pid-autotune:
Autotuning
----------
Finding suitable ``kp``, ``ki`` and ``kd`` control parameters for the PID controller manually
needs some experience with PID controllers. ESPHome has an auto-tuning algorithm that automatically
finds suitable PID parameters to start using an adaption of the Ziegler-Nichols method with
relay autotuning (Åström and Hägglund).
To autotune the control parameters:
1. Set up the PID controller with all control parameters set to zero:
.. code-block:: yaml
climate:
- platform: pid
id: pid_climate
name: "PID Climate Controller"
sensor: temperature_sensor
default_target_temperature: 21°C
heat_output: heater
control_parameters:
kp: 0.0
ki: 0.0
kd: 0.0
2. Create a :doc:`template switch </components/switch/template>` to start autotuning later:
.. code-block:: yaml
switch:
- platform: template
name: "PID Climate Autotune"
turn_on_action:
- climate.pid.autotune: pid_climate
3. Compile & Upload the new firmware.
Now you should have a climate entity called "PID Climate Controller" and a switch called
"PID Climate Autotune" visible in your frontend of choice.
The autotune algorithm works by repeatedly switching the heat/cool output to full power and off.
This induced an oscillation of the observed temperature and the measured period and amplitude
is automatically calculated.
But this also means you **have to set the setpoint** of the climate controller to a value the
device can reach. For example if the temperature of a room is to be controlled, the setpoint needs
to be a bit of the ambient temperature. If the ambient temperature is 20°C, the setpoint of the
climate device should be set to at least ~24°C so that an oscillation can be induced.
4. Set an appropriate setpoint (see above).
5. Click on the "PID Climate Autotune" and view the logs of the device.
You should see output like
.. code-block:: text
PID Autotune:
Autotune is still running!
Status: Trying to reach 24.25 °C
Stats so far:
Phases: 4
Detected 5 zero-crossings
# ...
For example, in the output above, the autotuner is driving the heating output at 100%
and trying to reach 24.25 °C.
This will continue for some time until data for 6 phases (or a bit more, depending on the data
quality) have been acquired.
6. When the PID autotuner has succeeded, output like the one below can be seen:
.. code-block:: text
PID Autotune:
State: Succeeded!
All checks passed!
Calculated PID parameters ("Ziegler-Nichols PID" rule):
Calculated PID parameters ("Ziegler-Nichols PID" rule):
control_parameters:
kp: 0.49460
ki: 0.00487
kd: 12.56301
Please copy these values into your YAML configuration! They will reset on the next reboot.
# ...
Copy the values in ``control_parameters`` into your configuration.
.. code-block:: yaml
climate:
- platform: pid
# ...
control_parameters:
kp: 0.49460
ki: 0.00487
kd: 12.56301
7. Complete, compile & upload the updated firmware.
If the calculated PID parameters are not good, you can try some of the alternative parameters
printed below the main control parameters in the log output.
``climate.pid.autotune`` Action
-------------------------------
This action starts the autotune process of the PID controller.
.. code-block:: yaml
on_...:
# Basic
- climate.pid.autotune: pid_climate
# Advanced
- climate.pid.autotune:
id: pid_climate
noiseband: 0.25
positive_output: 25%
negative_output: -25%
Configuration variables:
- **id** (**Required**, :ref:`config-id`): ID of the PID Climate to start autotuning for.
- **noiseband** (*Optional*, float): The noiseband of the process (=sensor) variable. The value
of the PID controller must be able to reach this value. Defaults to ``0.25``.
- **positive_output** (*Optional*, float): The positive output power to drive the heat output at.
Defaults to ``1.0``.
- **negative_output** (*Optional*, float): The positive output power to drive the cool output at.
Defaults to ``-1.0``.
``climate.pid.set_control_parameters`` Action
---------------------------------------------
This action sets new values for the control parameters of the PID controller. This can be
used to manually tune the PID controller. Make sure to take update the values you want on
the YAML file! They will reset on the next reboot.
.. code-block:: yaml
on_...:
- climate.pid.set_control_parameters:
id: pid_climate
kp: 0.0
ki: 0.0
kd: 0.0
Configuration variables:
- **id** (**Required**, :ref:`config-id`): ID of the PID Climate to start autotuning for.
- **kp** (**Required**, float): The factor for the proportional term of the PID controller.
- **ki** (*Optional*, float): The factor for the integral term of the PID controller.
Defaults to ``0``.
- **kd** (*Optional*, float): The factor for the derivative term of the PID controller.
Defaults to ``0``.
``climate.pid.reset_integral_term`` Action
------------------------------------------
This action resets the integral term of the PID controller to 0. This might be necessary under certain
conditions to avoid the control loop to overshoot (or undershoot) a target.
.. code-block:: yaml
on_...:
# Basic
- climate.pid.reset_integral_term: pid_climate
Configuration variables:
- **id** (**Required**, :ref:`config-id`): ID of the PID Climate being reset.
PID Climate Sensor
------------------
Additionally, the PID climate platform provides an optional sensor platform to monitor
the calculated PID parameters to help finding good PID values.
.. code-block:: yaml
sensor:
- platform: pid
name: "PID Climate Result"
type: RESULT
Configuration variables:
- **name** (**Required**, string): The name of the sensor
- **type** (**Required**, string): The value to monitor. One of
- ``RESULT`` - The resulting value (sum of P, I, and D terms).
- ``ERROR`` - The calculated error (setpoint - process_variable)
- ``PROPORTIONAL`` - The proportional term of the PID controller.
- ``INTEGRAL`` - The integral term of the PID controller.
- ``DERIVATIVE`` - The derivative term of the PID controller.
- ``HEAT`` - The resulting heating power to the supplied to the ``heat_output``.
- ``COOL`` - The resulting cooling power to the supplied to the ``cool_output``.
- ``KP`` - The current factor for the proportional term of the PID controller.
- ``KI`` - The current factor for the integral term of the PID controller.
- ``KD`` - The current factor for the differential term of the PID controller.
Advanced options:
- **climate_id** (*Optional*, :ref:`config-id`): The ID of the pid climate to get the values from.
See Also
--------
- Ziegler-Nichols Method: Nichols, N. B. and J. G. Ziegler (1942), 'Optimum settings for automatic
controllers', Transactions of the ASME, 64, 759-768
- Åström, K. J. and T. Hägglund (1984a), 'Automatic tuning of simple regulators',
Proceedings of IFAC 9th World Congress, Budapest, 1867-1872
- :doc:`/components/climate/index`
- :apiref:`pid/pid_climate.h`
- :apiref:`PID Autotuner <pid/pid_autotune.h>`
- :ghedit:`Edit`

77
components/climate/tcl112.rst
View File

@ -1,77 +0,0 @@
TCL112 Remote Climate
=====================
.. seo::
:description: Controls a TCL112-compatible Climate via IR
:image: air-conditioner.png
The ``tcl112`` climate platform allows you to control a TCL112-compatible AC unit by sending IR signals
as your remote unit would do.
This component requires that you have setup a :doc:`/components/remote_transmitter`.
Due to the unidirectional nature of IR remote controllers, this component cannot determine the
actual state of the device, and will assume the state of the device is the latest state requested.
.. figure:: images/climate-ui.png
:align: center
:width: 60.0%
.. code-block:: yaml
# Example configuration entry
remote_transmitter:
pin: GPIO32
carrier_duty_percent: 50%
climate:
- platform: tcl112
name: "Living Room AC"
Configuration variables:
------------------------
- **name** (**Required**, string): The name for the climate.
- **supports_cool** (*Optional*, boolean): Enables setting cool mode for this climate device. Defaults to ``True``.
- **supports_heat** (*Optional*, boolean): Enables setting heat mode for this climate device. Defaults to ``True``.
- **sensor** (*Optional*, :ref:`config-id`): The sensor that is used to measure the ambient
temperature. This is only for reporting the current temperature in the frontend.
- **receiver_id** (*Optional*, :ref:`config-id`): The remote_receiver id, see: :ref:`tcl112-receiver_id`.
- All other options from :ref:`Climate <config-climate>`.
Advanced options:
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **transmitter_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the remote transmitter.
.. _tcl112-receiver_id:
Using a receiver
----------------
When using a receiver it is recommended to put the IR receiver as close as possible to the equipment's
IR receiver.
.. code-block:: yaml
# Example configuration entry
remote_receiver:
id: rcvr
pin:
number: GPIO14
inverted: True
mode: INPUT_PULLUP
tolerance: 45 # high tolerance required for some remote control units
climate:
- platform: tcl112
name: "Living Room AC"
receiver_id: rcvr
See Also
--------
- :doc:`/components/climate/index`
- :doc:`/components/remote_transmitter`
- :apiref:`tcl112/tcl112.h`
- :ghedit:`Edit`

284
components/climate/thermostat.rst Normal file
View File

@ -0,0 +1,284 @@
Thermostat Climate Controller
=============================
.. seo::
:description: Instructions for setting up Thermostat climate controllers with ESPHome.
:image: air-conditioner.png
The ``thermostat`` climate platform allows you to control a climate control system in much the same manner as a
physical thermostat. Its operation is similar to the :doc:`bang-bang <bang_bang>` controller; a sensor measures a value
(the air temperature) and the controller will try to keep this value within a range defined by the set point(s). To do this,
the controller can activate devices like a heating unit and/or a cooling unit to change the value observed by the sensor.
When configured for both heating and cooling, it is essentially two :doc:`bang-bang <bang_bang>` controllers in one; it
differs, however, in that interation with the thermostat component is nearly identical to that of a real thermostat.
This component can operate in one of two ways:
- **Single-point**: A single threshold (set point) is defined; cooling may be activated when the observed temperature
exceeds the set point **or** heating may be activated when the observed temperature drops below the set point; that is,
the controller can only raise the temperature or lower the temperature. It cannot do both in this mode.
- **Dual-point**: Two thresholds (set points) are defined; cooling is activated when the observed temperature exceeds the
upper set point while heating is activated when the observed temperature drops below the lower set point; in other words,
the controller is able to both raise and lower the temperature as required.
This component/controller automatically determines which mode it should operate in based on what :ref:`actions <config-action>`
are configured -- more on this in a moment. Two parameters define the set points; they are ``target_temperature_low`` and
``target_temperature_high``. In single-point mode, however, only one is used. The set point(s) may be adjusted through the
front-end user interface. The screenshot below illustrates a thermostat controller in dual-point mode, where two set points
are available.
.. figure:: images/climate-ui.png
:align: center
:width: 60.0%
Dual-setpoint climate UI
This component works by triggering a number of :ref:`actions <config-action>` as required to keep the observed
temperature above/below/within the target range as defined by the set point(s). In general, when the observed temperature
drops below ``target_temperature_low`` the controller will trigger the ``heat_action`` to activate heating. When the observed
temperature exceeds ``target_temperature_high`` the controller will trigger the ``cool_action`` or the ``fan_only_action``
(as determined by the climate mode) to activate cooling. When the temperature has reached a point within the desired range, the
controller will trigger the ``idle_action`` to stop heating/cooling. Please see the next section for more detail.
A number of fan control modes are built into the climate/thermostat interface in Home Assistant; this component may also be
configured to trigger :ref:`actions <config-action>` based on the entire range (at the time this document was written) of fan
modes that Home Assistant offers.
.. code-block:: yaml
# Example dual-point configuration entry
climate:
- platform: thermostat
name: "Thermostat Climate Controller"
sensor: my_temperature_sensor
default_target_temperature_low: 20 °C
default_target_temperature_high: 22 °C
cool_action:
- switch.turn_on: air_cond
heat_action:
- switch.turn_on: heater
idle_action:
- switch.turn_off: air_cond
- switch.turn_off: heater
.. code-block:: yaml
# Example single-point configuration entry (for heating only)
climate:
- platform: thermostat
sensor: my_temperature_sensor
default_target_temperature_low: 20 °C
heat_action:
- switch.turn_on: heater
idle_action:
- switch.turn_off: heater
.. code-block:: yaml
# Example single-point configuration entry (for cooling only)
climate:
- platform: thermostat
sensor: my_temperature_sensor
default_target_temperature_high: 22 °C
cool_action:
- switch.turn_on: air_cond
idle_action:
- switch.turn_off: air_cond
Controller Behavior and Hysteresis
----------------------------------
In addition to the set points, a hysteresis value determines how far the temperature may vary from the set point value(s)
before an :ref:`action <config-action>` (cooling, heating, etc.) is triggered. It defaults to 0.5 °C.
A question that often surfaces about this component is, "What is the expected behavior?" Let's quickly discuss
*exactly when* the configured actions are called by the controller.
Consider the low set point (the one that typically activates heating) for a moment, and assume it is set to a common room
temperature of 21 °C. As mentioned above, the controller uses a default hysteresis value of 0.5 °C, so let's assume that
value here, as well. The controller as implemented in this component will allow the temperature to drop as low as the set
point's value (21 °C) *minus* the hysteresis value (0.5 °C), or 20.5 °C, before calling ``heat_action`` to activate heating.
After heating has been activated, it will remain active until the observed temperature reaches the set point (21 °C) *plus*
the hysteresis value (0.5 °C), or 21.5 °C. Once this temperature is reached, ``idle_action`` will be called to deactivate
heating.
The same behavior applies to the high set point, although the behavior is reversed in a sense; given an upper set point of
22 °C, ``cool_action`` would be called at 22.5 °C and ``idle_action`` would not be called until the temperature is reduced
to 21.5 °C.
Important Terminology
---------------------
Before we get into more configuration detail, let's take a step back and talk about the word "action"; we
need to carefully consider the context of the word in the upcoming section, as it has a double meaning and
will otherwise lead to some ambiguity.
- **ESPHome Action**: A task the ESPHome application performs as requested, such as
turning on a switch. See :ref:`Action <config-action>`.
- **Climate Action**: What the climate device is actively doing
- **Climate Mode**: What the climate device should (or should not) do
We'll call out which definition "action" we are referring to as we describe them below -- read carefully!
With respect to climate control, it is important to understand the subtle difference between the terms
"action" and "mode" as they *are not the same thing*:
Examples:
- **Heat Mode**: The climate device may heat but may **not** cool.
- **Heat Action**: The climate device is *actively distributing heated air* into the dwelling.
Got all that? Great. Let's take a closer look at some configuration.
Configuration Variables
-----------------------
The thermostat controller uses the sensor to determine whether it should heat or cool.
- **sensor** (**Required**, :ref:`config-id`): The sensor that is used to measure the current temperature.
Default Target Temperatures
***************************
These temperatures are used when the device first starts up.
- **default_target_temperature_low** (*Optional*, float): The default low target
temperature for the control algorithm. This can be dynamically set in the frontend later.
- **default_target_temperature_high** (*Optional*, float): The default high target
temperature for the control algorithm. This can be dynamically set in the frontend later.
**At least one of** ``default_target_temperature_low`` **and** ``default_target_temperature_high``
**must be specified.**
Heating and Cooling Actions
***************************
These are triggered when the climate control **action** is changed by the thermostat controller. Here,
"action" takes on both meanings described above, as these are both climate actions *and* ESPHome
:ref:`actions <config-action>`. These should be used to activate heating, cooling, etc. devices.
- **idle_action** (**Required**, :ref:`Action <config-action>`): The action to call when
the climate device should enter its idle state (not cooling, not heating).
- **heat_action** (*Optional*, :ref:`Action <config-action>`): The action to call when
the climate device should enter heating mode to increase the current temperature.
- **cool_action** (*Optional*, :ref:`Action <config-action>`): The action to call when
the climate device should enter cooling mode to decrease the current temperature.
- **dry_action** (*Optional*, :ref:`Action <config-action>`): The action to call when
the climate device should perform its drying (dehumidification) action. The thermostat
controller does not trigger this action; it is invoked by ``dry_mode`` (see below).
- **fan_only_action** (*Optional*, :ref:`Action <config-action>`): The action to call when
the climate device should activate its fan only (but does not heat or cool). The thermostat
controller triggers this action based on the upper target temperature when set to
``fan_only_mode`` (see below).
- All other options from :ref:`Climate <config-climate>`.
**At least one of** ``cool_action``, ``fan_only_action``, ``heat_action``, **and** ``dry_action``
**must be specified.**
If only one of ``cool_action``, ``fan_only_action``, ``heat_action``, and ``dry_action`` is specified,
the controller will configure itself to operate in single-point mode and, as such, Home Assistant will
display the single-point climate user interface for the device.
Heating and Cooling Modes
*************************
These are triggered when the climate control **mode** is changed. Note the absence of "action" in the
parameter name here -- these are still ESPHome :ref:`actions <config-action>`, however they are *not*
climate actions. Instead, they are climate *modes*. These :ref:`actions <config-action>` are useful
in that they could be used, for example, to toggle a group of LEDs on and/or off to provide a visual
indication of the current climate mode.
- **auto_mode** (*Optional*, :ref:`Action <config-action>`): The action to call when
the climate device is placed into "auto" mode (it may both cool and heat as required).
- **off_mode** (*Optional*, :ref:`Action <config-action>`): The action to call when
the climate device is placed into "off" mode (it is completely disabled).
- **heat_mode** (*Optional*, :ref:`Action <config-action>`): The action to call when
the climate device is placed into heat mode (it may heat as required, but not cool).
- **cool_mode** (*Optional*, :ref:`Action <config-action>`): The action to call when
the climate device is placed into cool mode (it may cool as required, but not heat).
- **dry_mode** (*Optional*, :ref:`Action <config-action>`): The action to call when
the climate device is placed into dry mode (for dehumidification).
- **fan_only_mode** (*Optional*, :ref:`Action <config-action>`): The action to call when
the climate device is placed into fan only mode (it may not heat or cool, but will activate
its fan as needed based on the upper target temperature value).
**The above actions are not to be used to activate cooling or heating devices!**
See the previous section for those.
Fan Mode Actions
****************
These are triggered when the climate control fan mode is changed. These are ESPHome :ref:`actions <config-action>`.
These should be used to control the fan only, if available.
- **fan_mode_auto_action** (*Optional*, :ref:`Action <config-action>`): The action to call when the fan
should be set to "auto" mode (the fan is controlled by the climate control system as required).
- **fan_mode_on_action** (*Optional*, :ref:`Action <config-action>`): The action to call when the fan
should run continuously.
- **fan_mode_off_action** (*Optional*, :ref:`Action <config-action>`): The action to call when the fan
should never run.
- **fan_mode_low_action** (*Optional*, :ref:`Action <config-action>`): The action to call when the fan
should run at its minimum speed.
- **fan_mode_medium_action** (*Optional*, :ref:`Action <config-action>`): The action to call when the fan
should run at an intermediate speed.
- **fan_mode_high_action** (*Optional*, :ref:`Action <config-action>`): The action to call when the fan
should run at its maximum speed.
- **fan_mode_middle_action** (*Optional*, :ref:`Action <config-action>`): The action to call when the fan
should direct its airflow at an intermediate area.
- **fan_mode_focus_action** (*Optional*, :ref:`Action <config-action>`): The action to call when the fan
should direct its airflow at a specific area.
- **fan_mode_diffuse_action** (*Optional*, :ref:`Action <config-action>`): The action to call when the fan
should direct its airflow over a broad area.
Swing Mode Actions
******************
These are triggered when the climate control swing mode is changed. These are ESPHome :ref:`actions <config-action>`.
These should be used to control the fan only, if available.
- **swing_off_action** (*Optional*, :ref:`Action <config-action>`): The action to call when the fan should
remain in a stationary position.
- **swing_horizontal_action** (*Optional*, :ref:`Action <config-action>`): The action to call when the fan
should oscillate in a horizontal direction.
- **swing_vertical_action** (*Optional*, :ref:`Action <config-action>`): The action to call when the fan
should oscillate in a vertical direction.
- **swing_both_action** (*Optional*, :ref:`Action <config-action>`): The action to call when the fan
should oscillate in horizontal and vertical directions.
Advanced Options
****************
- **hysteresis** (*Optional*, float): Defines how far the temperature may vary from the target values before
an :ref:`action <config-action>` (cooling, heating, etc.) is triggered. Defaults to 0.5 °C.
- **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 sleeping/at night).
- **default_target_temperature_low** (*Optional*, float): The default low target temperature for the control
algorithm when Away mode is selected. This can be dynamically set in the frontend later.
- **default_target_temperature_high** (*Optional*, float): The default high target temperature for the control
algorithm when Away mode is selected. This can be dynamically set in the frontend later.
**If configured, at least one of** ``default_target_temperature_low`` **and** ``default_target_temperature_high``
**must be specified in the away mode configuration.**
.. note::
While this platform uses the term temperature everywhere, it can also be used to regulate other values.
For example, controlling humidity is also possible with this platform.
Bang-bang vs. Thermostat
------------------------
Please see the :doc:`Bang-bang <bang_bang>` component's documentation for a detailed comparison of these two components.
See Also
--------
- :doc:`/components/climate/index`
- :doc:`/components/sensor/index`
- :ref:`config-action`
- :ghedit:`Edit`

59
components/climate/tuya.rst Normal file
View File

@ -0,0 +1,59 @@
Tuya Climate
============
.. seo::
:description: Instructions for setting up a Tuya climate device.
:image: air-conditioner.png
The ``tuya`` climate platform creates a climate device from a tuya component.
The Tuya fan requires a :doc:`/components/tuya` to be configured.
.. code-block:: text
[22:03:11][C][tuya:023]: Tuya:
[22:03:11][C][tuya:032]: Datapoint 1: switch (value: ON)
[22:03:11][C][tuya:032]: Datapoint 2: switch (value: OFF)
[22:03:11][C][tuya:034]: Datapoint 3: int value (value: 20)
[22:03:11][C][tuya:034]: Datapoint 4: int value (value: 19)
[22:03:11][C][tuya:034]: Datapoint 5: int value (value: 0)
[22:03:11][C][tuya:036]: Datapoint 7: enum (value: 1)
[22:03:11][C][tuya:046]: Product: '{"p":"ynjanlglr4qa6dxf","v":"1.0.0","m":0}'
On this controller, the data points are:
- 1 represents the climate on/off state.
- 2 represents the child lock switch. (use the :doc:`/components/switch/tuya` component to control this)
- 3 represents the target temperature.
- 4 represents the current temperature.
- 5 represents the timer but is not yet available to be used in ESPHome.
- 7 represents the eco mode switch. (use the :doc:`/components/switch/tuya` component to control this)
Based on this, you can create the climate device as follows:
.. code-block:: yaml
climate:
- platform: tuya
name: "My Climate Device"
switch_datapoint: 1
target_temperature_datapoint: 3
current_temperature_datapoint: 4
Configuration variables:
------------------------
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **name** (**Required**, string): The name of the climate device.
- **switch_datapoint** (**Required**, int): The datapoint id number of the climate switch.
- **target_temperature_datapoint** (**Required**, int): The datapoint id number of the target temperature.
- **current_temperature_datapoint** (**Required**, int): The datapoint id number of the current temperature.
- All other options from :ref:`Climate <config-climate>`.
See Also
--------
- :doc:`/components/tuya`
- :doc:`/components/climate/index`
- :apiref:`tuya/climate/tuya_climate.h`
- :ghedit:`Edit`

52
components/climate/yashima.rst
View File

@ -1,52 +0,0 @@
Yashima Remote Climate
======================
.. seo::
:description: Controls a Yashima compatible Climate via IR
:image: air-conditioner.png
The ``yashima`` climate platform allows you to control a Yashima compatible AC unit by sending IR signals
as your remote unit would do.
This component requires that you have setup a :doc:`/components/remote_transmitter`.
Due to the unidirectional nature of IR remote controllers, this component cannot determine the
actual state of the device, and will assume the state of the device is the latest state requested.
.. figure:: images/climate-ui.png
:align: center
:width: 60.0%
.. code-block:: yaml
# Example configuration entry
remote_transmitter:
pin: GPIO32
carrier_duty_percent: 50%
climate:
- platform: yashima
name: "Living Room AC"
Configuration variables:
------------------------
- **name** (**Required**, string): The name for the climate.
- **supports_cool** (*Optional*, boolean): Enables setting cool mode for this climate device. Defaults to ``True``.
- **supports_heat** (*Optional*, boolean): Enables setting heat mode for this climate device. Defaults to ``True``.
- **sensor** (*Optional*, :ref:`config-id`): The sensor that is used to measure the ambient
temperature. This is only for reporting the current temperature in the frontend.
- All other options from :ref:`Climate <config-climate>`.
Advanced options:
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **transmitter_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the remote transmitter.
See Also
--------
- :doc:`/components/climate/index`
- :doc:`/components/remote_transmitter`
- :apiref:`yashima/yashima.h`
- :ghedit:`Edit`

7
components/cover/template.rst
View File

@ -60,12 +60,15 @@ Configuration variables:
of hiding one of them. Defaults to ``false``.
- **has_position** (*Optional*, boolean): Whether this cover will publish its position as a floating point number.
By default (``false``), the cover only publishes OPEN/CLOSED position.
By setting this to true you can also send any position in between using the publish action.
Parameter useless if you set the POSITION_ACTION (is set to TRUE).
- **tilt_action** (*Optional*, :ref:`Action <config-action>`): The action that should
be performed when the remote (like Home Assistant's frontend) requests the cover be set to a specific
tilt position.
tilt position. The desired tilt is available in the lambda in the ``tilt`` variable.
- **tilt_lambda** (*Optional*, :ref:`lambda <config-lambda>`):
Lambda to be evaluated repeatedly to get the current tilt position of the cover.
- **position_action** (*Optional*, :ref:`Action <config-action>`): The action that should
be performed when the remote (like Home Assistant's frontend) requests the cover be set to a specific
position. The desired position is available in the lambda in the ``pos`` variable.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- All other options from :ref:`Cover <config-cover>`.

3
components/cover/time_based.rst
View File

@ -52,6 +52,9 @@ Configuration variables:
detectors. In this configuration the ``stop_action`` is not performed when the open or close
time is completed and if the cover is commanded to open or close the corresponding actions
will be performed without checking current state. Defaults to ``False``.
- **assumed_state** (*Optional*, boolean): Whether the true state of the cover is not known.
This will make the Home Assistant frontend show buttons for both OPEN and CLOSE actions, instead
of hiding or disabling one of them. Defaults to ``True``.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- All other options from :ref:`Cover <config-cover>`.

76
components/display/images/max7219/seg09.svg Normal file
View File

@ -0,0 +1,76 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<svg
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:cc="http://creativecommons.org/ns#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns="http://www.w3.org/2000/svg"
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
width="300"
height="300"
version="1"
id="svg14"
sodipodi:docname="seg09.svg"
inkscape:version="0.92.3 (2405546, 2018-03-11)">
<metadata
id="metadata20">
<rdf:RDF>
<cc:Work
rdf:about="">
<dc:format>image/svg+xml</dc:format>
<dc:type
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
</cc:Work>
</rdf:RDF>
</metadata>
<defs
id="defs18" />
<sodipodi:namedview
pagecolor="#ffffff"
bordercolor="#666666"
borderopacity="1"
objecttolerance="10"
gridtolerance="10"
guidetolerance="10"
inkscape:pageopacity="0"
inkscape:pageshadow="2"
inkscape:window-width="1581"
inkscape:window-height="480"
id="namedview16"
showgrid="false"
inkscape:zoom="1.5733333"
inkscape:cx="142.17599"
inkscape:cy="160.323"
inkscape:window-x="718"
inkscape:window-y="580"
inkscape:window-maximized="0"
inkscape:current-layer="svg14" />
<g
id="g12"
stroke="#000">
<path
d="m 190.797,154.49152 -15.212,15.5 h -59 l -15.517,-15.5 15.517,-15.5 h 59 z m 0,81.5 -15.212,15.5 h -59 l -15.517,-15.5 15.517,-15.5 h 59 z"
id="path2"
inkscape:connector-curvature="0"
style="fill:#ff0000;fill-rule:evenodd" />
<path
d="M98 75.385l15.5 15.212v45L98 151.115l-15.5-15.518v-45L98 75.385zM194 75.385l15.5 15.212v45L194 151.115l-15.5-15.518v-45L194 75.385z"
id="path4"
fill="none" />
<path
d="M 190.797,72.5 175.585,88 h -59 L 101.068,72.5 116.585,57 h 59 z"
id="path6"
style="fill:#ffffff;fill-opacity:1;fill-rule:evenodd"
inkscape:connector-curvature="0" />
<path
d="M98 157.443l15.5 15.212v45L98 233.172l-15.5-15.517v-45L98 157.443zM194 157.443l15.5 15.212v45L194 233.172l-15.5-15.517v-45l15.5-15.212z"
id="path8"
fill="none" />
<path
d="M237.5 239.25a12.25 12.25 0 1 1-24.5 0 12.25 12.25 0 1 1 24.5 0z"
id="path10"
stroke-linecap="round"
fill="none" />
</g>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 2.4 KiB

BIN
components/display/images/max7219digit.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 49 KiB

BIN
components/display/images/pcd8544-full.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 18 KiB

BIN
components/display/images/ssd1351-full.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 143 KiB

BIN
components/display/images/st7789v-full.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 445 KiB

BIN
components/display/images/tm1637-full.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 41 KiB

9
components/display/max7219.rst
View File

@ -105,10 +105,13 @@ segment of the previous position will be enabled.
it.strftime("%H.%M.%S");
// Result for 10:06:42 -> "10.06.42 "
// Change the display intnsity based on another id.
// Value should be from 0-15.
it.set_intensity(id(my_brightness));
Please see :ref:`display-printf` for a quick introduction into the ``printf`` formatting rules and
:ref:`display-strftime` for an introduction into the ``strftime`` time formatting.
.. _display-max7219_characters:
All 7-Segment Characters
@ -207,6 +210,8 @@ All 7-Segment Characters
------------------------------ ------------------------------
|max721908| ``_``
------------------------------ ------------------------------
|max721909| ``=``
------------------------------ ------------------------------
|max721906| ``|``
------------------------------ ------------------------------
|max72190D| ``c``
@ -310,6 +315,8 @@ All 7-Segment Characters
:class: component-image
.. |max721908| image:: images/max7219/seg08.svg
:class: component-image
.. |max721909| image:: images/max7219/seg09.svg
:class: component-image
.. |max721906| image:: images/max7219/seg06.svg
:class: component-image
.. |max72190D| image:: images/max7219/seg0D.svg

209
components/display/max7219digit.rst Normal file
View File

@ -0,0 +1,209 @@
MAX7219 Digit Display
=====================
.. seo::
:description: Instructions for setting up MAX7219 Digit displays.
:image: max7219digit.png
The ``max7219`` display platform allows you to use MAX7219 digit with ESPHome. Please note that this integration
is *only* for the digit "matrix" display, for the 7 segment display see :doc:`max7219`.
.. figure:: images/max7219digit.png
:align: center
:width: 75.0%
MAX7219 Digit Display.
As the communication with the MAX7219 Digit is done using SPI for this integration, you need
to have an :ref:`SPI bus <spi>` in your configuration with both the **mosi_pin** set (miso_pin is not required).
Connect VCC to 3.3V (the manufacturer recommends 4+ V, but 3.3V seems to work fine), DIN to your ``mosi_pin`` and
CS to your set ``cs_pin`` and finally GND to GND.
You can even daisy-chain multiple MAX7219s by connecting the DOUT of the previous chip in the chain to the
next DIN. With more than ~3 chips the 3.3V will probably not be enough, so then you will have to potentially
use a logic level converted.
.. code-block:: yaml
# Example configuration entry
spi:
clk_pin: D0
mosi_pin: D1
display:
- platform: max7219digit
cs_pin: D2
num_chips: 4
intensity: 15
lambda: |-
it.print(0, 0, id(digit_font), "HELLO!");
Configuration variables:
------------------------
- **cs_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The pin you have the CS line hooked up to.
- **num_chips** (*Optional*, integer): The number of chips you wish to use for daisy chaining. Defaults to
``4``.
- **rotate_chip** (*Optional*): Rotates every 8x8 chip. Valid values are ``0``, ``90``, ``180`` and ``270``.
Defaults to ``0``.
- **scroll_enable** (*Optional*, boolean): Turn scroll mode on when content does not fit. Defaults to ``True``.
- **scroll_mode** (*Optional*): Set the scroll mode. One of ``CONTINUOUS`` or ``STOP``. Defaults to ``CONTINUOUS``
- ``CONTINUOUS``: Always scrolls and the text repeats continuously, you might need to add some
separation at the end.
- ``STOP``: When text is over it waits the ``scroll_dwell`` time and scroll is set back to the start.
- **scroll_speed** (*Optional*, :ref:`config-time`): Set scroll speed. Defaults to ``250ms``
- **scroll_delay** (*Optional*, :ref:`config-time`): Set delay time before scroll starts. Defaults to ``1s``.
- **scroll_dwell** (*Optional*, :ref:`config-time`): Sets the wait time at the end of the scroll before starting
over. This is only used in mode ``STOP``. Defaults to ``1s``.
- **intensity** (*Optional*, integer): The intensity with which the MAX7219 should drive the outputs. Range is
from ``0``, least intense to ``15`` the brightest. Defaults to ``15``.
- **lambda** (*Optional*, :ref:`lambda <config-lambda>`): The lambda to use for rendering the content on the
MAX7219. See :ref:`display-max7219digit_lambda` for more information.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to re-draw the screen. Defaults to ``1s``.
- **spi_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`SPI Component <spi>` if you want
to use multiple SPI buses.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
.. _display-max7219digit_lambda:
Rendering Lambda
----------------
The MAX7219 digit is based on the fully fledged :ref:`display-engine`, as it has a concept of individual pixels 8 X 8
per max7219 chip. In the lambda you're passed a variable called ``it`` as with all other displays. Some "Special"
commands have been added to the basic display set.
.. code-block:: yaml
display:
- platform: max7219digit
cs_pin: D8
num_chips: 4
lambda: |-
it.strftime(0, 0, id(digit_font), "%H:%M", id(hass_time).now());
it.image(24, 0, id(my_image));
it.line(1, 7, 21, 7);
font:
- file: "pixelmix.ttf"
id: digit_font
size: 6
time:
- platform: homeassistant
id: hass_time
image:
- file: "smile.png"
id: my_image
This is roughly the code used to display the MAX7219 pictured in the image.
Scrolling
*********
By default the MAX7219Digit display has scroll enabled. The paramaters can be set in the YAML file.
They can also be changed in the Lambda by adding the following command:
.. code-block:: cpp
it.scroll(<on/off>, <mode>, <speed>, <delay>, <dwell>);
- **on/off** -> switch scrolling on or off, use true or false
- **mode** -> 0 = Continuous scrolling, 1 = Stop at end and reset
- **speed** -> Set speed of scrolling (ms for every step of one dot)
- **delay** -> pause time at start of scrolling
- **dwell** -> pause at end of scrolling (only in mode 1)
.. code-block:: yaml
display:
- platform: max7219digit
# ...
lambda: |-
# ...
it.scroll(true, 0, 100, 5000, 1500);
// OR
it.scroll(true, 0);
// OR
it.scroll(true);
- The screen does not scroll if the text fits within the screen.
- ``printdigit("...")`` and ``printdigitf("...")`` the alternative way of displaying text does not scroll
Screen inversion
****************
.. code-block:: yaml
display:
- platform: max7219digit
# ...
lambda: |-
it.invert_on_off(true);
// Print Hello at position 0 (left)
it.print(0,0, id(digit_font), "Hello!");
The function ``it.invert_on_off(true);`` will invert the display. So background pixels are on and texts pixels are
off. ``it.invert_on_off(false);`` sets the display back to normal. In case no argument is used: ``it.inverst_on_off();``
the inversion will toggle from on to off or visa versa. This will happen every time the display is updated.
So a blinking effect is created. The background pixels are only set at the next update, the pixels drawn in
the various function like print, line, etc. are directly influenced by the invert command.
.. code-block:: yaml
display:
- platform: max7219digit
# ...
lambda: |-
it.invert_on_off(true);
// Print Hello at position 0 (left)
it.print(0,0, id(digit_font), "Hello!");
it.line(0, 0, 31, 7, COLOR_OFF);
This code will only affect the line drawn on the screen. The line will wipe the pixels from top left to right bottom.
The background is not affected.
Screen intensity
****************
The intensity of the screen can be set "dynamically" within the lambda code with the following command: it.intensity(``0`` .. ``15``).
.. code-block:: yaml
display:
- platform: max7219digit
# ...
lambda: |-
it.intensity(10);
Screen ON/OFF
*************
The display can be switched on and off "dynamically" within the lambda code with the following command: it.turn_on_off(true or false).
.. code-block:: yaml
display:
- platform: max7219digit
# ...
lambda: |-
it.turn_on_off(true);
For a quick display some additional commands are embedded in the code with a related 8 pixel font. Three methods
(``printdigit``, ``printdigitf`` and ``strftimedigit``) can be used for diplaying characters. Each 8 X 8 grid is used to
display a single character. So not very space efficient. The format of the command is: ``it.printdigit("1234");`` or
``it.printdigitf("%s","1234")``;
Please see :ref:`display-printf` for a quick introduction into the ``printf`` formatting rules and
:ref:`display-strftime` for an introduction into the ``strftime`` time formatting.
See Also
--------
- :doc:`index`
- :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

@ -39,6 +39,8 @@ Configuration variables:
- **uart_id** (*Optional*, :ref:`config-id`): The ID of the :ref:`UART bus <uart>` you wish to use for this display.
Use this if you want to use multiple UART buses at once.
- **brightness** (*Optional*, percentage): Set the screen brightness. Must be in range
``0%`` to ``100%`` or ``0.0`` to ``1.0``. Defaults to ``100%``.
- **lambda** (*Optional*, :ref:`lambda <config-lambda>`): The lambda to use for rendering the content on the nextion display.
See :ref:`display-nextion_lambda` for more information.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to call the lambda to update the display.

72
components/display/pcd8544.rst Normal file
View File

@ -0,0 +1,72 @@
PCD 8544 Display (Nokia 5110/3310)
==================================
.. seo::
:description: Instructions for setting up PCD8544 display drivers.
:image: pcd8544.jpg
.. _pcd8544:
Usage
-----
The ``pcd8544`` display platform allows you to use
PCD8544 (`Adafruit <https://www.adafruit.com/product/338>`__)
displays with ESPHome. Connection to this display is made using the 4-Wire :ref:`SPI bus <spi>`.
It's a monochrome LCD display was used in old Nokia 5110/3310 cell phones.
The resolution of the display is 84x48 pixels.
.. figure:: images/pcd8544-full.jpg
:align: center
:width: 75.0%
PCD8544 Display
Connect CLK, DIN, CS (CE), DC, and RST to pins on your ESP. For power, connect
VCC to 3.3V and GND to GND.
.. code-block:: yaml
# Example configuration entry
spi:
clk_pin: D5
mosi_pin: D7
display:
- platform: pcd8544
reset_pin: D0
cs_pin: D8
dc_pin: D1
lambda: |-
it.print(0, 0, id(font), "Hello World!");
Backlight
*********
To use a backlight LIGHT pin needs to be connected to ground. If connected to GPIO pin it can be controlled from EPSHome. See :doc:`/components/light/monochromatic`.
Configuration variables:
************************
- **reset_pin** (**Required**)(:ref:`Pin Schema <config-pin_schema>`): The RESET pin.
- **cs_pin** (**Required**)(:ref:`Pin Schema <config-pin_schema>`): The CS pin.
- **dc_pin** (**Required**)(:ref:`Pin Schema <config-pin_schema>`): The DC pin.
- **lambda** (*Optional*, :ref:`lambda <config-lambda>`): The lambda to use for rendering the content on the display.
See :ref:`display-engine` for more information.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to re-draw the screen. Defaults to ``5s``.
- **pages** (*Optional*, list): Show pages instead of a single lambda. See :ref:`display-pages`.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
See Also
--------
- :doc:`index`
- :apiref:`pcd8544/pcd8544.h`
- `Tutorial from Adafruit <https://learn.adafruit.com/nokia-5110-3310-monochrome-lcd>`__
- `PCD8544 Library <https://github.com/adafruit/Adafruit-PCD8544-Nokia-5110-LCD-library>`__ by `Adafruit <https://www.adafruit.com/>`__
- :ghedit:`Edit`

101
components/display/ssd1325.rst
View File

@ -1,8 +1,8 @@
SSD1325 OLED Display
====================
SSD1325/7 OLED Display
======================
.. seo::
:description: Instructions for setting up SSD1325 OLED display drivers.
:description: Instructions for setting up SSD1325/7 OLED display drivers.
:image: ssd1325.jpg
.. _ssd1325-spi:
@ -12,7 +12,8 @@ Usage
The ``ssd1325_spi`` display platform allows you to use
SSD1325 (`datasheet <https://cdn-shop.adafruit.com/datasheets/SSD1325.pdf>`__,
`Adafruit <https://www.adafruit.com/product/2674>`__)
`Adafruit <https://www.adafruit.com/product/2674>`__) and SSD1327 (`datasheet <https://www.waveshare.com/w/upload/a/ac/SSD1327-datasheet.pdf>`__,
`Waveshare <https://www.waveshare.com/1.5inch-oled-module.htm>`__)
displays with ESPHome. Note that this component is for displays that are connected via the 4-Wire :ref:`SPI bus <spi>`.
.. figure:: images/ssd1325-full.jpg
@ -22,7 +23,11 @@ displays with ESPHome. Note that this component is for displays that are connect
SSD1325 OLED Display
Connect CLK, DIN, CS, DC, and RST to pins on your ESP. For power, connect
VCC to 3.3V and GND to GND.
VCC to 3.3V and GND to GND. Note that two jumper resistors on the back of the
display PCB may need to be moved to put the display into SPI mode.
`Adafruit <https://www.adafruit.com/product/2674>`__ has a
`guide <https://learn.adafruit.com/2-7-monochrome-128x64-oled-display-module/assembly>`__
that explains how to do this, if necessary.
.. code-block:: yaml
@ -40,18 +45,21 @@ VCC to 3.3V and GND to GND.
lambda: |-
it.print(0, 0, id(font), "Hello World!");
Configuration variables:
************************
Configuration Variables
***********************
- **model** (**Required**): The model of the display. Options are:
- ``SSD1325 128x32`` (SSD1325 with 128 columns and 32 rows)
- ``SSD1325 128x64``
- ``SSD1327 128x128`` (note SSD1327 instead of SSD1325)
- ``SSD1325 96x16``
- ``SSD1325 64x48``
- ``SSD1327 128x128`` **# Note the number seven!**
- **reset_pin** (:ref:`Pin Schema <config-pin_schema>`): The RESET pin.
- **cs_pin** (:ref:`Pin Schema <config-pin_schema>`): The CS pin.
- **cs_pin** (:ref:`Pin Schema <config-pin_schema>`): The pin on the ESP that that the CS line is connected to.
The CS line can be connected to GND if this is the only device on the SPI bus.
- **dc_pin** (:ref:`Pin Schema <config-pin_schema>`): The DC pin.
- **lambda** (*Optional*, :ref:`lambda <config-lambda>`): The lambda to use for rendering the content on the display.
See :ref:`display-engine` for more information.
@ -59,6 +67,83 @@ Configuration variables:
- **pages** (*Optional*, list): Show pages instead of a single lambda. See :ref:`display-pages`.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
Configuration examples
**********************
To utilize the grayscale capabilities of this display module, add a ``color:`` section to your YAML configuration;
please see :ref:`color <config-color>` for more details. As this is a grayscale display, it only uses the white color
element as shown below.
To use grayscale in your lambada:
.. code-block:: yaml
color:
- id: medium_gray
white: 50%
...
display:
...
lambda: |-
it.rectangle(0, 0, it.get_width(), it.get_height(), id(medium_gray));
To bring in grayscale images:
.. code-block:: yaml
image:
- file: "image.jpg"
id: my_image
resize: 120x120
type: GRAYSCALE
...
display:
...
lambda: |-
it.image(0, 0, id(my_image));
In this case, the image will be converted to grayscale (regardless of its original format) and rendered as such
when drawn on the display. Note that the original image may require some adjustment as not all images immediately
convert nicely to the 4-bit grayscale format this display supports.
Note that if ``type: GRAYSCALE`` is omitted, the image will render as a binary image (no grayscale); in this
case, a color attribute may be passed to the ``image()`` method as follows:
.. code-block:: yaml
image:
- file: "image.jpg"
id: my_image
resize: 120x120
...
display:
...
lambda: |-
it.image(0, 0, id(medium_gray), id(my_image));
This will draw the complete image with the given shade of gray.
To create a new color as needed in code:
.. code-block:: yaml
display:
...
lambda: |-
float white_intensity = 0.5;
Color variable_gray(0, 0, 0, white_intensity);
it.rectangle(0, 0, it.get_width(), it.get_height(), variable_gray);
The last argument of the ``Color`` constructor is the intensity of the white element; it is a percentage
(value of range 0 to 1). It may be defined by another variable so it is adjustable in code.
See Also
--------

108
components/display/ssd1351.rst Normal file
View File

@ -0,0 +1,108 @@
SSD1351 OLED Display
====================
.. seo::
:description: Instructions for setting up SSD1351 OLED display drivers.
:image: ssd1351.jpg
.. _ssd1351-spi:
Usage
-----
The ``ssd1351_spi`` display platform allows you to use
SSD1351 (`datasheet <https://cdn-shop.adafruit.com/datasheets/SSD1351-Revision+1.3.pdf>`__,
`Adafruit 128x128 <https://www.adafruit.com/product/1431>`__,
`Adafruit 128x96 <https://www.adafruit.com/product/1673>`__,
`Waveshare 128x128 <https://www.waveshare.com/product/displays/lcd-oled/lcd-oled-3/1.5inch-rgb-oled-module.htm>`__)
displays with ESPHome. This component is for displays that are connected via the 4-Wire :ref:`SPI bus <spi>`.
.. figure:: images/ssd1351-full.jpg
:align: center
:width: 75.0%
SSD1351 OLED Display
Connect CLK, DIN, CS, DC, and RST to pins on your ESP. For power, the Adafruit modules have two pins; connect
3.3 volts to their ``3v`` **or** connect 5 volts to their ``+`` pin. The Waveshare modules have only a Vcc pin
which should be connected to 3.3 volts only. Connect the GND or G pin to GND.
.. code-block:: yaml
# Example configuration entry
spi:
clk_pin: D5
mosi_pin: D7
display:
- platform: ssd1351_spi
model: "SSD1351 128x128"
reset_pin: D0
cs_pin: D8
dc_pin: D1
lambda: |-
it.print(0, 0, id(font), "Hello World!");
Configuration variables
***********************
- **model** (**Required**): The model of the display. Options are:
- ``SSD1351 128x128`` (SSD1351 with 128 columns and 128 rows)
- ``SSD1351 128x96`` (SSD1351 with 128 columns and 96 rows)
- **reset_pin** (:ref:`Pin Schema <config-pin_schema>`): The RESET pin.
- **cs_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The pin on the ESP that that the CS line is connected to.
The CS line can be connected to GND if this is the only device on the SPI bus.
- **dc_pin** (:ref:`Pin Schema <config-pin_schema>`): The DC pin.
- **lambda** (*Optional*, :ref:`lambda <config-lambda>`): The lambda to use for rendering the content on the display.
See :ref:`display-engine` for more information.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to re-draw the screen. Defaults to ``5s``.
- **pages** (*Optional*, list): Show pages instead of a single lambda. See :ref:`display-pages`.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
Configuration examples
**********************
Add a ``color:`` section to your YAML configuration; please see :ref:`color <config-color>` for more detail on this configuration section.
.. code-block:: yaml
color:
- id: my_red
red: 100%
green: 3%
blue: 5%
...
display:
...
lambda: |-
it.rectangle(0, 0, it.get_width(), it.get_height(), id(my_red));
To bring in color images:
.. code-block:: yaml
image:
- file: "image.jpg"
id: my_image
resize: 120x120
type: RGB
...
display:
...
lambda: |-
it.image(0, 0, id(my_image));
See Also
--------
- :doc:`index`
- :apiref:`ssd1351_base/ssd1351_base.h`
- `SSD1351 Library <https://github.com/adafruit/Adafruit-SSD1351-library>`__ by `Adafruit <https://www.adafruit.com/>`__
- :ghedit:`Edit`

264
components/display/st7789v.rst Normal file
View File

@ -0,0 +1,264 @@
ST7789V TFT LCD
===============
.. seo::
:description: Instructions for setting up ST7789V TFT LCD display drivers.
:image: st7789v-full.jpg
.. _st7789v:
Usage
-----
The ``st7789v`` display platform allows you to use
ST7789V (`datasheet <https://github.com/Xinyuan-LilyGO/TTGO-T-Display>`__,
`Tindie <https://www.tindie.com/products/ttgo/lilygor-ttgo-t-display/>`__)
displays with ESPHome. Note that this component utilizes the 4-Wire :ref:`SPI bus <spi>`; the physical
connection is already in place on the TTGO T-Display module as shown below.
.. figure:: images/st7789v-full.jpg
:align: center
:width: 75.0%
ST7789V TFT LCD on TTGO T-Display module
This module has a USB-C connector with an on-board serial adapter for programming. Simply connect to a
USB-C port to get started! (Depending on your operating system of choice, you might need to install an
appropriate driver.) It is also possible to power the module via the 5V and G (ground) pins along
the edges of the module, or via a battery attached to the connector on the bottom of the board. The
ESP32's UART pins are not brought out to the headers, so the on-board serial adapter must be used for
hardwired programming. (OTA updates are of course possible after ESPHome is initially installed.)
.. code-block:: yaml
# Example minimal configuration entry
spi:
clk_pin: GPIO18
mosi_pin: GPIO19
display:
- platform: st7789v
backlight_pin: GPIO4
cs_pin: GPIO5
dc_pin: GPIO16
reset_pin: GPIO23
lambda: |-
it.print(0, 0, id(font), "Hello World!");
.. warning::
When using the TTGO T-Display module, the GPIO pin numbers above *cannot be changed* as they are
hardwired within the module/PCB.
Configuration variables
***********************
- **backlight_pin** (:ref:`Pin Schema <config-pin_schema>`): The display's backlight pin.
- **cs_pin** (:ref:`Pin Schema <config-pin_schema>`): The CS pin.
- **dc_pin** (:ref:`Pin Schema <config-pin_schema>`): The DC pin.
- **reset_pin** (:ref:`Pin Schema <config-pin_schema>`): The RESET pin.
- **lambda** (*Optional*, :ref:`lambda <config-lambda>`): The lambda to use for rendering the content on the display.
See :ref:`display-engine` for more information.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to re-draw the screen. Defaults to ``5s``.
- **pages** (*Optional*, list): Show pages instead of a single lambda. See :ref:`display-pages`.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
Configuration examples
**********************
As of version 1.15, ESPHome supports color displays. To utilize the color capabilities of this display
module, you'll likely want to add a ``color:`` section to your YAML configuration; please see
:ref:`color <config-color>` for more detail on this configuration section.
To use colors in your lambada:
.. code-block:: yaml
color:
- id: my_red
red: 100%
green: 3%
blue: 5%
...
display:
...
lambda: |-
it.rectangle(0, 0, it.get_width(), it.get_height(), id(my_red);
To bring in color images:
.. code-block:: yaml
image:
- file: "image.jpg"
id: my_image
resize: 200x200
type: RGB565
...
display:
...
lambda: |-
it.image(0, 0, id(my_image));
Complete example
****************
The following is a complete example YAML configuration that does a few things beyond the usual
Wi-Fi, API, and OTA configuration. It defines:
- three fonts (well, one font in three sizes)
- a ``binary_sensor`` that indicates the state of connectivity to the API
- a ``binary_sensor`` for each of the two buttons on the TTGO module
- a ``switch``, allowing control of the backlight from HA
- several colors
- a color image to be shown on the display
- time, for display...on the display
- the SPI configuration for communicating with the display
- the display component itself, for use on the TTGO module
- a lambada which paints the screen as shown in the picture above:
- blue borders, with a sort of "title bar" along the top
- "ESPHome" in yellow in the top left corner
- the API connection status, "Online" in green when connected, "Offline" in red when not
- the time and date, more or less in the center of the display
To use this example, you need only to provide the font file, "Helvetica.ttf" (or update it to
a font of your choosing) and an image file, "image.png" (it may also be a ".jpg"). Place these
into the same directory as the YAML configuration file itself. Comment/Uncomment/Modify the
appropriate lines of C code in the lambada to hide or show the image or text as you wish.
.. code-block:: yaml
esphome:
name: esp_tdisplay
platform: ESP32
board: featheresp32
wifi:
ssid: "ssid"
password: "password"
# Enable fallback hotspot (captive portal) in case wifi connection fails
ap:
ssid: "esp_tdisplay"
password: "some_password"
captive_portal:
# Enable logging
logger:
# Enable Home Assistant API
api:
password: "some_api_password"
ota:
password: "some_ota_password"
color:
- id: my_red
red: 100%
green: 0%
blue: 0%
- id: my_yellow
red: 100%
green: 100%
blue: 0%
- id: my_green
red: 0%
green: 100%
blue: 0%
- id: my_blue
red: 0%
green: 0%
blue: 100%
- id: my_gray
red: 50%
green: 50%
blue: 50%
font:
- file: "Helvetica.ttf"
id: helvetica_48
size: 48
- file: "Helvetica.ttf"
id: helvetica_24
size: 24
- file: "Helvetica.ttf"
id: helvetica_12
size: 12
binary_sensor:
- platform: status
name: "Node Status"
id: system_status
- platform: gpio
pin:
number: GPIO0
inverted: true
name: "T-Display Button Input 0"
id: tdisplay_button_input_0
- platform: gpio
pin:
number: GPIO35
inverted: true
name: "T-Display Button Input 1"
id: tdisplay_button_input_1
# We can still control the backlight independently
switch:
- platform: gpio
pin: GPIO4
name: "Backlight"
id: backlight
image:
- file: "image.png"
id: my_image
resize: 200x200
type: RGB565
time:
- platform: homeassistant
id: esptime
spi:
clk_pin: GPIO18
mosi_pin: GPIO19
display:
- platform: st7789v
backlight_pin: GPIO4
cs_pin: GPIO5
dc_pin: GPIO16
reset_pin: GPIO23
rotation: 270
lambda: |-
it.rectangle(0, 0, it.get_width(), it.get_height(), id(my_blue));
it.rectangle(0, 20, it.get_width(), it.get_height(), id(my_blue)); // header bar
it.strftime((240 / 2), (140 / 3) * 1 + 5, id(helvetica_24), id(my_gray), TextAlign::CENTER, "%Y-%m-%d", id(esptime).now());
it.strftime((240 / 2), (140 / 3) * 2 + 5, id(helvetica_48), id(my_gray), TextAlign::CENTER, "%H:%M:%S", id(esptime).now());
it.print(5, 5, id(helvetica_12), id(my_yellow), TextAlign::TOP_LEFT, "ESPHome");
// Comment out the above lines to see the image without text overlaid
// it.image(0, 0, id(my_image));
if (id(system_status).state) {
it.print(235, 5, id(helvetica_12), id(my_green), TextAlign::TOP_RIGHT, "Online");
}
else {
it.print(235, 5, id(helvetica_12), id(my_red), TextAlign::TOP_RIGHT, "Offline");
}
See Also
--------
- :doc:`index`
- :apiref:`st7789v_base/st7789v_base.h`
- :ghedit:`Edit`

130
components/display/tm1637.rst Normal file
View File

@ -0,0 +1,130 @@
TM1637 7-Segment Display
========================
.. seo::
:description: Instructions for setting up TM1637 7-segment displays.
:image: tm1637.jpg
The ``tm1637`` display platform allows you to use the popular TM1637 7-segment display drivers with ESPHome.
.. figure:: images/tm1637-full.jpg
:align: center
:width: 75.0%
TM1637 7-Segment Display.
The module can be powered with 5v or with 3.3v too. To display the colon punctiation use the
``.`` in the colon place. (See clock example below)
.. code-block:: yaml
# Example configuration entry
display:
platform: tm1637
id: tm1637_display
clk_pin: D6
dio_pin: D5
lambda: |-
it.print("0123");
Configuration variables:
------------------------
- **clk_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The pin you have the CLK line hooked up to.
- **dio_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The pin you have the DIO line hooked up to.
- **intensity** (*Optional*, integer): The intensity with which the TM1637 should drive the outputs. Range is from
0 (least intense) to 7 (the default).
- **lambda** (*Optional*, :ref:`lambda <config-lambda>`): The lambda to use for rendering the content on the TM1637.
See :ref:`display-tm1637_lambda` for more information.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to re-draw the screen. Defaults to ``1s``.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
.. _display-tm1637_lambda:
Rendering Lambda
----------------
The TM1637 has a similar API to the fully fledged :ref:`display-engine`, but it's only a subset as the TM1637
7-segment displays don't have a concept of individual pixels. In the lambda you're passed a variable called ``it``
as with all other displays. In this case however, ``it`` is an TM1637 instance (see API Reference).
The most basic operation with the TM1637 is wiring a simple number to the screen as in the configuration example
at the top of this page. But even though you're passing in a string (here ``"0123"``), ESPHome converts it
into a representation that the TM1637 can understand: The exact pixels that should be turned on. And of course,
not all characters can be represented. You can see a full list of characters :ref:`at the MAX7219 docs <display-max7219_characters>`.
Each of the three methods (``print``, ``printf`` and ``strftime``) all optionally take a position argument at the
beginning which can be used to print the text at a specific position. This argument is ``0`` by default which
means the first character of the first TM1637. For example to start the first character of your text at
the end of the TM1637, you would write ``it.print(3, "0");``.
Also note that the ``.`` (dot) character is special because when ESPHome encounters it in the string the dot
segment of the previous position will be enabled.
.. code-block:: yaml
display:
- platform: tm1637
# ...
lambda: |-
// Print 0 at position 0 (left)
it.print("0");
// Result: "0 "
// Print 1 at position 1 (second character)
it.print(1, "1");
// Result: "01 "
// Let's write a sensor value (let's assume it's 42.1)
it.printf(0, "%.1f", id(my_sensor).state);
// Result: "42.1 " (the dot will appear on the "2" segment)
// Overwrite the previous content with blank
it.print(" ");
// Print a right-padded sensor value with 0 digits after the decimal
it.printf("S%3.0f", id(my_sensor).state);
// Result: "S 42"
// Print the current time
it.strftime("%H.%M");
// Result for 10:06:42 -> "10:06" on a display with : and "10.06" on a display with .
Please see :ref:`display-printf` for a quick introduction into the ``printf`` formatting rules and
:ref:`display-strftime` for an introduction into the ``strftime`` time formatting.
Creating a digital clock
************************
The following example creates a typical digital clock with the ``:`` colon flashing every second.
.. code-block:: yaml
time:
- platform: homeassistant
id: homeassistant_time
display:
platform: tm1637
clk_pin: D6
dio_pin: D5
update_interval: 500ms
lambda: |-
static int i = 0;
i++;
if ((i % 2) == 0)
it.strftime("%H.%M", id(homeassistant_time).now());
else
it.strftime("%H%M", id(homeassistant_time).now());
See Also
--------
- :doc:`index`
- :apiref:`tm1637/tm1637.h`
- `TD1637 Library <https://github.com/avishorp/TM1637>`__ by `Avishay <https://github.com/avishorp>`__
- :ghedit:`Edit`

5
components/display/waveshare_epaper.rst
View File

@ -73,10 +73,13 @@ Configuration variables:
- ``1.54in``
- ``2.13in`` (not tested)
- ``2.13in-ttgo`` (T5_V2.3 tested)
- ``2.70in`` (not tested)
- ``2.70in``
- ``2.90in``
- ``2.90in-b`` (B/W rendering only)
- ``4.20in``
- ``5.83in``
- ``7.50in``
- ``7.50inV2``
- **busy_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The BUSY pin. Defaults to not connected.
- **reset_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The RESET pin. Defaults to not connected.

110
components/esp32_ble_tracker.rst
View File

@ -52,6 +52,7 @@ for information on how you can find out the MAC address of a device and track it
resized. Please flash the ESP32 via USB when adding this to your configuration. After that,
you can use OTA updates again.
.. _config-esp32_ble_tracker:
Configuration variables:
------------------------
@ -75,6 +76,115 @@ Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID for this ESP32 BLE Hub.
Automations:
- **on_ble_advertise** (*Optional*, :ref:`Automation <automation>`): An automation to perform
when a Bluetooth advertising is received. See :ref:`esp32_ble_tracker-on_ble_advertise`.
- **on_ble_manufacturer_data_advertise** (*Optional*, :ref:`Automation <automation>`): An automation to
perform when a Bluetooth advertising with manufcaturer data is received. See
:ref:`esp32_ble_tracker-on_ble_manufacturer_data_advertise`.
- **on_ble_service_data_advertise** (*Optional*, :ref:`Automation <automation>`): An automation to
perform when a Bluetooth advertising with service data is received. See
:ref:`esp32_ble_tracker-on_ble_service_data_advertise`.
ESP32 Bluetooth Low Energy Tracker Automation
---------------------------------------------
.. _esp32_ble_tracker-on_ble_advertise:
``on_ble_advertise``
********************
This automation will be triggered when a Bluetooth advertising is received. A variable ``x`` of type
:apiclass:`esp32_ble_tracker::ESPBTDevice` is passed to the automation for use in lambdas.
.. code-block:: yaml
esp32_ble_tracker:
on_ble_advertise:
- mac_address: 11:22:33:44:55:66
then:
- lambda: |-
ESP_LOGD("ble_adv", "New BLE device");
ESP_LOGD("ble_adv", " address: %s", x.address_str().c_str());
ESP_LOGD("ble_adv", " name: %s", x.get_name().c_str());
ESP_LOGD("ble_adv", " Advertised service UUIDs:");
for (auto uuid : x.get_service_uuids()) {
ESP_LOGD("ble_adv", " - %s", uuid.to_string().c_str());
}
ESP_LOGD("ble_adv", " Advertised service data:");
for (auto data : x.get_service_datas()) {
ESP_LOGD("ble_adv", " - %s: (length %i)", data.uuid.to_string().c_str(), data.data.size());
}
ESP_LOGD("ble_adv", " Advertised manufacturer data:");
for (auto data : x.get_manufacturer_datas()) {
ESP_LOGD("ble_adv", " - %s: (length %i)", data.uuid.to_string().c_str(), data.data.size());
}
Configuration variables:
- **mac_address** (*Optional*, MAC Address): The MAC address to filter for this automation.
- See :ref:`Automation <automation>`.
.. _esp32_ble_tracker-on_ble_manufacturer_data_advertise:
``on_ble_manufacturer_data_advertise``
**************************************
This automation will be triggered when a Bluetooth advertising with manufcaturer data is received. A
variable ``x`` of type ``std::vector<uint8_t>`` is passed to the automation for use in lambdas.
.. code-block:: yaml
sensor:
- platform: template
name: "BLE Sensor"
id: ble_sensor
esp32_ble_tracker:
on_ble_manufacturer_data_advertise:
- mac_address: 11:22:33:44:55:66
manufacturer_id: 0590
then:
- lambda: |-
if (x[0] != 0x7b || x[1] != 0x61) return;
int value = x[2] + (x[3] << 8);
id(ble_sensor).publish_state(value);
Configuration variables:
- **mac_address** (*Optional*, MAC Address): The MAC address to filter for this automation.
- **manufacturer_id** (**Required**, string) 16 bit, 32 bit, or 128 bit BLE Manufacturer ID.
- See :ref:`Automation <automation>`.
.. _esp32_ble_tracker-on_ble_service_data_advertise:
``on_ble_on_ble_service_data_advertise``
****************************************
This automation will be triggered when a Bluetooth advertising with service data is received. A
variable ``x`` of type ``std::vector<uint8_t>`` is passed to the automation for use in lambdas.
.. code-block:: yaml
sensor:
- platform: template
name: "BLE Sensor"
id: ble_sensor
esp32_ble_tracker:
on_ble_service_data_advertise:
- mac_address: 11:22:33:44:55:66
service_uuid: 181A
then:
- lambda: 'id(ble_sensor).publish_state(x[0]);'
Configuration variables:
- **mac_address** (*Optional*, MAC Address): The MAC address to filter for this automation.
- **service_uuid** (**Required**, string) 16 bit, 32 bit, or 128 bit BLE Service UUID.
- See :ref:`Automation <automation>`.
See Also
--------

26
components/esp32_camera.rst
View File

@ -258,6 +258,32 @@ Configuration for TTGO T-Journal
pixel_clock_pin: GPIO21
# Image settings
name: My Camera
# ...
Configuration for TTGO-Camera Plus
----------------------------------
.. code-block:: yaml
# Example configuration entry
esp32_camera:
external_clock:
pin: GPIO4
frequency: 20MHz
i2c_pins:
sda: GPIO18
scl: GPIO23
data_pins: [GPIO34, GPIO13, GPIO26, GPIO35, GPIO39, GPIO38, GPIO37, GPIO36]
vsync_pin: GPIO5
href_pin: GPIO27
pixel_clock_pin: GPIO25
vertical_flip: false
horizontal_mirror: false
# Image settings
name: My Camera
# ...

13
components/esphome.rst
View File

@ -97,18 +97,23 @@ option you can tell ESPHome which Arduino framework to use for compiling.
For the ESP8266, you currently can manually pin the Arduino version to these values (see the full
list of Arduino frameworks `here <https://github.com/esp8266/Arduino/releases>`__):
* `2.5.2 <https://github.com/esp8266/Arduino/releases/tag/2.5.2>`__
* `2.6.3 <https://github.com/esp8266/Arduino/releases/tag/2.6.3>`__
* `2.6.2 <https://github.com/esp8266/Arduino/releases/tag/2.6.2>`__
* `2.6.1 <https://github.com/esp8266/Arduino/releases/tag/2.6.1>`__
* `2.5.2 <https://github.com/esp8266/Arduino/releases/tag/2.5.2>`__ (default)
* `2.5.1 <https://github.com/esp8266/Arduino/releases/tag/2.5.1>`__
* `2.5.0 <https://github.com/esp8266/Arduino/releases/tag/2.5.0>`__
* `2.4.2 <https://github.com/esp8266/Arduino/releases/tag/2.4.2>`__ (default)
* `2.4.2 <https://github.com/esp8266/Arduino/releases/tag/2.4.2>`__
* `2.4.1 <https://github.com/esp8266/Arduino/releases/tag/2.4.1>`__
* `2.4.0 <https://github.com/esp8266/Arduino/releases/tag/2.4.0>`__
* `2.3.0 <https://github.com/esp8266/Arduino/releases/tag/2.3.0>`__ (used by Tasmota etc)
* `2.3.0 <https://github.com/esp8266/Arduino/releases/tag/2.3.0>`__
For the ESP32, there are these Arduino `framework versions <https://github.com/espressif/arduino-esp32/releases>`__:
- `1.0.4 <https://github.com/espressif/arduino-esp32/releases/tag/1.0.4>`__ (default)
- `1.0.3 <https://github.com/espressif/arduino-esp32/releases/tag/1.0.3>`__
- `1.0.2 <https://github.com/espressif/arduino-esp32/releases/tag/1.0.2>`__
- `1.0.1 <https://github.com/espressif/arduino-esp32/releases/tag/1.0.1>`__ (default)
- `1.0.1 <https://github.com/espressif/arduino-esp32/releases/tag/1.0.1>`__
- `1.0.0 <https://github.com/espressif/arduino-esp32/releases/tag/1.0.0>`__
.. _esphome-esp8266_restore_from_flash:

82
components/exposure_notifications.rst Normal file
View File

@ -0,0 +1,82 @@
Exposure Notification Listener
==============================
.. seo::
:description: Instructions for setting up exposure notification listeners for ESPHome.
:image: exposure_notifications.png
The ``exposure_notifications`` component uses the :doc:`/components/esp32_ble_tracker` to discover
nearby COVID-19 exposure notification bluetooth messages sent by phones running the
`Google/Apple Exposure Notification service <https://www.google.com/covid19/exposurenotifications/>`__.
.. code-block:: yaml
# Example configuration entry
esp32_ble_tracker:
exposure_notifications:
on_exposure_notification:
then:
- lambda: |
ESP_LOGD("main", "Got notification:");
ESP_LOGD("main", " RPI: %s", hexencode(x.rolling_proximity_identifier).c_str());
ESP_LOGD("main", " RSSI: %d", x.rssi);
Configuration variables:
------------------------
- **on_exposure_notification** (*Optional*, :ref:`Automation <automation>`): An automation
to run when an exposure notification bluetooth message is received.
A variable ``x`` of type :apistruct:`exposure_notifications::ExposureNotification` is passed to the automation.
An exposure notification payload contains:
- Rolling proximity identifier (RPI): A 16-byte long value used to identify a given device in a 10-minute window.
- Associated encrypted metadata (AEM): Additional encrypted metadata, like transmit power.
Because the GAEN framework is designed to prevent tracking an individual, this data can essentially
only be used to check whether a device with enabled exposure notifications is nearby (and to limited degree
also count them).
Indicator of device with exposure notifications
-----------------------------------------------
The following configuration can be used as an indicator whether an exposure-notifications
enabled device is nearby. As long as an exposure notification has been received in the last
minute, the indicator will be on.
.. code-block:: yaml
esp32_ble_tracker:
switch:
- platform: gpio
pin: GPIO22
id: led
script:
- id: start_led
then:
- switch.turn_on: led
- delay: 1min
- switch.turn_off: led
exposure_notifications:
on_exposure_notification:
then:
- lambda: |
ESP_LOGD("main", "Got notification:");
ESP_LOGD("main", " RPI: %s", hexencode(x.rolling_proximity_identifier).c_str());
ESP_LOGD("main", " RSSI: %d", x.rssi);
# Stop existing timer so that turn_off doesn't get called
- script.stop: start_led
- script.execute: start_led
See Also
--------
- :doc:`esp32_ble_tracker`
- :apiref:`exposure_notifications/exposure_notifications.h`
- :ghedit:`Edit`

2
components/fan/binary.rst
View File

@ -27,6 +27,8 @@ Configuration variables:
- **name** (**Required**, string): The name for this fan.
- **oscillation_output** (*Optional*, :ref:`config-id`): The id of the
:ref:`output <output>` to use for the oscillation state of this fan. Default is empty.
- **direction_output** (*Optional*, :ref:`config-id`): The id of the
:ref:`output <output>` to use for the direction state of the fan. Default is empty.
- **id** (*Optional*, :ref:`config-id`): Manually specify
the ID used for code generation.
- All other options from :ref:`Fan Component <config-fan>`.

BIN
components/fan/images/tuyafan.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 29 KiB

2
components/fan/speed.rst
View File

@ -28,6 +28,8 @@ Configuration variables:
- **name** (**Required**, string): The name for this fan.
- **oscillation_output** (*Optional*, :ref:`config-id`): The id of the
:ref:`output <output>` to use for the oscillation state of this fan. Default is empty.
- **direction_output** (*Optional*, :ref:`config-id`): The id of the
:ref:`output <output>` to use for the direction state of the fan. Default is empty.
- **speed** (*Optional*): Set the float values for each speed setting:
- **low** (*Required*, float): Set the value for the low speed

71
components/fan/tuya.rst Normal file
View File

@ -0,0 +1,71 @@
Tuya Fan
========
.. seo::
:description: Instructions for setting up a Tuya ceiling fan switch.
:image: fan.svg
The ``tuya`` fan platform creates a variable speed fan from a
tuya component.
.. figure:: images/tuyafan.jpg
:align: center
:width: 40%
A Tuya based fan controller wall plate.
The Tuya fan requires a :doc:`/components/tuya` to be configured.
Here is an example output for a Tuya fan controller:
.. code-block:: text
[12:39:45][C][tuya:023]: Tuya:
[12:39:45][C][tuya:032]: Datapoint 1: switch (value: ON)
[12:39:45][C][tuya:036]: Datapoint 3: enum (value: 1)
[12:39:45][C][tuya:036]: Datapoint 6: enum (value: 0)
[12:39:45][C][tuya:034]: Datapoint 7: int value (value: 0)
[12:39:45][C][tuya:032]: Datapoint 9: switch (value: OFF)
[12:39:45][C][tuya:046]: Product: '{"p":"hqq73kftvzh8c92u","v":"1.0.0","m":0}'
On this controller, the data points are:
- 1 represents the fan on/off state.
- 3 represents the speed setting.
- 9 represents the additional light switch. (use the :doc:`/components/light/tuya` component to control this)
- 6 & 7 are unknown and don't seem to affect the state.
Based on this, you can create the fan as follows:
.. code-block:: yaml
# Create a fan
fan:
- platform: "tuya"
name: "MyFan"
switch_datapoint: 1
speed_datapoint: 3
Configuration variables:
------------------------
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **name** (**Required**, string): The name of the fan.
- **speed_datapoint** (**Required**, int): The datapoint id number of the fan speed.
- **switch_datapoint** (**Required**, int): The datapoint id number of the fan switch.
- **oscillation_datapoint** (**Optional**, int): The datapoint id number of the oscillation
switch. Probably not supported on any Tuya controllers currently, but it's there if need be.
- All other options from :ref:`Fan <config-fan>`.
.. note::
The MCU on the Tuya dimmer handles the LEDs and they dont seem to be controllable
over the serial bus.
See Also
--------
- :doc:`/components/tuya`
- :doc:`/components/fan/index`
- :apiref:`tuya/fan/tuya_fan.h`
- :ghedit:`Edit`

184
components/http_request.rst Normal file
View File

@ -0,0 +1,184 @@
HTTP Request
============
.. seo::
:description: Instructions for setting up HTTP Requests in ESPHome
:image: connection.png
:keywords: http, request
The ``http_request`` component lets you make HTTP/HTTPS requests.
.. note::
This component works only with :ref:`arduino framework <esphome-arduino_version>` 2.5.0 or newer.
First, you need to setup a component:
.. code-block:: yaml
# Example configuration entry
http_request:
useragent: esphome/device
timeout: 10s
Configuration variables:
------------------------
- **useragent** (*Optional*, string): User-Agent header for requests. Defaults to ``ESPHome``.
- **timeout** (*Optional*, :ref:`time <config-time>`): Timeout for request. Defaults to ``5s``.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
HTTP Request Actions
--------------------
Component support a number of :ref:`actions <config-action>` that can be used to send requests.
.. _http_request-get_action:
``http_request.get`` Action
***************************
This :ref:`action <config-action>` sends a GET request.
.. code-block:: yaml
on_...:
- http_request.get:
url: https://esphome.io
headers:
Content-Type: application/json
verify_ssl: false
# Short form
- http_request.get: https://esphome.io
Configuration variables:
- **url** (**Required**, string, :ref:`templatable <config-templatable>`): URL to send request.
- **headers** (*Optional*, mapping): Map of HTTP headers. Values are :ref:`templatable <config-templatable>`.
- **verify_ssl** (*Optional*, boolean): Verify the SSL certificate of the endpoint. Defaults to ``true``.
.. note::
Currently ESPHome **can't verify the SSL certificate** of the endpoint.
Set ``verify_ssl: false`` to make HTTPS request.
.. _http_request-post_action:
``http_request.post`` Action
****************************
This :ref:`action <config-action>` sends a POST request.
.. code-block:: yaml
on_...:
- http_request.post:
url: https://esphome.io
headers:
Content-Type: application/json
json:
key: value
verify_ssl: false
# Short form
- http_request.post: https://esphome.io
Configuration variables:
- **body** (*Optional*, string, :ref:`templatable <config-templatable>`): A HTTP body string to send with request.
- **json** (*Optional*, mapping): A HTTP body in JSON format. Values are :ref:`templatable <config-templatable>`. See :ref:`http_request-examples`.
- All other options from :ref:`http_request-get_action`.
.. _http_request-send_action:
``http_request.send`` Action
****************************
This :ref:`action <config-action>` sends a request.
.. code-block:: yaml
on_...:
- http_request.send:
method: PUT
url: https://esphome.io
headers:
Content-Type: application/json
body: "Some data"
verify_ssl: false
Configuration variables:
- **method** (**Required**, string): HTTP method to use (``GET``, ``POST``, ``PUT``, ``DELETE``, ``PATCH``).
- All other options from :ref:`http_request-post_action`.
.. _http_request-examples:
Examples
--------
Templatable values
******************
.. code-block:: yaml
on_...:
- http_request.post:
url: !lambda |-
return ((std::string) "https://esphome.io?state=" + id(my_sensor).state).c_str();
headers:
X-Custom-Header: !lambda |-
return ((std::string) "Value-" + id(my_sensor).state).c_str();
body: !lambda |-
return id(my_sensor).state;
Body in JSON format (syntax 1)
******************************
**Note:** all values of the map should be a strings.
It's impossible to send ``boolean`` or ``numbers`` with this syntax.
.. code-block:: yaml
on_...:
- http_request.post:
url: https://esphome.io
verify_ssl: false
json:
key: !lambda |-
return id(my_sensor).state;
greeting: "Hello World"
# Will send:
# {"key": "42.0", "greeting": "Hello World"}
Body in JSON format (syntax 2)
******************************
**Note:** use this syntax to send ``boolean`` or ``numbers`` in JSON.
The JSON message will be constructed using the `ArduinoJson <https://github.com/bblanchon/ArduinoJson>`__ library.
In the ``json`` option you have access to a ``root`` object which will represents the base object
of the JSON message. You can assign values to keys by using the ``root["KEY_NAME"] = VALUE;`` syntax
as seen below.
.. code-block:: yaml
on_...:
- http_request.post:
url: https://esphome.io
verify_ssl: false
json: |-
root["key"] = id(my_sensor).state;
root["greeting"] = "Hello World";
# Will send:
# {"key": 42.0, "greeting": "Hello World"}
See Also
--------
- :doc:`index`
- :apiref:`http_request/http_request.h`
- :ghedit:`Edit`

BIN
components/images/buzzer.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 37 KiB

BIN
components/images/rf_bridge-full.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 46 KiB

BIN
components/images/sn74hc595-full.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 128 KiB

BIN
components/images/tm1651-battery-display.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 115 KiB

2
components/light/cwww.rst
View File

@ -19,6 +19,7 @@ channels will be mixed using the color temperature configuration options.
warm_white: output_component2
cold_white_color_temperature: 6536 K
warm_white_color_temperature: 2000 K
constant_brightness: true
Configuration variables:
------------------------
@ -30,6 +31,7 @@ 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.
- **constant_brightness** (*Optional*, boolean): When enabled, this will keep the overall brightness of the cold and warm white channels constant by limiting the combined output to 100% of a single channel. This reduces the possible overall brightness but is necessary for some power supplies that are not able to run both channels at full brightness at once. Defaults to ``false``.
- **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.
- All other options from :ref:`Light <config-light>`.

183
components/light/index.rst
View File

@ -41,6 +41,11 @@ Configuration variables:
- ``ALWAYS_OFF`` - Always initialize the light as OFF on bootup.
- ``ALWAYS_ON`` - Always initialize the light as ON on bootup.
- **on_turn_on** (*Optional*, :ref:`Action <config-action>`): An automation to perform
when the light is turned on. See :ref:`light-on_turn_on_off_trigger`.
- **on_turn_off** (*Optional*, :ref:`Action <config-action>`): An automation to perform
when the light is turned off. See :ref:`light-on_turn_on_off_trigger`.
Additional Configuration variables for addressable lights:
- **color_correct** (*Optional*, list of float): Apply a color correction to each color channel.
@ -59,7 +64,7 @@ Advanced options:
.. _light-toggle_action:
``light.toggle`` Action
-----------------------
***********************
This action toggles a light with the given ID when executed.
@ -91,7 +96,7 @@ Configuration options:
.. _light-turn_on_action:
``light.turn_on`` Action
------------------------
************************
This action turns a light with the given ID on when executed.
@ -161,7 +166,7 @@ Configuration options:
.. _light-turn_off_action:
``light.turn_off`` Action
-------------------------
*************************
This action turns a light with the given ID off when executed.
@ -196,7 +201,7 @@ Configuration options:
.. _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.
@ -219,7 +224,7 @@ Configuration options:
.. _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.
@ -264,7 +269,7 @@ Configuration options:
.. _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.
@ -315,6 +320,25 @@ that the light is completely OFF, and ON means that the light is emitting at lea
# Same syntax for is_off
light.is_on: my_light
.. _light-on_turn_on_off_trigger:
``light.on_turn_on`` / ``light.on_turn_off`` Trigger
****************************************************
This trigger is activated each time the light is turned on or off. It is consistent
with the behavior of the ``light.is_on`` and ``light.is_off`` condition above.
.. code-block:: yaml
light:
- platform: binary # or any other platform
# ...
on_turn_on:
- logger.log: "Light Turned On!"
on_turn_off:
- logger.log: "Light Turned Off!"
.. _light-effects:
Light Effects
@ -691,8 +715,11 @@ 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 :apiclass:`AddressableLight <light::AddressableLight>`
instance (see API reference for more info).
Available variables in the lambda:
- **it** - :apiclass:`AddressableLight <light::AddressableLight>` instance (see API reference for more info).
- **current_color** - :apiclass:`ESPColor ` <light::ESPColor>` instance (see API reference for more info).
- **initial_run** - A bool which is true on the first execution of the lambda. Useful to reset static variables when restarting a effect.
.. code-block:: yaml
@ -720,6 +747,33 @@ instance (see API reference for more info).
it.range(0, 50) = ESPColor::BLACK;
it.all().fade_to_black(10);
.. code-block:: yaml
light:
- platform: ...
effects:
- addressable_lambda:
name: "My Custom Effect"
update_interval: 16ms
lambda: |-
// Static variables keep their value even when
// stopping and starting the effect again
static uint16_t progress = 0;
// normal variables lost their value after each
// execution - basically after each update_interval
uint16_t changes = 0;
// To reset static when stopping and starting the effect
// again you can use the initial_run variables
if (initial_run) {
progress = 0;
it.all() = ESPColor::BLACK;
// optionally do a return so nothing happens until the next update_interval
return;
}
Examples of this API can be found here:
https://github.com/esphome/esphome/blob/dev/esphome/components/light/addressable_light_effect.h
(the built-in addressable light effects).
@ -763,6 +817,119 @@ Configuration variables:
- **sequence** (*Optional*, :ref:`Action <config-action>`): The actions to perform in sequence
until the effect is stopped.
E1.31
*****
This effect enables controlling addressable lights using UDP-based
E1.31_ protocol.
JINX_ can be used to control E1.31_ enabled ESPHome.
.. code-block:: yaml
e131:
method: multicast # default: register E1.31 to Multicast group
light:
- platform: neopixelbus
num_leds: 189
effects:
- e131:
universe: 1
channels: RGB
Configuration variables:
- **method** (*Optional*): Listening method, one of ``multicast`` or ``unicast``. Defaults to ``multicast``.
- **universe** (*Required*, integer): The value of universe, between 1 to 512.
- **channels** (*Optional*): The type of data. This is used to specify if it is a ``MONO``,
``RGB`` or ``RGBW`` light and in which order the colors are. Defaults to ``RGB``.
There are three modes of operation:
- `MONO`: this supports 1 channel per LED (luminance), up-to 512 LEDs per universe
- `RGB`: this supports 3 channels per LED (RGB), up-to 170 LEDs (3*170 = 510 bytes) per universe
- `RGBW`: this supports 4 channels per LED (RGBW), up-to 128 LEDs (4*128 = 512 bytes) per universe
If there's more LEDs than allowed per-universe, additional universe will be used.
In the above example of 189 LEDs, first 170 LEDs will be assigned to 1 universe,
the rest of 19 LEDs will be automatically assigned to 2 universe.
It is possible to enable multiple light platforms to listen to the same universe concurrently,
allowing to replicate the behaviour on multiple strips.
.. _E1.31: https://www.doityourselfchristmas.com/wiki/index.php?title=E1.31_(Streaming-ACN)_Protocol
.. _JINX: http://www.live-leds.de/jinx-v1-3-with-resizable-mainwindow-real-dmx-and-sacne1-31/
Adalight
********
This effect enables controlling addressable lights using UART-based
Adalight_ protocol, allowing to create realtime ambient lighting effects.
Prismatik_ can be used to control addressable lights via Adalight_ protocol
on ESPHome.
.. code-block:: yaml
# Example configuration entry
# Disable logging over USB
logger:
baud_rate: 0
# Adalight requires higher RX buffer size
# to operate without flickering
uart:
rx_buffer_size: 1024
adalight:
light:
- platform: neopixelbus
...
effects:
- adalight:
# uart_id: additional_uart
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.
.. _Adalight: https://learn.adafruit.com/adalight-diy-ambient-tv-lighting
.. _Prismatik: https://github.com/psieg/Lightpack
WLED
****
This effect enables controlling addressable lights using UDP-based
`UDP Realtime Control`_ protocol used by WLED_, allowing to create realtime ambient
lighting effects.
Prismatik_ can be used to control addressable lights over network on ESPHome.
.. code-block:: yaml
wled:
light:
- platform: neopixelbus
...
effects:
- wled:
# port: 21324
Configuration variables:
- **port** (*Optional*, integer): The port to run the UDP server on. Defaults to ``21324``.
Currently the following realtime protocols are supported:
WARLS, DRGB, DRGBW, DNRGB and WLED Notifier.
.. _UDP Realtime Control: https://github.com/Aircoookie/WLED/wiki/UDP-Realtime-Control
.. _WLED: https://github.com/Aircoookie/WLED/wiki/UDP-Realtime-Control
.. _Prismatik: https://github.com/psieg/Lightpack
See Also
--------

1
components/light/neopixelbus.rst
View File

@ -65,6 +65,7 @@ Configuration variables:
- ``BIT_BANG`` (can flicker a bit)
- **num_leds** (**Required**, int): The number of LEDs attached.
- **invert** (*Optional*, boolean): Invert data output, for use with n-type transistor. Defaults to ``no``.
**Pin Options:** Some chipsets have two data pins to connect, others only have one.
If you have one line, only specify ``pin``, otherwise specify both ``clock_pin`` and ``data_pin``.

16
components/light/rgbw.rst
View File

@ -52,9 +52,25 @@ Configuration variables:
- **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.
- **effects** (*Optional*, list): A list of :ref:`light effects <light-effects>` to use for this light.
- **color_interlock** (*Optional*, boolean): When enabled, this will prevent white leds being on at the same
time as RGB leds. See :ref:`rgbw_color_interlock` for more information. Defaults to ``false``.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- All other options from :ref:`Light <config-light>`.
.. _rgbw_color_interlock:
Color Interlock
***************
With some LED bulbs, setting the RGB channels to maximum whilst wanting a white light will have a undesired
hue affect. Additionally, the brightness command may not work as expected depending upon configuration,
leaving users to adjust the white component level separately. For these cases a new configration variable
has been added: color_interlock.
Setting this variable to True will turn off RGB leds when white value is above 0 (or if they are to 255,255,255)
and turn off white leds if color is not set to 255,255,255. This also allows the brightness parameter to
control the intensity of the white leds.
See Also
--------

20
components/light/rgbww.rst
View File

@ -57,12 +57,20 @@ 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.
- **cold_white** (**Required**, :ref:`config-id`): The id of the float :ref:`output` to use for the cold white channel.
- **warm_white** (**Required**, :ref:`config-id`): The id of the float :ref:`output` to use for the warm white channel.
- **cold_white_color_temperature** (**Required**, float): The color temperate (in `mireds <https://en.wikipedia.org/wiki/Mired>`__ or Kelvin)
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.
- **cold_white** (**Required**, :ref:`config-id`): The id of the float :ref:`output` to use for the cold
white channel.
- **warm_white** (**Required**, :ref:`config-id`): The id of the float :ref:`output` to use for the warm
white channel.
- **cold_white_color_temperature** (**Required**, float): The color temperate (in
`mireds <https://en.wikipedia.org/wiki/Mired>`__ or Kelvin) 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.
- **constant_brightness** (*Optional*, boolean): When enabled, this will keep the overall brightness of the
cold and warm white channels constant by limiting the combined output to 100% of a single channel. This
reduces the possible overall brightness but is necessary for some power supplies that are not able to run
both channels at full brightness at once. Defaults to ``false``.
- **color_interlock** (*Optional*, boolean): When enabled, this will prevent white leds being on at the same
time as RGB leds. See :ref:`rgbw_color_interlock` for more information. Defaults to ``false``.
- **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.
- All other options from :ref:`Light <config-light>`.

6
components/light/tuya.rst
View File

@ -16,7 +16,7 @@ tuya serial component.
The dimmer switch I got would hang if the logger was configured to use the serial port
which meant it was bricked until I cut it open.
There are two components, the Tuya bus and the dimmer that uses it. The ``tuya``
There are two components, the Tuya bus and the dimmer that uses it. The :doc:`/components/tuya`
component requires a :ref:`UART bus <uart>` to be configured. Put the ``tuya`` component in
the config and it will list the possible devices for you in the config log.
@ -72,7 +72,7 @@ Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **name** (**Required**, string): The name of the light.
- **dimmer_datapoint** (**Required**, int): The datapoint id number of the dimmer value.
- **dimmer_datapoint** (*Optional*, int): The datapoint id number of the dimmer value.
- **switch_datapoint** (*Optional*, int): The datapoint id number of the power switch. My dimmer
required this to be able to turn the light on and off. Without this you would only be able to
change the brightness and would have to toggle the light using the physical buttons.
@ -81,6 +81,7 @@ Configuration variables:
- **max_value** (*Optional*, int, default 255): The highest dimmer value allowed. My dimmer had a
maximum of 255 which seems like it would be the typical value.
- All other options from :ref:`Light <config-light>`.
- At least one of *dimmer_datapoint* or *switch_datapoint* must be provided.
.. note::
@ -91,6 +92,7 @@ Configuration variables:
See Also
--------
- :doc:`/components/tuya`
- :doc:`/components/light/index`
- :apiref:`tuya/light/tuya_light.h`
- :ghedit:`Edit`

29
components/logger.rst
View File

@ -159,6 +159,35 @@ Configuration options:
- **tag** (*Optional*, string): The tag (seen in front of the message in the logs) to print the message
with. Defaults to ``main``.
Logger Automation
-----------------
.. _logger-on_message:
``on_message``
**************
This automation will be triggered when a new message is added to the log.
In :ref:`lambdas <config-lambda>` you can get the message, log level and tag from the trigger
using ``message`` (``const char *``), ``level`` (``int``) and ``tag`` (``const char *``).
.. code-block:: yaml
logger:
# ...
on_message:
level: ERROR
then:
- mqtt.publish:
topic: some/topic
payload: !lambda |-
return "Triggered on_message with level " + std::to_string(level) + ", tag " + tag + " and message " + message;
.. note::
Logging will not work in the ``on_message`` trigger. You can't use the :ref:`logger.log <logger-log_action>` action
and the ``ESP_LOGx`` logging macros in this automation.
See Also
--------

165
components/mcp230xx.rst
View File

@ -2,12 +2,113 @@ MCP230xx I/O Expander
=====================
.. seo::
:description: Instructions for setting up MCP23017 or MCP23008 digital port expanders in ESPHome.
:description: Instructions for setting up MCP23008, MCP23016 or MCP23017 digital port expander in ESPHome.
:image: mcp230xx.png
The Microchip MCP230xx series of general purpose, parallel I/O expansion for I²C
bus applications come in two different variants: the 8-bit MCP23008 and the 16-bit
MCP23017, which provide 8 and 16 additional GPIO pins, respectively.
The Microchip MCP230xx series of general purpose, parallel I/O expansion for I²C bus applications.
**Supported Variants :**
- :ref:`mcp23008-label`
- :ref:`mcp23016-label`
- :ref:`mcp23017-label`
.. _mcp23008-label:
MCP23008
--------
The MCP23008 component (`datasheet <http://ww1.microchip.com/downloads/en/devicedoc/21919e.pdf>`__,
`Adafruit <https://www.adafruit.com/product/593>`__) has 8 GPIOs that can be configured independently.
.. code-block:: yaml
# Example configuration entry
mcp23008:
- id: 'mcp23008_hub'
address: 0x20
# Individual outputs
switch:
- platform: gpio
name: "MCP23008 Pin #0"
pin:
mcp23008: mcp23008_hub
# Use pin number 0
number: 0
# One of INPUT, INPUT_PULLUP or OUTPUT
mode: INPUT_PULLUP
inverted: False
# Individual inputs
binary_sensor:
- platform: gpio
name: "MCP23008 Pin #1"
pin:
mcp23008: mcp23008_hub
# Use pin number 1
number: 1
# One of INPUT or INPUT_PULLUP
mode: INPUT
inverted: False
Configuration variables:
~~~~~~~~~~~~~~~~~~~~~~~~
- **id** (**Required**, :ref:`config-id`): The id to use for this MCP23008 component.
- **address** (*Optional*, int): The I²C address of the driver.
Defaults to ``0x20``.
.. _mcp23016-label:
MCP23016
--------
The MCP23016 component (`datasheet <http://ww1.microchip.com/downloads/en/devicedoc/20090c.pdf>`__)
has 16 GPIOs and can be configured the same way than the other variants.
.. note::
The 'INPUT_PULLUP' mode is not supported on this device.
.. code-block:: yaml
# Example configuration entry
mcp23016:
- id: 'mcp23016_hub'
address: 0x20
# Individual outputs
switch:
- platform: gpio
name: "MCP23016 Pin #0"
pin:
mcp23016: mcp23016_hub
# Use pin number 0
number: 0
mode: OUTPUT
inverted: False
# Individual inputs
binary_sensor:
- platform: gpio
name: "MCP23016 Pin #1"
pin:
mcp23016: mcp23016_hub
# Use pin number 1
number: 1
mode: INPUT
inverted: False
Configuration variables:
~~~~~~~~~~~~~~~~~~~~~~~~
- **id** (**Required**, :ref:`config-id`): The id to use for this MCP23016 component.
- **address** (*Optional*, int): The I²C address of the driver.
Defaults to ``0x20``.
.. _mcp23017-label:
MCP23017
--------
@ -37,52 +138,27 @@ binary sensor or GPIO switch.
mcp23017: mcp23017_hub
# Use pin number 0
number: 0
# One of INPUT, INPUT_PULLUP or OUTPUT
mode: OUTPUT
inverted: False
# Individual inputs
binary_sensor:
- platform: gpio
name: "MCP23017 Pin #1"
pin:
mcp23017: mcp23017_hub
# Use pin number 1
number: 1
# One of INPUT or INPUT_PULLUP
mode: INPUT_PULLUP
inverted: False
Configuration variables:
~~~~~~~~~~~~~~~~~~~~~~~~
- **id** (**Required**, :ref:`config-id`): The id to use for this MCP23017 component.
- **address** (*Optional*, int): The I²C address of the driver.
Defaults to ``0x21``.
MCP23008
--------
The configuration is essentially the same with the MCP23017 component
(`datasheet <http://ww1.microchip.com/downloads/en/devicedoc/21919e.pdf>`__,
`Adafruit <https://www.adafruit.com/product/593>`__):
.. code-block:: yaml
# Example configuration entry
mcp23008:
- id: 'mcp23008_hub'
address: 0x20
# Individual outputs
switch:
- platform: gpio
name: "MCP23008 Pin #0"
pin:
mcp23008: mcp23008_hub
# Use pin number 0
number: 0
# One of INPUT, INPUT_PULLUP or OUTPUT
mode: INPUT_PULLUP
inverted: False
Configuration variables:
~~~~~~~~~~~~~~~~~~~~~~~~
- **id** (**Required**, :ref:`config-id`): The id to use for this MCP23008 component.
- **address** (*Optional*, int): The I²C address of the driver.
Defaults to ``0x21``.
Defaults to ``0x20``.
See Also
@ -91,6 +167,7 @@ See Also
- :ref:`i2c`
- :doc:`switch/gpio`
- :doc:`binary_sensor/gpio`
- :apiref:`mcp23017/mcp23017.h`
- :apiref:`API Reference (MCP23008) <mcp23008/mcp23008.h>`
- :apiref:`API Reference (MCP23016) <mcp23016/mcp23016.h>`
- :apiref:`API Reference (MCP23017) <mcp23017/mcp23017.h>`
- :ghedit:`Edit`

74
components/mcp3008.rst Normal file
View File

@ -0,0 +1,74 @@
MCP3008 I/O Expander
====================
.. seo::
:description: Instructions for setting up MCP3008 10 Bit Analog to Digital Converter in ESPHome.
:image: mcp3008.png
.. note::
This page is incomplete and could some work. If you want to contribute, please read the
:doc:`contributing guide </guides/contributing>`. This page is missing:
- An image for the front page.
- Formal documentation of the mcp3008 sensor entry (parent, update_interval, number, etc.)
- See Dallas sensor for reference model
The Microchip Technology Inc. MCP3008
devices are successive approximation 10-bit Analogto-Digital (A/D) converters with on-board sample and
hold circuitry. Each pin will respond with a 0-1023 result depending on the voltage it is reading
MCP3008
-------
The MCP3008 component allows you to use MCP3008 8-Channel 10-Bit A/D Converter
(`datasheet <http://ww1.microchip.com/downloads/en/DeviceDoc/21295d.pdf>`__,
`Adafruit <https://www.adafruit.com/product/856>`__) in ESPHome.
It uses the :ref:`SPI Bus <spi>` for communication.
Once configured, you can use any of the 8 pins as
sensors for your projects.
.. code-block:: yaml
# Example configuration entry
mcp3008:
cs_pin: D8
# Example config of sensors.
# This is a NTCB3950 10K thermocoupler attached to pin 0
# of the MCP3008 with a 10K resistor as a voltage divider.
# See `resistance` and `ntc` platorms for other options
sensor:
- platform: mcp3008 # Attached to pin 0 of the MCP3008.
# The result will be a reading from 0-1023
update_interval: 1s
id: freezer_temp_source
number: 0 # pin number
- platform: resistance
id: freezer_resistance_sensor
sensor: freezer_temp_source
configuration: DOWNSTREAM
resistor: 10kOhm
- platform: ntc
id: freezer_temp
sensor: freezer_resistance_sensor
calibration:
b_constant: 3950
reference_temperature: 25°C
reference_resistance: 10kOhm
name: Freezer Temperature
Configuration variables:
~~~~~~~~~~~~~~~~~~~~~~~~
- **id** (**Required**, :ref:`config-id`): The id to use for this MCP3008 component.
- **cs_pin** (**Required**, int): The SPI cable select pin to use
See Also
--------
- :ref:`spi`
- :apiref:`mcp3008/mcp3008.h`
- :ghedit:`Edit`

81
components/output/ac_dimmer.rst Normal file
View File

@ -0,0 +1,81 @@
AC Dimmer Component
===================
.. seo::
:description: Instructions for setting up AC Dimmer integration in ESPHome.
:image: ac_dimmer.svg
.. warning::
This component has not been fully tested yet, if you are testing this component
please share your experience with the dimmer hardware and light model and
configuration here https://github.com/esphome/feature-requests/issues/278
Thanks!
The ``ac_dimmer`` component allows you to connect a dimmable light or other load
which supports phase control dimming to your ESPHome project.
There are several already made boards which are compatible with this integration,
for example the `RobotDyn dimmer
<https://robotdyn.com/ac-light-dimmer-module-1-channel-3-3v-5v-logic-ac-50-60hz-220v-110v.html>`__.
.. figure:: images/robotdyn_dimmer.jpg
:align: center
:width: 50.0%
RobotDyn Module. Image by `RobotDyn`_
.. _RobotDyn: https://robotdyn.com/ac-light-dimmer-module-1-channel-3-3v-5v-logic-ac-50-60hz-220v-110v.html
.. code-block:: yaml
# Example configuration entry
output:
- platform: ac_dimmer
id: dimmer1
gate_pin: D7
zero_cross_pin:
number: D6
mode: INPUT
inverted: yes
light:
- platform: monochromatic
output: dimmer1
name: Dimmerized Light
Configuration variables:
------------------------
- **gate_pin** (**Required**, :ref:`config-pin`): The pin used to control the Triac or
Mosfet.
- **zero_cross_pin** (**Required**, :ref:`config-pin`): The pin used to sense the AC
Zero cross event, you can have several dimmers controlled with the same zero cross
detector, in such case duplicate the ``zero_cross_pin`` config on each output.
- **method** (*Optional*): Set the method for dimming, can be:
- ``leading pulse`` (default): a short pulse to trigger a triac.
- ``leading``: gate pin driven high until the zero cross is detected
- ``trailing``: gate pin driven high from zero cross until dim period, this method
is suitable for mosfet dimmers only.
- **init_with_half_cycle** (*Optional*, boolean): Will send the first full half AC cycle
Try to use this for dimmable LED lights, it might help turning on at low brightness
levels. On Halogen lamps it might show at initial flicker. Defaults to ``False``.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- All other options from :ref:`Output <config-output>`.
Dimming lights with phase control can be tricky, the minimum level your light turns on
might be different from other lights, also the perceived light level might not correlate
to the percentage output set to the light, to try to minimize these behaviors you can
tweak the values ``min_power`` from this output component and also ``gamma_correct`` from
the monochromatic light.
See Also
--------
- :doc:`/components/output/index`
- :doc:`/components/light/monochromatic`
- :apiref:`ac_dimmer/ac_dimmer.h`
- :ghedit:`Edit`

62
components/output/esp32_dac.rst Normal file
View File

@ -0,0 +1,62 @@
ESP32 DAC
=========
.. seo::
:description: Instructions for setting up ESP32 digital-to-analog converter.
:image: dac.svg
The ESP32 DAC platform allows you to output analog voltages using the 8-bit digital-to-analog
converter of the ESP32. Unlike the :doc:`/components/output/ledc`, which can simulate an analog
signal by using a fast switching frequency, the hardware DAC can output a *real* analog signal with
no need for additional filtering.
The DAC spans across two pins, each on its own channel: GPIO25 (Channel 1) and GPIO26 (Channel 2).
The output level is a percentage of the board supply voltage (VDD_A) - generally this will be 3.3V.
.. code-block:: yaml
# Example configuration entry
output:
- platform: esp32_dac
pin: GPIO25
id: dac_output
# Example usage
on_...:
then:
- output.set_level:
id: dac_output
level: 50%
Configuration variables:
------------------------
- **pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The pin to use DAC on. Only GPIO25
and GPIO26 are supported.
- **id** (**Required**, :ref:`config-id`): The id to use for this output component.
- All other options from :ref:`Output <config-output>`.
Use Cases
---------
- Generating a specific (and dynamic) reference voltage for an external sensor or ADC, such as the
:doc:`/components/sensor/ads1115`
- Controlling the bias of a transistor
- Driving a bar graph or large amount of LEDs using an analog-controlled LED driver like the LM3914
(`datasheet <https://www.ti.com/lit/ds/symlink/lm3914.pdf>`__); this can allow you to make tank
level indicators, temperature gauges, and so on from a single output pin
See Also
--------
- :doc:`/components/output/index`
- :doc:`/components/output/ledc`
- :doc:`/components/output/esp8266_pwm`
- :doc:`/components/light/monochromatic`
- :doc:`/components/fan/speed`
- :doc:`/components/power_supply`
- :apiref:`esp32_dac/esp32_dac.h`
- :ghedit:`Edit`

BIN
components/output/images/robotdyn_dimmer.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 47 KiB

49
components/output/slow_pwm.rst Normal file
View File

@ -0,0 +1,49 @@
Slow PWM Output
===============
.. seo::
:description: Instructions for setting up slow pwm outputs for GPIO pins.
:image: pwm.png
Similar to PWM, the Slow PWM Output platform allows you to control GPIO pins by
pulsing them on/off over a longer time period. It could be used to control a
heating element through a relay where a fast PWM update cycle would not be appropriate.
.. note::
This is for **slow** PWM output. For fast-switching PWM outputs (for example,
lights), see these outputs:
- ESP32: :doc:`ledc`
- ESP8266: :doc:`esp8266_pwm`
.. code-block:: yaml
# Example configuration entry
output:
- platform: slow_pwm
pin: D1
id: my_slow_pwm
period: 15s
Configuration variables:
------------------------
- **pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The pin to pulse.
- **id** (**Required**, :ref:`config-id`): The id to use for this output component.
- **period** (**Required**, :ref:`config-time`): The duration of each cycle. (i.e. a 10s
period at 50% duty would result in the pin being turned on for 5s, then off for 5s)
- All other options from :ref:`Output <config-output>`.
See Also
--------
- :doc:`/components/output/index`
- :doc:`/components/output/esp8266_pwm`
- :doc:`/components/output/ledc`
- :doc:`/components/light/monochromatic`
- :doc:`/components/fan/speed`
- :doc:`/components/power_supply`
- :apiref:`slow_pwm/slow_pwm_output.h`
- :ghedit:`Edit`

2
components/pcf8574.rst
View File

@ -42,7 +42,7 @@ not work.
pcf8574: pcf8574_hub
# Use pin number 0
number: 0
# One of INPUT, INPUT_PULLUP or OUTPUT
# One of INPUT or OUTPUT
mode: OUTPUT
inverted: False

46
components/prometheus.rst Normal file
View File

@ -0,0 +1,46 @@
Prometheus Component
====================
.. seo::
:description: Instructions for setting up a prometheus exporter with ESPHome.
:image: prometheus.png
The ``prometheus`` component enables an HTTP endpoint for the
:doc:`web_server` in order to integrate a `Prometheus <https://prometheus.io/>`__ installation.
This can be used to scrape data directly into your Prometheus-based monitoring and alerting-system,
without the need of any other software.
The list of available metrics can be found by directly browsing your node under
``<ip or node_name.local>/metrics``, and may be increased in the future.
.. code-block:: yaml
# Example configuration entry
web_server:
# Activates prometheus /metrics endpoint
prometheus:
Configuration variables:
------------------------
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
.. note::
Example integration into the configuration of your prometheus:
.. code-block:: yaml
scrape_configs:
- job_name: esphome
static_configs:
- targets: [<ip or node_name.local>]
See Also
--------
- :apiref:`prometheus/prometheus_handler.h`
- :ghedit:`Edit`

12
components/remote_receiver.rst
View File

@ -33,6 +33,7 @@ Configuration variables:
- **lg**: Decode and dump LG infrared codes.
- **nec**: Decode and dump NEC infrared codes.
- **panasonic**: Decode and dump Panasonic infrared codes.
- **pioneer**: Decode and dump Pioneer infrared codes.
- **jvc**: Decode and dump JVC infrared codes.
- **samsung**: Decode and dump Samsung infrared codes.
- **sony**: Decode and dump Sony infrared codes.
@ -44,12 +45,14 @@ Configuration variables:
decoding process. Defaults to ``25%``.
- **buffer_size** (*Optional*, int): The size of the internal buffer for storing the remote codes. Defaults to ``10kB``
on the ESP32 and ``1kB`` on the ESP8266.
- **memory_blocks** (*Optional*, int): The number of RMT memory blocks used. Only used on ESP32 platfrom. Defaults to
``3``.
- **filter** (*Optional*, :ref:`time <config-time>`): Filter any pulses that are shorter than this. Useful for removing
glitches from noisy signals. Defaults to ``10us``.
- **idle** (*Optional*, :ref:`time <config-time>`): The amount of time that a signal should remain stable (i.e. not
change) for it to be considered complete. Defaults to ``10ms``.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. Use this if you have
multiple remote transmitters.
multiple remote receivers.
Automations:
@ -77,6 +80,9 @@ Automations:
- **on_panasonic** (*Optional*, :ref:`Automation <automation>`): An automation to perform when a
Panasonic remote code has been decoded. A variable ``x`` of type :apiclass:`remote_base::PanasonicData`
is passed to the automation for use in lambdas.
- **on_pioneer** (*Optional*, :ref:`Automation <automation>`): An automation to perform when a
pioneer remote code has been decoded. A variable ``x`` of type :apiclass:`remote_base::PioneerData`
is passed to the automation for use in lambdas.
.. _remote-receiver-binary-sensor:
@ -149,6 +155,10 @@ Remote code selection (exactly one of these has to be included):
- **address** (**Required**, int): The address to trigger on, see dumper output for more info.
- **command** (**Required**, int): The command.
- **pioneer**: Trigger on a decoded Pioneer remote code with the given data.
- **rc_code_1** (**Required**, int): The remote control code trigger on, see dumper output for more details.
- **rc_switch_raw**: Trigger on a decoded RC Switch raw remote code with the given data.
- **code** (**Required**, string): The remote code to listen for, copy this from the dumper output. To ignore a bit

30
components/remote_transmitter.rst
View File

@ -6,7 +6,6 @@ Remote Transmitter
:image: remote.png
:keywords: Infrared, IR, RF, Remote, TX
The ``remote_transmitter`` component lets you send digital packets to control
devices in your home. For example this includes infrared data or 433MHz RF signals.
@ -225,6 +224,35 @@ Configuration variables:
- **command** (**Required**, int): The command to send.
- All other options from :ref:`remote_transmitter-transmit_action`.
``remote_transmitter.transmit_pioneer`` Action
**********************************************
This :ref:`action <config-action>` sends a Pioneer infrared remote code to a remote transmitter.
.. code-block:: yaml
on_...:
- remote_transmitter.transmit_pioneer:
rc_code_1: 0xA556
rc_code_2: 0xA506
repeat:
times: 2
Configuration variables:
- **rc_code_1** (**Required**, int): The remote control code to send, see dumper output for more details.
- **rc_code_2** (**Optional**, int): The secondary remote control code to send; some codes are sent in
two parts.
- Note that ``repeat`` is still optional, however **Pioneer devices may require that a given code is
received multiple times before they will act on it.** Add this if your device does not respond to
commands sent with this action.
- All other options from :ref:`remote_transmitter-transmit_action`.
At the time this action was created, Pioneer maintained listings of IR codes used for their devices
`here <https://www.pioneerelectronics.com/PUSA/Support/Home-Entertainment-Custom-Install/IR+Codes>`__.
If unable to find your specific device in the documentation, find a device in the same class; the codes
are largely shared among devices within a given class.
``remote_transmitter.transmit_rc_switch_raw`` Action
****************************************************

198
components/rf_bridge.rst Normal file
View File

@ -0,0 +1,198 @@
RF Bridge Component
===================
.. seo::
:description: Instructions for setting up the RF Bridge in ESPHome.
:image: rf_bridge.jpg
:keywords: RF Bridge
The ``RF Bridge`` Component provides the ability to send and receive 433MHz remote codes without hardware
hacking the circuit board to bypass the ``efm8bb1`` MCU. This component implements the communcation protocol
that the original ``efm8bb1`` firmware implements. The device is connected via the
:doc:`UART bus </components/uart>`. The uart bus must be configured at the same speed of the module
which is 19200bps.
.. warning::
If you are using the :doc:`logger` make sure you disable the uart logging with the
``baud_rate: 0`` option.
.. figure:: images/rf_bridge-full.jpg
:align: center
:width: 60.0%
.. code-block:: yaml
# Example configuration entry
uart:
baud_rate: 19200
rf_bridge:
on_code_received:
- homeassistant.event:
event: esphome.rf_code_received
data:
sync: !lambda 'char buffer [10];return itoa(data.sync,buffer,16);'
low: !lambda 'char buffer [10];return itoa(data.low,buffer,16);'
high: !lambda 'char buffer [10];return itoa(data.high,buffer,16);'
code: !lambda 'char buffer [10];return itoa(data.code,buffer,16);'
Configuration variables:
------------------------
- **uart_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the UART hub.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **on_code_received** (*Optional*, :ref:`Automation <automation>`): An action to be
performed when a code is received. See :ref:`rf_bridge-on_code_received`.
.. _rf_bridge-on_code_received:
``on_code_received`` Trigger
----------------------------
With this configuration option you can write complex automations whenever a code is
received. To use the code, use a :ref:`lambda <config-lambda>` template, the code
and the corresponding protocol timings are available inside that lambda under the
variables named ``code``, ``sync``, ``high`` and ``low``.
.. code-block:: yaml
on_code_received:
- homeassistant.event:
event: esphome.rf_code_received
data:
sync: !lambda 'char buffer [10];return itoa(data.sync,buffer,16);'
low: !lambda 'char buffer [10];return itoa(data.low,buffer,16);'
high: !lambda 'char buffer [10];return itoa(data.high,buffer,16);'
code: !lambda 'char buffer [10];return itoa(data.code,buffer,16);'
.. _rf_bridge-send_code_action:
``rf_bridge.send_code`` Action
------------------------------
Send an RF code using this action in automations.
.. code-block:: yaml
on_...:
then:
- rf_bridge.send_code:
sync: 0x700
low: 0x800
high: 0x1000
code: 0xABC123
Configuration options:
- **sync** (**Required**, int, :ref:`templatable <config-templatable>`): RF Sync timing
- **low** (**Required**, int, :ref:`templatable <config-templatable>`): RF Low timing
- **high** (**Required**, int, :ref:`templatable <config-templatable>`): RF high timing
- **code** (**Required**, int, :ref:`templatable <config-templatable>`): RF code
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID of the RF Bridge if you have multiple components.
.. note::
This action can also be written in :ref:`lambdas <config-lambda>`:
.. code-block:: cpp
id(rf_bridge).send_code(0x700, 0x800, 0x1000, 0xABC123);
.. _rf_bridge-learn_action:
``rf_bridge.learn`` Action
--------------------------
Tell the RF Bridge to learn new protocol timings using this action in automations.
A new code with timings will be returned to :ref:`rf_bridge-on_code_received`
.. code-block:: yaml
on_...:
then:
- rf_bridge.learn
Configuration options:
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID of the RF Bridge if you have multiple components.
.. note::
This action can also be written in :ref:`lambdas <config-lambda>`:
.. code-block:: cpp
id(rf_bridge).learn();
Getting started with Home Assistant
-----------------------------------
The following code will get you up and running with a configuration sending codes to
Home Assistant as events and will also setup a service so you can send codes with your RF Bridge.
.. code-block:: yaml
api:
services:
- service: send_rf_code
variables:
sync: int
low: int
high: int
code: int
then:
- rf_bridge.send_code:
sync: !lambda 'return sync;'
low: !lambda 'return low;'
high: !lambda 'return high;'
code: !lambda 'return code;'
- service: learn
then:
- rf_bridge.learn
uart:
tx_pin: 1
rx_pin: 3
baud_rate: 19200
logger:
baud_rate: 0
rf_bridge:
on_code_received:
then:
- homeassistant.event:
event: esphome.rf_code_received
data:
sync: !lambda 'char buffer [10];return itoa(data.sync,buffer,16);'
low: !lambda 'char buffer [10];return itoa(data.low,buffer,16);'
high: !lambda 'char buffer [10];return itoa(data.high,buffer,16);'
code: !lambda 'char buffer [10];return itoa(data.code,buffer,16);'
Now your latest received code will be in an event.
To trigger the automation from Home Assistant you can invoke the service with this code:
.. code-block:: yaml
automation:
# ...
action:
- service: esphome.rf_bridge_send_rf_code
data:
sync: 0x700
low: 0x800
high: 0x1000
code: 0xABC123
See Also
--------
- :apiref:`rf_bridge/rf_bridge.h`
- :doc:`/components/uart`
- :ghedit:`Edit`

162
components/rtttl.rst Normal file
View File

@ -0,0 +1,162 @@
Rtttl Buzzer
============
.. seo::
:description: Instructions for setting up a buzzer to play tones and rtttl songs with ESPHome.
:image: crosshair-gps.png
The ``rtttl``, component allows you to easily connect a passive piezo buzzer to your microcontroller
and play monophonic songs. It accepts the Ring Tone Text Transfer Language, rtttl format (`Wikipedia
<https://en.wikipedia.org/wiki/Ring_Tone_Transfer_Language>`__) which allows to store simple melodies.
.. figure:: images/buzzer.jpg
:align: center
:width: 50.0%
Buzzer Module
Overview
--------
It's important that your buzzer is a **passive** one, if it beeps when you feed it with 3.3V then it is not
a passive one and this library will not work properly.
The tone generator needs a PWM capable output to work with, currently only the
:doc:`ESP8266 Software PWM Output<output/esp8266_pwm>` and
:doc:`ESP32 LEDC Output <output/ledc>` are supported.
.. code-block:: yaml
# Example configuration entry
output:
- platform: ledc
pin: GPIO22
id: rtttl_out
rtttl:
output: rtttl_out
Configuration variables:
------------------------
- **output** (**Required**, :ref:`config-id`): The id of the :ref:`float output <output>` to use for
this buzzer.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **on_finished_playback** (*Optional*, :ref:`Automation <automation>`): An action to be
performed when playback is finished.
``rtttl.play`` Action
---------------------
Plays an rtttl tone.
.. code-block:: yaml
on_...:
then:
- rtttl.play: 'MissionImp:d=16,o=6,b=95:32d,32d#,32d,32d#,32d,32d#,32d,32d#,32d,32d,32d#,32e,32f,32f#,32g,g,8p,g,8p,a#,p,c7,p,g,8p,g,8p,f,p,f#,p,g,8p,g,8p,a#,p,c7,p,g,8p,g,8p,f,p,f#,p,a#,g,2d,32p,a#,g,2c#,32p,a#,g,2c,a#5,8c,2p,32p,a#5,g5,2f#,32p,a#5,g5,2f,32p,a#5,g5,2e,d#,8d'
Configuration options:
- **play** (**Required**, string, :ref:`templatable <config-templatable>`): The rtttl string.
You can find many rtttl strings online on the web, they must start with a name, then a colon: ``:`` symbol
and more codes of the song itself. Tip: you can try playing with the values of d=16,o=6,b=95 and make the
song play at a different pace or pitch, e.g. setting o=7 instead will cause the song to play on a higher pitch.
``rtttl.stop`` Action
---------------------
Stops playback.
.. code-block:: yaml
on_...:
then:
- rtttl.stop
All actions
-----------
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID of the rtttl if you have multiple components.
``rtttl.is_playing`` Condition
------------------------------
This Condition returns true while playback is active.
.. code-block:: yaml
# In some trigger:
on_...:
if:
condition:
rtttl.is_playing
then:
logger.log: 'Playback is active!'
Common beeps
------------
You can do your own beep patterns too! Here are a few I made so you can just use right away or tweak them to your
like:
.. code-block:: yaml
two short:d=4,o=5,b=100:16e6,16e6
long:d=1,o=5,b=100:e6
siren:d=8,o=5,b=100:d,e,d,e,d,e,d,e
scale_up:d=32,o=5,b=100:c,c#,d#,e,f#,g#,a#,b
Test setup
----------
With the following code you can quickly setup a node and use Home Assistant's service in the developer tools.
E.g. for calling ``rtttl.play`` select the service ``esphome.test_esp8266_rtttl_play`` and in service data enter
.. code-block:: yaml
song_str: "mario:d=4,o=5,b=100:16e6,16e6,32p,8e6,16c6,8e6,8g6,8p,8g,8p,8c6,16p,8g,16p,8e,16p,8a,8b,16a#,8a,16g.,16e6,16g6,8a6,16f6,8g6,8e6,16c6,16d6,8b,16p,8c6,16p,8g,16p,8e,16p,8a,8b,16a#,8a,16g.,16e6,16g6,8a6,16f6,8g6,8e6,16c6,16d6,8b,8p,16g6,16f#6,16f6,16d#6,16p,16e6,16p,16g#,16a,16c6,16p,16a,16c6,16d6,8p,16g6,16f#6,16f6,16d#6,16p,16e6,16p,16c7,16p,16c7,16c7,p,16g6,16f#6,16f6,16d#6,16p,16e6,16p,16g#,16a,16c6,16p,16a,16c6,16d6,8p,16d#6,8p,16d6,8p,16c6"
Sample code
***********
.. code-block:: yaml
esphome:
name: test_esp8266
platform: ESP8266
board: nodemcuv2
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_pass
output:
- platform: esp8266_pwm
pin: D1
id: rtttl_out
rtttl:
output: rtttl_out
on_finished_playback:
- logger.log: 'Song ended!'
api:
services:
- service: play_rtttl
variables:
song_str: string
then:
- rtttl.play:
rtttl: !lambda 'return song_str;'
See Also
--------
- :apiref:`rtttl/rtttl.h`
- :ghedit:`Edit`

62
components/sensor/aht10.rst Normal file
View File

@ -0,0 +1,62 @@
AHT10 Temperature+Humidity Sensor
=================================
.. seo::
:description: Instructions for setting up AHT10 temperature and humidity sensors
:image: aht10.jpg
:keywords: aht10
The ``aht10`` Temperature+Humidity sensor allows you to use your aht10
(`datasheet <http://www.aosong.com/userfiles/files/media/aht10%E8%A7%84%E6%A0%BC%E4%B9%A6v1_1%EF%BC%8820191015%EF%BC%89.pdf>`__) i2c-based sensor with ESPHome.
.. figure:: images/aht10-full.jpg
:align: center
:width: 50.0%
AHT10 Temperature & Humidity Sensor.
.. figure:: images/temperature-humidity.png
:align: center
:width: 80.0%
.. note::
When configured for humidity, the log *'Components should block for at most 20-30ms in loop().'* will be generated in verbose mode. This is due to technical specs of the sensor and can not be avoided.
.. code-block:: yaml
# Example configuration entry
sensor:
- platform: aht10
temperature:
name: "Living Room Temperature"
humidity:
name: "Living Room Humidity"
update_interval: 60s
Configuration variables:
------------------------
- **temperature** (**Required**): The information for the temperature sensor.
- **name** (**Required**, string): The name for the temperature sensor.
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
- **humidity** (**Required**): The information for the humidity sensor
- **name** (**Required**, string): The name for the humidity sensor.
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``.
See Also
--------
- :ref:`sensor-filters`
- :apiref:`aht10/aht10.h`
- `AHT10 Library <https://github.com/Thinary/AHT10>`__ by `Thinary Electronic <https://github.com/Thinary>`__
- `Unofficial Translated AHT10 Datasheet (en) <https://wiki.liutyi.info/download/attachments/30507639/Aosong_AHT10_en_draft_0c.pdf>`__
- :ghedit:`Edit`

297
components/sensor/atm90e32.rst
View File

@ -17,7 +17,7 @@ The ATM90E32 IC can measure up to three AC voltages although typically only one
voltage measurement would be used for the mains electricity phase of a
household. Three current measurements are read via CT clamps.
The `CircuitSetup 2-Channel Energy Monitor <https://circuitsetup.us/index.php/product/split-single-phase-real-time-whole-house-energy-meter-v1-2/>`__ can read 2 current channels and one voltage channel.
The `CircuitSetup Split Single Phase Energy Meter <https://circuitsetup.us/index.php/product/split-single-phase-real-time-whole-house-energy-meter-v1-2/>`__ can read 2 current channels and 1 (expandable to 2) voltage channel.
.. figure:: images/atm90e32-cs-2chan-full.jpg
:align: center
@ -33,43 +33,10 @@ The `CircuitSetup 6-Channel Energy Monitor <https://circuitsetup.us/index.php/pr
CircuitSetup Expandable 6 Channel ESP32 Energy Meter Main Board.
.. code-block:: yaml
# Example configuration entry
spi:
clk_pin: 18
miso_pin: 19
mosi_pin: 23
sensor:
- platform: atm90e32
cs_pin: 5
phase_a:
voltage:
name: "EMON Line Voltage A"
current:
name: "EMON CT1 Current"
power:
name: "EMON Active Power CT1"
gain_voltage: 41820
gain_ct: 25498
phase_b:
current:
name: "EMON CT2 Current"
power:
name: "EMON Active Power CT2"
gain_voltage: 41820
gain_ct: 25498
frequency:
name: "EMON Line Frequency"
line_frequency: 50Hz
gain_pga: 2X
update_interval: 60s
Configuration variables:
------------------------
- **cs_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The pin CS is connected to.
- **cs_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The pin CS is connected to. For the 6 channel meter main board, this will always be 5 and 4. For the add-on boards a jumper can be selected for each CS pin, but default to 0 and 16.
- **line_frequency** (**Required**, string): The AC line frequency of the supply voltage. One of ``50Hz``, ``60Hz``.
- **phase_a** (*Optional*): The configuration options for the 1st phase.
@ -79,15 +46,25 @@ Configuration variables:
:ref:`Sensor <config-sensor>`.
- **power** (*Optional*): Use the power value on this phase in watts. All options from
:ref:`Sensor <config-sensor>`.
- **reactive_power** (*Optional*): Use the reactive power value on this phase. All options from
:ref:`Sensor <config-sensor>`.
- **power_factor** (*Optional*): Use the power factor value on this phase. All options from
:ref:`Sensor <config-sensor>`.
- **gain_voltage** (*Optional*, int): Voltage gain to scale the low voltage AC power pack to household mains feed.
Defaults to ``41820``.
Defaults to ``7305``.
- **gain_ct** (*Optional*, int): CT clamp calibration for this phase.
Defaults to ``25498``.
Defaults to ``27961``.
- **phase_b** (*Optional*): The configuration options for the 2nd phase. Same options as 1st phase.
- **phase_c** (*Optional*): The configuration options for the 3rd phase. Same options as 1st phase.
- **frequency** (*Optional*): Use the frequenycy value calculated by the meter. All options from
:ref:`Sensor <config-sensor>`.
- **chip_temperature** (*Optional*): Use the chip temperature value. All options from
:ref:`Sensor <config-sensor>`.
- **gain_pga** (*Optional*, string): The gain for the CT clamp, ``2X`` for 100A, ``4X`` for 100A - 200A. One of ``1X``, ``2X``, ``4X``.
Defaults to ``2X`` which is suitable for the popular SCT-013-000 clamp.
- **current_phases** (*Optional*): The number of phases the meter has, ``2`` or, ``3``
The 6 Channel Expandable Energy Meter should be set to ``3``, and the Split Single Phase meter should be set to ``2``. Defaults to ``3``.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``.
- **spi_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`SPI Component <spi>` if you want
to use multiple SPI buses.
@ -103,13 +80,31 @@ A load which uses a known amount of current can be used to calibrate. For for a
Voltage
^^^^^^^
Use the expected mains voltage for your region 110V/230V or plug in the Kill-A-Watt and select voltage. See what
Use the expected mains voltage for your region 110V/230V or plug in the Kill-A-Watt and select voltage. See what
value the ATM90E32 sensor reports for voltage. To adjust the sensor use the calculation:
``New gain_voltage = (your voltage reading / ESPHome voltage reading) * existing gain_voltage value``
Update **gain_voltage** for all phases in your ESPHome yaml, recompile and upload. Repeat as necessary.
Here are common voltage calibrations for the **Split Single Energy Meter**:
For meter <= v1.3:
- 42080 - 9v AC Transformer - Jameco 112336
- 32428 - 12v AC Transformer - Jameco 167151
For meter > v1.4:
- 37106 - 9v AC Transformer - Jameco 157041
- 38302 - 9v AC Transformer - Jameco 112336
- 29462 - 12v AC Transformer - Jameco 167151
For Meters >= v1.4 rev.3
- 3920 - 9v AC Transformer - Jameco 157041
Here are common voltage calibrations for the **Expandable 6 Channel Energy Meter**:
For meter <= v1.2:
- 42080 - 9v AC Transformer - Jameco 112336
- 32428 - 12v AC Transformer - Jameco 167151
For meter > v1.3:
- 7305 - 9v AC Transformer - Jameco 157041
Current
^^^^^^^
@ -122,13 +117,71 @@ sensor using calculation:
Update **gain_ct** for the phase in your ESPHome yaml, recompile and upload. Repeat as necessary.
It is possible that the two identical CT current sensors will have different
**gain_ct** numbers due to variances in manufacturing although it will be
**gain_ct** numbers due to variances in manufacturing, although it will be
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 ``2X``:
- 20A/25mA SCT-006: 10170
- 100A/50mA SCT-013-000: 25498
- 120A/40mA SCT-016: 39473
- Magnalab 100A: 46539
Here are common current calibrations for the **Expandable 6 Channel Energy Meter** when **gain_pga** is set to ``1X``:
- 20A/25mA SCT-006: 11131
- 30A/1V SCT-013-030: 8650
- 50A/1V SCT-013-050: 15420
- 80A/26.6mA SCT-010: 41996
- 100A/50ma SCT-013-000: 27961
- 120A/40mA: SCT-016: 41880
Additional Examples
-------------------
.. code-block:: yaml
# Example configuration entry for split single phase meter
spi:
clk_pin: 18
miso_pin: 19
mosi_pin: 23
sensor:
- platform: atm90e32
cs_pin: 5
phase_a:
voltage:
name: "EMON Line Voltage A"
current:
name: "EMON CT1 Current"
power:
name: "EMON Active Power CT1"
reactive_power:
name: "EMON Reactive Power CT1"
power_factor:
name: "EMON Power Factor CT1"
gain_voltage: 3920
gain_ct: 39473
phase_c:
current:
name: "EMON CT2 Current"
power:
name: "EMON Active Power CT2"
reactive_power:
name: "EMON Reactive Power CT2"
power_factor:
name: "EMON Power Factor CT2"
gain_voltage: 3920
gain_ct: 39473
frequency:
name: "EMON Line Frequency"
chip_temperature:
name: "EMON Chip Temperature"
line_frequency: 50Hz
current_phases: 2
gain_pga: 2X
update_interval: 60s
.. code-block:: yaml
# Example CircuitSetup 6-channel entry
@ -146,26 +199,27 @@ Additional Examples
name: "EMON CT1 Current"
power:
name: "EMON Active Power CT1"
gain_voltage: 47660
gain_voltage: 7305
gain_ct: 12577
phase_b:
current:
name: "EMON CT2 Current"
power:
name: "EMON Active Power CT2"
gain_voltage: 47660
gain_voltage: 7305
gain_ct: 12577
phase_c:
current:
name: "EMON CT3 Current"
power:
name: "EMON Active Power CT3"
gain_voltage: 47660
gain_voltage: 7305
gain_ct: 12577
frequency:
name: "EMON Line Frequency"
line_frequency: 50Hz
gain_pga: 2X
current_phases: 3
gain_pga: 1X
update_interval: 60s
- platform: atm90e32
cs_pin: 4
@ -174,25 +228,174 @@ Additional Examples
name: "EMON CT4 Current"
power:
name: "EMON Active Power CT4"
gain_voltage: 47660
gain_voltage: 7305
gain_ct: 12577
phase_b:
current:
name: "EMON CT5 Current"
power:
name: "EMON Active Power CT5"
gain_voltage: 47660
gain_voltage: 7305
gain_ct: 12577
phase_c:
current:
name: "EMON CT6 Current"
power:
name: "EMON Active Power CT6"
gain_voltage: 47660
gain_voltage: 7305
gain_ct: 12577
line_frequency: 50Hz
gain_pga: 2X
current_phases: 3
gain_pga: 1X
update_interval: 60s
.. code-block:: yaml
# Example CircuitSetup 6-channel without jumpers jp9-jp11 joined or < meter v1.4
# power is calculated in a template
substitutions:
disp_name: 6C
update_time: 10s
current_cal: '27961'
spi:
clk_pin: 18
miso_pin: 19
mosi_pin: 23
sensor:
- platform: atm90e32
cs_pin: 5
phase_a:
voltage:
name: ${disp_name} Volts A
id: ic1Volts
accuracy_decimals: 1
current:
name: ${disp_name} CT1 Amps
id: ct1Amps
gain_voltage: 7305
gain_ct: ${current_cal}
phase_b:
current:
name: ${disp_name} CT2 Amps
id: ct2Amps
gain_ct: ${current_cal}
phase_c:
current:
name: ${disp_name} CT3 Amps
id: ct3Amps
gain_ct: ${current_cal}
frequency:
name: ${disp_name} Freq A
line_frequency: 60Hz
current_phases: 3
gain_pga: 1X
update_interval: ${update_time}
- platform: atm90e32
cs_pin: 4
phase_a:
voltage:
name: ${disp_name} Volts B
id: ic2Volts
accuracy_decimals: 1
current:
name: ${disp_name} CT4 Amps
id: ct4Amps
gain_voltage: 7305
gain_ct: ${current_cal}
phase_b:
current:
name: ${disp_name} CT5 Amps
id: ct5Amps
gain_ct: ${current_cal}
phase_c:
current:
name: ${disp_name} CT6 Amps
id: ct6Amps
gain_ct: ${current_cal}
frequency:
name: ${disp_name} Freq B
line_frequency: 60Hz
current_phases: 3
gain_pga: 1X
update_interval: ${update_time}
#Watts per channel
- platform: template
name: ${disp_name} CT1 Watts
id: ct1Watts
lambda: return id(ct1Amps).state * id(ic1Volts).state;
accuracy_decimals: 0
unit_of_measurement: W
icon: "mdi:flash-circle"
update_interval: ${update_time}
- platform: template
name: ${disp_name} CT2 Watts
id: ct2Watts
lambda: return id(ct2Amps).state * id(ic1Volts).state;
accuracy_decimals: 0
unit_of_measurement: W
icon: "mdi:flash-circle"
update_interval: ${update_time}
- platform: template
name: ${disp_name} CT3 Watts
id: ct3Watts
lambda: return id(ct3Amps).state * id(ic1Volts).state;
accuracy_decimals: 0
unit_of_measurement: W
icon: "mdi:flash-circle"
update_interval: ${update_time}
- platform: template
name: ${disp_name} CT4 Watts
id: ct4Watts
lambda: return id(ct4Amps).state * id(ic2Volts).state;
accuracy_decimals: 0
unit_of_measurement: W
icon: "mdi:flash-circle"
update_interval: ${update_time}
- platform: template
name: ${disp_name} CT5 Watts
id: ct5Watts
lambda: return id(ct5Amps).state * id(ic2Volts).state;
accuracy_decimals: 0
unit_of_measurement: W
icon: "mdi:flash-circle"
update_interval: ${update_time}
- platform: template
name: ${disp_name} CT6 Watts
id: ct6Watts
lambda: return id(ct6Amps).state * id(ic2Volts).state;
accuracy_decimals: 0
unit_of_measurement: W
icon: "mdi:flash-circle"
update_interval: ${update_time}
#Total Amps
- platform: template
name: ${disp_name} Total Amps
id: totalAmps
lambda: return id(ct1Amps).state + id(ct2Amps).state + id(ct3Amps).state + id(ct4Amps).state + id(ct5Amps).state + id(ct6Amps).state ;
accuracy_decimals: 2
unit_of_measurement: A
icon: "mdi:flash"
update_interval: ${update_time}
#Total Watts
- platform: template
name: ${disp_name} Total Watts
id: totalWatts
lambda: return id(totalAmps).state * id(ic1Volts).state;
accuracy_decimals: 1
unit_of_measurement: W
icon: "mdi:flash-circle"
update_interval: ${update_time}
#kWh
- platform: total_daily_energy
name: ${disp_name} Total kWh
power_id: totalWatts
filters:
- multiply: 0.001
unit_of_measurement: kWh
See Also

9
components/sensor/bh1750.rst
View File

@ -28,8 +28,15 @@ your configuration for this sensor to work.
- platform: bh1750
name: "BH1750 Illuminance"
address: 0x23
measurement_time: 69
update_interval: 60s
By default the **measurement_time** is set to ``69`` which will result into measurements up
to 54612.5 lx for this sensor. For low-light situtations consider to choose a higer
measurement_time up to ``254`` which will result in a maximum measurement range up to 14835 lx.
For sunny scenes (for example outdoors with sunlight) use lower values down to ``31`` which will
give you the maximum measurement range up to 121556 lx.
Configuration variables:
------------------------
@ -37,6 +44,8 @@ Configuration variables:
- **address** (*Optional*, int): Manually specify the I^2C address of the sensor.
Defaults to ``0x23`` (address if address pin is pulled low). If the address pin is pulled high,
the address is ``0x5C``.
- **measurement_time** (*Optional*, int): Manually specifiy the measurement time between ``31``
and ``254``. Defaults to ``69``.
- **resolution** (*Optional*, string): The resolution of the sensor in lx. One of ``4.0``,
``1.0``, ``0.5``. Defaults to ``0.5`` (the maximum resolution).
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the

19
components/sensor/ble_rssi.rst
View File

@ -16,16 +16,29 @@ instructions for setting up this platform.
esp32_ble_tracker:
sensor:
# RSSI based on MAC address
- platform: ble_rssi
mac_address: AC:37:43:77:5F:4C
name: "BLE Google Home Mini RSSI value"
# RSSI based on Service UUID
- platform: ble_rssi
service_uuid: '11aa'
name: "BLE Test Service 16 bit RSSI value"
.. note::
Service UUID can be 16 bit long, as in the example, but it can also be 32 bit long
like `1122aaff`, or 128 bit long like `11223344-5566-7788-99aa-bbccddeeff00`.
Configuration variables:
------------------------
- **mac_address** (**Required**, MAC Address): The MAC address to track for this
sensor.
- **name** (**Required**, string): The name of the sensor.
- **name** (**Required**, string): The name of the sensor.
- **mac_address** (*Optional*, MAC Address): The MAC address to track for this
sensor. Either this or ''service_uuid'' has to be present.
- **service_uuid** (*Optional*, 16 bit, 32 bit, or 128 bit BLE Service UUID): The BLE
Service UUID which can be tracked if the device randomizes the MAC address. Either
this or ''mac_address'' has to be present.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- All other options from :ref:`Sensor <config-sensor>`.

2
components/sensor/dht.rst
View File

@ -64,7 +64,7 @@ Configuration variables:
- All other options from :ref:`Sensor <config-sensor>`.
- **model** (*Optional*, int): Manually specify the DHT model, can be
one of ``AUTO_DETECT``, ``DHT11``, ``DHT22``, ``AM2302``, ``RHT03``, ``SI7021``
one of ``AUTO_DETECT``, ``DHT11``, ``DHT22``, ``DHT22_TYPE2``, ``AM2302``, ``RHT03``, ``SI7021``
and helps with some connection issues. Defaults to ``AUTO_DETECT``. Auto detection doesn't work for the SI7021 chip.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the
sensor. Defaults to ``60s``.

87
components/sensor/hm3301.rst Normal file
View File

@ -0,0 +1,87 @@
The Grove - Laser PM2.5 Sensor (HM3301)
=======================================
.. seo::
:description: Instructions for setting up HM3301 Particulate matter sensor
:image: hm3301.png
The ``HM3301`` sensor platform allows you to use your HM3301 particulate matter sensor
(`more info <http://wiki.seeedstudio.com/Grove-Laser_PM2.5_Sensor-HM3301>`__)
sensors with ESPHome.
The sensor communicate with board by ``I2C`` protocol, and requires 3.3v.
.. code-block:: yaml
# Example configuration entry
i2c:
sensor:
- platform: hm3301
pm_1_0:
name: "PM1.0"
pm_2_5:
name: "PM2.5"
pm_10_0:
name: "PM10.0"
aqi:
name: "AQI"
type: "CAQI"
Configuration variables:
------------------------
- **pm_1_0** (*Optional*): Use the concentration of particulates of size less than 1.0µm in µg per cubic meter.
- **name** (**Required**, string): The name for the temperature sensor.
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
- **pm_2_5** (*Optional*): Use the concentration of particulates of size less than 2.5µm in µg per cubic meter.
- **name** (**Required**, string): The name for the temperature sensor.
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
- **pm_10_0** (*Optional*): Use the concentration of particulates of size less than 10.0µm in µg per cubic meter.
- **name** (**Required**, string): The name for the temperature sensor.
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
- **aqi** (*Optional*): AQI sensor. Requires the ``pm_2_5`` and ``pm_10_0`` sensors defined. See below.
- **type** (**Required**): One of: ``AQI`` or ``CAQI``.
- **name** (**Required**, string): The name for the temperature sensor.
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
- All other options from :ref:`Sensor <config-sensor>`.
Air Quality Sensor:
-------------------
There is a sensor which calculates quality of air based on PM 2.5 and PM 10.0 values.
There are two implementations:
- AQI: USA air quality standard
- CAQI: Europe air quality standard
.. code-block:: yaml
sensor:
- platform: hm3301
pm_2_5:
name: "PM2.5"
pm_10_0:
name: "PM10.0"
aqi:
name: "AQI"
type: "CAQI"
See Also
--------
- :doc:`/components/sensor/sds011`
- :ref:`sensor-filters`
- :apiref:`hm3301/hm3301.h`
- :ghedit:`Edit`

42
components/sensor/hmc5883l.rst
View File

@ -1,3 +1,5 @@
.. _hmc5883l:
HMC5883L Magnetometer
=====================
@ -8,9 +10,14 @@ HMC5883L Magnetometer
The ``hmc5883l`` allows you to use your HMC5883L triple-axis magnetometers
(`datasheet <https://cdn-shop.adafruit.com/datasheets/HMC5883L_3-Axis_Digital_Compass_IC.pdf>`__,
`Adafruit`_) with
ESPHome. The :ref:`I²C Bus <i2c>` is
required to be set up in your configuration for this sensor to work.
`Adafruit`_) with ESPHome. The :ref:`I²C Bus <i2c>` is required to be set up in your configuration
for this sensor to work.
.. figure:: ../../images/hmc5883l.jpg
:align: center
:width: 30.0%
HMC5883L Magnetometer.
.. _Adafruit: https://www.adafruit.com/product/1746
@ -28,6 +35,7 @@ required to be set up in your configuration for this sensor to work.
name: "HMC5883L Field Strength Z"
heading:
name: "HMC5883L Heading"
oversampling: 1x
range: 130uT
update_interval: 60s
@ -43,6 +51,8 @@ Configuration variables:
:ref:`Sensor <config-sensor>`.
- **heading** (*Optional*): The heading of the sensor in degrees. All options from
:ref:`Sensor <config-sensor>`.
- **oversampling** (*Optional*): The oversampling parameter for the sensor.
- **range** (*Optional*): The range parameter for the sensor.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``.
- **oversampling** (*Optional*): Number of readings to average over for each sample. One of ``1x``, ``2x``,
``4x``, ``8x``. Defaults to ``1x``.
@ -52,6 +62,32 @@ Configuration variables:
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
Oversampling Options
--------------------
By default, the HMC5883L sensor measures each value 1 times when requesting a new value. You can, however,
configure this amount. The result is the sensor will take the adverage of the x samples. Possible oversampling values:
- ``1x`` (default)
- ``2x``
- ``4x``
- ``8x``
Range Options
-------------
By default, the HMC5883L sensor measurement range is 130uT. You can, however,
configure this amount. Possible values:
- ``88uT``
- ``130uT`` (default)
- ``190uT``
- ``250uT``
- ``400uT``
- ``470uT``
- ``560uT``
- ``810uT``
See Also
--------

BIN
components/sensor/images/aht10-full.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 94 KiB

BIN
components/sensor/images/as3935.jpg
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 857 KiB

After

Width:  |  Height:  |  Size: 54 KiB

BIN
components/sensor/images/ina226-full.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 124 KiB

BIN
components/sensor/images/max31856-full.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 255 KiB

BIN
components/sensor/images/max31865-full.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 418 KiB

BIN
components/sensor/images/mpu6050-full.jpg
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1009 KiB

After

Width:  |  Height:  |  Size: 151 KiB

BIN
components/sensor/images/ruuvitag-full.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 34 KiB

BIN
components/sensor/images/ruuvitag-ui.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 27 KiB

BIN
components/sensor/images/sensirion-pm.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 17 KiB

BIN
components/sensor/images/sps30-wiring.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.9 KiB

BIN
components/sensor/images/sps30.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 12 KiB

BIN
components/sensor/images/tmp117.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 26 KiB

BIN
components/sensor/images/xiaomi_cgd1.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 53 KiB

BIN
components/sensor/images/xiaomi_cgg1-full.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 15 KiB

BIN
components/sensor/images/xiaomi_cgg1-ui.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 14 KiB

BIN
components/sensor/images/xiaomi_cgg1.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 20 KiB

BIN
components/sensor/images/xiaomi_gcls002.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 357 KiB

BIN
components/sensor/images/xiaomi_hhccjcy01.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 36 KiB

BIN
components/sensor/images/xiaomi_hhccpot002.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 8.8 KiB

BIN
components/sensor/images/xiaomi_jqjcy01ym.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 18 KiB

BIN
components/sensor/images/xiaomi_lywsd02-full.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 273 KiB

BIN
components/sensor/images/xiaomi_lywsd02-ui.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 2.6 KiB

BIN
components/sensor/images/xiaomi_lywsd02.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 76 KiB

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