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:
2025-04-10 13:25:35 -04:00
parent 9b43f600b8
commit 2bb5ce0327
7 changed files with 512 additions and 3 deletions

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