Razer Basilisk V3 X HyperSpeed Python Control for macOS

A Python-based solution to control the Razer Basilisk V3 X HyperSpeed mouse on macOS, using the USB protocol ported from the OpenRazer project.

Features

• DPI Control: Set custom DPI values (100-35,000) with quick presets
• Scroll Wheel LED: Control brightness and effects (Static, Spectrum, Wave, Breathing, Reactive)
• Battery Monitoring: Real-time battery level and charging status
• Device Information: Display firmware version and connection status
• Dark Theme UI: Razer-styled dark interface with green accents

Requirements

• macOS
• Python 3.6+
• Razer Basilisk V3 X HyperSpeed mouse connected via USB

Installation

1. Install dependencies:

pip install -r requirements.txt

2. You may need to install libusb on macOS:

brew install libusb

Usage

Option 1: Client-Daemon Architecture (Recommended for pyenv users)

This approach runs a privileged daemon for USB access while your GUI runs with your normal Python environment:

1. Run the GUI client (it will prompt for sudo to start the daemon):

python3 razer_gui_client.py

The GUI will automatically start the daemon with sudo when needed.

Option 2: Direct USB Access

Run the GUI directly with sudo:

sudo python3 razer_gui.py

Option 3: Preserve pyenv with sudo

Use the provided script to maintain your pyenv environment:

./run_with_pyenv.sh

Or use the control module directly:

from razer_control import RazerBasiliskControl, LEDEffect

# Connect to device
device = RazerBasiliskControl()

# Get battery level
battery = device.get_battery_level()
print(f"Battery: {battery}%")

# Set DPI
device.set_dpi(1600)

# Set LED effect
device.set_scroll_effect(LEDEffect.SPECTRUM)

# Close connection
device.close()

USB Protocol Details

The implementation uses the Razer USB HID protocol:

• Vendor ID: 0x1532 (Razer)
• Product ID: 0x00B9 (Basilisk V3 X HyperSpeed)
• Report Size: 90 bytes
• Command structure includes class, ID, and arguments with XOR checksum

Troubleshooting

1. Permission Denied: Run with sudo for USB access
2. Device Not Found: Ensure the mouse is connected via USB (not Bluetooth)
3. USB Errors: Try unplugging and reconnecting the device

Credits

USB protocol implementation based on the OpenRazer project.