Timers

The Timers API provides a simple interface for creating and managing timed events in Ocre containers. It supports creating one-shot and periodic timers with customizable intervals. The API leverages the Zephyr kernel's timer functionality to provide accurate timing with millisecond precision.

---

Header File

To use the Timer API in your application, include the ocre_api.h header from the Atym Toolchain, and link the ocre-sdk library when building your application.

#include "ocre_api.h"

Container Permissions

When using the timer API in your application, make sure to include the ocre_timer permission in your build.yaml configuration file. This enables build-time validation to ensure your application only uses the timer functions you've declared.

config:
  permissions:
    - ocre_timer

---

Execution Environment

Container applications shall use ocre_process_events() function to process their timer events. This is usually done in a loop, similar to following:

    // Main event loop - process events continuously
    while (1) {
        ocre_process_events();
    }

Types

Timer Callback Function

A function that will be called when a timer expires.

typedef void (*timer_callback_func_t)(void);

---

Methods

Create Timer

Creates a new timer with the specified ID.

int ocre_timer_create(int id);

Parameters:

Name	Type	Description
id	int	Timer identifier (must be between 1 and OCRE_MAX_TIMERS)

Returns:

Value	Description
0	on success
negative value	on error

Delete Timer

Stops and deletes the specified timer.

int ocre_timer_delete(int id);

Parameters:

Name	Type	Description
id	int	Timer identifier

Returns:

Value	Description
0	on success
negative value	on error

Start Timer

Starts the specified timer with the given interval.

int ocre_timer_start(int id, int interval, int is_periodic);

Parameters:

Name	Type	Description
id	int	Timer identifier
interval	int	Timer interval in milliseconds
is_periodic	int	1 for periodic timer, 0 for one-shot

Returns:

Value	Description
0	on success
negative value	on error

Stop Timer

Stops a running timer.

int ocre_timer_stop(int id);

Parameters:

Name	Type	Description
id	int	Timer identifier

Returns:

Value	Description
0	on success
negative value	on error

Get Remaining Time

Gets the remaining time for a timer.

int ocre_timer_get_remaining(int id);

Parameters:

Name	Type	Description
id	int	Timer identifier

Returns:

Value	Description
positive value	Remaining time in milliseconds
negative value	Error occurred

Register Timer Callback

Registers a callback function to be called when a timer expires.

int ocre_register_timer_callback(int timer_id, timer_callback_func_t callback);

Parameters:

Name	Type	Description
timer_id	int	Timer identifier
callback	timer_callback_func_t	Callback function to register

Returns:

Value	Description
0	on success
negative value	on error

Unregister Timer Callback

Unregisters a previously registered timer callback.

int ocre_unregister_timer_callback(int timer_id);

Parameters:

Name	Type	Description
timer_id	int	Timer identifier

Returns:

Value	Description
0	on success
negative value	on error

---

Reference

Function	Description	Parameters	Return Value	Error Conditions
ocre_timer_create	Creates a new timer	id: Timer identifier	0: Success Negative: Error	Invalid ID Timer already exists
ocre_timer_delete	Deletes a timer	id: Timer identifier	0: Success Negative: Error	Timer not found
ocre_timer_start	Starts a timer	id: Timer identifier interval: Time in ms is_periodic: 1=periodic, 0=one-shot	0: Success Negative: Error	Invalid ID Invalid interval
ocre_timer_stop	Stops a running timer	id: Timer identifier	0: Success Negative: Error	Timer not found
ocre_timer_get_remaining	Gets remaining time	id: Timer identifier	Positive: Time in ms Negative: Error	Invalid timer ID
ocre_register_timer_callback	Registers timer callback	timer_id: Timer identifier callback: Callback function	0: Success Negative: Error	Invalid timer ID Callback registration failed
ocre_unregister_timer_callback	Unregisters timer callback	timer_id: Timer identifier	0: Success Negative: Error	Invalid timer ID No callback registered

---