Initial Fedora brightness automation setup

README.md

@@ -0,0 +1,152 @@
+# 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.
+
+## 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_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
+```
+
+## Uninstall
+
+```bash
+./uninstall.sh
+```
+
+The uninstall script keeps `~/.config/brightness-automation/env` so local settings are not destroyed.