【插件】智能音箱接入Home Assistant整合PlusPlus

自从上一版实现了不用重启可以更新设备信息，后来发现可以通过HA集成管理的页面实现不重启修改插件配置，于是乎折腾实现了，然后想着既然插件配置能用UI管理了，干脆也把设备信息管理UI化管理吧。一开始计划是弄个在线文本编辑器直接编辑的，某天逛论坛看到jiluxinqing大大的帖子已经有成品了，然后研究了下学习到了前后端交互的方法，干脆就把以前的设备管理页面改造改造给用上了。这个版本也算是实现从“能用”到“易用”的一个跨越。

---

0. 插件说明

此为HAVCS(Home Assistant Voice Control Skill)v3版本，主要改动：

• 增加集成方式管理插件配置，无需重启HA
• 增加web管理设备页面
• 调整设备的信息属性设计和生成逻辑，作为集成的“设备”呈现而不是“组件”呈现
• 增加授权页面（可自定义客户端ID）>>*2020.04.05增加
• 调整各服务url进同一层级（/havcs/）>>*2020.04.05增加

---

1. 使用说明

1.1. APP的技能方式接入

使用官方APP技能，配合havcs服务可实现免公网IP接入。

• 下载havcs插件，放置到HA自定义插件目录，最终路径结构为{HA配置目录}/custom_components/havcs/__init__.py。

• 前往havcs服务页面注册账号，获取AppKey和AppSecret（先登录再生成，生成后记得保存）。

• 打开音箱APP（天猫精灵、小度、叮咚音箱/小京鱼）-> 搜索找到’havcs’技能 -> 关联账号 -> 输入注册的账号信息登录。

  注意

  新版（4.12.1）天猫精灵app技能绑定入口有点隐蔽，在APP里的首页->技能发现->输入搜索即可。

• 配置Home Assistant

  # {HA配置目录}/configuration.yaml
  havcs:
    platform:                               # 音箱平台服务网关，至少启用一个
      - aligenie                            # 天猫精灵
      - dueros                              # 小度
      - jdwhale                             # 叮咚
    skill:
      bind_device: True                     # 是否启动时更新设备绑定信息。不设置默认True（叮咚音箱才有效）>>*新版本加入<<
      sync_device: False                    # 是否主动上报设备状态。不设置默认False（小度音箱才有效）
    # mqtt相关设置，启用http代理服务及APP技能服务才生效
    setting:
      app_key: your_app_key                 # 注册账号获取的AppKey
      app_secret: your_app_secret           # 注册账号获取的AppSecret
      entity_key: your_entity_key           # 加密entity_id的key，自定义16个字符。不设置则不加密
    device_config: ui                       # 设备管理模式，text为原来文本编辑，ui为启用web管理页面。不设置默认text >>*新版本调整<<

新版本调整

device_config由原来设置设备信息文件路径更改为设置设备管理模式，设备信息文件保存路径{HA配置目录}/havcs.yaml或havcs-ui.yaml。

• 配置设备信息
  目前支持两种管理方式，这里以文本编辑模式介绍，具体属性名称见2.设备信息属性说明章节，web管理方式见4.UI管理章节

  # 配置文件整体结构（{HA配置目录}/havcs.yaml）
  设备1的device_id: # 格式havcs.xxx
    属性1:
    属性2:
  设备2的device_id:
    属性1:
    属性2:
  设备N的device_id:
    属性1:
    属性2:
  
  # 一个设备配置样例
  havcs.a_demo_light:
    entity_id: light.demo # 关联真实设备
    name: 主卧灯
    zone: 主卧

新版本调整

顶层id由entity_id更改为可自定义的device_id，entity_id放到属性中去。

调试建议

请确保HA中该设备已正常接入（开发者工具->状态有该设备的entity_id）,sensor.类型除外。

• 更新音箱平台设备信息
  • 先重载本地信息：调用服务（HA web->开发者工具->服务->调用havcs.reload）或者重启HA
  • 叮咚：首次通过APP重新绑定账号触发更新，后续可通过重载本地信息触发上报更新（bind_device配置为True）。
  • 天猫精灵：APP中重新绑定触发更新。
  • 小度：执行“发现设备”指令触发更新。

1.2. 自建技能方式接入

• 音箱技能配置见总教程
• 配置Home Assistant

  # {HA配置目录}/configuration.yaml
  havcs:
    platform:                               # 音箱平台服务网关，至少启用一个
      - aligenie                            # 天猫精灵
      - dueros                              # 小度
      - jdwhale                             # 叮咚
    http:
      clients:                              # 音箱平台客户端认证信息（使用插件的授权页面）。其节点下的键值对代表"client_id: client_secret"，其中client_id起始字符会匹配音箱平台，音箱平台上设置要与此处设置一致
        dueros{自定义字符}: {自定义密码}      # 小度平台认证信息，样例：duerosdemo: 123 代表client_id为duerosdemo，client_secret为123
        aligenie{自定义字符}: {自定义密码}    # 天猫精灵平台认证信息，样例：aligeniedemo: 123 代表client_id为aligeniedemo，client_secret为123
        jdwhale{自定义字符}: {自定义密码}     # 叮咚平台认证信息，样例：jdwhaledemo: 123 代表client_id为jdwhaledemo，client_secret为123
        aligenie_ignore: ignore             # PS: 如果不使用插件授权页面，也要随意设置一个键值对
      ha_url: http://localhost:8123         # HA主机本地访问地址，如果HA没配置base_url（http:组件里），可自动识别不用设置；（建议）否则设置http://localhost:{端口号} 或 https://localhost:{端口号}（HA启用ssl）
      expire_in_hours: 24                   # token超时时间，单位小时，不设置则默认24h
    device_config: ui                       # 设备管理模式，text为原来文本编辑，ui为启用web管理页面。不设置默认text >>*新版本调整<<

ha_url属性

ha_url通过HA内置方法自动识别时，由于新版HA会优先读取旧版本.storage/core.config的url配置，可能会因此导致不准确，建议配置。

- 配置设备信息及更新音箱平台设备信息同`1.1.APP的技能方式接入`章节。

---

2. 设备信息属性说明

支持文本编辑（{HA配置目录}/havcs.yaml）或web管理页面配置设备信息，用于生成音箱平台的设备（绑定设备）。

• 设备统一使用属性进行配置，属性列表如下：

属性名	描述	取值	样例	备注
havcs_visable	设备可见性	[‘aligenie’, ‘dueros’, ‘jdwhale’]	[‘aligenie’, ‘dueros’]	设置该属性则设备只对指定平台可见；如不设置，对所有平台可见
havcs_device_name	设备名称	*天猫精灵有限制	客厅灯	必填，建议“房间”+“设备类型”可以兼容三个平台使用；天猫精灵APP已支持自定义设备名称，与该处设置无关
havcs_zone	设备位置	*天猫精灵有限制	客厅	天猫精灵必填，其它可不用指定
havcs_device_type	设备类型	light /switch /sensor /input_boolean	light	一般不用指定
havcs_attributes	属性	[‘temperature’, ‘brightness’, ‘humidity’, ‘pm25’, ‘co2’, ‘power_state’]	[‘power_state’]	一般不用指定
havcs_actions	支持操作	[‘turn_on’, ‘turn_off’, ‘timing_turn_on’, ‘timing_turn_off’, ‘query_temperature’, ‘query_humidity’, ‘increase_brightness’, ‘decrease_brightness’]	[‘turn_on’, ‘turn_off’]	一般不用指定
havcs_related_sensors	传感器设备专用，关联真实传感器	sensor/group列表	[‘sensor.demo’, ‘group.demo’]	支持设置group，会搜索加入该分组下的sensor

新版本调整

增加entity_id；传感器删除related_sensors改用entity_id关联；属性名称简化掉havcs_开头。

格式

使用yaml语法，注意"属性名: 取值"需要有1个空格间隔。

2.1. 自定义指令操作

可通过设置actions属性，实现指定指令调用自定义的service。

• actions属性中设置对应的service指令（只能设置turn_on/turn_off/timing_turn_on/timing_turn_off/increase_brightness/decrease_brightness，对应打开/关闭/延时打开/延时关闭/调高亮度/调低亮度指令）

  #{HA配置目录}/havcs.yaml
  havcs.a_demo_call_service:  
    name: 客厅灯
    zone: 客厅
    #↓↓↓指令根据实际需要配置↓↓↓
    havcs_actions:
        # service指令格式:[domain, service_name, service_data（json字符串）]，具体内容需参见相应组件的服务定义。
        # 注意，参数变更为数组以支持多条指令，单条指令也别忘了加-
        turn_on:
          - ['common_timer', 'set', '{"entity_id":"switch.demo","duration":"01:00:00","operation":"off"}'] # 打开命令
          - ['input_boolean', 'turn_on', '{}'] # 同步打开状态
        turn_off:
          - ['common_timer', 'cancel', '{"entity_id":"switch.demo"}'] # 关闭命令
          - ['input_boolean', 'turn_off', '{}'] # 同步关闭状态
        timing_turn_on:         # 延时打开指令（小度音箱）
          - ['指令1']
          - ['指令2']
        timing_turn_off:        # 延时关闭指令（小度音箱）
          - ['指令1']
          - ['指令2']
        increase_brightness:
          - ['指令1']
          - ['指令2']
        decrease_brightness:
          - ['指令1']
          - ['指令2']

使用建议

调自动化(automation.turn_on)、调脚本(scrpit.turn_on)、调红外指令(climate.xiaomi_miio_send_command)等会比较适合。

天猫精灵无法自定义名称，不太适合使用。

---

3. 完成度

目前完成度有些低，后续再继续测试完善吧。

• 图例：✓ 支持，- 不支持，* 待测试
• switch/cover

操作	描述	aligenie	dueros	jdwhale
turn_on	打开	✓	✓	✓
turn_off	关闭	✓	✓	✓
timing_turn_on	延时打开	-	✓	-
timing_turn_off	延时关闭	-	✓	-

• light

操作	描述	aligenie	dueros	jdwhale
turn_on	打开	✓	✓	✓
turn_off	关闭	✓	✓	✓
timing_turn_on	延时打开	-	✓	-
timing_turn_off	延时关闭	-	✓	-
set_brightness	设置亮度	*	*	*
increase_brightness	调高亮度	✓	✓	✓
decrease_brightness	调低亮度	✓	✓	✓
set_color	设置颜色	*	✓	*

• sensor

操作	描述	aligenie	dueros	jdwhale
query_temperature	查询温度	✓	✓	✓
query_humidity	查询湿度	✓	✓	✓

• inpu_boolean

操作	描述	aligenie	dueros	jdwhale
turn_on	打开	✓	✓	✓
turn_off	关闭	✓	✓	✓
timing_turn_on	延时打开	-	✓	-
timing_turn_off	延时关闭	-	✓	-
increase_brightness	调高亮度	✓	✓	✓
decrease_brightness	调低亮度	✓	✓	✓

延时功能

延时打开/关闭需配合[通用定时器插件][7]实现。

---

4. 控制指令说明

• 叮咚
  • 打开/关闭

    #打开/关闭
    #用途：一般为电源控制
    #语义：打开/关闭{设备名称}
    #例子：打开主卧灯

  • 查询状态

    #打开/关闭
    #用途：查询设备状态
    #语义：查询{设备名称}的{状态/xx状态}
    #例子：查询主卧传感器的状态；查询主卧传感器的温度；查询主卧灯的电源状态

    使用建议

    传感器信息需要挂靠到具体设备上进行查询。一般来说温度、湿度需要挂靠到空气净化器类型上。

• 天猫精灵
  • 打开/关闭

    #打开/关闭
    #用途：一般为电源控制
    #语义：打开/关闭{房间名}的{设备类型/别名}
    #例子：打开主卧的灯。
    #备注：{房间名}、{设备类型/别名}需要指定，均为枚举值

    使用建议

    优先匹配“位置（可为空）+别名”：例如有台灯、灯两个设备，“打开台灯”则精确匹配台灯；然后匹配“位置（可为空）+设备类型”，例如有一个台灯设备，“打开吸顶灯”、“打开床头灯”等都可控制。指令不带位置，如设备别名多个匹配，询问设备位置；当有相同匹配，一起执行。

  • 查询状态

    #打开/关闭
    #用途：查询设备状态
    #语义：查询{房间名}{设备类型/别名}的{状态/xx状态}
    #例子：查询主卧传感器的状态；查询主卧传感器的温度

    补充

    查询传感器好像有个bug：查询所有状态不能正常播报；查询单个状态，发送的指令是查询所有状态的指令。

• 小度
  • 打开/关闭

    #打开/关闭
    #用途：一般为电源控制
    #语义：打开/关闭{设备名称}
    #例子：打开主卧灯

  • 查询状态

    #打开/关闭
    #用途：查询设备状态
    #语义：查询{设备名称}的{xx状态}/{设备名称}查询{xx状态}
    #例子：查询主卧传感器的温度/主卧传感器查询温度

    补充

    只能查询单一状态。

---

5. UI管理

• 启停插件/修改插件配置
  1.进入集成管理界面
  WEB界面->侧边栏配置->集成
  2.新增配置
  点右下角加号->搜索HAVCS，按界面提示新增配置
  3.修改配置
  删除后再新增：集成页面点击HAVCS: 主配置->右上角删除；或直接新增也会提示删除

设置优先级

通过集成管理web页面进行的设置优先级别更高会覆盖配置文件的设置，具体生效配置可以在havcs设备管理页面->工具栏”插件配置”查看。

• 设备信息管理
  1.进入管理页面
  WEB界面->侧边栏HAVCS设备
  2.编辑后，需要点击菜单栏的同步设备按钮或执行一次havcs.reload服务才能加载新的设备信息

补充

web管理设备信息只是取代之前的文本编辑，刷新设备信息的步骤暂时不变，设备信息会保存至{HA配置目录}/havcs-ui.yaml。

---

6. 调试说明

• 把havcs插件日志级别提高，过滤其它插件输出日志，方便观察日志输出，调试后注意恢复

  # [HA配置目录]/configuration.yaml
  logger:
    default: error  # 提高所有组件的默认级别，调试完后改回info（预设）
    logs:           # 设定指定组件的级别，debug有更详细的输出
      custom_components.havcs: debug

  1.根据教程设置好插件的日志级别，找到运行日志，再逐步操作观察所产生日志进行排查，着重检查以下几个步骤
  2.配置好插件，启动HA后，观看是否有mqtt连接成功信息（app技能接入方式） —排查插件配置信息
  3.授权过程，观看是否有相关的处理日志 —排查授权服务
  4.说音响指令后，观看是否有相关的处理日志 —排查语音平台接入
  5.web页面->开发者工具->服务->havcs.reload，观看是否生成设备信息 —排查havcs.yaml设备配置信息

调试建议

如需要帮助，请提供以上步骤相对应的日志信息方便定位原因。

---

7. 小结

• 发现集成（Integration）这个新大陆，又被迫读了不少代码去分析，补充了HA的组件加载过程链的知识盲区。
• 使用Vue改造了以前的设备管理页面实现了单页面管理，感觉效果还可以。