Many of the modules in an IPv6 stack need to take regular periodic actions and the period does not have to have to be accurately distanced. Using a dedicated timer for each of such modules has proven to be very resource hungry. The IoT Timer module aims to provide the needed timekeeping functionality. The unit of timekeeping is milliseconds and the IoT Timer's resolution is configurable by IOT_TIMER_RESOLUTION_IN_MS. To conserve power, this value should be set as high as allowed by the requirements. 100 ms can be used in most practical use cases.

The IoT Timer module can provide periodic callbacks for other modules based on their configured needs. The callback intervals can be configured as integral multiples of the resolution set by IOT_TIMER_RESOLUTION_IN_MS. It is also possible to receive a wall clock reference from the IoT Timer. This functionality can be used if regular periodic callbacks are not needed by a module, but it needs a reference wall clock to determine the time difference between certain events.

To be platform independent, the module has no internal tick source. Therefore, the application designer must cater the IoT Timer with calling the iot_timer_update procedure at regular intervals. For proper functioning, the interval between updates must be the same as IOT_TIMER_RESOLUTION_IN_MS.

Modules can query the IoT Timer for the current value of the wall clock with iot_timer_wall_clock_get.

Modules can act as clients of the IoT Timer by using iot_timer_client_list_set. After each update of the wall clock the module will cycle through the list of clients. If the updated value of the wall clock is an integral multiple of the callback interval of any clients, the callback procedure of the client is executed. To minimize drift between client callbacks, the callback function of each client should be designed in a way that the duration of execution does not vary and is as short as possible.

The list of clients can be set to NULL with iot_timer_client_list_set to cancel all subscriptions.

Code examples

Initializing an application timer as a tick source for the IoT Timer

#define IOT_TIMER_RESOLUTION_IN_MS 100
static app_timer_id_t m_iot_timer_tick_src_id;
static void iot_timer_tick_callback(void * p_context)
{
    UNUSED_VARIABLE(p_context);
    uint32_t err_code = iot_timer_update();
    APP_ERROR_CHECK(err_code);
}
static void timers_init(void)
{
    APP_TIMER_INIT(APP_TIMER_PRESCALER, APP_TIMER_MAX_TIMERS, APP_TIMER_OP_QUEUE_SIZE, NULL);
    uint32_t err_code = app_timer_create(&m_iot_timer_tick_src_id,
                                         APP_TIMER_MODE_REPEATED,
                                         iot_timer_tick_callback);
    APP_ERROR_CHECK(err_code);
}
int main(void)
{
    /*  ...   */
    timers_init();
    
    uint32_t err_code = app_timer_start(m_iot_timer_tick_src_id, \
                                        APP_TIMER_TICKS(IOT_TIMER_RESOLUTION_IN_MS, APP_TIMER_PRESCALER), \
                                        NULL);
    APP_ERROR_CHECK(err_code);
    /*  ...   */
}

Configuring clients for the IoT Timer

#define IOT_TIMER_RESOLUTION_IN_MS        200
#define IOT_TIMER_CLIENT_ONE_CB_INTERVAL  200
#define IOT_TIMER_CLIENT_TWO_CB_INTERVAL  400
static void iot_timer_client_one_callback(iot_timer_time_in_ms_t elapsed_time)
{
    /*  ...   */
}
static void iot_timer_client_two_callback(iot_timer_time_in_ms_t elapsed_time)
{
    /*  ...   */
}
int main(void)
{
    /*  ...   */
    const iot_timer_client_t list_of_clients[] = 
    {
        {iot_timer_client_one_callback, IOT_TIMER_CLIENT_ONE_CB_INTERVAL},
        {iot_timer_client_two_callback, IOT_TIMER_CLIENT_TWO_CB_INTERVAL},
    };
    const iot_timer_clients_list_t iot_timer_clients = 
    {
        (sizeof(list_of_clients) / sizeof(iot_timer_client_t)),
        &(list_of_clients[0]),
    };
    uint32_t err_code = iot_timer_client_list_set(&iot_timer_clients);
    APP_ERROR_CHECK(err_code);
    /*  ...   */
}

Querying the IoT Timer for the wall clock value

void procedure(void)
{
    /*  ...   */
    iot_timer_time_in_ms_t current_time;
    uint32_t err_code = iot_timer_wall_clock_get(&current_time);
    APP_ERROR_CHECK(err_code);
    /*  ...   */
}

Configuration parameters

The following configuration parameters should be defined in sdk_config.h.

IOT_TIMER_RESOLUTION_IN_MS

The resolution of timekeeping in milliseconds.

Restriction	Value
Minimum value	1
Dependencies	None, but the application designer must ensure that the iot_timer_update procedure is called repeatedly with the same frequency.

IOT_TIMER_DISABLE_API_PARAM_CHECK

Disables API parameter checks in the module. Set this define to 1 to disable checks on API parameters in the module.

API parameter checks are added to ensure that the correct parameters are passed to the module. These checks are useful during development phase, but they might be redundant when the application is finalized. Disabling these checks might improve performance.

Description	Value
Enable API parameters check	0
Disable API parameters check	1
Dependencies	None

Implementation specific limitations

The accuracy of the wall clock is limited by the value of IOT_TIMER_RESOLUTION_IN_MS and the accuracy of the external tick source.
The accuracy of the wall clock, in turn, determines the accuracy of client callbacks.
Client callbacks that take a long time to execute or have a great relative variation in execution time may introduce a drift for any subsequent callbacks.
In the current implementation the wall clock will overflow after 2^32 updates. If a client is configured with a callback interval that is comparable with the maximum time before a wall clock overflow (depending on IOT_TIMER_RESOLUTION_IN_MS), the interval between callbacks will be affected by the overflow. Therefore, the callback interval for any client should be far less than the maximum time before a wall clock overflow (depending on IOT_TIMER_RESOLUTION_IN_MS).

Table of Contents