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