Battery Health Tracker (O+ - Oppo - Realme Edition)

Advanced hardware-level battery health, BMS telemetry, and degradation tracker for Oppo, OnePlus, and Realme devices. Powered by Shizuku.

📌 Overview

On modern Android devices—particularly within the Oplus ecosystem (Oppo, OnePlus, Realme / ColorOS, OxygenOS, Realme UI)—the operating system restricts and abstracts critical battery metrics. Standard Android battery APIs typically return coarse percentage estimates, rounded cycle counts, or hidden health statistics.

Battery Health Tracker bridges this gap. By utilizing Shizuku to execute elevated unprivileged shell transactions (no root required), the app directly interrogates the kernel Battery Management System (BMS) hardware nodes (/sys/class/oplus_chg/battery/ and /sys/class/power_supply/battery/).

This delivers accurate, real-time electrochemical diagnostic data: true State of Health (SOH), cycle counts, internal cell resistance (ESR), cell temperature, thermal capacity compensation (IEC 61960), charging IC safety fault registers, and live wattage.

📸 Screenshots

AMOLED Pure Black	Light Theme	Hardware Diagnostics
Health Trend & Projection	Device Presets & Rated mAh	Theme Settings

✨ Key Features

🔬 Low-Level BMS & Kernel Telemetry (via Shizuku)

• Direct Fuel Gauge Queries: Reads physical registers directly from /sys/class/oplus_chg/battery/ and /sys/class/power_supply/battery/.
• True State of Health (SOH): Real electrochemical capacity evaluated against nominal factory design capacity.
• Hardware Cycle Counter: Reads non-volatile cycles tracked by the physical fuel gauge IC (immune to OS battery stat wipes).
• Dual-Cell SuperVOOC Monitoring: Individual cell voltages (cell0Volt, cell1Volt) and series balance \(\Delta\text{ mV}\).

⚡ True Full Charge vs Display 100%

• CC/CV Saturation Tracking: Distinguishes between the display "100%" (often end of Constant Current at ~90% saturation) and True Full Charge when Constant Voltage current tapers below cutoff (\(I \le 80\text{ mA}\)).

🌡️ IEC 61960 Thermal Compensation

• Normalized Capacity at 25°C: Eliminates seasonal capacity swings (winter vs summer) using the electrochemical standard formula: \(C_{25^\circ\text{C}} = \frac{C_{\text{fcc}}}{1.0 + 0.006 \times (T_{\text{batt}} - 25.0)}\)

🛡️ Silicon Safety & Protection Registers

• Hardware Fault Monitoring: Inspects physical protection flags in real time (short_c_hw_status, short_ic_otp_status, subboard_temp_err) with an instant SAFE / ALERT indicator.

📈 Internal Resistance (ESR)

• Dynamic Impedance Calculation: Estimates real-time internal resistance (\(\text{m}\Omega\)) using active \(\frac{\Delta V}{\Delta I}\) load steps, helping identify aging and degradation.

📊 Health Trends & Projections

• Interactive SOH Chart: Visual canvas trend with 100%, 90%, and 80% industrial replacement threshold lines.
• Cycle Life Projection: Estimates remaining cycles before reaching 80% capacity based on historical wear rate.
• Safe History Management: Multi-select deletion, persistent Trash bin, full restore, and CSV/JSON export.

🔔 Smart Notifications & Thermal Protection

• Snapshot Receipts: Confirmation cards for manual saves, 24h background logs (WorkManager), and 100% charger unplug events.
• Overheat Alarm: High-priority alert when battery temperature exceeds 42°C during high-speed charging or heavy workloads.

🚀 120 Hz UI & Themes

• Fluid Performance: Zero-allocation Composables locked to 120 Hz (8.33 ms frame budget).
• 4 Themes: System Default, Light, Dark, and AMOLED Pure Black (#000000) for zero OLED sub-pixel power draw.

💻 Built-in Diagnostic Console

• Real-Time Shell Inspector: Live log of every sysfs, dumpsys, and settings query with exit codes and fallback paths.
• 1-Click Bug Reporting: Instant Markdown generation ready to paste into GitHub Issues.

🏷️ SOH Determination Hierarchy

The app clearly indicates how SOH is sourced on your device:

1. BMS Hardware / OS: Direct read from OEM kernel fuel-gauge registers (ColorOS / OxygenOS / Realme UI certified).
2. Calculated SOH: Dynamically computed (\(\text{FCC} / \text{Typical Capacity} \times 100\)) when vendor firmware restricts direct SOH registers.
3. Unavailable via API: Fallback indicator when running without Shizuku permissions.

🌐 Multilingual

• Fully localized in English, Italian (Italiano), and Spanish (Español).

📱 Verified Device Battery Database & Hardware Compatibility

Manual rated capacity override is also supported in Settings for custom or unlisted models.

🛠️ How It Works (Technical Architecture)

flowchart TD
    subgraph Data Sources & Hardware Tiers
        A1["OPlus Kernel Sysfs MediaTek<br/>(oplus_chg/battery, battery_cc)"]
        A2["OPlus Kernel Sysfs Snapdragon<br/>(power_supply/battery/bms, battery_cycle)"]
        A3["Android 14+ HAL Interface<br/>(BatteryManager API 34+ id 7)"]
        A4["Universal Android API Fallback<br/>(Standard BatteryManager)"]
    end
    
    A1 & A2 -->|Elevated Shell via Shizuku| B[Multi-Path Hardware Resolver]
    A3 -->|Automated HAL Cycle Fallback| B
    A4 -->|Non-OPlus Fallback with Warnings| B
    
    B -->|Normalized Telemetry & Inferences| C[BatteryViewModel]
    C -->|StateFlow| D[Jetpack Compose UI]
    C -->|Persistent History| E[Room SQLite Database]
    C -->|Periodic & 100% Triggers| F[WorkManager & Charge Receiver]
    C -->|Sampling & Safety Alerts| G[NotificationHelper]

Multi-Tiered Hardware Resolution Pipeline

1. Tier 1: Direct OPlus Kernel Sysfs (via Shizuku)
   • Automatically adapts between MediaTek (battery_cc) and Qualcomm Snapdragon (battery_cycle, /power_supply/bms/) nodes within a single low-overhead Binder transaction.
   • Normalizes microampere (\(\mu\text{Ah}\)) PMIC registers to \(\text{mAh}\) and performs bidirectional SOH/FCC inference when nodes are partially restricted.
2. Tier 2: Android 14+ Hardware HAL Fallback
   • Automatically queries BatteryManager.getIntProperty(7) if vendor SELinux updates isolate custom sysfs cycle nodes.
3. Tier 3: Universal Android Fallback (Non-OPlus devices)
   • Graceful fallback for generic hardware with explicit warning badges to ensure instantaneous charge (CHARGE_COUNTER) is never confused with chemical health.

📥 Installation & Setup

Prerequisites

1. Device: Oppo, OnePlus, Realme (Android 14+), or any Android 14+ device.
2. Shizuku: Installed from Google Play or GitHub Releases and running via Wireless Debugging or Root.

App Setup

1. Download and install BatteryHealthTracker-v1.6.apk from Releases.
2. Open the app and grant the Notification Permission (required for background snapshot receipts and > 42°C overheat alerts).
3. Tap "Authorize Shizuku" and allow access when prompted.
4. Telemetry, health metrics, and hardware registers will populate immediately!

🔨 Building from Source

Requirements

• JDK 17 or JDK 21
• Android SDK 34 (compileSdk 34)
• Gradle 8.7+

Steps

1. Clone this repository:

   git clone https://github.com/FrancescoMin/batteryhealthtracker.git
   cd batteryhealthtracker
   

2. Build the debug APK using Gradle wrapper:

   # On Linux / macOS:
   ./gradlew assembleDebug
   
   # On Windows (PowerShell):
   .\gradlew.bat assembleDebug
   

3. Install directly to your connected device via ADB:

   adb install -r app/build/outputs/apk/debug/app-debug.apk
   

🔒 Privacy, Security & Permissions

• Transparent Network Usage (android.permission.INTERNET): Used exclusively for the manual in-app update check against official public GitHub Releases (api.github.com). Zero background analytics, zero telemetry trackers, zero personal data leaves your device.
• Transparent Notifications (POST_NOTIFICATIONS): Used strictly for local on-device sampling receipts (manual captures, 24h background sampling, and 100% unplug events) and critical battery overheat alarms (> 42°C). Never used for marketing or background telemetry.
• Zero Trackers / Telemetry: No Google Analytics, Firebase, Crashlytics, or third-party advertising SDKs.
• Local Storage Only: Historical measurements are stored in a local on-device SQLite database via Android Room.
• Open Source: Full source code is open, auditable, and distributed under the Apache-2.0 License.

🤝 Contributing

Contributions, device profile additions, translations, and feature suggestions are welcome!

📱 Device Testing & Verification

Do you own any of the devices marked as 🤝 Help wanted in the Hardware Compatibility Table?
Testing the app on your device is warmly encouraged and greatly appreciated!

• Install the app and grant access via Shizuku (no root required for most devices).
• Verify if real-time hardware telemetry (SOH, capacity, cycle count, temperature, voltage) is extracted accurately.
• Share your findings or report any anomalies using our Device Compatibility Report Form or open a GitHub Issue.

💻 Code & Preset Contributions

1. Fork the project.
2. Create your feature branch (git checkout -b feature/NewDevicePreset).
3. Commit your changes (git commit -m "Add verified battery preset for Device X").
4. Push to the branch (git push origin feature/NewDevicePreset).
5. Open a Pull Request.

⚖️ Disclaimer & Accuracy Notice

Battery Health Tracker is an independent diagnostic utility for monitoring and personal reference.

• Non-Official: This project is not affiliated with, endorsed by, or certified by Oppo, OnePlus, Realme, or BBK Electronics. It must not be confused with official manufacturer service tools or warranty inspection software.
• Sensor & Firmware Tolerances: Telemetry is read directly from kernel sysfs nodes and fuel-gauge registers via Shizuku. Reported metrics (SOH %, capacity, cell resistance) may fluctuate depending on operating temperature, OEM firmware revisions, and sensor calibration.

📄 License

Distributed under the Apache License, Version 2.0. See LICENSE for more information.

_{Built with ❤️ for Android enthusiasts, battery health purists, and the Shizuku community.}

What's Changed

🔄 In-App GitHub Release Checker

• Added manual update check in Settings: directly checks GitHub Releases via public API without background trackers.
• Semantic version comparison with instant changelog preview dialog and 1-tap APK download button.
• Declared transparent android.permission.INTERNET exclusively scoped for release checks.

📱 Hardware Presets & Database

• Added Oppo Find X9 Ultra battery preset (7500 mAh typical / 7290 mAh rated).
• Verified preset detection and capacity calculations.

🧪 Architecture & Tests

• Extracted pure BatteryTelemetryParser for decoupled, reliable fuel-gauge log parsing.
• Added comprehensive unit tests for version comparisons and telemetry decoding.