|
| 1 | +--- |
| 2 | +name: add-new-plugin |
| 3 | +description: 'Add a new plugin to ArduPilot Methodic Configurator (AMC). Use when implementing a new calibration, monitoring, or configuration plugin — e.g., "add a radio calibration plugin". Covers all five mandatory touch-points: plugin_constants.py, __main__.py, data_model_parameter_editor.py, frontend_tkinter_*.py, and configuration_steps_schema.json, plus the optional configuration_steps_*.json wiring and an optional renderer module.' |
| 4 | +argument-hint: 'plugin name (e.g. radio_calibration)' |
| 5 | +--- |
| 6 | + |
| 7 | +# Add a New Plugin to AMC |
| 8 | + |
| 9 | +## When to Use |
| 10 | + |
| 11 | +- Implementing a new GUI panel that appears alongside parameter editing (calibration, |
| 12 | + monitoring, testing, …). |
| 13 | +- Extending an existing configuration step with a plugin widget. |
| 14 | + |
| 15 | +## Background |
| 16 | + |
| 17 | +AMC uses a **plugin factory** pattern. Every plugin consists of: |
| 18 | + |
| 19 | +| Layer | File(s) | |
| 20 | +| ------- | --------- | |
| 21 | +| Constant | `plugin_constants.py` | |
| 22 | +| Data model | `data_model_<plugin>.py` | |
| 23 | +| Frontend | `frontend_tkinter_<plugin>.py` | |
| 24 | +| Registration | `__main__.py → register_plugins()` | |
| 25 | +| Data-model wiring | `data_model_parameter_editor.py → create_plugin_data_model()` | |
| 26 | +| Schema | `configuration_steps_schema.json` | |
| 27 | +| Step wiring | `configuration_steps_<VehicleType>.json` | |
| 28 | +| Architecture doc | `ARCHITECTURE_<plugin_name>.md` in the project root | |
| 29 | +| Renderer (optional) | `renderer_<name>.py` — for plugins needing a dedicated visualisation helper | |
| 30 | + |
| 31 | +The inline docs in `plugin_constants.py`, `__main__.py:register_plugins()`, and |
| 32 | +`data_model_parameter_editor.py:create_plugin_data_model()` should be kept in sync |
| 33 | +with this skill (schema path: `plugin > properties > name > enum`). |
| 34 | + |
| 35 | +--- |
| 36 | + |
| 37 | +## Step-by-Step Procedure |
| 38 | + |
| 39 | +### 1. Add the constant — `plugin_constants.py` |
| 40 | + |
| 41 | +Add a `PLUGIN_<NAME>` constant at the bottom of the file: |
| 42 | + |
| 43 | +```python |
| 44 | +PLUGIN_<NAME> = "<snake_case_name>" |
| 45 | +``` |
| 46 | + |
| 47 | +Example (RC calibration): |
| 48 | + |
| 49 | +```python |
| 50 | +PLUGIN_RC_CALIBRATION = "rc_calibration" |
| 51 | +``` |
| 52 | + |
| 53 | +### 2. Create the data model — `data_model_<plugin>.py` |
| 54 | + |
| 55 | +Create `ardupilot_methodic_configurator/data_model_<plugin>.py`. |
| 56 | + |
| 57 | +- Accept `flight_controller: FlightController` (and optionally |
| 58 | + `local_filesystem: LocalFilesystem`) in `__init__`. |
| 59 | +- Expose only business logic; **no tkinter imports**. |
| 60 | +- Follow the same structure as `data_model_accelerometer_calibration.py` or |
| 61 | + `data_model_battery_monitor.py` for inspiration. |
| 62 | + |
| 63 | +### 3. Create the frontend — `frontend_tkinter_<plugin>.py` |
| 64 | + |
| 65 | +Create `ardupilot_methodic_configurator/frontend_tkinter_<plugin>.py`. |
| 66 | + |
| 67 | +Mandatory elements: |
| 68 | + |
| 69 | +```python |
| 70 | +from ardupilot_methodic_configurator.plugin_constants import PLUGIN_<NAME> |
| 71 | +from ardupilot_methodic_configurator.plugin_factory import plugin_factory |
| 72 | + |
| 73 | +def _create_<plugin>_view(parent: object, model: object, base_window: object) -> <PluginView>: |
| 74 | + # Type checker verifies correct types are provided by the caller |
| 75 | + return <PluginView>(parent, model, base_window) # type: ignore[arg-type] |
| 76 | + |
| 77 | +def register_<plugin>_plugin() -> None: |
| 78 | + """Register the <plugin> plugin with the factory.""" |
| 79 | + plugin_factory.register(PLUGIN_<NAME>, _create_<plugin>_view) |
| 80 | +``` |
| 81 | + |
| 82 | +Optionally add a standalone `<PluginName>Window(BaseWindow)` class for |
| 83 | +development/testing (mark it `# pragma: no cover`). |
| 84 | + |
| 85 | +### 4. Register the plugin — `__main__.py → register_plugins()` |
| 86 | + |
| 87 | +Inside `register_plugins()` add a deferred import and a registration call: |
| 88 | + |
| 89 | +```python |
| 90 | +from ardupilot_methodic_configurator.frontend_tkinter_<plugin> import ( # noqa: PLC0415 |
| 91 | + register_<plugin>_plugin, |
| 92 | +) |
| 93 | +# ... |
| 94 | +register_<plugin>_plugin() |
| 95 | +``` |
| 96 | + |
| 97 | +Keep imports inside the function body to avoid circular-import issues (the |
| 98 | +`frontend_tkinter_*` modules import `plugin_factory` at module level). |
| 99 | + |
| 100 | +### 5. Wire the data model — `data_model_parameter_editor.py → create_plugin_data_model()` |
| 101 | + |
| 102 | +Add an `if` branch **before** the `raise ValueError` at the end: |
| 103 | + |
| 104 | +```python |
| 105 | +from ardupilot_methodic_configurator.data_model_<plugin> import <PluginDataModel> |
| 106 | +from ardupilot_methodic_configurator.plugin_constants import PLUGIN_<NAME> |
| 107 | + |
| 108 | +# inside create_plugin_data_model(): |
| 109 | +if plugin_name == PLUGIN_<NAME>: |
| 110 | + return <PluginDataModel>(self._flight_controller) if self.is_fc_connected else None |
| 111 | +``` |
| 112 | + |
| 113 | +Add the import with the other data-model imports near the top of the file, maintaining |
| 114 | +**alphabetical order** within the `data_model_*` import block (ruff enforces sorted |
| 115 | +imports and will flag violations during `ruff check`). |
| 116 | + |
| 117 | +### 6. Update the schema — `configuration_steps_schema.json` |
| 118 | + |
| 119 | +Find the `plugin > properties > name > enum` array and append the new plugin |
| 120 | +name string: |
| 121 | + |
| 122 | +```json |
| 123 | +"enum": [ |
| 124 | + "motor_test", |
| 125 | + "battery_monitor", |
| 126 | + "compass_calibration", |
| 127 | + "accelerometer_calibration", |
| 128 | + "<snake_case_name>" |
| 129 | +] |
| 130 | +``` |
| 131 | + |
| 132 | +### 7. (Optional) Wire to a configuration step — `configuration_steps_<VehicleType>.json` |
| 133 | + |
| 134 | +To show the plugin in a specific parameter-editing step, add a `"plugin"` key |
| 135 | +to the relevant step object: |
| 136 | + |
| 137 | +```json |
| 138 | +"<param_file>.param": { |
| 139 | + "why": "...", |
| 140 | + "plugin": { |
| 141 | + "name": "<snake_case_name>", |
| 142 | + "placement": "left" |
| 143 | + } |
| 144 | +} |
| 145 | +``` |
| 146 | + |
| 147 | +`placement` is either `"left"` (beside the scrollable frame) or `"top"` (above |
| 148 | +the parameter list). Repeat for each vehicle-type JSON that should display the |
| 149 | +plugin (`configuration_steps_ArduCopter.json`, `configuration_steps_ArduPlane.json`, |
| 150 | +`configuration_steps_Heli.json`, `configuration_steps_Rover.json`). |
| 151 | + |
| 152 | +### 8. Create the architecture document — `ARCHITECTURE_<plugin_name>.md` |
| 153 | + |
| 154 | +Every plugin must have a corresponding architecture document in the project root. |
| 155 | +Follow the same structure as `ARCHITECTURE_accelerometer_calibration.md` or |
| 156 | +`ARCHITECTURE_rc_calibration.md`: |
| 157 | + |
| 158 | +- Overview paragraph + key features list |
| 159 | +- Component layers ASCII diagram |
| 160 | +- File map table |
| 161 | +- Requirements Analysis (functional + non-functional) with ✅ / 🟡 / ❌ status |
| 162 | +- Data flow section (sequence diagrams in code blocks) |
| 163 | +- Any plugin-specific design notes (e.g., popup window, renderer module) |
| 164 | +- External reference links (MAVLink docs, ArduPilot wiki) |
| 165 | + |
| 166 | +### 9. (Optional) Create a renderer module — `renderer_<name>.py` |
| 167 | + |
| 168 | +If the plugin needs a dedicated visualisation helper (e.g., a 3D attitude renderer), |
| 169 | +create `ardupilot_methodic_configurator/renderer_<name>.py`. |
| 170 | + |
| 171 | +- **No tkinter dependency** — return a `PIL.Image.Image` that the frontend displays |
| 172 | + via a `ttk.Label`. |
| 173 | +- Avoid wildcard imports (`from SomeLib import *`) — ruff enforces explicit imports. |
| 174 | + Use `# noqa: ARG002` on the method signature if arguments are unused in a stub. |
| 175 | +- See `renderer_3d_quadcopter.py` for the established pattern. |
| 176 | + |
| 177 | +--- |
| 178 | + |
| 179 | +## Verification Checklist |
| 180 | + |
| 181 | +After completing all steps, verify: |
| 182 | + |
| 183 | +- [ ] `PLUGIN_<NAME>` constant exists in `plugin_constants.py` |
| 184 | +- [ ] `data_model_<plugin>.py` is importable and has no tkinter dependency |
| 185 | +- [ ] `frontend_tkinter_<plugin>.py` exports `register_<plugin>_plugin()` |
| 186 | +- [ ] `register_plugins()` in `__main__.py` imports and calls the register function |
| 187 | +- [ ] `create_plugin_data_model()` handles the new plugin name |
| 188 | +- [ ] New `data_model_*` import in `data_model_parameter_editor.py` is in alphabetical order |
| 189 | +- [ ] `configuration_steps_schema.json` enum includes the new name |
| 190 | +- [ ] Relevant `configuration_steps_*.json` files reference the plugin |
| 191 | +- [ ] (If renderer) `renderer_<name>.py` has no wildcard imports; unused stub args use `# noqa: ARG002` |
| 192 | +- [ ] `ARCHITECTURE_<plugin_name>.md` exists in the project root |
| 193 | +- [ ] `pytest tests/ -v` passes |
| 194 | +- [ ] `ruff check .` and `ruff format` pass |
| 195 | +- [ ] `mypy` / `pyright` / `pylint` pass |
| 196 | + |
| 197 | +--- |
| 198 | + |
| 199 | +## Reference: Touch-Point Summary |
| 200 | + |
| 201 | +The same five mandatory touch-points are documented inline in the source: |
| 202 | + |
| 203 | +- `plugin_constants.py` — top-of-file comment block |
| 204 | +- `__main__.py → register_plugins()` — docstring |
| 205 | +- `data_model_parameter_editor.py → create_plugin_data_model()` — docstring |
| 206 | + |
| 207 | +## Lessons Learned |
| 208 | + |
| 209 | +### Deferred imports inside functions avoid circular imports |
| 210 | + |
| 211 | +The `frontend_tkinter_*` modules import `plugin_factory` at module level. Importing |
| 212 | +them at the top of `__main__.py` would create a circular import. Always place the |
| 213 | +`from frontend_tkinter_<plugin> import register_<plugin>_plugin` call **inside** the |
| 214 | +`register_plugins()` function body, annotated with `# noqa: PLC0415`. |
0 commit comments