# Screen Brightness Control — Summary

Short overview of how the reTerminal DM brightness system works.

---

## What it does



---

## Components

| Component | Role |
|-----------|------|
| **screen-brightness** (daemon) | Reads sensor and override, drives backlight and buzzer; writes `/run/screen-brightness/state`. |
| **brightness-api** (HTTP) | Listens on `127.0.0.1:8765`. POST sets override (level 1–5 or auto); GET returns current state. |
| **brightness-overlay** (UI) | Small icon in bottom-right of screen; click to expand/collapse panel with buttons 1–5 and Auto. Talks to the API. |

---

## Levels and modes

- **Levels 1–5:** 1 = dimmest, 5 = brightest. Written to `/sys/class/backlight/lcd_backlight/brightness` (0 is never used).
- **Auto:** Override file set to `auto` (or missing). Daemon uses ambient light to pick level.
- **Manual:** Override file contains `1`–`5`. Daemon keeps that level until user switches back to Auto.

Override file: `/run/screen-brightness/override`  
State file (read-only): `/run/screen-brightness/state` (mode, level, lux, override=0|1).

---

## On-screen overlay

- **Icon:** Brightness (sun) icon in the bottom-right corner; transparent when retracted.
- **Click icon:** Panel expands with “Brightness”, buttons **1 2 3 4 5**, and **Auto**. Semi-transparent background behind the buttons.
- **Active state:** The current level or Auto is highlighted so you can see which is active.
- **Click again:** Panel retracts to icon only.

Overlay uses the local API; if GtkLayerShell is available (Wayland), it stays on top of fullscreen apps.

---

## Services and boot

- **screen-brightness.service** — Starts the daemon. `ExecStartPre` writes `auto` into the override file so every boot starts in Auto.
- **brightness-api.service** — Starts the HTTP API (after `screen-brightness`).
- **brightness-overlay** — Started from the user session (e.g. autostart) so it appears on the desktop.

---

## Quick reference

| Action | How |
|--------|-----|
| Set level 3 | Overlay: expand → click **3**. Or: `echo 3 > /run/screen-brightness/override` (root). |
| Set Auto | Overlay: expand → click **Auto**. Or: `echo auto > /run/screen-brightness/override`. |
| Read state | `curl http://127.0.0.1:8765/state` or `cat /run/screen-brightness/state`. |
| Config | `/etc/screen-brightness.conf` (optional); `systemctl reload screen-brightness` to apply. |

For full setup and regulations, see [SCREEN-BRIGHTNESS-MANUAL-SETUP.md](SCREEN-BRIGHTNESS-MANUAL-SETUP.md) and [SCREEN-BRIGHTNESS-REGULATIONS.md](SCREEN-BRIGHTNESS-REGULATIONS.md).