Crankshaft Management Tool (CSMT) - Documentation

Overview

The Crankshaft Management Tool (CSMT) is a comprehensive Python-based system management utility designed for OpenAuto systems. It replaces the original bash-based crankshaft script with a modular, maintainable, and extensible Python application.

✅ Status: Complete Rewrite Finished

• ✅ Modular Python architecture implemented
• ✅ All subsystem modules completed
• ✅ Cross-platform compatibility (Windows & Linux)
• ✅ Full CLI with subcommands
• ✅ Documentation and testing complete

🔗 See also: Windows Notes for Windows-specific information.

Table of Contents

• Installation
• Quick Start
• Command Reference
• Architecture
• Module Documentation
• Configuration
• Development
• Troubleshooting

Installation

Prerequisites

• Python 3.7 or higher
• Required Python packages (see requirements.txt)
• Root access for system operations
• Raspberry Pi or compatible system for hardware-specific features

Setup

1. Clone or copy the CSMT directory to your system
2. Install dependencies:

   pip3 install -r requirements.txt

3. Make the script executable:

   chmod +x csmt/crankshaft.py

4. Optionally, create a symlink for system-wide access:

   sudo ln -s /path/to/csmt/crankshaft.py /usr/local/bin/crankshaft

Quick Start

Basic Usage

# Show help
./crankshaft.py --help

# Check system information
./crankshaft.py system info

# Control brightness
./crankshaft.py brightness get
./crankshaft.py brightness set 128

# Manage audio
./crankshaft.py audio volume 75
./crankshaft.py audio devices

# System operations
./crankshaft.py system reboot
./crankshaft.py system shutdown

# Bluetooth management
./crankshaft.py bluetooth scan
./crankshaft.py bluetooth devices

Common Use Cases

1. System Monitoring:

   ./crankshaft.py misc diagnostics
   ./crankshaft.py system info
   ./crankshaft.py filesystem usage

2. Audio Setup:

   ./crankshaft.py audio devices
   ./crankshaft.py audio volume 50
   ./crankshaft.py audio test

3. Display Configuration:

   ./crankshaft.py display info
   ./crankshaft.py display resolution 1920 1080
   ./crankshaft.py display rotate 90

4. Bluetooth Setup:

   ./crankshaft.py bluetooth enable
   ./crankshaft.py bluetooth scan
   ./crankshaft.py bluetooth pair AA:BB:CC:DD:EE:FF

Command Reference

Global Options

• --verbose, -v: Enable verbose output
• --quiet, -q: Suppress banner and non-essential output
• --version: Show version information

Brightness Commands

• brightness get: Show current brightness level
• brightness set <level>: Set brightness (0-255)
• brightness up [--step N]: Increase brightness
• brightness down [--step N]: Decrease brightness
• brightness auto <enable>: Enable/disable auto brightness

Audio Commands

• audio devices: List available audio devices
• audio info: Show audio system information
• audio volume [level]: Get/set volume (0-100)
• audio mute: Mute audio
• audio unmute: Unmute audio
• audio output <device>: Set audio output device
• audio bluetooth <enable|disable>: Control Bluetooth audio
• audio test: Test audio output

System Commands

• system info: Show system information
• system reboot [--delay N]: Reboot system
• system shutdown [--delay N]: Shutdown system
• system service <name> <action>: Manage services
• system processes [--filter NAME]: List processes
• system kill <pid> [--force]: Kill process

Bluetooth Commands

• bluetooth enable: Enable Bluetooth
• bluetooth disable: Disable Bluetooth
• bluetooth info: Show Bluetooth information
• bluetooth scan [--duration N]: Scan for devices
• bluetooth devices: List paired devices
• bluetooth pair <address>: Pair with device
• bluetooth unpair <address>: Unpair device
• bluetooth connect <address>: Connect to device
• bluetooth disconnect <address>: Disconnect from device
• bluetooth trust <address>: Trust device
• bluetooth untrust <address>: Untrust device

Display Commands

• display info: Show display information
• display resolution [width height]: Get/set resolution
• display rotate [degrees]: Get/set rotation (0,90,180,270)
• display overscan [options]: Control overscan
• display test: Test display output

Filesystem Commands

• filesystem usage [path]: Show disk usage
• filesystem mounts: Show mounted filesystems
• filesystem info: Show filesystem information
• filesystem mount <device> <mountpoint>: Mount filesystem
• filesystem unmount <mountpoint>: Unmount filesystem
• filesystem readonly [enable|disable]: Control read-only root
• filesystem check <device> [--fix]: Check filesystem
• filesystem clean: Clean temporary files

Update Commands

• update check [system|openauto]: Check for updates
• update system: Update system packages
• update openauto: Update OpenAuto
• update install <package>: Install package
• update remove <package>: Remove package
• update clean: Clean package cache
• update packages: List installed packages
• update backup [--path DIR]: Create system backup

Miscellaneous Commands

• misc hardware: Show hardware information
• misc network: Show network status
• misc hostname [name]: Get/set hostname
• misc logs [--service NAME]: Show system logs
• misc monitor [--duration N]: Monitor system resources
• misc diagnostics: Run system diagnostics

Architecture

Directory Structure

csmt/
├── crankshaft.py          # Main CLI entry point
├── csmt/                  # Main package
│   ├── __init__.py       # Package initialization
│   ├── core.py           # Core manager
│   ├── modules/          # Subsystem modules
│   │   ├── __init__.py
│   │   ├── audio.py      # Audio management
│   │   ├── brightness.py # Brightness control
│   │   ├── bluetooth.py  # Bluetooth management
│   │   ├── display.py    # Display configuration
│   │   ├── filesystem.py # Filesystem operations
│   │   ├── misc.py       # Miscellaneous utilities
│   │   ├── system.py     # System management
│   │   └── update.py     # Update management
│   └── utils/            # Utility modules
│       ├── __init__.py
│       ├── config.py     # Configuration management
│       ├── display.py    # Output formatting
│       ├── exceptions.py # Custom exceptions
│       └── logger.py     # Logging setup
└── docs/                 # Documentation
    ├── README.md         # This file
    ├── ARCHITECTURE.md   # Detailed architecture
    ├── API.md            # API documentation
    └── EXAMPLES.md       # Usage examples

Design Principles

1. Modularity: Each subsystem is implemented as a separate module
2. Extensibility: Easy to add new commands and features
3. Error Handling: Comprehensive error handling and logging
4. Configuration: Centralized configuration management
5. Testing: Designed for easy unit testing
6. Documentation: Well-documented code and APIs

Core Components

1. CLI Parser (crankshaft.py): Command-line interface and argument parsing
2. Core Manager (core.py): Central coordinator for all operations
3. Subsystem Modules (modules/): Individual feature implementations
4. Utilities (utils/): Common utilities and helpers

Module Documentation

Audio Module (modules/audio.py)

Handles audio device management, volume control, and audio configuration.

Key Features:

• Audio device detection and listing
• Volume control and muting
• Audio output device selection
• Bluetooth audio support
• Audio testing capabilities

Brightness Module (modules/brightness.py)

Manages display brightness control and auto-brightness features.

Key Features:

• Current brightness detection
• Brightness level adjustment
• Auto-brightness configuration
• Brightness stepping (up/down)

Bluetooth Module (modules/bluetooth.py)

Comprehensive Bluetooth device management.

Key Features:

• Bluetooth controller management
• Device scanning and discovery
• Pairing and unpairing
• Connection management
• Device trust settings

Display Module (modules/display.py)

Display configuration and management.

Key Features:

• Resolution detection and setting
• Display rotation control
• Overscan configuration
• Display testing

Filesystem Module (modules/filesystem.py)

Filesystem operations and management.

Key Features:

• Disk usage monitoring
• Mount point management
• Read-only filesystem control
• Filesystem checking and repair
• Temporary file cleanup

System Module (modules/system.py)

Core system operations and monitoring.

Key Features:

• System information reporting
• Process management
• Service control
• System reboot/shutdown
• Resource monitoring

Update Module (modules/update.py)

Package and system update management.

Key Features:

• Update checking
• Package installation/removal
• System updates
• Backup creation
• Package cache management

Misc Module (modules/misc.py)

Miscellaneous utilities and diagnostics.

Key Features:

• Hardware information
• Network status
• System diagnostics
• Log file access
• Resource monitoring

Configuration

Configuration Files

The tool manages several configuration files:

1. Boot Configuration (/boot/config.txt): Raspberry Pi boot settings
2. Environment Configuration: System environment variables
3. Brightness Configuration: Saved brightness levels

Configuration Management

The ConfigManager class provides centralized configuration handling:

• Read/write boot configuration
• Environment variable management
• Configuration validation
• Backup and restore capabilities

Development

Adding New Commands

1. Create/Extend Module: Add functionality to appropriate module in modules/
2. Update CLI: Add command parser in crankshaft.py
3. Update Core: Add command routing in core.py
4. Add Tests: Create unit tests for new functionality
5. Update Documentation: Update this README and module docs

Code Style

• Follow PEP 8 Python style guidelines
• Use type hints where appropriate
• Include comprehensive docstrings
• Handle errors gracefully
• Log important operations

Testing

# Run unit tests
python -m pytest tests/

# Run specific module tests
python -m pytest tests/test_audio.py

# Run with coverage
python -m pytest --cov=csmt tests/

Troubleshooting

Common Issues

1. Permission Denied:

   • Ensure script is run with appropriate privileges
   • Use sudo for system operations

2. Module Import Errors:

   • Check Python path configuration
   • Verify all dependencies are installed

3. Hardware-Specific Features:

   • Some features require specific hardware (Raspberry Pi)
   • Check system compatibility

Debugging

Use verbose mode for detailed output:

./crankshaft.py --verbose <command>

Check logs for error details:

./crankshaft.py misc logs --service crankshaft

Getting Help

1. Check this documentation
2. Use built-in help: ./crankshaft.py --help
3. Check specific command help: ./crankshaft.py <command> --help
4. Review log files for error details

Version History

• v2.5.0: Initial Python rewrite
  • Modular architecture
  • Comprehensive command set
  • Improved error handling
  • Enhanced logging

License

GPL-3.0 License - See LICENSE file for details.