Beta

gartray

Quick Settings Panel

A quick settings panel with controls for volume, brightness, network (including enterprise WiFi), bluetooth, battery status, and power options. Built with zbus for D-Bus integration and gartk for X11/Cairo rendering.

View on GitHub Install

Features

Quick settings panel with system controls
Volume control via WirePlumber/PipeWire
Brightness control via sysfs backlight
Network management via NetworkManager
Enterprise WiFi (802.1X) with EAP form UI
Bluetooth control via BlueZ
Battery status via UPower
Power actions via systemd-logind
Do Not Disturb toggle (dunst integration)
Keyboard navigation with Escape, Tab, and arrow keys
IPC control via gartrayctl

Quick Start Guide

Get gartray running as a standalone quick settings panel or integrated with garbar.

1. Installation

Install gartray using the unified installer or build from source:

terminal

$ curl -fsSL https://gar.musicsian.com/install.sh | bash -s -- --component=gartray # Install via script

$ cd ~/.local/src/gardesk/gartray && cargo build --release # Or build from source

2. System Dependencies

gartray requires these system services for full functionality:

System Services

PipeWire/WirePlumber - Volume control
NetworkManager - Network/WiFi control
BlueZ - Bluetooth control
UPower - Battery status
systemd-logind - Power actions
dunst - Do Not Disturb (optional)

3. Running gartray

gartray runs as a daemon with three modes:

terminal

$ gartray daemon # Start the daemon

$ gartray panel # Show quick settings panel

$ gartray toggle # Toggle panel visibility

4. Configuration

Create a configuration file at ~/.config/gartray/config.toml:

terminal

$ mkdir -p ~/.config/gartray # Create config directory

$ $EDITOR ~/.config/gartray/config.toml # Edit configuration

5. Control with gartrayctl

Use gartrayctl to control the running daemon:

terminal

$ gartrayctl show 100 200 # Show panel at position (100, 200)

$ gartrayctl hide # Hide the panel

$ gartrayctl toggle # Toggle panel visibility

$ gartrayctl reload # Reload configuration

$ gartrayctl status # Get daemon status

$ gartrayctl quit # Stop the daemon

Configuration Reference

gartray uses TOML configuration at ~/.config/gartray/config.toml.

Full Configuration Example

~/.config/gartray/config.toml

# Quick settings panel
[panel]
enabled = true
width = 360                # Panel width in pixels
modules = [
  "volume",
  "brightness",
  "network",
  "bluetooth",
  "battery",
  "power"
]

# Volume control options
[panel.volume]
show_per_app = false       # Show per-application volume sliders
show_input = false         # Show input device controls

# Network options
[panel.network]
show_vpn = false           # Show VPN connections
show_ethernet = false      # Show ethernet interfaces

# Bluetooth options
[panel.bluetooth]
show_battery = false       # Show device battery percentage

# Theme customization
[theme]
preset = "dark"            # "dark", "light", or "custom"

Available Panel Modules

Module	Backend	Description
volume	wpctl	Volume slider and mute toggle
brightness	sysfs	Screen brightness slider
network	NetworkManager	WiFi networks and connection status
bluetooth	BlueZ	Bluetooth devices and pairing
battery	UPower	Battery status and time remaining
power	systemd-logind	Shutdown, reboot, suspend, hibernate
dnd	dunstctl	Do Not Disturb toggle

Overview

gartray is a quick settings panel for the gar desktop environment. It provides a popup panel with controls for volume, brightness, network, bluetooth, battery, and power actions.

Note: System tray functionality (XEMBED and SNI protocols) has been moved to garbar's built-in tray module. gartray now focuses on the quick settings panel.

Architecture

gartray consists of two binaries:

gartray - Main daemon managing the popup panel
gartrayctl - Control client for IPC commands

Key Components

Component	Purpose
daemon	Main event loop, lifecycle management
panel	Quick settings popup window
panel/eap	Enterprise WiFi (802.1X) authentication form
ipc	Unix socket IPC server/client
config	TOML configuration loading

Dependencies

gartk - Shared toolkit (gartk-core, gartk-x11, gartk-render)
zbus 4.0 - D-Bus communication
x11rb 0.13 - X11 protocol
cairo-rs 0.20 - 2D graphics
tokio 1.0 - Async runtime

Quick Settings Panel

The quick settings panel provides a unified interface for common system controls. It appears as a popup window that can be triggered via IPC or click events.

Select a module from the sidebar to learn about its specific functionality.

Panel Features

Transparent ARGB window with no decoration
Keyboard grab for input capture
Cairo-based rendering
Slider controls for continuous values
Toggle buttons for binary options
List views for network/bluetooth devices
Hover and drag interaction support

Keyboard Shortcuts

Key	Action
Escape	Close panel / cancel password entry / cancel EAP form
Enter	Connect to network / confirm EAP form
Tab	Next field (EAP form)
Shift+Tab	Previous field (EAP form)
Left / Right	Move cursor in text fields / cycle dropdowns
Home / End	Jump to start / end of text field

Volume Control

Controls audio volume via WirePlumber/PipeWire using the wpctl command.

State

volume - Current volume (0.0 to 1.0)
muted - Whether audio is muted

Commands

terminal

$ wpctl get-volume @DEFAULT_AUDIO_SINK@ # Query current volume

$ wpctl set-volume @DEFAULT_AUDIO_SINK@ 0.50 # Set volume to 50%

$ wpctl set-mute @DEFAULT_AUDIO_SINK@ toggle # Toggle mute

Output Parsing

The wpctl get-volume output is parsed:

Volume: 0.50 - Volume at 50%
Volume: 0.50 [MUTED] - Volume at 50%, muted

Configuration Options

[panel.volume]
show_per_app = false   # Per-application volume sliders
show_input = false     # Input device controls

Network Control

Controls WiFi and network connections via NetworkManager D-Bus interface.

State

wifi_enabled - Whether WiFi radio is on
connected_ssid - Currently connected network
access_points - List of available networks
scanning - Whether a scan is in progress

Access Point Info

ssid - Network name
strength - Signal strength (0-100%)
connected - Currently associated
security - Encryption type
path - D-Bus object path

Enterprise WiFi

When connecting to an enterprise (802.1X) network, gartray displays an EAP authentication form. See the Enterprise WiFi section in the sidebar for details.

Backend

Network connections are managed via nmcli (NetworkManager command-line tool).

Configuration Options

[panel.network]
show_vpn = false       # Show VPN connections
show_ethernet = false  # Show ethernet interfaces

Enterprise WiFi (802.1X)

gartray supports enterprise WiFi networks that require 802.1X/EAP authentication. When an enterprise network is detected, an EAP form is displayed for credential entry.

Supported EAP Methods

Method	Description
PEAP	Protected EAP (most common for enterprise WiFi)
TTLS	Tunneled TLS

EAP Form Fields

Identity - Username or email for authentication
Password - Authentication password
Anonymous Identity - Outer identity (optional, for privacy)
CA Certificate Path - Path to certificate authority file (optional)
Phase 2 Method - Inner authentication: MSCHAPv2, MSCHAP, PAP, CHAP, or GTC

Connection via nmcli

Enterprise connections are established using nmcli rather than D-Bus EAP calls. This provides broader compatibility with NetworkManager configurations.

equivalent nmcli command

$ nmcli connection add type wifi con-name "Enterprise" \

$ wifi.ssid "CorpNet" wifi-sec.key-mgmt wpa-eap \

$ 802-1x.eap peap 802-1x.identity "user@corp.com" \

$ 802-1x.phase2-auth mschapv2

Bluetooth Control

Controls Bluetooth via BlueZ D-Bus interface (org.bluez).

State

powered - Whether Bluetooth is enabled
available - Whether adapter is present
devices - List of known devices
discovering - Whether scanning for devices

Device Info

name - Human-readable device name
address - MAC address
paired - Bonded with device
connected - Active connection
trusted - Auto-connect enabled
icon - Theme icon name

Configuration Options

[panel.bluetooth]
show_battery = false   # Show device battery percentage

Battery Status

Displays battery information via UPower D-Bus interface.

D-Bus Interface

Interface	org.freedesktop.UPower.Device
Path	/org/freedesktop/UPower/devices/DisplayDevice

Properties

Property	Description
Percentage	Battery level (0-100%)
State	Charging (1), Discharging (2), Charged (4)
TimeToEmpty	Seconds until empty
TimeToFull	Seconds until fully charged
IsPresent	Whether battery is installed

Power Actions

Provides power management actions via systemd-logind D-Bus interface.

D-Bus Interface

Interface	org.freedesktop.login1.Manager
Path	/org/freedesktop/login1

Available Actions

Action	D-Bus Method	Fallback
Shutdown	PowerOff()	systemctl poweroff
Reboot	Reboot()	systemctl reboot
Suspend	Suspend()	systemctl suspend
Hibernate	Hibernate()	Suspend (fallback)
Logout	TerminateSession()	pkill -TERM -x gar

Standalone Mode

In standalone mode, gartray runs its panel independently of garbar.

Starting the Daemon

terminal

$ gartray daemon # Start in foreground

$ gartray daemon & # Start in background

Autostart

Add gartray to your X11 startup script:

~/.xinitrc

# Start gartray before window manager
gartray daemon &

# Start window manager
exec gar

Systemd User Service

~/.config/systemd/user/gartray.service

[Unit]
Description=gartray quick settings
After=graphical-session.target

[Service]
ExecStart=%h/.local/bin/gartray daemon
Restart=on-failure

[Install]
WantedBy=graphical-session.target

Integration with garbar

garbar handles system tray icons (XEMBED/SNI) directly via its built-in tray module. gartray complements garbar by providing the quick settings panel.

Quick Settings Panel Trigger

garbar can trigger gartray's quick settings panel via IPC:

quick_settings module

# garbar sends to gartray via Unix socket:
# /run/user/1000/gartray.sock (or /tmp/gartray.sock)
# {"command":"toggle","x":100,"y":200}

Typical Setup

Start gartray daemon (handles quick settings panel)
Start garbar with tray module (handles tray icons)
Configure garbar quick_settings to trigger gartray panel on click

Rendering

gartray uses Cairo for 2D graphics rendering with ARGB32 transparency support.

Icon Sources

Icons are loaded in priority order:

Theme icons - Searched in icon theme directories
Pixmaps - ARGB32 data from SNI D-Bus properties
Placeholder - Fallback if no icon available

Icon Theme Search Paths

~/.local/share/icons
/usr/share/icons
/usr/share/pixmaps

Themes Searched

hicolor
Adwaita
breeze
Papirus

Color Format Conversion

SNI icons use network byte order (big-endian ARGB), while Cairo uses native byte order (BGRA on little-endian systems):

D-Bus ARGB (big-endian):  A R G B
Cairo BGRA (native):      B G R A

Common Workflows

Basic Usage

terminal

$ gartray daemon & # Start daemon in background

$ gartrayctl toggle # Show/hide quick settings

Position Panel at Cursor

Show the panel at a specific position (useful for keybinds):

terminal

$ gartrayctl show $(xdotool getmouselocation --shell | grep -E "^[XY]=" | cut -d= -f2 | tr "\n" " ") # Show at cursor position

Keybind in gar

Add a keybind in your gar config to toggle the panel:

~/.config/gar/init.lua

-- Toggle gartray quick settings panel
gar.bind("Super+Shift+s", function()
    os.execute("gartrayctl toggle")
end)

Volume Control Keybinds

Direct volume control without opening the panel:

terminal

$ wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%+ # Volume up

$ wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%- # Volume down

$ wpctl set-mute @DEFAULT_AUDIO_SINK@ toggle # Toggle mute

Brightness Control Keybinds

Direct brightness control:

terminal

$ brightnessctl set +5% # Brightness up

$ brightnessctl set 5%- # Brightness down

Reload Configuration

terminal

$ gartrayctl reload # Reload config without restart

$ pkill -HUP gartray # Alternative: send SIGHUP

IPC Protocol

gartray uses a Unix domain socket for IPC communication with gartrayctl.

Socket Location

The socket is created at $XDG_RUNTIME_DIR/gartray.sock or /tmp/gartray.sock.

Protocol Format

Messages are JSON objects, one per line (JSON Lines format).

Commands

Command	JSON	Description
show	{"command":"show","x":100,"y":200}	Show panel at position
hide	{"command":"hide"}	Hide panel
toggle	{"command":"toggle","x":100,"y":200}	Toggle panel visibility
reload	{"command":"reload"}	Reload configuration
status	{"command":"status"}	Get daemon status
quit	{"command":"quit"}	Stop daemon

Response Format

// Success
{"success": true, "message": null, "data": null}

// Success with visibility (toggle/show/hide)
{"success": true, "message": null, "data": null, "visible": true}

// Error
{"success": false, "message": "error description", "data": null}

gartrayctl Commands

terminal

$ gartrayctl show [x] [y] # Show panel at position

$ gartrayctl hide # Hide panel

$ gartrayctl toggle [x] [y] # Toggle panel

$ gartrayctl reload # Reload config

$ gartrayctl status # Get daemon status

$ gartrayctl quit # Stop daemon

Direct Socket Communication

You can communicate directly with the socket using standard tools:

terminal

$ echo '{"command":"toggle"}' | socat - UNIX-CONNECT:$XDG_RUNTIME_DIR/gartray.sock # Using socat

$ echo '{"command":"status"}' | nc -U $XDG_RUNTIME_DIR/gartray.sock # Using netcat

Troubleshooting

Panel not showing

Check if the gartray daemon is running:

terminal

$ gartrayctl status # Check daemon status

$ ls $XDG_RUNTIME_DIR/gartray.sock # Check IPC socket

For tray icon issues, see garbar's tray module documentation instead.

Volume control not working

Verify WirePlumber/PipeWire is running:

terminal

$ wpctl status # Check WirePlumber status

$ systemctl --user status pipewire wireplumber # Check services

Brightness control not working

Check backlight device and permissions:

terminal

$ ls /sys/class/backlight/ # List backlight devices

$ cat /sys/class/backlight/*/brightness # Check current brightness

You may need to add your user to the video group or create udev rules for write access.

Network/Bluetooth not showing

Verify D-Bus services are running:

terminal

$ systemctl status NetworkManager # Check NetworkManager

$ systemctl status bluetooth # Check BlueZ

Power actions require password

Ensure polkit is configured for passwordless power actions:

/etc/polkit-1/rules.d/85-power.rules

polkit.addRule(function(action, subject) {
    if ((action.id == "org.freedesktop.login1.power-off" ||
         action.id == "org.freedesktop.login1.reboot" ||
         action.id == "org.freedesktop.login1.suspend" ||
         action.id == "org.freedesktop.login1.hibernate") &&
        subject.isInGroup("wheel")) {
        return polkit.Result.YES;
    }
});

Daemon already running

Check for existing daemon and stop it:

terminal

$ cat $XDG_RUNTIME_DIR/gartray.pid # Check PID file

$ gartrayctl quit # Stop existing daemon

$ pkill gartray # Force stop if needed

Debug logging

Enable debug output to diagnose issues:

terminal

$ RUST_LOG=debug gartray daemon # Run with debug logging

$ RUST_LOG=gartray=trace gartray daemon # Trace-level logging

Back to home

gartray

Features

Quick Start Guide

1. Installation

2. System Dependencies

3. Running gartray

4. Configuration

5. Control with gartrayctl

Configuration Reference

Full Configuration Example

Available Panel Modules

Overview

Architecture

Key Components

Dependencies

Quick Settings Panel

Panel Features

Keyboard Shortcuts

Volume Control

State

Commands

Output Parsing

Configuration Options

Brightness Control

State

Sysfs Interface

Device Discovery

Network Control

State

Access Point Info

Enterprise WiFi

Backend

Configuration Options

Enterprise WiFi (802.1X)

Supported EAP Methods

EAP Form Fields

Connection via nmcli

Bluetooth Control

State

Device Info

Configuration Options

Battery Status

D-Bus Interface

Properties

Power Actions

D-Bus Interface

Available Actions

Do Not Disturb

State

Commands

Configuration

File Locations

Loading Behavior

Custom Config Path

Integration

Standalone Mode

Starting the Daemon

Autostart

Systemd User Service

Integration with garbar

Quick Settings Panel Trigger

Typical Setup

Rendering

Icon Sources

Icon Theme Search Paths

Themes Searched

Color Format Conversion

Common Workflows

Basic Usage

Position Panel at Cursor

Keybind in gar

Volume Control Keybinds

Brightness Control Keybinds

Reload Configuration

IPC Protocol

Socket Location

Protocol Format

Commands

Response Format

gartrayctl Commands