Initial commit
This commit is contained in:
Aodhan Collins
333
docs/protocol.md
Normal file
333
docs/protocol.md
Normal file
@@ -0,0 +1,333 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user