MethodicConfigurator

Vehicle Configuration Directory Selection Sub-Application Architecture

Overview

The Vehicle Configuration Directory Selection sub-application allows users to either create a new vehicle configuration project or open an existing one. It manages the selection and creation of vehicle directories, handles template selection, and downloads parameter documentation metadata corresponding to the flight controller firmware version to the project directory.

The architecture follows a clean layered design with dependency injection, where the frontend components depend on the VehicleProjectManager factory/container class, which provides a unified interface to all backend services. This ensures loose coupling and better testability.

Requirements

Functional Requirements

  1. Directory Management
    • Must allow creation of new vehicle configuration directories
    • Must allow opening of existing vehicle configuration directories
    • Must provide re-open functionality for recently used directories
    • Must validate directory structure and required files
    • Must handle directory permissions and access rights
  2. Template System
    • Must provide a comprehensive template overview interface
    • Must support multiple vehicle types (ArduCopter, ArduPlane, Rover, Heli, etc.)
    • Must allow template selection based on vehicle characteristics
    • Must copy template files to new vehicle directories
    • Must preserve template structure and file organization
  3. Vehicle Template Selection
    • Must display available templates with descriptions
    • Must show template compatibility information
    • Must provide visual representation of template contents
    • Must allow filtering and searching of templates
    • Must support template comparison features
  4. Parameter Documentation Management
    • Must download parameter documentation metadata for FC firmware version
    • Must store documentation files in the appropriate project directory
    • Must handle offline operation when documentation is already available
    • Must validate documentation file integrity
    • Must support multiple documentation formats
  5. Project Configuration
    • Must initialize project configuration files
    • Must set up directory structure for parameter files
    • Must create necessary subdirectories and organize files
    • Must handle configuration file validation
    • Must support project metadata management
  6. Recent Vehicle Directories History
    • Must maintain a list of the 5 most recently opened vehicle directories
    • Must display recent directories in reverse chronological order (most recent first)
    • Must persist the history list across application sessions in settings.json
    • Must update history when a vehicle directory is successfully opened
    • Must preserve history entries for directories that become temporarily unavailable
    • Must be permissive when storing paths (directories may become valid later)
    • Must validate paths strictly when opening/using them (show error if invalid or missing)
    • Must display history in a read-only combobox widget with full absolute paths
    • Must allow selection from history via dropdown selection only (no text editing)
    • Must show error message if selected directory no longer exists
    • Must maintain history order when the same directory is opened again (promote to top)
    • Must limit history to maximum of 5 entries (oldest removed when limit exceeded)
    • Must normalize path separators according to the operating system (backslashes on Windows, forward slashes on Unix)
    • Must provide graceful fallback if history is empty or corrupted

Non-Functional Requirements

  1. Usability
    • Directory selection should be intuitive and user-friendly
    • Template overview should provide clear visual guidance
    • File operations should provide clear progress feedback
    • Error messages should be actionable and informative
  2. Performance
    • Directory operations should complete quickly
    • Template copying should handle large file sets efficiently
    • Documentation download should not block the user interface
    • Memory usage should be optimized for large template collections
  3. Reliability
    • Must handle incomplete or corrupted templates gracefully
    • Must verify successful completion of all file operations
    • Must provide rollback capability for failed operations
    • Must maintain project integrity during all operations
  4. Compatibility
    • Must support different operating system path conventions
    • Must handle various file system limitations
    • Must work with different permission systems
    • Must support unicode file names and paths

Architecture

Architectural Pattern

The directory selection sub-application follows a Factory/Container Pattern with Dependency Injection:

This architecture ensures:

GUI Frontend Components

Project Opener Window

frontend_tkinter_project_opener

Project Creator Window

frontend_tkinter_project_creator

Template Overview Window

Directory Selection Widgets

Business logic components

VehicleProjectManager (Facade/Factory)

Backend Components (accessed via VehicleProjectManager)

Project Creation Services

When use_fc_params=True and FC parameters are available, LocalFilesystem.copy_template_files_to_new_vehicle_dir() applies both blank_change_reason and FC value substitution in a single ParDict-based parse-modify-write pass per .param file, before re_init loads the directory.

Project Opening Services

Configuration Steps Backend

Vehicle Components Backend

Data Flow

The data flow follows the layered architecture pattern with clear separation of concerns:

  1. Application Initialization
    • Legacy settings migration: ProgramSettings.migrate_settings_to_latest_version() runs once on startup
    • VehicleProjectManager is instantiated with required backend services
    • VehicleProjectOpenerWindow receives VehicleProjectManager instance via dependency injection
    • Recent directories history loaded via ProgramSettings.get_recent_vehicle_dirs()
    • Templates are loaded through VehicleProjectManager
    • UI components are initialized with project manager reference
  2. Project Selection Flow
    • User interacts with VehicleProjectOpenerWindow main interface
    • Three options presented: Create New, Open Existing, Re-open Last Used
    • For new projects: VehicleProjectOpenerWindow launches VehicleProjectCreatorWindow
    • For existing projects: callback functions handle directory selection through VehicleDirectorySelectionWidgets
  3. New Project Creation Flow
    • VehicleProjectCreatorWindow instantiated with project_manager reference
    • User optionally enables use_fc_params
    • VehicleProjectCreator creates the directory from template
    • During the copy step, FC source values and/or blank-change-reason are applied in a single ParDict-based pass so that re_init reads fully-initialized files with no further writes
    • Frontend presents template selection and project configuration options
    • User selects template through TemplateOverviewWindow integration
    • Frontend delegates to project_manager.create_new_vehicle_from_template()
    • VehicleProjectManager coordinates with project creator services
    • Project creation delegated to specialized creator services
    • Success/failure feedback provided through manager interface
  4. Existing Project Opening Flow
    • User interacts with VehicleProjectOpenerWindow
    • Frontend presents project opening and re-opening options
    • User selects existing directory through DirectorySelectionWidgets with callbacks
    • Callback functions call project_manager.open_vehicle_directory() or project_manager.open_last_vehicle_directory()
    • VehicleProjectManager validates directory through opener services
    • Project state is reconstructed and validated
    • Error handling managed through consistent interface
  5. Architecture Benefits
    • Frontend never directly accesses backend services
    • All business logic centralized in VehicleProjectManager
    • Easy to test with mock VehicleProjectManager
    • Changes to backend services don’t affect frontend code
    • Clean separation between project opening and project creation concerns
  6. Recent Directories History Flow
    • On application startup, ProgramSettings.get_recent_vehicle_dirs() loads history from settings.json; the history is passed through the manager
    • History is passed to VehicleProjectOpenerWindow to populate the combobox widget
    • User selects a directory from the combobox dropdown
    • Frontend calls project_manager.open_vehicle_directory(selected_dir)
    • The VehicleProjectManager (business logic) stores the path in the recent‑vehicle history using LocalFilesystem/ProgramSettings abstractions; the frontend never touches the persistence layer directly
    • History is updated: selected directory moved/added to position [0], oldest removed if > 5 entries
    • Updated history is persisted to settings.json
    • History order maintained: most recent [0] to oldest [4]

Data Models and Storage

Recent Vehicle Directories History Storage

The recent vehicle directories are stored in the settings.json file in the user configuration directory:

Settings File Location:

Data Structure in settings.json:

{
    "Format version": 2,
    "recent_vehicle_history": [
        "C:\\Users\\username\\vehicles\\Quadcopter_Project_2026",
        "C:\\Users\\username\\vehicles\\Hexacopter_Project",
        "/mnt/projects/ArduPlane_Project",
        "C:\\Users\\username\\Documents\\Old_Copter",
        "/home/user/ardupilot/Test_Vehicle"
    ],
    "directory_selection": {
        "template_dir": "...",
        "new_base_dir": "..."
    },
    "display_usage_popup": { ... },
    "connection_history": [ ... ]
}

Data Schema:

Backward Compatibility:

Integration Points

The directory selection sub-application integrates with other components through the VehicleProjectManager interface:

Dependency Management

The architecture implements Dependency Inversion Principle:

Frontend (GUI) → VehicleProjectManager (Interface) → Backend Services

Dependencies Flow:

Benefits:

Template Management

Template Structure

Templates are organized hierarchically by vehicle type:

vehicle_templates/
├── ArduCopter/
│   ├── X-Quadcopter/
│   ├── Y6-Hexacopter/
│   └── Traditional-Helicopter/
├── ArduPlane/
│   ├── Fixed-Wing/
│   └── VTOL/
└── Rover/
    ├── 4WD/
    └── Boat/

Template Content

Each template contains:

Error Handling Strategy

Testing Strategy

The layered architecture enables comprehensive testing at each level:

Unit Testing

Test Fixtures and Mocking

Test Coverage Areas

Architecture Testing Benefits

Note: Acceptance tests for the Recent Vehicle Directories History feature are implemented in tests/acceptance_recent_vehicle_directories_history.py.

File Structure

# Frontend Layer (GUI)
frontend_tkinter_project_opener.py         # Main vehicle project selection interface
frontend_tkinter_project_creator.py        # Dedicated new project creation interface
frontend_tkinter_directory_selection.py    # Reusable directory selection widgets with callback support
frontend_tkinter_template_overview.py      # Template browsing and selection interface

# Facade/Factory Layer (Business Logic Coordination)
data_model_vehicle_project.py              # VehicleProjectManager facade/factory

# Backend Services Layer (Specialized Operations)
data_model_vehicle_project_creator.py      # New project creation services
data_model_vehicle_project_opener.py       # Existing project opening services
backend_filesystem.py                      # File system operations
backend_filesystem_configuration_steps.py  # Configuration step management
backend_filesystem_vehicle_components.py   # Vehicle component handling

# Test Layer
tests/test_frontend_tkinter_project_opener.py          # Project opener tests with mocked dependencies
tests/test_frontend_tkinter_project_creator.py         # Project creator tests with mocked dependencies
tests/test_frontend_tkinter_directory_selection.py     # Directory widgets tests
tests/test_frontend_tkinter_template_overview.py       # Template overview tests
tests/acceptance_recent_vehicle_directories_history.py # Acceptance tests for recent directories history feature

Dependencies

External Dependencies

Internal Architecture Dependencies

Dependency Injection Pattern

The architecture implements dependency injection where:

Architectural Benefits

Design Patterns Implemented

  1. Facade Pattern: VehicleProjectManager provides simplified interface to complex backend subsystems
  2. Factory Pattern: VehicleProjectManager creates and manages project-related objects
  3. Dependency Injection: Components receive dependencies via constructor parameters
  4. Layer Architecture: Clear separation between frontend, facade, and backend layers

Code Quality Improvements

Development Benefits

Template System Features

Template Categories

Template Validation

Template Customization

Performance Optimization

This site is open source. Improve this page.