Updated documentation. Attempted to track down a bug that causes disable speech sound to play with no interaction.?
This commit is contained in:
Storm Dragon
@ -1,4 +1,389 @@
|
||||
1. Basic
|
||||
2. Commands
|
||||
3. Useful API
|
||||
# Fenrir Development Guide
|
||||
|
||||
This document provides information for developers who want to contribute to Fenrir or understand its architecture.
|
||||
|
||||
## Project Structure
|
||||
|
||||
Fenrir follows a modular, driver-based architecture:
|
||||
|
||||
```
|
||||
src/fenrirscreenreader/
|
||||
├── core/ # Core system modules
|
||||
│ ├── fenrirManager.py # Main application manager
|
||||
│ ├── screenManager.py # Screen handling
|
||||
│ ├── inputManager.py # Input handling
|
||||
│ ├── outputManager.py # Speech/sound output
|
||||
│ ├── commandManager.py # Command system
|
||||
│ └── settingsManager.py # Configuration management
|
||||
├── commands/ # Command implementations
|
||||
│ ├── commands/ # User-invoked commands
|
||||
│ ├── onCursorChange/ # Cursor movement hooks
|
||||
│ ├── onScreenUpdate/ # Screen update hooks
|
||||
│ ├── onKeyInput/ # Key input hooks
|
||||
│ └── help/ # Tutorial system
|
||||
├── drivers/ # Driver implementations
|
||||
│ ├── inputDriver/ # Input drivers (evdev, pty, atspi)
|
||||
│ ├── screenDriver/ # Screen drivers (vcsa, pty)
|
||||
│ ├── speechDriver/ # Speech drivers (speechd, generic)
|
||||
│ └── soundDriver/ # Sound drivers (generic, gstreamer)
|
||||
└── utils/ # Utility modules
|
||||
```
|
||||
|
||||
## Core Architecture
|
||||
|
||||
### Driver System
|
||||
Fenrir uses a pluggable driver architecture:
|
||||
|
||||
1. **Input Drivers**: Capture keyboard input
|
||||
- evdevDriver: Linux evdev (recommended)
|
||||
- ptyDriver: Terminal emulation
|
||||
- atspiDriver: AT-SPI for desktop
|
||||
|
||||
2. **Screen Drivers**: Read screen content
|
||||
- vcsaDriver: Linux VCSA devices
|
||||
- ptyDriver: Terminal emulation
|
||||
|
||||
3. **Speech Drivers**: Text-to-speech output
|
||||
- speechdDriver: Speech-dispatcher
|
||||
- genericDriver: Command-line TTS
|
||||
|
||||
4. **Sound Drivers**: Audio output
|
||||
- genericDriver: Sox-based
|
||||
- gstreamerDriver: GStreamer
|
||||
|
||||
5. **Remote Drivers**: Remote control interfaces
|
||||
- unixDriver: Unix socket control
|
||||
- tcpDriver: TCP socket control
|
||||
|
||||
### Command System
|
||||
Commands are Python modules that implement specific functionality:
|
||||
|
||||
```python
|
||||
class command():
|
||||
def __init__(self):
|
||||
pass
|
||||
|
||||
def initialize(self, environment):
|
||||
self.env = environment
|
||||
|
||||
def shutdown(self):
|
||||
pass
|
||||
|
||||
def getDescription(self):
|
||||
return _('Command description')
|
||||
|
||||
def run(self):
|
||||
# Command implementation
|
||||
pass
|
||||
```
|
||||
|
||||
### Event Hooks
|
||||
Fenrir supports various event hooks:
|
||||
|
||||
- **onCursorChange**: Triggered when cursor moves
|
||||
- **onScreenUpdate**: Triggered on screen content changes
|
||||
- **onKeyInput**: Triggered on key presses
|
||||
- **onByteInput**: Triggered on byte-level input
|
||||
- **onScreenChanged**: Triggered when switching screens
|
||||
|
||||
## Development Setup
|
||||
|
||||
### Requirements
|
||||
- Python 3.6+
|
||||
- python3-evdev
|
||||
- python3-pyudev
|
||||
- speech-dispatcher
|
||||
- sox
|
||||
|
||||
### Getting Started
|
||||
```bash
|
||||
# Clone repository
|
||||
git clone https://git.stormux.org/storm/fenrir.git
|
||||
cd fenrir
|
||||
|
||||
# Install dependencies
|
||||
sudo pip3 install -r requirements.txt
|
||||
|
||||
# Run from source
|
||||
cd src/
|
||||
sudo ./fenrir -f -d
|
||||
```
|
||||
|
||||
### Testing
|
||||
```bash
|
||||
# Run in debug mode
|
||||
sudo ./fenrir -f -d -p
|
||||
|
||||
# Debug output goes to:
|
||||
# - Console (with -p flag)
|
||||
# - /var/log/fenrir.log
|
||||
```
|
||||
|
||||
## Creating Commands
|
||||
|
||||
### Basic Command
|
||||
Create a file in `src/fenrirscreenreader/commands/commands/`:
|
||||
|
||||
```python
|
||||
from fenrirscreenreader.core import debug
|
||||
|
||||
class command():
|
||||
def __init__(self):
|
||||
pass
|
||||
|
||||
def initialize(self, environment):
|
||||
self.env = environment
|
||||
|
||||
def shutdown(self):
|
||||
pass
|
||||
|
||||
def getDescription(self):
|
||||
return _('My custom command')
|
||||
|
||||
def run(self):
|
||||
# Get current text
|
||||
text = self.env['screen']['newContentText']
|
||||
|
||||
# Speak something
|
||||
self.env['runtime']['outputManager'].presentText('Hello World')
|
||||
|
||||
# Play sound
|
||||
self.env['runtime']['outputManager'].playSoundIcon('Accept')
|
||||
```
|
||||
|
||||
### Key Bindings
|
||||
Add key bindings in keyboard layout files:
|
||||
`config/keyboard/desktop.conf` or `config/keyboard/laptop.conf`
|
||||
|
||||
```ini
|
||||
[KEY_CTRL]#[KEY_ALT]#[KEY_H]=my_command
|
||||
```
|
||||
|
||||
### Event Hooks
|
||||
Create event handlers in appropriate directories:
|
||||
|
||||
```python
|
||||
# onCursorChange/my_hook.py
|
||||
class command():
|
||||
def __init__(self):
|
||||
pass
|
||||
|
||||
def initialize(self, environment):
|
||||
self.env = environment
|
||||
|
||||
def shutdown(self):
|
||||
pass
|
||||
|
||||
def getDescription(self):
|
||||
return _('My cursor change handler')
|
||||
|
||||
def run(self):
|
||||
if self.env['runtime']['cursorManager'].isCursorHorizontalMove():
|
||||
# Handle horizontal cursor movement
|
||||
pass
|
||||
```
|
||||
|
||||
## Creating Drivers
|
||||
|
||||
### Driver Template
|
||||
```python
|
||||
class driver():
|
||||
def __init__(self):
|
||||
pass
|
||||
|
||||
def initialize(self, environment):
|
||||
self.env = environment
|
||||
|
||||
def shutdown(self):
|
||||
pass
|
||||
|
||||
# Driver-specific methods...
|
||||
```
|
||||
|
||||
### Input Driver
|
||||
Implement these methods:
|
||||
- `getInputEvent()`: Return input events
|
||||
- `writeEventBuffer()`: Handle output events
|
||||
- `grabDevices()`: Take exclusive control
|
||||
- `releaseDevices()`: Release control
|
||||
|
||||
### Screen Driver
|
||||
Implement these methods:
|
||||
- `getCurrScreen()`: Get current screen content
|
||||
- `getSessionInformation()`: Get session info
|
||||
|
||||
### Speech Driver
|
||||
Implement these methods:
|
||||
- `speak()`: Speak text
|
||||
- `cancel()`: Stop speech
|
||||
- `setCallback()`: Set callback functions
|
||||
|
||||
### Remote Driver
|
||||
Implement these methods:
|
||||
- `initialize()`: Setup socket/connection
|
||||
- `watchDog()`: Listen for incoming commands
|
||||
- `shutdown()`: Clean up connections
|
||||
|
||||
#### Remote Driver Example
|
||||
```python
|
||||
class driver(remoteDriver):
|
||||
def initialize(self, environment):
|
||||
self.env = environment
|
||||
# Start watchdog thread
|
||||
self.env['runtime']['processManager'].addCustomEventThread(
|
||||
self.watchDog, multiprocess=True
|
||||
)
|
||||
|
||||
def watchDog(self, active, eventQueue):
|
||||
# Listen for connections and process commands
|
||||
while active.value:
|
||||
# Accept connections
|
||||
# Parse incoming data
|
||||
# Send to event queue
|
||||
eventQueue.put({
|
||||
"Type": fenrirEventType.RemoteIncomming,
|
||||
"Data": command_text
|
||||
})
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Settings System
|
||||
Settings are hierarchical:
|
||||
1. Command-line options (`-o`)
|
||||
2. Configuration file
|
||||
3. Hard-coded defaults
|
||||
|
||||
### Adding Settings
|
||||
1. Add default value to `core/settingsData.py`
|
||||
2. Access via `self.env['runtime']['settingsManager'].getSetting(section, key)`
|
||||
|
||||
## Debugging
|
||||
|
||||
### Debug Levels
|
||||
- 0: DEACTIVE
|
||||
- 1: ERROR
|
||||
- 2: WARNING
|
||||
- 3: INFO
|
||||
|
||||
### Debug Output
|
||||
```python
|
||||
self.env['runtime']['debug'].writeDebugOut(
|
||||
'Debug message',
|
||||
debug.debugLevel.INFO
|
||||
)
|
||||
```
|
||||
|
||||
### Testing Commands
|
||||
```bash
|
||||
# Test specific functionality
|
||||
sudo fenrir -f -d -o "general#debugLevel=3"
|
||||
|
||||
# Test with custom config
|
||||
sudo fenrir -f -s /path/to/test.conf
|
||||
```
|
||||
|
||||
## Contributing
|
||||
|
||||
### Code Style
|
||||
- Follow PEP 8
|
||||
- Use descriptive variable names
|
||||
- Add docstrings for complex functions
|
||||
- Handle exceptions gracefully
|
||||
|
||||
### Testing
|
||||
- Test with different drivers
|
||||
- Test keyboard layouts
|
||||
- Test on different terminals
|
||||
- Verify accessibility features
|
||||
|
||||
### Submitting Changes
|
||||
1. Fork the repository
|
||||
2. Create feature branch
|
||||
3. Make changes with clear commit messages
|
||||
4. Test thoroughly
|
||||
5. Submit pull request
|
||||
|
||||
## API Reference
|
||||
|
||||
### Environment Structure
|
||||
The `environment` dict contains all runtime data:
|
||||
|
||||
```python
|
||||
environment = {
|
||||
'runtime': {
|
||||
'settingsManager': settingsManager,
|
||||
'commandManager': commandManager,
|
||||
'screenManager': screenManager,
|
||||
'inputManager': inputManager,
|
||||
'outputManager': outputManager,
|
||||
'debug': debugManager,
|
||||
# ... other managers
|
||||
},
|
||||
'screen': {
|
||||
'newContentText': '',
|
||||
'oldContentText': '',
|
||||
'newCursor': {'x': 0, 'y': 0},
|
||||
'oldCursor': {'x': 0, 'y': 0},
|
||||
# ... screen data
|
||||
},
|
||||
'general': {
|
||||
'prevCommand': '',
|
||||
'currCommand': '',
|
||||
# ... general data
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Common Operations
|
||||
|
||||
#### Speaking Text
|
||||
```python
|
||||
self.env['runtime']['outputManager'].presentText('Hello')
|
||||
```
|
||||
|
||||
#### Playing Sounds
|
||||
```python
|
||||
self.env['runtime']['outputManager'].playSoundIcon('Accept')
|
||||
```
|
||||
|
||||
#### Getting Settings
|
||||
```python
|
||||
rate = self.env['runtime']['settingsManager'].getSetting('speech', 'rate')
|
||||
```
|
||||
|
||||
#### Cursor Information
|
||||
```python
|
||||
x = self.env['screen']['newCursor']['x']
|
||||
y = self.env['screen']['newCursor']['y']
|
||||
```
|
||||
|
||||
#### Screen Content
|
||||
```python
|
||||
text = self.env['screen']['newContentText']
|
||||
lines = text.split('\n')
|
||||
current_line = lines[self.env['screen']['newCursor']['y']]
|
||||
```
|
||||
|
||||
## Maintenance
|
||||
|
||||
### Release Process
|
||||
1. Update version in `fenrirVersion.py`
|
||||
2. Update changelog
|
||||
3. Test on multiple systems
|
||||
4. Tag release
|
||||
5. Update documentation
|
||||
|
||||
### Compatibility
|
||||
- Maintain Python 3.6+ compatibility
|
||||
- Test on multiple Linux distributions
|
||||
- Ensure driver compatibility
|
||||
- Check dependencies
|
||||
|
||||
## Resources
|
||||
|
||||
- **Repository**: https://git.stormux.org/storm/fenrir
|
||||
- **Wiki**: https://git.stormux.org/storm/fenrir/wiki
|
||||
- **Issues**: Use repository issue tracker
|
||||
- **Community**: IRC irc.stormux.org #stormux
|
||||
- **Email**: stormux+subscribe@groups.io
|
||||
Reference in New Issue
Block a user