Katseye Lightstick Controller

Control your KATSEYE official lightstick from your PC. Connects via Bluetooth and syncs the lightstick to any music playing on your computer for a home concert experience.

Features

• Connect to your lightstick via Bluetooth LE
• Test with an 8-color cycle to verify it works
• Concert Mode — lightstick reacts to music in real-time
  • Pulses with the bassline
  • Color cycles on every beat
  • Works with YouTube, Spotify, or any audio playing on your PC

Quick Start (Windows .exe)

1. Download Katseye Lightstick.exe from Releases
2. Turn on your lightstick and hold both buttons until it flashes blue
3. Open the app, click Connect
4. Play music and click Start Concert Mode

Running from Source

Requirements

• Windows 10/11
• Python 3.12+
• Bluetooth adapter (built-in works fine)
• KATSEYE official lightstick

Install

git clone https://github.com/ThatButters/Katseye-Lightstick.git
cd Katseye-Lightstick
pip install -r requirements.txt

Run the GUI

python app.py

Run concert mode from command line

python concert.py                    # auto-detect audio + lightstick
python concert.py --list-devices     # list audio outputs
python concert.py --device 38        # use a specific audio output
python concert.py --no-stick         # test audio visualization only

Use as a library

import asyncio
from katseye import KatseyeLightstick

async def main():
    stick = KatseyeLightstick()
    await stick.connect()

    await stick.set_color(255, 0, 0)      # red
    await stick.set_color_hex("#8000FF")   # purple
    await stick.off()                      # LEDs off

    battery = await stick.get_battery()    # battery percentage
    print(f"Battery: {battery}%")

    await stick.test_colors()              # cycle through 8 colors

    await stick.disconnect()

asyncio.run(main())

How It Works

The KATSEYE official lightstick uses Bluetooth Low Energy (BLE) with a custom GATT service by FANLIGHT Co. Color commands are sent as 9-byte packets:

[01] [FF] [00] [RR] [GG] [BB] [00] [00] [CHECKSUM]

• Bytes 0-2: Header (01 FF 00)
• Bytes 3-5: RGB color values (0-255)
• Bytes 6-7: Reserved (00 00)
• Byte 8: Checksum (sum of bytes 2-7, mod 256)

Written to characteristic 00010203-0405-0607-0809-0a0b0c0d2b19 on service 00010203-0405-0607-0809-0a0b0c0d1911.

Concert mode captures system audio via WASAPI loopback, runs FFT analysis, and maps bass energy to brightness/color cycling at ~12 updates per second.

Building the .exe

pip install pyinstaller
python -m PyInstaller --onefile --windowed --name "Katseye Lightstick" --add-data "katseye.py;." app.py

The exe will be in dist/.

Compatibility

This was reverse-engineered from the FANLIGHT BLE protocol and confirmed working with the KATSEYE official lightstick. Other FANLIGHT-manufactured lightsticks (IVE, BTS ver.4+, BIBI, P1Harmony, etc.) may use the same or similar protocol but have not been tested.

License

MIT