OneShot docs (PX4#1648)

musalmaz · Nov 11, 2021 · 65bda4f · 65bda4f
1 parent 4337b99
commit 65bda4f
Show file tree

Hide file tree

Showing 7 changed files with 123 additions and 7 deletions.
diff --git a/assets/peripherals/esc_pwm_duty_cycle.png b/assets/peripherals/esc_pwm_duty_cycle.png
diff --git a/en/SUMMARY.md b/en/SUMMARY.md
@@ -260,6 +260,7 @@
       * [PMW3901](sensor/pmw3901.md)
     * [ESCs & Motors](peripherals/esc_motors.md)
       * [PWM ESCs and Servos](peripherals/pwm_escs_and_servo.md)
+      * [OneShot ESCs and Servos](peripherals/oneshot.md)
       * [UAVCAN ESCs](uavcan/escs.md)
       * [DShot ESCs](peripherals/dshot.md)
     * [Camera](peripherals/camera.md)

diff --git a/en/advanced_config/esc_calibration.md b/en/advanced_config/esc_calibration.md
@@ -1,7 +1,7 @@
 # ESC Calibration
 
 :::note
-These instructions are only relevant to [PWM ESCs](../peripherals/pwm_escs_and_servo.md).
+These instructions are only relevant to [PWM ESCs](../peripherals/pwm_escs_and_servo.md) and [OneShot ESCs](../peripherals/oneshot.md) ([DShot](../peripherals/dshot.md) and [UAVCAN](../uavcan/escs.md) ESCs do not require calibration).
 :::
 
 Electronic Speed Controllers (ESCs) regulate motor speed (and direction) based on the PWM input value from the flight controller (FC).

diff --git a/en/peripherals/dshot.md b/en/peripherals/dshot.md
@@ -1,6 +1,6 @@
 # DShot ESCs
 
-DShot is an alternative ESC protocol that has several advantages over PWM or OneShot:
+DShot is an alternative ESC protocol that has several advantages over [PWM](../peripherals/pwm_escs_and_servo.md) or [OneShot](../peripherals/oneshot.md):
 - Reduced latency.
 - Increased robustness via a checksum.
 - No need for ESC calibration as the protocol uses digital encoding.
@@ -40,7 +40,7 @@ FMUv5x-based boards support DShot only on the first six FMU pins.
 You can't mix DShot ESCs/servos and PWM ESCs/servos on the FMU (DShot is enabled/disabled for *all* FMU pins on the port). 
 :::
 
-<span id="configuration"></span>
+
 ## Configuration
 
 :::warning

diff --git a/en/peripherals/esc_motors.md b/en/peripherals/esc_motors.md
@@ -1,12 +1,82 @@
 # ESCs & Motors
 
-Many PX4 drones use brushless motors that are driven by the flight controller via an Electronic Speed Controller (ESC) (the ESC converts a signal from the flight controller to an appropriate level of power delivered to the motor).
+Many PX4 drones use brushless motors that are driven by the flight controller via an Electronic Speed Controller (ESC).
+The ESC takes a signal from the flight controller and uses it to set control the level of power delivered to the motor.
 
-PX4 supports [ESCs that take a PWM input](../peripherals/pwm_escs_and_servo.md), ESCs that use the ESC *OneShot* standard, [DShot](../peripherals/dshot.md), [UAVCAN ESCs](../peripherals/uavcan_escs.md), PCA9685 ESC (via I2C), and some UART ESCs (from Yuneec).
+PX4 supports a number of common protocols for sending the signals to ESCs: [PWM ESCs](../peripherals/pwm_escs_and_servo.md), [OneShot ESCs](../peripherals/oneshot.md), [DShot ESCs](../peripherals/dshot.md), [UAVCAN ESCs](../peripherals/uavcan_escs.md), PCA9685 ESC (via I2C), and some UART ESCs (from Yuneec).
 
 For more information see:
 * [PWM ESCs and Servos](../peripherals/pwm_escs_and_servo.md)
+* [OneShot ESCs and Servos](../peripherals/oneshot.md)
 * [DShot](../peripherals/dshot.md)
 * [UAVCAN ESCs](../peripherals/uavcan_escs.md)
 * [ESC Calibration](../advanced_config/esc_calibration.md)
 * [ESC Firmware and Protocols Overview](https://oscarliang.com/esc-firmware-protocols/) (oscarliang.com)
+
+A high level overview of the main ESC/Servo protocols supported by PX4 is given below.
+
+## ESC Protocols
+
+### PWM
+
+[PWM ESCs](../peripherals/pwm_escs_and_servo.md) are commonly used for fixed wing vehicles and ground vehicles (vehicles that require a lower latency like multicopters typically use oneshot or dshot ESCs).
+
+PWM ESCs communicate using a periodic pulse, where the _width_ of the pulse indicates the desired power level.
+The pulse wdith typically ranges between 1000uS for zero power and 2000uS for full power.
+The periodic frame rate of the signal depends on the capability of the ESC, and commonly ranges between 50Hz and 490 Hz (the theoretical maximum being 500Hz for a very small "off" cycle).
+A higher rate is better for ESCs, in particular where a rapid response to setpoint changes is needed.
+For PWM servos 50Hz is usually sufficient, and many don't support higher rates.
+
+![duty cycle for PWM](../../assets/peripherals/esc_pwm_duty_cycle.png)
+
+In addition to being a relatively slow protocol PWM ESCs require [calibration](../advanced_config/esc_calibration.md) because the range values representing low and high values can vary signficantly.
+Unlike [dshot](#dshot) and [UAVCAN ESC](#UAVCAN) they do not have the ability to provide telemetry and feedback on ESC (or servo) state.
+
+Setup:
+- [ESC Wiring](../peripherals/pwm_escs_and_servo.md)
+- [PX4 Configuration](../peripherals/pwm_escs_and_servo.md#px4-configuration)
+- [ESC Calibration](../advanced_config/esc_calibration.md)
+
+
+
+### Oneshot 125
+
+[OneShot 125 ESCs](../peripherals/oneshot.md) are usually much faster than PWM ESCs, and hence more responsive and easier to tune.
+They are preferred over PWM for multicopters (but not as much as [DShot ESCs](#dshot), which do not require calibration, and may provide telemetry feedback).
+There are a number of variants of the OneShot protocol, which support different rates.
+PX4 only supports OneShot 125.
+
+OneShot 125 is the same as PWM but uses pulse widths that are 8 times shorter (from 125us to 250us for zero to full power).
+This allows OneShot 125 ESCs to have a much shorter duty cycle/higher rate. 
+For PWM the theoretical maximum is close to 500 Hz while for OneShot it approaches 4 kHz.
+The actual supported rate depends on the ESC used.
+
+Setup:
+- [ESC Wiring](../peripherals/pwm_escs_and_servo.md) (same as for PWM ESCs)
+- [PX4 Configuration](../peripherals/oneshot.md#px4-configuration)
+- [ESC Calibration](../advanced_config/esc_calibration.md)
+
+### DShot
+
+[DShot](../peripherals/dshot.md) is a digital ESC protocol that is highly recommended for vehicles that can benefit from reduce latency, in particular racing multicopters, VTOL vehicles, and so on.
+
+It has reduced latency annd is more robust than both [PWM](#pwm) and [OneShot](#oneshot).
+In addition it does not require ESC calibration, telemetry is available from some ESCs, and you can revers motor spin directions
+
+PX4 configuration is done by setting the desired rate using [DSHOT_CONFIG](../advanced_config/parameter_reference.md#DSHOT_CONFIG).
+The parameter value indicates the data rate in kbaud - e.g. DShot150 has a rate of 150kbaud.
+Higher rates result in lower latency, but lower rates are more robust (and hence more suitable for large aircraft with longer leads); some ESCs only support lower rates (see datasheets for information).
+
+Setup:
+- [ESC Wiring](../peripherals/pwm_escs_and_servo.md) (same as for PWM ESCs)
+- [PX4 Configuration](../peripherals/dshot.md#configuration) (using [DSHOT_CONFIG](../advanced_config/parameter_reference.md#DSHOT_CONFIG))
+- [DShot](../peripherals/dshot.md) also contains information about how to send commands etc.
+
+### UAVCAN
+
+[UAVCAN ESCs](../peripherals/uavcan_escs.md) are recommended when UAVCAN is the primary bus used for your vehicle.
+The PX4 implementation is currently limited to update rates of 200Hz.
+
+UAVCAN shares many similar benefits to [Dshot](#dshot) including high data rates, robust connection over long leads, telemetry feedback, no need for calibration of the ESC itself.
+
+[UAVCAN ESCs](../peripherals/uavcan_escs.md) are connected via the UAVCAN bus (setup and configuration are covered at that link).
diff --git a/en/peripherals/oneshot.md b/en/peripherals/oneshot.md
@@ -0,0 +1,38 @@
+# OneShot Servos and ESCs (Motor Controllers)
+
+PX4 support OneShot 125 ESCs (only).
+These are typically faster and more responsive than [PWM ESCs](../peripherals/pwm_escs_and_servo.md) but share the same wiring setup (all you need to do is set some different parameters)
+
+:::note
+[DShot](../peripherals/dshot.md) should always be used instead of OneShot where possible, as it is more responsive, more robust, does not required calibration, and may support telemetry.
+The only reason not to use DShot would be hardware limitations (insufficient DShot pins available or using an ESC that does not support DShot).
+:::
+
+
+## Overview
+
+OneShot is essentially a version of [PWM](../peripherals/pwm_escs_and_servo.md) that can be, in theory, up to 8 times faster.
+
+Both PWM and OneShot communicate using a periodic pulse, where the width of the pulse indicates the desired power level.
+For PWM the pulse length typically ranges between 1000uS (zero) and 2000uS (full power), while for OneShot 125 the pulse widths are 8 times shorter, ranging from 125us (zero power) to 250us (full power).
+
+The theoretical maximum rate at which pulses can be sent, and hence the responsiveness, depends on the width of the largest pulse.
+For PWM this rate is close to 500 Hz while for OneShot it approaches 4 kHz.
+In practice the actual maximum rate for OneShot ESCs is typically between 1 kHz and 2 kHz, depending on the ESC used.
+
+
+## Setup
+
+### Wiring
+
+Wiring is exactly the same as for [PWM ESCs](../peripherals/pwm_escs_and_servo.md) (and dshot).
+
+### PX4 Configuration
+
+To enable OneShot set the following parameters:
+- [DSHOT_CONFIG](../advanced_config/parameter_reference.md#DSHOT_CONFIG): Set to `0` in order to _disable_ DShot (so you can use OneShot)
+- [PWM_MAIN_RATE](../advanced_config/parameter_reference.md#PWM_MAIN_RATE)/[PWM_AUX_RATE](../advanced_config/parameter_reference.md#PWM_AUX_RATE): Set to `0` to enable OneShot 125 for all MAIN (IO) and AUX (FMU) ESC outputs, respectively.
+- [PWM_MAIN_MIN](../advanced_config/parameter_reference.md#PWM_MAIN_MIN)/[PWM_AUX_MIN](../advanced_config/parameter_reference.md#PWM_AUX_MIN) and [PWM_MAIN_MAX](../advanced_config/parameter_reference.md#PWM_MAIN_MAX)/[PWM_AUX_MAX](../advanced_config/parameter_reference.md#PWM_AUX_MAX): set to the normal PWM range, nominally `1000` to `2000`.
+  These are scaled internally to output appropriate pulse-widths for Oneshot.
+
+Then perform [ESC Calibration](../advanced_config/esc_calibration.md).
diff --git a/en/peripherals/pwm_escs_and_servo.md b/en/peripherals/pwm_escs_and_servo.md
@@ -58,9 +58,16 @@ On an opto-isolated ESC **without** BEC, the +5V line might need to be connected
 In this case the wire will normally be connected to the flight controller servo rail, and the servo rail must be powered from an additional BEC. 
 
 
-## PWM Configuration
+## PX4 Configuration
 
-The PX4 PWM configuration parameters can be found here: [PWM Outputs](../advanced_config/parameter_reference.md#pwm-outputs).
+Configure the outputs using the following paramters:
+- [PWM_MAIN_RATE](../advanced_config/parameter_reference.md#PWM_MAIN_RATE) (IO) and/or [PWM_AUX_RATE](../advanced_config/parameter_reference.md#PWM_AUX_RATE) (FMU): Set to the highest frame rate supported by the connected ESC, in Hz.
+- [PWM_MAIN_MIN](../advanced_config/parameter_reference.md#PWM_MAIN_MIN)/[PWM_AUX_MIN](../advanced_config/parameter_reference.md#PWM_AUX_MIN) and [PWM_MAIN_MAX](../advanced_config/parameter_reference.md#PWM_MAIN_MAX)/[PWM_AUX_MAX](../advanced_config/parameter_reference.md#PWM_AUX_MAX): Set to the normal PWM range, nominally `1000` to `2000`.
+- [DSHOT_CONFIG](../advanced_config/parameter_reference.md#DSHOT_CONFIG): Set to `0` in order to disable DShot.
+
+Then perform [ESC Calibration](../advanced_config/esc_calibration.md).
+
+Additional  PX4 PWM configuration parameters can be found here: [PWM Outputs](../advanced_config/parameter_reference.md#pwm-outputs).
 
 
 ## Troubleshooting