✓ Stable v0.1.0

gartray

Quick settings panel for the gardesk desktop

gartray is a quick settings panel that provides easy access to system controls including volume, screen brightness, WiFi networks, Bluetooth devices, battery status, and power options. Designed for the gardesk ecosystem, it integrates with system services via D-Bus and provides a polished UI built on gartk. Note: System tray functionality has been moved to garbar.

View on GitHub Download RPM

🎯 RPM Available

Installation

gartray is available as an RPM package for Fedora and RHEL-compatible distributions.

Using DNF (Recommended)

$sudo dnf config-manager --add-repo https://repos.musicsian.com/musicsian.repo

$sudo dnf install gartray

Building from Source

$git clone https://github.com/espadon/gardesk.git

$cd gardesk/gartray

$cargo build --release

$sudo cp target/release/gartray /usr/local/bin/

$sudo cp target/release/gartrayctl /usr/local/bin/

Dependencies

Runtime dependencies for all features:

wpctl - WirePlumber CLI for volume control (wireplumber package)
NetworkManager - WiFi management
BlueZ - Bluetooth support
UPower - Battery status
systemd - Power actions via login1
brightnessctl - Brightness control fallback (optional)
dunstctl - DND integration (optional, for dunst users)

Quick Start

Start the gartray daemon and show the quick settings panel:

Start the Daemon

$gartray daemon

INFO Starting gartray daemon INFO Connected to PipeWire via wpctl INFO Network module connected, WiFi enabled: true INFO Bluetooth module connected, powered: true INFO Power module connected to D-Bus

Show Quick Settings

$# Show at default position (0, 0)

$gartrayctl show

$# Show at specific screen position

$gartrayctl show 1200 50

$# Toggle panel visibility

$gartrayctl toggle 1200 50

Autostart with gar

Add gartray to your gar window manager startup:

-- ~/.config/gar/init.lua
gar.spawn("gartray daemon")

-- Bind to a key (e.g., Super+S)
gar.bind("super+s", function()
    -- Show panel at cursor position or fixed location
    gar.spawn("gartrayctl toggle 1200 50")
end)

Panel Features

The quick settings panel provides intuitive controls for common system settings:

Volume Control

Slider for system volume, mute toggle, real-time updates via WirePlumber/PipeWire.

Screen Brightness

Slider for backlight control, auto-detects laptop displays, uses sysfs or brightnessctl.

WiFi Networks

Toggle WiFi, scan for networks, connect with saved or new passwords, 802.1X enterprise support.

Bluetooth

Toggle Bluetooth, view paired devices, connect/disconnect, start discovery for new devices.

Battery Status

Display battery percentage, charging status, and estimated time remaining.

Power Options

Shutdown, reboot, suspend, hibernate, and logout via systemd-logind.

Configuration

gartray is configured via a TOML file at ~/.config/gartray/config.toml. All settings have sensible defaults - you only need to create a config file to customize behavior.

Minimal Configuration

A minimal config to change panel width and disable unused modules:

# ~/.config/gartray/config.toml

[panel]
width = 400
modules = ["volume", "brightness", "network", "power"]

Full Configuration Example

# ~/.config/gartray/config.toml

[panel]
enabled = true
width = 360
modules = ["volume", "brightness", "network", "bluetooth", "battery", "power"]

[panel.volume]
show_per_app = false
show_input = false

[panel.network]
show_vpn = true
show_ethernet = true

[panel.bluetooth]
show_battery = true

[theme]
preset = "dark"

Panel Options

Option	Type	Default	Description
`enabled`	bool	true	Enable the quick settings panel
`width`	u32	360	Panel width in pixels
`modules`	string[]	["volume", "brightness", "network", "bluetooth", "battery", "power"]	Enabled modules in display order

Volume Module Options

Option	Type	Default	Description
`show_per_app`	bool	false	Show per-application volume controls
`show_input`	bool	false	Show microphone/input controls

Network Module Options

Option	Type	Default	Description
`show_vpn`	bool	false	Show VPN connection status
`show_ethernet`	bool	false	Show wired ethernet connections

Bluetooth Module Options

Option	Type	Default	Description
`show_battery`	bool	false	Show battery level for connected Bluetooth devices

Theme Options

Option	Type	Default	Description
`preset`	string	"dark"	Theme preset: dark, light, or custom

Reload Configuration

Reload configuration without restarting the daemon:

$gartrayctl reload

Overview

gartray is a quick settings panel designed for the gardesk desktop environment. It provides a centralized interface for controlling common system settings without opening full-featured settings applications. The panel integrates with standard Linux desktop services via D-Bus to provide native functionality.

Key design principles:

Minimal resource usage - runs as a daemon, shows panel on demand
Native integration - uses D-Bus for system services, not wrapper scripts
Modular design - enable only the modules you need
Consistent UI - built on gartk for gardesk visual consistency

Note: System tray (StatusNotifierItem/SNI) functionality has been moved to garbar where it appears in the status bar alongside other indicators.

Architecture

gartray uses a daemon architecture where the main process maintains connections to system services and renders the panel when requested.

Daemon Model

The gartray daemon runs continuously in the background, maintaining D-Bus connections to system services. This allows the panel to open instantly without connection delays.

Daemon Lifecycle:
┌─────────────────────────────────────────────────────────┐
│ 1. Start daemon                                         │
│    ├── Load configuration                               │
│    ├── Initialize module connections                    │
│    │   ├── Volume: connect to wpctl                     │
│    │   ├── Brightness: probe /sys/class/backlight       │
│    │   ├── Network: connect to NetworkManager D-Bus     │
│    │   ├── Bluetooth: connect to BlueZ D-Bus            │
│    │   ├── Battery: connect to UPower D-Bus             │
│    │   ├── Power: connect to login1 D-Bus               │
│    │   └── DND: check for dunstctl                      │
│    └── Listen for IPC commands                          │
│                                                         │
│ 2. Handle IPC commands (show/hide/toggle/reload/quit)   │
│                                                         │
│ 3. When shown: render panel, handle user interaction    │
│                                                         │
│ 4. When hidden: return to idle, maintain connections    │
└─────────────────────────────────────────────────────────┘

Panel System

The panel is a popup window rendered using gartk. Each module contributes a section to the panel UI. Modules are displayed in the order specified in the configuration.

Panel Layout:
┌────────────────────────────────────────┐
│  🔊 Volume ──────────────────○──── 75% │
│  ☐ Mute                                │
├────────────────────────────────────────┤
│  🔆 Brightness ──────────────○──── 50% │
├────────────────────────────────────────┤
│  📶 WiFi: MyNetwork         [Toggle ☑] │
├────────────────────────────────────────┤
│  🔵 Bluetooth               [Toggle ☑] │
├────────────────────────────────────────┤
│  🔋 Battery: 85% ⚡          3h 20m    │
├────────────────────────────────────────┤
│  ⏻ Shutdown  🔄 Restart  💤 Suspend   │
└────────────────────────────────────────┘

Module Lifecycle

Each module implements a common interface for initialization and state updates. Modules gracefully handle unavailable services (e.g., no battery on a desktop).

// Module trait interface
pub trait PanelModule {
    /// Module name for configuration
    fn name(&self) -> &'static str;

    /// Update module state
    fn update(&mut self);
}

Modules are initialized at daemon startup and maintain their service connections for the daemon's lifetime. State is refreshed when the panel is shown to ensure current values.

D-Bus Integration

gartray integrates with standard Linux desktop services via D-Bus for native control of system settings.

NetworkManager

WiFi control uses the NetworkManager D-Bus interface on the system bus. This provides:

WiFi enable/disable via WirelessEnabled property
Network scanning via Device.Wireless.RequestScan
Access point enumeration with SSID, signal strength, security type
Connection management including saved credentials
Enterprise WiFi (802.1X) via nmcli for complex authentication

D-Bus Service: org.freedesktop.NetworkManager
Object: /org/freedesktop/NetworkManager

Key Methods:
  GetDevices() -> ao                    # Get device paths
  ActivateConnection(o, o, o)           # Activate a saved connection
  AddAndActivateConnection(a{sa{sv}}, o, o) # Create and connect

Device.Wireless Methods:
  RequestScan(a{sv})                    # Trigger network scan
  GetAccessPoints() -> ao               # Get available networks

BlueZ

Bluetooth control uses the BlueZ D-Bus interface. The module uses ObjectManager to discover adapters and devices dynamically.

Adapter discovery via ObjectManager.GetManagedObjects
Power control via Adapter1.Powered property
Device enumeration including paired and discovered devices
Connect/disconnect via Device1 interface
Discovery mode for pairing new devices

D-Bus Service: org.bluez
Object: / (for ObjectManager), /org/bluez/hci0 (adapter)

Adapter1 Interface:
  Powered (bool)           # Read/write power state
  StartDiscovery()         # Start scanning for devices
  StopDiscovery()          # Stop scanning

Device1 Interface:
  Connect()                # Connect to device
  Disconnect()             # Disconnect from device
  Name, Address, Paired, Connected, Icon (properties)

UPower

Battery information comes from UPower's DisplayDevice, which aggregates information from all power sources into a single logical battery.

D-Bus Service: org.freedesktop.UPower
Object: /org/freedesktop/UPower/devices/DisplayDevice

Device Properties:
  Percentage (d)           # 0-100 battery level
  State (u)                # 1=Charging, 2=Discharging, 4=FullyCharged
  TimeToEmpty (x)          # Seconds until empty (when discharging)
  TimeToFull (x)           # Seconds until full (when charging)
  IsPresent (b)            # Whether battery is physically present
  Type (u)                 # 2 = Battery

State Constants:
  0 = Unknown
  1 = Charging
  2 = Discharging
  3 = Empty
  4 = Fully Charged
  5 = Pending Charge
  6 = Pending Discharge

systemd-logind

Power actions use the systemd-logind D-Bus interface with systemctl fallback for environments where D-Bus calls may be restricted.

D-Bus Service: org.freedesktop.login1
Object: /org/freedesktop/login1

Manager Methods:
  PowerOff(b)              # Shutdown (interactive: bool)
  Reboot(b)                # Restart
  Suspend(b)               # Sleep
  Hibernate(b)             # Hibernate to disk
  TerminateSession(s)      # Logout (session id)

  CanPowerOff() -> s       # Check if action is allowed
  CanReboot() -> s         # Returns "yes", "no", or "challenge"
  CanSuspend() -> s
  CanHibernate() -> s

Rendering

gartray uses gartk for all rendering, providing consistent visuals with other gardesk components.

gartk Integration

The panel is rendered using gartk's rendering primitives:

Theme - Colors, fonts, and spacing from gartk theme system
Renderer - Cairo-based drawing for shapes and text
Window - X11 window management via gartk-x11
Event Loop - Input handling for sliders and buttons

Panel Layout

Modules are laid out vertically with configurable spacing. Each module renders its own section with:

Icon and label for identification
Primary control (slider, toggle, or status)
Optional secondary information (percentage, time remaining)
Interactive elements (buttons, lists)

Panel Modules

gartray is organized into independent modules, each providing a specific quick setting. Modules can be enabled or disabled via configuration, and their display order is configurable.

Volume Module

Controls audio output via wpctl, the WirePlumber command-line tool for PipeWire.

Features

Volume slider (0% to 150%)
Mute toggle
Real-time updates when volume changes externally

How It Works

# Get current volume
wpctl get-volume @DEFAULT_AUDIO_SINK@
# Output: "Volume: 0.75" or "Volume: 0.50 [MUTED]"

# Set volume to 80%
wpctl set-volume @DEFAULT_AUDIO_SINK@ 0.80

# Toggle mute
wpctl set-mute @DEFAULT_AUDIO_SINK@ toggle

Brightness Module

Controls screen brightness via the Linux backlight interface.

Features

Brightness slider (1% to 100%)
Auto-detects backlight device from /sys/class/backlight/
Falls back to brightnessctl if direct write fails

How It Works

# Direct sysfs access (requires permissions)
cat /sys/class/backlight/intel_backlight/brightness
cat /sys/class/backlight/intel_backlight/max_brightness
echo 500 > /sys/class/backlight/intel_backlight/brightness

# Fallback via brightnessctl
brightnessctl set 500

The module first attempts direct sysfs writes, which may require udev rules or group membership. If that fails, it uses brightnessctl which typically has the necessary permissions via polkit.

Network Module

WiFi control via NetworkManager D-Bus interface.

Features

WiFi enable/disable toggle
Scan and list available networks
Show signal strength and security type
Connect to networks with saved credentials
Password prompt for new WPA/WPA2 networks
802.1X enterprise WiFi authentication (via nmcli)

Security Types

Open - No password required
WPA/WPA2 - Personal networks with PSK
WPA-Ent/WPA2-Ent - Enterprise networks with 802.1X

Enterprise WiFi

For 802.1X enterprise networks, gartray prompts for EAP credentials:

EAP method (PEAP, TTLS, TLS)
Identity (username)
Password
Phase 2 authentication (MSCHAPv2, PAP, GTC)
Optional: Anonymous identity, CA certificate

Bluetooth Module

Bluetooth control via BlueZ D-Bus interface.

Features

Bluetooth enable/disable toggle
List paired and discovered devices
Show device type, connection status
Connect/disconnect devices
Start/stop discovery for pairing

Device Information

For each device, the module shows:

Name - Human-readable device name or alias
Address - Bluetooth MAC address
Icon - Device type (headphones, keyboard, phone, etc.)
Status - Paired, connected, trusted flags

Battery Module

Battery status via UPower D-Bus interface.

Features

Battery percentage (0-100%)
Charging/discharging indicator
Time remaining estimate (to empty or to full)
Appropriate icon based on level and state

Battery Icons

Discharging:
  80-100% → battery-full
  50-79%  → battery-good
  20-49%  → battery-low
  5-19%   → battery-caution
  0-4%    → battery-empty

Charging:
  80-100% → battery-full-charging
  50-79%  → battery-good-charging
  20-49%  → battery-low-charging
  0-19%   → battery-caution-charging

Fully Charged → battery-full-charged
Missing/No battery → battery-missing

Power Module

Power actions via systemd-logind D-Bus interface.

Actions

Shutdown - Power off the system
Reboot - Restart the system
Suspend - Sleep (RAM)
Hibernate - Sleep (disk)
Logout - End the current session

Fallback Handling

If D-Bus calls fail (e.g., due to polkit restrictions), the module falls back to:

systemctl poweroff for shutdown
systemctl reboot for restart
systemctl suspend for sleep
pkill -TERM -x gar for logout (kills window manager)

Do Not Disturb Module

Toggle notifications on/off, with optional dunst integration.

Features

Simple on/off toggle
Integrates with dunst via dunstctl if available
Falls back to local state tracking

Dunst Integration

# Check current state
dunstctl is-paused
# Output: "true" or "false"

# Enable DND (pause notifications)
dunstctl set-paused true

# Disable DND (resume notifications)
dunstctl set-paused false

Control CLI: gartrayctl

The gartrayctl command-line tool controls the gartray daemon via IPC. It's the primary way to show/hide the panel and manage the daemon.

Commands

Command	Description
`show [X] [Y]`	Show the quick settings panel at position X,Y (defaults to 0,0)
`hide`	Hide the quick settings panel
`toggle [X] [Y]`	Toggle panel visibility at position X,Y
`reload`	Reload configuration from disk
`status`	Show daemon status and module states
`quit`	Stop the gartray daemon

Usage Examples

Show at Specific Position

$# Show at top-right corner (assuming 1920x1080 screen)

$gartrayctl show 1560 0

Toggle with Keybind

Bind to a key in your window manager for quick access:

-- gar config (~/.config/gar/init.lua)
gar.bind("super+s", function()
    gar.spawn("gartrayctl toggle 1200 50")
end)

-- Or position near the mouse cursor
gar.bind("super+s", function()
    local mouse = gar.get_cursor_pos()
    gar.spawn("gartrayctl toggle " .. mouse.x .. " " .. mouse.y)
end)

Check Daemon Status

$gartrayctl status

Daemon: running Panel: hidden Modules: volume: available (75%, unmuted) brightness: available (50%) network: available (WiFi enabled, connected: MyNetwork) bluetooth: available (powered) battery: available (85%, discharging) power: available

IPC Protocol

gartray uses a Unix domain socket for IPC. The socket is created at $XDG_RUNTIME_DIR/gartray.sock.

Available Commands

Command	Description
`show`	Show panel at position (x: i32, y: i32)
`hide`	Hide the panel
`toggle`	Toggle panel visibility (x: i32, y: i32)
`reload`	Reload configuration
`status`	Get daemon and module status
`quit`	Stop the daemon

garbar Integration

gartray is commonly triggered from garbar status bar clicks. Add a widget to your garbar configuration:

-- garbar config
modules = {
    -- ... other modules ...
    {
        type = "button",
        icon = "settings",
        on_click = "gartrayctl toggle",  -- Opens at click position
    },
}

Common Issues

Volume Module Not Working

If the volume module shows as unavailable:

Check wpctl

$wpctl get-volume @DEFAULT_AUDIO_SINK@

Volume: 0.75

If this fails, ensure PipeWire and WirePlumber are installed and running:

$systemctl --user status pipewire wireplumber

$sudo dnf install pipewire wireplumber

Brightness Control Permission Denied

Direct sysfs writes require appropriate permissions. Solutions:

Option 1: Install brightnessctl

$sudo dnf install brightnessctl

Option 2: Add udev rule

# /etc/udev/rules.d/90-backlight.rules
ACTION=="add", SUBSYSTEM=="backlight", RUN+="/bin/chgrp video $sys$devpath/brightness"
ACTION=="add", SUBSYSTEM=="backlight", RUN+="/bin/chmod g+w $sys$devpath/brightness"

$# Then add your user to the video group

$sudo usermod -aG video $USER

$# Log out and back in for the change to take effect

WiFi Not Working

The network module requires NetworkManager:

$# Check if NetworkManager is running

$systemctl status NetworkManager

$# Start if not running

$sudo systemctl enable --now NetworkManager

Bluetooth Not Detected

Ensure BlueZ is running:

$systemctl status bluetooth

$sudo systemctl enable --now bluetooth

If you have a Bluetooth adapter but it's not detected:

$bluetoothctl show

$# Should show adapter info. If not:

$rfkill list bluetooth

$rfkill unblock bluetooth

Battery Not Showing

The battery module is automatically hidden on systems without batteries. Verify UPower detects your battery:

$upower -e

/org/freedesktop/UPower/devices/battery_BAT0 /org/freedesktop/UPower/devices/DisplayDevice

$upower -i /org/freedesktop/UPower/devices/DisplayDevice

percentage: 85% state: discharging time to empty: 3.3 hours

Power Actions Require Password

If shutdown/reboot prompts for authentication, this is a polkit policy. You can:

Option 1: Use systemctl (default fallback)

gartray automatically falls back to systemctl, which typically works without prompts.

Option 2: Configure polkit

/* /etc/polkit-1/rules.d/85-allow-shutdown.rules */
polkit.addRule(function(action, subject) {
    if (action.id.indexOf("org.freedesktop.login1.") == 0 &&
        subject.isInGroup("wheel")) {
        return polkit.Result.YES;
    }
});

Panel Opens at Wrong Position

The position is passed via gartrayctl. Make sure you're providing the correct coordinates:

$# Specify exact position

$gartrayctl show 1200 50

$# Or use toggle with position

$gartrayctl toggle 1200 50

Debug Mode

Run the daemon in foreground with verbose logging:

$RUST_LOG=debug gartray daemon --foreground

DEBUG Checking for wpctl... DEBUG Volume: 75%, muted: false DEBUG Found backlight device: intel_backlight (max=1000) DEBUG Current brightness: 50% ...

Getting Help

For further assistance:

Check the GitHub issues for known problems
Open a new issue with debug logs and system information
Include output of gartrayctl status