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

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


0.插件说明

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

  • 增加集成方式管理插件配置,无需重启HA
  • 增加web管理设备页面
  • 调整设备的信息属性设计和生成逻辑,作为集成的“设备”呈现而不是“组件”呈现

1.使用说明

1.1.APP的技能方式接入

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

  • 下载havcs插件,放置到HA自定义插件目录,最终路径结构为{HA配置目录}/custom_components/havcs/__init__.py
  • 前往页面注册账号,获取AppKey和AppSecret(先登录再生成,生成后记得保存)。
  • 音箱APP->搜索’havcs’技能->关联账号->输入注册的账号信息登录。
  • 配置Home Assistant

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    # {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 >>*新版本调整<<

    WARN:新版本调整 device_config由原来设置设备信息文件路径更改为设置设备管理模式,设备信息文件保存路径{HA配置目录}/havcs.yaml或havcs-ui.yaml

  • 配置设备信息
    目前支持两种管理方式,这里以文本编辑模式介绍,web管理见4.UI管理章节

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    # 配置文件整体结构({HA配置目录}/havcs.yaml)
    设备1的device_id: # 格式havcs.xxx
    属性1:
    属性2:
    设备2的device_id:
    属性1:
    属性2:
    设备N的device_id:
    属性1:
    属性2:

    WARN:新版本调整 顶层id由entity_id更改为可自定义的device_id,entity_id放到属性中去
    INFO:具体属性名称见第2章节。

    1
    2
    3
    4
    5
    # 一个设备配置样例
    havcs.a_demo_light:
    entity_id: light.demo # 关联真实设备
    name: 主卧灯
    zone: 主卧

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

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

1.2.自建技能方式接入

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

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    # {HA配置目录}/configuration.yaml                 
    havcs:
    platform: # 音箱平台服务网关,至少启用一个
    - aligenie # 天猫精灵
    - dueros # 小度
    - jdwhale # 叮咚
    http:
    ha_url: https://localhost:8123 # HA所在主机/容器IP地址,不设置则默认识别
    expire_in_hours: 24 # token超时时间,单位小时,不设置则默认24h
    device_config: ui # 设备管理模式,text为原来文本编辑,ui为启用web管理页面。不设置默认text >>*新版本调整<<
  • 配置设备信息及更新音箱平台设备信息同上章节


2.设备信息属性说明

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

  • 设备统一使用属性进行配置,属性列表如下:
属性名 描述 取值 样例 备注
visable 设备可见性 [‘aligenie’, ‘dueros’, ‘jdwhale’] [‘aligenie’, ‘dueros’] 设置该属性则设备只对指定平台可见;如不设置,对所有平台可见
entity_id 关联真实设备 - [‘light.demo’, ‘group.demo’] 必填,group配合type使用,会搜索加入该分组下的匹配的entity
name 设备名称 *天猫精灵限制 客厅灯 必填,建议“房间”+“设备类型”可以兼容三个平台使用
zone 设备位置 *天猫精灵限制 客厅 天猫精灵必填,其它可不用指定
type 设备类型 light /switch /sensor /input_boolean light 一般不用指定
attributes 属性 [‘temperature’, ‘brightness’, ‘humidity’, ‘pm25’, ‘co2’, ‘power_state’] [‘power_state’] 一般不用指定
actions 支持操作 [‘turn_on’, ‘turn_off’, ‘timing_turn_on’, ‘timing_turn_off’, ‘query_temperature’, ‘query_humidity’, ‘increase_brightness’, ‘decrease_brightness’] [‘turn_on’, ‘turn_off’] 一般不用指定

WARN:新版本调整 增加entity_id;传感器删除related_sensors改用entity_id关联;属性名称简化掉havcs_开头
INFO:属性字典的格式为”属性名: 取值”,需要有1个空格间隔。

2.1 自定义指令操作

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

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

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    #{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']

    INFO:调自动化(automation.turn_on)、调脚本(scrpit.turn_on)、调红外指令(climate.xiaomi_miio_send_command)等会比较适合。
    INFO:天猫精灵无法自定义名称,不太适合使用。


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 调低亮度

INFO:延时打开/关闭需配合通用定时器插件实现。


4.控制指令说明

  • 叮咚

    • 打开/关闭

      1
      2
      3
      4
      #打开/关闭
      #用途:一般为电源控制
      #语义:打开/关闭{设备名称}
      #例子:打开主卧灯
    • 查询状态

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

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

  • 天猫精灵

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

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

    • 查询状态
      1
      2
      3
      4
      #打开/关闭
      #用途:查询设备状态
      #语义:查询{房间名}{设备类型/别名}的{状态/xx状态}
      #例子:查询主卧传感器的状态;查询主卧传感器的温度

    INFO:查询传感器好像有个bug:查询所有状态不能正常播报;查询单个状态,发送的指令是查询所有状态的指令。

  • 小度

    • 打开/关闭
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      #打开/关闭
      #用途:一般为电源控制
      #语义:打开/关闭{设备名称}
      #例子:打开主卧灯
      ```
      - 查询状态
      ```yaml
      #打开/关闭
      #用途:查询设备状态
      #语义:查询{设备名称}的{xx状态}/{设备名称}查询{xx状态}
      #例子:查询主卧传感器的温度/主卧传感器查询温度

    INFO:只能查询单一状态。


4.UI管理

  • 启停插件/修改插件配置
  1. 进入集成管理界面
    WEB界面->侧边栏配置->集成
  2. 新增配置
    点右下角加号->搜索HAVCS,按界面提示新增配置
  3. 修改配置
    集成页面点击HAVCS: 主配置->右上角删除,删除后再新增
  • 设备信息管理
  1. 进入管理页面
    WEB界面->侧边栏HAVCS设备
  2. 编辑后,需要执行一次havcs.reload服务才能加载新的设备信息

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

5.调试说明

  • 把havcs插件日志级别提高,过滤其它插件输出日志,方便观察日志输出,调试后注意恢复
    1
    2
    3
    4
    5
    # [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设备配置信息

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


6.小结

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