meshx_os_timer.h File Reference

Header file for OS timer utilities. More...

#include <stdint.h>
#include "sys/queue.h"
#include "meshx_control_task.h"
#include "interface/rtos/meshx_rtos_timer.h"

Go to the source code of this file.

Data Structures
struct	meshx_os_timer
	Structure to hold parameters for the OS timer control task message. More...

Macros
#define	OS_TIMER_SIZE   sizeof(meshx_os_timer_t)
	return meshx_os_timer_t size
#define	OS_TMER_GET_TIMER_NAME(timer)
	return timer registered name pointer

Typedefs
typedef meshx_rtos_timer_t	meshx_os_timer_handle_t
	Alias for the meshx_rtos_timer_t type.
typedef struct meshx_os_timer	meshx_os_timer_t
	Alias for the meshx_os_timer structure.
typedef void(*	meshx_os_timer_cb_t) (const meshx_os_timer_t *p_timer)
	Timer callback function prototype.

Functions
meshx_err_t	meshx_os_timer_init (void)
	Initialize the OS timer module.
meshx_err_t	meshx_os_timer_create (const char *name, uint32_t period, bool reload, meshx_os_timer_cb_t cb, meshx_os_timer_t **timer_handle)
	Create a timer.
meshx_err_t	meshx_os_timer_start (const meshx_os_timer_t *timer_handle)
	Start a timer.
meshx_err_t	meshx_os_timer_restart (const meshx_os_timer_t *timer_handle)
	Restart a timer.
meshx_err_t	meshx_os_timer_set_period (meshx_os_timer_t *timer_handle, const uint32_t period_ms)
	Set period on an initialised timer.
meshx_err_t	meshx_os_timer_stop (const meshx_os_timer_t *timer_handle)
	Stop a timer.
meshx_err_t	meshx_os_timer_delete (meshx_os_timer_t **timer_handle)
	Delete a timer.

Detailed Description

Header file for OS timer utilities.

Copyright © 2024 - 2025 MeshX

This file contains the definitions and includes necessary for working with OS timers in the ESP32 BLE mesh node application.

Author

Pranjal Chanda

Macro Definition Documentation

OS_TIMER_SIZE

#define OS_TIMER_SIZE   sizeof(meshx_os_timer_t)

return meshx_os_timer_t size

OS_TMER_GET_TIMER_NAME

#define OS_TMER_GET_TIMER_NAME

(

timer

)

Value:

(timer->timer_handle.timer_name)

return timer registered name pointer

Typedef Documentation

meshx_os_timer_cb_t

typedef void(* meshx_os_timer_cb_t) (const meshx_os_timer_t *p_timer)

Timer callback function prototype.

This function is called when the timer expires.

Parameters

[in]

p_timer

The timer handle.

meshx_os_timer_handle_t

typedef meshx_rtos_timer_t meshx_os_timer_handle_t

Alias for the meshx_rtos_timer_t type.

This typedef provides a more convenient name for the FreeRTOS timer handle type, used for creating and managing timers.

meshx_os_timer_t

typedef struct meshx_os_timer meshx_os_timer_t

Alias for the meshx_os_timer structure.

This typedef provides a more convenient name for the meshx_os_timer structure, which holds the parameters for the OS timer control task message.

Function Documentation

meshx_os_timer_create()

meshx_err_t meshx_os_timer_create	(	const char *	name,
		uint32_t	period,
		bool	reload,
		meshx_os_timer_cb_t	cb,
		meshx_os_timer_t **	timer_handle )

Create a timer.

This function creates a timer with the given period and callback function.

Parameters

[in]	name	The name of the timer.
[in]	period	The period of the timer in milliseconds.
[in]	reload	If true, the timer will automatically reload after expiring.
[in]	cb	The callback function to be called when the timer expires.
[in,out]	timer_handle	The timer handle.

Example:

meshx_os_timer_t * meshx_os_timer_inst;
meshx_err_t err = meshx_os_timer_create("Example_Timer", 1000, 1, &example_os_timer_cb, &os_timer_inst);

Returns

MESHX_SUCCESS on success, or an error code on failure.

{
    if (timer_handle == NULL)
    {
        return MESHX_INVALID_STATE;
    }
 
    if ((*timer_handle) != NULL && (*timer_handle)->init == OS_TIMER_INIT_MAGIC)
        return MESHX_INVALID_STATE;
 
    meshx_err_t err = MESHX_SUCCESS;
 
    *timer_handle = (meshx_os_timer_t *)MESHX_MALLOC(OS_TIMER_SIZE);
    if (*timer_handle == NULL)
        return MESHX_NO_MEM;
 
    (*timer_handle)->cb = cb;
    (*timer_handle)->period = period;
 
    err = meshx_rtos_timer_create(&(*timer_handle)->timer_handle,
        name,
        (meshx_rtos_timer_callback_t)&meshx_os_timer_fire_cb,
        *timer_handle,
        period,
        reload);
    if (err)
    {
        MESHX_FREE(*timer_handle);
        return err;
    }
 
    SLIST_INSERT_HEAD(&meshx_os_timer_reg_table_head, (*timer_handle), next);
    (*timer_handle)->init = OS_TIMER_INIT_MAGIC;
 
    return err;
}

meshx_os_timer_delete()

meshx_err_t meshx_os_timer_delete

(

meshx_os_timer_t **

timer_handle

)

Delete a timer.

This function deletes the given timer.

Parameters

timer_handle

The timer handle.

Returns

MESHX_SUCCESS on success, or an error code on failure.

{
    meshx_err_t err;
 
    if (timer_handle == NULL)
    {
        return MESHX_INVALID_STATE;
    }
 
    if (*timer_handle == NULL || (*timer_handle)->init != OS_TIMER_INIT_MAGIC)
        return MESHX_INVALID_STATE;
 
    MESHX_LOGI(MODULE_ID_COMPONENT_OS_TIMER, "Deleting timer %s", OS_TMER_GET_TIMER_NAME((*timer_handle)));
 
    err = meshx_rtos_timer_delete(&(*timer_handle)->timer_handle);
    if (err)
        return err;
 
    (*timer_handle)->init = 0;
 
    SLIST_REMOVE(&meshx_os_timer_reg_table_head, *timer_handle, meshx_os_timer, next);
    MESHX_FREE(*timer_handle);
 
    return MESHX_SUCCESS;
}

meshx_os_timer_init()

meshx_err_t meshx_os_timer_init

(

void

)

Initialize the OS timer module.

This function initializes the OS timer module.

Returns

MESHX_SUCCESS on success, or an error code on failure.

{
    meshx_err_t err;
#if CONFIG_ENABLE_UNIT_TEST
    err = register_unit_test(MODULE_ID_COMPONENT_OS_TIMER, &meshx_os_timer_unit_test_cb_handler);
    if (err)
    {
        MESHX_LOGE(MODULE_ID_COMPONENT_OS_TIMER, "unit_test reg failed: (%d)", err);
        return err;
    }
#endif /* CONFIG_ENABLE_UNIT_TEST */
    err = control_task_msg_subscribe(
        CONTROL_TASK_MSG_CODE_SYSTEM,
        OS_TIMER_CONTROL_TASK_EVT_MASK,
        (control_task_msg_handle_t)&meshx_os_timer_control_task_cb);
 
    return err;
}

meshx_os_timer_restart()

meshx_err_t meshx_os_timer_restart

(

const meshx_os_timer_t *

timer_handle

)

Restart a timer.

This function re-starts the given timer.

Parameters

timer_handle

The timer handle.

Returns

MESHX_SUCCESS on success, or an error code on failure.

{
    if (timer_handle == NULL)
    {
        return MESHX_INVALID_STATE;
    }
    if (timer_handle->init != OS_TIMER_INIT_MAGIC)
        return MESHX_INVALID_STATE;
 
    return control_task_msg_publish(
        CONTROL_TASK_MSG_CODE_SYSTEM,
        CONTROL_TASK_MSG_EVT_SYSTEM_TIMER_REARM,
        timer_handle,
        OS_TIMER_SIZE);
}

meshx_os_timer_set_period()

meshx_err_t meshx_os_timer_set_period	(	meshx_os_timer_t *	timer_handle,
		const uint32_t	period_ms )

Set period on an initialised timer.

This function reset period of initialised timer.

Parameters

timer_handle	The timer handle.
period_ms	New period in ms

Returns

MESHX_SUCCESS on success, or an error code on failure.

{
    if (timer_handle == NULL)
    {
        return MESHX_INVALID_STATE;
    }
    if (timer_handle->init != OS_TIMER_INIT_MAGIC)
        return MESHX_INVALID_STATE;
 
    timer_handle->period = period_ms;
 
    return control_task_msg_publish(
        CONTROL_TASK_MSG_CODE_SYSTEM,
        CONTROL_TASK_MSG_EVT_SYSTEM_TIMER_PERIOD,
        timer_handle,
        OS_TIMER_SIZE);
}

meshx_os_timer_start()

meshx_err_t meshx_os_timer_start

(

const meshx_os_timer_t *

timer_handle

)

Start a timer.

This function starts the given timer.

Parameters

timer_handle

The timer handle.

Returns

MESHX_SUCCESS on success, or an error code on failure.

{
    if (timer_handle == NULL)
    {
        return MESHX_INVALID_STATE;
    }
    if (timer_handle->init != OS_TIMER_INIT_MAGIC)
        return MESHX_INVALID_STATE;
 
    return control_task_msg_publish(
        CONTROL_TASK_MSG_CODE_SYSTEM,
        CONTROL_TASK_MSG_EVT_SYSTEM_TIMER_ARM,
        timer_handle,
        OS_TIMER_SIZE);
}

meshx_os_timer_stop()

meshx_err_t meshx_os_timer_stop

(

const meshx_os_timer_t *

timer_handle

)

Stop a timer.

This function stops the given timer.

Parameters

timer_handle

The timer handle.

Returns

MESHX_SUCCESS on success, or an error code on failure.

{
    if (timer_handle == NULL)
    {
        return MESHX_INVALID_STATE;
    }
    if (timer_handle->init != OS_TIMER_INIT_MAGIC)
        return MESHX_INVALID_STATE;
 
    return control_task_msg_publish(
        CONTROL_TASK_MSG_CODE_SYSTEM,
        CONTROL_TASK_MSG_EVT_SYSTEM_TIMER_DISARM,
        timer_handle,
        OS_TIMER_SIZE);
}