piper Documentation

File: README.md

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.

File: data/svgs/README.md

libratbag gnome theme

Requirements

See the Logitech G403 for an example of a device with a small amount of buttons,
and the Logitech G700 for an example of a device with a large amount of buttons.

Canvas size should be between 400x400 and 500x500 pixels.
Three layers in the final SVG:
1. a lower layer named "Device" with the device itself. Each button on the
  device should have an id buttonX, with X being the number of the button
  (so for button 0 the id would be button0). Similarly, each LED on the device
  should have an id ledX.
2. a middle layer named "Buttons" with the button leaders (see below for
  leaders).
3. an upper layer named "LEDs" with the LED leaders.
A leader line is a path that extends from the button or LED to the left or the
right of the device (see below). Each leader line requires the following:
- It should start with a 7x7 square placed on or close to the button or LED
  that it maps with.
- From this square, a path should extend left or right (see below).
- Each path should end with a 1x1 pixel with identifier buttonX-leader (or
  ledX-leader), where X is the number of the button (or LED) with
  which the leader maps. For button 0, this would be button0-leader.
- All these elements should be grouped and given the identifier buttonX-path
  (or ledX-path for LEDs)
Leader lines should have a vertical spacing of at least 40 pixels. When there
are several leader lines above and below each other, make the spacing between
them equal.
If the device's scroll wheel supports horizontal tilting, add two small arrows
left and right of the scroll wheel with the respective button identifiers (see
the Logitech G700 for an example). Do not cut the scroll wheel in half
vertically to map these buttons.
If there aren't too many buttons, preferably make the leaders point to the
right with the device itself placed on the left. If the buttons would extend
below or above the device, make some point to the left instead with the device
itself centered in the middle. In this case, half of the leaders should extend
to the left and the other half to the right.
When a leader points to the right, its 1x1 pixel should have a style property
text-align:start. When a leader points to the left, its 1x1 pixel should
have a style property text-align:end.
The canvas should be resized so that there is a 20px gap between the device
and the edge of the canvas and no gap between the 1x1 pixels and the canvas.

Please note that due to the way the SVG is drawn, you cannot rely on the
z-ordering of elements to line up or cover elements (as noted in this
issue, which includes links to
examples). As such, please make sure that you align the elements appropriately;
this
comment
includes some helpful tips.

Technique

The simplest approach is to find a photo of the device and import it into
inkscape. Put it on the lowest layer, create a new layer "Device" above it
and start tracing the outlines and edges of the device. Fill in the shapes
and your device should resemble the underlying photo. Delete the photo
layer, add leaders in their respective layers and you're done.

Make sure the image looks ''toned-down'' and not realistic. Do not use dark or
bright colors.

File: po/README.md

i18n

This directory contains the translations of Piper.

For errors in translations, please file an
issue.

New or updated translations are always welcome. To start a new translation, run:

text

$ meson translation-build
$ ninja -C translation-build piper-pot
# Now you can optionally remove the build directory
$ rm -rf translation-build
$ cp po/piper.pot po/$lang.po

where $lang is the language code of your target language, e.g. nl for Dutch
or en_GB for British English. Edit the
LINGUAS file and
add your language code, keeping the list sorted alphabetically. Finally, open
the .po file you just created and translate all the strings. Don't forget to
fill in the information in the header!

To update an existing translation, run:

text

$ meson translation-build
$ ninja -C translation-build piper-update-po
# Now you can optionally remove the build directory
$ rm -rf translation-build

and update the po/$lang.po file of your target language.

When you are done translating, file a pull request on
GitHub or, if you don't know how to, open
an issue and attach the .po
file there.

File: README.md Copy Chapter