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

Initial commit

Browse Source
This commit is contained in:
Aodhan Collins
2026-02-22 12:51:32 +00:00
commit 0267543622
21 changed files with 2888 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

165
docs/development.md Normal file
View File

@@ -0,0 +1,165 @@
# Development Guide
## Project Architecture
This project uses a userspace approach to configure the Azeron Cyborg keypad. Since Linux already recognizes the device as a HID device, we don't need a kernel driver. Instead, we communicate directly with the device using libusb to send configuration commands.
## Directory Structure
- `libazeron/` - Core C library for device communication
- `azeron-cli/` - Command-line interface tool
- `azeron-gui/` - Python GUI application (planned)
- `docs/` - Documentation
- `scripts/` - Helper scripts and udev rules
## Building from Source
### Prerequisites
- CMake 3.10 or higher
- C compiler (GCC or Clang)
- libusb-1.0 development files
- json-c development files
#### Fedora/RHEL
```bash
sudo dnf install cmake gcc libusb1-devel json-c-devel
```
#### Ubuntu/Debian
```bash
sudo apt-get install cmake build-essential libusb-1.0-0-dev libjson-c-dev
```
### Build Instructions
```bash
mkdir build
cd build
cmake ..
make
sudo make install
```
### Build Options
```bash
# Debug build
cmake -DCMAKE_BUILD_TYPE=Debug ..
# Specify installation prefix
cmake -DCMAKE_INSTALL_PREFIX=/usr/local ..
# Build without udev rules
cmake -DINSTALL_UDEV_RULES=OFF ..
```
## Development Workflow
### 1. Core Library Development
The `libazeron` library is the foundation. It handles:
- USB device detection and connection
- Configuration protocol implementation
- Error handling and logging
Key files:
- `libazeron/azeron.h` - Public API
- `libazeron/azeron.c` - Implementation
- `libazeron/protocol.md` - Protocol documentation
### 2. Testing Protocol
Since we may not have Windows software to reverse engineer from, we'll use a systematic approach:
1. **Device Enumeration**: List all USB descriptors and endpoints
2. **Control Transfers**: Test standard USB control transfers
3. **Interrupt Transfers**: Monitor interrupt endpoints for data
4. **Configuration Commands**: Try to discover configuration commands
5. **Response Analysis**: Parse device responses
Useful tools:
- `lsusb -v -d 16d0:113c` - Device information
- `usbhid-dump` - HID report descriptors
- `evtest` - Input event testing
- Wireshark with USBPcap - Protocol analysis (if Windows available)
### 3. Adding New Features
1. Implement feature in `libazeron` first
2. Add CLI support in `azeron-cli`
3. Add GUI support in `azeron-gui` (if applicable)
4. Update documentation
5. Add tests
## Code Style
- C code follows Linux kernel style (indent with tabs)
- Functions should be documented with Doxygen comments
- Error handling: check all return values
- Memory management: free all allocated memory
- Use const where appropriate
## Debugging
### Enable Debug Output
```bash
# Set debug environment variable
export AZERON_DEBUG=1
azeron-cli list
```
### USB Debugging
```bash
# Monitor USB traffic (requires root)
sudo usbmon -f -t > usb_trace.txt
# Use with azeron-cli to capture configuration commands
```
### Common Issues
1. **Permission Denied**: Install udev rules or run with sudo
2. **Device Not Found**: Check USB connection and device permissions
3. **Configuration Not Applying**: Ensure device is in configuration mode
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
## Testing
### Unit Tests
```bash
cd build
make test
```
### Manual Testing
1. Connect Azeron device
2. Run `azeron-cli list` to verify detection
3. Test button mapping: `azeron-cli map-button 5 KEY_W`
4. Verify mapping works in game/application
5. Test profile save/load functionality
## Release Process
1. Update version in CMakeLists.txt
2. Update CHANGELOG.md
3. Create git tag: `git tag -a v1.0.0 -m "Release version 1.0.0"`
4. Push tag: `git push origin v1.0.0`
5. Create release packages
## Resources
- [libusb API Documentation](https://libusb.info/)
- [Linux Input Subsystem](https://www.kernel.org/doc/html/latest/input/)
- [USB HID Specification](https://www.usb.org/hid)

196
docs/installation.md Normal file
View File

@@ -0,0 +1,196 @@
# Installation Guide
## Quick Install
### Fedora/RHEL/CentOS
```bash
# Install dependencies
sudo dnf install libusb1-devel json-c-devel
# Build from source
git clone <repository-url>
cd azeron-linux
mkdir build && cd build
cmake ..
make
sudo make install
# Install udev rules for non-root access
sudo cp scripts/udev-rules/99-azeron.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger
```
### Ubuntu/Debian
```bash
# Install dependencies
sudo apt-get update
sudo apt-get install build-essential cmake libusb-1.0-0-dev libjson-c-dev
# Build from source
git clone <repository-url>
cd azeron-linux
mkdir build && cd build
cmake ..
make
sudo make install
# Install udev rules for non-root access
sudo cp scripts/udev-rules/99-azeron.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger
```
### Arch Linux
```bash
# Install dependencies
sudo pacman -S base-devel cmake libusb json-c
# Build from source (same as above)
```
## Dependencies
### Required
- **libusb-1.0** (>= 1.0.16) - USB device communication
- **json-c** - Configuration file format support
- **CMake** (>= 3.10) - Build system
- **C compiler** - GCC or Clang
### Optional (for GUI)
- **Python 3** - For GUI application
- **PyQt5 or PyGTK** - GUI toolkit
## Building from Source
### Step 1: Install Dependencies
Choose your distribution from the sections above and install the required packages.
### Step 2: Clone Repository
```bash
git clone <repository-url>
cd azeron-linux
```
### Step 3: Build
```bash
mkdir build
cd build
cmake ..
make -j$(nproc)
```
### Step 4: Install
```bash
sudo make install
```
This installs:
- `libazeron.so` - Core library (to /usr/local/lib)
- `azeron-cli` - Command-line tool (to /usr/local/bin)
- Header files (to /usr/local/include)
- udev rules (to /etc/udev/rules.d)
- Documentation (to /usr/local/share/doc)
### Step 5: Configure Permissions
For non-root access to the USB device:
```bash
sudo cp scripts/udev-rules/99-azeron.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger
```
Then unplug and reconnect your Azeron device.
## Verification
Verify installation:
```bash
# Check if azeron-cli is installed
which azeron-cli
# List connected devices
azeron-cli list
# Should show something like:
# Device 0: Azeron Cyborg Keypad (16d0:113c)
```
## Troubleshooting
### "command not found: azeron-cli"
The install directory may not be in your PATH. Add it:
```bash
echo 'export PATH=/usr/local/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
```
Or use the full path: `/usr/local/bin/azeron-cli`
### "Permission denied" when accessing device
1. Ensure udev rules are installed correctly
2. Check rule file permissions: `ls -l /etc/udev/rules.d/99-azeron.rules`
3. Reconnect the device after installing rules
4. As a temporary workaround, use sudo: `sudo azeron-cli list`
### "libazeron.so: cannot open shared object file"
The library path may not be configured. Add it:
```bash
echo '/usr/local/lib' | sudo tee /etc/ld.so.conf.d/azeron.conf
sudo ldconfig
```
### Device not detected
1. Check USB connection: `lsusb | grep 16d0`
2. Verify device appears: `lsusb -v -d 16d0:113c`
3. Check kernel messages: `dmesg | tail -20`
4. Ensure no other program is using the device
### Build errors
1. Ensure all dependencies are installed
2. Check CMake version: `cmake --version` (needs >= 3.10)
3. Check compiler version: `gcc --version`
4. Look for missing development packages
## Uninstallation
```bash
cd build
sudo make uninstall
```
To also remove udev rules:
```bash
sudo rm /etc/udev/rules.d/99-azeron.rules
sudo udevadm control --reload-rules
```
## Package Managers
### Future Plans
We plan to provide packages for:
- Fedora COPR repository
- Ubuntu PPA
- Arch Linux AUR
- openSUSE OBS
Check back soon or help us create packages!

333
docs/protocol.md Normal file
View 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