Initial commit

docs/installation.md

@@ -0,0 +1,196 @@
+# Installation Guide
+
+## Quick Install
+
+### Fedora/RHEL/CentOS
+
+```bash
+# Install dependencies
+sudo dnf install libusb1-devel json-c-devel
+
+# Build from source
+git clone <repository-url>
+cd azeron-linux
+mkdir build && cd build
+cmake ..
+make
+sudo make install
+
+# Install udev rules for non-root access
+sudo cp scripts/udev-rules/99-azeron.rules /etc/udev/rules.d/
+sudo udevadm control --reload-rules
+sudo udevadm trigger
+```
+
+### Ubuntu/Debian
+
+```bash
+# Install dependencies
+sudo apt-get update
+sudo apt-get install build-essential cmake libusb-1.0-0-dev libjson-c-dev
+
+# Build from source
+git clone <repository-url>
+cd azeron-linux
+mkdir build && cd build
+cmake ..
+make
+sudo make install
+
+# Install udev rules for non-root access
+sudo cp scripts/udev-rules/99-azeron.rules /etc/udev/rules.d/
+sudo udevadm control --reload-rules
+sudo udevadm trigger
+```
+
+### Arch Linux
+
+```bash
+# Install dependencies
+sudo pacman -S base-devel cmake libusb json-c
+
+# Build from source (same as above)
+```
+
+## Dependencies
+
+### Required
+- **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
+
+## Building from Source
+
+### Step 1: Install Dependencies
+
+Choose your distribution from the sections above and install the required packages.
+
+### Step 2: Clone Repository
+
+```bash
+git clone <repository-url>
+cd azeron-linux
+```
+
+### Step 3: Build
+
+```bash
+mkdir build
+cd build
+cmake ..
+make -j$(nproc)
+```
+
+### Step 4: Install
+
+```bash
+sudo make install
+```
+
+This installs:
+- `libazeron.so` - Core library (to /usr/local/lib)
+- `azeron-cli` - Command-line tool (to /usr/local/bin)
+- Header files (to /usr/local/include)
+- udev rules (to /etc/udev/rules.d)
+- Documentation (to /usr/local/share/doc)
+
+### Step 5: Configure Permissions
+
+For non-root access to the USB device:
+
+```bash
+sudo cp scripts/udev-rules/99-azeron.rules /etc/udev/rules.d/
+sudo udevadm control --reload-rules
+sudo udevadm trigger
+```
+
+Then unplug and reconnect your Azeron device.
+
+## Verification
+
+Verify installation:
+
+```bash
+# Check if azeron-cli is installed
+which azeron-cli
+
+# List connected devices
+azeron-cli list
+
+# Should show something like:
+# Device 0: Azeron Cyborg Keypad (16d0:113c)
+```
+
+## Troubleshooting
+
+### "command not found: azeron-cli"
+
+The install directory may not be in your PATH. Add it:
+
+```bash
+echo 'export PATH=/usr/local/bin:$PATH' >> ~/.bashrc
+source ~/.bashrc
+```
+
+Or use the full path: `/usr/local/bin/azeron-cli`
+
+### "Permission denied" when accessing device
+
+1. Ensure udev rules are installed correctly
+2. Check rule file permissions: `ls -l /etc/udev/rules.d/99-azeron.rules`
+3. Reconnect the device after installing rules
+4. As a temporary workaround, use sudo: `sudo azeron-cli list`
+
+### "libazeron.so: cannot open shared object file"
+
+The library path may not be configured. Add it:
+
+```bash
+echo '/usr/local/lib' | sudo tee /etc/ld.so.conf.d/azeron.conf
+sudo ldconfig
+```
+
+### Device not detected
+
+1. Check USB connection: `lsusb | grep 16d0`
+2. Verify device appears: `lsusb -v -d 16d0:113c`
+3. Check kernel messages: `dmesg | tail -20`
+4. Ensure no other program is using the device
+
+### Build errors
+
+1. Ensure all dependencies are installed
+2. Check CMake version: `cmake --version` (needs >= 3.10)
+3. Check compiler version: `gcc --version`
+4. Look for missing development packages
+
+## Uninstallation
+
+```bash
+cd build
+sudo make uninstall
+```
+
+To also remove udev rules:
+
+```bash
+sudo rm /etc/udev/rules.d/99-azeron.rules
+sudo udevadm control --reload-rules
+```
+
+## Package Managers
+
+### Future Plans
+
+We plan to provide packages for:
+- Fedora COPR repository
+- Ubuntu PPA
+- Arch Linux AUR
+- openSUSE OBS
+
+Check back soon or help us create packages!