From 6723b24075abcc903cae1509a111382b1077e206 Mon Sep 17 00:00:00 2001
From: blakadder <blakadder@users.noreply.github.com>
Date: Sat, 23 Feb 2019 12:01:50 +0100
Subject: [PATCH] Merged button usage action matrix

---
 Button-usage.md | 28 ++++++++++++++++++++++++++--
 1 file changed, 26 insertions(+), 2 deletions(-)

diff --git a/Button-usage.md b/Button-usage.md
index 54041185..ab6ae031 100644
--- a/Button-usage.md
+++ b/Button-usage.md
@@ -1,4 +1,4 @@
-If your device has one, the built in hardware push button offers a lot of functionality. Keep in mind that if you have changed [ButtonTopic](commands#buttontopic), [SetOption2](commands#setoption2), [SetOption11](commands#setoption11) or [SetOption13](commands#setoption13) some functionality will be changed or removed.
+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), [SetOption2](commands#setoption2), [SetOption11](commands#setoption11) or [SetOption13](commands#setoption13) some 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.
@@ -24,4 +24,28 @@ Start OTA download of firmware using [OtaUrl](commands#otaurl). The green LED is
 ### 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.
 
-The button is usually connected to `GPIO0` *(NodeMCU pin D3)*
+## 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).
+
+Command [`SetOption11`](commands#setoption11) allows for swapping the functionality of the push button.
+
+These changes result in the following table [(larger image)](https://user-images.githubusercontent.com/5904370/53023433-89cc9600-345d-11e9-8de3-9c89fb7af2f1.png):
+
+![Action matrix](https://user-images.githubusercontent.com/5904370/53023433-89cc9600-345d-11e9-8de3-9c89fb7af2f1.png)
+
+#### Example
+
+You can control a ceiling fan from a Sonoff Touch:<br>
+If your standard topic of Sonoff Touch is `light` and the ceiling fan topic is `ceilingfan` issue these commands on the Sonoff Touch to activate the double press feature.
+```
+buttontopic ceilingfan
+setoption11 1
+```
+
+Taken from the discussion:
+[https://github.com/arendst/Sonoff-Tasmota/issues/200#issuecomment-343756826](https://github.com/arendst/Sonoff-Tasmota/issues/200#issuecomment-343756826)
+
+[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