Initial commit
This commit is contained in:
Aodhan Collins
165
docs/development.md
Normal file
165
docs/development.md
Normal file
@@ -0,0 +1,165 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user