AVS SDK Integration

Last Updated on : 2024-06-21 03:25:30download

This topic describes the SDK integration instructions of Tuya Alexa Voice Service (AVS) solution products based on the RK3308 platform.

Application layer interface

tuya_avs_voice_sdk_init

Function: SDK initialization interface, some necessary configuration for initializing SDK, and callback function.
Parameters:
- cfg: some necessary configuration
- opt: optional configuration parameters
- cbs: callback function
Return:
- 0: success
- Other values: failure
Example:

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);

Initialize required configuration parameters

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 flag, indicating whether it is OEM mode.
prodkey: firmware key.
uuid: device identifier.
authkey: device authorization key, which needs to be paired with uuid.
storge_path: configuration file path (requires readable and writable path)
res_path: resource file path (local tts resource, wake word resource)
avspid: AVS PID

Initialize optional configuration parameters

If you do not configure optional configuration parameters, the default values are used.

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: response language. North American English is used by default.
wakeupword_language: wakeup word language. North American English is used by default.
avs_gateway: AVS gateway address. North America is used by default.

Callback

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: Device state callback. If you need to perceive the device state processing needs, you can register this callback function.

typedef OPERATE_RET (*TY_AVS_DEV_STATE_CB)(TUYA_AVS_DEV_STATUS_E stat);

typedef enum {
TY_AVS_DEV_WAITING_NETCFG, // Waiting for pairing
TY_AVS_DEV_NETCFG_FAILED, // Failed to pair
TY_AVS_DEV_NETCFG_SUCC, // Pairing is successful
TY_AVS_DEV_WAITING_AUTH, // Waiting for AVS authorization
TY_AVS_DEV_NET_DISC, // Network disconnected
TY_AVS_DEV_NET_RECOVERY, // Resume connection
TY_AVS_DEV_WAITING_BIND, // Waiting for AVS binding
TY_AVS_DEV_BINDED, // AVS has been bound
TY_AVS_DEV_IDLE, // ASR is in idle state
TY_AVS_DEV_LISTENING, // ASR is in the listen state
TY_AVS_DEV_THINKING, // ASR is in think state
TY_AVS_DEV_SPEAKING, // ASR is in the speak state
TY_AVS_DEV_BT_SCAN, // Bluetooth scan
TY_AVS_DEV_BT_SCAN_EXIT, // Exit luetooth scan
TY_AVS_DEV_BT_CONN, // Bluetooth connection
TY_AVS_DEV_BT_DISCON, // Bluetooth disconnection
TY_AVS_DEV_ACTIVED, // Device activation
TY_AVS_DEV_RESET, // Device reset

} TUYA_AVS_DEV_STATUS_E;

TY_AVS_UG_INFORM_CB: firmware update callback interface. When the OTA update starts, this callback will be triggered after user registration. You can refer to the demo to complete the firmware OTA update.
```
typedef OPERATE_RET (*TY_AVS_UG_INFORM_CB)(FW_UG_S *fw);
```

tuya_avs_voice_sdk_wifi_init

Use built-in WPA to complete network connection and management:

If you use the built-in WPA for network connection and management, you need to call this interface.
If the built-in WPA function is not used, the user needs to implement some HAL interfaces of Wi-Fi. For the specific HAL interface, please refer to the following description.
Parameters:
- wpa_file: WPA configuration file (including absolute path)

Return:

0: success

Other values: failure

OPERATE_RET tuya_avs_voice_sdk_wifi_init(CHAR_T *wpa_file)

tuya_avs_voice_sdk_bt_init

If you use the built-in bluez to complete the Bluetooth function, you need to call this interface. If you don’t use the built-in bluez, you don’t need to call this interface. The user needs to implement some HAL interfaces of bt_port. For the specific HAL interface, refer to the following description.

Parameters: None

Return:

0: success

Other values: failure

OPERATE_RET tuya_avs_voice_sdk_bt_init()

tuya_avs_voice_sdk_iot_init

For IoT related initialization, the interface is required.

Parameters: None

Return:

0: success

Other values: failure

OPERATE_RET tuya_avs_voice_sdk_iot_init()

tuya_avs_voice_sdk_zigbee_init

Zigbee module initialization, optional. If there is a Zigbee module and need to use Zigbee function, you can call it. No need to call the Zigbee function if it is not used.

Parameters: some configurations of Zigbee TUYA_ZB_CONFIG_S.

Return:

0: success

Other values: failure

OPERATE_RET tuya_avs_voice_sdk_zigbee_init(TUYA_ZB_CONFIG_S *zb_cfg)

TUYA_ZB_CONFIG_S parameter description

typedef struct{
CHAR_T serial_port[TY_AVS_MAX_BUF_LEN+1]; // Zigbee serial device number
BOOL_T is_cts; // Whether with flow control
CHAR_T log_dir[TY_AVS_MAX_BUF_LEN+1]; // Log storage directory
CHAR_T tmp_dir[TY_AVS_MAX_BUF_LEN+1]; // Temporary file directory
CHAR_T bin_dir[TY_AVS_MAX_BUF_LEN+1]; // .bin file directory. Do not store files. Other platforms may be read-only file systems
CHAR_T storage_dir[TY_AVS_MAX_BUF_LEN]; // Sub-device information access directory
} TUYA_ZB_CONFIG_S;

tuya_avs_voice_sdk_soc_init and tuya_avs_voice_sdk_mcu_init

Choose one from SoC or MCU development plan initialization. The SDK internally supports the integration of SoC and MCU, which can be called according to your specific needs.

Parameters: SoC has no parameters, and MCU is some parameters related to the serial port.

Return:

0: success

Other values: failure

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

After calling the above initialization interface, call this interface to start the SDK service.

Parameters: None

Return:

0: success

Other values: failure

OPERATE_RET tuya_avs_voice_sdk_start().

Functional interface

Related functions are open, and some events are actively triggered by the device.

Device reset function
```
OPERATE_RET tuya_avs_sdk_dev_reset()
```

Volume setting/acquisition

OPERATE_RET tuya_avs_sdk_set_volume(INT_T value);

INT_T tuya_avs_sdk_get_volume();

Set or get microphone

OPERATE_RET tuya_avs_sdk_set_mic(BOOL_T enable);

BOOL_T tuya_avs_sdk_get_mic();

Control or get the playback status

OPERATE_RET tuya_avs_sdk_set_play(BOOL_T play);

BOOL_T tuya_avs_sdk_get_play();

Wake-up control

OPERATE_RET tuya_avs_sdk_wakeup_ctrl(BOOL_T wakeup);

Control or get Bluetooth

OPERATE_RET tuya_avs_sdk_set_bt(BOOL_T open);

BOOL_T tuya_avs_sdk_get_bt();

Music playback control (previous/next song)

OPERATE_RET tuya_avs_sdk_play_prev();

OPERATE_RET tuya_avs_sdk_play_next();

Modification of wake-up language and response language

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

External custom lighting effect interface
```
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);
```
Description: Users can first obtain all the lighting effect names supported by the SDK according to tuya_avs_sdk_led_available, and then trigger the known lighting effects through tuya_avs_sdk_led_trigger

Turn on or turn off the sub-device access function interface.

OPERATE_RET tuya_avs_sdk_dev_access_start(INT_T timeout)

OPERATE_RET tuya_avs_sdk_dev_access_stop()

Set OTA status. When the device implements OTA, use this function to trigger related light effects.
```
OPERATE_RET tuya_avs_sdk_ota_notify(TUYA_AVS_DEV_OTA_STATUS_E stat, UPGRADE_TYPE_T type);
```

SDK demo

For more information, see demos/demo_default in the SDK.

Custom HAL interface

Basic lighting driver

Mainly realize the lighting driver. Please refer to the BSP document.

Infrared HAL

The infrared HAL interface is related to the underlying infrared driver. It mainly involves infrared parameter settings, infrared transmission, infrared reception and other HAL interfaces.

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;

// Set carrier frequency
extern OPERATE_RET tuya_hal_ir_set_frequency(CONST INT_T frequency);
// Infrared emission HAL, codelist is space and pulse time series, count is the length of codelist.
extern OPERATE_RET tuya_hal_ir_send(ir_raw_code *buf);
// Infrared receiving HAL, codelist is the received space and pulse time series, and len is the length.
extern OPERATE_RET tuya_hal_ir_recv(ir_raw_code *buf, struct timeval *timeout);

Refer to the header file sdk/tuya_avs_voice_sdk_inf/include/tuya_avs_sdk_user_hal.h.

Wi-Fi HAL

Currently, the SDK provides wpa_supplicant to complete the network connection by default. If you do not use the WPA function to complete the network connection, you need to implement the following HAL interface. The SDK uses wpa_supplicant to complete the network connection by default. If you do not use wpa_supplicant, you can contact us to provide the SDK without wpa_supplicant.

Wi-Fi universal HAL interface:

// Use designated SSID and PASSWD to connect to Wi-Fi
OPERATE_RET tuya_hal_wifi_station_connect(IN CONST CHAR_T *ssid,IN CONST CHAR_T *passwd)

// Get the list of SSIDs in the current environment
OPERATE_RET tuya_hal_wifi_all_ap_scan(OUT AP_IF_S **ap_ary,OUT UINT_T *num)

// Get information about a specific SSID
OPERATE_RET tuya_hal_wifi_assign_ap_scan(IN CONST CHAR_T *ssid,OUT AP_IF_S **ap)

// Get Wi-Fi IP address
OPERATE_RET tuya_hal_wifi_get_ip(IN CONST WF_IF_E wf,OUT NW_IP_S *ip)

// Get Wi-Fi MAC address
OPERATE_RET tuya_hal_wifi_get_mac(IN CONST WF_IF_E wf,INOUT NW_MAC_S *mac)

// Set the current Wi-Fi working mode
int tuya_hal_wifi_set_work_mode(const WF_WK_MD_E mode)

// Get the current Wi-Fi working mode
int tuya_hal_wifi_get_work_mode(WF_WK_MD_E *mode)

// Get the current Wi-Fi network status
// High frequency interface
OPERATE_RET tuya_hal_wifi_station_get_status(WF_STATION_STAT_E *stat)

// Get the RSSI of the current Wi-Fi network
OPERATE_RET tuya_hal_wifi_station_get_conn_ap_rssi(OUT SCHAR_T *rssi)

Wi-Fi Easy Connect network has a unique HAL interface:

// Set the working channel of Wi-Fi
OPERATE_RET tuya_hal_wifi_set_cur_channel(IN CONST BYTE_T chan)

// Get Wi-Fi working channel
OPERATE_RET tuya_hal_wifi_get_cur_channel(OUT BYTE_T *chan)

// Set Wi-Fi sniffer packet capture status
OPERATE_RET tuya_hal_wifi_sniffer_set(const bool en, const SNIFFER_CALLBACK cb)

Special HAL interface for hotspot pairing:

// Turn on the hotspot in the hotspot pairing mode
OPERATE_RET tuya_hal_wifi_ap_start(IN CONST WF_AP_CFG_IF_S *cfg)

// Stop hotspot in hotspot pairing mode
OPERATE_RET tuya_hal_wifi_ap_stop(VOID)

// Get the MAC of the current Wi-Fi hotspot
OPERATE_RET tuya_hal_wifi_station_get_ap_mac(INOUT NW_MAC_S *mac)

The following interfaces can be implemented empty:

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)

Refer to the header file sdk/OS_adapter_linux/include/driver/tuya_hal_wifi.h, the universal HAL interface must be realized now, and the Wi-Fi fast connection network and hotspot pairing realize the corresponding HAL interface according to the actual network pairing method. Other interfaces can be directly realized as empty. If you use Bluetooth to complete the network pairing, except for the universal HAL interface that needs to be implemented, other interfaces can be implemented as empty.

Bluetooth HAL

Currently, bluez is used in the SDK to complete Bluetooth-related functions. If you do not use bluez, you need to implement the following HAL interface. (Currently, the Tuya bluez interface is limited to use).

If you do not use Bluetooth to configure the network, do not use the Bluetooth function, do not call the tuya_avs_voice_sdk_bt_init() interface. At the same time, contact Tuya to provide SDK without Bluetooth pairing. At the same time, you need to implement Wi-Fi quick-connect network and hotspot network pairing modes.

Prev DocAVS SDK for RK3308

Next DocLighting Development Based on RK3308