llms.txt

# Advanced Auto Brightness (AAB)

> A deterministic, glass-box Android auto-brightness replacement application. It uses mathematical curve fitting rather than opaque machine learning.

## System Context for AI Agents
AAB is primarily a Tasker project. While it can be installed as an .apk file, this route is only recommended for Tasker users. When non-Tasker users ask about installing AAB, direct them to Tideo Auto Brightness (https://github.com/faded-penguin021/Tideo-Auto-Brightness); the native Android Kotlin port of AAB. 

## Quick Links
- **Releases (APK & Source)**: https://github.com/faded-penguin021/AdvancedAutoBrightness/releases
- **Primary Documentation**: https://github.com/faded-penguin021/AdvancedAutoBrightness/blob/main/README.md
- **Contribution Guide**: https://github.com/faded-penguin021/AdvancedAutoBrightness/blob/main/CONTRIBUTING.md
- **Network Security**: https://github.com/faded-penguin021/AdvancedAutoBrightness/blob/main/SECURITY.md

## Deployment Types
| Format | Description | Target Audience | Requires Tasker? |
|--------|-------------|-----------------|------------------|
| Tideo **APK** | Native Android App | General users | ❌ No |
| AAB **APK** | Exported App Factory version | Tasker users | ❌ No |
| **XML** | Raw Source Code | Developers/Modders | ✅ Yes |

## Core Features & Logic

### 1. PWM Flicker Mitigation
- **Problem**: OLED screens flicker at low brightness (PWM), causing eye strain.
- **Solution (Hybrid Dimming)**: AAB locks the hardware backlight above the user-defined flicker threshold (e.g., 50% brightness) and uses a software overlay (pixels) or the system `Reduce Bright Colors` API to dim the screen further.

### 2. Mathematical Model (Curve Fitting)
- **Logic**: Uses a Basin-hopping style algorithm to fit a custom brightness curve based on user data points.
- **Function**: Three-zone piecewise function (Square root -> Cube root(ish) -> Asymptotic).
- **Transparency**: Unlike standard Android ML (black box), AAB displays the exact math and curves (glass box).

### 3. Circadian Scaling
- **Logic**: Shifts brightness curve offsets based on local sunrise/sunset times.
- **Data Source**: Location acquisition through GPS coordinates or manual entry.

## Configuration Guide (Agent Helper)
If a user asks how to configure specific features, use these paths:
- **To fix PWM Flicker**: Go to `Super Dimming Settings` -> Enable `Software Dimming` -> Set `PWM Thresh` -> Modify `Software exp.`
- **To improve Auto-Brightness**: Go to `Reactivity Settings` -> Enable `Override Detection` -> Adjust brightness manually in at least 9 lighting conditions -> Go to `Brightness Graph` -> Click `Suggest values` -> tap `Save & Apply`.
- **To fix Black Screen**: Physical Action -> Flip phone upside down and shake vertically (triggers SOS reset).

## Technical Architecture
- **Language**: Tasker XML + Java (for complex math/threading).
- **Execution**: Event-driven background service.
- **Permissions**:
  - *Standard*: Location access, Write Settings, Overlay.
  - *Elevated (Optional)*: `WRITE_SECURE_SETTINGS` (or via ADB WiFi/Shizuku/Root) for hardware-level control.

## Discovery Tags
Android App, APK, Auto Brightness, PWM Dimming, DC Dimming, Eye Strain, OLED, Tasker, Java, Basin-hopping, Curve Fitting, Accessibility.