嵌入式 SDK集成
创建产品
DDS-Device-SDK是DUI平台针对嵌入式设备开发的对话定制服务SDK。开发者需要到DUI平台注册开发者账号,并熟悉DUI平台技能定制与产品发布。
关联阅读
注:分支号就是接口配置中的”aliasKey”。
产品ID
请记住产品ID,详见下图:
aliasKey
发布下载页面的分支号即是“aliasKey”,如下图:
deviceProfile
授权信息,每一个设备对应一个授权profile文件,产品发布之后到 “授权管理” 标签页下载,如下图:
在开发时,调用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状态。
消息格式
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”详见下图示例:
参数以json字符串返回给客户端,即payload中的”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数组字符串,如:![]() |
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包。