### Build and Install

Source: https://github.com/libratbag/libratbag/wiki/contributing/Building-from-source

Compiles the libratbag project using ninja and installs it to the system. This command should be run after initializing the build.

```bash
ninja -C builddir
sudo ninja -C builddir install
```

--------------------------------

### Install libratbag on Fedora

Source: https://github.com/libratbag/libratbag/wiki/Installation

Use this command to install libratbag on Fedora systems.

```bash
dnf install libratbag-ratbagd
```

--------------------------------

### Start Ratbagd Service

Source: https://github.com/libratbag/libratbag/wiki/Usage

To start a new ratbagd service, first kill any existing instances and then launch it with the --verbose flag. This is typically done when building from source.

```bash
> sudo killall ratbagd # kill any current running daemons
> sudo /usr/local/bin/ratbagd --verbose
or 
> sudo /usr/sbin/ratbagd --verbose
```

--------------------------------

### Install Dependencies with apt

Source: https://github.com/libratbag/libratbag/wiki/contributing/Building-from-source

Installs the necessary development libraries for building libratbag on Debian-based systems. Ensure your system is up-to-date before running.

```bash
sudo apt install cmake libudev-dev libevdev-dev libsystemd-dev libglib2.0-dev libjson-glib-dev libunistring-dev check valgrind swig
```

--------------------------------

### Install libratbag on Arch Linux

Source: https://github.com/libratbag/libratbag/wiki/Installation

Use this command to install libratbag on Arch Linux systems.

```bash
pacman -S libratbag
```

--------------------------------

### Configure libratbag Build Options

Source: https://github.com/libratbag/libratbag/blob/master/README.md

Example of setting configure-time options for the meson build system, such as disabling documentation. Use 'meson configure builddir' to list available options.

```bash
meson configure builddir -Ddocumentation=false
```

--------------------------------

### Install ratbagd on Debian/Ubuntu

Source: https://github.com/libratbag/libratbag/wiki/Installation

Use this command to install the ratbagd service on Debian (10+) and Ubuntu (18.04+) systems.

```bash
apt install ratbagd
```

--------------------------------

### Clone and Compile libratbag

Source: https://github.com/libratbag/libratbag/blob/master/README.md

Commands to clone the libratbag repository, initialize the build with meson, and compile using ninja. The default installation prefix is /usr/local.

```bash
git clone https://github.com/libratbag/libratbag.git
cd libratbag
meson builddir
ninja -C builddir
sudo ninja -C builddir install
```

--------------------------------

### Build with Custom Prefix

Source: https://github.com/libratbag/libratbag/wiki/contributing/Building-from-source

Builds and installs libratbag to a custom prefix, typically used to overwrite a system installation. Ensure you remove the system package first.

```bash
meson builddir --prefix=/usr
ninja -C builddir
sudo ninja -C builddir install
```

--------------------------------

### Get Device Information with ratbagctl

Source: https://github.com/libratbag/libratbag/wiki/ratbagctl

The 'info' command displays detailed information about a specific device, including its profiles, buttons, LEDs, and resolution settings. Device names can be matched by substring and should be quoted if they contain spaces.

```bash
$ ratbagctl "Logitech MX Anywhere 2S" info
hidraw4 - Logitech MX Anywhere 2S
               SVG: logitech-mx-anywhere2.svg
 Number of Buttons: 8
    Number of Leds: 0
Number of Profiles: 1
Profile 0: (active)
  Name : 'Profile 1'
  Resolutions:
    0: 1000dpi @ 0Hz (active)
  Button: 0 type left is mapped to 'button 1'
  Button: 1 type right is mapped to 'button 2'
  Button: 2 type middle is mapped to 'button 3'
  Button: 3 type side is mapped to 'button 4'
  Button: 4 type extra is mapped to 'button 5'
  Button: 5 type wheel-left is mapped to 'wheel-left'
  Button: 6 type wheel-right is mapped to 'wheel-right'
  Button: 7 type unknown is mapped to none
```

--------------------------------

### Debugging ratbagd.devel Manually

Source: https://github.com/libratbag/libratbag/wiki/Developers

Manually start ratbagd.devel for debugging with gdb. Use --verbose=raw for raw message output. Connect to this instance using ratbagctl.devel with --use-existing-ratbagd.

```bash
sudo ./build/ratbagd.devel --verbose=raw
```

```bash
sudo ./build/ratbagctl.devel --use-existing-ratbagd list
```

--------------------------------

### Get and Set DPI Settings with ratbagctl

Source: https://github.com/libratbag/libratbag/wiki/ratbagctl

Use 'get' and 'set' commands to query and modify DPI settings for a specific profile and resolution. If the active profile and resolution are not specified, ratbagctl defaults to the currently active ones.

```bash
$ ratbagctl "Logitech MX Anywhere 2S" profile 0 resolution 0 dpi get
1000
```

```bash
$ ratbagctl "Logitech MX Anywhere 2S" profile 0 resolution 0 dpi set 800
```

```bash
$ ratbagctl "Logitech MX Anywhere 2S" profile 0 resolution 0 dpi get
800
```

```bash
$ ratbagctl "Logitech MX Anywhere 2S" dpi get
800
```

```bash
$ ratbagctl "Logitech MX Anywhere 2S" dpi set 1000
```

```bash
$ ratbagctl "Logitech MX Anywhere 2S" dpi get
1000
```

--------------------------------

### Debug Ratbagd with ratbagctl.devel

Source: https://github.com/libratbag/libratbag/wiki/Usage

Use `ratbagctl.devel` from the build directory to test and debug ratbagd. This command starts a one-shot ratbagd on a custom D-Bus interface without conflicting with existing services.

```bash
> sudo ./builddir/ratbagdctl.devel --verbose event9 info
```

```text
event9 - Logitech G500s Laser Gaming Mouse
               SVG: logitech-g500.svg
      Capabilities: query-configuration, resolution, switchable-resolution, profile, switchable-profile, disable-profile, button, button-keys, button-macros
 Number of Buttons: 13
    Number of Leds: 0
Number of Profiles: 1
Profile 0: (active)
  Name : ''
  Resolutions:
    0: 800x800dpi @ 500Hz (active)
    1: 1000x1000dpi @ 500Hz (default)
    2: 2000x2000dpi @ 500Hz
    3: 5500x5500dpi @ 500Hz
    4: 8200x8200dpi @ 500Hz
  Button: 0 type left is mapped to 'button 1'
  Button: 1 type middle is mapped to 'button 2'
  Button: 2 type right is mapped to 'button 3'
  Button: 3 type thumb is mapped to UNKNOWN
  Button: 4 type thumb2 is mapped to UNKNOWN
  Button: 5 type thumb3 is mapped to 'button 6'
  Button: 6 type wheel-left is mapped to 'wheel-left'
  Button: 7 type wheel-right is mapped to 'wheel-right'
  Button: 8 type resolution-up is mapped to 'resolution-up'
  Button: 9 type resolution-down is mapped to 'resolution-down'
  Button: 10 type unknown is mapped to 'button 11'
  Button: 11 type unknown is mapped to 'button 12'
  Button: 12 type unknown is mapped to none
```

--------------------------------

### Debugging with ratbagctl.devel

Source: https://github.com/libratbag/libratbag/wiki/Developers

Use ratbagctl.devel to test libratbag without restarting the system service. It starts a temporary ratbagd instance. Use --keepalive to keep the instance running after the command.

```bash
sudo ./build/ratbagctl.devel event20 info
```

```bash
sudo ./build/ratbagctl.devel --keepalive list
```

```bash
sudo ./build/ratbagctl.devel -vv list
```

--------------------------------

### Get device information with ratbagctl

Source: https://github.com/libratbag/libratbag/wiki/devices/G600

Use this command with your device name to retrieve detailed information, including the total number of physical buttons. This is crucial for understanding your mouse's capabilities before configuring G-Shift.

```bash
ratbagctl "Logitech Gaming Mouse G600" info
```

--------------------------------

### Uninstall libratbag

Source: https://github.com/libratbag/libratbag/blob/master/README.md

Command to uninstall libratbag using ninja. This will remove the installed files.

```bash
sudo ninja -C builddir uninstall
```

--------------------------------

### Get Verbose USB Device Information

Source: https://github.com/libratbag/libratbag/wiki/Adding-a-device

Retrieve detailed information about a specific USB device using its vendor and product ID with `lsusb -d <vendor>:<product> --verbose`. Running this command with `sudo` provides all available information.

```bash
sudo lsusb -d 195d:2030 --verbose
```

--------------------------------

### Get button action with ratbagctl

Source: https://github.com/libratbag/libratbag/wiki/devices/G600

Retrieve the current action assigned to a specific button. Replace `$N` with the button's ID. This helps in verifying existing configurations before making changes.

```bash
ratbagctl "Logitech Gaming Mouse G600" button $N action get
```

--------------------------------

### Create Minimal Device Data File

Source: https://github.com/libratbag/libratbag/wiki/Adding-a-new-device

Create a basic `.device` file for your new hardware. The `DeviceMatch` entry must correspond to the USB ID observed during device detection.

```bash
$ sudo cat > /usr/share/libratbag/logitech-mx-anywhere-2s.device <<EOF
[Device]
Name=Logitech MX Anywhere 2S
DeviceMatch=usb:046d:406a
EOF
```

--------------------------------

### Clone and Initialize Build

Source: https://github.com/libratbag/libratbag/wiki/contributing/Building-from-source

Clones the libratbag repository from GitHub and initializes the build directory using meson. This prepares the project for compilation.

```bash
git clone https://github.com/libratbag/libratbag.git
cd libratbag
meson builddir
```

--------------------------------

### Debug HID++ Communication

Source: https://github.com/libratbag/libratbag/wiki/Adding-a-new-device

Run ratbagd with the updated device file and observe the HID++ communication. An `ERR_UNSUPPORTED` error may indicate the device is in a power-saving state.

```bash
$ sudo /usr/bin/ratbagd.disabled --verbose=raw
ratbag debug: New device: Logitech MX Anywhere 2S
ratbag debug: Using data directory '/usr/share/libratbag'
ratbag debug: device assigned driver hidpp20
ratbag debug: hidraw info: bus 0x03 vendor 0x46d product 0x406a
ratbag debug: Logitech MX Anywhere 2S is device '/dev/hidraw1'.
ratbag debug: HID report ID 01
ratbag debug: HID report ID 0e
ratbag debug: HID report ID 02
ratbag debug: HID report ID 03
ratbag debug: HID report ID 04
ratbag debug: HID report ID 10
ratbag debug: HID report ID 11
ratbag debug: HID report ID 20
ratbag debug: HID report ID 21
ratbag raw: hidpp write: 11 ff 00 18 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
ratbag raw: hidpp read:  10 01 8f 00 18 09 00
ratbag debug:     HID++ error from the device (1): ERR_UNSUPPORTED (09)
```

--------------------------------

### Native Debug Launch Configuration in launch.json for vscode

Source: https://github.com/libratbag/libratbag/wiki/Debugging

Set up a launch configuration in launch.json for debugging the 'ratbagd' executable natively. This configuration uses the custom GDB script and specifies the 'build' task as a pre-launch task.

```json
{
    // Use IntelliSense to learn about possible attributes. 
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "(gdb) Launch",
            "type": "cppdbg",
            "request": "launch",
            "program": "${workspaceFolder}/builddir/ratbagd",
            "args": ["--verbose=raw"],
            "stopAtEntry": false,
            "cwd": "${workspaceFolder}",
            "environment": [],
            "miDebuggerPath": "${workspaceFolder}/.vscode/gdb",
            "externalConsole": false,
            "MIMode": "gdb",
            
            "setupCommands": [
                {
                    "description": "Enable pretty-printing for gdb",
                    "text": "-enable-pretty-printing",
                    "ignoreFailures": true
                }
            ],
            "preLaunchTask": "build"
        }
```

--------------------------------

### org.freedesktop.ratbag1.Manager Interface

Source: https://github.com/libratbag/libratbag/blob/master/doc/dbus.rst

The org.freedesktop.ratbag1.Manager interface is the entry point to interact with ratbagd.

```APIDOC
## org.freedesktop.ratbag1.Manager

### Description
The org.freedesktop.ratbag1.Manager interface is the entry point to interact with ratbagd.

### Attributes

#### APIVersion
- **type**: i
- **flags**: read-only, constant
- **Description**: The DBus API version. This is a stopgap feature while the DBus API is still in flux. The version has no backwards or forward-compatibility guarantees - your client must understand **exactly** the same version, it is not enough to support an older or a newer version.

#### Devices
- **type**: ao
- **flags**: read-only, mutable
- **Description**: An array of read-only object paths referencing the available devices. The devices implement the :ref:`device` interface.
```

--------------------------------

### List Available Devices with ratbagctl

Source: https://github.com/libratbag/libratbag/wiki/ratbagctl

Use 'ratbagctl list' to see all devices currently recognized by ratbagd. The output format is 'device id: device name'.

```bash
$ ratbagctl list
sobbing-zokor:  Logitech G500s Laser Gaming Mouse
booming mara:   Logitech MX Anywhere 2S 
```

--------------------------------

### List Available Devices

Source: https://github.com/libratbag/libratbag/wiki/Adding-a-new-device

Run this command to check if your device is already recognized by ratbagctl. Ensure ratbagd is not running for accurate results.

```bash
$ ratbagctl list
No devices available.
```

--------------------------------

### LED Configuration

Source: https://github.com/libratbag/libratbag/blob/master/doc/dbus.rst

Configuration properties for LEDs on a device.

```APIDOC
## org.freedesktop.ratbag1.Led

### Index

:type: u
:flags: read-only, constant

Index of the LED.

### Mode

:type: u
:flags: read-write, mutable

Enum describing the current mode, see :attr:`Modes`.

### Modes Enum

:type: au
:flags: read-only, constant

A list of modes supported by this LED.

+-------+-------------------------------------+
| Value | Definition                          |
+=======+=====================================+
|   0   | LED is off                          |
+-------+-------------------------------------+
|   1   | LED is on with constant brightness  |
+-------+-------------------------------------+
|   2   | LED cycles through a set of colors. |
|       | This mode ignores the :attr:`Color` |
|       | values.                             |
+-------+-------------------------------------+
|   3   | LED uses a breathing-style animation|
+-------+-------------------------------------+

In the future, extra values may get added. Clients must ignore unknown Modes.

### Color

:type: (uuu)
:flags: read-write, mutable

32-bit unsigned int triplet (RGB) of the LED's color. Only the least significant bits are valid, the :attr:`ColorDepth` property defines the number of bits for each color. When writing to this property, all bits outside the color depth must be 0.

### ColorDepth

:type: u
:flags: read-only, constant

An enum specifying the color depth of this LED. Permitted values are:

+-------+-------------------------------+ 
| Value | Definition                    |
+=======+===============================+
|   0   | 0 bits per color (monochrome) |
+-------+-------------------------------+
|   1   | 8 bits per color              |
+-------+-------------------------------+ 
|   2   | 1 bit per color               |
+-------+-------------------------------+

In the future, extra values may get added. Clients must ignore unknown ``ColorDepths`` and not manipulate the LED color where the ``ColorDepth`` is unknown.

### EffectDuration

:type: u
:flags: read-write, mutable

The effect duration in ms, possible values are in the range 0 - 10000.

### Brightness

:type: u
:flags: read-write, mutable

The brightness of the LED, normalized to the range 0-255, inclusive. Where the LED supports less than 8-bit of brightness, libratbag maps the value to a device-supported value in an implementation-defined manner.
```

--------------------------------

### Dockerfile for Libratbag Ubuntu Image

Source: https://github.com/libratbag/libratbag/wiki/Dockerfile

This Dockerfile sets up an Ubuntu-based environment with all the necessary build tools and Python dependencies for Libratbag. Change the base image if your system differs.

```Dockerfile
# You can change the image to match your system
# https://hub.docker.com/_/ubuntu
FROM ubuntu:groovy

RUN apt-get update && apt-get upgrade -y && apt-get install -y \
    build-essential \
    manpages-dev \
    bash \
    less \
    vim \
    software-properties-common \
    libssl-dev \
    libffi-dev \
    libudev-dev\
    libevdev-dev\
    libsystemd-dev \
    libglib2.0-dev\
    libjson-glib-dev\
    check \
    valgrind \
    swig \
    libunistring-dev \
    python3 \
    python3-pip \
    python3-dev \
    python3-setuptools \
    python3-wheel \
    ninja-build

RUN python3 -m pip install meson

```

--------------------------------

### Run ratbagd with Raw Verbose Output

Source: https://github.com/libratbag/libratbag/wiki/Adding-a-new-device

Execute the disabled ratbagd with raw verbose logging to observe device detection and initial data. This helps in identifying device IDs and potential issues.

```bash
$ sudo /usr/bin/ratbagd.disabled --verbose=raw
ratbag debug: New device: Logitech MX Anywhere 2S
ratbag debug: Using data directory '/usr/share/libratbag'
ratbag debug: No data file found for 046d:406a
ratbag debug: New device: Logitech USB Receiver
ratbag debug: Using data directory '/usr/share/libratbag'
ratbag debug: No data file found for 046d:c52b
ratbag debug: New device: ELAN Touchscreen
ratbag debug: Using data directory '/usr/share/libratbag'
ratbag debug: No data file found for 04f3:0224
```

--------------------------------

### Docker Compose for Libratbag

Source: https://github.com/libratbag/libratbag/wiki/Dockerfile

This docker-compose.yml file defines the service for Libratbag, building the image from the Dockerfile, setting up the working directory, and mounting the current directory as a volume. It also specifies the command to configure, build, and set permissions for the build directory.

```yaml
version: "3.9"
services:
  ratbag:
    build: .
    image: libratbag:latest
    working_dir: /ratbag
    volumes:
      - ./:/ratbag
    command: >
      bash -c "meson builddir --wipe --debug  ||
               meson builddir --debug && 
               ninja -C /ratbag/builddir &&
               chmod -R 777 /ratbag/builddir"

```

--------------------------------

### Docker Debug Launch Configuration in launch.json for vscode

Source: https://github.com/libratbag/libratbag/wiki/Debugging

Configure a launch setting in launch.json for debugging 'ratbagd' within a Docker environment. It utilizes the 'build-docker' pre-launch task and includes source file mapping for debugging.

```json
{
            "name": "(gdb) Launch-Docker",
            "type": "cppdbg",
            "request": "launch",
            "program": "${workspaceFolder}/builddir/ratbagd",
            "args": [],
            "stopAtEntry": false,
            "cwd": "${workspaceFolder}",
            "environment": [],
            "miDebuggerPath": "${workspaceFolder}/.vscode/gdb",
            "externalConsole": false,
            
            "MIMode": "gdb",  

            "setupCommands": [
                {
                    "description": "Enable pretty-printing for gdb",
                    "text": "-enable-pretty-printing",
                    "ignoreFailures": true
                }
            ],
    
            
            "preLaunchTask": "build-docker",
            "sourceFileMap": {
                "/ratbag/src": "${workspaceFolder}/src",
                "/ratbag/ratbagd": "${workspaceFolder}/ratbagd",                
                "/ratbag": "${workspaceFolder}"

             }
        }
    ]
}
```

--------------------------------

### List available devices with ratbagctl

Source: https://github.com/libratbag/libratbag/wiki/devices/G600

Run this command to identify your mouse's device name. Ensure your mouse is plugged in directly to the computer, not a USB hub, for reliable detection.

```bash
ratbagctl
```

--------------------------------

### org.freedesktop.ratbag1.Device Interface

Source: https://github.com/libratbag/libratbag/blob/master/doc/dbus.rst

The org.freedesktop.ratbag1.Device interface describes a single device known to ratbagd.

```APIDOC
## org.freedesktop.ratbag1.Device

### Description
The org.freedesktop.ratbag1.Device interface describes a single device known to ratbagd.

### Attributes

#### Model
- **type**: s
- **flags**: read-only, constant
- **Description**: An ID identifying the physical device model. This string is guaranteed to be unique for a specific model and always identical for devices of that model.

  This is a string of one of the following formats:

  - ``usb:1234:abcd:0``
  - ``bluetooth:5678:ef01:0``
  - ``unknown``

  In the future, other formats may get added. Clients must ignore unknown string formats.

  For a string starting with ``usb:``, the format is the bus type (USB) followed by a 4-digit lowercase hex USB vendor ID, followed by a 4-digit lowercase hex USB product ID, followed by an decimal version number of unspecified length. These four elements are separated by a colon (``:``).

  For a string starting with ``bluetooth:``, the format is the bus type (Bluetooth) followed by a 4-digit lowercase hex Bluetooth vendor ID, followed by a 4-digit lowercase hex Bluetooth product ID, followed by an decimal version number of unspecified length. These four elements are separated by a colon (``:``).

  For the string ``unknown``, the model of the device cannot be determined. This is usually a bug in libratbag.
```

--------------------------------

### List USB Devices with lsusb

Source: https://github.com/libratbag/libratbag/wiki/Adding-a-device

Use `lsusb` to list connected USB devices and their identifiers. This is a prerequisite for creating device configuration files.

```bash
$ lsusb
... 
Bus 002 Device 015: ID 046d:c24e Logitech, Inc. G500s Laser Gaming Mouse
...
```

--------------------------------

### hidpp List Devices

Source: https://github.com/libratbag/libratbag/wiki/G203

Lists HID++ devices connected to the system. This command helps identify the specific device path (e.g., /dev/hidraw1) for the Logitech G203 LIGHTSYNC Gaming Mouse, which is necessary for further investigation with hidpp.

```bash
hidpp-list-devices 
/dev/hidraw1: Logitech G203 LIGHTSYNC Gaming Mouse (046d:c092) HID++ 4.2

```

--------------------------------

### Enable and Reload Systemd Service for ratbagd

Source: https://github.com/libratbag/libratbag/blob/master/README.md

Commands to reload the systemd daemon and DBus service, and then enable the ratbagd service for DBus activation. This ensures ratbagd can run as a systemd service.

```bash
sudo systemctl daemon-reload
sudo systemctl reload dbus.service

sudo systemctl enable ratbagd.service
```

--------------------------------

### Define Build Tasks in tasks.json for vscode

Source: https://github.com/libratbag/libratbag/wiki/Debugging

Configure tasks.json to define build processes. Includes a 'build' task for native compilation using meson and ninja, and a 'build-docker' task for building and running services with docker-compose.

```json
{
    // See https://go.microsoft.com/fwlink/?LinkId=733558
    // for the documentation about the tasks.json format
    "version": "2.0.0",
    "tasks": [
        {
            "label": "build",
            "type": "shell",
            "command": "meson builddir --debug --wipe && ninja -C builddir"
        }, 
        {
            "label": "build-docker",
            "type": "docker-compose",
            "dockerCompose": {
                "up": {
                    "detached": false,
                    "build": true, 
                    "services": ["ratbag"]
                },
                "files": [
                    "${workspaceFolder}/docker-compose.yml"
                ]
            }
        }        
    ]
}
```

--------------------------------

### hidpp List Features

Source: https://github.com/libratbag/libratbag/wiki/G203

Lists the supported HID++ features for a given device. This output shows the available features for the Logitech G203 LIGHTSYNC Gaming Mouse, including device information, DPI settings, report rate, RGB effects, and onboard profiles. Use this to understand the device's capabilities and potential areas for investigation.

```bash
hidpp-list-features /dev/hidraw1
Logitech G203 LIGHTSYNC Gaming Mouse (046d:c092) is a HID++ 4.2 device
Feature 0x01: [0x0001] Feature set
Feature 0x02: [0x0003] Device FW version
Feature 0x03: [0x0005] Device name
Feature 0x04: [0x1801] ? (hidden, internal)
Feature 0x05: [0x1802] Device reset (hidden, internal)
Feature 0x06: [0x1806] Configurable device properties (hidden, internal)
Feature 0x07: [0x1e00] Enable hidden features (hidden)
Feature 0x08: [0x1e22] ? (hidden, internal)
Feature 0x09: [0x1eb0] ? (hidden, internal)
Feature 0x0a: [0x2201] Adjustable dpi
Feature 0x0b: [0x18b1] ? (hidden, internal)
Feature 0x0c: [0x00c2] DFUcontrol 3
Feature 0x0d: [0x8060] Report rate
Feature 0x0e: [0x8071] RGB Effects
Feature 0x0f: [0x8100] Onboard profiles
Feature 0x10: [0x8110] Mouse button spy
Feature 0x11: [0x18a1] ? (hidden, internal)
Feature 0x12: [0x8081] Per-key lighting v2

```

--------------------------------

### Configure GDB for Elevated Privileges in vscode

Source: https://github.com/libratbag/libratbag/wiki/Debugging

Create a 'gdb' script in the .vscode folder to allow the debugger to run with elevated privileges using pkexec. Ensure the script has execute permissions.

```bash
pkexec /usr/bin/gdb "$@"
```

--------------------------------

### Re-run Debugging After Waking Device

Source: https://github.com/libratbag/libratbag/wiki/Adding-a-new-device

After waking the device (e.g., by clicking a button), re-run the verbose logging command. This should show successful communication or different errors.

```bash
ratbag debug: New device: Logitech MX Anywhere 2S
ratbag debug: Using data directory '/opt/libratbag/share/libratbag'
ratbag debug: device assigned driver hidpp20
ratbag debug: hidraw info: bus 0x03 vendor 0x46d product 0x406a
ratbag debug: Logitech MX Anywhere 2S is device '/dev/hidraw1'.
ratbag debug: HID report ID 01
ratbag debug: HID report ID 0e
ratbag debug: HID report ID 02
ratbag debug: HID report ID 03
ratbag debug: HID report ID 04
ratbag debug: HID report ID 10
ratbag debug: HID report ID 11
ratbag debug: HID report ID 20
```

--------------------------------

### Update Device Data File with Driver

Source: https://github.com/libratbag/libratbag/wiki/Adding-a-new-device

Add the `Driver=` line to the `.device` file. For most modern Logitech devices, `hidpp20` is the correct driver. If this fails, `hidpp10` may be an alternative.

```bash
[Device]
Name=Logitech MX Anywhere 2S
DeviceMatch=usb:046d:406a
Driver=hidpp20
```

--------------------------------

### Set UTF-8 Locale

Source: https://github.com/libratbag/libratbag/wiki/contributing/Building-from-source

Temporarily sets the system's locale to UTF-8 to resolve potential Unicode decoding errors during the build process. This should be done before running meson.

```bash
export LANG=en_US.utf8
```

--------------------------------

### Libratbag Architecture Diagram

Source: https://github.com/libratbag/libratbag/wiki/Developers

This diagram illustrates the interaction between different components of libratbag, including D-Bus and direct library access.

```text
                 [ratbagd.py] ---DBus--- ratbagd - libratbag
               /                                             \
[ratbagctl.py]                                                 /dev/input/eventX
               \                                             /
                 [ratbagc.py] - [swig bindings] - libratbag
 

```

--------------------------------

### Button API

Source: https://github.com/libratbag/libratbag/blob/master/doc/dbus.rst

Details the org.freedesktop.ratbag1.Button interface, including properties for index and mapping. The mapping property defines the action type and its associated value.

```APIDOC
## org.freedesktop.ratbag1.Button

### Description
Represents a button on the device and its current mapping.

### Attributes

#### Index
- **Type**: u
- **Flags**: read-only, constant
- **Description**: Index of the button.

#### Mapping
- **Type**: (uv)
- **Flags**: read-write, mutable
- **Description**: The current button mapping. The first element is the ``ActionType`` and the second is the variant value.
    - If ActionType is *Button*, the variant is an unsigned integer (``u``) for the button number.
    - If ActionType is *Special*, the variant is an unsigned integer (``u``) for the special value.
    - If ActionType is *Macro*, the variant is an array of integer tuples (``a(uu)``) where each tuple is ``(type, keycode)``.
```

--------------------------------

### Set button action with ratbagctl

Source: https://github.com/libratbag/libratbag/wiki/devices/G600

Assign a new action to a button, such as a macro. Replace `$N` with the button ID. Ensure that for every `+` modifier key used, a corresponding `-` is also present to avoid issues. Do not use button ID 20, as it is reserved for G-Shift color information. Also, avoid using button IDs greater than or equal to the total number of physical buttons reported in step 2.

```bash
ratbagctl "Logitech Gaming Mouse G600" button $N action set macro +KEY_LEFTSHIFT KEY_RESERVED -KEY_LEFTSHIFT && echo "worked $?" || echo "failed $?"
```

--------------------------------

### Action Types

Source: https://github.com/libratbag/libratbag/blob/master/doc/dbus.rst

Defines the possible types of actions that can be mapped to device inputs.

```APIDOC
## Action Types

### Description
Defines the possible types of actions that can be mapped to device inputs.

### Values

+---------+--------------------------------------+
| Value   | Description                          |
+=========+======================================+
|   0     | Key release event                    |
+---------+--------------------------------------+
|   1     | Key press event                      |
+---------+--------------------------------------+ 

If the ActionType is *None*, the variant is an unsigned integer (``u``) of value 0.
If the ActionType is *Unknown*, the variant is an unsigned integer (``u``) of value 0.

### ActionTypes Enum

:type: au
:flags: read-only, constant

+---------+---------+--------------------------------------+
| Value   | Name    | Description                          |
+=========+=========+======================================+
|   0     | None    | No mapping configured                |
+---------+---------+--------------------------------------+
|   1     | Button  | Mapping to a logical button number   |
+---------+---------+--------------------------------------+
|   2     | Special | Mapping to a special function        |
+---------+---------+--------------------------------------+
|   3     | Key     | Mapping to a simple key action       |
+---------+---------+--------------------------------------+
|   4     | Macro   | Mapping to a macro key sequence      |
+---------+---------+--------------------------------------+
| 1000    | Unknown | An unknown or unreadable mapping type|
+---------+---------+--------------------------------------+

Clients must ignore :attr:`ActionTypes` unknown to them.
```

--------------------------------

### Debugging with ratbag-command

Source: https://github.com/libratbag/libratbag/wiki/Developers

Use ratbag-command to interact directly with the libratbag static library, bypassing the D-Bus layer. This is useful for debugging library-level issues or developing new features.

```bash
sudo ./build/ratbag-command list
```

--------------------------------

### Profile Attributes

Source: https://github.com/libratbag/libratbag/blob/master/doc/dbus.rst

Attributes available for an org.freedesktop.ratbag1.Profile object.

```APIDOC
## Profile Attributes (`org.freedesktop.ratbag1.Profile`)

### Index

- **Type**: u (unsigned integer)
- **Flags**: read-only, constant
- **Description**: The zero-based index of this profile.

### Name

- **Type**: s (string)
- **Flags**: read-write, mutable
- **Description**: The name of this profile. If the name is the empty string, the profile name cannot be changed.

### Disabled

- **Type**: b (boolean)
- **Flags**: read-write, mutable
- **Description**: True if this profile is disabled, false otherwise. Note that a disabled profile might not have correct bindings, so it's a good thing to rebind everything before calling :func:`Commit`.

### IsActive

- **Type**: b (boolean)
- **Flags**: read-only, mutable
- **Description**: True if this is the currently active profile, false otherwise. Profiles can only be set to active, but never to not active - at least one profile must be active at all times. This property is read-only, use the :func:`SetActive` method to activate a profile.

### IsDirty

- **Type**: b (boolean)
- **Flags**: read-only, mutable
- **Description**: True if this profile is dirty, false otherwise. Dirty, that is, the device needs committing after being configured. This property becomes `true` whenever any other property of the profile is updated.

### Resolutions

- **Type**: ao (array of objects)
- **Flags**: read-only, mutable
- **Description**: Provides the object paths of all resolutions in this profile. This property is mutable if the device supports adding and removing resolutions.

### Buttons

- **Type**: ao (array of objects)
- **Flags**: read-only, constant
- **Description**: Provides the object paths of all buttons in this profile.

### Leds

- **Type**: ao (array of objects)
- **Flags**: read-only, constant
- **Description**: Provides the object paths of all LEDs in this profile.

### AngleSnapping

- **Type**: i (integer)
- **Flags**: read-write, mutable
- **Description**: Sensor angle snapping boolean value as an int (1 or 0), or `-1` to indicate that the device doesn't support reading and/or writing this value.

### Debounce

- **Type**: i (integer)
- **Flags**: read-write, mutable
- **Description**: Int for the button debounce time in milliseconds assigned to this profile. This time must be one of those listed in :attr:`Debounces`, or `-1` to indicate that changing debounce time for this device is not allowed.

### Debounces

- **Type**: au (array of unsigned integers)
- **Flags**: read-write, constant
- **Description**: A list of permitted button debounce times. Values in this list may be used in the :attr:`Debounce` property. This list is always sorted ascending; the lowest debounce time is the first item in the list. This list may be empty if the device does not support reading and/or writing the debounce time.

### ReportRate

- **Type**: u (unsigned integer)
- **Flags**: read-write, mutable
- **Description**: uint for the report rate in Hz assigned to this profile. This rate must be one of those listed in :attr:`ReportRates`.

### ReportRates

- **Type**: au (array of unsigned integers)
- **Flags**: read-write, constant
- **Description**: A list of permitted report rates in Hz. Values in this list may be used in the :attr:`ReportRate` property. This list is always sorted ascending.
```

--------------------------------

### Resolution API

Source: https://github.com/libratbag/libratbag/blob/master/doc/dbus.rst

Details the org.freedesktop.ratbag1.Resolution interface, including properties for index, capabilities, active/default status, and resolution values. It also includes methods to set the active and default resolutions.

```APIDOC
## org.freedesktop.ratbag1.Resolution

### Description
Represents a resolution setting for a device, including its capabilities and current status.

### Attributes

#### Index
- **Type**: u
- **Flags**: read-only, constant
- **Description**: Index of the resolution.

#### Capabilities
- **Type**: au
- **Flags**: read-only, constant
- **Description**: Bit-mask of capabilities. Known values include:
    - 1: Resolution can be set for x and y axes separately.
    - 2: Resolution can be disabled and enabled.
    Clients must ignore unknown Capabilities.

#### IsActive
- **Type**: b
- **Flags**: read-only, mutable
- **Description**: True if this is the currently active resolution, false otherwise. Use :func:`SetActive` to change.

#### IsDefault
- **Type**: b
- **Flags**: read-only, mutable
- **Description**: True if this is the currently default resolution, false otherwise. Use :func:`SetDefault` to change.

#### IsDisabled
- **Type**: b
- **Flags**: read-write, mutable
- **Description**: True if this resolution is disabled, false otherwise.

#### Resolution
- **Type**: v
- **Flags**: read-write, mutable
- **Description**: The resolution for this entry in dpi. Can be a single unsigned integer for both axes or a tuple (uu) for separate axes. The type must be preserved.

#### Resolutions
- **Type**: au
- **Flags**: read-only, constant
- **Description**: A list of permitted resolutions, sorted ascending.

### Methods

#### SetActive()
- **Description**: Set this resolution to be the active one.
- **Returns**: ()

#### SetDefault()
- **Description**: Set this resolution to be the default.
- **Returns**: ()
```

--------------------------------

### Device Properties

Source: https://github.com/libratbag/libratbag/blob/master/doc/dbus.rst

Properties available for a libratbag device.

```APIDOC
## Device Properties

### Name

- **Type**: s (string)
- **Flags**: read-only, constant
- **Description**: The device's name, suitable for presentation to the user.

### FirmwareVersion

- **Type**: s (string)
- **Flags**: read-only, constant
- **Description**: A device-specific string with the firmware version, or the empty string. For devices with a major/minor or purely numeric firmware version, the conversion into a string is implementation-defined.

### Profiles

- **Type**: ao (array of objects)
- **Flags**: read-only, mutable
- **Description**: Provides the list of profile paths for all profiles on this device. This property is mutable if the device supports adding and removing profiles.
```

--------------------------------

### Special Button Functions

Source: https://github.com/libratbag/libratbag/blob/master/doc/dbus.rst

Reference for special button functions supported by libratbag.

```APIDOC
## Special button functions

All special button function values are based on the value.
```

--------------------------------

### ratbagctl Device Info

Source: https://github.com/libratbag/libratbag/wiki/G203

Displays detailed information about the Logitech G203 LIGHTSYNC Gaming Mouse, including model, button count, LED count, profile information, report rate, resolutions, button mappings, and LED settings. Use this command to verify device recognition and configuration.

```bash
ratbagctl warbling-mara info  
warbling-mara - Logitech G203 LIGHTSYNC Gaming Mouse  
             Model: usb:046d:c092:0  
 Number of Buttons: 6  
    Number of Leds: 1  
Number of Profiles: 1  
Profile 0: (active)  
  Name: n/a  
  Report Rate: 1000Hz  
  Resolutions:  
    0: 400dpi  
    1: 800dpi (active) (default)  
    2: 1600dpi  
    3: 3200dpi  
    4: 0dpi  
  Button: 0 is mapped to 'button 1'  
  Button: 1 is mapped to 'button 2'  
  Button: 2 is mapped to 'button 3'  
  Button: 3 is mapped to 'button 4'  
  Button: 4 is mapped to 'button 5'  
  Button: 5 is mapped to 'resolution-cycle-up'  
  LED: 0, depth: rgb, mode: cycle, duration: 6000, brightness: 127  

```

--------------------------------

### Stop ratbagd Service

Source: https://github.com/libratbag/libratbag/wiki/Adding-a-new-device

Before manual control, stop the running ratbagd service. This ensures that your manual operations are not overridden by the system service.

```bash
$ sudo killall ratbagd
```

--------------------------------

### Disable System ratbagd

Source: https://github.com/libratbag/libratbag/wiki/Adding-a-new-device

To prevent ratbagd from auto-starting and interfering with debugging, rename its executable. This is a temporary measure for development.

```bash
$ sudo mv /usr/bin/ratbagd /usr/bin/ratbagd.disabled
```

--------------------------------

### Report Rate API

Source: https://github.com/libratbag/libratbag/blob/master/doc/dbus.rst

Provides information about the permitted report rates for a device. This list is sorted and indicates the lowest report rate first. It may be empty if the device does not support reading or writing report rates.

```APIDOC
## Report Rate API

### Description
A list of permitted report rates. Values in this list may be used in the :attr:`ReportRate` property. This list is always sorted ascending, the lowest report rate is the first item in the list.

This list may be empty if the device does not support reading and/or writing the report rate.

### Flags
read-write, constant
```