MethodicConfigurator

Customizing configuration steps

⚠️ For most users: You don’t need to customize these files. This section is intended for advanced users, integrators, and developers who need to extend or modify the configuration workflow.

The ArduPilot Methodic Configurator uses several configuration files to manage and visualize vehicle parameters. These files are crucial for the tool’s operation and are organized in a specific directory structure.

Overview of Configuration Files

The ArduPilot Methodic Configurator relies on the following key files:

Intermediate Parameter Files

Each intermediate parameter file is a plain text file, editable with ArduPilot Methodic Configurator or any common text editor like Notepad++, nano, or VS Code.

File contents:

Comments start with the # character. Example:

# Arming with Rudder enable/disable
# Allow arm/disarm by rudder input. When enabled arming can be done with right rudder, disarming with left rudder.
# 0: Disabled
# 1: ArmingOnly
# 2: ArmOrDisarm
ARMING_RUDDER,0 # We find it safer to use only a switch to arm instead of through rudder inputs

Configuration Steps file

The configuration steps file is a JSON file that defines the workflow, documentation, and advanced behavior for each intermediate parameter file. It serves as the central control mechanism for how the Methodic Configurator processes vehicle configuration steps.

File Structure

The configuration steps file contains two main top-level objects:

{
  "steps": {
    "NN_step_name.param": {
      // Step configuration here
    }
  },
  "phases": {
    "Phase Name": {
      "description": "Phase description",
      "start": 2
    }
  }
}

Best Practices

Follow these guidelines when creating or modifying configuration steps:

  1. Always provide meaningful explanations: The why and why_now fields are crucial for user understanding. Be clear and specific.
  2. Keep URLs current: External documentation links may move. Regularly verify that blog_url and wiki_url are still valid.
  3. Use derived parameters for dynamic values: When parameter values depend on component specifications, use derived_parameters with expressions rather than forcing fixed values.
  4. Provide fallbacks: In derived_parameters, use vehicle_components.get() and fc_parameters.get() with default values to prevent errors.
  5. Organize with phases: Group related configuration steps into phases to help users understand the overall workflow.
  6. Include migration info: When renaming steps, keep the old filename in old_filenames to maintain backward compatibility with existing projects.
  7. Test expressions thoroughly: Complex expressions in derived parameters should be tested with various input values to ensure correct calculations.

Step Fields Reference

Each step in the configuration file can include the following fields. Start with the Required Fields for every step, then add Optional Fields as needed for advanced features.

Required Fields (All steps must include these)

why: Explains the purpose and importance of this configuration step.

why_now: Explains why this step needs to be performed at this specific point in the configuration sequence.

blog_text: Short text describing the step for blog/documentation references.

blog_url: URL to the blog or documentation page for this step.

wiki_text: Short text describing the step for wiki references.

wiki_url: URL to the ArduPilot wiki documentation for this step.

external_tool_text: Name of an external tool needed for this step (can be empty string if not needed).

external_tool_url: URL to download or access the external tool (can be empty string if not needed).

mandatory_text: Indicates whether the step is mandatory or optional with percentages.

Optional Fields

auto_changed_by: Name of the tool or process that automatically modifies these parameters.

autoimport_nondefault_regexp: Array of regular expressions to match parameters for automatic import if they have non-default values.

forced_parameters: Parameters that are set to fixed values without user modification.

derived_parameters: Parameters whose values are calculated based on other data (component specifications, expressions, etc.).

jump_possible: Allows users to skip ahead to another step under certain conditions.

old_filenames: List of previous filenames for this step (for migration purposes).

rename_connection: Expression to dynamically rename a connection based on component data.

download_file: Downloads a file from the internet to the local vehicle project directory.

upload_file: Uploads a file from the vehicle project directory to the flight controller.

plugin: Loads a specialized plugin window for this step.

instructions_popup: Displays a popup message when the user enters this step.

Phases (Optional)

Phases group related steps into logical sections of the configuration workflow.

Phase fields:

Example:

"phases": {
  "IMU temperature calibration": {
    "description": "Temperature calibration for accurate sensor readings",
    "start": 2
  },
  "Basic mandatory configuration": {
    "description": "Core vehicle configuration required for safe operation",
    "start": 4
  },
  "Optical flow calibration": {
    "description": "Optional advanced positioning",
    "optional": true,
    "start": 50
  }
}

Complete Examples

The vehicle-specific default configuration steps files can be used as example/inspiration:

Vehicle Components File

The vehicle components file (vehicle_components.json) is a JSON file located in the vehicle-specific directory that stores comprehensive information about all vehicle components and their configurations. It serves as the central data source for component specifications, connections, and firmware versions used by the Methodic Configurator.

Purpose and Use Cases

The vehicle components file is used to:

File Structure and Schema

The vehicle components file follows a strict JSON schema defined in vehicle_components_schema.json. It contains the following top-level properties:

{
  "Format version": 1,
  "Program version": "x.x.x",
  "Configuration template": "Template Name",
  "Components": {
    "Flight Controller": { /* flight controller details */ },
    "Frame": { /* frame details */ },
    "Battery Monitor": { /* battery monitor details */ },
    "Battery": { /* battery details */ },
    "ESC": { /* ESC details */ },
    "Motors": { /* motor details */ },
    "Propellers": { /* propeller details */ },
    "RC Receiver": { /* RC receiver details */ },
    "RC Transmitter": { /* RC transmitter details */ },
    "Telemetry": { /* telemetry module details */ },
    "GNSS Receiver": { /* GNSS receiver details */ }
  }
}

Component Properties

Each component can include the following properties:

Product Information

Firmware Information (where applicable)

Flight Controller Connection (for physically connected components)

Component-Specific Specifications

Each component type may have specialized specifications:

Battery:

Motors:

Propellers:

Frame:

Notes and Metadata

Editing the Vehicle Components File

The vehicle components file can be edited in several ways:

1. Using the GUI Component Editor

The recommended way for most users:

  1. Open the ArduPilot Methodic Configurator
  2. Load or create a vehicle configuration
  3. Use the Component Editor window to view and modify all component information
  4. Changes are saved to the vehicle’s vehicle_components.json file

2. Manual JSON Editing

For advanced users who want to edit directly:

  1. Locate the vehicle-specific vehicle_components.json file
  2. Edit with any JSON-compatible text editor (VS Code, Notepad++, nano)
  3. Ensure the JSON remains valid
  4. Validate against the schema before using in the application

Deriving Parameters from Components

One of the key features of the vehicle components file is the ability to derive flight controller parameters automatically based on component specifications. In the configuration_steps_*.json file, you can reference component data:

"derived_parameters": {
  "BATT_CAPACITY": {
    "New Value": "vehicle_components['Battery']['Specifications']['Capacity mAh']",
    "Change Reason": "Total battery capacity from component editor"
  },
  "ATC_ACCEL_P_MAX": {
    "New Value": "max(10000,(round(-2.613267*vehicle_components['Propellers']['Specifications']['Diameter_inches']**3+343.39216*vehicle_components['Propellers']['Specifications']['Diameter_inches']**2-15083.7121*vehicle_components['Propellers']['Specifications']['Diameter_inches']+235771, -2)))",
    "Change Reason": "Derived from propeller size specifications"
  }
}

Validation and Compatibility Checks

The application validates the vehicle components file to ensure:

If validation errors are found, the application displays clear error messages indicating which components or properties need correction.

Vehicle Image File

The vehicle image file (vehicle.jpg) is an optional photograph or diagram stored in the vehicle-specific directory that provides a visual reference of the vehicle during configuration.

File Format and Location

Guidelines for Vehicle Images

When creating or providing a vehicle image:

Creating or Updating the Vehicle Image

  1. Take a photograph: Use a camera or smartphone to capture the vehicle
  2. Process the image: Crop to show the vehicle clearly, adjust lighting if needed
  3. Convert to JPEG (if not already): Use image editing software to save as .jpg format with at most 400x400 pixels
  4. Place in vehicle directory: Copy to the same directory as vehicle_components.json
  5. Name consistently: Ensure the filename is exactly vehicle.jpg for the application to locate it automatically

Image Not Found Handling

If vehicle.jpg is missing:

This site is open source. Improve this page.