Skip to content

MATRIX.md

Latest commit

 

History

History
362 lines (281 loc) · 9.14 KB

MATRIX.md

File metadata and controls

362 lines (281 loc) · 9.14 KB
Raw

LED Matrix Control Guide

This guide explains how to use advanced LED matrix features for per-key RGB control on supported Razer keyboards.

Prerequisites

  • A Razer keyboard with LED matrix support (most Razer Blade laptops and high-end keyboards)
  • The integration installed and running
  • (Optional) Pillow library for image support: pip install Pillow

Matrix Capabilities

When your keyboard supports LED matrix, you can:

  • Control individual key colors
  • Create custom patterns and gradients
  • Display images on your keyboard
  • Create animations by sending rapid updates

Quick Start

Using Predefined Patterns

The easiest way is to use the built-in patterns that appear as effects in Home Assistant:

  1. Open Home Assistant
  2. Find your keyboard light entity
  3. Select one of the matrix patterns from the effects dropdown:
    • matrix_wasd - Gaming keys highlight
    • matrix_arrows - Arrow keys highlight
    • matrix_gradient_horizontal - Left-to-right gradient
    • matrix_gradient_vertical - Top-to-bottom gradient
    • matrix_border - Outer edge glow
    • matrix_corners - Corner highlights

Custom Control via MQTT

For more control, publish JSON messages to the matrix topic.

Find your matrix topic:

homeassistant/light/<device_id>/matrix/set

Replace <device_id> with your device identifier (e.g., razer_blade_14_2025).

Examples

1. Highlight Specific Keys

Light up the Escape, F1, and Enter keys in red:

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

2. Create a Gradient

Rainbow gradient from left to right:

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

3. Checkerboard Pattern

Alternating red and blue:

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

4. Display an Image

First, convert your image to base64:

base64 -w 0 your_image.png > image_base64.txt

Then send it:

{
  "image": "<paste_base64_data_here>"
}

5. Clear/Reset

Turn all keys off (black):

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

Or set all to one color:

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

Home Assistant Automations

Notification Indicator

Flash specific keys when doorbell rings:

automation:
  - alias: "Doorbell flash keyboard"
    trigger:
      - platform: state
        entity_id: binary_sensor.doorbell
        to: "on"
    action:
      - repeat:
          count: 3
          sequence:
            - service: mqtt.publish
              data:
                topic: homeassistant/light/razer_blade_14_2025/matrix/set
                payload: '{"clear": true, "color": [255, 0, 0]}'
            - delay: "00:00:00.5"
            - service: mqtt.publish
              data:
                topic: homeassistant/light/razer_blade_14_2025/matrix/set
                payload: '{"clear": true, "color": [0, 0, 0]}'
            - delay: "00:00:00.5"

Temperature Heatmap

Show CPU temperature as a gradient:

automation:
  - alias: "CPU temp on keyboard"
    trigger:
      - platform: state
        entity_id: sensor.cpu_temperature
    action:
      - service: mqtt.publish
        data:
          topic: homeassistant/light/razer_blade_14_2025/matrix/set
          payload: >
            {% set temp = states('sensor.cpu_temperature') | float %}
            {% if temp < 50 %}
              {"pattern": "gradient_horizontal", "color1": [0, 255, 0], "color2": [255, 255, 0]}
            {% elif temp < 70 %}
              {"pattern": "gradient_horizontal", "color1": [255, 255, 0], "color2": [255, 128, 0]}
            {% else %}
              {"pattern": "gradient_horizontal", "color1": [255, 128, 0], "color2": [255, 0, 0]}
            {% endif %}

Meeting Indicator

Show red when in a meeting:

automation:
  - alias: "Meeting mode keyboard"
    trigger:
      - platform: state
        entity_id: calendar.work_calendar
    action:
      - choose:
          - conditions:
              - condition: state
                entity_id: calendar.work_calendar
                state: "on"
            sequence:
              - service: mqtt.publish
                data:
                  topic: homeassistant/light/razer_blade_14_2025/matrix/set
                  payload: '{"clear": true, "color": [255, 0, 0]}'
        default:
          - service: light.turn_on
            target:
              entity_id: light.razer_blade_14_2025_keyboard
            data:
              effect: spectrum

Python Script Example

For more complex patterns, you can create Python scripts:

#!/usr/bin/env python3
import paho.mqtt.publish as publish
import json
import time

MQTT_HOST = "homeassistant.local"
TOPIC = "homeassistant/light/razer_blade_14_2025/matrix/set"

# Create a wave animation
for offset in range(22):  # Assuming ~22 columns
    keys = []
    for col in range(22):
        # Calculate wave position
        brightness = int(128 + 127 * ((col + offset) % 10) / 10)
        keys.append({
            "row": 2,  # Middle row
            "col": col,
            "r": brightness,
            "g": 0,
            "b": 255 - brightness
        })

    payload = json.dumps({"keys": keys})
    publish.single(TOPIC, payload, hostname=MQTT_HOST)
    time.sleep(0.1)

Finding Key Positions

The predefined patterns (like matrix_wasd) may not work correctly on your keyboard because matrix layouts vary between models. Use the discovery tool to find the correct positions:

cd openrazer-ha
./scripts/discover_matrix.py

Discovery modes:

  1. Sequential scan - Lights each position one at a time. Watch your keyboard and note which physical key lights up for each (row, col) position.

  2. Grid pattern - Shows a checkerboard (red/blue) to visualize the layout.

  3. Interactive test - Manually test specific positions:

    Positions (row,col): 2,1 3,1 3,2 3,3

Configuring Custom Patterns

Once you've found the correct positions, edit your config.yaml. You can use two formats:

Traditional Format

List each coordinate individually:

matrix_patterns:
  wasd:
    - [2, 10]  # W (your actual position)
    - [3, 9]   # A
    - [3, 10]  # S
    - [3, 11]  # D
  arrows:
    - [4, 18]  # Up
    - [5, 17]  # Left
    - [5, 18]  # Down
    - [5, 19]  # Right

Range Notation Format

For complex patterns, use range notation to avoid listing every coordinate:

Range notation supports:

  • Single values: "0" → [0]
  • Comma-separated: "0,5,10" → [0, 5, 10]
  • Ranges: "1-5" → [1, 2, 3, 4, 5]
  • Mixed: "0,2-5,10" → [0, 2, 3, 4, 5, 10]

Examples:

matrix_patterns:
  # Border pattern - light up all edge keys
  border:
    - {row: 0, cols: "0-21"}      # Top edge: all columns in row 0
    - {row: 5, cols: "0-21"}      # Bottom edge: all columns in row 5
    - {rows: "1-4", col: 0}       # Left edge: rows 1-4 in column 0
    - {rows: "1-4", col: 21}      # Right edge: rows 1-4 in column 21

  # Function keys (F1-F12)
  function_keys:
    - {row: 0, cols: "2-13"}      # F1 through F12

  # Number row
  number_row:
    - {row: 1, cols: "1-11"}      # 1 through 0

  # Gaming cluster (WASD + QE + Shift)
  gaming_cluster:
    - {row: 2, cols: "1,10"}      # Q and E
    - {row: 2, col: 10}           # W
    - {rows: "3", cols: "9-11"}   # A, S, D
    - {row: 4, col: 1}            # Shift

  # Numpad area (if your keyboard has one)
  numpad:
    - {rows: "2-4", cols: "18-20"}  # 3x3 grid

You can also mix both formats:

matrix_patterns:
  custom_pattern:
    - [0, 0]                      # Traditional: single key
    - {row: 0, cols: "5-10"}      # Range: multiple keys
    - [2, 15]                     # Traditional: another single key

After editing config.yaml, restart the service:

systemctl --user restart openrazer-ha.service

Your custom patterns will appear as effects in Home Assistant (e.g., matrix_custom_pattern).

Tips

  1. Finding Key Positions: Row and column numbers start at 0. Use the discovery tool above to map your keyboard.
  2. Performance: Sending many updates rapidly may cause lag. Limit to ~10-20 updates per second.
  3. Brightness: The per-key colors combine with the global brightness setting.
  4. Image Size: Images are automatically resized. Small images will be scaled up, which may look pixelated.
  5. Patterns vs Keys: When you set individual keys, all other keys turn off unless you specify them too.

Troubleshooting

Matrix effects don't appear in HA:

  • Check that your device supports lighting_led_matrix capability
  • Look for "LED matrix detected" in the logs: journalctl --user -u openrazer-ha.service

Keys don't light up:

  • Verify row/col are within bounds (check matrix dimensions in logs)
  • Ensure the device is on and brightness > 0

Image doesn't display:

  • Install Pillow: pip install Pillow
  • Check the image is valid PNG/JPEG and base64 encoded properly

Custom patterns don't work:

  • Verify JSON syntax is correct
  • Check MQTT broker is receiving messages
  • Review logs for error messages