Community-driven macOS utility for Razer peripherals
Battery monitoring, RGB control, and HID communication for 250+ devices
Your teacher explains every battery state, step by step.
Open Razer macOS gives you native macOS control over your Razer peripherals without Razer Synapse. The battery menu bar app lives in your menu bar and keeps you informed about your wireless mouse's charge level with color-coded icons and smart polling. The RGB control GUI lets you set lighting effects on mice and keyboards.
The star of the show. A lightweight rumps-based menu bar app that monitors your wireless Razer mouse battery.
- Download
Razer-Battery-v1.0.0-macOS.zipfrom Releases - Extract and drag Razer Battery.app to
/Applications - Right-click the app > Open (required first time for unsigned apps)
- Optional: Add to System Settings > General > Login Items for auto-start
The menu bar icon changes color and shape based on your battery level:
| State | Battery | Icon | Color | Description |
|---|---|---|---|---|
| Critical | 0 -- 10% | Single partial segment | Red | Time to charge immediately |
| Low | 11 -- 30% | One full segment | Orange | Charge soon |
| Medium | 31 -- 60% | Two segments | Orange + Yellow-Green | Comfortable range |
| Full | 61 -- 100% | Three segments | Green | Fully operational |
| Charging (low) | Any, charging <=30% | Lightning bolt | Orange bolt | Plugged in, still low |
| Charging (high) | Any, charging >30% | Lightning bolt | Green + White bolt | Plugged in, charging well |
| Disconnected | -- | Empty outline | Gray | Mouse not found |
- Normal: Checks battery every 5 minutes (configurable: 1, 5, 10, or 15 min)
- Disconnected: Switches to fast 30-second polling until your mouse reconnects
- Wake: Waits 2 seconds after sleep/wake for USB re-enumeration, then refreshes
- Staleness guard: Forces a re-scan if no successful read in 10+ minutes
Configurable from the menu bar dropdown. Settings persist to ~/.config/razer-battery/settings.json.
| Setting | Default | Options |
|---|---|---|
| Poll interval | 5 min | 1, 5, 10, 15 minutes |
| Low battery threshold | 20% | 10%, 15%, 20% |
| Low battery notification | On | On / Off |
| Display mode | Icon + % | Icon + %, % only, Icon only |
| Launch at login | Off | On / Off |
A PyQt5 interface for setting LED effects on Razer mice and keyboards.
python3 main.pySupported effects: Static color, Breathing, Wave, Reactive
Each effect has configurable parameters (color, speed, direction) through an intuitive tabbed interface.
Important: Razer's DriverKit extensions claim exclusive HID access. Uninstall them first:
sudo systemextensionsctl uninstall R2H967U7J8 com.razer.appengine.driver sudo systemextensionsctl uninstall R2H967U7J8 com.razer.appengine.virtual.driver
- macOS (tested on recent versions)
- Python 3.8+
- Homebrew
# Install system dependency
brew install hidapi
# Clone the repository
git clone https://github.com/ForestApps/OpenMacOSRazer.git
cd OpenMacOSRazer
# Create virtual environment
python3 -m venv venv
source venv/bin/activate
# Install Python dependencies
pip install -r requirements.txt# Battery menu bar app
python3 razer_battery_tray.py
# RGB control GUI
python3 main.pyNote: Grant Input Monitoring permission to your terminal in System Settings > Privacy & Security if you encounter HID access errors.
Over 250 Razer devices supported via OpenRazer hardware definitions:
| Category | Examples |
|---|---|
| Mice | DeathAdder (Chroma, Elite, V2-V4), Basilisk (V2, V3, Ultimate), Viper (Ultimate, Mini, 8K), Naga (Trinity, Pro, X), Mamba, Orochi |
| Keyboards | BlackWidow (Chroma, Elite, V3, V4), Huntsman (Elite, Mini, V2), Ornata, Cynosa, DeathStalker |
| Laptops | Blade Stealth, Blade 14/15/17 (various years) |
| Headsets | Kraken 7.1, Kraken Ultimate, Kraken Kitty |
| Accessories | Firefly, Goliathus, Mouse Bungees, Headset Stands, Charging Pads |
While definitions for all devices are included, specific feature support (e.g. unique matrix effects) may vary. Battery monitoring targets wireless mice.
+------------------+
| Menu Bar App |
| (rumps / PyQt5) |
+--------+---------+
|
+--------v---------+
| razer_common |
| Protocol Layer |
+--------+---------+
|
+--------v---------+
| hidapi |
| HID over USB |
+--------+---------+
|
+--------v---------+
| Razer Device |
| (VID: 0x1532) |
+------------------+
Protocol: 90-byte HID feature reports with CRC validation. Battery queries use command class 0x07 with per-device transaction IDs. Responses are validated, retried across interfaces on failure, and converted from raw 0-255 values to 0-100% percentages.
Error Recovery: Exponential backoff on repeated failures, per-interface retry logic, and interface preference tracking that remembers the last working interface.
Menu bar shows a warning icon instead of battery percentage?
- Remove Razer drivers -- they claim exclusive HID access:
sudo systemextensionsctl uninstall R2H967U7J8 com.razer.appengine.driver sudo systemextensionsctl uninstall R2H967U7J8 com.razer.appengine.virtual.driver
- Enable Input Monitoring: System Settings > Privacy & Security > Input Monitoring > enable Razer Battery
- Relaunch the app
- Check logs:
~/Library/Logs/razer-battery-tray.logforopen failedHID errors
- Fine-tune matrix effects for advanced keyboards
- Key remapping and macro support
- Auto-sync device definitions with upstream OpenRazer
Contributions welcome! Here's how you can help:
- Test: Report which devices work and which need tweaks
- Code: Submit PRs for new features or bug fixes
- Reverse engineer: Help decode protocols for unsupported features
# Run the test suite
python3 -m pytest tests/ -v- Fork the repository
- Create a feature branch
- Submit a Pull Request
Built on the shoulders of the OpenRazer project -- huge thanks for their extensive reverse engineering and hardware definitions that power device support in this application.
GNU General Public License v3.0
This project is not affiliated with Razer Inc.