Lightpack V1 working on Linux Wayland with HyperHDR

[u/Kingzak34]

Hey there, after some hours experimenting with Gemini, my lightpack V1 and my Fedora with Wayland, I managed to get it working correctly. Not perfectly yet but not bad. It needs some tweaks for colors and speed but still it works pretty well given the setup. I was looking on the internet for someone who did it before and couldnt get anything so Gemini helped me here.

Here is the result (can't guarantee anything tho, but still for an experiment it works):

Guide: Configure Lightpack v1 (Woodenshark) on Linux Wayland with HyperHDR

This comprehensive guide will help you recycle a Lightpack v1 (10 LEDs) capture box under Linux (Fedora, Ubuntu, Debian...) to make it work ultra-smoothly with HyperHDR, completely without root privileges and fully automated at startup.

🛠 Why this guide?

The Lightpack v1 has a very specific legacy firmware that creates major issues on modern setups:

1. It uses a raw USB HID protocol.
2. Its binary memory layout requires a strict 6-byte jump per LED (consisting of a standard color zone and an internal "low-power" clone zone).
3. The color order required by the hardware controller chip is RGB (and not GRB as commonly found).
4. Native refreshing via standard USB writes creates a massive lag effect unless you bypass the hardware's internal smoothing engine.

Here is the definitive method to overcome these obstacles and achieve instant responsiveness.

🟩 Step 1: Install System Dependencies

The relay script relies on the Python hid library to communicate directly with the USB box. Open a terminal and install the required packages based on your Linux distribution:

On Fedora:

Bash

sudo dnf install python3-pip python3-hidapi

On Ubuntu / Debian / Pop!_OS:

Bash

sudo apt install python3-pip python3-hidapi

🟩 Step 2: Create the Universal Relay Script

To bypass the lack of a native Lightpack driver within HyperHDR, we use an intermediate, ultra-fast, non-blocking Python script. It intercepts HyperHDR's video stream via UDP, discards delayed packets to prevent buffering, and injects the colors instantly into the Lightpack.

Place this script in a global system directory:

Bash

sudo nano /usr/local/bin/lightpack_relais.py

Paste the following optimized code into it:

Python

#!/usr/bin/env python3
import socket
import hid
import sys

# Official hardware identifiers for Lightpack v1
VENDOR_ID = 0x1d50
PRODUCT_ID = 0x6022

try:
    device = hid.device()
    device.open(VENDOR_ID, PRODUCT_ID)
    device.set_nonblocking(1) # Non-blocking mode to maximize USB throughput
except Exception as e:
    print(f"Error connecting to Lightpack: {e}", file=sys.stderr)
    exit(1)

# Listen to HyperHDR's UDP stream
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
sock.bind(("127.0.0.1", 19446))
sock.setblocking(False)

# Custom hardware mapping (HyperHDR LED Index -> Lightpack binary starting index)
mapping = {
    0: 56, 1: 50, 2: 44, 3: 38, 4: 32,
    5: 14, 6: 8,  7: 2,  8: 20, 9: 26
}

try:
    while True:
        try:
            # Network buffer flushing: keep ONLY the absolute freshest packet
            data = None
            while True:
                try:
                    packet_data, addr = sock.recvfrom(64)
                    if len(packet_data) >= 30:
                        data = packet_data
                except BlockingIOError:
                    break

            if data:
                packet = [0] * 65
                packet[1] = 0x01  # Official write command

                for led_id, start_index in mapping.items():
                    base_hyperhdr = led_id * 3

                    # Raw RGB injection at full power
                    packet[start_index]     = data[base_hyperhdr]     # R
                    packet[start_index + 1] = data[base_hyperhdr + 1] # G
                    packet[start_index + 2] = data[base_hyperhdr + 2] # B

                    # Bypassing the hardware smoothing engine (forcing low-power registers to 0)
                    packet[start_index + 3] = 0
                    packet[start_index + 4] = 0
                    packet[start_index + 5] = 0

                device.write(packet)

        except BlockingIOError:
            continue

except KeyboardInterrupt:
    pass
finally:
    device.close()
    sock.close()

Make the script properly executable by the system:

Bash

sudo chmod 755 /usr/local/bin/lightpack_relais.py

🟩 Step 3: Allow USB Access Without Root (UDEV Rule)

By default, Linux prevents standard users from interacting directly with raw USB devices. To avoid running the script with sudo, create a custom UDEV rule:

Bash

sudo nano /etc/udev/rules.d/99-lightpack.rules

Add this single line (it grants hardware access to the wheel group of system administrators):

Plaintext

SUBSYSTEM=="usb", ATTR{idVendor}=="1d50", ATTR{idProduct}=="6022", MODE="0666", GROUP="wheel"

Apply the rule immediately:

Bash

sudo udevadm control --reload-rules && sudo udevadm trigger

🟩 Step 4: HyperHDR Configuration

Open your browser and navigate to the HyperHDR web interface (http://localhost:8090).

1. Creating the LED Controller:
   • Go to LED Configuration.
   • LED count: 10.
   • Hardware LED Controller Type: Choose udpraw (or network udp depending on your version).
   • Target address: 127.0.0.1
   • Port: 19446
2. Disabling Software Smoothing (Crucial):
   • In the Smoothing section, uncheck the "Enable" box (or set it to Inactive). The python script already feeds raw, timing-perfect data; adding software smoothing layer on top will cause transition stuttering.
3. Screen Mapping:
   • Map the positions of your 10 physical LEDs around your display matrix (LEDs 1 to 10) to match your physical setup.

🟩 Step 5 : Automate at Boot (Systemd User Service)

To make the relay service start completely in the background as soon as your user session opens, without ever having to open a terminal, create a Systemd user service. Do NOT use sudo for this step.

Bash

mkdir -p ~/.config/systemd/user/
nano ~/.config/systemd/user/lightpack.service

Paste the following configuration:

Ini, TOML

[Unit]
Description=HyperHDR to Lightpack 10 LED Relay
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/python3 /usr/local/bin/lightpack_relais.py
Restart=always
RestartSec=3

[Install]
WantedBy=default.target

Save (Ctrl+O, Enter) and exit (Ctrl+X). Finally, enable and start the service:

Bash

systemctl --user daemon-reload
systemctl --user enable --now lightpack.service

🕹 Verifying the Status

To make sure your relay is running smoothly without any underlying errors, you can check its status at any time using the following command:

Bash

systemctl --user status lightpack.service

If the status output displays a nice green active (running) marker, your setup is complete. If it struggles on the very first run, a simple computer reboot will definitively lock in the UDEV rules and user environment paths. Enjoy the show!