Narrative explanation of Advanced Auto-Brightness

For the enthusiasts, here’s a narrative breakdown of how this project works.

Narrative 1: The Main Event - Processing a New Lux Value
This is the central nervous system of the project. It outlines the full journey from a raw light sensor reading to a potential screen brightness adjustment. The logic is primarily housed in the Evaluate Light Change task (ID: 257).

Event Trigger & Execution Pathway: The process begins with the Monitor Ambient Light profile (prof267). This is an Event based profile listening to the Light Sensor. It's configured with a 2000ms monitoring period and a 1-lux change threshold, striking a balance between responsiveness and battery conservation. Following our refactor, this profile now calls the Process Sensor Event task (ID: 264), which then directly calls the Evaluate Light Change task (ID: 257), passing the raw lux reading (%as_values1) into %par1.

Intelligent Throttling: The very first actions in Evaluate Light Change serve as a gatekeeper. It checks a global timestamp, %LastAAB, against the current time (%TIMEMS). If the elapsed time is less than the user-configured %AAB_Throttle value, the task is immediately stopped. The parent Monitor Ambient Light profile is configured with a collision handling strategy that ensures any sensor events firing during this throttle period are efficiently discarded, preventing a queue from building up and saving resources.

Bootstrapping the System: If %SmoothedLux isn't set (which is true on the very first run after the screen turns on, or if the system hasn't fully initialized after a display-off period, and auto-brightness is deemed active), the system runs a special one-time seeding routine. It sets %SmoothedLux equal to the current raw input (%par1) and forces %LuxAlpha (the smoothing factor) to 1. This ensures the system has valid baseline values and performs an initial, unfiltered brightness calculation.

The Core Math & Decision Engine: This is where the magic happens.

Robust Relative Change: The key metric for deciding if a change is "significant" is its relative change. This is calculated as abs(current_lux - smoothed_lux) / (smoothed_lux + 1).
CRITICAL ROBUSTNESS: The calculation now includes a +1 in the denominator. This elegantly and robustly prevents a divide-by-zero error even when %SmoothedLux is exactly 0, ensuring the logic is sound in completely dark environments without requiring a separate conditional check.
Clamping the Change: The raw %relative_change value is then fed as %par1 into the Clamp Relative Change sub-task (ID: 263). This task uses %par1 and acts as a pure function, clamping the input between 0.02 and 0.4 (which effectively scales 0-40% relative change). This establishes an absolute floor and ceiling for the relative change value, guarding against potential mathematical anomalies or extreme out-of-range sensor readings, promoting system stability.
The Dynamic Threshold: Instead of a simple, fixed threshold, this project calculates a dynamic one on every run. It computes two different threshold curves and picks the more forgiving one:
%thresh_pow = 0.0624 * (%SmoothedLux ^ 0.121): A power curve that scales with the ambient light. As lux increases, a larger relative change is required to trigger an update.
%thresh_abs = %AAB_AbsFloor / (%SmoothedLux + 1): A curve based on an absolute lux floor (e.g., 2 lux). This dominates in dark environments, ensuring that a small but meaningful change (like going from 1 lux to 3 lux) is always detected. The +1 in the denominator consistent with the relative change calculation ensures robustness for very low lux values.
The %dynamic_threshold is set to max(%thresh_pow, %thresh_abs). This is a brilliant piece of signal processing that makes the system highly sensitive in the dark and stable in bright light.

The Final Decision & Smoothing:

The Gate: The system proceeds only IF %relative_change > %dynamic_threshold. If not, the task ends here, saving resources.
Adaptive Low-Pass Filter: If the gate is passed, the Lux Smoothing task (ID: 262) is called. It calculates a smoothing factor, %lux_alpha, using the formula 1 - e^(-0.15 * %lux_delta ^ 0.33). In simple terms, the larger the change in lux (%lux_delta), the closer %lux_alpha gets to 1. This gives more weight to the new reading for big changes (fast reaction) and more weight to the old smoothed value for small changes (high stability).
Mapping & Execution: The newly calculated %new_smoothed_lux is passed to the Map Lux to Brightness task (ID: 261), which uses a multi-zone formula to convert the lux value to a 0-255 brightness level. That final value is then sent through the Smooth Brightness Transition task (ID: 258), which animates the change over a series of small, rapid steps for a pleasant visual effect. (Note: In debug mode, Smooth Brightness Transition can be bypassed for immediate feedback.)
State Update: Finally, the global variables %SmoothedLux and %LastAAB are updated with the new values, preparing the system for the next event.

Narrative 2: Waking Up - The Screen-On Initialization
The Initialize (Display On) profile (prof265) ensures the system kickstarts instantly and correctly every time the screen is turned on.

First-Time Setup: On the very first run ever, a check for %AAB_SetupComplete fails, triggering the Initialize AAB Defaults task (ID: 259). This task populates over a dozen %AAB_* global variables with default constants for all the formulas and timings, and it posts a one-time notification to the user.

Instantaneous Lux Reading: The task immediately uses the Sensor Info action to get a synchronous light sensor reading. This is a key trick: it gets the current lux value right now, without having to wait for the asynchronous Monitor Ambient Light event to fire. This allows the screen brightness to be set correctly the very instant it turns on.

Seeding the Engine: This initial lux value is immediately passed to the Evaluate Light Change task (ID: 257). This performs the first brightness calculation and seeds the %SmoothedLux and %LastAAB state variables.

Preventing a Race Condition: This is a critical piece of logic for system stability. After setting the initial brightness, the task temporarily hides any setup notification and enters a Wait action for the full duration of the throttle period (%AAB_Throttle, default 1020 ms). Only after this wait does it enable the Monitor Ambient Light profile. This guarantees that the initialization process has fully completed and set the %LastAAB timestamp before the sensor monitoring profile is even allowed to begin firing its own events. This prevents the first real sensor event from being improperly throttled.

Narrative 3: Going to Sleep - The Screen-Off Teardown
The Hibernate (Display Off) profile (prof266) is responsible for cleanly and completely shutting down the entire AAB system to ensure zero battery drain while the screen is off.

Cease Monitoring: The very first action this profile takes is to turn off the Monitor Ambient Light profile (prof267). This immediately stops all sensor monitoring, which is the primary source of activity for this project.

Terminate In-Flight Tasks: It then executes Stop actions for the Smooth Brightness Transition (ID: 258) and Map Lux to Brightness (ID: 261) tasks. This is a crucial cleanup step that prevents a "ghost" update, which might have been triggered right before the screen was turned off, from trying to complete its work and potentially writing a new brightness value to a powered-down display.

Annihilate Session State: Finally, the task systematically clears all global variables that hold session state: %AutoBrightRunning, %SmoothedLux, %LuxAlpha, and %LastAAB. The core configuration variables (%AAB_*) are left untouched. This "scorched earth" approach to state management is a pillar of this project's robustness. It guarantees that every single screen-on cycle starts from a perfectly clean, known-good state, preventing any possibility of a corrupted value from one session affecting the next.