Raven/vpc-shift-tool
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Rename udev rules file and update documentation

Browse Source 
- 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
This commit is contained in:
raven
2025-04-10 13:25:35 -04:00
parent 9b43f600b8
commit 2bb5ce0327
7 changed files with 512 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.gitignore vendored
View File

@@ -4,7 +4,7 @@
### C++ template ### C++ template
# Prerequisites # Prerequisites
*.d #*.d
# Compiled Object files # Compiled Object files
*.slo *.slo

135
CONTRIBUTING.md Normal file
View File

@@ -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).

150
INSTALL.md Normal file
View File

@@ -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

2
Makefile
View File

@@ -25,7 +25,7 @@ install:
install -d $(DESTDIR)$(PREFIX)/bin install -d $(DESTDIR)$(PREFIX)/bin
install -d $(DESTDIR)/etc/udev/rules.d install -d $(DESTDIR)/etc/udev/rules.d
install -m 0755 target/$(target)/$(prog)$(extension) $(DESTDIR)$(PREFIX)/bin 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: clean:
cargo clean cargo clean

110
README.md
View File

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

116
TECHNICAL.md Normal file
View File

@@ -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<Mutex<T>>` for shared state
- `Arc<(Mutex<bool>, 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

0
udev/rules.d/99-vpc.rules → udev/rules.d/70-vpc.rules
View File