## 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](https://github.com/libratbag/libratbag/blob/master/README.md#running-ratbagd-as-dbus-activated-systemd-service) 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](https://github.com/libratbag/libratbag/tree/master/data/devices) 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](https://github.com/libratbag/piper/wiki/Installation) for how to install Piper. Building Piper from git ======================= Piper uses the [meson build system](http://mesonbuild.com/). Run the following commands to clone Piper and initialize the build: ```sh 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: ```sh 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](https://github.com/libratbag/piper/wiki/Installation) 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. ```sh 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: ```sh meson test -C builddir ``` Source ====== ```sh 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](https://github.com/libratbag/piper/blob/master/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](https://github.com/libratbag/piper/issues/48), which includes links to examples). As such, please make sure that you align the elements appropriately; [this comment](https://github.com/libratbag/piper/issues/48#issuecomment-315979109) 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](https://github.com/libratbag/piper/issues/new). New or updated translations are always welcome. To start a new translation, run: $ 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](https://github.com/libratbag/piper/blob/master/po/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: $ 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](https://github.com/libratbag/piper) or, if you don't know how to, [open an issue](https://github.com/libratbag/piper/issues/new) and attach the `.po` file there.