Add New Plugin

Add or Extend an AMC Plugin

Read .github/copilot-instructions.md and relevant architecture guidance. Use CodeGraph when available to inspect PluginFactory, PluginModelContext, ParameterEditor.create_plugin_data_model() and a similar existing plugin.

Integration points

Plugin-specific Python modules belong under ardupilot_methodic_configurator/plugins/, not directly in the package root.

1. Add PLUGIN_<NAME> in ardupilot_methodic_configurator/plugins/plugin_constants.py.
2. Create ardupilot_methodic_configurator/plugins/data_model_<name>.py for the model and its typed business logic dependencies.
3. Create ardupilot_methodic_configurator/plugins/frontend_tkinter_<name>.py for the view and both factories.
4. Add (module_name, registration_function_name) to the lazy registrations tuple in ardupilot_methodic_configurator/__main__.py:register_plugins(). Preserve independent import/error handling so one broken plugin does not prevent others from registering.
5. Append the name to ardupilot_methodic_configurator/configuration_steps_schema.json at plugin > properties > name > enum.
6. Wire relevant ardupilot_methodic_configurator/configuration_steps_<VehicleType>.json entries.
7. Document architecture in the project-root ARCHITECTURE_<name>.md.

ParameterEditor.create_plugin_data_model() is the shared dispatch point: it checks registration and flight-controller requirements, builds a PluginModelContext, and calls the registered model factory. Keep plugin model logic in data_model_<name>.py; do not add plugin-specific imports or branches to the shared dispatcher. The four shared source integration points are the constant, startup registration, plugin-local registration and schema; step wiring and documentation complete the feature.

Factory pattern

Use actual plugin types for view constructors. Factory adapters accept shared interfaces; follow existing narrowly scoped typing adaptations.

Minimal illustrative fragment for ardupilot_methodic_configurator/plugins/frontend_tkinter_<name>.py; it shows the factory wiring and assumes the example model and view classes are defined in that module.

from ardupilot_methodic_configurator.plugins.plugin_constants import PLUGIN_EXAMPLE
from ardupilot_methodic_configurator.plugins.plugin_factory import PluginModelContext, plugin_factory


def _create_model(context: PluginModelContext) -> ExampleDataModel:
    return ExampleDataModel(context.parameter_editor)


def _create_view(parent: tk.Frame | ttk.Frame, model: object, base_window: object) -> ExampleView:
    return ExampleView(parent, model, base_window)  # type: ignore[arg-type]


def register_example_plugin() -> None:
    plugin_factory.register(
        PLUGIN_EXAMPLE,
        _create_view,
        _create_model,
        requires_flight_controller=False,
    )

The context provides flight_controller, local_filesystem and parameter_editor; inject only needed dependencies. FC-required plugins use requires_flight_controller=True (the default). Explicitly opt out for plugins that transform staged parameters and should work offline.

Step wiring and conditions

placement is "left" or "top". Use existing JSON "if" support for firmware/component-dependent visibility instead of duplicating rules in views. For example, a plugin restricted to firmware below 4.7.0:

"plugin": {
    "name": "example",
    "placement": "top",
    "if": "Version(vehicle_components['Flight Controller']['Firmware']['Version'].split(' ')[0]) < Version('4.7.0')"
}

ParameterEditor.get_plugin() evaluates conditions and hides plugins when false or evaluation fails. Test thresholds and unresolved versions as relevant. Use existing version sources consistently; do not assume a connected FC. Respect requested comparison semantics, including prereleases.

Update every applicable bundled vehicle-type JSON. Customized project JSON can override bundled configuration: document required custom-project wiring. Check the actual parameter groups and firmware support for each vehicle before wiring a step. Include a vehicle family only when its firmware provides the plugin's controls; do not infer support from similar names such as ATC_* and AR_*. For firmware-gated behavior, verify the parameter's first supported release and use that evidence to justify the condition.

Views, lifecycle and staged values

• Keep domain rules in models, without Tkinter or external I/O in pure domain calculations. Use existing backend adapters for external operations.
• Implement PluginView behavior, including activation, deactivation and destruction. Cancel timers, callbacks and resources when hidden or removed. Simple views can have no-op lifecycle hooks.
• Wrap user-facing text in _() and provide tooltips for interactive controls.
• Use BaseWindow for standalone windows; follow existing embedded-view patterns.
• Distinguish editing New values from saving or uploading to the FC.
• Respect read-only, forced/derived and metadata constraints. Validate bulk edits before mutation or explicitly report partial outcomes.
• When changing a parameter's explanation, use parameter.change_reason and the parameter's setter APIs. change_reason_for_file is the serialized form and can include markers such as @manual_override; do not feed that form back as user text or append markers yourself.
• For numeric UI input, handle conversion errors separately from range errors and show translated guidance with the accepted range rather than raw Python exception text.
• Refresh with existing helpers in plugins/frontend_tkinter_helpers.py.
• Define whether repeated clicks compound, replace or are idempotent. Test this behavior and disclose potentially surprising effects in the UI.

Optional renderer modules also belong under plugins/; keep them independent of Tkinter. Do not add a renderer if ordinary widgets suffice.