Weylus

Weylus turns your tablet or smart phone into a graphic tablet/touch screen for your computer!

Weylus in action with Xournal++:

Table of Contents

• Features
• Installation
  • Packages
• Running
  • Fullscreen
  • Keyboard Input
  • Automation
  • Linux
    • Wayland
    • Hardware Acceleration
    • Weylus as Second Screen
      • Intel GPU on Xorg with Intel drivers
      • Dummy Plugs
      • Other Options
    • Encryption
  • macOS
    • Hardware Acceleration
  • Windows
    • Hardware Acceleration
• Building
  • Docker
• How does this work?
  • Stylus/Touch
  • Screen mirroring & window capturing
• FAQ

Features

• Control your mouse with your tablet
• Mirror your screen to your tablet
• Send keyboard input using physical keyboards
• Hardware accelerated video encoding

The above features are available on all Operating Systems but Weylus works best on Linux. Additional features on Linux are:

• Support for a stylus/pen (supports pressure and tilt)
• Multi-touch: Try it with software that supports multi-touch, like Krita, and see for yourself!
• Capturing specific windows and only drawing to them
• Faster screen mirroring
• Tablet as second screen

Installation

Just grab the latest release for your OS from the releases page and install it on your computer. No apps except a modern browser (Firefox 80+, iOS/iPadOS 13+) are required on your tablet. If you run Linux make sure to follow the instructions described here to enable uinput for features like pressure sensitivity and multitouch!

Packages

AUR packages for Weylus are available here:

• From source: weylus
• Prebuilt binary: weylus-bin

Running

Start Weylus, preferably set an access code in the access code box and press the Start button. This will start a webserver running on your computer. To control your computer with your tablet you need to open the url http://<address of your computer>:<port set in the menu, default is 1701>, if possible Weylus will display to you the url you need to open and show a QR code with the encoded address. If you have a firewall running make sure to open a TCP port for the webserver (1701 by default) and the websocket connection (9001 by default).

On many Linux distributions this is done with ufw:

sudo ufw allow 1701/tcp
sudo ufw allow 9001/tcp

Please only run Weylus in networks you trust as there is no encryption to enable minimal latencies.

Fullscreen

You may want to add a bookmark to your home screen on your tablet as this enables running Weylus in full screen mode (on iOS/iPadOS this needs to be done with Safari). If you are not on iOS/iPadOS there is a button to toggle full screen mode.

Keyboard Input

Weylus supports keyboard input for physical keyboards, so if you have a Bluetooth keyboard, just connect it to your tablet and start typing. Due to technical limitations onscreen keyboards are not supported.

Automation

Weylus provides some features to make automation as convenient as possible. There is a command-line interface; --no-gui for example starts Weylus in headless mode without a gui. For more options see weylus --help. If you want to run a specific script e.g., once a client connects to your computer you can do so by parsing the log Weylus generates. You may want to enable more verbose logging by setting the environment variable WEYLUS_LOG_LEVEL to DEBUG or TRACE as well as WEYLUS_LOG_JSON to true to enable easily parseable JSON logging.

Linux

Weylus uses the uinput interface to simulate input events on Linux. To enable stylus and multi-touch support /dev/uinput needs to be writable by Weylus. To make /dev/uinput permanently writable by your user, run:

sudo groupadd -r uinput
sudo usermod -aG uinput $USER
echo 'KERNEL=="uinput", MODE="0660", GROUP="uinput", OPTIONS+="static_node=uinput"' \
| sudo tee /etc/udev/rules.d/60-weylus.rules

Then, either reboot, or run

sudo udevadm control --reload
sudo udevadm trigger

then log out and log in again. To undo this, run:

sudo rm /etc/udev/rules.d/60-weylus.rules

This allows your user to synthesize input events system-wide, even when another user is logged in. Therefore, untrusted users should not be added to the uinput group.

Wayland

Weylus offers experimental support for Wayland. Installing pipewire and xdg-desktop-portal as well as one of:

• xdg-desktop-portal-gtk for GNOME
• xdg-desktop-portal-kde for KDE
• xdg-desktop-portal-wlr for wlroots-based compositors like Sway is required.

There are still some things that do not work:

• input mapping for windows
• displaying proper window names
• capturing the cursor

Hardware Acceleration

On Linux Weylus supports hardware accelerated video encoding through the Video Acceleration API (VAAPI) or Nvidia's NVENC. By default hardware acceleration is disabled as quality and stability of the hardware encoded video stream varies widely among different hardware and sufficient quality can not be guaranteed. If VAAPI is used it is possible to select a specific driver by setting the environment variable LIBVA_DRIVER_NAME. You can find possible values with the command ls /usr/lib/dri/ | sed -n 's/^\(\S*\)_drv_video.so$/\1/p'. On some distributions the drivers may not reside in /usr/lib/dri but for example in /usr/lib/x86_64-linux-gnu/dri and may not be found by Weylus. To force Weylus to search another directory for drivers, the environment variable LIBVA_DRIVERS_PATH can be set. Additionally you can specify the VAAPI device to use by setting WEYLUS_VAAPI_DEVICE; by default devices can be found in /dev/dri. On some systems this is not optional and this variable must be set. If VAAPI doesn't work out of the box for you, have a look into /dev/dri, often setting WEYLUS_VAAPI_DEVICE=/dev/dri/renderD129 is already the solution. Note that you may need to install the driver(s) first.

Nvidias NVENC is very fast but delivers a video stream of noticeably lower quality (at least on my GeForce GTX 1050 Mobile GPU) but more recent GPUs should provide higher quality. For this to work nvidia drivers need to be installed.

Weylus as Second Screen

There are a few possibilities to use Weylus to turn your tablet into a second screen.

Intel GPU on Xorg with Intel drivers

Intel's drivers support creating virtual outputs that can be configured via xrandr.

But first a word of warning: The following configuration may break starting the X server. This means you might end up without a graphical login or X may get stuck and just display a black screen. So make sure you know what you are doing or are at least able to recover from a broken X server.

You will need to install the xf86-video-intel driver and create the file /etc/X11/xorg.conf.d/20-intel.conf with the following contents:

Section "Device"
    Identifier "intelgpu0"
    Driver "intel"

    # this adds two virtual monitors / devices
    Option "VirtualHeads" "2"

    # if your screen is flickering one of the following options might help
    # Option "TripleBuffer" "true"
    # Option "TearFree"     "true"
    # Option "DRI"          "false"
EndSection

After a reboot xrandr will show two additional monitors VIRTUAL1 and VIRTUAL2 and can be used to configure them. To activate VIRTUAL1 with a screen size of 1112x834 and a refresh rate of 60 fps the following commands can be used:

> # this generates all input parameters xrandr needs
> #from a given screen resolution and refresh rate
> gtf 1112 834 60

  # 1112x834 @ 60.00 Hz (GTF) hsync: 51.78 kHz; pclk: 75.81 MHz
  Modeline "1112x834_60.00"  75.81  1112 1168 1288 1464  834 835 838 863  -HSync +Vsync
> # setup the monitor
> xrandr --newmode "1112x834_60.00"  75.81  1112 1168 1288 1464  834 835 838 863  -HSync +Vsync
> xrandr --addmode VIRTUAL1 1112x834_60.00
> xrandr --output VIRTUAL1 --mode 1112x834_60.00
> # check if everything is in order
> xrandr

Now you should be able to configure this monitor in your system setting like a regular second monitor and for example set its position relative to your primary monitor.

After setting up the virtual monitor start Weylus and select it in the capture menu. You may want to enable displaying the cursor in this case. That is it!

Dummy Plugs

Weylus detects if you use multiple monitors and you can select the one you want to mirror. So if you want to use Weylus as a second screen you could just buy another monitor. Obviously this is pointless as if you already bought that monitor, there is no need to use Weylus! This is where so called HDMI/Displayport/VGA Dummy Plugs come in handy. These are small devices that pretend to be a monitor but only cost a fraction of the price of an actual monitor.

Once you have bought one and plugged it into your computer you can configure an additional screen just like you would do with an actual one and then use Weylus to mirror this virtual screen.

Other Options

The following is untested/incomplete, feel free to do more research and open a pull request to expand documentation on this!

• On Wayland with sway there is create_output which can be used to [create h