feat: add optional step instruction popup

Signed-off-by: Omkar Sarkar <omkarsarkar24@gmail.com>

Author: OmkarSarkar204

ardupilot_methodic_configurator/backend_filesystem_configuration_steps.py

@@ -335,3 +335,9 @@ def get_plugin(self, selected_file: str) -> Optional[dict]:
         if selected_file in self.configuration_steps:
             return self.configuration_steps[selected_file].get("plugin")
         return None
+
+    def get_instructions_popup(self, selected_file: str) -> Optional[dict]:
+        """Get the instructions popup configuration for the selected file."""
+        if selected_file in self.configuration_steps:
+            return self.configuration_steps[selected_file].get("instructions_popup")
+        return None

ardupilot_methodic_configurator/configuration_steps_ArduCopter.json

@@ -283,6 +283,10 @@
             }
         },
         "16_pid_adjustment.param": {
+            "instructions_popup": {
+              "type": "info",
+              "msg": "This step is optional, only perform it if your vehicle is tiny, huge, or its motor outputs oscillate"
+            },
             "why": "With very large or very small vehicles the default PID values are not suitable for the first flight",
             "why_now": "Most other parameters are done and these need to be corrected (depending on the vehicle size) before the first flight",
             "blog_text": "Adjust the Proportional-Integral-Derivative (PID) controllers based on the vehicle size before the first flight",

ardupilot_methodic_configurator/configuration_steps_schema.json

@@ -168,6 +168,23 @@
                   "description": "Where to place the plugin: 'left' for left of scrollable frame, 'top' for above contents"
                 }
               }
+            },
+            "instructions_popup": {
+              "type": "object",
+              "description": "Optional instructions to display as a popup when entering this step",
+              "properties": {
+                "type": {
+                  "type": "string",
+                  "enum": ["info", "warning"],
+                  "description": "The type of popup dialog to display (info or warning)"
+                },
+                "msg": {
+                  "type": "string",
+                  "description": "The instruction message to display to the user"
+                }
+              },
+              "required": ["type", "msg"],
+              "additionalProperties": false
             }
           }
         }

ardupilot_methodic_configurator/configuration_steps_strings.py

@@ -356,6 +356,7 @@ def configuration_steps_descriptions() -> None:
     _config_steps_descriptions = _("Name of tool/process that automatically changes these parameters")
     _config_steps_descriptions = _("Name/description of external tool needed")
     _config_steps_descriptions = _("New value for the parameter")
+    _config_steps_descriptions = _("Optional instructions to display as a popup when entering this step")
     _config_steps_descriptions = _("Phases of the configuration process")
     _config_steps_descriptions = _("Previous filenames for this step")
     _config_steps_descriptions = _("Reason for changing the parameter")
@@ -364,7 +365,9 @@ def configuration_steps_descriptions() -> None:
     _config_steps_descriptions = _("Short description for wiki reference")
     _config_steps_descriptions = _("Starting step number of this phase")
     _config_steps_descriptions = _("Text indicating if step is mandatory or optional with percentages")
+    _config_steps_descriptions = _("The instruction message to display to the user")
     _config_steps_descriptions = _("The name of the plugin to load")
+    _config_steps_descriptions = _("The type of popup dialog to display (info or warning)")
     _config_steps_descriptions = _("URL to blog documentation")
     _config_steps_descriptions = _("URL to external tool")
     _config_steps_descriptions = _("URL to wiki documentation")

ardupilot_methodic_configurator/data_model_parameter_editor.py

@@ -2170,6 +2170,10 @@ def parse_mandatory_level_percentage(self, text: str) -> tuple[int, str]:
     def get_plugin(self, filename: str) -> Optional[dict]:
         return self._local_filesystem.get_plugin(filename)
 
+    def get_instructions_popup(self, filename: str) -> Optional[dict]:
+        """Get the optional instructions popup data for a given configuration step."""
+        return self._local_filesystem.get_instructions_popup(filename)
+
     def create_plugin_data_model(self, plugin_name: str) -> Optional[object]:
         """
         Create and return a data model for the specified plugin.

ardupilot_methodic_configurator/frontend_tkinter_parameter_editor.py

@@ -1028,6 +1028,17 @@ def on_param_file_combobox_change(self, _event: Union[None, tk.Event], forced: b
             self.repopulate_parameter_table()
             self._update_skip_button_state()
 
+            # Display optional instruction step
+            popup_data = self.parameter_editor.get_instructions_popup(final_file)
+            if popup_data:
+                msg = popup_data.get("msg", "")
+                popup_type = popup_data.get("type", "info")
+
+                if popup_type == "warning":
+                    self.ui.show_warning(_("Step Instructions"), _(msg))
+                else:
+                    self.ui.show_info(_("Step Instructions"), _(msg))
+
     def _update_progress_bar_from_file(self, selected_file: str) -> None:
         if self.parameter_editor.configuration_phases():
             try:

tests/test_backend_filesystem_configuration_steps.py

@@ -641,5 +641,21 @@ def test_multiple_forced_param_errors_collected() -> None:
     assert config_steps.forced_parameters["test_file"]["GOOD2"].value == 20
 
 
+def test_get_instructions_popup() -> None:
+    """Test that the filesystem correctly retrieves the instructions popup dictionary."""
+    config_steps = ConfigurationSteps("dummy_dir", "dummy_type")
+    config_steps.configuration_steps = {
+        "16_pid_adjustment.param": {"instructions_popup": {"type": "info", "msg": "Test message"}},
+        "other.param": {},
+    }
+
+    # Test when it exists
+    assert config_steps.get_instructions_popup("16_pid_adjustment.param") == {"type": "info", "msg": "Test message"}
+    # Test when it doesn't exist
+    assert config_steps.get_instructions_popup("other.param") is None
+    # Test when file doesn't exist
+    assert config_steps.get_instructions_popup("missing.param") is None
+
+
 if __name__ == "__main__":
     unittest.main()

tests/test_frontend_tkinter_parameter_editor.py

@@ -2002,3 +2002,41 @@ def test_multiple_button_clicks_invoke_workflow_each_time(self, parameter_editor
 
         # Assert - workflow was called three times
         assert param_editor_mock.create_forum_help_zip_workflow.call_count == 3
+
+
+class TestStepInstructionsPopupWorkflows:
+    """Cover the step instructions popup behaviors when navigating files."""
+
+    def test_user_sees_info_popup_when_instructions_exist(self, parameter_editor_window: ParameterEditorWindow) -> None:
+        """
+        User receives an informational popup for steps with info instructions.
+
+        GIVEN: Instructions exist with type 'info'
+        WHEN: The parameter file changes to that step
+        THEN: An info popup is displayed to the user
+        """
+        param_editor_mock = cast("MagicMock", parameter_editor_window.parameter_editor)
+        param_editor_mock.get_instructions_popup.return_value = {"type": "info", "msg": "Test info message"}
+
+        parameter_editor_window.on_param_file_combobox_change(None)
+
+        ui_mock = cast("MagicMock", parameter_editor_window.ui)
+        ui_mock.show_info.assert_called_once_with("Step Instructions", "Test info message")
+        ui_mock.show_warning.assert_not_called()
+
+    def test_user_sees_warning_popup_when_instructions_exist(self, parameter_editor_window: ParameterEditorWindow) -> None:
+        """
+        User receives a warning popup for steps with warning instructions.
+
+        GIVEN: Instructions exist with type 'warning'
+        WHEN: The parameter file changes to that step
+        THEN: A warning popup is displayed to the user
+        """
+        param_editor_mock = cast("MagicMock", parameter_editor_window.parameter_editor)
+        param_editor_mock.get_instructions_popup.return_value = {"type": "warning", "msg": "Test warning message"}
+
+        parameter_editor_window.on_param_file_combobox_change(None)
+
+        ui_mock = cast("MagicMock", parameter_editor_window.ui)
+        ui_mock.show_warning.assert_called_once_with("Step Instructions", "Test warning message")
+        ui_mock.show_info.assert_not_called()