Rover: improved balance bot tuning instructions

rover/source/docs/balance_bot-home.rst

@@ -9,19 +9,7 @@ ArduPilot Rover includes support for Self Balancing Robots or Balance Bots. This
 ..  youtube:: EmhTBPNDpWw
     :width: 100%
 
-
-
-Supported Control Modes
------------------------
-
-- Manual
-- Hold
-- Acro
-- Guided
-- Auto
-- RTL
-
-.. note:: New or inexperienced ArduPilot users are recommended to go through the Rover :ref:`Introduction<gettit>`, :ref:`First Time Setup<apmrover-setup>` and :ref:`First drive<rover-first-drive>` sections before proceeding with this section.
+.. note:: New users are recommended to go through the Rover :ref:`Introduction<gettit>`, :ref:`First Time Setup<apmrover-setup>` and :ref:`First drive<rover-first-drive>` sections before proceeding with this section.
 
 Get Started
 -----------

rover/source/docs/balance_bot-tuning.rst

@@ -4,54 +4,62 @@
 Tuning the Balance Bot
 ======================
 
-Tuning Manual/Hold Mode
-=======================
-Manual and Hold Modes use a PID controller to control pitch angle. This section describes the tuning process for the Pitch Controller. The parameters involved in tuning Manual/Hold Modes are:
+Tuning Pitch Control
+====================
 
-- :ref:`BAL_PITCH_MAX<BAL_PITCH_MAX>`: Maximum pitch angle limit
-- :ref:`BAL_PITCH_TRIM <BAL_PITCH_TRIM>`: Pitch trim to offset tilt of center of mass
-- :ref:`ATC_BAL_P <ATC_BAL_P>`: P Gain
-- :ref:`ATC_BAL_I <ATC_BAL_I>`: I Gain
-- :ref:`ATC_BAL_D <ATC_BAL_D>`: D Gain
-
-**1) Configure PID tuning plot** :
-The tuning process will be easier when viewing the PID tuning plot. To select the Pitch Control PID for plotting, set:
-
-- :ref:`GCS_PID_MASK <GCS_PID_MASK>` = 4 
-
-Now, the plot can be viewed by selecting PID_Tuning from Misssion Planner.
-
-**2) PID tuning with no RC input** :
-Keep the vehicle upright and then arm it in Manual Mode. 
-Tune the P, I and D gains so that the vehicle can stay upright. The vehicle may show tendency to drift off in either direction, but still must be able to hold on to zero degree pitch. This can be checked on the PID tuning plot.
+The Pitch controller should be tuned in Manual mode. The parameters involved in tuning this controller are:
 
-.. warning:: Give throttle input for short durations only. Otherwise the vehicle will reach full speed and become unable to balance. Pull back throttle stick to stop the vehicle.
-
-**3) PID tuning with RC input** :
-Provide throttle input on the RC transmitter and see if the vehicle is able to follow the desired pitch angle, in the PID tuning plot.  Tweak the PID gains so that the vehicle is able to follow the desired pitch angle. Good tuning of the pitch controller is crucial for tuning other Control Modes.
+- :ref:`BAL_PITCH_MAX<BAL_PITCH_MAX>`: Pitch angle limit.  If the user provides full throttle the vehicle will attempt to lean at this angle
+- :ref:`BAL_PITCH_TRIM <BAL_PITCH_TRIM>`: Pitch trim to offset tilt of center of mass
+- :ref:`ATC_BAL_SPD_FF <ATC_BAL_SPD_FF>`: Feed forward gain using the current speed.  This should normally be set to 0
+- :ref:`ATC_BAL_FF <ATC_BAL_FF>`: Feed forward gain using desired pitch angle.  This should normally be set to 0
+- :ref:`ATC_BAL_P <ATC_BAL_P>`: P gain used to correct the current pitch angle error.  Higher values will result in faster error correction but if too high will lead to oscillation.
+- :ref:`ATC_BAL_I <ATC_BAL_I>`: I gain used to correct long term pitch angle errors.  Setting to the same value as P often works well.  If set too high this could lead to slow oscillations.
+- :ref:`ATC_BAL_D <ATC_BAL_D>`: D gain used to correct changes in pitch angle error.  Setting to higher values may result in a more stable pitch control but if too high can lead to very fast oscillations.
+- :ref:`ATC_BAL_IMAX <ATC_BAL_IMAX>`: I term maximum value.  This should normally be set to 1
+- :ref:`ATC_BAL_FLTT <ATC_BAL_FLTT>`: Filter applied to the desired pitch angle.  Lower values lead to a slower moving desired pitch angle target.  Higher values lead to a more responsive pitch target
+- :ref:`ATC_BAL_FLTE <ATC_BAL_FLTE>`: Filter applied to the pitch error.  Lower values lead to a slower response to pitch angle errors.  Higher values lead to a faster response
+- :ref:`ATC_BAL_FLTD <ATC_BAL_FLTD>`: Filter applied to the pitch error applied to the D term.  Lower values lead to a slower response to changes in pitch angle errors.  Higher values lead to a faster response
+
+Good tuning of the pitch controller is crucial for tuning other Control Modes.
+
+Real-time Tuning of Pitch Control
+---------------------------------
+
+It is best to connect the ground station (e.g. Mission Planner) to the vehicle using a telemetry radio and then enable real-time display of the Pitch PID controller's inputs and outputs by doing the following
+
+- Set :ref:`GCS_PID_MASK <GCS_PID_MASK>` = 4 (Pitch)
+- Connect with Mission Planner, go to the Data screen and check the "Tuning" checkbox in the bottom middle.  From the large "Display This" window check "piddesired", "pidachieved" and optionally "pidP", "pidI" and "pidD"
+- Stand the vehicle upright and arm in Manual mode
+- With the throttle stick in the middle the "piddesired" should always be zero while the "pidachieved" will move as the vehicle pitches back and forth
+- Open Mission Planner's Config Full Parameter Tree and adjust :ref:`ATC_BAL_P <ATC_BAL_P>`, :ref:`ATC_BAL_I <ATC_BAL_I>` and :ref:`ATC_BAL_D <ATC_BAL_D>` gains so that "pidachieved" follows "piddesired" (e.g. stays near zero)
+- The vehicle may drift off in either direction so be ready to catch it and return it to its original position.  Drifting is not necessarily a problem at this stage, the goal is for "pidachieved" to follow "piddesired" as closely as possible
+- Apply throttle stick inputs which should result in "piddesired" changing.  Continue to adjust the gains so "pidachieved" tracks well
 
 .. _balance_bot-tuning-pitch-trim:
 
-**4) Adjust pitch trim** :
-Sometimes the vehicle may show tendency to drift off in one direction while upright. This is because the center of mass may be slightly off the vertical axis at zero pitch. Tweaking the :ref:`BAL_PITCH_TRIM <BAL_PITCH_TRIM>` parameter can offset this. This parameter sets the angle for zero-pitch or upright position. Change it slowly in steps of 0.1 till the vehicle doesnt drift anymore.
+Reducing Drift with Pitch Trim
+------------------------------
+
+If the vehicle consistently drifts in one direction while upright in Manual mode the center of mass may be slightly off of center.  :ref:`BAL_PITCH_TRIM <BAL_PITCH_TRIM>` sets the default pitch angle at zero throttle. Adjust it in steps of 0.1 degrees until the vehicle's drift is reduced.
 
 .. _balance_bot-tuning-acro:
 
 Tuning Acro Mode
 ================
-The following parameters must be set as specified below:
+
+The following parameters should be set
 
 - :ref:`CRUISE_THROTTLE <CRUISE_THROTTLE>` = 0 (This parameter can cause conflicts otherwise, in Balance Bots)
 - :ref:`CRUISE_SPEED <CRUISE_SPEED>`: Maximum speed limit for Speed Controller. To be set by trial and error
 
-
 With the above parameters set, follow the tuning guides for :ref:`Speed <rover-tuning-throttle-and-speed>` and :ref:`Steering<rover-tuning-steering-rate>`. Another important thing to note is that the feed-forward term described in these pages does not make any positive contribution in a balance bot and is best, set to zero.
 
 Guided, Auto, RTL
 =================
-To change mode to Acro after an Auto mission is completed set
 
-- :ref:`MIS_DONE_BEHAVE <MIS_DONE_BEHAVE>` =2 
+Follow the :ref:`Navigation tuning instructions <rover-tuning-navigation>` to tune the vehicle for autonomous modes including Guided, Auto and RTL.
 
-By default it switches to Hold Mode, which can cause the vehicle to crash.
+Optionally it may be convenient to automatically change the mode to Acro after an Auto mission is completed by setting
 
+- :ref:`MIS_DONE_BEHAVE <MIS_DONE_BEHAVE>` = 2 (Acro)

rover/source/docs/balance_bot-working.rst

@@ -12,23 +12,26 @@ Balancing
 
 .. image:: /images/balance_bot-balancing.png
 
-A Balance Bot is inherently unstable about its wheel axis(pitch axis). If the vehicle is not in upright position(zero pitch angle), gravity applies a torque that causes the vehicle to fall over in the direction of pitch. To counteract this, the motors must apply a reverse torque, which then causes the vehicle to accelerate in the direction of pitch. 
+A Balance Bot is inherently unstable about its pitch axis. If the vehicle is not perfectly verticle (e.g. pitch angle of zero), gravity applies a torque that causes the vehicle to fall over in the direction of pitch. To counteract this, the motors must apply a reverse torque which causes the vehicle to accelerate in the direction of pitch.
 
 .. image:: /images/balance_bot-control.png
 
-A control system is used to decide the appropriate motor signal to keep the vehicle balanced. The control system takes in a desired pitch value(zero for balancing), uses the sensors on the vehicle to determine its actual pitch angle and calculates the motor signal required to drive the actual pitch angle to the desired value.
+A Pitch PID controller is used to calculate the required throttle to keep the vehicle pitched at a desired angle (e.g. zero to stay balanced without moving forward).
 
 Accelerate/Decelerate
 =====================
 
 .. image:: /images/balance_bot-accelerate.png
 
-As explained previously, when the pitch is non zero, the vehicle is forced to accelerate as it tries to keep itself from falling. Taking this idea forward, if the control system is set to keep the vehicle at a non zero pitch, the vehicle will be forced to accelerate continuously as it tries to maintain that pitch. To accelerate forward, the vehicle can be made to pitch forward and to decelerate or accelerate backwards, the vehicle can be pitched back.
+As explained previously, when the pitch is non zero, the vehicle is forced to accelerate as it tries to keep itself from falling. Taking this idea forward, if the control system is set to keep the vehicle at a non zero pitch, the vehicle will be forced to accelerate continuously as it tries to maintain that pitch. To accelerate forward, the vehicle can be commanded to pitch forward and to decelerate or accelerate backwards, the vehicle can be commanded to pitch back.
 
 
-Rover vs Balance Bot:
-+++++++++++++++++++++
-The working of a Balance Bot is closer to that of a Copter than a conventional Rover. The motion of a Balance Bot is actually caused by the vehicle pitching, rather than simply a motor throttle. This is unlike in a Rover, where the user can directly control motor throttle, to control the vehicle's acceleration. In a Balance Bot, the user controls the pitch angle, which in turns causes the vehicle to accelerate. The motor throttle in a Balance Bot, is determined by the control system and is meant to correct and hold its pitch.
+Pilot Control of a Balance Bot
+==============================
+
+With more typical Rovers (e.g. not balance bots), while in Manual mode, the pilot directly controls the vehicle's throttle output using Ch3 of the transmitter (see top section of the image below).
+
+With Balance Bots however the pilot's throttle controls the desired pitch angle (up to the maximum held in :ref:`BAL_PITCH_MAX<BAL_PITCH_MAX>`).  The throttle output is then calculated by the pitch controller in order to keep the vehicle at the desired pitch.
 
 .. image:: /images/balance_bot-working.png