Creating a virtual device

Make sure you've set up relabsd before continuing.

There should be an executable at build/relabsd. It will in all likelihood require root privileges to be able to operate.

Finding the physical device

The first step is to know what physical device relabsd is intended to work on. On POSIX systems, the physical device is represented by a file (likely in /dev/input/). If you are having trouble finding which file is your device, you can use:

$ cat /proc/bus/input/devices

The Handlers= part should tell you which /dev/input/event is for your device.

Your device might not be in /dev/input/ at all though. If you are using a 3DConnexion device, you should check out this wiki page, as it contains instructions on how to create a symbolic link to your device in /dev/input/, making it a lot easier to find. A possible alternative is mentioned in https://github.com/nsensfel/relabsd/issues/2.

If you are planning on using a mouse, you might want to tell your device manager to stop considering it as a mouse while it is used by relabsd, because otherwise the virtual device will also be considered to be a mouse, as it is a clone of the real device (it can be slightly annoying).

You can use # ./build/relabsd -? device_file_name to print information on the device file name.

Future feature (not implemented yet)

By running # ./build/relabsd -?, you can list all the compatible input devices.

Finding the configuration file

If your are lucky, the configuration file for your device has already been written and can be found in conf/. Otherwise, you'll have to create your own configuration file (and maybe share it?) according to the syntax described in this wiki page. Use the # ./build/relabsd -? device_file_name to list the axes that can be configured.

Running relabsd

There are multiple ways to run relabsd. Bear in mind that any virtual device created by relabsd has a name prefixed by "relabsd: " (or whatever you configured as RELABSD_DEVICE_PREFIX), even if you changed through an invocation parameter. This is to make it easier to identify (by you AND by the device manager).

Simple / Legacy

If you just want to test out a configuration file, you might not care to set up a complex relabsd instance. There are two shortcuts to use relabsd:

• You can run # ./build/relabsd device_file_name config_file to run a relabsd instance for device_file_name with the configuration in config_file.
• You can also change the name of the device using # ./build/relabsd device_file_name config_file virtual_device_name.

Note that these will not create a daemon process.

Advanced

Run # ./build/relabsd for a complete list of all options. If you are interested in a more complex use of relabsd, the following modes are available:

Compatibility test mode

Using # ./build/relabsd -? device_file_name you can find out about information about the device's compatibility with relabsd. This command will return:

• 2 if the device has relative axes and the requested virtual device configuration is compatible.
• 1 if the device has relative axes and the configuration is not compatible.
• 0 if the device has no relative axes (not compatible).
• -1 on error.

Independent mode

This is the equivalent to simple / legacy mode, except that it still allows for the options to be used. # ./build/relabsd -1 device_file_name will create an independent instance of relabsd. For reference, the aforementioned simple legacy mode commands translate to:

• # ./build/relabsd device_file_name config_file -> # ./build/relabsd -1 device_file_name -f config_file
• # ./build/relabsd device_file_name config_file virtual_device_name -> # ./build/relabsd -1 device_file_name -f config_file -n virtual_device_name If you choose to create a daemon using this mode (-d option), you will have to send a signal to close relabsd (or disconnect the physical device).

Client & Server mode

If you want to later be able to control a relabsd instance, you will have to use this mode. Here, an UNIX socket is created to allow for commands to be sent to the relabsd process. ./build/relabsd -s socket_file_name device_file_name will create the server instance using socket_file_name as the communication socket. For those unfamiliar with UNIX sockets, this means that a socket_file_name file will be created so that other programs can use the socket by referencing to the file. ./build/relabsd -c socket_file_name will pass the commands given as parameters to the corresponding server process. It should be noted that modifying the virtual device in any way other than changing the timeout option will result in the virtual device being destroyed and re-created, which may lead to issues if it is currently used by an application. Also, the timeout option only takes effect after the next input from the physical device.