简介

DCS协议是DuerOS服务端与设备端之间的通讯协议,是一套把DuerOS的智能语音交互能力向所有设备开放的API。智能音箱、智能TV、智能冰箱等设备端,通过这套API与服务端进行通讯,实现DCS协议客户端逻辑,接入DuerOS服务,就能够让设备具有DuerOS的所有交互能力。

协议概要

DCS协议由指令、事件、端状态三个部分组成。

指令(directive)是服务端下发给设备端,设备端需要执行的操作。比如播放一个语音(Speak指令),设置一个闹钟(SetAlert指令),播放一个音乐(Play指令)等等。

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

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

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

事件分级

DCS事件 (event) 分为交互事件统计事件 两种。

交互事件是设备端上报给服务端,通知服务端在设备端发生的事情,并且服务端有可能下发指令给设备端,对用户的请求进行响应。

统计事件是设备端上报给服务端,通知服务端在设备端发生的事情,并且服务端只对设备端行为进行记录,不下发指令给设备端,不对用户的请求进行响应。

在DCS事件定义时,如果不做特别说明,默认分级为交互事件; 如果需要对事件分级进行明确定义,按照以下规范进行定义:

  • 在协议定义范围内,增加三级标题,标题名称为'事件分级'
  • 在正文的第一行顶格说明事件级别,级别名称斜体加粗 ,名称后面详细阐述事件分级的原因。
  • 示例如下:
### 事件分级

***统计事件***: 本事件目前主要用于统计目的,服务端接入层对本事件进行直接处理,不向服务端下游模块透传,无服务响应指令返回。

协议分层

DCS协议分传输层、消息格式层、端能力层三个层次。

传输层

传输层在DCS协议最底层,决定设备端与服务端之间的连接方式。

目前DCS服务提供基于HTTP/2的传输层协议,详细内容阅读传输层协议文档。

消息格式层

在传输层之上,我们确定请求和响应的具体字段格式,这一层为消息格式层。消息格式层确定指令、事件、端状态,以及访问令牌、设备ID等等字段的位置和格式。

目前DCS协议定义了基于HTTP请求和响应格式的消息格式,详细内容阅读消息格式文档。

端能力层

最上层端能力层,定义设备端的硬件和系统自身所具备的各种能力,如语音输入能力、语音输出能力、音频播放能力等等。每一种端能力包含一套对应的指令与事件的定义,加上必要的端状态定义。设备具备并实现的端能力越多,设备所能支持的技能也越多,如询问天气、股票等信息需要设备具备语音输入能力和语音输出能力,而要能够播放音乐则需要设备有音频播放能力。

端能力的列表和详细协议内容,阅读端能力接口文档。

协议版本

当端能力接口的指令、事件增加或删除、指令或事件的payload发生调整、端状态定义发生变更时,将通过版本化的方式描述并记录这些端能力接口的变更,不同的端能力都有独立的版本控制,版本号格式为MAJOR.MINOR,设备所支持的端能力接口及版本可以在设备的didp的配置中设置和调整。

MINOR版本

向前兼容的非破坏性变更,应该自增MINOR版本号,MINOR增加的典型场景如下:

  • 端能力接口增加新的指令或事件
  • 指令或事件的payload增加参数

MAJOR版本

非向前兼容的破坏性变更,应该自增MAJOR版本号,MAJOR增加的典型场景如下:

  • 端能力接口中已经存在的指令或事件被删除
  • 指令或事件的payload参数的数据类型发生变化
  • 现有指令或事件的payload参数被删除