aodhan/azeron-cyborg-linux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
18f84a538a53ce3195b11c441617306fdde03773
azeron-cyborg-linux/docs/development.md
Aodhan Collins 0267543622 Initial commit
2026-02-22 12:51:32 +00:00

3.9 KiB
Raw Blame History

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

sudo dnf install cmake gcc libusb1-devel json-c-devel

Ubuntu/Debian

sudo apt-get install cmake build-essential libusb-1.0-0-dev libjson-c-dev

Build Instructions

mkdir build
cd build
cmake ..
make
sudo make install

Build Options

# 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

# Set debug environment variable
export AZERON_DEBUG=1
azeron-cli list

USB Debugging

# 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

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