diff --git a/utils/include/stm32_time.h b/utils/include/stm32_time.h
index d8bda36f23ae71206ddcd97797ebff6371fcea49..2eed9f5908db54df8e8366294fe629d51a884477 100644
--- a/utils/include/stm32_time.h
+++ b/utils/include/stm32_time.h
@@ -1,20 +1,169 @@
+/** @file */
+
#ifndef _STM32_TIME_H
#define _STM32_TIME_H
+/**
+ * \brief Structure to handle blocking time delays and timeouts using a timer
+ *
+ * This structure is a wrapper around any timer in order to handle time delays
+ * and timeouts in a unified way. This structure requires a function to get the
+ * accumulated number of counts of a timer and the number of timer counts per
+ * micro-second of the timer.
+ *
+ * A single structure can only be used to handle a single timeout or delay,
+ * but several structures can share a single timer without any performance
+ * decrease.
+ *
+ * A time structure is first initialized by calling the time_init() function.
+ * Using this structure, it is possible to implement delays in
+ * seconds (time_delay_s()), milli-seconds (time_delay_ms()) and micro-seconds
+ * (time_delay_us()), and also start (time_set_timeout()) and cancel
+ * (time_cancel_timeout()) timeout, as well as checks its status (time_is_timeout()).
+ *
+ */
typedef struct
{
+ /**
+ * \brief Target number of timer counts for the delay or timeout
+ *
+ * Absolute number of timer counts that must be reached to unblock any of the
+ * delay functions or activate the timeout feature. This value is internally
+ * computed taking into account the current number of counts and the desired
+ * time when any of the following functions are called:
+ * * time_set_timeout()
+ * * time_delay_s()
+ * * time_delay_ms()
+ * * time_delay_us()
+ *
+ */
unsigned long long int target_time;
+ /**
+ * \brief Number of timer counts per each micro-second
+ *
+ * This parameter holds the number of timer counts per each micro-second. This
+ * parameter depends on the configuration of the associated timer and its value
+ * must be provided when calling the time_init() function. This value should not
+ * be modified afterwards.
+ *
+ */
int counts_per_us;
+ /**
+ * \brief Function pointer to get the accumulated number of counts of the timer
+ *
+ * The associated timer must provide a function which does not accept any parameters
+ * and returns the accumulated number of timer counts since the last reset as an
+ * unsigned long long variable (8 bytes in most architectures).
+ *
+ * This pointer must be provided at initilaization time when the time_init() function
+ * is called, and should not be modified afterwards.
+ *
+ */
unsigned long long int (*get_time)(void);
}TTime;
/* public functions */
+/**
+ * \brief Function to initialize a time structure
+ *
+ * This function initializes a time structure. This function must be called before
+ * calling any other function.
+ *
+ * \param time pointer to a valid TTime structure to be initialized. If
+ * memory is not pre-allocated before calling this function, its
+ * behavior is unpredictable.
+ * \param counts_per_us number of timer counts per micro-second. This value
+ * must coincide with the actual value of the associated timer.
+ * \param get_time pointer to a function to get the accumulated number of
+ * timer counts since the last reset. This function must be implemented
+ * by the associated timer module.
+ */
void time_init(TTime *time,int counts_per_us,unsigned long long int(*get_time)(void));
+/**
+ * \brief Function to set the desired timeout in micro-seconds
+ *
+ * This functions sets the desired time to generate a timeout event if it is not
+ * canceller by the time_cancel_timeout() function. After calling this function,
+ * the time_is_timeout() function will return true if the current time is past
+ * the time when this function was called plus the desired timeout value.
+ *
+ * If this function is called when there is an active timeout, the timeout
+ * condition is updated by the provided timeout value. This function activates
+ * the timeout, but it does not block. The time_is_timeout() function should be
+ * be used to check the state of the timeout, and the time_cancel_timeout()
+ * function to cancel it.
+ *
+ * \param time pointer to a valid TTime structure to be initialized. If
+ * memory is not pre-allocated before calling this function, its
+ * behavior is unpredictable.
+ * \param timeout_us value of the desired timeout in micro-seconds.
+ */
void time_set_timeout(TTime *time,long int timeout_us);
+/**
+ * \brief Function to check if the desired time has elapsed
+ *
+ * This function checks whether the current time is past the time when the
+ * time_set_timeout() function was called plus the desired timeout or not.
+ * If this function will always return false if it is called when no timeout
+ * has been activated by calling the time_set_timeout()
+ *
+ * \param time pointer to a valid TTime structure to be initialized. If
+ * memory is not pre-allocated before calling this function, its
+ * behavior is unpredictable.
+ *
+ * \return true if the timeout condition is active of false if the timeout
+ * is not yet active or there is no timeout active.
+ */
unsigned char time_is_timeout(TTime *time);
+/**
+ * \brief Function to cancel the current timeout
+ *
+ * This function cancels any timeout condition currently active. If no timeout
+ * is active when this function is called, nothing happens.
+ *
+ * \param time pointer to a valid TTime structure to be initialized. If
+ * memory is not pre-allocated before calling this function, its
+ * behavior is unpredictable.
+ */
void time_cancel_timeout(TTime *time);
+/**
+ * \brief Function to wait a given time in micro-seconds
+ *
+ * This function blocks until the specifierd time in micro-seconds has elapsed.
+ * If this function is called when there is an active timeout, the timeout is
+ * automatically cancelled.
+ *
+ * \param time pointer to a valid TTime structure to be initialized. If
+ * memory is not pre-allocated before calling this function, its
+ * behavior is unpredictable.
+ * \param delay_us value of the desired delay in micro-seconds
+ */
void time_delay_us(TTime *time,int delay_us);
+/**
+ * \brief Function to wait a given time in milli-seconds
+ *
+ * This function blocks until the specifierd time in milli-seconds has elapsed.
+ * If this function is called when there is an active timeout, the timeout is
+ * automatically cancelled.
+ *
+ * \param time pointer to a valid TTime structure to be initialized. If
+ * memory is not pre-allocated before calling this function, its
+ * behavior is unpredictable.
+ * \param delay_ms value of the desired delay in milli-seconds
+ */
void time_delay_ms(TTime *time,int delay_ms);
+/**
+ * \brief Function to wait a given time in seconds
+ *
+ * This function blocks until the specifierd time in seconds has elapsed.
+ * If this function is called when there is an active timeout, the timeout is
+ * automatically cancelled.
+ *
+ * \param time pointer to a valid TTime structure to be initialized. If
+ * memory is not pre-allocated before calling this function, its
+ * behavior is unpredictable.
+ * \param delay_s value of the desired delay in seconds
+ */
void time_delay_s(TTime *time,int delay_s);
#endif