libwebsockets/lib/drivers/button/README.md

# LWS GPIO Button class drivers

Lws provides an GPIO button controller class, this centralizes handling a set of
up to 31 buttons for resource efficiency.  Each controller has two OS timers,
one for interrupt to bottom-half event triggering and another that runs at 5ms
intervals only when one or more button is down.

Each button has its own active level control and sophisticated state tracking;
each button can apply its own classification regime, to allow for different
physical button characteristics, if not overridden a default one is provided.

Both the controller and individual buttons specify names that are used in the
JSON events produced when the buttons perform actions.

## Button electronic to logical event processing

Buttons are monitored using GPIO interrupts since this is very cheap in the
usual case no interaction is ongoing.  There is assumed to be one interrupt
per GPIO, but they are pointed at the same ISR, with an opaque pointer to an
internal struct passed per-interrupt to differentiate them and bind them to a
particular button.

The interrupt is set for notification of the active-going edge, usually if
the button is pulled-up, that's the downgoing edge only.  This avoids any
ambiguity about the interrupt meaning, although oscillation is common around
the transition region when the signal is becoming inactive too.

An OS timer is used to schedule a bottom-half handler outside of interrupt
context.

To combat commonly-seen partial charging of the actual and parasitic network
around the button causing drift and oscillation, the bottom-half briefly drives
the button signal to the active level, forcing a more deterministic charge level
if it reached the point the interrupt was triggered.  This removes much of the
unpredictable behaviour in the us range.  It would be better done in the ISR
but many OS apis cannot perform GPIO operations in interrupt context.

The bottom-half makes sure a monitoring timer is enabled, by refcount.  This
is the engine of the rest of the classification while any button is down.  The
monitoring timer happens per OS tick or 5ms, whichever is longer.

## Declaring button controllers

An array of button map elements if provided first mapping at least GPIOs to
button names, and also optionally the classification regime for that button.

Then the button controller definition which points back to the button map.

```
static const lws_button_map_t bcm[] = {
	{
		.gpio			= GPIO_NUM_0,
		.smd_interaction_name	= "user"
	},
};

static const lws_button_controller_t bc = {
	.smd_bc_name			= "bc",
	.gpio_ops			= &lws_gpio_plat,
	.button_map			= &bcm[0],
	.active_state_bitmap		= 0,
	.count_buttons			= LWS_ARRAY_SIZE(bcm),
};

	struct lws_button_state *bcs;

	bcs = lws_button_controller_create(context, &bc);
	if (!bcs) {
		lwsl_err("%s: could not create buttons\n", __func__);
		goto spin;
	}
```

That is all that is needed for init, button events will be issued on lws_smd
when buttons are pressed.

### Regime settings

The classification regime is designed to reflect both the user interaction
style and the characteristics of a particular type of button.

Member|Default|Meaning
---|---|---
ms_min_down|20ms|Down events shorter than this are ignored
ms_min_down_longpress|300ms|Down events longer than this are reported as a long-click
ms_up_settle|20ms|After the first indication a button is no longer down, the button is ignored for this interval
ms_doubleclick_grace|120ms|The time allowed after a click to see if a second, double-click, is forthcoming
ms_repeat_down|0 / disabled|If held down, interval at which to issue `stilldown` events
flags|LWSBTNRGMFLAG_CLASSIFY_DOUBLECLICK|Control which classifications can apply

### lws_smd System Message Distribution Events

The button controller emits system messages of class `LWSSMDCL_INTERACTION`,
using a JSON formatted payload

```
{
	"type":  "button",
	"src":   "controller-name/button-name",
	"event": "event-name"
}
```

For example, `{"type":"button","src":"bc/user","event":"doubleclick"}`

JSON is used because it is maintainable, extensible, self-documenting and does
not require a central, fragile-against-versioning specification of mappings.
Using button names allows the same code to adapt to different hardware or
button mappings.  Button events may be synthesized for test or other purposes
cleanly and clearly.

All the events are somewhat filtered, too short glitches from EMI or whatever
are not reported.  "up" and "down" events are reported for the buttons in case
the intention is the duration of the press is meaningful to the user code, but
more typically the user code wants to consume a higher-level classification of
the interaction, eg, that it can be understood as a single "double-click" event. 

Event name|Meaning
---|---
down|The button passes a filter for being down, useful for duration-based response
stilldown|The regime can be configured to issue "repeat" notifications at intervals
up|The button has come up, useful for duration-based response
click|The button activity resulted in a classification as a single-click
longclick|The button activity resulted in a classification as a long-click
doubleclick|The button activity resulted in a classification as a double-click

Since double-click detection requires delaying click reporting until it becomes
clear a second click isn't coming, it is enabled as a possible classification in
the regime structure and the regime structure chosen per-button.

Typically user code is interested in, eg, a high level classification of what
the button is doing, eg, a "click" event on a specific button.  Rather than
perform a JSON parse, these events can be processed as strings cheaply using
`lws_json_simple_strcmp()`, it's dumb enough to be cheap but smart enough to
understand enough JSON semantics to be accurate, while retaining the ability to
change and extend the JSON, eg

```
	if (!lws_json_simple_strcmp(buf, len, "\"src\":", "bc/user")) {
		if (!lws_json_simple_strcmp(buf, len, "\"event\":", "click")) {
			...
		}
		...
	}
```

### Relationship between up / down and classification

Classification|Sequencing
---|---
click|down-up-click (it's classified when it went up and cannot be a longclick)
longclick|down-longclick-up (it's classified while still down)
doubleclick|down-up-down-doubleclick-up (classified as soon as second click down long enough)

If the regime is configured for it, any "down" may be followed by one or more
"stilldown" at intervals if the button is down long enough