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

added button topic and minor fixes

blakadder 2019-05-07 01:09:29 +02:00
parent ae63e0f12c
commit 60f2133107
1 changed files with 58 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

72
Button-usage.md

@ -1,34 +1,79 @@
If your device has one, the built in hardware push button offers a lot of functionality. Keep in mind that if you [have changed](#Changing-default-button-functionality) [ButtonTopic](commands#buttontopic), [SetOption1](commands#setoption1), [SetOption11](commands#setoption11) or [SetOption13](commands#setoption13) some functionality will be changed or removed.
## Multi press functionality
>If you [have changed](#Changing-default-button-functionality) [ButtonTopic](commands#buttontopic), [SetOption1](commands#setoption1), [SetOption11](commands#setoption11) or [SetOption13](commands#setoption13) some of the listed functionality will be changed or removed.
### 1 short press
Toggles the relay, either directly or by sending a MQTT message like ```cmnd/sonoff/POWER1 ON```. This will blink the LED twice and sends a MQTT status message like ```stat/sonoff/POWER1 ON```. If ```cmnd/sonoff/ButtonRetain on``` has been used the MQTT message will also contain the MQTT retain flag.
Toggles the relay. This will blink the LED twice and send an MQTT status message like ```stat/sonoff/POWER1 ON```. If ```cmnd/sonoff/ButtonRetain on``` has been used the MQTT message will also contain the MQTT retain flag.
### 2 short presses
Toggles the second relay (if available on the device). This will blink the LED twice and sends a MQTT status message like ```stat/sonoff/POWER2 on```.
Toggles the second relay (if available on the device). This will blink the LED twice and send an MQTT status message like ```stat/sonoff/POWER2 on```.
### 3 short presses
Start Wi-Fi smart config allowing for SSID and password configuration using an Android mobile phone with the [ESP8266 SmartConfig](https://play.google.com/store/apps/details?id=com.cmmakerclub.iot.esptouch) app. The LED will blink during the config period. A single button press during this period will abort and restart the device.
Start Wi-Fi smart config allowing for SSID and password configuration using an Android mobile phone with the [ESP8266 SmartConfig](https://play.google.com/store/apps/details?id=com.cmmakerclub.iot.esptouch) app. The LED will blink during the config period. A single button press during this period will abort and restart the device. **Only in sonoff-classic.bin**
### 4 short presses
Start Wi-Fi manager providing an Access Point with IP address 192.168.4.1 and a web server allowing the configuration of Wi-Fi. The LED will blink during the config period. A single button press during this period will abort and restart the device.
### 5 short presses
Start Wi-Fi Protected Setup (WPS) allowing for SSID and password configuration using the router's WPS button or web page. The LED will blink during the config period. A single button press during this period will abort and restart the device.
Start Wi-Fi Protected Setup (WPS) allowing for SSID and password configuration using the router's WPS button or web page. The LED will blink during the config period. A single button press during this period will abort and restart the device. **Only in sonoff-classic.bin**
### 6 short presses
Restart the device.
Restarts the device.
### 7 short presses
Start OTA download of firmware using [OtaUrl](commands#otaurl). The green LED is lit during the update.
Start OTA update of firmware using [OtaUrl](commands#otaurl). The green LED is lit during the update.
### Pressing the button for over 40 seconds
Reset settings to firmware defaults as defined in ```my_user_config.h``` and ```user_config_override.h``` and restart the device.
### **Pressing the button for over 40 seconds**
Resets the device to firmware defaults and restarts it.
>:warning: When a button is configured with a [Switchmode](commands#switchmode) that keeps it as ON while depressed it activates this function.
## [ButtonTopic](Commands#ButtonTopic)
**`ButtonTopic 0`**
> Default option
By default a button controls the corresponding relay and doesn't send any MQTT messages itself.
No MQTT message will be published on account of the new button state. The message you see in console is the new state of the relay that is controlled and not the button state.
**`ButtonTopic 1`**
> Sets MQTT button topic to device %topic%
When changing the state of the button 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 = ON```
*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.
**`ButtonTopic <value>`**
> Set button 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 `ButtonTopic sonoff02`.
*Example: Device topic `sonoff`, `SwitchMode 1`, custom topic `sonoff02` yields the following message.*
```MQT: cmnd/sonoff02/POWER = TOGGLE```
If you have a device with the topic `sonoff02` this action will toggle its relay while not affecting anything on the `sonoff` device.
### In summary
`ButtonTopic 0` controls the relay directly.
`ButtonTopic 1` sends an MQTT message to the device topic. This sets the state of the devices relay accordingly.
`ButtonTopic <value>` sends an MQTT message command to the custom topic. This does not change the state of the devices relay.
## Changing default button functionality
From version 5.1.6 on, hold button functionality for both the push button AND the external push button was implemented.
If a [`ButtonTopic`](commands#buttontopic) (and if [`SetOption1`](commands#SetOption1)`= 1`) or [`SwitchTopic`](commands#SwitchTopic) is defined (and [`SwitchMode`](commands#switchmode)`= 5` or `6`) and a button is pressed longer than defined Key Hold Time ([`SetOption32`](commands#setoption32) default 4 seconds) an MQTT message like `cmnd/%topic%/POWER HOLD` will be sent. `HOLD` can be changed with [`StateText4`](commands#StateText4).
If a [`ButtonTopic`](commands#buttontopic) (and if [`SetOption1`](commands#SetOption1) 1`) or [`SwitchTopic 1`](commands#SwitchTopic) is defined (and [`SwitchMode`](commands#switchmode) is set to `5` or `6`) and a button is pressed longer than defined Key Hold Time ([`SetOption32`](commands#setoption32) default 4 seconds) an MQTT message like `cmnd/%topic%/POWER HOLD` will be sent. `HOLD` can be changed with [`StateText4`](commands#StateText4).
Command [`SetOption11`](commands#setoption11) allows for swapping the functionality of the push button.
@ -44,7 +89,6 @@ If your standard topic of Sonoff Touch is `light` and the ceiling fan topic is `
buttontopic ceilingfan
setoption11 1
```
Taken from the [issue #200](https://github.com/arendst/Sonoff-Tasmota/issues/200#issuecomment-343756826) discussion.
All of the above is easier accomplished using [Rules](Rules)!
[Example using Rules](https://github.com/arendst/Sonoff-Tasmota/wiki/Rules#16-using-an-external-button-with-single-press---double-press-and-hold)