LCD Backlight Control Plugin for Volumio 3
Hits: 116
Plugin for Volumio 3 for automatic LCD backlight control based on ambient light levels using VEML7700 light sensor.
This plugin automatically adjusts the brightness of LCD displays with backlight control based on ambient lighting conditions. It uses the VEML7700 ambient light sensor to measure lux levels and dynamically adjusts display brightness for optimal viewing in any lighting environment.
Features
- Automatic Brightness Control: Adjusts LCD backlight based on VEML7700 sensor data
- Configurable Brightness Range: Set minimum and maximum brightness levels according to your preferences
- Smooth Transitions: Configurable smoothing factor for gradual brightness changes
- Customizable Sensor Calibration: Fine-tune sensor response using lux multiplier
- Flexible Measurement Interval: Configure how often the sensor reads ambient light (0.1 - 10 seconds)
- Multi-language Support: Includes English and all translations supported by Volumio system (de, fr, pl, cz, ...)
Hardware Components
| Component | Model/Type | Description |
|---|
| Main Unit |
Raspberry Pi 3B+ |
Control unit |
| Display |
7" LCD DPI (OFI009) |
Touch display connected via DPI interface |
| Encoder |
KY-040 |
Rotary encoder for volume control |
| Light Sensor |
VEML7700 (BH-014PA) |
16-bit I2C ambient light sensor |
Wiring Diagram
I2C Bus (VEML7700 sensor)
Raspberry Pi 3B+ VEML7700 (WL7700)
───────────────── ──────────────────
Pin 1 (3.3V) ──────── Pin 5 (+3.3V)
Pin 3 (GPIO 2) ──────── Pin 2 (SDA)
Pin 5 (GPIO 3) ──────── Pin 1 (SCL)
Pin 6 (GND) ──────── Pin 4 (GND)
GPIO Pin Reference
+-----+-----+---------+------+---+---Pi 3B+-+---+------+---------+-----+-----+
| BCM | wPi | Name | Mode | V | Physical | V | Mode | Name | wPi | BCM |
+-----+-----+---------+------+---+----++----+---+------+---------+-----+-----+
| | | 3.3v | | | 1 || 2 | | | 5v | | |
| 2 | 8 | SDA.1 | ALT0 | 1 | 3 || 4 | | | 5v | | |
| 3 | 9 | SCL.1 | ALT0 | 1 | 5 || 6 | | | 0v | | |
| 4 | 7 | GPIO. 7 | IN | 1 | 7 || 8 | 1 | IN | TxD | 15 | 14 |
+-----+-----+---------+------+---+----++----+---+------+---------+-----+-----+
Rotary Encoder (KY-040)
- CLK: GPIO pin (BCM numbering from
gpio readall)
- DT: GPIO pin (BCM numbering)
- SW: GPIO pin (button)
- +: 3.3V
- GND: Ground
Note: Configure encoder pins in Volumio Rotary Encoder plugin using BCM pin numbers.
KY-040 rotary encoder connection is not required for proper plugin functionality.
Display Connection
- Power: +5V and GND from X1 connector
- DPI signals: Connected according to DPI configuration in
/boot/config.txt
Installation
- Manual Plugin Installation
- If it does not, it is necessary to delete the file /data/configuration/plugins.json and restart Volumio using the command
volumio vrestart
- Automatic Installation – Install the plugin via the Volumio web interface (currently unavailable):
- Go to Plugins → Install Plugins
- Search for "LCD Backlight Control" or upload the plugin package.
The installation script will perform:
- Python dependency installation (
python3-smbus)
- Copying Python control script to
/usr/local/bin/
- Creating configuration directory at
/etc/lcd_backlight/
- Installing and enabling systemd service
- Setting appropriate permissions
Configuration
Access plugin settings via Volumio web interface under Plugins → LCD Backlight Control button Settings.
Available Settings
Measurement Interval
- Range: 0.1 - 10 seconds
- Default: 1 second
- Description: Time between light sensor measurements. Lower values provide more responsive brightness changes but may increase CPU usage.
Minimum Brightness
- Range: 0 - 255
- Default: 12
- Description: The lowest brightness level the display will reach. Prevents the screen from becoming too dim or completely off.
Maximum Brightness
- Range: 0 - 255
- Default: 255
- Description: The highest brightness level the display will reach. Can be lowered to save power or limit maximum brightness.
Lux Multiplier
- Range: 0.01 - 10
- Default: 0.75
- Description: Calibration multiplier for VEML7700 sensor. Increase for brighter response to ambient light, decrease for darker response. Use to fine-tune sensor sensitivity to your environment.
Smoothing Factor
- Range: 0.0 - 1.0
- Default: 0.3
- Description: Controls the speed of brightness transitions. Lower values create slower, smoother transitions. Higher values make brightness changes more immediate and responsive.
Playback Brightness Boost
- Range: 0 - 255
- Default: 0
- Description: Additional brightness added to the calculated brightness level during music playback. This ensures better screen visibility when actively using the player. Set to 0 to disable this feature.
Boost Duration After Playback
- Range: 0 - 300 seconds
- Default: 30 seconds
- Description: How long to maintain the brightness boost after playback stops. This provides a grace period before the brightness returns to ambient-based levels. Useful to keep the screen bright while browsing between tracks.
How It Works
Ambient Light Control
- The plugin reads ambient light levels from the VEML7700 sensor at regular intervals
- The lux reading is multiplied by the configured lux multiplier for calibration
- The brightness value is calculated using a logarithmic curve and constrained within the min/max range
Playback Boost System
- The plugin monitors Volumio's playback state via its REST API (http://localhost:3000/api/v1/getState)
- When playback status changes to "play":
- The configured brightness boost is added to the ambient-calculated brightness
- The boost remains active throughout playback
- When playback stops:
- A countdown timer starts for the configured boost duration
- The boost remains active during this period
- After the timer expires, brightness returns to ambient-only control
- A smoothing algorithm gradually adjusts the backlight to prevent abrupt changes
Final Brightness Calculation
Final Brightness = min(MAX_BACKLIGHT, Ambient_Brightness + Playback_Boost)
Technical Details
File Structure
lcd_backlight/
├── index.js # Main plugin driver
├── backlight_control.py # Python script for hardware control
├── lcd_backlight.service # Systemd service
├── install.sh # Installation script
├── uninstall.sh # Uninstallation script
├── UIConfig.json # Web interface configuration
├── package.json # Plugin metadata
└── i18n/ # Translations
├── strings_en.json # English strings
├── strings_sk.json # Slovak strings
└── strings_xx.json # other language strings
/usr/local/bin/
└── backlight_control.py # Main Python skript
Configuration Files
The plugin stores configuration in two locations:
1. Persistent Configuration
/data/plugins/system_hardware/lcd_backlight/config.json
- Stores all plugin settings
- Managed by Volumio configuration system
2. Runtime Configuration
/etc/lcd_backlight/
- Individual files for each setting (e.g.,
lcd_enabled, lcd_int_time)
- Read by Python control script
- Allows real-time configuration updates without restarting the service
Service Management
The plugin uses a systemd service (lcd_backlight.service) that:
- Runs Python control script as a daemon
- Automatically starts at boot when plugin is enabled
- Automatically restarts on failure
- Logs to systemd journal
Log Output Example
For debugging purposes, uncomment two lines 294 - 295 in backlight_control.py:
# Uncomment for debugging
# if success:
# print(f"[{time.strftime('%H:%M:%S')}] Lux: {lux:6.1f} | Brightness: {self.current_brightness:3d}/{self.max_backlight}")
Console output will be:
[12:34:56] Lux: 245.3 | Brightness: 145/255
[12:34:57] Lux: 248.1 | Brightness: 147/255
[12:34:58] Lux: 251.7 | Brightness: 149/255
Troubleshooting
Plugin Won't Start
- Check if VEML7700 sensor is properly connected via I²C
- Verify I²C is enabled in your system (
sudo i2cdetect -y 1)
- Check systemd service status:
systemctl status lcd_backlight.service
- Check logs:
journalctl -u lcd_backlight.service -f
Brightness Doesn't Change
- Verify backlight device exists:
ls /sys/class/backlight/
- Check configuration files in
/etc/lcd_backlight/
- Ensure
lcd_enabled is set to 1
- Test sensor measurements manually
Brightness Changes Too Fast/Slow
- Adjust Smoothing Factor setting
- Lower values = slower transitions
- Higher values = faster transitions
Display Too Bright/Dark
- Adjust Lux Multiplier to calibrate sensor response
- Adjust Minimum Brightness and Maximum Brightness ranges
- Test in different lighting conditions
Uninstallation
The plugin can be uninstalled via Volumio web interface. The uninstallation process:
- Stops and disables systemd service
- Removes service file
- Removes Python control script
- Cleans up configuration files
