This is an old revision of the document!

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

#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);
}

Parameter Table:

Option	Type	Default	Description
id	integer	–	Unique Element ID
virtual_wire	uint8_t	–	ID(s) of the virtual wire(s) assigned
name	string	–	Friendly label
pin	uint8_t	–	GPIO pin number connected to the button
active_low	bool	false	Whether active state is low (true for inverted logic)
pullup	bool	true	Enable internal pull-up resistor
debounce_delay	uint8_t	50	Amount of delay (in milliseconds) used for debouncing.
press_delay	uint16_t	250	Amount of delay (in milliseconds) for determining a short press.
long_press_delay	uint16_t	750	Amount of delay (in milliseconds) for determining a long press.

Property Status Messages:

enum class MOSH_Element_Button_Status

Name	Bit	Description
RESET	0x00	Sent when the switch is first registered.
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	Parameters	Description
onPropertyChange(callback)	Subscribe	❌	callback()	Callback for when the state property changes.
onPriority(callback)	Subscribe	❌	callback()	Similar to `onPropertyChange`, but triggers immediately for high-priority events like button presses, which may affect timing-sensitive behavior.
setActiveLow(bool)	Write	❌	bool	Button is pressed when pulled low
setDebounce(uint16_t)	Write	❌	uint16_t	Set the debounce time in milliseconds
setLongPressDelay(uint16_t)	Write	❌	uint16_t	Set the long-press delay in milliseconds
setName(string)	Write	❌	string	Set a friendly name for the element
setPin(uint8_t)	Write	✅	uint8_t	The pin the button is wired to
setPressDelay(uint16_t)	Write	❌	uint16_t	Set the press delay in milliseconds
setPullup(bool)	Write	❌	bool	Use the internal pullup

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 millis) 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

MOSH Wiki

Table of Contents