azeron-cyborg-linux/plan.md

# 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)
- **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*)
- **Working Features**: Basic input with pre-configured mappings (stored in device firmware)
- **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
The device has 5 interfaces:
1. **Interface 0**: Vendor-specific (0xFF) - Unused for configuration
2. **Interface 1**: HID - Main button input (29 buttons)
3. **Interface 2**: HID Boot Mouse - Mouse emulation
4. **Interface 3**: HID - Analog stick input
5. **Interface 4**: HID with IN/OUT endpoints - Configuration interface (endpoints 0x06 OUT, 0x85 IN)

## Architecture Decision
**Userspace Application Approach** (no kernel driver needed):
- Linux already recognizes device as HID
- Configuration is done through USB interrupt transfers on Interface 4
- Userspace app can communicate using libusb
- No kernel module required - more portable and easier to maintain

## Project Structure
```
azeron-cyborg-linux/
├── libazeron/          # Core library for device communication
│   ├── azeron.c        # Main library implementation
│   ├── azeron.h        # Public API header
│   ├── 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
│   ├── main.c          # CLI application entry point
│   ├── commands.c      # Command implementations
│   ├── utils.c         # CLI utilities
│   └── CMakeLists.txt  # CLI build configuration
├── docs/               # Documentation
│   ├── installation.md # Installation instructions
│   ├── development.md  # Development guide
│   └── protocol.md     # Complete protocol documentation
├── scripts/            # Helper scripts
│   ├── udev-rules/     # udev rules for device permissions
│   └── build.sh        # Build script
├── CMakeLists.txt      # Main build configuration
├── captures/           # USB capture files for analysis
└── README.md           # Project overview
```

## Implementation Phases

### Phase 1: Core Library (libazeron) ✅ COMPLETED
- [x] Set up build system (CMake)
- [x] Implement USB device detection and connection
- [x] Create device communication abstraction layer
- [x] Implement USB interrupt transfers for configuration
- [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 ✅ COMPLETED
- [x] Capture USB traffic from Windows software
- [x] Analyze configuration interface (Interface 4)
- [x] Document configuration command structure
- [x] Map button IDs and analog stick data formats
- [x] Understand profile storage and retrieval
- [x] Document complete protocol specification

**Key Protocol Findings:**
- Configuration uses Interface 4 (endpoints 0x06 OUT, 0x85 IN)
- Fixed 64-byte HID reports with request-response pattern
- Commands: 0x122a (status), 0x12C8 (read config), 0x26FC (write profile), 0x26FD (save profile)
- 2 profiles stored in device EEPROM, switchable via hardware 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
- [ ] Real-time configuration testing

### Phase 4: GUI Application (azeron-gui) ⏳ PLANNED
- [ ] 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 ⏳ PLANNED
- [ ] 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
- [ ] Configuration backup/restore

### Phase 6: Testing and Documentation 🔄 IN PROGRESS
- [ ] Unit tests for core library
- [ ] Integration tests for CLI
- [x] User documentation (installation, development)
- [x] Protocol documentation
- [x] udev rules for non-root access
- [ ] Packaging (RPM for Fedora, DEB for Ubuntu)

## Technical Requirements

### Dependencies
- **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

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

## Success Criteria
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, angle adjustment from -180° to 180°)
3. Both hardware profiles can be configured and switched
4. Configuration persists on the device (stored in EEPROM)
5. CLI tool works reliably for all configuration tasks
6. GUI tool provides intuitive visual configuration (future)
7. No root access required (proper udev rules)
8. Documentation covers installation and common use cases

## Next Steps
1. Complete CLI save functionality (0x26FD command implementation)
2. Add comprehensive error handling and validation
3. Create unit tests for core library functions
4. Implement configuration export/import in CLI
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.