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
This commit is contained in:
2
.gitignore
vendored
2
.gitignore
vendored
@@ -4,7 +4,7 @@
|
||||
|
||||
### C++ template
|
||||
# Prerequisites
|
||||
*.d
|
||||
#*.d
|
||||
|
||||
# Compiled Object files
|
||||
*.slo
|
||||
|
||||
135
CONTRIBUTING.md
Normal file
135
CONTRIBUTING.md
Normal 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
150
INSTALL.md
Normal 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
2
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
|
||||
|
||||
110
README.md
110
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)
|
||||
|
||||
116
TECHNICAL.md
Normal file
116
TECHNICAL.md
Normal 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
|
||||
Reference in New Issue
Block a user