Add Datetime entities (#859)

aioesphomeapi/api.proto

@@ -48,6 +48,7 @@ service APIConnection {
   rpc media_player_command (MediaPlayerCommandRequest) returns (void) {}
   rpc date_command (DateCommandRequest) returns (void) {}
   rpc time_command (TimeCommandRequest) returns (void) {}
+  rpc datetime_command (DateTimeCommandRequest) returns (void) {}
 
   rpc subscribe_bluetooth_le_advertisements (SubscribeBluetoothLEAdvertisementsRequest) returns (void) {}
   rpc bluetooth_device_request(BluetoothDeviceRequest) returns (void) {}
@@ -1768,3 +1769,40 @@ message ValveCommandRequest {
   float position = 3;
   bool stop = 4;
 }
+
+// ==================== DATETIME DATETIME ====================
+message ListEntitiesDateTimeResponse {
+  option (id) = 112;
+  option (source) = SOURCE_SERVER;
+  option (ifdef) = "USE_DATETIME_DATETIME";
+
+  string object_id = 1;
+  fixed32 key = 2;
+  string name = 3;
+  string unique_id = 4;
+
+  string icon = 5;
+  bool disabled_by_default = 6;
+  EntityCategory entity_category = 7;
+}
+message DateTimeStateResponse {
+  option (id) = 113;
+  option (source) = SOURCE_SERVER;
+  option (ifdef) = "USE_DATETIME_DATETIME";
+  option (no_delay) = true;
+
+  fixed32 key = 1;
+  // If the datetime does not have a valid state yet.
+  // Equivalent to `!obj->has_state()` - inverse logic to make state packets smaller
+  bool missing_state = 2;
+  fixed32 epoch_seconds = 3;
+}
+message DateTimeCommandRequest {
+  option (id) = 114;
+  option (source) = SOURCE_CLIENT;
+  option (ifdef) = "USE_DATETIME_DATETIME";
+  option (no_delay) = true;
+
+  fixed32 key = 1;
+  fixed32 epoch_seconds = 2;
+}

aioesphomeapi/client.py

@@ -38,6 +38,7 @@ from .api_pb2 import (  # type: ignore
     ClimateCommandRequest,
     CoverCommandRequest,
     DateCommandRequest,
+    DateTimeCommandRequest,
     DeviceInfoRequest,
     DeviceInfoResponse,
     ExecuteServiceArgument,
@@ -1118,6 +1119,18 @@ class APIClient:
             TimeCommandRequest(key=key, hour=hour, minute=minute, second=second)
         )
 
+    def datetime_command(
+        self,
+        key: int,
+        epoch_seconds: int,
+    ) -> None:
+        self._get_connection().send_message(
+            DateTimeCommandRequest(
+                key=key,
+                epoch_seconds=epoch_seconds,
+            )
+        )
+
     def select_command(self, key: int, state: str) -> None:
         self._get_connection().send_message(SelectCommandRequest(key=key, state=state))
 

aioesphomeapi/core.py

@@ -40,6 +40,8 @@ from .api_pb2 import (  # type: ignore
     CoverStateResponse,
     DateCommandRequest,
     DateStateResponse,
+    DateTimeCommandRequest,
+    DateTimeStateResponse,
     DeviceInfoRequest,
     DeviceInfoResponse,
     DisconnectRequest,
@@ -62,6 +64,7 @@ from .api_pb2 import (  # type: ignore
     ListEntitiesClimateResponse,
     ListEntitiesCoverResponse,
     ListEntitiesDateResponse,
+    ListEntitiesDateTimeResponse,
     ListEntitiesDoneResponse,
     ListEntitiesFanResponse,
     ListEntitiesLightResponse,
@@ -374,4 +377,7 @@ MESSAGE_TYPE_TO_PROTO = {
     109: ListEntitiesValveResponse,
     110: ValveStateResponse,
     111: ValveCommandRequest,
+    112: ListEntitiesDateTimeResponse,
+    113: DateTimeStateResponse,
+    114: DateTimeCommandRequest,
 }

aioesphomeapi/model.py

@@ -690,6 +690,18 @@ class TimeState(EntityState):
     second: int = 0
 
 
+# ==================== DATETIME DATETIME ====================
+@_frozen_dataclass_decorator
+class DateTimeInfo(EntityInfo):
+    pass
+
+
+@_frozen_dataclass_decorator
+class DateTimeState(EntityState):
+    missing_state: bool = False
+    epoch_seconds: int = 0
+
+
 # ==================== SELECT ====================
 @_frozen_dataclass_decorator
 class SelectInfo(EntityInfo):
@@ -885,6 +897,7 @@ COMPONENT_TYPE_TO_INFO: dict[str, type[EntityInfo]] = {
     "climate": ClimateInfo,
     "number": NumberInfo,
     "date": DateInfo,
+    "datetime": DateTimeInfo,
     "select": SelectInfo,
     "siren": SirenInfo,
     "button": ButtonInfo,
@@ -1242,6 +1255,7 @@ _TYPE_TO_NAME = {
     LightInfo: "light",
     NumberInfo: "number",
     DateInfo: "date",
+    DateTimeInfo: "datetime",
     SelectInfo: "select",
     SensorInfo: "sensor",
     SirenInfo: "siren",

aioesphomeapi/model_conversions.py

@@ -8,6 +8,7 @@ from .api_pb2 import (  # type: ignore
     ClimateStateResponse,
     CoverStateResponse,
     DateStateResponse,
+    DateTimeStateResponse,
     FanStateResponse,
     LightStateResponse,
     ListEntitiesAlarmControlPanelResponse,
@@ -17,6 +18,7 @@ from .api_pb2 import (  # type: ignore
     ListEntitiesClimateResponse,
     ListEntitiesCoverResponse,
     ListEntitiesDateResponse,
+    ListEntitiesDateTimeResponse,
     ListEntitiesFanResponse,
     ListEntitiesLightResponse,
     ListEntitiesLockResponse,
@@ -56,6 +58,8 @@ from .model import (
     CoverState,
     DateInfo,
     DateState,
+    DateTimeInfo,
+    DateTimeState,
     EntityInfo,
     EntityState,
     FanInfo,
@@ -93,6 +97,7 @@ SUBSCRIBE_STATES_RESPONSE_TYPES: dict[Any, type[EntityState]] = {
     LightStateResponse: LightState,
     NumberStateResponse: NumberState,
     DateStateResponse: DateState,
+    DateTimeStateResponse: DateTimeState,
     SelectStateResponse: SelectState,
     SensorStateResponse: SensorState,
     SirenStateResponse: SirenState,
@@ -115,6 +120,7 @@ LIST_ENTITIES_SERVICES_RESPONSE_TYPES: dict[Any, type[EntityInfo] | None] = {
     ListEntitiesLightResponse: LightInfo,
     ListEntitiesNumberResponse: NumberInfo,
     ListEntitiesDateResponse: DateInfo,
+    ListEntitiesDateTimeResponse: DateTimeInfo,
     ListEntitiesSelectResponse: SelectInfo,
     ListEntitiesSensorResponse: SensorInfo,
     ListEntitiesSirenResponse: SirenInfo,

tests/test_client.py

@@ -42,6 +42,7 @@ from aioesphomeapi.api_pb2 import (
     ClimateCommandRequest,
     CoverCommandRequest,
     DateCommandRequest,
+    DateTimeCommandRequest,
     DeviceInfoResponse,
     DisconnectResponse,
     ExecuteServiceArgument,
@@ -668,6 +669,30 @@ async def test_time_command(
     send.assert_called_once_with(TimeCommandRequest(**req))
 
 
+# Test date_time command
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "cmd, req",
+    [
+        (
+            dict(key=1, epoch_seconds=1735648230),
+            dict(key=1, epoch_seconds=1735648230),
+        ),
+        (
+            dict(key=1, epoch_seconds=1735689600),
+            dict(key=1, epoch_seconds=1735689600),
+        ),
+    ],
+)
+async def test_datetime_command(
+    auth_client: APIClient, cmd: dict[str, Any], req: dict[str, Any]
+) -> None:
+    send = patch_send(auth_client)
+
+    auth_client.datetime_command(**cmd)
+    send.assert_called_once_with(DateTimeCommandRequest(**req))
+
+
 @pytest.mark.asyncio
 @pytest.mark.parametrize(
     "cmd, req",

tests/test_model.py

@@ -14,6 +14,7 @@ from aioesphomeapi.api_pb2 import (
     ClimateStateResponse,
     CoverStateResponse,
     DateStateResponse,
+    DateTimeStateResponse,
     DeviceInfoResponse,
     FanStateResponse,
     HomeassistantServiceMap,
@@ -25,6 +26,7 @@ from aioesphomeapi.api_pb2 import (
     ListEntitiesClimateResponse,
     ListEntitiesCoverResponse,
     ListEntitiesDateResponse,
+    ListEntitiesDateTimeResponse,
     ListEntitiesFanResponse,
     ListEntitiesLightResponse,
     ListEntitiesLockResponse,
@@ -77,6 +79,8 @@ from aioesphomeapi.model import (
     CoverState,
     DateInfo,
     DateState,
+    DateTimeInfo,
+    DateTimeState,
     DeviceInfo,
     FanInfo,
     FanState,
@@ -274,6 +278,8 @@ def test_api_version_ord():
         (TextState, TextStateResponse),
         (TimeInfo, ListEntitiesTimeResponse),
         (TimeState, TimeStateResponse),
+        (DateTimeInfo, ListEntitiesDateTimeResponse),
+        (DateTimeState, DateTimeStateResponse),
     ],
 )
 def test_basic_pb_conversions(model, pb):