Major reorganization: Separate native HID solution from OTD diagnostics
After extensive testing, determined that OpenTabletDriver does NOT work reliably with Paintstorm in distrobox. Reorganized the project to clearly separate the working native HID solution from OTD troubleshooting tools. NEW STRUCTURE: native-hid-tablet-mapping/ (RECOMMENDED) - Complete button mapping solution using native Linux HID drivers - Configuration-based system with tablet-button-config.conf - apply-button-mappings.sh: Reads config and generates xbindkeys setup - setup-autostart.sh: Makes button mappings persistent across reboots - Detection scripts: test-pen-buttons.sh, test-tablet-keyboard-events.sh - README explaining setup for Huion tablets on Arch Linux otd-diagnostics/ (NOT RECOMMENDED) - Diagnostic tools created during OTD troubleshooting - Documents why OTD doesn't work (mouse freeze, launch failures, etc.) - Kept for reference and debugging purposes only - README explaining the issues and recommending native HID instead NATIVE HID ADVANTAGES: ✅ Full pressure sensitivity (0-8191 levels) ✅ Tilt support (X/Y angles) ✅ Button mapping with xbindkeys ✅ No mouse freezing ✅ No second-launch failures ✅ Stable, reliable operation CONFIGURATION SYSTEM: - tablet-button-config.conf: User-editable button mappings - Supports pen buttons (xinput) and tablet buttons (keyboard events) - Examples: pen_button_2="ctrl+z", tablet_keycode_56="e" - Run apply-button-mappings.sh to generate and apply xbindkeys config - Run setup-autostart.sh for persistence TESTED CONFIGURATION: - Distribution: Arch Linux - Tablet: Huion G930L - 6 tablet buttons (already send keyboard events) - 2 pen buttons (mapped via xbindkeys) - No OpenTabletDriver required Updated main README to reflect native HID as recommended solution. Clearly marked OTD as not recommended with explanation.
+764 −210 · 19 files changed
-
README.md+108 −210 -
native-hid-tablet-mapping/README.md+203 −0 -
native-hid-tablet-mapping/apply-button-mappings.sh+175 −0 -
detect-tablet-buttons.sh => native-hid-tablet-mapping/detect-tablet-buttons.sh+0 −0 -
native-hid-tablet-mapping/setup-autostart.sh+83 −0 -
native-hid-tablet-mapping/tablet-button-config.conf+92 −0 -
test-pen-buttons.sh => native-hid-tablet-mapping/test-pen-buttons.sh+0 −0 -
test-tablet-keyboard-events.sh => native-hid-tablet-mapping/test-tablet-keyboard-events.sh+0 −0 -
otd-diagnostics/README.md+103 −0 -
TABLET-INPUT-GUIDE.md => otd-diagnostics/TABLET-INPUT-GUIDE.md+0 −0 -
check-which-device-used.sh => otd-diagnostics/check-which-device-used.sh+0 −0 -
diagnose-pointer-freeze.sh => otd-diagnostics/diagnose-pointer-freeze.sh+0 −0 -
fix-pointer-freeze.sh => otd-diagnostics/fix-pointer-freeze.sh+0 −0 -
paintstorm-with-otd-wrapper.sh => otd-diagnostics/paintstorm-with-otd-wrapper.sh+0 −0 -
test-paintstorm-relaunch-issue.sh => otd-diagnostics/test-paintstorm-relaunch-issue.sh+0 −0 -
test-pressure-data.sh => otd-diagnostics/test-pressure-data.sh+0 −0 -
test-which-device-active.sh => otd-diagnostics/test-which-device-active.sh+0 −0 -
test-xsetwacom-compatibility.sh => otd-diagnostics/test-xsetwacom-compatibility.sh+0 −0 -
track-device-state-changes.sh => otd-diagnostics/track-device-state-changes.sh+0 −0
@@ -1,6 +1,6 @@ # Paintstorm Studio Distrobox Setup -A complete setup script to run Paintstorm Studio v2.50 in an Ubuntu 20.04 distrobox container on modern Linux systems, with full tablet pressure and tilt support for OpenTabletDriver. +A complete setup script to run Paintstorm Studio v2.50 in an Ubuntu 20.04 distrobox container on modern Linux systems, with full tablet pressure and tilt support using **native Linux HID drivers**. ## Features @@ -10,12 +10,12 @@ A complete setup script to run Paintstorm Studio v2.50 in an Ubuntu 20.04 distro - All required dependencies installed - Font crash prevention configured -✅ **Tablet Support** (NEW in v2.4) +✅ **Tablet Support** (Native HID - RECOMMENDED) - Full pressure sensitivity (0-8191 levels) - Tilt support (X/Y angles) -- OpenTabletDriver (OTD) integration - **Hidraw device passthrough** for pressure/tilt data -- Input device passthrough for basic tablet events +- Button mapping to keyboard shortcuts +- No OpenTabletDriver required! ✅ **Hardware Acceleration** - Automatic NVIDIA GPU detection and support @@ -24,7 +24,7 @@ A complete setup script to run Paintstorm Studio v2.50 in an Ubuntu 20.04 distro ✅ **Easy Management** - Desktop launcher integration - Management script for maintenance -- Diagnostic tools for troubleshooting +- Configuration-based button mapping ## Quick Start @@ -34,13 +34,12 @@ A complete setup script to run Paintstorm Studio v2.50 in an Ubuntu 20.04 distro # Install distrobox and podman sudo pacman -S distrobox podman -# Install OpenTabletDriver (for tablet support) -# Follow instructions at: https://opentabletdriver.net/ -# Then start it: -otd-daemon & -otd detect # Detect your tablet +# For button mapping (optional) +sudo pacman -S xbindkeys xdotool ``` +**Note**: OpenTabletDriver is NOT required and NOT recommended for Paintstorm. Native HID works better. + ### Installation 1. **Clone or download this repository** @@ -61,241 +60,136 @@ otd detect # Detect your tablet ## Tablet Pressure & Tilt Support -### Important for Tablet Users - -If you're using a graphics tablet with OpenTabletDriver, you **MUST** ensure hidraw devices are passed to the container for pressure and tilt to work. +### ✅ Using Native HID (RECOMMENDED) -### Quick Check +Native Linux HID drivers provide full pressure and tilt support without any configuration: ```bash -# Run the diagnostic script -./test-tablet-pressure.sh -``` - -This will check: -- ✅ OpenTabletDriver status -- ✅ Kernel driver blacklist -- ✅ Hidraw devices on host -- ✅ Hidraw devices in container -- ✅ Input device configuration - -### If Pressure/Tilt Doesn't Work - -See **[TABLET-PRESSURE-FIX.md](TABLET-PRESSURE-FIX.md)** for detailed troubleshooting guide. - -**TL;DR:** -1. Make sure OpenTabletDriver is running: `otd-daemon &` -2. Recreate the container with the latest script (it will pass hidraw devices) -3. Run diagnostic: `./test-tablet-pressure.sh` - -## What's Included - -### Scripts - -- **`paintstorm-install-distrobox.sh`** - Main installation orchestrator -- **`container-setup.sh`** - Container environment setup -- **`paintstorm-launcher.sh`** - Application launcher template -- **`paintstorm-manage.sh`** - Container management utilities -- **`test-tablet-pressure.sh`** - Tablet diagnostic tool - -### Generated Files - -- **`~/paintstorm`** - Launch wrapper (installed from paintstorm-launcher.sh) -- **`~/paintstorm-manage.sh`** - Management script (installed from repo) - -### Project Structure - -``` -paintstorm-distrobox-legacy/ -├── paintstorm-install-distrobox.sh # Main installer (run this) -├── container-setup.sh # Container environment configuration -├── paintstorm-launcher.sh # App launcher template -├── paintstorm-manage.sh # Management utilities -├── test-tablet-pressure.sh # Diagnostic tool -├── README.md # This file -└── TABLET-PRESSURE-FIX.md # Detailed troubleshooting guide +# Just launch Paintstorm - it works! +~/paintstorm ``` -All scripts are properly separated for maintainability. No more embedded HEREDOCs! - -### Container Contents - -- Ubuntu 20.04 base -- GLEW 1.13.0 (required for Paintstorm) -- X11 libraries and tools -- Input device libraries (xinput, evtest, etc.) -- Font packages (crash prevention) -- Paintstorm Studio v2.50 +**What you get:** +- ✅ Full pressure sensitivity (0-8191 levels) +- ✅ Tilt support (X/Y angles) +- ✅ Stable, reliable operation +- ✅ No mouse freezing issues +- ✅ Works every time -### Device Passthrough (v2.4) +### Configure Tablet Buttons -The script automatically detects and passes: -- `/dev/input/event*` - Input event devices -- `/dev/input/js*` - Joystick devices -- `/dev/input/*wacom*` - Wacom tablet devices -- `/dev/input/*tablet*` - Generic tablet devices -- **`/dev/hidraw*`** - Raw HID devices (pressure/tilt data) ← **NEW** -- X11 sockets and Xauthority -- NVIDIA GPU (if detected) - -## Management - -### Container Management +See **[native-hid-tablet-mapping/](native-hid-tablet-mapping/)** for button mapping tools. +**Quick setup:** ```bash -~/paintstorm-manage.sh -``` - -Options: -1. Export container (for backup/sharing) -2. Import container -3. Container info -4. **Test tablet input** (check device passthrough) -5. Fix tablet permissions -6. Exit +cd native-hid-tablet-mapping/ -### Troubleshooting +# Detect your buttons +./test-pen-buttons.sh +./test-tablet-keyboard-events.sh -#### Check Container Status -```bash -distrobox list -``` - -#### Enter Container Manually -```bash -distrobox enter paintstorm-legacy -``` - -#### Test Tablet in Container -```bash -distrobox enter paintstorm-legacy -- xinput list -distrobox enter paintstorm-legacy -- ls -la /dev/hidraw* -``` +# Configure mappings +nano tablet-button-config.conf -#### View Debug Output -```bash -~/paintstorm -# Check the debug output for device information -``` +# Apply configuration +./apply-button-mappings.sh -#### Full Diagnostic -```bash -./test-tablet-pressure.sh +# Make it persistent +./setup-autostart.sh ``` -## Known Issues & Solutions +### ❌ OpenTabletDriver NOT Recommended -### 1. Pressure/Tilt Not Working +Testing revealed OTD has unfixable issues with Paintstorm: +- Mouse freezes during drawing +- Pressure fails on second launch +- Device recognition problems -**Problem**: Tablet works but no pressure sensitivity or tilt +**If you want to troubleshoot OTD anyway**, see [otd-diagnostics/](otd-diagnostics/) (not recommended). -**Solution**: See [TABLET-PRESSURE-FIX.md](TABLET-PRESSURE-FIX.md) +## Quick Check -**Quick fix**: ```bash -# Make sure OTD is running -otd-daemon & - -# Recreate container with latest script -./paintstorm-install-distrobox.sh -# Answer 'y' to recreate - -# Verify hidraw passthrough +# Test pressure and tilt ./test-tablet-pressure.sh ``` -### 2. Font Crash on Startup - -**Solution**: Already fixed! The script creates empty font directories to prevent this crash. - -### 3. GLEW Library Error - -**Solution**: The script builds GLEW 1.13.0 from source and patches RPATH automatically. - -### 4. Permission Denied on /dev/hidraw* +This will verify: +- ✅ Hidraw devices on host +- ✅ Hidraw devices in container +- ✅ Input device configuration -**Solution**: -```bash -# Add user to input group -sudo usermod -a -G input $USER -# Logout/login to apply +## Project Structure -# Or temporarily fix -sudo chmod a+rw /dev/hidraw* +``` +paintstorm-distrobox-legacy/ +│ +├── README.md # This file +├── TABLET-PRESSURE-FIX.md # Detailed tablet troubleshooting +│ +├── paintstorm-install-distrobox.sh # Main installer +├── container-setup.sh # Container configuration +├── paintstorm-launcher.sh # App launcher template +├── paintstorm-manage.sh # Container management +├── test-tablet-pressure.sh # General tablet diagnostic +│ +├── native-hid-tablet-mapping/ # ✅ RECOMMENDED: Button mapping tools +│ ├── README.md # Setup guide +│ ├── tablet-button-config.conf # Your button mappings +│ ├── apply-button-mappings.sh # Apply configuration +│ ├── setup-autostart.sh # Make persistent +│ ├── test-pen-buttons.sh # Detect pen buttons +│ ├── test-tablet-keyboard-events.sh # Detect tablet buttons +│ └── detect-tablet-buttons.sh # Comprehensive detection +│ +└── otd-diagnostics/ # ❌ NOT RECOMMENDED: OTD troubleshooting + ├── README.md # Why OTD doesn't work + └── (various diagnostic scripts) # For debugging OTD issues ``` -### 5. Container Already Exists - -The script will detect existing containers and offer to recreate. This is **required** when updating device passthrough settings. - -## Technical Details - -### Why Distrobox? - -Paintstorm Studio v2.50 requires: -- Old GLEW version (1.13.0) -- Old library versions -- Specific font configuration - -Running in Ubuntu 20.04 container avoids conflicts with modern system libraries. - -### Why Hidraw Passthrough? +## Tested Configuration -OpenTabletDriver communicates directly with tablet hardware via `/dev/hidraw*` to: -- Read raw HID reports (pressure, tilt, buttons, battery) -- Bypass kernel drivers (wacom, hid_uclogic are blacklisted) -- Create virtual input device with processed data -- Support advanced features not in kernel drivers +- **Distribution**: Arch Linux +- **Tablet**: Huion G930L (works with other Huion tablets) +- **Drivers**: Native Linux HID (generic hid driver) +- **Container**: Ubuntu 20.04 (distrobox/podman) +- **Button Mapping**: xbindkeys + xdotool -Without hidraw passthrough, only basic pointer movement works. +## Known Issues & Solutions -### Device Architecture +### Pressure/Tilt Works Perfectly ✅ -``` -Tablet Hardware - ↓ -/dev/hidraw* (raw HID data) ← OpenTabletDriver reads here - ↓ -otd-daemon (processes data) - ↓ -Virtual Input Device (processed events) - ↓ -/dev/input/event* ← Applications read here - ↓ -Paintstorm Studio -``` +Native HID provides full pressure and tilt support out of the box. No configuration needed. -Both hidraw and event devices must be available in the container. +### Button Mapping -## System Requirements +Your Huion G930L has: +- **6 tablet buttons**: Already send keyboard shortcuts (Ctrl+Alt+Z, [, ], b, etc.) +- **2 pen buttons**: Can be mapped with xbindkeys -- Linux system with X11 (Wayland may work but untested) -- Distrobox installed -- Podman or Docker -- For tablets: OpenTabletDriver -- For NVIDIA: nvidia-container-toolkit (optional, auto-detected) +See `native-hid-tablet-mapping/README.md` for complete setup. -## Tested Configurations +### OpenTabletDriver Issues -- ✅ Arch Linux + Podman + OpenTabletDriver -- ✅ NVIDIA GPU with proprietary drivers -- ✅ X11 desktop environment -- ✅ Huion/Wacom/XP-Pen tablets (via OpenTabletDriver) +**Don't use OTD with Paintstorm.** See `otd-diagnostics/README.md` for details on why it doesn't work. ## Version History -### v2.4 (2026-01-23) - **CURRENT** +### v2.5 (2024-01-24) - **CURRENT** +- ✅ Reorganized into native HID (recommended) and OTD diagnostics (not recommended) +- ✅ Added configuration-based button mapping system +- ✅ Created comprehensive native HID setup guide +- ✅ Documented why OTD doesn't work with Paintstorm +- ✅ Cleaned up script organization + +### v2.4 (2024-01-23) - ✅ Added hidraw device detection and passthrough -- ✅ Created tablet diagnostic script -- ✅ Enhanced debug output for troubleshooting -- ✅ Updated management script with hidraw testing -- ✅ Improved error messages and user guidance -- ✅ **Fixed pressure sensitivity and tilt support** +- ✅ Created tablet diagnostic scripts +- ✅ Extensive OTD troubleshooting (determined OTD not viable) ### v2.3 - Pen tablet support with event device passthrough - X11 input libraries -- Debug output for tablet devices ### v2.0-2.2 - Initial distrobox implementation @@ -303,6 +197,16 @@ Both hidraw and event devices must be available in the container. - Font crash prevention - NVIDIA support +## Recommendation + +**For Huion tablets (and likely other brands):** + +1. ✅ **Use native HID** (no OTD) +2. ✅ **Configure buttons** with xbindkeys (see `native-hid-tablet-mapping/`) +3. ✅ **Enjoy full pressure and tilt** without any hassle + +This provides the best experience with Paintstorm in distrobox. + ## Contributing Found an issue? Have improvements? Please open an issue or pull request. @@ -315,16 +219,10 @@ This setup script is provided as-is for use with legally obtained copies of Pain - Paintstorm Studio by Sergey Kolesov - Distrobox by Luca Di Maio -- OpenTabletDriver by OpenTabletDriver Contributors - -## Support - -For issues specific to: -- **Paintstorm Studio**: Contact Paintstorm support -- **Distrobox**: See https://distrobox.it/ -- **OpenTabletDriver**: See https://opentabletdriver.net/ -- **This setup script**: Open an issue in this repository +- Native HID tablet support by Linux kernel developers --- **Happy painting! 🎨** + +**For tablet button setup, go to:** `native-hid-tablet-mapping/` @@ -0,0 +1,203 @@ +# Native HID Tablet Button Mapping + +**For Huion tablets using native Linux HID drivers (NO OpenTabletDriver required)** + +This folder contains tools to configure your Huion tablet buttons to keyboard shortcuts using the native Linux HID driver with xinput and xbindkeys. + +## ⚠️ Important: This is NOT for OpenTabletDriver + +**OpenTabletDriver does NOT work reliably** with Paintstorm in distrobox. Issues include: +- Mouse freezing during drawing +- Pressure stops working on second launch +- Device detection conflicts + +**This solution uses native Linux HID support instead**, which provides: +- ✅ Full pressure sensitivity (0-8191 levels) +- ✅ Tilt support +- ✅ Tablet button mapping to keyboard shortcuts +- ✅ Pen button mapping to keyboard shortcuts +- ✅ No mouse freezing +- ✅ Reliable, consistent behavior + +## Tested Configuration + +- **Distribution**: Arch Linux +- **Tablet**: Huion G930L (should work with other Huion tablets) +- **Drivers**: Native Linux HID (generic hid driver) +- **Kernel drivers blacklisted**: wacom, hid_uclogic (for OTD compatibility, but we don't use OTD) + +## Quick Start + +### 1. Detect Your Buttons + +First, find out what buttons your tablet and pen have: + +```bash +# Detect tablet buttons (usually 6 buttons) +./test-tablet-keyboard-events.sh + +# Detect pen buttons (usually 2 buttons on the side) +./test-pen-buttons.sh +``` + +**Note the button numbers and keycodes shown!** + +### 2. Configure Button Mappings + +Edit the configuration file: + +```bash +nano tablet-button-config.conf +``` + +Map each button to the keyboard shortcut you want. Examples are provided in the file. + +### 3. Apply the Mappings + +```bash +./apply-button-mappings.sh +``` + +This will: +- Read your configuration +- Set up xbindkeys with your mappings +- Start xbindkeys in the background + +### 4. Make it Persistent + +Add to your startup applications: + +```bash +./setup-autostart.sh +``` + +This creates an autostart entry so your button mappings load on every boot. + +## Your Huion G930L Configuration + +Based on testing, your tablet has: + +**Tablet Buttons (6 buttons)**: Already send keyboard events +- Button 1: `Ctrl+Alt+Z` +- Button 2: `Ctrl+KP_Subtract` (Keypad -) +- Button 3: `Ctrl+KP_Add` (Keypad +) +- Button 4: `[` (left bracket) +- Button 5: `]` (right bracket) +- Button 6: `b` + +You can remap these if you want different keys. + +**Pen Buttons (2 buttons)**: xinput buttons +- Button 2: Can be mapped to any keyboard shortcut +- Button 8 or 9: (second button - test to find the number) + +## Files in This Folder + +### Configuration & Setup +- **`tablet-button-config.conf`** - Your button mappings configuration +- **`apply-button-mappings.sh`** - Apply mappings from config file +- **`setup-autostart.sh`** - Make mappings persistent (autostart) + +### Detection & Testing +- **`test-tablet-keyboard-events.sh`** - Test tablet button events +- **`test-pen-buttons.sh`** - Test pen button events +- **`detect-tablet-buttons.sh`** - Comprehensive button detection + +### Legacy +- **`configure-tablet-buttons.sh`** - Old manual configuration (use config file instead) + +## How It Works + +### Tablet Buttons +Your Huion tablet exposes buttons as a keyboard device (id=24). When you press a tablet button, it sends a keyboard event (keycode). + +These can be: +1. Used as-is if you like the default mappings +2. Remapped with `xmodmap` to different keys +3. Remapped with `xbindkeys` to complex shortcuts + +### Pen Buttons +Pen buttons are xinput buttons (button 2, button 3, etc.). They can be remapped with: +- **xbindkeys** - Map to any keyboard shortcut or command +- **xsetwacom** - Only if xsetwacom works with Huion (test with `test-xsetwacom-compatibility.sh`) + +## Example Button Mappings + +```bash +# ~/.xbindkeysrc + +# Pen button 2 -> Ctrl+Z (undo) +"xdotool key ctrl+z" + b:2 + Release + +# Pen button 3 -> Ctrl+Shift+Z (redo) +"xdotool key ctrl+shift+z" + b:3 + Release + +# Remap tablet keycode 56 (currently 'b') to 'e' for eraser +"xdotool key e" + c:56 + Release +``` + +## Troubleshooting + +### Buttons not working +1. Make sure native devices are enabled (not using OTD): + ```bash + pkill otd-daemon + xinput enable 10 && xinput enable 11 + ``` + +2. Check if xbindkeys is running: + ```bash + pgrep xbindkeys + ``` + +3. Reload xbindkeys after config changes: + ```bash + killall xbindkeys && xbindkeys + ``` + +### Finding button numbers +- Run the detection scripts to see button numbers +- Press each button and note the output +- Tablet buttons show as keycodes +- Pen buttons show as button numbers + +### Dependencies +```bash +sudo pacman -S xbindkeys xdotool +``` + +## Why Not OpenTabletDriver? + +We tested OTD extensively and found: +- ❌ Mouse freezes during drawing (pointer grabbing conflict) +- ❌ Pressure stops working on second launch (device state issue) +- ❌ Requires disabling native devices which breaks on relaunch +- ❌ Complex configuration for minimal benefit + +Native HID provides everything needed: +- ✅ Pressure and tilt work perfectly +- ✅ Stable and reliable +- ✅ Button mapping with xbindkeys +- ✅ No special configuration required + +**Only use OTD if you need:** +- Custom pressure curves (native provides linear 0-8191) +- Very specific tablet area constraints +- OTD-specific features + +For button mapping and normal use, **native HID is superior**. + +## Credits + +Created for Paintstorm Studio distrobox setup. +Tested on Arch Linux with Huion G930L. + +## Support + +If you have issues: +1. Run the detection scripts +2. Check the main distrobox README +3. See `../otd-diagnostics/` if you really want to try OTD (not recommended) @@ -0,0 +1,175 @@ +#!/bin/bash +# Apply tablet button mappings from configuration file + +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +BOLD='\033[1m' +NC='\033[0m' + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +CONFIG_FILE="$SCRIPT_DIR/tablet-button-config.conf" +XBINDKEYS_RC="$HOME/.xbindkeysrc" + +echo "==========================================" +echo "Apply Tablet Button Mappings" +echo "==========================================" +echo "" + +# Check dependencies +MISSING_DEPS="" +if ! command -v xbindkeys &> /dev/null; then + MISSING_DEPS="$MISSING_DEPS xbindkeys" +fi +if ! command -v xdotool &> /dev/null; then + MISSING_DEPS="$MISSING_DEPS xdotool" +fi + +if [ -n "$MISSING_DEPS" ]; then + echo -e "${YELLOW}Missing dependencies:$MISSING_DEPS${NC}" + echo "" + echo "Install with:" + echo " sudo pacman -S$MISSING_DEPS" + echo "" + read -p "Install now? [y/N]: " install_deps + if [[ "$install_deps" =~ ^[Yy]$ ]]; then + sudo pacman -S$MISSING_DEPS + else + exit 1 + fi +fi + +# Check config file exists +if [ ! -f "$CONFIG_FILE" ]; then + echo -e "${RED}ERROR: Configuration file not found${NC}" + echo "Expected: $CONFIG_FILE" + exit 1 +fi + +echo "Reading configuration from:" +echo " $CONFIG_FILE" +echo "" + +# Backup existing xbindkeys config +if [ -f "$XBINDKEYS_RC" ]; then + BACKUP="$XBINDKEYS_RC.bak.$(date +%Y%m%d_%H%M%S)" + cp "$XBINDKEYS_RC" "$BACKUP" + echo -e "${YELLOW}Backed up existing config to:${NC}" + echo " $BACKUP" + echo "" +fi + +# Start building new xbindkeys config +cat > "$XBINDKEYS_RC" << 'HEADER' +# xbindkeys configuration for Huion tablet +# Generated by apply-button-mappings.sh +# DO NOT EDIT DIRECTLY - Edit tablet-button-config.conf instead + +HEADER + +# Parse config file and generate xbindkeys entries +MAPPED_COUNT=0 + +# Source the config file to get variables +source "$CONFIG_FILE" 2>/dev/null || true + +# Generate pen button mappings +if [ -n "$pen_button_2" ]; then + if [ -n "$pen_button_2_command" ]; then + echo "\"$pen_button_2_command\"" >> "$XBINDKEYS_RC" + else + echo "\"xdotool key $pen_button_2\"" >> "$XBINDKEYS_RC" + fi + echo " b:2 + Release" >> "$XBINDKEYS_RC" + echo "" >> "$XBINDKEYS_RC" + echo -e "${GREEN}✓ Mapped pen button 2 → $pen_button_2${NC}" + ((MAPPED_COUNT++)) +fi + +if [ -n "$pen_button_3" ]; then + if [ -n "$pen_button_3_command" ]; then + echo "\"$pen_button_3_command\"" >> "$XBINDKEYS_RC" + else + echo "\"xdotool key $pen_button_3\"" >> "$XBINDKEYS_RC" + fi + echo " b:3 + Release" >> "$XBINDKEYS_RC" + echo "" >> "$XBINDKEYS_RC" + echo -e "${GREEN}✓ Mapped pen button 3 → $pen_button_3${NC}" + ((MAPPED_COUNT++)) +fi + +# Generate tablet keycode mappings +for keycode in 34 35 37 52 56 64 82 86; do + var_name="tablet_keycode_${keycode}" + cmd_var_name="tablet_keycode_${keycode}_command" + + mapping="${!var_name}" + command="${!cmd_var_name}" + + if [ -n "$mapping" ]; then + if [ -n "$command" ]; then + echo "\"$command\"" >> "$XBINDKEYS_RC" + else + echo "\"xdotool key $mapping\"" >> "$XBINDKEYS_RC" + fi + echo " c:$keycode + Release" >> "$XBINDKEYS_RC" + echo "" >> "$XBINDKEYS_RC" + echo -e "${GREEN}✓ Mapped tablet keycode $keycode → $mapping${NC}" + ((MAPPED_COUNT++)) + fi +done + +echo "" +echo "==========================================" +echo "Configuration Summary" +echo "==========================================" +echo "" +echo "Total mappings applied: $MAPPED_COUNT" +echo "Configuration file: $XBINDKEYS_RC" +echo "" + +if [ "$MAPPED_COUNT" -eq 0 ]; then + echo -e "${YELLOW}⚠ No mappings found in config file${NC}" + echo "" + echo "Edit the configuration file to add mappings:" + echo " nano $CONFIG_FILE" + echo "" + echo "Then run this script again." + exit 0 +fi + +# Stop existing xbindkeys +if pgrep xbindkeys > /dev/null; then + echo "Stopping existing xbindkeys..." + killall xbindkeys + sleep 1 +fi + +# Start xbindkeys +echo "Starting xbindkeys..." +xbindkeys + +if pgrep xbindkeys > /dev/null; then + echo -e "${GREEN}✓ xbindkeys started successfully${NC}" + echo "" + echo "Your button mappings are now active!" + echo "" + echo "To test:" + echo " - Press your pen buttons" + echo " - Press your tablet buttons" + echo " - They should send the configured keyboard shortcuts" + echo "" + echo "To make this persistent across reboots:" + echo " ./setup-autostart.sh" +else + echo -e "${RED}✗ Failed to start xbindkeys${NC}" + echo "" + echo "Check for errors:" + echo " xbindkeys -v" +fi + +echo "" +echo "To reload after editing config:" +echo " ./apply-button-mappings.sh" +echo "" @@ -0,0 +1,83 @@ +#!/bin/bash +# Setup autostart for tablet button mappings + +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' + +AUTOSTART_DIR="$HOME/.config/autostart" +DESKTOP_FILE="$AUTOSTART_DIR/tablet-button-mappings.desktop" + +echo "==========================================" +echo "Setup Tablet Button Mapping Autostart" +echo "==========================================" +echo "" + +# Create autostart directory if it doesn't exist +mkdir -p "$AUTOSTART_DIR" + +# Create desktop entry +cat > "$DESKTOP_FILE" << 'EOF' +[Desktop Entry] +Type=Application +Name=Tablet Button Mappings +Comment=Apply Huion tablet button mappings with xbindkeys +Exec=xbindkeys +Terminal=false +Hidden=false +NoDisplay=false +X-GNOME-Autostart-enabled=true +StartupNotify=false +EOF + +if [ -f "$DESKTOP_FILE" ]; then + echo -e "${GREEN}✓ Created autostart entry${NC}" + echo " $DESKTOP_FILE" + echo "" + echo "xbindkeys will now start automatically on login." + echo "" + echo "Make sure ~/.xbindkeysrc is configured first:" + echo " ./apply-button-mappings.sh" + echo "" +else + echo -e "${RED}✗ Failed to create autostart entry${NC}" + exit 1 +fi + +echo "==========================================" +echo "Verification" +echo "==========================================" +echo "" + +if [ -f "$HOME/.xbindkeysrc" ]; then + echo -e "${GREEN}✓ xbindkeys configuration exists${NC}" + echo " ~/.xbindkeysrc" +else + echo -e "${YELLOW}⚠ No xbindkeys configuration found${NC}" + echo " Run: ./apply-button-mappings.sh" +fi + +echo "" + +if pgrep xbindkeys > /dev/null; then + echo -e "${GREEN}✓ xbindkeys is currently running${NC}" +else + echo -e "${YELLOW}⚠ xbindkeys is not running${NC}" + echo " Start it: xbindkeys" +fi + +echo "" +echo "==========================================" +echo "Testing" +echo "==========================================" +echo "" +echo "To test the autostart:" +echo " 1. Logout" +echo " 2. Login again" +echo " 3. Test your button mappings" +echo "" +echo "To disable autostart:" +echo " rm $DESKTOP_FILE" +echo "" @@ -0,0 +1,92 @@ +# Huion Tablet Button Configuration +# Edit this file to customize your button mappings + +# ============================================ +# PEN BUTTONS (xinput buttons) +# ============================================ +# Your Huion pen has 2 buttons on the side +# These are xinput button numbers (found by running test-pen-buttons.sh) + +# Pen button 2 -> Undo (Ctrl+Z) +pen_button_2="ctrl+z" + +# Pen button 3 -> Redo (Ctrl+Shift+Z) +# Uncomment this line if you have a second pen button +#pen_button_3="ctrl+shift+z" + +# More pen button examples: +#pen_button_2="e" # Switch to eraser +#pen_button_3="b" # Switch to brush +#pen_button_2="ctrl+s" # Save +#pen_button_3="bracketleft" # Decrease brush size + + +# ============================================ +# TABLET BUTTONS (keyboard events) +# ============================================ +# Your tablet buttons already send keyboard events (keycodes) +# Current mappings (found by running test-tablet-keyboard-events.sh): +# +# Keycode 37 + 64 + 52 = Ctrl+Alt+Z +# Keycode 37 + 82 = Ctrl+KP_Subtract +# Keycode 37 + 86 = Ctrl+KP_Add +# Keycode 34 = bracketleft [ +# Keycode 35 = bracketright ] +# Keycode 56 = b + +# To remap tablet buttons, uncomment and edit these lines: + +# Remap keycode 56 (currently 'b') to 'e' for eraser +#tablet_keycode_56="e" + +# Remap keycode 34 (currently '[') to Ctrl+S for save +#tablet_keycode_34="ctrl+s" + +# Remap keycode 35 (currently ']') to Ctrl+O for open +#tablet_keycode_35="ctrl+o" + +# More examples: +#tablet_keycode_56="space" # Space bar +#tablet_keycode_56="ctrl+shift+a" # Complex shortcut +#tablet_keycode_56="F5" # Function key + + +# ============================================ +# ADVANCED: Custom Commands +# ============================================ +# You can also run shell commands instead of keyboard shortcuts + +# Example: Pen button runs a script +#pen_button_2_command="/path/to/your/script.sh" + +# Example: Tablet button opens an application +#tablet_keycode_56_command="xdg-open ~/Pictures" + + +# ============================================ +# NOTES +# ============================================ +# +# Key names: +# - Use lowercase: a, b, c +# - Modifiers: ctrl, shift, alt, super +# - Special: space, Return, Escape, Tab, BackSpace +# - Function: F1, F2, F3, etc. +# - Brackets: bracketleft, bracketright +# - Keypad: KP_Add, KP_Subtract, KP_Multiply, etc. +# +# Multiple modifiers: +# ctrl+shift+s +# ctrl+alt+Delete +# +# Button numbers: +# Run test-pen-buttons.sh to find your pen button numbers +# Common: 2, 3, 8, 9 +# +# Keycodes: +# Run test-tablet-keyboard-events.sh to find tablet keycodes +# Your tablet: 34, 35, 37, 52, 56, 64, 82, 86 +# +# After editing this file, run: +# ./apply-button-mappings.sh +# @@ -0,0 +1,103 @@ +# OpenTabletDriver Diagnostics + +⚠️ **WARNING: OpenTabletDriver does NOT work reliably with Paintstorm in distrobox** + +This folder contains diagnostic tools for troubleshooting OpenTabletDriver (OTD) issues. These tools were created during extensive testing of OTD integration. + +## Why This Folder Exists + +We attempted to make OpenTabletDriver work with Paintstorm in the distrobox container. After extensive testing and debugging, we discovered **multiple unfixable issues**: + +### Issue 1: Mouse Freezing +**Symptom**: Mouse freezes while drawing with pen, unfreezes on Alt+Tab +**Cause**: X11 pointer grabbing conflict between OTD virtual device and mouse +**Scripts**: `diagnose-pointer-freeze.sh`, `fix-pointer-freeze.sh` + +### Issue 2: Second Launch Failure +**Symptom**: Pressure works on first launch, fails on second launch +**Cause**: Native devices get re-enabled between launches +**Scripts**: `test-paintstorm-relaunch-issue.sh`, `track-device-state-changes.sh` + +### Issue 3: Device Recognition +**Symptom**: Paintstorm doesn't recognize OTD virtual device for pressure +**Cause**: Paintstorm expects specific device names/types +**Scripts**: `check-which-device-used.sh`, `test-which-device-active.sh`, `test-pressure-data.sh` + +## Recommendation + +**Use native HID instead of OpenTabletDriver.** + +See `../native-hid-tablet-mapping/` for the working solution. + +Native HID provides: +- ✅ Full pressure sensitivity (0-8191 levels) +- ✅ Tilt support +- ✅ Button mapping with xbindkeys +- ✅ No mouse freezing +- ✅ No second-launch issues +- ✅ Reliable, stable operation + +## When to Use These Tools + +Only use these diagnostic tools if you: +1. Want to understand why OTD doesn't work +2. Are debugging OTD for other applications (not Paintstorm) +3. Need to document OTD issues for bug reports + +**For Paintstorm use, go to `../native-hid-tablet-mapping/` instead.** + +## Diagnostic Tools + +### Device Detection & Testing +- **`check-which-device-used.sh`** - Shows which device is active (native vs OTD virtual) +- **`test-which-device-active.sh`** - Alternative device activity test +- **`test-pressure-data.sh`** - Verify if OTD virtual device sends pressure data + +### Mouse/Pointer Issues +- **`diagnose-pointer-freeze.sh`** - Diagnose mouse freezing issues +- **`fix-pointer-freeze.sh`** - Interactive menu to fix pointer conflicts + +### Launch Issues +- **`test-paintstorm-relaunch-issue.sh`** - Test for second-launch failures +- **`track-device-state-changes.sh`** - Track xinput device state changes + +### Compatibility Testing +- **`test-xsetwacom-compatibility.sh`** - Test if xsetwacom works with Huion + +### Wrappers & Guides +- **`paintstorm-with-otd-wrapper.sh`** - Wrapper that ensures OTD config (doesn't fully fix issues) +- **`TABLET-INPUT-GUIDE.md`** - Complete technical guide to OTD vs native HID + +## The Bottom Line + +After creating all these diagnostic tools and testing extensively: + +**OpenTabletDriver is NOT recommended for Paintstorm in distrobox.** + +The issues are fundamental to how X11, distrobox, and Paintstorm interact with input devices. No amount of configuration or scripting fully resolves them. + +**Use native HID** for a superior, hassle-free experience. + +## Technical Summary + +### Why OTD Fails + +1. **Device Grabbing**: OTD takes exclusive hidraw access, making native devices appear active but with no data +2. **Application Recognition**: Paintstorm doesn't recognize OTD virtual devices as pressure-capable +3. **State Persistence**: Device enable/disable states don't persist correctly across application launches +4. **Pointer Conflicts**: X11 master pointer can't properly handle both mouse and OTD virtual device + +### Why Native HID Works + +1. **Direct HID Support**: Generic Linux HID driver provides full pressure and tilt +2. **No Virtualization**: Applications see real hardware devices +3. **Stable State**: No device swapping or enable/disable needed +4. **Standard Protocol**: Uses standard X11 XInput2 protocol + +## Credits + +These diagnostics were created during an extensive effort to make OTD work with Paintstorm. While the effort was ultimately unsuccessful for this use case, the tools may be useful for understanding OTD behavior in other contexts. + +**For actual tablet usage with Paintstorm: Use native HID.** + +See: `../native-hid-tablet-mapping/`