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

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
- **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, 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
The device has 5 interfaces:
1. **Interface 0**: Vendor-specific (0xFF) - Likely configuration interface
2. **Interface 1**: HID - Main input interface (buttons)
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 - Likely LED/control interface
5. **Interface 4**: HID with IN/OUT endpoints - Configuration interface (endpoints 0x06 OUT, 0x85 IN)
## Architecture Decision
**Userspace Application Approach** (not kernel driver needed):
**Userspace Application Approach** (no kernel driver needed):
- Linux already recognizes device as HID
- Configuration is done through USB control transfers
- Userspace app can communicate with vendor-specific interface
- 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-linux/
azeron-cyborg-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.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
│ └── Makefile
├── azeron-gui/ # GUI configuration application
│ ├── main.py # Python GUI (Qt/GTK)
│ ├── ui/ # UI files
│ └── requirements.txt
│ ├── main.c # CLI application entry point
│ ├── commands.c # Command implementations
│ ├── utils.c # CLI utilities
│ └── CMakeLists.txt # CLI build configuration
├── docs/ # Documentation
│ ├── installation.md
│ ├── usage.md
│ └── development.md
│ ├── 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
└── tests/ # Test suite
└── test_protocol.c
├── CMakeLists.txt # Main build configuration
├── captures/ # USB capture files for analysis
└── README.md # Project overview
```
## 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 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
- [ ] 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 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
### 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)
**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)
### 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
@@ -81,48 +104,59 @@ azeron-linux/
- [ ] Real-time configuration testing
- [ ] Save/load configuration files
### Phase 5: Advanced Features
- [ ] LED control and effects (if supported)
- [ ] Macro recording and playback
### 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
### Phase 6: Testing and Documentation 🔄 IN PROGRESS
- [ ] Unit tests for core library
- [ ] Integration tests for CLI and GUI
- [ ] User documentation and tutorials
- [ ] 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)
- [ ] 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
- **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 or GNU Autotools
- CMake build system
- 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
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. 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
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.