diff --git a/DBusInterface.md b/DBusInterface.md index 8dfd6791..d65eac4b 100644 --- a/DBusInterface.md +++ b/DBusInterface.md @@ -11,93 +11,327 @@ Interfaces: - org.freedesktop.ratbag1.Button - org.freedesktop.ratbag1.Led -The **org.freedesktop.ratbag1.Manager** interface provides: -- Properties: - - Devices -> array of object paths with interface Device - - Themes -> array of strings with theme names. The theme 'default' is - guaranteed to be available. -- Signals: - - DeviceNew -> new device available, carries object path - - DeviceRemoved -> device removed, carries object path +For a list of dbus types as used below, see https://dbus.freedesktop.org/doc/dbus-specification.html -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 - - GetSvg(string) -> 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. +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. -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 +org.freedesktop.ratbag1.Manager +=============================== -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.Manager** interface is the entry point to +interact with ratbagd. -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 +### Properties -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 +#### `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. + +### Signals + +#### `DeviceNew(o)` +Notifies the client that a new device is available. The new device's +object path is provided as argument in the signal. + +This signal is auxilary to the +`org.freedesktop.DBus.Properties.PropertyChanged` signal for the `Devices` +property. + +#### `DeviceRemoved(o)` + +Notifies the client that a device has been removed. The device's old +object path is provided as argument in the signal. + +When this signal is received, all references to this device have been +dropped by ratbagd. Further attempts at querying or modifying this +device will fail. + +This signal is auxilary to the +`org.freedesktop.DBus.Properties.PropertyChanged` signal for the `Devices` +property. + +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. + +#### `SvgPath` +- type: `s`, read-only, constant + +The device's SVG file name including the absolute 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