azeron-cyborg-linux/docs/protocol.md

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:

   # 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:

   # 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:

// 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:

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

// 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