Software Timer

This topic describes how to create, start, stop, and delete a software timer that can measure time in milliseconds.

The software timer applies to the following use cases:

• TAL_TIMER_ONCE: A one-time timer that executes once and is then ready for deletion.

• TAL_TIMER_CYCLE: A timer that repeats according to a preset schedule until it is stopped or deleted.

Features

Manage scheduled tasks using a polling mechanism to regularly check their readiness.

How it works

Runtime environment

Reference the header file tal_sw_timer.h.

Data structure

Timer type

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

Timer expiration callback

typedef PVOID_T TIMER_ID;  // Timer ID
typedef VOID_T (* TAL_TIMER_CB)(TIMER_ID timer_id, VOID_T *arg);

API description

Initialize software timer

The software timer should be initialized during system service initialization. In other words, if you have already invoked system service initialization, there is no need to trigger software timer initialization.

/**
 * @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);

Create a software timer

/**
 * @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);

Start a software timer

/**
 * @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);

Check if the timer is running

/**
 * @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);

Delete a software timer

/**
 * @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);

Stop a software timer

/**
* @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);

Get the time left on the timer

/**
 * @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);

Trigger a software timer

/**
 * @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);

Free the memory allocated for a software timer

/**
 * @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);

Get the number of the nodes in a timer

/**
 * @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);

Example

// Timer callback
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();

    // Create a timer
    op_ret = tal_sw_timer_create((TAL_TIMER_CB)__fun_timer_cb, NULL, &test_timer);
    if (OPRT_OK != op_ret) {
        return;
    }

    // Start a one-time timer, with a timeout of 1s
    op_ret = tal_sw_timer_start(test_timer, 1000, TAL_TIMER_ONCE);
    if (OPRT_OK != op_ret) {
        return;
    }
    return;
}

system_sw_timer in TuyaOS example collection contains the complete example code.

FAQs

Is there a limit on the number of software timers?

There is no set limit. The limit depends on the system resources.

What is the minimum timeout period of a timer?

It is 10 milliseconds. If you require a timeout of less than 10 milliseconds, opt for a hardware timer instead.

What are the considerations when using software timers?

• Avoid running scheduled startup and timer creation in hardware interrupts as they both involve operations with linked lists and mutexes.
• Avoid executing tasks in timer callbacks that block the queue for too long, as this may disrupt the functioning of other jobs.