Merge 5f41b15b7e into 9ceca34b28

* remove use of tev & fix type errors

* lint fix

* make private classes private

* simplify inheritance

* fix thread naming

* fix the deleted public data class

* remove tev

* fix access violation

* style: format code

* style: param init

* fix: fix event async set

* fix: fix mips re-connect error

---------

Co-authored-by: topsworld <sworldtop@gmail.com>

README.md

@@ -1,6 +1,6 @@
 # Xiaomi Home Integration for Home Assistant
 
-[English](./README.md) | [简体中文](./doc/README_zh.md)
+[English](./README.md) | [简体中文](./doc/README_zh.md) | [日本語](./doc/README_ja.md)
 
 Xiaomi Home Integration is an integrated component of Home Assistant supported by Xiaomi official. It allows you to use Xiaomi IoT smart devices in Home Assistant.
 

custom_components/xiaomi_home/miot/miot_client.py

@@ -357,7 +357,7 @@ class MIoTClient:
         # Cloud mips
         self._mips_cloud.unsub_mips_state(
             key=f'{self._uid}-{self._cloud_server}')
-        self._mips_cloud.disconnect()
+        self._mips_cloud.deinit()
         # Cancel refresh cloud devices
         if self._refresh_cloud_devices_timer:
             self._refresh_cloud_devices_timer.cancel()
@@ -370,7 +370,7 @@ class MIoTClient:
                 for mips in self._mips_local.values():
                     mips.on_dev_list_changed = None
                     mips.unsub_mips_state(key=mips.group_id)
-                    mips.disconnect()
+                    mips.deinit()
                 if self._mips_local_state_changed_timers:
                     for timer_item in (
                             self._mips_local_state_changed_timers.values()):

custom_components/xiaomi_home/miot/miot_ev.py

@@ -1,324 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-Copyright (C) 2024 Xiaomi Corporation.
-
-The ownership and intellectual property rights of Xiaomi Home Assistant
-Integration and related Xiaomi cloud service API interface provided under this
-license, including source code and object code (collectively, "Licensed Work"),
-are owned by Xiaomi. Subject to the terms and conditions of this License, Xiaomi
-hereby grants you a personal, limited, non-exclusive, non-transferable,
-non-sublicensable, and royalty-free license to reproduce, use, modify, and
-distribute the Licensed Work only for your use of Home Assistant for
-non-commercial purposes. For the avoidance of doubt, Xiaomi does not authorize
-you to use the Licensed Work for any other purpose, including but not limited
-to use Licensed Work to develop applications (APP), Web services, and other
-forms of software.
-
-You may reproduce and distribute copies of the Licensed Work, with or without
-modifications, whether in source or object form, provided that you must give
-any other recipients of the Licensed Work a copy of this License and retain all
-copyright and disclaimers.
-
-Xiaomi provides the Licensed Work on an "AS IS" BASIS, WITHOUT WARRANTIES OR
-CONDITIONS OF ANY KIND, either express or implied, including, without
-limitation, any warranties, undertakes, or conditions of TITLE, NO ERROR OR
-OMISSION, CONTINUITY, RELIABILITY, NON-INFRINGEMENT, MERCHANTABILITY, or
-FITNESS FOR A PARTICULAR PURPOSE. In any event, you are solely responsible
-for any direct, indirect, special, incidental, or consequential damages or
-losses arising from the use or inability to use the Licensed Work.
-
-Xiaomi reserves all rights not expressly granted to you in this License.
-Except for the rights expressly granted by Xiaomi under this License, Xiaomi
-does not authorize you in any form to use the trademarks, copyrights, or other
-forms of intellectual property rights of Xiaomi and its affiliates, including,
-without limitation, without obtaining other written permission from Xiaomi, you
-shall not use "Xiaomi", "Mijia" and other words related to Xiaomi or words that
-may make the public associate with Xiaomi in any form to publicize or promote
-the software or hardware devices that use the Licensed Work.
-
-Xiaomi has the right to immediately terminate all your authorization under this
-License in the event:
-1. You assert patent invalidation, litigation, or other claims against patents
-or other intellectual property rights of Xiaomi or its affiliates; or,
-2. You make, have made, manufacture, sell, or offer to sell products that knock
-off Xiaomi or its affiliates' products.
-
-MIoT event loop.
-"""
-import selectors
-import heapq
-import time
-import traceback
-from typing import Any, Callable, TypeVar
-import logging
-import threading
-
-# pylint: disable=relative-beyond-top-level
-from .miot_error import MIoTEvError
-
-_LOGGER = logging.getLogger(__name__)
-
-TimeoutHandle = TypeVar('TimeoutHandle')
-
-
-class MIoTFdHandler:
-    """File descriptor handler."""
-    fd: int
-    read_handler: Callable[[Any], None]
-    read_handler_ctx: Any
-    write_handler: Callable[[Any], None]
-    write_handler_ctx: Any
-
-    def __init__(
-            self, fd: int,
-            read_handler: Callable[[Any], None] = None,
-            read_handler_ctx: Any = None,
-            write_handler: Callable[[Any], None] = None,
-            write_handler_ctx: Any = None
-    ) -> None:
-        self.fd = fd
-        self.read_handler = read_handler
-        self.read_handler_ctx = read_handler_ctx
-        self.write_handler = write_handler
-        self.write_handler_ctx = write_handler_ctx
-
-
-class MIoTTimeout:
-    """Timeout handler."""
-    key: TimeoutHandle
-    target: int
-    handler: Callable[[Any], None]
-    handler_ctx: Any
-
-    def __init__(
-            self, key: str = None, target: int = None,
-            handler: Callable[[Any], None] = None,
-            handler_ctx: Any = None
-    ) -> None:
-        self.key = key
-        self.target = target
-        self.handler = handler
-        self.handler_ctx = handler_ctx
-
-    def __lt__(self, other):
-        return self.target < other.target
-
-
-class MIoTEventLoop:
-    """MIoT event loop."""
-    _poll_fd: selectors.DefaultSelector
-
-    _fd_handlers: dict[str, MIoTFdHandler]
-
-    _timer_heap: list[MIoTTimeout]
-    _timer_handlers: dict[str, MIoTTimeout]
-    _timer_handle_seed: int
-
-    # Label if the current fd handler is freed inside a read handler to
-    # avoid invalid reading.
-    _fd_handler_freed_in_read_handler: bool
-
-    def __init__(self) -> None:
-        self._poll_fd = selectors.DefaultSelector()
-        self._timer_heap = []
-        self._timer_handlers = {}
-        self._timer_handle_seed = 1
-        self._fd_handlers = {}
-        self._fd_handler_freed_in_read_handler = False
-
-    def loop_forever(self) -> None:
-        """Run an event loop in current thread."""
-        next_timeout: int
-        while True:
-            next_timeout = 0
-            # Handle timer
-            now_ms: int = self.__get_monotonic_ms
-            while len(self._timer_heap) > 0:
-                timer: MIoTTimeout = self._timer_heap[0]
-                if timer is None:
-                    break
-                if timer.target <= now_ms:
-                    heapq.heappop(self._timer_heap)
-                    del self._timer_handlers[timer.key]
-                    if timer.handler:
-                        timer.handler(timer.handler_ctx)
-                else:
-                    next_timeout = timer.target-now_ms
-                    break
-            # Are there any files to listen to
-            if next_timeout == 0 and self._fd_handlers:
-                next_timeout = None  # None == infinite
-            # Wait for timers & fds
-            if next_timeout == 0:
-                # Neither timer nor fds exist, exit loop
-                break
-            # Handle fd event
-            events = self._poll_fd.select(
-                timeout=next_timeout/1000.0 if next_timeout else next_timeout)
-            for key, mask in events:
-                fd_handler: MIoTFdHandler = key.data
-                if fd_handler is None:
-                    continue
-                self._fd_handler_freed_in_read_handler = False
-                fd_key = str(id(fd_handler.fd))
-                if fd_key not in self._fd_handlers:
-                    continue
-                if (
-                    mask & selectors.EVENT_READ > 0
-                    and fd_handler.read_handler
-                ):
-                    fd_handler.read_handler(fd_handler.read_handler_ctx)
-                if (
-                    mask & selectors.EVENT_WRITE > 0
-                    and self._fd_handler_freed_in_read_handler is False
-                    and fd_handler.write_handler
-                ):
-                    fd_handler.write_handler(fd_handler.write_handler_ctx)
-
-    def loop_stop(self) -> None:
-        """Stop the event loop."""
-        if self._poll_fd:
-            self._poll_fd.close()
-            self._poll_fd = None
-            self._fd_handlers = {}
-            self._timer_heap = []
-            self._timer_handlers = {}
-
-    def set_timeout(
-        self, timeout_ms: int, handler: Callable[[Any], None],
-        handler_ctx: Any = None
-    ) -> TimeoutHandle:
-        """Set a timer."""
-        if timeout_ms is None or handler is None:
-            raise MIoTEvError('invalid params')
-        new_timeout: MIoTTimeout = MIoTTimeout()
-        new_timeout.key = self.__get_next_timeout_handle
-        new_timeout.target = self.__get_monotonic_ms + timeout_ms
-        new_timeout.handler = handler
-        new_timeout.handler_ctx = handler_ctx
-        heapq.heappush(self._timer_heap, new_timeout)
-        self._timer_handlers[new_timeout.key] = new_timeout
-        return new_timeout.key
-
-    def clear_timeout(self, timer_key: TimeoutHandle) -> None:
-        """Stop and remove the timer."""
-        if timer_key is None:
-            return
-        timer: MIoTTimeout = self._timer_handlers.pop(timer_key, None)
-        if timer:
-            self._timer_heap = list(self._timer_heap)
-            self._timer_heap.remove(timer)
-            heapq.heapify(self._timer_heap)
-
-    def set_read_handler(
-        self, fd: int, handler: Callable[[Any], None], handler_ctx: Any = None
-    ) -> bool:
-        """Set a read handler for a file descriptor.
-
-        Returns:
-            bool: True, success. False, failed.
-        """
-        self.__set_handler(
-            fd, is_read=True, handler=handler, handler_ctx=handler_ctx)
-
-    def set_write_handler(
-        self, fd: int, handler: Callable[[Any], None], handler_ctx: Any = None
-    ) -> bool:
-        """Set a write handler for a file descriptor.
-
-        Returns:
-            bool: True, success. False, failed.
-        """
-        self.__set_handler(
-            fd, is_read=False, handler=handler, handler_ctx=handler_ctx)
-
-    def __set_handler(
-        self, fd, is_read: bool, handler: Callable[[Any], None],
-        handler_ctx: Any = None
-    ) -> bool:
-        """Set a handler."""
-        if fd is None:
-            raise MIoTEvError('invalid params')
-
-        if not self._poll_fd:
-            raise MIoTEvError('event loop not started')
-
-        fd_key: str = str(id(fd))
-        fd_handler = self._fd_handlers.get(fd_key, None)
-
-        if fd_handler is None:
-            fd_handler = MIoTFdHandler(fd=fd)
-            fd_handler.fd = fd
-            self._fd_handlers[fd_key] = fd_handler
-
-        read_handler_existed = fd_handler.read_handler is not None
-        write_handler_existed = fd_handler.write_handler is not None
-        if is_read is True:
-            fd_handler.read_handler = handler
-            fd_handler.read_handler_ctx = handler_ctx
-        else:
-            fd_handler.write_handler = handler
-            fd_handler.write_handler_ctx = handler_ctx
-
-        if fd_handler.read_handler is None and fd_handler.write_handler is None:
-            # Remove from epoll and map
-            try:
-                self._poll_fd.unregister(fd)
-            except (KeyError, ValueError, OSError) as e:
-                del e
-            self._fd_handlers.pop(fd_key, None)
-            # May be inside a read handler, if not, this has no effect
-            self._fd_handler_freed_in_read_handler = True
-        elif read_handler_existed is False and write_handler_existed is False:
-            # Add to epoll
-            events = 0x0
-            if fd_handler.read_handler:
-                events |= selectors.EVENT_READ
-            if fd_handler.write_handler:
-                events |= selectors.EVENT_WRITE
-            try:
-                self._poll_fd.register(fd, events=events, data=fd_handler)
-            except (KeyError, ValueError, OSError) as e:
-                _LOGGER.error(
-                    '%s, register fd, error, %s, %s, %s, %s, %s',
-                    threading.current_thread().name,
-                    'read' if is_read else 'write',
-                    fd_key, handler, e, traceback.format_exc())
-                self._fd_handlers.pop(fd_key, None)
-                return False
-        elif (
-            read_handler_existed != (fd_handler.read_handler is not None)
-            or write_handler_existed != (fd_handler.write_handler is not None)
-        ):
-            # Modify epoll
-            events = 0x0
-            if fd_handler.read_handler:
-                events |= selectors.EVENT_READ
-            if fd_handler.write_handler:
-                events |= selectors.EVENT_WRITE
-            try:
-                self._poll_fd.modify(fd, events=events, data=fd_handler)
-            except (KeyError, ValueError, OSError) as e:
-                _LOGGER.error(
-                    '%s, modify fd, error, %s, %s, %s, %s, %s',
-                    threading.current_thread().name,
-                    'read' if is_read else 'write',
-                    fd_key, handler, e, traceback.format_exc())
-                self._fd_handlers.pop(fd_key, None)
-                return False
-
-        return True
-
-    @property
-    def __get_next_timeout_handle(self) -> str:
-        # Get next timeout handle, that is not larger than the maximum
-        # value of UINT64 type.
-        self._timer_handle_seed += 1
-        # uint64 max
-        self._timer_handle_seed %= 0xFFFFFFFFFFFFFFFF
-        return str(self._timer_handle_seed)
-
-    @property
-    def __get_monotonic_ms(self) -> int:
-        """Get monotonic ms timestamp."""
-        return int(time.monotonic()*1000)

custom_components/xiaomi_home/miot/miot_i18n.py

@@ -48,7 +48,7 @@ MIoT internationalization translation.
 import asyncio
 import logging
 import os
-from typing import Optional
+from typing import Optional, Union
 
 # pylint: disable=relative-beyond-top-level
 from .common import load_json_file
@@ -98,7 +98,7 @@ class MIoTI18n:
 
     def translate(
         self, key: str, replace: Optional[dict[str, str]] = None
-    ) -> str | dict | None:
+    ) -> Union[str, dict, None]:
         result = self._data
         for item in key.split('.'):
             if item not in result:

custom_components/xiaomi_home/miot/miot_lan.py

@@ -381,7 +381,8 @@ class _MIoTLanDevice:
                     _MIoTLanDeviceState(state.value+1))
                 # Fast ping
                 if self._if_name is None:
-                    _LOGGER.error('if_name is Not set for device, %s', self.did)
+                    _LOGGER.error(
+                        'if_name is Not set for device, %s', self.did)
                     return
                 if self.ip is None:
                     _LOGGER.error('ip is Not set for device, %s', self.did)
@@ -419,10 +420,10 @@ class _MIoTLanDevice:
                 self.online = True
             else:
                 _LOGGER.info('unstable device detected, %s', self.did)
-                self._online_offline_timer = \
+                self._online_offline_timer = (
                     self._manager.internal_loop.call_later(
                         self.NETWORK_UNSTABLE_RESUME_TH,
-                        self.__online_resume_handler)
+                        self.__online_resume_handler))
 
     def __online_resume_handler(self) -> None:
         _LOGGER.info('unstable resume threshold past, %s', self.did)
@@ -508,9 +509,9 @@ class MIoTLan:
             key='miot_lan', group_id='*',
             handler=self.__on_mips_service_change)
         self._enable_subscribe = enable_subscribe
-        self._virtual_did = str(virtual_did) \
-            if (virtual_did is not None) \
-            else str(secrets.randbits(64))
+        self._virtual_did = (
+            str(virtual_did) if (virtual_did is not None)
+            else str(secrets.randbits(64)))
         # Init socket probe message
         probe_bytes = bytearray(self.OT_PROBE_LEN)
         probe_bytes[:20] = (
@@ -948,7 +949,7 @@ class MIoTLan:
 
 # The following methods SHOULD ONLY be called in the internal loop
 
-    def ping(self, if_name: str | None, target_ip: str) -> None:
+    def ping(self, if_name: Optional[str], target_ip: str) -> None:
         if not target_ip:
             return
         self.__sendto(
@@ -964,7 +965,7 @@ class MIoTLan:
     ) -> None:
         if timeout_ms and not handler:
             raise ValueError('handler is required when timeout_ms is set')
-        device: _MIoTLanDevice | None = self._lan_devices.get(did)
+        device: Optional[_MIoTLanDevice] = self._lan_devices.get(did)
         if not device:
             raise ValueError('invalid device')
         if not device.cipher:
@@ -1232,7 +1233,7 @@ class MIoTLan:
             return
         # Keep alive message
         did: str = str(struct.unpack('>Q', data[4:12])[0])
-        device: _MIoTLanDevice | None = self._lan_devices.get(did)
+        device: Optional[_MIoTLanDevice] = self._lan_devices.get(did)
         if not device:
             return
         timestamp: int = struct.unpack('>I', data[12:16])[0]
@@ -1272,8 +1273,8 @@ class MIoTLan:
             _LOGGER.warning('invalid message, no id, %s, %s', did, msg)
             return
         # Reply
-        req: _MIoTLanRequestData | None = \
-            self._pending_requests.pop(msg['id'], None)
+        req: Optional[_MIoTLanRequestData] = (
+            self._pending_requests.pop(msg['id'], None))
         if req:
             if req.timeout:
                 req.timeout.cancel()
@@ -1334,7 +1335,7 @@ class MIoTLan:
         return False
 
     def __sendto(
-        self, if_name: str | None, data: bytes, address: str, port: int
+        self, if_name: Optional[str], data: bytes, address: str, port: int
     ) -> None:
         if if_name is None:
             # Broadcast
@@ -1356,7 +1357,7 @@ class MIoTLan:
         try:
             # Scan devices
             self.ping(if_name=None, target_ip='255.255.255.255')
-        except Exception as err: # pylint: disable=broad-exception-caught
+        except Exception as err:  # pylint: disable=broad-exception-caught
             # Ignore any exceptions to avoid blocking the loop
             _LOGGER.error('ping device error, %s', err)
             pass

doc/README_ja.md

@@ -0,0 +1,396 @@
+# Home Assistant Xiaomi Home Integration
+
+[English](../README.md) | [简体中文](./README_zh.md) | [日本語](./README_ja.md)
+
+Xiaomi Home Integrationは、Xiaomi公式がサポートするHome Assistantの統合コンポーネントであり、Home AssistantでXiaomi IoTスマートデバイスを使用できるようにします。
+
+## インストール
+
+> Home Assistantのバージョン要件：
+>
+> - Core $\geq$ 2024.11.0
+> - Operating System $\geq$ 13.0
+
+### 方法1：GitHubからgit cloneコマンドを使用してダウンロード
+
+```bash
+cd config
+git clone https://github.com/XiaoMi/ha_xiaomi_home.git
+cd ha_xiaomi_home
+./install.sh /config
+```
+
+この方法でXiaomi Home Integrationをインストールすることをお勧めします。特定のバージョンに更新したい場合は、対応するタグに切り替えるだけです。
+
+例：Xiaomi Home Integrationのバージョンをv1.0.0に更新する
+
+```bash
+cd config/ha_xiaomi_home
+git checkout v1.0.0
+./install.sh /config
+```
+
+### 方法2：[HACS](https://hacs.xyz/)
+
+HACS > オーバーフローメニュー > カスタムリポジトリ > リポジトリ：https://github.com/XiaoMi/ha_xiaomi_home.git & カテゴリ：Integration > 追加
+
+> Xiaomi HomeはまだHACSストアにデフォルトとして追加されていません。近日中に追加予定です。
+
+### 方法3：[Samba](https://github.com/home-assistant/addons/tree/master/samba)または[FTPS](https://github.com/hassio-addons/addon-ftp)を使用して手動でインストール
+
+ダウンロードして、`custom_components/xiaomi_home`フォルダをHome Assistantの`config/custom_components`フォルダにコピーします。
+
+## 設定
+
+### ログイン
+
+[設定 > デバイスとサービス > 統合を追加](https://my.home-assistant.io/redirect/brand/?brand=xiaomi_home) > `Xiaomi Home`を検索 > 次へ > ここをクリックしてログイン > Xiaomiアカウントでサインイン
+
+[![Open your Home Assistant instance and start setting up a new integration.](https://my.home-assistant.io/badges/config_flow_start.svg)](https://my.home-assistant.io/redirect/config_flow_start/?domain=xiaomi_home)
+
+### MIoTデバイスを追加
+
+ログインに成功すると、「家庭とデバイスを選択」ダイアログボックスが表示されます。Home Assistantにインポートしたいデバイスを含む家庭を選択できます。
+
+### 複数ユーザーログイン
+
+Xiaomiアカウントのログインとユーザー設定が完了した後、設定済みのXiaomi Home Integrationページで他のXiaomiアカウントを追加できます。
+
+方法：[設定 > デバイスとサービス > 設定済み > Xiaomi Home](https://my.home-assistant.io/redirect/integration/?domain=xiaomi_home) > 中枢を追加 > 次へ > ここをクリックしてログイン > Xiaomiアカウントでサインイン
+
+[![Open your Home Assistant instance and show an integration.](https://my.home-assistant.io/badges/integration.svg)](https://my.home-assistant.io/redirect/integration/?domain=xiaomi_home)
+
+### 設定の更新
+
+「設定オプション」ダイアログボックスで設定を変更できます。ユーザーのニックネームやXiaomi Home APPからインポートするデバイスのリストなどを更新できます。
+
+方法：[設定 > デバイスとサービス > 設定済み > Xiaomi Home](https://my.home-assistant.io/redirect/integration/?domain=xiaomi_home) > 設定 > 更新するオプションを選択
+
+### アクションのデバッグモード
+
+アクションのデバッグモードを有効にすると、パラメータ付きのアクションコマンドメッセージをデバイスに手動で送信できます。パラメータ付きのアクションコマンドを送信するためのユーザーインターフェースは、テキストエンティティとして表示されます。
+
+方法：[設定 > デバイスとサービス > 設定済み > Xiaomi Home](https://my.home-assistant.io/redirect/integration/?domain=xiaomi_home) > 設定 > アクションのデバッグモード
+
+## セキュリティ
+
+Xiaomi Home Integrationと関連するクラウドインターフェースは、Xiaomi公式が提供しています。デバイスリストを取得するためにXiaomiアカウントを使用してログインする必要があります。Xiaomi Home IntegrationはOAuth 2.0のログインプロセスを実装しており、Home Assistantアプリケーションにアカウントのパスワードを保存しません。ただし、Home Assistantプラットフォームの制限により、ログインに成功した後、Xiaomiアカウントのユーザー情報（デバイス情報、証明書、トークンなど）がHome Assistantの設定ファイルに平文で保存されます。Home Assistantの設定ファイルを適切に保管する必要があります。設定ファイルが漏洩すると、他の人があなたの身元でログインする可能性があります。
+
+## FAQ
+
+- Xiaomi Home IntegrationはすべてのXiaomi Homeデバイスをサポートしていますか？
+
+  Xiaomi Home Integrationは現在、ほとんどのXiaomi Homeデバイスカテゴリをサポートしていますが、Bluetoothデバイス、赤外線デバイス、仮想デバイスなどの一部のカテゴリはサポートしていません。
+
+- Xiaomi Home Integrationは複数のXiaomiアカウントをサポートしていますか？
+
+  はい、複数のXiaomiアカウントをサポートしています。さらに、Xiaomi Home Integrationは、異なるアカウントに属するデバイスを同じエ<E38198><E382A8><EFBFBD>アに追加することができます。
+
+- Xiaomi Home Integrationはローカルコントロールをサポートしていますか？
+
+  ローカルコントロールは、[Xiaomi Central Hub Gateway](https://www.mi.com/shop/buy/detail?product_id=15755&cfrom=search)（ファームウェアバージョン3.4.0_0000以上）または内蔵の中央ハブゲートウェイ（ソフトウェアバージョン0.8.0以上）を持つXiaomi Homeデバイスによって実装されます。Xiaomi Central Hub Gatewayまたは中央ハブゲートウェイ機能を持つ他のデバイスがない場合、すべてのコントロールコマンドはXiaomi Cloudを介して送信されます。Home Assistantのローカルコントロール機能をサポートするXiaomi Central Hub Gateway（内蔵中央ハブゲートウェイを含む）のファームウェアはまだリリースされていません。アップグレード計画については、MIoTチーム<E383BC><E383A0>通知を参照してください。
+
+  Xiaomi Central Hub Gatewayは中国本土でのみ利用可能であり、他の地域では利用できません。
+
+  Xiaomi Home Integrationは、Xiaomi LANコントロール機能を有効にすることで部分的なローカルコントロールを実装することもできます。Xiaomi LANコントロール機能は、Home Assistantと同じローカルエリアネットワーク内のIPデバイス（WiFiまたはイーサネットケーブルでルーターに接続されたデバイス）のみを制御できます。BLE Mesh、ZigBeeなどのデバイスは制御できません。この機能は一部の異常を引き起こす可能性があります。この機能を使用しないことをお勧めします。Xiaomi LANコントロール機能は、[設定 > デバイスとサービス > 設定済み > Xiaomi Home](https://my.home-assistant.io/redirect/integration/?domain=xiaomi_home) > 設定 > LANコントロール設定の更新で有効にできます。
+
+  Xiaomi LANコントロール機能は地域制限がなく、すべての地域で利用可能です。ただし、Home Assistantが存在するローカルエリアネットワーク内に中央ゲートウェイがある場合、統合でXiaomi LANコントロール機能が有効になっていても、機能は有効になりません。
+
+- Xiaomi Home Integrationはどの地域で利用可能ですか？
+
+  Xiaomi Home Integrationは、中国本土、ヨーロッパ、インド、ロシア、シンガポール、アメリカの6つの地域で利用できます。異なる地域のXiaomi Cloudのユーザーデータは相互に隔離されているため、設定プロセスでMIoTデバイスをインポートする際に地域を選択する必要があります。Xiaomi Home Integrationは、異なる地域のデバイスを同じエリアにインポートすることができます。
+
+## メッセージングの原理
+
+### クラウドを介したコントロール
+
+<div align=center>
+<img src="./images/cloud_control.jpg" width=300>
+
+図1：クラウドコントロールアーキテクチャ
+
+</div>
+
+Xiaomi Home Integrationは、MIoT CloudのMQTT Brokerで関心のあるデバイスメッセージを購読します。デバイスのプロパティが変更されたり、デバイスイベントが発生したりすると、デバイスはMIoT Cloudに上りメッセージを送信し、MQTT Brokerは購読されたデバイスメッセージをXiaomi Home Integrationにプッシュします。Xiaomi Home Integrationは、クラウドで現在のデバイスプロパティ値を取得するためにポーリングする必要がないため、プロパティが変更されたりイベントが発生したりするとすぐに通知メッセージを受信できます。メッセージ購読メカニズムのおかげで、Xiaomi Home Integrationは、統合設定が完了したときにクラウドからすべてのデバイスのプロパティを一度だけクエリし、クラウドへのアクセス圧力はほとんどありません。
+
+Xiaomi Home Integrationは、MIoT CloudのHTTPインター<E382BF><E383BC><EFBFBD>ェースを介してデバイスにコマンドメッセージを送信してデバイスを制御します。デバイスは、MIoT Cloudから送信された下りメッセージを受信した後に反応し、応答します。
+
+### ローカルでのコントロール
+
+<div align=center>
+<img src="./images/local_control.jpg" width=300>
+
+図2：ローカルコントロールアーキテクチャ
+
+</div>
+
+Xiaomi Central Hub Gatewayには標準のMQTT Brokerが含まれており、完全な購読公開メカニズムを実装しています。Xiaomi Home Integrationは、Xiaomi Central Hub Gatewayを介して関心のあるデバイスメッセージを購読します。デバイスのプロパティが変更されたり、デバイスイベントが発生したりすると、デバイスはXiaomi Central Hub Gatewayに上りメッセージを送信し、MQTT Brokerは購読されたデバイスメッセージをXiaomi Home Integrationにプッシュします。
+
+Xiaomi Home Integrationがデバイスを制御する必要がある場合、MQTT Brokerにデバイスコマンドメッセージを公開し、Xiaomi Central Hub Gatewayがデバイスに転送します。デバイスは、ゲートウェイから送信された下りメッセージを<E382B8><E38292><EFBFBD>信した後に反応し、応答します。
+
+## MIoT-Spec-V2とHome Assistantエンティティのマッピング関係
+
+[MIoT-Spec-V2](https://iot.mi.com/v2/new/doc/introduction/knowledge/spec)は、MIoT Specification Version 2の略であり、Xiaomi IoTプラットフォームが策定したIoTプロトコルであり、IoTデバイスの機能を標準的に記述するために使用されます。これには、機能定義（他のIoTプラットフォームではデータモデルと呼ばれる）、インタラクションモデル、メッセージ形式、およびエンコーディングが含まれます。
+
+MIoT-Spec-V2プロトコルでは、製品はデバイスとして定義されます。デバイスにはいくつかのサービスが含まれます。サービスにはいくつかのプロパティ、イベント、およびアクションが含まれる場合があります。Xiaomi Home Integrationは、MIoT-Spec-V2に従ってHome Assistantエンティティを作成します。変換関係は次のとおりです。
+
+### 一般的な変換
+
+- プロパティ
+
+| フォーマット | アクセス | 値リスト | 値範囲 | Home Assistantのエンティティ |
+| ------------ | -------- | -------- | ------ | ---------------------------- |
+| 書き込み可能 | 文字列   | -        | -      | テキスト                     |
+| 書き込み可能 | ブール   | -        | -      | スイッチ                     |
+| 書き込み可能 | 文字列以外 & ブール以外 | 存在する | - | セレクト                     |
+| 書き込み可能 | 文字列以外 & ブール以外 | 存在しない | 存在する | ナンバー                     |
+| 書き込み不可 | -        | -        | -      | センサー                     |
+
+- イベント
+
+MIoT-Spec-V2イベントは、Home Assistantのイベントエンティティに変換されます。イベントのパラメータもエンティティの`_trigger_event`に渡されます。
+
+- アクション
+
+| in        | Home Assistantのエンティティ |
+| --------- | ---------------------------- |
+| 空        | ボタン                       |
+| 空でない  | 通知                         |
+
+アクションのデバッグモードが有効になっている場合、アクションの`in`フィールドが空でない場合、テキストエンティティも作成されます。
+
+エンティティの詳細ページの「属性」項目には、入力パラメータの形式が表示されます。入力パラメータは順序付きリストであり、角括弧[]で囲まれています。リスト内の文字列要素は二重引用符""で囲まれています。
+
+例：xiaomi.wifispeaker.s12 siid=5 aiid=5インスタンスの「Intelligent Speaker Execute Text Directive」アクションによって変換された通知エンティティの詳細ページの「属性」項目には、アクションパラメータとして`[Text Content(str), Silent Execution(bool)]`が表示されます。適切にフォーマットされた入力は`["Hello", true]`です。
+
+### 特定の変換
+
+MIoT-Spec-V2は、タイプを定義するためにURNを使用します。形式は`urn:<namespace>:<type>:<name>:<value>[:<vendor-product>:<version>]`であり、`name`はデバイス、サービス、プロパティ、イベント、アクションのインスタンスを説明するための人間が読める単語またはフレーズです。Xiaomi Home Integrationは、インスタンスの名前に基づいてMIoT-Spec-V2インスタンスを特定のHome Assistantエンティティに変換するかどうかを最初に判断します。特定の変換ルールに一致しないインスタンスについては、一般的な変換ルールを使用して変換します。
+
+`namespace`はMIoT-Spec-V2インスタンスの名前空間です。その値がmiot-spec-v2の場合、仕様はXiaomiによって定義されたことを意味します。その値がbluetooth-specの場合、仕様はBluetooth Special Interest Group（SIG）によって定義されたことを意味します。その値がmiot-spec-v2またはbluetooth-specでない場合、仕様は他のベンダーによって定義されたことを意味します。MIoT-Spec-V2の`namespace`がmiot-spec-v2でない場合、エンティティの名前の前に星印`*`が追加されます。
+
+- デバイス
+
+変換は`SPEC_DEVICE_TRANS_MAP`に従います。
+
+```
+{
+    '<device instance name>':{
+        'required':{
+            '<service instance name>':{
+                'required':{
+                    'properties': {
+                        '<property instance name>': set<property access: str>
+                    },
+                    'events': set<event instance name: str>,
+                    'actions': set<action instance name: str>
+                },
+                'optional':{
+                    'properties': set<property instance name: str>,
+                    'events': set<event instance name: str>,
+                    'actions': set<action instance name: str>
+                }
+            }
+        },
+        'optional':{
+            '<service instance name>':{
+                'required':{
+                    'properties': {
+                        '<property instance name>': set<property access: str>
+                    },
+                    'events': set<event instance name: str>,
+                    'actions': set<action instance name: str>
+                },
+                'optional':{
+                    'properties': set<property instance name: str>,
+                    'events': set<event instance name: str>,
+                    'actions': set<action instance name: str>
+                }
+            }
+        },
+        'entity': str
+    }
+}
+```
+
+"device instance name"の下の"required"フィールドは、デバイスの必須サービスを示します。"optional"フィールドは、デバイスのオプションサービスを示します。"entity"フィールドは、作成されるHome Assistantエンティティを示します。"service instance name"の下の"required"フィールドと"optional"フィールドは、それぞれサービスの必須プロパティ、イベント、およびアクションを示します。"required"フィールドの"properties"フィールドの"property instance name"の値は、プロパティのアクセスモードです。成功した一致の条件は、"property instance name"の値が対応するMIoT-Spec-V2プロパティインスタンスのアクセスモードのサブセットであることです。
+
+MIoT-Spec-V2デバイスインスタンスがすべての必須サービス、プロパティ、イベント、アクションを含まない場合、Home Assistantエンティティは作成されません。
+
+- サービス
+
+変換は`SPEC_SERVICE_TRANS_MAP`に従います。
+
+```
+{
+    '<service instance name>':{
+        'required':{
+            'properties': {
+                '<property instance name>': set<property access: str>
+            },
+            'events': set<event instance name: str>,
+            'actions': set<action instance name: str>
+        },
+        'optional':{
+            'properties': set<property instance name: str>,
+            'events': set<event instance name: str>,
+            'actions': set<action instance name: str>
+        },
+        'entity': str
+    }
+}
+```
+
+"service instance name"の下の"required"フィールドは、サービスの必須プロパティ、イベント、およびアクションを示します。"optional"フィールドは、サービスのオプションプロパティ、イベント、およびアクションを示します。"entity"フィールドは、作成されるHome Assistantエンティティを示します。"required"フィールドの"properties"フィールドの"property instance name"の値は、プロパティのアクセスモードです。成功した一致の条件は、"property instance name"の値が対応するMIoT-Spec-V2プロパティインスタンスのアクセスモードのサブセットであることです。
+
+MIoT-Spec-V2サービスインスタンスがすべての必須プロパティ、イベント、アクションを含まない場合、Home Assistantエンティティは作成されません。
+
+- プロパティ
+
+変換は`SPEC_PROP_TRANS_MAP`に従います。
+
+```
+{
+    'entities':{
+        '<entity name>':{
+            'format': set<str>,
+            'access': set<str>
+        }
+    },
+    'properties': {
+        '<property instance name>':{
+            'device_class': str,
+            'entity': str
+        }
+    }
+}
+```
+
+"entity name"の下の"format"フィールドは、プロパティのデータ形式を表し、1つの値と一致することが成功した一致を示します。"entity name"の下の"access"フィールドは、プロパティのアクセスモードを表し、すべての値と一致することが成功した一致を示します。
+
+"property instance name"の下の"entity"フィールドの値は、"entities"フィールドの"entity name"の1つであり、作成されるHome Assistantエンティティを示します。"property instance name"の下の"device_class"フィールドは、作成されるHome Assistantエンティティの`_attr_device_class`を示します。
+
+- イベント
+
+変換は`SPEC_EVENT_TRANS_MAP`に従います。
+
+```
+{
+    '<event instance name>': str
+}
+```
+
+イベントインスタンス名の値は、作成されるHome Assistantエンティティの`_attr_device_class`を示します。
+
+### MIoT-Spec-V2フィルタ
+
+`spec_filter.json`は、Home Assistantエンティティに変換されないMIoT-Spec-V2インスタンスをフィルタリングするために使用されます。
+
+`spec_filter.json`の形式は次のとおりです。
+
+```
+{
+    "<MIoT-Spec-V2 device instance>":{
+        "services": list<service_iid: str>,
+        "properties": list<service_iid.property_iid: str>,
+        "events": list<service_iid.event_iid: str>,
+        "actions": list<service_iid.action_iid: str>,
+    }
+}
+```
+
+`spec_filter.json`辞書のキーは、MIoT-Spec-V2デバイスインスタンスのURN（"version"フィールドを除く）です。同じ製品の異なるバージョンのファームウェアは、異なるバージョンのMIoT-Spec-V2デバイスインスタンスに関連付けられる場合があります。MIoTプラットフォームでは、ベンダーが製品のMIoT-Spec-V2を定義する際に、高バージョンのMIoT-Spec-V2インスタンスが低バージョンのMIoT-Spec-V2インスタンスをすべて含む必要があります。そのため、`spec_filter.json`のキーはMIoT-Spec-V2デバイスインスタンスのバージョン番号を指定する必要はありません。
+
+デバイスインスタンスの下の"services"、"properties"、"events"、"actions"フィールドの値は、変換プロセスで無視されるサービス、プロパティ、イベント、アクションのインスタンスID（iid）です。ワイルドカードマッチングがサポートされています。
+
+例：
+
+```
+{
+    "urn:miot-spec-v2:device:television:0000A010:xiaomi-rmi1":{
+        "services": ["*"]   # すべてのサービスをフィルタリングします。これは、そのようなMIoT-Spec-V2デバイスインスタンスを完全に無視することと同等です。
+    },
+    "urn:miot-spec-v2:device:gateway:0000A019:xiaomi-hub1": {
+        "services": ["3"],  # iid=3のサービスをフィルタリングします。
+        "properties": ["4.*"]   # iid=4のサービス内のすべてのプロパティをフィルタリングします。
+        "events": ["4.1"],  # iid=4のサービス内のiid=1のイベントをフィルタリングします。
+        "actions": ["4.1"]  # iid=4のサービス内のiid=1のアクションをフィルタリングします。
+    }
+}
+```
+
+すべてのデバイスのデバイス情報サービス（urn:miot-spec-v2:service:device-information:00007801）は、Home Assistantエンティティに変換されません。
+
+## 多言語サポート
+
+Xiaomi Homeの設定フロー言語オプションで選択可能な言語は、簡体字中国語、繁体字中国語、英語、スペイン語、ロシア語、フランス語、ドイツ語、日本語の8つの言語です。設定フローページの簡体字中国語と英語は開発者によって手動でレビューされています。他の言語は機械翻訳によって翻訳されています。設定フローページの単語や文を変更したい場合は、`custom_components/xiaomi_home/translations/`および`custom_components/xiaomi_home/miot/i18n/`ディレクトリ内の該当する言語のjsonファイルを変更する必要があります。
+
+Home Assistantエンティティ名を表示する際、Xiaomi HomeはデバイスベンダーがMIoT Cloudからダウンロードした多言語ファイルを使用します。このファイルには、デバイスのMIoT-Spec-V2インスタンスの翻訳が含まれています。`multi_lang.json`はローカルで管理されている多言語辞書であり、クラウドから取得した多言語ファイルよりも優先され、デバイスの翻訳を補完または修正するために使用できます。
+
+`multi_lang.json`の形式は次のとおりです。
+
+```
+{
+    "<MIoT-Spec-V2 device instance>": {
+        "<language code>": {
+            "<instance code>": <translation: str>
+        }
+    }
+}
+```
+
+`multi_lang.json`辞書のキーは、MIoT-Spec-V2デバイスインスタンスのURN（"version"フィールドを除く）です。
+
+言語コードは、zh-Hans、zh-Hant、en、es、ru、fr、de、jaのいずれかであり、上記の選択可能な8つの言語に対応しています。
+
+インスタンスコードは、MIoT-Spec-V2インスタンスのコードであり、次の形式です：
+
+```
+service:<siid>                  # サービス
+service:<siid>:property:<piid>  # プロパティ
+service:<siid>:property:<piid>:valuelist:<value> # プロパティの値リストの値
+service:<siid>:event:<eiid>     # イベント
+service:<siid>:action:<aiid>    # アクション
+```
+
+siid、piid、eiid、aiid、およびvalueはすべて10進数の3桁の整数です。
+
+例：
+
+```
+{
+    "urn:miot-spec-v2:device:health-pot:0000A051:chunmi-a1": {
+        "zh-Hant": {
+            "service:002": "養生壺",
+            "service:002:property:001": "工作狀態",
+            "service:002:property:001:valuelist:000": "待機中",
+            "service:002:action:002": "停止烹飪",
+            "service:005:event:001": "烹飪完成"
+        }
+    }
+}
+```
+
+> Home Assistantで`custom_components/xiaomi_home/miot/specs`ディレクトリ内の`specv2entity.py`、`spec_filter.json`、`multi_lang.json`ファイルの内容を編集した場合、統合の設定ページでエンティティ変換ルールを更新する必要があります。方法：[設定 > デバイスとサービス > 設定済み > Xiaomi Home](https://my.home-assistant.io/redirect/integration/?domain=xiaomi_home) > 設定 > エンティティ変換ルールの更新
+
+## ドキュメント
+
+- [ライセンス](../LICENSE.md)
+- 貢献ガイドライン：[English](../CONTRIBUTING.md) | [简体中文](./CONTRIBUTING_zh.md)
+- [変更履歴](./CHANGELOG.md)
+- 開発ドキュメント：https://developers.home-assistant.io/docs/creating_component_index
+
+## ディレクトリ構造
+
+- miot：コアコード。
+- miot/miot_client：統合にユーザーを追加するには、miot_clientインスタンスを追加する必要があります。
+- miot/miot_cloud：クラウドサービスに関連する機能を含みます。OAuthログインプロセス、HTTPインターフェース機能（ユーザー情報の取得、デバイス制御コマンドの送信など）。
+- miot/miot_device：デバイスエンティティ。デバイス情報、プロパティ、イベント、アクションの処理ロジックを含みます。
+- miot/miot_mips：メッセージバス。メソッドの購読と公開のためのものです。
+- miot/miot_spec：MIoT-Spec-V2を解析します。
+- miot/miot_lan：デバイスLANコントロール。デバイスの発見、デバイスの制御などを含みます。
+- miot/miot_mdns：中央ハブゲートウェイサービスのLAN発見。
+- miot/miot_network：ネットワーク状態とネットワーク情報の取得。
+- miot/miot_storage：統合のファイルストレージ。
+- miot/test：テストスクリプト。
+- config_flow：設定フロー。

doc/README_zh.md

@@ -1,6 +1,6 @@
 # Home Assistant 米家集成
 
-[English](../README.md) | [简体中文](./README_zh.md)
+[English](../README.md) | [简体中文](./README_zh.md) | [日本語](./README_ja.md)
 
 米家集成是一个由小米官方提供支持的 Home Assistant 的集成组件，它可以让您在 Home Assistant 中使用小米 IoT 智能设备。
 

test/conftest.py

@@ -20,7 +20,6 @@ def load_py_file():
         'const.py',
         'miot_cloud.py',
         'miot_error.py',
-        'miot_ev.py',
         'miot_i18n.py',
         'miot_lan.py',
         'miot_mdns.py',

test/test_ev.py

@@ -1,55 +0,0 @@
-# -*- coding: utf-8 -*-
-"""Unit test for miot_ev.py."""
-import os
-import pytest
-
-# pylint: disable=import-outside-toplevel, disable=unused-argument
-
-
-@pytest.mark.github
-def test_mev_timer_and_fd():
-    from miot.miot_ev import MIoTEventLoop, TimeoutHandle
-
-    mev = MIoTEventLoop()
-    assert mev
-    event_fd: os.eventfd = os.eventfd(0, os.O_NONBLOCK)
-    assert event_fd
-    timer4: TimeoutHandle = None
-
-    def event_handler(event_fd):
-        value: int = os.eventfd_read(event_fd)
-        if value == 1:
-            mev.clear_timeout(timer4)
-            print('cancel timer4')
-        elif value == 2:
-            print('event write twice in a row')
-        elif value == 3:
-            mev.set_read_handler(event_fd, None, None)
-            os.close(event_fd)
-            event_fd = None
-            print('close event fd')
-
-    def timer1_handler(event_fd):
-        os.eventfd_write(event_fd, 1)
-
-    def timer2_handler(event_fd):
-        os.eventfd_write(event_fd, 1)
-        os.eventfd_write(event_fd, 1)
-
-    def timer3_handler(event_fd):
-        os.eventfd_write(event_fd, 3)
-
-    def timer4_handler(event_fd):
-        raise ValueError('unreachable code')
-
-    mev.set_read_handler(
-        event_fd, event_handler, event_fd)
-
-    mev.set_timeout(500, timer1_handler, event_fd)
-    mev.set_timeout(1000, timer2_handler, event_fd)
-    mev.set_timeout(1500, timer3_handler, event_fd)
-    timer4 = mev.set_timeout(2000, timer4_handler, event_fd)
-
-    mev.loop_forever()
-    # Loop will exit when there are no timers or fd handlers.
-    mev.loop_stop()