HAL API 接口示例

更新时间：2023-01-29 07:32:07下载pdf

HAL 层 API 是涂鸦抽象各芯片硬件外设封装的一层标准接口，您无需接入涂鸦平台的各种芯片硬件外设底层实现逻辑，只需调用统一的 API，填写相应参数，即可快速使用相关外设，完成产品功能，加快产品的开发速度。

当前 SDK 版本支持 UART、Software（软件定时）、ADC、PWM 等外设接口。用户可参考以下各外设 API 示例 demo 来实现相关功能。

HAL 层列表如下：

名称	功能说明
UART	UART 外设相关函数的使用说明
TIMER	TIMER 外设相关函数的使用说明
ADC	ADC 外设相关函数的使用说明
PWM	PWM 外设相关函数的使用说明

UART

UART 接口文件为 TuyaOS\include\components\tal_driver\include\tal_uart.h 文件。

API 列表

函数名称	功能描述
`tal_uart_init`	串口初始化
`tal_uart_read`	串口接收
`tal_uart_write`	串口发送
`tal_uart_deinit`	关闭串口

API 说明

串口初始化函数：初始化串口，申请资源。

函数原型：
```
OPERATE_RET tal_uart_init(UINT32_T port_id, TAL_UART_CFG_T *cfg);
```
参数说明：

参数名称参数类型说明

port_id UINT32_T 串口 ID

*cfg TAL_UART_CFG_T TAL_UART_CFG_T 枚举中的值
串口接收函数

函数原型：
```
INT_T tal_uart_read(UINT32_T port_id, UINT8_T *data, UINT32_T len);
```
参数说明：

参数名称参数类型说明

port_id UINT32_T 串口 ID

*data UINT8_T 接收数据存放地址的指针

len UINT32_T 接收数据的最大长度
串口发送函数

函数原型：
```
INT_T tal_uart_write(UINT32_T port_id, CONST UINT8_T *data, UINT32_T len);
```
参数说明：

参数名称参数类型说明

port_id UINT32_T 串口 ID

*data UINT8_T 发送数据的指针

len UINT32_T 发送数据长度
串口关闭函数

函数原型：
```
OPERATE_RET tal_uart_deinit(UINT32_T port_id);
```
参数说明：

参数名称参数类型说明

port_id UINT32_T 串口 ID

参数名称	参数类型	说明
`port_id`	`UINT32_T`	串口 ID
`*cfg`	`TAL_UART_CFG_T`	`TAL_UART_CFG_T` 枚举中的值

参数名称	参数类型	说明
`port_id`	`UINT32_T`	串口 ID
`*data`	`UINT8_T`	接收数据存放地址的指针
`len`	`UINT32_T`	接收数据的最大长度

参数名称	参数类型	说明
`port_id`	`UINT32_T`	串口 ID
`*data`	`UINT8_T`	发送数据的指针
`len`	`UINT32_T`	发送数据长度

参数名称	参数类型	说明
`port_id`	`UINT32_T`	串口 ID

串口使用示例

tal_uart.h 文件有详细的接口定义，串口使用有一定的限制，需要在 tuya_init_first 或以后再使用。下面通过一个使用串口接收和发送信息的例子来展示使用方法。

OPERATE_RET uart_demo(VOID_T)
{
    UINT32_T op_ret;
    UINT8_T uart0_rx_buf[BUFFER_SIZE];
    TAL_UART_CFG_T uart_cfg = {
        .rx_buffer_size = 256,
        .open_mode = 0,
        {
            .baudrate = 115200,
            .parity = TUYA_UART_PARITY_TYPE_NONE,
            .databits = TUYA_UART_DATA_LEN_8BIT,
            .stopbits = TUYA_UART_STOP_LEN_1BIT,
            .flowctrl = TUYA_UART_FLOWCTRL_NONE,
        }
    };
    tal_uart_init(USER_UART0, &uart_cfg);

    tal_uart_write(USER_UART0, "Hello uart0 init!\r\n", 20);

    op_ret = tal_uart_read(USER_UART0, uart0_rx_buf, strlen(uart0_rx_buf));

    TAL_PR_DEBUG("uart0_rx_buf : %s\r\n");

    if (op_ret > 0) {

         tal_uart_write(USER_UART0, uart0_rx_buf, strlen(uart0_rx_buf));

     }   else{

         tal_uart_write(USER_UART0, "no recv data\r\n", 15);

     }

    return OPRT_OK;
}

Timer

API 列表

函数名称	功能描述
`tal_sw_timer_init`	软件定时器初始化
`tal_sw_timer_create`	创建软件定时器
`tal_sw_timer_delete`	删除软件定时器
`tal_sw_timer_stop`	停止软件定时器
`tal_sw_timer_is_running`	软件定时器正在运行
`tal_sw_timer_start`	启动软件定时器
`tal_sw_timer_trigger`	触发软件定时器
`tal_sw_timer_release`	释放软件定时器所有资源

API 说明

软件定时器初始化函数

函数原型：

/**
 * @brief Initializing the software timer
 *
 * @param VOID
 *
 * @note This API is used for initializing the software timer
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tal_sw_timer_init(VOID_T);

创建软件定时器函数

函数原型：

/**
 * @brief create a software timer
 *
 * @param[in] pTimerFunc: the processing function of the timer
 * @param[in] pTimerArg:  the parameater of the timer function
 * @param[out] p_timerID: timer id
 *
 * @note This API is used for creating a software timer
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tal_sw_timer_create(TAL_TIMER_CB func, VOID_T *arg, TIMER_ID *timer_id);

参数说明：

参数名称	参数类型	说明
`func`	`TAL_TIMER_CB`	定时器的处理功能
`*arg`	`VOID_T`	定时器函数的参数
`*timer_id`	`TIMER_ID`	定时器 ID

删除软件定时器函数

函数原型：

/**
 * @brief Delete the software timer
 *
 * @param[in] timerID: timer id
 *
 * @note This API is used for deleting the software timer
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tal_sw_timer_delete(TIMER_ID timer_id);

参数说明：

参数名称	参数类型	说明
`timer_id`	`TIMER_ID`	定时器ID

软件定时器启动函数

函数原型：

/**
 * @brief Start the software timer
 *
 * @param[in] timerID:    timer id
 * @param[in] timeCycle:  timer running cycle
 * @param[in] timer_type: timer type
 *
 * @note This API is used for starting the software timer
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tal_sw_timer_start(TIMER_ID timer_id, TIME_MS time_ms, TIMER_TYPE timer_type);

参数说明：

参数名称	参数类型	说明
`timer_id`	`TIMER_ID`	定时器 ID
`time_ms`	`TIME_MS`	定时器定时时间
`timer_type`	`TIMER_TYPE`	定时器运行类型：单次/循环

定时类型：

  typedef PVOID_T TIMER_ID;  // 定时器 ID
  typedef VOID_T (* TAL_TIMER_CB)(TIMER_ID timer_id, VOID_T *arg);   //定时器回调函数类型

  /**
  * @brief the type of timer
  */
  typedef enum {
      TAL_TIMER_ONCE = 0,    //单次运行，定时器超时后停止计数
      TAL_TIMER_CYCLE,       //循环运行，定时器超时后重新开始计数
  }TIMER_TYPE;

软件定时器停止函数

函数原型：

/**
 * @brief Stop the software timer
 *
 * @param[in] timerID: timer id
 *
 * @note This API is used for stopping the software timer
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tal_sw_timer_stop(TIMER_ID timer_id);

参数说明：

参数名称	参数类型	说明
`timer_id`	`TIMER_ID`	定时器 ID

软件定时器运行中函数

函数原型：

/**
 * @brief Identify the software timer is running
 *
 * @param[in] timerID: timer id
 *
 * @note This API is used to identify whether the software timer is running
 *
 * @return TRUE or FALSE
 */
BOOL_T tal_sw_timer_is_running(TIMER_ID timer_id);

参数说明：

参数名称	参数类型	说明
`timer_id`	`TIMER_ID`	定时器 ID

触发软件定时器函数

函数原型：

/**
 * @brief Trigger the software timer
 *
 * @param[in] timerID: timer id
 *
 * @note This API is used for triggering the software timer instantly.
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tal_sw_timer_trigger(TIMER_ID timer_id);

参数说明：

参数名称	参数类型	说明
`timer_id`	`TIMER_ID`	定时器 ID

释放软件定时器函数

函数原型：

/**
 * @brief Release all resources of the software timer
 *
 * @param VOID
 *
 * @note This API is used for releasing all resources of the software timer
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tal_sw_timer_release(VOID_T);

软件定时器使用示例

本节介绍 software timer 的使用方法，tal_sw_timer.h 中有详细的接口定义。下面是 software timer 的使用例子：创建定时器设置定时时间，当时间到之后打开串口输出打印信息。

// 1. 定义一个定时器变量 ID，不需要初始化参数
TIMER_ID etimer_bright_delay;

// 2. 定义定时器回调函数
VOID_T app_light_bright_cb(TKL_TIMER_ID timer_id, VOID_T *arg)

{

    TAL_PR_DEBUG("--------app_light_bright_cb-------\r\n");

    tal_gpio_write(LED0_GPIO_NUM, LED_STATUS_OFF);

}

// 3. 在 `tuya_init_second` 或者之后两层中创建定时器，将定时器和回调函数绑定在一起
tal_sw_timer_create(app_light_bright_cb, NULL, &etimer_bright_delay);

// 4. 在需要调用定时器事件的时候开启定时器
//     第一个参数为定时器 ID
//     第二个参数为定时器定时时间
//     第三个参数为 flag，once: 定时器只运行一次，cycle: 周期运行

tal_sw_timer_start(etimer_bright_delay, POWER_UP_LED_ON_TIME, TAL_TIMER_ONCE);

// 5. 在需要关闭定时器的时候调用关闭的接口，参数为需要关闭的定时器 ID。
tkl_sw_timer_stop(etimer_bright_delay);

ADC

API 列表

函数名称	功能描述
`tal_adc_init`	ADC 初始化
`tal_adc_deinit`	关闭 ADC 函数
`tal_adc_read_data`	ADC 读取函数
`tal_adc_read_single_channel`	ADC 读取信号通道数
`tal_adc_width_get`	ADC 获取宽度值
`tal_adc_temperature_get`	ADC 获取温度值
`tal_adc_ref_voltage_get`	获取 ADC 电压值

API 说明

ADC 初始化函数

函数原型：

/**
 * @brief tuya hal adc init
 * 
 * @param[in] unit_num: adc unit number
 * @param[in] cfg: adc config
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tal_adc_init(UINT32_T unit_num, TUYA_ADC_BASE_CFG_T *cfg);

参数说明：

参数名称	参数类型	说明
`unit_num`	`UINT32_T`	单元通道 ID
`*cfg`	`TUYA_ADC_BASE_CFG_T`	`TUYA_ADC_BASE_CFG_T` 结构体中的值

数据类型：

/**
 * ADC采样类型
 */
typedef enum {
    TUYA_ADC_INNER_SAMPLE_VOL = 0,
    TUYA_ADC_EXTERNAL_SAMPLE_VOL
} TUYA_ADC_TYPE_E;

/**
 * ADC 配置
 */
typedef struct {
    UINT8_T *ch_list;       //ADC 通道列表
    UINT8_T ch_nums;        //ADC 通道数
    UINT8_T  width;         //采样宽度
    TUYA_ADC_TYPE_E type;   //类型
    UINT32_T   ref_vol;     //参考电压（bat: mv），如果不支持设置参考电压，忽略它
} TUYA_ADC_BASE_CFG_T;

关闭 ADC 函数

函数原型：

/**
 * @brief adc deinit
 * 
 * @param[in] unit_num: adc unit number
 * @param[in] ch_num: adc channel number
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tal_adc_deinit(UINT32_T unit_num);

参数说明：

参数名称	参数类型	说明
`unit_num`	`UINT32_T`	单元通道 ID

ADC 读取函数

函数原型：

/**
 * @brief adc read
 * 
 * @param[in] unit_num: adc unit number
 * @param[out] buff: points to the list of data read from the ADC register
 * @param[out] len:  buff len
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tal_adc_read_data(UINT32_T unit_num, UINT32_T *buff, UINT8_T len);

参数说明：

参数名称	参数类型	说明
`unit_num`	`UINT32_T`	单元通道 ID
`*buff`	`UINT32_T`	指向从 ADC 寄存器读取的数据列表
`len`	`UINT32_T`	数据长度

ADC 读取信号通道数

函数原型：

/**
 * @brief read single channel
 *
 * @param[in] unit_num: adc unit number
 * @param[in] ch_num: channel number in one unit
 * @param[out] buf: convert result buffer
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 *
 */
OPERATE_RET tal_adc_read_single_channel(UINT32_T unit_num, UINT8_T ch_num, UINT32_T *buf);

参数说明：

参数名称	参数类型	说明
`unit_num`	`UINT32_T`	单元通道 ID
`ch_num`	`UINT8_T`	每个单元中的通道数
`*buf`	`UINT32_T`	转换结果缓冲区

ADC 获取宽度值

函数原型：

/**
 * @brief get adc width
 * 
 * @param[in] unit_num: adc unit number

 *
 * @return adc width
 */
UINT8_T tal_adc_width_get(UINT32_T unit_num);

参数说明：

参数名称	参数类型	说明
`unit_num`	`UINT32_T`	单元通道 ID

ADC 获取温度值

函数原型：

/**
 * @brief adc get temperature
 *
 * @return temperature(bat: 'C)
 */
INT32_T tal_adc_temperature_get(VOID_T);

获取 ADC 电压值

函数原型：

/**
 * @brief get adc reference voltage
 * 
 * @param[in] port: adc port

 *
 * @return adc reference voltage(bat: mv)
 */
UINT32_T tal_adc_ref_voltage_get(VOID_T);

ADC 应用示例

读取 ADC 电压值并通过串口输出电压信息。

/*
 * @FileName: your project
 * @Author: Tuya
 * @Email:
 * @LastEditors: Tuya
 * @Date: 2022-03-07 14:24:24
 * @LastEditTime: 2022-03-16 15:58:12
 * @Copyright: HANGZHOU TUYA INFORMATION TECHNOLOGY CO.,LTD
 * @Company:  http://www.tuya.com
 * @Description:
 */

#include "tal_system.h"
#include "tal_gpio.h"
#include "tuya_adc_demo.h"
#include "tal_adc.h"
#include "tkl_adc.h"
#include "tal_uart.h"
#include "tal_log.h"
#include "tal_sw_timer.h"

/***********************************************************
************************micro define************************
***********************************************************/
#define adc_ch_num 1
#define adc_width 1000
#define ADC_LIST *GPIO_PIN
#define ADC_SAMPLE_TIME_MS 1000
#define adc_type TUYA_ADC_INNER_SAMPLE_VOL

TIMER_ID etimer_adc;
BOOL_T g_user_adc_init_flag = FALSE;
STATIC UCHAR_T sg_adc_channel = 0;
extern OPERATE_RET tkl_adc_mapping_to_gpio(UINT32_T ch_id, UINT32_T gpio_id);

VOID_T adc_ch_num_set(UCHAR_T channel_num)
{
    sg_adc_channel = channel_num;
}

OPERATE_RET tuya_adc_init(VOID_T)
{
    UINT32_T adc_data;
    OPERATE_RET v_ret = OPRT_COM_ERROR;

    TUYA_ADC_BASE_CFG_T adc_cfg = {
    .ch_list = ADC_LIST[0],
    .ch_nums = adc_ch_num,
    .width = adc_width,
    .type = adc_type,
};

    tkl_adc_mapping_to_gpio(0, 17);   //PD2;

    v_ret = tal_adc_init(0, &adc_cfg);


    if (v_ret != OPRT_OK) {
        TAL_PR_DEBUG("adc init error!");
    }

    g_user_adc_init_flag = TRUE;
    adc_ch_num_set(adc_ch_num);

    TAL_PR_DEBUG("adc init ok!");

    return v_ret;

}

PWM

API 列表

函数名称	功能描述
`tal_pwm_init`	PWM 初始化
`tal_pwm_deinit`	关闭 PWM
`tal_pwm_start`	PWM 启动函数
`tal_pwm_stop`	PWM 停止函数
`tal_pwm_info_set`	设置 PWM 信息
`tal_pwm_info_get`	获取

API 说明

PWM 初始化函数

函数原型：

/**
 * @brief pwm init
 * 
 * @param[in] ch_id: pwm channal id,id index starts from 0
 * @param[in] cfg: pwm config
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tal_pwm_init(UINT32_T ch_id, TUYA_PWM_BASE_CFG_T *cfg);

参数说明：

参数名称	参数类型	说明
`ch_id`	`UINT32_T`	PWM 通道 ID，索引从 `0` 开始
`*cfg`	`TUYA_PWM_BASE_CFG_T`	`TUYA_PWM_BASE_CFG_T` 结构体中的值

/**
 * @brief pwm config
 */
typedef struct {
    TUYA_PWM_POLARITY_E  polarity;    //PWM 输出极性
    UINT_T              duty;       // 占空比（bet: 10000 == 1/100）
    UINT_T              frequency;  // 频率（bet: Hz）
} TUYA_PWM_BASE_CFG_T;

PWM 启动函数

函数原型：

/**
 * @brief pwm start
 * 
 * @param[in] ch_id: pwm channal id,id index starts at 0
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tal_pwm_start(UINT32_T ch_id);

参数说明：

参数名称	参数类型	说明
`ch_id`	`UINT32_T`	PWM 通道 ID，索引从 `0` 开始

PWM 停止函数

函数原型：

/**
 * @brief pwm stop
 * 
 * @param[in] ch_id: pwm channal id,id index starts from 0
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tal_pwm_stop(UINT32_T ch_id);

参数说明：

参数名称	参数类型	说明
`ch_id`	`UINT32_T`	PWM 通道 ID，索引从 `0` 开始

PWM 关闭函数

函数原型：

/**
 * @brief pwm deinit
 * 
 * @param[in] ch_id: pwm channal id,id index starts from 0
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tal_pwm_deinit(UINT32_T ch_id);

参数说明：

参数名称	参数类型	说明
`ch_id`	`UINT32_T`	PWM 通道 ID，索引从 `0` 开始

设置 PWM 函数

函数原型：

/**
 * @brief set pwm info
 * 
 * @param[in] ch_id: pwm channal id,id index starts from 0
 * @param[in] info: pwm info
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tal_pwm_info_set(UINT32_T ch_id, TUYA_PWM_BASE_CFG_T *info);

参数说明：

参数名称	参数类型	说明
`ch_id`	`UINT32_T`	PWM 通道 ID，索引从 `0` 开始
`*info`	`TUYA_PWM_BASE_CFG_T`	`TUYA_PWM_BASE_CFG_T` 结构体中的值

获取 PWM 函数

函数原型：

/**
 * @brief get pwm info
 * 
 * @param[in] ch_id: pwm channal id,id index starts from 0
 * @param[out] info: pwm info
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tal_pwm_info_get(UINT32_T ch_id, TUYA_PWM_BASE_CFG_T *info);

参数说明：

参数名称	参数类型	说明
`ch_id`	`UINT32_T`	PWM 通道 ID，索引从 `0` 开始
`*info`	`TUYA_PWM_BASE_CFG_T`	`TUYA_PWM_BASE_CFG_T` 结构体中的值

PWM 使用示例

tal_pwm.h 文件中有详细的接口定义，下面通过一个 PWM 输出控制灯闪烁的例子来说明使用方法。

#define pwm_ch_num 2
#define pwm_duty 500
#define pwm_frequency 1000
#define pwm_polarity TUYA_PWM_POSITIVE

BOOL_T g_pwm_bPolarity = FALSE;
BOOL_T g_user_pwm_init_flag = FALSE;

/**
 * @brief pwm config
 */
typedef struct {
    TUYA_PWM_POLARITY_E  polarity;
    UINT_T              duty;       // (bet: 10000 == 1/100)
    UINT_T              frequency;  // (bet: Hz)
} TUYA_PWM_BASE_CFG_T;


OPERATE_RET app_pwm_init(VOID_T)
{
    OPERATE_RET v_ret = OPRT_COM_ERROR;

    TUYA_PWM_BASE_CFG_T v_cfg = {
        .duty = 0,
        .frequency = pwm_frequency,
        .polarity = pwm_polarity,
    };
    tkl_pwm_mapping_to_gpio(0, 8);//PB1;

    v_ret = tal_pwm_init(0, &v_cfg);
    v_ret = tal_pwm_start(0);
    if(v_ret!=OPRT_OK) {
        TAL_PR_DEBUG("pwm init error!");
    }
    g_user_pwm_init_flag = TRUE;

    g_pwm_bPolarity = pwm_polarity;
    app_light_ctrl_ch_num_set(pwm_ch_num);
    TAL_PR_DEBUG("pwm init ok!");
    return v_ret;
}