188 lines
6.0 KiB
Markdown
188 lines
6.0 KiB
Markdown
# 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.
|