mirrors
/
Tasmota
mirror of https://github.com/arendst/Tasmota.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

new article

blakadder 2019-05-07 01:16:01 +02:00
parent e676ed270c
commit 6134ea9042
1 changed files with 131 additions and 99 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

228
Buttons-and-Switches.md

@ -1,137 +1,169 @@
# Introduction
Tasmota supports connecting push-buttons and switches. In addition to the push-button available on some modules, additional push-buttons and switches can be connected to GPIO pins.
Buttons and switches are primarily used to toggle (turn ON or OFF) device relays.
As an example, the standard Sonoff device has a relay to turn on/off an external device and a button to toggle the state of the relay. Additional "Buttons" or "Switches" can be configured using the [[Gpio Command|Commands#gpio]]. (See [[GPIO-Locations]] for how to connect to these GPIO's.)
A standard device usually has at least one button (exception being bulbs and some lights) to control the relay(s).
# Button or Switch
The Tasmota software distinguishes between "Button" and "Switch" in the following manner:
- Button
- Suitable for mechanical push-button (suitable for touch button when [`SetOption13`](Commands#setoption13) is set to `1`)
- Supports single-click, double-click and long press actions
- Supports special action, e.g. factory reset, WIFI setup etc if the button is pressed repeatedly or held for a long time
- Switch
- Suitable for [mechanical push-button](https://en.wikipedia.org/wiki/Push-button), [touch button](https://en.wikipedia.org/wiki/Touch_switch) and [mechanical toggle switch](https://en.wikipedia.org/wiki/Switch#Toggle_switch)
Additional buttons and switches can be [wired](Expanding-Sonoffs#connect-switch) to a free GPIO and configured in Module or Template settings.
# Switch configuration
Video tutorial: [Tasmota SwitchMode Explained](https://www.youtube.com/watch?v=kiXAGkyqFeU) by Dr Zzs
> Tasmota does not publish the state of the switch in any way.
It only sends commands directly to the corresponding relay or to an MQTT topic.
By default the configuration for a "switch" is like this:
## Button vs. Switch
A button (also called a push-button) is a momentary or non-latching switch which causes a temporary change in the state of an electrical circuit only while the switch is pressed. An automatic mechanism (i.e. a spring) returns the switch to its default position immediately afterwards, restoring the initial circuit condition.
`SwitchMode 0` (Set switch mode to TOGGLE) - every time the button gets pressed the relay changes its state (on/off).
A switch (more precisely a latching switch), when activated by the user, remains in that state until activated again.
`SwitchTopic<x> 0` (Disable use of MQTT switch topic) Does not publish an MQTT message to the switch topictopic. Instead the relay will be controlled directly. Once the relay changes its state the firmware will publish an MQTT message with the new state.
Both have a similar function but Tasmota distinguishes between a "Button" and a "Switch" in other ways.
# Button
<img align=right src="https://user-images.githubusercontent.com/5904370/57244172-2273ba80-7038-11e9-89ce-49ef46cb36d6.png" width=100>
Tasmota `Button` is normally the button supplied on the device. In most cases it is a momentary push-button (capacitive touch button in wall switches).
e.g.: `stat/sonoff01/POWER ON`
By default a button toggles the corresponding relay. Every time the button gets pressed the relay changes `Power` state (ON or OFF).
**Important**:
The Sonoff-Tasmota firmware does not publish the state of the switch in any way! It only send commands (directly to the corresponding relay or via MQTT to a topic).
Besides toggling the `Power` state, a button is also used to activate [multi press button functions](Button-usage#multi-press-functions):
See [Button-usage](Button-usage) on a detailed multi press function list, ButtonTopic options and changing default Button functionality.
# Switch
<img align=right src="https://user-images.githubusercontent.com/5904370/57244373-84ccbb00-7038-11e9-85a9-3af6531c9f6d.png" width=100>
In Tasmota a `Switch` is any switch or push-button additionally connected to a free GPIO. Some possibilities include:
- [mechanical toggle switch](https://en.wikipedia.org/wiki/Switch#Toggle_switch) - also called a rocker switch
- [capacitive touch switch](https://en.wikipedia.org/wiki/Touch_switch)
- [reed switch](https://en.wikipedia.org/wiki/Reed_switch)
- [PIR sensor](https://en.wikipedia.org/wiki/Passive_infrared_sensor) - even though its technically a sensor it is configured as a switch in Tasmota
- [mechanical push-button](https://en.wikipedia.org/wiki/Push-button)
By default a switch toggles the corresponding relay. Every time the switch gets pressed the relay changes its state (ON or OFF).
Apart from the default toggling of the relay, switches can be configured to do long press (HOLD) actions, send messages to different MQTT topics or commands to other Tasmota devices.
> Now to make everything a little confusing:
>
>A built in push-button can be configured as a Switch and a toggle switch can be configured as a Button. We don't recommend to do so, but it is entirely possible!
## Switch and button usage
## [SwitchMode](Commands#switchmode)
> For visual learners: [Tasmota Switchmode Explained](https://www.youtube.com/watch?v=kiXAGkyqFeU) - video by Dr Zzs
You can change the mode for a switch by executing a [command](Commands#switchmode) in the web console, via HTTP, via MQTT or via serial.
To change the mode of the switch use [`SwitchMode`](Commands#switchmode) command.
### SwitchMode 1 and 2
**`SwitchMode 0`**
```Default Tasmota switch mode (0 = toggle, 1 = toggle)```
Same behaviour as `SwitchMode 7`
**`SwitchMode 1`**
Set switch mode to FOLLOW (0 = Off, 1 = On)
While pressing the button/switch (closing the circuit) the button will send `ON` (directly or via MQTT depending on [SwitchTopic](Commands#switchmode)) and `OFF` when released (open circuit).
```Set switch to follow mode (0 = OFF, 1 = ON)```
While pressing the switch (closing the circuit) the button will send `ON` and when released (open circuit) send `OFF` .
**`SwitchMode 2`**
Set switch mode to inverted FOLLOW (0 = On, 1 = Off)
```Set switch to inverted follow mode (0 = ON, 1 = OFF)```
The opposite of Mode 1.
While pressing the switch (closing the circuit) the button will send `OFF` and when released (open circuit) send `ON` .
#### Conclusion
You probably want to use `SwitchMode 1` when connecting a [toggle switch](https://en.wikipedia.org/wiki/Switch#Toggle_switch) to your Sonoff device. This way the 'software switch' will have the same state as the 'hardware switch'.
If the real switch is in the "on" position, the state of the software switch is `ON` as well.
### SwitchMode 3 and 4
> You want to use `SwitchMode 1` when connecting a [toggle switch](https://en.wikipedia.org/wiki/Switch#Toggle_switch) to your device (e.g. a classic light switch). This way the "software switch" will mirror the state of the "hardware switch".
If the real switch is in the "ON" position, the state in Tasmota is `ON` as well.
**`SwitchMode 3`**
Set switch mode to PUSHBUTTON (Normally 1, 0 = toggle)
```Set switch to push-button mode (Default 1 = ON, 0 = toggle)```
The switch will send a command (directly or via MQTT) when the switch opens the circuit (`OFF`). When closing the circuit (`ON`), nothing will happen.
The switch will send a toggle command when the switch is released (opening the circuit). When pressing the switch (closing the circuit) nothing will happen. Default switch state is ON and when pressed its OFF.
**`SwitchMode 4`**
Set switch mode to inverted PUSHBUTTON (Normally 0, 1 = toggle)
```Set switch to inverted push-button mode (Default 0 = OFF, 1 = toggle)```
The switch will send a command when changing to `ON`. Nothing happens when changing to `OFF`.
The switch will send a toggle command when pressing switch (closing the circuit). When the switch is released (opening the circuit) nothing will happen. Default switch state is OFF and when pressed its ON.
#### Conclusion
>When connecting a [momentary switch](https://en.wikipedia.org/wiki/Switch#Biased_switches) (a push-button) you will want to use `SwitchMode 3` or `SwitchMode 4`.
When connecting a [momentary switch](https://en.wikipedia.org/wiki/Switch#Biased_switches) (a push button) you want to use `SwitchMode 3` or `SwitchMode 4`.
`SwitchMode 4` is the same as the default behavior (`SwitchMode 0`) for Sonoff devices.
**`SwitchMode 5`**
```Set switch to push-button with long press mode (Default 1 = ON, 0 = toggle, long press = HOLD )```
The switch will send a toggle command when the switch is released (opening the circuit). When pressing the switch (closing the circuit) nothing will happen. Default switch state is ON and when pressed its OFF.
When held for time set in `SetOption32` (default = 4s) sends HOLD message (Use Switch<x>#state=3 in rules).
**`SwitchMode 6`**
```Set switch to inverted push-button with long press mode (Default 0 = OFF, 1 = toggle, long press = HOLD )```
The switch will send a toggle command when pressed (closing the circuit). When the switch is released (opening the circuit) nothing will happen. Default switch state is OFF and when pressed its ON.
When held for time set in `SetOption32` (default = 4s) sends HOLD message (Use Switch<x>#state=3 in rules).
>Long press or hold can be used in [conjunction with rules](rules) to create additional features or to control another Tasmota device.
**`SwitchMode 7`**
```Set switch to toggle PUSHBUTTON (0 = toggle, 1 = toggle)```
The switch will send a toggle command when pressed and another toggle command when released.
>`SwitchMode 7` has the same behaviour as the default `SwitchMode 0`*
## [SwitchTopic](Commands#switchtopic)
SwitchTopic and ButtonTopic are almost identical in use. Read [ButtonTopic](Button-usage#ButtonTopic) for its guide.
### Note about SwitchTopic and MQTT
**`SwitchTopic<x> 0`**
When using `SwitchTopic 1` or `2` and your MQTT broker becomes unavailable, Tasmota falls back to default `SwitchTopic 0`, which is not optimal.
Disable use of MQTT switch topic
No MQTT message will be published on account of the new switch state. The message you see in MQTT is the new state of the relay that gets changed, like explained above.
e.g.: `stat/sonoff01/POWER ON`
**`SwitchTopic<x> 1`**
Set MQTT switch topic to device MQTT Topic
When changing the state of the switch (depending on the `SwitchMode`) an MQTT command gets send via MQTT. This command will have the topic defined as the default topic of the Sonoff device.
e.g.: `cmnd/sonoff01/POWER ON` (Notice the `cmnd` instead of the `stat` at the beginning.)
This command will be received by the device itself and the relay will be set to the defined state. Just like receiving the same command from any other MQTT source.
**`SwitchTopic<x> 2`**
Set MQTT switch topic to firmware default `MQTT_SWITCH_TOPIC`. Typically `MQTT_SWITCH_TOPIC` is set to `0` unless you compile your own firmware and change this value in `user_config_override.h`. If `MQTT_SWITCH_TOPIC` is set to a string, then this command will have the same behavior as outlined below.
**`SwitchTopic<x> <value>`**
Set MQTT switch topic (32 chars max)
This will send a MQTT message with a user-defined topic.
Whether this message will trigger anything depends on the setup of the user.
For example, when setting the topic to `sonoff2` this could trigger the relay on the Sonoff device that listens to messages with this specific topic.
### Use case
To trigger something within your smart home automation hub you can define the `SwitchTopic<x>` to `sonoff01-switch1` (for example).
This will send a message like this: `cmnd/sonoff01-switch1/POWER ON`
In [openHAB](openhab) you define an item that subscribes to this topic and sets its state according to the message content.
```java
Switch Sonoff01_Switch1 "Sonoff01 Switch1 [%s]" <switch> { mqtt="<[mosquitto:cmnd/sonoff01-switch1/POWER1:state:default]" }
```
### Conclusion
`SwitchTopic<x> 0` controls the relay directly.
`SwitchTopic<x> 1` sends a message with the default device topic to MQTT. This message will get picked up by the device itself and sets the state of the relay accordingly.
`SwitchTopic<x> <value>` sends a command with a custom topic of `<value>` via MQTT. This will not get picked up unless you configure any device to subscribe to this topic.
[Examples with Rules](Rules#16-using-an-external-button-with-single-press---double-press-and-hold)
### ⚠️ MQTT broker not available ⚠️
When using `SwitchTopic<x> <value>` and the MQTT broker is not available, Tasmota falls back using `SwitchTopic<x> 0`.
To prevent this, a rule like the following can be set:
To avoid this, instead of `SwitchTopic`, we recommend using this rule which works always.
```
rule1
rule1 on switch1#state=1 do publish YOUR-CUSTOM-SWITCH-TOPIC ON endon
rule1 on
Rule1 on switch1#state do publish cmnd/custom-topic/POWER %value% endon
Rule1 1
```
If you still need to use SwitchTopic, read on!
**`SwitchTopic 0`**
> Default option
By default a switch controls the corresponding relay and doesn't send any MQTT messages itself.
No MQTT message will be published on account of the new switch state. The message you see in console is the new state of the relay that is controlled and not the switch state.
**`SwitchTopic 1`**
> Sets MQTT switch topic to device %topic%
When changing the state of the switch an MQTT message is sent to the device topic with the payload according to `SwitchMode` set.
*Example: Device topic `sonoff`, `SwitchMode 3` yields the following message.*
```MQT: cmnd/sonoff/POWER = TOGGLE```
*Notice the ***`cmnd`*** instead of the `stat` at the beginning.*
This is the same as sending an MQTT commands to this device, the device relay will be set to the defined state.
**`SwitchTopic <value>`**
> Set switch topic to a custom topic (32 characters max)
This will send an MQTT message to a custom defined topic similarly to option 1.
For example, we set the topic to `sonoff02` with `SwitchTopic sonoff02`.
*Example: Device topic `sonoff`, `SwitchMode 1`, custom topic `sonoff02` yields the following message.*
```MQT: cmnd/sonoff02/POWER = ON```
If you have a device with the topic `sonoff02` this action will turn on its relay while not affecting anything on the `sonoff` device.
### In summary
`SwitchTopic 0` controls the relay directly.
`SwitchTopic 1` sends an MQTT message to the device topic. This sets the state of the devices relay accordingly.
`SwitchTopic <value>` sends an MQTT message command to the custom topic. This does not change the state of the devices relay.