多模态交互套件开发手册

版本记录

![](/media/202407/2024-07-11_192118_0105440.8786638602576475.png)

目 录

[一、 软件包说明 1](#_Toc164775818)

[1 安装套件包 1](#_Toc164775819)

[2 串口DEMO 2](#_Toc164775820)

[3 视频预览DEMO 2](#_Toc164775821)

[二、 程序功能模块 2](#_Toc164775822)

[三、 串口数据解析 3](#_Toc164775823)

[1 概述 3](#_Toc164775824)

[2 通信接口及参数 3](#_Toc164775825)

[3 消息格式 3](#_Toc164775826)

[4 通信规则 4](#_Toc164775827)

[5 通信格式 4](#_Toc164775828)

[四、 串口发送控制消息 5](#_Toc164775829)

[1 确认消息 5](#_Toc164775830)

[2 WIFI配置 5](#_Toc164775831)

[3 AIUI配置 6](#_Toc164775832)

[4 主控消息 6](#_Toc164775833)

[5 设置以太网静态IP 9](#_Toc164775834)

[五、 串口接收AIUI消息 10](#_Toc164775835)

[1 AIUI结果事件 10](#_Toc164775836)

[2 WIFI状态 11](#_Toc164775837)

[3 多模态麦克风和摄像头状态 11](#_Toc164775838)

[六、 多模态设备视频传输协议 11](#_Toc164775839)

[1 概述 12](#_Toc164775840)

[2 消息格式 12](#_Toc164775841)

[3 通信规则 12](#_Toc164775842)

[4 通信格式 13](#_Toc164775843)

[5 图像格式消息 14](#_Toc164775844)

[6 图像二进制消息 14](#_Toc164775845)

[7 人脸检测消息 14](#_Toc164775846)

[七、 常见问题 15](#_Toc164775847)

[1 怎么查看AIUI上串口消息的处理接收？ 15](#_Toc164775848)

[2 串口消息构造后发送给AIUI，为什么没有执行对应操作（如发了合成命令，没有合成播放等）？ 15](#_Toc164775849)

[3 图像卡顿，1秒仅收到2帧图像数据 16](#_Toc164775850)

[4 图像传输对带宽的要求 17](#_Toc164775851)

# 软件包说明

## 安装套件包

安装套件包解压缩后包含体验评估板语音交互能力所需的app以及更新app的批处理脚本。

![](/media/202407/2024-07-11_193734_0759460.8306310588544698.png)

批处理安装脚本：scripts/ install\_all.bat

批处理卸载脚本：scripts/ uninstall\_all.bat

## 串口DEMO

开发包中提供了windows、Android、Linux平台的demo。

Android：Android\_UART

Windows：QT\_UART\_DEMO、Windows\_C#\_SerialDemo

其他平台也可以参考Linux C：串口历险记(含Simple代码)

## 视频预览DEMO

开发中提供了Android平台的视频接收端demo。

多模态AndroidSocketVideoDemo

# 程序功能模块

![https://aiui-file.cn-bj.ufileos.com/aiui-doc/3_access_service/access_evm/screenshot_1519546039919.png](/media/202407//1720696807.1038961.png)上位机和AIUI模块通过串口通信，适用于有屏幕需求或硬件扩展需求（如机器人，智能家居等）。

如上图所示，为上位机模式的开发结构图，UARTService充当AIUIService和上位机之间的中介，一面负责将AIUI的结果通过串口发送给上位机，一面将上位机通过串口发送的指令发送到AIUI。

AIUIProductDemo是个可选的选项，因为如果在上位机上对结果进行解析播放，那么AIUI模块上的AIUIProductDemo的播报就不必要了。

# 串口数据解析

## 概述

上位机可以通过串口向AIUI语音模块发送握手消息同步状态，例如发送WIFI配置信息。

## 通信接口及参数

* 波特率：115200
* 数据位：8
* 停止位：1
* 奇偶校验：无
* 流控：无

AIUI使用模块上的串口RS232，对应文件系统下的/dev/ttyS2。

## 消息格式

![](/media/202407/2024-07-11_192332_6127890.9386817468135736.png)

## 通信规则

* 双向通信，进行一问一答式通信；
* 不分主从机，双方都可向对方发送请求信息；
* 双方发送握手信号，确定与对方串口通信是否正常；在未接收到响应时，可以每隔100ms发送一次握手请求信号；
* 接收方接到请求后需在50ms内发送响应；
* 除确认消息外发送方发送完成后若超过300ms未得到响应则判定为超时进行重发，重发次数为3次。

## 通信格式

![download](/media/202407//1720696807.111784.png)通信格式定义了握手消息，AIUI配置消息，WIFI配置消息，AIUI消息，主控消息，确认消息。下面将分类详述：

消息长度：

数据格式中3~4字节为消息数据长度，消息长度编码为小端模式，即第3字节存储低字节，第4字节存储高字节。如握手请求消息中消息数据有4字节，则消息长度为4，编码到3~4字节就是0x04 0x00

消息ID：

数据格式中5~6字节为消息ID，与消息长度类似，也是小端模式编码。可以使用消息ID过滤因超时重发导致的重复消息。两字节长度的消息ID取值0-65535，所以在实际使用中需要循环使用，具体实现可以参考Android平台上的源码实现。

校检码：

数据格式中每种数据类型的最后一个字节都是校检码，用于检验串口传输的正确性。其计算方式为除校检码字节外所有字节求和取反并加1。公式如下:

checkcode = ~sum(字节0+字节2+...+字节n) + 1

编码格式：

消息中字符串类型的数据编码格式为UTF-8。

AIUI消息格式中的数据采用GZIP压缩格式，压缩前的编码格式也是UTF-8格式。

确认消息：

确认消息是一个特殊的消息类型，它是对其他类型消息的确认，它的消息ID与其要确认的消息的ID相同。

如一个AIUI消息的消息ID为0x9527，那对应的确认消息的消息ID也应该是0x9527。

# 串口发送控制消息

## 确认消息

确认消息是一个特殊的消息类型，它是对其他类型消息的确认，它的消息ID与其要确认的消息的ID相同。

如一个AIUI消息的消息ID为0x9527，那对应的确认消息的消息ID也应该是0x9527。

## WIFI配置

WIFI配置结果中，状态取值：

0：从机当前与路由连接

加密方式分为三类：

0：OPEN

1：WEP

2：WPA

## AIUI配置

AIUI配置的格式为JSON，content中包含配置文件内容，可配置字段参考[AIUI配置文件](https://aiui-doc.xf-yun.com/project-1/doc-13/#%E9%85%8D%E7%BD%AE%E6%96%87%E4%BB%B6)内容，除AIUI配置文件中的内容外还可以通过launch\_demo配置是否启动AIUIProductDemo。

配置appid，key，场景等示例如下:

{

"type": "aiui\_cfg",

"content": {

"login":{

"appid":"xxxxxxxx",

"key":"xxxxxxxx"

},

"launch\_demo": false

}

**注意：AIUI只需配置一次，后面即使重启也会继续生效，AIUI配置生效需要重启服务，所以AIUI配置应尽可能只在首次启动无配置或配置修改的情况下使用。**

注：配置项字段取值参见中[AIUI配置文件](https://aiui-doc.xf-yun.com/project-1/doc-13/#%E9%85%8D%E7%BD%AE%E6%96%87%E4%BB%B6)部分说明

## 主控消息

主控消息是上位机发送给AIUI模块的消息，格式为JSON。

主控消息根据内部字段type的不同，控制AIUI的不同功能。

AIUI控制

type为aiui\_msg，发送AIUI控制消息:

{

"type": "aiui\_msg",

"content": {

"msg\_type": 23, // CMD\_STOP\_RECORD **停止录制数据**

"arg1": 0,

"arg2": 0,

"params": "",

"data": "" //非必须，值为原数据的base64编码

}

注：各个字段取值具体说明参见[AIUIMessage类型](https://aiui-doc.xf-yun.com/project-1/doc-14/#aiuimessage)说明部分

WIFI状态查询

type为status，通过query字段查询不同状态:

{

"type": "status",

"content": {

"query": "wifi" // 查询AIUI WIFI状态信息

}

多模态麦克风和摄像头状态查询

type为status，通过query字段查询不同状态:

{

"type": "status",

"content": {

"query": "speech\_device" // 查询多模态设备状态信息

}

AIUI结果过滤命令

默认情况下，AIUI会将用户在云端配置的所有语义场景类型的结果都通过串口发送给上位机。

但是可能在某些情况下，比如上位机是单片机，仅仅需要接收操控类的指令，对天气，音乐，故事类的结果仅希望在AIUI模块上播出，而不需要发送到上位机。

在这种情况下，开发者可以通过命令控制过滤选择发送到上位机的AIUI结果的场景类型：

{

"type": "event\_filter",

"content": {

"type\_filter" : {

"select" : [],

"unselect": []

},

"sub\_filter": {

"select" : [],

"unselect": []

},

"service\_filter": {

"select" : [],

"unselect": []

}

其中type\_filter根据AIUIEvent的eventType来过滤，具体取值请参考[AIUIEvent](https://aiui-doc.xf-yun.com/project-1/doc-14/#aiuievent)小节。select字段为允许发送的类型，unselect字段为不允许发送的类型。注意：取值类型为字符串类型，而不是int类型。如下为过滤唤醒事件示例：

{

"type": "event\_filter",

"content": {

"type\_filter" : {

"select" : ["4"] //结果事件对应取值为4

}

sub\_filter根据结果事件中的sub字段来过滤，具体取值：iat、nlp、asr、tpp。如下为过滤后处理结果示例：

{

"type": "event\_filter",

"content": {

"sub\_filter" : {

"select" : ["tpp"]

}

service\_filter根据结果事件中的service字段来过滤，如下为过滤天气结果示例：

{

"type": "event\_filter",

"content": {

"service\_filter" : {

"select" : ["weather"]

}

## 设置以太网静态IP

设备默认使用DHCP获取设备IP，切换为静态IP可发送以下消息内容：

{

"staticIp": true, //设置为静态IP

"address": "192.168.1.123", //ip配置

"mask": "255.255.255.0", //子网掩码配置

"gateway": "192.168.1.1", //网关配置

"dns": "192.168.1.1" //DNS配置

}

# 串口接收AIUI消息

AIUI消息是AIUI模块传递给上位机的消息，表示听写语义数据返回或者主控消息操作的结果。  
原始内容格式为JSON，**但是为了传输的效率，实际消息内容采用了GZIP压缩格式**。

AIUI消息根据type字段的不同值解析数据。

## AIUI结果事件

type为aiui\_event，代表AIUI结果返回，总体结构示例：

{

"type": "aiui\_event",

"content": {

"eventType":1, //事件类型

"arg1":0, //参数1

"arg2":0, //参数2

"info":{}, //描述信息

"result":{} //结果

}

## WIFI状态

type为wifi\_status，代表WIFI状态查询返回或者当AIUI网络状态变化时主动通知，示例如下:

{

"type": "wifi\_status",

"content": {

"connected": true/false, //AIUI WIFI查询状态信息

"ssid": "connected\_ssid" //当connected为true时，此字段表示当前连接的wifi名称

}

## 多模态麦克风和摄像头状态

type为speech\_device\_status，代表当主动查询或者轮训每分钟通知一次多模态硬件状态，示例如下:

{

"type": "speech\_device\_status",

"content": {

"local\_ip": "192.168.100.18", //设备当前IP

"audio\_state": 0, //麦克风硬件状态

"video\_state": 0, //摄像头状态

"engine\_state": 0, //多模态引擎初始化状态

"mic\_test": 0 //运行时mic检测状态

}

# 多模态设备视频传输协议

上位机可通过socket与盒子建立视频传输通道，可参照开发包中的Android示例代码实现摄像头视频预览。

## 概述

上位机可以通过socket连接盒子来获取到实时图像帧数据，以及人脸检测结果信息。

**设备IP**：如果盒子为动态ip，可通过[发送串口](#_多模态麦克风和摄像头状态查询)指令来获取ip。

**指定端口**：9090

## 消息格式

消息格式与串口协议类似，唯一不同点为消息数据长度位从2个字节扩充到4个字节。

![](/media/202407/2024-07-11_192455_1178870.37551600842406585.png)

## 通信规则

* 半双工通信，进行一问一答式通信；
* 语音模组主要负责下发消息，上位机主要负责接收消息及回复确认消息；
* 建立socket连接之后，盒子会首先下发图像帧格式消息，上位机获取到图像格式方可进行图像绘制；
* 若语音模组未收到上位机的确认消息，会在超时500ms之后再发送最新的图像数据，无重发规则；

## 通信格式

![](/media/202407//1720696807.1338985.png)通信格式定义了图像格式消息、人脸检测消息、图像帧消息、确认消息。下面将分类详述：

消息长度：

数据格式中3-6字节为消息数据长度，消息长度编码为小端模式，即第3字节存储低字节，第6字节存储高字节。如确认消息中消息数据有4字节，则消息长度为4，编码到3-6字节就是0x04 0x00 0x00 0x00

消息ID：

数据格式中7-8字节为消息ID，与消息长度类似，也是小端模式编码。可以使用消息ID过滤因超时重发导致的重复消息。两字节长度的消息ID取值0-65535，所以在实际使用中需要循环使用，具体实现可以参考Android平台上的源码实现。

校检码：

数据格式中每种数据类型的最后一个字节都是校检码，由于图像帧数据较大，校验位固定为0x00

编码格式：

消息中字符串类型的数据编码格式为UTF-8。  
图像帧数据为bgr格式的二进制数据

确认消息：

确认消息是一个特殊的消息类型，它是对其他类型消息的确认，它的消息ID与其要确认的消息的ID相同。

如一个图像帧消息的消息ID为0x9527，那对应的确认消息的消息ID也应该是0x9527。

## 图像格式消息

图像格式的数据为json字符串，包含图像的宽、高、格式信息。

{

"format":0, // 0:bgr 1:jpeg

"width":500,

"height":500

}

注意：图像格式仅在建立socket连接时下发一次

## 图像二进制消息

根据图像格式消息获取图像对应的解析格式，默认格式为JPEG压缩格式

JPEG格式

JPEG格式为有损压缩格式，上位机需对图像进行JPEG解压缩，获取原始位图后再进行屏幕渲染。

bgr格式

bgr图像数据为原始图像数据，图像数据传输对网络带宽要求较高，一帧图像的大小为个width*height*3字节，帧率最高25fps，色彩通道顺序为RGB RGB …

## 人脸检测消息

人脸检测结果为json字符串，结果中数据仅作为参考使用。

无人脸时：

{

"hasFace": false, //有无人脸

"wakeup": false, //是否人脸唤醒

"frameIndex": 0 //图像帧id

}

有人脸时：

{

"hasFace": true, //有无人脸

"wakeup": true, //是否人脸唤醒

"frameIndex": 0, //图像帧id

"x": 10, //人脸左上角x坐标

"y": 10, //人脸左上角y坐标

"w": 100, //人脸宽度

"h": 100, // 人脸高度

"faceIndex":101, //人脸跟随id

"headPitch": -0.2, //头姿上下偏转角

"headYaw":-0.2, //头姿左右偏转角

"mouthOcc":false //true:嘴部遮挡 false:嘴部无遮挡

}

# 常见问题

## ****怎么查看AIUI上串口消息的处理接收？****

通过adb logcat -s UART\_Manager:*（adb连接参照调试）查看AIUI串口的日志。

## 串口消息构造后发送给AIUI，为什么没有执行对应操作（如发了合成命令，没有合成播放等）？

没有执行对应操作可能的原因分三种：

* 消息格式构造问题
* 消息ID重复
* 消息内容构造问题

对于上述三种原因可以按如下方法依次排查：

如果收到了AIUI对消息的确认消息，那说明消息构造没问题，反之应该检查下消息构造的格式是否有问题。

因为协议中消息ID的说明，AIUI会对消息ID与之前接受的200条消息ID进行比较，如果有相同则认为是因确认超时重发的消息，而进行过滤，直接返回对应的确认消息，不会对消息进行解析处理。

通过adb logcat -s UART\_Manager:*（adb连接参照调试）查看AIUI串口的日志。 如果log中有:

recv same data, send ack drop it !!!

那说明消息ID与之前有重复，请检查消息ID的构造逻辑问题。

消息内容的构造问题，请仔细对照主控消息内定义的消息内容格式，比如合成消息中的文本内容的编码格式要为utf-8。

## 图像卡顿，1秒仅收到2帧图像数据

![D:\Tencent\WeChat Files\wxid_4109851096612\FileStorage\Temp\20711cd62a3d52583cfb325ee878943.png](/media/202407//1720696807.1527195.png)语音模组如果未收到确认消息，延迟500ms后才发出下一帧数据，可通过查看语音模组adb logcat -s VideoSocketClient:* 日志，观察发送/接收的消息ID的时间是否存在较大间隔，如下图设备端发送完-91,1的消息id，上位机的确认消息延迟了516ms才收到，需要检测下上位机socket发送一包数据后是否执行flush操作。

## 图像传输对带宽的要求

如果传输格式为JPEG压缩格式，使用百兆带宽即可。