Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve Linux FAQ structuring #2

Merged
merged 2 commits into from
Oct 26, 2023
Merged

Improve Linux FAQ structuring #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3173fc2
Simplify styling
X9VoiD Oct 26, 2023
364501f
Improve Linux FAQ structuring
X9VoiD Oct 26, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions OpenTabletDriver.Web/Views/Wiki/Development/AddingTabletSupport.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
title: Adding Tablet Support
---

#### WIP
23 changes: 23 additions & 0 deletions OpenTabletDriver.Web/Views/Wiki/Documentation/Logs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
---
title: Logs
---

### GUI

To view logs, click on the `Console` tab. Optionally, change filter from `Information` to `Debug` for more detailed logs.

To export logs, click `Help` -> `Export diagnostics...` in the top menu bar.

Sometimes OpenTabletDriver crashes hard. This is usually caused by a bug in OpenTabletDriver. Due to the crash, it will be impossible to retrieve the logs from GUI. In this case, you can find a partial log in the following locations:

| OS | Location |
| --- | --- |
| Windows | `%appdata%\OpenTabletDriver\daemon.txt` |
| Linux | `~/.local/share/OpenTabletDriver/daemon.txt` |
| macOS | `~/Library/Application Support/OpenTabletDriver/daemon.txt` |

### Daemon

The output from daemon is the log.

On Linux when running daemon via systemd service, the log for daemon is recorded by systemd. To view the log, run `journalctl -u opentabletdriver.service`.
51 changes: 51 additions & 0 deletions OpenTabletDriver.Web/Views/Wiki/Documentation/UdevRules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
---
title: Udev Rules
---

Make sure that the installed OpenTabletDriver version is at least **0.6.3.0**. If still not working even with the latest version, refer to the instructions below depending on if you installed OpenTabletDriver via:

- [Package manager](#package-manager)
- [Built from source](#built-from-source)

### Package manager

#### Standard FHS distro

Run the following script in bash as root:

```bash
echo "Finding old udev rules..."
for c in /etc/udev/rules.d/9{0,9}-opentabletdriver.rules; do
if [ -f "${c}" ]; then
echo "Deleting ${c}"
rm "${c}"
fi
done

echo "Finding old kernel blacklist rules..."
if [ -f /etc/modprobe.d/blacklist.conf ]; then
echo "Deleting /etc/modprobe.d/blacklist.conf"
rm /etc/modprobe.d/blacklist.conf
done

udevadm control --reload-rules && udevadm trigger
```

> This script cleans up obsolete udev rules and reloads udev.

Then update the initramfs:

| Distro | Command |
| --- | --- |
| Arch Linux | `sudo mkinitcpio -P` |
| Debian/Ubuntu | `sudo update-initramfs -u` |

For other distros, refer to your distro's documentation on how to update the initramfs.

#### Non-standard FHS distro

Refer to your distro's documentation on how to remove udev rules of the name `90-opentabletdriver.rules` or `99-opentabletdriver.rules`.

### Built from source

Make sure you built OpenTabletDriver via [these instructions](https://github.com/OpenTabletDriver/OpenTabletDriver#linux) and extracted the generic binary tarball correctly.
232 changes: 79 additions & 153 deletions OpenTabletDriver.Web/Views/Wiki/FAQ/Linux.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,229 +2,156 @@
title: "Linux FAQ"
---

### My tablet is not detected? {#tablet-not-detected}
### My tablet is not detected?

For sanity reasons, make sure that your tablet is actually plugged in to your computer, and is detected by your OS.
#### Tablet Connection

You can check this with `lsusb` or a GUI utility. `dmesg` may also be handy to inspect USB plug or unplug events
Make sure that the tablet is actually plugged in to your computer properly. Check this by running `lsusb` in a terminal or by watching the output of `dmesg` or `udevadm monitor` when plugging in the tablet.

Once you are 100% sure your tablet is connected to your computer, and your kernel is seeing it,
ensure that your specific tablet make and model is supported by checking our list of supported tablets [here](/Tablets).
OpenTabletDriver currently has _no support_ for tablets connected via Bluetooth. Make sure that your tablet is connected via USB. There is partial support for tablets connected via wireless dongle.

If you plugged in your tablet _before_ installing OpenTabletDriver, please replug your tablet, otherwise detection might be impaired.
Once the tablet is connected properly, verify if your tablet is in the list of supported tablets [here](/Tablets). If it is not, you may do one of the following:

We currently do not support tablets that connect directly to a computer via Bluetooth,
and there is only limited support for tablets that use wireless USB receivers, so please make sure your tablet is connected via cable.
- [Create a tablet support request in Github.](https://github.com/OpenTabletDriver/OpenTabletDriver/issues/new?assignees=&labels=configuration&projects=&template=tablet_configuration.yml&title=Add+support+for+)
- [Create a tablet support thread in #config-creation channel of the Discord server.](/Discord)
- [Make your own tablet configuration.](/Wiki/Development/AddingTabletSupport)

If you installed OpenTabletDriver with a package manager, and replugging the tablet does not help, you might need to reboot your computer.
#### Troubleshooting

Please reboot before attempting the solutions below to avoid misconfiguration.
If your tablet is connected properly and is supported, but is still not detected, [check logs](/Wiki/Documentation/Logs) for any errors or warnings. If you find any, try finding for a match and its accompanying solution below:

#### It is a supported tablet, but still doesn't detect after a reboot?
##### UCLogic kernel module is loaded {#hid_uclogic}

Look for a log that resembles the following:
_Symptoms_

<small class="text-muted">Hint: You can see the console log under the "Console" tab in OpenTabletDriver.UX. You will better find problems when you
Switch from `Info` to `Debug` mode in the bottom left of the Console panel.
</small>

##### hid_uclogic kernel module interference {#hid_uclogic}

> Another tablet driver found: UC Logic\
> ArgumentOutOfRangeException Value range is [0, 15]. (Parameter 'value')

These errors may happen if the `hid_uclogic` kernel module is loaded at the same time as OpenTabletDriver.

You can remove and blacklist this module to stop it from loading in the future by running the following commands:
```bash
echo "blacklist hid_uclogic" | sudo tee -a /etc/modprobe.d/blacklist.conf
sudo rmmod hid_uclogic
```
Another tablet driver found: UC Logic
```

##### Missing udev rules {#udev}

> Not permitted to open HID class device at /dev/hidrawX
```
ArgumentOutOfRangeException: Value range is [0, 15]. (Parameter 'value)
```

If you have followed the previous instructions, usually this is the only reason OpenTabletDriver will fail to detect your tablet when it's supported.
[_Solution_](/Wiki/Documentation/UdevRules)

This issue can be resolved by ensuring that you have proper udev rules configured.
##### Insufficient permissions {#udev}

###### From Package Manager
_Symptoms_

If you installed OpenTabletDriver via your package manager, you may just need to reload and trigger the rules:
```bash
sudo udevadm control --reload-rules
sudo udevadm trigger
```
Not permitted to open HID class device at /dev/hidrawX
```

If it still doesn't work after this point, and you installed OpenTabletDriver with a package manager, please reboot, some systems may require this.

###### Portable install
[_Solution_](/Wiki/Documentation/UdevRules)

If you installed OpenTabletDriver without using a package manager you will not have proper udev rules set up and must build your own.
It is highly recommended that you use your package manager where available.
#### Tablet-specific Troubleshooting

This process will require you to have the dotnet 7 SDK installed before proceeding:
```bash
# Clone the repository, change current directory to the repository
git clone https://github.com/OpenTabletDriver/OpenTabletDriver.git
cd ./OpenTabletDriver
##### CTL-x100

# Generate rules, moves them to the udev rules directory
./generate-rules.sh
sudo mv ./bin/99-opentabletdriver.rules /etc/udev/rules.d/99-opentabletdriver.rules
It is possible for CTL-x100 tablets to boot in Android mode (the mode they use when interfacing with android devices like phones) instead of PC mode in some rare cases. To fix this, press
the outer 2 express keys for 3-4 seconds until the LEDs change brightness. This toggles the tablet's operating mode
between PC (high LED brightness) and Android mode (low LED brightness).

# Reload udev rules
sudo udevadm control --reload-rules
> Note: If you are sure your tablet is in PC mode, please follow the general instructions [here](#my-tablet-is-not-detected).

# Clean up leftovers
cd ..
rm -rf OpenTabletDriver
```
Then restart OpenTabletDriver and replug your tablet.
### Tablet is detected but not working?

#### My tablet is not supported, what can I do about that?
#### Fresh Install {#fail-virtual-device}

If you want to add support for your tablet on your own, feel free to look at a similar configuration on our GitHub and our configuration documentation.
If this is a fresh install and you have not configured your tablet yet, [check logs](/Wiki/Documentation/Logs) for any errors or warnings. If you find any, try finding for a match and its accompanying solution below:

If you would like help with supporting your tablet, or would prefer us to do it, join our [Discord](/Discord) and create a post in `#config-creation` or a support channel.
##### Missing uinput device

### My cursor is teleporting? {#ghost-cursor}
_Symptoms_

This occurs when another program is reading the tablet at the same time as OpenTabletDriver, if this is happening everywhere on the system,
the solution to this is very simple:
```bash
echo "blacklist wacom" | sudo tee -a /etc/modprobe.d/blacklist.conf
sudo rmmod wacom
```
If you are using a Wayland compositor, it may be required for you to use artist mode to pass the tablet to the driver as a virtual tablet, rather than an absolute mouse - certain applications like SDL and XWayland may incorrectly handle the cursor otherwise.
This is a rather simple config change, which can be found <a href="#artist-mode">here</a>.
Failed to initialize virtual tablet. (error code ENODEV)
```

### I blacklisted kernel modules, but they load on startup? {#blacklisted-modules-loading}
_Solution_

This issue can be caused by either your initramfs not containing the instructions to not load the modules
or another crucial service loading the module despite it being blacklisted. You will have to find that service
yourself if the solution below does not solve your issue.
Reboot your computer.

Rebuilding the initramfs is an easy process, but the commands to do this can vary between distributions of linux.
##### Missing uinput device support

#### Arch
_Symptoms_

```bash
sudo mkinitcpio -P
```

#### Debian / Ubuntu
```bash
sudo update-initramfs -u
Failed to initialize virtual tablet. (error code ENOENT)
```

### My tablet detects, but it isn't working? {#fail-virtual-device}

If this is on a fresh install of OpenTabletDriver, usually problems like this can be solved
simply by restarting your computer. If it isn't resolved you may try resetting your OpenTabletDriver
settings to the defaults with `File > Reset to defaults`, then pressing save.

If your issue is still not resolved, and you are using OpenTabletDriver.UX, navigate to the "Console" tab
at the top of the main interface, switch from `Info` to `Debug` in the bottom left of that window and you will be see every log message.
If you are using the daemon directly, simply look for a log entry
that resembles the following:

#### EACCESS

> Failed to initialize virtual tablet. (error code EACCES)
_Solution_

This usually occurs when udev is improperly set up or hasn't explictly been reloaded.
Make sure that your kernel has uinput support. If you are using a custom kernel or builds kernel from source, make sure that you have enabled `CONFIG_INPUT_UINPUT` in your kernel configuration. Refer to your distro's documentation regarding kernel configuration.

Make sure your rules are correct by heading [here](#udev).
##### Missing uinput device permissions

#### ENODEV
_Symptoms_

> Failed to initialize virtual tablet. (error code ENODEV)

This error occurs after updating the kernel but without rebooting, you should reboot your computer
and check if the problem is resolved.

#### ENOENT
This error occurs when the `CONFIG_INPUT_UINPUT` kernel option is disabled. Make sure it is enabled in
your kernel config.

##### Gentoo
Check the option `CONFIG_INPUT_UINPUT` in /usr/src/linux.config. If it is not enabled, use the following steps

```bash
cd /usr/src/linux
sudo make menuconfig
```
Failed to initialize virtual tablet. (error code EACCES)
```

Having done that, select y (for always active) or m (for building as a module) for the option in
*Device Drivers ---> Input Device Support ---> Miscellaneous devices ---> User level driver support* and rebuild the kernel.

##### Other Distros

Refer to your distribution's documentation regarding kernel configuration to enable this option.

This is probably due to your kernel not having uinput built in, if `stat /dev/uinput` doesn't return a file and you are using a custom kernel,
compile your kernel with support for uinput or use a different kernel.
[_Solution_](/Wiki/Documentation/UdevRules)

### Poor performance with NVIDIA {#performance-nvidia}
#### Non-fresh Install

Disable "Force full composition pipeline" in the NVIDIA settings panel.
Try disabling your filters one-by-one and see if input finally works.

### Stuck cursor in osu!lazer (Wayland) {#osu-lazer-broken-input-wayland}
### My cursor is stuck in osu!lazer (Wayland) {#osu-lazer-broken-input-wayland}

Make sure you set the `SDL_VIDEODRIVER` to `wayland`:
Make sure you set the `SDL_VIDEODRIVER` to `wayland`. Some examples:

```bash
env SDL_VIDEODRIVER=wayland ./osu.AppImage
```
or

```bash
env SDL_VIDEODRIVER=wayland osu-lazer
```

### My CTL-x100 is not detected? {#CTL-x100-android-mode}
It is possible for CTL-x100 tablets to boot in Android mode (the mode they use when interfacing with android devices like phones) instead of PC mode in some rare cases. To fix this, press
the outer 2 express keys for 3-4 seconds until the LEDs change brightness. This toggles the tablet's operating mode
between PC (high LED brightness) and Android mode (low LED brightness).
### Tablet is working but there is no pressure {#artist-mode}

<small class="text-muted">
Note: If you are sure your tablet is in PC mode, please follow our generalised instructions [here](#tablet-not-detected)
</small>
Pressure support is available by changing the output mode of OpenTabletDriver to Artist Mode:

- Change output mode (at the bottom left of OpenTabletDriver) to Artist Mode.
- Remove Tip Binding in the Pen Settings panel by opening advanced binding editor (press '...' next to the binding), then press "Clear".
- Save your settings and then try drawing in an application that supports pressure.

### The systemd user service doesn't automatically start? {#systemd-autostart}
You will also need to use artist mode mouse bindings in the advanced binding editor instead of regular mouse buttons. Regular mouse buttons are _not_ supported in artist mode.

If you have enabled the systemd user service and this happens,
your distro isn't properly activating `graphical-session.target` to ensure OpenTabletDriver starts cleanly.
### The daemon does not start on boot

If you are experiencing this, add `otd-daemon` to the autostart of your desktop environment for OpenTabletDriver to work on startup.
#### systemd {#systemd-autostart}

### How do I start the driver when I'm not using systemd? {#non-systemd}
Make sure that you have enabled the systemd service:

On non-systemd distros you do have not have a specified way to automatically start the daemon.
Instead, if you have installed a packaged build you can run `otd-daemon` in a terminal
```bash
systemctl user enable opentabletdriver.service --now
```

If you are not using a packaged build and instead compiled from source,
you will need to run `./OpenTabletDriver.Daemon` in your terminal from the build directory instead.
If this does not work, this means that the desktop environment is not configured correctly to integrate with systemd. In such case, refer to your desktop environment's documentation on how to autostart processes on login. The command to execute on login is:

You may place this in your desktop environment startup for it to automatically start.
```bash
otd-daemon
```

### Enabling pressure using Artist Mode {#artist-mode}
#### Other init systems

Pressure support is available by changing the output mode of OpenTabletDriver to Artist Mode:
OpenTabletDriver offers no official support for other init systems. Refer to your init system's documentation on how to autostart processes on login. The command to execute on login is:

- Change output mode (at the bottom left of OpenTabletDriver) to Artist Mode.
- Remove the Tip Binding in the Pen Settings panel by clicking the 3 dots, then pressing clear.
- Save your settings and try drawing in an applicantion that supports pressure.
```bash
otd-daemon
```

You will also need to use artist mode mouse bindings in the advanced binding editor (press '...' next to the binding)
instead of regular mouse buttons. Regular mouse buttons are not currently supported in artist mode.
> This command should be run as user, not root.

### Disabling libinput's tablet device smooething
### The cursor feels slow on Artist Mode

Using artist mode will result in some minor smoothing due to libinput's tablet handling.

To disable this smoothing, add the contents below to `/etc/libinput/local-overrides.quirks`:

```ini
[OpenTabletDriver Virtual Tablets]
MatchName=OpenTabletDriver*
Expand All @@ -236,5 +163,4 @@ You should restart the OpenTabletDriver daemon after updating this file.
### I have tried these solutions, but my problem still persists! {#discord}

If you are still encountering problems with OpenTabletDriver,
it will be easier to help you over in our [Discord](/Discord) server,
where we may ask you to do certain debugging steps and give you different instructions to help resolve your problem.
it will be easier to help you over in our [Discord](/Discord) server. We will guide you in doing certain debugging steps and will give you different instructions to help resolve your problem.
Loading