Feature Request: Add generic lux input support for DIY ambient light sensors

Author: FanchangWangCreated Sep 7, 2026Updated Sep 7, 2026

Background

Currently, Twinkle Tray's ambient light auto-brightness feature only supports two types of hardware sensors:

  1. Windows standard HID ambient light sensors — they require hardware compliant with USB HID sensor specifications, which has a high barrier for DIY implementation.
  2. Yocto-Light-V2 commercial USB sensors — dedicated hardware with relatively high cost and limited accessibility.

However, DIY ambient light sensor solutions using common microcontrollers (ESP8266 / ESP32 / RP2040, etc.) paired with low-cost light modules (BH1750 / VEML7700, etc.) are very popular among desktop users. These setups have very low hardware cost, can output standard Lux values stably, and provide accuracy fully sufficient for display auto-brightness use cases.

Currently these DIY solutions cannot integrate directly with Twinkle Tray. Users have to write their own intermediate scripts to read Lux values and control display brightness separately, which means they cannot reuse Twinkle Tray's mature features like brightness curves, smooth transitions, and multi-monitor management — resulting in a fragmented user experience.


Proposed Solutions

Option 1: Local text file reader (simplest implementation, recommended priority)

Add a new "Generic File Sensor" option with the following core logic:

  • Users specify a local text file path in Settings.
  • Twinkle Tray reads the file content periodically in read-only mode, and parses the plain numeric value inside as the Lux illuminance value.
  • Fully reuses all existing logic: sensor data validation, fallback behavior, brightness mapping, smooth transitions, etc.

Advantages:

  • Very low implementation effort, with minimal intrusion to the existing codebase.
  • Extremely versatile: Lux values from any source (serial port, UDP broadcast, HTTP API, custom scripts, etc.) can be fed into Twinkle Tray simply by writing to the text file. Compatible with all DIY hardware solutions.
  • Can also serve as a simple entry point for developers to debug sensor functionality.

Option 2: Plugin-based sensor extension interface (long-term plan)

Open up a plugin specification for sensor adapters, allowing third parties to implement custom Lux acquisition logic (serial, network, custom hardware protocols, etc.) and load them as plugins into Twinkle Tray.

Advantages: Strong ecosystem extensibility — the community can contribute support for more niche sensor solutions. Drawbacks: Larger development effort, suitable for long-term roadmap planning.


Expected Benefits

  1. Significantly lowers the hardware barrier for users to enable ambient light auto-brightness, allowing more users to use Twinkle Tray's auto-dimming capability with low-cost DIY solutions.
  2. Covers a broader desktop user base and unlocks community ecosystem potential.
  3. Users can leverage Twinkle Tray's mature dimming capabilities for a more cohesive overall experience.

Source: xanderfrangos/twinkle-tray