From 74efb5e3dea650221f5814afff64228d251ea9be Mon Sep 17 00:00:00 2001 From: Sebastian 'gonX' Jensen Date: Mon, 18 Aug 2025 23:11:02 +0200 Subject: [PATCH 1/5] Documentation: Add 'Known Bugs' WIP --- site/_wiki/Documentation/KnownBugs.md | 81 +++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 site/_wiki/Documentation/KnownBugs.md diff --git a/site/_wiki/Documentation/KnownBugs.md b/site/_wiki/Documentation/KnownBugs.md new file mode 100644 index 00000000..af492d72 --- /dev/null +++ b/site/_wiki/Documentation/KnownBugs.md @@ -0,0 +1,81 @@ +--- +title: Known Bugs +--- + +## Introduction {#introduction} + +OpenTabletDriver still has some fundamental and sometimes hard to fix bugs. +This page tries to document the bigger ones. + +The `0.6.x` branch is based on the GUI framework Eto, and the `avalonia` +branch, which will eventually be migrated into `master`, is based on the GUI +framework Avalonia. + +Many of these bugs have a planned milestone to be fixed in. + +## Bugs caused by Eto {#eto-bugs} + +### [#1821 - Multikey bindings doesn't respect keyboard layout](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/1821) {#multikey-binding-keyboard-layout} + +For non-QWERTY users (e.g. AZERTY), you may experience that keyboard bindings +are read correctly in the GUI, but sent as a QWERTY keycode by the daemon. + +Eto only allows us to read the processed keyboard layout. + +This is planned to be fixed with the migration to Avalonia. + +There are 2 known workarounds: + +#### Workaround 1: Temporarily Use QWERTY when setting up keys {#multikey-binding-keyboard-layout-workaround1} + +- Change your keyboard layout to QWERTY +- Set up the bindings you want to use, clicking your normal keys +- Change your keyboard layout back to the one you want to use + +#### Workaround 2: Force Virtual Keyboard to use U.S. English layout (Linux only) {#multikey-binding-keyboard-layout-workaround2} + +Keyboard Layouts are system-wide on Windows on MacOS. + +##### Sway window manager + +Put this _after_ any other keyboard configuration: + +```conf +input '0:0:OpenTabletDriver_Virtual_Keyboard' { + xkb_layout us +} +``` + +##### X11 Window Manager + +TODO + +## Assorted Bugs {#general-bugs} + +### [#3834 - Eraser behavior may be spotty on Linux](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/3834) +### [#3804 - Daemon IPC is not multi-user friendly](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/3804) +### [#3515 - Tablet firmware version featureset variations are difficult to detect](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/3515) +### [#3266 - Flatpak release does not install udev rules or kernel module blacklist](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/3266) +### [#3179 - Setup Wizard will constantly pop up as long as user never saves a config](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/3179) +### [#3171 - Some tablets may not work coming out of systemd sleep/suspend](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/3171) +### [#2964 - (Linux only?) Monitor layouts with negative offsets may confuse GUI quick-settings](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/2964) +### [#2955 - Disconnecting tablets mid-event (e.g. button press) may cause the button to remain pressed](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/2957) +### [#2536 - CLI is unmaintained](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/2536) + +Also [#1952 - Command `setoutputmode` not working](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/1952) + +### [#2510 - Bindings do not accomodate select output mode / Mouse buttons not working in Windows Ink or Artist Mode](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/2510) +### [#2106](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/2106)/[#1855](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/1855) (Linux/MacOS only) Daemon may misbehave if stdout is lost +### [#1666 - Similar tablets are not separately addressible](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/1666) +### [#1143 - Monitor layout changes are not detected and require a daemon restart](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/1143) +### [#1071 - Output may be up to 1 pixel off intended pixel on some configurations](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/1071) + +## Niche bugs (for plugin developers or similar) {#niche-bugs} + +### [#3830 - External daemon-interacting applications may desynchronize settings shown in GUI](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/3830) + +## Feature Requests + +Instead of listing all planned features (which would be a lot of work), look +for issues with the `enhancement` tag and looking at issues with a set milestone: +[example search](https://github.com/OpenTabletDriver/OpenTabletDriver/issues?q=is%3Aissue%20state%3Aopen%20label%3Aenhancement%20has%3Amilestone) From 3b60d5d2575b9b8aa923f80b047e220fc8b5fbc9 Mon Sep 17 00:00:00 2001 From: Sebastian 'gonX' Jensen Date: Mon, 27 Apr 2026 15:04:33 +0200 Subject: [PATCH 2/5] wiki/Doc/KnownBugs: Clean up 'multikey bindings' section --- site/_wiki/Documentation/KnownBugs.md | 48 +++++++++++++++++++-------- 1 file changed, 35 insertions(+), 13 deletions(-) diff --git a/site/_wiki/Documentation/KnownBugs.md b/site/_wiki/Documentation/KnownBugs.md index af492d72..bad4f731 100644 --- a/site/_wiki/Documentation/KnownBugs.md +++ b/site/_wiki/Documentation/KnownBugs.md @@ -15,7 +15,7 @@ Many of these bugs have a planned milestone to be fixed in. ## Bugs caused by Eto {#eto-bugs} -### [#1821 - Multikey bindings doesn't respect keyboard layout](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/1821) {#multikey-binding-keyboard-layout} +### Multikey bindings doesn't respect keyboard layout {#multikey-binding-keyboard-layout} For non-QWERTY users (e.g. AZERTY), you may experience that keyboard bindings are read correctly in the GUI, but sent as a QWERTY keycode by the daemon. @@ -24,19 +24,45 @@ Eto only allows us to read the processed keyboard layout. This is planned to be fixed with the migration to Avalonia. -There are 2 known workarounds: +See [OpenTabletDriver issue #1821](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/1821) for more details. -#### Workaround 1: Temporarily Use QWERTY when setting up keys {#multikey-binding-keyboard-layout-workaround1} +How to work around this depends on your operating system: -- Change your keyboard layout to QWERTY -- Set up the bindings you want to use, clicking your normal keys -- Change your keyboard layout back to the one you want to use +#### System-wide keyboard layout: Temporarily use U.S. English layout when setting up keys {#multikey-binding-keyboard-layout-system-wide-layouts} -#### Workaround 2: Force Virtual Keyboard to use U.S. English layout (Linux only) {#multikey-binding-keyboard-layout-workaround2} +Suitable for: -Keyboard Layouts are system-wide on Windows on MacOS. +- Windows +- macOS +- Linux users with system-wide keyboard layouts (some X11 setups) -##### Sway window manager +How to apply the workaround: + +1. Change your keyboard layout to QWERTY +2. Set up the bindings you want to use, clicking your normal keys +3. Change your keyboard layout back to the one you want to use + +This way, operating systems with system-wide keyboard layouts will emit the +intended keys, despite the resulting button possibly seeming incorrect. + +#### Per-keyboard layout: Force Virtual Keyboard to use U.S. English layout {#multikey-binding-keyboard-layout-linux-per-keyboard-layouts} + +**This section normally only applies to Linux users** + +How to do this depends on your software stack: + +- Wayland-based stacks must configure this in their Desktop Environment's (KDE/Gnome/sway/etc) settings +- X11-based display stacks must change X11 `xorg.conf` settings (see `man 5 xorg.conf`), or use `setxkbmap` during runtime. + +##### X11 {#multikey-binding-keyboard-layout-linux-X11} + +Unless you're using special configuration (`setxkbmap -device ` / udev rule `ENV{XKBLAYOUT}` / similar), chances are you're using a system-wide keyboard layout. + +In that case, follow the workaround presented for [Windows/macOS](#multikey-binding-keyboard-layout-win-macos) users. + +If it turns out that this doesn't work anyway, make sure the virtual keyboard from OpenTabletDriver is assigned the US-American layout. + +##### Sway window manager {#multikey-binding-keyboard-layout-linux-sway} Put this _after_ any other keyboard configuration: @@ -46,10 +72,6 @@ input '0:0:OpenTabletDriver_Virtual_Keyboard' { } ``` -##### X11 Window Manager - -TODO - ## Assorted Bugs {#general-bugs} ### [#3834 - Eraser behavior may be spotty on Linux](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/3834) From 8b506205d6f18c928396b7f654f8c77ef66d257a Mon Sep 17 00:00:00 2001 From: Sebastian 'gonX' Jensen Date: Mon, 27 Apr 2026 15:05:02 +0200 Subject: [PATCH 3/5] wiki/Doc/KnownBugs: Specify Eto bugs are GUI-only --- site/_wiki/Documentation/KnownBugs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/_wiki/Documentation/KnownBugs.md b/site/_wiki/Documentation/KnownBugs.md index bad4f731..68973d74 100644 --- a/site/_wiki/Documentation/KnownBugs.md +++ b/site/_wiki/Documentation/KnownBugs.md @@ -13,7 +13,7 @@ framework Avalonia. Many of these bugs have a planned milestone to be fixed in. -## Bugs caused by Eto {#eto-bugs} +## Bugs in GUI caused by Eto {#eto-bugs} ### Multikey bindings doesn't respect keyboard layout {#multikey-binding-keyboard-layout} From 798dc1052092e0359119d801194f1aaf7cca7522 Mon Sep 17 00:00:00 2001 From: Sebastian 'gonX' Jensen Date: Mon, 27 Apr 2026 16:07:56 +0200 Subject: [PATCH 4/5] wiki/Doc/KnownBugs: Finalize - Simplify sections - Finalize detailing workarounds - Finalize annotating the issue at hand - Finalize titles --- site/_wiki/Documentation/KnownBugs.md | 115 ++++++++++++++++++++------ 1 file changed, 88 insertions(+), 27 deletions(-) diff --git a/site/_wiki/Documentation/KnownBugs.md b/site/_wiki/Documentation/KnownBugs.md index 68973d74..d24c3c16 100644 --- a/site/_wiki/Documentation/KnownBugs.md +++ b/site/_wiki/Documentation/KnownBugs.md @@ -13,7 +13,33 @@ framework Avalonia. Many of these bugs have a planned milestone to be fixed in. -## Bugs in GUI caused by Eto {#eto-bugs} +## Notable OpenTabletDriver bugs {#notable-bugs} + +These bugs are likely to affect a sizable portion of users + +### Monitor layout changes are not automatically detected {#monitor-layout-changes-not-detected} + +If you change your monitor layout (such as resolution, position, rotation, or +similar) in your system settings, you need to restart the OpenTabletDriver +daemon completely. + +See [OpenTabletDriver issue #1143](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/1143) +for more details. + +### Bindings do not accomodate select output mode (Mouse buttons not working in Windows Ink or Linux Artist Mode) {#eto-keyboard-reading-is-weird} + +While Adaptive Bindings try to solve this issue, users using specific bindings +(e.g. Mouse Button Binding on Windows Ink/Linux Artist Mode) will find that +their bindings are not working. + +To help users diagnose this, OpenTabletDriver v0.6.7 logs an error when using +(built-in) bindings with unsupported output modes. + +The primary cause for this is that the output modes are restricted from +outputting these events to the operating system. + +See [OpenTabletDriver issue #2078](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/2078) +for more details. ### Multikey bindings doesn't respect keyboard layout {#multikey-binding-keyboard-layout} @@ -24,7 +50,8 @@ Eto only allows us to read the processed keyboard layout. This is planned to be fixed with the migration to Avalonia. -See [OpenTabletDriver issue #1821](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/1821) for more details. +See [OpenTabletDriver issue #1821](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/1821) +for more details. How to work around this depends on your operating system: @@ -56,11 +83,15 @@ How to do this depends on your software stack: ##### X11 {#multikey-binding-keyboard-layout-linux-X11} -Unless you're using special configuration (`setxkbmap -device ` / udev rule `ENV{XKBLAYOUT}` / similar), chances are you're using a system-wide keyboard layout. +Unless you're using special configuration (`setxkbmap -device ` / udev rule +`ENV{XKBLAYOUT}` / similar), chances are you're using a system-wide keyboard +layout. -In that case, follow the workaround presented for [Windows/macOS](#multikey-binding-keyboard-layout-win-macos) users. +In that case, follow the workaround presented for +[System-wide keyboard layout](#multikey-binding-keyboard-layout-system-wide-layouts) users. -If it turns out that this doesn't work anyway, make sure the virtual keyboard from OpenTabletDriver is assigned the US-American layout. +If it turns out that this doesn't work anyway, make sure the virtual keyboard +from OpenTabletDriver is assigned the US-American layout. ##### Sway window manager {#multikey-binding-keyboard-layout-linux-sway} @@ -72,32 +103,62 @@ input '0:0:OpenTabletDriver_Virtual_Keyboard' { } ``` -## Assorted Bugs {#general-bugs} +### Some tablets may not work coming out of system sleep/suspend {#sleep-wakeup-is-inconsistent} + +Replugging the device always fixes this. + +See [OpenTabletDriver issue #3171](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/3171) +for more details. + +### Disconnecting tablets mid-event (e.g. button press) causes the event to remain held (button permanently pressed) {#disconnected-tablets-do-not-reset-pipeline} + +The only known workaround is to restart the daemon or send the same type of +event again (e.g. from the reconnected or another device) + +See [OpenTabletDriver issue #2955](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/2957) +for more details. + +### (Linux) Flatpak release does not install udev rules or kernel module blacklist {#flatpak-missing-permissions} + +This means that the Flatpak release may show no tablets detected, caused by +missing permissions or conflicting drivers. + +Follow the instructions from the description of the Flatpak package to set these up properly. + +See [OpenTabletDriver issue #3266](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/3266) +for more details. + +## Assorted OpenTabletDriver Bugs {#general-bugs} + +These bugs are unlikely to be encountered by users, but have been seen in the wild + +### Similar tablets are not separately addressible {#single-tablet-per-tablet-model} + +This means if you have tablets of the same model then only the first iterated +matching device will work. + +There is no known workaround. The driver is fundamentally not prepared for +multiple models of the same device. + +See [OpenTabletDriver issue #1666](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/1666) +for more details. + +### Output may be up to 1 pixel off intended pixel on some configurations {#output-one-pixel-off} -### [#3834 - Eraser behavior may be spotty on Linux](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/3834) -### [#3804 - Daemon IPC is not multi-user friendly](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/3804) -### [#3515 - Tablet firmware version featureset variations are difficult to detect](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/3515) -### [#3266 - Flatpak release does not install udev rules or kernel module blacklist](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/3266) -### [#3179 - Setup Wizard will constantly pop up as long as user never saves a config](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/3179) -### [#3171 - Some tablets may not work coming out of systemd sleep/suspend](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/3171) -### [#2964 - (Linux only?) Monitor layouts with negative offsets may confuse GUI quick-settings](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/2964) -### [#2955 - Disconnecting tablets mid-event (e.g. button press) may cause the button to remain pressed](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/2957) -### [#2536 - CLI is unmaintained](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/2536) +This is practically speaking not noticeable and as such is not prioritized at all. +It is unclear which setups are affected. -Also [#1952 - Command `setoutputmode` not working](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/1952) +See [OpenTabletDriver issue #1071](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/1071) +for more details. -### [#2510 - Bindings do not accomodate select output mode / Mouse buttons not working in Windows Ink or Artist Mode](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/2510) -### [#2106](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/2106)/[#1855](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/1855) (Linux/MacOS only) Daemon may misbehave if stdout is lost -### [#1666 - Similar tablets are not separately addressible](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/1666) -### [#1143 - Monitor layout changes are not detected and require a daemon restart](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/1143) -### [#1071 - Output may be up to 1 pixel off intended pixel on some configurations](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/1071) +## Niche bugs {#niche-bugs} -## Niche bugs (for plugin developers or similar) {#niche-bugs} +These bugs are unlikely to affect any users at all aside from esoteric or unsupported setups -### [#3830 - External daemon-interacting applications may desynchronize settings shown in GUI](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/3830) +### Daemon and GUI may misbehave if daemon's stdout is lost {#stdout-required} -## Feature Requests +Backgrounding the daemon without sending its output to a valid file (or pipe) +is not supported yet. -Instead of listing all planned features (which would be a lot of work), look -for issues with the `enhancement` tag and looking at issues with a set milestone: -[example search](https://github.com/OpenTabletDriver/OpenTabletDriver/issues?q=is%3Aissue%20state%3Aopen%20label%3Aenhancement%20has%3Amilestone) +See OpenTabletDriver issues [#2106](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/2106) +and [#1855](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/1855) for more details From 471582233ea5cf5bcd138f05d1b8d7d4cd04ee21 Mon Sep 17 00:00:00 2001 From: Sebastian 'gonX' Jensen Date: Mon, 27 Apr 2026 17:25:53 +0200 Subject: [PATCH 5/5] (minor) satisfy linter --- site/_wiki/Documentation/KnownBugs.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/site/_wiki/Documentation/KnownBugs.md b/site/_wiki/Documentation/KnownBugs.md index d24c3c16..d2b5cd6f 100644 --- a/site/_wiki/Documentation/KnownBugs.md +++ b/site/_wiki/Documentation/KnownBugs.md @@ -74,7 +74,7 @@ intended keys, despite the resulting button possibly seeming incorrect. #### Per-keyboard layout: Force Virtual Keyboard to use U.S. English layout {#multikey-binding-keyboard-layout-linux-per-keyboard-layouts} -**This section normally only applies to Linux users** +> **Note:** This section normally only applies to Linux users How to do this depends on your software stack: @@ -95,7 +95,7 @@ from OpenTabletDriver is assigned the US-American layout. ##### Sway window manager {#multikey-binding-keyboard-layout-linux-sway} -Put this _after_ any other keyboard configuration: +Put this *after* any other keyboard configuration: ```conf input '0:0:OpenTabletDriver_Virtual_Keyboard' {