开发指南

## 1. 编写⽬的

本⽂档旨在指导⽤户完成AIBot超脑机器⼈套件⾃定义产品开发。

## 2. 准备⼯作

准备好以下物件：
- **AIBot超脑机器⼈套件**
包含开发模组、电源线、WiFi及蓝⽛天线
- **USB TypeC数据线**
⽤于烧录镜像及ADB调试
- **显⽰器⼀台，及HDMI视频线**
⽤于连接开发板显⽰界⾯
- **键盘及⿏标**
⽤于连接开发板进⾏开发与调试
- **外界USB摄像头及USB⻨克⻛**
⽤于连接开发板进⾏视频及⾳频数据采集
- **开发PC**
⽤于开发与调试

## 3. 系统配置
开发模组⾃带**Ubuntu®**系统，接通电源与显⽰器后即可进⼊系统界⾯。
默认⽤户账号：**iflytek**，默认密码：**iflytek**。
系统默认已安装**ROS2**开发环境。
注意：系统需要连接⽹络后⽅可使⽤语⾳交互、IoT登录及视频监控等在线功能︔

## 4. SDK介绍
- **client节点**
⽤于demo展⽰，开发者可根据此节点中的实例代码，熟悉如何与其他各功能节点进⾏通信；
- **launcher节点**
⽤于初始化时，拉起其他各节点，以及传输各节点所需的初始化参数，⽐如APPID等；
- **⾳频采集节点**
⽤于采集⾳频数据并发送给其他节点；
- **摄像头采集节点**
⽤于采集视频数据并发送给其他节点；
- **降噪及唤醒节点**
⽤于语⾳降噪和进⾏唤醒识别，发送降噪后的⾳频及唤醒消息；
- **AIUI节点**
⽤于语⾳识别与交互；
- **CV节点**
⽤于视觉识别功能，如⼿势识别、⼈脸识别、物体检测等；
- **IoT节点**
⽤于连接IoT平台，上传设备状态信息及获取平台下发的控制命令发送给⽤户等；
- **XRTC节点**
⽤于视频推流到平台进⾏远程监控；
- **配置⽂件**
⽤于初始化的⼀些参数配置与⽇志配置；
- **依赖库及资源**
运⾏语⾳交互及CV能⼒需要依赖的基础库与模型⽂件；

## 5. 申请授权
开发套件SDK中包含的AIUI交互、CV识别等能⼒，均需要进⾏授权后⽅可正常使⽤。
**授权⽅法：**提供APPID三元组，以及预计使⽤的设备量、使⽤时间等信息，给到技术⽀持侧进⾏⼈⼯授权︔

## 6. 开发调试
### 6.1 系统架构

![](/media/202304/超脑模组ROS设计v04_1681888763.jpg)

### 6.2 配置管理

各功能节点使⽤统⼀的配置⽂件⽤于配置管理；
配置⽂件的主要功能包括：

- 指定初始化需要启动的节点
- 指定各节点初始化需要的参数，⽐如APPID三元组、设备唯⼀码、⼯作⽬录（⽤于存放模型资源及引擎依赖库、保存⽇志等等）
- 设置⽇志输出格式
	
配置⽂件参考格式如下:

```json
{
	//"init_node_info":"初始化节点, true表⽰需要启动, false表⽰不需要启动",
	"init_node":{
		"aiui":true,
		"iot":false,
		"xrtc":false,
		"cv":false
	},
	//"init_param_info":"初始化参数",
	"init_param":{
		"scene":"main",
		"work_dir":"/path/to/work/dir/xxxxxxxxxxxxx",
		"ability":"spark_xtts"
	},
	//"log_info":"⽇志配置",
	"log":{
		//"level_info":"DEBUG:0, INFO:1, WARN:2, ERROR:3, CRITICAL:4, Default:2",
		"level":2,
		//"format_info":"time:1, thread:2, level:4, function:8, file:16, line:32,
		ALL:-1, OFF:0, Default:47",
		"format":55,
		//"output_info":"console:0, logcat:1, file:2, OFF:0,
		Default:0(Linux/Windows/iOS),1(Android)",
		"output":0,
		//"file_size_info":"max size of log file, unit:KB, range:10~10240,
		default:1024",
		"file_size":1024,
		//"save_path_info":"log saving path, Default: curent work directory",
		"save_path":".",
		"//save_mode_info":"log file saving mode, 0:delete first half then append,
		1:rename current file then append in new one, Default:0",
		"save_mode":0,
		//"color_info":"print level with ANSI color",
		"color":true
	},
	...
	}
```

### 6.3 通信协议

开发者通过ROS标准化接⼝来与SDK内各节点进⾏数据通信；
详细的通信协议，请参考标准化协议接⼝；

### 6.4 运⾏流程
下图简单描述了开发者如何与各节点通信的⼤致流程：

![](/media/202304/无标题2_1681888957.png)

### 6.5 初始化
开发者通过与**launcher**节点通信来进⾏初始化；
初始化过程包含以下步骤：
1. 设置SDK运⾏的⼀些必需参数，⽐如APP三元组、IoT账号以及设备唯一码（UID）；
2. 指定配置⽂件路径（用于设置框架库运行的一些功能参数）与⼯作⽬录（用于存放授权缓存文件、依赖引擎库和模型资源）；
3. 调⽤/r_launcher/init服务，传⼊上述参数，并等待launcher节点响应成功；

完成上述步骤后，即可正常使⽤语⾳交互操作以及⼿势识别等功能；

### 6.6 语⾳交互
语⾳交互功能主要由audio_capture节点、vtn节点和aiui节点和负责，⼤致流程如下：
1. audio_capture节点负责采集原始⾳频数据，并抛出原始音频数据；
2. vtn节点收到原始⾳频数据后，进⾏降噪和回声消除，并发布`/r_vtn/iataudio`话题来抛出降噪后的⾳频；同时将处理后的音频送⼊唤醒引擎进⾏处理，如果识别到用户说了唤醒词，则发布`/r_vtn/event`话题，抛出唤醒结果；
3. aiui节点收到唤醒结果后，开始接收降噪后的⾳频进⾏在线识别，并通过`/r_aiui/result`话题抛出识
别结果与语义结果等；
4. 开发者收到识别语义结果后进⾏后续处理；

### 6.7 视觉交互
视觉交互功能主要由camera节点、和cv节点和负责，⼤致流程如下：
1. camera节点负责采集原始视频数据，并发送`/ucar_camera/image_raw`话题来抛出原始视频数据；
2. cv节点收到视频数据，送⼊引擎进⾏处理，并通过`/r_cv/result`话题抛出处理结果；
3. 开发者收到处理结果后进⾏后续处理；

### 6.8 IoT控制
IoT控制主要由iot节点负责，⼤致流程如下：
1. ⽤户通过机器⼈超脑平台发送控制命令，iot节点收到请求后，通过/r_iot/result抛出对应的命令；
2. 开发者收到控制命令，进⾏后续处理，⽐如运动控制、建图等；

### 6.9 视频监控
视频监控主要由xrtc节点负责，⼤致流程如下：
1. 开发者通过调⽤/r_xrtc/room服务进⼊房间或者退出房间，进⼊房间后即可开始推流，退出房间即可断
开推流；
2. ⽤户通过机器⼈超脑平台进⼊对应的房间来观看监控视频；

### 6.10 ⽇志输出
各节点的运⾏⽇志均通过ROS标准的⽇志系统输出，可直接统⼀进⾏开关或者保存；
配置⽂件中的⽇志模块，可以分别对各节点单独进⾏⽇志输出的等级、格式设置，参⻅6.2⼩节；

### 6.11 异常处理
各节点在发⽣异常报错时，均会通过对应的/node_name/error话题抛出；
开发者收到错误话题后，可根据错误描述进⾏后续的处理，⽐如重启节点或者提⽰⽤户；