星路

追寻那一缕星光,在漆黑夜晚前行

0%

【插件】HAVCS食用说明

折腾语音音箱接入控制家里设备从开始构想到现在已经两年有多了:一开始是用别人的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 proxy模式

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

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


2. 教程传送门

旧版本已不更新,留个备查入口,建议使用v3版本


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到公网,减少安全风险
  • 测试建议

    • 调整插件的日志等级为DEBUG,重点关注授权过程是否有产生错误日志
    • 本地环境测试访问插件的授权页面(使用HA的ip),确保能访问(说明插件正常启动)
    • 外网环境(可使用手机数据)测试访问授权页面(使用域名),确保:1、能访问(说明反代正常工作并且网络正常);2、没有不安全连接告警(说明证书正常)
  • 证书相关补充

    • 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服务,即可在网页设备管理界面看到新的设备信息。