166 lines
3.9 KiB
Markdown
166 lines
3.9 KiB
Markdown
# 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)
|