# 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