Browse Source
Switched the GPIO matrix driver to debouncing using a simple integrator algorithm. Whenever a key is pressed, we now scan at a rate controlled by debounce-scan-period-ms (default 1 ms) until all keys are released, then return to either waiting for an interrupt or polling more slowly. The timers for key press and release can now be controlled separately, so debounce-period is deprecated in favor of debounce-press-ms and debounce-release-ms. Global Kconfig options ZMK_KSCAN_DEBOUNCE_PRESS_MS and ZMK_KSCAN_DEBOUNCE_RELEASE_MS are also added to make these easier to set. Added documentation for debouncing options.xmkb
Joel Spadin
3 years ago
committed by
Pete Johanson
8 changed files with 348 additions and 64 deletions
@ -0,0 +1,62 @@ |
|||||||
|
/*
|
||||||
|
* Copyright (c) 2021 The ZMK Contributors |
||||||
|
* |
||||||
|
* SPDX-License-Identifier: MIT |
||||||
|
*/ |
||||||
|
|
||||||
|
#include "debounce.h" |
||||||
|
|
||||||
|
static uint32_t get_threshold(const struct debounce_state *state, |
||||||
|
const struct debounce_config *config) { |
||||||
|
return state->pressed ? config->debounce_release_ms : config->debounce_press_ms; |
||||||
|
} |
||||||
|
|
||||||
|
static void increment_counter(struct debounce_state *state, const int elapsed_ms) { |
||||||
|
if (state->counter + elapsed_ms > DEBOUNCE_COUNTER_MAX) { |
||||||
|
state->counter = DEBOUNCE_COUNTER_MAX; |
||||||
|
} else { |
||||||
|
state->counter += elapsed_ms; |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
static void decrement_counter(struct debounce_state *state, const int elapsed_ms) { |
||||||
|
if (state->counter < elapsed_ms) { |
||||||
|
state->counter = 0; |
||||||
|
} else { |
||||||
|
state->counter -= elapsed_ms; |
||||||
|
} |
||||||
|
} |
||||||
|
|
||||||
|
void debounce_update(struct debounce_state *state, const bool active, const int elapsed_ms, |
||||||
|
const struct debounce_config *config) { |
||||||
|
// This uses a variation of the integrator debouncing described at
|
||||||
|
// https://www.kennethkuhn.com/electronics/debounce.c
|
||||||
|
// Every update where "active" does not match the current state, we increment
|
||||||
|
// a counter, otherwise we decrement it. When the counter reaches a
|
||||||
|
// threshold, the state flips and we reset the counter.
|
||||||
|
state->changed = false; |
||||||
|
|
||||||
|
if (active == state->pressed) { |
||||||
|
decrement_counter(state, elapsed_ms); |
||||||
|
return; |
||||||
|
} |
||||||
|
|
||||||
|
const uint32_t flip_threshold = get_threshold(state, config); |
||||||
|
|
||||||
|
if (state->counter < flip_threshold) { |
||||||
|
increment_counter(state, elapsed_ms); |
||||||
|
return; |
||||||
|
} |
||||||
|
|
||||||
|
state->pressed = !state->pressed; |
||||||
|
state->counter = 0; |
||||||
|
state->changed = true; |
||||||
|
} |
||||||
|
|
||||||
|
bool debounce_is_active(const struct debounce_state *state) { |
||||||
|
return state->pressed || state->counter > 0; |
||||||
|
} |
||||||
|
|
||||||
|
bool debounce_is_pressed(const struct debounce_state *state) { return state->pressed; } |
||||||
|
|
||||||
|
bool debounce_get_changed(const struct debounce_state *state) { return state->changed; } |
||||||
@ -0,0 +1,56 @@ |
|||||||
|
/*
|
||||||
|
* Copyright (c) 2021 The ZMK Contributors |
||||||
|
* |
||||||
|
* SPDX-License-Identifier: MIT |
||||||
|
*/ |
||||||
|
|
||||||
|
#pragma once |
||||||
|
|
||||||
|
#include <stdbool.h> |
||||||
|
#include <stdint.h> |
||||||
|
#include <sys/util.h> |
||||||
|
|
||||||
|
#define DEBOUNCE_COUNTER_BITS 14 |
||||||
|
#define DEBOUNCE_COUNTER_MAX BIT_MASK(DEBOUNCE_COUNTER_BITS) |
||||||
|
|
||||||
|
struct debounce_state { |
||||||
|
bool pressed : 1; |
||||||
|
bool changed : 1; |
||||||
|
uint16_t counter : DEBOUNCE_COUNTER_BITS; |
||||||
|
}; |
||||||
|
|
||||||
|
struct debounce_config { |
||||||
|
/** Duration a switch must be pressed to latch as pressed. */ |
||||||
|
uint32_t debounce_press_ms; |
||||||
|
/** Duration a switch must be released to latch as released. */ |
||||||
|
uint32_t debounce_release_ms; |
||||||
|
}; |
||||||
|
|
||||||
|
/**
|
||||||
|
* Debounces one switch. |
||||||
|
* |
||||||
|
* @param state The state for the switch to debounce. |
||||||
|
* @param active Is the switch currently pressed? |
||||||
|
* @param elapsed_ms Time elapsed since the previous update in milliseconds. |
||||||
|
* @param config Debounce settings. |
||||||
|
*/ |
||||||
|
void debounce_update(struct debounce_state *state, const bool active, const int elapsed_ms, |
||||||
|
const struct debounce_config *config); |
||||||
|
|
||||||
|
/**
|
||||||
|
* @returns whether the switch is either latched as pressed or it is potentially |
||||||
|
* pressed but the debouncer has not yet made a decision. If this returns true, |
||||||
|
* the kscan driver should continue to poll quickly. |
||||||
|
*/ |
||||||
|
bool debounce_is_active(const struct debounce_state *state); |
||||||
|
|
||||||
|
/**
|
||||||
|
* @returns whether the switch is latched as pressed. |
||||||
|
*/ |
||||||
|
bool debounce_is_pressed(const struct debounce_state *state); |
||||||
|
|
||||||
|
/**
|
||||||
|
* @returns whether the pressed state of the switch changed in the last call to |
||||||
|
* debounce_update. |
||||||
|
*/ |
||||||
|
bool debounce_get_changed(const struct debounce_state *state); |
||||||
@ -0,0 +1,100 @@ |
|||||||
|
--- |
||||||
|
title: Debouncing |
||||||
|
sidebar_label: Debouncing |
||||||
|
--- |
||||||
|
|
||||||
|
To prevent contact bounce (also known as chatter) and noise spikes from causing |
||||||
|
unwanted key presses, ZMK uses a [cycle-based debounce algorithm](https://www.kennethkuhn.com/electronics/debounce.c), |
||||||
|
with each key debounced independently. |
||||||
|
|
||||||
|
By default the debounce algorithm decides that a key is pressed or released after |
||||||
|
the input is stable for 5 milliseconds. You can decrease this to improve latency |
||||||
|
or increase it to improve reliability. |
||||||
|
|
||||||
|
If you are having problems with a single key press registering multiple inputs, |
||||||
|
you can try increasing the debounce press and/or release times to compensate. |
||||||
|
You should also check for mechanical issues that might be causing the bouncing, |
||||||
|
such as hot swap sockets that are making poor contact. You can try replacing the |
||||||
|
socket or using some sharp tweezers to bend the contacts back together. |
||||||
|
|
||||||
|
## Debounce Configuration |
||||||
|
|
||||||
|
### Global Options |
||||||
|
|
||||||
|
You can set these options in your `.conf` file to control debouncing globally. |
||||||
|
Values must be <= 127. |
||||||
|
|
||||||
|
- `CONFIG_ZMK_KSCAN_DEBOUNCE_PRESS_MS`: Debounce time for key press in milliseconds. Default = 5. |
||||||
|
- `CONFIG_ZMK_KSCAN_DEBOUNCE_RELEASE_MS`: Debounce time for key release in milliseconds. Default = 5. |
||||||
|
|
||||||
|
For example, this would shorten the debounce time for both press and release: |
||||||
|
|
||||||
|
```ini |
||||||
|
CONFIG_ZMK_KSCAN_DEBOUNCE_PRESS_MS=3 |
||||||
|
CONFIG_ZMK_KSCAN_DEBOUNCE_RELEASE_MS=3 |
||||||
|
``` |
||||||
|
|
||||||
|
### Per-driver Options |
||||||
|
|
||||||
|
You can add these Devicetree properties to a kscan node to control debouncing for |
||||||
|
that instance of the driver. Values must be <= 127. |
||||||
|
|
||||||
|
- `debounce-press-ms`: Debounce time for key press in milliseconds. Default = 5. |
||||||
|
- `debounce-release-ms`: Debounce time for key release in milliseconds. Default = 5. |
||||||
|
- ~~`debounce-period`~~: Deprecated. Sets both press and release debounce times. |
||||||
|
- `debounce-scan-period-ms`: Time between reads in milliseconds when any key is pressed. Default = 1. |
||||||
|
|
||||||
|
If one of the global options described above is set, it overrides the corresponding |
||||||
|
per-driver option. |
||||||
|
|
||||||
|
For example, if your board/shield has a kscan driver labeled `kscan0` in its |
||||||
|
`.overlay`, `.dts`, or `.dtsi` files, |
||||||
|
|
||||||
|
```devicetree |
||||||
|
kscan0: kscan { |
||||||
|
compatible = "zmk,kscan-gpio-matrix"; |
||||||
|
... |
||||||
|
}; |
||||||
|
``` |
||||||
|
|
||||||
|
then you could add this to your `.keymap`: |
||||||
|
|
||||||
|
```devicetree |
||||||
|
&kscan0 { |
||||||
|
debounce-press-ms = <3>; |
||||||
|
debounce-release-ms = <3>; |
||||||
|
}; |
||||||
|
``` |
||||||
|
|
||||||
|
This must be placed outside of any blocks surrounded by curly braces (`{...}`). |
||||||
|
|
||||||
|
`debounce-scan-period-ms` determines how often the keyboard scans while debouncing. It defaults to 1 ms, but it can be increased to reduce power use. Note that the debounce press/release timers are rounded up to the next multiple of the scan period. For example, if the scan period is 2 ms and debounce timer is 5 ms, key presses will take 6 ms to register instead of 5. |
||||||
|
|
||||||
|
## Eager Debouncing |
||||||
|
|
||||||
|
Eager debouncing means reporting a key change immediately and then ignoring |
||||||
|
further changes for the debounce time. This eliminates latency but it is not |
||||||
|
noise-resistant. |
||||||
|
|
||||||
|
ZMK does not currently support true eager debouncing, but you can get something |
||||||
|
very close by setting the time to detect a key press to zero and the time to detect |
||||||
|
a key release to a larger number. This will detect a key press immediately, then |
||||||
|
debounce the key release. |
||||||
|
|
||||||
|
```ini |
||||||
|
CONFIG_ZMK_KSCAN_DEBOUNCE_PRESS_MS=0 |
||||||
|
CONFIG_ZMK_KSCAN_DEBOUNCE_RELEASE_MS=5 |
||||||
|
``` |
||||||
|
|
||||||
|
Also consider setting `CONFIG_ZMK_KSCAN_DEBOUNCE_PRESS_MS=1` instead, which adds |
||||||
|
one millisecond of latency but protects against short noise spikes. |
||||||
|
|
||||||
|
## Comparison With QMK |
||||||
|
|
||||||
|
ZMK's default debouncing is similar to QMK's `sym_defer_pk` algorithm. |
||||||
|
|
||||||
|
Setting `CONFIG_ZMK_KSCAN_DEBOUNCE_PRESS_MS=0` for eager debouncing would be similar |
||||||
|
to QMK's (unimplemented as of this writing) `asym_eager_defer_pk`. |
||||||
|
|
||||||
|
See [QMK's Debounce API documentation](https://beta.docs.qmk.fm/using-qmk/software-features/feature_debounce_type) |
||||||
|
for more information. |
||||||
Loading…
Reference in new issue