266 lines
7.5 KiB
Markdown
266 lines
7.5 KiB
Markdown
[](https://github.com/derdoktor667/DShotRMT/actions/workflows/ci.yml)
|
||
|
||
# DShotRMT - ESP32 Library (Rewrite for ESP-IDF 5)
|
||
|
||
A modern, robust C++ library for generating DShot signals on the ESP32 using the new ESP-IDF 5 RMT encoder API (`rmt_tx.h` / `rmt_rx.h`).
|
||
Supports all standard DShot modes (150, 300, 600) and features continuous frame transmission with configurable pause.
|
||
**Now with BiDirectional DShot support and advanced command management!**
|
||
|
||
> The legacy version (using the old `rmt.h` API) is still available in the `oldAPI` branch.
|
||
|
||
---
|
||
|
||
## 🚀 Features
|
||
|
||
- **All DShot Modes:** DSHOT150, DSHOT300 (default), DSHOT600, (DSHOT1200)
|
||
- **BiDirectional DShot:** Experimental support for RPM feedback
|
||
- **Advanced Command Manager:** High-level API for ESC configuration and control
|
||
- **Command Sequences:** Predefined initialization and calibration sequences
|
||
- **Continuous Frames:** Independent timed, Hardware signal generation
|
||
- **Configurable Pause:** Ensures ESCs can reliably detect frame boundaries
|
||
- **Simple API:** Easy integration into your Arduino or ESP-IDF project
|
||
|
||
---
|
||
|
||
## 📦 Installation
|
||
|
||
Clone this repository and add it to your Arduino libraries or ESP-IDF components.
|
||
|
||
```sh
|
||
git clone https://github.com/derdoktor667/DShotRMT.git
|
||
```
|
||
|
||
---
|
||
|
||
## ⚡ Quick Start
|
||
|
||
### Basic Usage (DShotRMT)
|
||
|
||
```cpp
|
||
#include <DShotRMT.h>
|
||
|
||
// Create motor instance
|
||
DShotRMT motor(17, DSHOT300);
|
||
|
||
void setup() {
|
||
Serial.begin(115200);
|
||
motor.begin();
|
||
}
|
||
|
||
void loop() {
|
||
motor.sendThrottle(1000); // Send throttle value
|
||
delay(20);
|
||
}
|
||
```
|
||
|
||
### Advanced Usage (DShotCommandManager)
|
||
|
||
```cpp
|
||
#include <DShotRMT.h>
|
||
#include <DShotCommandManager.h>
|
||
|
||
// Create motor and command manager instances
|
||
DShotRMT motor(17, DSHOT300);
|
||
DShotCommandManager cmdManager(motor);
|
||
|
||
void setup() {
|
||
Serial.begin(115200);
|
||
motor.begin();
|
||
cmdManager.begin();
|
||
|
||
// Execute initialization sequence
|
||
cmdManager.executeInitSequence();
|
||
}
|
||
|
||
void loop() {
|
||
// Your main code here
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🎛️ DShotCommandManager API
|
||
|
||
The `DShotCommandManager` provides a high-level interface for ESC control and configuration:
|
||
|
||
### Motor Control
|
||
- `stopMotor()` - Stop motor immediately
|
||
- `set3DMode(bool enable)` - Enable/disable 3D mode
|
||
- `setSpinDirection(bool reversed)` - Set motor spin direction
|
||
- `saveSettings()` - Save current settings to ESC
|
||
|
||
### LED Control (BLHeli32 only)
|
||
- `setLED(uint8_t led_number, bool state)` - Control ESC LEDs (0-3)
|
||
|
||
### Beacon Functions
|
||
- `activateBeacon(uint8_t beacon_number)` - Activate motor beeping (1-5)
|
||
|
||
### Telemetry
|
||
- `setExtendedTelemetry(bool enable)` - Enable/disable extended telemetry
|
||
- `requestESCInfo()` - Request ESC information
|
||
|
||
### Command Sequences
|
||
- `executeInitSequence()` - Basic ESC initialization
|
||
- `executeCalibrationSequence()` - ESC calibration sequence
|
||
- `executeSequence(sequence, length)` - Custom command sequences
|
||
|
||
### Utility Functions
|
||
- `getCommandName(command)` - Get command name as string
|
||
- `isValidCommand(command)` - Validate command
|
||
- `printStatistics()` - Print execution statistics
|
||
- `resetStatistics()` - Reset execution counters
|
||
|
||
---
|
||
|
||
## 📚 Examples
|
||
|
||
### 1. Basic DShot Control
|
||
Use the `dshot300.ino` example for simple throttle control.
|
||
|
||
### 2. Advanced Command Management
|
||
Use the `command_manager.ino` example for interactive ESC control:
|
||
|
||
```
|
||
=== DShot Command Manager Menu ===
|
||
Basic Commands:
|
||
1 - Stop Motor
|
||
2 - Activate Beacon 1
|
||
3 - Set Normal Spin Direction
|
||
4 - Set Reversed Spin Direction
|
||
5 - Enable 3D Mode
|
||
6 - Disable 3D Mode
|
||
7 - Save Settings
|
||
8 - Turn LED 0 ON
|
||
9 - Turn LED 0 OFF
|
||
|
||
Sequences:
|
||
i - Execute Initialization Sequence
|
||
c - Execute Calibration Sequence
|
||
|
||
Advanced:
|
||
cmd <number> - Send DShot command (0 - 47)
|
||
throttle <value> - Set throttle (48 - 2047)
|
||
throttle 0 - Stop sending throttle
|
||
```
|
||
|
||
---
|
||
|
||
## 📚 DShot Protocol Overview
|
||
|
||
DShot transmits 16-bit packets to brushless ESCs:
|
||
|
||
- **11 bits:** Throttle value
|
||
- **1 bit:** Telemetry request
|
||
- **4 bits:** Checksum (CRC)
|
||
|
||
Data is sent MSB-first. Pulse timing depends on the selected DShot mode.
|
||
|
||
| DSHOT | Bitrate | TH1 | TH0 | Bit Time (µs) | Frame Time (µs) |
|
||
|-------|-------------|-------|--------|---------------|-----------------|
|
||
| 150 | 150 kbit/s | 5.00 | 2.50 | 6.67 | ~106.72 |
|
||
| 300 | 300 kbit/s | 2.50 | 1.25 | 3.33 | ~53.28 |
|
||
| 600 | 600 kbit/s | 1.25 | 0.625 | 1.67 | ~26.72 |
|
||
|
||
Each frame is followed by a pause to help ESCs detect separate frames.
|
||
|
||
|
||
|
||
---
|
||
|
||
## 🔒 Checksum Calculation
|
||
|
||
The checksum is calculated over the first 12 bits (throttle + telemetry):
|
||
|
||
```c
|
||
crc = (value ^ (value >> 4) ^ (value >> 8)) & 0x0F;
|
||
```
|
||
|
||
### Bidirectional DSHOT
|
||
|
||
Bidirectional DSHOT (sometimes called "inverted DSHOT") inverts the signal level:
|
||
A logical '1' is low, and a '0' is high. This signals the ESC to send telemetry packets back.
|
||
|
||
**Bidirectional CRC:**
|
||
|
||
```c
|
||
crc = (~(value ^ (value >> 4) ^ (value >> 8))) & 0x0F;
|
||
```
|
||
|
||
> **Note:** Bidirectional DShot is experimental. Further hardware testing is needed.
|
||
|
||
---
|
||
|
||
## 🛠️ ESP32 RMT Peripheral
|
||
|
||
The RMT (Remote Control) peripheral generates accurate, hardware-timed signals for controlling external devices.
|
||
Perfect for DShot:
|
||
- Utilizes latest ESP-IDF APIs
|
||
- Hardware-timed pulses
|
||
- CPU-independent
|
||
- Loop mode with inter-frame pause
|
||
- Reliable under system load
|
||
|
||
---
|
||
|
||
## 📝 Core API Reference
|
||
|
||
### DShotRMT Class
|
||
- `DShotRMT(gpio_num_t gpio, dshot_mode_t mode, bool isBidirectional)`
|
||
- `uint16_t begin()`
|
||
- `bool sendThrottle(uint16_t throttle)`
|
||
- `bool sendCommand(uint16_t command)`
|
||
- `uint16_t getERPM()` - Get eRPM (bidirectional mode only)
|
||
- `uint32_t getMotorRPM(uint8_t magnet_count)` - Convert to motor RPM
|
||
|
||
### DShotCommandManager Class
|
||
- `DShotCommandManager(DShotRMT &dshot_instance)`
|
||
- `bool begin()`
|
||
- `dshot_command_result_t sendCommand(dshot_commands_t command, uint16_t repeat_count = 1)`
|
||
- `dshot_command_result_t sendCommandWithDelay(dshot_commands_t command, uint16_t repeat_count, uint32_t delay_ms)`
|
||
|
||
All command methods return a `dshot_command_result_t` structure containing:
|
||
- `bool success` - Command execution status
|
||
- `uint32_t execution_time_us` - Execution time in microseconds
|
||
- `const char* error_message` - Error description
|
||
|
||
---
|
||
|
||
## 🎯 DShot Commands
|
||
|
||
The library supports all standard DShot commands:
|
||
|
||
| Command | Value | Description |
|
||
|---------|-------|-------------|
|
||
| MOTOR_STOP | 0 | Stop motor |
|
||
| BEACON1-5 | 1-5 | Motor beeping |
|
||
| ESC_INFO | 6 | Request ESC information |
|
||
| SPIN_DIRECTION_1/2 | 7-8 | Set spin direction |
|
||
| 3D_MODE_OFF/ON | 9-10 | 3D mode control |
|
||
| SAVE_SETTINGS | 12 | Save settings to ESC |
|
||
| EXTENDED_TELEMETRY_ENABLE/DISABLE | 13-14 | Telemetry control |
|
||
| LED0-3_ON/OFF | 22-29 | LED control (BLHeli32) |
|
||
| AUDIO_STREAM_MODE | 30 | KISS audio mode |
|
||
| SILENT_MODE | 31 | KISS silent mode |
|
||
|
||
---
|
||
|
||
## 📖 References
|
||
|
||
- [DSHOT – the missing Handbook](https://brushlesswhoop.com/dshot-and-bidirectional-dshot/)
|
||
- [DSHOT in the Dark](https://dmrlawson.co.uk/index.php/2017/12/04/dshot-in-the-dark/)
|
||
- [ESP32 Technical Reference Manual](https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf)
|
||
|
||
---
|
||
|
||
## 📄 License
|
||
|
||
MIT License – see [LICENSE](LICENSE)
|
||
|
||
---
|
||
|
||
## 👤 Author
|
||
|
||
**Wastl Kraus**
|
||
GitHub: [@derdoktor667](https://github.com/derdoktor667)
|
||
Website: [wir-sind-die-matrix.de](https://wir-sind-die-matrix.de)
|