嵌入式 SDK集成

创建产品

DDS-Device-SDK是DUI平台针对嵌入式设备开发的对话定制服务SDK。开发者需要到DUI平台注册开发者账号，并熟悉DUI平台技能定制与产品发布。

关联阅读

注：分支号就是接口配置中的”aliasKey”。

产品ID

请记住产品ID，详见下图：

Minion

aliasKey

发布下载页面的分支号即是“aliasKey”，如下图：

Minion

deviceProfile

授权信息，每一个设备对应一个授权profile文件，产品发布之后到 “授权管理” 标签页下载，如下图：

Minion
在开发时，调用dds_start函数，需要将profile文件中的内容作为配置参数deviceProfile的值传给dds，或者通过savedProfile配置参数，将profile文件路径传给dds，dds会完成后续授权相关操作。

 

集成前提

音频参数：采样频率为16KHz，每个采样点2Bytes，单通道；

播放器能播放url mp3格式；

有物理按键(可选)。

 

dds对话状态切换

IDLE：dds初始化以后处于IDLE状态，等待事件触发；

LISTENING：侦听状态，按钮事件长按按下、语音唤醒或者VAD检测有语音时触发从IDLE切换到LISTENDING；dds会主动读取音频数据，把经过VAD处理以后的音频数据送到云端识别；按键释放或者VAD结束，切换到UNDERSTANDING；

UNDERSTANDING：语义理解对话管理状态，等待云端对话返回结果，包含：命令控制、本地接口调用、语音播报；

  • reset或者session结束，则切换到IDLE；
  • 按键长按按下、唤醒、播放结束或者session继续切换到LISTENING；
  • session继续并且有语音播放，保持UNDERSTANDING状态。

 

消息格式

dds接口之间通过Message Pack格式交互数据，协议说明详见：http://msgpack.org/;

格式为：message type + payload；其中payload是key，value格式；key是字符串，value可以为：int, double, boolean, string, bin类型，其中bin类型是二进制数据。

消息接口

struct dds_msg;

/* 消息创建与释放 */
struct dds_msg *dds_msg_new();
int dds_msg_delete(struct dds_msg *msg);

/* 消息封装接口 *//* 注意，以下接口中char *key, char *value这两个参数不能为NULL */
int dds_msg_set_type(struct dds_msgt *msg, int type);
int dds_msg_set_integer(struct dds_msg *msg, char *key, int value);
int dds_msg_set_double(struct dds_msg *msg, char *key, double value);
int dds_msg_set_boolean(struct dds_msg *msg, char *key, int value);
int dds_msg_set_string(struct dds_msg *msg, char *key, char *value);
int dds_msg_set_bin(struct dds_msg *msg, char *key, char *value, int value_len);int dds_msg_set_bin_p(struct dds_msg *msg, char *key, char *value, int value_len);/*该接口保存二进制数据的指针，不复制具体的数据内容，适用于内存较小的场景*/

/* 消息解析接口 */
int dds_msg_get_type(struct dds_msgt *msg, int *type);
int dds_msg_get_integer(struct dds_msg *msg, char *key, int *value);
int dds_msg_get_double(struct dds_msg *msg, char *key, double *value);
int dds_msg_get_boolean(struct dds_msg *msg, char *key, int *value);
int dds_msg_get_string(struct dds_msg *msg, char *key, char **value);
int dds_msg_get_bin(struct dds_msg *msg, char *key, char **value, int *value_len);int dds_msg_get_bin_p(struct dds_msg *msg, char *key, char **value, int *value_len);

/* 消息调试接口 */
void dds_msg_print(struct dds_msg *msg);

消息类型

DDS_EV_OUT_RECORD_AUDIO

说明

录音事件，该接口dds每100ms调用一次，主动向开发者索要音频数据，若开发者采用该方式送数据，则在回调中用DDS_EV_IN_AUDIO_STREAM消息，将录音传递给dds。

message type

    DDS_EV_OUT_RECORD_AUDIO

payload

    无

DDS_EV_OUT_NATIVE_CALL

说明

本地调用，dds服务端查询本地数据, 结果数据在回调中通过DDS_EV_IN_NATIVE_RESPONSE消息返回给dui服务。开发者在定制平台，定制任务的资源来源接口，即payload中的”api”详见下图示例：

参数以json字符串返回给开户端，即paload中的”param”，点击API配置,在如下页面配置参数:

message type

    DDS_EV_OUT_NATIVE_CALL

payload

key value 说明
api string 如上述示例中为："resp/native/call"
param json string

如上述示例中为：

{ 
    “intentName”: "自定义意图1"，
    “widgetType”: "text"，
    “test”： “test-val”
}

DDS_EV_OUT_COMMAND

说明

控制命令，开发者在DUI平台定制的控制命令，详见下图：

参数以json字符串返回。

 

message type

    DDS_EV_OUT_COMMAND

payload

key value type 说明
api string 上述示例为："volume/up"
param json string

如果用户说，音量调到十，上述示例返回的参数为:

{
    “value”: 10
}

DDS_EV_OUT_MEDIA

说明

多媒体播放列表。

message type

    DDS_EV_OUT_MEDIA

payload

key value type 说明
list json array string

播放列表是json数组字符串，如：

[
     {
        "linkUrl":"http://cdndown.dorylist.com/uploads/ogg/2013/05/09/4448.ogg",
        "title":"新上海滩 ",
        "extra": {
            "resType":"ogg"
        },
        "subTitle":"叶丽仪",
        "imageUrl":"",
        "label":"其 它"
    },
     {
        "linkUrl":"http://cdndown.dorylist.com/uploads/ogg/2017/04/18/033828787.ogg",
        "title":"The Moment",
        "extra": {
            "resType":"ogg"
        },
        "subTitle":"Kenny G",
        "imageUrl":"",
        "label":"其 它"
    }
]

DDS_EV_OUT_STATUS

说明

dds状态：“idle”，“listening”，“understanding”，详见上述状态切换。 

message type

    DDS_EV_OUT_STATUS

payload

key value type 说明
status string dds状态，取值有：“idle”，“listening”，“understanding”
trigger string

idle状态有该字段，表明触发的原因

"reset"：开发者调用reset强制将状态切换到idle

"disconnect"：长连接维持的2分钟内无操作，断开连接

 

DDS_EV_OUT_TTS

说明

语音合成音频url地址，一般为mp3格式。

message type

    DDS_EV_OUT_TTS

payload

key value type 说明

speakUrl

 string 合成音url地址，如: "http://tts.dui.ai/runtime/v1/cache0f91269784b3bcb9401e6854011e04f4e4f1b3ce" 
source string 产生合成的原因，"dui"：dui对话返回，"external"：开发者自定义合成文本，生成的合成音
nlg string 合成音的文本，可选

DDS_EV_OUT_ASR_RESULT

说明

实时识别结果。

message type

    DDS_EV_OUT_ASR_RESULT

payload


key value type 说明

var

 string 识别中间结果，如：“你好”
text string 识别的最终结果
pinyin string 合成音的文本，拼音

DDS_EV_OUT_ERROR

说明

dds异常。

message type

    DDS_EV_OUT_ERROR

payload

key value type 说明
error string 异常提示信息
errorId int

错误码，错误码的定义如下：

DDS_ERROR_FATAL 1001
DDS_ERROR_TIMEOUT 1002
DDS_ERROR_NETWORK 1003
DDS_ERROR_SERVER 1004
DDS_ERROR_LOGIC 1005
DDS_ERROR_INPUT 1006
source string 错误是在哪个连接上产生的，tts表示请求自定义合成报错

DDS_EV_OUT_DUI_RESPONSE

说明

DUI服务返回的完整结果。

message type

    DDS_EV_OUT_DUI_RESPONSE

payload

key value type 说明
response json string

DUI服务返回结果，结果中主要字段含义如下：

{
	 "dm":{
		"shouldEndSession":true,                  // boolean, false:交互中,true:结束
		"nlg":"xxx",                              // dm文本输出
		"dataFrom": "xxx",                        // 资源来源类型，来源有"webhook", "native", "function","proxy"
		"api": "xxx",                             // 资源来源，webhook地址或者nativeApi指令 或者function 的id
		"param": {                                // webhook/native传递的参数
			"key1": val1,
			"key2": val2
		},
		"command":{
			 "api":"xxx",                         // 客户端动作
			 "param":{                            // 传递的参数
				 "key1":"xxx",
				 "key2":"xxx",
				 ...
			 }
		},
		"widget":{                                // h5控件相关
			 ...
		}
	},
	"sessionId": "83161c65dc844a15abb3437b3afb0028", //多轮对话Id
	"speakUrl": "https:\/\/dds.dui.ai\/runtime\/v1\/cache\/a918df35a5314d51911607df3c6e3aa9", //对话合成音地址
}

 

DDS_EV_OUT_DUI_LOGIN

说明

该事件表示授权完成，可以进行交互了。

DDS_EV_OUT_CINFO_RESULT

说明

cinfo的操作，执行结果。

message type

    DDS_EV_OUT_CINFO_RESULT

payload

key value type 说明
operation string 返回结果对应的操作类型，get/set
result string cinfo的执行情况，success/failed
cinfo json string

get操作的返回结果，比如：

cinfo tts返回结果：{"result":{"sampleRate":8000,"speed":1,"volume":80,"voiceId":"zhilingf","audioType":"mp3"}}

cinfo 词库返回结果：{"result":{"type":"vocab","data":["苏州","南京"]}}

DDS_EV_OUT_PRODUCT_CONFIG_RESULT

说明

获取到的dui平台上的产品配置，目前只抛出了tts配置信息。

message type

    DDS_EV_OUT_PRODUCT_CONFIG_RESULT

payload

key value type 说明
result string 产品配置获取结果，success/failed
tts json string

tts配置：

tts: {
"enable": true,
"test": "思必驰对话定制平台，为设备和产品赋予认知、思考、决策的能力，是国内领先的一站式对话定制平台。",
"visible": true,
"voice": "zhilingf",
"volume": 50,
"type": "cloud",
"speed": 0.800000
}

DDS_EV_OUT_WEB_CONNECT

说明

和DUI平台tcp连接状态。

message type

    DDS_EV_OUT_WEB_CONNECT

payload

key value 说明
result string connected/disconnected

DDS_EV_IN_SPEECH

说明

语音事件输入，包含：语音开始，语音结束，值分别为：“start”，"end"。

message type

    DDS_EV_IN_SPEECH
payload
key value type 说明
action string

语音事件，其值分别为：

"start"：语音开始；

"end"：语音结束；
asrParams json string

识别的配置参数，在start的时候传入

{
"vadEnable": false,
"realBack": true,
"res": "aihome"
}

 

DDS_EV_IN_WAKEUP

说明

唤醒事件，该事件会触发dds读取音频，内部使用VAD（默认给出的库，不包含该功能；如果需要唤醒、vad等功能，推荐配合duilite sdk使用）。

message type

    DDS_EV_IN_WAKEUP

payload

    无

DDS_EV_IN_NATIVE_RESPONSE

说明

本地调用返回结果, 在DDS_EV_OUT_NATIVE_CALL回调中使用该消息。

message type

    DDS_EV_IN_NATIVE_RESPONSE

payload

支持两种数据输入：

1. key-value的形式逐个输入，value只支持string格式，示例代码如下

struct dds_msg *msg = dds_msg_new();
dds_msg_set_type(retmsg, DDS_EV_IN_NATIVE_RESPONSE);
dds_msg_set_string(msg, "key1", "value1");
dds_msg_set_string(msg, "key2", "value2");
dds_send(msg); /* 把消息发送给服务端 */
dds_msg_delete();

2. json格式一次输入

struct dds_msg *msg = dds_msg_new();
dds_msg_set_type(msg, DDS_EV_IN_NATIVE_RESPONSE);
dds_msg_set_string(msg, "json", "{\"text\": \"查到你要的内容\"}");
dds_send(msg);
dds_msg_delete(msg);

DDS_EV_IN_RESET

说明

 重置对话，该接口阻塞实现。

message type

 
    DDS_EV_IN_RESET
payload
key value type 说明
keepConnection boolean

是否在reset的时候保持连接

1 true

0 false

DDS_EV_IN_EXIT

说明

退出dds。

message type

 
    DDS_EV_IN_EXIT
payload

    无

DDS_EV_IN_CUSTOM_TTS_TEXT

说明

合成接口，开发者可以自定义需要合成的文本，该接口在0.2.9之后的版本实现。

message type

     DDS_EV_IN_CUSTOM_TTS_TEXT

payload

key value type 说明
text string 需要合成的中文文本
voiceId string 必选，合成音的音色
speed double 可选，合成音的速度
volume int 可选，合成音的音量大小

DDS_EV_IN_AUDIO_STREAM

说明

音频流，支持两种送音频方式：

1. 在DDS_EV_OUT_RECORD_AUDIO回调中发送音频，此方式为dds主动索要音频；

2. 用户主动发送音频，忽略DDS_EV_OUT_RECORD_AUDIO回调，不在dds回调线程，直接使用dds_send接口发送音频。

message type

    DDS_EV_IN_AUDIO_STREAM

payload

key value type 说明
audio binary

音频流的值为二进制数据，消息封装如下：

 

struct dds_msg *msg = dds_msg_new();dds_msg_set_type(msg, DDS_EV_IN_AUDIO_STREAM);
dds_msg_set_bin(msg, "audio", data, length);
dds_send(msg);
dds_msg_delete();

 

DDS_EV_IN_PLAYER_STATUS

说明

播放状态。

message type

    DDS_EV_IN_PLAYER_STATUS

payload

key value type 说明
status string 如果播放结束，值为："end"，dds接收到'end'之后会转到“listening”状态

DDS_EV_IN_NLU_TEXT

说明

语义请求，请求结果和语音请求一致。

message type

    DDS_EV_IN_NLU_TEXT

payload

key value type 说明
text string 需要进行语义请求的文本

DDS_EV_IN_WAKEUP_WORD

说明

配置单个唤醒词，oneshot的时候使用；

该配置仅对当前dds实例生效，会被下次DDS_EV_IN_WAKEUP_WORD设置更新。

message type

    DDS_EV_IN_WAKEUP_WORD

payload

key value type 说明
wakeupWord string 唤醒词内容，比如：“你好小乐”

DDS_EV_IN_CINFO_OPERATE

说明

操作cinfo，设置/获取/删除单个终端自定义配置。

注意：cinfo针对词库的操作，该词库必须被产品用到，否则在调用set get delete操作时服务端会报错。

message type

    DDS_EV_IN_CINFO_OPERATE

payload

set：

key value type 说明
operation string 需要执行的操作，set
location json string 设置地址信息，比如：{"city": "苏州市"}
tts json string 设置云端合成配置，比如：{"voiceId":"zhilingf","speed":1.0,"volume":80,"sampleRate":8000,"audioType":"mp3"}
vocab_name string

需要设置的词库名称，比如："城市名称" （该词库必须在产品的技能词库中包含，否则返回result: failed）
vocab_data json string

需要设置的对应于vocab_name词库下的词条

设置词库，vocab_name和vocab_data必选，否则不操作。

格式：["词一", "词二”, "词三", "词一同义词: 词一", "词一同义词2: 词一"] （设置同义词，必须包含“词一”本身）

比如：["苏州”, "北京", "上海”] ， ["苏州”, "北京", "上海”, "帝都:北京", "首都:北京"]

get：

key value type 说明
operation string 需要执行的操作，get
cinfo string 需要获取的配置类型，比如："tts", "location", "vocab"
vocab_name string 需要查询的词库名称，如果词库不存在或词库下没有词条，返回result: failed

delete：

key value type 说明
operation string 需要执行的操作，delete（（目前支持vocab进行删除）
cinfo string 需要删除的配置类型，支持 "location", "vocab"
vocab_name string

需要删除的词库名称
vocab_data json string

需要删除的vocab_name词库下的词条

如果operation=delete, cinfo=vocab, vocab_name="某个词库“，vocab_data="["该词库下的某个词条"]"，则删除该词条

如果operation=delete, cinfo=vocab, vocab_name="某个词库“，不设置vocab_data，则删除该词库下的所有词条

DDS_EV_IN_DM_INTENT

说明

跳过识别和语义，直接进入指定的意图对话。

message_type

    DDS_EV_IN_DM_INTENT

payload

key value type 说明
skill string

技能名称，必选
task string 任务名称，必选
intent string 意图名称，必选
slots json string

语义槽的key-value，可选

格式为：｛"语义槽1":"语义槽1的值"，语义槽2":"语义槽2的值"｝

DDS_EV_IN_PHRASE_HINTS

说明

热词设置，目前仅支持基础技术识别时使用；

该配置仅对当前dds实例生效，会被下次DDS_EV_IN_PHRASE_HINTS设置更新；

设置热词后，会将语音优先识别为热词中的词。

message_type

    DDS_EV_IN_PHRASE_HINTS

payload

key value type 说明
phraseHints json string

热词配置

格式为： [{"type": "vocab", "name": "词库名", "data":["短语1", "短语2"]}]

其中：type为词库类型，目前只支持vocab

示例："[{"type":"vocab","name":"联系人","data":["张三","李四"]}]"

DDS_EV_IN_PRODUCT_CONFIG

说明

获取dui控制台上的该产品配置。

message_type

    DDS_EV_IN_PRODUCT_CONFIG

payload

    无

软件接口

dds_ev_callback

typedef int (*dds_ev_callback)(void *userdata, struct dds_msg *msg);

事件回调函数，所有的DDS_EV_OUT事件都会通过该接口告诉开发者。

 

struct dds_opt 

struct dds_opt {

    dds_ev_callback _handler;

    void *userdata;

};

 

结构体成员

  • _handler：事件回调函数；
  • userdata：用户数据。

dds_start 

int dds_start(struct dds_msg *conf, struct dds_opt *opt);

 

函数功能

启动dds，该接口会一直阻塞，需要在一个单独的线程里面调用执行，通过事件回调函数和系统交互；通过发送事件DDS_EV_IN_EXIT，让其退出。

参数

conf：dds配置，开发需要配置productId、aliasKey、deviceProfile，这三个值，需要在dui控制台上获取。
配置示例如：

 

struct dds_msg *msg = dds_msg_new(); 
dds_msg_set_string(msg, "productId", "100000xxxx");
dds_msg_set_string(msg, "aliasKey", "prod");
dds_msg_set_string(msg, "savedProfile", "xxxx"); //xxx为设备对应的profile文件的路径

 

opt：可选配置参数，有事件回调函数和用户数据

 

返回值

0：成功
-1: 失败

dds_send

int dds_send(struct dds_msg *msg); 

 

函数功能

发送数据给dds，一般是DDS_EV_IN_事件，该接口线程安全。

参数

msg：消息数据，先创建消息，调完dds_send以后，该消息即可释放。

返回值

0： 成功
1：失败

EXAMPLE

详见sdk开发包