iFLYOS文档学习笔记

一、什么是智能硬件开放平台？为什么要开放？
我们生活中，已经实现了人与人之间的连接，现在需要将人与机器设备连接，这就需要一套完整的系统和连接规则，那么这么好的系统为什么要开放给大家使用呢？其实之前通过学习Google的tensorflow框架了解到，开放出来其实是为了打造一个属于自己的生态，扩大自己的范围，我们认为机器学习是未来新产品和新技术的一个关键部分。在这一个领域的研究是全球性的，并且发展很快，却缺少一个标准化的工具。通过分享这个我们认为是世界上最好的机器学习工具库之一的东东，我们希望能够创造一个开放的标准，来促进交流研究想法和将机器学习算法产品化。Google的工程师们确实在用它来提供用户直接在用的产品和服务，而Google的研究团队也将在他们的许多科研文章中分享他们对Tensorflow的使用。

二、设备接入介绍
1.iflyos架构

二、控制台设备管理
通过控制台，设备接入者可以自己定义设置自己想要的实现功能。
1.client_id将会被iFLYOS用于判定设备型号，一个型号的设备（比如叮咚音箱mini2）都会使用相同的client_id。
2.控制台设备管理包括注册账号、登录账号、创建设备、云端配置、集成测试、自动更新设备的版本号、设备认证。

三、拦截器
1.前拦截器：可以在用户请求进入iflyos技能之前，对用户的请求进行拦截。当你配置了前拦截器，我们会生成一个PreInterceptorRequest，发送到拦截器的地址更具拦截器的响应作进一步的端指令处理。
2.后拦截器：当iflyos技能无法处理用户请求（即用户语料未能命中任意技能）时，如果你配备了后拦截器，那么我们会生成一个PostInterceptorRequest发送到你的拦截器，再根据拦截器响应做进一步的端指令处理。

四、儿童模式
设备在儿童模式下，与通用模式存在以下区别：
设备将不会请求到不适合儿童收听和查看的技能和内容；
设备将优先请求到与儿童需求匹配的技能和内容；
设备将更换发音人为儿童发音人。
如果你开发的设备主要面向家庭场景，我们建议你打开儿童模式的开关。当你在设备控制台打开开关后，用户可以在APP中打开和关闭儿童模式。

五、持续交互
持续交互就是不用询问时每次都需要唤醒，在打开持续交互的情况下，用户与设备之间的语音交互更接近真实的人与人之间的聊天。
全双工持续交互：在全双工持续交互模式下，用户可以在设备播放TTS/音乐/闹钟时，直接发起语音请求，无需等待播放完毕。如果你的设备配置拥有较好的设备回声消除和降噪效果，我们建议你尽量支持全双工持续交互，为用户提供更好的语音交互体验。

六、设备人设
就是你给发音人什么人设，比如蓝小飞，小飞小飞，巧虎等等。

七、终端自定义唤醒词
一般定义的为三音节的词，提高识别的准确度。

EVS（Embedded iFLYOS Voice Service）嵌入式协议的接入
1.创建设备
2.授权认证
获取token及其他信息

{
  "token_type": "bearer",
  "refresh_token": "4_vujpFOfu0G5yf4**************DwX5S80s74CY7",
  "expires_in": 86400000,//单位秒
  "created_at": 1526485197,//单位秒
  "access_token": "bd6XMEqzIokI6mnMM**************iKAdYNa9T-1WXY"
}

3.连接协议-使用WebSocket连接到iFLYOS
device_id是指每个设备的唯一标识，一般使用设备的SN码即可，然后将上面步骤获取的access_token和device_id作为URL参数，连接websocket

4.交互协议说明

iFLYOS中，我们把设备发送到服务端的指令称为请求(request),一次发送一个请求object，每次发送请求时，均需要同步发送iflyos_header和iflyos_context.

iflyos_header 中的内容为向云端报告本次请求来源（如硬件设备）的基础信息。
iflyos_context 用于向云端同步当前的设备状态，以功能模块为区分，代表发送请求时设备最新的信息。每次对服务端发起的请求都要包含它，iflyos_context 中需要包含所有已经实现的设备模块的信息。

"iflyos_context": {
  "system": {...},
  "recognizer": {...},语音识别器信息
  "speaker": {...},扬声器信息
  "audio_player": {...},
  "alarm": {...},
  "screen": {...},
  "template": {...},设备模板显示信息
  "video_player": {...},
  "app_action": {...},
  "playback_controller": {...},
  "launcher": {...},启动器
  "interceptor": {...}拦截器
}

IFLYOS云端发送给设备的回复，也就是设备接收到服务端的指令称为响应（response），一次接收一个iflyos_meta（解析通用回复）和iflyos_response集。

5.功能模块说明
就是一些常见的功能

IVS接入
iFLYOS Voice Service(简称IVS)协议是iFLYOS服务端与设备端之间的通讯协议，是一套把iFLYOS的智能语音交互能力向智能硬件设备开放的API。智能硬件通过这套API与服务端进行通讯，实现IVS协议客户端逻辑，接入iFLYOS服务，就能够让设备具有iFLYOS的所有交互能力。

1.协议概要
IVS协议由指令、事件、端状态三个部分组成
指令（directive）是服务端下发给设备端，设备端需要执行的操作。比如播放一个语音（Speak指令），设置一个闹钟（SetAlert指令），播放一个音乐（Play指令）等等。

事件（event）是设备端上报给服务端，通知服务端在设备端发生的事情。比如音乐播放开始了（PlaybackStarted事件），音乐播放结束了（PlaybackFinished事件），闹铃开始响了（AlertStarted事件），设备被唤醒并开始接受用户语音请求（ListenStarted事件）等等。

指令和事件是IVS协议最基本的要素，设备端上发生的变化都通过上报相应的事件来通知服务端，服务端通过下发指令给设备端，对用户请求进行响应。

设备端在上报事件时，需要带上设备端的端状态（context）信息。比如当前是否有音乐正在播放，播放到哪里了（PlaybackState），设备端是否有设置闹铃，闹铃状态（AlertsState）等等。对用户的请求，服务端结合端目前所处的状态，决定合理的响应，下发相应的指令。

2.协议分层
IVS协议分传输层、消息格式层、设备能力层三个层次
传输层：在IVS协议最底层，决定设备端与服务端之间的连接方式
消息格式层：在传输层之上，我们确定请求和响应的具体字段格式
设备能力层：最上层，定义设备端的硬件和系统自身具备的各种能力如语音输入能力、语音输出能力、音频播放能力等等。

指令由云端下发，客户端执行相关操作
事件由客户端上报至服务端，将客户端状态和发生的事件告知服务端。

3.传输协议(HTTP/2)
IVS是一个服务，需要通过HTTP/2来长连接向客户端下发由云端发起的指令。
帧：HTTP协议的基本单位，每一帧都代表了不同的用途，比如headers和data帧组成了基本的http请求与返回。
流：在同一个http连接内，设备与服务器交换的一系列独立、双向的帧序列
接口：IVS向你的产品提供的访问IVS内建技能的接口
下行通道：你在你的 HTTP/2 连接中建立的一个用于从云端向你的设备推送指令的流。下行通道由设备建立，保持半开状态。主要用于接收从云端发出的指令。
云端指令： 由云端直接向你的设备发起的指令。比如当用户通过手机 App 调整设备的音量时，云端将直接通过下行通道向设备推送调整音量的指令（而不是通过语音请求）。

1.创建HTTP/2连接
与 IVS 维持连接有两点要求：
创建下行通道流
向 IVS 同步你的产品的组件状态（语音识别、音频播放器、提醒、扬声器、语音合成）

状态同步之后，你的设备即可利用这个连接来：
向 IVS 发送事件并接收指令响应
从下行通道接收云端发起的指令

2.维持HTTP/2连接
几个地方要注意的
1.建议使用10ms、320字节分片（每次发送320字节的data帧）、流式地向IVS传输捕获到的音频，过大的分片会导致不必要的缓冲，导致延迟增加。
2.单个 HTTP/2 连接仅支持 10 个并发的流，包括事件流、下行通道和心跳。再次提醒，事件流收到响应之后应该关闭。
3.大多数请求库对读取时间可能会有超时机制。由于 IVS 的下行通道流是一个长连接，在相当长一段时间内即便没有指令下发也应当维持开启状态。因此需要将读取超时设置为至少 60 分钟。
4.事件流生命周期
每一个事件都使用自己独立的流发送。通常情况下一条流会在当 IVS 返回指令和对应的音频附件之后关闭。
请求应该是顺序处理的。也就是说，应该在 IVS 开始响应你的上一个请求（设备收到了响应头）之后才发出新的请求。
5.下行通道生命周期
一些指令也可能会并行于事件流地从下行通道发送到你的设备。下行通道通常用于接收云端发起的指令。
连接到 IVS 之后的 10 秒内应该向 directives 路径发起一个 GET 请求。
下行通道流用于向你的设备发送云端发起的指令和附件，比如说计时器、闹钟，以及通过 App 远程发起的操作。和事件流不同，下行通道流不应立刻关闭，而应该维持长时间的半开状态。
当下行通道被关闭，你的设备应该立刻重新建立新的下行通道，以确保及时接收云端指令。
6.心跳和超时
你的设备应该采取下列其中一个措施来维持连接。遇到失败后需要关闭连接并重试。
连接空闲时每 5 分钟 向 IVS 发送一个 PING 帧
连接空闲时每 5 分钟 向 /ping 接口发出一个 GET 请求
7.服务端主动断开连接
当服务器主动断开了连接，你的设备应该：
开启一个新的连接，并将所有新的请求移到这个连接上进行
在所有已开启的请求（以及他们对应的流）都处理完毕之后关闭旧的连接。
维持连接关闭前已经打开的流播 URL（比如音乐播放），直到播放结束
如果重新连接失败，设备应该采取适当的间隔重试机制。