129 lines
4.5 KiB
Markdown
129 lines
4.5 KiB
Markdown
# Cthulhu Remote Controller - Available Commands
|
|
|
|
This document lists the currently available D-Bus commands in Cthulhu's Remote Controller interface.
|
|
|
|
> **Note**: This is a work-in-progress. As more modules are exposed via D-Bus, this document will be expanded. Eventually this will be auto-generated using `tools/generate_dbus_documentation.py`.
|
|
|
|
## Service-Level Commands
|
|
|
|
Available on the main service object `/org/stormux/Cthulhu/Service`:
|
|
|
|
### Service Commands
|
|
|
|
| Command | Description | Parameters | Returns |
|
|
|---------|-------------|------------|---------|
|
|
| `GetVersion` | Returns Cthulhu's version string | None | String (version + revision) |
|
|
| `PresentMessage` | Present a message via speech/braille | `message` (string) | Boolean (success) |
|
|
| `ShowPreferences` | Opens Cthulhu's preferences GUI | None | Boolean (success) |
|
|
| `Quit` | Exits Cthulhu | None | Boolean (accepted) |
|
|
| `ListCommands` | Lists available service commands | None | List of (name, description) tuples |
|
|
| `ListModules` | Lists registered D-Bus modules | None | List of module names |
|
|
|
|
### Example Usage
|
|
|
|
```bash
|
|
# Get Cthulhu version
|
|
busctl --user call org.stormux.Cthulhu.Service /org/stormux/Cthulhu/Service \
|
|
org.stormux.Cthulhu.Service GetVersion
|
|
|
|
# Present a custom message
|
|
busctl --user call org.stormux.Cthulhu.Service /org/stormux/Cthulhu/Service \
|
|
org.stormux.Cthulhu.Service PresentMessage s "Hello from D-Bus"
|
|
|
|
# List available commands
|
|
busctl --user call org.stormux.Cthulhu.Service /org/stormux/Cthulhu/Service \
|
|
org.stormux.Cthulhu.Service ListCommands
|
|
|
|
# List registered modules
|
|
busctl --user call org.stormux.Cthulhu.Service /org/stormux/Cthulhu/Service \
|
|
org.stormux.Cthulhu.Service ListModules
|
|
|
|
# Open preferences
|
|
busctl --user call org.stormux.Cthulhu.Service /org/stormux/Cthulhu/Service \
|
|
org.stormux.Cthulhu.Service ShowPreferences
|
|
|
|
# Quit Cthulhu
|
|
busctl --user call org.stormux.Cthulhu.Service /org/stormux/Cthulhu/Service \
|
|
org.stormux.Cthulhu.Service Quit
|
|
```
|
|
|
|
## Module-Level Commands
|
|
|
|
Module-level commands are available and can be discovered via `ListModules`. Two key additions are:
|
|
|
|
### PluginSystemManager
|
|
|
|
Session-only plugin control (does not persist preferences):
|
|
|
|
- `ListPlugins`
|
|
- `ListActivePlugins`
|
|
- `IsPluginActive` (parameterized)
|
|
- `SetPluginActive` (parameterized)
|
|
- `RescanPlugins`
|
|
|
|
### Plugin Modules
|
|
|
|
Plugins that expose D-Bus decorators are automatically registered as modules using the naming
|
|
convention `Plugin_<ModuleName>` (e.g., `Plugin_GameMode`, `Plugin_WindowTitleReader`).
|
|
|
|
#### WindowTitleReader (Plugin_WindowTitleReader)
|
|
|
|
- `SetEnabled` (parameterized) -> enabled (bool)
|
|
- `Enabled` (runtime getter)
|
|
|
|
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
|
|
```
|
|
|
|
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
|
|
```
|
|
|
|
# Check current state
|
|
busctl --user call org.stormux.Cthulhu.Service \
|
|
/org/stormux/Cthulhu/Service/Plugin_WindowTitleReader \
|
|
org.stormux.Cthulhu.Module ExecuteRuntimeGetter s 'Enabled'
|
|
|
|
See [README-REMOTE-CONTROLLER.md](README-REMOTE-CONTROLLER.md) for comprehensive D-Bus API documentation and usage examples.
|
|
|
|
## Verifying D-Bus Service Status
|
|
|
|
```bash
|
|
# Check if Cthulhu's D-Bus service is running
|
|
busctl --user list | grep Cthulhu
|
|
|
|
# Introspect the service to see all available methods
|
|
busctl --user introspect org.stormux.Cthulhu.Service /org/stormux/Cthulhu/Service
|
|
|
|
# Get detailed service information
|
|
busctl --user status org.stormux.Cthulhu.Service
|
|
```
|
|
|
|
## Contributing
|
|
|
|
To add new D-Bus-accessible functionality:
|
|
|
|
1. Add `@dbus_service.command`, `@dbus_service.getter`, or `@dbus_service.setter` decorators to methods
|
|
2. Register the module with the D-Bus service in `src/cthulhu/cthulhu.py`
|
|
3. Rebuild and test with busctl
|
|
4. Update this documentation (or regenerate using `tools/generate_dbus_documentation.py` when available)
|
|
|
|
## Desktop Environment Compatibility
|
|
|
|
Cthulhu's D-Bus Remote Controller is desktop-agnostic and works across all Linux desktop environments:
|
|
- GNOME, KDE Plasma, XFCE, LXDE
|
|
- Tiling window managers (i3, Sway, bspwm, etc.)
|
|
- Any environment with D-Bus session bus support
|
|
|
|
The service uses only standard D-Bus infrastructure with no desktop-specific dependencies.
|