libratbag/piper

GTK application to configure gaming devices

Piper

Piper is a GTK+ application to configure gaming mice. Piper is merely a graphical frontend to the ratbagd DBus daemon, see the libratbag README for instructions on how to run ratbagd.

If you are running piper from git, we recommend using libratbag from git as well to make sure the latest bugfixes are applied.

Supported Devices

Piper is merely a frontend, the list of supported devices depends on libratbag. See the libratbag device files for a list of all known devices. The device-specific protocols usually have to be reverse-engineered and the features available may vary to the manufacturer's advertized features.

Screenshots

And if you see the mousetrap, something isn't right. Usually this means that either ratbagd is not running (like in this screenshot), ratbagd needs to be updated to a newer version, or some other unexpected error occured.

Installing Piper

See our Wiki for how to install Piper.

Building Piper from git

Piper uses the meson build system. Run the following commands to clone Piper and initialize the build:

git clone https://github.com/libratbag/piper.git
cd piper
meson builddir --prefix=/usr/

To build or re-build after code-changes and install, run:

ninja -C builddir
sudo ninja -C builddir install

Note: builddir is the build output directory and can be changed to any other directory name.

See our Wiki for what to do when you encounter missing dependencies.

Contributing

Yes please. It's best to contact us first to see what you could do. Note that the devices displayed by Piper come from libratbag.

For quicker development iteration, there is a special binary piper.devel that uses data files from the git directory. This removes the need to install piper after every code change.

ninja -C builddir
./builddir/piper.devel

Note that this still requires ratbagd to run on the system bus.

Piper tries to conform to Python's PEP8 style guide using the black formatter. Checking if code is formatted is done as a part of the test suite.

You can check if your code passes tests before submitting changes using the following command:

meson test -C builddir

Source

git clone https://github.com/libratbag/piper.git

Bugs

Bugs can be reported in the issue tracker on our GitHub repo: https://github.com/libratbag/piper/issues

License

Licensed under the GPLv2. See the COPYING file for the full license information.

piper's Issues

LED capability check needed

One of the LEDs on my G303 apparently cannot be set to breathing, but piper exposes that option. We should grey out that button if the cap isn't there.

This isn't a piper bug just yet, libratbag doesn't expose this option

ButtonDialog should allow the user to set timeouts

Making this into a separate issue so that I can fix it after #47 is merged, as a feature on its own.

This will probably take the form of a checkbox in the capture page, that will then make the button dialog track the interval within key events.

Drop all indices from the GUI

E.g. "LED X: ", or the number of the resolution in the list, etc. None of this is interesting to the user, except for profiles perhaps because we need the index to differentiate those.

Ratbagd bindings need unit tests

This should be easier after libratbag/libratbag#218, so now is the time to write tests.

Resolution sliders need stops and reasonable ranges

Comment from @hadess during GUADEC when I demoed it: the resolution sliders should have increments and snap to those (e.g. every 50 or 100 dpi).

Also, the resolution range can be capped to a resonable range, if we don't expect anyone to set 12000 dpi, we shouldn't display it.

crash due to lack of compatibility with ratbag

commit ff3730f3fba7dc9e4660fe841097d4f1fe1793e8 in ratbag changed naming convention.

piper/init.py line 172 and line 177 contain description instead of name. Replacing those lines prevents crash if device is not recognized. There might be more examples of such incompatibility in the code.

after installing, libratbag, ratbagd and piper, when I run piper nothing happens

What information would you like me to give you for this issue?

404.svg needs to be symbolic

This way we can more closely match the empty state design pattern in various perspectives and dialogs.

Control widgets should have tooltips to explain their purpose

As per the title.

Resolutions page needs a way to set a profile's default resolution.

The mockups left this out, so this isn't yet decided.

@whot suggested a check mark next to the delete button (functioning like a radio button, e.g. only one can be selected at any given time) or an "advanced" popup menu that has the check mark in there, and if supported by the device also exposes the scale for the y-resolution. My personal preference would be the former, but let's open a discussion on this.

Highlight active resolution

as $SUBJECT

Handle device disconnects

If there are no configurable devices left, display the error perspective saying as such. If there are one or more devices left, display the welcome perspective.

Align the SVGs in the welcome perspective

See #84 (comment).

ButtonDialog should allow capturing button presses and releases as well

Create a Flatpak including libratbag and ratbagd

Hello,

@whot asked me to look into creating a Flatpak of Piper which includes libratbag and ratbagd. This issue is meant to track required items. I will edit this post to add items as I go; other findings will be added as comments.

RUNTIME: we will require GNOME's runtime as we require GLib and GTK+ for Piper. Versions generally don't matter, but we need to see what version of GTK+ we want to use. Newer versions have fancier widgets, but this might limit availability in distributions like Debian when Piper is installed without Flatpak.

TODO:

• Make libratbag, ratbagd and Piper build systems compliant with the Build API as required for flatpak-builder
  • libratbag
  • ratbagd
  • Piper
• AppData file for Piper (optional)
• All files exported from the Flatpak need to have the application ID as their prefix. We can either rename the relevant source files or use flatpak-builder to rename the files at build time. My preference would be the former to keep it simple.
  • Desktop file
  • Application icon
  • ratbagd.service.in (not sure how this works with an org.freedesktop.ratbagd ID in the Flatpak for Piper with org.freedesktop.Piper yet)

Packaging PIPER as Snap app

I’ve read the comments on the issue #5.
As far as I know, snap packaging system can already overcome those issues.

As the next ubuntu release will ship with gnome and snap apps can be installed in the majority of the distros, I’d suggest to try the snap apps...

Here is an example of a meson app for reference: https://github.com/snapcore/snapcraft/tree/0a62dc065b033e84925198e25fcba775a833e0ba/integration_tests/snaps/meson-hello

And here the interfaces of the snap apps:
https://snapcraft.io/docs/reference/interfaces

piper crashes when no devices are available

Start ratbagd without any devices plugged in, watch piper crash and burn. What a spectacle! I'll go get popcorn :)

Running from source tree, using local files
Could not find any devices. Do you have anything vaguely mouse-looking plugged in?
Traceback (most recent call last):
  File "/home/whot/code/ratbag/piper/piper/application.py", line 52, in do_activate
    window = Window(self._ratbag, application=self)
  File "/home/whot/code/ratbag/piper/piper/window.py", line 57, in __init__
    capabilities = self._device.capabilities
AttributeError: 'NoneType' object has no attribute 'capabilities'

Handle device connects

if the user is in the welcome screen, simply add it to the list. If the user is in the error perspective, switch to the welcome perspective. Otherwise, simply make the back button visible if it wasn't already.

Possibly an in-app notification can be added to tell the user his device has been recognized.

The Off page in the LED dialog needs an image

It needs an image according to the empty states guidelines, see also https://wiki.gnome.org/Design/OS/EmptyStates

Highlighting LEDs changes their z-stacking

Visible with the SVG in libratbag/libratbag#228

In an svg, elements' z stacking order determines whether they are visible and what parts of them are. A common trick for drawings (especially for lazy people) is to simply let something be obscured by another element instead of having to perfectly line up the edges. In the G303 drawing in pull request libratbag/libratbag#228 this is the case for the left LED - the top of it is hidden by the button.

Highlighting that LED seems to change the z-stacking order, causing the element to appear above the button that should otherwise obscure it.

Allow setting profile names

Not yet in libratbag, but once it does we should support it. See libratbag/libratbag#275.

piper won't start

In Ubuntu Artful i get this error in terminal:

$ piper
Traceback (most recent call last):
File "/usr/bin/piper", line 32, in
from piper.application import Application
ModuleNotFoundError: No module named 'piper'

changing a resolution should not change the active one

When testing a device that has resolution 2 active, changing any other resolution in the Resolution panel and committing to the device changes the active resolution back to the first one (0).

I do not have this behavior with ratbagctl so I guess piper must be overwriting the active resolution...

ButtonDialog should also work with key release

Making this into a separate issue so that I can fix it after #47 is merged, as a feature on its own.

Add a back button to the MousePerspective if there are > 1 devices

Depends on #84 to be merged first.

Piper should check a device's capabilities before exposing configuration

In #35 I added a check for RatbagdDevice.CAP_RESOLUTION and RatbagdDevice.CAP_LED before adding the resolutions and led page respectively.

The resolutions page should probably also check for RatbagdDevice.CAP_SWITCHABLE_RESOLUTION and only expose the list when it is set, or something like that. @whot What do you think?

Save button is not obvious

Comment from @hadess when I showed him piper at GUADEC: the save button to actually write to the mouse is not obvious enough, needs to be differently placed.

Confirm before exiting with uncommitted changes

As pointed out by @hadess in #69:

• Ask the user whether to apply all the settings to the mouse before exiting (same pattern as when you exit gedit with an unsaved file)
• Add a preference to automatically save to the mouse when exiting (default to yes?)

I definitely want to implement the first; I'm not sure if the second is worth it.

Don't allow unsetting the left button

If we map current logical left button to anything else, map another button to left instead. Default approach: search for the right button and swap it. Otherwise pick some random button (?).

We don't want to end up without a left button

Make the buttons in the SVG clickable for configuration

Another comment from @hadess at GUADEC: make the buttons clickable for configuration, instead of requiring the user to click on the buttons. Suggested approach was using a colormap for picking.

Remove "Resolution 0" labels from the resolution list

Superfluous, the DPI and the delete button are enough.

Same applies to the "Resolution" label just above the slider, we should remove that.

Bindings should share the same DBus connection

From #10:

One thing I did notice is that every Ratbagd* class instantiates a new DBus connection by inheriting from _RatbagdDBus. It seems unnecessary to me to have one DBus connection for each profile, resolution, button, et cetera. Is this design intentional or is this something we can/should improve?

It's not really a problem, just inefficient.

piper crash when ratbagd isn't available

When ratbagd isn't running, piper crashes instead of showing me a nice dialog. This is commit afdadb6 on your buttons branch

$> n install && /opt/libratbag/bin/piper 
[0/1] Installing files.
Installing subdir /home/whot/code/ratbag/piper/piper to /opt/libratbag/lib/python3.6/site-packages
Installing data/piper.gresource to /opt/libratbag/share/piper/piper.gresource
Installing /home/whot/code/ratbag/piper/data/org.freedesktop.Piper.desktop to /opt/libratbag/share/applications
Installing /home/whot/code/ratbag/piper/data/org.freedesktop.Piper.svg to /opt/libratbag/share/icons/hicolor/scalable/apps
Installing /home/whot/code/ratbag/piper/build/piper to /opt/libratbag/bin
Running custom install script '/usr/bin/env sh /home/whot/code/ratbag/piper/meson_install.sh'
gtk-update-icon-cache: Cache file created successfully.
Traceback (most recent call last):
  File "/opt/libratbag/lib/python3.6/site-packages/piper/application.py", line 53, in do_activate
    window = Window(self._ratbag, application=self)
  File "/opt/libratbag/lib/python3.6/site-packages/piper/window.py", line 51, in __init__
    self._device = self._fetch_ratbag_device()
  File "/opt/libratbag/lib/python3.6/site-packages/piper/window.py", line 67, in _fetch_ratbag_device
    if len(self._ratbag.devices) == 0:
AttributeError: 'NoneType' object has no attribute 'devices'

displaying the scale for changing the resolution can be masked

Clicking on resolution 4, at the end of the list often pops up the resolution scale to interact outside of the current view.

The user needs to scroll down to access it, which is counter intuitive.

We need to make sure the scale is always visible after a click by moving all the rest up (with an animation if possible, or @jimmac is going to complain).

Improve keyboard support

There is no keyboard support for navigating lists or switching stack pages and the like. We should probably add that at some point, especially in case you mess up your only device and need the keyboard to fix it :)

Logitech G602 - Piper/libratbag Problem

Installed Piper from Aur, all fine.

Started ratbagd and got this:
ratbagd.service - Daemon to introspect and modify configurable mice
Loaded: loaded (/usr/lib/systemd/system/ratbagd.service; enabled; vendor preset: disabled)
Active: failed (Result: core-dump) since Tue 2017-08-08 18:20:17 CEST; 1min 56s ago
Process: 18686 ExecStart=/usr/bin/ratbagd (code=dumped, signal=SEGV)
Main PID: 18686 (code=dumped, signal=SEGV)

ratbagd.service: Unit entered failed state.
ratbagd.service: Failed with result 'core-dump'.
ratbagd.service: Service hold-off time over, scheduling restart.
Stopped Daemon to introspect and modify configurable mice.
ratbagd.service: Start request repeated too quickly.
Failed to start Daemon to introspect and modify configurable mice.
ratbagd.service: Unit entered failed state.
ratbagd.service: Failed with result 'core-dump'.

After I restarted my computer and got no error. Ratbagd is running. sudo ratbagd and I can see some mouse related infos like battery percent and a few other things:

ratbag debug: Logitech USB Receiver is device '/dev/hidraw3'.
ratbag debug: Logitech USB Receiver 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: report ID 80
ratbag debug: 'Logitech USB Receiver' is using protocol v2.0
ratbag debug: device battery level is 50% (next 20%), status 0
ratbag debug: device has adjustable dpi
ratbag error: HID++ error from the device (1): ERR_INVALID_ADDRESS (02)
ratbag error: Error while requesting resolution: Protocol error (-71)
ratbag debug: device has adjustable report rate
ratbag debug: device has color effects
ratbag error: HID++ error from the device (1): ERR_INVALID_ADDRESS (02)
Speicherzugriffsfehler (Speicherabzug geschrieben)

The wireless G602 should be working. ID 046d:c537 Logitech, Inc, it´s in the hwdb.

Don´t know what´s wrong here.

Running Manjaro and installed from AUR

Switch active resolution on resolution adjustments

When we click on a resolution and start changing it, we should switch to that resolution so that the user sees the effects once the auto-apply runs in the background.

install instructions

Hello

Can you provide some install instructions for ubuntu please?

I've done python setup.py build, python setup.py install.

But I'm getting:

ImportError: No module named 'ratbagd'

When I run it.

Piper's ratbagd bindings need a `RatbagdLED` class

This is required to support configuration of LEDs.

Use `*_by_func` instead of shuffling handler ids around

Just found these functions, they're a lot easier to use than remembering handler ids and using those.

disconnect_by_func, handler_block_by_func.

Add search field to button mapping dialog

Above the long list of mapable button, let's add a search field. Blame @jimmac for the suggestion :)

Fix the ResolutionsPage to show the button that switches resolutions

This was lost when ratbagd switched to enums. It's just a matter of changing one line to match with the correct enum value instead of a string value.

Make it possible to run piper from the source tree

./build/piper should just work without any further setup. Since that requires some extra bits to load the module path or at least set up the path, might be easier to just provide a ./build/piper.devel script that mangles everything into place as required.

Do not crash if ratbagd is not loaded

With the new dbus activation, users are still required to call systemctl enable ratbagd.service before being able to launch piper.
If this step has not been completed, piper crashes with GLib.Error: g-io-error-quark: Error calling StartServiceByName for org.freedesktop.ratbag1: GDBus.Error:org.freedesktop.systemd1.LoadFailed: Unit dbus-org.freedesktop.ratbag1.service failed to load: No such file or directory. (36).

It would be good to catch the exception and present a message to the user that there are some configuration commands that needs to be run.

Add support for translations

There isn't much to translate yet, but we should support for this at one point in time. This comes down to adding the necessary changes in Meson and adding a po directory.

ButtonsPage displays macros as their integer keycodes

I couldn't test this before, but I just noticed it with the test device from running ratbagd.devel: the buttonspage displays macros using their integer keycodes. This is easily solved by copying the code from KeyStroke::_update_macro, but that results in (unnecessary?) duplication.

I was thinking of adding a (possibly static) method to RatbagdButton to get the human-readable string representation of the macro, if it is mapped to a macro. What are your thoughts on this? Tagging @whot and @bentiss

XML error during install

When trying to install piper, ninja gives the following error

XMLLINT not set and xmllint not found in path; skipping xml preprocessing.

Profile cycle buttons must apply across all profiles

If we assign a button to profile cycle up or some other profile switching, that mapping must be assigned across all profiles. Otherwise clicking the same button will eventually land you in a profile with no way out.

Long time when switching profiles

Playing with the G700 and switching between profiles introduces an ever growing timeout between the actual action on the profile switch button (going from profile0 to profile1) and the update on the screen.

I set the G700 profile 0 to a refresh rate of 125, which outputs an error on piper terminal when we retrieve this profile:

• at launch (profile 0 selected): 1 "Ooops, rate is 125 and I don't know how to deal with that." is displayed
• going to profile1 is immediate
• going back to profile 0, 2 "Ooops..." are displayed
• going to profile 2 takes few seconds
• going back to profile 0, 6 "Ooops..." are displayed
• etc...

Looks like we forget to clean up after a profile has been loaded or we need to use a caching mechanism in piper

Ratbag bindings should have proper enums

Going to do this once all different PRs that have binding changes are in.