This driver for Atmel® | SMART ARM®-based microcontrollers provides an interface for the configuration and management of the device's Configurable Custom Logic functionality.

Support and FAQ: visit Microchip Support

The following peripheral is used by this module:

TSENS (Temperature Sensor)

The following devices can use this module:

Atmel | SMART SAM C21

The outline of this documentation is as follows:

Prerequisites

There are no prerequisites for this module.

Module Overview

The Temperature Sensor (TSENS) can be used to accurately measure the operating temperature of the device. TSENS accurately measures the operating temperature of the device by comparing the difference in two temperature dependent frequencies to a known frequency. The frequency of the temperature dependent oscillator (TOSC) is measured twice: first with the min configuration and next with the maximum configuration. The resulting signed value is proportional to the temperature and is corrected for offset by the contents of the OFFSET register.

Accurately measures a temperature:

±1°C over 0°C ~ 60°C
±3°C over -40°C ~ 85°C
±5°C over -40°C ~ 105°C

The number of periods of GCLK_TSENS used for the measurement is defined by the GAIN register. The width of the resulting pulse is measured using a counter clocked by GCLK_TSENS in the up direction for the 1^st phase and in the down 2^nd phase. Register GAIN and OFFSET is loaded from NVM, or can also be fixed by user.

\[ VALUE = OFFSET + (\frac{f_{TOSCMIN} - f_{TOSCMAX}}{f_{GCLK}}) \times GAIN \]

Note

If fix this bitfield, the relationship between GCLK frequency, GAIN and resolution as below:

Resolution (#/°C)	GAIN@48MHz	GAIN@40MHz
×1 (1°C)	960	800
×10 (0.1°C)	9600	8000
×100 (0.01°C)	96000	80000

Window Monitor

The TSENS module window monitor function can be used to automatically compare the conversion result against a predefined pair of upper and lower threshold values.

Events

Event generation and event actions are configurable in the TSENS.

The TSENS has one actions that can be triggered upon event reception:

Start conversion

The TSENS can generate the following output event:

Window monitor

If the event actions are enabled in the configuration, any incoming event will trigger the action.

If the window monitor event is enabled, an event will be generated when the configured window condition is detected.

Special Considerations

There are no special considerations for this module.

Extra Information

For extra information, see Extra Information for TSENS Driver. This includes:

Examples

For a list of examples related to this driver, see Examples for TSENS Driver.

API Overview

Data Structures
struct	tsens_calibration
	Calibration configuration structure. More...

struct	tsens_config
	TSENS configuration structure. More...

struct	tsens_events
	TSENS event enable/disable structure. More...

struct	tsens_module
	TSENS software device instance structure. More...

struct	tsens_window_config
	Window monitor configuration structure. More...

Macros
#define	ERRATA_14476 true
	The magnitude of the temperature measurement value decreases with increasing temperature, i.e. More...

Typedefs
typedef void(*	tsens_callback_t )(enum tsens_callback)
	Type of the callback functions. More...

Enumerations
enum	tsens_callback { TSENS_CALLBACK_RESULT_READY, TSENS_CALLBACK_OVERRUN, TSENS_CALLBACK_WINDOW, TSENS_CALLBACK_OVF }
	TSENS Callback Types. More...

enum	tsens_event_action { TSENS_EVENT_ACTION_DISABLED = 0, TSENS_EVENT_ACTION_START_CONV = TSENS_EVCTRL_STARTEI }
	TSENS event action enum. More...

enum	tsens_window_mode { TSENS_WINDOW_MODE_DISABLE = TSENS_CTRLC_WINMODE_DISABLE, TSENS_WINDOW_MODE_ABOVE = TSENS_CTRLC_WINMODE_ABOVE, TSENS_WINDOW_MODE_BELOW = TSENS_CTRLC_WINMODE_BELOW, TSENS_WINDOW_MODE_INSIDE = TSENS_CTRLC_WINMODE_INSIDE, TSENS_WINDOW_MODE_OUTSIDE = TSENS_CTRLC_WINMODE_OUTSIDE, TSENS_WINDOW_MODE_HYST_ABOVE = TSENS_CTRLC_WINMODE_HYST_ABOVE, TSENS_WINDOW_MODE_HYST_BELOW = TSENS_CTRLC_WINMODE_HYST_BELOW }
	TSENS window monitor mode enum. More...

Module Status Flags
TSENS status flags, returned by tsens_get_status() and cleared by tsens_clear_status().
#define	TSENS_STATUS_RESULT_READY (1UL << 0)
	TSENS result ready. More...

#define	TSENS_STATUS_OVERRUN (1UL << 1)
	TSENS result overwritten before read. More...

#define	TSENS_STATUS_WINDOW (1UL << 2)
	Window monitor match. More...

#define	TSENS_STATUS_OVERFLOW (1UL << 3)
	TSENS result overflows. More...

Driver Initialization and Configuration
enum status_code	tsens_init (struct tsens_config *config)
	Initializes the TSENS. More...

void	tsens_get_config_defaults (struct tsens_config *const config)
	Initializes an TSENS configuration structure to defaults. More...

Status Management
static uint32_t	tsens_get_status (void)
	Retrieves the current module status. More...

static void	tsens_clear_status (const uint32_t status_flags)
	Clears a module status flag. More...

Enable, Disable, and Reset TSENS Module, Start Conversion and Read Result
static bool	tsens_is_syncing (void)
	Determines if the hardware module is currently synchronizing to the bus. More...

static void	tsens_enable (void)
	Enables the TSENS module. More...

static void	tsens_disable (void)
	Disables the TSENS module. More...

static void	tsens_reset (void)
	Resets the TSENS module. More...

static void	tsens_enable_events (struct tsens_events *const events)
	Enables an TSENS event output. More...

static void	tsens_disable_events (struct tsens_events *const events)
	Disables an TSENS event output. More...

static void	tsens_start_conversion (void)
	Start a TSENS conversion. More...

enum status_code	tsens_read (int32_t *result)
	Reads the TSENS result. More...

Callback Management
enum status_code	tsens_register_callback (struct tsens_module *const module, tsens_callback_t callback_func, enum tsens_callback callback_type)
	Registers a callback. More...

enum status_code	tsens_unregister_callback (struct tsens_module *const module, enum tsens_callback callback_type)
	Unregisters a callback. More...

static void	tsens_enable_callback (enum tsens_callback callback_type)
	Enables callback. More...

static void	tsens_disable_callback (enum tsens_callback callback_type)
	Disables callback. More...

void	tsens_read_job (struct tsens_module const module_inst, int32_t result)
	Read result from TSENS. More...

#define ERRATA_14476 true

The magnitude of the temperature measurement value decreases with increasing temperature, i.e.

it has a negative temperature coefficient. Errata reference: 14476.

#define TSENS_STATUS_OVERFLOW (1UL << 3)

TSENS result overflows.

Referenced by tsens_clear_status(), and tsens_get_status().

#define TSENS_STATUS_OVERRUN (1UL << 1)

TSENS result overwritten before read.

Referenced by tsens_clear_status(), tsens_get_status(), and tsens_read().

#define TSENS_STATUS_RESULT_READY (1UL << 0)

TSENS result ready.

Referenced by tsens_clear_status(), tsens_get_status(), and tsens_read().

#define TSENS_STATUS_WINDOW (1UL << 2)

Window monitor match.

Referenced by tsens_clear_status(), and tsens_get_status().

typedef void(* tsens_callback_t)(enum tsens_callback)

Type of the callback functions.

enum tsens_callback

TSENS Callback Types.

Callback types for TSENS callback driver.

Enumerator
TSENS_CALLBACK_RESULT_READY	Callback for result ready.
TSENS_CALLBACK_OVERRUN	Callback when result overwritten before read.
TSENS_CALLBACK_WINDOW	Callback when window is hit.
TSENS_CALLBACK_OVF	Callback when the result overflows.

enum tsens_event_action

TSENS event action enum.

Enum for the possible actions to take on an incoming event.

Enumerator
TSENS_EVENT_ACTION_DISABLED	Event action disabled.
TSENS_EVENT_ACTION_START_CONV	Start conversion.

enum tsens_window_mode

TSENS window monitor mode enum.

Enum for the possible window monitor modes for the TSENS.

Enumerator
TSENS_WINDOW_MODE_DISABLE	No window mode.
TSENS_WINDOW_MODE_ABOVE	RESULT > WINLT.
TSENS_WINDOW_MODE_BELOW	RESULT < WINUT.
TSENS_WINDOW_MODE_INSIDE	WINLT < RESULT < WINUT.
TSENS_WINDOW_MODE_OUTSIDE	!(WINLT < RESULT < WINUT)
TSENS_WINDOW_MODE_HYST_ABOVE	VALUE > WINUT with hysteresis to WINLT.
TSENS_WINDOW_MODE_HYST_BELOW	VALUE < WINLT with hysteresis to WINUT.

static void tsens_clear_status ( const uint32_t status_flags )

inlinestatic

Clears a module status flag.

Clears the given status flag of the module.

Parameters

[in]	module_inst	Pointer to the TSENS software instance struct
[in]	status_flags	Bitmask of `TSENS_STATUS_*` flags to clear

References TSENS_STATUS_OVERFLOW, TSENS_STATUS_OVERRUN, TSENS_STATUS_RESULT_READY, and TSENS_STATUS_WINDOW.

Referenced by tsens_read().

static void tsens_disable ( void )

inlinestatic

Disables the TSENS module.

Disables an TSENS module that was previously enabled.

References tsens_is_syncing().

Referenced by tsens_reset().

static void tsens_disable_callback ( enum tsens_callback callback_type )

inlinestatic

Disables callback.

Disables the callback function registered by the tsens_register_callback.

Parameters

[in] callback_type Callback type given by an enum

References TSENS_CALLBACK_OVERRUN, TSENS_CALLBACK_OVF, TSENS_CALLBACK_RESULT_READY, and TSENS_CALLBACK_WINDOW.

static void tsens_disable_events ( struct tsens_events *const events )

inlinestatic

Disables an TSENS event output.

Disables one or more output events to or from the TSENS module. See tsens_events for a list of events this module supports.

Note: Events cannot be altered while the module is enabled.

Parameters

[in] events Struct containing flags of events to disable

References Assert, and tsens_events::generate_event_on_window_monitor.

static void tsens_enable ( void )

inlinestatic

Enables the TSENS module.

Enables an TSENS module that has previously been configured.

References tsens_is_syncing().

Referenced by configure_tsens().

static void tsens_enable_callback ( enum tsens_callback callback_type )

inlinestatic

Enables callback.

Enables the callback function registered by tsens_register_callback. The callback function will be called from the interrupt handler when the conditions for the callback type are met.

Parameters

[in] callback_type Callback type given by an enum

References TSENS_CALLBACK_OVERRUN, TSENS_CALLBACK_OVF, TSENS_CALLBACK_RESULT_READY, and TSENS_CALLBACK_WINDOW.

Referenced by configure_tsens_callbacks().

static void tsens_enable_events ( struct tsens_events *const events )

inlinestatic

Enables an TSENS event output.

Enables one or more input or output events to or from the TSENS module. See tsens_events for a list of events this module supports.

Note: Events cannot be altered while the module is enabled.

Parameters

[in] events Struct containing flags of events to enable

References Assert, and tsens_events::generate_event_on_window_monitor.

void tsens_get_config_defaults ( struct tsens_config *const config )

Initializes an TSENS configuration structure to defaults.

Initializes a given TSENS configuration struct to a set of known default values. This function should be called on any new instance of the configuration struct before being modified by the user application.

The default configuration is as follows:

GCLK generator 0 (GCLK main) clock source
All events (input and generation) disabled
Free running disabled
Run in standby disabled
Window monitor disabled
Register GAIN value
Register OFFSET value

Note: Register GAIN and OFFSET is loaded from NVM, or can also be fixed. If this bitfield is to be fixed, pay attention to the relationship between GCLK frequency, GAIN, and resolution. See Chapter Module Overview.

Parameters

[out] config Pointer to configuration struct to initialize to default values

References Assert, tsens_config::calibration, tsens_config::clock_source, tsens_config::event_action, tsens_config::free_running, tsens_calibration::gain, GAIN_1_OFFSET, GCLK_GENERATOR_0, tsens_calibration::offset, tsens_config::run_in_standby, TSENS_EVENT_ACTION_DISABLED, TSENS_WINDOW_MODE_DISABLE, tsens_config::window, tsens_window_config::window_lower_value, tsens_window_config::window_mode, and tsens_window_config::window_upper_value.

Referenced by configure_tsens().

static uint32_t tsens_get_status ( void )

inlinestatic

Retrieves the current module status.

Retrieves the status of the module, giving overall state information.

Returns: Bit mask of TSENS status flags.

Return values

TSENS_STATUS_RESULT_READY	TSENS result is ready to be read
TSENS_STATUS_OVERRUN	TSENS result overwritten before read
TSENS_STATUS_WINDOW	TSENS has detected a value inside the set window range
TSENS_STATUS_OVERFLOW	TSENS result overflows

References TSENS_STATUS_OVERFLOW, TSENS_STATUS_OVERRUN, TSENS_STATUS_RESULT_READY, and TSENS_STATUS_WINDOW.

Referenced by tsens_read().

enum status_code tsens_init ( struct tsens_config * config )

Initializes the TSENS.

Initializes the TSENS device struct and the hardware module based on the given configuration struct values.

Parameters

[in] config Pointer to the configuration struct

Returns: Status of the initialization procedure.

Return values

STATUS_OK	The initialization was successful
STATUS_ERR_INVALID_ARG	Invalid argument(s) were provided
STATUS_BUSY	The module is busy with a reset operation
STATUS_ERR_DENIED	The module is enabled

References _tsens_set_config(), Assert, STATUS_BUSY, STATUS_ERR_DENIED, system_apb_clock_set_mask(), and SYSTEM_CLOCK_APB_APBA.

Referenced by configure_tsens().

static bool tsens_is_syncing ( void )

inlinestatic

Determines if the hardware module is currently synchronizing to the bus.

Checks to see if the underlying hardware peripheral module(s) are currently synchronizing across multiple clock domains to the hardware bus. This function can be used to delay further operations on a module until such time that it is ready, to prevent blocking delays for synchronization in the user application.

Returns: Synchronization status of the underlying hardware module(s).

Return values

true	If the module synchronization is ongoing
false	If the module has completed synchronization

Referenced by tsens_disable(), tsens_enable(), tsens_reset(), and tsens_start_conversion().

enum status_code tsens_read ( int32_t * result )

Reads the TSENS result.

Reads the result from a TSENS conversion that was previously started.

Parameters

[out] result Pointer to store the result value in

Returns: Status of the TSENS read request.

Return values

STATUS_OK	The result was retrieved successfully
STATUS_BUSY	A conversion result was not ready
STATUS_ERR_OVERFLOW	The result register has been overwritten by the TSENS module before the result was read by the software

References Assert, STATUS_BUSY, STATUS_ERR_BAD_DATA, STATUS_ERR_OVERFLOW, STATUS_OK, tsens_clear_status(), tsens_get_status(), TSENS_STATUS_OVERRUN, and TSENS_STATUS_RESULT_READY.

Referenced by main().

void tsens_read_job	(	struct tsens_module *const	module_inst,
		int32_t *	result
	)

Read result from TSENS.

Parameters

[in]	module_inst	Pointer to the TSENS software instance struct
[out]	result	Pointer to store the TSENS result

References Assert, result, and tsens_start_conversion().

Referenced by main().

enum status_code tsens_register_callback	(	struct tsens_module *const	module,
		tsens_callback_t	callback_func,
		enum tsens_callback	callback_type
	)

Registers a callback.

Registers a callback function which is implemented by the user.

Note: The callback must be enabled by for the interrupt handler to call it when the condition for the callback is met.

Parameters

[in]	module	Pointer to TSENS software instance struct
[in]	callback_func	Pointer to callback function
[in]	callback_type	Callback type given by an enum

References Assert, STATUS_ERR_INVALID_ARG, and STATUS_OK.

Referenced by configure_tsens_callbacks().

static void tsens_reset ( void )

inlinestatic

Resets the TSENS module.

Resets an TSENS module, clearing all module state and registers to their default values.

References tsens_disable(), and tsens_is_syncing().

static void tsens_start_conversion ( void )

inlinestatic

Start a TSENS conversion.

Start a new TSENS conversion.

References tsens_is_syncing().

Referenced by main(), and tsens_read_job().

enum status_code tsens_unregister_callback	(	struct tsens_module *const	module,
		enum tsens_callback	callback_type
	)

Unregisters a callback.

Unregisters a callback function which is implemented by the user.

Parameters

[in]	module	Pointer to TSENS software instance struct
[in]	callback_type	Callback type given by an enum

References Assert, NULL, STATUS_ERR_INVALID_ARG, and STATUS_OK.

Microchip® Advanced Software Framework

Prerequisites

Module Overview

Window Monitor

Events

Special Considerations

Extra Information

Examples

API Overview

Data Structures

Macros

Typedefs

Enumerations

Module Status Flags

Driver Initialization and Configuration

Status Management

Enable, Disable, and Reset TSENS Module, Start Conversion and Read Result

Callback Management