Buttons-and-switches.md

@@ -12,26 +12,30 @@ For example, when modifying boot mode for the first relay - in headers it is def
 
 ESPurna supports up to 8 buttons connected to various GPIO pins. These buttons are defined using C preprocessor flag `BUTTONx_PIN` (x being a number from 1 to 8). Some buttons might be onboard, and you might have the option of connecting some additional, depending on the board you are using.
 
-Each button can operate in number of different modes, configured using `BUTTONx_MODE` flag:
+Each button can operate in number of different modes, configured using `BUTTONx_CONFIG` flag:
 - `BUTTON_PUSHBUTTON` - connected button is of push-button type, possible events are: `pressed`, `released`, `double clicked`, `long clicked` and `long-long clicked`).
 - `BUTTON_SWITCH` - connected button is actually a flip-switch, only reports the `click` event on both transitions.
 
 In addition, each button can have additional options that are logically `ORed` with type of button:
 - `BUTTON_DEFAULT_HIGH` - what should be default state of a button.
 - `BUTTON_SET_PULLUP` - should internal pull-up be enabled for a given GPIO (note that not all GPIOs support pullup)
 
-For example `-DBUTTON3_PIN=2 -DBUTTON3_MODE=4` (4 is the sum of BUTTON_PUSHBUTTON + BUTTON_SET_PULLUP) will configure Button3 on a GPIO02, will treat it as Push-button and will set the internal pull-up.
+For example `-DBUTTON3_PIN=2 -DBUTTON3_CONFIG=9` (9 is the result of BUTTON_PUSHBUTTON | BUTTON_SET_PULLUP, or 0b1001 in binary form) will configure Button3 on a GPIO02, will treat it as Push-button and will set the internal pull-up.
 
-Event codes (as reported via MQTT) are (note that `released` and `click` have the same code but are generated by different types of buttons):
+Event codes (as reported via MQTT) are (note that `released` and `click` have the same code but are generated by different types of buttons)
 
-```
-#define BUTTON_EVENT_NONE 0
-#define BUTTON_EVENT_PRESSED 1
-#define BUTTON_EVENT_RELEASED 2
-#define BUTTON_EVENT_CLICK 2
-#define BUTTON_EVENT_DBLCLICK 3
-#define BUTTON_EVENT_LNGCLICK 4
-#define BUTTON_EVENT_LNGLNGCLICK 5
+As seen in https://github.com/xoseperez/espurna/blob/b289c77021c4d3fcd70feb25ca14178929f31e6c/code/espurna/button.h#L19-L27:
+
+```cpp
+enum class button_event_t {
+ None = 0,
+ Pressed = 1,
+ Click = 2,
+ DoubleClick = 3,
+ LongClick = 4,
+ LongLongClick = 5,
+ TripleClick = 6
+};
 ```
 To every button event an action can be assigned by setting the corresponding value to the button event define. The following button events are available
 ```
@@ -43,31 +47,33 @@ To every button event an action can be assigned by setting the corresponding val
 ```
 To every event, one of the following actions can be assigned:
 ```
-BUTTON_MODE_NONE
-BUTTON_MODE_TOGGLE (-> Toggle relay)
-BUTTON_MODE_ON (-> Turn relay ON)
-BUTTON_MODE_OFF (-> Turn relay OFF)
-BUTTON_MODE_AP (-> Access point mode)
-BUTTON_MODE_RESET (-> Reboot the device)
-BUTTON_MODE_PULSE (-> NOT IMPLEMENTED)
-BUTTON_MODE_FACTORY (-> Erase settings and reboot)
-BUTTON_MODE_WPS (-> Save new WiFi connection settings via WPS)
-BUTTON_MODE_SMART_CONFIG (-> Save new WiFi connection settings via SmartConfig)
-BUTTON_MODE_DIM_UP (-> Lights: increase brightness)
-BUTTON_MODE_DIM_DOWN (-> Lights: decrease brightness)
+BUTTON_ACTION_NONE
+BUTTON_ACTION_TOGGLE (-> Toggle relay)
+BUTTON_ACTION_ON (-> Turn relay ON)
+BUTTON_ACTION_OFF (-> Turn relay OFF)
+BUTTON_ACTION_AP (-> Access point mode)
+BUTTON_ACTION_RESET (-> Reboot the device)
+BUTTON_ACTION_PULSE (-> NOT IMPLEMENTED)
+BUTTON_ACTION_FACTORY (-> Erase settings and reboot)
+BUTTON_ACTION_WPS (-> Save new WiFi connection settings via WPS)
+BUTTON_ACTION_SMART_CONFIG (-> Save new WiFi connection settings via SmartConfig)
+BUTTON_ACTION_DIM_UP (-> Lights: increase brightness)
+BUTTON_ACTION_DIM_DOWN (-> Lights: decrease brightness)
+BUTTON_ACTION_DISPLAY_ON (-> Thermostat: toggle display)
 ```
 
-> NOTE: For button mode `BUTTON_SWITCH`. only the click event is available currently, therefore configuration of other events make no sense.
+> NOTE: For button mode `BUTTON_SWITCH`. only the click event is available currently, therefore configuration of other events will not make any difference.
 
 Button 1 has the following defaults:
 ```
-#define BUTTONx_PRESS BUTTON_MODE_NONE
-#define BUTTONx_CLICK BUTTON_MODE_TOGGLE 
-#define BUTTONx_DBLCLICK BUTTON_MODE_AP
-#define BUTTONx_LNGCLICK BUTTON_MODE_RESET
-#define BUTTONx_LNGLNGCLICK BUTTON_MODE_FACTORY
+#define BUTTONx_PRESS BUTTON_ACTION_NONE
+#define BUTTONx_CLICK BUTTON_ACTION_TOGGLE 
+#define BUTTONx_DBLCLICK BUTTON_ACTION_AP
+#define BUTTONx_LNGCLICK BUTTON_ACTION_RESET
+#define BUTTONx_LNGLNGCLICK BUTTON_ACTION_FACTORY
 ```
-> NOTE: If you plan using button1, please make sure you override these settings. 
+> NOTE: If you plan using button1, please make sure you override these settings.
+> NOTE: You can always test out configuration by setting `btnPress0`, `btnClick0` etc. from runtime with the correct numeric representation of an action.
 
 Buttons 2 to 8 `BUTTONx_CLICK` event is set to ``BUTTON_MODE_TOGGLE``, while every other event is set to ``BUTTON_MODE_NONE``.
 
@@ -76,7 +82,7 @@ Buttons 2 to 8 `BUTTONx_CLICK` event is set to ``BUTTON_MODE_TOGGLE``, while eve
 ESPurna supports up to 8 connected LEDs to various GPIO pins. These LEDs are defined using C preprocessor flag `LEDx_PIN` (x being a number from 1 to 8). Some LEDs might be onboard, and you might have the option of connecting some additional, depending on the board you are using.
 
 Each LED can be bound to a relay state (see below), or operate in one of following modes, defined by `LED_MODE`:
-- `LED_MODE_MQTT`: LED will be managed from MQTT (OFF by default)
+- `LED_MODE_MANUAL`: LED will be managed from MQTT (OFF by default)
 - `LED_MODE_WIFI`: LED will blink according to the WIFI status
 - `LED_MODE_FOLLOW`: LED will follow the state of the linked relay (check `RELAY#_LED`)
 - `LED_MODE_FOLLOW_INVERSE`: LED will follow the opposite state of the linked relay (check `RELAY#_LED`)