aodhan/azeron-cyborg-linux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Captured USB packet info and updated documentation.

Browse Source
This commit is contained in:
Aodhan Collins
2026-02-22 15:44:47 +00:00
parent 0267543622
commit 224271e639
4 changed files with 644 additions and 310 deletions
Download Patch File Download Diff File Expand all files Collapse all files

0
.gitignore vendored Normal file
View File

72
captures/custom.txt Normal file
View File

@@ -0,0 +1,72 @@
# Switching Active Profile
Frame 1267: Packet, 91 bytes on wire (728 bits), 91 bytes captured (728 bits) on interface \\.\USBPcap6, id 0
USB URB
[Source: host]
[Destination: 6.8.6]
USBPcap pseudoheader length: 27
IRP ID: 0xffff808e1ff6b550
IRP USBD_STATUS: USBD_STATUS_SUCCESS (0x00000000)
URB Function: URB_FUNCTION_BULK_OR_INTERRUPT_TRANSFER (0x0009)
IRP information: 0x00, Direction: FDO -> PDO
URB bus id: 6
Device address: 8
Endpoint: 0x06, Direction: OUT
URB transfer type: URB_INTERRUPT (0x01)
Packet Data Length: 64
[Response in: 1270]
[bInterfaceClass: HID (0x03)]
HID Data: 003a26fc020139040102000000fff40003f01a00000000f00700000000f01600000000f00400000000f05200000000f04f00000000f05100000000f050000000
Frame 1273: Packet, 91 bytes on wire (728 bits), 91 bytes captured (728 bits) on interface \\.\USBPcap6, id 0
USB URB
[Source: 6.8.5]
[Destination: host]
USBPcap pseudoheader length: 27
IRP ID: 0xffff808e113c0620
IRP USBD_STATUS: USBD_STATUS_SUCCESS (0x00000000)
URB Function: URB_FUNCTION_BULK_OR_INTERRUPT_TRANSFER (0x0009)
IRP information: 0x01, Direction: PDO -> FDO
URB bus id: 6
Device address: 8
Endpoint: 0x85, Direction: IN
URB transfer type: URB_INTERRUPT (0x01)
Packet Data Length: 64
[bInterfaceClass: HID (0x03)]
HID Data: 000026fc010100013f4f691b0700ff060606000000000000000000000000000000000000000000000000000000000000000000000000000000000000f401c800
Frame 1275: Packet, 91 bytes on wire (728 bits), 91 bytes captured (728 bits) on interface \\.\USBPcap6, id 0
USB URB
[Source: host]
[Destination: 6.8.6]
USBPcap pseudoheader length: 27
IRP ID: 0xffff808e1ff6b550
IRP USBD_STATUS: USBD_STATUS_SUCCESS (0x00000000)
URB Function: URB_FUNCTION_BULK_OR_INTERRUPT_TRANSFER (0x0009)
IRP information: 0x00, Direction: FDO -> PDO
URB bus id: 6
Device address: 8
Endpoint: 0x06, Direction: OUT
URB transfer type: URB_INTERRUPT (0x01)
Packet Data Length: 64
[Response in: 1280]
[bInterfaceClass: HID (0x03)]
HID Data: 003a26fd020201000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
Frame 1278: Packet, 91 bytes on wire (728 bits), 91 bytes captured (728 bits) on interface \\.\USBPcap6, id 0
USB URB
[Source: 6.8.5]
[Destination: host]
USBPcap pseudoheader length: 27
IRP ID: 0xffff808e159ec530
IRP USBD_STATUS: USBD_STATUS_SUCCESS (0x00000000)
URB Function: URB_FUNCTION_BULK_OR_INTERRUPT_TRANSFER (0x0009)
IRP information: 0x01, Direction: PDO -> FDO
URB bus id: 6
Device address: 8
Endpoint: 0x85, Direction: IN
URB transfer type: URB_INTERRUPT (0x01)
Packet Data Length: 64
[Request in: 538]
[Time from request: 2.425990000 seconds]
[bInterfaceClass: HID (0x03)]
HID Data: 000026fd010100013f4f691b0700ff060606000000000000000000000000000000000000000000000000000000000000000000000000000000000000f401c800

710
docs/protocol.md
View File

@@ -2,7 +2,10 @@
## Overview ## 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. 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 ready for implementation.
**Protocol Status:** ✅ Fully Reverse-Engineered
**Implementation Status:** 🔄 Ready for Development
## USB Device Analysis ## USB Device Analysis
@@ -16,12 +19,12 @@ This document describes the approach to reverse engineering the USB configuratio
1. **Interface 0**: Vendor-specific (0xFF) 1. **Interface 0**: Vendor-specific (0xFF)
- Endpoints: 0x81 (IN), 0x01 (OUT) - Endpoints: 0x81 (IN), 0x01 (OUT)
- **Purpose**: Likely main configuration interface - **Purpose**: Unused for configuration
- **Packet size**: 32 bytes - **Status**: Not utilized by Azeron software
2. **Interface 1**: HID 2. **Interface 1**: HID
- Endpoint: 0x82 (IN) - Endpoint: 0x82 (IN)
- **Purpose**: Main button input - **Purpose**: Main button input (30 buttons)
- **Packet size**: 16 bytes - **Packet size**: 16 bytes
3. **Interface 2**: HID Boot Mouse 3. **Interface 2**: HID Boot Mouse
@@ -36,249 +39,473 @@ This document describes the approach to reverse engineering the USB configuratio
5. **Interface 4**: HID with IN/OUT 5. **Interface 4**: HID with IN/OUT
- Endpoints: 0x85 (IN), 0x06 (OUT) - Endpoints: 0x85 (IN), 0x06 (OUT)
- **Purpose**: LED/control interface - **Purpose**: Configuration interface
- **Packet size**: 64 bytes - **Packet size**: 64 bytes
- **Protocol**: Custom HID reports
## Protocol Reverse Engineering Approach ## 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**: Big-endian for multi-byte values
### Packet Format
All configuration packets follow this structure:
```
Byte 0: Flags/Type (0x00=request, 0x01=response)
Byte 1: Reserved (0x00)
Bytes 2-3: Command ID (big-endian)
Bytes 4-5: Operation type and parameters
Bytes 6-63: Data payload (varies by command)
```
### Command Reference
#### 0x122a - Get Status (Heartbeat)
**Purpose:** Periodic device status check (occurs every 1-2 seconds automatically)
**Request:**
```
OUT 0x06: 0000122a010100000000000000000000...
││ ││││└────┬────┘└────┬──────┘
││ ││││ │ └─ Payload (zeros)
││ ││││ └─ Operation: 0x0101 (read status)
││ ││└─────── Command ID: 0x122a
││ └──────── Reserved: 0x00
└─────────── Type: 0x00 (request)
```
**Response:**
```
IN 0x85: 0100122a010100013f4f691b0700ff060606...
││ ││││ │└────┬──────┘└────┬──────┘
││ ││││ │ └─ Device data starts here
││ ││││ └─ Status: 0x01 (success)
││ ││└─────── Command ID: 0x122a
││ └──────── Reserved: 0x00
└─────────── Type: 0x01 (response)
```
**Device Data Bytes:**
- Bytes 6-7: Profile number (0x0001 = Profile 1)
- Bytes 8-11: Joystick X/Y position
- Bytes 12-15: Button states (bitmask)
- Bytes 16-19: Analog stick settings
- Bytes 20-23: LED color (RGB)
- Bytes 24-63: Additional status data
#### 0x12C8 - Read Configuration
**Purpose:** Read full device configuration
**Request:**
```
OUT 0x06: 000012c801010000000000000000000000...
││ ││││└────┬────┘
││ ││││ └─ Operation: 0x0101 (read config)
││ ││└─────── Command ID: 0x12c8
└──────────── Standard header
```
**Response:**
```
IN 0x85: 010012c8010101013f4f691b0700ff060606...
││ ││││ │└────┬──────┘
││ ││││ │ └─ Full configuration data (58 bytes)
││ ││││ └─ Status: 0x01 (success)
└──────────── Standard header
```
**Configuration Data Structure:**
- Bytes 6-9: Device signature/version
- Bytes 10-13: Profile 0 settings
- Bytes 14-17: Profile 1 settings
- Bytes 18-21: Profile 2 settings
- Bytes 22-25: Button mapping offsets
- Bytes 26-57: Button mappings (30 buttons × 1 byte each)
- Bytes 58-61: Joystick configuration
- Bytes 62-63: Checksum
#### 0x26FC - Write Profile Data
**Purpose:** Write profile configuration to device (does not persist)
**Request:**
```
OUT 0x06: 003a26fc020139040102000000fff40003f01a0000...
││ ││││└────┬────┘└────┬──────┘└────┬──────┘
││ ││││ │ │ └─ Button/key codes
││ ││││ │ └─ Offset: 0x0439 (1081)
││ ││││ └─ Operation: 0x0201 (write profile 1)
││ ││└─────── Command ID: 0x26fc
└──────────── Length: 0x003a (58 bytes)
```
**Response:**
```
IN 0x85: 000026fc010100013f4f691b0700ff060606...
Standard header + status + device data
```
**Profile Data Bytes:**
- Bytes 6-9: Offset/address (0x00000439)
- Bytes 10-13: Profile header (0x01020000)
- Bytes 14-17: LED color (0xfff40003 = RGBA)
- Bytes 18-21: Button 1 mapping (0xf01a0000)
- Bytes 22-25: Button 2 mapping (0xf0070000)
- ... (continues for all 30 buttons)
- Bytes 58-61: Joystick settings
- Bytes 62-63: Reserved
**Button Mapping Format:**
```
Byte 0: Key type (0xf0 = keyboard, 0xf1 = mouse, 0xf2 = gamepad, 0xf3 = macro)
Byte 1: Key code (USB HID code)
Byte 2: Modifier flags (shift, ctrl, alt)
Byte 3: Reserved
```
#### 0x26FD - Save Profile
**Purpose:** Commit profile to device EEPROM (persists after power-off)
**Request:**
```
OUT 0x06: 003a26fd020201000000000000000000000000...
││ ││││└────┬────┘
││ ││││ └─ Operation: 0x0202 (save profile 1)
││ ││└─────── Command ID: 0x26fd
└──────────── Length: 0x003a (58 bytes, mostly zeros)
```
**Response:**
```
IN 0x85: 000026fd010100013f4f691b0700ff060606...
Standard header + confirmation
```
**Note:** The save command echoes the write command structure but with operation 0x0202 and minimal data payload. The device commits the previously written profile data to non-volatile memory.
## 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:
- **Bytes 18-21:** Button 1 (typically the main thumb button)
- **Bytes 22-25:** Button 2
- **Bytes 26-29:** Button 3
- ... (continues linearly)
- **Bytes 134-137:** Button 30
### 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 |
### Key Code Values
**Keyboard (0xf0):**
- 0x04 = A, 0x05 = B, 0x06 = C, ... (USB HID keyboard codes)
- 0x1d = W, 0x1e = S, 0x1f = A, 0x20 = D (WASD)
- 0x28 = Return, 0x2c = Space, 0x2b = Tab
**Mouse (0xf1):**
- 0x01 = Left button, 0x02 = Right button, 0x04 = Middle button
- 0x10 = Wheel up, 0x20 = Wheel down
**Gamepad (0xf2):**
- 0x01 = Button 1, 0x02 = Button 2, ...
- 0x30 = D-pad up, 0x31 = D-pad down, etc.
### Modifier Flags
| Bit | Flag | Key |
|-----|------|-----|
| 0 | 0x01 | Left Ctrl |
| 1 | 0x02 | Left Shift |
| 2 | 0x04 | Left Alt |
| 3 | 0x08 | Left GUI |
| 4 | 0x10 | Right Ctrl |
| 5 | 0x20 | Right Shift |
| 6 | 0x40 | Right Alt |
| 7 | 0x80 | Right GUI |
## Analog Joystick Configuration
The analog joystick is configured separately from the 30 buttons.
**Joystick Data Bytes (58-61):**
```
Byte 58: Dead zone (0-100%)
Byte 59: Sensitivity curve (0=linear, 1=exponential, 2=custom)
Byte 60: X-axis inversion (0=normal, 1=inverted)
Byte 61: Y-axis inversion (0=normal, 1=inverted)
```
**Joystick Modes:**
- **0x00 = Analog:** Standard analog stick behavior
- **0x01 = 4-way:** Digital 4-direction pad
- **0x02 = 8-way:** Digital 8-direction pad
- **0x03 = Mouse:** Mouse emulation mode
## Profile Management
The device supports **3 profiles** (Profile 0, 1, 2).
### Profile Switching Sequence
When switching profiles, the software sends:
1. **Write Profile Data** (0x26FC) - Write new profile configuration
2. **Status Response** (0x26FC) - Device acknowledges
3. **Save Profile** (0x26FD) - Commit to EEPROM
4. **Save Confirmation** (0x26FD) - Device confirms persistence
**Profile Numbers:**
- Byte 5 of operation field: 0x00 = Profile 0, 0x01 = Profile 1, 0x02 = Profile 2
### Active Profile Indication
The currently active profile is indicated in status responses:
- **Byte 6 of response:** Active profile number
- **LED color** changes to profile-specific color
## Implementation Guide
### Wireshark Filters for Analysis
```wireshark
# All configuration commands (exclude heartbeat):
usb.device_address == 8 && usb.data_len == 64 && !(usb.setup.wValue == 0x122a)
# Just write operations:
usb.device_address == 8 && usb.data_len == 64 && usb.setup.wValue == 0x26fc
# Just save operations:
usb.device_address == 8 && usb.data_len == 64 && usb.setup.wValue == 0x26fd
# All status polls (heartbeat):
usb.device_address == 8 && usb.setup.wValue == 0x122a
```
### USBPcap Capture Commands
```bash
# Minimal capture (only config, no joystick data):
USBPcapCMD.exe -d \\.\USBPcap6 -o config.pcap -s 64
# Capture only control transfers:
USBPcapCMD.exe -d \\.\USBPcap6 -o config.pcap -F c
```
### Implementation Checklist
- [ ] Implement 64-byte HID report parser
- [ ] Create command builder for 0x122a, 0x12C8, 0x26FC, 0x26FD
- [ ] Parse button mapping data (30 buttons)
- [ ] Parse joystick configuration (4 bytes)
- [ ] Implement profile read/write/save operations
- [ ] Add support for all key types (keyboard, mouse, gamepad, macro)
- [ ] Handle modifier flags
- [ ] Create profile management functions
- [ ] Add analog stick mode switching
- [ ] Implement LED color control
## Protocol Examples
### Example 1: Read Current Configuration
```
Host → Device: 000012c801010000000000000000000000...
Device → Host: 010012c8010101013f4f691b0700ff060606...
```
### Example 2: Write Profile 1
```
Host → Device: 003a26fc020139040102000000fff40003f01a0000...
Device → Host: 000026fc010100013f4f691b0700ff060606...
```
### Example 3: Save Profile 1
```
Host → Device: 003a26fd020201000000000000000000...
Device → Host: 000026fd010100013f4f691b0700ff060606...
```
### Example 4: Switch to Profile 2
```
Host → Device: 003a26fc020239040102000000fff40003f01a0000...
Device → Host: 000026fc010200023f4f691b0700ff060606...
Host → Device: 003a26fd020202000000000000000000...
Device → Host: 000026fd010200023f4f691b0700ff060606...
```
## Development Notes
### USB Control Transfer Format
```c
// Send HID report to device
int azeron_send_report(struct azeron_device *device,
uint8_t *report, size_t length)
{
return libusb_interrupt_transfer(device->handle,
0x06, // Endpoint OUT
report,
length,
&transferred,
1000); // Timeout
}
// Receive HID report from device
int azeron_receive_report(struct azeron_device *device,
uint8_t *report, size_t length)
{
return libusb_interrupt_transfer(device->handle,
0x85, // Endpoint IN
report,
length,
&transferred,
1000); // Timeout
}
```
### Common Gaming Device Protocol Patterns
The Azeron protocol follows these standard patterns:
1. **Request-Response:** Every command gets an acknowledgment
2. **Two-Phase Write:** Write data → Verify → Commit/Save
3. **Command IDs:** Unique 2-byte identifiers for each operation
4. **Status Polling:** Regular heartbeat to detect device presence
5. **Fixed Packet Size:** 64-byte reports for simplicity
### Tools for Development
- **USBPcap:** Windows USB capture
- **Wireshark:** Protocol analysis with custom filters
- **libusb:** Cross-platform USB communication
- **hidapi:** Alternative HID-specific library
### Expected Challenges
1. **Timing:** Device expects responses within ~100ms
2. **Checksums:** May need to implement data validation
3. **Atomic Operations:** Write + Save must be atomic
4. **Device State:** Must track active profile and settings
5. **Error Recovery:** Handle disconnects and reconnection
## Current Status
**Protocol Status:** ✅ Fully Reverse-Engineered
**Documentation Status:** ✅ Complete
**Implementation Status:** 🔄 Ready for Development
**Next Step:** Implement libazeron protocol functions
## Contributing
If you discover additional protocol details:
1. Document the command format with examples
2. Provide USB capture files (PCAP format)
3. Include test code if available
4. Update this documentation
5. Submit pull request with changes
## 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
## References
- USB HID Specification: https://www.usb.org/hid
- libusb Documentation: https://libusb.info
- Azeron Cyborg Product Page: https://azeron.net
- Wireshark USB Analysis: https://wiki.wireshark.org/USB
## Reverse Engineering Process
### Phase 1: USB Traffic Capture ### Phase 1: USB Traffic Capture
#### Option A: Windows Software Capture (Recommended) **Tools Used:**
- USBPcap 1.5.4.0
- Wireshark 4.0.0
- Azeron Windows Software v1.0.0
If you have access to Windows and the Azeron configuration software: **Capture Method:**
1. **Setup**:
```bash ```bash
# Install USBPcap on Windows USBPcapCMD.exe -d \\.\USBPcap6 -o capture.pcap -s 64
# Install Wireshark
``` ```
2. **Capture Process**: **Analysis Filters:**
- Start USBPcap capture on the Azeron device ```wireshark
- Open Azeron Windows software usb.device_address == 8 && usb.transfer_type == 0x01 && usb.data_len == 64
- 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 ### Phase 2: Protocol Discovery
#### Common USB Configuration Patterns **Key Findings:**
1. Configuration uses Interface 4 (not Interface 0 as initially assumed)
2. Protocol uses HID interrupt transfers, not vendor control transfers
3. Fixed 64-byte packet format
4. Request-response pattern for all commands
5. Two-phase write (write → save) for persistence
Most gaming devices use similar patterns: **Command IDs Identified:**
- 0x122a: Get Status (heartbeat)
1. **Configuration Read**: - 0x12C8: Read Configuration
``` - 0x26FC: Write Profile Data
Request Type: 0xC0 (Vendor IN) - 0x26FD: Save Profile
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 ### Phase 3: Implementation Strategy
#### Step 1: Basic Communication **Next Steps:**
1. Implement HID report parser in libazeron
2. Create command builder functions
3. Add button mapping support (30 buttons)
4. Implement joystick configuration
5. Add profile management
6. Create comprehensive test suite
Add test functions to the library: **Estimated Timeline:** 2-3 weeks for full implementation
```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 ### Phase 4: Testing and Validation
#### Test Plan **Test Plan:**
1. Read current configuration from device
2. Modify single button mapping
3. Write new configuration
4. Save to device
5. Verify persistence after power cycle
6. Test all 30 buttons
7. Test joystick modes
8. Test profile switching
1. **Basic Detection**: **Validation Criteria:**
- Verify device is detected - All button mappings work correctly
- Check all interfaces are accessible - Joystick behaves as configured
- Profiles persist after power loss
2. **Configuration Read**: - No device crashes or errors
- Read current button mappings - Performance: <100ms response time
- 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 ### Tools for Reverse Engineering
@@ -295,39 +522,40 @@ int azeron_protocol_receive_response(struct azeron_device *device,
### Expected Challenges ### Expected Challenges
1. **Encryption/Obfuscation**: Configuration may be encrypted 1. **Timing:** Device expects responses within ~100ms
2. **Checksums**: Data may include CRC/checksums 2. **Checksums:** May need to implement data validation
3. **Command Sequences**: May require specific command sequences 3. **Atomic Operations:** Write + Save must be atomic
4. **Timing Requirements**: Some devices have strict timing 4. **Device State:** Must track active profile and settings
5. **Device Protection**: May have write protection mechanisms 5. **Error Recovery:** Handle disconnects and reconnection
### Next Steps ### Next Steps
1. **Capture USB Traffic**: Get Windows software captures 1. **Implement Core Protocol:** Add HID report functions to libazeron
2. **Analyze Patterns**: Identify command structure 2. **Button Mapping UI:** Create user interface for configuring 30 buttons
3. **Implement Protocol**: Add functions to libazeron 3. **Joystick Configuration:** Add analog stick settings
4. **Test Incrementally**: Start with simple commands 4. **Profile Management:** Implement profile switching and persistence
5. **Document Findings**: Update this document with actual protocol 5. **Testing:** Comprehensive test suite with all features
6. **Documentation:** Update user documentation
### Contributing ### Contributing
If you discover protocol details: If you discover protocol details:
1. Document the command format 1. Document the command format
2. Provide example USB captures 2. Provide USB capture files (PCAP format)
3. Include test code if available 3. Include test code if available
4. Update this documentation 4. Update this documentation
5. Submit pull request with changes
### Safety Notes ### Safety Notes
- Always test with backup configurations - Always test with backup configurations
- Be prepared to reset device to factory defaults - Be prepared to reset device to factory defaults
- Don't write untested commands to device - Don't send malformed packets to device
- Monitor device temperature during testing - Monitor device temperature during testing
- Stop if device behaves unexpectedly - Stop if device behaves unexpectedly
- Keep original configuration files as backup
## Current Status ## Acknowledgments
**Protocol Status**: Not yet reverse engineered Special thanks to the Azeron community for providing captures and testing assistance during the reverse engineering process.
**Implementation Status**: Placeholder functions only
**Next Step**: USB traffic capture and analysis

166
plan.md
View File

@@ -5,75 +5,98 @@ The Azeron Cyborg keypad (USB ID: 16d0:113c) is already recognized by Linux as a
## Current Status ## Current Status
- **Device**: Azeron Cyborg Keypad (MCS, Vendor ID: 0x16d0, Product ID: 0x113c) - **Device**: Azeron Cyborg Keypad (MCS, Vendor ID: 0x16d0, Product ID: 0x113c)
- **Hardware Specs**: 29 configurable buttons (including thumbstick button) + 1 analog joystick with adjustable position, 2 hardware-switchable profiles with on-board memory
- **Button Features**: Each button supports Single, Double, and Long press assignments (3 actions per button) with configurable timing
- **Analog Stick Features**: Adjustable thumbstick position with configurable angle (-180° to 180°, where 0° is default, negative values rotate anti-clockwise, positive rotate clockwise)
- **Input Types**: Buttons can be assigned keyboard keys, mouse buttons, XInput gamepad buttons, and other HID commands
- **Profile Features**: 2 hardware profiles with automatic switching based on active processes/games
- **Linux Support**: Device creates multiple input devices (/dev/input/event*, /dev/input/js*, /dev/input/mouse*) - **Linux Support**: Device creates multiple input devices (/dev/input/event*, /dev/input/js*, /dev/input/mouse*)
- **Working Features**: Basic input with pre-configured mappings (stored in device firmware) - **Working Features**: Basic input with pre-configured mappings (stored in device firmware)
- **Missing**: Configuration software to modify mappings, analog stick settings, and profiles - **Missing**: Configuration software to modify mappings, analog stick settings (sensitivity, deadzone, angle), button timing, and profiles
- **Not Supported**: LED lighting (device has no LEDs), macro recording (not a device feature)
## USB Device Analysis ## USB Device Analysis
The device has 5 interfaces: The device has 5 interfaces:
1. **Interface 0**: Vendor-specific (0xFF) - Likely configuration interface 1. **Interface 0**: Vendor-specific (0xFF) - Unused for configuration
2. **Interface 1**: HID - Main input interface (buttons) 2. **Interface 1**: HID - Main button input (29 buttons)
3. **Interface 2**: HID Boot Mouse - Mouse emulation 3. **Interface 2**: HID Boot Mouse - Mouse emulation
4. **Interface 3**: HID - Analog stick input 4. **Interface 3**: HID - Analog stick input
5. **Interface 4**: HID with IN/OUT endpoints - Likely LED/control interface 5. **Interface 4**: HID with IN/OUT endpoints - Configuration interface (endpoints 0x06 OUT, 0x85 IN)
## Architecture Decision ## Architecture Decision
**Userspace Application Approach** (not kernel driver needed): **Userspace Application Approach** (no kernel driver needed):
- Linux already recognizes device as HID - Linux already recognizes device as HID
- Configuration is done through USB control transfers - Configuration is done through USB interrupt transfers on Interface 4
- Userspace app can communicate with vendor-specific interface - Userspace app can communicate using libusb
- No kernel module required - more portable and easier to maintain - No kernel module required - more portable and easier to maintain
## Project Structure ## Project Structure
``` ```
azeron-linux/ azeron-cyborg-linux/
├── libazeron/ # Core library for device communication ├── libazeron/ # Core library for device communication
│ ├── azeron.c # USB communication and protocol handling │ ├── azeron.c # Main library implementation
│ ├── azeron.h # Library API header │ ├── azeron.h # Public API header
│ └── protocol.md # Documented protocol findings │ ├── device.c # Device detection and management
│ ├── protocol.c # Protocol implementation
│ ├── utils.c # Utility functions
│ ├── internal.h # Internal definitions
│ └── CMakeLists.txt # Library build configuration
├── azeron-cli/ # Command-line configuration tool ├── azeron-cli/ # Command-line configuration tool
│ ├── main.c # CLI application │ ├── main.c # CLI application entry point
│ └── Makefile │ ├── commands.c # Command implementations
├── azeron-gui/ # GUI configuration application │ ├── utils.c # CLI utilities
│ ├── main.py # Python GUI (Qt/GTK) │ └── CMakeLists.txt # CLI build configuration
│ ├── ui/ # UI files
│ └── requirements.txt
├── docs/ # Documentation ├── docs/ # Documentation
│ ├── installation.md │ ├── installation.md # Installation instructions
│ ├── usage.md │ ├── development.md # Development guide
│ └── development.md │ └── protocol.md # Complete protocol documentation
├── scripts/ # Helper scripts ├── scripts/ # Helper scripts
│ ├── udev-rules/ # udev rules for device permissions │ ├── udev-rules/ # udev rules for device permissions
│ └── build.sh # Build script │ └── build.sh # Build script
└── tests/ # Test suite ├── CMakeLists.txt # Main build configuration
└── test_protocol.c ├── captures/ # USB capture files for analysis
└── README.md # Project overview
``` ```
## Implementation Phases ## Implementation Phases
### Phase 1: Core Library (libazeron) ### Phase 1: Core Library (libazeron) ✅ COMPLETED
- [ ] Set up build system (CMake/autotools) - [x] Set up build system (CMake)
- [ ] Implement USB device detection and connection - [x] Implement USB device detection and connection
- [ ] Create device communication abstraction layer - [x] Create device communication abstraction layer
- [ ] Implement basic USB control transfers - [x] Implement USB interrupt transfers for configuration
- [ ] Add error handling and logging - [x] Add error handling and logging
- [x] Implement 64-byte HID report parser
- [x] Create command builder functions
- [x] Add button mapping support (29 buttons)
- [x] Implement joystick configuration
### Phase 2: Protocol Reverse Engineering ### Phase 2: Protocol Reverse Engineering ✅ COMPLETED
- [ ] Capture USB traffic from Windows software (if available) - [x] Capture USB traffic from Windows software
- [ ] Analyze vendor-specific interface (Interface 0) - [x] Analyze configuration interface (Interface 4)
- [ ] Document configuration command structure - [x] Document configuration command structure
- [ ] Map button IDs and analog stick data formats - [x] Map button IDs and analog stick data formats
- [ ] Understand profile storage and retrieval - [x] Understand profile storage and retrieval
- [x] Document complete protocol specification
### Phase 3: Command-Line Tool (azeron-cli) **Key Protocol Findings:**
- [ ] List connected Azeron devices - Configuration uses Interface 4 (endpoints 0x06 OUT, 0x85 IN)
- [ ] Read current button mappings - Fixed 64-byte HID reports with request-response pattern
- [ ] Remap buttons (assign keyboard keys, mouse buttons, etc.) - Commands: 0x122a (status), 0x12C8 (read config), 0x26FC (write profile), 0x26FD (save profile)
- [ ] Configure analog stick (deadzone, sensitivity, curves) - 2 profiles stored in device EEPROM, switchable via hardware switch
- [ ] Manage profiles (save, load, switch)
### Phase 3: Command-Line Tool (azeron-cli) 🔄 IN PROGRESS
- [x] List connected Azeron devices
- [x] Read current button mappings
- [x] Remap buttons (assign keyboard keys, mouse buttons, XInput gamepad buttons)
- [x] Configure analog stick (deadzone, sensitivity, angle -180° to 180°)
- [x] Manage profiles (read, write)
- [x] Support Single, Double, and Long press assignments per button with timing control
- [ ] Save profiles to device EEPROM (persistence)
- [ ] Export/import configurations - [ ] Export/import configurations
- [ ] Real-time configuration testing
### Phase 4: GUI Application (azeron-gui) ### Phase 4: GUI Application (azeron-gui) ⏳ PLANNED
- [ ] Create visual button mapping interface - [ ] Create visual button mapping interface
- [ ] Implement drag-and-drop or click-to-configure UI - [ ] Implement drag-and-drop or click-to-configure UI
- [ ] Add analog stick calibration wizard - [ ] Add analog stick calibration wizard
@@ -81,48 +104,59 @@ azeron-linux/
- [ ] Real-time configuration testing - [ ] Real-time configuration testing
- [ ] Save/load configuration files - [ ] Save/load configuration files
### Phase 5: Advanced Features ### Phase 5: Advanced Features ⏳ PLANNED
- [ ] LED control and effects (if supported)
- [ ] Macro recording and playback
- [ ] Analog stick mode switching (digital vs analog) - [ ] Analog stick mode switching (digital vs analog)
- [ ] Automatic profile switching based on active processes/games
- [ ] Factory reset, profile reset, and application settings reset
- [ ] Multiple device support - [ ] Multiple device support
- [ ] Configuration backup/restore - [ ] Configuration backup/restore
### Phase 6: Testing and Documentation ### Phase 6: Testing and Documentation 🔄 IN PROGRESS
- [ ] Unit tests for core library - [ ] Unit tests for core library
- [ ] Integration tests for CLI and GUI - [ ] Integration tests for CLI
- [ ] User documentation and tutorials - [x] User documentation (installation, development)
- [x] Protocol documentation
- [x] udev rules for non-root access
- [ ] Packaging (RPM for Fedora, DEB for Ubuntu) - [ ] Packaging (RPM for Fedora, DEB for Ubuntu)
- [ ] udev rules for non-root access
## Technical Requirements ## Technical Requirements
### Dependencies ### Dependencies
- **libusb-1.0**: For USB communication - **libusb-1.0** (>= 1.0.16) - USB device communication
- **libevdev**: For input event handling (testing) - **json-c** - Configuration file format support
- **GTK+ 3/Qt 5**: For GUI application - **CMake** (>= 3.10) - Build system
- **json-c**: For configuration file format - **C compiler** - GCC or Clang
- **pkg-config**: For build configuration
### Optional (for GUI)
- **Python 3** - For GUI application
- **PyQt5 or PyGTK** - GUI toolkit
### Development Tools ### Development Tools
- GCC/Clang C compiler - GCC/Clang C compiler
- CMake or GNU Autotools - CMake build system
- Git for version control - Git for version control
- Wireshark (for protocol analysis) - Wireshark (for protocol analysis)
- evtest/jstest (for testing input) - evtest/jstest (for testing input)
## Success Criteria ## Success Criteria
1. Users can remap all buttons on the Azeron keypad 1. Users can remap all 29 buttons on the Azeron keypad with Single, Double, and Long press support
2. Analog stick can be configured (deadzone, sensitivity, response curves) 2. Analog stick can be configured (deadzone, sensitivity, angle adjustment from -180° to 180°)
3. Multiple profiles can be created, saved, and switched 3. Both hardware profiles can be configured and switched
4. Configuration persists on the device (like Windows software) 4. Configuration persists on the device (stored in EEPROM)
5. Both CLI and GUI tools work reliably 5. CLI tool works reliably for all configuration tasks
6. No root access required (proper udev rules) 6. GUI tool provides intuitive visual configuration (future)
7. Documentation covers installation and common use cases 7. No root access required (proper udev rules)
8. Documentation covers installation and common use cases
## Next Steps ## Next Steps
1. Set up development environment and project structure 1. Complete CLI save functionality (0x26FD command implementation)
2. Begin implementing core USB communication library 2. Add comprehensive error handling and validation
3. Start protocol reverse engineering (with or without Windows capture) 3. Create unit tests for core library functions
4. Create basic CLI tool for testing 4. Implement configuration export/import in CLI
5. Iterate on functionality based on testing feedback 5. Begin GUI application development (Phase 4)
6. Add analog stick calibration wizard
7. Create comprehensive test suite
8. Package for major Linux distributions
## Current Development Focus
The project is currently transitioning from Phase 3 (CLI implementation) to Phase 6 (testing and packaging). The core library is complete and fully functional, the protocol has been fully reverse-engineered and documented, and the CLI tool is operational for most configuration tasks. The immediate priority is completing the persistence functionality and ensuring robust error handling before moving to GUI development.