More d-bus stuff added.
This commit is contained in:
Storm Dragon
@@ -1,8 +1,15 @@
|
||||
# Cthulhu Remote Controller (D-Bus Interface)
|
||||
|
||||
> **✅ STABLE**: This D-Bus interface has been successfully ported from Orca v49.alpha and integrated
|
||||
> into Cthulhu. The API is functional and ready for use, providing external control and automation
|
||||
> capabilities for the Cthulhu screen reader.
|
||||
> **⚠️⚠️ WORK IN PROGRESS**: This D-Bus interface is brand new and not yet feature complete.
|
||||
Low-risk feature additions will continue to be made. The API may be
|
||||
modified beyond bug fixes in future versions based on feedback from consumers of this support.
|
||||
Such changes will be documented here.
|
||||
|
||||
> **💡 Desktop-Agnostic Design**: Cthulhu's D-Bus Remote Controller is built on standard D-Bus
|
||||
session bus infrastructure and works across all desktop environments (GNOME, KDE Plasma, XFCE,
|
||||
i3, Sway, etc.). The D-Bus service uses no desktop-specific dependencies and follows universal
|
||||
D-Bus conventions, making it suitable for integration with any application or automation tool
|
||||
on any Linux desktop environment or window manager.
|
||||
|
||||
[TOC]
|
||||
|
||||
@@ -12,16 +19,42 @@ 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`
|
||||
- **Module Object Paths**: `/org/stormux.Cthulhu/Service/ModuleName`
|
||||
(e.g., `/org/stormux/Cthulhu/Service/SpeechAndVerbosityManager`)
|
||||
|
||||
See [REMOTE-CONTROLLER-COMMANDS.md](REMOTE-CONTROLLER-COMMANDS.md) for a complete
|
||||
list of available commands.
|
||||
|
||||
## Dependencies
|
||||
|
||||
The D-Bus interface requires:
|
||||
|
||||
- **dasbus** - Python D-Bus library used by Cthulhu for the remote controller implementation.
|
||||
([Installation instructions](https://dasbus.readthedocs.io/en/latest/index.html))
|
||||
- **python-dasbus** package (available on most distributions)
|
||||
|
||||
## Alternative Tools for D-Bus Interaction
|
||||
|
||||
While this documentation primarily uses `gdbus` for examples, you can use any D-Bus tool or library:
|
||||
|
||||
### Using `busctl` (systemd D-Bus tool)
|
||||
```bash
|
||||
busctl --user call org.stormux.Cthulhu.Service /org/stormux/Cthulhu/Service \
|
||||
org.stormux.Cthulhu.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")
|
||||
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
|
||||
```
|
||||
|
||||
## Service-Level Commands
|
||||
|
||||
@@ -29,13 +62,6 @@ Commands available directly on the main service (`/org/stormux/Cthulhu/Service`)
|
||||
|
||||
### Get Cthulhu's Version
|
||||
|
||||
```bash
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service \
|
||||
org.stormux.Cthulhu.Service GetVersion
|
||||
```
|
||||
|
||||
**Alternative using gdbus:**
|
||||
```bash
|
||||
gdbus call --session --dest org.stormux.Cthulhu.Service \
|
||||
--object-path /org/stormux/Cthulhu/Service \
|
||||
@@ -44,17 +70,8 @@ gdbus call --session --dest org.stormux.Cthulhu.Service \
|
||||
|
||||
**Returns:** String containing the version (and revision if available)
|
||||
|
||||
**Example output:** `s "Cthulhu screen reader version 2025.06.05-plugins (rev 408fb85)"`
|
||||
|
||||
### Present a Custom Message in Speech and/or Braille
|
||||
|
||||
```bash
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service \
|
||||
org.stormux.Cthulhu.Service PresentMessage s "Your message here"
|
||||
```
|
||||
|
||||
**Alternative using gdbus:**
|
||||
```bash
|
||||
gdbus call --session --dest org.stormux.Cthulhu.Service \
|
||||
--object-path /org/stormux/Cthulhu/Service \
|
||||
@@ -67,15 +84,28 @@ gdbus call --session --dest org.stormux.Cthulhu.Service \
|
||||
|
||||
**Returns:** Boolean indicating success
|
||||
|
||||
### List Available Service Commands
|
||||
### Show Cthulhu's Preferences GUI
|
||||
|
||||
```bash
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service \
|
||||
org.stormux.Cthulhu.Service ListCommands
|
||||
gdbus call --session --dest org.stormux.Cthulhu.Service \
|
||||
--object-path /org/stormux/Cthulhu/Service \
|
||||
--method org.stormux.Cthulhu.Service.ShowPreferences
|
||||
```
|
||||
|
||||
**Alternative using gdbus:**
|
||||
**Returns:** Boolean indicating success
|
||||
|
||||
### Quit Cthulhu
|
||||
|
||||
```bash
|
||||
gdbus call --session --dest org.stormux.Cthulhu.Service \
|
||||
--object-path /org/stormux/Cthulhu/Service \
|
||||
--method org.stormux.Cthulhu.Service.Quit
|
||||
```
|
||||
|
||||
**Returns:** Boolean indicating if the quit request was accepted
|
||||
|
||||
### List Available Service Commands
|
||||
|
||||
```bash
|
||||
gdbus call --session --dest org.stormux.Cthulhu.Service \
|
||||
--object-path /org/stormux/Cthulhu/Service \
|
||||
@@ -86,13 +116,6 @@ gdbus call --session --dest org.stormux.Cthulhu.Service \
|
||||
|
||||
### List Registered Modules
|
||||
|
||||
```bash
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service \
|
||||
org.stormux.Cthulhu.Service ListModules
|
||||
```
|
||||
|
||||
**Alternative using gdbus:**
|
||||
```bash
|
||||
gdbus call --session --dest org.stormux.Cthulhu.Service \
|
||||
--object-path /org/stormux/Cthulhu/Service \
|
||||
@@ -119,13 +142,6 @@ You can discover and execute these for each module.
|
||||
|
||||
#### List Commands for a Module
|
||||
|
||||
```bash
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/ModuleName \
|
||||
org.stormux.Cthulhu.Module ListCommands
|
||||
```
|
||||
|
||||
**Alternative using gdbus:**
|
||||
```bash
|
||||
gdbus call --session --dest org.stormux.Cthulhu.Service \
|
||||
--object-path /org/stormux/Cthulhu/Service/ModuleName \
|
||||
@@ -136,15 +152,29 @@ Replace `ModuleName` with an actual module name from `ListModules`.
|
||||
|
||||
**Returns:** List of (command_name, description) tuples.
|
||||
|
||||
#### List Runtime Getters for a Module
|
||||
#### List Parameterized Commands for a Module
|
||||
|
||||
```bash
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/ModuleName \
|
||||
org.stormux.Cthulhu.Module ListRuntimeGetters
|
||||
gdbus call --session --dest org.stormux.Cthulhu.Service \
|
||||
--object-path /org/stormux/Cthulhu/Service/ModuleName \
|
||||
--method org.stormux.Cthulhu.Module.ListParameterizedCommands
|
||||
```
|
||||
|
||||
**Alternative using gdbus:**
|
||||
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 \
|
||||
@@ -157,13 +187,6 @@ Replace `ModuleName` with an actual module name from `ListModules`.
|
||||
|
||||
#### List Runtime Setters for a Module
|
||||
|
||||
```bash
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/ModuleName \
|
||||
org.stormux.Cthulhu.Module ListRuntimeSetters
|
||||
```
|
||||
|
||||
**Alternative using gdbus:**
|
||||
```bash
|
||||
gdbus call --session --dest org.stormux.Cthulhu.Service \
|
||||
--object-path /org/stormux/Cthulhu/Service/ModuleName \
|
||||
@@ -178,13 +201,6 @@ Replace `ModuleName` with an actual module name from `ListModules`.
|
||||
|
||||
#### Execute a Runtime Getter
|
||||
|
||||
```bash
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/ModuleName \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeGetter s 'PropertyName'
|
||||
```
|
||||
|
||||
**Alternative using gdbus:**
|
||||
```bash
|
||||
gdbus call --session --dest org.stormux.Cthulhu.Service \
|
||||
--object-path /org/stormux/Cthulhu/Service/ModuleName \
|
||||
@@ -200,22 +216,16 @@ gdbus call --session --dest org.stormux.Cthulhu.Service \
|
||||
##### Example: Get the current speech rate
|
||||
|
||||
```bash
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/SpeechAndVerbosityManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeGetter s 'Rate'
|
||||
gdbus call --session --dest org.stormux.Cthulhu.Service \
|
||||
--object-path /org/stormux/Cthulhu/Service/SpeechAndVerbosityManager \
|
||||
--method org.stormux.Cthulhu.Module.ExecuteRuntimeGetter 'Rate'
|
||||
|
||||
```
|
||||
|
||||
This will return the rate as a GLib Variant.
|
||||
|
||||
#### Execute a Runtime Setter
|
||||
|
||||
```bash
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/ModuleName \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeSetter s 'PropertyName' v <value>
|
||||
```
|
||||
|
||||
**Alternative using gdbus:**
|
||||
```bash
|
||||
gdbus call --session --dest org.stormux.Cthulhu.Service \
|
||||
--object-path /org/stormux/Cthulhu/Service/ModuleName \
|
||||
@@ -232,26 +242,13 @@ gdbus call --session --dest org.stormux.Cthulhu.Service \
|
||||
##### Example: Set the current speech rate
|
||||
|
||||
```bash
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/SpeechAndVerbosityManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeSetter s 'Rate' v '<90>'
|
||||
gdbus call --session --dest org.stormux.Cthulhu.Service \
|
||||
--object-path /org/stormux/Cthulhu/Service/SpeechAndVerbosityManager \
|
||||
--method org.stormux.Cthulhu.Module.ExecuteRuntimeSetter 'Rate' '<90>'
|
||||
```
|
||||
|
||||
#### Execute a Module Command
|
||||
|
||||
```bash
|
||||
# With user notification
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/ModuleName \
|
||||
org.stormux.Cthulhu.Module ExecuteCommand s 'CommandName' b true
|
||||
|
||||
# Without user notification (silent)
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/ModuleName \
|
||||
org.stormux.Cthulhu.Module ExecuteCommand s 'CommandName' b false
|
||||
```
|
||||
|
||||
**Alternative using gdbus:**
|
||||
```bash
|
||||
# With user notification
|
||||
gdbus call --session --dest org.stormux.Cthulhu.Service \
|
||||
@@ -271,325 +268,105 @@ gdbus call --session --dest org.stormux.Cthulhu.Service \
|
||||
|
||||
**Returns:** Boolean indicating success
|
||||
|
||||
### Please Note
|
||||
#### Execute a Parameterized Command
|
||||
|
||||
**Setting `notify_user=true` is not a guarantee that feedback will be presented.** Some commands
|
||||
inherently don't make sense to announce. For example:
|
||||
```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
|
||||
```
|
||||
|
||||
**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
|
||||
```
|
||||
|
||||
This will return a list of available voices for US English.
|
||||
|
||||
### User Notification Applicability
|
||||
|
||||
**Setting `notify_user=true` is not a guarantee that feedback will be presented.**
|
||||
|
||||
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.
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/SpeechAndVerbosityManager \
|
||||
org.stormux.Cthulhu.Module ExecuteCommand s 'InterruptSpeech' b true
|
||||
gdbus call --session --dest org.stormux.Cthulhu.Service \
|
||||
--object-path /org/stormux/Cthulhu/Service/SpeechAndVerbosityManager \
|
||||
--method org.stormux.Cthulhu.Module.ExecuteCommand 'InterruptSpeech' true
|
||||
```
|
||||
|
||||
In those cases Cthulhu will ignore the value of `notify_user`.
|
||||
|
||||
**Setting `notify_user=false` is a guarantee that Cthulhu will remain silent.** If Cthulhu provides any
|
||||
feedback when `notify_user=false`, it should be considered a bug.
|
||||
|
||||
## Integration with Cthulhu's Plugin System
|
||||
|
||||
The D-Bus Remote Controller integrates seamlessly with Cthulhu's pluggy-based plugin system. Plugins can:
|
||||
|
||||
- Register their own D-Bus commands using the `@cthulhu_hookimpl` decorator
|
||||
- Expose plugin-specific functionality via the remote controller
|
||||
- Access the D-Bus service through the dynamic API manager
|
||||
|
||||
See the main `CLAUDE.md` file for more details on plugin development with D-Bus integration.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Service Not Available
|
||||
|
||||
If you get "The name is not activatable" or similar errors:
|
||||
|
||||
1. **Check if Cthulhu is running:**
|
||||
```bash
|
||||
ps aux | grep cthulhu
|
||||
```
|
||||
|
||||
2. **Check if the D-Bus service is registered:**
|
||||
```bash
|
||||
busctl --user list | grep -i cthulhu
|
||||
```
|
||||
|
||||
3. **Verify dasbus is installed:**
|
||||
```bash
|
||||
python3 -c "import dasbus; print('dasbus available')"
|
||||
```
|
||||
|
||||
4. **Check Cthulhu debug output:**
|
||||
```bash
|
||||
DISPLAY=:0 ~/.local/bin/cthulhu --debug 2>&1 | grep -i dbus
|
||||
```
|
||||
|
||||
### Common Issues
|
||||
|
||||
- **Timing Issues**: The D-Bus service starts after ATSPI initialization. Wait a few seconds after Cthulhu startup before attempting D-Bus calls.
|
||||
- **Permissions**: Ensure you're using `--user` with busctl/gdbus for session bus access.
|
||||
- **Display**: Make sure `DISPLAY=:0` is set when running Cthulhu in terminal sessions.
|
||||
|
||||
## Speech and Key Echo Control Examples
|
||||
|
||||
### SpeechManager Module
|
||||
|
||||
The SpeechManager module provides comprehensive control over Cthulhu's speech settings:
|
||||
|
||||
#### Speech Muting
|
||||
```bash
|
||||
# Check if speech is muted
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/SpeechManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeGetter s "SpeechIsMuted"
|
||||
|
||||
# Mute speech
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/SpeechManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeSetter sv "SpeechIsMuted" b true
|
||||
|
||||
# Unmute speech
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/SpeechManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeSetter sv "SpeechIsMuted" b false
|
||||
```
|
||||
|
||||
#### Verbosity Control
|
||||
```bash
|
||||
# Get current verbosity level
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/SpeechManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeGetter s "VerbosityLevel"
|
||||
|
||||
# Set verbosity to brief
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/SpeechManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeSetter sv "VerbosityLevel" s "brief"
|
||||
|
||||
# Set verbosity to verbose
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/SpeechManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeSetter sv "VerbosityLevel" s "verbose"
|
||||
```
|
||||
|
||||
#### Punctuation Control
|
||||
```bash
|
||||
# Get current punctuation level
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/SpeechManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeGetter s "PunctuationLevel"
|
||||
|
||||
# Set punctuation level (none/some/most/all)
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/SpeechManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeSetter sv "PunctuationLevel" s "all"
|
||||
```
|
||||
|
||||
#### Other Speech Settings
|
||||
```bash
|
||||
# Number pronunciation
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/SpeechManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeSetter sv "SpeakNumbersAsDigits" b true
|
||||
|
||||
# Capitalization style (none/icon/spell)
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/SpeechManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeSetter sv "CapitalizationStyle" s "spell"
|
||||
|
||||
# Indentation and justification speech
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/SpeechManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeSetter sv "SpeakIndentationAndJustification" b true
|
||||
|
||||
# Display-only text mode
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/SpeechManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeSetter sv "OnlySpeakDisplayedText" b false
|
||||
```
|
||||
|
||||
### TypingEchoManager Module
|
||||
|
||||
The TypingEchoManager module provides granular control over key echo and typing feedback:
|
||||
|
||||
#### Master Key Echo Control
|
||||
```bash
|
||||
# Check if key echo is enabled
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/TypingEchoManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeGetter s "KeyEchoEnabled"
|
||||
|
||||
# Enable key echo
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/TypingEchoManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeSetter sv "KeyEchoEnabled" b true
|
||||
|
||||
# Disable key echo
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/TypingEchoManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeSetter sv "KeyEchoEnabled" b false
|
||||
```
|
||||
|
||||
#### Character, Word, and Sentence Echo
|
||||
```bash
|
||||
# Character echo (echo characters as they're typed)
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/TypingEchoManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeSetter sv "CharacterEchoEnabled" b true
|
||||
|
||||
# Word echo (speak word when completed)
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/TypingEchoManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeSetter sv "WordEchoEnabled" b true
|
||||
|
||||
# Sentence echo (speak sentence when completed)
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/TypingEchoManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeSetter sv "SentenceEchoEnabled" b false
|
||||
```
|
||||
|
||||
#### Key Type Controls
|
||||
```bash
|
||||
# Alphabetic keys (a-z, A-Z)
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/TypingEchoManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeSetter sv "AlphabeticKeysEnabled" b true
|
||||
|
||||
# Numeric keys (0-9)
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/TypingEchoManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeSetter sv "NumericKeysEnabled" b true
|
||||
|
||||
# Punctuation keys (!@#$%^&*(),.;' etc.)
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/TypingEchoManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeSetter sv "PunctuationKeysEnabled" b true
|
||||
|
||||
# Space key
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/TypingEchoManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeSetter sv "SpaceEnabled" b true
|
||||
|
||||
# Modifier keys (Ctrl, Alt, Shift, etc.)
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/TypingEchoManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeSetter sv "ModifierKeysEnabled" b false
|
||||
|
||||
# Function keys (F1-F12)
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/TypingEchoManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeSetter sv "FunctionKeysEnabled" b true
|
||||
|
||||
# Action keys (Enter, Tab, Backspace, Delete, Escape)
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/TypingEchoManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeSetter sv "ActionKeysEnabled" b true
|
||||
|
||||
# Navigation keys (Arrow keys, Home, End, Page Up/Down)
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/TypingEchoManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeSetter sv "NavigationKeysEnabled" b false
|
||||
|
||||
# Diacritical keys (accented characters)
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/TypingEchoManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeSetter sv "DiacriticalKeysEnabled" b true
|
||||
```
|
||||
|
||||
### Complete Automation Script Example
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Complete Cthulhu Speech and Key Echo Configuration via D-Bus
|
||||
|
||||
echo "=== Configuring Cthulhu via D-Bus ==="
|
||||
|
||||
# Speech Configuration
|
||||
echo "Setting up speech preferences..."
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/SpeechManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeSetter sv "VerbosityLevel" s "brief"
|
||||
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/SpeechManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeSetter sv "PunctuationLevel" s "some"
|
||||
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/SpeechManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeSetter sv "SpeakNumbersAsDigits" b true
|
||||
|
||||
# Key Echo Configuration
|
||||
echo "Setting up key echo preferences..."
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/TypingEchoManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeSetter sv "KeyEchoEnabled" b true
|
||||
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/TypingEchoManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeSetter sv "AlphabeticKeysEnabled" b true
|
||||
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/TypingEchoManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeSetter sv "NumericKeysEnabled" b true
|
||||
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service/TypingEchoManager \
|
||||
org.stormux.Cthulhu.Module ExecuteRuntimeSetter sv "ModifierKeysEnabled" b false
|
||||
|
||||
echo "Configuration complete!"
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Quick Test Script
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Test Cthulhu D-Bus Remote Controller
|
||||
|
||||
echo "Testing Cthulhu D-Bus Remote Controller..."
|
||||
|
||||
# Get version
|
||||
echo "Version:"
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service \
|
||||
org.stormux.Cthulhu.Service GetVersion
|
||||
|
||||
# Present a message
|
||||
echo "Presenting message..."
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service \
|
||||
org.stormux.Cthulhu.Service PresentMessage s "Hello from D-Bus!"
|
||||
|
||||
# List available modules
|
||||
echo "Available modules:"
|
||||
busctl --user call org.stormux.Cthulhu.Service \
|
||||
/org/stormux/Cthulhu/Service \
|
||||
org.stormux.Cthulhu.Service ListModules
|
||||
|
||||
echo "D-Bus test complete!"
|
||||
```
|
||||
|
||||
## Integration Status
|
||||
|
||||
- ✅ **Core D-Bus service**: Fully integrated with Cthulhu
|
||||
- ✅ **Service lifecycle**: Automatic start/shutdown with Cthulhu
|
||||
- ✅ **Message presentation**: `PresentMessage()` method working
|
||||
- ✅ **Version info**: `GetVersion()` method working
|
||||
- ✅ **Deferred startup**: D-Bus service starts after ATSPI initialization to prevent crashes
|
||||
- ✅ **Error handling**: Proper exception handling and logging
|
||||
- 🔄 **Module registration**: Ready for individual managers to register D-Bus commands
|
||||
- 🔄 **Plugin integration**: Plugins can expose D-Bus commands using decorators
|
||||
|
||||
## Future Development
|
||||
|
||||
- Add more speech configuration commands, getters, and setters
|
||||
- Expose Cthulhu's plugin system commands via D-Bus
|
||||
- Integrate with Cthulhu's advanced features (indentation audio, self-voicing, etc.)
|
||||
- Progressively expose all of Cthulhu's commands and settings via the remote controller interface
|
||||
|
||||
## Related Files
|
||||
|
||||
- `src/cthulhu/dbus_service.py` - Main D-Bus service implementation
|
||||
- `src/cthulhu/cthulhu.py` - Integration and startup logic
|
||||
- `CLAUDE.md` - Main development guide with plugin integration details
|
||||
**Setting `notify_user=false` is not a guarantee that Cthulhu will remain silent**, though for the
|
||||
most part Cthulhu will try to respect this value. The exceptions are:
|
||||
|
||||
1. If executing the command has resulted in UI being shown, such as a dialog or menu, the
|
||||
newly-shown UI will be presented in speech and/or braille based on the user's settings.
|
||||
Failure to announce that the user has been removed from one window and placed in another
|
||||
could be extremely confusing.
|
||||
2. If the *sole* purpose of the command is to announce something without making any other
|
||||
changes, e.g. `PresentTime`, executing it with `notify_user=false` makes no sense. Adding
|
||||
checks and early returns to handle this possibility does not seem worth doing. If you
|
||||
don't want Cthulhu to present the time, don't ask Cthulhu to present the time. 😃
|
||||
|
||||
### Navigator Module "Enabled" State Applicability
|
||||
|
||||
**In the Remote Controller, Navigator commands are expected to work even when not "enabled."**
|
||||
|
||||
Some of Cthulhu's Navigator modules, namely Table Navigator, Caret Navigator, and Structural Navigator,
|
||||
have an "enabled" state. The reason for this is very much tied to the keyboard-centric nature of
|
||||
Cthulhu's commands. For instance, if Cthulhu always grabbed "H" (for heading navigation) and the arrow
|
||||
keys (for caret navigation), normal interaction with applications would be completely broken. For
|
||||
this reason, Navigator modules whose commands will prevent normal, native interaction with
|
||||
applications are typically not enabled by default and can be easily disabled.
|
||||
|
||||
In contrast, performing Navigator commands via D-Bus does not prevent native interaction with
|
||||
applications. For instance, one could use the Remote Controller to move to the next heading without
|
||||
causing H to stop functioning in editable fields. For this reason, and to avoid a performance hit,
|
||||
the decision was made to not check if (keyboard-centric) navigation commands were enabled. As a
|
||||
result, it should be possible to use Remote Controller navigation even in "focus mode" or other
|
||||
cases where Cthulhu is not controlling the caret. This is by design.
|
||||
|
||||
Given the keyboard-centric nature of Cthulhu's commands, there may be instances in which one uses the
|
||||
Remote Controller for navigation and Cthulhu fails to correctly update its location in response. If
|
||||
Cthulhu correctly updates its location when the same navigation command is executed via keyboard,
|
||||
please report the Remote Controller failure as a new bug in Cthulhu's issue tracker.
|
||||
|
||||
### The "Stickiness" (or Lack Thereof) of On-The-Fly Settings Changes
|
||||
|
||||
Cthulhu has a number of keyboard commands to temporarily change settings such as speech rate, pitch,
|
||||
volume; capitalization style; punctuation level; etc., etc. The question is: how long should
|
||||
on-the-fly modifications to settings persist?
|
||||
|
||||
Early on in Cthulhu's development, the conclusion was that on-the-fly settings changes should be
|
||||
seen as quite temporary, presumed to be used to address a specific one-time need. For instance,
|
||||
if reading some difficult-to-understand text, one might want to reduce the speed just for that text.
|
||||
If one were doing a final proofread of some content, one might want to briefly set the punctuation
|
||||
level to all. If one needs slow speed and/or verbose punctuation all the time, those should be set
|
||||
in Cthulhu's Preferences dialogs -- either globally or on a per-app basis. Cthulhu also has a profile
|
||||
feature through which the user can save settings and quickly load/unload them by switching profiles*.
|
||||
|
||||
Whether or not that historical decision was the right decision goes beyond the scope of the
|
||||
Remote Controller. The primary purpose of the Remote Controller is to provide D-Bus access to
|
||||
commands and runtime settings as if they were performed by the user via keyboard command. Thus if
|
||||
a setting changed via Remote Controller persists (or fails to persist) in the same way as when
|
||||
changed via keyboard command, it is not a Remote Controller bug. (It may be a general Cthulhu
|
||||
bug or feature request, and you are encouraged to file it as such.) On the other hand, if the
|
||||
behavior of the Remote Controller differs from that of the corresponding or related keyboard
|
||||
command, please report that Remote Controller failure as a new bug in Cthulhu's issue tracker.
|
||||
|
||||
\* *Note: Remote Controller support for profile management is still pending.*
|
||||
|
||||
Reference in New Issue
Block a user