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

The org.freedesktop.ratbag1.Manager interface provides:

• Properties:
  • Devices -> array of object paths with interface Device
• Signals:
  • DeviceNew -> new device available, carries object path
  • DeviceRemoved -> device removed, carries object path

The org.freedesktop.ratbag1.Device interface provides:

• Properties:
  • Id -> unique ID of this device
  • Capabilities -> array of uints with the capabilities enum from libratbag
  • Description -> device name
  • Svg -> device SVG name (file only)
  • SvgPath -> device SVG name (full absolute path)
  • Profiles -> array of object paths with interface Profile
  • ActiveProfile -> index of the currently active profile in Profiles
• Methods:
  • GetProfileByIndex(uint) -> returns the object path for the given index
  • Commit() -> commit the changes to the device

The org.freedesktop.ratbag1.Profile interface provides:

• Properties:
  • Index -> index of the profile
  • Resolutions -> array of object paths with interface Resolution
  • Buttons -> array of object paths with interface Button
  • Leds -> array of object paths with interface Led
  • ActiveResolution -> index of the currently active resolution in Resolutions
  • DefaultResolution -> index of the default resolution in Resolutions
• Methods:
  • SetActive(void) -> set this profile to be the active profile
  • GetResolutionByIndex(uint) -> returns the object path for the given index
• Signals:
  • ActiveProfileChanged -> active profile changed, carries index of the new active profile

The org.freedesktop.ratbag1.Resolution interface provides:

• Properties:
  • Index -> index of the resolution
  • Capabilities -> array of uints with the capabilities enum from libratbag
  • XResolution -> uint for the x resolution assigned to this entry
  • YResolution -> uint for the y resolution assigned to this entry
  • ReportRate -> uint for the report rate in Hz assigned to this entry
  • Maximum -> uint for the maximum possible resolution
  • Minimum -> uint for the minimum possible resolution
• Methods:
  • SetResolution(uint, uint) -> x/y resolution to assign
  • SetReportRate(uint) -> uint for the report rate to assign
  • SetDefault -> set this resolution to be the default
• Signals:
  • ActiveResolutionChanged -> active resolution changed, carries index of the new active resolution
  • DefaultResolutionChanged -> default resolution changed, carries index of the new default resolution

The org.freedesktop.ratbag1.Button interface provides:

• Properties:
  • Index -> index of the button
  • Type -> string describing the button type
  • ButtonMapping -> uint of the current button mapping (if mapping to button)
  • SpecialMapping -> string of the current special mapping (if mapped to special)
  • KeyMapping -> array of uints, first entry is the keycode, other entries, if any, are modifiers (if mapped to key)
  • ActionType -> string describing the action type of the button ("none", "button", "key", "special", "macro", "unknown"). This decides which *Mapping property has a value
  • ActionTypes -> array of strings, possible values for ActionType
• Methods:
  • SetButtonMapping(uint) -> set the button mapping to the given button
  • SetSpecialMapping(string) -> set the button mapping to the given special entry
  • SetKeyMapping(uint[]) -> set the key mapping, first entry is the keycode, other entries, if any, are modifier keycodes
  • Disable(void) -> disable this button

The org.freedesktop.ratbag1.Led interface provides:

• Properties:
  • Index -> index of the LED
  • Mode -> uint mapping to the mode enum from libratbag
  • Type -> string describing the LED type
  • Color -> uint triplet (RGB) of the LED's color
  • EffectRate -> the effect rate in Hz, possible values are in the range 100 - 20000
  • Brightness -> the brightness of the LED, possible values are in the range 0 - 255
• Methods:
  • SetMode(uint) -> set the mode to the given mode enum value from libratbag
  • SetColor((uuu)) -> set the color to the given uint triplet (RGB)
  • SetEffectRate(uint) -> set the effect rate in Hz, possible values are in the range 100 - 20000
  • SetBrightness(int) -> 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.