From 2bb5ce0327b4e53e6dcb2c313c295327e0ed3625 Mon Sep 17 00:00:00 2001 From: raven <7156279+RavenX8@users.noreply.github.com> Date: Thu, 10 Apr 2025 13:25:35 -0400 Subject: [PATCH] Rename udev rules file and update documentation - Renamed udev rules file from 99-vpc.rules to 70-vpc.rules for better priority - Updated all references to the file in Makefile and documentation - Added instructions for manually creating udev rules when using precompiled binaries - Improved installation instructions for both Windows and Linux platforms --- .gitignore | 2 +- CONTRIBUTING.md | 135 ++++++++++++++++++ INSTALL.md | 150 ++++++++++++++++++++ Makefile | 2 +- README.md | 110 +++++++++++++- TECHNICAL.md | 116 +++++++++++++++ udev/rules.d/{99-vpc.rules => 70-vpc.rules} | 0 7 files changed, 512 insertions(+), 3 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 INSTALL.md create mode 100644 TECHNICAL.md rename udev/rules.d/{99-vpc.rules => 70-vpc.rules} (100%) diff --git a/.gitignore b/.gitignore index 98af525..36b5430 100644 --- a/.gitignore +++ b/.gitignore @@ -4,7 +4,7 @@ ### C++ template # Prerequisites -*.d +#*.d # Compiled Object files *.slo diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..7c6f165 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,135 @@ +# Contributing to OpenVPC Shift Tool + +Thank you for your interest in contributing to the OpenVPC Shift Tool! This document provides guidelines and instructions for contributing to the project. + +## Code of Conduct + +Please be respectful and considerate of others when contributing to this project. We aim to foster an inclusive and welcoming community. + +## Getting Started + +1. Fork the repository on GitHub +2. Clone your fork locally: + ``` + git clone https://github.com/YOUR-USERNAME/vpc-shift-tool.git + cd vpc-shift-tool + ``` +3. Add the original repository as an upstream remote: + ``` + git remote add upstream https://github.com/RavenX8/vpc-shift-tool.git + ``` +4. Create a new branch for your changes: + ``` + git checkout -b feature/your-feature-name + ``` + +## Development Environment Setup + +1. Install the Rust toolchain from [rustup.rs](https://rustup.rs/) +2. Install dependencies: + - Windows: No additional dependencies required + - Linux: `sudo apt install libudev-dev pkg-config` (Ubuntu/Debian) + +3. Build the project: + ``` + cargo build + ``` + +4. Run the application: + ``` + cargo run + ``` + +## Making Changes + +1. Make your changes to the codebase +2. Write or update tests as necessary +3. Ensure all tests pass: + ``` + cargo test + ``` +4. Format your code: + ``` + cargo fmt + ``` +5. Run the linter: + ``` + cargo clippy + ``` + +## Commit Guidelines + +- Use clear and descriptive commit messages +- Reference issue numbers in your commit messages when applicable +- Keep commits focused on a single change +- Use the present tense ("Add feature" not "Added feature") + +## Pull Request Process + +1. Update your fork with the latest changes from upstream: + ``` + git fetch upstream + git rebase upstream/main + ``` +2. Push your changes to your fork: + ``` + git push origin feature/your-feature-name + ``` +3. Create a pull request through the GitHub interface +4. Ensure your PR description clearly describes the changes and their purpose +5. Link any related issues in the PR description + +## Code Style + +- Follow the Rust style guidelines +- Use meaningful variable and function names +- Add comments for complex logic +- Document public functions and types + +## Project Structure + +- `src/main.rs`: Application entry point and main structure +- `src/about.rs`: About screen information +- `src/config.rs`: Configuration handling +- `src/device.rs`: Device representation and management +- `src/hid_worker.rs`: HID communication worker thread +- `src/state.rs`: Application state management +- `src/ui.rs`: User interface components +- `src/util.rs`: Utility functions and constants + +## Adding Support for New Devices + +If you're adding support for new device types: + +1. Update the device detection logic in `device.rs` +2. Add any necessary report format definitions in `util.rs` +3. Test with the actual hardware if possible +4. Document the new device support in your PR + +## Testing + +- Write unit tests for new functionality +- Test on both Windows and Linux if possible +- Test with actual VirPil hardware if available + +## Documentation + +- Update the README.md with any new features or changes +- Document new functions and types with rustdoc comments +- Update TECHNICAL.md for significant architectural changes + +## Reporting Issues + +If you find a bug or have a suggestion for improvement: + +1. Check if the issue already exists in the [GitHub Issues](https://github.com/RavenX8/vpc-shift-tool/issues) +2. If not, create a new issue with: + - A clear title and description + - Steps to reproduce the issue + - Expected and actual behavior + - System information (OS, Rust version, etc.) + - Screenshots if applicable + +## License + +By contributing to this project, you agree that your contributions will be licensed under the project's [GNU General Public License v3.0](LICENSE). diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..fb49e42 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,150 @@ +# Installation Guide for OpenVPC Shift Tool + +This guide provides detailed instructions for installing and setting up the OpenVPC Shift Tool on different operating systems. + +## Windows Installation + +### Using Pre-built Binary + +1. Download the Windows build artifact (`Windows-x86_64_build`) from the [GitHub Actions](https://github.com/RavenX8/vpc-shift-tool/actions) page by selecting the most recent successful workflow run +2. The downloaded artifact is the executable binary itself (shift_tool.exe) +3. Place it in a location of your choice and run it + +### Building from Source on Windows + +1. Install the Rust toolchain from [rustup.rs](https://rustup.rs/) +2. Open Command Prompt or PowerShell +3. Clone the repository: + ``` + git clone https://github.com/RavenX8/vpc-shift-tool.git + cd vpc-shift-tool + ``` +4. Build the release version: + ``` + cargo build --release + ``` +5. The executable will be available at `target\release\shift_tool.exe` + +## Linux Installation + +### Using Pre-built Binary + +1. Download the Linux build artifact (`Linux-x86_64_build`) from the [GitHub Actions](https://github.com/RavenX8/vpc-shift-tool/actions) page by selecting the most recent successful workflow run +2. The downloaded artifact is the executable binary itself, no extraction needed. Just make it executable: + ``` + chmod +x Linux-x86_64_build + # Optionally rename it to something more convenient + mv Linux-x86_64_build shift_tool + ``` +3. Create and install the udev rules for device access: + ``` + sudo mkdir -p /etc/udev/rules.d/ + # Create the udev rule file + echo -e '# Virpil Control devices\nSUBSYSTEM=="usb", ATTRS{idVendor}=="3344", TAG+="uaccess", GROUP:="input"' | sudo tee /etc/udev/rules.d/70-vpc.rules + sudo udevadm control --reload-rules + sudo udevadm trigger + ``` +4. Make the binary executable and run it: + ``` + chmod +x shift_tool + ./shift_tool + ``` + +### Building from Source on Linux + +1. Install dependencies: + ``` + # Ubuntu/Debian + sudo apt install build-essential libudev-dev pkg-config + + # Fedora + sudo dnf install gcc libudev-devel pkgconfig + + # Arch Linux + sudo pacman -S base-devel + ``` + +2. Install the Rust toolchain from [rustup.rs](https://rustup.rs/) + +3. Clone the repository: + ``` + git clone https://github.com/RavenX8/vpc-shift-tool.git + cd vpc-shift-tool + ``` + +4. Build and install using the Makefile: + ``` + make + sudo make install + ``` + + Or manually: + ``` + cargo build --release + sudo cp target/release/shift_tool /usr/local/bin/ + sudo mkdir -p /etc/udev/rules.d/ + sudo cp udev/rules.d/70-vpc.rules /etc/udev/rules.d/ + sudo udevadm control --reload-rules + sudo udevadm trigger + ``` + +## Verifying Installation + +After installation, you can verify that the application can detect your VirPil devices: + +1. Connect your VirPil device(s) to your computer +2. Launch the OpenVPC Shift Tool +3. Click the "Refresh Devices" button +4. Your devices should appear in the dropdown menus + +If devices are not detected: + +- On Windows, ensure you have the correct drivers installed +- On Linux, verify the udev rules are installed correctly and you've reloaded the rules +- Check that your devices are properly connected and powered on + +## Configuration Location + +The application stores its configuration in: + +- Windows: `%APPDATA%\shift_tool.json` +- Linux: `~/.config/shift_tool.json` + +## Uninstallation + +### Windows + +Simply delete the application files. + +### Linux + +If installed using the Makefile: +``` +sudo rm /usr/local/bin/shift_tool +sudo rm /etc/udev/rules.d/70-vpc.rules +``` + +## Troubleshooting + +### Linux Permission Issues + +If you encounter permission issues accessing the devices on Linux: + +1. Ensure the udev rules are installed correctly +2. Add your user to the input group: + ``` + sudo usermod -a -G input $USER + ``` +3. Log out and log back in, or reboot your system +4. Verify your user is in the input group: + ``` + groups $USER + ``` + +### Windows Device Access Issues + +If the application cannot access devices on Windows: + +1. Ensure no other application (like the official VPC software) is currently using the devices +2. Try running the application as Administrator (right-click, "Run as Administrator") +3. Check Device Manager to ensure the devices are properly recognized by Windows diff --git a/Makefile b/Makefile index 2e9e797..c67b69d 100644 --- a/Makefile +++ b/Makefile @@ -25,7 +25,7 @@ install: install -d $(DESTDIR)$(PREFIX)/bin install -d $(DESTDIR)/etc/udev/rules.d install -m 0755 target/$(target)/$(prog)$(extension) $(DESTDIR)$(PREFIX)/bin - install -m 0644 udev/rules.d/99-vpc.rules $(DESTDIR)/etc/udev/rules.d + install -m 0644 udev/rules.d/70-vpc.rules $(DESTDIR)/etc/udev/rules.d clean: cargo clean diff --git a/README.md b/README.md index ff03698..b23ec18 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,110 @@ -# vpc-shift-tool +# OpenVPC - Shift Tool +A free and open-source alternative to the VPC Shift Tool bundled with the VirPil control software package. + +## Overview + +OpenVPC Shift Tool is a utility designed for VirPil flight simulation controllers. It allows you to combine button inputs from multiple VirPil devices using logical operations (OR, AND, XOR), creating a "shift state" that can be sent to receiver devices. This enables more complex control schemes and button combinations for flight simulators. + +## Features + +- Connect to multiple VirPil devices simultaneously +- Configure source devices that provide button inputs +- Set up receiver devices that receive the combined shift state +- Choose between different logical operations (OR, AND, XOR) for each bit +- Automatic device detection for VirPil hardware +- Configuration saving and loading +- Cross-platform support (Windows and Linux) + +## Installation + +### Pre-built Binaries + +Pre-built binaries for Windows and Linux are available in the GitHub Actions artifacts for each commit. You can find them by: + +1. Going to the [Actions tab](https://github.com/RavenX8/vpc-shift-tool/actions) +2. Selecting the most recent successful workflow run +3. Downloading the appropriate artifact for your platform (Linux-x86_64_build or Windows-x86_64_build) + +### Building from Source + +#### Prerequisites + +- Rust toolchain (install from [rustup.rs](https://rustup.rs/)) +- For Linux: libudev-dev package + +#### Build Steps + +```bash +# Clone the repository +git clone https://github.com/RavenX8/vpc-shift-tool.git +cd vpc-shift-tool + +# Build the release version +cargo build --release +``` + +The compiled binary will be available in `target/release/`. + +### Linux Installation + +On Linux, you need to install udev rules to access VirPil devices without root privileges: + +```bash +# Using the Makefile +sudo make install + +# Or manually +sudo cp udev/rules.d/70-vpc.rules /etc/udev/rules.d/ +sudo udevadm control --reload-rules +sudo udevadm trigger +``` + +## Usage + +1. Launch the application +2. The main interface shows three sections: + - **Sources**: Devices that provide button inputs + - **Rules**: Logical operations to apply to each bit + - **Receivers**: Devices that receive the combined shift state + +3. Add source devices by selecting them from the dropdown menu +4. Configure which bits are active for each source +5. Set the logical operation (OR, AND, XOR) for each bit in the Rules section +6. Add receiver devices that will receive the combined shift state +7. Click "Start" to begin the shift operation + +## Configuration + +The application automatically saves your configuration to: +- Windows: `%APPDATA%\shift_tool.json` +- Linux: `~/.config/shift_tool.json` + +## Troubleshooting + +### Device Not Detected + +- Ensure your VirPil devices are properly connected +- On Linux, verify udev rules are installed correctly +- Try refreshing the device list with the "Refresh Devices" button + +### Permission Issues on Linux + +If you encounter permission issues accessing the devices on Linux: + +1. Ensure the udev rules are installed correctly +2. Log out and log back in, or reboot your system +3. Verify your user is in the "input" group: `groups $USER` + +## License + +GNU General Public License v3.0 + +## Author + +RavenX8 + +## Links + +- [GitHub Repository](https://github.com/RavenX8/vpc-shift-tool) +- [Gitea Repository](https://gitea.azgstudio.com/Raven/vpc-shift-tool) diff --git a/TECHNICAL.md b/TECHNICAL.md new file mode 100644 index 0000000..25c2a79 --- /dev/null +++ b/TECHNICAL.md @@ -0,0 +1,116 @@ +# OpenVPC Shift Tool - Technical Documentation + +This document provides technical details about the OpenVPC Shift Tool application, its architecture, and how it works internally. + +## Architecture Overview + +The application is built using Rust with the following main components: + +1. **GUI Layer**: Uses the `eframe` crate (egui) for cross-platform GUI +2. **HID Communication**: Uses the `hidapi` crate to communicate with VirPil devices +3. **Configuration Management**: Uses the `fast_config` crate for saving/loading settings +4. **Worker Thread**: Background thread that handles device communication + +## Core Components + +### Main Application Structure + +The main application is represented by the `ShiftTool` struct in `src/main.rs`, which contains: + +- State management +- Device list +- Shared state between UI and worker thread +- Configuration data + +### Modules + +- **about.rs**: Contains application information and about screen text +- **config.rs**: Configuration data structures and serialization +- **device.rs**: Device representation and management +- **hid_worker.rs**: Background worker thread for HID communication +- **state.rs**: Application state enum +- **ui.rs**: User interface drawing and event handling +- **util.rs**: Utility functions and constants + +## Data Flow + +1. The application scans for VirPil devices (vendor ID 0x3344) +2. User selects source and receiver devices in the UI +3. When "Start" is clicked, a worker thread is spawned +4. The worker thread: + - Opens connections to all configured devices + - Reads input from source devices + - Applies logical operations based on configuration + - Writes the resulting shift state to receiver devices +5. Shared state (protected by mutexes) is used to communicate between the UI and worker thread + +## Device Communication + +### Device Detection + +Devices are detected using the HID API, filtering for VirPil's vendor ID (0x3344). The application creates `VpcDevice` objects for each detected device, which include: + +- Vendor ID and Product ID +- Device name and firmware version +- Serial number +- Usage page/ID + +### HID Protocol + +The application supports different report formats based on device firmware versions. The worker thread: + +1. Reads HID reports from source devices +2. Extracts button states from the reports +3. Applies logical operations (OR, AND, XOR) to combine states +4. Formats the combined state into HID reports +5. Sends the reports to receiver devices + +## Configuration + +Configuration is stored in JSON format using the `fast_config` crate. The configuration includes: + +- Source devices (vendor ID, product ID, serial number, enabled bits) +- Receiver devices (vendor ID, product ID, serial number, enabled bits) +- Shift modifiers (logical operations for each bit) + +## Threading Model + +The application uses a main UI thread and a separate worker thread: + +1. **Main Thread**: Handles UI rendering and user input +2. **Worker Thread**: Performs HID communication in the background + +Thread synchronization is achieved using: +- `Arc>` for shared state +- `Arc<(Mutex, Condvar)>` for signaling thread termination + +## Linux-Specific Features + +On Linux, the application requires udev rules to access HID devices without root privileges. The rule is installed to `/etc/udev/rules.d/70-vpc.rules` and contains: + +``` +# Virpil Control devices +SUBSYSTEM=="usb", ATTRS{idVendor}=="3344", TAG+="uaccess", GROUP:="input" +``` + +## Building and Deployment + +The application can be built using Cargo: + +```bash +cargo build --release +``` + +A Makefile is provided for easier installation on Linux, which: +1. Builds the application +2. Installs the binary to `/usr/local/bin` +3. Installs udev rules to `/etc/udev/rules.d/` + +## Future Development + +Potential areas for enhancement: +- Support for additional device types +- More complex logical operations +- Custom button mapping +- Profile management +- Integration with game APIs diff --git a/udev/rules.d/99-vpc.rules b/udev/rules.d/70-vpc.rules similarity index 100% rename from udev/rules.d/99-vpc.rules rename to udev/rules.d/70-vpc.rules