ha-google-home 项目技术解析与实践指南

项目核心架构解析

ha-google-home 作为 Home Assistant 的自定义组件，采用模块化设计实现与 Google Home 设备的深度集成。核心架构围绕设备数据管理与服务交互两大主线构建，通过分层设计实现功能解耦。

核心模块交互流程

组件采用"配置-数据-实体"三层架构：

1. 配置层：通过 config_flow.py 处理用户认证与初始化参数设置，生成持久化配置项
2. 数据层：api.py 实现与 Google Home 设备的通信协议，models.py 定义设备状态数据结构
3. 实体层：sensor.py/switch.py/number.py 将设备数据转化为 Home Assistant 标准实体

模块间通过事件驱动模式协作：配置流程完成后触发设备发现，API 模块定期轮询设备状态，状态更新通过 entity.py 定义的基础类同步到各类实体组件。

关键文件功能详解

1. 核心配置模块

🔧 manifest.json - 组件元数据定义

{
  "domain": "google_home",        // 组件唯一标识
  "config_flow": true,            // 启用配置流程
  "requirements": [               // 依赖库声明
    "glocaltokens==0.2.4",        // Google Home 认证库
    "httplib2==0.19.0",           // HTTP 通信库
    "zeroconf==0.36.2"            // 设备发现协议
  ]
}

该文件决定组件加载方式及依赖管理，requirements 字段声明的库会在组件初始化时自动安装。

🔧 config_flow.py - 配置流程控制器 实现 OAuth 认证流程与设备配对逻辑，核心方法 async_step_user 处理用户凭证输入，通过 _get_master_token 和 _get_access_token 完成 Google 账户认证。配置完成后生成的令牌会存储在 Home Assistant 配置存储中。

2. 设备通信模块

🔌 api.py - 设备通信核心 提供与 Google Home 设备交互的完整接口集，关键功能包括：

• async_get_master_token/async_get_access_token: 处理 Google 账户认证
• get_google_devices: 发现局域网内的 Google Home 设备
• update_alarms_and_timers: 同步设备闹钟与计时器状态
• reboot_google_device: 远程重启设备

设备通信采用 REST API 与 mDNS 发现结合的方式，通过 zeroconf 实现局域网设备自动发现，glocaltokens 库处理认证令牌管理。

3. 数据模型与实体

📊 models.py - 设备数据模型 定义 GoogleHomeDevice 核心类，封装设备基本信息与状态管理：

class GoogleHomeDevice:
    def __init__(self, device_id, name, auth_token):
        self.device_id = device_id  # 设备唯一标识
        self.name = name            # 设备名称
        self.auth_token = auth_token # 访问令牌
        # 状态属性
        self.alarms = []
        self.timers = []
        self.do_not_disturb = False

提供 get_next_alarm()、set_do_not_disturb() 等方法封装设备状态操作。

⚙️ 实体实现

• 传感器 (sensor.py): 实现闹钟、计时器、设备状态等信息采集
• 开关 (switch.py): 控制"勿扰模式"等二进制状态
• 数字控制 (number.py): 调节闹钟音量等数值型参数

所有实体继承自 entity.py 中定义的 GoogleHomeBaseEntity，统一实现设备状态同步与属性管理。

配置实践指南

1. 环境准备

# 克隆项目到 Home Assistant 自定义组件目录
git clone https://gitcode.com/gh_mirrors/ha/ha-google-home
cd ha-google-home

2. 组件安装

将 custom_components/google_home 目录复制到 Home Assistant 配置目录的 custom_components 文件夹下，重启 Home Assistant 后通过配置界面添加组件。

3. 服务调用示例

设备状态刷新

service: google_home.update_devices
target:
  entity_id: google_home.living_room_speaker

设置勿扰模式

service: switch.turn_on
target:
  entity_id: switch.living_room_speaker_do_not_disturb

典型应用场景

1. 智能家居联动

通过传感器获取 Google Home 设备状态，实现场景自动化：

• 当检测到"下一个闹钟"状态变化时，自动开启卧室灯光
• 基于设备在线状态判断家人是否在家，联动安防系统

2. 远程设备管理

利用 api.py 提供的远程控制能力：

• 定时检查儿童房间的 Google Home 设备使用时长
• 离家时通过服务调用远程重启不稳定的设备

3. 数据统计与分析

通过传感器收集的历史数据：

• 分析家庭成员使用 Google Home 的习惯
• 统计闹钟设置频率与作息规律

该组件通过清晰的模块化设计，将 Google Home 设备功能无缝集成到 Home Assistant 生态系统，为智能家居场景提供了丰富的扩展可能。核心代码路径可参考：设备管理、API通信、实体实现。