aodhan/azeron-cyborg-linux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
91cdb36243f3e525a786b86b2ff12c925db2926a
azeron-cyborg-linux/docs/protocol.md

6.0 KiB
Raw Blame History

Azeron Configuration Protocol Documentation

Overview

This document describes the USB configuration protocol for the Azeron Cyborg keypad (USB ID: 16d0:113c). The protocol has been reverse-engineered through USB traffic analysis and is now implemented in libazeron.

Protocol Status: ✅ Fully Reverse-Engineered
Implementation Status: ✅ Implemented in libazeron

USB Device Analysis

Device Descriptor Summary

  • Vendor ID: 0x16d0 (MCS)
  • Product ID: 0x113c (Azeron Keypad)
  • Configuration: 1 configuration, 5 interfaces
  • Power: 500mA (bus-powered)

Interface Breakdown

  1. Interface 0: Vendor-specific (0xFF)

    • Endpoints: 0x81 (IN), 0x01 (OUT)
    • Purpose: Unused for configuration
    • Status: Not utilized by Azeron software

  2. Interface 1: HID

    • Endpoint: 0x82 (IN)
    • Purpose: Main button input (30 buttons)
    • Packet size: 16 bytes

  3. Interface 2: HID Boot Mouse

    • Endpoint: 0x83 (IN)
    • Purpose: Mouse emulation
    • Packet size: 7 bytes

  4. Interface 3: HID

    • Endpoint: 0x84 (IN)
    • Purpose: Analog stick input
    • Packet size: 16 bytes

  5. Interface 4: HID with IN/OUT

    • Endpoints: 0x85 (IN), 0x06 (OUT)
    • Purpose: Configuration interface
    • Packet size: 64 bytes
    • Protocol: Custom HID reports

Configuration Protocol

Protocol Characteristics

  • Interface Used: Interface 4 (endpoints 0x06 OUT, 0x85 IN)
  • Transfer Type: Interrupt transfers (0x01)
  • Packet Format: Fixed 64-byte HID reports
  • Command Structure: Request-response pattern
  • Endianness: Little-endian for offsets and delays, Big-endian for Command IDs.

Packet Format

All configuration packets follow this structure:

Byte 0:    Flags/Type (0x00=request, 0x01=response)
Byte 1:    Reserved/Length (0x3a for config writes)
Bytes 2-3: Command ID (big-endian)
Bytes 4-5: Operation type and parameters
Bytes 6-63: Data payload (varies by command)

Command Reference (Cyborg Model)

0x122a - Get Status (Heartbeat)

Purpose: Periodic device status check. Returns current profile configuration.

  • Payload Index 0: Status (0x01 = Success)
  • Payload Index 1: Active Profile ID (0, 1, 2)
  • Payload Index 3: Joystick Mode
  • Payload Index 8: Stick Angle
  • Payload Index 10: Deadzone
  • Payload Index 11: Response Curve
  • Payload Index 12: Sensitivity
  • Payload Index 13: Inversion flags (Bit 0: X, Bit 1: Y)

0x2000 - Set Global Settings

Purpose: Configure timing delays for actions.

  • Bytes 54-55 (Payload): Long Press Delay (ms, little-endian, e.g., f401 = 500ms)
  • Bytes 56-57 (Payload): Double Press Delay (ms, little-endian, e.g., c800 = 200ms)

0x20F6 - Set Single Press

0x20F8 - Set Long Press

0x204A - Set Double Press

Purpose: Surgical update for a specific button action.

  • Byte 10 (Payload): Button ID (0-based)
  • Byte 22 (Payload): Key Type (0xf0 = Keyboard)
  • Byte 23 (Payload): Key Code (HID)

0x204B - Commit Button Changes

Purpose: Makes surgical updates (0x20F6/F8/4A) active.

0x26EC - Bulk Write Profile

Purpose: Writes a complete profile block.

  • Byte 3 (Payload): Joystick Mode (0x00=Analog, 0x01=WASD4, 0x02=WASD8, 0x03=Mouse)
  • Byte 8 (Payload): Stick Angle (0-255)
  • Byte 10 (Payload): Deadzone (0-100)

0x26ED - Commit Bulk Write

Purpose: Persists bulk changes to EEPROM.

Command Reference (Classic Model)

Note: These commands are used by older Azeron versions and may differ from Cyborg.

0x12C8 - Read Configuration

Purpose: Read full device configuration.

0x26FB - Read Configuration (Cyborg)

Purpose: Read specific memory blocks.

Button Mapping Reference

The Azeron Cyborg has 30 configurable buttons plus 1 analog joystick.

Button Numbering

Buttons are numbered 1-30 in the configuration data. Each button has 3 actions (Single, Long, Double), each 4 bytes.

  • Profile Offset 8-11: Button 1 Single
  • Profile Offset 12-15: Button 1 Long
  • Profile Offset 16-19: Button 1 Double
  • ... (continues linearly)

Key Type Codes

Code Type Description
0xf0 Keyboard Standard keyboard key
0xf1 Mouse Mouse button/wheel
0xf2 Gamepad Gamepad button/axis
0xf3 Macro Macro sequence
0xf4 Media Media control key
0xf5 Layer Layer switch

Analog Joystick Configuration

The analog joystick is configured separately from the 30 buttons.

Joystick Profile Data (Indices relative to payload start):

Index 3:  Joystick Mode (0x00=Analog, 0x01=WASD4, 0x02=WASD8, 0x03=Mouse)
Index 8:  Stick Angle (0-255)
Index 10: Dead zone (0-100%)
Index 11: Sensitivity curve (0=linear, 1=exponential, etc.)
Index 12: Sensitivity (0-100)
Index 13: Inversion flags (Bit 0: X, Bit 1: Y)

Profile Management

The device supports 3 profiles (Profile 0, 1, 2).

Active Profile Indication

The currently active profile is indicated in status responses:

  • Byte 1 of payload: Active profile number
  • LED color changes to profile-specific color

Implementation Checklist

  • Implement 64-byte HID report parser
  • Create command builder for 0x122a, 0x26FB, 0x26EC, 0x26ED
  • Parse button mapping data (30 buttons x 3 actions)
  • Parse joystick configuration (mode, angle, deadzone, etc)
  • Implement profile read/write/save operations
  • Add support for all key types (keyboard, mouse, gamepad)
  • Handle modifier flags
  • Create profile management functions
  • Add analog stick mode switching
  • Implement LED color control

Safety Notes

  • Always test with backup configurations
  • Be prepared to reset device to factory defaults
  • Don't send malformed packets to device
  • Monitor device temperature during testing
  • Stop if device behaves unexpectedly
  • Keep original configuration files as backup

Acknowledgments

Special thanks to the Azeron community for providing captures and testing assistance during the reverse engineering process.