esphome 2025.8.4__py3-none-any.whl → 2025.9.0__py3-none-any.whl

esphome/components/bl0940/number/__init__.py

@@ -0,0 +1,94 @@
+import esphome.codegen as cg
+from esphome.components import number
+import esphome.config_validation as cv
+from esphome.const import (
+    CONF_MAX_VALUE,
+    CONF_MIN_VALUE,
+    CONF_MODE,
+    CONF_RESTORE_VALUE,
+    CONF_STEP,
+    ENTITY_CATEGORY_CONFIG,
+    UNIT_PERCENT,
+)
+
+from .. import CONF_BL0940_ID, bl0940_ns
+from ..sensor import BL0940
+
+# Define calibration types
+CONF_CURRENT_CALIBRATION = "current_calibration"
+CONF_VOLTAGE_CALIBRATION = "voltage_calibration"
+CONF_POWER_CALIBRATION = "power_calibration"
+CONF_ENERGY_CALIBRATION = "energy_calibration"
+
+BL0940Number = bl0940_ns.class_("BL0940Number")
+
+CalibrationNumber = bl0940_ns.class_(
+    "CalibrationNumber", number.Number, cg.PollingComponent
+)
+
+
+def validate_min_max(config):
+    if config[CONF_MAX_VALUE] <= config[CONF_MIN_VALUE]:
+        raise cv.Invalid("max_value must be greater than min_value")
+    return config
+
+
+CALIBRATION_SCHEMA = cv.All(
+    number.number_schema(
+        CalibrationNumber,
+        entity_category=ENTITY_CATEGORY_CONFIG,
+        unit_of_measurement=UNIT_PERCENT,
+    )
+    .extend(
+        {
+            cv.Optional(CONF_MODE, default="BOX"): cv.enum(number.NUMBER_MODES),
+            cv.Optional(CONF_MAX_VALUE, default=10): cv.All(
+                cv.float_, cv.Range(max=50)
+            ),
+            cv.Optional(CONF_MIN_VALUE, default=-10): cv.All(
+                cv.float_, cv.Range(min=-50)
+            ),
+            cv.Optional(CONF_STEP, default=0.1): cv.positive_float,
+            cv.Optional(CONF_RESTORE_VALUE): cv.boolean,
+        }
+    )
+    .extend(cv.COMPONENT_SCHEMA),
+    validate_min_max,
+)
+
+# Configuration schema for BL0940 numbers
+CONFIG_SCHEMA = cv.Schema(
+    {
+        cv.GenerateID(): cv.declare_id(BL0940Number),
+        cv.GenerateID(CONF_BL0940_ID): cv.use_id(BL0940),
+        cv.Optional(CONF_CURRENT_CALIBRATION): CALIBRATION_SCHEMA,
+        cv.Optional(CONF_VOLTAGE_CALIBRATION): CALIBRATION_SCHEMA,
+        cv.Optional(CONF_POWER_CALIBRATION): CALIBRATION_SCHEMA,
+        cv.Optional(CONF_ENERGY_CALIBRATION): CALIBRATION_SCHEMA,
+    }
+)
+
+
+async def to_code(config):
+    # Get the BL0940 component instance
+    bl0940 = await cg.get_variable(config[CONF_BL0940_ID])
+
+    # Process all calibration types
+    for cal_type, setter_method in [
+        (CONF_CURRENT_CALIBRATION, "set_current_calibration_number"),
+        (CONF_VOLTAGE_CALIBRATION, "set_voltage_calibration_number"),
+        (CONF_POWER_CALIBRATION, "set_power_calibration_number"),
+        (CONF_ENERGY_CALIBRATION, "set_energy_calibration_number"),
+    ]:
+        if conf := config.get(cal_type):
+            var = await number.new_number(
+                conf,
+                min_value=conf.get(CONF_MIN_VALUE),
+                max_value=conf.get(CONF_MAX_VALUE),
+                step=conf.get(CONF_STEP),
+            )
+            await cg.register_component(var, conf)
+
+            if restore_value := config.get(CONF_RESTORE_VALUE):
+                cg.add(var.set_restore_value(restore_value))
+            cg.add(getattr(bl0940, setter_method)(var))

esphome/components/bl0940/number/calibration_number.cpp

@@ -0,0 +1,29 @@
+#include "calibration_number.h"
+#include "esphome/core/log.h"
+
+namespace esphome {
+namespace bl0940 {
+
+static const char *const TAG = "bl0940.number";
+
+void CalibrationNumber::setup() {
+  float value = 0.0f;
+  if (this->restore_value_) {
+    this->pref_ = global_preferences->make_preference<float>(this->get_object_id_hash());
+    if (!this->pref_.load(&value)) {
+      value = 0.0f;
+    }
+  }
+  this->publish_state(value);
+}
+
+void CalibrationNumber::control(float value) {
+  this->publish_state(value);
+  if (this->restore_value_)
+    this->pref_.save(&value);
+}
+
+void CalibrationNumber::dump_config() { LOG_NUMBER("", "Calibration Number", this); }
+
+}  // namespace bl0940
+}  // namespace esphome

esphome/components/bl0940/number/calibration_number.h

@@ -0,0 +1,26 @@
+#pragma once
+
+#include "esphome/components/number/number.h"
+#include "esphome/core/component.h"
+#include "esphome/core/preferences.h"
+
+namespace esphome {
+namespace bl0940 {
+
+class CalibrationNumber : public number::Number, public Component {
+ public:
+  void setup() override;
+  void dump_config() override;
+  float get_setup_priority() const override { return setup_priority::HARDWARE; }
+
+  void set_restore_value(bool restore_value) { this->restore_value_ = restore_value; }
+
+ protected:
+  void control(float value) override;
+  bool restore_value_{true};
+
+  ESPPreferenceObject pref_;
+};
+
+}  // namespace bl0940
+}  // namespace esphome

esphome/components/bl0940/sensor.py

@@ -8,6 +8,7 @@ from esphome.const import (
     CONF_ID,
     CONF_INTERNAL_TEMPERATURE,
     CONF_POWER,
+    CONF_REFERENCE_VOLTAGE,
     CONF_VOLTAGE,
     DEVICE_CLASS_CURRENT,
     DEVICE_CLASS_ENERGY,
@@ -23,12 +24,133 @@ from esphome.const import (
     UNIT_WATT,
 )
 
-DEPENDENCIES = ["uart"]
+from . import bl0940_ns
 
+DEPENDENCIES = ["uart"]
 
-bl0940_ns = cg.esphome_ns.namespace("bl0940")
 BL0940 = bl0940_ns.class_("BL0940", cg.PollingComponent, uart.UARTDevice)
 
+CONF_LEGACY_MODE = "legacy_mode"
+
+CONF_READ_COMMAND = "read_command"
+CONF_WRITE_COMMAND = "write_command"
+
+CONF_RESISTOR_SHUNT = "resistor_shunt"
+CONF_RESISTOR_ONE = "resistor_one"
+CONF_RESISTOR_TWO = "resistor_two"
+
+CONF_CURRENT_REFERENCE = "current_reference"
+CONF_ENERGY_REFERENCE = "energy_reference"
+CONF_POWER_REFERENCE = "power_reference"
+CONF_VOLTAGE_REFERENCE = "voltage_reference"
+
+DEFAULT_BL0940_READ_COMMAND = 0x58
+DEFAULT_BL0940_WRITE_COMMAND = 0xA1
+
+# Values according to BL0940 application note:
+# https://www.belling.com.cn/media/file_object/bel_product/BL0940/guide/BL0940_APPNote_TSSOP14_V1.04_EN.pdf
+DEFAULT_BL0940_VREF = 1.218  # Vref = 1.218
+DEFAULT_BL0940_RL = 1  # RL = 1 mΩ
+DEFAULT_BL0940_R1 = 0.51  # R1 = 0.51 kΩ
+DEFAULT_BL0940_R2 = 1950  # R2 = 5 x 390 kΩ -> 1950 kΩ
+
+# ----------------------------------------------------
+# values from initial implementation
+DEFAULT_BL0940_LEGACY_READ_COMMAND = 0x50
+DEFAULT_BL0940_LEGACY_WRITE_COMMAND = 0xA0
+
+DEFAULT_BL0940_LEGACY_UREF = 33000
+DEFAULT_BL0940_LEGACY_IREF = 275000
+DEFAULT_BL0940_LEGACY_PREF = 1430
+# Measured to 297J  per click according to power consumption of 5 minutes
+# Converted to kWh (3.6MJ per kwH). Used to be 256 * 1638.4
+DEFAULT_BL0940_LEGACY_EREF = 3.6e6 / 297
+# ----------------------------------------------------
+
+
+# methods to calculate voltage and current reference values
+def calculate_voltage_reference(vref, r_one, r_two):
+    # formula: 79931 / Vref * (R1 * 1000) / (R1 + R2)
+    return 79931 / vref * (r_one * 1000) / (r_one + r_two)
+
+
+def calculate_current_reference(vref, r_shunt):
+    # formula: 324004 * RL / Vref
+    return 324004 * r_shunt / vref
+
+
+def calculate_power_reference(voltage_reference, current_reference):
+    # calculate power reference based on voltage and current reference
+    return voltage_reference * current_reference * 4046 / 324004 / 79931
+
+
+def calculate_energy_reference(power_reference):
+    # formula: power_reference * 3600000 / (1638.4 * 256)
+    return power_reference * 3600000 / (1638.4 * 256)
+
+
+def validate_legacy_mode(config):
+    # Only allow schematic calibration options if legacy_mode is False
+    if config.get(CONF_LEGACY_MODE, True):
+        forbidden = [
+            CONF_REFERENCE_VOLTAGE,
+            CONF_RESISTOR_SHUNT,
+            CONF_RESISTOR_ONE,
+            CONF_RESISTOR_TWO,
+        ]
+        for key in forbidden:
+            if key in config:
+                raise cv.Invalid(
+                    f"Option '{key}' is only allowed when legacy_mode: false"
+                )
+    return config
+
+
+def set_command_defaults(config):
+    # Set defaults for read_command and write_command based on legacy_mode
+    legacy = config.get(CONF_LEGACY_MODE, True)
+    if legacy:
+        config.setdefault(CONF_READ_COMMAND, DEFAULT_BL0940_LEGACY_READ_COMMAND)
+        config.setdefault(CONF_WRITE_COMMAND, DEFAULT_BL0940_LEGACY_WRITE_COMMAND)
+    else:
+        config.setdefault(CONF_READ_COMMAND, DEFAULT_BL0940_READ_COMMAND)
+        config.setdefault(CONF_WRITE_COMMAND, DEFAULT_BL0940_WRITE_COMMAND)
+    return config
+
+
+def set_reference_values(config):
+    # Set default reference values based on legacy_mode
+    if config.get(CONF_LEGACY_MODE, True):
+        config.setdefault(CONF_VOLTAGE_REFERENCE, DEFAULT_BL0940_LEGACY_UREF)
+        config.setdefault(CONF_CURRENT_REFERENCE, DEFAULT_BL0940_LEGACY_IREF)
+        config.setdefault(CONF_POWER_REFERENCE, DEFAULT_BL0940_LEGACY_PREF)
+        config.setdefault(CONF_ENERGY_REFERENCE, DEFAULT_BL0940_LEGACY_PREF)
+    else:
+        vref = config.get(CONF_VOLTAGE_REFERENCE, DEFAULT_BL0940_VREF)
+        r_one = config.get(CONF_RESISTOR_ONE, DEFAULT_BL0940_R1)
+        r_two = config.get(CONF_RESISTOR_TWO, DEFAULT_BL0940_R2)
+        r_shunt = config.get(CONF_RESISTOR_SHUNT, DEFAULT_BL0940_RL)
+
+        config.setdefault(
+            CONF_VOLTAGE_REFERENCE, calculate_voltage_reference(vref, r_one, r_two)
+        )
+        config.setdefault(
+            CONF_CURRENT_REFERENCE, calculate_current_reference(vref, r_shunt)
+        )
+        config.setdefault(
+            CONF_POWER_REFERENCE,
+            calculate_power_reference(
+                config.get(CONF_VOLTAGE_REFERENCE), config.get(CONF_CURRENT_REFERENCE)
+            ),
+        )
+        config.setdefault(
+            CONF_ENERGY_REFERENCE,
+            calculate_energy_reference(config.get(CONF_POWER_REFERENCE)),
+        )
+
+    return config
+
+
 CONFIG_SCHEMA = (
     cv.Schema(
         {
@@ -69,10 +191,24 @@ CONFIG_SCHEMA = (
                 device_class=DEVICE_CLASS_TEMPERATURE,
                 state_class=STATE_CLASS_MEASUREMENT,
             ),
+            cv.Optional(CONF_LEGACY_MODE, default=True): cv.boolean,
+            cv.Optional(CONF_READ_COMMAND): cv.hex_uint8_t,
+            cv.Optional(CONF_WRITE_COMMAND): cv.hex_uint8_t,
+            cv.Optional(CONF_REFERENCE_VOLTAGE): cv.float_,
+            cv.Optional(CONF_RESISTOR_SHUNT): cv.float_,
+            cv.Optional(CONF_RESISTOR_ONE): cv.float_,
+            cv.Optional(CONF_RESISTOR_TWO): cv.float_,
+            cv.Optional(CONF_CURRENT_REFERENCE): cv.float_,
+            cv.Optional(CONF_ENERGY_REFERENCE): cv.float_,
+            cv.Optional(CONF_POWER_REFERENCE): cv.float_,
+            cv.Optional(CONF_VOLTAGE_REFERENCE): cv.float_,
         }
     )
     .extend(cv.polling_component_schema("60s"))
     .extend(uart.UART_DEVICE_SCHEMA)
+    .add_extra(validate_legacy_mode)
+    .add_extra(set_command_defaults)
+    .add_extra(set_reference_values)
 )
 
 
@@ -99,3 +235,16 @@ async def to_code(config):
     if external_temperature_config := config.get(CONF_EXTERNAL_TEMPERATURE):
         sens = await sensor.new_sensor(external_temperature_config)
         cg.add(var.set_external_temperature_sensor(sens))
+
+    # enable legacy mode
+    cg.add(var.set_legacy_mode(config.get(CONF_LEGACY_MODE)))
+
+    # Set bl0940 commands after validator has determined which defaults to use if not set
+    cg.add(var.set_read_command(config.get(CONF_READ_COMMAND)))
+    cg.add(var.set_write_command(config.get(CONF_WRITE_COMMAND)))
+
+    # Set reference values after validator has set the values either from defaults or calculated
+    cg.add(var.set_current_reference(config.get(CONF_CURRENT_REFERENCE)))
+    cg.add(var.set_voltage_reference(config.get(CONF_VOLTAGE_REFERENCE)))
+    cg.add(var.set_power_reference(config.get(CONF_POWER_REFERENCE)))
+    cg.add(var.set_energy_reference(config.get(CONF_ENERGY_REFERENCE)))

esphome/components/bl0942/bl0942.cpp

@@ -149,7 +149,7 @@ void BL0942::setup() {
   this->write_reg_(BL0942_REG_USR_WRPROT, 0);
 
   if (this->read_reg_(BL0942_REG_MODE) != mode)
-    this->status_set_warning("BL0942 setup failed!");
+    this->status_set_warning(LOG_STR("BL0942 setup failed!"));
 
   this->flush();
 }

esphome/components/ble_client/output/__init__.py

@@ -27,7 +27,7 @@ CONFIG_SCHEMA = cv.All(
 )
 
 
-def to_code(config):
+async def to_code(config):
     var = cg.new_Pvariable(config[CONF_ID])
     if len(config[CONF_SERVICE_UUID]) == len(esp32_ble_tracker.bt_uuid16_format):
         cg.add(
@@ -63,6 +63,6 @@ def to_code(config):
         )
         cg.add(var.set_char_uuid128(uuid128))
     cg.add(var.set_require_response(config[CONF_REQUIRE_RESPONSE]))
-    yield output.register_output(var, config)
-    yield ble_client.register_ble_node(var, config)
-    yield cg.register_component(var, config)
+    await output.register_output(var, config)
+    await ble_client.register_ble_node(var, config)
+    await cg.register_component(var, config)

esphome/components/bluetooth_proxy/__init__.py

@@ -80,7 +80,7 @@ CONFIG_SCHEMA = cv.All(
         cv.Schema(
             {
                 cv.GenerateID(): cv.declare_id(BluetoothProxy),
-                cv.Optional(CONF_ACTIVE, default=False): cv.boolean,
+                cv.Optional(CONF_ACTIVE, default=True): cv.boolean,
                 cv.SplitDefault(CONF_CACHE_SERVICES, esp32_idf=True): cv.All(
                     cv.only_with_esp_idf, cv.boolean
                 ),

esphome/components/bluetooth_proxy/bluetooth_connection.h

@@ -8,7 +8,7 @@ namespace esphome::bluetooth_proxy {
 
 class BluetoothProxy;
 
-class BluetoothConnection : public esp32_ble_client::BLEClientBase {
+class BluetoothConnection final : public esp32_ble_client::BLEClientBase {
  public:
   void dump_config() override;
   void loop() override;

esphome/components/bluetooth_proxy/bluetooth_proxy.cpp

@@ -24,6 +24,9 @@ void BluetoothProxy::setup() {
   this->connections_free_response_.limit = BLUETOOTH_PROXY_MAX_CONNECTIONS;
   this->connections_free_response_.free = BLUETOOTH_PROXY_MAX_CONNECTIONS;
 
+  // Capture the configured scan mode from YAML before any API changes
+  this->configured_scan_active_ = this->parent_->get_scan_active();
+
   this->parent_->add_scanner_state_callback([this](esp32_ble_tracker::ScannerState state) {
     if (this->api_connection_ != nullptr) {
       this->send_bluetooth_scanner_state_(state);
@@ -36,6 +39,9 @@ void BluetoothProxy::send_bluetooth_scanner_state_(esp32_ble_tracker::ScannerSta
   resp.state = static_cast<api::enums::BluetoothScannerState>(state);
   resp.mode = this->parent_->get_scan_active() ? api::enums::BluetoothScannerMode::BLUETOOTH_SCANNER_MODE_ACTIVE
                                                : api::enums::BluetoothScannerMode::BLUETOOTH_SCANNER_MODE_PASSIVE;
+  resp.configured_mode = this->configured_scan_active_
+                             ? api::enums::BluetoothScannerMode::BLUETOOTH_SCANNER_MODE_ACTIVE
+                             : api::enums::BluetoothScannerMode::BLUETOOTH_SCANNER_MODE_PASSIVE;
   this->api_connection_->send_message(resp, api::BluetoothScannerStateResponse::MESSAGE_TYPE);
 }
 
@@ -183,6 +189,12 @@ void BluetoothProxy::bluetooth_device_request(const api::BluetoothDeviceRequest
         this->send_device_connection(msg.address, false);
         return;
       }
+      if (!msg.has_address_type) {
+        ESP_LOGE(TAG, "[%d] [%s] Missing address type in connect request", connection->get_connection_index(),
+                 connection->address_str().c_str());
+        this->send_device_connection(msg.address, false);
+        return;
+      }
       if (connection->state() == espbt::ClientState::CONNECTED ||
           connection->state() == espbt::ClientState::ESTABLISHED) {
         this->log_connection_request_ignored_(connection, connection->state());
@@ -209,13 +221,9 @@ void BluetoothProxy::bluetooth_device_request(const api::BluetoothDeviceRequest
         connection->set_connection_type(espbt::ConnectionType::V3_WITHOUT_CACHE);
         this->log_connection_info_(connection, "v3 without cache");
       }
-      if (msg.has_address_type) {
-        uint64_to_bd_addr(msg.address, connection->remote_bda_);
-        connection->set_remote_addr_type(static_cast<esp_ble_addr_type_t>(msg.address_type));
-        connection->set_state(espbt::ClientState::DISCOVERED);
-      } else {
-        connection->set_state(espbt::ClientState::SEARCHING);
-      }
+      uint64_to_bd_addr(msg.address, connection->remote_bda_);
+      connection->set_remote_addr_type(static_cast<esp_ble_addr_type_t>(msg.address_type));
+      connection->set_state(espbt::ClientState::DISCOVERED);
       this->send_connections_free();
       break;
     }

esphome/components/bluetooth_proxy/bluetooth_proxy.h

@@ -50,7 +50,7 @@ enum BluetoothProxySubscriptionFlag : uint32_t {
   SUBSCRIPTION_RAW_ADVERTISEMENTS = 1 << 0,
 };
 
-class BluetoothProxy : public esp32_ble_tracker::ESPBTDeviceListener, public Component {
+class BluetoothProxy final : public esp32_ble_tracker::ESPBTDeviceListener, public Component {
   friend class BluetoothConnection;  // Allow connection to update connections_free_response_
  public:
   BluetoothProxy();
@@ -130,7 +130,9 @@ class BluetoothProxy : public esp32_ble_tracker::ESPBTDeviceListener, public Com
 
   std::string get_bluetooth_mac_address_pretty() {
     const uint8_t *mac = esp_bt_dev_get_address();
-    return str_snprintf("%02X:%02X:%02X:%02X:%02X:%02X", 17, mac[0], mac[1], mac[2], mac[3], mac[4], mac[5]);
+    char buf[18];
+    format_mac_addr_upper(mac, buf);
+    return std::string(buf);
   }
 
  protected:
@@ -161,7 +163,8 @@ class BluetoothProxy : public esp32_ble_tracker::ESPBTDeviceListener, public Com
   // Group 4: 1-byte types grouped together
   bool active_;
   uint8_t connection_count_{0};
-  // 2 bytes used, 2 bytes padding
+  bool configured_scan_active_{false};  // Configured scan mode from YAML
+  // 3 bytes used, 1 byte padding
 };
 
 extern BluetoothProxy *global_bluetooth_proxy;  // NOLINT(cppcoreguidelines-avoid-non-const-global-variables)

esphome/components/button/__init__.py

@@ -17,7 +17,7 @@ from esphome.const import (
     DEVICE_CLASS_RESTART,
     DEVICE_CLASS_UPDATE,
 )
-from esphome.core import CORE, coroutine_with_priority
+from esphome.core import CORE, CoroPriority, coroutine_with_priority
 from esphome.core.entity_helpers import entity_duplicate_validator, setup_entity
 from esphome.cpp_generator import MockObjClass
 
@@ -134,6 +134,6 @@ async def button_press_to_code(config, action_id, template_arg, args):
     return cg.new_Pvariable(action_id, template_arg, paren)
 
 
-@coroutine_with_priority(100.0)
+@coroutine_with_priority(CoroPriority.CORE)
 async def to_code(config):
     cg.add_global(button_ns.using)

esphome/components/button/button.cpp

@@ -6,6 +6,19 @@ namespace button {
 
 static const char *const TAG = "button";
 
+// Function implementation of LOG_BUTTON macro to reduce code size
+void log_button(const char *tag, const char *prefix, const char *type, Button *obj) {
+  if (obj == nullptr) {
+    return;
+  }
+
+  ESP_LOGCONFIG(tag, "%s%s '%s'", prefix, type, obj->get_name().c_str());
+
+  if (!obj->get_icon_ref().empty()) {
+    ESP_LOGCONFIG(tag, "%s  Icon: '%s'", prefix, obj->get_icon_ref().c_str());
+  }
+}
+
 void Button::press() {
   ESP_LOGD(TAG, "'%s' Pressed.", this->get_name().c_str());
   this->press_action();

esphome/components/button/button.h

@@ -7,13 +7,10 @@
 namespace esphome {
 namespace button {
 
-#define LOG_BUTTON(prefix, type, obj) \
-  if ((obj) != nullptr) { \
-    ESP_LOGCONFIG(TAG, "%s%s '%s'", prefix, LOG_STR_LITERAL(type), (obj)->get_name().c_str()); \
-    if (!(obj)->get_icon().empty()) { \
-      ESP_LOGCONFIG(TAG, "%s  Icon: '%s'", prefix, (obj)->get_icon().c_str()); \
-    } \
-  }
+class Button;
+void log_button(const char *tag, const char *prefix, const char *type, Button *obj);
+
+#define LOG_BUTTON(prefix, type, obj) log_button(TAG, prefix, LOG_STR_LITERAL(type), obj)
 
 #define SUB_BUTTON(name) \
  protected: \

esphome/components/camera/buffer.h

@@ -0,0 +1,18 @@
+#pragma once
+
+#include <cinttypes>
+#include <cstddef>
+
+namespace esphome::camera {
+
+/// Interface for a generic buffer that stores image data.
+class Buffer {
+ public:
+  /// Returns a pointer to the buffer's data.
+  virtual uint8_t *get_data_buffer() = 0;
+  /// Returns the length of the buffer in bytes.
+  virtual size_t get_data_length() = 0;
+  virtual ~Buffer() = default;
+};
+
+}  // namespace esphome::camera

esphome/components/camera/buffer_impl.cpp

@@ -0,0 +1,20 @@
+#include "buffer_impl.h"
+
+namespace esphome::camera {
+
+BufferImpl::BufferImpl(size_t size) {
+  this->data_ = this->allocator_.allocate(size);
+  this->size_ = size;
+}
+
+BufferImpl::BufferImpl(CameraImageSpec *spec) {
+  this->data_ = this->allocator_.allocate(spec->bytes_per_image());
+  this->size_ = spec->bytes_per_image();
+}
+
+BufferImpl::~BufferImpl() {
+  if (this->data_ != nullptr)
+    this->allocator_.deallocate(this->data_, this->size_);
+}
+
+}  // namespace esphome::camera

esphome/components/camera/buffer_impl.h

@@ -0,0 +1,26 @@
+#pragma once
+
+#include "buffer.h"
+#include "camera.h"
+
+namespace esphome::camera {
+
+/// Default implementation of Buffer Interface.
+/// Uses a RAMAllocator for memory reservation.
+class BufferImpl : public Buffer {
+ public:
+  explicit BufferImpl(size_t size);
+  explicit BufferImpl(CameraImageSpec *spec);
+  // -------- Buffer --------
+  uint8_t *get_data_buffer() override { return data_; }
+  size_t get_data_length() override { return size_; }
+  // ------------------------
+  ~BufferImpl() override;
+
+ protected:
+  RAMAllocator<uint8_t> allocator_;
+  size_t size_{};
+  uint8_t *data_{};
+};
+
+}  // namespace esphome::camera

esphome/components/camera/camera.h

@@ -15,6 +15,26 @@ namespace camera {
  */
 enum CameraRequester : uint8_t { IDLE, API_REQUESTER, WEB_REQUESTER };
 
+/// Enumeration of different pixel formats.
+enum PixelFormat : uint8_t {
+  PIXEL_FORMAT_GRAYSCALE = 0,  ///< 8-bit grayscale.
+  PIXEL_FORMAT_RGB565,         ///< 16-bit RGB (5-6-5).
+  PIXEL_FORMAT_BGR888,         ///< RGB pixel data in 8-bit format, stored as B, G, R (1 byte each).
+};
+
+/// Returns string name for a given PixelFormat.
+inline const char *to_string(PixelFormat format) {
+  switch (format) {
+    case PIXEL_FORMAT_GRAYSCALE:
+      return "PIXEL_FORMAT_GRAYSCALE";
+    case PIXEL_FORMAT_RGB565:
+      return "PIXEL_FORMAT_RGB565";
+    case PIXEL_FORMAT_BGR888:
+      return "PIXEL_FORMAT_BGR888";
+  }
+  return "PIXEL_FORMAT_UNKNOWN";
+}
+
 /** Abstract camera image base class.
  *  Encapsulates the JPEG encoded data and it is shared among
  *  all connected clients.
@@ -43,6 +63,29 @@ class CameraImageReader {
   virtual ~CameraImageReader() {}
 };
 
+/// Specification of a caputured camera image.
+/// This struct defines the format and size details for images captured
+/// or processed by a camera component.
+struct CameraImageSpec {
+  uint16_t width;
+  uint16_t height;
+  PixelFormat format;
+  size_t bytes_per_pixel() {
+    switch (format) {
+      case PIXEL_FORMAT_GRAYSCALE:
+        return 1;
+      case PIXEL_FORMAT_RGB565:
+        return 2;
+      case PIXEL_FORMAT_BGR888:
+        return 3;
+    }
+
+    return 1;
+  }
+  size_t bytes_per_row() { return bytes_per_pixel() * width; }
+  size_t bytes_per_image() { return bytes_per_pixel() * width * height; }
+};
+
 /** Abstract camera base class. Collaborates with API.
  *  1) API server starts and installs callback (add_image_callback)
  *     which is called by the camera when a new image is available.