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)
• 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