From 60f2133107a2d5dca0e4d1fdd150662b58ee92d4 Mon Sep 17 00:00:00 2001 From: blakadder Date: Tue, 7 May 2019 01:09:29 +0200 Subject: [PATCH] added button topic and minor fixes --- Button-usage.md | 72 +++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 58 insertions(+), 14 deletions(-) diff --git a/Button-usage.md b/Button-usage.md index b2424a03..5cb974dc 100644 --- a/Button-usage.md +++ b/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 `** + +> 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 ` 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) \ No newline at end of file