storm/cthulhu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Backport Orca's d-bus remote fixes.

Browse Source
This commit is contained in:
Storm Dragon
2026-04-26 13:18:23 -04:00
parent 337b5d4273
commit 265feb8188
7 changed files with 1017 additions and 888 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README-REMOTE-CONTROLLER.md
+89 -174
View File
@@ -22,10 +22,11 @@ on any Linux desktop environment or window manager.
Cthulhu exposes a D-Bus service at:
- **Service Name**: `org.stormux.Cthulhu.Service`
- **Main Object Path**: `/org/stormux/Cthulhu/Service`
- **Module Object Paths**: `/org/stormux.Cthulhu/Service/ModuleName`
(e.g., `/org/stormux/Cthulhu/Service/SpeechAndVerbosityManager`)
- **Service Name**: `org.stormux.Cthulhu1.Service`
- **Main Object Path**: `/org/stormux/Cthulhu1/Service`
- **Module Object Paths**: `/org/stormux/Cthulhu1/Service/ModuleName`
(e.g., `/org/stormux/Cthulhu1/Service/SpeechManager`)
- **Module Interfaces**: `org.stormux.Cthulhu1.ModuleName`
See [REMOTE-CONTROLLER-COMMANDS.md](REMOTE-CONTROLLER-COMMANDS.md) for a complete
list of available commands.
@@ -43,34 +44,34 @@ While this documentation primarily uses `gdbus` for examples, you can use any D-
### Using `busctl` (systemd D-Bus tool)
```bash
busctl --user call org.stormux.Cthulhu.Service /org/stormux/Cthulhu/Service \
org.stormux.Cthulhu.Service GetVersion
busctl --user call org.stormux.Cthulhu1.Service /org/stormux/Cthulhu1/Service \
org.stormux.Cthulhu1.Service GetVersion
```
### Using Python with `dasbus`
```python
from dasbus.connection import SessionMessageBus
bus = SessionMessageBus()
proxy = bus.get_proxy("org.stormux.Cthulhu.Service", "/org/stormux/Cthulhu/Service")
proxy = bus.get_proxy("org.stormux.Cthulhu1.Service", "/org/stormux/Cthulhu1/Service")
version = proxy.GetVersion()
```
### Using `qdbus` (Qt D-Bus tool - available on KDE)
```bash
qdbus org.stormux.Cthulhu.Service /org/stormux/Cthulhu/Service \
org.stormux.Cthulhu.Service.GetVersion
qdbus org.stormux.Cthulhu1.Service /org/stormux/Cthulhu1/Service \
org.stormux.Cthulhu1.Service.GetVersion
```
## Service-Level Commands
Commands available directly on the main service (`/org/stormux/Cthulhu/Service`):
Commands available directly on the main service (`/org/stormux/Cthulhu1/Service`):
### Get Cthulhu's Version
```bash
gdbus call --session --dest org.stormux.Cthulhu.Service \
--object-path /org/stormux/Cthulhu/Service \
--method org.stormux.Cthulhu.Service.GetVersion
gdbus call --session --dest org.stormux.Cthulhu1.Service \
--object-path /org/stormux/Cthulhu1/Service \
--method org.stormux.Cthulhu1.Service.GetVersion
```
**Returns:** String containing the version (and revision if available)
@@ -78,9 +79,9 @@ gdbus call --session --dest org.stormux.Cthulhu.Service \
### Present a Custom Message in Speech and/or Braille
```bash
gdbus call --session --dest org.stormux.Cthulhu.Service \
--object-path /org/stormux/Cthulhu/Service \
--method org.stormux.Cthulhu.Service.PresentMessage "Your message here"
gdbus call --session --dest org.stormux.Cthulhu1.Service \
--object-path /org/stormux/Cthulhu1/Service \
--method org.stormux.Cthulhu1.Service.PresentMessage "Your message here"
```
**Parameters:**
@@ -92,9 +93,9 @@ gdbus call --session --dest org.stormux.Cthulhu.Service \
### Show Cthulhu's Preferences GUI
```bash
gdbus call --session --dest org.stormux.Cthulhu.Service \
--object-path /org/stormux/Cthulhu/Service \
--method org.stormux.Cthulhu.Service.ShowPreferences
gdbus call --session --dest org.stormux.Cthulhu1.Service \
--object-path /org/stormux/Cthulhu1/Service \
--method org.stormux.Cthulhu1.Service.ShowPreferences
```
**Returns:** Boolean indicating success
@@ -102,44 +103,39 @@ gdbus call --session --dest org.stormux.Cthulhu.Service \
### Quit Cthulhu
```bash
gdbus call --session --dest org.stormux.Cthulhu.Service \
--object-path /org/stormux/Cthulhu/Service \
--method org.stormux.Cthulhu.Service.Quit
gdbus call --session --dest org.stormux.Cthulhu1.Service \
--object-path /org/stormux/Cthulhu1/Service \
--method org.stormux.Cthulhu1.Service.Quit
```
**Returns:** Boolean indicating if the quit request was accepted
### List Available Service Commands
## Discovering Modules and Their Capabilities
Use the standard DBus introspection interface to discover registered modules:
```bash
gdbus call --session --dest org.stormux.Cthulhu.Service \
--object-path /org/stormux/Cthulhu/Service \
--method org.stormux.Cthulhu.Service.ListCommands
gdbus introspect --session --dest org.stormux.Cthulhu1.Service \
--object-path /org/stormux/Cthulhu1/Service --recurse
```
**Returns:** List of (command_name, description) tuples
### List Registered Modules
The child `<node>` entries beneath `/org/stormux/Cthulhu1/Service` are the
registered modules. To inspect the methods and properties for one module:
```bash
gdbus call --session --dest org.stormux.Cthulhu.Service \
--object-path /org/stormux/Cthulhu/Service \
--method org.stormux.Cthulhu.Service.ListModules
gdbus introspect --session --dest org.stormux.Cthulhu1.Service \
--object-path /org/stormux/Cthulhu1/Service/SpeechManager
```
**Returns:** List of module names
## Interacting with Modules
Each registered module exposes its own set of operations. Based on the underlying Cthulhu code, these
are categorized as **Commands**, **Runtime Getters**, and **Runtime Setters**:
Each registered module exposes its own native DBus interface. Based on the underlying Cthulhu code,
these are categorized as **Commands** and **Properties**:
- **Commands**: Actions that perform a task. These typically correspond to Cthulhu commands bound
to a keystroke (e.g., `IncreaseRate`).
- **Runtime Getters**: Operations that retrieve the current value of an item, often a setting
(e.g., `GetRate`).
- **Runtime Setters**: Operations that set the current value of an item, often a setting
(e.g., `SetRate`). Note that setting a value does NOT cause it to become permanently saved.
- **Properties**: Runtime values, often settings (e.g., `Rate`). Setting a property does not cause
it to become permanently saved.
You can discover and execute these for each module.
@@ -147,41 +143,41 @@ You can discover and execute these for each module.
Plugins that expose D-Bus decorators are automatically registered as modules using the naming
convention `Plugin_<ModuleName>` (e.g., `Plugin_GameMode`, `Plugin_WindowTitleReader`). Use
`ListModules` to discover available plugin modules at runtime.
standard DBus introspection to discover available plugin modules at runtime.
#### Plugin_WindowTitleReader
Controls for the Window Title Reader plugin:
- Parameterized command: `SetEnabled` (`enabled`: bool)
- Runtime getter: `Enabled`
- Method: `SetEnabled` (`enabled`: bool, `notify_user`: bool)
- Property: `Enabled`
Example:
```bash
gdbus call --session --dest org.stormux.Cthulhu.Service \
--object-path /org/stormux/Cthulhu/Service/Plugin_WindowTitleReader \
--method org.stormux.Cthulhu.Module.ExecuteParameterizedCommand \
'SetEnabled' '{"enabled": <true>}' false
gdbus call --session --dest org.stormux.Cthulhu1.Service \
--object-path /org/stormux/Cthulhu1/Service/Plugin_WindowTitleReader \
--method org.stormux.Cthulhu1.Plugin_WindowTitleReader.SetEnabled true false
# Check current state
gdbus call --session --dest org.stormux.Cthulhu.Service \
--object-path /org/stormux/Cthulhu/Service/Plugin_WindowTitleReader \
--method org.stormux.Cthulhu.Module.ExecuteRuntimeGetter 'Enabled'
gdbus call --session --dest org.stormux.Cthulhu1.Service \
--object-path /org/stormux/Cthulhu1/Service/Plugin_WindowTitleReader \
--method org.freedesktop.DBus.Properties.Get \
org.stormux.Cthulhu1.Plugin_WindowTitleReader Enabled
```
Busctl example:
```bash
busctl --user call org.stormux.Cthulhu.Service \
/org/stormux/Cthulhu/Service/Plugin_WindowTitleReader \
org.stormux.Cthulhu.Module ExecuteParameterizedCommand \
s a{sv} b 'SetEnabled' 1 enabled b true false
busctl --user call org.stormux.Cthulhu1.Service \
/org/stormux/Cthulhu1/Service/Plugin_WindowTitleReader \
org.stormux.Cthulhu1.Plugin_WindowTitleReader SetEnabled bb true false
# Check current state
busctl --user call org.stormux.Cthulhu.Service \
/org/stormux/Cthulhu/Service/Plugin_WindowTitleReader \
org.stormux.Cthulhu.Module ExecuteRuntimeGetter s 'Enabled'
busctl --user call org.stormux.Cthulhu1.Service \
/org/stormux/Cthulhu1/Service/Plugin_WindowTitleReader \
org.freedesktop.DBus.Properties Get ss \
org.stormux.Cthulhu1.Plugin_WindowTitleReader Enabled
```
### PluginSystemManager Module
@@ -190,166 +186,85 @@ The `PluginSystemManager` module provides session-only plugin control:
- `ListPlugins`
- `ListActivePlugins`
- `IsPluginActive` (parameterized)
- `SetPluginActive` (parameterized)
- `IsPluginActive`
- `SetPluginActive`
- `RescanPlugins`
These calls do **not** persist changes to user preferences.
### Discovering Module Capabilities
#### List Commands for a Module
```bash
gdbus call --session --dest org.stormux.Cthulhu.Service \
--object-path /org/stormux/Cthulhu/Service/ModuleName \
--method org.stormux.Cthulhu.Module.ListCommands
```
Replace `ModuleName` with an actual module name from `ListModules`.
**Returns:** List of (command_name, description) tuples.
#### List Parameterized Commands for a Module
```bash
gdbus call --session --dest org.stormux.Cthulhu.Service \
--object-path /org/stormux/Cthulhu/Service/ModuleName \
--method org.stormux.Cthulhu.Module.ListParameterizedCommands
```
Replace `ModuleName` with an actual module name from `ListModules`.
**Returns:** List of (command_name, description, parameters) tuples, where `parameters` is a
list of (parameter_name, parameter_type) tuples.
**Example output:**
```bash
([('GetVoicesForLanguage',
'Returns a list of available voices for the specified language.',
[('language', 'str'), ('variant', 'str'), ('notify_user', 'bool')])],)
```
#### List Runtime Getters for a Module
```bash
gdbus call --session --dest org.stormux.Cthulhu.Service \
--object-path /org/stormux/Cthulhu/Service/ModuleName \
--method org.stormux.Cthulhu.Module.ListRuntimeGetters
```
Replace `ModuleName` with an actual module name from `ListModules`.
**Returns:** List of (getter_name, description) tuples.
#### List Runtime Setters for a Module
```bash
gdbus call --session --dest org.stormux.Cthulhu.Service \
--object-path /org/stormux/Cthulhu/Service/ModuleName \
--method org.stormux.Cthulhu.Module.ListRuntimeSetters
```
Replace `ModuleName` with an actual module name from `ListModules`.
**Returns:** List of (setter_name, description) tuples.
### Executing Module Operations
#### Execute a Runtime Getter
#### Get a Property
```bash
gdbus call --session --dest org.stormux.Cthulhu.Service \
--object-path /org/stormux/Cthulhu/Service/ModuleName \
--method org.stormux.Cthulhu.Module.ExecuteRuntimeGetter 'PropertyName'
gdbus call --session --dest org.stormux.Cthulhu1.Service \
--object-path /org/stormux/Cthulhu1/Service/ModuleName \
--method org.freedesktop.DBus.Properties.Get \
org.stormux.Cthulhu1.ModuleName PropertyName
```
**Parameters:**
- `PropertyName` (string): The name of the runtime getter to execute.
**Returns:** The value returned by the getter as a GLib variant (type depends on the getter).
##### Example: Get the current speech rate
```bash
gdbus call --session --dest org.stormux.Cthulhu.Service \
--object-path /org/stormux/Cthulhu/Service/SpeechAndVerbosityManager \
--method org.stormux.Cthulhu.Module.ExecuteRuntimeGetter 'Rate'
gdbus call --session --dest org.stormux.Cthulhu1.Service \
--object-path /org/stormux/Cthulhu1/Service/SpeechManager \
--method org.freedesktop.DBus.Properties.Get \
org.stormux.Cthulhu1.SpeechManager Rate
```
This will return the rate as a GLib Variant.
#### Execute a Runtime Setter
#### Set a Property
```bash
gdbus call --session --dest org.stormux.Cthulhu.Service \
--object-path /org/stormux/Cthulhu/Service/ModuleName \
--method org.stormux.Cthulhu.Module.ExecuteRuntimeSetter 'PropertyName' <value>
gdbus call --session --dest org.stormux.Cthulhu1.Service \
--object-path /org/stormux/Cthulhu1/Service/ModuleName \
--method org.freedesktop.DBus.Properties.Set \
org.stormux.Cthulhu1.ModuleName PropertyName '<value>'
```
**Parameters:**
- `PropertyName` (string): The name of the runtime setter to execute.
- `<value>`: The value to set, as a GLib variant (type depends on the setter).
**Returns:** Boolean indicating success.
##### Example: Set the current speech rate
```bash
gdbus call --session --dest org.stormux.Cthulhu.Service \
--object-path /org/stormux/Cthulhu/Service/SpeechAndVerbosityManager \
--method org.stormux.Cthulhu.Module.ExecuteRuntimeSetter 'Rate' '<90>'
gdbus call --session --dest org.stormux.Cthulhu1.Service \
--object-path /org/stormux/Cthulhu1/Service/SpeechManager \
--method org.freedesktop.DBus.Properties.Set \
org.stormux.Cthulhu1.SpeechManager Rate '<90>'
```
#### Execute a Module Command
```bash
# With user notification
gdbus call --session --dest org.stormux.Cthulhu.Service \
--object-path /org/stormux/Cthulhu/Service/ModuleName \
--method org.stormux.Cthulhu.Module.ExecuteCommand 'CommandName' true
gdbus call --session --dest org.stormux.Cthulhu1.Service \
--object-path /org/stormux/Cthulhu1/Service/ModuleName \
--method org.stormux.Cthulhu1.ModuleName.CommandName true
# Without user notification (silent)
gdbus call --session --dest org.stormux.Cthulhu.Service \
--object-path /org/stormux/Cthulhu/Service/ModuleName \
--method org.stormux.Cthulhu.Module.ExecuteCommand 'CommandName' false
gdbus call --session --dest org.stormux.Cthulhu1.Service \
--object-path /org/stormux/Cthulhu1/Service/ModuleName \
--method org.stormux.Cthulhu1.ModuleName.CommandName false
```
**Parameters (both required):**
- `CommandName` (string): The name of the command to execute
- `notify_user` (boolean): Whether to notify the user of the action (see section below)
**Returns:** Boolean indicating success
#### Execute a Parameterized Command
```bash
gdbus call --session --dest org.stormux.Cthulhu.Service \
--object-path /org/stormux/Cthulhu/Service/ModuleName \
--method org.stormux.Cthulhu.Module.ExecuteParameterizedCommand 'CommandName' \
'{"param1": <"value1">, "param2": <"value2">}' false
gdbus call --session --dest org.stormux.Cthulhu1.Service \
--object-path /org/stormux/Cthulhu1/Service/ModuleName \
--method org.stormux.Cthulhu1.ModuleName.CommandName \
"value1" "value2" false
```
**Parameters:**
- `CommandName` (string): The name of the parameterized command to execute
- `parameters` (dict): Dictionary of parameter names and values as GLib variants
- `notify_user` (boolean): Whether to notify the user of the action
**Returns:** The result returned by the command as a GLib variant (type depends on the command)
##### Example: Get voices for a specific language
```bash
gdbus call --session --dest org.stormux.Cthulhu.Service \
--object-path /org/stormux/Cthulhu/Service/SpeechAndVerbosityManager \
--method org.stormux.Cthulhu.Module.ExecuteParameterizedCommand 'GetVoicesForLanguage' \
'{"language": <"en-us">, "variant": <"">}' false
gdbus call --session --dest org.stormux.Cthulhu1.Service \
--object-path /org/stormux/Cthulhu1/Service/SpeechManager \
--method org.stormux.Cthulhu1.SpeechManager.GetVoicesForLanguage "en-us" "" false
```
This will return a list of available voices for US English.
@@ -362,9 +277,9 @@ Some commands inherently don't make sense to announce. For example:
```bash
# This command should simply stop speech, not announce that it is stopping speech.
gdbus call --session --dest org.stormux.Cthulhu.Service \
--object-path /org/stormux/Cthulhu/Service/SpeechAndVerbosityManager \
--method org.stormux.Cthulhu.Module.ExecuteCommand 'InterruptSpeech' true
gdbus call --session --dest org.stormux.Cthulhu1.Service \
--object-path /org/stormux/Cthulhu1/Service/SpeechManager \
--method org.stormux.Cthulhu1.SpeechManager.InterruptSpeech true
```
In those cases Cthulhu will ignore the value of `notify_user`.