====== Button ======

This page describes the configuration options available for the MOSH button element, including how to define its properties and map them to virtual wires.

The button element reads a digital GPIO pin and reports press, release, and advanced input events such as long press, double press, and short-long combinations.

==== Creating a Button element ====

<code c>
#include <mosh_core.h>
#include <elements/button.h>

MOSH_Core MOSH_Core;

const uint8_t pin = 4
MOSH_Element_Button* myButton = nullptr;

void setup() {
  myButton.monitor(pin);
  MOSH_Core.registerElement(myButton);
}
</code>

==== Parameter Table: ====

|**Option**          |**Type**|**Default**|**Description**|
|active_low          |bool    |false|Whether active state is low (true for inverted logic)|
|debounce_delay      |uint8_t |50   |Amount of delay (in milliseconds) used for debouncing|
|id                  |integer |--   |Unique Element ID|
|long_press_delay    |uint16_t|750  |Amount of delay (in milliseconds) for determining a long press|
|name                |string  |--   |Friendly label|
|pin                 |uint8_t |--   |GPIO pin number connected to the button|
|press_delay         |uint16_t|250  |Amount of delay (in milliseconds) for determining a short press|
|pullup              |bool    |true |Enable internal pull-up resistor|
|stream_on_press     |bool    |false|Sends a stream of PRESS notifications when the button is active|
|stream_on_press_freq|uint16_t|50   |The amount of time between PRESS notifications when stream_on_press is true|
|virtual_wire        |uint8_t |--   |ID of the virtual wire is assigned|
|constant_on         |bool    |false|When 
==== Property Status Messages: ====
<code c>
enum class MOSH_Element_Button_Status
</code>

|**Name**|**Bit**|**Description**|
|RESET|0x00|Reserved for future use.|
|STATE_ON|0x01|Sent when the button is placed in the "pressed" position.|
|STATE_OFF|0x02|Sent when the button is released|
|PRESS|0x03|Sent when the button is pressed and released within the press_delay|
|DOUBLE_PRESS|0x04|Sent when the button is pressed and release twice within the press_delay|
|LONG_PRESS|0x05|Sent after the button is released after being pressed for long_press_delay|
|SHORT_LONG_PRESS|0x06|Sent after a combination of a PRESS and LONG_PRESS|
|USER_DEF1|0xFC|Sent with button_element.send_userdef_1()|
|USER_DEF2|0xFD|Sent with button_element.send_userdef_2()|
|USER_DEF3|0xFE|Sent with button_element.send_userdef_3()|
|USER_DEF4|0xFF|Sent with button_element.send_userdef_4()|

====Static config:====
None

====Setup Methods:====

Methods intended to be called during setup or initialization. These configure how the element behaves and are typically not changed during runtime.

|**Method**|**Direction**|**Required**|**Default**|**Parameters**|**Description**|
|setActiveLow(bool)|Write|❌|true|bool|Button is pressed when pulled low|
|setDebounce(uint16_t)|Write|❌|10|uint16_t|Set the debounce time in milliseconds|
|setLongPressDelay(uint16_t)|Write|❌|750|uint16_t|Set the long-press delay in milliseconds|
|setName(string)|Write|❌|//null//|string|Set a friendly name for the element|
|setPin(uint8_t)|Write|✅|//null//|uint8_t|The pin the button is wired to|
|setPressDelay(uint16_t)|Write|❌|250|uint16_t|Set the press delay in milliseconds|
|setPullup(bool)|Write|❌|true|bool|Use the internal pullup|
|setStreamOnPress(bool)|Write|❌|false|bool|Button will send stream of PRESS events while active|
|setStreamOnPressFreq(uint16_t)|Write|❌|//null//|uint16_t|Sets how frequently a PRESS event is sent during a press stream|
====Runtime Methods: ====

|**Method**|**Direction**|**Parameters**|**returns**|**Description**|
|buttonIsPressed()|Read|--|bool|Returns true if button is pressed, false if not|
|getFriendlyName()|Read|--|string|Returns the friendly name of the element|
|getLastPropertyChange()|Read|--|uint32_t|get the amount of time (in millies) since the last state change)|
|getProperty(name)|Read|friendlyName, state, event, lastChange|PropertyValue|Returns the current value of a property|
|getID()|Read|--|uint8_t|Returns the element's unique ID|
|getName()|Read|--|String|Returns the element's friendly name.|
|send_userdef_1()|User called|--|void|User defined action|
|send_userdef_2()|User called|--|void|User defined action|
|send_userdef_3()|User called|--|void|User defined action|
|send_userdef_4()|User called|--|void|User defined action|