Repository: ArduPilot/MethodicConfigurator
Pull request #241: Update TUNING_GUIDE_ArduCopter.md
Author: login: dkemxr
Labels: name: documentation
description: Improvements or additions to documentation
Created: 2025-03-07T20:52:55Z | Merged: 2025-03-09T23:14:24Z

Add a section about how to determine if there is motor output oscillation and how to correct it.


Diff:
diff --git a/TUNING_GUIDE_ArduCopter.md b/TUNING_GUIDE_ArduCopter.md
index 0e07d4c25..f2791fc5a 100644
--- a/TUNING_GUIDE_ArduCopter.md
+++ b/TUNING_GUIDE_ArduCopter.md
@@ -648,11 +648,67 @@ Land and disarm.
 > level close to or bellow 0.2 you will need to set the [MOT_HOVER_LEARN](https://ardupilot.org/copter/docs/parameters.html#mot-hover-learn)
 > parameter to 0 (using the `Add` button on the GUI) and follow the [setting hover throttle instructions](https://ardupilot.org/copter/docs/ac_throttlemid.html)
 
-Immediately check for hot motors.
-If the motors are excessively hot or you observe audible or visible oscillations, review the `.bin` dataflash log.
-High or fluctuating `RATE.*out` values will indicate which PID gain needs to be reduced in order to eliminate the output oscillations that are causing the motors to overheat.
-Refer to the section on [Initial tuning oscilations](https://ardupilot.org/copter/docs/initial-tuning-flight.html#initial-aircraft-tune).
-Return to the file `16_pid_adjustment.param`, make the necessary adjustments to the PID gains, upload the changes to the flight controller, and conduct another test flight.
+### 7.1.1 Check for Motor Output Oscillation
+
+After landing from your first hover flight, immediately check the motors for excessive heat.
+Hot motors indicate a [potential oscillation problem](https://ardupilot.org/copter/docs/initial-tuning-flight.html#initial-aircraft-tune)
+that needs to be addressed.
+
+**Signs of oscillation issues:**
+
+- Excessively hot motors after flight
+- Audible vibrations/oscillations during flight
+- Visible shaking of the vehicle
+- Hard to control or sluggish behavior
+**If you observe any of these signs:**
+
+1. [Download the `.bin` dataflash log](https://ardupilot.org/copter/docs/common-downloading-and-analyzing-data-logs-in-mission-planner.html) from your flight
+2. Review the `RATE.*out` values in the log
+3. If you see high (> 0.15) or oscillating `RATE.*out` values:
+   - Identify which PID gains need reduction to eliminate oscillations
+     - typically one of these: `ATC_RAT_PIT_D`, `ATC_RAT_PIT_I`, `ATC_RAT_PIT_P`, `ATC_RAT_RLL_D`, `ATC_RAT_RLL_I`, `ATC_RAT_RLL_P`
+   - Return to file `16_pid_adjustment.param` and lower the corresponding oscillation-causing gains by 50% or more
+   - Upload the adjusted parameters to the flight controller
+   - if you have flown **more than 30 seconds in ALT_HOLD mode**:
+     - select and upload file `20_throttle_controller.param` to correct the `PSC_ACCZ_P` and `PSC_ACCZ_I` values.
+   - Conduct another test flight to verify the changes
+
+**Understanding Output Oscillation:**
+
+Below is an example showing severe output oscillation in a typical 4" quadcopter using default parameters.
+The graph shows Motor RC Outputs (RCOU-C1-C4) at hover:
+
+![Default Parameters](images/blog/severe_rcout_oscillations.jpg)
+
+This level of oscillation makes the craft unflyable due to visible shaking. **Tuning cannot proceed until this is corrected.**
+
+Even after applying the [Initial Tune Parameters in Section 6.8](#68-initial-attitude-pid-gains-vehicle-size-dependent) (or  [Mission Planner under Mandatory Hardware in Section 6.9](#69-configure-mandatory-hardware-parameters)):
+
+![Initial Parameters](images/blog/rcout_oscillations_with_initial_params.jpg)
+
+The oscillation persists, though it may not be visible to the eye. Without reviewing logs, this could be mistakenly considered acceptable flight behavior.
+
+**Root Causes:**
+
+Output oscillation typically results from a mismatch between default PID values and vehicle characteristics:
+
+- Motor kV rating
+- Propeller size
+- Battery power
+- Thrust-to-weight ratio (hover thrust)
+
+The main culprits are usually:
+
+- Rate PID gains too high
+- Vertical Acceleration Controller gains too high
+
+**Solution:**
+
+Here's an example of corrected output:
+
+![Rate and vert accel gains Parameters](images/blog/no_rcout_oscillations.jpg)
+
+With oscillations eliminated, you can proceed with further tuning steps.
 
 # 8. Minimalistic mandatory tuning
 
diff --git a/images/blog/no_rcout_oscillations.jpg b/images/blog/no_rcout_oscillations.jpg
new file mode 100644
index 000000000..310f1fc1f
Binary files /dev/null and b/images/blog/no_rcout_oscillations.jpg differ
diff --git a/images/blog/rcout_oscillations_with_initial_params.jpg b/images/blog/rcout_oscillations_with_initial_params.jpg
new file mode 100644
index 000000000..c676d33e3
Binary files /dev/null and b/images/blog/rcout_oscillations_with_initial_params.jpg differ
diff --git a/images/blog/severe_rcout_oscillations.jpg b/images/blog/severe_rcout_oscillations.jpg
new file mode 100644
index 000000000..9a0fb0107
Binary files /dev/null and b/images/blog/severe_rcout_oscillations.jpg differ


Reviews:
user: login: copilot-pull-request-reviewer[bot]
body: ## PR Overview

This PR updates the ArduCopter tuning guide by adding a section that outlines motor output oscillation and how to correct it.  
- Added a new section "7.2 Check for Motor Output Oscillation" with explanations and images.  
- Provided detailed examples of tuning adjustments to eliminate output oscillation.

### Reviewed Changes

| File                     | Description                                                    |
| ------------------------ | -------------------------------------------------------------- |
| TUNING_GUIDE_ArduCopter.md | Added a section to explain detection and correction of motor output oscillation |

Copilot reviewed 1 out of 1 changed files in this pull request and generated 2 comments.



state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-08T12:44:04Z
user: login: copilot-pull-request-reviewer[bot]
body: ## PR Overview

This PR updates the ArduCopter tuning guide by adding a section on identifying and correcting motor output oscillation.  
- Introduces a new troubleshooting section (Section 7.2) with examples and visual aids.  
- Provides guidance on adjusting PID and PSC parameters based on observed oscillation symptoms.

### Reviewed Changes

| File                     | Description                                                    |
| ------------------------ | -------------------------------------------------------------- |
| TUNING_GUIDE_ArduCopter.md | Added section detailing motor output oscillation diagnosis and correction steps |

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.



state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-08T13:21:49Z
user: login: copilot-pull-request-reviewer[bot]
body: ## PR Overview

This PR updates the ArduCopter tuning guide by adding a new section that explains how to diagnose motor output oscillation and recommends corrective tuning adjustments.  
- Added a new section "7.1.1 Check for Motor Output Oscillation" describing observable oscillation symptoms and associated PID tuning adjustments.  
- Included example log downloads and images illustrating oscillation conditions and tuning results.

### Reviewed Changes

| File                         | Description                                                          |
| ---------------------------- | -------------------------------------------------------------------- |
| TUNING_GUIDE_ArduCopter.md   | New section added to help users identify and correct motor oscillation|

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.



state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-08T16:07:52Z
user: login: dkemxr
body: Looks good.
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-09T14:40:35Z
user: login: amilcarlucas
state: APPROVED
author_association: COLLABORATOR
submitted_at: 2025-03-09T23:10:31Z
user: login: copilot-pull-request-reviewer[bot]
body: ## PR Overview

This pull request adds a new section to the ArduCopter tuning guide to help users identify and address motor output oscillation issues.  
- Introduces section 7.1.1 with detailed steps for checking motor oscillation and associated symptoms.  
- Provides practical guidance on reviewing logs, adjusting PID gains, and re-testing the flight controller settings.

### Reviewed Changes

| File                         | Description                                                    |
| ---------------------------- | -------------------------------------------------------------- |
| TUNING_GUIDE_ArduCopter.md   | New section added for recognizing and correcting motor oscillation. |

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.



state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-09T23:11:31Z

Review comments:
diff_hunk: @@ -653,6 +653,21 @@ If the motors are excessively hot or you observe audible or visible oscillations
 High or fluctuating `RATE.*out` values will indicate which PID gain needs to be reduced in order to eliminate the output oscillations that are causing the motors to overheat.
 Refer to the section on [Initial tuning oscilations](https://ardupilot.org/copter/docs/initial-tuning-flight.html#initial-aircraft-tune).
 Return to the file `16_pid_adjustment.param`, make the necessary adjustments to the PID gains, upload the changes to the flight controller, and conduct another test flight.
+# 7.2 Check for Motor Output Oscillation
+The following are examples of Output Oscillation and how to address it. First, we will look at a stark example of how a typical 4" (4S) quadcopter performs on default parameters by graphing the Motor RC Outputs (RCOU-C1-C4) at Hover.
+![Default Parameters](https://github.com/user-attachments/assets/ea6a8b56-6151-4e24-a579-9721cb004556)
+This is what Output Oscillation looks like and it's severe. This craft was unflyable with visual oscillation/shaking. Tuning cannot advance without correcting this.
+In all cases the Initial Tune Parameters, which can be found in Mission Planner under the Mandatory Hardware screens, should be entered. But, these are pre-1st flight parameters and will not on their own produce the best, or even good, stability. Here is an example of those parameters applied to this craft:
+![Default Parameters](https://github.com/user-attachments/assets/76378ac1-4978-4589-9e1e-374e756e64b7)
+It has not improved at all but there was no visible oscillation which without reviewing the log might be assumed to be flying well. It's not the case! You cannot achieve a good tune under this condition. So, why is there output oscillation? It's a function of several factors; motor kV, prop size, battery power and thrust/weight (which resolves to hover thrust). A summary of the Arducopter documentaion states that this is a result of the Rate PID's and the Vertical Acceleration Controller gains being too high for this craft and many like it. These parameters are:
path: TUNING_GUIDE_ArduCopter.md
user: login: Copilot
body: There is a typo in 'documentaion'; please update it to 'documentation'.
```suggestion
It has not improved at all but there was no visible oscillation which without reviewing the log might be assumed to be flying well. It's not the case! You cannot achieve a good tune under this condition. So, why is there output oscillation? It's a function of several factors; motor kV, prop size, battery power and thrust/weight (which resolves to hover thrust). A summary of the Arducopter documentation states that this is a result of the Rate PID's and the Vertical Acceleration Controller gains being too high for this craft and many like it. These parameters are:
```
created_at: 2025-03-08T12:44:04Z
author_association: CONTRIBUTOR
diff_hunk: @@ -653,6 +653,21 @@ If the motors are excessively hot or you observe audible or visible oscillations
 High or fluctuating `RATE.*out` values will indicate which PID gain needs to be reduced in order to eliminate the output oscillations that are causing the motors to overheat.
 Refer to the section on [Initial tuning oscilations](https://ardupilot.org/copter/docs/initial-tuning-flight.html#initial-aircraft-tune).
 Return to the file `16_pid_adjustment.param`, make the necessary adjustments to the PID gains, upload the changes to the flight controller, and conduct another test flight.
+# 7.2 Check for Motor Output Oscillation
+The following are examples of Output Oscillation and how to address it. First, we will look at a stark example of how a typical 4" (4S) quadcopter performs on default parameters by graphing the Motor RC Outputs (RCOU-C1-C4) at Hover.
+![Default Parameters](https://github.com/user-attachments/assets/ea6a8b56-6151-4e24-a579-9721cb004556)
+This is what Output Oscillation looks like and it's severe. This craft was unflyable with visual oscillation/shaking. Tuning cannot advance without correcting this.
+In all cases the Initial Tune Parameters, which can be found in Mission Planner under the Mandatory Hardware screens, should be entered. But, these are pre-1st flight parameters and will not on their own produce the best, or even good, stability. Here is an example of those parameters applied to this craft:
+![Default Parameters](https://github.com/user-attachments/assets/76378ac1-4978-4589-9e1e-374e756e64b7)
+It has not improved at all but there was no visible oscillation which without reviewing the log might be assumed to be flying well. It's not the case! You cannot achieve a good tune under this condition. So, why is there output oscillation? It's a function of several factors; motor kV, prop size, battery power and thrust/weight (which resolves to hover thrust). A summary of the Arducopter documentaion states that this is a result of the Rate PID's and the Vertical Acceleration Controller gains being too high for this craft and many like it. These parameters are:
+ATC_RAT_PIT_D  (and Roll)
+ATC_RAT_PIT_I  (and Roll)
+ATC_RAT_PIT_P  (and Roll)
+PSC_ACCZ_I
+PSC_ACCZ_P
+The typical approach is to lower the rate PID's by 50% and the PSC parameters to; P=hover thrust value and I=2x hover thrust value. With this craft a further reduction in the Rate PID's was required to ~35%. And now those parameters applied:
+![Rate and vert accel gains Paramters](https://github.com/user-attachments/assets/059b9276-3819-43e7-8d90-0fb48b656765)
path: TUNING_GUIDE_ArduCopter.md
user: login: Copilot
body: There is a typo in the image alt text 'Paramters'; please change it to 'Parameters'.
```suggestion
![Rate and vert accel gains Parameters](https://github.com/user-attachments/assets/059b9276-3819-43e7-8d90-0fb48b656765)
```
created_at: 2025-03-08T12:44:04Z
author_association: CONTRIBUTOR
diff_hunk: @@ -649,11 +649,47 @@ Land and disarm.
 > parameter to 0 (using the `Add` button on the GUI) and follow the [setting hover throttle instructions](https://ardupilot.org/copter/docs/ac_throttlemid.html)
 
 Immediately check for hot motors.
-If the motors are excessively hot or you observe audible or visible oscillations, review the `.bin` dataflash log.
+If the motors are excessively hot or you observe audible or visible oscillations,
+[download and review the `.bin` dataflash log from the vehicle](https://ardupilot.org/copter/docs/common-downloading-and-analyzing-data-logs-in-mission-planner.html).
 High or fluctuating `RATE.*out` values will indicate which PID gain needs to be reduced in order to eliminate the output oscillations that are causing the motors to overheat.
 Refer to the section on [Initial tuning oscilations](https://ardupilot.org/copter/docs/initial-tuning-flight.html#initial-aircraft-tune).
 Return to the file `16_pid_adjustment.param`, make the necessary adjustments to the PID gains, upload the changes to the flight controller, and conduct another test flight.
 
+### 7.1.1 Check for Motor Output Oscillation
+
+The following are examples of Output Oscillation and how to address it.
+First, we will look at a stark example of how a typical 4" (4S) quadcopter performs on default parameters by graphing the Motor RC Outputs (RCOU-C1-C4) at Hover:
+![Default Parameters](images/blog/severe_rcout_oscillations.jpg)
+This is what Output Oscillation looks like and it's severe.
+This craft was unflyable with visual oscillation/shaking.
+Tuning cannot advance without correcting this.
+In all cases the Initial Tune Parameters, which can be found in Mission Planner under the Mandatory Hardware screens, should be entered.
+But, these are pre-1st flight parameters and will not on their own produce the best, or even good, stability.
+Here is an example of those parameters applied to this craft:
+![Default Parameters](images/blog/rcout_oscillations_with_initial_params.jpg)
+It has not improved at all but there was no visible oscillation which without reviewing the log might be assumed to be flying well. It's not the case! You cannot achieve a good tune under this condition.
+So, why is there output oscillation?
+It's a function of several factors; motor kV, prop size, battery power and thrust/weight (which resolves to hover thrust).
+A summary of the Arducopter documentation states that this is a result of the Rate PID's and the Vertical Acceleration Controller gains being too high for this craft and many like it.
+These parameters are:
+
+```params
+ATC_RAT_PIT_D
+ATC_RAT_PIT_I
+ATC_RAT_PIT_P
+ATC_RAT_RLL_D
+ATC_RAT_RLL_I
+ATC_RAT_RLL_P
+PSC_ACCZ_I
+PSC_ACCZ_P
+```
+
+The typical approach is to lower the rate PID's by 50% and the PSC parameters to; P=hover thrust value and I=2x hover thrust value.
path: TUNING_GUIDE_ArduCopter.md
user: login: Copilot
body: [nitpick] Consider replacing the semicolon after 'to' with a colon for improved grammatical clarity.
```suggestion
The typical approach is to lower the rate PID's by 50% and the PSC parameters to: P=hover thrust value and I=2x hover thrust value.
```
created_at: 2025-03-08T16:07:52Z
author_association: CONTRIBUTOR
diff_hunk: @@ -648,11 +648,68 @@ Land and disarm.
 > level close to or bellow 0.2 you will need to set the [MOT_HOVER_LEARN](https://ardupilot.org/copter/docs/parameters.html#mot-hover-learn)
 > parameter to 0 (using the `Add` button on the GUI) and follow the [setting hover throttle instructions](https://ardupilot.org/copter/docs/ac_throttlemid.html)
 
-Immediately check for hot motors.
-If the motors are excessively hot or you observe audible or visible oscillations, review the `.bin` dataflash log.
-High or fluctuating `RATE.*out` values will indicate which PID gain needs to be reduced in order to eliminate the output oscillations that are causing the motors to overheat.
-Refer to the section on [Initial tuning oscilations](https://ardupilot.org/copter/docs/initial-tuning-flight.html#initial-aircraft-tune).
-Return to the file `16_pid_adjustment.param`, make the necessary adjustments to the PID gains, upload the changes to the flight controller, and conduct another test flight.
+### 7.1.1 Check for Motor Output Oscillation
+
+After landing from your first hover flight, immediately check the motors for excessive heat.
+Hot motors indicate a [potential oscillation problem](https://ardupilot.org/copter/docs/initial-tuning-flight.html#initial-aircraft-tune)
+that needs to be addressed.
+
+**Signs of oscillation issues:**
+
+- Excessively hot motors after flight
+- Audible vibrations/oscillations during flight
+- Visible shaking of the vehicle
+- Hard to control or slugish behavior
+
path: TUNING_GUIDE_ArduCopter.md
user: login: Copilot
body: The word 'slugish' appears to be misspelled; consider changing it to 'sluggish'.
```suggestion
- Hard to control or sluggish behavior
```
created_at: 2025-03-09T23:11:31Z
author_association: CONTRIBUTOR
diff_hunk: @@ -648,11 +648,68 @@ Land and disarm.
 > level close to or bellow 0.2 you will need to set the [MOT_HOVER_LEARN](https://ardupilot.org/copter/docs/parameters.html#mot-hover-learn)
 > parameter to 0 (using the `Add` button on the GUI) and follow the [setting hover throttle instructions](https://ardupilot.org/copter/docs/ac_throttlemid.html)
 
-Immediately check for hot motors.
-If the motors are excessively hot or you observe audible or visible oscillations, review the `.bin` dataflash log.
-High or fluctuating `RATE.*out` values will indicate which PID gain needs to be reduced in order to eliminate the output oscillations that are causing the motors to overheat.
-Refer to the section on [Initial tuning oscilations](https://ardupilot.org/copter/docs/initial-tuning-flight.html#initial-aircraft-tune).
-Return to the file `16_pid_adjustment.param`, make the necessary adjustments to the PID gains, upload the changes to the flight controller, and conduct another test flight.
+### 7.1.1 Check for Motor Output Oscillation
+
+After landing from your first hover flight, immediately check the motors for excessive heat.
+Hot motors indicate a [potential oscillation problem](https://ardupilot.org/copter/docs/initial-tuning-flight.html#initial-aircraft-tune)
+that needs to be addressed.
+
+**Signs of oscillation issues:**
+
+- Excessively hot motors after flight
+- Audible vibrations/oscillations during flight
+- Visible shaking of the vehicle
+- Hard to control or slugish behavior
+
+**If you observe any of these signs:**
+
+1. [Download the `.bin` dataflash log](https://ardupilot.org/copter/docs/common-downloading-and-analyzing-data-logs-in-mission-planner.html) from your flight
+2. Review the `RATE.*out` values in the log
+3. If you see high (> 0.15) or oscillating `RATE.*out` values:
+   - Identify which PID gains need reduction to eliminate oscillations
+     - typically one of these: `ATC_RAT_PIT_D`, `ATC_RAT_PIT_I`, `ATC_RAT_PIT_P`, `ATC_RAT_RLL_D`, `ATC_RAT_RLL_I`, `ATC_RAT_RLL_P`
+   - Return to file `16_pid_adjustment.param` and lower the corresponding oscilation-causing gains by 50% or more
path: TUNING_GUIDE_ArduCopter.md
user: login: Copilot
body: The word 'oscilation' appears to be misspelled; consider correcting it to 'oscillation'.
```suggestion
   - Return to file `16_pid_adjustment.param` and lower the corresponding oscillation-causing gains by 50% or more
```
created_at: 2025-03-09T23:11:31Z
author_association: CONTRIBUTOR

PR comments:
user: login: amilcarlucas
created_at: 2025-03-08T14:58:32Z
body: @dkemxr Thanks for the PR, I did some reformatting.

The second image is a duplicate of the first. Can you fix that?

author_association: COLLABORATOR
user: login: amilcarlucas
created_at: 2025-03-08T16:09:17Z
body: I squashed all the fixes into your original commit. Now, it's a single commit authored by you.

I plan to use AI to improve and streamline the wording. @dkemxr is that ok for you?

author_association: COLLABORATOR
user: login: amilcarlucas
created_at: 2025-03-08T16:16:25Z
body: Checking Motor Output Oscillation
Motor output oscillation can severely impact flight performance. Let's examine how to identify and address this issue.

Example Analysis
Here's an example showing motor outputs (RCOU-C1 through C4) at hover for a typical 4" quadcopter on 4S power:

With Default Parameters
Default Parameters

This graph shows severe output oscillation that made the craft unflyable, with visible shaking. The tuning process cannot proceed until this is corrected.

With Initial Tune Parameters
Initial Parameters

Even after applying the initial tune parameters from Mission Planner's Mandatory Hardware screens, the oscillation persists. While there may not be visible shaking, the log data reveals the vehicle is not flying well.

Understanding the Root Cause
The output oscillation is caused by several factors:

Motor kV rating
Propeller size
Battery power
Thrust-to-weight ratio (which determines hover thrust)
According to ArduCopter documentation, this typically occurs when the Rate PID gains and Vertical Acceleration Controller gains are too high for the specific vehicle configuration.

Key Parameters to Adjust
Solution
The standard approach is to:

Reduce rate PID values by 50%
Set PSC parameters:
P = hover thrust value
I = 2x hover thrust value
For this specific craft, a further reduction to ~35% of the original Rate PID values was required.

After Adjustment
Optimized Parameters

With these adjustments applied, the oscillation is eliminated and the vehicle is ready for further tuning steps.
author_association: COLLABORATOR