# 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

- [x] Implement 64-byte HID report parser
- [x] Create command builder for 0x122a, 0x26FB, 0x26EC, 0x26ED
- [x] Parse button mapping data (30 buttons x 3 actions)
- [x] Parse joystick configuration (mode, angle, deadzone, etc)
- [x] Implement profile read/write/save operations
- [x] Add support for all key types (keyboard, mouse, gamepad)
- [ ] Handle modifier flags
- [x] Create profile management functions
- [x] 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.