razerbat

A system tray battery indicator for Razer peripherals on Linux, powered by OpenRazer.

razerbat

Discharging	Discharging	Discharging	Charging

What is this?

Razer does not officially support Linux. The community project OpenRazer fills that gap by providing a daemon that exposes Razer device data (including battery level and charging state) over D-Bus.

This project reads that data and displays it as a system tray icon that updates in real time — so you always know how much battery your Razer mouse, keyboard, or headset has left without opening any app.

Why Rust?

This project is a rewrite of the original RazerBatteryTray by HoroTW, which was written in Python. The Python version works well but is painful to install: it requires a working Python environment, pip, and several packages (openrazer, pystray, pillow) that are not always easy to get right — especially on distributions like NixOS.

The Rust rewrite ships as a single compiled binary with no Python runtime, no pip, and no virtual environments. Rust was chosen because:

Zero runtime dependencies beyond system libraries that are already present on any Linux desktop (libdbus-1).
Single binary install — just copy the executable and run it.
Low resource usage — the binary sits in the background polling at 5 Hz and uses negligible CPU and memory.
Memory safety — Rust's ownership model eliminates a whole class of bugs at compile time.
Modern Linux tooling — zbus (pure-Rust D-Bus) and ksni (KStatusNotifierItem) are excellent, well-maintained crates that map directly to the Linux desktop protocols used by every major desktop environment.

Pre-requisites

1. OpenRazer daemon

The daemon must be installed and running on your system. It is the only non-trivial dependency and provides all the device data.

⚠️ Device support depends on OpenRazer, not on this app.
If your device is physically connected but not shown by --list, it means your installed version of OpenRazer does not yet have a kernel driver for it.
Check the OpenRazer supported devices list and consider updating OpenRazer to the latest version.

Follow the official installation guide for your distribution: 👉 https://openrazer.github.io/

Quick links:

After installation, make sure the daemon is running:

systemctl --user status openrazer-daemon
# or start it:
systemctl --user start openrazer-daemon

2. System library: `libdbus-1`

Almost certainly already installed on your system. If not:

# Ubuntu / Debian
sudo apt install libdbus-1-3

# Fedora
sudo dnf install dbus-libs

# Arch
sudo pacman -S dbus

3. System tray support

The app uses the KStatusNotifierItem / AppIndicator protocol supported by:

KDE Plasma — works out of the box.
GNOME on Wayland — requires the AppIndicator and KStatusNotifierItem Support GNOME Shell extension. Enable it in the Extensions app.
Most other desktop environments — should work natively (XFCE, Cinnamon, MATE, etc.).

Installation

Option A — Download binary (recommended)

Go to the Releases page and download the latest razerbat-*-linux-x86_64.tar.gz.
Extract and run the built-in installer:

tar -xzf razerbat-*-linux-x86_64.tar.gz
cd razerbat
./razerbat install

This single command will:

Copy the binary to ~/.local/bin/razerbat
Copy icons to ~/.local/share/razerbat/icons/
Auto-detect your device and configure autostart at login

To specify a device manually:

./razerbat install --device "Cobra Pro"

Make sure ~/.local/bin is in your $PATH, then run:

razerbat --list

Icons path: The binary looks for an icons/ directory next to itself. The installer places icons at ~/.local/share/razerbat/icons/ and the binary at ~/.local/bin/razerbat — run the installer from the extracted folder so both paths are correctly resolved.

Uninstall

To remove razerbat and all its files:

razerbat uninstall

This removes:

~/.local/bin/razerbat
~/.local/share/razerbat/ (icons)
~/.config/autostart/razerbat.desktop

Option B — Build from source

1. Install Rust (if you don't have it):

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

2. Install system dependency:

sudo apt install libdbus-1-dev pkg-config   # Debian / Ubuntu
sudo pacman -S dbus pkgconf                  # Arch
sudo dnf install dbus-devel pkgconf          # Fedora

3. Clone, build and install:

git clone https://github.com/zenardi/razerbat.git
cd razerbat
cargo build --release
./target/release/razerbat install

Usage

List detected Razer devices (to find your device name):

razerbat --list

Example output:

Listing Available Devices:
Razer Cobra Pro (Wireless)
    Has Battery: true

Start the tray icon by passing part of the device name:

razerbat "Cobra"
# or a more specific match:
razerbat "Cobra Pro"

The icon will animate from 100 % down to 0 % and back up to the current battery level on startup, then update every 0.2 seconds.

Configuration Options

All options are passed as command-line flags:

Flag	Short	Description
`--list`	`-l`	List all devices that have a battery and exit
`--list-all`	`-a`	List all devices, including those without a battery
`--parsable`	`-p`	Reduce output verbosity (one device name per line, no labels) — useful for scripting
`--quit-on-disconnect`	`-q`	Exit when the device disconnects instead of waiting for reconnect
`--help`	`-h`	Show help message
`--version`	`-V`	Print version

Examples

# Simple tray icon
razerbat "Viper Ultimate"

# Quit instead of hiding the icon when the mouse is turned off
razerbat --quit-on-disconnect "Viper"

# Scripting: get the first battery device name cleanly
DEVICE=$(razerbat --list --parsable | head -1)
razerbat "$DEVICE"

Logging

Set the LOG_LEVEL environment variable to control verbosity:

LOG_LEVEL=DEBUG razerbat "Cobra"

Available levels: ERROR, WARN (default), INFO, DEBUG.

Autostart

To launch the tray icon automatically at login, add it to your desktop environment's autostart.

Generic (XDG autostart)

mkdir -p ~/.config/autostart
cat > ~/.config/autostart/razerbat.desktop << 'EOF'
[Desktop Entry]
Type=Application
Name=Razer Battery Tray
Exec=razerbat "Cobra Pro"
Icon=battery
Comment=System tray battery indicator for Razer peripherals
X-GNOME-Autostart-enabled=true
EOF

Replace "Cobra Pro" with the part of your device name from --list.

KDE Plasma

Add the same .desktop file to ~/.config/autostart/, or use System Settings → Autostart.

systemd user service

mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/razerbat.service << 'EOF'
[Unit]
Description=Razer Battery Tray
After=graphical-session.target

[Service]
ExecStart=%h/.local/bin/razerbat "Cobra Pro"
Restart=on-failure
RestartSec=5

[Install]
WantedBy=graphical-session.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now razerbat

Behaviour Details

Device reconnect

By default, if the device disconnects (turned off, goes to sleep, USB unplugged), the icon hides into the overflow tray. When the device reconnects, the icon reappears automatically. Use --quit-on-disconnect if you prefer the app to exit instead (e.g. to restart via a udev rule).

Sleep detection

Some Razer devices report 0 % battery when they enter sleep mode. The app detects this: if the battery level drops suddenly from ≥ 5 % to 0 % while not charging, it assumes the device is sleeping and continues displaying the last known battery level.

Icon set

The icons/ directory contains 202 PNG files:

bat_0.png … bat_100.png — discharging states
bat_0_c.png … bat_100_c.png — charging states

Icons are loaded lazily and cached in memory after first use.

Troubleshooting

My device is connected but not listed by `--list`

Run lsusb | grep -i razer and note the product ID (the 4-digit hex number after 1532:).
Then check if it appears in the OpenRazer supported devices list: 👉 https://openrazer.github.io/#devices

If your product ID is missing, your device is not yet supported by OpenRazer. The app has no way to communicate with it regardless — this tool relies entirely on the OpenRazer kernel driver and daemon. Options:

Update OpenRazer to the latest version — newer devices are added regularly.
Request support by opening an issue on the OpenRazer GitHub.

Device is listed but the tray icon doesn't appear

On GNOME/Wayland, make sure the AppIndicator and KStatusNotifierItem Support extension is installed and enabled.
Try restarting your desktop session.

OpenRazer daemon is not running

systemctl --user start openrazer-daemon
# Check status:
systemctl --user status openrazer-daemon
# Enable on login:
systemctl --user enable openrazer-daemon

Credits

Original Python implementation by HoroTW
Battery icons by HoroTW
Device data provided by the OpenRazer project and its contributors

Development

Prerequisites

# Rust toolchain (via rustup — recommended)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

# System library required by the tray (libdbus-1-dev)
sudo apt install libdbus-1-dev pkg-config   # Debian / Ubuntu
sudo pacman -S dbus pkgconf                  # Arch
sudo dnf install dbus-devel pkgconf          # Fedora

Build

# Debug build (faster compile, includes debug symbols)
cargo build

# Release build (optimised, stripped — use this for distribution)
cargo build --release
strip target/release/razerbat

The compiled binary is placed at:

target/debug/razerbat (debug)
target/release/razerbat (release)

Run locally

# List detected devices
cargo run -- --list

# Start tray for a specific device
cargo run -- "Cobra"

# With debug logging
LOG_LEVEL=DEBUG cargo run -- "Cobra"

Note: cargo run resolves icons/ automatically by searching two levels up from the binary, so it works from the project root without any extra setup.

Test

# Run all unit tests
cargo test

# Run tests with output visible
cargo test -- --nocapture

Lint & format

# Check formatting (same check run in CI)
cargo fmt --check

# Apply formatting
cargo fmt

# Run linter (warnings are errors in CI)
cargo clippy -- -D warnings

Run all CI checks locally

cargo fmt --check && cargo clippy -- -D warnings && cargo test && cargo build --release

Contributing

Pull requests are welcome. For major changes, please open an issue first.

Name		Name	Last commit message	Last commit date
.github		.github
icons		icons
imgs		imgs
src		src
.gitignore		.gitignore
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation