MethodicConfigurator

Vehicle Configuration Directory Selection Sub-Application Architecture

Overview

The Vehicle Configuration Directory Selection sub-application allows users to create a new vehicle configuration project, import one from a configured flight controller or .bin log, or open an existing project. It manages directory selection and downloads parameter documentation for the project firmware.

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 FC values are supplied, template parameter files are transformed during copying; the manager then persists firmware metadata and writes any remaining values to a numbered import file before opening the project.

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
    • New-project choices include template, configured-flight-controller, and .bin log creation
    • VehicleProjectOpenerWindow launches VehicleProjectCreatorWindow for template or configured-FC creation
    • For existing projects: callback functions handle directory selection through VehicleDirectorySelectionWidgets
  3. New Project Creation Flow
    • VehicleProjectCreatorWindow instantiated with project_manager reference
    • Template creation presents a selectable template and optional settings
    • Configured-FC creation resolves the matching empty firmware template automatically and uses live FC values
    • VehicleProjectManager delegates copying to VehicleProjectCreator, persists project metadata, imports any remaining FC values, opens the project, and updates recent-directory history
    • Success and failure feedback is provided through the manager interface
  4. .bin Log Import Flow
    • User clicks Create a vehicle project from a .bin log file in VehicleProjectOpenerWindow (option-1 panel, via BinLogSelectionWidgets)
    • Frontend opens a file-picker; user selects a .bin ArduPilot log file
    • Frontend delegates to project_manager.create_new_vehicle_from_bin_log(bin_file)
    • VehicleProjectManager asks VehicleProjectCreator to extract firmware/default/current parameters, resolve the matching empty template, and copy it without live-FC injection
    • The shared import finalization persists firmware metadata, replaces 00_default.param with extracted defaults, and exports remaining values to a numbered import file
    • The project is opened and manager history/state are updated only after file preparation succeeds
    • Success/failure feedback provided through manager interface; on failure the new directory is not registered in session history and manager in-memory state is not updated, though filesystem changes to the new project directory are not rolled back
  5. 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
  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

This site is open source. Improve this page.