feat(project-opener): create vehicle project from ArduPilot .bin log file

Add a "Create a vehicle project from a .bin log file" button to the
New Vehicle panel in the project-opener window.

Orchestration in data_model_vehicle_project.py
(create_new_vehicle_from_bin_log):
- Scaffolds the project from empty_4.6.x with current FC params used for
  template substitution
- Replaces the template's 00_default.param with the .bin-extracted
  defaults snapshot (key deviation from normal template-based creation)
- Exports remaining current parameters into a numbered
  *_imported_bin_log_parameters.param file

GUI additions:
- BinLogSelectionWidgets reusable widget added to
  frontend_tkinter_directory_selection.py
- Widget wired into VehicleProjectOpenerWindow.create_option1_widgets()

Address Copilot PR review comments for bin log import feature

- Move open_vehicle_directory() to end of create_new_vehicle_from_bin_log() to ensure UI/session operates on authoritative filesystem state after all file modifications (fixes stale state issue)
- Add exception handler for VehicleProjectOpenError in BinLogSelectionWidgets UI to display friendly error dialog instead of crashing
- Extract template directory name to BIN_IMPORT_TEMPLATE_DIR class constant to reduce duplication and ease future maintenance when template version changes
- Add clarifying multi-line comment explaining why infer_comp_specs_and_conn_from_fc_params and use_fc_params flags are reused for log-derived parameters

All 100 tests pass, all code quality checks pass.

Author: amilcarlucas

ARCHITECTURE_3_directory_selection.md

@@ -254,7 +254,38 @@ The data flow follows the layered architecture pattern with clear separation of
    - Project creation delegated to specialized creator services
    - Success/failure feedback provided through manager interface
 
-4. **Existing Project Opening Flow**
+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` orchestrates the following steps via `VehicleProjectCreator`:
+     1. `extract_firmware_version_from_bin_log()` — reads the `VER` (or `MSG`) record from the
+        log to determine vehicle type (e.g. `ArduCopter`) and firmware version (e.g. `4.6.3`);
+        `pymavlink` is imported lazily at call time so it does not slow application startup
+     2. `template_dir_for_bin_import()` — resolves and validates the matching template directory
+        (e.g. `ArduCopter/empty_4.6.x`); raises a user-friendly error if none is installed
+     3. `create_new_vehicle_from_template()` — copies the template with `fc_connected=False`
+        so no live FC values are injected
+     4. `extract_param_files_from_bin_log()` — extracts default and current parameter values
+        from the log's `PARM` messages; also imported lazily
+     5. `LocalFilesystem.fw_version` is set to `"major.minor.patch"` before `re_init()` is
+        called, preventing the template's placeholder version from being used
+     6. `re_init()` — points the filesystem at the new vehicle directory
+     7. `set_fc_fw_version_and_type_in_components_json()` — persists the detected firmware
+        version and type into `vehicle_components.json`
+     8. `write_param_default_values_to_file()` — overwrites `00_default.param` with the
+        log-extracted defaults
+     9. Parameters present in the log but absent/different in the template files are exported
+        to `xx_imported_bin_log_parameters.param`; `re_init()` is called again to pick up
+        the new file
+     10. Manager state (`_settings`, `configuration_template`, recent-dir history) is updated
+         only after `open_vehicle_directory()` succeeds, ensuring manager metadata
+         is committed only on success
+   - 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
@@ -263,14 +294,14 @@ The data flow follows the layered architecture pattern with clear separation of
    - Project state is reconstructed and validated
    - Error handling managed through consistent interface
 
-5. **Architecture Benefits**
+6. **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**
+7. **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

USECASES.md

@@ -12,6 +12,7 @@ Hence the two main use cases are:
 
 But there are other use cases as well:
 
+- [Create a vehicle project from a .bin log file](#create-a-vehicle-project-from-a-bin-log-file)
 - [Create a vehicle configuration based on a correctly configured vehicle](#create-a-vehicle-configuration-based-on-a-correctly-configured-vehicle)
 - [Review and or edit configuration files without having the vehicle FC](#review-and-or-edit-configuration-files-without-having-the-vehicle-fc)
 - [Use the correct default values](#use-the-correct-default-values)
@@ -78,6 +79,42 @@ Please scroll down and make sure you do not miss a property.
 
 If something is not clear, read the [ArduPilot Methodic Configurator user manual](USERMANUAL.md)
 
+## Create a vehicle project from a .bin log file
+
+Use this workflow when you have an ArduPilot `.bin` flight-log file recorded by a vehicle that was already
+running a valid configuration and you want to reconstruct a methodic-configurator project from it —
+no physical flight controller required.
+
+The software reads the `.bin` file to automatically determine:
+
+- **Vehicle type** (e.g. ArduCopter, ArduPlane, Rover) from the log's `VER` or `MSG` record
+- **Firmware version** (major.minor.patch) from the same record — used to select the right
+  parameter-documentation metadata and to populate `vehicle_components.json`
+- **Default parameter values** — the per-build defaults stored in the log (`PARM` messages with `Default` attribute)
+- **Current parameter values** — the values that were actually active when the log was recorded
+
+1. Open the *ArduPilot Methodic Configurator* software.
+1. Select `Skip FC connection, just edit .param files on disk` button.
+![AMC no connection](images/App_screenshot_FC_connection_no_connection.png)
+1. Click the **Create a vehicle project from a .bin log file** button.
+1. In the file-picker that opens, select your `.bin` log file.
+   - The software automatically detects the vehicle type and firmware version.
+   - A matching template directory (e.g. `ArduCopter/empty_4.6.x`) is selected automatically.
+   - The project is named after the log file (without the `.bin` extension) and created in the
+     default vehicles directory.
+   - `00_default.param` is populated with the default values extracted from the log.
+   - A `xx_imported_bin_log_parameters.param` file is created for any current values that differ
+     from the template's parameter files — giving you a clear delta to review and tune.
+   - `vehicle_components.json` is updated with the detected firmware type and version.
+1. Review and edit the vehicle components in the *Vehicle Component Editor* window.
+   The firmware type and version fields will already be pre-filled from the log.
+1. Press *Save data and start configuration*.
+1. You should now see the *Parameter file editor and uploader* window.
+   ![AMC parameter file editor and uploader](images/App_screenshot2.png)
+1. Follow the procedure to [configure the vehicle parameters](USERMANUAL.md#step-4-parameter-file-editor-and-uploader-interface).
+
+If something is not clear, read the [ArduPilot Methodic Configurator user manual](USERMANUAL.md)
+
 ## Create a vehicle configuration based on a correctly configured vehicle
 
 1. Connect the flight controller to the computer using a USB cable.

USERMANUAL.md

@@ -167,7 +167,7 @@ It provides three main options for selecting a vehicle directory:
 
 #### New
 
-Create a new vehicle configuration directory
+Create a new vehicle configuration directory, either from a template or from a `.bin` log file.
 
 #### Open
 
@@ -201,6 +201,23 @@ It's useful for setting up a new vehicle configuration quickly.
 - Enter the name for the new vehicle directory in the "Destination new vehicle name" field.
 - Click the "Create vehicle directory from template" button to create the new vehicle directory on the base directory and copy the template files to it.
 
+### Create a New Vehicle Configuration Directory from a .bin Log File
+
+If you have an ArduPilot `.bin` log file recorded by a correctly running vehicle, the software can
+build a complete project from it — no physical flight controller connection required.
+
+- Click the **Create a vehicle project from a .bin log file** button in the **New** panel.
+- In the file-picker, select your `.bin` log file.
+- The software automatically:
+  - Reads the vehicle type and firmware version from the log's `VER` (or `MSG`) record.
+  - Selects the matching template directory (e.g. `ArduCopter/empty_4.6.x`).
+  - Names the project after the log file (without the `.bin` extension).
+  - Writes the default parameter values extracted from the log into `00_default.param`.
+  - Creates `xx_imported_bin_log_parameters.param` for any current values that differ from the
+    template's parameter files, giving you a clear delta to review.
+  - Sets the firmware type and version in `vehicle_components.json`.
+- You are taken directly to the Vehicle Component Editor with the firmware fields pre-filled.
+
 ### Step 3: Vehicle Component Editor Interface
 
 Here you specify the components of your vehicle, their properties and how they are connected to the flight controller.

ardupilot_methodic_configurator/backend_filesystem_vehicle_components.py

@@ -13,11 +13,11 @@
 from json import dump as json_dump
 from json import load as json_load
 
-# from logging import warning as logging_warning
 # from sys import exit as sys_exit
 from logging import debug as logging_debug
 from logging import error as logging_error
 from logging import info as logging_info
+from logging import warning as logging_warning
 from os import makedirs as os_makedirs
 from os import path as os_path
 from os import walk as os_walk
@@ -338,6 +338,28 @@ def get_fc_fw_version_from_vehicle_components_json(self) -> str:
             logging_error(error_msg.format(version_str=version_str, filename=self.vehicle_components_fs.json_filename))
         return ""
 
+    def set_fc_fw_version_and_type_in_components_json(self, fw_version: str, vehicle_type: str, vehicle_dir: str) -> None:
+        """
+        Update the firmware version and type in the loaded vehicle_components.json and save it to disk.
+
+        This ensures the project's component metadata reflects the actual firmware that was
+        running when the .bin log was recorded, rather than the template's placeholder values.
+
+        Args:
+            fw_version: Full firmware version string in "major.minor.patch" format (e.g. "4.6.3").
+            vehicle_type: Firmware type string (e.g. "ArduCopter").
+            vehicle_dir: Path to the vehicle directory containing vehicle_components.json.
+
+        """
+        data = self.vehicle_components_fs.data
+        if data and "Components" in data:
+            fc_firmware = data["Components"].setdefault("Flight Controller", {}).setdefault("Firmware", {})
+            fc_firmware["Version"] = fw_version
+            fc_firmware["Type"] = vehicle_type
+            error_occurred, msg = self.save_vehicle_components_json_data(data, vehicle_dir)
+            if error_occurred:
+                logging_warning("%s", msg)
+
     @staticmethod
     def supported_vehicles() -> tuple[str, ...]:
         return ("AP_Periph", "AntennaTracker", "ArduCopter", "ArduPlane", "ArduSub", "Blimp", "Heli", "Rover", "SITL")

ardupilot_methodic_configurator/data_model_vehicle_project.py

@@ -16,6 +16,7 @@
 
 from ardupilot_methodic_configurator import _
 from ardupilot_methodic_configurator.backend_filesystem import LocalFilesystem
+from ardupilot_methodic_configurator.data_model_par_dict import is_within_tolerance
 from ardupilot_methodic_configurator.data_model_vehicle_project_creator import NewVehicleProjectSettings, VehicleProjectCreator
 from ardupilot_methodic_configurator.data_model_vehicle_project_opener import VehicleProjectOpener
 
@@ -156,6 +157,92 @@ def create_new_vehicle_from_template(
             self.open_vehicle_directory(new_path)
         return new_path
 
+    def create_new_vehicle_from_bin_log(self, bin_file: str) -> str:
+        """
+        Create a new vehicle configuration directory from an ArduPilot .bin log file.
+
+        The vehicle type and firmware version are extracted from the .bin file itself.
+        The project is based on the matching empty_{major}.{minor}.x template, uses the
+        extracted current parameter values for template substitution, replaces the
+        template's 00_default.param with the extracted defaults snapshot, and exports any
+        remaining parameters missing from the AMC files into a final import file.
+
+        Args:
+            bin_file: Path to the ArduPilot .bin log file
+
+        Returns:
+            The created vehicle directory path
+
+        Raises:
+            VehicleProjectCreationError: If creation, extraction, or template lookup fails
+
+        """
+        firmware_info = self._creator.extract_firmware_version_from_bin_log(bin_file)
+        vehicle_type = firmware_info[0]
+        fw_version = f"{firmware_info[1]}.{firmware_info[2]}.{firmware_info[3]}"
+        template_dir = self._creator.template_dir_for_bin_import(vehicle_type, firmware_info[1], firmware_info[2])
+        default_params, current_params = self._creator.extract_param_files_from_bin_log(bin_file)
+        fc_parameters = {name: param.value for name, param in current_params.items()}
+        settings = NewVehicleProjectSettings(
+            blank_change_reason=True,
+            infer_comp_specs_and_conn_from_fc_params=True,
+            use_fc_params=True,
+        )
+
+        new_path = self._creator.create_new_vehicle_from_template(
+            template_dir,
+            str(LocalFilesystem.get_vehicles_default_dir()),
+            self._creator.vehicle_name_from_bin_log(bin_file),
+            settings,
+            fc_connected=False,
+            fc_parameters=fc_parameters,
+        )
+
+        # Point the filesystem at the new vehicle directory before any reads or writes.
+        # write_param_default_values_to_file() and compound_params() rely on vehicle_dir,
+        # so re_init() must be called here to avoid accidentally operating on the previously-open project.
+        # Set fw_version first so re_init() does not override it with the template's placeholder version.
+        self._local_filesystem.fw_version = fw_version
+        self._local_filesystem.re_init(new_path, vehicle_type)
+        # Persist the correct firmware version and type into vehicle_components.json so subsequent
+        # re_init calls (and the user when they inspect the project) see the actual recorded firmware.
+        self._local_filesystem.set_fc_fw_version_and_type_in_components_json(fw_version, vehicle_type, new_path)
+
+        self._local_filesystem.write_param_default_values_to_file(default_params)
+
+        # Build the baseline from log-extracted defaults plus compounded AMC step files.
+        # This avoids exporting params that merely match 00_default.param but are absent
+        # from the numbered step files.
+        compounded_step_params, _first_config_step = self._local_filesystem.compound_params(skip_default=True)
+        baseline_params = default_params.deep_copy()
+        baseline_params.update(compounded_step_params)
+
+        if imported_params := current_params.get_missing_or_different(baseline_params, is_within_tolerance):
+            self._local_filesystem.export_to_param(
+                imported_params,
+                self._creator.next_import_filename(new_path),
+                annotate_doc=False,
+            )
+            self._local_filesystem.re_init(new_path, vehicle_type)
+
+        if self._flight_controller is not None:
+            self._flight_controller.fc_parameters = fc_parameters
+
+        # Open the vehicle directory only after all file modifications are complete and filesystem state is synced.
+        # This ensures the UI/session operates on the authoritative filesystem state, not stale in-memory cache.
+        # Also note: infer_comp_specs_and_conn_from_fc_params and use_fc_params are reused for log-derived params
+        # because the semantics align: we're supplying external parameter values for template substitution.
+        self.open_vehicle_directory(new_path)
+
+        # Update manager state only after the whole import succeeds so that a failure in any preceding step
+        # (including open_vehicle_directory) does not leave the manager in a partially-updated state and
+        # does not pollute the recently-used template history with an incomplete project.
+        self._settings = settings
+        self.configuration_template = self.get_directory_name_from_path(template_dir)
+        self.store_recently_used_template_dirs(template_dir, str(LocalFilesystem.get_vehicles_default_dir()))
+
+        return new_path
+
     # Vehicle project opening operations
     def open_vehicle_directory(self, vehicle_dir: str) -> str:
         """