feat(dshot): Extended Telemetry and EEPROM support

Overhauls the DShot driver with per-timer BDShot selection, multi-timer sequential capture, Extended DShot Telemetry (EDT), and AM32 ESC EEPROM read/write via MAVLink. Expands ESC support from 8 to 12 channels. BDShot: - Per-timer BDShot protocol selection via actuator config UI - Multi-timer sequential burst/capture on any DMA-capable timer - Adaptive per-channel GCR bitstream decoding - Per-channel online/offline detection with hysteresis Extended DShot Telemetry (EDT): - Temperature, voltage, current from BDShot frames (no serial wire) - New DSHOT_BIDIR_EDT parameter - EDT data merged with serial telemetry when both available AM32 EEPROM: - Read/write AM32 ESC settings via MAVLink ESC_EEPROM message - ESCSettingsInterface abstraction for future ESC firmware types - New DSHOT_ESC_TYPE parameter Other changes: - Per-motor pole count params DSHOT_MOT_POL1–12 (replaces MOT_POLE_COUNT) - EscStatus/EscReport expanded to 12 ESCs with uint16 bitmasks - Numerous bounds-check, overflow, and concurrency fixes - Updated DShot documentation
2026-05-26 01:17:51 +08:00 · 2026-03-17 16:38:33 -08:00
parent c9ee06ff17
commit f00e46f618
48 changed files with 2997 additions and 1692 deletions
@@ -72,7 +72,7 @@ The ESC RPM feedback is used to track the rotor blade pass frequency and its har

 ESC RPM feedback requires ESCs capable of providing RPM feedback such as [DShot](../peripherals/dshot.md) with telemetry connected, a bidirectional DShot set up ([work in progress](https://github.com/PX4/PX4-Autopilot/pull/23863)), or [UAVCAN/DroneCAN ESCs](../dronecan/escs.md).
 Before enabling, make sure that the ESC RPM is correct.
-You might have to adjust the [pole count of the motors](../advanced_config/parameter_reference.md#MOT_POLE_COUNT).
+You might have to adjust the per-motor pole count (`DSHOT_MOT_POL1`–`DSHOT_MOT_POL12`).

 The following parameters should be set to enable and configure dynamic notch filters:

@@ -51,6 +51,18 @@ Other
 - Open source AM32 firmware
 - [DIU Blue Framework Listed](https://www.diu.mil/blue-uas/framework)

+## PX4 Configuration
+
+The ARK 4IN1 ESC supports DShot 300/600, Bidirectional DShot, and PWM input protocols.
+
+- **Bidirectional DShot**: Select BDShot300 or BDShot600 in the [Actuator Configuration](../config/actuators.md) to enable eRPM telemetry.
+- **[Extended DShot Telemetry (EDT)](https://github.com/bird-sanctuary/extended-dshot-telemetry)**: AM32 firmware supports EDT, which provides temperature, voltage, and current through the BDShot signal. Enable with `DSHOT_BIDIR_EDT=1`.
+- **AM32 EEPROM Settings**: Set `DSHOT_ESC_TYPE=1` to enable reading and writing ESC firmware settings via a ground station.
+
+See [DShot ESCs](../peripherals/dshot.md) for full setup details.
+
 ## See Also

 - [ARK 4IN1 ESC CONS](https://docs.arkelectron.com/electronic-speed-controller/ark-4in1-esc) (ARK Docs)
+- [DShot and Bidirectional DShot](https://brushlesswhoop.com/dshot-and-bidirectional-dshot/) (brushlesswhoop.com - General DShot reference)
+- [Extended DShot Telemetry (EDT) Specification](https://github.com/bird-sanctuary/extended-dshot-telemetry) (bird-sanctuary)
@@ -47,71 +47,12 @@ Then connect the battery and arm the vehicle.
 The ESCs should initialize and the motors turn in the correct directions.

 - If the motors do not spin in the correct direction (for the [selected airframe](../airframes/airframe_reference.md)) you can reverse them in the UI using the **Set Spin Direction** option (this option appears after you select DShot and assign motors).
-  You can also reverse motors by sending an [ESC Command](#commands).

 ## ESC Commands {#commands}

 Commands can be sent to the ESC via the [MAVLink shell](../debug/mavlink_shell.md).
 See [here](../modules/modules_driver.md#dshot) for a full reference of the supported commands.

-The most important ones are:
-
- Make a motor connected to FMU output pin 1 beep (helps with identifying motors)
-
-  ```sh
-  dshot beep1 -m 1
-  ```
-
- Retrieve ESC information (requires telemetry, see below):
-
-  ```sh
-  nsh> dshot esc_info -m 2
-  INFO  [dshot] ESC Type: #TEKKO32_4in1#
-  INFO  [dshot] MCU Serial Number: xxxxxx-xxxxxx-xxxxxx-xxxxxx
-  INFO  [dshot] Firmware version: 32.60
-  INFO  [dshot] Rotation Direction: normal
-  INFO  [dshot] 3D Mode: off
-  INFO  [dshot] Low voltage Limit: off
-  INFO  [dshot] Current Limit: off
-  INFO  [dshot] LED 0: unsupported
-  INFO  [dshot] LED 1: unsupported
-  INFO  [dshot] LED 2: unsupported
-  INFO  [dshot] LED 3: unsupported
-  ```
-
- Permanently set the spin direction of a motor connected to FMU output pin 1 (while motors are _not_ spinning):
-  - Set spin direction to `reversed`:
-
-    ```sh
-    dshot reverse -m 1
-    dshot save -m 1
-    ```
-
-    Retrieving ESC information will then show:
-
-    ```sh
-    Rotation Direction: reversed
-    ```
-
-  - Set spin direction to `normal`:
-
-    ```sh
-    dshot normal -m 1
-    dshot save -m 1
-    ```
-
-    Retrieving ESC information will then show:
-
-    ```sh
-    Rotation Direction: normal
-    ```
-
-  ::: info
-  - The commands will have no effect if the motors are spinning, or if the ESC is already set to the corresponding direction.
-  - The ESC will revert to its last saved direction (normal or reversed) on reboot if `save` is not called after changing the direction.
-
-  :::
-
 ## ESC Telemetry

 Some ESCs are capable of sending telemetry back to the flight controller through a UART RX port.
@@ -130,60 +71,76 @@ To enable this feature (on ESCs that support it):
 1. Join all the telemetry wires from all the ESCs together, and then connect them to one of the RX pins on an unused flight controller serial port.
 2. Enable telemetry on that serial port using [DSHOT_TEL_CFG](../advanced_config/parameter_reference.md#DSHOT_TEL_CFG).

-After a reboot you can check if telemetry is working (make sure the battery is connected) using:
-
-```sh
-dshot esc_info -m 1
-```
-
-::: tip
-You may have to configure [MOT_POLE_COUNT](../advanced_config/parameter_reference.md#MOT_POLE_COUNT) to get the correct RPM values.
+:::tip
+You may have to configure the per-motor pole count parameters ([`DSHOT_MOT_POL1`–`DSHOT_MOT_POL12`](../advanced_config/parameter_reference.md#DSHOT_MOT_POL1)) to get correct RPM values.
+The default value for these is 14 poles, which is typical for 5-inch prop motors.
 :::

-::: tip
-Not all DSHOT-capable ESCs support `[esc_info]`(e.g. APD 80F3x), even when telemetry is supported and enabled.
-The resulting error is:
-
-```sh
-ERROR [dshot] No data received. If telemetry is setup correctly, try again.
-```
-
-Check manufacturer documentation for confirmation/details.
+:::tip
+[Extended DShot Telemetry (EDT)](#extended-dshot-telemetry-edt) can provide temperature, voltage, and current through the BDShot signal — no serial telemetry wire needed.
 :::

 ## Bidirectional DShot (Telemetry)

 <Badge type="tip" text="PX4 v1.16" />

-Bidirectional DShot is a protocol that can provide telemetry including: high rate ESC RPM data, voltage, current, and temperature with a single wire.
+Bidirectional DShot (BDShot) enables the ESC to send eRPM telemetry back to the flight controller on the same signal wire used for throttle commands — no additional telemetry wire is needed for RPM data.
+High-rate eRPM data significantly improves the performance of [Dynamic Notch Filters](../config_mc/filter_tuning.md#dynamic-notch-filters) and enables more precise vehicle tuning.

-The PX4 implementation currently enables only ESC RPM (eRPM) data collection from each ESC at high frequencies.
-This telemetry significantly improves the performance of [Dynamic Notch Filters](../config_mc/filter_tuning.md#dynamic-notch-filters) and enables more precise vehicle tuning.
+With [Extended DShot Telemetry (EDT)](#extended-dshot-telemetry-edt) enabled, BDShot can also provide temperature, voltage, and current data.
+
+### Hardware Support
+
+BDShot requires a flight controller with DMA-capable timers.
+Any FMU output on a supported timer can be used for BDShot — multiple timers are supported through sequential burst/capture.
+
+Supported processors:
+
+- **STM32H7**: All FMU outputs on DMA-capable timers
+- **i.MXRT** (V6X-RT & Tropic): All FMU outputs

 ::: info
-The [ESC Telemetry](#esc-telemetry) described above is currently still necessary if you want voltage, current, or temperature information.
-It's setup and use is independent of bidirectional DShot.
-:::
-
-### Hardware Setup
-
 The ESC must be connected to FMU outputs only.
-These will be labeled `MAIN` on flight controllers that only have one PWM bus, and `AUX` on controllers that have both `MAIN` and `AUX` ports (i.e. FCs that have an IO board).
-
-::: warning **Limited hardware support**
-This feature is only supported on flight controllers with the following processors:
-
- STM32H7: First four FMU outputs
-  - Must be connected to the first 4 FMU outputs, and these outputs must also be mapped to the same timer.
-  - [KakuteH7](../flight_controller/kakuteh7v2.md) is not supported because the outputs are not mapped to the same timer.
- [i.MXRT](../flight_controller/nxp_mr_vmu_rt1176.md) (V6X-RT & Tropic): 8 FMU outputs.
-
-No other boards are supported.
+These are labeled `MAIN` on controllers with a single PWM bus, and `AUX` on controllers with both `MAIN` and `AUX` ports (i.e. those with an IO board).
 :::

-### Configuration {#bidirectional-dshot-configuration}
+### PX4 Configuration {#bidirectional-dshot-configuration}

-To enable bidirectional DShot, set the [DSHOT_BIDIR_EN](../advanced_config/parameter_reference.md#DSHOT_BIDIR_EN) parameter.
+BDShot is enabled **per-timer** in the [Actuator Configuration](../config/actuators.md) UI.
+Select **BDShot150**, **BDShot300**, or **BDShot600** as the output protocol instead of the corresponding DShot speed.
+There is no separate enable parameter — choosing a BDShot protocol activates bidirectional telemetry on that timer's outputs.

-The system calculates actual motor RPM from the received eRPM data using the [MOT_POLE_COUNT](../advanced_config/parameter_reference.md#MOT_POLE_COUNT) parameter.
-This parameter must be set correctly for accurate RPM reporting.
+The system calculates actual motor RPM from eRPM data using per-motor pole count parameters: `DSHOT_MOT_POL1` through `DSHOT_MOT_POL12` (one per motor output).
+The default is 14 poles, which is typical for 5-inch prop motors.
+If you are using AM32 ESCs, the motor pole count must also be set in the AM32 firmware configuration (e.g. via the AM32 configurator tool) to match.
+
+### Extended DShot Telemetry (EDT)
+
+EDT extends BDShot by interleaving temperature, voltage, and current data into the eRPM telemetry frames.
+This allows ESC health monitoring through the same signal wire, without requiring a separate serial telemetry connection.
+
+To enable EDT:
+
+1. Configure BDShot on the desired outputs (see above).
+2. Set `DSHOT_BIDIR_EDT` to `1` and reboot.
+
+The ESC firmware must support EDT (e.g. [AM32](https://github.com/am32-firmware/AM32)).
+
+When both serial telemetry and BDShot/EDT are enabled, the driver merges data from both sources.
+
+## AM32 ESC Settings (EEPROM)
+
+PX4 can read and write AM32 ESC firmware settings (EEPROM) via a ground station, enabling remote ESC configuration without connecting directly to each ESC.
+
+### Requirements
+
+- ESCs running [AM32 firmware](https://github.com/am32-firmware/AM32) with serial telemetry connected ([DSHOT_TEL_CFG](../advanced_config/parameter_reference.md#DSHOT_TEL_CFG))
+- `DSHOT_ESC_TYPE` set to `1` (AM32)
+- Ground station with ESC EEPROM support (QGroundControl feature in development)
+- MAVLink development dialect enabled on the flight controller
+
+### How It Works
+
+PX4 automatically reads the full EEPROM from each ESC on boot.
+The ground station can then display individual settings and allow the user to modify them.
+Changes are written back to the ESC one byte at a time using the DShot programming protocol.
@@ -7,7 +7,7 @@ Regression test for DSHOT working with PX4
 ## Preflight

 - Ensure vehicle is using a DSHOT ESC
- Parameter [DSHOT_BIDIR_EN](../advanced_config/parameter_reference.md#DSHOT_BIDIR_EN) is enabled
+- Bidirectional DShot is configured (BDShot150/300/600 selected in [Actuator Configuration](../config/actuators.md))
 - Parameter [DSHOT_TEL_CFG](../advanced_config/parameter_reference.md#DSHOT_TEL_CFG) is configured (if ESC supports telemetry)
 - Parameter [SDLOG_PROFILE](../advanced_config/parameter_reference.md#SDLOG_PROFILE) has Debug (`5`) checked