FEATURE: added a quick-start guide and updated the usermanual

Added screenshots Added usage flowchart
ArduPilot · Jun 10, 2024 · d7aa643 · d7aa643
1 parent b72209d
commit d7aa643
Show file tree

Hide file tree

Showing 22 changed files with 135 additions and 30 deletions.
diff --git a/QUICKSTART.md b/QUICKSTART.md
@@ -0,0 +1,83 @@
+# Quick start guide
+
+## 1. Install *ArduPilot Methodic Configurator* software on a PC or Mac
+
+1. Download and install [ArduPilot Methodic Configurator](https://github.com/ArduPilot/MethodicConfigurator/releases/tag/latest) software.
+
+![AMC install 01](images/AMC_install_01.png)
+
+![AMC install 02](images/AMC_install_02.png)
+
+![AMC install 03](images/AMC_install_03.png)
+
+![AMC install 04](images/AMC_install_04.png)
+
+## 2. Install *Mission Planner* software on a PC or Mac
+
+1. Download and install [Mission Planner](https://firmware.ardupilot.org/Tools/MissionPlanner/).
+1. Make sure to install all the recommended device drivers when asked to.
+
+## 3. Install *ArduPilot* firmware on the flight controller
+
+1. Connect the flight controller to the computer using a USB cable.
+1. Open *Mission Planner* software.
+1. Go to *SETUP* > *Install Firmware* select your vehicle type and install version 4.3.8 **or newer** of the ArduPilot firmware onto the flight controller.
+1. Wait until the firmware download is complete.
+1. Disconnect the USB cable from the flight controller.
+
+## 4. Use the *ArduPilot Methodic Configurator* software for the first time
+
+1. Connect the flight controller to the computer using a USB cable.
+1. Wait at least 7 seconds.
+1. Open the *ArduPilot Methodic Configurator* software.
+1. The software should now automatically detect and connect to your flight controller.
+![AMC FC info and parameter download](images/App_screenshot_FC_info_and_param_download.png)
+1. Select the vehicle template that better resembles your own vehicle.
+![AMC template selection1](images/App_screenshot_Vehicle_directory1.png)
+![AMC template selection2](images/App_screenshot_Vehicle_overview.png)
+1. Give a name to your vehicle.
+![AMC new vehicle name](images/App_screenshot_Vehicle_directory2.png)
+1. Press *Create vehicle configuration from template*.
+![AMC new vehicle create](images/App_screenshot_Vehicle_directory3.png)
+1. Edit all the components of your vehicle to match your own in the *vehicle Component Editor* window.
+![AMC component editor](images/App_screenshot_Component_Editor.png)
+1. Press *Save data and start configuration*.
+1. The application will validate your input.
+If issues are found the problematic fields' background will be marked in red color.
+Correct those entries and press the `Save data and start configuration` button again.
+1. You should now see the *Parameter file editor and uploader* window.
+![AMC parameter file editor and uploader](images/App_screenshot2.png)
+
+If something is not clear, read the [ArduPilot Methodic Configurator user manual](USERMANUAL.md)
+
+## 5. Configure the vehicle's parameters in a traceable way
+
+The following simple loop is presented as welcome instructions:
+![AMC welcome instructions](images/App_screenshot_instructions.png)
+
+Now do this in a loop until the software automatically closes or you are asked to close the software:
+
+- Read all the documentation links displayed at the top of the GUI (marked with the big red number 4),
+- Edit the parameter's *New value* and *Reason changed* fields to match your vehicle (marked with the big red number 5),
+- Press *Del* and/or *Add* buttons to delete or add parameters respectively (marked with the big red number 5),
+- Press *Upload selected params to FC, and advance to next param file* (marked with the big red number 7),
+- Repeat until the program automatically closes.
+
+
+## 6. Use the *ArduPilot Methodic Configurator* software after having created a vehicle from template
+
+1. Connect the flight controller to the computer using a USB cable.
+1. Wait at least 7 seconds.
+1. Open the *ArduPilot Methodic Configurator* software.
+1. The software should now automatically detect and connect to your flight controller.
+![AMC FC info and parameter download](images/App_screenshot_FC_info_and_param_download.png)
+1. Open the vehicle configuration directory that you created in the [Use the *ArduPilot Methodic Configurator* software for the first time](#4-use-the-ardupilot-methodic-configurator-software-for-the-first-time).
+![AMC open vehicle configuration](images/App_screenshot_Vehicle_directory4.png)
+double-click and step inside the directory that you want to use, not just select it
+1. Edit all the components of your vehicle to match your own.
+![AMC component editor](images/App_screenshot_Component_Editor.png)
+1. Press *Save data and start configuration*.
+1. You should now see the *Parameter file editor and uploader* window.
+![AMC parameter file editor and uploader](images/App_screenshot2.png)
+1. Proceed as explained on [section 5](#5-configure-the-vehicles-parameters-in-a-traceable-way)
+Congratulations your flight controller is now fully configured in the safest and fastest way publicly know.
diff --git a/README.md b/README.md
@@ -8,13 +8,16 @@
 | | | [![coverage](https://github.com/ArduPilot/MethodicConfigurator/actions/workflows/coverage.yml/badge.svg)](https://github.com/ArduPilot/MethodicConfigurator/actions/workflows/coverage.yml) | [![Windows Build](https://github.com/ArduPilot/MethodicConfigurator/actions/workflows/windows_build.yml/badge.svg)](https://github.com/ArduPilot/MethodicConfigurator/actions/workflows/windows_build.yml) |
 
 Amilcar Lucas's ArduPilot Methodic Configurator is a Python tool that implements a [clear and proven configuration sequence of ArduPilot of drones](https://discuss.ardupilot.org/t/how-to-methodically-tune-almost-any-multicopter-using-arducopter-4-4-x/110842/1).
+
+![When to use ArduPilot Methodic Configurator](images/when_to_use_amc.png)
+
 It provides a graphical user interface (GUI) for managing and visualizing ArduPilot parameters, parameter files and documentation.
 
 ![Application Screenshot](images/App_screenshot1.png)
 
 ## Usage
 
-Usage is detailed in the [USERMANUAL.md](USERMANUAL.md) file
+There is a [Quick-start guide](QUICKSTART.md) and a more detailed [Usermanual](USERMANUAL.md)
 
 ## MS Windows Installation
 

diff --git a/USERMANUAL.md b/USERMANUAL.md
@@ -14,71 +14,86 @@ Before starting the application on your PC you should connect a flight controlle
 
 This interface allows users to select or add a connection to a flight controller **if one was not yet auto-detected**.
 
-<p align="center">
-  <img src="images/App_screenshot_FC_connection.png" width=45% />
+![Flight controller connection selection window](images/App_screenshot_FC_connection.png)
+<figure>
 <br>
   <ins><b><i>Flight controller connection selection window</i></b></ins>
-</p>
+</figure>
 
 It provides three main options for connecting to a flight controller:
 
-#### Option 1: Auto-connect
+#### Option 1: Auto-connect to flight controller
 
 This option automatically attempts to connect to a flight controller that has been connected to the PC. The user must wait for at least 7 seconds for the flight controller to fully boot before attempting the connection.
 
-#### Option 2: Manually Select or Add a Connection
+#### Option 2: Select flight controller connection
 
-This option allows users to manually select an existing flight controller connection or add a new one. It provides a dropdown menu listing all available connections, including an option to add a new connection.
+Manually select an existing flight controller connection or add a new one.
+It provides a dropdown menu listing all available connections, including an option to add a new connection.
 
 - To select an existing connection, use the dropdown menu to choose the desired connection.
 - To add a new connection, select "Add another" from the dropdown menu. A dialog box will prompt you to enter the connection string for the new flight controller.
 
-#### Option 3: Skip Flight Controller Connection
+#### Option 3: No flight controller Connection
 
-This option allows users to skip the flight controller connection process. It proceeds with editing the intermediate `.param` files on disk without fetching parameter values nor parameter default parameter values from the flight controller.
+Skip the flight controller connection process.
+It proceeds with editing the intermediate `.param` files on disk without fetching parameter values nor parameter default parameter values from the flight controller.
 
-### Vehicle Directory Selection Interface
+### Flight Controller Info and parameter download
+
+If a flight controller is connected the software will now get information from it.
+The information is presented in the corresponding window and at the same time all flight controller parameters are downloaded to the PC.
+
+![Flight controller info and parameter download](images/App_screenshot_FC_info_and_param_download.png)
+<figure>
+<br>
+  <ins><b><i>Flight controller info and parameter download</i></b></ins>
+</figure>
+
+
+### Vehicle Configuration Directory Selection Interface
 
 This interface allows users to select a vehicle directory that contains intermediate parameter files for ArduPilot **if one was not specified with the `--vehicle-dir` command line parameter**.
 
-<p align="center">
-  <img src="images/App_screenshot_Vehicle_directory.png" width=45% />
+![Vehicle Selection Window](images/App_screenshot_Vehicle_directory.png)
+<figure align="center">
 <br>
   <ins><b><i>Vehicle Selection Window</i></b></ins>
-</p>
+</figure>
 
 It provides three main options for selecting a vehicle directory:
 
-#### Option 1: Create a New Vehicle Configuration Directory Based on an Existing Template
+#### Option 1: Create a new vehicle configuration directory
 
 Create a new vehicle configuration directory by copying files from an existing template directory.
 It's useful for setting up a new vehicle configuration quickly.
 
-- Use the "Template directory" `...` button to select the existing vehicle template directory containing the intermediate parameter files to be copied.
+- Use the "Template directory" `...` button to select the existing vehicle template directory containing the intermediate parameter files to be copied. Use the overview window to select the template that better matches the components of your own vehicle.
+![Vehicle template overview](images/App_screenshot_Vehicle_overview.png)
 - Use the "Base directory" `...` button to select the existing directory where the new vehicle directory will be created.
 - Enter the name for the new vehicle directory in the "New vehicle name" field.
 - Click the "Create vehicle directory from template" button to create the new vehicle directory on the base directory and copy the template files to it.
 
-#### Option 2: Use an Existing Vehicle Configuration Directory
+#### Option 2: Open an existing vehicle configuration directory
 
 Select an existing vehicle configuration directory that already contains intermediate parameter files.
 It's useful for editing an existing vehicle configuration.
 
 - Use the "Vehicle directory" `...` button to select the existing vehicle directory containing the intermediate parameter files.
 
-#### Option 3: Use the last used Vehicle Configuration Directory
+#### Option 3: Open the last used vehicle configuration Directory
 
 Select the last used vehicle configuration directory.
 
-### Component Editor Interface
+### Vehicle Component Editor Interface
 
 Here you specify the components of your vehicle, their properties and how they are connected to the flight controller.
 
-<p align="center">
-  <img src="images/App_screenshot_Component_Editor.png" width=55% />
+![Component Editor Window](images/App_screenshot_Component_Editor.png)
+<figure align="center">
 <br>
   <ins><b><i>Component Editor Window</i></b></ins>
-</p>
+</figure>
 
 Change every field to match your vehicle's.
 When finished press the `Save data and start configuration` button.
@@ -91,15 +106,15 @@ Correct those entries and press the `Save data and start configuration` button a
 
 Here you sequentially configure the parameters of your flight controller to meet your needs while having all the available documentation at your fingertips.
 
-<p align="center">
-  <img src="images/App_screenshot2.png" width=85% />
+![Parameter File Editor and Uploader Window (main application)](images/App_screenshot2.png)
+<figure align="center">
 <br>
   <ins><b><i>Parameter File Editor and Uploader Window (main application)</i></b></ins>
-</p>
+</figure>
 
 #### 1. See the Current Vehicle Directory (optional)
 
-- this vehicle contains the files to be edited and uploaded
+- this vehicle configuration directory contains the files to be edited and uploaded
 
 #### 2. Select an Intermediate Parameter File (optional)
 
@@ -108,11 +123,10 @@ Here you sequentially configure the parameters of your flight controller to meet
 - The first available intermediate parameter file not named `00_default.param` will be selected by default
 - If the selection changes, the parameter table will update to display the parameters from the selected file.
 
-#### 3. Select a Flight Controller Connection (optional)
+#### 3. About information and help links (optional)
 
-- **If a flight controller is detected and the `--device` command-line parameter was not explicitly set, it will connect to it.**
-- The `Flight controller connection:` Combobox lists available connections.
-- Select a connection to establish communication with the flight controller.
+When you click the ArduPilot logo the following window will appear:
+![About and help information](images/App_screenshot_about.png)
 
 #### 4. Viewing Documentation
 
@@ -145,11 +159,16 @@ Here you sequentially configure the parameters of your flight controller to meet
 - The entire ArduPilot official parameter documentation is available on the tooltip, no need to use a browser to search for it.
 - The `Add` button adds a parameter to the current intermediate parameter file.
 
-#### 6. Focus on the changed parameters (optional)
+#### 6a. Focus on the changed parameters (optional)
 
 - You can focus on the changed parameters by ticking the "See only changed parameters" checkbox
 - Usually, you want to see all parameters and look at their mouse-over tooltips to decide if and how you want to change them
 
+#### 6b. Annotate parameter metadata information into the parameter files (optional)
+
+Annotate parameter metadata information into the parameter files in the form of comments preceding the respective parameter.
+It will create bigger and harder-to-compare parameter files but is more suitable for text editor editing.
+
 #### 7. Uploading Parameters to the Flight Controller
 
 - You can also jump to a particular file using the Combobox as explained in [2. Select an intermediate parameter file](#2-select-an-intermediate-parameter-file-optional)

diff --git a/images/AMC_install_01.png b/images/AMC_install_01.png
diff --git a/images/AMC_install_02.png b/images/AMC_install_02.png
diff --git a/images/AMC_install_03.png b/images/AMC_install_03.png
diff --git a/images/AMC_install_04.png b/images/AMC_install_04.png
diff --git a/images/AMC_install_05.png b/images/AMC_install_05.png
diff --git a/images/App_screenshot1.png b/images/App_screenshot1.png
diff --git a/images/App_screenshot2.png b/images/App_screenshot2.png
diff --git a/images/App_screenshot_Component_Editor.png b/images/App_screenshot_Component_Editor.png
diff --git a/images/App_screenshot_FC_connection.png b/images/App_screenshot_FC_connection.png
diff --git a/images/App_screenshot_FC_info_and_param_download.png b/images/App_screenshot_FC_info_and_param_download.png
diff --git a/images/App_screenshot_Vehicle_directory.png b/images/App_screenshot_Vehicle_directory.png
diff --git a/images/App_screenshot_Vehicle_directory1.png b/images/App_screenshot_Vehicle_directory1.png
diff --git a/images/App_screenshot_Vehicle_directory2.png b/images/App_screenshot_Vehicle_directory2.png
diff --git a/images/App_screenshot_Vehicle_directory3.png b/images/App_screenshot_Vehicle_directory3.png
diff --git a/images/App_screenshot_Vehicle_directory4.png b/images/App_screenshot_Vehicle_directory4.png
diff --git a/images/App_screenshot_Vehicle_overview.png b/images/App_screenshot_Vehicle_overview.png
diff --git a/images/App_screenshot_about.png b/images/App_screenshot_about.png
diff --git a/images/App_screenshot_instructions.png b/images/App_screenshot_instructions.png
diff --git a/images/when_to_use_amc.png b/images/when_to_use_amc.png