update-motor-diagrams

name	update-motor-diagrams
description	Update motor diagram SVG files from ArduPilot documentation. Use when downloading new motor diagrams via scripts/download_motor_diagrams.py, adding new SVG filenames to the motor_diagrams list, or verifying SVG files in ardupilot_methodic_configurator/images/.

Motor Diagrams Update Instructions

This document provides AI-assisted instructions for updating the ArduPilot motor diagram SVG files in the ArduPilot Methodic Configurator.

Overview

The ArduPilot Methodic Configurator includes motor diagram SVG files that help users understand the correct motor order and rotation for their vehicle frame type. These diagrams are sourced from the official ArduPilot documentation at https://ardupilot.org/copter/docs/connect-escs-and-motors.html.

Automated Update Process

The scripts/download_motor_diagrams.py script automatically downloads all motor diagram SVG files from the ArduPilot documentation. This script is run periodically via GitHub Actions to keep the diagrams up to date.

Manual Update Instructions

Prerequisites

1. Working Directory: Ensure you're in the project root directory
2. Network Access: Internet connection required to download SVG files
3. File Permissions: Write access to ardupilot_methodic_configurator/images/ directory

Step-by-Step Process

1. Run the Download Script:

   python scripts/download_motor_diagrams.py
   

2. Verify Downloads: Check that all SVG files are present in ardupilot_methodic_configurator/images/

3. Update Script if Needed: If new motor diagrams are added to the ArduPilot documentation:

   • Visit https://ardupilot.org/copter/docs/connect-escs-and-motors.html
   • Identify new SVG diagram URLs in the format https://ardupilot.org/copter/_images/m_*.svg
   • Add the new SVG filenames to the motor_diagrams list in scripts/download_motor_diagrams.py

AI Assistant Guidelines

When tasked with updating motor diagrams:

1. Check Current State:

   • Verify existing SVG files in ardupilot_methodic_configurator/images/
   • Check the current motor_diagrams list in the download script

2. Fetch Latest Documentation:

   • Use web scraping tools to examine https://ardupilot.org/copter/docs/connect-escs-and-motors.html
   • Extract all motor diagram SVG URLs from the page
   • Compare with the current list to identify new diagrams

3. Update Script:

   • Add any new SVG filenames to the motor_diagrams list
   • Maintain the existing categorization (QUAD, HEXA, OCTO, etc.)
   • Preserve the comment structure for clarity

4. Download and Verify:

   • Run the updated script to download new diagrams
   • Verify all downloads completed successfully
   • Check file sizes and integrity

File Structure

ardupilot_methodic_configurator/
├── images/
│   ├── ArduPilot_icon.png
│   ├── ArduPilot_logo.png
│   ├── m_01_00_quad_plus.svg
│   ├── m_01_01_quad_x.svg
│   ├── ... (all motor diagram SVGs)
│   └── m_14_01_deca_x_and_cw_x.svg
└── ...

scripts/
├── download_motor_diagrams.py
└── ...

Motor Diagram Categories

The motor diagrams are categorized by frame type:

• QUAD FRAMES (m_01_*): Standard quadcopter configurations
• HEXA FRAMES (m_02_*): Hexacopter configurations
• OCTO FRAMES (m_03_*): Octocopter configurations
• OCTO QUAD FRAMES (m_04_*): Octo-quad configurations
• Y6 FRAMES (m_05_*): Y6 configurations
• TRICOPTER FRAMES (m_07_*): Tricopter configurations
• BICOPTER FRAMES (m_10_*): Bicopter configurations
• DODECAHEXA FRAMES (m_12_*): 12-motor configurations
• DECA FRAMES (m_14_*): 10-motor configurations

Integration with GUI

The downloaded SVG files are used by the motor test sub-application to display the correct motor layout diagram based on the selected FRAME_CLASS and FRAME_TYPE parameters. The mapping between frame parameters and SVG files follows the ArduPilot convention:

• Frame class determines the base type (1=QUAD, 2=HEXA, 3=OCTO, etc.)
• Frame type determines the specific configuration (0=PLUS, 1=X, etc.)
• SVG filename format: m_{frame_class:02d}_{frame_type:02d}_{description}.svg

Testing

After updating motor diagrams:

1. Visual Verification: Open SVG files to ensure they display correctly
2. GUI Testing: Test the motor test sub-application to verify diagrams display properly
3. Size Check: Ensure file sizes are reasonable (typically 5-50KB for SVG files)
4. Python Code Linting: Run ruff check scripts/download_motor_diagrams.py to ensure Python code quality
5. Markdown Linting: Use npx markdownlint-cli2 or similar tools for markdown file validation (do not use ruff for markdown files)

Troubleshooting

Common Issues

1. Download Failures:

   • Check network connectivity
   • Verify ArduPilot documentation URLs are still valid
   • Check for rate limiting or access restrictions

2. Missing Diagrams:

   • Ensure all diagram URLs are included in the script
   • Check for new diagrams added to ArduPilot documentation

3. File Corruption:

   • Re-download affected files
   • Verify SVG file integrity by opening in a viewer

Error Handling

The download script includes error handling for:

• Network connectivity issues
• Invalid URLs or missing files
• File system write permissions
• URL security validation (only HTTPS URLs allowed)

Maintenance Schedule

• Automated: GitHub Actions runs the update script weekly
• Manual Review: Check for new ArduPilot releases quarterly
• Code Review: Review script updates when ArduPilot documentation structure changes

Related Files

• scripts/download_motor_diagrams.py: Main download script
• .github/workflows/update_motor_diagrams.yml: CI/CD automation
• windows/ardupilot_methodic_configurator.iss: Windows installer configuration
• ardupilot_methodic_configurator/frontend_tkinter_motor_test.py: GUI integration
• ARCHITECTURE_motor_test.md: Motor test sub-application architecture

---

This document should be updated whenever the motor diagram update process or ArduPilot documentation structure changes.