Skip to main content

Module led_controller

aethermapd

Module led_controller 

Source
Expand description

LED Controller for Azeron Cyborg keypad

This module provides HID-based LED control for the Azeron Cyborg keypad. It manages the HID device connection, handles device enumeration with proper interface selection (filtering out keyboard interface), and provides async methods for LED zone control.

§Device Information (Discovered via USB enumeration)

  • Vendor ID: 0x16d0 (MCS / Azeron LTD)
  • Product ID: 0x12f7 (Azeron Cyborg 2 Keypad)
  • LED Control Interface: Interface 4, usage_page 0xff01 (vendor-specific)

§Protocol (DISCOVERED via Wireshark USB capture)

The Azeron Cyborg 2 uses a binary protocol (not the text protocol used by earlier Azeron models). The protocol was discovered via USB packet capture while operating the official Azeron software.

HARDWARE CAPABILITY: The official Azeron software only controls brightness for the side LED (blue). No RGB color control is exposed in the official software.

Protocol Status:

  • ✅ Device identification confirmed (vendor: 0x16d0, product: 0x12f7)
  • ✅ Interface 4 (usage_page 0xff01) confirmed as LED control
  • ✅ 64-byte packet format (data sent to HID OUT endpoint 6)
  • ✅ Brightness control protocol discovered
  • ✅ Keepalive protocol discovered
  • ❌ RGB control protocol unknown (not exposed in official software)

§Packet Format

All LED packets are 64 bytes:

Offset  Size    Description
------  ------  -----------
0       2 bytes Sequence/type (0x0001 for LED, 0x0000 for keepalive)
2       2 bytes Command counter (little-endian, increments)
4       1 byte  Always 0x01
5       1 byte  Always 0x01
6       2 bytes Brightness value (little-endian: 0x0100 = 256 min, 0x0196 = 406 max)
8       1 byte  Always 0x00
9       1 byte  Always 0x00
10-63   54 bytes Padding (0x00)

§Brightness Encoding

Brightness is encoded as a 16-bit little-endian value at offset 6:

  • Minimum (dim): 0x0100 = 256
  • Maximum (bright): 0x0196 = 406
  • Range: 150 steps (0-149 in byte 6, with byte 7 = 0x01)
  • Formula: brightness = 256 + byte6
  • Percentage: percent = (brightness - 256) * 100 / 150

§Keepalive Packets

The device expects regular keepalive packets to maintain the connection:

0000125901010000... (64 bytes)
  • Bytes 2-3 increment as a counter (0x1259, 0x125A, …)
  • If keepalive stops, the device may disconnect or become unresponsive

§Interface Selection

Azeron Cyborg 2 exposes 5 HID interfaces:

  • Interface 0: Vendor Specific (255/93/1) - Configuration
  • Interface 1: HID (3/0/0) - Keyboard input (via evdev)
  • Interface 2: HID Mouse (3/1/2) - Mouse emulation
  • Interface 3: HID (3/0/0) - Unknown
  • Interface 4: HID (3/0/0) with usage_page 0xff01 - LED control

We must open interface 4 (usage_page 0xff01), not the keyboard interfaces, or LED commands will fail silently.

§Privilege Timing

The HID device must be opened BEFORE privilege drop in main.rs, or access will be denied. This module provides find_led_interface() for use during privileged initialization.

Structs§

DeviceLedState
Per-device LED state (persists across hotplug)
LedController
LED controller for Azeron Cyborg keypad
LedState
LED state tracking for a device

Enums§

LedError
LED controller errors
LedPattern
LED pattern types for visual effects
LedZone
LED zones on the Azeron Cyborg keypad