Detailed Description

TEMPDRV Temperature Sensor Driver.

The source files for the TEMP driver library resides in the emdrv/tempdrv folder, and consists of tempdrv.c and tempdrv.h.

Introduction

TEMPDRV gives the user a nice interface to the EMU internal temperature sensor which is present on the EFR32 and some EFM32 devices. The TEMPDRV supports application specific callbacks at given temperature thresholds. The EMU internal temperature sensor is running in EM0-EM4H and is capable of waking up the core on temperature change. The EMU temperature sensor is running continuously and measurements are taken every 250 ms.

Note: The TEMPDRV is using the EMU peripheral and not the ADC peripheral. The ADC contains another internal temperature sensor which is not touched by the TEMPDRV.

The TEMPDRV also provides an important errata fix for the EFR32 first generation devices when operating at high temperature environments (above 50°C). The errata document for the EFR32 describes the errata which is called "EMU_E201 - High Temperature Operation". To implement the errata fix in a user application it is enough to include the TEMPDRV and call TEMPDRV_Init() at the start of the program. This will activate the errata fix code which is modifying registers based on changes in the EMU temperature.

Configuration Options

Some properties of the TEMPDRV driver are compile-time configurable. These properties are set in a file named tempdrv_config.h. A template for this file, containing default values, resides in the emdrv/tempdrv/config folder. To configure TEMPDRV for your application, provide your own configuration file. These are the available configuration parameters with default values defined.

  // Callback table depth (for high and low callbacks each)
  #define TEMPDRV_CALLBACK_DEPTH 5

  // Allow temperature sensor to wake the device up from EM4
  #define TEMPDRV_EM4WAKEUP false

  // Allow TEMPDRV to define the EMU_IRQ_Handler. Enable if EMU_IRQ_Handler is 
  // defined elsewhere.
  #define EMU_CUSTOM_IRQ_HANDLER false

Callback table depth determines the number of concurrent callbacks that can be registered at a single time. The depth applies to each limit, so depth of 5 allows up to 5 high and 5 low callbacks to be registered. There are no run-time configuration options for TEMPDRV.

The API

This section contain brief descriptions of the functions in the API. You will find detailed information on input and output parameters and return values by clicking on the function names. Most functions return an error code, ECODE_EMDRV_TEMPDRV_OK is returned on success, see ecode.h and tempdrv.h for other error codes.

Your application code must include one header file: tempdrv.h.

TEMPDRV_Init(), TEMPDRV_DeInit()
These functions initializes or deinitializes the TEMPDRV driver. This will erase any registered callbacks and disabled all interrupts. Typically TEMPDRV_Init() is called once in your startup code.

TEMPDRV_Enable()
Enable or disable the temperature driver without losing any registered callbacks.

TEMPDRV_GetTemp()
Get the current temperature in degrees Celsius. This measurement is based on a conversion from the EMU temperature sensor and calibration data that is stored in the DI page.

TEMPDRV_RegisterCallback(), TEMPDRV_UnregisterCallback()
Callbacks can be registered for rising or falling thresholds and will called as soon as the temperature matches the specified threshold. Multiple callbacks at the same temperature are not permitted, nor are mismatches between temperature and limit (e. g temperature is lower than current but the limit is set to high). Additionally, unregistering a callback will remove all entries of matching callbacks.

Example

#include "tempdrv.h"

boolean flag = false;

void callback(int8_t temp, TEMPDRV_LimitType_t limit)
{
  flag = true;
}

int main(void)
{
  TEMPDRV_Init();

  // Register a callback at 10 degrees above current temperature
  TEMPDRV_RegisterCallback(TEMPDRV_GetTemp()+10, TEMPDRV_LIMIT_HIGH, callback);

  while (flag==false) {};
}

Macros
#define	ECODE_EMDRV_TEMPDRV_BAD_LIMIT (ECODE_EMDRV_TEMPDRV_BASE \| 0x00000003)
	Temperature mismatch with limit.

#define	ECODE_EMDRV_TEMPDRV_DUP_TEMP (ECODE_EMDRV_TEMPDRV_BASE \| 0x00000008)
	Requested temperature is a duplicate.

#define	ECODE_EMDRV_TEMPDRV_NO_CALLBACK (ECODE_EMDRV_TEMPDRV_BASE \| 0x00000004)
	Can't find callback.

#define	ECODE_EMDRV_TEMPDRV_NO_INIT (ECODE_EMDRV_TEMPDRV_BASE \| 0x00000001)
	Function requires prior initialization.

#define	ECODE_EMDRV_TEMPDRV_NO_SPACE (ECODE_EMDRV_TEMPDRV_BASE \| 0x00000005)
	No more space to register.

#define	ECODE_EMDRV_TEMPDRV_OK (ECODE_OK)
	Success return value.

#define	ECODE_EMDRV_TEMPDRV_PARAM_ERROR (ECODE_EMDRV_TEMPDRV_BASE \| 0x00000002)
	Illegal input parameter.

#define	ECODE_EMDRV_TEMPDRV_TEMP_OVER (ECODE_EMDRV_TEMPDRV_BASE \| 0x00000007)
	Requested temperature above measurable range.

#define	ECODE_EMDRV_TEMPDRV_TEMP_UNDER (ECODE_EMDRV_TEMPDRV_BASE \| 0x00000006)
	Requested temperature below measurable range.

Typedefs
typedef void(*	TEMPDRV_Callback_t) (int8_t temp, TEMPDRV_LimitType_t limit)
	TEMPDRV temperature limit callback function. More...

typedef enum TEMPDRV_LimitType	TEMPDRV_LimitType_t

Enumerations
enum	TEMPDRV_LimitType { TEMPDRV_LIMIT_LOW = 0, TEMPDRV_LIMIT_HIGH = 1 }

Functions
Ecode_t	TEMPDRV_DeInit (void)
	De-initialize the TEMP driver. More...

Ecode_t	TEMPDRV_Enable (bool enable)
	Enable or disable the TEMP driver. More...

uint8_t	TEMPDRV_GetActiveCallbacks (TEMPDRV_LimitType_t limit)
	Get the number of active callbacks for a limit. More...

int8_t	TEMPDRV_GetTemp (void)
	Get the current temperature. More...

Ecode_t	TEMPDRV_Init (void)
	Initialize the TEMP driver. More...

void	TEMPDRV_IRQHandler (void)
	TEMPDRV IRQ Handler. More...

Ecode_t	TEMPDRV_RegisterCallback (int8_t temp, TEMPDRV_LimitType_t limit, TEMPDRV_Callback_t callback)
	Register a callback in the TEMP driver. More...

Ecode_t	TEMPDRV_UnregisterCallback (TEMPDRV_Callback_t callback)
	Unregister a callback in the TEMP driver. More...

Typedef Documentation

typedef void(* TEMPDRV_Callback_t) (int8_t temp, TEMPDRV_LimitType_t limit)

TEMPDRV temperature limit callback function.

This callback function is called from interrupt context. The callback function is called when the current temperature is equal to or exceeds one of the temperature limits that have been registered with the driver.

Parameters

[in]	temp	The current temperature at the time when the EMU temperature triggers an interrupt. Note that this is not necessarily the same temperature as was specified when registering a callback.
[in]	limit	The upper/lower limit reached

Definition at line 91 of file tempdrv.h.

typedef enum TEMPDRV_LimitType TEMPDRV_LimitType_t

Temperature limit. This is used in the TEMPDRV to specify the direction of temperature change.

Enumeration Type Documentation

enum TEMPDRV_LimitType

Temperature limit. This is used in the TEMPDRV to specify the direction of temperature change.

Enumerator
TEMPDRV_LIMIT_LOW	Temperature low. Used to specify that a temperature is decreasing.
TEMPDRV_LIMIT_HIGH	Temperature high. Used to specify that a temperature is increasing.

Definition at line 69 of file tempdrv.h.

Function Documentation

Ecode_t TEMPDRV_DeInit ( void )

De-initialize the TEMP driver.

This will clear all the registered callbacks and disable the EMU IRQ in the NVIC.

Returns: ECODE_EMDRV_TEMPDRV_OK on success.

Definition at line 597 of file tempdrv.c.

References disableInterrupts(), and ECODE_EMDRV_TEMPDRV_OK.

Ecode_t TEMPDRV_Enable ( bool enable )

Enable or disable the TEMP driver.

Parameters

[in] enable true to enable the TEMP driver, false to disable the TEMP driver.

Returns: ECODE_EMDRV_TEMPDRV_OK on success.

Definition at line 618 of file tempdrv.c.

References disableInterrupts(), ECODE_EMDRV_TEMPDRV_OK, and updateInterrupts().

uint8_t TEMPDRV_GetActiveCallbacks ( TEMPDRV_LimitType_t limit )

Get the number of active callbacks for a limit.

Parameters

[in] limit Limit type, refer to TEMPDRV_LimitType_t.

Returns: Number of active callbacks

Definition at line 645 of file tempdrv.c.

References TEMPDRV_LIMIT_HIGH, and TEMPDRV_LIMIT_LOW.

int8_t TEMPDRV_GetTemp ( void )

Get the current temperature.

Returns: Current temperature in degrees Celsius.

Definition at line 683 of file tempdrv.c.

References convertToTemp(), and EMU.

Referenced by TEMPDRV_IRQHandler(), and TEMPDRV_RegisterCallback().

Ecode_t TEMPDRV_Init ( void )

Initialize the TEMP driver.

This will clear all the registered callbacks and enable the EMU IRQ in the NVIC. Calling this function will also enable the EMU_E201 errata fix for first generation Pearl, Jade and EFR32 devices.

Returns: ECODE_EMDRV_TEMPDRV_OK on success.

Definition at line 547 of file tempdrv.c.

References _DEVINFO_CAL_TEMP_MASK, _DEVINFO_CAL_TEMP_SHIFT, DEVINFO, disableInterrupts(), ECODE_EMDRV_TEMPDRV_OK, and updateInterrupts().

void TEMPDRV_IRQHandler ( void )

TEMPDRV IRQ Handler.

This IRQ Handler should be called from within the EMU_IRQ_Handler in order to enable TEMPDRV callbacks. This is included by default with EMU_CUSTOM_IRQ_HANDLER defined as false.

TEMPDRV IRQ Handler.

This function must be called by the EMU interrupt handler in order to support the TEMPDRV callback mechanism.

This function handles the EMU_IF_TEMPHIGH, EMU_IF_TEMPLOW interrupt flags from the EMU internal temperature sensor.

Definition at line 108 of file tempdrv.c.

References TEMPDRV_CallbackSet_t::callback, TEMPDRV_GetTemp(), TEMPDRV_LIMIT_HIGH, TEMPDRV_LIMIT_LOW, and updateInterrupts().

Referenced by EMU_IRQHandler().

Ecode_t TEMPDRV_RegisterCallback	(	int8_t	temp,
		TEMPDRV_LimitType_t	limit,
		TEMPDRV_Callback_t	callback
	)

Register a callback in the TEMP driver.

This function is used for registering an application callback when the temperature changes. Note that when calling this function an application must specify the direction of the temperature change, use TEMPDRV_LIMIT_LOW to receive a callback when the temperature drops below the specified temp and use TEMPDRV_LIMIT_HIGH to receive a callback when the temperature increases above the specified temp.

Note: The user registered callback will be cleared once it's called. This means that the callback functions are not persistent, and have to be managed by the application. This feature can be used to implement a user controlled hysteresis. So for instance to register a callback at 50°C with a 5°C hysteresis you can first register a callback at 50°C or above using this function, and when the callback fires you can use this function again to register a callback when the temperature decreases to 45°C or below. Each time a callback fires you only need to call the TEMPDRV_RegisterCallback() function, there is no need to call TEMPDRV_UnregisterCallback().

It's important to know the current temperature before calling this function. Attempting to register a callback that would fire immediately is not supported and will result in a return value of ECODE_EMDRV_TEMPDRV_BAD_LIMIT. Examples of an illegal scenario would be to register a callback for a temperature that is higher than the current temperature and with a limit set to TEMPDRV_LIMIT_LOW.

Parameters

[in]	temp	Temperature to trigger on given in number of °C.
[in]	limit	Limit type, refer to TEMPDRV_LimitType_t. Using TEMPDRV_LIMIT_LOW will register a callback when the EMU temperature reaches temp °C or lower, and using TEMPDRV_LIMIT_HIGH will register a callback when the EMU temperature reaches temp °C or higher.
[in]	callback	User defined function to call when temperature threshold is reached or passed.

Returns

ECODE_EMDRV_TEMPDRV_OK on success.

ECODE_EMDRV_TEMPDRV_PARAM_ERROR if the callback is NULL.

ECODE_EMDRV_TEMPDRV_NO_INIT if the user has forgot to call TEMPDRV_Init() before attempting to register a callback.

ECODE_EMDRV_TEMPDRV_BAD_LIMIT is returned if temp is below the current temperature and is TEMPDRV_LIMIT_LOW. It is also returned if temp is above the current temperature and is TEMPDRV_LIMIT_HIGH.

ECODE_EMDRV_TEMPDRV_DUP_TEMP is returned if a duplicate callback is detected. A duplicate callback is if you attempt to register a new callback with the same temp and the same limit as some already registered callback.

Definition at line 750 of file tempdrv.c.

References addCallback(), checkForDuplicates(), ECODE_EMDRV_TEMPDRV_BAD_LIMIT, ECODE_EMDRV_TEMPDRV_DUP_TEMP, ECODE_EMDRV_TEMPDRV_NO_INIT, ECODE_EMDRV_TEMPDRV_PARAM_ERROR, TEMPDRV_GetTemp(), TEMPDRV_LIMIT_HIGH, and TEMPDRV_LIMIT_LOW.