ustd::Switch Class Reference

mupplet-core GPIO Switch class More...

#include <mup_switch.h>

Public Types
enum	Mode {   Default , Rising , Falling , Flipflop ,   Timer , Duration , BinarySensor }

Public Member Functions
	Switch (String name, uint8_t port, Mode mode=Mode::Default, bool activeLogic=false, String customTopic="", int8_t interruptIndex=-1, unsigned long debounceTimeMs=0)
void	setDebounce (long ms)
void	activateCounter (bool bActive)
void	setTimerDuration (unsigned long ms)
void	setMode (Mode newmode, unsigned long duration=0)
void	begin (Scheduler *_pSched)
void	setLogicalState (bool newLogicalState)
void	setStateRefresh (int logicalStateRefreshEverySecs)
void	setToggle ()
void	setPulse ()

Detailed Description

mupplet-core GPIO Switch class

The Switch class allows to integrate switches and buttons in muwerk by either polling GPIOs or by using interrupts. Optional automatic debouncing is provided for both modes, but mostly important for interrupt-mode.

In mode falling or rising, only a 'trigger' event is generated, there is no on or off state. This is useful to implement push-button events.

The mupplet can automatically generate short- and long-press events and provide timing information about length of button presses.

Other options include flip-flop mode and monostable impulses.

Additionally, a binary_sensor mode is available that simply reports the state of the input pin. Note however that there is a simpler implementation of BinarySensor available in the mupplet-sensor project, which is recommended for most use-cases.

The physical hardware of a switch can be overriden by a software setLogicalState, a switch stays in override-mode until the next state change of the physical hardware is detected.

Messages

Messages sent by the switch mupplet:

topic	message body	comment
<mupplet-name>/switch/state	on, off or trigger	switch state, usually on or off. In modes falling and rising only trigger messages are sent on rising or falling signal.
<mupplet-name>/switch/debounce	<time-in-ms>	reply to <mupplet-name>/switch/debounce/get, switch debounce time in ms [0..1000]ms.
<custom-topic>	on, off or trigger	If a custom-topic is given during switch init, an addtional message is publish on switch state changes with that topic, The message is identical to ../switch/state', usually on or off. In modes falling and rising only trigger.
<mupplet-name>/switch/shortpress	trigger	Switch is in duration mode, and button is pressed for less than <shortpress_ms> (default 3000ms).
<mupplet-name>/switch/longpress	trigger	Switch is in duration mode, and button is pressed for less than <longpress_ms> (default 30000ms), yet longer than shortpress.
<mupplet-name>/switch/verylongtpress	trigger	Switch is in duration mode, and button is pressed for longer than <longpress_ms> (default 30000ms).
<mupplet-name>/switch/duration	<ms>	Switch is in duration mode, message contains the duration in ms the switch was pressed.
<mupplet-name>/switch/counter	<count>	If counter was activated (see switch/counter/start msg below, or activateCounter() ), the number of times the switch as been switch logcial on.

Message received by the switch mupplet:

topic	message body	comment
<mupplet-name>/switch/set	on, off, true, false, toggle	Override switch setting. When setting the switch state via message, the hardware port remains overridden until the hardware changes state (e.g. button is physically pressed). Sending a switch/set message puts the switch in override-mode: e.g. when sending switch/set on, the state of the button is signalled on, even so the physical button might be off. Next time the physical button is pressed (or changes state), override mode is stopped, and the state of the actual physical button is published again.
<mupplet-name>/switch/mode/set	default, rising, falling, flipflop, binary_sensor, timer <time-in-ms>, duration [shortpress_ms[,longpress_ms]]	Mode default sends on when a button is pushed, off on release. falling and rising send trigger on corresponding signal change. flipflop changes the state of the logical switch on each change from button on to off. timer keeps the switch on for the specified duration (ms). duration mode sends messages switch/shortpress, if button was pressed for less than <shortpress_ms> (default 3000ms), switch/longpress if pressed less than <longpress_ms>, and switch/verylongpress for longer presses.
<mupplet-name>/switch/debounce/set	<time-in-ms>	String encoded switch debounce time in ms, [0..1000]ms. Default is 20ms. This is especially need, when switch is created in interrupt mode (see comment in example).
<mupplet-name>/switch/state/get		Sends current switch state (logical).
<mupplet-name>/binary_sensor/state/get		Sends current binary_sensor state, for Mode::BinarySensor only, (logical).
<mupplet-name>/switch/counter/get		Send current number of counts, if counter is active, otherwise NaN.
<mupplet-name>/switch/counter/start		Start counter, counter messages will be sent, count is reset to 0. All counters are off by default.
<mupplet-name>/switch/counter/stop		Stop counting

More information: Switch application notes

Member Enumeration Documentation

Mode

enum ustd::Switch::Mode

The mode switch is operating in

Enumerator
Default	Standard mode, changes between on-state (button pressed) and off-state (released)
Rising	Act on level changes LOW->HIGH, generates a 'trigger' message (push-button event)
Falling	Act on level changes HIGH->LOW, generates a 'trigger' message (push-button event)
Flipflop	Each trigger changes state for on to off or vice-versa
Timer	Each trigger generates an on-state for a given time (monostable)
Duration	Timing information is provided: SHORTPRESS, LONGPRESS, VERYLONGPRESS and absolute duration
BinarySensor	Act as binary sensor, reporting state as ../binary_sensor/state instead of ../switch/state

Constructor & Destructor Documentation

Switch()

ustd::Switch::Switch ( String  name, uint8_t  port, Mode  mode = Mode::Default, bool  activeLogic = false, String  customTopic = "", int8_t  interruptIndex = -1, unsigned long  debounceTimeMs = 0  )

inline

Instantiate a muwerk switch

Parameters

name	The name of the switch mupplet, referenced in pub/sub messages
port	GPIO port the switch is connected to.
mode	The Mode of operation of the switch.
activeLogic	'false' indicates that signal level LOW is switch active (default), 'true' indicates that signal level HIGH is switch active.
customTopic	An optional topic string that is sent in addition to the standard <mupplet-name>/switch/state message. Useful to indicate specific usages, e.g. a movement detector connected to the switch input.
interruptIndex	Optional ESP interrupt index 0..15, must be unique in a given system.
debounceTimeMs	Debouncing treshhold, important if used in interrupt mode.

Member Function Documentation

activateCounter()

void ustd::Switch::activateCounter ( bool  bActive )

inline

Start counter and send count messages for each switch activation

Parameters

bActive

On true, the counter is reset to 0, and a message with current count will be send on every switch activation to logical true. false stops counter.

begin()

void ustd::Switch::begin ( Scheduler *  _pSched )

inline

Initialize GPIOs and activate switch hardware

setDebounce()

void ustd::Switch::setDebounce ( long  ms )

inline

Change debounce time

Parameters

ms	New debounce time in ms. In interrupt mode values between 5-20ms are useful.

setLogicalState()

void ustd::Switch::setLogicalState ( bool  newLogicalState )

inline

Temporarily override the physical state of the switch with a software-induced state

The new logical state (which might not reflect the actual hardware) remains in effect until a state-change of the actual hardware is detected.

Parameters

newLogicalState

true: switch is simulated on, false, switch is simulated off.

setMode()

void ustd::Switch::setMode ( Mode  newmode, unsigned long  duration = 0  )

inline

Set the switch into one of the switch Mode

Parameters

newmode	The new Mode
duration	For Mode::Timer: the length in ms the switch stays on on reception of a trigger.

setPulse()

void ustd::Switch::setPulse ( )

inline

Temporarily override the physical state of the switch by simulating a pulse.

The new logical state (which might not reflect the actual hardware) remains in effect until a state-change of the actual hardware is detected.

setStateRefresh()

void ustd::Switch::setStateRefresh ( int  logicalStateRefreshEverySecs )

inline

Periodically publish switch / binary_sensor state every logicalStateRefreshEverySecs seconds

Parameters

logicalStateRefreshEverySecs

Number of seconds after which the current state of a switch is published

setTimerDuration()

void ustd::Switch::setTimerDuration ( unsigned long  ms )

inline

Set the duration of on-state in Mode::Timer

A switch in Mode::Timer stays on for the time of ms, if a trigger is received.

Parameters

ms	time in ms.

setToggle()

void ustd::Switch::setToggle ( )

inline

Temporarily override the physical state of the switch by toggling the current state.

The new logical state (which might not reflect the actual hardware) remains in effect until a state-change of the actual hardware is detected.

---

The documentation for this class was generated from the following file:

• src/mup_switch.h