From 43a6fe9b6cb446974db2f3cce1f1f9b67cbe1719 Mon Sep 17 00:00:00 2001
From: Kevin Ahrendt <kevin.ahrendt@openhomefoundation.org>
Date: Tue, 3 Mar 2026 19:06:36 -0600
Subject: [PATCH] [core] add a StaticTask helper to manage task lifecycles
 (#14446)

---
 esphome/core/config.py       |  4 +++
 esphome/core/static_task.cpp | 64 ++++++++++++++++++++++++++++++++++++
 esphome/core/static_task.h   | 50 ++++++++++++++++++++++++++++
 3 files changed, 118 insertions(+)
 create mode 100644 esphome/core/static_task.cpp
 create mode 100644 esphome/core/static_task.h

diff --git a/esphome/core/config.py b/esphome/core/config.py
index 9411949bb9..4f526404fe 100644
--- a/esphome/core/config.py
+++ b/esphome/core/config.py
@@ -687,6 +687,10 @@ FILTER_SOURCE_FILES = filter_source_files_from_platform(
             PlatformFramework.ESP32_ARDUINO,
             PlatformFramework.ESP32_IDF,
         },
+        "static_task.cpp": {
+            PlatformFramework.ESP32_ARDUINO,
+            PlatformFramework.ESP32_IDF,
+        },
         "time_64.cpp": {
             PlatformFramework.ESP8266_ARDUINO,
             PlatformFramework.BK72XX_ARDUINO,
diff --git a/esphome/core/static_task.cpp b/esphome/core/static_task.cpp
new file mode 100644
index 0000000000..4cfead44c2
--- /dev/null
+++ b/esphome/core/static_task.cpp
@@ -0,0 +1,64 @@
+#include "esphome/core/static_task.h"
+
+#ifdef USE_ESP32
+
+#include "esphome/core/helpers.h"
+
+namespace esphome {
+
+bool StaticTask::create(TaskFunction_t fn, const char *name, uint32_t stack_size, void *param, UBaseType_t priority,
+                        bool use_psram) {
+  if (this->handle_ != nullptr) {
+    // Task is already created; must call destroy() first
+    return false;
+  }
+
+  if (this->stack_buffer_ != nullptr && (stack_size > this->stack_size_ || use_psram != this->use_psram_)) {
+    // Existing buffer is too small or wrong memory type; deallocate to reallocate below
+    RAMAllocator<StackType_t> allocator(this->use_psram_ ? RAMAllocator<StackType_t>::ALLOC_EXTERNAL
+                                                         : RAMAllocator<StackType_t>::ALLOC_INTERNAL);
+    allocator.deallocate(this->stack_buffer_, this->stack_size_);
+    this->stack_buffer_ = nullptr;
+  }
+
+  if (this->stack_buffer_ == nullptr) {
+    this->stack_size_ = stack_size;
+    this->use_psram_ = use_psram;
+    RAMAllocator<StackType_t> allocator(use_psram ? RAMAllocator<StackType_t>::ALLOC_EXTERNAL
+                                                  : RAMAllocator<StackType_t>::ALLOC_INTERNAL);
+    this->stack_buffer_ = allocator.allocate(stack_size);
+  }
+  if (this->stack_buffer_ == nullptr) {
+    return false;
+  }
+
+  this->handle_ = xTaskCreateStatic(fn, name, this->stack_size_, param, priority, this->stack_buffer_, &this->tcb_);
+  if (this->handle_ == nullptr) {
+    this->deallocate();
+    return false;
+  }
+  return true;
+}
+
+void StaticTask::destroy() {
+  if (this->handle_ != nullptr) {
+    TaskHandle_t handle = this->handle_;
+    this->handle_ = nullptr;
+    vTaskDelete(handle);
+  }
+}
+
+void StaticTask::deallocate() {
+  this->destroy();
+  if (this->stack_buffer_ != nullptr) {
+    RAMAllocator<StackType_t> allocator(this->use_psram_ ? RAMAllocator<StackType_t>::ALLOC_EXTERNAL
+                                                         : RAMAllocator<StackType_t>::ALLOC_INTERNAL);
+    allocator.deallocate(this->stack_buffer_, this->stack_size_);
+    this->stack_buffer_ = nullptr;
+    this->stack_size_ = 0;
+  }
+}
+
+}  // namespace esphome
+
+#endif  // USE_ESP32
diff --git a/esphome/core/static_task.h b/esphome/core/static_task.h
new file mode 100644
index 0000000000..5fd5b38f9e
--- /dev/null
+++ b/esphome/core/static_task.h
@@ -0,0 +1,50 @@
+#pragma once
+
+#ifdef USE_ESP32
+
+#include <freertos/FreeRTOS.h>
+#include <freertos/task.h>
+
+#include <cstdint>
+
+namespace esphome {
+
+/** Helper for FreeRTOS static task management.
+ * Bundles TaskHandle_t, StaticTask_t, and the stack buffer into one object with create/destroy methods.
+ */
+class StaticTask {
+ public:
+  /// @brief Check if the task has been created and not yet destroyed.
+  bool is_created() const { return this->handle_ != nullptr; }
+
+  /// @brief Get the FreeRTOS task handle.
+  TaskHandle_t get_handle() const { return this->handle_; }
+
+  /// @brief Allocate stack and create task.
+  /// @param fn         Task function
+  /// @param name       Task name (for debug)
+  /// @param stack_size Stack size in StackType_t words
+  /// @param param      Parameter passed to task function
+  /// @param priority   FreeRTOS task priority
+  /// @param use_psram  If true, allocate stack in PSRAM; otherwise internal RAM
+  /// @return true on success
+  bool create(TaskFunction_t fn, const char *name, uint32_t stack_size, void *param, UBaseType_t priority,
+              bool use_psram);
+
+  /// @brief Delete the task but keep the stack buffer allocated for reuse by a subsequent create() call.
+  void destroy();
+
+  /// @brief Delete the task (if running) and free the stack buffer.
+  void deallocate();
+
+ protected:
+  TaskHandle_t handle_{nullptr};
+  StaticTask_t tcb_;
+  StackType_t *stack_buffer_{nullptr};
+  uint32_t stack_size_{0};
+  bool use_psram_{false};
+};
+
+}  // namespace esphome
+
+#endif  // USE_ESP32