Home API Android SDK 版本说明

2025-09-08

适用于 Android 的示例应用版本 1.4.1 已发布。

新功能

• 创建、重命名、更新和删除会议室。
• 调试到第三方 Matter 结构。

修复的已知问题

• 权限撤消页面链接现在可以正常使用。

2025-08-29

  Home API 公开 Beta 版版本 1.4.1  

此版本修复了多个 bug，并提升了 Home API Android SDK 的 Beta 版质量。

最低版本

• Google Play 服务：25.33.32
• Google 集线器的最低固件版本：
  • Cast：3.76.495998
  • Fuchsia：27.20250422.103.3600
• Android SDK：home.android.sdk_1_4_1
• Google Home 应用：适用于任何版本
• androidx.core 库：适用于任何版本
• Matter 版本： 1.4.0.0

新功能

• Device API
  • 定义了一个新的 DecommissionIneligibleReason，用于尝试停用多来源设备。请参阅 多来源设备。

已知问题

• 当当前处于活动状态的 Hub 被强制移除时，在 5 分钟的时间窗口内，无法控制某些设备。5 分钟后，设备控制功能会恢复。

修复的已知问题

• 当用户尝试将温控器设置为不支持的模式时，Android 示例应用会崩溃。

2025-07-31

  Home API 公开 Beta 版 1.4.0  

此版本修复了多个 bug，并提升了 Home API Android SDK 的 Beta 版质量。

最低版本

• Google Play 服务：25.28.34
• Google 集线器的最低固件版本：
  • Cast：3.76.486931
  • Fuchsia：27.20250422.103.3600
• Android SDK：home.android.sdk_1_4_0
• Google Home 应用：适用于任何版本
• androidx.core 库：适用于任何版本
• Matter 版本： 1.4.0.0

新功能

• Automation API
  • 自动化操作可以限制为最多执行有限次数。请参阅限制执行次数。

• Device API
  • 能够以编程方式移除 Matter 设备。请参阅移除设备。
  • 以下已弃用的 HomeDevice 成员已被移除：
    1. HomeDevice.trait()。请参阅 访问 Android 设备和设备元数据。
    2. HomeDevice.isInRoom。请改用 HomeDevice.roomId。
    3. HomeDevice.isInStructure。请改用 HomeDevice.structureId。
• Structure API
  • Home.hasPermissions() 现在同时包含用户的 OAuth 授权状态（对结构的访问权限）以及应用权限授予。
• Android 示例应用
  • 替换了已弃用的 API 调用。
  • 重命名设备。
  • 删除仅支持 Matter 的设备。

已知问题

• 在手机上退出登录并重新登录后，Home API 应用无法控制设备。
  • 解决方法：关闭应用或将其置于后台，然后等待至少 10 秒再重试。

修复的已知问题

• 已返回底座的吸尘器设备未注册“已返回底座”状态。

2025-07-08

借助 Cast 固件版本 3.76.479819，Nest WiFi Pro 现在可以充当 Home API 中枢。

2025-06-26

  Home API 公开 Beta 版 1.3.2  

此版本修复了 bug，并提升了 Home API Android SDK 的 Beta 版质量。

最低版本

• Google Play 服务：25.23.31
• Google 集线器的最低固件版本：
  • 投放：
    • Google Home、Google Home Mini 和 Google Nest Mini：3.75.468362
    • Google Nest Audio：3.75.476451
  • Fuchsia：26.20250116.103.2900
• Android SDK：home.android.sdk_1_3_2
• Google Home 应用：适用于任何版本
• androidx.core 库：适用于任何版本
• Matter 版本： 1.4.0.0

新功能

• SDK 制品已分为两个单独的制品：
  • Home API SDK 框架 (play-services-home-17.0.0.aar)
  • SDK 特征和设备类型 (play-services-home-types-17.0.0.aar)

  从该版本开始，开发者需要在项目的编译时和运行时库路径中同时包含这两个制品。

Android 示例应用

• 用户可以断开与应用的关联并撤消应用的权限。
• 更新了 SDK 制品，以包含 play-services-home-17.0.0 和 play-services-home-types-17.0.0。

已知问题

• 已返回底座的吸尘器设备未注册“已返回底座”状态。

2025-06-05

  Home API 公开 Beta 版 1.3.1  

此版本修复了 bug，并提升了 Home API Android SDK 的 Beta 版质量。

最低版本

• Google Play 服务：25.19.32
• Google 集线器的最低固件版本：
  • Cast：3.75.468222
  • Fuchsia：26.20250116.103.2201
• Android SDK：home.android.sdk_202505_EAP_1_3_1_RC06
• Google Home 应用：适用于任何版本
• androidx.core 库：适用于任何版本
• Matter 版本： 1.4.0.0

新功能

特征

• 引入了 SyntheticSwitch 特征，可简化对 Matter 开关设备生成的事件的处理，并允许开关触发自动化启动器。
• ExtendedDoorLock 特征存在重大变更：user_id 字段数据类型已从 String 更改为 Long。请参阅
  • ExtendedDoorLockTrait.LockStateChange.user_id
  • ExtendedDoorLockTrait.PrivacyModeActor.user_id

  使用此特征的应用需要重新编译。

Android 示例应用

添加了用于记录结构、设备、类型、特征和自动化操作状态的函数，以便更轻松地进行调试。

已知问题

在 Android 示例应用中，创建自动化按钮有时需要多次点按才能触发。

修复的已知问题

• 如果在 Google Home 应用 (GHA) 中未设置住宅位置，则在创建自动化操作时，Google Home 应用会因出现 FailedPreconditionException 而崩溃（如需了解如何设置住宅位置，请参阅更改 Google 家庭住址）。
• 在 Android 示例应用中，之前向用户显示了具有 connectivityState PARTIALLY_ONLINE 的设备处于离线状态。此状态现在表示为在线。

2025-05-12

  Home API 公开 Beta 版版本 1.3  

此版本修复了 bug，并提升了 Home API Android SDK 的 Beta 版质量。

最低版本

• Google Play 服务：25.16.33
• Google 集线器的最低固件版本：
  • Cast：3.75.468222
  • Fuchsia：26.20250116.103.2201
• Android SDK：home.android.sdk_202504_EAP_1_3_RC00
• Google Home 应用：适用于任何版本
• androidx.core 库：适用于任何版本
• Matter 版本： 1.4.0.0

新功能

• Automation API
  • 新增了对 周期性预定事件启动器的支持，开发者可以使用 cron 表达式创建基于时钟时间、太阳时间和日历条件的周期性自动化操作。
• Device API
  • 新增了重命名设备的功能。请参阅更改设备的名称。
• Structure API
  • 添加了重命名聊天室的功能。请参阅更改聊天室名称。

已知问题

如果在 Google Home 应用 (GHA) 中未设置住宅位置，则在创建自动化操作时，Google Home 应用会因出现 FailedPreconditionException 而崩溃（请参阅更改 Google 家庭住址，了解如何设置住宅位置）。

• 解决方法：在尝试创建自动化操作之前，使用 Discovery API 检查家庭住址是否存在。

修复的已知问题

• 从 Wi-Fi 切换到移动网络时，设备控制延迟可能会增加。
• 中枢恢复出厂设置后，设备可能会显示为离线。

2025-04-09

  Home API 公开 Beta 版版本 1.2.1  

此版本修复了 bug，并提升了 Home API Android SDK 的 Beta 版质量。

最低版本

• Google Play 服务：25.09.33
• Google 集线器的最低固件版本：
  • Cast：3.75.468222
  • Fuchsia：24.20241009.103.1900601¹
• Android SDK：home.android.sdk_202503_EAP_1_2_1_RC02
• Google Home 应用：适用于任何版本
• androidx.core 库：1.10.0
• Matter 版本： 1.4.0.0

^{1. 此 build 目前正在向正式版渠道推出，并将于 2025 年 4 月 22 日之前面向所有设备提供。}

新功能

• 提升了从 Home Graph 加载对象时的性能。
• Automation API
  • 新增了对 实体过滤器的支持，该过滤器可让自动化操作根据自动化操作中指定的条件动态选择设备。
• Device API
  • 云到云设备信息现已在 BasicInformationTrait 中提供。

已知问题

• 从 Wi-Fi 切换到移动网络时，设备控制延迟可能会增加。
• 中枢恢复出厂设置后，设备可能会显示为离线。

修复的已知问题

• 如果在初始化之前或初始化完成之前调用 Discovery API，系统会抛出 HomeException，其中包含 code 14: UNKNOWN 和消息“No route found.”。
• 在包含多个结构和多个用户的环境中，切换结构和用户可能会导致未返回任何设备。

2025-03-14

  Home API 公开 Beta 版 1.2.0  

此版本修复了 bug，并提升了 Home API Android SDK 的 Beta 版质量。

最低版本

• Google Play 服务的最低版本：25.06.32
• Google Hub 固件最低版本：
  • Cast 版本：3.75.456944
  • Fuchsia 最低版本：24.20241009.103.1900601
• Android SDK：home.android.sdk_1_2_0_RC06
• Google Home 应用最低版本：适用于任何版本
• androidx.core 库最低版本：1.10.0
• Matter 版本： 1.3.0.0
  • 注意：不支持临时 Matter 设备类型和集群。

新功能

• 自动化 API：
  • 支持在自动化条件中使用日期范围和部分日期。 请参阅使用包含 between 的日期。
  • 在之前的版本中，Discovery API 本应针对某些位图字段返回 BitmapConstraint，但却返回了 NumberSetConstraint。这些字段现在会按预期返回 BitmapConstraint。这仅限于 LevelControl 特征命令中的 optionsMask 和 optionsOverride 位图。

已知问题

• 从 Wi-Fi 切换到移动网络时，设备控制延迟可能会增加。
• 中枢恢复出厂设置后，设备可能会显示为离线。
• 如果在初始化之前或初始化完成之前调用 Discovery API，系统会抛出 HomeException，其中包含 code 14: UNKNOWN 和消息“No route found.”。
  • 解决方法：仅在实际需要自动化候选对象时调用 Discovery API。不预提取和缓存候选实体。在实体上调用 Discovery API 方法之前，检查该实体是否处于在线状态。
• 在包含多个结构和多个用户的环境中，切换结构和用户可能会导致未返回任何设备。

修复的已知问题

• Home API 应用在启动后首次调用 HomeManager.structures() 时，即使存在一个或多个结构，也会收到零个结构。这会给人一种错误的印象，即 Google 账号未关联任何住宅。
• 在加载、创建和修改自动化操作时，用户可能需要等待很长时间。
• 从“相机”应用启动设置流程的用户需要扫描两次二维码才能完成 Matter 调试。
• 在包含 200 部以上设备的结构中，Discovery API 可能只会返回无候选设备。

2025-01-29

  Home API 公开 Beta 版 1.1.0  

此版本修复了 bug，并提升了 Home API Android SDK 的 Beta 版质量。

最低版本

• Google Play 服务的最低版本：25.02.32
• Google Hub 固件最低版本：
  • Cast 版本：3.75.456944
  • Fuchsia 最低版本：24.20241009.103.1900500
• Android SDK：home.android.sdk_202412_EAP_1_1_RC04
• Google Home 应用最低版本：适用于任何版本
• androidx.core 库最低版本：1.10.0
• Matter 版本： 1.3.0.0
  • 注意：不支持临时 Matter 设备类型和集群。

新功能

• Streaming API：
  • 提供事件流，用于通知已添加、更改和移除的结构、房间和设备。
  • 请参阅订阅实体关系事件。
• 批处理 API（实验性）：
  • 允许开发者批量发送多个命令，这些命令会同时执行。
  • 请参阅一次发送多条命令。

已知问题

• 在加载、创建和修改自动化操作时，用户可能需要等待很长时间。
• 从“相机”应用启动设置流程的用户需要扫描两次二维码才能完成 Matter 调试。
• 在包含 200 部以上设备的结构中，Discovery API 可能只会返回无候选设备。

修复的已知问题

• 切换已登录的 Google 账号可能会失败并导致错误。
• Google TV 设备可能无法用于使用 MediaPlayback 特征的自动化操作。
• 在仅包含 Google 集线器的结构中：
  • Matter 设备在 Google Home 应用中可能显示为离线。
  • Google 助理无法控制 Matter 设备。
  • 智能显示屏无法控制 Matter 设备或显示任何 Matter 设备的状态。
• 对于某些设备，应用可能无法始终反映准确的状态，并且您的应用报告的状态可能与 Google 应用（例如 Google Home 应用）报告的状态不同。这通常是因为设备未向 Google 报告状态。
  • 解决方法：使用 Google 应用检查状态可解决不一致问题。

2025-01-14

更新了有关 Home API 初始化的指导信息。

我们已明确指出，Home 的实例应初始化为上下文单例。这样可确保在您的应用中提供更顺畅的用户体验，并避免因会话无效而导致错误。

2025-01-07

  Home API 公开 Beta 版发布  

在公开开发者 Beta 版期间，所有开发者都可以开始构建和测试自己的应用。

此版本包含 bug 修复，并提升了 Home API Android SDK 的 Beta 版质量，包括改进了对 Google Nest Audio 和 Google TV 设备的支持。

最低版本

• Google Play 服务最低版本：24.45.34
• Google Hub 固件最低版本：
  • Cast 版本：3.74.444798
  • Fuchsia 最低版本：22.20240805.103.161
• Android SDK：home.android.sdk_202411_EAP_1_0_1_RC00
• Google Home 应用 (GHA) 最低版本：适用于任何版本
• androidx.core 库最低版本：1.10.0
• Matter 版本： 1.3.0.0
  • 注意：不支持临时 Matter 设备类型和集群。

已知问题

• 切换已登录的 Google 账号可能会失败并导致错误。
  • 解决方法：重新运行权限流程或重启应用。
• Google TV 设备可能无法用于使用 MediaPlayback 特征的自动化操作。
• 在仅包含 Google 集线器的结构中：
  • Matter 设备在 Google Home 应用 (GHA) 中可能显示为离线。
  • Google 助理无法控制 Matter 设备。
  • 智能显示屏无法控制 Matter 设备，也无法显示任何 Matter 设备的状态。
• 对于某些设备，应用可能无法始终反映准确的状态，并且您的应用报告的状态可能与 Google 应用（例如 Google Home 应用 [GHA]）报告的状态不同。这通常是由于设备未向 Google 报告状态。
  • 解决方法：使用 Google 应用检查状态可解决不一致问题。

修复的已知问题

• 如果在调试过程中将应用最小化，调试可能会失败。
  • 解决方法：使用 suppressHalfSheetNotification() API 在应用中使用 Commissioning API 时禁止显示半屏通知。
• 服务器端问题可能会导致“Ok Google”启动器无法在自动化操作中正常运行。
• 使用运行 Fuchsia 且结构中没有任何 Matter 设备的 hub 时，如果 hub 处于空闲状态超过 3 小时，调试第一个 Matter 设备会导致该 Matter 设备处于离线状态。
• 在对中枢执行恢复出厂设置后，即使设备报告为在线，向新调试的设备发送的命令也可能会失败。