Detailed Description

Temperature driver.

Overview

The Temperature driver provides services related to measuring and reacting to the current temperature of the chip and changes to it.

The two main services provided are:

Getting the current temperature
Providing notification callbacks when the temperature changes

Usage

Initialisation

Unlike most drivers, there is only a single instance of the temperature driver that is always available once Temperature_init() is called. Temperature_init() should be called once before using other Temperature driver APIs. Subsequent Temperature_init() calls will have no effect.

Getting the Current Temperature

The most basic function of the driver is to provide the current temperature and return it. It is encoded as a signed integer in degrees C.

Notifications

The other major function of the Temperature driver is to notify the application when the temperature changes and crosses an application-defined threshold.

There are three default usecases for this:

High threshold. The application will receive a notification callback when currentTemperature >= thresholdHigh.
Low threshold. The application will receive a notification callback when currentTemperature <= thresholdLow.
Range threshold. The application will receive a notification callback when currentTemperature >= thresholdHigh || currentTemperature <= thresholdLow. This setup addresses usecases where a notification is required when the temperature changes by a certain amount regardless of whether it is up or down. Adjusting clock offsets based on temperature is a good example of this.

Registering Notifications

There are three functions that register a notification for the application:

Multiple notifications may be registered. The different parts of the application and drivers that need to respond to a temperature change do not need to know of one another. Each notification must have its own Temperature_NotifyObj and must be registered individually.

Notification Callbacks

Once the chip temperature crosses the smallest high threshold or largest low threshold amongst the registered notifications, the driver will iterate over the entire list of registered notification and check which ones have triggered. Notifications that have triggered are removed from the list of registered notifications and thus are no longer registered. Their callback function is then invoked.

If an application wishes to reregister a notification that just triggered and was unregistered, it may register it again from within the notification callback or another context.

It is possible to determine whether the high or low threshold triggered the notification callback as follows:

currentTemperature <= thresholdTemperature: Low threshold triggered
currentTemperature >= thresholdTemperature: High threshold triggered This information is only reasonably useful when registering a notification with both a high and low threshold using Temperature_registerNotifyRange(). Even then, the expected basic usecase only cares about the current temperature and adding an offset to it when registering the notification again.

Unregistering Notifications

Registered notifications are unregistered in two ways:

Automatically when a notification triggers
By calling Temperature_unregisterNotify()

Unregistered notifications may be registered again at any time.

Measured vs True Temperature

While the driver aims to supply and act on an accurate absolute temperature, there will be differences between the measured vs the true temperature due to inherent variances in the manufacturing process. The nature of these differences varies by device family.

Examples of such differences:

A constant per-chip offset between the measured and the true temperature
An temperature dependent per-chip offset between the measured and the true temperature
A variance in the measured temperature when measuring multiple times at the same chip temperature

It is strongly recommended to read the device-specific Temperature driver documentation for details of the temperature sensor characteristics and how they might affect choices of threshold values.

Synopsis

#include <ti/drivers/Temperature.h>
#define WINDOW_DELTA 10
Temperature_init();
currentTemperature = Temperature_getTemperature();
result = Temperature_registerNotifyRange(&notifyObject,
                                         currentTemperature + WINDOW_DELTA,
                                         currentTemperature - WINDOW_DELTA,
                                         myNotifyFxn,
                                         clientArg);

Examples

Register a High Threshold Notification

// The notification will trigger when the temperature reaches 40 C
#define THRESHOLD_CUTOFF 40
#include <ti/drivers/Temperature.h>
void thresholdNotifyFxn(int16_t currentTemperature,
                        int16_t thresholdTemperature,
                        uintptr_t clientArg,
                        Temperature_NotifyObj *notifyObject) {
   // Post a semaphore, set a flag, or otherwise act upon the temperature
   // change.
}
...
// Initialize the Temperature driver and register a notification.
Temperature_init();
int_fast16_t status = Temperature_registerNotifyHigh(notifyObject,
                                                     THRESHOLD_CUTOFF,
                                                     thresholdNotifyFxn,
                                                     NULL);
if (status != Temperature_STATUS_SUCCESS) {
    // Handle error
}

Register a Range Threshold Notification and Reregister in Callback

#define THRESHOLD_DELTA 5
#include <ti/drivers/Temperature.h>
void deltaNotificationFxn(int16_t currentTemperature,
                      int16_t thresholdTemperature,
                      uintptr_t clientArg,
                      Temperature_NotifyObj *notifyObject) {
    int_fast16_t status;
    status = Temperature_registerNotifyRange(notifyObject,
                                             currentTemperature + THRESHOLD_DELTA,
                                             currentTemperature - THRESHOLD_DELTA,
                                             deltaNotificationFxn,
                                             NULL);
    if (status != Temperature_STATUS_SUCCESS) {
        while(1);
    }
}
 ...
// Initialize the Temperature driver and register a notification.
Temperature_init();
int16_t currentTemperature = Temperature_getTemperature();
int_fast16_t status = Temperature_registerNotifyRange(notifyObject,
                                                      currentTemperature + THRESHOLD_DELTA,
                                                      currentTemperature - THRESHOLD_DELTA,
                                                      deltaNotificationFxn,
                                                      NULL);

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <ti/drivers/utils/List.h>

Include dependency graph for Temperature.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	Temperature_NotifyObj
	Temperature notify object structure. More...

Macros
#define	Temperature_STATUS_RESERVED (-32)

#define	Temperature_STATUS_SUCCESS (0)
	Successful status code. More...

#define	Temperature_STATUS_ERROR (-1)
	Generic error status code. More...

Typedefs
typedef void(*	Temperature_NotifyFxn) (int16_t currentTemperature, int16_t thresholdTemperature, uintptr_t clientArg, Temperature_NotifyObj *notifyObject)
	Function prototype for a notification callback. More...

Functions
void	Temperature_init (void)
	This function initializes the Temperature driver. More...

int16_t	Temperature_getTemperature (void)
	Gets the current temperature in degrees C. More...

int_fast16_t	Temperature_registerNotifyHigh (Temperature_NotifyObj *notifyObject, int16_t thresholdHigh, Temperature_NotifyFxn notifyFxn, uintptr_t clientArg)
	Registers a notification with a high threshold. More...

int_fast16_t	Temperature_registerNotifyLow (Temperature_NotifyObj *notifyObject, int16_t thresholdLow, Temperature_NotifyFxn notifyFxn, uintptr_t clientArg)
	Registers a notification with a low threshold. More...

int_fast16_t	Temperature_registerNotifyRange (Temperature_NotifyObj *notifyObject, int16_t thresholdHigh, int16_t thresholdLow, Temperature_NotifyFxn notifyFxn, uintptr_t clientArg)
	Registers a notification with both a high and low threshold. More...

int_fast16_t	Temperature_unregisterNotify (Temperature_NotifyObj *notifyObject)
	Unregisters a currently registered notification. More...

int16_t	Temperature_getThresholdHigh (Temperature_NotifyObj *notifyObject)
	Get the high threshold of a notification. More...

int16_t	Temperature_getThresholdLow (Temperature_NotifyObj *notifyObject)
	Get the low threshold of a notification. More...

void	Temperature_getThresholdRange (Temperature_NotifyObj notifyObject, int16_t thresholdHigh, int16_t *thresholdLow)
	Get the high and low threshold of a notification. More...

uintptr_t	Temperature_getClientArg (Temperature_NotifyObj *notifyObject)
	Get the application-provided clientArg of a notification. More...

Temperature_NotifyFxn	Temperature_getNotifyFxn (Temperature_NotifyObj *notifyObject)
	Get the notifyFxn provided during registration. More...

Macro Definition Documentation

§ Temperature_STATUS_RESERVED

#define Temperature_STATUS_RESERVED (-32)

Common Temperature status code reservation offset. Temperature driver implementations should offset status codes with Temperature_STATUS_RESERVED growing negatively.

Example implementation specific status codes:

#define TemperatureXYZ_STATUS_ERROR0    Temperature_STATUS_RESERVED - 0
#define TemperatureXYZ_STATUS_ERROR1    Temperature_STATUS_RESERVED - 1
#define TemperatureXYZ_STATUS_ERROR2    Temperature_STATUS_RESERVED - 2

§ Temperature_STATUS_SUCCESS

#define Temperature_STATUS_SUCCESS (0)

Successful status code.

Functions return Temperature_STATUS_SUCCESS if the function was executed successfully.

§ Temperature_STATUS_ERROR

#define Temperature_STATUS_ERROR (-1)

Generic error status code.

Functions return Temperature_STATUS_ERROR if the function was not executed successfully.

Typedef Documentation

§ Temperature_NotifyFxn

typedef void(* Temperature_NotifyFxn) (int16_t currentTemperature, int16_t thresholdTemperature, uintptr_t clientArg, Temperature_NotifyObj *notifyObject)

Function prototype for a notification callback.

Parameters

[in]	currentTemperature	Current chip temperature
[in]	thresholdTemperature	Temperature threshold that caused this notification callback.
[in]	clientArg	Argument provided by the application during registration.
	[in/out]	notifyObject The notification object that was registered previously. This pointer may be used to register the notification again with updated inputs from within the notification callback.

Function Documentation

§ Temperature_init()

void Temperature_init ( void )

This function initializes the Temperature driver.

This function initializes the internal state of the Temperature driver. It must be called before calling any other Temperature functions. Calling this function multiple times will only have an effect the first time.

§ Temperature_getTemperature()

int16_t Temperature_getTemperature ( void )

Gets the current temperature in degrees C.

Returns: Current temperature in degrees C

§ Temperature_registerNotifyHigh()

int_fast16_t Temperature_registerNotifyHigh	(	Temperature_NotifyObj *	notifyObject,
		int16_t	thresholdHigh,
		Temperature_NotifyFxn	notifyFxn,
		uintptr_t	clientArg
	)

Registers a notification with a high threshold.

This function registers a Temperature notification with a high threshold. Once the chip temperature rises above thresholdHigh, notifyFxn is called and the notification is automatically unregistered.

Parameters

	notifyObject	Structure to be initialized. After returning, it will contain the data necessary to issue a notification callback. The memory of the structure must persist while the notification is registered.
[in]	thresholdHigh	Threshold temperature in degrees C
[in]	notifyFxn	Callback function that is called once the chip temperature rises above `thresholdHigh`.
[in]	clientArg	Application-specified argument

Return values

Temperature_STATUS_SUCCESS	The notification was successfully registered.
Temperature_STATUS_ERROR	There was an error during registration.

Precondition: Temperature_init() called

§ Temperature_registerNotifyLow()

int_fast16_t Temperature_registerNotifyLow	(	Temperature_NotifyObj *	notifyObject,
		int16_t	thresholdLow,
		Temperature_NotifyFxn	notifyFxn,
		uintptr_t	clientArg
	)

Registers a notification with a low threshold.

This function registers a Temperature notification with a low threshold. Once the chip temperature falls below thresholdLow, notifyFxn is called and the notification is automatically unregistered.

Parameters

	notifyObject	Structure to be initialized. After returning, it will contain the data necessary to issue a notification callback. The memory of the structure must persist while the notification is registered.
[in]	thresholdLow	Threshold temperature in degrees C
[in]	notifyFxn	Callback function that is called once the chip temperature falls below `thresholdLow`.
[in]	clientArg	Application-specified argument

Return values

Temperature_STATUS_SUCCESS	The notification was successfully registered.
Temperature_STATUS_ERROR	There was an error during registration.

Precondition: Temperature_init() called

§ Temperature_registerNotifyRange()

int_fast16_t Temperature_registerNotifyRange	(	Temperature_NotifyObj *	notifyObject,
		int16_t	thresholdHigh,
		int16_t	thresholdLow,
		Temperature_NotifyFxn	notifyFxn,
		uintptr_t	clientArg
	)

Registers a notification with both a high and low threshold.

This function registers a Temperature notification with a high and low threshold. Once the chip temperature rises above thresholdHigh or falls below thresholdLow, notifyFxn is called and the notification is automatically unregistered.

Parameters

	notifyObject	Structure to be initialized. After returning, it will contain the data necessary to issue a notification callback. The memory of the structure must persist while the notification is registered.
[in]	thresholdHigh	High threshold temperature in degrees C
[in]	thresholdLow	Low threshold temperature in degrees C
[in]	notifyFxn	Callback function that is called once the chip temperature falls below `thresholdLow`, or rises above `thresholdHigh`.
[in]	clientArg	Application-specified argument

Return values

Temperature_STATUS_SUCCESS	The notification was successfully registered
Temperature_STATUS_ERROR	There was an error during registration

Precondition: Temperature_init() called

§ Temperature_unregisterNotify()

int_fast16_t Temperature_unregisterNotify ( Temperature_NotifyObj * notifyObject )

Unregisters a currently registered notification.

This function unregisters a currently registered notification. It should not be called on a notifyObject that is not currently registered.

Parameters

notifyObject Notification to unregister.

Return values

Temperature_STATUS_SUCCESS	The notification was successfully unregistered.
Temperature_STATUS_ERROR	There was an error during unregistration.

Precondition: Register notifyObject with Temperature_registerNotifyHigh(), Temperature_registerNotifyLow(), or Temperature_registerNotifyRange()

§ Temperature_getThresholdHigh()

int16_t Temperature_getThresholdHigh ( Temperature_NotifyObj * notifyObject )

Get the high threshold of a notification.

This function should not be called on a notifyObject registered with Temperature_registerNotifyLow(). The high threshold value returned in that case will be a device-specific invalid temperature.

Parameters

notifyObject Notification to get the high threshold of.

Returns: High threshold in degrees C.

Precondition: Register notifyObject with Temperature_registerNotifyHigh(), or Temperature_registerNotifyRange()

§ Temperature_getThresholdLow()

int16_t Temperature_getThresholdLow ( Temperature_NotifyObj * notifyObject )

Get the low threshold of a notification.

This function should not be called on a notifyObject registered with Temperature_registerNotifyHigh(). The low threshold value returned in that case will be a device-specific invalid temperature.

Parameters

notifyObject Notification to get the low threshold of.

Returns: Low threshold in degrees C.

Precondition: Register notifyObject with Temperature_registerNotifyLow(), or Temperature_registerNotifyRange()

§ Temperature_getThresholdRange()

void Temperature_getThresholdRange	(	Temperature_NotifyObj *	notifyObject,
		int16_t *	thresholdHigh,
		int16_t *	thresholdLow
	)

Get the high and low threshold of a notification.

This function should not be called on a notifyObject registered with Temperature_registerNotifyLow() or Temperature_registerNotifyHigh(). The unconfigured threshold value returned in that case will be a device-specific invalid temperature.

Parameters

	notifyObject	Notification to get the high and low threshold of.
[out]	thresholdHigh	High threshold value in degrees C written back by this function.
[out]	thresholdLow	Low threshold value in degrees C written back by this function.

Precondition: Register notifyObject with Temperature_registerNotifyRange()

§ Temperature_getClientArg()

uintptr_t Temperature_getClientArg ( Temperature_NotifyObj * notifyObject )

Get the application-provided clientArg of a notification.

Parameters

notifyObject Notification to get the clientArg of.

Returns: The clientArg provided during registration.

Precondition: Register notifyObject with Temperature_registerNotifyHigh(), Temperature_registerNotifyLow(), or Temperature_registerNotifyRange()

§ Temperature_getNotifyFxn()

Temperature_NotifyFxn Temperature_getNotifyFxn ( Temperature_NotifyObj * notifyObject )

Get the notifyFxn provided during registration.

Parameters

notifyObject Notification to get the notifyFxn of.

Returns: The notifyFxn provided during registration

Precondition: Register notifyObject with Temperature_registerNotifyHigh(), Temperature_registerNotifyLow(), or Temperature_registerNotifyRange()

Detailed Description

Overview

Usage

Initialisation

Getting the Current Temperature

Notifications

Registering Notifications

Notification Callbacks

Unregistering Notifications

Measured vs True Temperature

Synopsis

Examples

Register a High Threshold Notification

Register a Range Threshold Notification and Reregister in Callback

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

§ Temperature_STATUS_RESERVED

§ Temperature_STATUS_SUCCESS

§ Temperature_STATUS_ERROR

Typedef Documentation

§ Temperature_NotifyFxn

Function Documentation

§ Temperature_init()

§ Temperature_getTemperature()

§ Temperature_registerNotifyHigh()

§ Temperature_registerNotifyLow()

§ Temperature_registerNotifyRange()

§ Temperature_unregisterNotify()

§ Temperature_getThresholdHigh()

§ Temperature_getThresholdLow()

§ Temperature_getThresholdRange()

§ Temperature_getClientArg()

§ Temperature_getNotifyFxn()