feat(backlight): add command to cycle brightness

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

@@ -9,11 +9,13 @@
 #define BL_TOG_CMD 2
 #define BL_INC_CMD 3
 #define BL_DEC_CMD 4
-#define BL_SET_CMD 5
+#define BL_CYCLE_CMD 5
+#define BL_SET_CMD 6
 
 #define BL_ON BL_ON_CMD 0
 #define BL_OFF BL_OFF_CMD 0
 #define BL_TOG BL_TOG_CMD 0
 #define BL_INC BL_INC_CMD 0
 #define BL_DEC BL_DEC_CMD 0
+#define BL_CYCLE BL_CYCLE_CMD 0
 #define BL_SET BL_SET_CMD

app/include/zmk/backlight.h

@@ -14,3 +14,4 @@ bool zmk_backlight_is_on();
 int zmk_backlight_set_brt(uint8_t brightness);
 uint8_t zmk_backlight_get_brt();
 uint8_t zmk_backlight_calc_brt(int direction);
+uint8_t zmk_backlight_calc_brt_cycle();

app/src/backlight.c

@@ -137,6 +137,14 @@ uint8_t zmk_backlight_calc_brt(int direction) {
     return CLAMP(brt, 0, BRT_MAX);
 }
 
+uint8_t zmk_backlight_calc_brt_cycle() {
+    if (state.brightness == BRT_MAX) {
+        return 0;
+    } else {
+        return zmk_backlight_calc_brt(1);
+    }
+}
+
 #if IS_ENABLED(CONFIG_ZMK_BACKLIGHT_AUTO_OFF_IDLE) || IS_ENABLED(CONFIG_ZMK_BACKLIGHT_AUTO_OFF_USB)
 static int backlight_auto_state(bool *prev_state, bool new_state) {
     if (state.on == new_state) {

app/src/behaviors/behavior_backlight.c

@@ -35,6 +35,10 @@ on_keymap_binding_convert_central_state_dependent_params(struct zmk_behavior_bin
         binding->param1 = BL_SET_CMD;
         binding->param2 = zmk_backlight_calc_brt(-1);
         break;
+    case BL_CYCLE_CMD:
+        binding->param1 = BL_SET_CMD;
+        binding->param2 = zmk_backlight_calc_brt_cycle();
+        break;
     default:
         return 0;
     }
@@ -61,6 +65,10 @@ static int on_keymap_binding_pressed(struct zmk_behavior_binding *binding,
         uint8_t brt = zmk_backlight_calc_brt(-1);
         return zmk_backlight_set_brt(brt);
     }
+    case BL_CYCLE_CMD: {
+        uint8_t brt = zmk_backlight_calc_brt_cycle();
+        return zmk_backlight_set_brt(brt);
+    }
     case BL_SET_CMD:
         return zmk_backlight_set_brt(binding->param2);
     default:

app/tests/backlight/cycle/events.patterns

@@ -0,0 +1 @@
+s/.*zmk_backlight_update: //p

app/tests/backlight/cycle/keycode_events.snapshot

@@ -0,0 +1,14 @@
+Update backlight brightness: 40%
+Update backlight brightness: 60%
+Update backlight brightness: 80%
+Update backlight brightness: 100%
+Update backlight brightness: 0%
+Update backlight brightness: 20%
+Update backlight brightness: 40%
+Update backlight brightness: 60%
+Update backlight brightness: 80%
+Update backlight brightness: 100%
+Update backlight brightness: 0%
+Update backlight brightness: 20%
+Update backlight brightness: 40%
+Update backlight brightness: 60%

app/tests/backlight/cycle/native_posix.conf

@@ -0,0 +1,14 @@
+CONFIG_KSCAN=n
+CONFIG_ZMK_KSCAN_MOCK_DRIVER=y
+CONFIG_ZMK_KSCAN_GPIO_DRIVER=n
+CONFIG_GPIO=y
+CONFIG_GPIO_EMUL=y
+CONFIG_ZMK_BLE=n
+CONFIG_LOG=y
+CONFIG_LOG_BACKEND_SHOW_COLOR=n
+CONFIG_ZMK_LOG_LEVEL_DBG=y
+CONFIG_DEBUG=y
+CONFIG_SYS_CLOCK_TICKS_PER_SEC=1000
+
+CONFIG_LED_GPIO=y
+CONFIG_ZMK_BACKLIGHT=y

app/tests/backlight/cycle/native_posix.keymap

@@ -0,0 +1,78 @@
+#include <behaviors.dtsi>
+#include <dt-bindings/zmk/keys.h>
+#include <dt-bindings/zmk/kscan_mock.h>
+#include <dt-bindings/zmk/backlight.h>
+
+/ {
+	chosen {
+		zmk,backlight = &backlight;
+	};
+
+	backlight: leds {
+		compatible = "gpio-leds";
+		led_0 {
+			gpios = <&gpio0 0 GPIO_ACTIVE_HIGH>;
+			label = "Backlight LED 0";
+		};
+		led_1 {
+			gpios = <&gpio0 1 GPIO_ACTIVE_HIGH>;
+			label = "Backlight LED 1";
+		};
+	};
+
+	keymap {
+		compatible = "zmk,keymap";
+		label ="Default keymap";
+
+		default_layer {
+			bindings = <
+				&bl BL_CYCLE &none
+				&none        &none
+			>;
+		};
+	};
+};
+
+&kscan {
+	events = <
+		/* BL_CYCLE */
+		ZMK_MOCK_PRESS(0,0,10)
+		ZMK_MOCK_RELEASE(0,0,10)
+		/* BL_CYCLE */
+		ZMK_MOCK_PRESS(0,0,10)
+		ZMK_MOCK_RELEASE(0,0,10)
+		/* BL_CYCLE */
+		ZMK_MOCK_PRESS(0,0,10)
+		ZMK_MOCK_RELEASE(0,0,10)
+		/* BL_CYCLE */
+		ZMK_MOCK_PRESS(0,0,10)
+		ZMK_MOCK_RELEASE(0,0,10)
+		/* BL_CYCLE */
+		ZMK_MOCK_PRESS(0,0,10)
+		ZMK_MOCK_RELEASE(0,0,10)
+		/* BL_CYCLE */
+		ZMK_MOCK_PRESS(0,0,10)
+		ZMK_MOCK_RELEASE(0,0,10)
+		/* BL_CYCLE */
+		ZMK_MOCK_PRESS(0,0,10)
+		ZMK_MOCK_RELEASE(0,0,10)
+		/* BL_CYCLE */
+		ZMK_MOCK_PRESS(0,0,10)
+		ZMK_MOCK_RELEASE(0,0,10)
+		/* BL_CYCLE */
+		ZMK_MOCK_PRESS(0,0,10)
+		ZMK_MOCK_RELEASE(0,0,10)
+		/* BL_CYCLE */
+		ZMK_MOCK_PRESS(0,0,10)
+		ZMK_MOCK_RELEASE(0,0,10)
+		/* BL_CYCLE */
+		ZMK_MOCK_PRESS(0,0,10)
+		ZMK_MOCK_RELEASE(0,0,10)
+		/* BL_CYCLE */
+		ZMK_MOCK_PRESS(0,0,10)
+		ZMK_MOCK_RELEASE(0,0,10)
+		/* BL_CYCLE */
+		ZMK_MOCK_PRESS(0,0,10)
+		ZMK_MOCK_RELEASE(0,0,10)
+	>;
+};

docs/docs/behaviors/backlight.md

@@ -20,18 +20,21 @@ This will allow you to reference the actions defined in this header such as `BL_
 
 Here is a table describing the action for each define:
 
-| Define   | Action                                   |
+| Define     | Action                      |
-| -------- | ---------------------------------------- |
+| ---------- | --------------------------- |
-| `BL_TOG` | Toggles the backlight on and off         |
+| `BL_ON`    | Turn on backlight           |
-| `BL_ON`  | Turn on backlight on and off             |
+| `BL_OFF`   | Turn off backlight          |
-| `BL_OFF` | Toggles the backlight feature on and off |
+| `BL_TOG`   | Toggle backlight on and off |
-| `BL_INC` | Increase backlight brightness            |
+| `BL_INC`   | Increase brightness         |
-| `BL_DEC` | Decrease backlight brightness            |
+| `BL_DEC`   | Decrease brightness         |
+| `BL_CYCLE` | Cycle brightness            |
+| `BL_SET`   | Set a specific brightness   |
 
 ## Behavior Binding
 
 - Reference: `&bl`
 - Parameter #1: The backlight action define, e.g. `BL_TOG` or `BL_INC`
+- Parameter #2: Only applies to `BL_SET`and is the brightness value
 
 ### Examples
 
@@ -41,8 +44,8 @@ Here is a table describing the action for each define:
    &bl BL_TOG
    ```
 
-1. Increase backlight brightness
+1. Sets a specific brightness
 
    ```
-   &bl BL_INC
+   &bl BL_SET 50
    ```