【插件】HAVCS食用说明

折腾语音音箱接入控制家里设备从开始构想到现在已经两年有多了:一开始是用别人的PHP版天猫精灵网关尝了鲜;然后有了想整合多个音箱平台接入的想法,于是尝试搭建过nodered版本网关;再后来想着自定义技能方式更方便不同平台的接入,又折腾出一个整合版PHP网关并想着提供APP技能方便使用,结果审核翻车了,考虑到自用部署过于复杂就没发布了;然后恰好碰上单平台插件版网关的出现,然后做了HAVCS整合插件,为了进一步简化使用,目前迭代了2个版本,考虑到使用方法变化较大,特意整了这个汇总版的说明。


1. HAVCS是什么

含义:
全称为Home Assistant Voice Control Skill,诣在提供Home Assistant对接音箱平台的能力,通过在Home Assistant上运行本插件,可对接音箱厂家的技能开放平台(自建技能或用线上技能),响应音箱指令控制相关设备。
本插件实际上由两大功能模块组成:

  • MQTT对接服务

    配合本人搭建的mqtt中转服务,可以将音箱云平台的音箱命令消息、oauth消息转发到无公网环境下家中的Home Assistant。

  • 音箱组件

    即智能音箱本地网关插件,对音箱云平台的音箱命令消息进行解析、处理,可以初始化为HTTP网关服务与音箱云平台直接对接。

有三种使用模式,适合不同场景的接入:

  • 模式一 http模式

    • 生成音箱http网关,通过自建测试技能接入
    • 适合家庭宽带有公网ip或已实现内网穿透场景下使用
    • 建议有条件、不怕折腾就用这个,留服务资源给有需要的人
  • 模式二 http proxy模式

    • 生成音箱http网关,同时使用mqtt代理穿透内网访问,通过自建测试技能接入
    • 适合家庭宽带无公网ip场景下使用
    • 临时提供,视服务资源情况会停止
  • 模式三 skill模式

    • 通过官方音箱APP技能接入,目前技能已上线叮咚、天猫精灵、小度
    • 适合无公网省事场景使用
    • 服务资源有限不能保证稳定
  • 各模式难度指数

    模式一:★★★★☆

    模式二:★★☆☆☆

    模式三:★☆☆☆☆


2. 教程传送门

3. 关于自建技能

自建技能需要额外两个步骤,因涉及较多的知识及不同的环境存在差异,本人只能作简单指引

  • 将本地HA服务网址发布到公网

    申请域名、申请域名https证书、路由器设置DDNS(域名绑定)、路由器设置端口转发访问HA

  • 音箱技能平台的配置

    平台需要填写三种url:授权地址,Token地址,Service地址。根据选用授权地址不同,有以下两种填写方案:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    #方案一 使用HA自带的授权页面

    #授权页面网址
    https://{你的域名及端口}/auth/authorize

    #Token页面网址
    https://{你的域名及端口}/havcs/auth/token(v3版)
    https://{你的域名及端口}/havcs_auth(v2版)
    https://{你的域名及端口}/aihome_auth(v1版)

    #WebService(服务网关)网址
    https://{你的域名及端口}/havcs/service(v3版)
    https://{你的域名及端口}/havcs_auth(v2版)
    https://{你的域名及端口}/aihome_service(v1版)

    #Client Id,填回调地址域名那一串即可(HA要求格式)
    小度:https://xiaodu.baidu.com
    天猫:https://open.bot.tmall.com
    叮咚:不支持,因为平台不允许client_id为"https://"开头

    #Client Secret
    随便填写,不做校验
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
#方案二 使用插件的授权页面(v3 2020.04.05后版本增加)

#授权页面网址
https://{你的域名及端口}/havcs/auth/authorize

#Token页面网址
https://{你的域名及端口}/havcs/auth/token

#WebService(服务网关)网址
https://{你的域名及端口}/havcs/service

#Client Id,在插件配置文件定义
与插件(配置文件)所设置的一致

#Client Secret,在插件配置文件定义
与插件(配置文件)所设置的一致
  • 实践建议

    • 外网服务地址需要使用https,https证书使用腾讯云、阿里云或者Let’s Encrypt等兼容性好的,并注意有效期
    • 部署nginx或apache反向代理访问HA,在nginx上配置https,本地可以保留http访问HA
    • 先本地测试可访问插件授权页面(插件正常启动),再外网测试(手机数据链接访问)可访问插件授权页面(反代正常工作)
    • 如无外网访问HA需求,建议使用插件授权页面,只反代/havcs/层级uri到公网
  • 详细设置可参考以下教程
    小度音箱接入hass详细过程
    小度音箱接入HomeAssistant采用自带OAuth访问控制

4. 设备信息v2至v3迁移

v3版本的属性有一些小调整,可以将v2版本的{HA配置目录}/havcs.yml里面旧的设备信息按照新格式调整好后,保存为{HA配置目录}/havcs-ui.yml,执行一次havcs.reload服务,即可在网页设备管理界面看到新的设备信息。