嵌入式 SDK集成

创建产品

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

关联阅读

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

产品ID

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

Minion

aliasKey

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

Minion

deviceProfile

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

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

前提

1）音频参数：采样率为16K，采样点2B，单通道；

2）播放器能播放url mp3格式；

3）有物理按键(可选)。

dds对话状态切换

IDLE：reset或者session结束，则切换到IDLE；
LISTENING：侦听状态，按钮事件长按按下、语音唤醒或者VAD检测有语音时触发从IDLE切换到LISTENDING；dds会主动读取音频数据，把经过VAD处理以后的音频数据送到云端识别；按键释放或者VAD结束，切换到UNDERSTANDING；
UNDERSTANDING：语义理解对话管理状态，等待云端对话返回结果，包含：命令控制、本地接口调用、语音播报；

1）reset或者session结束，则切换到IDLE；

2）按键长按按下、唤醒、播放结束或者session继续切换到LISTENING；

3）session继续并且有语音播放，保持UNDERSTANDING状态。

Minion

消息格式

dds接口之间通过Message Pack格式交互数据，协议说明详见：http://msgpack.org/;
格式为：message type + payload；其中payload是key，value格式；key是字符串，value可以为：int, double, boolean,bin类型，其中bin类型是二进制数据。

消息接口

struct dds_msg;

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

/* 消息封装接口 */
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_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);

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

消息类型

DDS_EV_OUT_RECORD_AUDIO

说明：录音事件，产生该事件，需要把音频数据发送给dds。

message type：DDS_EV_OUT_RECORD_AUDIO

payload：无

DDS_EV_OUT_NATIVE_CALL

说明：本地调用，dds服务端查询本地数据。开发者在定制平台，定制任务的资源来源接口，即payload中的”api”详见下图示例：

Minion

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

Minion

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平台定制的控制命令，详见下图：

Minion

参数以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数组字符串，如：

DDS_EV_OUT_STATUS

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

message type：DDS_EV_OUT_STATUS

payload

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

DDS_EV_OUT_TTS

说明：语音合成音频url地址，一般为mp3格式

message type：DDS_EV_OUT_TTS

payload

key	value type	说明
speakUrl	String	合成音url地址，如: "https://s.dui.ai/tts/v1?refText=为您播放&speed=0.800000&volume=50&speaker=zhilingf"

DDS_EV_OUT_ASR_RESULT

说明：实时识别结果

message type：DDS_EV_OUT_ASR_RESULT

payload

key	value type	说明
var	String	识别结果，如：“你好”

DDS_EV_OUT_ERROR

说明：dds异常

message type：DDS_EV_OUT_ERROR

payload

key	value type	说明
error	String	异常提示信息

DDS_EV_OUT_DUI_RESPONSE

说明：DUI服务返回的完整结果

message type：DDS_EV_OUT_DUI_RESPONSE

payload

key	value type	说明
response	String	DUI服务返回结果

DDS_EV_IN_SPEECH

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

message type：DDS_EV_IN_SPEECH

payload

key	value type	说明
action	String	语音事件，其值分别为： "start"：语音开始； "end"：语音结束；

DDS_EV_IN_WAKEUP

说明：唤醒事件

message type：DDS_EV_IN_WAKEUP

payload：无

DDS_EV_IN_NATIVE_RESPONSE

说明：本地调用返回结果

message type：DDS_EV_IN_NATIVE_RESPONSE

payload：dds本地调用返回结果支持key，value方式返回，可以设置多个；如：

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

DDS_EV_IN_RESET

说明：重置对话

message type：DDS_EV_IN_RESET

payload：无

DDS_EV_IN_EXIT

说明：退出dds

message type：DDS_EV_IN_EXIT

payload：无

DDS_EV_IN_AUDIO_STREAM

说明：音频流

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_ev_callback

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

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

struct dds_opt

struct dds_opt {
dds_ev_callback _handler;
void *userdata;
};

结构体成员

1）_handler：事件回调函数；

2）userdata：用户数据。

dds_start

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

函数功：启动dds，该接口会一直阻塞，通过事件回调函数和系统交互；通过发送事件DDS_EV_OUT_EXIT，让其退出。

参数：conf：dds配置，开发需要配置productId、aliasKey、deviceProfile，获取这三个值，如前文所述。配置示例如：

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, "deviceId", "macId");
dds_msg_set_string(msg, "deviceProfile", "xxxx"); //xxx为设备对应的profile的内容

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

返回值

1）0：成功

2）-1: 失败

dds_send

int dds_send(struct dds_msg *msg);

函数功能：发送数据给dds，一般是DDS_EV_IN_事件。

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

返回值

1）0：成功

2）1：失败

DEMO

已提供树莓派demo，请前往SDK下载页下载对应的SDK包。