Re-org brushless ESCs,DShot, and BLHeli for better flow

common/source/docs/common-advanced-configuration.rst

@@ -41,7 +41,7 @@ tuning options for the vehicle.
 [site wiki="plane"]
     Crash Detection <crash-detect>
 [/site]
-    Brushless ESCs <common-dshot>
+    BLHeli ESCs <common-blheli32-passthru>
     EKF (Extended Kalman Filter) <common-apm-navigation-extended-kalman-filter-overview>
     EKF Affinity & Lane Switching <common-ek3-affinity-lane-switching>
 [site wiki="copter,rover"]

common/source/docs/common-blheli32-passthru.rst

@@ -1,17 +1,19 @@
 .. _common-blheli32-passthru:
 
-BLHeli_32 Pass-Through Support
-==============================
+BLHeli32/ BLHeli-S Pass-Through Support
+=======================================
+
+In addition to offering enhanced capabilities such as reversing and often, telemetry, BLHeli capable ESCs have the ability to have their parameters and features programmed through the autopilot while it is connected to a PC (if the autopilot firmware provides this capability also). This BLHeli pass-through protocol allows you to configure and upgrade your ESCs without having to disconnect them from your vehicle. You can plug a USB cable into your autopilot and run the BLHeliSuite or BLHeliSuite32 software for Windows to configure your ESCs. 
+
+Most BLHeli ESCs can autodetect if PWM or DShot is selected by the motor protocol parameter set by the user. See the configuration section of :ref:`common-brushless-escs` for more information. In addition, some BLHeli32 capable ESCs offer bi-directional capabilities for telemetry reporting over the control link, see the section below.
 
 .. note::
-   ArduPilot firmware supports the pass-through protocol with up-to-date BLHeli_32 firmware and BLHeliSuite32 or BLHeli_S firmware and BLHeliSuite only.
+   ArduPilot firmware supports the pass-through protocol with up-to-date BLHeli_32 firmware and BLHeliSuite32, or BLHeli_S firmware and BLHeliSuite only.
 
 .. warning:: For pass-through to function, the :ref:`motor protocol <MOT_PWM_TYPE>` (Copter,Rover) or :ref:`Q_M_PWM_TYPE<Q_M_PWM_TYPE>` (QuadPlane) must be set to a digital protocol, ie. one of the DShot protocols. If you wish to use one of the other protocols, just reset the motor protocol after using pass-through to change motor directions or set min/max values. The autopilot must be re-booted after a protocol change.
 
-BLHeli pass-through protocol allows you to configure and upgrade your ESCs without having to disconnect them from your vehicle. You can plug a USB cable into your autopilot and run the BLHeliSuite or BLHeliSuite32 software for Windows to configure your ESCs. ArduPilot firmware supports the pass-through protocol with BLHeli_32 and BLHeli_S only.
-
-The following section shows how to setup BLHeli pass-through support:
----------------------------------------------------------------------
+BLHeli pass-through setup and use:
+----------------------------------
 
 ..  youtube:: np7xXY_e5sA
     :width: 100%
@@ -28,4 +30,33 @@ To enable BLHeli pass-through you need to set the following parameters and reboo
 Now connect a USB cable to your autopilot and use BLHeliSuite32 on Windows to connect. Select "BLHeli32 Bootloader (Betaflight/Cleanflight)" from the interfaces menu.
 
 .. image:: ../../../images/blhelisuite32.jpg
-    :target: ../_images/blhelisuite32.jpg
+    :target: ../_images/blhelisuite32.jpg
+
+Reversible DShot ESCs
+---------------------
+
+Currently, only BLHeli32 and BLHeli-S capable reversible DShot ESCs are supported. In order to use one, the output which drives it must be designated with the appropriate bit in the :ref:`SERVO_BLH_3DMASK<SERVO_BLH_3DMASK>` bitmask parameter. This will map the outputs 1000-1500-2000 values to the correct digital values for the ESC to provide FullReverse-Idle-FullForward range operation, respectively.
+
+If the craft has been setup for DShot commands then ArduPilot will supply the correct command at startup in order to set the ESCs in reversible mode.
+
+In a similar fashion, normal output rotation direction can be reversed by setting :ref:`SERVO_BLH_RVMASK<SERVO_BLH_RVMASK>` without any changes needing to be made through ESC setup software (e.g. BLHeliSuite). This can also be used on ESCs with forward and reversed active operation, ie reversible ESCs, to set the "forward" direction's rotation.
+
+.. note:: Currently, ArduPilot only supports the use of reversible ESCs for Plane and Rover, not Copter.
+
+BLHeli32 ESC Telemetry
+----------------------
+
+Many brushless BLHeli ESCs offer telemetry reporting of important ESC data, such as RPM, Temperature, Current, etc. for use in OSDs or for controlling ArudPilot functions like variable center frequency noise filters. This can be via a serial connection to one of the autopilot's UART RX inputs, whose ``SERIALx_PROTOCOL`` has been set to "16" (ESC Telemetry), or directly over its control connection if it has Bi-Directional DShot capability (only available on certain BLHeli32 capable ESCs at present).
+
+.. image:: ../../../images/dshot-telemwire.png
+    :target: https://shop.holybro.com/holybro-tekko32-esc35a_p1074.html
+
+*image courtesy of holybro.com*
+
+For BLHeli32 ESC telemetery, see:
+
+.. toctree::
+    :maxdepth: 1
+
+    BLHeli32 ESC Telemetry <common-dshot-blheli32-telemetry>
+

common/source/docs/common-brushless-escs.rst

@@ -1,10 +1,10 @@
 .. _common-brushless-escs:
 
-====================
-Brushless Motor ESCs
-====================
+====================================
+PWM,OneSHot, and DShot Protocol ESCs
+====================================
 
-The most common electric motor used with ArduPilot vehicles is brushless and requires a brushless ESC for control. Two main protocols for communicating with these ESCs are PWM and DShot. See :ref:`common-dshot` for configuration information on brushless ESCs.
+The most common electric motor used with ArduPilot vehicles is brushless and requires a brushless ESC for control. The main protocols for controlling these ESCs are PWM, OneShot, and DShot. In addition, some include the ability to be configured via an external PC application called BLHeli Suite or BLHeli32 Suite. See :ref:`common-blheli32-passthru` for more information on ESCs with that capability, but the following sections apply to ArduPilot's setup for those ESCs also.
 
 PWM
 ===
@@ -13,20 +13,35 @@ These are the most common ESCs for non-copter applications and were historically
 .. image:: ../../../images/hobbywing-esc.jpg
 
 
-PWM ESCs use a periodic input pulse of width typically between 1000uS and 2000uS for zero to full power, respectively. The frame rate of these pulses is usually between 50Hz to 490Hz. The faster frame rates allow quicker control reactions to be sent to the motor, if the ESC has capability for those frame rates. The frame rate is controlled by :ref:`RC_SPEED<RC_SPEED>` for all vertical lift motors on a vehicle.
+PWM ESCs use a periodic input pulse of width typically between 1000uS and 2000uS for zero to full power, respectively. The frame rate of these pulses is usually between 50Hz to 490Hz. The faster frame rates allow quicker control reactions to be sent to the motor, if the ESC has capability for those frame rates.
+
+The frame rate is controlled by :ref:`RC_SPEED<RC_SPEED>` for all PWM protocol motors on a Copter and Rover, and :ref:`SERVO_RATE<SERVO_RATE>` for PWM ESCs for normal forward motors on Plane. :ref:`Q_RC_SPEED<Q_RC_SPEED>` controls this for PWM protocol VTOL esc/motors in QuadPlane.
 
 .. note:: be sure of the capabilities of your ESC before selecting a higher frame rate to avoid damage to the ESC.
 
+
+OneShot
+=======
 An even faster PWM protocol is OneShot125 (sometimes shortened to just OneShot). If the ESC has this capability, then the pulse widths are divided by a factor of 8 for even faster communication from the autopilot to the ESC since the commands get to the ESC 8 times faster at any given frame rate. In addition, the capability to increase the frame rate up to 490Hz is allowed.
 
 .. note:: OneShot (vs OneShot125) is an older protocol that uses the same pulse widths as Normal PWM, but has a higher fixed frame rate equal to the autopilot main loop rate. It has been replaced by OneShot125.
 
 DShot
 =====
 
-Dshot is a digital ESC protocol. In contrast to traditional servo-type PWM it allows fast, high resolution digital communication. This opens the door for more precise vehicle control. This is especially useful in multirotor and quadplane applications.
+DShot is a digital ESC protocol. In contrast to traditional servo-type PWM it allows fast, high resolution digital communication. This opens the door for more precise vehicle control. This is especially useful in multirotor and quadplane applications.
 
-..  note::
+DShot is available in various digital communication baud rates, as well as a version supporting ESC telemetry via the control input connection (some ESCs offer telemetry reporting via a separate serial connection):
+
+- DShot150 at 150kbaud (recommended for larger aircraft with long signal lead runs)
+- DShot300 at 300kbaud
+- DShot600 at 600kbaud (recommended)
+- DShot1200 at 1200kbaud
+- Bi-directional DShot at 150, 300, 600 and 1200kbaud on supported firmware (includes telemetry)
+
+.. note:: Bi-directional DShot is a feature currently only offered on ESCs that also have BLHeli32 capability. See :ref:`common-blheli32-passthru` for more information on ESCs with that capability.
+
+.. note::
    Only try DShot on ESCs that are known to support it or you will get unpredictable results. Reverse thrust is supported in ArduPilot 4.0 and later firmware versions.
 
 The DShot ESC protocol's key advantages are:
@@ -36,18 +51,70 @@ The DShot ESC protocol's key advantages are:
 - no need to do any ESC throttle range calibration
 - very high protocol frame rates are supported
 
-While DShot is available on many ESCs, those with BLHeli32 capability, offer the most performance and often, additional features such as ESC telemetry. In addition, ArduPilot provides special programming capability for BLHeli32 ESCs via its passthrough feature (See :ref:`common-dshot` section.)
+While DShot is available on many ESCs, those with BLHeli32 and BLHeli-S setup capability, offer the most performance and often, additional features such as ESC telemetry. In addition, ArduPilot provides special programming capability for BLHeli32 and BLHeli-S ESCs via its passthrough feature (See :ref:`common-blheli32-passthru` section.)
 
 .. note::
    Recently there is a growing number of proprietary and non-proprietary 16 / 32 bit ESCs with firmware that support DShot and other digital ESC protocols, but not BLHeli_32-specific features like passthrough and telemetry. See your ESC's manual for further detail on supported features.
 
-Where to buy
-============
+For larger aircraft with longer cable runs using DShot ESC protocol, we recommend using the lowest baud rate, DShot150, as it is the most reliable protocol (lower baudrates are less susceptible to noise on cables). Higher rates can be more susceptible to noise but also tie up the allocated DMA channel for a shorter period so can be beneficial on flight controllers with a lot of DMA sharing.
+
+For smaller craft, DShot600 is by far the most widely used and can therefore be a more suitable choice simply because of the amount of testing that it has had, rather than the newer DShot1200 protocol.
+
+Bi-directional DShot involves a longer pulse width since it has to wait for a response from the ESC before it can send another pulse and thus DShot300 and DShot600 are to be preferred. Bi-directional DShot does not share DMA channels and so there is no impact on other peripherals.
+
+.. note:: When an output is configured for DShot, the ``SERVOx_MIN/MAX/TRIM`` parameters for that output will always be ignored since DShot does not use these parameters. The trim  value used will be  1500 if it's a reversible output, or 1000 if normal output setup in DShot, and the output range always be 1000-2000. No ESC calibration step is required.
+
+Configuration
+=============
+
+Protocol Selection
+------------------
+The ESC control protocol is selected by the :ref:`MOT_PWM_TYPE <MOT_PWM_TYPE>` parameter on Copter and Rover, or :ref:`Q_M_PWM_TYPE <Q_M_PWM_TYPE>` on QuadPlanes for its copter function motors.
+
+.. note:: The autopilot should be re-booted after changing the protocol type.
+
+On Plane, all other motors use Normal (PWM) protocol. However, in Plane, any motor, like the traditional fixed wing's main motor or Dual Motor Tailsitters (SERVOn_FUNCTION = 70 throttle, 73 throttle left and / or 74 throttle right), can be changed to a protocol other than PWM using the :ref:`SERVO_BLH_MASK<SERVO_BLH_MASK>` parameter to specify the output number of the motor together with the :ref:`SERVO_BLH_OTYPE<SERVO_BLH_OTYPE>` parameter to select the protocol of these motors independently of that selected for the copter function motors. 
+
+.. note:: All mask-based configuration can only be changed at a PWM group level, please consult the documentation for your flight controller to ascertain which outputs are on different groups. See :ref:`Mixing ESC Protocols<mixing-escs>` section below.
+
+.. warning:: Be sure your ESC can support the configuration you select for it. Damage can occur otherwise. This includes frame rates discussed below. Also be careful when switching between digital and analogue output types without re-calibrating ESCs as this can lead to uncommanded motor output.
+
+DShot Update Rates
+------------------
+
+The frequency at which DShot pulses are sent can be configured through :ref:`SERVO_DSHOT_RATE<SERVO_DSHOT_RATE>`. By default ArduPilot will output a DShot data pulse every time a new IMU sample is ready *and* at a fixed 1Khz interval. On a copter with the standard 400Hz scheduler loop rate this works out at about 1.4Khz. However, the output is quite irregular - in order to get more regular output :ref:`SERVO_DSHOT_RATE<SERVO_DSHOT_RATE>` can be configured to send pulses at multiples of the scheduler loop rate. Thus if set to 2 the pulses will be sent at 800Hz, set to 3 at 1.2Khz and so on. The difference being very, very even output which can benefit copters needing tighter motor control (for instance smaller racers). It is not recommended to send pulses at less than 1Khz due to reports of BLHeli32 occasionally missing frames on some flight controllers, similarly sending at higher rates can result in increased reliability and faster recovery from missed pulses where needed at the cost of some CPU. Very high rates can only be used for faster DShot speeds since otherwise pulses might overlap - for instance the fastest rate that DShot150 can theoretically support is 4Khz.
+
+DShot Commands
+--------------
+
+On certain ESCs DShot commands are supported. These allow functions such as ESC LEDs, beeps and motor direction to be manipulated by the flight controller. In order to use DShot commands :ref:`SERVO_DSHOT_ESC<SERVO_DSHOT_ESC>` must be set to the type of ESC that is in use. Notify functions (e.g. LEDs :ref:`NTF_LED_TYPES<NTF_LED_TYPES>` and Buzzer :ref:`NTF_BUZZ_TYPES<NTF_BUZZ_TYPES>`) can then be configured to include DShot as an output type.
+
+The current commands supported are:
+
+-    Dshot LEDs on/off
+-    Dshot Buzzer on/off
+-    Reverse motor direction
+-    Enable 3D operation
+
+.. warning:: Currently, ArduPilot supports the command set (:ref:`SERVO_DSHOT_ESC<SERVO_DSHOT_ESC>` =1) that is commonly used, however, others are appearing and may not be compatible, resulting in undefined operation. Use caution (remove blades!) until correct operation using type=1 is verified for your ESC
+
+.. _mixing-escs:
+
+Mixing ESC Protocols
+====================
+
+While all the servo/motor outputs of an ArduPilot autopilot are capable of Normal PWM operation at 50Hz frame rates, not all are capable of other ESC protocol configurations. And, usually, these configurations must apply to pre-designated groups of outputs, even if they are not all driving an ESC. So the following cautions apply:
+
+#. The 8 "MAIN" outputs of autopilots using an IOMCU (like PixHawk and Cube), cannot be used for  protocols other than Normal PWM and OneShot. On these autopilots, only the additional "AUX" outputs can properly support OneShot125 and DShot protocols. If you attempt to set a "MAIN" output to DShot, then normal PWM output will occur, even though it has been set to a DShot protocol.
+
+#. For :ref:`Pixracer <common-pixracer-overview>` and :ref:`other boards <common-autopilots>` without a separate IOMCU coprocessor, all servo/motor outputs can be used.
+
+#. Groups of outputs sharing a common timer, MUST have the same advanced configuration. Usually, these are specified in the autopilot's hardware description linked from the :ref:`common-autopilots` page. For example, if an output is configured for DShot in a group, then you cannot use another output in that group for Normal PWM ESC **or** normal PWM servo operation.
+
+.. note:: Everytime the autopilot initializes, it sends a log message to the ground control station, showing which outputs are PWM/Oneshot/or DShot. The remaining higher numbered outputs are assigned as GPIOs.
 
-A `search for "BLHeli32 shopping" <https://www.google.com/search?q=blheli32&tbm=shop>`__ turns up many compatible ESCs.  Look for an ESC which includes the telemetry wire connector like the `HolyBro Tekko32 shown below <https://shop.holybro.com/holybro-tekko32-esc35a_p1074.html>`__
+.. image:: ../../../images/RCOutbanner.jpg
 
-.. image:: ../../../images/dshot-telemwire.png
-    :target: https://shop.holybro.com/holybro-tekko32-esc35a_p1074.html
 
-*image courtesy of holybro.com*
+.. _esc-telemetry:
 

common/source/docs/common-dshot-blheli32-telemetry.rst

@@ -1,5 +1,6 @@
 .. _common-dshot-blheli32-telemetry:
 
+====================================
 BLHeli_32 and BLHeli_S ESC Telemetry
 ====================================