Reduce API component memory usage with conditional compilation (#9262)

esphome/components/api/__init__.py

@@ -136,23 +136,26 @@ async def to_code(config):
     cg.add(var.set_reboot_timeout(config[CONF_REBOOT_TIMEOUT]))
     cg.add(var.set_batch_delay(config[CONF_BATCH_DELAY]))
 
-    for conf in config.get(CONF_ACTIONS, []):
-        template_args = []
-        func_args = []
-        service_arg_names = []
-        for name, var_ in conf[CONF_VARIABLES].items():
-            native = SERVICE_ARG_NATIVE_TYPES[var_]
-            template_args.append(native)
-            func_args.append((native, name))
-            service_arg_names.append(name)
-        templ = cg.TemplateArguments(*template_args)
-        trigger = cg.new_Pvariable(
-            conf[CONF_TRIGGER_ID], templ, conf[CONF_ACTION], service_arg_names
-        )
-        cg.add(var.register_user_service(trigger))
-        await automation.build_automation(trigger, func_args, conf)
+    if actions := config.get(CONF_ACTIONS, []):
+        cg.add_define("USE_API_YAML_SERVICES")
+        for conf in actions:
+            template_args = []
+            func_args = []
+            service_arg_names = []
+            for name, var_ in conf[CONF_VARIABLES].items():
+                native = SERVICE_ARG_NATIVE_TYPES[var_]
+                template_args.append(native)
+                func_args.append((native, name))
+                service_arg_names.append(name)
+            templ = cg.TemplateArguments(*template_args)
+            trigger = cg.new_Pvariable(
+                conf[CONF_TRIGGER_ID], templ, conf[CONF_ACTION], service_arg_names
+            )
+            cg.add(var.register_user_service(trigger))
+            await automation.build_automation(trigger, func_args, conf)
 
     if CONF_ON_CLIENT_CONNECTED in config:
+        cg.add_define("USE_API_CLIENT_CONNECTED_TRIGGER")
         await automation.build_automation(
             var.get_client_connected_trigger(),
             [(cg.std_string, "client_info"), (cg.std_string, "client_address")],
@@ -160,6 +163,7 @@ async def to_code(config):
         )
 
     if CONF_ON_CLIENT_DISCONNECTED in config:
+        cg.add_define("USE_API_CLIENT_DISCONNECTED_TRIGGER")
         await automation.build_automation(
             var.get_client_disconnected_trigger(),
             [(cg.std_string, "client_info"), (cg.std_string, "client_address")],

esphome/components/api/api_connection.cpp

@@ -1511,7 +1511,9 @@ ConnectResponse APIConnection::connect(const ConnectRequest &msg) {
   if (correct) {
     ESP_LOGD(TAG, "%s connected", this->get_client_combined_info().c_str());
     this->flags_.connection_state = static_cast<uint8_t>(ConnectionState::AUTHENTICATED);
+#ifdef USE_API_CLIENT_CONNECTED_TRIGGER
     this->parent_->get_client_connected_trigger()->trigger(this->client_info_, this->client_peername_);
+#endif
 #ifdef USE_HOMEASSISTANT_TIME
     if (homeassistant::global_homeassistant_time != nullptr) {
       this->send_time_request();

esphome/components/api/api_server.cpp

@@ -184,7 +184,9 @@ void APIServer::loop() {
     }
 
     // Rare case: handle disconnection
+#ifdef USE_API_CLIENT_DISCONNECTED_TRIGGER
     this->client_disconnected_trigger_->trigger(client->client_info_, client->client_peername_);
+#endif
     ESP_LOGV(TAG, "Remove connection %s", client->client_info_.c_str());
 
     // Swap with the last element and pop (avoids expensive vector shifts)

esphome/components/api/api_server.h

@@ -105,7 +105,18 @@ class APIServer : public Component, public Controller {
   void on_media_player_update(media_player::MediaPlayer *obj) override;
 #endif
   void send_homeassistant_service_call(const HomeassistantServiceResponse &call);
-  void register_user_service(UserServiceDescriptor *descriptor) { this->user_services_.push_back(descriptor); }
+  void register_user_service(UserServiceDescriptor *descriptor) {
+#ifdef USE_API_YAML_SERVICES
+    // Vector is pre-allocated when services are defined in YAML
+    this->user_services_.push_back(descriptor);
+#else
+    // Lazy allocate vector on first use for CustomAPIDevice
+    if (!this->user_services_) {
+      this->user_services_ = std::make_unique<std::vector<UserServiceDescriptor *>>();
+    }
+    this->user_services_->push_back(descriptor);
+#endif
+  }
 #ifdef USE_HOMEASSISTANT_TIME
   void request_time();
 #endif
@@ -134,19 +145,34 @@ class APIServer : public Component, public Controller {
   void get_home_assistant_state(std::string entity_id, optional<std::string> attribute,
                                 std::function<void(std::string)> f);
   const std::vector<HomeAssistantStateSubscription> &get_state_subs() const;
-  const std::vector<UserServiceDescriptor *> &get_user_services() const { return this->user_services_; }
+  const std::vector<UserServiceDescriptor *> &get_user_services() const {
+#ifdef USE_API_YAML_SERVICES
+    return this->user_services_;
+#else
+    static const std::vector<UserServiceDescriptor *> EMPTY;
+    return this->user_services_ ? *this->user_services_ : EMPTY;
+#endif
+  }
 
+#ifdef USE_API_CLIENT_CONNECTED_TRIGGER
   Trigger<std::string, std::string> *get_client_connected_trigger() const { return this->client_connected_trigger_; }
+#endif
+#ifdef USE_API_CLIENT_DISCONNECTED_TRIGGER
   Trigger<std::string, std::string> *get_client_disconnected_trigger() const {
     return this->client_disconnected_trigger_;
   }
+#endif
 
  protected:
   void schedule_reboot_timeout_();
   // Pointers and pointer-like types first (4 bytes each)
   std::unique_ptr<socket::Socket> socket_ = nullptr;
+#ifdef USE_API_CLIENT_CONNECTED_TRIGGER
   Trigger<std::string, std::string> *client_connected_trigger_ = new Trigger<std::string, std::string>();
+#endif
+#ifdef USE_API_CLIENT_DISCONNECTED_TRIGGER
   Trigger<std::string, std::string> *client_disconnected_trigger_ = new Trigger<std::string, std::string>();
+#endif
 
   // 4-byte aligned types
   uint32_t reboot_timeout_{300000};
@@ -156,7 +182,15 @@ class APIServer : public Component, public Controller {
   std::string password_;
   std::vector<uint8_t> shared_write_buffer_;  // Shared proto write buffer for all connections
   std::vector<HomeAssistantStateSubscription> state_subs_;
+#ifdef USE_API_YAML_SERVICES
+  // When services are defined in YAML, we know at compile time that services will be registered
   std::vector<UserServiceDescriptor *> user_services_;
+#else
+  // Services can still be registered at runtime by CustomAPIDevice components even when not
+  // defined in YAML. Using unique_ptr allows lazy allocation, saving 12 bytes in the common
+  // case where no services (YAML or custom) are used.
+  std::unique_ptr<std::vector<UserServiceDescriptor *>> user_services_;
+#endif
 
   // Group smaller types together
   uint16_t port_{6053};

esphome/core/defines.h

@@ -101,8 +101,11 @@
 #define USE_AUDIO_FLAC_SUPPORT
 #define USE_AUDIO_MP3_SUPPORT
 #define USE_API
+#define USE_API_CLIENT_CONNECTED_TRIGGER
+#define USE_API_CLIENT_DISCONNECTED_TRIGGER
 #define USE_API_NOISE
 #define USE_API_PLAINTEXT
+#define USE_API_YAML_SERVICES
 #define USE_MD5
 #define USE_MQTT
 #define USE_NETWORK

tests/integration/fixtures/api_conditional_memory.yaml

@@ -0,0 +1,71 @@
+esphome:
+  name: api-conditional-memory-test
+host:
+api:
+  actions:
+    - action: test_simple_service
+      then:
+        - logger.log: "Simple service called"
+        - binary_sensor.template.publish:
+            id: service_called_sensor
+            state: ON
+    - action: test_service_with_args
+      variables:
+        arg_string: string
+        arg_int: int
+        arg_bool: bool
+        arg_float: float
+      then:
+        - logger.log:
+            format: "Service called with: %s, %d, %d, %.2f"
+            args: [arg_string.c_str(), arg_int, arg_bool, arg_float]
+        - sensor.template.publish:
+            id: service_arg_sensor
+            state: !lambda 'return arg_float;'
+  on_client_connected:
+    - logger.log:
+        format: "Client %s connected from %s"
+        args: [client_info.c_str(), client_address.c_str()]
+    - binary_sensor.template.publish:
+        id: client_connected
+        state: ON
+    - text_sensor.template.publish:
+        id: last_client_info
+        state: !lambda 'return client_info;'
+  on_client_disconnected:
+    - logger.log:
+        format: "Client %s disconnected from %s"
+        args: [client_info.c_str(), client_address.c_str()]
+    - binary_sensor.template.publish:
+        id: client_connected
+        state: OFF
+    - binary_sensor.template.publish:
+        id: client_disconnected_event
+        state: ON
+
+logger:
+  level: DEBUG
+
+binary_sensor:
+  - platform: template
+    name: "Client Connected"
+    id: client_connected
+    device_class: connectivity
+  - platform: template
+    name: "Client Disconnected Event"
+    id: client_disconnected_event
+  - platform: template
+    name: "Service Called"
+    id: service_called_sensor
+
+sensor:
+  - platform: template
+    name: "Service Argument Value"
+    id: service_arg_sensor
+    unit_of_measurement: ""
+    accuracy_decimals: 2
+
+text_sensor:
+  - platform: template
+    name: "Last Client Info"
+    id: last_client_info

tests/integration/test_api_conditional_memory.py

@@ -0,0 +1,205 @@
+"""Integration test for API conditional memory optimization with triggers and services."""
+
+from __future__ import annotations
+
+import asyncio
+
+from aioesphomeapi import (
+    BinarySensorInfo,
+    EntityState,
+    SensorInfo,
+    TextSensorInfo,
+    UserService,
+    UserServiceArgType,
+)
+import pytest
+
+from .types import APIClientConnectedFactory, RunCompiledFunction
+
+
+@pytest.mark.asyncio
+async def test_api_conditional_memory(
+    yaml_config: str,
+    run_compiled: RunCompiledFunction,
+    api_client_connected: APIClientConnectedFactory,
+) -> None:
+    """Test API triggers and services work correctly with conditional compilation."""
+    loop = asyncio.get_running_loop()
+    # Keep ESPHome process running throughout the test
+    async with run_compiled(yaml_config):
+        # First connection
+        async with api_client_connected() as client:
+            # Verify device info
+            device_info = await client.device_info()
+            assert device_info is not None
+            assert device_info.name == "api-conditional-memory-test"
+
+            # List entities and services
+            entity_info, services = await asyncio.wait_for(
+                client.list_entities_services(), timeout=5.0
+            )
+
+            # Find our entities
+            client_connected: BinarySensorInfo | None = None
+            client_disconnected_event: BinarySensorInfo | None = None
+            service_called_sensor: BinarySensorInfo | None = None
+            service_arg_sensor: SensorInfo | None = None
+            last_client_info: TextSensorInfo | None = None
+
+            for entity in entity_info:
+                if isinstance(entity, BinarySensorInfo):
+                    if entity.object_id == "client_connected":
+                        client_connected = entity
+                    elif entity.object_id == "client_disconnected_event":
+                        client_disconnected_event = entity
+                    elif entity.object_id == "service_called":
+                        service_called_sensor = entity
+                elif isinstance(entity, SensorInfo):
+                    if entity.object_id == "service_argument_value":
+                        service_arg_sensor = entity
+                elif isinstance(entity, TextSensorInfo):
+                    if entity.object_id == "last_client_info":
+                        last_client_info = entity
+
+            # Verify all entities exist
+            assert client_connected is not None, "client_connected sensor not found"
+            assert client_disconnected_event is not None, (
+                "client_disconnected_event sensor not found"
+            )
+            assert service_called_sensor is not None, "service_called sensor not found"
+            assert service_arg_sensor is not None, "service_arg_sensor not found"
+            assert last_client_info is not None, "last_client_info sensor not found"
+
+            # Verify services exist
+            assert len(services) == 2, f"Expected 2 services, found {len(services)}"
+
+            # Find our services
+            simple_service: UserService | None = None
+            service_with_args: UserService | None = None
+
+            for service in services:
+                if service.name == "test_simple_service":
+                    simple_service = service
+                elif service.name == "test_service_with_args":
+                    service_with_args = service
+
+            assert simple_service is not None, "test_simple_service not found"
+            assert service_with_args is not None, "test_service_with_args not found"
+
+            # Verify service arguments
+            assert len(service_with_args.args) == 4, (
+                f"Expected 4 args, found {len(service_with_args.args)}"
+            )
+
+            # Check arg types
+            arg_types = {arg.name: arg.type for arg in service_with_args.args}
+            assert arg_types["arg_string"] == UserServiceArgType.STRING
+            assert arg_types["arg_int"] == UserServiceArgType.INT
+            assert arg_types["arg_bool"] == UserServiceArgType.BOOL
+            assert arg_types["arg_float"] == UserServiceArgType.FLOAT
+
+            # Track state changes
+            states: dict[int, EntityState] = {}
+            states_future: asyncio.Future[None] = loop.create_future()
+
+            def on_state(state: EntityState) -> None:
+                states[state.key] = state
+                # Check if we have initial states for connection sensors
+                if (
+                    client_connected.key in states
+                    and last_client_info.key in states
+                    and not states_future.done()
+                ):
+                    states_future.set_result(None)
+
+            client.subscribe_states(on_state)
+
+            # Wait for initial states
+            await asyncio.wait_for(states_future, timeout=5.0)
+
+            # Verify on_client_connected trigger fired
+            connected_state = states.get(client_connected.key)
+            assert connected_state is not None
+            assert connected_state.state is True, "Client should be connected"
+
+            # Verify client info was captured
+            client_info_state = states.get(last_client_info.key)
+            assert client_info_state is not None
+            assert isinstance(client_info_state.state, str)
+            assert len(client_info_state.state) > 0, "Client info should not be empty"
+
+            # Test simple service
+            service_future: asyncio.Future[None] = loop.create_future()
+
+            def check_service_called(state: EntityState) -> None:
+                if state.key == service_called_sensor.key and state.state is True:
+                    if not service_future.done():
+                        service_future.set_result(None)
+
+            # Update callback to check for service execution
+            client.subscribe_states(check_service_called)
+
+            # Call simple service
+            client.execute_service(simple_service, {})
+
+            # Wait for service to execute
+            await asyncio.wait_for(service_future, timeout=5.0)
+
+            # Test service with arguments
+            arg_future: asyncio.Future[None] = loop.create_future()
+            expected_float = 42.5
+
+            def check_arg_sensor(state: EntityState) -> None:
+                if (
+                    state.key == service_arg_sensor.key
+                    and abs(state.state - expected_float) < 0.01
+                ):
+                    if not arg_future.done():
+                        arg_future.set_result(None)
+
+            client.subscribe_states(check_arg_sensor)
+
+            # Call service with arguments
+            client.execute_service(
+                service_with_args,
+                {
+                    "arg_string": "test_string",
+                    "arg_int": 123,
+                    "arg_bool": True,
+                    "arg_float": expected_float,
+                },
+            )
+
+            # Wait for service with args to execute
+            await asyncio.wait_for(arg_future, timeout=5.0)
+
+        # After disconnecting first client, reconnect and verify triggers work
+        async with api_client_connected() as client2:
+            # Subscribe to states with new client
+            states2: dict[int, EntityState] = {}
+            connected_future: asyncio.Future[None] = loop.create_future()
+
+            def on_state2(state: EntityState) -> None:
+                states2[state.key] = state
+                # Check for reconnection
+                if state.key == client_connected.key and state.state is True:
+                    if not connected_future.done():
+                        connected_future.set_result(None)
+
+            client2.subscribe_states(on_state2)
+
+            # Wait for connected state
+            await asyncio.wait_for(connected_future, timeout=5.0)
+
+            # Verify client is connected again (on_client_connected fired)
+            assert states2[client_connected.key].state is True, (
+                "Client should be reconnected"
+            )
+
+            # The client_disconnected_event should be ON from when we disconnected
+            # (it was set ON by on_client_disconnected trigger)
+            disconnected_state = states2.get(client_disconnected_event.key)
+            assert disconnected_state is not None
+            assert disconnected_state.state is True, (
+                "Disconnect event should be ON from previous disconnect"
+            )