Implement datetime time entity (#850)

aioesphomeapi/api.proto

@@ -46,6 +46,7 @@ service APIConnection {
   rpc lock_command (LockCommandRequest) returns (void) {}
   rpc media_player_command (MediaPlayerCommandRequest) returns (void) {}
   rpc date_command (DateCommandRequest) returns (void) {}
+  rpc time_command (TimeCommandRequest) returns (void) {}
 
   rpc subscribe_bluetooth_le_advertisements (SubscribeBluetoothLEAdvertisementsRequest) returns (void) {}
   rpc bluetooth_device_request(BluetoothDeviceRequest) returns (void) {}
@@ -1660,3 +1661,44 @@ message DateCommandRequest {
   uint32 month = 3;
   uint32 day = 4;
 }
+
+// ==================== DATETIME TIME ====================
+message ListEntitiesTimeResponse {
+  option (id) = 103;
+  option (source) = SOURCE_SERVER;
+  option (ifdef) = "USE_DATETIME_TIME";
+
+  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 TimeStateResponse {
+  option (id) = 104;
+  option (source) = SOURCE_SERVER;
+  option (ifdef) = "USE_DATETIME_TIME";
+  option (no_delay) = true;
+
+  fixed32 key = 1;
+  // If the time does not have a valid state yet.
+  // Equivalent to `!obj->has_state()` - inverse logic to make state packets smaller
+  bool missing_state = 2;
+  uint32 hour = 3;
+  uint32 minute = 4;
+  uint32 second = 5;
+}
+message TimeCommandRequest {
+  option (id) = 105;
+  option (source) = SOURCE_CLIENT;
+  option (ifdef) = "USE_DATETIME_TIME";
+  option (no_delay) = true;
+
+  fixed32 key = 1;
+  uint32 hour = 2;
+  uint32 minute = 3;
+  uint32 second = 4;
+}

aioesphomeapi/client.py

@@ -65,6 +65,7 @@ from .api_pb2 import (  # type: ignore
     SubscribeVoiceAssistantRequest,
     SwitchCommandRequest,
     TextCommandRequest,
+    TimeCommandRequest,
     UnsubscribeBluetoothLEAdvertisementsRequest,
     VoiceAssistantEventData,
     VoiceAssistantEventResponse,
@@ -1108,6 +1109,11 @@ class APIClient:
             DateCommandRequest(key=key, year=year, month=month, day=day)
         )
 
+    def time_command(self, key: int, hour: int, minute: int, second: int) -> None:
+        self._get_connection().send_message(
+            TimeCommandRequest(key=key, hour=hour, minute=minute, second=second)
+        )
+
     def select_command(self, key: int, state: str) -> None:
         self._get_connection().send_message(SelectCommandRequest(key=key, state=state))
 

aioesphomeapi/core.py

@@ -76,6 +76,7 @@ from .api_pb2 import (  # type: ignore
     ListEntitiesSwitchResponse,
     ListEntitiesTextResponse,
     ListEntitiesTextSensorResponse,
+    ListEntitiesTimeResponse,
     LockCommandRequest,
     LockStateResponse,
     MediaPlayerCommandRequest,
@@ -103,6 +104,8 @@ from .api_pb2 import (  # type: ignore
     TextCommandRequest,
     TextSensorStateResponse,
     TextStateResponse,
+    TimeCommandRequest,
+    TimeStateResponse,
     UnsubscribeBluetoothLEAdvertisementsRequest,
     VoiceAssistantEventResponse,
     VoiceAssistantRequest,
@@ -360,4 +363,7 @@ MESSAGE_TYPE_TO_PROTO = {
     100: ListEntitiesDateResponse,
     101: DateStateResponse,
     102: DateCommandRequest,
+    103: ListEntitiesTimeResponse,
+    104: TimeStateResponse,
+    105: TimeCommandRequest,
 }

aioesphomeapi/model.py

@@ -653,6 +653,22 @@ class DateState(EntityState):
     day: int = 0
 
 
+# ==================== DATETIME TIME ====================
+
+
+@_frozen_dataclass_decorator
+class TimeInfo(EntityInfo):
+    pass
+
+
+@_frozen_dataclass_decorator
+class TimeState(EntityState):
+    missing_state: bool = False
+    hour: int = 0
+    minute: int = 0
+    second: int = 0
+
+
 # ==================== SELECT ====================
 @_frozen_dataclass_decorator
 class SelectInfo(EntityInfo):
@@ -830,6 +846,7 @@ COMPONENT_TYPE_TO_INFO: dict[str, type[EntityInfo]] = {
     "media_player": MediaPlayerInfo,
     "alarm_control_panel": AlarmControlPanelInfo,
     "text": TextInfo,
+    "time": TimeInfo,
 }
 
 
@@ -1183,6 +1200,7 @@ _TYPE_TO_NAME = {
     MediaPlayerInfo: "media_player",
     AlarmControlPanelInfo: "alarm_control_panel",
     TextInfo: "text_info",
+    TimeInfo: "time",
 }
 
 

aioesphomeapi/model_conversions.py

@@ -29,6 +29,7 @@ from .api_pb2 import (  # type: ignore
     ListEntitiesSwitchResponse,
     ListEntitiesTextResponse,
     ListEntitiesTextSensorResponse,
+    ListEntitiesTimeResponse,
     LockStateResponse,
     MediaPlayerStateResponse,
     NumberStateResponse,
@@ -38,6 +39,7 @@ from .api_pb2 import (  # type: ignore
     SwitchStateResponse,
     TextSensorStateResponse,
     TextStateResponse,
+    TimeStateResponse,
 )
 from .model import (
     AlarmControlPanelEntityState,
@@ -76,6 +78,8 @@ from .model import (
     TextSensorInfo,
     TextSensorState,
     TextState,
+    TimeInfo,
+    TimeState,
 )
 
 SUBSCRIBE_STATES_RESPONSE_TYPES: dict[Any, type[EntityState]] = {
@@ -95,6 +99,7 @@ SUBSCRIBE_STATES_RESPONSE_TYPES: dict[Any, type[EntityState]] = {
     LockStateResponse: LockEntityState,
     MediaPlayerStateResponse: MediaPlayerEntityState,
     AlarmControlPanelStateResponse: AlarmControlPanelEntityState,
+    TimeStateResponse: TimeState,
 }
 
 LIST_ENTITIES_SERVICES_RESPONSE_TYPES: dict[Any, type[EntityInfo] | None] = {
@@ -117,4 +122,5 @@ LIST_ENTITIES_SERVICES_RESPONSE_TYPES: dict[Any, type[EntityInfo] | None] = {
     ListEntitiesLockResponse: LockInfo,
     ListEntitiesMediaPlayerResponse: MediaPlayerInfo,
     ListEntitiesAlarmControlPanelResponse: AlarmControlPanelInfo,
+    ListEntitiesTimeResponse: TimeInfo,
 }

tests/test_client.py

@@ -63,6 +63,7 @@ from aioesphomeapi.api_pb2 import (
     SubscribeVoiceAssistantRequest,
     SwitchCommandRequest,
     TextCommandRequest,
+    TimeCommandRequest,
     VoiceAssistantAudioSettings,
     VoiceAssistantEventData,
     VoiceAssistantEventResponse,
@@ -641,6 +642,30 @@ async def test_date_command(
     send.assert_called_once_with(DateCommandRequest(**req))
 
 
+# Test time command
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "cmd, req",
+    [
+        (
+            dict(key=1, hour=12, minute=30, second=30),
+            dict(key=1, hour=12, minute=30, second=30),
+        ),
+        (
+            dict(key=1, hour=0, minute=0, second=0),
+            dict(key=1, hour=0, minute=0, second=0),
+        ),
+    ],
+)
+async def test_time_command(
+    auth_client: APIClient, cmd: dict[str, Any], req: dict[str, Any]
+) -> None:
+    send = patch_send(auth_client)
+
+    auth_client.time_command(**cmd)
+    send.assert_called_once_with(TimeCommandRequest(**req))
+
+
 @pytest.mark.asyncio
 @pytest.mark.parametrize(
     "cmd, req",

tests/test_model.py

@@ -36,6 +36,7 @@ from aioesphomeapi.api_pb2 import (
     ListEntitiesServicesResponse,
     ListEntitiesSwitchResponse,
     ListEntitiesTextSensorResponse,
+    ListEntitiesTimeResponse,
     LockStateResponse,
     MediaPlayerStateResponse,
     NumberStateResponse,
@@ -45,6 +46,7 @@ from aioesphomeapi.api_pb2 import (
     SwitchStateResponse,
     TextSensorStateResponse,
     TextStateResponse,
+    TimeStateResponse,
 )
 from aioesphomeapi.model import (
     _TYPE_TO_NAME,
@@ -98,6 +100,8 @@ from aioesphomeapi.model import (
     TextSensorInfo,
     TextSensorState,
     TextState,
+    TimeInfo,
+    TimeState,
     UserService,
     UserServiceArg,
     UserServiceArgType,
@@ -261,6 +265,8 @@ def test_api_version_ord():
         (AlarmControlPanelInfo, ListEntitiesAlarmControlPanelResponse),
         (AlarmControlPanelEntityState, AlarmControlPanelStateResponse),
         (TextState, TextStateResponse),
+        (TimeInfo, ListEntitiesTimeResponse),
+        (TimeState, TimeStateResponse),
     ],
 )
 def test_basic_pb_conversions(model, pb):
@@ -376,6 +382,7 @@ def test_user_service_conversion():
         MediaPlayerInfo,
         AlarmControlPanelInfo,
         TextInfo,
+        TimeInfo,
     ],
 )
 def test_build_unique_id(model):