Merge remote-tracking branch 'qmk/develop' into develop

* qmk/develop: (32 commits)
  [Keyboard] Add macro3 PCB support (qmk#15131)
  [Keyboard] Add layout options, hotswap version to portal 66 (qmk#14719)
  [Keyboard] Add Bourgeau 75% PCB (qmk#15072)
  [Keyboard] Fix bandominedoni via keymap compilation (qmk#15171)
  Fix additional board sizes for RGB Matrix (qmk#15170)
  kb_elmo/m0116_usb: Fix Configurator Key Sequence (qmk#15147)
  Require explicit enabling of RGB Matrix modes (qmk#15018)
  Reimplements WPM feature to be smaller & precise (qmk#13902)
  Add support for deferred executors. (qmk#14859)
  Add needed include to pointing_device.c (qmk#15167)
  Fix uart function prototypes (qmk#15162)
  Rework and expand Pointing Device support (qmk#14343)
  Partially reinstate CI formatting process (qmk#15155)
  kb_elmo/elmopad: fix macro reference in info.json (qmk#15142)
  kb_elmo/m0110a_usb: Fix Configurator Key Sequence (qmk#15143)
  Update UART driver API (qmk#14839)
  Fix hebrew emoji in langs.md (qmk#15140)
  [Keyboard] Add space between Cradio info.json layout (qmk#15127)
  add wait to unicode for win (qmk#15061)
  [Docs] Correct logic of tap hold statement (qmk#14992)
  ...

.github/workflows/format.yaml

@@ -19,7 +19,9 @@ jobs:
     container: qmkfm/qmk_cli
 
     steps:
-    - uses: rlespinasse/github-slug-action@v3.x
+    - name: Install dependencies
+      run: |
+        apt-get update && apt-get install -y dos2unix
 
     - uses: actions/checkout@v2
       with:
@@ -31,12 +33,17 @@ jobs:
         output: ' '
         fileOutput: ' '
 
-    - name: Run qmk format-c and qmk format-python
+    - name: Run qmk formatters
       shell: 'bash {0}'
       run: |
-        qmk format-c --core-only -n $(< ~/files.txt)
-        format_c_exit=$?
-        qmk format-python -n
-        format_python_exit=$?
+        qmk format-c --core-only $(< ~/files.txt)
+        qmk format-python
+        qmk format-text $(< ~/files.txt)
+        git diff
 
-        exit $((format_c_exit + format_python_exit))
+    - name: Fail when formatting required
+      run: |
+        for file in $(git diff --name-only); do
+          echo "::error file=${file}::::File Requires Formatting"
+        done
+        test -z "$(git diff --name-only)"

builddefs/generic_features.mk

@@ -19,6 +19,7 @@ GRAVE_ESC_ENABLE ?= yes
 GENERIC_FEATURES = \
     COMBO \
     COMMAND \
+    DEFERRED_EXEC \
     DIGITIZER \
     DIP_SWITCH \
     DYNAMIC_KEYMAP \

common_features.mk

@@ -107,10 +107,43 @@ ifeq ($(strip $(MOUSEKEY_ENABLE)), yes)
     SRC += $(QUANTUM_DIR)/mousekey.c
 endif
 
+VALID_POINTING_DEVICE_DRIVER_TYPES := adns5050 adns9800 analog_joystick cirque_pinnacle_i2c cirque_pinnacle_spi pmw3360 pimoroni_trackball custom
+POINTING_DEVICE_DRIVER ?= custom
 ifeq ($(strip $(POINTING_DEVICE_ENABLE)), yes)
-    OPT_DEFS += -DPOINTING_DEVICE_ENABLE
-    MOUSE_ENABLE := yes
-    SRC += $(QUANTUM_DIR)/pointing_device.c
+    ifeq ($(filter $(POINTING_DEVICE_DRIVER),$(VALID_POINTING_DEVICE_DRIVER_TYPES)),)
+        $(error POINTING_DEVICE_DRIVER="$(POINTING_DEVICE_DRIVER)" is not a valid pointing device type)
+    else
+        OPT_DEFS += -DPOINTING_DEVICE_ENABLE
+        MOUSE_ENABLE := yes
+        SRC += $(QUANTUM_DIR)/pointing_device.c
+        SRC += $(QUANTUM_DIR)/pointing_device_drivers.c
+        ifneq ($(strip $(POINTING_DEVICE_DRIVER)), custom)
+            SRC += drivers/sensors/$(strip $(POINTING_DEVICE_DRIVER)).c
+            OPT_DEFS += -DPOINTING_DEVICE_DRIVER_$(strip $(shell echo $(POINTING_DEVICE_DRIVER) | tr '[:lower:]' '[:upper:]'))
+        endif
+        OPT_DEFS += -DPOINTING_DEVICE_DRIVER_$(strip $(POINTING_DEVICE_DRIVER))
+        ifeq ($(strip $(POINTING_DEVICE_DRIVER)), adns9800)
+            OPT_DEFS += -DSTM32_SPI -DHAL_USE_SPI=TRUE
+            QUANTUM_LIB_SRC += spi_master.c
+        else ifeq ($(strip $(POINTING_DEVICE_DRIVER)), analog_joystick)
+            OPT_DEFS += -DSTM32_ADC -DHAL_USE_ADC=TRUE
+            LIB_SRC += analog.c
+        else ifeq ($(strip $(POINTING_DEVICE_DRIVER)), cirque_pinnacle_i2c)
+            OPT_DEFS += -DSTM32_I2C -DHAL_USE_I2C=TRUE
+            SRC += drivers/sensors/cirque_pinnacle.c
+            QUANTUM_LIB_SRC += i2c_master.c
+        else ifeq ($(strip $(POINTING_DEVICE_DRIVER)), cirque_pinnacle_spi)
+            OPT_DEFS += -DSTM32_SPI -DHAL_USE_SPI=TRUE
+            SRC += drivers/sensors/cirque_pinnacle.c
+            QUANTUM_LIB_SRC += spi_master.c
+        else ifeq ($(strip $(POINTING_DEVICE_DRIVER)), pimoroni_trackball)
+            OPT_DEFS += -DSTM32_SPI -DHAL_USE_I2C=TRUE
+            QUANTUM_LIB_SRC += i2c_master.c
+        else ifeq ($(strip $(POINTING_DEVICE_DRIVER)), pmw3360)
+            OPT_DEFS += -DSTM32_SPI -DHAL_USE_SPI=TRUE
+            QUANTUM_LIB_SRC += spi_master.c
+        endif
+    endif
 endif
 
 VALID_EEPROM_DRIVER_TYPES := vendor custom transient i2c spi

docs/_langs.md

@@ -3,7 +3,7 @@
   - [:cn: 中文](/zh-cn/)
   - [:es: Español](/es/)
   - [:fr: Français](/fr-fr/)
-  - [:he: עברית](/he-il/)
+  - [:israel: עברית](/he-il/)
   - [:brazil: Português](/pt-br/)
   - [:ru: Русский](/ru-ru/)
   - [:jp: 日本語](/ja/)

docs/config_options.md

@@ -446,6 +446,8 @@ Use these to enable or disable building certain features. The more you have enab
   * Forces the keyboard to wait for a USB connection to be established before it starts up
 * `NO_USB_STARTUP_CHECK`
   * Disables usb suspend check after keyboard startup. Usually the keyboard waits for the host to wake it up before any tasks are performed. This is useful for split keyboards as one half will not get a wakeup call but must send commands to the master.
+* `DEFERRED_EXEC_ENABLE`
+  * Enables deferred executor support -- timed delays before callbacks are invoked. See [deferred execution](custom_quantum_functions.md#deferred-execution) for more information.
 
 ## USB Endpoint Limitations
 

docs/custom_quantum_functions.md

@@ -405,3 +405,69 @@ And you're done.  The RGB layer indication will only work if you want it to. And
 * Keymap: `void eeconfig_init_user(void)`, `uint32_t eeconfig_read_user(void)` and `void eeconfig_update_user(uint32_t val)`
 
 The `val` is the value of the data that you want to write to EEPROM.  And the `eeconfig_read_*` function return a 32 bit (DWORD) value from the EEPROM. 
+
+### Deferred Execution :id=deferred-execution
+
+QMK has the ability to execute a callback after a specified period of time, rather than having to manually manage timers.
+
+#### Deferred executor callbacks
+
+All _deferred executor callbacks_ have a common function signature and look like:
+
+```c
+uint32_t my_callback(uint32_t trigger_time, void *cb_arg) {
+    /* do something */
+    bool repeat = my_deferred_functionality();
+    return repeat ? 500 : 0;
+}
+```
+
+The first argument `trigger_time` is the intended time of execution. If other delays prevent executing at the exact trigger time, this allows for "catch-up" or even skipping intervals, depending on the required behaviour.
+
+The second argument `cb_arg` is the same argument passed into `defer_exec()` below, and can be used to access state information from the original call context.
+
+The return value is the number of milliseconds to use if the function should be repeated -- if the callback returns `0` then it's automatically unregistered. In the example above, a hypothetical `my_deferred_functionality()` is invoked to determine if the callback needs to be repeated -- if it does, it reschedules for a `500` millisecond delay, otherwise it informs the deferred execution background task that it's done, by returning `0`.
+
+?> Note that the returned delay will be applied to the intended trigger time, not the time of callback invocation. This allows for generally consistent timing even in the face of occasional late execution.
+
+#### Deferred executor registration
+
+Once a callback has been defined, it can be scheduled using the following API:
+
+```c
+deferred_token my_token = defer_exec(1500, my_callback, NULL);
+```
+
+The first argument is the number of milliseconds to wait until executing `my_callback` -- in the case above, `1500` milliseconds, or 1.5 seconds.
+
+The third parameter is the `cb_arg` that gets passed to the callback at the point of execution. This value needs to be valid at the time the callback is invoked -- a local function value will be destroyed before the callback is executed and should not be used. If this is not required, `NULL` should be used.
+
+The return value is a `deferred_token` that can consequently be used to cancel the deferred executor callback before it's invoked. If a failure occurs, the returned value will be `INVALID_DEFERRED_TOKEN`. Usually this will be as a result of supplying `0` to the delay, or a `NULL` for the callback. The other failure case is if there are too many deferred executions "in flight" -- this can be increased by changing the limit, described below.
+
+#### Extending a deferred execution
+
+The `deferred_token` returned by `defer_exec()` can be used to extend a the duration a pending execution waits before it gets invoked:
+```c
+// This will re-delay my_token's future execution such that it is invoked 800ms after the current time
+extend_deferred_exec(my_token, 800);
+```
+
+#### Cancelling a deferred execution
+
+The `deferred_token` returned by `defer_exec()` can be used to cancel a pending execution before it gets invoked:
+```c
+// This will cancel my_token's future execution
+cancel_deferred_exec(my_token);
+```
+
+Once a token has been canceled, it should be considered invalid. Reusing the same token is not supported.
+
+#### Deferred callback limits
+
+There are a maximum number of deferred callbacks that can be scheduled, controlled by the value of the define `MAX_DEFERRED_EXECUTORS`.
+
+If registrations fail, then you can increase this value in your keyboard or keymap `config.h` file, for example to 16 instead of the default 8:
+
+```c
+#define MAX_DEFERRED_EXECUTORS 16
+```

docs/feature_led_matrix.md

@@ -166,26 +166,26 @@ You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `con
 
 |Define                                                 |Description                                    |
 |-------------------------------------------------------|-----------------------------------------------|
-|`#define DISABLE_LED_MATRIX_ALPHAS_MODS`               |Disables `LED_MATRIX_ALPHAS_MODS`              |
-|`#define DISABLE_LED_MATRIX_BREATHING`                 |Disables `LED_MATRIX_BREATHING`                |
-|`#define DISABLE_LED_MATRIX_BAND`                      |Disables `LED_MATRIX_BAND`                     |
-|`#define DISABLE_LED_MATRIX_BAND_PINWHEEL`             |Disables `LED_MATRIX_BAND_PINWHEEL`            |
-|`#define DISABLE_LED_MATRIX_BAND_SPIRAL`               |Disables `LED_MATRIX_BAND_SPIRAL`              |
-|`#define DISABLE_LED_MATRIX_CYCLE_LEFT_RIGHT`          |Disables `LED_MATRIX_CYCLE_LEFT_RIGHT`         |
-|`#define DISABLE_LED_MATRIX_CYCLE_UP_DOWN`             |Disables `LED_MATRIX_CYCLE_UP_DOWN`            |
-|`#define DISABLE_LED_MATRIX_CYCLE_OUT_IN`              |Disables `LED_MATRIX_CYCLE_OUT_IN`             |
-|`#define DISABLE_LED_MATRIX_DUAL_BEACON`               |Disables `LED_MATRIX_DUAL_BEACON`              |
-|`#define DISABLE_LED_MATRIX_SOLID_REACTIVE_SIMPLE`     |Disables `LED_MATRIX_SOLID_REACTIVE_SIMPLE`    |
-|`#define DISABLE_LED_MATRIX_SOLID_REACTIVE_WIDE`       |Disables `LED_MATRIX_SOLID_REACTIVE_WIDE`      |
-|`#define DISABLE_LED_MATRIX_SOLID_REACTIVE_MULTIWIDE`  |Disables `LED_MATRIX_SOLID_REACTIVE_MULTIWIDE` |
-|`#define DISABLE_LED_MATRIX_SOLID_REACTIVE_CROSS`      |Disables `LED_MATRIX_SOLID_REACTIVE_CROSS`     |
-|`#define DISABLE_LED_MATRIX_SOLID_REACTIVE_MULTICROSS` |Disables `LED_MATRIX_SOLID_REACTIVE_MULTICROSS`|
-|`#define DISABLE_LED_MATRIX_SOLID_REACTIVE_NEXUS`      |Disables `LED_MATRIX_SOLID_REACTIVE_NEXUS`     |
-|`#define DISABLE_LED_MATRIX_SOLID_REACTIVE_MULTINEXUS` |Disables `LED_MATRIX_SOLID_REACTIVE_MULTINEXUS`|
-|`#define DISABLE_LED_MATRIX_SOLID_SPLASH`              |Disables `LED_MATRIX_SOLID_SPLASH`             |
-|`#define DISABLE_LED_MATRIX_SOLID_MULTISPLASH`         |Disables `LED_MATRIX_SOLID_MULTISPLASH`        |
-|`#define DISABLE_LED_MATRIX_WAVE_LEFT_RIGHT`           |Disables `LED_MATRIX_WAVE_LEFT_RIGHT`          |
-|`#define DISABLE_LED_MATRIX_WAVE_UP_DOWN`              |Disables `LED_MATRIX_WAVE_UP_DOWN`             |
+|`#define ENABLE_LED_MATRIX_ALPHAS_MODS`                |Enables `LED_MATRIX_ALPHAS_MODS`              |
+|`#define ENABLE_LED_MATRIX_BREATHING`                  |Enables `LED_MATRIX_BREATHING`                |
+|`#define ENABLE_LED_MATRIX_BAND`                       |Enables `LED_MATRIX_BAND`                     |
+|`#define ENABLE_LED_MATRIX_BAND_PINWHEEL`              |Enables `LED_MATRIX_BAND_PINWHEEL`            |
+|`#define ENABLE_LED_MATRIX_BAND_SPIRAL`                |Enables `LED_MATRIX_BAND_SPIRAL`              |
+|`#define ENABLE_LED_MATRIX_CYCLE_LEFT_RIGHT`           |Enables `LED_MATRIX_CYCLE_LEFT_RIGHT`         |
+|`#define ENABLE_LED_MATRIX_CYCLE_UP_DOWN`              |Enables `LED_MATRIX_CYCLE_UP_DOWN`            |
+|`#define ENABLE_LED_MATRIX_CYCLE_OUT_IN`               |Enables `LED_MATRIX_CYCLE_OUT_IN`             |
+|`#define ENABLE_LED_MATRIX_DUAL_BEACON`                |Enables `LED_MATRIX_DUAL_BEACON`              |
+|`#define ENABLE_LED_MATRIX_SOLID_REACTIVE_SIMPLE`      |Enables `LED_MATRIX_SOLID_REACTIVE_SIMPLE`    |
+|`#define ENABLE_LED_MATRIX_SOLID_REACTIVE_WIDE`        |Enables `LED_MATRIX_SOLID_REACTIVE_WIDE`      |
+|`#define ENABLE_LED_MATRIX_SOLID_REACTIVE_MULTIWIDE`   |Enables `LED_MATRIX_SOLID_REACTIVE_MULTIWIDE` |
+|`#define ENABLE_LED_MATRIX_SOLID_REACTIVE_CROSS`       |Enables `LED_MATRIX_SOLID_REACTIVE_CROSS`     |
+|`#define ENABLE_LED_MATRIX_SOLID_REACTIVE_MULTICROSS`  |Enables `LED_MATRIX_SOLID_REACTIVE_MULTICROSS`|
+|`#define ENABLE_LED_MATRIX_SOLID_REACTIVE_NEXUS`       |Enables `LED_MATRIX_SOLID_REACTIVE_NEXUS`     |
+|`#define ENABLE_LED_MATRIX_SOLID_REACTIVE_MULTINEXUS`  |Enables `LED_MATRIX_SOLID_REACTIVE_MULTINEXUS`|
+|`#define ENABLE_LED_MATRIX_SOLID_SPLASH`               |Enables `LED_MATRIX_SOLID_SPLASH`             |
+|`#define ENABLE_LED_MATRIX_SOLID_MULTISPLASH`          |Enables `LED_MATRIX_SOLID_MULTISPLASH`        |
+|`#define ENABLE_LED_MATRIX_WAVE_LEFT_RIGHT`            |Enables `LED_MATRIX_WAVE_LEFT_RIGHT`          |
+|`#define ENABLE_LED_MATRIX_WAVE_UP_DOWN`               |Enables `LED_MATRIX_WAVE_UP_DOWN`             |
 
 ## Custom LED Matrix Effects :id=custom-led-matrix-effects