fw: Add dynamic backlight feature with ALS-based intensity control

Implements user-toggleable dynamic backlight that automatically adjusts
backlight intensity based on ambient light sensor readings. When
enabled, backlight intensity scales linearly between 5% (Low) and the
user's configured max intensity based on ambient light condition.

Note: Threshold values (20/120) are initial estimates and will likely
need to be adjusted based on real-world testing and user feedback

Signed-off-by: Joshua Jun <joshuajun@proton.me>

Author: jplexer

platform/platform_capabilities.py

@@ -59,6 +59,7 @@
     'HAS_FLASH_OTP',
     'HAS_VIBE_AW86225',
     'HAS_PBLBOOT',
+    'HAS_DYNAMIC_BACKLIGHT',
 }
 
 board_capability_dicts = [
@@ -365,6 +366,7 @@
             'HAS_ALS_W1160',
             'HAS_MAGNETOMETER',
             'HAS_PBLBOOT',
+            'HAS_DYNAMIC_BACKLIGHT',
         },
     },
 ]

src/fw/apps/system_apps/settings/settings_display.c

@@ -166,6 +166,9 @@ enum SettingsDisplayItem {
   SettingsDisplayBacklightMode,
   SettingsDisplayMotionSensor,
   SettingsDisplayAmbientSensor,
+#if CAPABILITY_HAS_DYNAMIC_BACKLIGHT
+  SettingsDisplayDynamicIntensity,
+#endif
   SettingsDisplayBacklightIntensity,
   SettingsDisplayBacklightTimeout,
 #if PLATFORM_SPALDING
@@ -208,6 +211,11 @@ static void prv_select_click_cb(SettingsCallbacks *context, uint16_t row) {
     case SettingsDisplayAmbientSensor:
       light_toggle_ambient_sensor_enabled();
       break;
+#if CAPABILITY_HAS_DYNAMIC_BACKLIGHT
+    case SettingsDisplayDynamicIntensity:
+      backlight_set_dynamic_intensity_enabled(!backlight_is_dynamic_intensity_enabled());
+      break;
+#endif
     case SettingsDisplayBacklightIntensity:
       prv_intensity_menu_push(data);
       break;
@@ -266,8 +274,26 @@ static void prv_draw_row_cb(SettingsCallbacks *context, GContext *ctx,
         subtitle = i18n_noop("Off");
       }
       break;
+#if CAPABILITY_HAS_DYNAMIC_BACKLIGHT
+    case SettingsDisplayDynamicIntensity:
+      title = i18n_noop("Dynamic Backlight");
+      if (backlight_is_dynamic_intensity_enabled()) {
+        subtitle = i18n_noop("On");
+      } else {
+        subtitle = i18n_noop("Off");
+      }
+      break;
+#endif
     case SettingsDisplayBacklightIntensity:
+#if CAPABILITY_HAS_DYNAMIC_BACKLIGHT
+      if (backlight_is_dynamic_intensity_enabled()) {
+        title = i18n_noop("Max Intensity");
+      } else {
+        title = i18n_noop("Intensity");
+      }
+#else
       title = i18n_noop("Intensity");
+#endif
       subtitle = s_intensity_labels[prv_intensity_get_selection_index()];
       break;
     case SettingsDisplayBacklightTimeout:

src/fw/board/board_sf32lb52.h

@@ -131,6 +131,11 @@ typedef struct {
   //ambient light config
   uint32_t ambient_light_dark_threshold;
   uint32_t ambient_k_delta_threshold;
+#if CAPABILITY_HAS_DYNAMIC_BACKLIGHT
+  //dynamic backlight thresholds
+  uint32_t dynamic_backlight_min_threshold;
+  uint32_t dynamic_backlight_max_threshold;
+#endif
 } BoardConfig;
 
 typedef struct {

src/fw/board/boards/board_obelix.c

@@ -546,6 +546,10 @@ const BoardConfig BOARD_CONFIG = {
   .backlight_on_percent = 25,
   .ambient_light_dark_threshold = 150,
   .ambient_k_delta_threshold = 25,
+#if CAPABILITY_HAS_DYNAMIC_BACKLIGHT
+  .dynamic_backlight_min_threshold = 20,
+  .dynamic_backlight_max_threshold = 120,
+#endif
 };
 
 const BoardConfigButton BOARD_CONFIG_BUTTON = {

src/fw/services/common/light.c

@@ -85,6 +85,15 @@ static bool s_user_controlled_state;
 //! For temporary disabling backlight (ie: low power mode)
 static bool s_backlight_allowed = false;
 
+//! Cached ambient light level captured when backlight turns on (to avoid feedback from backlight illuminating sensor)
+static uint32_t s_cached_ambient_light_level = 0;
+
+//! Starting intensity for fade-out (captured when fade begins)
+static uint16_t s_fade_start_intensity = 0;
+
+//! Fade step size (calculated once at start of fade to avoid rounding jitter)
+static uint16_t s_fade_step_size = 0;
+
 //! Mutex to guard all the above state. We have a pattern of taking the lock in the public functions and assuming
 //! it's already taken in the prv_ functions.
 static PebbleMutex *s_mutex;
@@ -100,11 +109,54 @@ static void light_timer_callback(void *data) {
 static uint16_t prv_backlight_get_intensity(void) {
   // low_power_mode backlight intensity (25% of max brightness)
   const uint16_t backlight_low_power_intensity = (BACKLIGHT_BRIGHTNESS_MAX * (uint32_t)25) / 100;
-  return low_power_is_active() ? backlight_low_power_intensity : backlight_get_intensity();
+  
+  if (low_power_is_active()) {
+    return backlight_low_power_intensity;
+  }
+  
+#if CAPABILITY_HAS_DYNAMIC_BACKLIGHT && !defined(RECOVERY_FW)
+  // Dynamic backlight: adjust intensity based on ambient light sensor
+  if (backlight_is_dynamic_intensity_enabled()) {
+    // Use cached light level to avoid feedback from backlight illuminating the sensor
+    uint32_t light_level = s_cached_ambient_light_level;
+    uint16_t user_max_intensity = backlight_get_intensity();
+    
+    // Low intensity is always 5% (the "Low" setting)
+    const uint16_t low_intensity = (BACKLIGHT_BRIGHTNESS_MAX * (uint32_t)5) / 100;
+    
+    // Get thresholds from board config
+    const uint32_t min_light_threshold = BOARD_CONFIG.dynamic_backlight_min_threshold;
+    const uint32_t max_light_threshold = BOARD_CONFIG.dynamic_backlight_max_threshold;
+    
+    // If below minimum threshold, return low intensity
+    if (light_level < min_light_threshold) {
+      return low_intensity;
+    }
+    
+    // Clamp light level to max threshold
+    if (light_level > max_light_threshold) {
+      light_level = max_light_threshold;
+    }
+    
+    // Scale linearly from low_intensity to user_max_intensity based on ambient light
+    // Adjusted to start scaling from min_light_threshold
+    uint32_t dynamic_intensity = low_intensity + 
+      ((user_max_intensity - low_intensity) * (light_level - min_light_threshold)) / 
+      (max_light_threshold - min_light_threshold);
+    
+    return (uint16_t)dynamic_intensity;
+  }
+#endif
+  
+  return backlight_get_intensity();
 }
 
 static void prv_change_brightness(int32_t new_brightness) {
-  const uint16_t HALF_BRIGHTNESS = (prv_backlight_get_intensity() - BACKLIGHT_BRIGHTNESS_OFF) / 2;
+  // Use fade start intensity during fading, otherwise get current intensity
+  uint16_t reference_intensity = (s_light_state == LIGHT_STATE_ON_FADING && s_fade_start_intensity > 0) 
+                                  ? s_fade_start_intensity 
+                                  : prv_backlight_get_intensity();
+  const uint16_t HALF_BRIGHTNESS = (reference_intensity - BACKLIGHT_BRIGHTNESS_OFF) / 2;
 
   // update the debug stats
   if (new_brightness > HALF_BRIGHTNESS && s_current_brightness <= HALF_BRIGHTNESS) {
@@ -126,10 +178,19 @@ static void prv_change_brightness(int32_t new_brightness) {
 }
 
 static void prv_change_state(BacklightState new_state) {
+  BacklightState old_state = s_light_state;
   s_light_state = new_state;
 
+  // Capture ambient light level when transitioning from OFF to ON states
+  // This prevents feedback from the backlight illuminating the sensor
+  if ((new_state == LIGHT_STATE_ON || new_state == LIGHT_STATE_ON_TIMED) && 
+      s_current_brightness == BACKLIGHT_BRIGHTNESS_OFF) {
+    s_cached_ambient_light_level = ambient_light_get_light_level();
+  }
+
   // Calculate the new brightness and reset any timers based on our state.
   int32_t new_brightness = 0;
+  
   switch (new_state) {
     case LIGHT_STATE_ON:
       new_brightness = prv_backlight_get_intensity();
@@ -143,7 +204,12 @@ static void prv_change_state(BacklightState new_state) {
                       light_timer_callback, NULL, 0 /* flags */);
       break;
     case LIGHT_STATE_ON_FADING:
-      new_brightness = s_current_brightness - (prv_backlight_get_intensity() / LIGHT_FADE_STEPS);
+      // Capture the starting intensity only when we first enter fading state
+      if (old_state != LIGHT_STATE_ON_FADING) {
+        s_fade_start_intensity = s_current_brightness;
+        s_fade_step_size = s_fade_start_intensity / LIGHT_FADE_STEPS;
+      }
+      new_brightness = s_current_brightness - s_fade_step_size;
 
       if (new_brightness <= BACKLIGHT_BRIGHTNESS_OFF) {
         // Done fading!
@@ -193,6 +259,9 @@ void light_init(void) {
   s_timer_id = new_timer_create();
   s_num_buttons_down = 0;
   s_user_controlled_state = false;
+  s_cached_ambient_light_level = 0;
+  s_fade_start_intensity = 0;
+  s_fade_step_size = 0;
   s_mutex = mutex_create();
 }
 

src/fw/shell/normal/prefs.c

@@ -78,6 +78,11 @@ static bool s_backlight_motion_enabled = true;
 #define PREF_KEY_MOTION_SENSITIVITY "motionSensitivity"
 static uint8_t s_motion_sensitivity = 100; // Default to maximum sensitivity (100%)
 
+#if CAPABILITY_HAS_DYNAMIC_BACKLIGHT
+#define PREF_KEY_BACKLIGHT_DYNAMIC_INTENSITY "lightDynamicIntensity"
+static bool s_backlight_dynamic_intensity_enabled = false;
+#endif
+
 #define PREF_KEY_BACKLIGHT_AMBIENT_THRESHOLD "lightAmbientThreshold"
 static uint32_t s_backlight_ambient_threshold = 0; // default set from board config in shell_prefs_init()
 
@@ -278,6 +283,13 @@ static bool prv_set_s_backlight_motion_enabled(bool *enabled) {
   return true;
 }
 
+#if CAPABILITY_HAS_DYNAMIC_BACKLIGHT
+static bool prv_set_s_backlight_dynamic_intensity_enabled(bool *enabled) {
+  s_backlight_dynamic_intensity_enabled = *enabled;
+  return true;
+}
+#endif
+
 static bool prv_set_s_motion_sensitivity(uint8_t *sensitivity) {
   // Clamp sensitivity to 0-100 range
   if (*sensitivity > 100) {
@@ -880,6 +892,16 @@ void backlight_set_motion_enabled(bool enable) {
   prv_pref_set(PREF_KEY_BACKLIGHT_MOTION, &enable, sizeof(enable));
 }
 
+#if CAPABILITY_HAS_DYNAMIC_BACKLIGHT
+bool backlight_is_dynamic_intensity_enabled(void) {
+  return s_backlight_dynamic_intensity_enabled;
+}
+
+void backlight_set_dynamic_intensity_enabled(bool enable) {
+  prv_pref_set(PREF_KEY_BACKLIGHT_DYNAMIC_INTENSITY, &enable, sizeof(enable));
+}
+#endif
+
 uint8_t shell_prefs_get_motion_sensitivity(void) {
   return s_motion_sensitivity;
 }

src/fw/shell/normal/prefs_values.h.inc

@@ -9,6 +9,9 @@
   PREFS_MACRO(PREF_KEY_BACKLIGHT_INTENSITY, s_backlight_intensity)
   PREFS_MACRO(PREF_KEY_BACKLIGHT_MOTION, s_backlight_motion_enabled)
   PREFS_MACRO(PREF_KEY_MOTION_SENSITIVITY, s_motion_sensitivity)
+#if CAPABILITY_HAS_DYNAMIC_BACKLIGHT
+  PREFS_MACRO(PREF_KEY_BACKLIGHT_DYNAMIC_INTENSITY, s_backlight_dynamic_intensity_enabled)
+#endif
   PREFS_MACRO(PREF_KEY_BACKLIGHT_AMBIENT_THRESHOLD, s_backlight_ambient_threshold)
   PREFS_MACRO(PREF_KEY_STATIONARY, s_stationary_mode_enabled)
   PREFS_MACRO(PREF_KEY_DEFAULT_WORKER, s_default_worker)

src/fw/shell/prefs.h

@@ -89,6 +89,12 @@ void backlight_set_intensity_percent(uint8_t intensity_percent);
 bool backlight_is_motion_enabled(void);
 void backlight_set_motion_enabled(bool enable);
 
+#if CAPABILITY_HAS_DYNAMIC_BACKLIGHT
+// Dynamic backlight intensity based on ambient light sensor
+bool backlight_is_dynamic_intensity_enabled(void);
+void backlight_set_dynamic_intensity_enabled(bool enable);
+#endif
+
 // Motion sensitivity for accelerometer shake detection (0-100, lower = less sensitive)
 // Only available on platforms with LSM6DSO (Asterix, Obelix)
 uint8_t shell_prefs_get_motion_sensitivity(void);