esphome 2024.12.4__py3-none-any.whl → 2025.2.0__py3-none-any.whl

esphome/config_validation.py

@@ -3,6 +3,7 @@
 from contextlib import contextmanager
 from dataclasses import dataclass
 from datetime import datetime
+from ipaddress import AddressValueError, IPv4Address, ip_address
 import logging
 import os
 import re
@@ -67,7 +68,6 @@ from esphome.const import (
 from esphome.core import (
     CORE,
     HexInt,
-    IPAddress,
     Lambda,
     TimePeriod,
     TimePeriodMicroseconds,
@@ -1130,7 +1130,7 @@ def domain(value):
     if re.match(vol.DOMAIN_REGEX, value) is not None:
         return value
     try:
-        return str(ipv4(value))
+        return str(ipaddress(value))
     except Invalid as err:
         raise Invalid(f"Invalid domain: {value}") from err
 
@@ -1160,21 +1160,29 @@ def ssid(value):
     return value
 
 
-def ipv4(value):
-    if isinstance(value, list):
-        parts = value
-    elif isinstance(value, str):
-        parts = value.split(".")
-    elif isinstance(value, IPAddress):
-        return value
-    else:
-        raise Invalid("IPv4 address must consist of either string or integer list")
-    if len(parts) != 4:
-        raise Invalid("IPv4 address must consist of four point-separated integers")
-    parts_ = list(map(int, parts))
-    if not all(0 <= x < 256 for x in parts_):
-        raise Invalid("IPv4 address parts must be in range from 0 to 255")
-    return IPAddress(*parts_)
+def ipv4address(value):
+    try:
+        address = IPv4Address(value)
+    except AddressValueError as exc:
+        raise Invalid(f"{value} is not a valid IPv4 address") from exc
+    return address
+
+
+def ipv4address_multi_broadcast(value):
+    address = ipv4address(value)
+    if not (address.is_multicast or (address == IPv4Address("255.255.255.255"))):
+        raise Invalid(
+            f"{value} is not a multicasst address nor local broadcast address"
+        )
+    return address
+
+
+def ipaddress(value):
+    try:
+        address = ip_address(value)
+    except ValueError as exc:
+        raise Invalid(f"{value} is not a valid IP address") from exc
+    return address
 
 
 def _valid_topic(value):
@@ -1660,6 +1668,12 @@ class SplitDefault(Optional):
         esp32_c3=vol.UNDEFINED,
         esp32_c3_arduino=vol.UNDEFINED,
         esp32_c3_idf=vol.UNDEFINED,
+        esp32_c6=vol.UNDEFINED,
+        esp32_c6_arduino=vol.UNDEFINED,
+        esp32_c6_idf=vol.UNDEFINED,
+        esp32_h2=vol.UNDEFINED,
+        esp32_h2_arduino=vol.UNDEFINED,
+        esp32_h2_idf=vol.UNDEFINED,
         rp2040=vol.UNDEFINED,
         bk72xx=vol.UNDEFINED,
         rtl87xx=vol.UNDEFINED,
@@ -1691,6 +1705,18 @@ class SplitDefault(Optional):
         self._esp32_c3_idf_default = vol.default_factory(
             _get_priority_default(esp32_c3_idf, esp32_c3, esp32_idf, esp32)
         )
+        self._esp32_c6_arduino_default = vol.default_factory(
+            _get_priority_default(esp32_c6_arduino, esp32_c6, esp32_arduino, esp32)
+        )
+        self._esp32_c6_idf_default = vol.default_factory(
+            _get_priority_default(esp32_c6_idf, esp32_c6, esp32_idf, esp32)
+        )
+        self._esp32_h2_arduino_default = vol.default_factory(
+            _get_priority_default(esp32_h2_arduino, esp32_h2, esp32_arduino, esp32)
+        )
+        self._esp32_h2_idf_default = vol.default_factory(
+            _get_priority_default(esp32_h2_idf, esp32_h2, esp32_idf, esp32)
+        )
         self._rp2040_default = vol.default_factory(rp2040)
         self._bk72xx_default = vol.default_factory(bk72xx)
         self._rtl87xx_default = vol.default_factory(rtl87xx)
@@ -1704,6 +1730,8 @@ class SplitDefault(Optional):
             from esphome.components.esp32 import get_esp32_variant
             from esphome.components.esp32.const import (
                 VARIANT_ESP32C3,
+                VARIANT_ESP32C6,
+                VARIANT_ESP32H2,
                 VARIANT_ESP32S2,
                 VARIANT_ESP32S3,
             )
@@ -1724,6 +1752,16 @@ class SplitDefault(Optional):
                     return self._esp32_c3_arduino_default
                 if CORE.using_esp_idf:
                     return self._esp32_c3_idf_default
+            elif variant == VARIANT_ESP32C6:
+                if CORE.using_arduino:
+                    return self._esp32_c6_arduino_default
+                if CORE.using_esp_idf:
+                    return self._esp32_c6_idf_default
+            elif variant == VARIANT_ESP32H2:
+                if CORE.using_arduino:
+                    return self._esp32_h2_arduino_default
+                if CORE.using_esp_idf:
+                    return self._esp32_h2_idf_default
             else:
                 if CORE.using_arduino:
                     return self._esp32_arduino_default

esphome/const.py

@@ -1,6 +1,6 @@
 """Constants used by esphome."""
 
-__version__ = "2024.12.4"
+__version__ = "2025.2.0"
 
 ALLOWED_NAME_CHARS = "abcdefghijklmnopqrstuvwxyz0123456789-_"
 VALID_SUBSTITUTIONS_CHARACTERS = (
@@ -15,15 +15,6 @@ PLATFORM_LIBRETINY_OLDSTYLE = "libretiny"
 PLATFORM_RP2040 = "rp2040"
 PLATFORM_RTL87XX = "rtl87xx"
 
-TARGET_PLATFORMS = [
-    PLATFORM_BK72XX,
-    PLATFORM_ESP32,
-    PLATFORM_ESP8266,
-    PLATFORM_HOST,
-    PLATFORM_LIBRETINY_OLDSTYLE,
-    PLATFORM_RP2040,
-    PLATFORM_RTL87XX,
-]
 
 SOURCE_FILE_EXTENSIONS = {".cpp", ".hpp", ".h", ".c", ".tcc", ".ino"}
 HEADER_FILE_EXTENSIONS = {".h", ".hpp", ".tcc"}
@@ -103,6 +94,7 @@ CONF_BRIGHTNESS = "brightness"
 CONF_BRIGHTNESS_LIMITS = "brightness_limits"
 CONF_BROKER = "broker"
 CONF_BSSID = "bssid"
+CONF_BUFFER_DURATION = "buffer_duration"
 CONF_BUFFER_SIZE = "buffer_size"
 CONF_BUILD_PATH = "build_path"
 CONF_BUS_VOLTAGE = "bus_voltage"
@@ -490,6 +482,7 @@ CONF_MEMORY_BLOCKS = "memory_blocks"
 CONF_MESSAGE = "message"
 CONF_METHANE = "methane"
 CONF_METHOD = "method"
+CONF_MIC_GAIN = "mic_gain"
 CONF_MICROPHONE = "microphone"
 CONF_MIN_BRIGHTNESS = "min_brightness"
 CONF_MIN_COOLING_OFF_TIME = "min_cooling_off_time"
@@ -535,9 +528,11 @@ CONF_NAME_FONT = "name_font"
 CONF_NBITS = "nbits"
 CONF_NEC = "nec"
 CONF_NETWORKS = "networks"
+CONF_NEVER = "never"
 CONF_NEW_PASSWORD = "new_password"
 CONF_NITROGEN_DIOXIDE = "nitrogen_dioxide"
 CONF_NOISE_LEVEL = "noise_level"
+CONF_NOTIFY = "notify"
 CONF_NUM_ATTEMPTS = "num_attempts"
 CONF_NUM_CHANNELS = "num_channels"
 CONF_NUM_CHIPS = "num_chips"
@@ -622,6 +617,7 @@ CONF_OTA = "ota"
 CONF_OUTDOOR_TEMPERATURE = "outdoor_temperature"
 CONF_OUTPUT = "output"
 CONF_OUTPUT_ID = "output_id"
+CONF_OUTPUT_SPEAKER = "output_speaker"
 CONF_OUTPUTS = "outputs"
 CONF_OVERSAMPLING = "oversampling"
 CONF_PACKAGES = "packages"
@@ -866,6 +862,7 @@ CONF_TARGET_TEMPERATURE_LOW = "target_temperature_low"
 CONF_TARGET_TEMPERATURE_LOW_COMMAND_TOPIC = "target_temperature_low_command_topic"
 CONF_TARGET_TEMPERATURE_LOW_STATE_TOPIC = "target_temperature_low_state_topic"
 CONF_TARGET_TEMPERATURE_STATE_TOPIC = "target_temperature_state_topic"
+CONF_TASK_STACK_IN_PSRAM = "task_stack_in_psram"
 CONF_TEMPERATURE = "temperature"
 CONF_TEMPERATURE_COMPENSATION = "temperature_compensation"
 CONF_TEMPERATURE_OFFSET = "temperature_offset"

esphome/core/__init__.py

@@ -54,16 +54,6 @@ class HexInt(int):
         return f"{sign}0x{value:X}"
 
 
-class IPAddress:
-    def __init__(self, *args):
-        if len(args) != 4:
-            raise ValueError("IPAddress must consist of 4 items")
-        self.args = args
-
-    def __str__(self):
-        return ".".join(str(x) for x in self.args)
-
-
 class MACAddress:
     def __init__(self, *parts):
         if len(parts) != 6:
@@ -592,7 +582,7 @@ class EsphomeCore:
 
     @property
     def config_dir(self):
-        return os.path.dirname(self.config_path)
+        return os.path.abspath(os.path.dirname(self.config_path))
 
     @property
     def data_dir(self):
@@ -699,7 +689,7 @@ class EsphomeCore:
         _LOGGER.debug("Adding: %s", expression)
         return expression
 
-    def add_global(self, expression):
+    def add_global(self, expression, prepend=False):
         from esphome.cpp_generator import Expression, Statement, statement
 
         if isinstance(expression, Expression):
@@ -708,7 +698,10 @@ class EsphomeCore:
             raise ValueError(
                 f"Add '{expression}' must be expression or statement, not {type(expression)}"
             )
-        self.global_statements.append(expression)
+        if prepend:
+            self.global_statements.insert(0, expression)
+        else:
+            self.global_statements.append(expression)
         _LOGGER.debug("Adding global: %s", expression)
         return expression
 

esphome/core/base_automation.h

@@ -2,6 +2,7 @@
 
 #include "esphome/core/automation.h"
 #include "esphome/core/component.h"
+#include "esphome/core/hal.h"
 #include "esphome/core/defines.h"
 #include "esphome/core/preferences.h"
 

esphome/core/config.py

@@ -1,21 +1,17 @@
 import logging
 import multiprocessing
 import os
-import re
+from pathlib import Path
 
 from esphome import automation
 import esphome.codegen as cg
 import esphome.config_validation as cv
 from esphome.const import (
-    CONF_ARDUINO_VERSION,
     CONF_AREA,
-    CONF_BOARD,
-    CONF_BOARD_FLASH_MODE,
     CONF_BUILD_PATH,
     CONF_COMMENT,
     CONF_COMPILE_PROCESS_LIMIT,
     CONF_ESPHOME,
-    CONF_FRAMEWORK,
     CONF_FRIENDLY_NAME,
     CONF_INCLUDES,
     CONF_LIBRARIES,
@@ -30,13 +26,9 @@ from esphome.const import (
     CONF_PLATFORMIO_OPTIONS,
     CONF_PRIORITY,
     CONF_PROJECT,
-    CONF_SOURCE,
     CONF_TRIGGER_ID,
-    CONF_TYPE,
     CONF_VERSION,
     KEY_CORE,
-    PLATFORM_ESP8266,
-    TARGET_PLATFORMS,
     __version__ as ESPHOME_VERSION,
 )
 from esphome.core import CORE, coroutine_with_priority
@@ -44,7 +36,6 @@ from esphome.helpers import copy_file_if_changed, get_str_env, walk_files
 
 _LOGGER = logging.getLogger(__name__)
 
-BUILD_FLASH_MODES = ["qio", "qout", "dio", "dout"]
 StartupTrigger = cg.esphome_ns.class_(
     "StartupTrigger", cg.Component, automation.Trigger.template()
 )
@@ -58,8 +49,6 @@ ProjectUpdateTrigger = cg.esphome_ns.class_(
     "ProjectUpdateTrigger", cg.Component, automation.Trigger.template(cg.std_string)
 )
 
-VERSION_REGEX = re.compile(r"^[0-9]+\.[0-9]+\.[0-9]+(?:[ab]\d+)?$")
-
 
 VALID_INCLUDE_EXTS = {".h", ".hpp", ".tcc", ".ino", ".cpp", ".c"}
 
@@ -83,6 +72,9 @@ def validate_hostname(config):
 
 
 def valid_include(value):
+    # Look for "<...>" includes
+    if value.startswith("<") and value.endswith(">"):
+        return value
     try:
         return cv.directory(value)
     except cv.Invalid:
@@ -111,7 +103,6 @@ else:
     _compile_process_limit_default = cv.UNDEFINED
 
 
-CONF_ESP8266_RESTORE_FROM_FLASH = "esp8266_restore_from_flash"
 CONFIG_SCHEMA = cv.All(
     cv.Schema(
         {
@@ -175,14 +166,9 @@ PRELOAD_CONFIG_SCHEMA = cv.Schema(
     {
         cv.Required(CONF_NAME): cv.valid_name,
         cv.Optional(CONF_BUILD_PATH): cv.string,
-        # Compat options, these were moved to target-platform specific sections
-        # but we'll keep these around for a long time because every config would
-        # be impacted
-        cv.Optional(CONF_PLATFORM): cv.one_of(*TARGET_PLATFORMS, lower=True),
-        cv.Optional(CONF_BOARD): cv.string_strict,
-        cv.Optional(CONF_ESP8266_RESTORE_FROM_FLASH): cv.valid,
-        cv.Optional(CONF_BOARD_FLASH_MODE): cv.valid,
-        cv.Optional(CONF_ARDUINO_VERSION): cv.valid,
+        cv.Optional(CONF_PLATFORM): cv.invalid(
+            "Please remove the `platform` key from the [esphome] block and use the correct platform component. This style of configuration has now been removed."
+        ),
         cv.Optional(CONF_MIN_VERSION, default=ESPHOME_VERSION): cv.All(
             cv.version_number, cv.validate_esphome_version
         ),
@@ -191,7 +177,31 @@ PRELOAD_CONFIG_SCHEMA = cv.Schema(
 )
 
 
-def preload_core_config(config, result):
+def _is_target_platform(name):
+    from esphome.loader import get_component
+
+    try:
+        if get_component(name, True).is_target_platform:
+            return True
+    except KeyError:
+        pass
+    return False
+
+
+def _list_target_platforms():
+    target_platforms = []
+    root = Path(__file__).parents[1]
+    for path in (root / "components").iterdir():
+        if not path.is_dir():
+            continue
+        if not (path / "__init__.py").is_file():
+            continue
+        if _is_target_platform(path.name):
+            target_platforms += [path.name]
+    return target_platforms
+
+
+def preload_core_config(config, result) -> str:
     with cv.prepend_path(CONF_ESPHOME):
         conf = PRELOAD_CONFIG_SCHEMA(config[CONF_ESPHOME])
 
@@ -204,63 +214,28 @@ def preload_core_config(config, result):
         conf[CONF_BUILD_PATH] = os.path.join(build_path, CORE.name)
     CORE.build_path = CORE.relative_internal_path(conf[CONF_BUILD_PATH])
 
-    has_oldstyle = CONF_PLATFORM in conf
-    newstyle_found = [key for key in TARGET_PLATFORMS if key in config]
-    oldstyle_opts = [
-        CONF_ESP8266_RESTORE_FROM_FLASH,
-        CONF_BOARD_FLASH_MODE,
-        CONF_ARDUINO_VERSION,
-        CONF_BOARD,
-    ]
+    target_platforms = []
 
-    if not has_oldstyle and not newstyle_found:
+    for domain, _ in config.items():
+        if domain.startswith("."):
+            continue
+        if _is_target_platform(domain):
+            target_platforms += [domain]
+
+    if not target_platforms:
         raise cv.Invalid(
             "Platform missing. You must include one of the available platform keys: "
-            + ", ".join(TARGET_PLATFORMS),
+            + ", ".join(_list_target_platforms()),
             [CONF_ESPHOME],
         )
-    if has_oldstyle and newstyle_found:
+    if len(target_platforms) > 1:
         raise cv.Invalid(
-            f"Please remove the `platform` key from the [esphome] block. You're already using the new style with the [{conf[CONF_PLATFORM]}] block",
-            [CONF_ESPHOME, CONF_PLATFORM],
+            f"Found multiple target platform blocks: {', '.join(target_platforms)}. Only one is allowed.",
+            [target_platforms[0]],
         )
-    if len(newstyle_found) > 1:
-        raise cv.Invalid(
-            f"Found multiple target platform blocks: {', '.join(newstyle_found)}. Only one is allowed.",
-            [newstyle_found[0]],
-        )
-    if newstyle_found:
-        # Convert to newstyle
-        for key in oldstyle_opts:
-            if key in conf:
-                raise cv.Invalid(
-                    f"Please move {key} to the [{newstyle_found[0]}] block.",
-                    [CONF_ESPHOME, key],
-                )
-
-    if has_oldstyle:
-        plat = conf.pop(CONF_PLATFORM)
-        plat_conf = {}
-        if CONF_ESP8266_RESTORE_FROM_FLASH in conf:
-            plat_conf["restore_from_flash"] = conf.pop(CONF_ESP8266_RESTORE_FROM_FLASH)
-        if CONF_BOARD_FLASH_MODE in conf:
-            plat_conf[CONF_BOARD_FLASH_MODE] = conf.pop(CONF_BOARD_FLASH_MODE)
-        if CONF_ARDUINO_VERSION in conf:
-            plat_conf[CONF_FRAMEWORK] = {}
-            if plat != PLATFORM_ESP8266:
-                plat_conf[CONF_FRAMEWORK][CONF_TYPE] = "arduino"
-
-            try:
-                if conf[CONF_ARDUINO_VERSION] not in ("recommended", "latest", "dev"):
-                    cv.Version.parse(conf[CONF_ARDUINO_VERSION])
-                plat_conf[CONF_FRAMEWORK][CONF_VERSION] = conf.pop(CONF_ARDUINO_VERSION)
-            except ValueError:
-                plat_conf[CONF_FRAMEWORK][CONF_SOURCE] = conf.pop(CONF_ARDUINO_VERSION)
-        if CONF_BOARD in conf:
-            plat_conf[CONF_BOARD] = conf.pop(CONF_BOARD)
-        # Insert generated target platform config to main config
-        config[plat] = plat_conf
+
     config[CONF_ESPHOME] = conf
+    return target_platforms[0]
 
 
 def include_file(path, basename):
@@ -390,7 +365,19 @@ async def to_code(config):
         CORE.add_job(add_arduino_global_workaround)
 
     if config[CONF_INCLUDES]:
-        CORE.add_job(add_includes, config[CONF_INCLUDES])
+        # Get the <...> includes
+        system_includes = []
+        other_includes = []
+        for include in config[CONF_INCLUDES]:
+            if include.startswith("<") and include.endswith(">"):
+                system_includes.append(include)
+            else:
+                other_includes.append(include)
+        # <...> includes should be at the start
+        for include in system_includes:
+            cg.add_global(cg.RawStatement(f"#include {include}"), prepend=True)
+        # Other includes should be at the end
+        CORE.add_job(add_includes, other_includes)
 
     if project_conf := config.get(CONF_PROJECT):
         cg.add_define("ESPHOME_PROJECT_NAME", project_conf[CONF_NAME])

esphome/core/defines.h

@@ -14,8 +14,13 @@
 #define ESPHOME_PROJECT_VERSION_30 "v2"
 #define ESPHOME_VARIANT "ESP32"
 
+// logger
+#define ESPHOME_LOG_LEVEL ESPHOME_LOG_LEVEL_VERY_VERBOSE
+
 // Feature flags
 #define USE_ALARM_CONTROL_PANEL
+#define USE_AUDIO_FLAC_SUPPORT
+#define USE_AUDIO_MP3_SUPPORT
 #define USE_API
 #define USE_API_NOISE
 #define USE_API_PLAINTEXT
@@ -49,6 +54,7 @@
 #define USE_LVGL_IMAGE
 #define USE_LVGL_KEY_LISTENER
 #define USE_LVGL_KEYBOARD
+#define USE_LVGL_METER
 #define USE_LVGL_ROLLER
 #define USE_LVGL_ROTARY_ENCODER
 #define USE_LVGL_TOUCHSCREEN
@@ -59,7 +65,9 @@
 #define USE_NETWORK
 #define USE_NEXTION_TFT_UPLOAD
 #define USE_NUMBER
+#define USE_ONLINE_IMAGE_BMP_SUPPORT
 #define USE_ONLINE_IMAGE_PNG_SUPPORT
+#define USE_ONLINE_IMAGE_JPEG_SUPPORT
 #define USE_OTA
 #define USE_OTA_PASSWORD
 #define USE_OTA_STATE_CALLBACK
@@ -119,7 +127,7 @@
 #endif
 
 #ifdef USE_ESP_IDF
-#define USE_ESP_IDF_VERSION_CODE VERSION_CODE(4, 4, 2)
+#define USE_ESP_IDF_VERSION_CODE VERSION_CODE(5, 1, 5)
 #endif
 
 #if defined(USE_ESP32_VARIANT_ESP32S2)

esphome/core/gpio.h

@@ -53,6 +53,13 @@ class GPIOPin {
 
   virtual void pin_mode(gpio::Flags flags) = 0;
 
+  /**
+   * @brief Retrieve GPIO pin flags.
+   *
+   * @return The GPIO flags describing the pin mode and properties.
+   */
+  virtual gpio::Flags get_flags() const = 0;
+
   virtual bool digital_read() = 0;
 
   virtual void digital_write(bool value) = 0;

esphome/core/helpers.cpp

@@ -45,7 +45,9 @@
 #endif
 #ifdef USE_ESP32
 #include "esp32/rom/crc.h"
-
+#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(5, 3, 2)
+#include "esp_mac.h"
+#endif
 #include "esp_efuse.h"
 #include "esp_efuse_table.h"
 #endif
@@ -126,19 +128,21 @@ uint16_t crc16(const uint8_t *data, uint16_t len, uint16_t crc, uint16_t reverse
     }
   } else
 #endif
-      if (reverse_poly == 0xa001) {
-    while (len--) {
-      uint8_t combo = crc ^ (uint8_t) *data++;
-      crc = (crc >> 8) ^ CRC16_A001_LE_LUT_L[combo & 0x0F] ^ CRC16_A001_LE_LUT_H[combo >> 4];
-    }
-  } else {
-    while (len--) {
-      crc ^= *data++;
-      for (uint8_t i = 0; i < 8; i++) {
-        if (crc & 0x0001) {
-          crc = (crc >> 1) ^ reverse_poly;
-        } else {
-          crc >>= 1;
+  {
+    if (reverse_poly == 0xa001) {
+      while (len--) {
+        uint8_t combo = crc ^ (uint8_t) *data++;
+        crc = (crc >> 8) ^ CRC16_A001_LE_LUT_L[combo & 0x0F] ^ CRC16_A001_LE_LUT_H[combo >> 4];
+      }
+    } else {
+      while (len--) {
+        crc ^= *data++;
+        for (uint8_t i = 0; i < 8; i++) {
+          if (crc & 0x0001) {
+            crc = (crc >> 1) ^ reverse_poly;
+          } else {
+            crc >>= 1;
+          }
         }
       }
     }
@@ -259,7 +263,7 @@ bool random_bytes(uint8_t *data, size_t len) {
 bool str_equals_case_insensitive(const std::string &a, const std::string &b) {
   return strcasecmp(a.c_str(), b.c_str()) == 0;
 }
-#if ESP_IDF_VERSION_MAJOR >= 5
+#if __cplusplus >= 202002L
 bool str_startswith(const std::string &str, const std::string &start) { return str.starts_with(start); }
 bool str_endswith(const std::string &str, const std::string &end) { return str.ends_with(end); }
 #else

esphome/core/helpers.h

@@ -11,6 +11,14 @@
 
 #include "esphome/core/optional.h"
 
+#ifdef USE_ESP8266
+#include <Esp.h>
+#endif
+
+#ifdef USE_RP2040
+#include <Arduino.h>
+#endif
+
 #ifdef USE_ESP32
 #include <esp_heap_caps.h>
 #endif
@@ -155,7 +163,7 @@ template<typename T, typename U> T remap(U value, U min, U max, T min_out, T max
   return (value - min) * (max_out - min_out) / (max - min) + min_out;
 }
 
-/// Calculate a CRC-8 checksum of \p data with size \p len.
+/// Calculate a CRC-8 checksum of \p data with size \p len using the CRC-8-Dallas/Maxim polynomial.
 uint8_t crc8(const uint8_t *data, uint8_t len);
 
 /// Calculate a CRC-16 checksum of \p data with size \p len.
@@ -684,20 +692,23 @@ template<class T> class RAMAllocator {
   };
 
   RAMAllocator() = default;
-  RAMAllocator(uint8_t flags) : flags_{flags} {}
+  RAMAllocator(uint8_t flags) {
+    // default is both external and internal
+    flags &= ALLOC_INTERNAL | ALLOC_EXTERNAL;
+    if (flags != 0)
+      this->flags_ = flags;
+  }
   template<class U> constexpr RAMAllocator(const RAMAllocator<U> &other) : flags_{other.flags_} {}
 
   T *allocate(size_t n) {
     size_t size = n * sizeof(T);
     T *ptr = nullptr;
 #ifdef USE_ESP32
-    // External allocation by default or if explicitely requested
-    if ((this->flags_ & Flags::ALLOC_EXTERNAL) || ((this->flags_ & Flags::ALLOC_INTERNAL) == 0)) {
+    if (this->flags_ & Flags::ALLOC_EXTERNAL) {
       ptr = static_cast<T *>(heap_caps_malloc(size, MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT));
     }
-    // Fallback to internal allocation if explicitely requested or no flag is specified
-    if (ptr == nullptr && ((this->flags_ & Flags::ALLOC_INTERNAL) || (this->flags_ & Flags::ALLOC_EXTERNAL) == 0)) {
-      ptr = static_cast<T *>(malloc(size));  // NOLINT(cppcoreguidelines-owning-memory,cppcoreguidelines-no-malloc)
+    if (ptr == nullptr && this->flags_ & Flags::ALLOC_INTERNAL) {
+      ptr = static_cast<T *>(heap_caps_malloc(size, MALLOC_CAP_INTERNAL | MALLOC_CAP_8BIT));
     }
 #else
     // Ignore ALLOC_EXTERNAL/ALLOC_INTERNAL flags if external allocation is not supported
@@ -710,8 +721,46 @@ template<class T> class RAMAllocator {
     free(p);  // NOLINT(cppcoreguidelines-owning-memory,cppcoreguidelines-no-malloc)
   }
 
+  /**
+   * Return the total heap space available via this allocator
+   */
+  size_t get_free_heap_size() const {
+#ifdef USE_ESP8266
+    return ESP.getFreeHeap();  // NOLINT(readability-static-accessed-through-instance)
+#elif defined(USE_ESP32)
+    auto max_internal =
+        this->flags_ & ALLOC_INTERNAL ? heap_caps_get_free_size(MALLOC_CAP_8BIT | MALLOC_CAP_INTERNAL) : 0;
+    auto max_external =
+        this->flags_ & ALLOC_EXTERNAL ? heap_caps_get_free_size(MALLOC_CAP_8BIT | MALLOC_CAP_SPIRAM) : 0;
+    return max_internal + max_external;
+#elif defined(USE_RP2040)
+    return ::rp2040.getFreeHeap();
+#elif defined(USE_LIBRETINY)
+    return lt_heap_get_free();
+#else
+    return 100000;
+#endif
+  }
+
+  /**
+   * Return the maximum size block this allocator could allocate. This may be an approximation on some platforms
+   */
+  size_t get_max_free_block_size() const {
+#ifdef USE_ESP8266
+    return ESP.getMaxFreeBlockSize();  // NOLINT(readability-static-accessed-through-instance)
+#elif defined(USE_ESP32)
+    auto max_internal =
+        this->flags_ & ALLOC_INTERNAL ? heap_caps_get_largest_free_block(MALLOC_CAP_8BIT | MALLOC_CAP_INTERNAL) : 0;
+    auto max_external =
+        this->flags_ & ALLOC_EXTERNAL ? heap_caps_get_largest_free_block(MALLOC_CAP_8BIT | MALLOC_CAP_SPIRAM) : 0;
+    return std::max(max_internal, max_external);
+#else
+    return this->get_free_heap_size();
+#endif
+  }
+
  private:
-  uint8_t flags_{Flags::ALLOW_FAILURE};
+  uint8_t flags_{ALLOC_INTERNAL | ALLOC_EXTERNAL};
 };
 
 template<class T> using ExternalRAMAllocator = RAMAllocator<T>;