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 快连配网和热点配网模式。