Developers - SebastianPfliegel/libratbag GitHub Wiki

Things to know

Almost everything related to libratbag has to run as root to access the hidraw device nodes, create a DBus service, etc. You can work around this by changing permissions but this documentation will just assume you're running as root.

Debugging with ratbagctl.devel

This helper tool is a python wrapper around ratbagd.devel, a custom ratbagd that uses the git sha in the dbus name to avoid clashes with the system-wide ratbagd. ratbagctl.devel starts that ratbagd, runs the command and terminates it again after. This allows for quick testing without requiring install/restart service cycles. Use ratbagctl.devel in the same way as ratbagctl, e.g. sudo ./build/ratbagctl.devel info event20.

The --keepalive commandline argument keeps ratbagd.devel running after issuing the command, allowing other tools to connect to this temporary instance. The dbus name is printed on the commandline, e.g.

> sudo ./build/ratbagctl.devel --keepalive list
event20:   Logitech Gaming Mouse G303      
event7:    Logitech G500s Laser Gaming Mouse
test_device: Test device                     

export RATBAGCTL_DEVEL="org.freedesktop.ratbag_devel1_55670ea"

Appending -v, -vv, -vvv etc. passes down the verbosity level to ratbagd and is useful for debugging raw messages. Adding extra vs increases verbosity.

> sudo ./build/ratbagctl.devel -vv list        
ratbag debug: driver match found: Test driver
test_device: "Test device", 4 profiles
ratbag debug: Logitech Gaming Mouse G303 is device '/dev/hidraw3'.
ratbag debug: Logitech Gaming Mouse G303 is device '/dev/hidraw4'.
ratbag debug: report ID 01
ratbag debug: report ID 03
ratbag debug: report ID 04
ratbag debug: report ID 10
ratbag debug: report ID 11
ratbag debug: 'Logitech Gaming Mouse G303' is using protocol v4.2
ratbag debug: device has adjustable dpi
...

Debugging with ratbag-command

This helper tool is a python wrapper around the libratbag (static) library itself. Because it skips the DBus intermediate layer, it is useful when adding new features to the library or when debugging potential bugs in the DBus layer. Its arguments are the same as the ones from ratbagctl, use --help to get a list of supported arguments.

> sudo ./build/ratbag-command list