AVS SDK 对接文档

更新时间：2024-06-20 08:41:49下载pdf

本文基于 RK3308 平台介绍了涂鸦 AVS（Alexa Voice Service）方案产品的 SDK 对接说明。

应用层接口

tuya_avs_voice_sdk_init

功能：SDK 初始化接口，初始化 SDK 的一些必须配置，和回调函数。
参数：
- cfg：必须的一些配置
- opt：可选的配置参数
- cbs：回调函数
返回：
- 0 成功
- 非 0 失败

示例：

OPERATE_RET tuya_avs_voice_sdk_init(TUYA_AVS_SDK_MUST_CFG_S *cfg, TUYA_AVS_SDK_OPT_CFG_S *opt, TUYA_AVS_SDK_CBS_S *cbs);

初始化必选配置参数

typedef struct {
GW_WF_START_MODE wf_mode;
BOOL_T oem_flag;
CHAR_T prodkey[TY_AVS_MAX_BUF_LEN];
CHAR_T uuid[TY_AVS_MAX_BUF_LEN];
CHAR_T authkey[TY_AVS_MAX_BUF_LEN];
CHAR_T storge_path[TY_AVS_MAX_BUF_LEN];
CHAR_T res_path[TY_AVS_MAX_BUF_LEN];
CHAR_T avspid[TY_AVS_MAX_BUF_LEN];
} TUYA_AVS_SDK_MUST_CFG_S;

oem_flag: oem 标识，是否是oem方式。
prodkey：固件key。
uuid：设备标识id。
authkey：设备授权码，需要与uuid配对使用。
storge_path：配置文件路径（需要可读写的路径）
res_path：资源文件路径（本地tts资源，唤醒词资源）
avspid：avs pid

初始化可选配置参数

若您没有配置可选配置参数，则使用默认值。

typedef struct {
CHAR_T respond_language[TY_AVS_MAX_BUF_LEN];
CHAR_T wakeupword_language[TY_AVS_MAX_BUF_LEN];
CHAR_T avs_gateway[256];
} TUYA_AVS_SDK_OPT_CFG_S;

respond_language 应答语言，默认使用北美英语。
wakeupword_language：唤醒词语言，默认使用北美英语。
avs_gateway：avs 网关地址，默认使用北美区。

回调函数

typedef struct {
TY_AVS_DEV_STATE_CB dev_state_cb;
TY_AVS_UG_INFORM_CB ug_inform_cb;
GW_APP_LOG_PATH_CB upload_log_cb;
} TUYA_AVS_SDK_CBS_S;

TY_AVS_DEV_STATE_CB：设备状态回调，若您需要感知设备状态处理需求，可以通过注册此回调函数。

typedef OPERATE_RET (*TY_AVS_DEV_STATE_CB)(TUYA_AVS_DEV_STATUS_E stat);

typedef enum {
TY_AVS_DEV_WAITING_NETCFG, // 等待配网
TY_AVS_DEV_NETCFG_FAILED, // 配网失败
TY_AVS_DEV_NETCFG_SUCC, // 配网成功
TY_AVS_DEV_WAITING_AUTH, // 等待AVS授权
TY_AVS_DEV_NET_DISC, // 网络断开连接
TY_AVS_DEV_NET_RECOVERY, // 网络恢复连接
TY_AVS_DEV_WAITING_BIND, // 等待avs绑定
TY_AVS_DEV_BINDED, // avs已绑定
TY_AVS_DEV_IDLE, // ASR处于idle状态
TY_AVS_DEV_LISTENING, // ASR处于listen状态
TY_AVS_DEV_THINKING, // ASR处于think状态
TY_AVS_DEV_SPEAKING, // ASR处于speak状态
TY_AVS_DEV_BT_SCAN, // 蓝牙scan
TY_AVS_DEV_BT_SCAN_EXIT, // 蓝牙scan 退出
TY_AVS_DEV_BT_CONN, // 蓝牙连接
TY_AVS_DEV_BT_DISCON, // 蓝牙断开连接
TY_AVS_DEV_ACTIVED, // 设备激活
TY_AVS_DEV_RESET, // 设备重置

} TUYA_AVS_DEV_STATUS_E;

TY_AVS_UG_INFORM_CB：固件升级回调接口。当开始 OTA 升级时，用户注册后，会触发此回调，您可以参考 Demo 完成固件 OTA 升级。
```
typedef OPERATE_RET (*TY_AVS_UG_INFORM_CB)(FW_UG_S *fw);
```

tuya_avs_voice_sdk_wifi_init

使用内置 WPA 来完成网络连接和管理：

若使用内置的 WPA 来网络连接和管理，则需要调用此接口；
若不使用内置的 WPA 功能，则用户需要实现Wi-Fi的一些HAL接口，具体HAL接口参考后面说明。
参数：
- wpa_file：WPA 配置文件（包含绝对路径）

0 成功
非0 失败

OPERATE_RET tuya_avs_voice_sdk_wifi_init(CHAR_T *wpa_file)

tuya_avs_voice_sdk_bt_init

若使用内置的bluez来完成蓝牙功能，则需要调用此接口；若不使用内置的bluez，则无需调用此接口，用户需要实现bt_port的一些HAL接口，具体HAL接口参考后面说明。

参数：无
返回：0 代表成功，非 0 值则代表失败
```
OPERATE_RET tuya_avs_voice_sdk_bt_init()
```

tuya_avs_voice_sdk_iot_init

IoT 相关初始化，必调接口。

参数：无
返回：0 代表成功，非 0 值则代表失败
```
OPERATE_RET tuya_avs_voice_sdk_iot_init()
```

tuya_avs_voice_sdk_zigbee_init

Zigbee 模组初始化，可选，若有 Zigbee 模组且需要使用 Zigbee 功能，则可调用。不使用 Zigbee 功能无需调用。

参数：TUYA_ZB_CONFIG_S Zigbee 的一些配置。

返回：0 代表成功，非 0 值则代表失败

OPERATE_RET tuya_avs_voice_sdk_zigbee_init(TUYA_ZB_CONFIG_S *zb_cfg)

TUYA_ZB_CONFIG_S 参数说明

typedef struct{
CHAR_T serial_port[TY_AVS_MAX_BUF_LEN+1]; // Zigbee串口设备号
BOOL_T is_cts; // 是否带有流控
CHAR_T log_dir[TY_AVS_MAX_BUF_LEN+1]; // 日志存储目录
CHAR_T tmp_dir[TY_AVS_MAX_BUF_LEN+1]; // 临时文件目录
CHAR_T bin_dir[TY_AVS_MAX_BUF_LEN+1]; // bin文件目录，勿存放文件，其他平台可能为只读文件系统
CHAR_T storage_dir[TY_AVS_MAX_BUF_LEN]; // 子设备信息存取目录
} TUYA_ZB_CONFIG_S;

tuya_avs_voice_sdk_soc_init 和 tuya_avs_voice_sdk_mcu_init

SoC 或 MCU 开发方案初始化，二选一。SDK内部支持 SoC 和 MCU 方式对接，根据您的具体需求调用。

参数：SoC 无参数，MCU 是串口相关的一些参数。

返回：0 代表成功，非 0 值则代表失败

OPERATE_RET tuya_avs_voice_sdk_soc_init()

OPERATE_RET tuya_avs_voice_sdk_mcu_init(CHAR_T *name, UINT_T speed, CHAR_T parity, UINT8_T data_bit, UINT8_T stop_bit)

tuya_avs_voice_sdk_start

调用上述初始化接口后，调用该接口启动SDK服务。

参数：无
返回：0 代表成功，非 0 值则代表失败
```
OPERATE_RET tuya_avs_voice_sdk_start()。
```

功能性接口

相关功能开放，由设备主动触发的一些事件。

设备重置功能
```
OPERATE_RET tuya_avs_sdk_dev_reset()
```

音量设置/获取

OPERATE_RET tuya_avs_sdk_set_volume(INT_T value);

INT_T tuya_avs_sdk_get_volume();

设置或获取麦克风

OPERATE_RET tuya_avs_sdk_set_mic(BOOL_T enable);

BOOL_T tuya_avs_sdk_get_mic();

控制或获取播放状态

OPERATE_RET tuya_avs_sdk_set_play(BOOL_T play);

BOOL_T tuya_avs_sdk_get_play();

唤醒控制

OPERATE_RET tuya_avs_sdk_wakeup_ctrl(BOOL_T wakeup);

控制或获取蓝牙

OPERATE_RET tuya_avs_sdk_set_bt(BOOL_T open);

BOOL_T tuya_avs_sdk_get_bt();

音乐播放控制（上一下/下一首）

OPERATE_RET tuya_avs_sdk_play_prev();

OPERATE_RET tuya_avs_sdk_play_next();

唤醒语言和应答语言修改

OPERATE_RET tuya_avs_sdk_change_lacale(CHAR_T *respond_language, CHAR_T *wakeword_language);

对外自定义灯效接口
```
OPERATE_RET tuya_avs_sdk_led_trigger(IN CHAR_T *name);
OPERATE_RET tuya_avs_sdk_led_available(OUT CHAR_T ***names, OUT INT_T *count);
```
说明：用户可以先根据 tuya_avs_sdk_led_available 获取SDK所有支持的灯效名称，然后通过 tuya_avs_sdk_led_trigger 触发知道的灯效

开启或关闭子设备接入功能接口。

OPERATE_RET tuya_avs_sdk_dev_access_start(INT_T timeout)

OPERATE_RET tuya_avs_sdk_dev_access_stop()

设置OTA 状态，设备实现OTA过程中，通过该函数来触发相关灯效。

OPERATE_RET tuya_avs_sdk_ota_notify(TUYA_AVS_DEV_OTA_STATUS_E stat, UPGRADE_TYPE_T type);

SDK Demo

具体参考 SDK 中的 demos/demo_default。

自定义 HAL 接口

基础灯效驱动

主要实现灯效驱动，请参考 BSP 文档。

红外 HAL

红外HAL接口，跟底层红外驱动相关。主要涉及红外参数设置，红外发送，红外接收等HAL接口。

typedef struct ir_raw_code{
int *codelist; /**< space and pulse time array list */
unsigned int count; /**< codelist real data count */
unsigned int size; /**< codelist buffer size */
} ir_raw_code;

// 设置载波频率
extern OPERATE_RET tuya_hal_ir_set_frequency(CONST INT_T frequency);
// 红外发射HAL，codelist为 space and pulse time 系列，count为 codelist的长度。
extern OPERATE_RET tuya_hal_ir_send(ir_raw_code *buf);
// 红外接收HAL，codelist 为接收到 space and pulse time 系列，len 为长度。
extern OPERATE_RET tuya_hal_ir_recv(ir_raw_code *buf, struct timeval *timeout);

参考头文件 sdk/tuya_avs_voice_sdk_inf/include/tuya_avs_sdk_user_hal.h。

Wi-Fi HAL

目前SDK中默认提供使用wpa_supplicant来完成网络连接。若不使用 WPA 功能来完成网络连接，需要实现以下HAL接口（SDK 默认使用 wpa_supplicant 来完成网络连接，若不使用联系涂鸦提供不带 wpa_supplicant 的 SDK）

Wi-Fi 通用 HAL 接口：

// 使用指定SSID和PASSWD连接Wi-Fi
OPERATE_RET tuya_hal_wifi_station_connect(IN CONST CHAR_T *ssid,IN CONST CHAR_T *passwd)

// 获取当前环境下的SSID列表
OPERATE_RET tuya_hal_wifi_all_ap_scan(OUT AP_IF_S **ap_ary,OUT UINT_T *num)

// 获取特定SSID的信息
OPERATE_RET tuya_hal_wifi_assign_ap_scan(IN CONST CHAR_T *ssid,OUT AP_IF_S **ap)

// 获取Wi-Fi的IP地址
OPERATE_RET tuya_hal_wifi_get_ip(IN CONST WF_IF_E wf,OUT NW_IP_S *ip)

// 获取Wi-Fi的MAC地址
OPERATE_RET tuya_hal_wifi_get_mac(IN CONST WF_IF_E wf,INOUT NW_MAC_S *mac)

// 设置当前Wi-Fi工作模式
int tuya_hal_wifi_set_work_mode(const WF_WK_MD_E mode)

// 获取当前Wi-Fi工作模式
int tuya_hal_wifi_get_work_mode(WF_WK_MD_E *mode)

// 获取当前Wi-Fi联网状态
//高频接口
OPERATE_RET tuya_hal_wifi_station_get_status(WF_STATION_STAT_E *stat)

// 获取当前Wi-Fi联网的RSSI
OPERATE_RET tuya_hal_wifi_station_get_conn_ap_rssi(OUT SCHAR_T *rssi)

Wi-Fi 快连配网特有 HAL 接口：

// 设置Wi-Fi的工作信道
OPERATE_RET tuya_hal_wifi_set_cur_channel(IN CONST BYTE_T chan)

// 获取Wi-Fi的工作信道
OPERATE_RET tuya_hal_wifi_get_cur_channel(OUT BYTE_T *chan)

// 设置Wi-Fi的sniffer抓包状态
OPERATE_RET tuya_hal_wifi_sniffer_set(const bool en, const SNIFFER_CALLBACK cb)

热点配网特有 HAL 接口：

// 热点配网模式下开启热点
OPERATE_RET tuya_hal_wifi_ap_start(IN CONST WF_AP_CFG_IF_S *cfg)

// 热点配网模式下停止热点
OPERATE_RET tuya_hal_wifi_ap_stop(VOID)

// 获取当前Wi-Fi 热点的MAC
OPERATE_RET tuya_hal_wifi_station_get_ap_mac(INOUT NW_MAC_S *mac)

以下接口空实现即可：

OPERATE_RET tuya_hal_wifi_set_mac(IN CONST WF_IF_E wf,IN CONST NW_MAC_S *mac)

OPERATE_RET tuya_hal_wifi_get_bssid(uint8_t mac[6])

OPERATE_RET tuya_hal_set_wifi_lp_mode(const bool en, const unsigned int dtim)

OPERATE_RET tuya_hal_wifi_set_country_code(const COUNTRY_CODE_E ccode)

OPERATE_RET tuya_hal_wifi_set_socket_broadcast_all(const int socket_fd, const bool enable)

OPERATE_RET tuya_hal_wifi_close_concurrent_ap(void)

OPERATE_RET tuya_hal_wifi_send_mgnt(const uint8_t *buf, const uint32_t len)

OPERATE_RET tuya_hal_wifi_register_recv_mgnt_callback(bool enable, WIFI_REV_MGNT_CB recv_cb)

OPERATE_RET tuya_hal_wifi_station_disconnect(VOID)

参考头文件 sdk/OS_adapter_linux/include/driver/tuya_hal_wifi.h，通用HAL接口必现实现，Wi-Fi 快连配网和热点配网根据实际配网方式实现对应HAL接口。其他接口可直接实现为空。若使用蓝牙完成配网，除了通用HAL接口需要实现外，其他接口都可以实现为空。

蓝牙 HAL

目前 SDK 中使用的是bluez来完成蓝牙相关功能。若不使用bluez，需要实现以下HAL接口。(目前限定使用涂鸦 bluez接口)。

若不使用蓝牙配网，不使用蓝牙功能，不调用tuya_avs_voice_sdk_bt_init()接口。同时联系涂鸦提供不带蓝牙配网的SDK。同时您需要实现 Wi-Fi 快连配网和热点配网模式。

上一篇基于 RK3308 的 SDK 参考

下一篇基于 RK3308 的灯效开发