软件定时器

TuyaOS 提供软件定时器，支持毫秒级的定时功能，您可以创建、启动、停止和删除定时器。

软件定时器 主要适用场景如下：

• 单次定时器 TAL_TIMER_ONCE：即仅执行一次，执行完成之后不再执行，等待您删除。

• 循环定时器 TAL_TIMER_CYCLE：会循环执行，一直到您停止或者删除该定时器。

功能描述

​实现定时任务管理功能，采用轮询机制判断是否有定时任务到期。

工作原理

运行环境

关联头文件：tal_sw_timer.h

数据结构

定时类型

/**
 * @brief the type of timer
 */
typedef enum {
    TAL_TIMER_ONCE = 0,
    TAL_TIMER_CYCLE,
}TIMER_TYPE;

定时到达时的回调

typedef PVOID_T TIMER_ID;  // 定时器 ID
typedef VOID_T (* TAL_TIMER_CB)(TIMER_ID timer_id, VOID_T *arg);

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] func: the processing function of the timer
 * @param[in] arg: the parameater of the timer function
 * @param[out] timer_id: timer ID
 *
 * @note This API is used for create 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);

启动软件定时器

/**
 * @brief Start the software timer
 *
 * @param[in] timer_id: timer ID
 * @param[in] time_ms: 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);

判断定时器是否运行

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

删除软件定时器

/**
 * @brief Delete the software timer
 *
 * @param[in] timer_id: 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);

停止软件定时器

/**
* @brief Stop the software timer
*
* @param[in] timer_id: 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);

获取定时器剩余时间

/**
 * @brief Get the software timer remaining time
 *
 * @param[in] timer_id: timer ID
 * @param[in] remain_time: ms
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tal_sw_timer_remain_time_get(TIMER_ID timer_id, UINT_T *remain_time);

触发软件计时器

/**
 * @brief Trigger the software timer
 *
 * @param[in] timer_id: 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);

释放软件定时器的所有资源

/**
 * @brief Release all resource of the software timer
 *
 * @param VOID
 *
 * @note This API is used for releasing all resource 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);

获取定时器节点数量

/**
 * @brief Get timer node currently
 *
 * @param VOID
 *
 * @note This API is used for getting the timer node currently.
 *
 * @return the timer node count.
 */
INT_T tal_sw_timer_get_num(VOID_T);

使用示例

//定时器回调函数
STATIC VOID __fun_timer_cb(UINT_T timerID, PVOID_T pTimerArg)
{

}

VOID __start_soft_timer(VOID)
{
    TIMER_ID test_timer;
    OPERATE_RET op_ret = OPRT_OK;

    tal_sw_timer_init();

    //创建定时器
    op_ret = tal_sw_timer_create((TAL_TIMER_CB)__fun_timer_cb, NULL, &test_timer);
    if (OPRT_OK != op_ret) {
        return;
    }

    //启动单次定时器，周期 1 秒
    op_ret = tal_sw_timer_start(test_timer, 1000, TAL_TIMER_ONCE);
    if (OPRT_OK != op_ret) {
        return;
    }
    return;
}

详细示例代码可参考框架内自带的 TuyaOS 示例集合 中的 system_sw_timer。

常见问题

软件定时器有数量限制吗？

无数量限制，上限取决于系统资源。

软件定时器的最小定时周期是多少？

软件定时器的最小定时周期 10ms。若周期小于 10ms，请选用系统硬件定时器。

使用软件定时器需要注意什么？

• 定时启动和定时器添加都有链表和互斥锁的操作，不要在 硬件中断 中使用。
• 定时器回调中尽量不要执行阻塞太长时间的任务，以免导致其他定时任务无法执行。