libratbag/DBusInterface.md

The ratbagd DBus-Interface

Note: the DBus interface is subject to change

Interfaces:

• org.freedesktop.ratbag1.Manager
• org.freedesktop.ratbag1.Device
• org.freedesktop.ratbag1.Profile
• org.freedesktop.ratbag1.Resolution
• org.freedesktop.ratbag1.Button
• org.freedesktop.ratbag1.Led

For a list of dbus types as used below, see https://dbus.freedesktop.org/doc/dbus-specification.html

Properties marked as 'constant' do not change for the lifetime of the object. Properties marked as 'mutable' may change, and a org.freedesktop.DBus.Properties.PropertyChanged signal is sent for those unless otherwise specified.

org.freedesktop.ratbag1.Manager

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

Properties

Devices

• type ao, read-only, mutable

Provides the object paths of all current devices, see org.freedesktop.ratbag1.Device

Themes

• type as, read-only, constant

Provides the list of available theme names. This list is guaranteed to have one theme available ('default'). Other themes are implementation defined. A theme listed here is only a guarantee that the theme is known to libratbag and that SVGs may exist, it is not a guarantee that the SVG for any specific device exists. In other words, a device may not have an SVG for a specific theme.

This list is static for the lifetime of ratbagd.

org.freedesktop.ratbag1.Device

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

Properties

Id

• type: s, read-only, constant

An ID describing this device. This ID should not be used for presentation to the user.

Description

• type: s, read-only, constant

The device's name, suitable for presentation to the user.

Capabilities

• type: au, read-only, constant

The capabilities supported by this device. see enum ratbag_device_capability in libratbag.h for the list of permissible capabilities.

Svg

• type: s, read-only, constant

The device's SVG file name, without path.

Profiles

• type: ao, read-only, mutable

This property is mutable if the device supports adding and removing profiles.

Provides the list of profile paths for all profiles on this device, see org.freedesktop.ratbag1.Profile.

ActiveProfile

• type: u, read-only, mutable

The index of the currently active profile in Profiles.

Methods

GetProfileByIndex(u) → (o)

Returns the object path for the profile with the given index

Commit() → ()

Commits the changes to the device. Changes to the device are batched; they are not written to the hardware until Commit() is invoked.

GetSvg(s) → (s)

Returns the full path to the SVG for the given theme or an empty string if none is available. The theme must be one of org.freedesktop.ratbag1.Manager.Themes. The theme 'default' is guaranteed to be available. ratbagd may return the path to a file that doesn't exist. This is the case if the device has SVGs available but not for the given theme.

org.freedesktop.ratbag1.Profile

Properties

Index

• type: u, read-only, constant

The index of this profile

Resolutions

• type: ao, read-only, mutable

This property is mutable if the device supports adding and removing resolutions.

Provides the object paths of all resolutions in this profile, see org.freedesktop.ratbag1.Resolution

Buttons

• type: ao, read-only, constant

Provides the object paths of all buttons in this profile, see org.freedesktop.ratbag1.Button

Leds

• type: ao, read-only, constant

Provides the object paths of all LEDs in this profile, see org.freedesktop.ratbag1.Led

ActiveResolution

• type: u, read-only, mutable

Index of the currently active resolution in Resolutions

DefaultResolution

• type: u, read-only, mutable

Index of the default resolution in Resolutions

Methods

SetActive() → ()

Set this profile to be the active profile

GetResolutionByIndex(u) → (o)

Returns the object path for the given index

Signals

ActiveProfileChanged(u)

Active profile changed, carries index of the new active profile

org.freedesktop.ratbag1.Resolution

Properties:

Index

• type: u, read-only, constant

Index of the resolution

Capabilities

• type: au, read-only, constant

Array of uints with the capabilities enum from libratbag

XResolution

• type: u, read-only, mutable

uint for the x resolution assigned to this entry

YResolution

• type: u, read-only, mutable

uint for the y resolution assigned to this entry

ReportRate

• type: u, read-only, mutable

uint for the report rate in Hz assigned to this entry

Maximum

• type: u, read-only, constant

uint for the maximum possible resolution

Minimum

• type: u, read-only, constant

uint for the minimum possible resolution

Methods:

SetResolution(u, u) → ()

x/y resolution to assign

SetReportRate(uint) → ()

uint for the report rate to assign

SetDefault() → ()

Set this resolution to be the default

Signals:

ActiveResolutionChanged(u)

Active resolution changed, carries index of the new active resolution

DefaultResolutionChanged(u)

Default resolution changed, carries index of the new default resolution

org.freedesktop.ratbag1.Button

Properties:

Index

• type: u, read-only, constant

Index of the button

Type

• type: s, read-only, constant

String describing the button type

ButtonMapping

• type: u, read-only, mutable

uint of the current button mapping (if mapping to button)

SpecialMapping

• type: s, read-only, mutable

String of the current special mapping (if mapped to special)

KeyMapping

• type: au, read-only, mutable

Array of uints, first entry is the keycode, other entries, if any, are modifiers (if mapped to key)

ActionType

• type: s, read-only, mutable

String describing the action type of the button ("none", "button", "key", "special", "macro", "unknown"). This decides which Mapping property has a value

ActionTypes

• type: as, read-only, constant Array of strings, possible values for ActionType

Methods:

SetButtonMapping(u) → ()

Set the button mapping to the given button

SetSpecialMapping(s) → ()

Set the button mapping to the given special entry

SetKeyMapping(au) → ()

Set the key mapping, first entry is the keycode, other entries, if any, are modifier keycodes

Disable() → ()

Disable this button

org.freedesktop.ratbag1.Led

Properties:

Index

• type: u, read-only, constant

Index of the LED

Mode

• type: u, read-only, mutable

uint mapping to the mode enum from libratbag

Type

• type: s, read-only, mutable

String describing the LED type

Color

• type: (uuu), read-only, mutable uint triplet (RGB) of the LED's color

EffectRate

• type: u, read-only, mutable

The effect rate in Hz, possible values are in the range 100 - 20000

Brightness

• type: u, read-only, mutable

The brightness of the LED, possible values are in the range 0 - 255

Methods:

SetMode(u) → ()

Set the mode to the given mode enum value from libratbag

SetColor((uuu)) → ()

Set the color to the given uint triplet (RGB)

SetEffectRate(u) → ()

Set the effect rate in Hz, possible values are in the range 100 - 20000

SetBrightness(i) → ()

Set the brightness, possible values are in the range 0 - 255

For easier debugging, objects paths are constructed from the device. e.g. /org/freedesktop/ratbag/button/event5/p0/b10 is the button interface for button 10 on profile 0 on event5. The naming is subject to change. Do not rely on a constructed object path in your application.