# Fedora Brightness Automation Buttons OSD

Small Fedora/GNOME brightness setup for laptops with an internal Linux backlight and an external DDC/CI monitor.

The internal display is the master. Brightness keys change the internal panel, show a compact OSD, and a user service mirrors the same percentage to the external monitor with `ddcutil`.

This avoids drift from letting two outputs auto-adjust independently.

## Architecture

The real brightness change is intentionally immediate:

```text
brightness-up/down-all
  -> brightnessctl immediately changes the internal display
  -> brightness-osd only displays or updates the visual feedback
  -> external-brightness-sync.service mirrors the internal percentage later
```

The actual `brightnessctl` call must not be debounced. Only the OSD may be smoothed by reusing the running OSD process and extending its hide timer.

The external monitor is not changed in the key-binding scripts. `ddcutil` is slower than an internal backlight write, so it runs separately in the sync service.

## Features

- Internal display controlled with `brightnessctl`
- External monitor mirrored with `ddcutil` VCP code `10`
- Compact GTK4/libadwaita OSD for custom brightness shortcuts
- Optional Wayland top-edge positioning with `gtk4-layer-shell`
- systemd user service for continuous external sync
- Configurable backlight device, DDC bus, monitor model, step size, and sync interval
- Optional wluma config where only the internal display is managed

## Tested Setup

- Fedora 43
- GNOME Shell 49
- Internal panel: `intel_backlight`
- External monitor: DDC/CI via `ddcutil`

Other Fedora/GNOME setups should work if `brightnessctl` and `ddcutil` can control the displays.

## Dependencies

```bash
sudo dnf install -y brightnessctl ddcutil python3-gobject gtk4 libadwaita gtk4-layer-shell
```

`gtk4-layer-shell` is recommended on GNOME Wayland. Without it, GNOME may place the OSD like a normal GTK window instead of pinning it at the top edge.

If your `ddcutil` command needs sudo, configure passwordless sudo for the specific command you use. Example:

```text
jan ALL=(root) NOPASSWD: /usr/bin/ddcutil
```

Use a stricter sudoers rule if you prefer limiting arguments.

## Quick Install

```bash
git clone https://gitea.diehanis.de/Jan/Fedora_Brightness_Automation_Buttons_OSD.git
cd Fedora_Brightness_Automation_Buttons_OSD
./install.sh
```

The installer writes:

```text
~/.local/bin/brightness-osd
~/.local/bin/brightness-up-all
~/.local/bin/brightness-down-all
~/.local/bin/brightness-sync-hg342pcb
~/.config/systemd/user/external-brightness-sync.service
~/.config/brightness-automation/env
```

Then set your GNOME custom keyboard shortcuts to:

```text
/home/YOUR_USER/.local/bin/brightness-down-all
/home/YOUR_USER/.local/bin/brightness-up-all
```

Use the full path in GNOME Settings.

## Configuration

Edit:

```text
~/.config/brightness-automation/env
```

Default config:

```bash
BRIGHTNESS_BACKLIGHT_DEVICE="intel_backlight"
BRIGHTNESS_SYNC_BACKLIGHT="/sys/class/backlight/intel_backlight"
BRIGHTNESS_OSD_BACKLIGHT="/sys/class/backlight/intel_backlight"
BRIGHTNESS_STEP="10"
BRIGHTNESS_DDCUTIL_MODEL="HG342PCB"
BRIGHTNESS_DDCUTIL_DISPLAY="1"
BRIGHTNESS_DDCUTIL_BUS="16"
BRIGHTNESS_SYNC_INTERVAL="1"
BRIGHTNESS_SYNC_MIN_PERCENT="1"
BRIGHTNESS_OSD_VISIBLE_MS="1400"
```

After changing DDC or sync values:

```bash
systemctl --user restart external-brightness-sync.service
```

## Finding Your Values

Backlight device:

```bash
brightnessctl -l
ls /sys/class/backlight
```

External monitor:

```bash
sudo ddcutil detect
sudo ddcutil getvcp 10
```

If `ddcutil detect` reports a bus like `/dev/i2c-16`, set:

```bash
BRIGHTNESS_DDCUTIL_BUS="16"
```

## wluma

If you use `wluma`, let it manage only the internal display. The external monitor should follow through the sync service.

Optional install of the example wluma config:

```bash
INSTALL_WLUMA_CONFIG=1 ./install.sh
systemctl --user restart wluma.service
```

Example config is in:

```text
wluma/config.toml
```

## Status

```bash
systemctl --user status external-brightness-sync.service
journalctl --user -u external-brightness-sync.service -n 50 --no-pager
```

## Design Notes

Implementation decisions and failed attempts are documented in:

```text
docs/implementation-log.md
```

## Uninstall

```bash
./uninstall.sh
```

The uninstall script keeps `~/.config/brightness-automation/env` so local settings are not destroyed.