Upstream/esphome-docs
1
0
Fork 0
mirror of https://github.com/esphome/esphome-docs.git synced 2025-02-28 03:41:57 +01:00
Code Issues Projects Releases Wiki Activity

Merge branch 'current' into beta

Browse Source
This commit is contained in:
Jesse Hills 2023-04-17 15:45:23 +12:00
commit 9f83c63bb5
No known key found for this signature in database
GPG Key ID: BEAAE804EFD8E83A
17 changed files with 123 additions and 923 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.github/workflows/docker.yml vendored
View File

@ -20,7 +20,7 @@ jobs:
steps:
-
name: Checkout source code
uses: actions/checkout@v3.5.0
uses: actions/checkout@v3.5.2
-
name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
@ -39,7 +39,7 @@ jobs:
-
name: Build and push
id: docker_build
uses: docker/build-push-action@v3
uses: docker/build-push-action@v4
with:
context: .
push: true

2
.github/workflows/lint.yml vendored
View File

@ -19,7 +19,7 @@ jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3.5.0
- uses: actions/checkout@v3.5.2
- name: Set up Python 3.8
uses: actions/setup-python@v4
with:

4
.github/workflows/stale.yml vendored
View File

@ -16,7 +16,7 @@ jobs:
stale:
runs-on: ubuntu-latest
steps:
- uses: actions/stale@v7
- uses: actions/stale@v8
with:
days-before-pr-stale: 60
days-before-pr-close: 7
@ -35,7 +35,7 @@ jobs:
close-issues:
runs-on: ubuntu-latest
steps:
- uses: actions/stale@v7
- uses: actions/stale@v8
with:
days-before-pr-stale: -1
days-before-pr-close: -1

11
.vscode/tasks.json vendored Normal file
View File

@ -0,0 +1,11 @@
{
"version": "2.0.0",
"tasks": [
{
"label": "Live HTML build",
"type": "shell",
"command": "make live-html",
"problemMatcher": []
},
]
}

27
_redirects
View File

@ -9,3 +9,30 @@
/changelog/2022.12.4.html /changelog/2022.12.0.html 301
/components/display/ili9341.html /components/display/ili9xxx.html 301
/cookbook/brilliant-mirabella-genio-smart-plugs.html https://devices.esphome.io/devices/Mirabella-Genio-Wi-Fi-1-USB 301
/cookbook/zemismart-rgbw-downlights.html https://devices.esphome.io/devices/Zemismart-LED-RGBWW-Downlight 301
/cookbook/relay.html https://devices.esphome.io/devices/Generic-Relay 301
/cookbook/pir.html https://devices.esphome.io/devices/Generic-PIR 301
/cookbook/mirabella-genio-bulb.html https://devices.esphome.io/devices/Mirabella-Genio-Monochromatic-Bulbs 301
/cookbook/air_gradient_diy_air_quality_sensor.html https://devices.esphome.io/devices/AirGradient-DIY 301
/cookbook/ble_itag.html https://devices.esphome.io/devices/ble_itag 301
/cookbook/bruh.html https://devices.esphome.io/devices/bruh 301
/cookbook/esw01-eu.html https://devices.esphome.io/devices/Etekcity-Voltson-ESW01-EU 301
/cookbook/geiger-counter.html https://devices.esphome.io/devices/geiger-counter 301
/cookbook/h801.html https://devices.esphome.io/devices/H801-RGBW-LED-Controller 301
/cookbook/iaq_board.html https://devices.esphome.io/devices/iaq_board 301
/cookbook/ifan02.html https://devices.esphome.io/devices/Sonoff-iFan02 301
/cookbook/ilonda-wifi-smart-fish-feeder.html https://devices.esphome.io/devices/ilonda-wifi-smart-fish-feeder 301
/cookbook/iwoole_rgbw_table_lamp.html https://devices.esphome.io/devices/iwoole_rgbw_table_lamp 301
/cookbook/teckin_sb50.html https://devices.esphome.io/devices/Teckin-SB50_rgbww 301
/cookbook/temt6000.html https://devices.esphome.io/devices/temt6000 301
/cookbook/tracer-an.html https://devices.esphome.io/devices/epever_mptt_tracer_an 301
/cookbook/tuya_rgbw.html https://devices.esphome.io/devices/tuya_rgbw 301
/cookbook/uart_text_sensor.html /cookbook/lambda_magic.html#custom-uart-text-sensor 301
/cookbook/endstop-cover.html /components/cover/endstop.html 301
/cookbook/sonoff-light-switch.html https://devices.esphome.io/devices/Sonoff-Dual-DIY-light 301
/cookbook/sonoff-basic-light-switch.html https://devices.esphome.io/devices/Sonoff-Basic-DIY-light 301
/cookbook/sonoff-dual-light-switch.html https://devices.esphome.io/devices/Sonoff-Dual-DIY-light 301
/cookbook/sonoff-t1-3.html https://devices.esphome.io/devices/Sonoff-T1-T2-T3 301
/cookbook/dual-r2-cover.html /cookbook/lambda_magic.html#one-button-cover-control 301

2
components/output/template.rst
View File

@ -72,7 +72,7 @@ It is possible to access the state value inside Lambdas:
- output.turn_off: button_off
Complete example from the cookbook: :doc:`Sonoff Dual Light Switch</cookbook/sonoff-dual-light-switch>`.
Complete example: `Sonoff Dual Light Switch <https://devices.esphome.io/devices/Sonoff-Dual-DIY-light>`__.
See Also
--------

4
components/sensor/homeassistant.rst
View File

@ -32,7 +32,7 @@ Entity state attributes can also be imported:
This component is only for numeral states. If you want to import arbitrary text states
from Home Assistant, use the :doc:`Home Assistant Text Sensor </components/text_sensor/homeassistant>`.
Albeit you might not plan to *export* states from the node and you do not need an entity of the node
Although you might not plan to *export* states from the node and you do not need an entity of the node
in Home Assistant, this component still requires you to register the node under Home Assistant. See:
:doc:`Getting started with Home Assistant </guides/getting_started_hassio>`
@ -50,7 +50,7 @@ Configuration variables:
.. note::
The sensors implemented by this component are by default ``internal``, to avoid exporting back them to
The sensors implemented by this component are by default ``internal``, to avoid exporting them back to
Home Assistant. Should you still want to do that (eg. because you use ESPHome's very efficient filters
on them) you need to specifically configure ``internal: false``. Also, ``state_class``, ``unit_of_measurement``
are not inherited from the imported sensor so you need to set them manually.

101
cookbook/dual-r2-cover.rst
View File

@ -1,101 +0,0 @@
Dual relay cover motor control
==============================
.. seo::
:description: An example of how to integrate covers that are controlled by two relays into ESPHome.
:image: sonoff_dual_r2.jpg
:keywords: Relay, Sonoff Dual R2, Cover
The following is a possible configuration file for common covers that use a motor with 2 inputs.
Only one should be powered at a time (interlocking) to either move the cover up or down. For this
the `Sonoff Dual R2 <https://www.itead.cc/sonoff-dual.html>`__ can be used which has two independent
relays. Additionally this configuration allows the single button on the Sonoff to control the motion
by cycling between: open->stop->close->stop->...
These kind of motors automatically stop when the end of the cover movement is reached. However,
to be safe, this automation stops powering the motor after 1 minute of movement. In the rare case
of the end-stop switch in the motor failing this will reduce the risk for damage or fire.
Of the four main components (button sensor, 2 relays switches and the cover), only the cover will be
visible to the end-user. The other three are hidden by means of not including a ``name``. This is to
prevent accidentally switching on both relays simultaneously from Home Assistant as that might be harmful
for some motors.
.. note::
Controlling the cover to quickly (sending new open/close commands within a minute of previous commands)
might cause unexpected behaviour (eg: cover stopping halfway). This is because the delayed relay off
feature is implemented using asynchronous automations. So every time an open/close command is sent a
delayed relay off command is added and old ones are not removed.
.. code-block:: yaml
esphome:
name: cover
esp8266:
board: esp01_1m
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
api:
logger:
ota:
binary_sensor:
- platform: gpio
pin:
number: GPIO10
inverted: true
id: button
on_press:
then:
# logic for cycling through movements: open->stop->close->stop->...
- lambda: |
if (id(my_cover).current_operation == COVER_OPERATION_IDLE) {
// Cover is idle, check current state and either open or close cover.
if (id(my_cover).is_fully_closed()) {
id(my_cover).open();
} else {
id(my_cover).close();
}
} else {
// Cover is opening/closing. Stop it.
id(my_cover).stop();
}
switch:
- platform: gpio
pin: GPIO12
interlock: &interlock [open_cover, close_cover]
id: open_cover
- platform: gpio
pin: GPIO5
interlock: *interlock
id: close_cover
cover:
- platform: time_based
name: "Cover"
id: my_cover
open_action:
- switch.turn_on: open_cover
open_duration: 60s
close_action:
- switch.turn_on: close_cover
close_duration: 60s
stop_action:
- switch.turn_off: open_cover
- switch.turn_off: close_cover
See Also
--------
- :doc:`/guides/automations`
- :doc:`/components/cover/time_based`
- :doc:`/devices/sonoff`
- :ghedit:`Edit`

94
cookbook/endstop-cover.rst
View File

@ -1,94 +0,0 @@
Template Cover with Endstops
============================
.. seo::
:description: An example of how to integrate covers with endstops in ESPHome.
:image: window-open.svg
The following is an example configuration for controlling covers (like window blinds etc)
with ESPHome. This guide assumes that the cover is set up with two endstops at the top
and the bottom. When these endstops are reached, the cover will automatically stop.
To protect the motors from spinning indefinitely (in case an endstop fails) the motors
also have a maximum run time - after 3 minutes they will automatically turn off even if the
endstop is not reached.
ESPHome uses Home Assistant's cover architecture model which has two states: "OPEN" or
"CLOSED". We will map OPEN to "cover is at the top endstop" and CLOSE to "cover is at the bottom".
.. code-block:: yaml
switch:
# The switch that turns the UP direction on
- platform: gpio
pin: D1
id: up_pin
# Use interlocking to keep at most one of the two directions on
interlock: &interlock_group [up_pin, down_pin]
# If ESP reboots, do not attempt to restore switch state
restore_mode: always off
# The switch that turns the DOWN direction on
- platform: gpio
pin: D2
id: down_pin
interlock: *interlock_group
restore_mode: always off
binary_sensor:
- platform: gpio
pin: D4
id: top_endstop
- platform: gpio
pin: D5
id: bottom_endstop
cover:
- platform: endstop
name: "My Endstop Cover"
id: my_cover
open_action:
- switch.turn_on: up_pin
open_duration: 2min
open_endstop: top_endstop
close_action:
- switch.turn_on: down_pin
close_duration: 2min
close_endstop: bottom_endstop
stop_action:
- switch.turn_off: up_pin
- switch.turn_off: down_pin
max_duration: 3min
You can then optionally also add manual controls to the cover with three buttons:
open, close, and stop.
.. code-block:: yaml
binary_sensor:
# [...] - Previous binary sensors
- platform: gpio
id: open_button
pin: D3
on_press:
- cover.open: my_cover
- platform: gpio
id: close_button
pin: D6
on_press:
- cover.close: my_cover
- platform: gpio
id: stop_button
pin: D7
on_press:
- cover.stop: my_cover
See Also
--------
- :doc:`/guides/automations`
- :doc:`/components/cover/template`
- :doc:`dual-r2-cover`
- :ghedit:`Edit`

74
cookbook/lambda_magic.rst
View File

@ -105,7 +105,7 @@ Custom UART Text Sensor
-----------------------
Lots of devices communicate using the UART protocol. If you want to read
lines from uart to a Text Sensor you can do so using this code example.
lines from uart to a Text Sensor you can do so using this code example.
With this you can use automations or lambda to set switch or sensor states.
@ -186,6 +186,8 @@ And in YAML:
text_sensors:
id: "uart_readline"
For more details see :doc:`/custom/uart` and :doc:`/components/uart`.
.. _lambda_magic_uart_switch:
Custom UART Switch
@ -295,12 +297,78 @@ will still look like they operate simultaneously.
- script.execute: rf_transmitter_queue
open_duration: 27s
.. _lambda_magic_1button_coover:
One Button Cover Control
------------------------
The configuration below shows how with a single button you can control the motion of a motorized cover
by cycling between: open->stop->close->stop->...
In this example a :doc:`/components/cover/time_based` is used with the GPIO configuration of a Sonoff Dual R2.
.. note::
Controlling the cover to quickly (sending new open/close commands within a minute of previous commands)
might cause unexpected behaviour (eg: cover stopping halfway). This is because the delayed relay off
feature is implemented using asynchronous automations. So every time an open/close command is sent a
delayed relay off command is added and old ones are not removed.
.. code-block:: yaml
esp8266:
board: esp01_1m
binary_sensor:
- platform: gpio
pin:
number: GPIO10
inverted: true
id: button
on_press:
then:
# logic for cycling through movements: open->stop->close->stop->...
- lambda: |
if (id(my_cover).current_operation == COVER_OPERATION_IDLE) {
// Cover is idle, check current state and either open or close cover.
if (id(my_cover).is_fully_closed()) {
id(my_cover).open();
} else {
id(my_cover).close();
}
} else {
// Cover is opening/closing. Stop it.
id(my_cover).stop();
}
switch:
- platform: gpio
pin: GPIO12
interlock: &interlock [open_cover, close_cover]
id: open_cover
- platform: gpio
pin: GPIO5
interlock: *interlock
id: close_cover
cover:
- platform: time_based
name: "Cover"
id: my_cover
open_action:
- switch.turn_on: open_cover
open_duration: 60s
close_action:
- switch.turn_on: close_cover
close_duration: 60s
stop_action:
- switch.turn_off: open_cover
- switch.turn_off: close_cover
See Also
--------
- :ref:`config-lambda`
- :ref:`automation`
- :doc:`/components/uart`
- :doc:`/custom/uart`
- :ghedit:`Edit`

172
cookbook/sonoff-basic-light-switch.rst
View File

@ -1,172 +0,0 @@
DIY Light switch using a Sonoff Basic
=====================================
.. seo::
:description: An example of how to integrate a light switch into Home Assistant using ESPHome
:keywords: Relay, Sonoff Basic, Sonoff Dual Dual R1, Light, HASS, Home Assistant, ESPHome
.. note::
This is a DIY solution, and you will need to have some knowledge of electrical wiring and enough
capabilities to do this work safely.
The author, and the ESPHome team, take no responsibility for any actions, injuries or outcomes
from following this guide.
In some countries you may need specific qualifications before you can carry out such work in
a residential property.
Background
----------
Moving your entire house to smart lighting can end up being very expense, for instance if you have a
light fitting with 5 lamps in it that's 5 expensive smart bulbs to buy just for one room! Smart bulbs
clearly have some great advantages, dimmable, colour temperature or even full colour changing. What
if all you're after is a cost effective way to turn them on and off?
The ideal solution would be to replace the light switch with one that can be controlled by home
assistant, whilst retaining the ease of use of a standard light that would also continue to work if
the network went down, or Home Assistant failed etc.
It turns out Sonoff do exactly this product, it called a T1-UK (other country options available),
however you soon found the touch aspect of them might not 'feel right' and certainly might not get the
approval of other members of your household. However if this solution appeals to you, check out the
:doc:`Cookbook guide for T1/T2/T3</cookbook/sonoff-t1-3>`
The other option to consider is a standard '2 way' light switch (like you might have on an upstairs
/ downstairs control in your house) but using relays for the second switch. For many this will have
the disadvantage that if you remotely changed the light status the switch is then 'upside down'.
The Solution
------------
Use a 'retractive' style light switch. That is one that is spring loaded and so always returns to the
'off' position. It's effectively a push button, that looks like a light switch. Combining this with a
Sonoff Basic gives you the ideal solution for somewhere around £5. That's much cheaper than buying lots
of expensive smart bulbs, but of course you only get on / off control.
You will have several potential hurdles to overcome:
1. The first is that you do need to have a neutral at the location of the Sonoff. Many houses will not have
this as standard at the light switch.
2. You need enough space to accommodate your Sonoff Basic at your chosen location.
If you're lucky most of the locations will have plasterboard walls, and you will be able to simply drop a neutral
wire down the inside of the wall to the lights switch (where you locate the Sonoff).
Also, if you have plasterboard walls, most of the light switch back boxes are the plastic dry lining style boxes.
This can come in useful because if you remove the PCB from the plastic case it actually fits in the back box nicely.
.. warning::
If you plan to take the PCB out of the plastic case you need to make sure it's properly insulated, and that the back
box is deep enough to hold the PCB as well as the switch. You should also insulate the PCB, for instance by dropping it
in a heavy duty glue lined heat shrink sleeve.
**The PCB has mains electricity flowing through it, if you are in any doubt about your capabilities do not attempt to do
this.**
If you have a light switch in a brick wall, an option might be to place the Sonoff Basic above the light in the ceiling void,
and use the cable that ran from the light to the switch as a low voltage cable to connect the Sonoff GPIO.
.. warning::
If you are going to reuse existing wiring to connect to the GPIO, you must make sure it's connected directly to the switch
and does not have mains voltage on it from another circuit.
Implementation
--------------
So having established the pitfalls that you need to overcome lets crack on with making this work.
Please make sure you have read up about :doc:`the Sonoff Basic and how to flash it with ESPHome </devices/sonoff_basic>`.
As that won't be covered here.Also make sure you know your way around a soldering iron and can find the relevant information
about the location of the GPIO pins on the Sonoff Basic if you need to.
If you have a Sonoff Basic V1 devices GPIO14 is already presented on a pin header on the PCB next to the programming pins.
On the V2 and V3 PCBs, there is a solder pad underneath the PCB that will let you get at this GPIO.
You have 2 choices when it comes to picking which GPIO to use. GPIO0 or GPIO14. GPIO0 is used by the push button switch on the
the PCB so you will need to locate the right pin on the switch and solder a wire onto it if you're going to use that one. Whichever
one you pick, you will also need to use the ground or 0V pin for the other side of the switch. Once you have soldered your wires
into place, a handy tip is to add a drop of glue over the wire, a little way away from the solder joint, so give some strain relief
to the joint.
Now you have a pair of wires from the GPIO and 0V to your retractive switch lets look at the code.
.. code-block:: yaml
esphome:
name: my_ls
esp8266:
board: esp01_1m
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
logger:
api:
ota:
binary_sensor:
- platform: gpio
pin:
number: GPIO14
mode:
input: true
pullup: true
inverted: true
id: button_1
on_press:
then:
- light.toggle: light_1
- platform: status
name: "My LS Status"
output:
- platform: gpio
pin: GPIO12
id: relay_1
light:
- platform: binary
name: "My Light"
id: light_1
output: relay_1
status_led:
pin:
number: GPIO13
inverted: yes
In the above code block, there is a *secrets.yaml* file so that you have just one place to change WiFi
details for all your devices.
Although not visible day to day, there is also the status LED configured so that it can be used when setting
up / debugging. Also a configured binary sensor to give status in case you want to perform an action / alert
if the light switch disconnects for any reason.
.. note::
If you wanted to use a pull cord switch (in a bathroom for instance) that works like a standard switch and
changes state each pull (as opposed to a retractive switch that you press and let go) then you can change
a single line *on_press:* to *on_state:* which will trigger the light toggle every time the state of the
switch changes.
If you do this it's important that you do not use GPIO0, otherwise if the device reboots and the switch happens
to be in the closed state the Sonoff will boot into flash mode and not work.
See Also
--------
- :doc:`/cookbook/sonoff-light-switch`
- :doc:`/guides/automations`
- :doc:`/devices/sonoff_basic`

260
cookbook/sonoff-dual-light-switch.rst
View File

@ -1,260 +0,0 @@
DIY Light switch using a Sonoff Dual
====================================
.. seo::
:description: An example of how to integrate a dual light switch into Home Assistant using ESPHome
:keywords: Relay, Sonoff Dual Dual R1, Light, HASS, Home Assistant, ESPHome
.. note::
This is a DIY solution, and you will need to have some knowledge of electrical wiring and enough
capabilities to do this work safely.
The author, and the ESPHome team, take no responsibility for any actions, injuries or outcomes
from following this guide.
In some countries you may need specific qualifications before you can carry out such work in
a residential property.
Please read up on :doc:`/cookbook/sonoff-basic-light-switch` to get the background and principals of
the this project. It's all basically the same, but with a double switch.
So we will be using GPIO4 and GPIO14 for the two retractive switches, again they will both short to 0V
when the switch is clicked.
R1
--
The R1 version of the Dual controls the relays via the UART, so the code gets a bit complex here.
.. code-block:: yaml
esphome:
name: dual_ls
esp8266:
board: esp01_1m
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
logger:
baud_rate: 0
# Enable Home Assistant API
api:
ota:
uart:
tx_pin: GPIO01
rx_pin: GPIO03
baud_rate: 19200
switch:
- platform: template
id: relay_1
turn_on_action:
if:
condition:
switch.is_off: relay_2
then:
- uart.write: [0xA0, 0x04, 0x01, 0xA1]
else:
- uart.write: [0xA0, 0x04, 0x03, 0xA1]
turn_off_action:
if:
condition:
switch.is_off: relay_2
then:
- uart.write: [0xA0, 0x04, 0x00, 0xA1]
else:
- uart.write: [0xA0, 0x04, 0x02, 0xA1]
optimistic: true
- platform: template
id: relay_2
turn_on_action:
if:
condition:
switch.is_off: relay_1
then:
- uart.write: [0xA0, 0x04, 0x02, 0xA1]
else:
- uart.write: [0xA0, 0x04, 0x03, 0xA1]
turn_off_action:
if:
condition:
switch.is_off: relay_1
then:
- uart.write: [0xA0, 0x04, 0x00, 0xA1]
else:
- uart.write: [0xA0, 0x04, 0x01, 0xA1]
optimistic: true
binary_sensor:
- platform: gpio
pin:
number: GPIO4
mode:
input: true
pullup: true
inverted: true
id: button_1
on_press:
then:
- light.toggle: light_1
- platform: gpio
pin:
number: GPIO14
mode:
input: true
pullup: true
inverted: true
id: button_2
on_press:
then:
- light.toggle: light_2
- platform: status
name: "Dual LS Status"
status_led:
pin:
number: GPIO13
inverted: yes
output:
- platform: template
type: binary
id: out_1
write_action:
if:
condition:
light.is_on: light_1
then:
- switch.turn_on: relay_1
else:
- switch.turn_off: relay_1
- platform: template
type: binary
id: out_2
write_action:
if:
condition:
light.is_on: light_2
then:
- switch.turn_on: relay_2
else:
- switch.turn_off: relay_2
light:
- platform: binary
name: "Dual L1"
id: light_1
output: out_1
- platform: binary
name: "Dual L2"
id: light_2
output: out_2
In the above code block, there is a *secrets.yaml* file so that you have just one place to change WiFi
details for all your devices.
The logger baud_rate: 0 is required to make sure the logged does not send any data over the UART or it would
mess with the relays.
Although not visible day to day, there is also the status LED configured so that it can be used when setting
up / debugging. Also a configured binary sensor to give status in case you want to perform an action / alert
if the light switch disconnects for any reason.
R2
--
This one is a lot simpler as it uses real GPIO for its relays. Please note this is untested, but should work!
It's basically the same as the :doc:`T2 </cookbook/sonoff-t1-3>`
.. code-block:: yaml
esphome:
name: dual_ls
esp8266:
board: esp01_1m
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
logger:
api:
ota:
binary_sensor:
- platform: gpio
pin:
number: GPIO0
mode:
input: true
pullup: true
inverted: true
id: button
on_press:
then:
- light.toggle: light_1
- platform: gpio
pin:
number: GPIO14
mode:
input: true
pullup: true
inverted: true
id: button
on_press:
then:
- light.toggle: light_2
- platform: status
name: "Dual LS Status"
output:
- platform: gpio
pin: GPIO12
id: relay_1
- platform: gpio
pin: GPIO5
id: relay_2
light:
- platform: binary
name: "Dual L1"
id: light_1
output: relay_1
- platform: binary
name: "Dual L2"
id: light_2
output: relay_2
status_led:
pin:
number: GPIO13
inverted: yes
See Also
--------
- :doc:`/cookbook/sonoff-light-switch`
- :doc:`/guides/automations`
- :doc:`/devices/sonoff_basic`

23
cookbook/sonoff-light-switch.rst
View File

@ -1,23 +0,0 @@
Sonoff Light switch options
===========================
.. seo::
:description: A series of options on using Sonoff devices as a light switch within ESPHome
:keywords: Relay, Sonoff Basic, Sonoff Dual Dual R1, Light, HASS, Home Assistant, ESPHome
There are a number of options for using Sonoff Devices as light switches, including purpose built ones
like the T1/2/3 Series
.. imgtable::
Sonoff T1/T2/T3, cookbook/sonoff-T1-3, sonoff_1t_t3.png
Sonoff Basic, cookbook/sonoff-basic-light-switch, sonoff_basic.jpg
Sonoff Dual, cookbook/sonoff-dual-light-switch, sonoff_dual_r2.jpg
See Also
--------
- :doc:`/guides/automations`
- :doc:`/devices/sonoff_basic`

255
cookbook/sonoff-t1-3.rst
View File

@ -1,255 +0,0 @@
Sonoff T1/T2/T3 UK
==================
.. seo::
:description: An example of how to integrate a T1 T2 or T3 Sonoff light switch into Home Assistant
using ESPHome
:image: sonoff_1t_t3.png
:keywords: Relay, Sonoff Basic, Sonoff Dual Dual R1, Light, HASS, Home Assistant, ESPHome
Please make sure you have read up about :doc:`the Sonoff T1 / T2 / T3 and how to flash it with ESPHome </devices/sonoff_t1_uk_3gang_v1.1>`.
So let's get straight on with the code!
T1
--
.. code-block:: yaml
esphome:
name: my_t1
esp8266:
board: esp01_1m
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
logger:
api:
ota:
binary_sensor:
- platform: gpio
pin:
number: GPIO0
mode:
input: true
pullup: true
inverted: true
id: button_1
on_press:
then:
- light.toggle: light_1
- platform: status
name: "T1 Status"
output:
- platform: gpio
pin: GPIO12
id: relay_1
light:
- platform: binary
name: "T1"
id: light_1
output: relay_1
status_led:
pin:
number: GPIO13
inverted: yes
In the above code block, there is a *secrets.yaml* file so that you have just one place to change WiFi
details for all your devices.
The use_address is required because the Sonoff T series don't work with mDNS properly. This means that it will
show as off line in the dashboard, and you will need to use the IP address to view the logs or upload new versions
of the firmware. You will also need to manually add the device in integrations by IP address. You will need to
assign a fixed IP in the above configuration, or use a fixed IP assigned by your DHCP server.
See `issue #810 <https://github.com/esphome/issues/issues/810>`__ for further details.
T2
--
.. code-block:: yaml
esphome:
name: my_t2
esp8266:
board: esp01_1m
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
logger:
api:
ota:
binary_sensor:
- platform: gpio
pin:
number: GPIO0
mode:
input: true
pullup: true
inverted: true
id: button_1
on_press:
then:
- light.toggle: light_1
- platform: gpio
pin:
number: GPIO9
mode:
input: true
pullup: true
inverted: true
id: button_2
on_press:
then:
- light.toggle: light_2
- platform: status
name: "T2 Status"
output:
- platform: gpio
pin: GPIO12
id: relay_1
- platform: gpio
pin: GPIO5
id: relay_2
light:
- platform: binary
name: "T2 L1"
id: light_1
output: relay_1
- platform: binary
name: "T2 L2"
id: light_2
output: relay_2
status_led:
pin:
number: GPIO13
inverted: yes
T3
--
.. code-block:: yaml
esphome:
name: my_t3
esp8266:
board: esp01_1m
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
logger:
api:
ota:
binary_sensor:
- platform: gpio
pin:
number: GPIO0
mode:
input: true
pullup: true
inverted: true
id: button_1
on_press:
then:
- light.toggle: light_1
- platform: gpio
pin:
number: GPIO9
mode:
input: true
pullup: true
inverted: true
id: button_2
on_press:
then:
- light.toggle: light_2
- platform: gpio
pin:
number: GPIO10
mode:
input: true
pullup: true
inverted: true
id: button_3
on_press:
then:
- light.toggle: light_3
- platform: status
name: "T3 Status"
output:
- platform: gpio
pin: GPIO12
id: relay_1
- platform: gpio
pin: GPIO5
id: relay_2
- platform: gpio
pin: GPIO4
id: relay_3
light:
- platform: binary
name: "T3 L1"
id: light_1
output: relay_1
- platform: binary
name: "T3 L2"
id: light_2
output: relay_2
- platform: binary
name: "T3 L3"
id: light_3
output: relay_3
status_led:
pin:
number: GPIO13
inverted: yes
See Also
--------
- :doc:`/cookbook/sonoff-light-switch`
- :doc:`/guides/automations`
- :doc:`/devices/sonoff_t1_uk_3gang_v1.1`

1
images/garage-variant.svg Normal file
View File

@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M22 9V20H20V11H4V20H2V9L12 5L22 9M19 12H5V14H19V12M19 18H5V20H19V18M19 15H5V17H19V15Z" /></svg>
Side by Side

After

Width:  |  Height:  |  Size: 164 B

1
images/head-lightbulb-outline.svg Normal file
View File

@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 3C16.9 3 20 6.1 20 10C20 12.8 18.4 15.2 16 16.3V21H9V18H8C6.9 18 6 17.1 6 16V13H4.5C4.1 13 3.8 12.5 4.1 12.2L6 9.7C6.2 5.9 9.2 3 13 3M13 1C8.4 1 4.6 4.4 4.1 8.9L2.5 11C1.9 11.8 1.9 12.8 2.3 13.6C2.7 14.3 3.3 14.8 4 14.9V16C4 17.9 5.3 19.4 7 19.9V23H18V17.5C20.5 15.8 22 13.1 22 10C22 5 18 1 13 1M14 14H12V13H14V14M15.6 9.5C15.3 9.9 15 10.3 14.5 10.6V12H11.5V10.6C10.1 9.8 9.6 7.9 10.4 6.5S13.1 4.6 14.5 5.4 16.4 8.1 15.6 9.5Z" /></svg>
Side by Side

After

Width:  |  Height:  |  Size: 508 B

11
index.rst
View File

@ -815,14 +815,11 @@ Cookbook
.. imgtable::
Sonoff light switch options, cookbook/sonoff-light-switch, light_switch.png
Garage Door, cookbook/garage-door, window-open.svg
Dual Relay Motor Cover, cookbook/dual-r2-cover, sonoff_dual_r2.jpg
ESP32 Water Leak Detector, cookbook/leak-detector-m5stickC, leak-detector-m5stickC_main_index.jpg
BME280 Environment, cookbook/bme280_environment, bme280.jpg
Lambda Magic: Tips and Tricks, cookbook/lambda_magic, head-lightbulb-outline.svg
Garage Door Template Cover, cookbook/garage-door, garage-variant.svg
Time & Temperature on OLED Display, cookbook/display_time_temp_oled, display_time_temp_oled_2.jpg
Lambda Magic, cookbook/lambda_magic, language-cpp.svg
Endstop Cover, cookbook/endstop-cover, window-open.svg
ESP32 Water Leak Detector, cookbook/leak-detector-m5stickC, leak-detector-m5stickC_main_index.jpg
BME280 Environment extras, cookbook/bme280_environment, bme280.jpg
Non-Invasive Power Meter, cookbook/power_meter, power_meter.jpg
Sonoff Fishpond Pump, cookbook/sonoff-fishpond-pump, cookbook-sonoff-fishpond-pump.jpg
Arduino Port Extender, cookbook/arduino_port_extender, arduino_logo.svg