openrazer-ha

Home Assistant integration for Razer keyboard lighting via MQTT Discovery.

This daemon exposes your Razer laptop keyboard as a light entity in Home Assistant, allowing you to control brightness, color, and effects from the HA interface or automations.

Features

• MQTT Discovery: Automatic device detection in Home Assistant
• Brightness control: 0-100% brightness adjustment
• RGB color picker: Full color control for static lighting
• Effects: Dynamic detection based on device capabilities - supports spectrum, wave, breath (single/dual/random), reactive, ripple (standard/random), starlight (single/dual/random), static, and more
• Bidirectional sync: Changes reflect in both HA and on the keyboard
• Availability tracking: HA shows device as unavailable when daemon stops
• Auto-reconnect: Automatically reconnects to MQTT broker if connection is lost

Supported Devices

This integration should work with any Razer keyboard supported by openrazer. The code uses capability detection, so effects that aren't available on your specific device are automatically skipped.

Tested

• Razer Blade 14 (2025)

Expected to work

• All Razer Blade laptops with RGB keyboards
• Razer BlackWidow series
• Razer Huntsman series
• Razer Ornata series
• Razer Cynosa series
• Any device listed on openrazer's supported devices page with type "keyboard"

If you've tested this with your device, please open an issue to let us know and we'll add it to the tested list!

Prerequisites

1. openrazer

openrazer is an open-source driver and daemon that provides userspace access to Razer device features on Linux.

Install openrazer for your distribution:

• Ubuntu/Debian: See PPA instructions
• Fedora: sudo dnf install openrazer-meta
• Arch Linux: sudo pacman -S openrazer-daemon python-openrazer
• openSUSE: See OBS instructions

After installation:

1. Add your user to the plugdev group (required for device access):

   sudo gpasswd -a $USER plugdev

2. Log out and back in for group membership to take effect

3. Start the openrazer daemon:

   systemctl --user enable --now openrazer-daemon.service

4. Verify your device is detected:

   razer-cli -l

   You should see your Razer device listed.

2. Home Assistant with MQTT

You need a working Home Assistant installation with an MQTT broker. If you haven't set this up yet:

1. Install an MQTT broker - The easiest option is the Mosquitto add-on if running Home Assistant OS/Supervised

2. Enable MQTT integration in Home Assistant:

   • Go to Settings → Devices & Services → Add Integration → MQTT
   • Configure it to connect to your broker

3. Note your MQTT broker details - You'll need:

   • Hostname/IP address of the broker
   • Port (usually 1883)
   • Username and password (if authentication is enabled)

3. Python 3.10+

Most modern Linux distributions include Python 3.10 or later. Verify with:

python3 --version

Installation

Quick install

1. Clone and install:

   git clone https://github.com/alitheg/openrazer-ha.git
   cd openrazer-ha
   sudo ./scripts/install.sh

2. Configure MQTT connection:

   sudo nano /opt/openrazer-ha/config.yaml

   Update the host, username, and password fields to match your MQTT broker.

3. Enable and start the service:

   systemctl --user enable --now openrazer-ha.service

4. Verify it's running:

   systemctl --user status openrazer-ha.service

Manual installation

If you prefer to install manually or to a different location:

1. Create a virtual environment (with access to system packages for openrazer):

   python3 -m venv venv --system-site-packages
   source venv/bin/activate
   pip install -r requirements.txt

2. Configure and run:

   cp config.yaml.example config.yaml
   # Edit config.yaml with your MQTT broker details
   ./venv/bin/python razer_ha_service.py

Usage

Check service status

systemctl --user status openrazer-ha.service

View logs

journalctl --user -u openrazer-ha.service -f

Restart service

systemctl --user restart openrazer-ha.service

Home Assistant

Once the daemon is running and connected to your MQTT broker, Home Assistant will automatically discover the device. You'll find it under:

Settings → Devices & Services → MQTT

The device appears as a light entity with:

• On/Off toggle
• Brightness slider
• Color picker
• Effect dropdown

Example automations

Red keyboard when microphone is active:

automation:
  - alias: "Red keyboard when recording"
    trigger:
      - platform: state
        entity_id: binary_sensor.microphone_active
        to: "on"
    action:
      - service: light.turn_on
        target:
          entity_id: light.razer_blade_14_2025_keyboard
        data:
          rgb_color: [255, 0, 0]
          brightness: 255

Dim keyboard at night:

automation:
  - alias: "Dim keyboard at night"
    trigger:
      - platform: time
        at: "22:00:00"
    action:
      - service: light.turn_on
        target:
          entity_id: light.razer_blade_14_2025_keyboard
        data:
          brightness: 50

Advanced: LED Matrix Control

If your device supports per-key RGB control (LED matrix), additional features are available.

For detailed documentation, examples, and automation recipes, see MATRIX.md

Predefined Matrix Patterns

These appear as effects in the Home Assistant UI:

• matrix_wasd - Highlight WASD gaming keys
• matrix_arrows - Highlight arrow keys
• matrix_gradient_horizontal - Horizontal color gradient
• matrix_gradient_vertical - Vertical color gradient
• matrix_border - Light up border keys
• matrix_corners - Light up corner keys

Note: The default key positions for matrix_wasd and matrix_arrows may not match your keyboard layout. Use the discovery tool to find correct positions:

./scripts/discover_matrix.py

Then configure them in your config.yaml. See MATRIX.md for details.

Custom Matrix Control via MQTT

For advanced users, you can control individual keys or create custom patterns by publishing to the matrix topic:

Topic: homeassistant/light/razer_blade_14_2025/matrix/set

Set individual keys:

{
  "keys": [
    {"row": 0, "col": 0, "r": 255, "g": 0, "b": 0},
    {"row": 0, "col": 1, "r": 0, "g": 255, "b": 0},
    {"row": 0, "col": 2, "r": 0, "g": 0, "b": 255}
  ]
}

Create gradient patterns:

{
  "pattern": "gradient_horizontal",
  "color1": [255, 0, 0],
  "color2": [0, 0, 255]
}

Available patterns: gradient_horizontal, gradient_vertical, checkerboard

Load an image:

{
  "image": "<base64_encoded_png_data>"
}

The image will be automatically resized to fit your keyboard's LED matrix.

Clear the matrix:

{
  "clear": true,
  "color": [0, 0, 0]
}

Example: Temperature Visualization

automation:
  - alias: "Keyboard shows CPU temperature"
    trigger:
      - platform: state
        entity_id: sensor.cpu_temperature
    action:
      - service: mqtt.publish
        data:
          topic: homeassistant/light/razer_blade_14_2025/matrix/set
          payload: >
            {
              "pattern": "gradient_horizontal",
              "color1": [0, 255, 0],
              "color2": [255, 0, 0]
            }

Configuration

/opt/openrazer-ha/config.yaml options:

mqtt:
  host: "homeassistant.local"  # MQTT broker hostname or IP
  port: 1883                    # MQTT broker port
  username: ""                  # MQTT username (leave empty if no auth)
  password: ""                  # MQTT password (leave empty if no auth)
  tls: false                    # Enable TLS (optional)
  ca_certs: "/path/to/ca.crt"   # CA certificate for TLS (optional)

homeassistant:
  discovery_prefix: "homeassistant"  # HA MQTT discovery prefix

logging:
  level: "INFO"  # DEBUG, INFO, WARNING, ERROR

Troubleshooting

"No Razer keyboard found"

1. Check openrazer daemon is running:

   systemctl --user status openrazer-daemon

2. Verify your device is detected:

   razer-cli -l

3. Ensure your user is in the plugdev group:

   groups

   If plugdev is not listed, add yourself and re-login:

   sudo gpasswd -a $USER plugdev

"Failed to connect to MQTT"

1. Verify MQTT broker is running and accessible:

   mosquitto_pub -h YOUR_HOST -t test -m "hello"

2. Check credentials in /opt/openrazer-ha/config.yaml

3. Ensure firewall allows connection to MQTT port (usually 1883)

4. If using Home Assistant's Mosquitto add-on, ensure you've created a user for MQTT

Device shows as unavailable in HA

1. Check the daemon is running:

   systemctl --user status openrazer-ha.service

2. Check logs for errors:

   journalctl --user -u openrazer-ha.service --no-pager -n 50

3. Verify MQTT connectivity by checking if messages are being published:

   mosquitto_sub -h YOUR_HOST -t "homeassistant/light/#" -v

Service won't start after reboot

User services require a login session. Enable lingering to start services at boot:

loginctl enable-linger $USER

Updating

To update an existing installation to the latest version:

cd openrazer-ha
git pull
sudo ./scripts/update.sh

The update script will:

• Stop the service (if running)
• Update all code and dependencies
• Preserve your config.yaml
• Update the systemd service file
• Restart the service automatically

Uninstallation

Run the uninstall script:

cd openrazer-ha
sudo ./scripts/uninstall.sh

Or manually:

systemctl --user disable --now openrazer-ha.service
rm ~/.config/systemd/user/openrazer-ha.service
sudo rm -rf /opt/openrazer-ha

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

Apache License 2.0 - see LICENSE for details.

Acknowledgments

• openrazer - The open-source driver that makes this possible
• paho-mqtt - Eclipse MQTT client library
• Home Assistant - Open-source home automation platform