From f2392082f692f1fb6dc90060fa7c667db8c7211c Mon Sep 17 00:00:00 2001 From: Sebastian 'gonX' Jensen Date: Fri, 15 Mar 2024 16:08:26 +0100 Subject: [PATCH 01/20] wiki/Dev/Configurations: Rename title to 'Tablet configuration reference' --- site/_wiki/Development/Configurations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/_wiki/Development/Configurations.md b/site/_wiki/Development/Configurations.md index dc185d5..efb78d8 100644 --- a/site/_wiki/Development/Configurations.md +++ b/site/_wiki/Development/Configurations.md @@ -1,5 +1,5 @@ --- -title: Writing OpenTabletDriver Configurations +title: Tablet configuration reference --- ## Device Information From 7bdddb107ff987d4f29f933e1faef35a80e3778c Mon Sep 17 00:00:00 2001 From: Sebastian 'gonX' Jensen Date: Fri, 15 Mar 2024 16:08:44 +0100 Subject: [PATCH 02/20] wiki/Documentation: Add Configuration guide --- .../_wiki/Documentation/ConfigurationGuide.md | 418 ++++++++++++++++++ 1 file changed, 418 insertions(+) create mode 100644 site/_wiki/Documentation/ConfigurationGuide.md diff --git a/site/_wiki/Documentation/ConfigurationGuide.md b/site/_wiki/Documentation/ConfigurationGuide.md new file mode 100644 index 0000000..16d468e --- /dev/null +++ b/site/_wiki/Documentation/ConfigurationGuide.md @@ -0,0 +1,418 @@ +--- +title: "Guide: Adding support for a new tablet" +--- + +## Prelude + +This guide will step you through how to make a configuration for a tablet. Some +tablets can take a few minutes to set up, while others can require analyzing +the USB packets sent by the manufacturers tablet driver among other things. + +It is probably worthwhile to keep the [Tablet configuration reference] open in +another tab. This guide will assume that you are aware of the details provided +on that page. + +[Tablet configuration reference]: {% link _wiki/Development/Configurations.md %} + +## Preparing your system for adding support + +It is highly recommended to remove (or unload) your existing tablet drivers +before proceeding. + +### Uninstalling drivers on Windows + +Tablet drivers are often automatically installed by Windows. + +Running [TabletDriverCleanup] is the easiest way to ensure that +OpenTabletDriver has access to the tablet. + +[TabletDriverCleanup]: {{ site.data.links.external.TabletDriverCleanup.latest }} + +### Unloading drivers on Linux + +If you've installed OpenTabletDriver from an official package, the stock tablet +drivers are already blacklisted. + +Still, run the following command to ensure that the upstream drivers are unloaded: + +```sh +sudo rmmod hid_uclogic wacom 2>/dev/null +``` + +You likely need to set up udev rules so that your user can access the raw +device directly. + +Normally, this is autogenerated by the build process and uses the officially +supported configs. + +You can define these manually for now, and put them in a local udev rule file, +e.g. `/etc/udev/rules.d/91-opentabletdriver-adds.rules`: + +```conf +KERNEL=="hidraw*", ATTRS{idVendor}=="b33f", ATTRS{idProduct}=="c4k3", TAG+="uaccess", TAG+="udev-acl" +SUBSYSTEM=="usb", ATTRS{idVendor}=="b33f", ATTRS{idProduct}=="c4k3", TAG+="uaccess", TAG+="udev-acl" +``` + +Make sure to change the values of `idVendor` and `idProduct` as appropriate. +You can get them with `lsusb`. + +> Note: `idVendor` and `idProduct` must be in base-16 (hexadecimal) as opposed + to the base-10 format used in OpenTabletDriver configurations. + +See `man 7 udev` for systemd udev syntax. If you're not using systemd udev, see +your distro documentation, or change the appropriate usb and hidraw permissions +manually. + +### MacOS + +TODO, probably just uninstall existing drivers? + +## Configuration Template + +Getting a configuration template is usually simple if OpenTabletDriver supports +other tablets from your manufacturer, especially if it's in the same line of +models. + +- Copy a "neighbouring" configuration from the + `OpenTabletDriver.Configurations/Configurations/` folder +- Rename the file to be `.json`, e.g. `H420.json` + +If your manufacturer does not have an existing template, please use the +[Configuration skeleton] or copy any other tablet configuration and follow the +guide carefully. + +> Note that the configuration format between OpenTabletDriver 0.6 (`0.6.x`) and + 0.7 (`master`) differs slightly. Make sure that you pick a configuration of + the same format as the version of OpenTabletDriver you're using. + +[Configuration skeleton]: https://github.com/OpenTabletDriver/OpenTabletDriver/issues/3249 + +## Setting specifications according to official manufacturer specifications + +Setting up some of the specifications now can simplify touching up later values +if you know what they are. You can also add them as you discover the feature; +we will ensure the specifications are set correctly at the end of the guide. + +Some (almost) always correct values include: +- Pen and tablet (aux) button counts +- Tool support (such as tablet mouse) +- Touch support +- Pen pressure range + +Digitizer dimensions (for both pen and touch digitizer) will be determined as a +later part of the guide, and is not always correct. + +Note that wheels (rings) are not yet supported, and should not be directly defined +(even as a button). See [OpenTabletDriver#1367] for more information + +[OpenTabletDriver#1367]: https://github.com/OpenTabletDriver/OpenTabletDriver/issues/1367 + +## Configuring the digitizer identifier + +Configuring a correct digitizer identifier is the bread and butter of tablet +detection. This section covers how to set all the identifier fields +appropriately. + +A single tablet model generally only needs a single identifier. Still, firmware +variants for an otherwise identical tablet can cause tablets to need more than +1 identifier to correctly identify variants. + +Therefore, it is important to make your identifier as relaxed as possible while +still being strict enough to not cause identifier conflicts with other +configurations. + +Detection, in broad terms, checks in the following order: + +1. Match VendorID and ProductID +2. If not null, match InputReportLength and OutputReportLength + - This helps select a specific interface of the tablet +3. If not null, match DeviceStrings + - This helps differentiate between firmwares + +There is more to detection than this (such as attributes), but 99.9% of use +cases can be covered with the above. + +### ID's and report lengths + +At the very minimum, your configuration should have a non-null `VendorID` and `ProductID`. + +If your tablet has multiple interfaces, it is very likely only 1 of them +contains the tablet data stream. This is where `InputReportLength` and +`OutputReportLength` comes in. + +Even if your tablet only has a single interface, it is often a good idea to +specify at least one of the lengths as non-zero, and only define them as `null` +if you know what you're doing + +> If you specify report lengths as null, it can be hard to fix any future + conflicts that may arise without knowing what values your specific tablet + has. If you do decide to specify them as null, please make sure to include a + OpenTabletDriver diagnostics with the pull request, or include the lengths in + the commit description. + +### Picking the Parser {#parser} + +Picking the parser is the most important part of ensuring your tablet functions +correctly. Picking the wrong parser can result in missing or (sometimes subtly) +broken features. + +You must use a class which implements the `Parse(byte[])` function. + +How to write a parser from scratch is out of scope of this guide, but if you +find that a parser you're using needs a code change to work, it is usually a +better idea to make a new parser that builds off it instead. + +To see which functionality is supported by a parser, please see the code for +the parsers return paths in its `Parse(byte[])` function. An example is +provided below. + +#### `XP_PenReportParser` example + +At the time of this writing, [`XP_PenReportParser`] can return 5 different +types of reports (not in order) + +[`XP_PenReportParser`]: https://github.com/OpenTabletDriver/OpenTabletDriver/blob/f14a184fef67a52637ab494497a151044bafd553/OpenTabletDriver.Configurations/Parsers/XP_Pen/XP_PenReportParser.cs#L7-L21 + +##### `OutOfRangeReport` + +Fairly selfdescript, it doesn't actually report any specific values to the +OS but rather 'resets' the pen out. + +##### `XP_PenAuxReport`: + +Reports `IAuxReport`, an aux-buttons-only report, ie. no position coordinates. + +##### `XP_PenTabletReport` + +Reports the following reports: + +- `ITabletReport` + - The pen's pressure + - Pen buttons + - It is an `IAbsolutePositionReport` that also reports the following: + - The 2-point vector of the pen +- `ITiltReport` + - The 2-point vector of the pen's tilt +- `IEraserReport` + - Whether the eraser is active or not + +##### `XP_PenTabletOverflowReport` + +An almost identical version of the above `XP_PenTabletReport` except with +larger ranges for the position coordinate and the data structure adjusted +accordingly. + +##### `TabletReport` + +A barebones tablet report that only reports an `ITabletReport` + +### Init strings (Feature/OutputInitReport, InitializationStrings) + +These are almost always necessary to use to bring the tablet out of HID mode +and into a more preferred mode, e.g. vendor mode. + +Vendor mode is the mode used by the official drivers, and allows +OpenTabletDriver to support all of the tablets features, assuming the parser +supports it. + +Getting these can be achieved in 2 ways: + +#### Guessing + +Copying the appropriate init strings from a sibling configuration is usually +adequate. + +#### USB Packet capture + +This is usually done with Wireshark (and winpcap). A guide on this is planned +but not in progress. See [opentabletdriver.github.io#171] for more information. + +[opentabletdriver.github.io#171]: https://github.com/OpenTabletDriver/opentabletdriver.github.io/issues/171 + +### Device strings + +In some cases, vendors (especially Huion) might release a tablet with different +specifications that otherwise has the same ID's as another released tablet. + +While this complicates things, we have another tool in our arsenal called +device strings descriptors. + +The configuration format is a dictionary where the key matches the descriptor +ID (up to 255) and the value is a regex that the string descriptor's value must +match with. + +## Validating values + +Assuming you now have a configuration that correctly identifies your tablet, +you now have to validate that you're using the correct parser and then the +correct configuration values. + +### Validating the parser + +This section is **not** for making sure the specifications in the configuration +is configured correctly, only the parser. + +The values below can be validated from entirely within the tablet debugger. + +The tablet debugger will show the values as parsed directly from the tablet, +before any configuration adjustments (such as button count) take place. + +If any of the values seems absent or malfunctioning, you are probably +using the wrong parser. + +#### Digitizer {#validate-parser-digitizer} + +Verify that the top left of the tablet equals to `[0, 0]` or `[1, 1]`. + +Verify that the X and Y values increment monotonically. Critically, the value +must never wrap around. + +#### Pen maximum pressure + +Value must transition somewhat smoothly from around 0 to its maximum value. + +#### All pen and auxiliary buttons + +Every button click must cause a distinct state change. + +Some tablets may support a separate 'unclick' report. + +#### Tool identification + +This is mostly a Wacom feature, and can be difficult to read manually from the +tablet debugger. Use the recording feature of the tablet debugger and read the +annotated file for tool idenfication. + +Unless you have many tools at your disposal, testing the actual functionality +can be difficult. `ToolID` is the "model number" of the tool, whereas +`ToolSerial` is the, well, the serial ID of the tool. + +The tool ID is used for art programs (and the operating system) to assume some +defaults. The extent of exposing tool ID correctly is not completely finished, +and is only partially supported on Linux for now. + +The serial ID is very useful for artists that have multiple of the same tool so +that their art program can track per-tool settings. + +#### Touch + +Touch is currently not exposed to the operating system, but some parsers do +parse touch. If your tablet does parse touch, make sure that it behaves +similarly to the [pen digitizer](#validate-parser-digitizer). + +See [OpenTabletDriver#1664] for more information on exposing this to the OS. + +[OpenTabletDriver#1664]: https://github.com/OpenTabletDriver/OpenTabletDriver/issues/1664 + +### Correctly determining digitizer dimensions + +The ideal way to calculate the these values, is to first figure out the `MaxX` and +`MaxY` values of the digitizer. + +You will need the following values: + +- The LPMM (lines per millimeter) of the tablet for both axises (horizontal and vertical). +- The maximum reported **X** (horizontal) value of the tablet +- The maximum reported **Y** (vertical) value of the tablet + +> The manufacturers digitizer dimensions can often times be slightly wrong + (usually rounded up), so getting this right ensures that users can keep using + the exact same tablet area between different tablets in OpenTabletDriver + +#### Getting maximum X and Y values + +You can get the X and Y values from OpenTabletDriver's tablet debugger. +Move your tool (e.g. pen) to the outer edges (usually right side and bottom +side) of the digitizer area while keeping an eye on the reported X and Y values +in the tablet debugger. + +If your tablet is reporting very quickly, it might be worth using the tablet data recording feature. +> A way to easily display the maximum value returned is planned but not + implemented yet. See [OpenTabletDriver#2433] for more information. + +The `MaxX` and `MaxY` values should be equal to the highest observed value +reported by the tablet on each axis. + +To ensure getting the highest possible X and Y values, make sure that you're +moving your tool to the edge at multiple angles. + +If your achieved `MaxX` and `MaxY` values seem incorrect (such as 4096 x 4096), +you might be initializing the tablet incorrectly, or you're not using the +correct parser. See the [Parser](#parser) section for more information. + +[OpenTabletDriver#2433]: https://github.com/OpenTabletDriver/OpenTabletDriver/issues/2433 + +#### Getting the LPMM + +This is almost always exactly 100 or exactly 200 for both axises. + +> If your tablet only offers an line per inch (LPI) value, you can divide the + LPI by `25.4` to get the LPMM. + +#### Calculating the width and height + +With the LPMM and maximum values reported by the tablet in hand, calculate the +width and the height using the following formulas: + +```py +Width = MaxX / Horizontal_LPMM +Height = MaxY / Vertical_LPMM +``` + +Double check that the resulting width and height is close to the manufacturer's +specified digitizer working area. + +A deviation of up to 10% is normal, but if it is obviously wrong (more than 50% +out), confirm that both your LPMM and width/height values are correct. + +> If the guessed LPMM seems incorrect, it is better to manually measure the + width and the height of the digitizers active area. + +### Verify functionality + +Now that you've checked the values for correctness, you now have to validate +the exposed functionality as much as possible. + +You don't need to validate every single feature set in the OS. For example, +pressure is assumed working if the tablet debugger reports it correctly. + +You now need to double check that the following functionality completely works: + +- The entirety of the tablets area is usable +- All pen buttons works and can be assigned +- All auxiliary (tablet) buttons works and can be assigned +- Extra tool functionality, if able: + - Tablet mouse + - Any other tools your tablet might support + +If anything is not working to your expectations, you might be using the wrong +parser, or you specified some values incorrectly. + +## Fin + +That's it, you've now successfully made a tablet configuration! + +Now, optionally commit it with `git` and push it to your chosen branch and an open a [pull request]. + +[pull request]: {{ site.data.links.project.UpstreamRepo }}/pulls + +## FAQ + +### My cursor is going everywhere! + +Make sure you've uninstalled other drivers. + +If you did, and you're on Linux, your tablet might need the `libinputoverride` attribute. + +### My tablet can't be that difficult to add, TL;DR? + +- Copy existing config from a sibling tablet +- Adjust identifiers and confirm that the tablet debugger is doing things now +- Confirm that the parser is functioning correctly (pressure etc) +- Figure out `MaxX` and `MaxY` and `LPMM` of your tablet's digitizer. +- Adjust height and widths based off of `MaxX`, `MaxY` and their `LPMM`. +- Double check that it still works from a replug +- Double check that all the specifications are correct + - Buttons, digitizer area, pressure, touch, etc. +- Submit pull request to the appropriate branch and pray that your configuration passes tests + - If submitting a PR, don't forget to update `TABLETS.md` to document the support. From 1a21bfbe85d1ab5faef80f413133d6875cc4e9be Mon Sep 17 00:00:00 2001 From: Sebastian Jensen Date: Sun, 17 Nov 2024 15:32:11 +0100 Subject: [PATCH 03/20] (minor) ConfigurationGuide: grammar Co-authored-by: jamesbt365 --- site/_wiki/Documentation/ConfigurationGuide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/_wiki/Documentation/ConfigurationGuide.md b/site/_wiki/Documentation/ConfigurationGuide.md index 16d468e..98bf6ef 100644 --- a/site/_wiki/Documentation/ConfigurationGuide.md +++ b/site/_wiki/Documentation/ConfigurationGuide.md @@ -100,7 +100,7 @@ Some (almost) always correct values include: - Pen pressure range Digitizer dimensions (for both pen and touch digitizer) will be determined as a -later part of the guide, and is not always correct. +later part of the guide, and are not always correct. Note that wheels (rings) are not yet supported, and should not be directly defined (even as a button). See [OpenTabletDriver#1367] for more information From 9dffb2d1f0f63d8f4d36d42a8139cbc738418c21 Mon Sep 17 00:00:00 2001 From: Sebastian 'gonX' Jensen Date: Sat, 12 Apr 2025 17:35:02 +0200 Subject: [PATCH 04/20] (minor) Documentation/ConfigurationGuide: satisfy linter --- .../_wiki/Documentation/ConfigurationGuide.md | 29 ++++++++++--------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/site/_wiki/Documentation/ConfigurationGuide.md b/site/_wiki/Documentation/ConfigurationGuide.md index 98bf6ef..ddd087a 100644 --- a/site/_wiki/Documentation/ConfigurationGuide.md +++ b/site/_wiki/Documentation/ConfigurationGuide.md @@ -94,6 +94,7 @@ if you know what they are. You can also add them as you discover the feature; we will ensure the specifications are set correctly at the end of the guide. Some (almost) always correct values include: + - Pen and tablet (aux) button counts - Tool support (such as tablet mouse) - Touch support @@ -125,9 +126,9 @@ Detection, in broad terms, checks in the following order: 1. Match VendorID and ProductID 2. If not null, match InputReportLength and OutputReportLength - - This helps select a specific interface of the tablet + - This helps select a specific interface of the tablet 3. If not null, match DeviceStrings - - This helps differentiate between firmwares + - This helps differentiate between firmwares There is more to detection than this (such as attributes), but 99.9% of use cases can be covered with the above. @@ -178,7 +179,7 @@ types of reports (not in order) Fairly selfdescript, it doesn't actually report any specific values to the OS but rather 'resets' the pen out. -##### `XP_PenAuxReport`: +##### `XP_PenAuxReport` Reports `IAuxReport`, an aux-buttons-only report, ie. no position coordinates. @@ -187,14 +188,14 @@ Reports `IAuxReport`, an aux-buttons-only report, ie. no position coordinates. Reports the following reports: - `ITabletReport` - - The pen's pressure - - Pen buttons - - It is an `IAbsolutePositionReport` that also reports the following: - - The 2-point vector of the pen + - The pen's pressure + - Pen buttons + - It is an `IAbsolutePositionReport` that also reports the following: + - The 2-point vector of the pen - `ITiltReport` - - The 2-point vector of the pen's tilt + - The 2-point vector of the pen's tilt - `IEraserReport` - - Whether the eraser is active or not + - Whether the eraser is active or not ##### `XP_PenTabletOverflowReport` @@ -382,8 +383,8 @@ You now need to double check that the following functionality completely works: - All pen buttons works and can be assigned - All auxiliary (tablet) buttons works and can be assigned - Extra tool functionality, if able: - - Tablet mouse - - Any other tools your tablet might support + - Tablet mouse + - Any other tools your tablet might support If anything is not working to your expectations, you might be using the wrong parser, or you specified some values incorrectly. @@ -398,7 +399,7 @@ Now, optionally commit it with `git` and push it to your chosen branch and an op ## FAQ -### My cursor is going everywhere! +### My cursor is going everywhere Make sure you've uninstalled other drivers. @@ -413,6 +414,6 @@ If you did, and you're on Linux, your tablet might need the `libinputoverride` a - Adjust height and widths based off of `MaxX`, `MaxY` and their `LPMM`. - Double check that it still works from a replug - Double check that all the specifications are correct - - Buttons, digitizer area, pressure, touch, etc. + - Buttons, digitizer area, pressure, touch, etc. - Submit pull request to the appropriate branch and pray that your configuration passes tests - - If submitting a PR, don't forget to update `TABLETS.md` to document the support. + - If submitting a PR, don't forget to update `TABLETS.md` to document the support. From 3e69e1922fb3518260ed1d020f3055a18c8c5ee1 Mon Sep 17 00:00:00 2001 From: Sebastian 'gonX' Jensen Date: Sat, 12 Apr 2025 17:54:34 +0200 Subject: [PATCH 05/20] Doc/ConfigurationGuide: MacOS: Replace TODO with rudimentary suggestion --- site/_wiki/Documentation/ConfigurationGuide.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/site/_wiki/Documentation/ConfigurationGuide.md b/site/_wiki/Documentation/ConfigurationGuide.md index ddd087a..8079a41 100644 --- a/site/_wiki/Documentation/ConfigurationGuide.md +++ b/site/_wiki/Documentation/ConfigurationGuide.md @@ -65,7 +65,8 @@ manually. ### MacOS -TODO, probably just uninstall existing drivers? +All you should need for OpenTabletDriver to initialize and access your tablet, +is uninstalling the OEM drivers. ## Configuration Template From b0c013671cb9f2c6cf2cda10683aed420656908c Mon Sep 17 00:00:00 2001 From: Sebastian 'gonX' Jensen Date: Sat, 12 Apr 2025 18:01:58 +0200 Subject: [PATCH 06/20] ConfigurationGuide: Permit use of wheel buttons as aux buttons --- site/_wiki/Documentation/ConfigurationGuide.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/site/_wiki/Documentation/ConfigurationGuide.md b/site/_wiki/Documentation/ConfigurationGuide.md index 8079a41..c290021 100644 --- a/site/_wiki/Documentation/ConfigurationGuide.md +++ b/site/_wiki/Documentation/ConfigurationGuide.md @@ -104,8 +104,11 @@ Some (almost) always correct values include: Digitizer dimensions (for both pen and touch digitizer) will be determined as a later part of the guide, and are not always correct. -Note that wheels (rings) are not yet supported, and should not be directly defined -(even as a button). See [OpenTabletDriver#1367] for more information +Note that wheels (rings) are not yet supported, and should not be directly defined. +See [OpenTabletDriver#1367] for more information + +If the parser you use picks up wheel buttons as an aux button, make sure to +take this into consideration when specifying aux button count. [OpenTabletDriver#1367]: https://github.com/OpenTabletDriver/OpenTabletDriver/issues/1367 From 72e24b4820bd88c31fde474946b09a40ab3a8aae Mon Sep 17 00:00:00 2001 From: Sebastian 'gonX' Jensen Date: Sat, 12 Apr 2025 21:07:38 +0200 Subject: [PATCH 07/20] ConfigurationGuide: reword null report length PR suggestions We always want a diagnostic file in a PR, reword it so that people can optionally put the report lengths in the commit message --- site/_wiki/Documentation/ConfigurationGuide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/site/_wiki/Documentation/ConfigurationGuide.md b/site/_wiki/Documentation/ConfigurationGuide.md index c290021..18a3871 100644 --- a/site/_wiki/Documentation/ConfigurationGuide.md +++ b/site/_wiki/Documentation/ConfigurationGuide.md @@ -152,8 +152,8 @@ if you know what you're doing > If you specify report lengths as null, it can be hard to fix any future conflicts that may arise without knowing what values your specific tablet has. If you do decide to specify them as null, please make sure to include a - OpenTabletDriver diagnostics with the pull request, or include the lengths in - the commit description. + OpenTabletDriver diagnostics with the pull request, and optionally include + the lengths in the commit description. ### Picking the Parser {#parser} From 8fc212639d43ddcb3cc01b3113629f3a9352e2ae Mon Sep 17 00:00:00 2001 From: Sebastian 'gonX' Jensen Date: Sat, 12 Apr 2025 22:08:46 +0200 Subject: [PATCH 08/20] ConfigurationGuide: Add Common initialization strings Used the following jq command to extract initialization strings from current configurations in OpenTabletDriver codebase: jq '{ name: .Name, InitializationStrings: .DigitizerIdentifiers[].InitializationStrings } | select(.InitializationStrings != null)' OpenTabletDriver.Configurations/Configurations/**/*.json --- .../_wiki/Documentation/ConfigurationGuide.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/site/_wiki/Documentation/ConfigurationGuide.md b/site/_wiki/Documentation/ConfigurationGuide.md index 18a3871..aeac1a3 100644 --- a/site/_wiki/Documentation/ConfigurationGuide.md +++ b/site/_wiki/Documentation/ConfigurationGuide.md @@ -227,6 +227,25 @@ Getting these can be achieved in 2 ways: Copying the appropriate init strings from a sibling configuration is usually adequate. +##### Common initialization strings + +For many UC-Logic based tablets, like Huion and Gaomon, they seem to all share +almost the same indices to probe across many generations. + +Here are some recommended starting points for initialization strings, in order +of most common to least common + +- `200` +- `100` + +If `100` works but you have missing auxiliary buttons, you may need to follow +it up with an string initialization on `123` + +The following 2 initialization strings have only been seen once: + +- `109` +- `100` followed by `110` + #### USB Packet capture This is usually done with Wireshark (and winpcap). A guide on this is planned From f52354e504641a7d929e39ba16c42d9fa6a77991 Mon Sep 17 00:00:00 2001 From: Sebastian 'gonX' Jensen Date: Sat, 12 Apr 2025 22:28:50 +0200 Subject: [PATCH 09/20] ConfigurationGuide: Add Common device strings section The following jq command was used to print out the device strings: jq '{ name: .Name, DeviceStrings: .DigitizerIdentifiers[].DeviceStrings } | select(.DeviceStrings != null)' OpenTabletDriver.Configurations/Configurations/**/*.json --- .../_wiki/Documentation/ConfigurationGuide.md | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/site/_wiki/Documentation/ConfigurationGuide.md b/site/_wiki/Documentation/ConfigurationGuide.md index aeac1a3..49cd12d 100644 --- a/site/_wiki/Documentation/ConfigurationGuide.md +++ b/site/_wiki/Documentation/ConfigurationGuide.md @@ -265,6 +265,28 @@ The configuration format is a dictionary where the key matches the descriptor ID (up to 255) and the value is a regex that the string descriptor's value must match with. +While they are similar to initialization strings, the difference here is that +we read the returned output when initializing the string, and as such can match +tablets based on its contents. + +#### Common device strings + +Below are some usually common device strings for various vendors. + +These are not guaranteed to be correct across all models for the vendor, but +may help some people decode their meaning. + +| Index | Value | +| ----: | :---- | +| 2 | XP-Pen: Model Name +| 4 | XP-Pen: Firmware Build ID +| 5 | XP-Pen: Firmware Build String +| 23 | VEIKK: Firmware Build Date +| 201 | Gaomon, Huion, and some other UC-Logic based: Firmware Build ID + +Be wary that probing strings can also change behavior in the device, which can +usually be rectified by replugging the tablet. + ## Validating values Assuming you now have a configuration that correctly identifies your tablet, From 3a347c43e3a903e626bf4ba95e172e38bf606bc6 Mon Sep 17 00:00:00 2001 From: Sebastian Jensen Date: Sun, 13 Apr 2025 00:58:31 +0200 Subject: [PATCH 10/20] ConfigurationGuide: detail what happens on wrong parser Co-authored-by: jamesbt365 --- site/_wiki/Documentation/ConfigurationGuide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/site/_wiki/Documentation/ConfigurationGuide.md b/site/_wiki/Documentation/ConfigurationGuide.md index 49cd12d..7f547a1 100644 --- a/site/_wiki/Documentation/ConfigurationGuide.md +++ b/site/_wiki/Documentation/ConfigurationGuide.md @@ -303,8 +303,8 @@ The values below can be validated from entirely within the tablet debugger. The tablet debugger will show the values as parsed directly from the tablet, before any configuration adjustments (such as button count) take place. -If any of the values seems absent or malfunctioning, you are probably -using the wrong parser. +If any of the values seems absent or malfunctioning (overflowing, abrupt jumps), +you are probably using the wrong parser. #### Digitizer {#validate-parser-digitizer} From 2c663801d123a25a9abf21b5bda4aae90c78e0f2 Mon Sep 17 00:00:00 2001 From: Sebastian 'gonX' Jensen Date: Sun, 13 Apr 2025 01:01:38 +0200 Subject: [PATCH 11/20] ConfigurationGuide: Mention PassthroughReportParser in Parser selection section --- site/_wiki/Documentation/ConfigurationGuide.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/site/_wiki/Documentation/ConfigurationGuide.md b/site/_wiki/Documentation/ConfigurationGuide.md index 7f547a1..22da9cb 100644 --- a/site/_wiki/Documentation/ConfigurationGuide.md +++ b/site/_wiki/Documentation/ConfigurationGuide.md @@ -171,6 +171,14 @@ To see which functionality is supported by a parser, please see the code for the parsers return paths in its `Parse(byte[])` function. An example is provided below. +If you don't know anything about your tablet, or if you're writing your own +parser, it is recommended to start out with the `PassthroughReportParser` +parser, as it does not directly parse data but instead just allows the Tablet +Debugger to display the raw data. + +It is important to not get overzealous and pick a too specific parser before +you've ensured that the tablet is initialized correctly. + #### `XP_PenReportParser` example At the time of this writing, [`XP_PenReportParser`] can return 5 different From 1fe1219a7237ce13c009c53b9e4e84b43da9b9b2 Mon Sep 17 00:00:00 2001 From: Sebastian 'gonX' Jensen Date: Sun, 13 Apr 2025 01:05:29 +0200 Subject: [PATCH 12/20] (minor) ConfigurationGuide: linting --- site/_wiki/Documentation/ConfigurationGuide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/_wiki/Documentation/ConfigurationGuide.md b/site/_wiki/Documentation/ConfigurationGuide.md index 22da9cb..a2e3781 100644 --- a/site/_wiki/Documentation/ConfigurationGuide.md +++ b/site/_wiki/Documentation/ConfigurationGuide.md @@ -311,7 +311,7 @@ The values below can be validated from entirely within the tablet debugger. The tablet debugger will show the values as parsed directly from the tablet, before any configuration adjustments (such as button count) take place. -If any of the values seems absent or malfunctioning (overflowing, abrupt jumps), +If any of the values seems absent or malfunctioning (overflowing, abrupt jumps), you are probably using the wrong parser. #### Digitizer {#validate-parser-digitizer} From 52d0da6450d4ef445e2ac87f2bbc4aa3c8b23155 Mon Sep 17 00:00:00 2001 From: Sebastian 'gonX' Jensen Date: Sun, 13 Apr 2025 01:10:35 +0200 Subject: [PATCH 13/20] ConfigurationGuide: add reference to Discord --- site/_wiki/Documentation/ConfigurationGuide.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/site/_wiki/Documentation/ConfigurationGuide.md b/site/_wiki/Documentation/ConfigurationGuide.md index a2e3781..20fdf30 100644 --- a/site/_wiki/Documentation/ConfigurationGuide.md +++ b/site/_wiki/Documentation/ConfigurationGuide.md @@ -442,6 +442,9 @@ You now need to double check that the following functionality completely works: If anything is not working to your expectations, you might be using the wrong parser, or you specified some values incorrectly. +If you're stuck, you can visit our [Discord]({{ site.data.links.project.DiscordInvite }}) and +ask for help in one of the following channels: `#configs` or `#support-misc` + ## Fin That's it, you've now successfully made a tablet configuration! From c1a87e51577024faada5f46b0ff3e29946a0e3ad Mon Sep 17 00:00:00 2001 From: Sebastian 'gonX' Jensen Date: Sun, 13 Apr 2025 01:35:19 +0200 Subject: [PATCH 14/20] ConfigurationGuide: add static ID's for headers --- .../_wiki/Documentation/ConfigurationGuide.md | 52 +++++++++---------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/site/_wiki/Documentation/ConfigurationGuide.md b/site/_wiki/Documentation/ConfigurationGuide.md index 20fdf30..ee1e8eb 100644 --- a/site/_wiki/Documentation/ConfigurationGuide.md +++ b/site/_wiki/Documentation/ConfigurationGuide.md @@ -19,7 +19,7 @@ on that page. It is highly recommended to remove (or unload) your existing tablet drivers before proceeding. -### Uninstalling drivers on Windows +### Uninstalling drivers on Windows {#preparing-windows} Tablet drivers are often automatically installed by Windows. @@ -28,7 +28,7 @@ OpenTabletDriver has access to the tablet. [TabletDriverCleanup]: {{ site.data.links.external.TabletDriverCleanup.latest }} -### Unloading drivers on Linux +### Unloading drivers on Linux {#preparing-linux} If you've installed OpenTabletDriver from an official package, the stock tablet drivers are already blacklisted. @@ -63,12 +63,12 @@ See `man 7 udev` for systemd udev syntax. If you're not using systemd udev, see your distro documentation, or change the appropriate usb and hidraw permissions manually. -### MacOS +### MacOS {#preparing-macos} All you should need for OpenTabletDriver to initialize and access your tablet, is uninstalling the OEM drivers. -## Configuration Template +## Configuration Template {#config-template-intro} Getting a configuration template is usually simple if OpenTabletDriver supports other tablets from your manufacturer, especially if it's in the same line of @@ -88,7 +88,7 @@ guide carefully. [Configuration skeleton]: https://github.com/OpenTabletDriver/OpenTabletDriver/issues/3249 -## Setting specifications according to official manufacturer specifications +## Setting specifications according to official manufacturer specifications {#oem-values} Setting up some of the specifications now can simplify touching up later values if you know what they are. You can also add them as you discover the feature; @@ -112,7 +112,7 @@ take this into consideration when specifying aux button count. [OpenTabletDriver#1367]: https://github.com/OpenTabletDriver/OpenTabletDriver/issues/1367 -## Configuring the digitizer identifier +## Configuring the digitizer identifier {#digitizer-identifier} Configuring a correct digitizer identifier is the bread and butter of tablet detection. This section covers how to set all the identifier fields @@ -137,7 +137,7 @@ Detection, in broad terms, checks in the following order: There is more to detection than this (such as attributes), but 99.9% of use cases can be covered with the above. -### ID's and report lengths +### ID's and report lengths {#identifiers-and-report-lengths} At the very minimum, your configuration should have a non-null `VendorID` and `ProductID`. @@ -219,7 +219,7 @@ accordingly. A barebones tablet report that only reports an `ITabletReport` -### Init strings (Feature/OutputInitReport, InitializationStrings) +### Init strings (Feature/OutputInitReport, InitializationStrings) {#init-strings} These are almost always necessary to use to bring the tablet out of HID mode and into a more preferred mode, e.g. vendor mode. @@ -235,7 +235,7 @@ Getting these can be achieved in 2 ways: Copying the appropriate init strings from a sibling configuration is usually adequate. -##### Common initialization strings +##### Common initialization strings {#common-init-strings} For many UC-Logic based tablets, like Huion and Gaomon, they seem to all share almost the same indices to probe across many generations. @@ -254,14 +254,14 @@ The following 2 initialization strings have only been seen once: - `109` - `100` followed by `110` -#### USB Packet capture +#### USB Packet capture {#pcap} This is usually done with Wireshark (and winpcap). A guide on this is planned but not in progress. See [opentabletdriver.github.io#171] for more information. [opentabletdriver.github.io#171]: https://github.com/OpenTabletDriver/opentabletdriver.github.io/issues/171 -### Device strings +### Device strings {#device-strings} In some cases, vendors (especially Huion) might release a tablet with different specifications that otherwise has the same ID's as another released tablet. @@ -277,7 +277,7 @@ While they are similar to initialization strings, the difference here is that we read the returned output when initializing the string, and as such can match tablets based on its contents. -#### Common device strings +#### Common device strings {#common-device-strings} Below are some usually common device strings for various vendors. @@ -295,13 +295,13 @@ may help some people decode their meaning. Be wary that probing strings can also change behavior in the device, which can usually be rectified by replugging the tablet. -## Validating values +## Validating values {#validation} Assuming you now have a configuration that correctly identifies your tablet, you now have to validate that you're using the correct parser and then the correct configuration values. -### Validating the parser +### Validating the parser {#validation-parser} This section is **not** for making sure the specifications in the configuration is configured correctly, only the parser. @@ -314,24 +314,24 @@ before any configuration adjustments (such as button count) take place. If any of the values seems absent or malfunctioning (overflowing, abrupt jumps), you are probably using the wrong parser. -#### Digitizer {#validate-parser-digitizer} +#### Digitizer {#validation-parser-digitizer} Verify that the top left of the tablet equals to `[0, 0]` or `[1, 1]`. Verify that the X and Y values increment monotonically. Critically, the value must never wrap around. -#### Pen maximum pressure +#### Pen maximum pressure {#validation-parser-pen-pressure} Value must transition somewhat smoothly from around 0 to its maximum value. -#### All pen and auxiliary buttons +#### All pen and auxiliary buttons {#validation-parser-buttons} Every button click must cause a distinct state change. Some tablets may support a separate 'unclick' report. -#### Tool identification +#### Tool identification {#validation-tool-identification} This is mostly a Wacom feature, and can be difficult to read manually from the tablet debugger. Use the recording feature of the tablet debugger and read the @@ -348,7 +348,7 @@ and is only partially supported on Linux for now. The serial ID is very useful for artists that have multiple of the same tool so that their art program can track per-tool settings. -#### Touch +#### Touch {#validation-touch} Touch is currently not exposed to the operating system, but some parsers do parse touch. If your tablet does parse touch, make sure that it behaves @@ -358,7 +358,7 @@ See [OpenTabletDriver#1664] for more information on exposing this to the OS. [OpenTabletDriver#1664]: https://github.com/OpenTabletDriver/OpenTabletDriver/issues/1664 -### Correctly determining digitizer dimensions +### Correctly determining digitizer dimensions {#digitizer-correct-dimensions} The ideal way to calculate the these values, is to first figure out the `MaxX` and `MaxY` values of the digitizer. @@ -373,7 +373,7 @@ You will need the following values: (usually rounded up), so getting this right ensures that users can keep using the exact same tablet area between different tablets in OpenTabletDriver -#### Getting maximum X and Y values +#### Getting maximum X and Y values {#digitizer-max-positional-values} You can get the X and Y values from OpenTabletDriver's tablet debugger. Move your tool (e.g. pen) to the outer edges (usually right side and bottom @@ -396,14 +396,14 @@ correct parser. See the [Parser](#parser) section for more information. [OpenTabletDriver#2433]: https://github.com/OpenTabletDriver/OpenTabletDriver/issues/2433 -#### Getting the LPMM +#### Getting the LPMM {#digitizer-lpmm} This is almost always exactly 100 or exactly 200 for both axises. > If your tablet only offers an line per inch (LPI) value, you can divide the LPI by `25.4` to get the LPMM. -#### Calculating the width and height +#### Calculating the width and height {#digitizer-dimensions-calculation} With the LPMM and maximum values reported by the tablet in hand, calculate the width and the height using the following formulas: @@ -422,7 +422,7 @@ out), confirm that both your LPMM and width/height values are correct. > If the guessed LPMM seems incorrect, it is better to manually measure the width and the height of the digitizers active area. -### Verify functionality +### Verify functionality {#verify-functionality} Now that you've checked the values for correctness, you now have to validate the exposed functionality as much as possible. @@ -453,9 +453,9 @@ Now, optionally commit it with `git` and push it to your chosen branch and an op [pull request]: {{ site.data.links.project.UpstreamRepo }}/pulls -## FAQ +## FAQ {#faq} -### My cursor is going everywhere +### My cursor is going everywhere {#faq-cursor-skipping} Make sure you've uninstalled other drivers. From 22ca483f19e5380bef9fa5e7a540721de08a5094 Mon Sep 17 00:00:00 2001 From: Sebastian 'gonX' Jensen Date: Sun, 13 Apr 2025 01:36:08 +0200 Subject: [PATCH 15/20] ConfigurationGuide: Wikify init strings in device strings section --- site/_wiki/Documentation/ConfigurationGuide.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/site/_wiki/Documentation/ConfigurationGuide.md b/site/_wiki/Documentation/ConfigurationGuide.md index ee1e8eb..c231b32 100644 --- a/site/_wiki/Documentation/ConfigurationGuide.md +++ b/site/_wiki/Documentation/ConfigurationGuide.md @@ -273,9 +273,9 @@ The configuration format is a dictionary where the key matches the descriptor ID (up to 255) and the value is a regex that the string descriptor's value must match with. -While they are similar to initialization strings, the difference here is that -we read the returned output when initializing the string, and as such can match -tablets based on its contents. +While they are similar to [initialization strings](#init-strings), the +difference here is that we read the returned output when initializing the +string, and as such can match tablets based on its contents. #### Common device strings {#common-device-strings} From 93d95d40529eaba4e95428c1c8b86faf33c55d60 Mon Sep 17 00:00:00 2001 From: Sebastian 'gonX' Jensen Date: Sun, 13 Apr 2025 01:36:42 +0200 Subject: [PATCH 16/20] ConfigurationGuide: Embolden vendor names in string index table --- site/_wiki/Documentation/ConfigurationGuide.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/site/_wiki/Documentation/ConfigurationGuide.md b/site/_wiki/Documentation/ConfigurationGuide.md index c231b32..2095524 100644 --- a/site/_wiki/Documentation/ConfigurationGuide.md +++ b/site/_wiki/Documentation/ConfigurationGuide.md @@ -286,11 +286,11 @@ may help some people decode their meaning. | Index | Value | | ----: | :---- | -| 2 | XP-Pen: Model Name -| 4 | XP-Pen: Firmware Build ID -| 5 | XP-Pen: Firmware Build String -| 23 | VEIKK: Firmware Build Date -| 201 | Gaomon, Huion, and some other UC-Logic based: Firmware Build ID +| 2 | **XP-Pen**: Model Name +| 4 | **XP-Pen**: Firmware Build ID +| 5 | **XP-Pen**: Firmware Build String +| 23 | **VEIKK**: Firmware Build Date +| 201 | **Gaomon**, **Huion**, and some other **UC-Logic** based: Firmware Build ID Be wary that probing strings can also change behavior in the device, which can usually be rectified by replugging the tablet. From 5eca3763b21444ee2c470bb5ee25343d6a7868ef Mon Sep 17 00:00:00 2001 From: Sebastian 'gonX' Jensen Date: Sun, 13 Apr 2025 01:37:11 +0200 Subject: [PATCH 17/20] ConfigurationGuide: LPMM section: thousands of LPI is possible too --- site/_wiki/Documentation/ConfigurationGuide.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/site/_wiki/Documentation/ConfigurationGuide.md b/site/_wiki/Documentation/ConfigurationGuide.md index 2095524..1d92d9e 100644 --- a/site/_wiki/Documentation/ConfigurationGuide.md +++ b/site/_wiki/Documentation/ConfigurationGuide.md @@ -398,7 +398,8 @@ correct parser. See the [Parser](#parser) section for more information. #### Getting the LPMM {#digitizer-lpmm} -This is almost always exactly 100 or exactly 200 for both axises. +This is almost always exactly 100 LPMM or exactly 200 LPMM for both axises, or another +round value, like LPI rounded to nearest thousands, like 4000 LPI. > If your tablet only offers an line per inch (LPI) value, you can divide the LPI by `25.4` to get the LPMM. From c00888210fb518c9a2c38a6302d4b18dbeebe883 Mon Sep 17 00:00:00 2001 From: Sebastian 'gonX' Jensen Date: Sun, 13 Apr 2025 01:37:29 +0200 Subject: [PATCH 18/20] ConfigurationGuide: Link to other FAQ's in FAQ section --- site/_wiki/Documentation/ConfigurationGuide.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/site/_wiki/Documentation/ConfigurationGuide.md b/site/_wiki/Documentation/ConfigurationGuide.md index 1d92d9e..026982c 100644 --- a/site/_wiki/Documentation/ConfigurationGuide.md +++ b/site/_wiki/Documentation/ConfigurationGuide.md @@ -456,6 +456,12 @@ Now, optionally commit it with `git` and push it to your chosen branch and an op ## FAQ {#faq} +You should also read the [General FAQ]({% link _wiki/FAQ/General.md %}) and +your OS-appropriate FAQ ([Windows]({% link _wiki/FAQ/Windows.md %}), +[Linux]({% link _wiki/FAQ/Linux.md %}), +[MacOS]({% link _wiki/FAQ/MacOS.md %}) +too for other issues that might not be covered below. + ### My cursor is going everywhere {#faq-cursor-skipping} Make sure you've uninstalled other drivers. From 437e4fe6941e6e5a56e6448e06e5dca94166726a Mon Sep 17 00:00:00 2001 From: Sebastian 'gonX' Jensen Date: Sun, 13 Apr 2025 01:53:00 +0200 Subject: [PATCH 19/20] ConfigurationGuide: fix invalid anchor link --- site/_wiki/Documentation/ConfigurationGuide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/_wiki/Documentation/ConfigurationGuide.md b/site/_wiki/Documentation/ConfigurationGuide.md index 026982c..d665d80 100644 --- a/site/_wiki/Documentation/ConfigurationGuide.md +++ b/site/_wiki/Documentation/ConfigurationGuide.md @@ -352,7 +352,7 @@ that their art program can track per-tool settings. Touch is currently not exposed to the operating system, but some parsers do parse touch. If your tablet does parse touch, make sure that it behaves -similarly to the [pen digitizer](#validate-parser-digitizer). +similarly to the [pen digitizer](#validation-parser-digitizer). See [OpenTabletDriver#1664] for more information on exposing this to the OS. From 50d9a526cf72d730f0885c0dd5a40101437f56e5 Mon Sep 17 00:00:00 2001 From: Sebastian 'gonX' Jensen Date: Sun, 13 Apr 2025 01:53:18 +0200 Subject: [PATCH 20/20] (minor) ConfigurationGuide: fix missing end parenthesis --- site/_wiki/Documentation/ConfigurationGuide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/_wiki/Documentation/ConfigurationGuide.md b/site/_wiki/Documentation/ConfigurationGuide.md index d665d80..1082bda 100644 --- a/site/_wiki/Documentation/ConfigurationGuide.md +++ b/site/_wiki/Documentation/ConfigurationGuide.md @@ -459,7 +459,7 @@ Now, optionally commit it with `git` and push it to your chosen branch and an op You should also read the [General FAQ]({% link _wiki/FAQ/General.md %}) and your OS-appropriate FAQ ([Windows]({% link _wiki/FAQ/Windows.md %}), [Linux]({% link _wiki/FAQ/Linux.md %}), -[MacOS]({% link _wiki/FAQ/MacOS.md %}) +[MacOS]({% link _wiki/FAQ/MacOS.md %})) too for other issues that might not be covered below. ### My cursor is going everywhere {#faq-cursor-skipping}