1# LWS GPIO Button class drivers 2 3Lws provides an GPIO button controller class, this centralizes handling a set of 4up to 31 buttons for resource efficiency. Each controller has two OS timers, 5one for interrupt to bottom-half event triggering and another that runs at 5ms 6intervals only when one or more button is down. 7 8Each button has its own active level control and sophisticated state tracking; 9each button can apply its own classification regime, to allow for different 10physical button characteristics, if not overridden a default one is provided. 11 12Both the controller and individual buttons specify names that are used in the 13JSON events produced when the buttons perform actions. 14 15## Button electronic to logical event processing 16 17Buttons are monitored using GPIO interrupts since this is very cheap in the 18usual case no interaction is ongoing. There is assumed to be one interrupt 19per GPIO, but they are pointed at the same ISR, with an opaque pointer to an 20internal struct passed per-interrupt to differentiate them and bind them to a 21particular button. 22 23The interrupt is set for notification of the active-going edge, usually if 24the button is pulled-up, that's the downgoing edge only. This avoids any 25ambiguity about the interrupt meaning, although oscillation is common around 26the transition region when the signal is becoming inactive too. 27 28An OS timer is used to schedule a bottom-half handler outside of interrupt 29context. 30 31To combat commonly-seen partial charging of the actual and parasitic network 32around the button causing drift and oscillation, the bottom-half briefly drives 33the button signal to the active level, forcing a more deterministic charge level 34if it reached the point the interrupt was triggered. This removes much of the 35unpredictable behaviour in the us range. It would be better done in the ISR 36but many OS apis cannot perform GPIO operations in interrupt context. 37 38The bottom-half makes sure a monitoring timer is enabled, by refcount. This 39is the engine of the rest of the classification while any button is down. The 40monitoring timer happens per OS tick or 5ms, whichever is longer. 41 42## Declaring button controllers 43 44An array of button map elements if provided first mapping at least GPIOs to 45button names, and also optionally the classification regime for that button. 46 47Then the button controller definition which points back to the button map. 48 49``` 50static const lws_button_map_t bcm[] = { 51 { 52 .gpio = GPIO_NUM_0, 53 .smd_interaction_name = "user" 54 }, 55}; 56 57static const lws_button_controller_t bc = { 58 .smd_bc_name = "bc", 59 .gpio_ops = &lws_gpio_plat, 60 .button_map = &bcm[0], 61 .active_state_bitmap = 0, 62 .count_buttons = LWS_ARRAY_SIZE(bcm), 63}; 64 65 struct lws_button_state *bcs; 66 67 bcs = lws_button_controller_create(context, &bc); 68 if (!bcs) { 69 lwsl_err("%s: could not create buttons\n", __func__); 70 goto spin; 71 } 72``` 73 74That is all that is needed for init, button events will be issued on lws_smd 75when buttons are pressed. 76 77### Regime settings 78 79The classification regime is designed to reflect both the user interaction 80style and the characteristics of a particular type of button. 81 82Member|Default|Meaning 83---|---|--- 84ms_min_down|20ms|Down events shorter than this are ignored 85ms_min_down_longpress|300ms|Down events longer than this are reported as a long-click 86ms_up_settle|20ms|After the first indication a button is no longer down, the button is ignored for this interval 87ms_doubleclick_grace|120ms|The time allowed after a click to see if a second, double-click, is forthcoming 88ms_repeat_down|0 / disabled|If held down, interval at which to issue `stilldown` events 89flags|LWSBTNRGMFLAG_CLASSIFY_DOUBLECLICK|Control which classifications can apply 90 91### lws_smd System Message Distribution Events 92 93The button controller emits system messages of class `LWSSMDCL_INTERACTION`, 94using a JSON formatted payload 95 96``` 97{ 98 "type": "button", 99 "src": "controller-name/button-name", 100 "event": "event-name" 101} 102``` 103 104For example, `{"type":"button","src":"bc/user","event":"doubleclick"}` 105 106JSON is used because it is maintainable, extensible, self-documenting and does 107not require a central, fragile-against-versioning specification of mappings. 108Using button names allows the same code to adapt to different hardware or 109button mappings. Button events may be synthesized for test or other purposes 110cleanly and clearly. 111 112All the events are somewhat filtered, too short glitches from EMI or whatever 113are not reported. "up" and "down" events are reported for the buttons in case 114the intention is the duration of the press is meaningful to the user code, but 115more typically the user code wants to consume a higher-level classification of 116the interaction, eg, that it can be understood as a single "double-click" event. 117 118Event name|Meaning 119---|--- 120down|The button passes a filter for being down, useful for duration-based response 121stilldown|The regime can be configured to issue "repeat" notifications at intervals 122up|The button has come up, useful for duration-based response 123click|The button activity resulted in a classification as a single-click 124longclick|The button activity resulted in a classification as a long-click 125doubleclick|The button activity resulted in a classification as a double-click 126 127Since double-click detection requires delaying click reporting until it becomes 128clear a second click isn't coming, it is enabled as a possible classification in 129the regime structure and the regime structure chosen per-button. 130 131Typically user code is interested in, eg, a high level classification of what 132the button is doing, eg, a "click" event on a specific button. Rather than 133perform a JSON parse, these events can be processed as strings cheaply using 134`lws_json_simple_strcmp()`, it's dumb enough to be cheap but smart enough to 135understand enough JSON semantics to be accurate, while retaining the ability to 136change and extend the JSON, eg 137 138``` 139 if (!lws_json_simple_strcmp(buf, len, "\"src\":", "bc/user")) { 140 if (!lws_json_simple_strcmp(buf, len, "\"event\":", "click")) { 141 ... 142 } 143 ... 144 } 145``` 146 147### Relationship between up / down and classification 148 149Classification|Sequencing 150---|--- 151click|down-up-click (it's classified when it went up and cannot be a longclick) 152longclick|down-longclick-up (it's classified while still down) 153doubleclick|down-up-down-doubleclick-up (classified as soon as second click down long enough) 154 155If the regime is configured for it, any "down" may be followed by one or more 156"stilldown" at intervals if the button is down long enough 157