From 6e3006c4c879104c69541aa74e13ae62847be04e Mon Sep 17 00:00:00 2001 From: Wastl Kraus Date: Sat, 4 Oct 2025 21:41:25 +0200 Subject: [PATCH] prepare release 0.9.0 --- LICENSE | 4 +-- README.md | 28 ++++++++++++++----- .../throttle_percent/throttle_percent.ino | 2 +- examples/web_client/web_client.ino | 7 ++--- examples/web_control/web_control.ino | 6 ++-- library.properties | 2 +- src/DShotRMT.h | 15 +++++++--- src/dshot_definitions.h | 21 ++++++++------ src/{dshot_config.cpp => dshot_init.cpp} | 24 ++++++++++++---- src/{dshot_config.h => dshot_init.h} | 11 ++++++-- src/dshot_utils.h | 12 +++++++- src/web_utilities/ota_update.h | 2 +- src/web_utilities/web_content.h | 2 +- 13 files changed, 94 insertions(+), 42 deletions(-) rename src/{dshot_config.cpp => dshot_init.cpp} (91%) rename src/{dshot_config.h => dshot_init.h} (78%) diff --git a/LICENSE b/LICENSE index e77c526..433d0ec 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2021 Wastl Kraus +Copyright (c) 2023 derdoktor667 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. +SOFTWARE. \ No newline at end of file diff --git a/README.md b/README.md index c5f7b46..ac47120 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,15 @@ # DShotRMT - ESP32 RMT DShot Driver [![Arduino CI](https://github.com/derdoktor667/DShotRMT/actions/workflows/ci.yml/badge.svg)](https://github.com/derdoktor667/DShotRMT/actions/workflows/ci.yml) +[![Arduino Library](https://img.shields.io/badge/Arduino-Library-blue.svg)](https://www.arduinolibraries.com/libraries/dshot-rmt) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -An Arduino IDElibrary for generating DShot signals on ESP32 microcontrollers using the **modern ESP-IDF 5 RMT encoder API** (`rmt_tx.h` / `rmt_rx.h`). This library specifically leverages the official `rmt_bytes_encoder` API for an efficient, hardware-timed, and maintainable implementation. It provides a simple way to control brushless motors in both Arduino and ESP-IDF projects. +An Arduino IDE library for generating DShot signals on ESP32 microcontrollers using the **modern ESP-IDF 5 RMT Encoder API** (`rmt_tx.h` / `rmt_rx.h`). This library specifically leverages the official `rmt_bytes_encoder` API for an efficient, hardware-timed and maintainable implementation. It provides a simple way to control BLHeli ESCs in both Arduino and ESP-IDF projects. The legacy version using the old `rmt.h` API is available in the `oldAPI` branch. +--- + ### DShot300 Example Output Here's an example of the output from the `dshot300` example sketch: @@ -15,7 +19,7 @@ Here's an example of the output from the `dshot300` example sketch: ## 🚀 Core Features - **Multiple DShot Modes:** Supports DSHOT150, DSHOT300, DSHOT600, and DSHOT1200. -- **Bidirectional DShot Support:** Implemented, but note that official support is limited due to potential instability and external hardware requirements. Use with caution. +- **Bidirectional DShot Support:** Implemented, but note that official support is limited due to potential instability and external hardware requirements. Use with caution (and pull-up). - **Hardware-Timed Signals:** Precise signal generation using the ESP32 RMT peripheral, ensuring stable and reliable motor control. - **Simple API:** Easy-to-use C++ class with intuitive methods like `sendThrottlePercent()`. - **Error Handling:** Provides detailed feedback on operation success or failure via `dshot_result_t`. @@ -43,11 +47,11 @@ The DShot protocol defines specific timing characteristics for each mode. The fo ## ⚡ Quick Start -Here's a basic example of how to use the `DShotRMT` library to control a motor. Please use example sketches for more detailes: +Here's a basic example of how to use the `DShotRMT` library to control a motor. Note that `DShotRMT.h` now includes all necessary dependencies, so you only need to include this single header. Please use example sketches for more detailes: ```cpp #include -#include // Include the DShotRMT library +#include // Define the GPIO pin connected to the motor ESC const gpio_num_t MOTOR_PIN = GPIO_NUM_27; @@ -65,14 +69,13 @@ void setup() { printCpuInfo(Serial); Serial.println("Motor initialized. Ramping up to 25% throttle..."); - -} + } void loop() { // Ramp up to 25% throttle over 2.5 seconds for (int i = 0; i <= 25; i++) { motor.sendThrottlePercent(i); - delay(100); + delay(200); } Serial.println("Stopping motor."); @@ -80,6 +83,9 @@ void loop() { // Print DShot Info printDShotInfo(motor, Serial); + + // Take a break before next bench run + delay(3000); } ``` @@ -124,6 +130,14 @@ The main class is `DShotRMT`. Here are the most important methods: - `getEncodedFrameValue()`: Gets the last encoded DShot frame value. - `getThrottleValue()`: Gets the last transmitted throttle value. +## ⚙️ ESP-IDF Integration + +This library is built upon the ESP-IDF framework, specifically leveraging its RMT (Remote Control Peripheral) module for precise signal generation. For detailed information on the underlying ESP-IDF components and their usage, please refer to the official ESP-IDF documentation: + +* [ESP-IDF v5.5.1 Documentation](https://docs.espressif.com/projects/esp-idf/en/v5.5.1/) + +--- + ## 🤝 Contributing Contributions are welcome! Please fork the repository, create a feature branch, and submit a pull request. diff --git a/examples/throttle_percent/throttle_percent.ino b/examples/throttle_percent/throttle_percent.ino index 0ae022d..5bf6dfa 100644 --- a/examples/throttle_percent/throttle_percent.ino +++ b/examples/throttle_percent/throttle_percent.ino @@ -1,6 +1,6 @@ /** * @file throttle_percent.ino - * @brief Demo sketch for DShotRMT library using percentage throttle. + * @brief Example sketch for DShotRMT library demonstrating throttle control by percentage * @author Wastl Kraus * @date 2025-09-20 * @license MIT diff --git a/examples/web_client/web_client.ino b/examples/web_client/web_client.ino index fda65ef..7bae523 100644 --- a/examples/web_client/web_client.ino +++ b/examples/web_client/web_client.ino @@ -1,6 +1,6 @@ /** * @file web_client.ino - * @brief DShotRMT Web Control as WiFi Client + * @brief Example sketch for DShotRMT library demonstrating web control via a client * @author Wastl Kraus * @date 2025-09-11 * @license MIT @@ -16,10 +16,9 @@ ******************************************************************/ #include -#include -#include - #include +#include +#include #include "web_utilities/ota_update.h" #include "web_utilities/web_content.h" diff --git a/examples/web_control/web_control.ino b/examples/web_control/web_control.ino index cac075b..0a88df2 100644 --- a/examples/web_control/web_control.ino +++ b/examples/web_control/web_control.ino @@ -1,6 +1,6 @@ /** * @file web_control.ino - * @brief Demo sketch for DShotRMT library + * @brief Example sketch for DShotRMT library demonstrating web control via an access point * @author Wastl Kraus * @date 2025-09-09 * @license MIT @@ -16,9 +16,9 @@ ******************************************************************/ #include -#include - #include +#include +#include #include "web_utilities/web_content.h" #include diff --git a/library.properties b/library.properties index 36cdefa..24e98af 100644 --- a/library.properties +++ b/library.properties @@ -1,5 +1,5 @@ name=DShotRMT -version=0.8.9 +version=0.9.0 author=Wastl Kraus maintainer=Wastl Kraus license=MIT diff --git a/src/DShotRMT.h b/src/DShotRMT.h index ca1eade..a76819c 100644 --- a/src/DShotRMT.h +++ b/src/DShotRMT.h @@ -9,12 +9,14 @@ #pragma once #include +#include + #include -#include #include +#include #include "dshot_definitions.h" -#include "dshot_config.h" +#include "dshot_init.h" // DShot Protocol Constants static constexpr auto DSHOT_THROTTLE_FAILSAFE = 0; @@ -69,17 +71,22 @@ public: uint16_t getEncodedFrameValue() const { return _encoded_frame_value; } private: + // Configuration gpio_num_t _gpio; dshot_mode_t _mode; bool _is_bidirectional; uint16_t _motor_magnet_count; dshot_timing_us_t _dshot_timing; + + // RMT Handles & Config rmt_channel_handle_t _rmt_tx_channel = nullptr; rmt_channel_handle_t _rmt_rx_channel = nullptr; rmt_encoder_handle_t _dshot_encoder = nullptr; rmt_ticks_t _rmt_ticks; uint16_t _pulse_level = 1; // Default to high uint16_t _idle_level = 0; // Default to low + + // Timing & State uint64_t _last_transmission_time_us = 0; uint64_t _frame_timer_us = 0; uint16_t _last_throttle = 0; @@ -87,7 +94,7 @@ private: uint16_t _encoded_frame_value = 0; uint64_t _last_command_timestamp = 0; - // Telemetry related + // Telemetry std::atomic _last_erpm_atomic = 0; std::atomic _telemetry_ready_flag_atomic = false; rmt_rx_event_callbacks_t _rx_event_callbacks = { @@ -110,4 +117,4 @@ private: static bool IRAM_ATTR _on_rx_done(rmt_channel_handle_t rmt_rx_channel, const rmt_rx_done_event_data_t *edata, void *user_data); }; -#include "dshot_utils.h" // Workround for util functions \ No newline at end of file +#include "dshot_utils.h" // Include for helper functions \ No newline at end of file diff --git a/src/dshot_definitions.h b/src/dshot_definitions.h index 11a4ccc..e01cbe2 100644 --- a/src/dshot_definitions.h +++ b/src/dshot_definitions.h @@ -1,10 +1,15 @@ +/** + * @file dshot_definitions.h + * @brief Defines DShot protocol constants, data structures, and command enums for DShotRMT library + * @author Wastl Kraus + * @date 2025-10-04 + * @license MIT + */ + #pragma once -#include -#include -#include -#include -#include +#include +#include // Defines the available DShot communication speeds. enum dshot_mode_t @@ -13,8 +18,7 @@ enum dshot_mode_t DSHOT150, DSHOT300, DSHOT600, - DSHOT1200, - DSHOT_MODE_MAX + DSHOT1200 }; // Represents the 16-bit DShot data packet sent to the ESC. @@ -152,6 +156,5 @@ const dshot_timing_us_t DSHOT_TIMING_US[] = { {6.67, 5.00}, // DSHOT150 {3.33, 2.50}, // DSHOT300 {1.67, 1.25}, // DSHOT600 - {0.83, 0.67}, // DSHOT1200 - {0.00, 0.00} // DSHOT_MODE_MAX (dummy entry) + {0.83, 0.67} // DSHOT1200 }; diff --git a/src/dshot_config.cpp b/src/dshot_init.cpp similarity index 91% rename from src/dshot_config.cpp rename to src/dshot_init.cpp index d2b44c4..4f2f6c3 100644 --- a/src/dshot_config.cpp +++ b/src/dshot_init.cpp @@ -1,4 +1,12 @@ -#include "dshot_config.h" +/** + * @file dshot_init.cpp + * @brief RMT configuration and initialization functions for DShotRMT library + * @author Wastl Kraus + * @date 2025-10-04 + * @license MIT + */ + +#include "dshot_init.h" // Function to initialize the RMT TX channel dshot_result_t init_rmt_tx_channel(gpio_num_t gpio, rmt_channel_handle_t *out_channel, bool is_bidirectional) @@ -38,12 +46,10 @@ dshot_result_t init_rmt_rx_channel(gpio_num_t gpio, rmt_channel_handle_t *out_ch .mem_block_symbols = RMT_BUFFER_SYMBOLS, }; - rmt_receive_config_t rmt_rx_config = { - .signal_range_min_ns = DSHOT_PULSE_MIN_NS, - .signal_range_max_ns = DSHOT_PULSE_MAX_NS, - }; - + if (rmt_new_rx_channel(&rx_channel_config, out_channel) != DSHOT_OK) + { return {false, DSHOT_RX_INIT_FAILED}; + } if (rmt_rx_register_event_callbacks(*out_channel, rx_event_callbacks, user_data) != DSHOT_OK) { @@ -58,6 +64,12 @@ dshot_result_t init_rmt_rx_channel(gpio_num_t gpio, rmt_channel_handle_t *out_ch // Start the receiver to wait for incoming telemetry data rmt_symbol_word_t rx_symbols[GCR_BITS_PER_FRAME]; size_t rx_size_bytes = GCR_BITS_PER_FRAME * sizeof(rmt_symbol_word_t); + + rmt_receive_config_t rmt_rx_config = { + .signal_range_min_ns = DSHOT_PULSE_MIN_NS, + .signal_range_max_ns = DSHOT_PULSE_MAX_NS, + }; + if (rmt_receive(*out_channel, rx_symbols, rx_size_bytes, &rmt_rx_config) != DSHOT_OK) { return {false, DSHOT_RECEIVER_FAILED}; diff --git a/src/dshot_config.h b/src/dshot_init.h similarity index 78% rename from src/dshot_config.h rename to src/dshot_init.h index a50e2d5..7003f5e 100644 --- a/src/dshot_config.h +++ b/src/dshot_init.h @@ -1,8 +1,15 @@ +/** + * @file dshot_init.h + * @brief RMT configuration and initialization function declarations for DShotRMT library + * @author Wastl Kraus + * @date 2025-10-04 + * @license MIT + */ + #pragma once -#include -#include #include +#include #include "dshot_definitions.h" diff --git a/src/dshot_utils.h b/src/dshot_utils.h index 623afe3..31d15bf 100644 --- a/src/dshot_utils.h +++ b/src/dshot_utils.h @@ -1,7 +1,17 @@ +/** + * @file dshot_utils.h + * @brief Utility functions for DShotRMT library + * @author Wastl Kraus + * @date 2025-10-04 + * @license MIT + */ + #pragma once #include -#include "DShotRMT.h" // Include the full class definition + +// Forward declaration of the DShotRMT class to break circular dependency +class DShotRMT; // Error Messages static constexpr char NONE[] = ""; diff --git a/src/web_utilities/ota_update.h b/src/web_utilities/ota_update.h index 1d78be7..1d85cc3 100644 --- a/src/web_utilities/ota_update.h +++ b/src/web_utilities/ota_update.h @@ -2,7 +2,7 @@ * @file ota_update.h * @brief Contains the HTML, CSS, and JavaScript for the OTA (Over-The-Air) update web page. * @author Wastl Kraus - * @date 2025-09-13 + * @date 2025-10-04 * @license MIT */ diff --git a/src/web_utilities/web_content.h b/src/web_utilities/web_content.h index d5b3a0a..c41a6e2 100644 --- a/src/web_utilities/web_content.h +++ b/src/web_utilities/web_content.h @@ -2,7 +2,7 @@ * @file web_content.h * @brief Contains the HTML, CSS, and JavaScript for the main DShot control web page. * @author Wastl Kraus - * @date 2025-09-13 + * @date 2025-10-04 * @license MIT */