# Azeron Cyborg Linux Configuration Software - Project Plan

## Overview
The Azeron Cyborg keypad (USB ID: 16d0:113c) is already recognized by Linux as a HID device and basic functionality works. However, Linux users need configuration software to remap buttons, configure analog sticks, and manage profiles - similar to the Windows software.

## Current Status
- **Device**: Azeron Cyborg Keypad (MCS, Vendor ID: 0x16d0, Product ID: 0x113c)
- **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)
- **Missing**: Configuration software to modify mappings, analog stick settings, and profiles

## USB Device Analysis
The device has 5 interfaces:
1. **Interface 0**: Vendor-specific (0xFF) - Likely configuration interface
2. **Interface 1**: HID - Main input interface (buttons)
3. **Interface 2**: HID Boot Mouse - Mouse emulation
4. **Interface 3**: HID - Analog stick input
5. **Interface 4**: HID with IN/OUT endpoints - Likely LED/control interface

## Architecture Decision
**Userspace Application Approach** (not kernel driver needed):
- Linux already recognizes device as HID
- Configuration is done through USB control transfers
- Userspace app can communicate with vendor-specific interface
- No kernel module required - more portable and easier to maintain

## Project Structure
```
azeron-linux/
├── libazeron/          # Core library for device communication
│   ├── azeron.c        # USB communication and protocol handling
│   ├── azeron.h        # Library API header
│   └── protocol.md     # Documented protocol findings
├── azeron-cli/         # Command-line configuration tool
│   ├── main.c          # CLI application
│   └── Makefile
├── azeron-gui/         # GUI configuration application
│   ├── main.py         # Python GUI (Qt/GTK)
│   ├── ui/             # UI files
│   └── requirements.txt
├── docs/               # Documentation
│   ├── installation.md
│   ├── usage.md
│   └── development.md
├── scripts/            # Helper scripts
│   ├── udev-rules/     # udev rules for device permissions
│   └── build.sh        # Build script
└── tests/              # Test suite
    └── test_protocol.c
```

## Implementation Phases

### Phase 1: Core Library (libazeron)
- [ ] Set up build system (CMake/autotools)
- [ ] Implement USB device detection and connection
- [ ] Create device communication abstraction layer
- [ ] Implement basic USB control transfers
- [ ] Add error handling and logging

### Phase 2: Protocol Reverse Engineering
- [ ] Capture USB traffic from Windows software (if available)
- [ ] Analyze vendor-specific interface (Interface 0)
- [ ] Document configuration command structure
- [ ] Map button IDs and analog stick data formats
- [ ] Understand profile storage and retrieval

### Phase 3: Command-Line Tool (azeron-cli)
- [ ] List connected Azeron devices
- [ ] Read current button mappings
- [ ] Remap buttons (assign keyboard keys, mouse buttons, etc.)
- [ ] Configure analog stick (deadzone, sensitivity, curves)
- [ ] Manage profiles (save, load, switch)
- [ ] Export/import configurations

### Phase 4: GUI Application (azeron-gui)
- [ ] Create visual button mapping interface
- [ ] Implement drag-and-drop or click-to-configure UI
- [ ] Add analog stick calibration wizard
- [ ] Profile management with visual indicators
- [ ] Real-time configuration testing
- [ ] Save/load configuration files

### Phase 5: Advanced Features
- [ ] LED control and effects (if supported)
- [ ] Macro recording and playback
- [ ] Analog stick mode switching (digital vs analog)
- [ ] Multiple device support
- [ ] Configuration backup/restore

### Phase 6: Testing and Documentation
- [ ] Unit tests for core library
- [ ] Integration tests for CLI and GUI
- [ ] User documentation and tutorials
- [ ] Packaging (RPM for Fedora, DEB for Ubuntu)
- [ ] udev rules for non-root access

## Technical Requirements

### Dependencies
- **libusb-1.0**: For USB communication
- **libevdev**: For input event handling (testing)
- **GTK+ 3/Qt 5**: For GUI application
- **json-c**: For configuration file format
- **pkg-config**: For build configuration

### Development Tools
- GCC/Clang C compiler
- CMake or GNU Autotools
- Git for version control
- Wireshark (for protocol analysis)
- evtest/jstest (for testing input)

## Success Criteria
1. Users can remap all buttons on the Azeron keypad
2. Analog stick can be configured (deadzone, sensitivity, response curves)
3. Multiple profiles can be created, saved, and switched
4. Configuration persists on the device (like Windows software)
5. Both CLI and GUI tools work reliably
6. No root access required (proper udev rules)
7. Documentation covers installation and common use cases

## Next Steps
1. Set up development environment and project structure
2. Begin implementing core USB communication library
3. Start protocol reverse engineering (with or without Windows capture)
4. Create basic CLI tool for testing
5. Iterate on functionality based on testing feedback