(for v0.4) Add a way to jump to bootloader and/or reset settings on startup

app/CMakeLists.txt

@@ -30,6 +30,7 @@ target_sources(app PRIVATE src/behavior.c)
 target_sources_ifdef(CONFIG_ZMK_KSCAN_SIDEBAND_BEHAVIORS app PRIVATE src/kscan_sideband_behaviors.c)
 target_sources(app PRIVATE src/matrix_transform.c)
 target_sources(app PRIVATE src/physical_layouts.c)
+target_sources(app PRIVATE src/reset.c)
 target_sources(app PRIVATE src/sensors.c)
 target_sources_ifdef(CONFIG_ZMK_WPM app PRIVATE src/wpm.c)
 target_sources(app PRIVATE src/event_manager.c)

app/Kconfig

@@ -704,6 +704,15 @@ config ZMK_KEYMAP_SENSORS_DEFAULT_TRIGGERS_PER_ROTATION
 
 endif # ZMK_KEYMAP_SENSORS
 
+config ZMK_BOOT_MAGIC_COMBO
+    bool "Enable actions when keys are held at boot"
+    default y
+    depends on DT_HAS_ZMK_BOOT_MAGIC_COMBO_ENABLED
+
+config ZMK_BOOT_MAGIC_COMBO_TIMEOUT_MS
+    int "Milliseconds to wait for a boot magic combo at startup"
+    default 500
+
 module = ZMK
 module-str = zmk
 source "subsys/logging/Kconfig.template.log_config"

app/dts/behaviors/reset.dtsi

@@ -18,7 +18,7 @@
         // Behavior can be invoked on peripherals, so name must be <= 8 characters.
         bootloader: bootload {
             compatible = "zmk,behavior-reset";
-            type = <RST_UF2>;
+            type = <ZMK_RESET_BOOTLOADER>;
             bootloader;
             #binding-cells = <0>;
             display-name = "Bootloader";

app/dts/bindings/zmk,boot-magic-combo.yaml

@@ -0,0 +1,23 @@
+# Copyright (c) 2026, The ZMK Contributors
+# SPDX-License-Identifier: MIT
+
+description: |
+  Triggers one or more actions if a combination of keys is held while the keyboard boots.
+  This is typically used for recovering a keyboard in cases such as &bootloader
+  being missing from the keymap or a split peripheral which isn't connected to
+  the central, and therefore can't process the keymap.
+
+compatible: "zmk,boot-magic-combo"
+
+properties:
+  combo-positions:
+    type: array
+    required: true
+    description: Zero-based indices of the keys which must be simultaneously pressed to trigger the action(s).
+  # Boot magic actions:
+  jump-to-bootloader:
+    type: boolean
+    description: Reboots into the bootloader.
+  reset-settings:
+    type: boolean
+    description: Clears settings and reboots.

app/dts/bindings/zmk,physical-layout.yaml

@@ -27,3 +27,6 @@ properties:
   keys:
     type: phandle-array
     description: Array of key physical attributes.
+  boot-magic-combos:
+    type: phandles
+    description: List of combos specific to this layout that enter bootloader or reset settings when held during boot.

app/include/dt-bindings/zmk/reset.h

@@ -4,10 +4,6 @@
  * SPDX-License-Identifier: MIT
  */
 
-#define RST_WARM 0x00
-#define RST_COLD 0x01
-
-// AdaFruit nrf52 Bootloader Specific. See
-// https://github.com/adafruit/Adafruit_nRF52_Bootloader/blob/d6b28e66053eea467166f44875e3c7ec741cb471/src/main.c#L107
-
-#define RST_UF2 0x57
+#define ZMK_RESET_WARM 0
+#define ZMK_RESET_COLD 1
+#define ZMK_RESET_BOOTLOADER 2

app/include/zmk/ble.h

@@ -40,7 +40,7 @@ bool zmk_ble_active_profile_is_open(void);
 bool zmk_ble_active_profile_is_connected(void);
 char *zmk_ble_active_profile_name(void);
 
-int zmk_ble_unpair_all(void);
+void zmk_ble_unpair_all(void);
 
 int zmk_ble_set_device_name(char *name);
 

app/include/zmk/boot_magic.h

@@ -0,0 +1,24 @@
+/*
+ * Copyright (c) 2026 The ZMK Contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#pragma once
+
+#include <zephyr/types.h>
+#include <stdbool.h>
+#include <zephyr/sys/util.h>
+
+struct zmk_boot_magic_combo_config {
+    const uint16_t *combo_positions;
+    uint8_t combo_positions_len;
+    bool jump_to_bootloader;
+    bool reset_settings;
+    bool *state;
+};
+
+#define ZMK_BOOT_MAGIC_COMBO_CONFIG_NAME(node_id) _CONCAT(zmk_boot_magic_combo_config_, node_id)
+
+#define ZMK_BOOT_MAGIC_COMBO_CONFIG_DECLARE(node_id)                                               \
+    extern const struct zmk_boot_magic_combo_config ZMK_BOOT_MAGIC_COMBO_CONFIG_NAME(node_id)

app/include/zmk/physical_layouts.h

@@ -9,6 +9,7 @@
 #include <zephyr/kernel.h>
 #include <zmk/matrix_transform.h>
 #include <zmk/event_manager.h>
+#include <zmk/boot_magic.h>
 
 struct zmk_physical_layout_selection_changed {
     uint8_t selection;
@@ -39,6 +40,9 @@ struct zmk_physical_layout {
 
     const struct zmk_key_physical_attrs *keys;
     size_t keys_len;
+
+    const struct zmk_boot_magic_combo_config *const *boot_magic_combos;
+    size_t boot_magic_combos_len;
 };
 
 #define ZMK_PHYS_LAYOUTS_FOREACH(_ref) STRUCT_SECTION_FOREACH(zmk_physical_layout, _ref)
@@ -62,4 +66,4 @@ int zmk_physical_layouts_get_position_map(uint8_t source, uint8_t dest, size_t m
  * @retval a negative errno value in the case of errors
  * @retval a positive length of the position map array that map is updated to point to.
  */
-int zmk_physical_layouts_get_selected_to_stock_position_map(uint32_t const **map);
+int zmk_physical_layouts_get_selected_to_stock_position_map(uint32_t const **map);

app/include/zmk/reset.h

@@ -0,0 +1,25 @@
+/*
+ * Copyright (c) 2023 The ZMK Contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#pragma once
+
+#include <zephyr/toolchain.h>
+#include <dt-bindings/zmk/reset.h>
+
+/**
+ * Reboot the system.
+ * @param type If CONFIG_RETENTION_BOOT_MODE is set: A BOOT_MODE_TYPE_* value indicating which type
+ * of reboot. Otherwise, A ZMK_RESET_* value indicating how to reboot.
+ */
+void zmk_reset(int type);
+
+/**
+ * Clear all persistent settings.
+ *
+ * This should typically be followed by a call to zmk_reset() to ensure that
+ * all subsystems are properly reset.
+ */
+void zmk_reset_settings(void);

app/src/behaviors/behavior_reset.c

@@ -7,12 +7,12 @@
 #define DT_DRV_COMPAT zmk_behavior_reset
 
 #include <zephyr/device.h>
-#include <zephyr/sys/reboot.h>
 #include <zephyr/logging/log.h>
 
 #include <drivers/behavior.h>
 
 #include <zmk/behavior.h>
+#include <zmk/reset.h>
 
 #if IS_ENABLED(CONFIG_RETENTION_BOOT_MODE)
 
@@ -37,19 +37,10 @@ static int on_keymap_binding_pressed(struct zmk_behavior_binding *binding,
     const struct behavior_reset_config *cfg = dev->config;
 
 #if IS_ENABLED(CONFIG_RETENTION_BOOT_MODE)
-    int ret = bootmode_set(cfg->boot_mode);
-    if (ret < 0) {
-        LOG_ERR("Failed to set the bootloader mode (%d)", ret);
-        return ZMK_BEHAVIOR_OPAQUE;
-    }
-
-    sys_reboot(SYS_REBOOT_WARM);
+    zmk_reset(cfg->boot_mode);
 #else
-    // See
-    // https://github.com/adafruit/Adafruit_nRF52_Bootloader/blob/d6b28e66053eea467166f44875e3c7ec741cb471/src/main.c#L107
-    sys_reboot(cfg->type);
+    zmk_reset(cfg->type);
 #endif /* IS_ENABLED(CONFIG_RETENTION_BOOT_MODE) */
-
     return ZMK_BEHAVIOR_OPAQUE;
 }
 

app/src/ble.c

@@ -336,6 +336,32 @@ int zmk_ble_prof_disconnect(uint8_t index) {
     return result;
 }
 
+void zmk_ble_unpair_all(void) {
+    LOG_WRN("Clearing all existing BLE bond information from the keyboard");
+
+    int err = bt_unpair(BT_ID_DEFAULT, NULL);
+    if (err) {
+        LOG_ERR("Failed to unpair default identity: %d", err);
+    }
+
+    for (int i = 0; i < 8; i++) {
+        char setting_name[32];
+        sprintf(setting_name, "ble/profiles/%d", i);
+
+        int err = settings_delete(setting_name);
+        if (err) {
+            LOG_ERR("Failed to delete profile setting: %d", err);
+        }
+
+        sprintf(setting_name, "ble/peripheral_addresses/%d", i);
+
+        err = settings_delete(setting_name);
+        if (err) {
+            LOG_ERR("Failed to delete peripheral setting: %d", err);
+        }
+    }
+}
+
 bt_addr_le_t *zmk_ble_active_profile_addr(void) { return &profiles[active_profile].peer; }
 
 struct bt_conn *zmk_ble_active_profile_conn(void) {
@@ -692,32 +718,7 @@ static void zmk_ble_ready(int err) {
 static int zmk_ble_complete_startup(void) {
 
 #if IS_ENABLED(CONFIG_ZMK_BLE_CLEAR_BONDS_ON_START)
-    LOG_WRN("Clearing all existing BLE bond information from the keyboard");
-
-    bt_unpair(BT_ID_DEFAULT, NULL);
-
-    for (int i = 0; i < 8; i++) {
-        char setting_name[15];
-        sprintf(setting_name, "ble/profiles/%d", i);
-
-        int err = settings_delete(setting_name);
-        if (err) {
-            LOG_ERR("Failed to delete setting: %d", err);
-        }
-    }
-
-    // Hardcoding a reasonable hardcoded value of peripheral addresses
-    // to clear so we properly clear a split central as well.
-    for (int i = 0; i < 8; i++) {
-        char setting_name[32];
-        sprintf(setting_name, "ble/peripheral_addresses/%d", i);
-
-        int err = settings_delete(setting_name);
-        if (err) {
-            LOG_ERR("Failed to delete setting: %d", err);
-        }
-    }
-
+    zmk_ble_unpair_all();
 #endif // IS_ENABLED(CONFIG_ZMK_BLE_CLEAR_BONDS_ON_START)
 
     bt_conn_cb_register(&conn_callbacks);

app/src/boot/CMakeLists.txt

@@ -2,3 +2,4 @@
 target_sources_ifdef(CONFIG_ZMK_BOOTMODE_TO_MAGIC_VALUE_MAPPER app PRIVATE bootmode_to_magic_mapper.c)
 target_sources_ifdef(CONFIG_ZMK_DBL_TAP_BOOTLOADER app PRIVATE dbl_tap_bootloader.c)
 target_sources_ifdef(CONFIG_ZMK_BOOT_STM32_ENFORCE_NBOOT_SEL app PRIVATE stm32_enforce_nboot_sel.c)
+target_sources_ifdef(CONFIG_ZMK_BOOT_MAGIC_COMBO app PRIVATE boot_magic_combo.c)

app/src/boot/boot_magic_combo.c

@@ -0,0 +1,122 @@
+/*
+ * Copyright (c) 2026 The ZMK Contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#define DT_DRV_COMPAT zmk_boot_magic_combo
+
+#include <zephyr/device.h>
+#include <zephyr/devicetree.h>
+#include <zephyr/init.h>
+#include <zephyr/kernel.h>
+#include <zephyr/toolchain.h>
+#include <zephyr/logging/log.h>
+
+#include <zmk/reset.h>
+#include <zmk/event_manager.h>
+#include <zmk/events/position_state_changed.h>
+#include <zmk/boot_magic.h>
+#include <zmk/physical_layouts.h>
+
+#if IS_ENABLED(CONFIG_RETENTION_BOOT_MODE)
+
+#include <zephyr/retention/bootmode.h>
+
+#endif /* IS_ENABLED(CONFIG_RETENTION_BOOT_MODE) */
+
+LOG_MODULE_DECLARE(zmk, CONFIG_ZMK_LOG_LEVEL);
+
+#if DT_HAS_COMPAT_STATUS_OKAY(DT_DRV_COMPAT)
+
+#define BOOT_KEY_CONFIG(n)                                                                         \
+    static const uint16_t boot_key_combo_positions_##n[] = DT_INST_PROP(n, combo_positions);       \
+    static bool boot_key_state_##n[DT_INST_PROP_LEN(n, combo_positions)];                          \
+    const struct zmk_boot_magic_combo_config ZMK_BOOT_MAGIC_COMBO_CONFIG_NAME(DT_DRV_INST(n)) = {  \
+        .combo_positions = boot_key_combo_positions_##n,                                           \
+        .combo_positions_len = DT_INST_PROP_LEN(n, combo_positions),                               \
+        .jump_to_bootloader = DT_INST_PROP_OR(n, jump_to_bootloader, false),                       \
+        .reset_settings = DT_INST_PROP_OR(n, reset_settings, false),                               \
+        .state = boot_key_state_##n,                                                               \
+    };
+
+DT_INST_FOREACH_STATUS_OKAY(BOOT_KEY_CONFIG)
+
+static int64_t timeout_uptime;
+
+static int timeout_init(const struct device *device) {
+    timeout_uptime = k_uptime_get() + CONFIG_ZMK_BOOT_MAGIC_COMBO_TIMEOUT_MS;
+    return 0;
+}
+
+SYS_INIT(timeout_init, APPLICATION, CONFIG_APPLICATION_INIT_PRIORITY);
+
+static void trigger_boot_key(const struct zmk_boot_magic_combo_config *config) {
+    if (config->reset_settings) {
+        LOG_INF("Boot key: resetting settings");
+        zmk_reset_settings();
+    }
+
+    if (config->jump_to_bootloader) {
+        LOG_INF("Boot key: jumping to bootloader");
+#if IS_ENABLED(CONFIG_RETENTION_BOOT_MODE)
+        zmk_reset(BOOT_MODE_TYPE_BOOTLOADER);
+#else
+        zmk_reset(ZMK_RESET_BOOTLOADER);
+#endif /* IS_ENABLED(CONFIG_RETENTION_BOOT_MODE) */
+    } else if (config->reset_settings) {
+        // If resetting settings but not jumping to bootloader, we need to reboot
+        // to ensure all subsystems are properly reset.
+#if IS_ENABLED(CONFIG_RETENTION_BOOT_MODE)
+        zmk_reset(BOOT_MODE_TYPE_NORMAL);
+#else
+        zmk_reset(ZMK_RESET_WARM);
+#endif /* IS_ENABLED(CONFIG_RETENTION_BOOT_MODE) */
+    }
+}
+
+static int event_listener(const zmk_event_t *eh) {
+    if (likely(k_uptime_get() > timeout_uptime)) {
+        return ZMK_EV_EVENT_BUBBLE;
+    }
+
+    const struct zmk_position_state_changed *ev = as_zmk_position_state_changed(eh);
+    int selected = zmk_physical_layouts_get_selected();
+
+    if (!ev || selected < 0) {
+        return ZMK_EV_EVENT_BUBBLE;
+    }
+
+    const struct zmk_physical_layout *const *layouts;
+    zmk_physical_layouts_get_list(&layouts);
+    const struct zmk_physical_layout *active = layouts[selected];
+
+    for (int i = 0; i < active->boot_magic_combos_len; i++) {
+        const struct zmk_boot_magic_combo_config *config = active->boot_magic_combos[i];
+        for (int j = 0; j < config->combo_positions_len; j++) {
+            if (ev->position == config->combo_positions[j]) {
+                config->state[j] = ev->state;
+                if (ev->state) {
+                    bool all_keys_pressed = true;
+                    for (int k = 0; k < config->combo_positions_len; k++) {
+                        if (!config->state[k]) {
+                            all_keys_pressed = false;
+                            break;
+                        }
+                    }
+                    if (all_keys_pressed) {
+                        trigger_boot_key(config);
+                    }
+                }
+                break;
+            }
+        }
+    }
+
+    return ZMK_EV_EVENT_BUBBLE;
+}
+
+ZMK_LISTENER(boot_magic_combo, event_listener);
+ZMK_SUBSCRIPTION(boot_magic_combo, zmk_position_state_changed);
+
+#endif /* DT_HAS_COMPAT_STATUS_OKAY(DT_DRV_COMPAT) */