🔦 TorchElos

Advanced Hardware-Level Flashlight Intensity Controller for POCO F5 (marble)

Full 1 to 500 Intensity Range, Zero-Flash Nightlight Startup, and Bidirectional Quick Settings Synchronization.

---

Important

🧪 PUBLIC BETA — ROOT ACCESS REQUIRED

• TorchElos is currently in public Beta.
• ROOT ACCESS IS MANDATORY: You must have KernelSU, Magisk, or APatch installed. Without Root permissions, Android prevents apps from directly controlling the PMIC kernel sysfs registers.
• Engineered specifically for POCO F5 (marble) and Redmi Note 12 Turbo (Snapdragon 7+ Gen 2) on Android 13 to 16+.

---

⚠️ Disclaimer & Hardware Warning

Caution

USE AT YOUR OWN RISK — NO LIABILITY

• Do NOT run intensity level 500 (100% / Plein phare) continuously for extended periods.
  At level 500, the dual PMIC LED drivers inject 500 mA of continuous electrical current into the flash module. This generates significant heat and can cause thermal degradation, reduce LED lifespan, or cause hardware damage to the flash module if left running unattended.
• We strongly recommend using level 500 only for short bursts when maximum illumination is required. For daily use, levels between 1 and 130 provide more than enough illumination while remaining cool and energy-efficient.
• The author and contributors of TorchElos assume NO responsibility or liability for any hardware damage, overheated/burnt LED units, battery degradation, software crashes, or any other issues that may occur on your device.

---

📖 Background

On the POCO F5 and Redmi Note 12 Turbo (Snapdragon 7+ Gen 2), standard Android flashlight apps cannot adjust brightness because the OEM camera HAL does not expose multi-level brightness controls (FLASH_INFO_STRENGTH_MAXIMUM_LEVEL = 1). On top of that, the system driver fires a harsh factory pulse on activation — unpleasant when all you want is a soft nightlight.

---

💡 How TorchElos Works

TorchElos bypasses the restricted Camera HAL by interfacing directly with the Qualcomm PMIC kernel drivers via root (sysfs):

• Direct Hardware Control: Drives the LED driver across the full 1 to 500 hardware range for fine-grained brightness control.
• Zero-Flash Soft Startup: Suppresses the harsh factory ignition pulse, enabling the light to turn on directly at your chosen intensity (such as an ultra-dim level 1 nightlight).
• Quick Settings Sync: Synchronizes state with the system Quick Settings flashlight tile, and applies your saved intensity when the stock tile is used.
• Non-Destructive: No system or vendor partition is ever modified. Changes are volatile (reverted on reboot) and the standard camera flash triggers are automatically restored when turning off.

---

✨ Features

• Ultra-Lightweight Footprint:
  • Highly optimized with R8 minification and resource shrinking (~2.0 MB).
• Full 1 to 500 Range:
  • 1 / 500 : Ultra-soft nightlight — easy on your eyes in complete darkness.
  • 50 / 500 : Eco illumination for reading and navigation.
  • 130 / 500 : Standard balanced flashlight (factory default intensity).
  • 500 / 500 : Maximum hardware turbo.
• Intuitive Controls:
  • Smooth intensity slider.
  • Direct numeric entry dialog (tap the level badge to enter exact values like 42 or 360).
  • One-tap quick presets: Nightlight (1), Eco (50), Standard (130), Turbo (500).
• Zero-Friction Launch:
  • Launches instantly without requiring camera runtime permissions.
• Quick Settings Integration:
  • Dedicated custom tile (TorchTileService) with real-time level readout.
  • Synchronized with the stock system flashlight toggle.
• Hardware Telemetry & Status:
  • Automatic detection of your root solution (KernelSU, Magisk, APatch), device model, flash PMIC, and active ROM.

---

📱 Compatibility & Requirements

Requirement	Supported
Target Device	POCO F5 (marble) / Redmi Note 12 Turbo
Processor	Qualcomm Snapdragon 7+ Gen 2 (SM7475)
Android Version	Android 13 to 16+ (API 33+), targetSdk 35
ROM Support	LineageOS, crDroid, PixelOS, and all AOSP ROMs, as well as Stock rooted HyperOS / MIUI
Root Solution	KernelSU, Magisk, or APatch (Required)

---

🚀 Installation

1. Download the latest TorchElos-v*.apk from the Releases section.
2. Install the APK on your device.
3. Open TorchElos and Grant Superuser / Root permissions when prompted (by KernelSU, Magisk, or APatch).
4. (Optional) Add the Torch tile to your Quick Settings panel.

Warning

Upgrading from v1.0.0-beta or v1.1.0-beta: the release signing key was rotated for security reasons. Android will refuse to install the new version over the old one — uninstall the previous version first, then install v1.2.0-beta.

---

🩺 Troubleshooting

Symptom	Fix
"Intensity control unavailable"	Root access is not granted to TorchElos. Open KernelSU Next / Magisk / APatch, allow TorchElos, then reopen the app.
Camera flash stopped working after a crash	The CamX triggers may still be disarmed. Reopen TorchElos once (they are restored automatically) or reboot the device.
The intensity slider is missing	The app fell back to the standard Camera2 engine (no root, or the device does not expose led:torch_0). See the first row.
Stock flashlight tile behaves differently	The stock tile goes through the camera service; use the dedicated Torch tile for the most reliable behavior.

Found a bug or an unsupported device? Please open an issue.

---

🛠️ Building from Source

Prerequisites: Android Studio Ladybug / Meerkat or command-line Gradle with JDK 21 and Android SDK 35+.

# Clone the repository
git clone https://github.com/tgiraud2007/TorchElos.git
cd TorchElos

# Build the Debug APK
./gradlew assembleDebug

# The generated APK will be located at:
# app/build/outputs/apk/debug/app-debug.apk

# Run unit tests and lint
./gradlew testDebugUnitTest lintDebug

Release signing

Release builds are signed from a local, git-ignored keystore.properties file at the project root:

storeFile=app/torchelos-release.jks
storePassword=********
keyAlias=torchelos
keyPassword=********

# Generate a new keystore (only if you do not have one)
keytool -genkeypair -v -keystore app/torchelos-release.jks -storetype PKCS12 \
  -alias torchelos -keyalg RSA -keysize 4096 -validity 10000

# Build the signed Release APK
./gradlew assembleRelease

Without keystore.properties, release builds are simply left unsigned (debug builds are unaffected).

Releasing

Releases are automated. Bump versionName and versionCode in app/build.gradle.kts, commit, then push a tag:

git tag v1.2.0-beta
git push origin v1.2.0-beta

The Release workflow then builds the signed APK and publishes it on the tag. Signing relies on the repository Actions secrets (KEYSTORE_BASE64, KEYSTORE_PASSWORD, KEY_ALIAS, KEY_PASSWORD).

---

📄 License

This project is licensed under the MIT License.