Add infrared receiver entity

homeassistant/components/esphome/infrared.py

@@ -7,7 +7,7 @@
 
 from aioesphomeapi import EntityState, InfraredCapability, InfraredInfo
 
-from homeassistant.components.infrared import InfraredCommand, InfraredEntity
+from homeassistant.components.infrared import InfraredCommand, InfraredEmitterEntity
 from homeassistant.core import callback
 
 from .entity import (
@@ -21,8 +21,10 @@
 PARALLEL_UPDATES = 0
 
 
-class EsphomeInfraredEntity(EsphomeEntity[InfraredInfo, EntityState], InfraredEntity):
-    """ESPHome infrared entity using native API."""
+class EsphomeInfraredEntity(
+    EsphomeEntity[InfraredInfo, EntityState], InfraredEmitterEntity
+):
+    """ESPHome infrared emitter entity using native API."""
 
     @callback
     def _on_device_update(self) -> None:

homeassistant/components/infrared/__init__.py

@@ -3,18 +3,22 @@
 from __future__ import annotations
 
 from abc import abstractmethod
+from collections.abc import Callable
+from dataclasses import dataclass
 from datetime import timedelta
+from enum import StrEnum
 import logging
 from typing import final
 
 from infrared_protocols import Command as InfraredCommand
+import voluptuous as vol
 
 from homeassistant.config_entries import ConfigEntry
 from homeassistant.const import STATE_UNAVAILABLE
-from homeassistant.core import Context, HomeAssistant, callback
+from homeassistant.core import CALLBACK_TYPE, Context, HomeAssistant, callback
 from homeassistant.exceptions import HomeAssistantError
 from homeassistant.helpers import config_validation as cv, entity_registry as er
-from homeassistant.helpers.entity import EntityDescription
+from homeassistant.helpers.entity import Entity, EntityDescription
 from homeassistant.helpers.entity_component import EntityComponent
 from homeassistant.helpers.restore_state import RestoreEntity
 from homeassistant.helpers.typing import ConfigType
@@ -25,15 +29,30 @@
 
 __all__ = [
     "DOMAIN",
-    "InfraredEntity",
-    "InfraredEntityDescription",
+    "InfraredEmitterEntity",
+    "InfraredEmitterEntityDescription",
+    "InfraredReceivedSignal",
+    "InfraredReceiverEntity",
+    "InfraredReceiverEntityDescription",
     "async_get_emitters",
+    "async_get_receivers",
     "async_send_command",
+    "async_subscribe_receiver",
 ]
 
+
+class InfraredDeviceClass(StrEnum):
+    """Device class for infrared entities."""
+
+    RECEIVER = "receiver"
+    EMITTER = "emitter"
+
+
 _LOGGER = logging.getLogger(__name__)
 
-DATA_COMPONENT: HassKey[EntityComponent[InfraredEntity]] = HassKey(DOMAIN)
+DATA_COMPONENT: HassKey[
+    EntityComponent[InfraredEmitterEntity | InfraredReceiverEntity]
+] = HassKey(DOMAIN)
 ENTITY_ID_FORMAT = DOMAIN + ".{}"
 PLATFORM_SCHEMA = cv.PLATFORM_SCHEMA
 PLATFORM_SCHEMA_BASE = cv.PLATFORM_SCHEMA_BASE
@@ -42,9 +61,9 @@
 
 async def async_setup(hass: HomeAssistant, config: ConfigType) -> bool:
     """Set up the infrared domain."""
-    component = hass.data[DATA_COMPONENT] = EntityComponent[InfraredEntity](
-        _LOGGER, DOMAIN, hass, SCAN_INTERVAL
-    )
+    component = hass.data[DATA_COMPONENT] = EntityComponent[
+        InfraredEmitterEntity | InfraredReceiverEntity
+    ](_LOGGER, DOMAIN, hass, SCAN_INTERVAL)
     await component.async_setup(config)
 
     return True
@@ -67,7 +86,25 @@ def async_get_emitters(hass: HomeAssistant) -> list[str]:
     if component is None:
         return []
 
-    return [entity.entity_id for entity in component.entities]
+    return [
+        entity.entity_id
+        for entity in component.entities
+        if isinstance(entity, InfraredEmitterEntity)
+    ]
+
+
+@callback
+def async_get_receivers(hass: HomeAssistant) -> list[str]:
+    """Get all infrared receiver entity IDs."""
+    component = hass.data.get(DATA_COMPONENT)
+    if component is None:
+        return []
+
+    return [
+        entity.entity_id
+        for entity in component.entities
+        if isinstance(entity, InfraredReceiverEntity)
+    ]
 
 
 async def async_send_command(
@@ -91,7 +128,7 @@ async def async_send_command(
     ent_reg = er.async_get(hass)
     entity_id = er.async_validate_entity_id(ent_reg, entity_id_or_uuid)
     entity = component.get_entity(entity_id)
-    if entity is None:
+    if entity is None or not isinstance(entity, InfraredEmitterEntity):
         raise HomeAssistantError(
             translation_domain=DOMAIN,
             translation_key="entity_not_found",
@@ -104,14 +141,62 @@ async def async_send_command(
     await entity.async_send_command_internal(command)
 
 
-class InfraredEntityDescription(EntityDescription, frozen_or_thawed=True):
-    """Describes infrared entities."""
+@callback
+def async_subscribe_receiver(
+    hass: HomeAssistant,
+    entity_id_or_uuid: str,
+    signal_callback: Callable[[InfraredReceivedSignal], None],
+) -> CALLBACK_TYPE:
+    """Subscribe to IR signals from a specific receiver entity.
+
+    Raises:
+        HomeAssistantError: If the receiver entity is not found.
+    """
+    component = hass.data.get(DATA_COMPONENT)
+    if component is None:
+        raise HomeAssistantError(
+            translation_domain=DOMAIN,
+            translation_key="component_not_loaded",
+        )
 
+    ent_reg = er.async_get(hass)
+    try:
+        entity_id = er.async_validate_entity_id(ent_reg, entity_id_or_uuid)
+    except vol.Invalid as err:
+        raise HomeAssistantError(
+            translation_domain=DOMAIN,
+            translation_key="receiver_not_found",
+            translation_placeholders={"entity_id": entity_id},
+        ) from err
 
-class InfraredEntity(RestoreEntity):
-    """Base class for infrared transmitter entities."""
+    entity = component.get_entity(entity_id)
+    if entity is None or not isinstance(entity, InfraredReceiverEntity):
+        raise HomeAssistantError(
+            translation_domain=DOMAIN,
+            translation_key="receiver_not_found",
+            translation_placeholders={"entity_id": entity_id},
+        )
 
-    entity_description: InfraredEntityDescription
+    return entity.async_subscribe_received_signal(signal_callback)
+
+
+@dataclass(frozen=True, slots=True)
+class InfraredReceivedSignal:
+    """Represents a received IR signal."""
+
+    timings: list[int]
+    modulation: int | None = None
+
+
+class InfraredEmitterEntityDescription(EntityDescription, frozen_or_thawed=True):
+    """Describes infrared emitter entities."""
+
+
+class InfraredEmitterEntity(RestoreEntity):
+    """Base class for infrared emitter entities."""
+
+    entity_description: InfraredEmitterEntityDescription
+    _attr_device_class: InfraredDeviceClass = InfraredDeviceClass.EMITTER
     _attr_should_poll = False
     _attr_state: None = None
 
@@ -151,3 +236,63 @@ async def async_send_command(self, command: InfraredCommand) -> None:
         Raises:
             HomeAssistantError: If transmission fails.
         """
+
+
+class InfraredReceiverEntityDescription(EntityDescription, frozen_or_thawed=True):
+    """Describes infrared receiver entities."""
+
+
+class InfraredReceiverEntity(Entity):
+    """Base class for infrared receiver entities."""
+
+    entity_description: InfraredReceiverEntityDescription
+    _attr_device_class: InfraredDeviceClass = InfraredDeviceClass.RECEIVER
+    _attr_should_poll = False
+    _attr_state: None = None
+
+    __last_signal_received: str | None = None
+
+    def __init__(self) -> None:
+        """Initialize the receiver entity."""
+        super().__init__()
+        self.__signal_callbacks: set[Callable[[InfraredReceivedSignal], None]] = set()
+
+    @property
+    @final
+    def state(self) -> str | None:
+        """Return the entity state."""
+        return self.__last_signal_received
+
+    @final
+    def _handle_received_signal(self, signal: InfraredReceivedSignal) -> None:
+        """Handle a received IR signal.
+
+        Called by platform implementations when a signal is received.
+        Updates entity state and notifies subscribers.
+        """
+        self.__last_signal_received = dt_util.utcnow().isoformat(
+            timespec="milliseconds"
+        )
+        self.async_write_ha_state()
+        for signal_callback in self.__signal_callbacks:
+            try:
+                signal_callback(signal)
+            except Exception:
+                _LOGGER.exception("Error in signal callback for %s", self.entity_id)
+
+    @callback
+    def async_subscribe_received_signal(
+        self,
+        signal_callback: Callable[[InfraredReceivedSignal], None],
+    ) -> CALLBACK_TYPE:
+        """Subscribe to received IR signals.
+
+        Returns a callable to unsubscribe.
+        """
+        self.__signal_callbacks.add(signal_callback)
+
+        @callback
+        def remove_callback() -> None:
+            self.__signal_callbacks.discard(signal_callback)
+
+        return remove_callback

homeassistant/components/infrared/icons.json

@@ -2,6 +2,9 @@
   "entity_component": {
     "_": {
       "default": "mdi:led-on"
+    },
+    "receiver": {
+      "default": "mdi:led-off"
     }
   }
 }

homeassistant/components/infrared/strings.json

@@ -1,10 +1,21 @@
 {
+  "entity_component": {
+    "_": {
+      "name": "Infrared emitter"
+    },
+    "receiver": {
+      "name": "Infrared receiver"
+    }
+  },
   "exceptions": {
     "component_not_loaded": {
       "message": "Infrared component not loaded"
     },
     "entity_not_found": {
       "message": "Infrared entity `{entity_id}` not found"
+    },
+    "receiver_not_found": {
+      "message": "Infrared receiver entity `{entity_id}` not found"
     }
   }
 }

homeassistant/components/kitchen_sink/infrared.py

@@ -5,16 +5,27 @@
 import infrared_protocols
 
 from homeassistant.components import persistent_notification
-from homeassistant.components.infrared import InfraredEntity
+from homeassistant.components.infrared import (
+    InfraredEmitterEntity,
+    InfraredReceivedSignal,
+    InfraredReceiverEntity,
+)
 from homeassistant.config_entries import ConfigEntry
-from homeassistant.core import HomeAssistant
+from homeassistant.core import HomeAssistant, callback
 from homeassistant.helpers.device_registry import DeviceInfo
+from homeassistant.helpers.dispatcher import (
+    async_dispatcher_connect,
+    async_dispatcher_send,
+)
+from homeassistant.helpers.entity import Entity
 from homeassistant.helpers.entity_platform import AddConfigEntryEntitiesCallback
 
 from . import DOMAIN
 
 PARALLEL_UPDATES = 0
 
+INFRARED_COMMAND_SIGNAL = f"{DOMAIN}_infrared_command_signal"
+
 
 async def async_setup_entry(
     hass: HomeAssistant,
@@ -24,37 +35,60 @@ async def async_setup_entry(
     """Set up the demo infrared platform."""
     async_add_entities(
         [
-            DemoInfrared(
-                unique_id="ir_transmitter",
-                device_name="IR Blaster",
-                entity_name="Infrared Transmitter",
+            DemoInfraredEmitter(
+                unique_id="ir_emitter",
+                entity_name="Infrared Emitter",
+            ),
+            DemoInfraredReceiver(
+                unique_id="ir_receiver",
+                entity_name="Infrared Receiver",
             ),
         ]
     )
 
 
-class DemoInfrared(InfraredEntity):
+# pylint: disable=hass-enforce-class-module
+class DemoInfraredEntityBase(Entity):
     """Representation of a demo infrared entity."""
 
     _attr_has_entity_name = True
     _attr_should_poll = False
 
-    def __init__(
-        self,
-        unique_id: str,
-        device_name: str,
-        entity_name: str,
-    ) -> None:
+    def __init__(self, unique_id: str, entity_name: str) -> None:
         """Initialize the demo infrared entity."""
+        super().__init__()
         self._attr_unique_id = unique_id
         self._attr_device_info = DeviceInfo(
-            identifiers={(DOMAIN, unique_id)},
-            name=device_name,
+            identifiers={(DOMAIN, "infrared")}, name="IR Blaster"
         )
         self._attr_name = entity_name
 
+
+class DemoInfraredEmitter(DemoInfraredEntityBase, InfraredEmitterEntity):
+    """Representation of a demo infrared emitter entity."""
+
     async def async_send_command(self, command: infrared_protocols.Command) -> None:
         """Send an IR command."""
+        raw_timings = command.get_raw_timings()
         persistent_notification.async_create(
-            self.hass, str(command.get_raw_timings()), title="Infrared Command"
+            self.hass, str(raw_timings), title="Infrared Command Sent"
+        )
+        async_dispatcher_send(self.hass, INFRARED_COMMAND_SIGNAL, raw_timings)
+
+
+class DemoInfraredReceiver(DemoInfraredEntityBase, InfraredReceiverEntity):
+    """Representation of a demo infrared receiver entity."""
+
+    @callback
+    def _on_dispacher_signal(self, raw_timings: list[int]) -> None:
+        """Handle received infrared command signal."""
+        self._handle_received_signal(InfraredReceivedSignal(timings=raw_timings))
+
+    async def async_added_to_hass(self) -> None:
+        """Called when entity is added to hass."""
+        await super().async_added_to_hass()
+        self.async_on_remove(
+            async_dispatcher_connect(
+                self.hass, INFRARED_COMMAND_SIGNAL, self._on_dispacher_signal
+            )
         )