折腾语音音箱接入控制家里设备从开始构想到现在已经两年有多了:一开始是用别人的PHP版天猫精灵网关尝了鲜;然后有了想整合多个音箱平台接入的想法,于是尝试搭建过nodered版本网关;再后来想着自定义技能方式更方便不同平台的接入,又折腾出一个整合版PHP网关并想着提供APP技能方便使用,结果审核翻车了,考虑到自用部署过于复杂就没发布了;然后恰好碰上单平台插件版网关的出现,然后做了HAVCS整合插件,为了进一步简化使用,目前迭代了2个版本,考虑到使用方法变化较大,特意整了这个汇总版的说明。
1. HAVCS是什么
含义:
HAVCS全称为Home Assistant Voice Control Skill,诣在提供Home Assistant对接音箱平台的能力,通过在Home Assistant上运行本插件,可对接音箱厂家的技能开放平台(自建技能或用线上技能),响应音箱指令控制相关设备。
本插件实际上由两大功能模块组成:
MQTT对接服务
配合本人搭建的mqtt中转服务,可以将音箱云平台的音箱命令消息、oauth消息转发到无公网环境下家中的Home Assistant。音箱组件
即智能音箱本地网关插件,对音箱云平台的音箱命令消息进行解析、处理,可以初始化为HTTP网关服务与音箱云平台直接对接。
有三种使用模式,适合不同场景的接入:模式一 http模式
- 生成音箱http网关,通过
平台自建的测试技能
接入 - 适合家庭宽带
有公网ip
或已实现内网穿透
场景下使用 - 建议有条件、不怕折腾就用这个,留服务资源给有需要的人
- 生成音箱http网关,通过
模式二 http proxy模式
- 生成音箱http网关,同时使用mqtt代理穿透内网访问,通过
平台自建的测试技能
接入 - 适合家庭宽带
无公网ip
场景下使用 - 临时提供,视服务资源情况会停止
- 生成音箱http网关,同时使用mqtt代理穿透内网访问,通过
模式三 skill模式
- 通过
官方音箱APP技能
接入,目前技能已上线叮咚、天猫精灵、小度
- 适合
无公网
、简单接入
场景使用 - 服务资源有限不能保证稳定
- 通过
各模式难度指数
模式一:★★★★☆
模式二:★★☆☆☆
模式三:★☆☆☆☆
2. 教程传送门
旧版本已不更新,留个备查入口,建议使用v3版本
- HAVCS v1: > 使用说明 > 下载地址
基于单插件版本简单整合、设备信息通过customize.yml配置 - HAVCS v2: > 使用说明 > 下载地址
初步统一设备定义、设备信息通过独立havcs.yml配置 - HAVCS v3: > 使用说明 > 下载地址
实现全UI管理:集成方式配置插件、web网页管理设备
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
叮咚:https://alphadev.jd.com
#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,在插件配置文件定义
与插件(配置文件)所设置的一致Client Id和Client Secret
方案一授权过程要求Client Id与重定向url头段(scheme://host:port)一致,不校验Client Secret。
方案二授权过程要求Client Id和Client Secret与设置的一致。
实践建议
- 外网服务地址需要使用https,https证书使用腾讯云、阿里云或者Let’s Encrypt等兼容性好的,并注意有效期,
证书不匹配域名或失效也会导致授权失败
- 部署nginx或apache反向代理访问HA,在nginx上配置https,本地可以保留http访问HA
- 如无外网访问HA需求,建议使用插件的授权页面,只反代/havcs/层级uri到公网,减少安全风险
- 外网服务地址需要使用https,https证书使用腾讯云、阿里云或者Let’s Encrypt等兼容性好的,并注意有效期,
测试建议
- 调整插件的日志等级为DEBUG,重点关注
授权过程
是否有产生错误日志 - 本地环境测试访问插件的授权页面(使用HA的ip),确保能访问(说明插件正常启动)
- 外网环境(可使用手机数据)测试访问授权页面(使用域名),确保:1、能访问(说明反代正常工作并且网络正常);2、没有不安全连接告警(说明证书正常)
- 调整插件的日志等级为DEBUG,重点关注
证书相关补充
- Let’s Encrypt申请下来证书有四种:cert.pem(证书)、chain.pem(中间证书)、fullchain.pem(证书&中间证书)、privkey.pem(私匙)
- 腾讯云申请下来证书有好几个目录,如果需要分开的证书用Apache目录:1_root_bundle.crt(中间证书)、2_havcs.ljr.im.crt(证书)、3_havcs.ljr.im.key(私匙)。如果需要合并的证书用Nginx目录:1_havcs.ljr.im_bundle.crt(证书&中间证书)、2_havcs.ljr.im.key(私匙)
- 群晖配置反向代理/Apache配置,需要三个文件,按
私匙、证书、中间证书
设置对应文件 - HA设置https/Nginx配置,需要两个文件,按
私匙、证书&中间证书
设置对应文件服务端证书配置
不同服务端软件的证书配置有差异:有的单独设置了"中间证书"项,有的则合并一个"证书&中间证书"项。但一样的是,服务端需要提供完整的证书(证书链)才能让客户端(一般是浏览器)追溯到内置的可信根证书完成验证。所以不同机构颁发的证书文件名有差异,只要理解其实际内容即可,实际上"证书&中间证书"文件就是"证书"文件内容追加"中间证书"文件内容组成。
详细设置可参考以下教程
小度音箱接入hass详细过程
小度音箱接入HomeAssistant采用自带OAuth访问控制
智能音箱接入Home Assistant内网穿透frp相关配置
4. 设备信息v2至v3迁移
v3版本的属性有一些小调整,可以将v2版本的{HA配置目录}/havcs.yml
里面旧的设备信息按照新格式调整好后,保存为{HA配置目录}/havcs-ui.yml
,执行一次havcs.reload
服务,即可在网页设备管理界面看到新的设备信息。