334 lines
9.0 KiB
Markdown
334 lines
9.0 KiB
Markdown
# Azeron Configuration Protocol Documentation
|
|
|
|
## Overview
|
|
|
|
This document describes the approach to reverse engineering the USB configuration protocol for the Azeron Cyborg keypad (USB ID: 16d0:113c). The device uses a vendor-specific USB interface for configuration, which needs to be understood to implement full configuration support.
|
|
|
|
## 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**: Likely main configuration interface
|
|
- **Packet size**: 32 bytes
|
|
|
|
2. **Interface 1**: HID
|
|
- Endpoint: 0x82 (IN)
|
|
- **Purpose**: Main button input
|
|
- **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**: LED/control interface
|
|
- **Packet size**: 64 bytes
|
|
|
|
## Protocol Reverse Engineering Approach
|
|
|
|
### Phase 1: USB Traffic Capture
|
|
|
|
#### Option A: Windows Software Capture (Recommended)
|
|
|
|
If you have access to Windows and the Azeron configuration software:
|
|
|
|
1. **Setup**:
|
|
```bash
|
|
# Install USBPcap on Windows
|
|
# Install Wireshark
|
|
```
|
|
|
|
2. **Capture Process**:
|
|
- Start USBPcap capture on the Azeron device
|
|
- Open Azeron Windows software
|
|
- Perform configuration changes:
|
|
- Map a button to different key
|
|
- Change analog stick settings
|
|
- Switch profiles
|
|
- Save configuration
|
|
- Stop capture and save the data
|
|
|
|
3. **Analysis**:
|
|
- Look for control transfers to Interface 0
|
|
- Identify command patterns
|
|
- Map request types and data formats
|
|
|
|
#### Option B: Linux Exploration
|
|
|
|
Without Windows software, we can try to discover the protocol:
|
|
|
|
1. **Basic Communication Test**:
|
|
```bash
|
|
# Use the azeron-cli tool to attempt communication
|
|
./build/azeron-cli list
|
|
|
|
# Try to read from configuration endpoint
|
|
# (This will require implementing test functions)
|
|
```
|
|
|
|
2. **USB Control Transfer Testing**:
|
|
- Test standard USB requests
|
|
- Try vendor-specific requests
|
|
- Monitor device responses
|
|
|
|
### Phase 2: Protocol Discovery
|
|
|
|
#### Common USB Configuration Patterns
|
|
|
|
Most gaming devices use similar patterns:
|
|
|
|
1. **Configuration Read**:
|
|
```
|
|
Request Type: 0xC0 (Vendor IN)
|
|
Request: 0x01-0xFF (varies by device)
|
|
Value: 0x0000
|
|
Index: Interface number (0)
|
|
Data: Response buffer
|
|
```
|
|
|
|
2. **Configuration Write**:
|
|
```
|
|
Request Type: 0x40 (Vendor OUT)
|
|
Request: 0x01-0xFF (varies by device)
|
|
Value: 0x0000
|
|
Index: Interface number (0)
|
|
Data: Command/data buffer
|
|
```
|
|
|
|
#### Expected Command Structure
|
|
|
|
Based on similar devices, the protocol likely includes:
|
|
|
|
1. **Read Current Configuration**:
|
|
- Command to read all button mappings
|
|
- Command to read analog stick settings
|
|
- Command to read profile information
|
|
|
|
2. **Write Configuration**:
|
|
- Command to set button mapping
|
|
- Command to set analog stick parameters
|
|
- Command to save configuration to device
|
|
|
|
3. **Profile Management**:
|
|
- Command to switch active profile
|
|
- Command to read/write profile data
|
|
|
|
### Phase 3: Implementation Strategy
|
|
|
|
#### Step 1: Basic Communication
|
|
|
|
Add test functions to the library:
|
|
|
|
```c
|
|
// In libazeron/protocol.c
|
|
int azeron_protocol_test_read(struct azeron_device *device)
|
|
{
|
|
uint8_t buffer[64];
|
|
int ret;
|
|
|
|
// Try various vendor requests
|
|
for (int req = 0x01; req <= 0xFF; req++) {
|
|
ret = azeron_device_control_transfer(device,
|
|
0xC0, // Vendor IN
|
|
req, // Request
|
|
0x0000, // Value
|
|
0x0000, // Index (Interface 0)
|
|
buffer, sizeof(buffer),
|
|
1000);
|
|
if (ret > 0) {
|
|
printf("Request 0x%02x: %d bytes\n", req, ret);
|
|
// Print buffer contents
|
|
}
|
|
}
|
|
|
|
return AZERON_SUCCESS;
|
|
}
|
|
```
|
|
|
|
#### Step 2: Button Mapping Discovery
|
|
|
|
The button mapping likely uses:
|
|
- Button ID (1-32)
|
|
- Key type (keyboard, mouse, gamepad, macro)
|
|
- Key code or action
|
|
- Modifiers (shift, ctrl, alt)
|
|
|
|
Expected data structure:
|
|
```c
|
|
struct button_mapping {
|
|
uint8_t button_id;
|
|
uint8_t key_type;
|
|
uint16_t key_code;
|
|
uint8_t modifiers;
|
|
};
|
|
```
|
|
|
|
#### Step 3: Analog Stick Configuration
|
|
|
|
Analog stick settings likely include:
|
|
- Dead zone (0-100%)
|
|
- Sensitivity curve (linear, exponential)
|
|
- X/Y inversion flags
|
|
- Mode (analog, 4-way digital, 8-way digital, mouse)
|
|
|
|
#### Step 4: Profile Management
|
|
|
|
Profile commands likely:
|
|
- Read profile (0-2)
|
|
- Write profile
|
|
- Set active profile
|
|
- Save to device EEPROM
|
|
|
|
### Phase 4: Testing and Validation
|
|
|
|
#### Test Plan
|
|
|
|
1. **Basic Detection**:
|
|
- Verify device is detected
|
|
- Check all interfaces are accessible
|
|
|
|
2. **Configuration Read**:
|
|
- Read current button mappings
|
|
- Verify against known configuration
|
|
|
|
3. **Configuration Write**:
|
|
- Change single button mapping
|
|
- Verify change persists
|
|
- Test in-game/application
|
|
|
|
4. **Profile Management**:
|
|
- Create multiple profiles
|
|
- Switch between profiles
|
|
- Verify profile persistence
|
|
|
|
### Development Notes
|
|
|
|
#### USB Control Transfer Format
|
|
|
|
```c
|
|
// Vendor request to interface 0
|
|
int azeron_protocol_send_command(struct azeron_device *device,
|
|
uint8_t request,
|
|
uint16_t value,
|
|
uint16_t index,
|
|
uint8_t *data,
|
|
size_t size,
|
|
int timeout)
|
|
{
|
|
return libusb_control_transfer(device->handle,
|
|
0x40, // Vendor OUT
|
|
request,
|
|
value,
|
|
index,
|
|
data,
|
|
size,
|
|
timeout);
|
|
}
|
|
|
|
int azeron_protocol_receive_response(struct azeron_device *device,
|
|
uint8_t request,
|
|
uint16_t value,
|
|
uint16_t index,
|
|
uint8_t *data,
|
|
size_t size,
|
|
int timeout)
|
|
{
|
|
return libusb_control_transfer(device->handle,
|
|
0xC0, // Vendor IN
|
|
request,
|
|
value,
|
|
index,
|
|
data,
|
|
size,
|
|
timeout);
|
|
}
|
|
```
|
|
|
|
#### Common Gaming Device Protocol Patterns
|
|
|
|
1. **Init/Handshake**:
|
|
- Send init command
|
|
- Receive device info/acknowledgment
|
|
|
|
2. **Read Configuration**:
|
|
- Send read command with offset/address
|
|
- Receive configuration data
|
|
- May require multiple transfers for full config
|
|
|
|
3. **Write Configuration**:
|
|
- Send write command with data
|
|
- Receive acknowledgment
|
|
- Send save command to persist
|
|
|
|
4. **Profile Operations**:
|
|
- Select profile (0-2)
|
|
- Read/write profile data
|
|
- Set as active profile
|
|
|
|
### Tools for Reverse Engineering
|
|
|
|
#### USB Capture Tools
|
|
- **USBPcap**: Windows USB capture
|
|
- **Wireshark**: Protocol analysis
|
|
- **usbmon**: Linux kernel USB monitoring
|
|
- **libusb debug**: Enable debug output
|
|
|
|
#### Analysis Tools
|
|
- **Protocol analyzers**: Wireshark with USB dissectors
|
|
- **Hex editors**: For examining binary data
|
|
- **Custom scripts**: Python with pyusb for testing
|
|
|
|
### Expected Challenges
|
|
|
|
1. **Encryption/Obfuscation**: Configuration may be encrypted
|
|
2. **Checksums**: Data may include CRC/checksums
|
|
3. **Command Sequences**: May require specific command sequences
|
|
4. **Timing Requirements**: Some devices have strict timing
|
|
5. **Device Protection**: May have write protection mechanisms
|
|
|
|
### Next Steps
|
|
|
|
1. **Capture USB Traffic**: Get Windows software captures
|
|
2. **Analyze Patterns**: Identify command structure
|
|
3. **Implement Protocol**: Add functions to libazeron
|
|
4. **Test Incrementally**: Start with simple commands
|
|
5. **Document Findings**: Update this document with actual protocol
|
|
|
|
### Contributing
|
|
|
|
If you discover protocol details:
|
|
|
|
1. Document the command format
|
|
2. Provide example USB captures
|
|
3. Include test code if available
|
|
4. Update this documentation
|
|
|
|
### Safety Notes
|
|
|
|
- Always test with backup configurations
|
|
- Be prepared to reset device to factory defaults
|
|
- Don't write untested commands to device
|
|
- Monitor device temperature during testing
|
|
- Stop if device behaves unexpectedly
|
|
|
|
## Current Status
|
|
|
|
**Protocol Status**: Not yet reverse engineered
|
|
**Implementation Status**: Placeholder functions only
|
|
**Next Step**: USB traffic capture and analysis
|