351 lines
10 KiB
Markdown
351 lines
10 KiB
Markdown
# WiseTLP
|
|
|
|
**AI-powered TLP configuration automation tool for Linux power management optimization**
|
|
|
|
WiseTLP is a professional-grade command-line application that leverages artificial intelligence to automatically generate optimized TLP (Linux Advanced Power Management) configurations tailored to your specific system hardware and usage patterns.
|
|
|
|
## Features
|
|
|
|
### Core Functionality
|
|
|
|
- **Comprehensive System Detection**: Automatically detects Linux distribution, hardware specifications, power management capabilities, and existing configurations
|
|
- **AI-Powered Configuration Generation**: Uses advanced AI models to generate optimized TLP configurations based on your system and preferences
|
|
- **Multi-Provider AI Support**: Compatible with multiple AI services including Groq, OpenRouter, Gemini, and custom OpenAI-compatible endpoints
|
|
- **Interactive User Interface**: Guided configuration process with clear explanations and user-friendly prompts
|
|
- **Secure API Key Management**: Encrypted storage of API keys with master password protection
|
|
- **Automated TLP Installation**: Handles TLP installation across major Linux distributions with proper privilege escalation
|
|
|
|
### System Compatibility
|
|
|
|
WiseTLP supports major Linux distributions including:
|
|
|
|
- **Debian-based**: Ubuntu, Debian, Linux Mint, Elementary OS, Pop!_OS
|
|
- **Red Hat-based**: Fedora, RHEL, CentOS, Rocky Linux, AlmaLinux
|
|
- **Arch-based**: Arch Linux, Manjaro, EndeavourOS, Garuda Linux
|
|
- **SUSE-based**: openSUSE Leap, openSUSE Tumbleweed
|
|
- **Other**: Alpine Linux, Gentoo
|
|
|
|
### Security Features
|
|
|
|
- **Encrypted API Key Storage**: API keys are encrypted using AES-GCM with master password protection
|
|
- **Secure Privilege Escalation**: Minimal privilege escalation with user confirmation and secure sudo handling
|
|
- **Input Validation**: Comprehensive input sanitization and validation to prevent security vulnerabilities
|
|
- **Configuration Backup**: Automatic backup of existing TLP configurations before applying changes
|
|
|
|
## Installation
|
|
|
|
### Prerequisites
|
|
|
|
- Linux operating system (kernel 2.6.32 or later)
|
|
- Go 1.22 or later (for building from source)
|
|
- sudo privileges (for TLP installation and configuration)
|
|
|
|
### Building from Source
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://git.gostacks.org/iwasforcedtobehere/WiseTLP/autotlp.git
|
|
cd autotlp
|
|
|
|
# Build the application
|
|
go build -o autotlp ./cmd/autotlp
|
|
|
|
# Install to system path (optional)
|
|
sudo mv autotlp /usr/local/bin/
|
|
```
|
|
|
|
### Quick Start
|
|
|
|
```bash
|
|
# Run WiseTLP with interactive setup
|
|
./autotlp
|
|
|
|
# Or if installed system-wide
|
|
autotlp
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Basic Usage
|
|
|
|
WiseTLP provides an interactive command-line interface that guides you through the configuration process:
|
|
|
|
1. **System Detection**: WiseTLP automatically detects your system specifications
|
|
2. **TLP Installation**: If TLP is not installed, WiseTLP can install it for you
|
|
3. **AI Service Configuration**: Choose and configure your preferred AI service
|
|
4. **User Preferences**: Specify your power management preferences and use case
|
|
5. **Configuration Generation**: AI generates an optimized TLP configuration
|
|
6. **Review and Apply**: Review the generated configuration and apply it to your system
|
|
|
|
### AI Service Configuration
|
|
|
|
WiseTLP supports multiple AI providers:
|
|
|
|
#### Groq (Recommended for speed)
|
|
```
|
|
Provider: Groq
|
|
Endpoint: https://api.groq.com/openai/v1/chat/completions
|
|
Model: openai/gpt-oss-20b
|
|
```
|
|
|
|
#### OpenRouter (Multiple model options)
|
|
```
|
|
Provider: OpenRouter
|
|
Endpoint: https://openrouter.ai/api/v1/chat/completions
|
|
Model: meta-llama/llama-3.1-8b-instruct:free (or others)
|
|
```
|
|
|
|
#### Google Gemini
|
|
```
|
|
Provider: Gemini
|
|
Endpoint: https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent
|
|
Model: gemini-pro
|
|
```
|
|
|
|
#### Custom OpenAI-compatible
|
|
```
|
|
Provider: Custom
|
|
Endpoint: [Your custom endpoint]
|
|
Model: [Your model name]
|
|
```
|
|
|
|
### Configuration Options
|
|
|
|
#### Power Profiles
|
|
|
|
- **Balanced**: Optimal balance between performance and power efficiency
|
|
- **Performance**: Maximum performance with higher power consumption
|
|
- **Power Saving**: Maximum battery life with reduced performance
|
|
- **Custom**: Specify custom requirements and settings
|
|
|
|
#### Use Cases
|
|
|
|
- **General**: Web browsing, office work, media consumption
|
|
- **Development**: Programming, compiling, development tools
|
|
- **Gaming**: Gaming and graphics-intensive applications
|
|
- **Server**: Server workloads, always-on services
|
|
- **Multimedia**: Video editing, rendering, content creation
|
|
- **Office**: Primarily office applications and productivity
|
|
|
|
#### Special Requirements
|
|
|
|
- Minimize fan noise
|
|
- Prevent thermal throttling
|
|
- Optimize for external displays
|
|
- Gaming performance priority
|
|
- Maximum WiFi performance
|
|
- Minimize disk wear
|
|
- Fast system wake/sleep
|
|
|
|
## Configuration Examples
|
|
|
|
### Example 1: Gaming Laptop
|
|
|
|
```bash
|
|
Power Profile: Performance
|
|
Use Case: Gaming
|
|
Battery Priority: Balanced
|
|
Performance Mode: Maximum
|
|
Special Requirements: Gaming performance priority, Prevent thermal throttling
|
|
```
|
|
|
|
Generated settings include:
|
|
- CPU governor: performance on AC, balanced on battery
|
|
- Platform profile: performance
|
|
- Aggressive GPU power management
|
|
- Optimized disk settings for game loading
|
|
|
|
### Example 2: Development Workstation
|
|
|
|
```bash
|
|
Power Profile: Balanced
|
|
Use Case: Development
|
|
Battery Priority: Runtime
|
|
Performance Mode: Adaptive
|
|
Special Requirements: Fast system wake/sleep, Minimize fan noise
|
|
```
|
|
|
|
Generated settings include:
|
|
- CPU governor: ondemand on AC, powersave on battery
|
|
- Balanced disk APM levels
|
|
- Conservative thermal management
|
|
- Optimized compilation performance
|
|
|
|
### Example 3: Ultrabook for Office Work
|
|
|
|
```bash
|
|
Power Profile: Power Saving
|
|
Use Case: Office
|
|
Battery Priority: Longevity
|
|
Performance Mode: Efficient
|
|
Special Requirements: Minimize fan noise, Maximum WiFi performance
|
|
```
|
|
|
|
Generated settings include:
|
|
- CPU governor: powersave
|
|
- Aggressive power management
|
|
- Conservative disk settings
|
|
- Optimized for battery longevity
|
|
|
|
## Architecture
|
|
|
|
WiseTLP follows a modular architecture with clear separation of concerns:
|
|
|
|
```
|
|
autotlp/
|
|
├── cmd/autotlp/ # Main application entry point
|
|
├── internal/ # Internal application modules
|
|
│ ├── ai/ # AI client implementation
|
|
│ ├── config/ # Configuration management
|
|
│ ├── security/ # Security and privilege management
|
|
│ ├── system/ # System detection and information gathering
|
|
│ └── tlp/ # TLP installation and configuration
|
|
├── pkg/ # Public packages
|
|
│ ├── types/ # Type definitions
|
|
│ └── utils/ # Utility functions
|
|
├── test/ # Integration tests
|
|
├── docs/ # Documentation
|
|
└── examples/ # Example configurations
|
|
```
|
|
|
|
### Key Components
|
|
|
|
- **System Detector**: Identifies Linux distribution, hardware, and power management capabilities
|
|
- **AI Client**: Handles communication with various AI service providers
|
|
- **TLP Manager**: Manages TLP installation, configuration, and validation
|
|
- **Security Manager**: Handles privilege escalation and secure key storage
|
|
- **Configuration Engine**: Processes user preferences and generates TLP settings
|
|
|
|
## Security Considerations
|
|
|
|
WiseTLP implements several security measures:
|
|
|
|
### API Key Protection
|
|
- API keys are encrypted using AES-GCM with a user-provided master password
|
|
- Keys are stored in `~/.config/autotlp/` with restrictive permissions (0600)
|
|
- Master password is hashed using SHA-256 for verification
|
|
|
|
### Privilege Escalation
|
|
- Minimal privilege escalation using sudo only when necessary
|
|
- Clear user prompts explaining why elevated privileges are required
|
|
- Secure handling of elevated processes with proper exit code propagation
|
|
|
|
### Input Validation
|
|
- Comprehensive input sanitization to prevent injection attacks
|
|
- Path validation to prevent directory traversal vulnerabilities
|
|
- Configuration validation to ensure system stability
|
|
|
|
## Testing
|
|
|
|
WiseTLP includes comprehensive test coverage:
|
|
|
|
```bash
|
|
# Run all tests
|
|
go test ./...
|
|
|
|
# Run tests with coverage
|
|
go test -cover ./...
|
|
|
|
# Run specific package tests
|
|
go test ./pkg/utils
|
|
go test ./internal/system
|
|
go test ./internal/config
|
|
```
|
|
|
|
### Test Categories
|
|
|
|
- **Unit Tests**: Test individual functions and components
|
|
- **Integration Tests**: Test component interactions
|
|
- **System Tests**: Test on various Linux distributions (manual)
|
|
|
|
## Contributing
|
|
|
|
We welcome contributions to WiseTLP! Please follow these guidelines:
|
|
|
|
### Development Setup
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch: `git checkout -b feature-name`
|
|
3. Make your changes with proper tests
|
|
4. Ensure all tests pass: `go test ./...`
|
|
5. Follow Go coding standards and run `gofmt`
|
|
6. Submit a pull request with a clear description
|
|
|
|
### Code Standards
|
|
|
|
- Follow Go best practices and idiomatic patterns
|
|
- Include comprehensive error handling
|
|
- Add tests for new functionality
|
|
- Update documentation for API changes
|
|
- Use structured logging with appropriate log levels
|
|
|
|
### Reporting Issues
|
|
|
|
Please report bugs and feature requests through GitHub Issues:
|
|
|
|
1. Check existing issues first
|
|
2. Provide detailed system information
|
|
3. Include steps to reproduce bugs
|
|
4. Attach relevant log output or configuration files
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
#### TLP Installation Fails
|
|
```
|
|
Error: failed to install TLP: permission denied
|
|
```
|
|
**Solution**: Ensure you have sudo privileges and run with appropriate permissions.
|
|
|
|
#### AI API Connection Issues
|
|
```
|
|
Error: failed to validate AI connection: connection timeout
|
|
```
|
|
**Solution**: Check your internet connection, API key validity, and endpoint URL.
|
|
|
|
#### System Detection Problems
|
|
```
|
|
Error: failed to detect system: unsupported distribution
|
|
```
|
|
**Solution**: WiseTLP supports major distributions. For unsupported distributions, please file an issue.
|
|
|
|
### Debug Mode
|
|
|
|
Enable debug logging for troubleshooting:
|
|
|
|
```bash
|
|
export TLP_DEBUG=1
|
|
./autotlp
|
|
```
|
|
|
|
### Log Files
|
|
|
|
Application logs are written to:
|
|
- stdout/stderr for interactive sessions
|
|
- System journal when run as a service
|
|
|
|
## Performance
|
|
|
|
WiseTLP is designed for efficiency:
|
|
|
|
- **Startup Time**: < 1 second for system detection
|
|
- **AI Response Time**: 5-30 seconds depending on provider and model
|
|
- **Configuration Application**: < 5 seconds
|
|
- **Memory Usage**: < 50MB during operation
|
|
- **Binary Size**: < 10MB compiled
|
|
|
|
|
|
|
|
### Version History
|
|
|
|
- **v1.0.0**: Initial release with core functionality
|
|
- AI-powered configuration generation
|
|
- Multi-provider AI support
|
|
- Comprehensive system detection
|
|
- Secure API key management
|
|
- Automated TLP installation
|
|
|
|
|
|
**WiseTLP** - Intelligent power management for the modern Linux desktop and server.
|