Atmel Software Framework

 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Common Sensor API

Functions

bool sensor_add_event (sensor_t *sensor, sensor_event_t sensor_event, sensor_event_callback handler, volatile void *arg, bool enable)
 Install a sensor event handler. More...
 
bool sensor_attach (sensor_t *sensor, sensor_type_t type, int num, void *aux)
 Attach a specified sensor descriptor to a sensor device. More...
 
bool sensor_calibrate (sensor_t *sensor, sensor_calibration_t caltype, int code, void *info)
 Calibrate a sensor device. More...
 
bool sensor_device_enum (sensor_type_t type, sensor_enum_callback func, void *arg)
 Enumerate sensor devices. More...
 
bool sensor_device_id (sensor_t *sensor, uint32_t *id, uint8_t *ver)
 Get sensor hardware device ID. More...
 
static bool sensor_disable_event (sensor_t *sensor, sensor_event_t sensor_event)
 Disable a sensor event handler. More...
 
static bool sensor_enable_event (sensor_t *sensor, sensor_event_t sensor_event)
 Enable a sensor event handler. More...
 
bool sensor_enum_bandwidth (sensor_t *sensor, const sensor_band_t **table, size_t *count)
 Enumerate sensor bandwidth settings. More...
 
bool sensor_enum_range (sensor_t *sensor, const sensor_range_t **table, size_t *count)
 Enumerate sensor range settings. More...
 
static bool sensor_get_acceleration (sensor_t *sensor, sensor_data_t *data)
 Get acceleration sensor data. More...
 
static bool sensor_get_angle (sensor_t *sensor, sensor_data_t *data, int angle)
 Read angular rate sensor data. More...
 
static bool sensor_get_bandwidth (sensor_t *sensor, int16_t *bandwidth_Hz)
 Get the sensor operational bandwidth. More...
 
static bool sensor_get_channel (sensor_t *sensor, uint16_t *channel)
 Get sensor channel. More...
 
static bool sensor_get_field (sensor_t *sensor, sensor_data_t *data)
 Get sensor field strength data. More...
 
static bool sensor_get_heading (sensor_t *sensor, sensor_data_t *data)
 Get sensor heading data. More...
 
static bool sensor_get_intensity (sensor_t *sensor, sensor_data_t *data)
 Get sensor intensity data. More...
 
static bool sensor_get_light (sensor_t *sensor, sensor_data_t *data)
 Get sensor light level data. More...
 
static bool sensor_get_pressure (sensor_t *sensor, sensor_data_t *data)
 Get pressure sensor data. More...
 
static bool sensor_get_proximity (sensor_t *sensor, sensor_data_t *data)
 Get sensor proximity data. More...
 
static bool sensor_get_range (sensor_t *sensor, int16_t *range)
 Get the sensor operational range. More...
 
static bool sensor_get_rotation (sensor_t *sensor, sensor_data_t *data)
 Get rotation sensor data. More...
 
static bool sensor_get_sample_interval (sensor_t *sensor, int16_t *interval_ms)
 Get the sensor operational sample interval. More...
 
static bool sensor_get_sample_rate (sensor_t *sensor, int16_t *sample_Hz)
 Get the sensor operational sample rate. More...
 
bool sensor_get_state (sensor_t *sensor, sensor_state_t *mode)
 Get a sensor mode. More...
 
static bool sensor_get_temperature (sensor_t *sensor, sensor_data_t *data)
 Get temperature sensor data. More...
 
bool sensor_get_threshold (sensor_t *sensor, sensor_threshold_t threshold, int16_t *value)
 Get a sensor operational threshold. More...
 
static bool sensor_get_vector (sensor_t *sensor, vector3_t *vector)
 Get vector sensor data. More...
 
bool sensor_ioctl (sensor_t *sensor, sensor_command_t cmd, void *arg)
 Execute a sensor device control function. More...
 
bool sensor_read (sensor_t *sensor, sensor_read_t type, sensor_data_t *data)
 Read sensor data. More...
 
bool sensor_reset (sensor_t *sensor, int arg)
 Initiate a sensor device software reset. More...
 
bool sensor_selftest (sensor_t *sensor, int *test_code, void *arg)
 Activate a sensor self-test function. More...
 
static bool sensor_set_bandwidth (sensor_t *sensor, int16_t bandwidth_Hz)
 Set the sensor operational bandwidth. More...
 
static bool sensor_set_channel (sensor_t *sensor, int16_t channel)
 Set sensor channel. More...
 
static bool sensor_set_current (sensor_t *sensor, int16_t current_mA)
 Set the sensor operational current. More...
 
static bool sensor_set_range (sensor_t *sensor, int16_t range)
 Set the sensor operational range. More...
 
static bool sensor_set_sample_interval (sensor_t *sensor, int16_t interval_ms)
 Set the sensor operational sample interval. More...
 
static bool sensor_set_sample_rate (sensor_t *sensor, int16_t sample_Hz)
 Set the sensor operational sample rate. More...
 
bool sensor_set_state (sensor_t *sensor, sensor_state_t mode)
 Set a sensor mode. More...
 
bool sensor_set_tap (sensor_t *sensor, sensor_tap_params_t *params)
 Set tap event parameters. More...
 
bool sensor_set_threshold (sensor_t *sensor, sensor_threshold_t threshold, int16_t value)
 Set a sensor operational threshold. More...
 
bool sensor_sleep (sensor_t *sensor, int arg)
 Set a sensor device to low-power or standby mode. More...
 
static bool sensor_driver_unimpl (sensor_t *sensor)
 Unimplemented driver function handler. More...
 

Platform Interfaces

const char * sensor_api_version (void)
 Atmel Software Framework Common Sensor API version. More...
 
sensor_hal_tsensor_find (sensor_type_t type)
 Find a sensor hardware descriptor. More...
 
bool sensor_irq_connect (uint32_t intr_pin, void(*handler)(volatile void *), void *arg)
 Install a sensor device interrupt handler. More...
 
sensor_hal_tsensor_list (size_t *dev_count)
 Fetch the sensor hardware descriptor list. More...
 
bool sensor_platform_init (void)
 Initialize the Sensor Platform Hardware. More...
 
uint32_t sensor_timestamp (void)
 This function returns the current timestamp counter value. More...
 

bool sensor_add_event ( sensor_t sensor,
sensor_event_t  sensor_event,
sensor_event_callback  handler,
volatile void *  arg,
bool  enable 
)

Install a sensor event handler.

This routine installs a sensor event handler that will be called when the specified sensor events occur. Function parameters specify the specific sensor event to be reported, the address of the handler function to be called, an optional parameter that will be passed to the handler, and whether the event handler should initially be enabled or disabled.

The event handler can subsequently be enabled and disabled using the sensor_event_enable() and sensor_event_disable() routines.

Parameters
sensorSpecifies an initialized sensor descriptor
sensor_eventSpecifies the sensor event type
handlerSpecifies an application-defined callback
argSpecifies an optional callback argument
enableSpecifies whether or not the event should be enabled
Returns
bool true if the call succeeds, else false is returned.

This routine installs a sensor event handler that will be called when the specified sensor events occur. Function parameters specify the specific sensor event to be reported, the address of the handler function to be called, an optional parameter that will be passed to the handler, and whether the event handler should initially be enabled or disabled.

The event handler can subsequently be enabled and disabled using the sensor_event_enable() and sensor_event_disable() routines.

Parameters
sensorSpecifies an initialized sensor descriptor
sensor_eventSpecifies the sensor event type
handlerSpecifies an application-defined callback
argSpecifies an optional callback argument
enableSpecifies whether or not the event should be enabled
Returns
bool true if the call succeeds, else false is returned.

References arg, sensor_event_callback_t::arg, callback, default_event_handler(), sensor_event_callback_t::handler, NULL, and SENSOR_DRV_CALL.

const char* sensor_api_version ( void  )

Atmel Software Framework Common Sensor API version.

This routine Gets the Sensor API version number and release date.

Returns
The address of a null-terminated read-only version string.

This routine Gets the Sensor API version number and release date.

Returns
The address of a null-terminated read-only version string.
bool sensor_attach ( sensor_t sensor,
sensor_type_t  type,
int  num,
void *  aux 
)

Attach a specified sensor descriptor to a sensor device.

Applications invoke this routine to attach a sensor_t instance to an existing sensor device of a specified type. Assuming the attach call is successful, the sensor_t instance can then be used with other sensor API functions to perform operations on the device.

Parameters
sensorSpecifies a descriptor to attach to the sensor device.
typeSpecifies the sensor type to attach.
numDriver instance number; currently ignored.
auxAPI Reserved value; should always be set to zero.
Returns
bool true if the call succeeds, else false is returned.

Applications invoke this routine to attach a sensor_t instance to an existing sensor device of a specified type. Assuming the attach call is successful, the sensor_t instance can then be used with other sensor API functions to perform operations on the device.

Parameters
sensorSpecifies a descriptor to attach to the sensor device.
typeSpecifies the sensor type to attach.
numDriver instance number; currently ignored.
auxAPI Reserved value; should always be set to zero.
Returns
bool true if the call succeeds, else false is returned.

References sensor_desc::aux, sensor_desc::err, sensor_desc::hal, sensor_desc::mod, NULL, SENSOR_ERR_DRIVER, SENSOR_ERR_NONE, sensor_find(), sensor_hal::sensor_init, SENSOR_STATE_NORMAL, and sensor_desc::type.

bool sensor_calibrate ( sensor_t sensor,
sensor_calibration_t  caltype,
int  code,
void *  caldata 
)

Calibrate a sensor device.

Parameters
sensorThe address of an initialized sensor descriptor.
caltypeThe type of calibration to perform.
codeDevice-specific calibration code or step parameter.
infoUnimplemented (ignored) parameter.
Returns
bool true if the call succeeds, else false is returned.
Parameters
sensorThe address of an initialized sensor descriptor.
caltypeThe type of calibration to perform.
Returns
bool true if the call succeeds, else false is returned.

References SENSOR_DRV_CALL.

bool sensor_device_enum ( sensor_type_t  type,
sensor_enum_callback  func,
void *  arg 
)

Enumerate sensor devices.

This routine is a sensor device enumeration function that will call a user-defined callback func for each sensor of a specified type configured into the system. The user-callback function will be passed the address of a sensor_hal_t HAL descriptor corresponding to the sensor type along with a user-specified address arg storing any additional function arguments.

If the specified sensor type is SENSOR_TYPE_UNKNOWN, then the user func will be called for every sensor device in the system.

Once called, the user-callback function must return a boolean true value to continue iterating the list, else false to cease device list iteration. This routine returns when there are not more sensors of the requested type in the device list, or when the user function returns zero (false).

Note that this function will not be included in the API by default. Build a sensor system with INCLUDE_SENSOR_ENUM defined to include this routine.

Parameters
typeSpecifies the sensor type to enumerate.
funcSpecifies the address of a user callback function.
argSpecifies the address of a callback function argument.
Returns
bool true if the call succeeds, else false is returned.

This routine is a sensor device enumeration function that will call a user-defined callback func for each sensor of a specified type configured into the system. The user-callback function will be passed the address of a sensor_hal_t HAL descriptor corresponding to the sensor type along with a user-specified address arg storing any additional function arguments.

If the specified sensor type is SENSOR_TYPE_UNKNOWN, then the user func will be called for every sensor device in the system.

Once called, the user-callback function must return a boolean true value to continue iterating the list, else false to cease device list iteration. This routine returns when there are not more sensors of the requested type in the device list, or when the user function returns zero (false).

Note that this function will not be included in the API by default. Build a sensor system with INCLUDE_SENSOR_ENUM defined to include this routine.

Parameters
typeSpecifies the sensor type to enumerate.
funcSpecifies the address of a user callback function.
argSpecifies the address of a callback function argument.
Returns
bool true if the call succeeds, else false is returned.

References count, sensor_hal::dev_type, n, sensor_list(), and SENSOR_TYPE_UNKNOWN.

bool sensor_device_id ( sensor_t sensor,
uint32_t *  id,
uint8_t *  ver 
)

Get sensor hardware device ID.

This routine returns device-specific sensor hardware identification and, optionally, version values. Unimplemented values will be set to zero. For example, devices supporting a dedicated ID register, but not a version register, will set "id" to the ID value and "ver" to zero.

Parameters
sensorThe address of an initialized sensor descriptor.
idAn address where the device ID is returned.
verAn address where the device version is returned.
Returns
bool true if the call succeeds, else false is returned.

This routine returns device-specific sensor hardware identification and, optionally, version values. Unimplemented values will be set to zero. For example, devices supporting a dedicated ID register, but not a version register, will set "id" to the ID value and "ver" to zero.

Parameters
sensorThe address of an initialized sensor descriptor.
idAn address where the device ID is returned.
verAn address where the device version is returned.
Returns
bool true if the call succeeds, else false is returned.

References sensor_data_t::device, sensor_read(), SENSOR_READ_ID, and status.

static bool sensor_disable_event ( sensor_t sensor,
sensor_event_t  sensor_event 
)
inlinestatic

Disable a sensor event handler.

This routine disables the handler for a sensor event. The event handler must have already been defined using sensor_add_event(). To enable the event, see sensor_enable_event().

Parameters
sensorSpecifies an initialized sensor descriptor
sensor_eventSpecifies the sensor event type
Returns
bool true if the call succeeds, else false is returned.

References SENSOR_DISABLE_EVENT, and sensor_ioctl().

static bool sensor_driver_unimpl ( sensor_t sensor)
inlinestatic

Unimplemented driver function handler.

This routine is called in the API to set the sensor error status and return a status indicating a function call failure when a driver has been invoked to run an interface that's not implemented in the driver.

Parameters
sensorThe address of an initialized sensor descriptor.
Returns
bool Always returns false.

References sensor_desc::err, and SENSOR_ERR_FUNCTION.

static bool sensor_enable_event ( sensor_t sensor,
sensor_event_t  sensor_event 
)
inlinestatic

Enable a sensor event handler.

This routine enables the handler for a sensor event. The event handler must have already been defined using sensor_add_event(). To disable the event, see sensor_disable_event().

Parameters
sensorSpecifies an initialized sensor descriptor
sensor_eventSpecifies the sensor event type
Returns
bool true if the call succeeds, else false is returned.

References SENSOR_ENABLE_EVENT, and sensor_ioctl().

bool sensor_enum_bandwidth ( sensor_t sensor,
const sensor_band_t **  table,
size_t *  count 
)

Enumerate sensor bandwidth settings.

This routine returns the address of a table, if any, holding device-specific sensor bandwidth settings. The use and context of the settings are specific to the device and typically documented in the manufacturer's data sheets for the device.

Parameters
sensorThe address of a sensor descriptor.
tableLocation where the table address is returned.
countLocation where the number of table elements is returned.
Returns
bool true if the call succeeds, else false is returned.

This routine returns the address of a table, if any, holding device-specific sensor bandwidth settings. The use and context of the settings are specific to the device and typically documented in the manufacturer's data sheets for the device.

Parameters
sensorThe address of a sensor descriptor.
tableLocation where the table address is returned.
countLocation where the number of table elements is returned.
Returns
bool true if the call succeeds, else false is returned.

References sensor_caps_t::band_count, sensor_caps_t::band_table, sensor_device_t::caps, and sensor_desc::drv.

bool sensor_enum_range ( sensor_t sensor,
const sensor_range_t **  table,
size_t *  count 
)

Enumerate sensor range settings.

This routine returns the address of a table, if any, holding device-specific sensor range settings. The units of the settings are specific to the device and typically documented in the manufacturer's data sheets for the device.

Parameters
sensorThe address of a sensor descriptor.
tableLocation where the table address is returned.
countLocation where the number of table elements is returned.
Returns
bool true if the call succeeds, else false is returned.

This routine returns the address of a table, if any, holding device-specific sensor range settings. The units of the settings are specific to the device and typically documented in the manufacturer's data sheets for the device.

Parameters
sensorThe address of a sensor descriptor.
tableLocation where the table address is returned.
countLocation where the number of table elements is returned.
Returns
bool true if the call succeeds, else false is returned.

References sensor_device_t::caps, sensor_desc::drv, sensor_caps_t::range_count, and sensor_caps_t::range_table.

sensor_hal_t* sensor_find ( sensor_type_t  type)

Find a sensor hardware descriptor.

This routine returns the address of a sensor hardware descriptor, based on the sensor type specified in the type parameter. The first hardware entry with the correct type will be used.

This utility is currently used to abstract the details of the device list implementation from the rest of the API. However, it will not be retained in future versions of the API. As a result applications and library code should not use this routine. If list iteration is required in API clients, use the sensor_device_enum() function.

Parameters
typeThe type of sensor to find in hardware descriptor list
Returns
The address of the sensor hardware descriptor, or NULL if not found

References index, and sensor_list().

Referenced by sensor_attach().

static bool sensor_get_acceleration ( sensor_t sensor,
sensor_data_t data 
)
inlinestatic

Get acceleration sensor data.

Parameters
sensorThe address of an initialized sensor descriptor.
dataSpecifies an address where sensor data is stored.
Returns
bool true if the call succeeds, else false is returned.

References sensor_read(), and SENSOR_READ_ACCELERATION.

static bool sensor_get_angle ( sensor_t sensor,
sensor_data_t data,
int  angle 
)
inlinestatic

Read angular rate sensor data.

This routine returns a data sample for an angle of a specified angular rate sensor device such as a gyroscope.

In the event of a false return from this routine, the contents stored at the location specified by data are undefined.

Note
This routine is only supported for drivers implementing the get_rotation driver interface.
Parameters
sensorThe address of an initialized sensor descriptor.
dataSpecifies an address where sensor data is stored.
angleSpecifies the angle (pitch = 0, roll = 1, yaw = 2)
Returns
bool true if the call succeeds, else false is returned.

References sensor_read(), SENSOR_READ_ROTATION, and sensor_data_t::value.

static bool sensor_get_bandwidth ( sensor_t sensor,
int16_t *  bandwidth_Hz 
)
inlinestatic

Get the sensor operational bandwidth.

Parameters
sensorThe address of an initialized sensor descriptor.
bandwidth_HzThe current sensor operational bandwidth in Hertz.
Returns
bool true if the call succeeds, else false is returned.

References SENSOR_GET_BANDWIDTH, and sensor_ioctl().

static bool sensor_get_channel ( sensor_t sensor,
uint16_t *  channel 
)
inlinestatic

Get sensor channel.

This routine obtains the individual channel that is currently selected within a multi-channel sensor device.

Parameters
sensorThe address of an initialized sensor descriptor.
channelThe address where the current channel is to be returned.
Returns
bool true if the call succeeds, else false is returned.

References sensor_desc::channel.

static bool sensor_get_field ( sensor_t sensor,
sensor_data_t data 
)
inlinestatic

Get sensor field strength data.

Parameters
sensorThe address of an initialized sensor descriptor.
dataSpecifies an address where sensor data is stored.
Returns
bool true if the call succeeds, else false is returned.

References sensor_read(), and SENSOR_READ_FIELD.

static bool sensor_get_heading ( sensor_t sensor,
sensor_data_t data 
)
inlinestatic

Get sensor heading data.

Parameters
sensorThe address of an initialized sensor descriptor.
dataSpecifies an address where sensor data is stored.
Returns
bool true if the call succeeds, else false is returned.

References sensor_read(), and SENSOR_READ_HEADING.

static bool sensor_get_intensity ( sensor_t sensor,
sensor_data_t data 
)
inlinestatic

Get sensor intensity data.

Parameters
sensorThe address of an initialized sensor descriptor.
dataSpecifies an address where sensor data is stored.
Returns
bool true if the call succeeds, else false is returned.

References sensor_read(), and SENSOR_READ_INTENSITY.

static bool sensor_get_light ( sensor_t sensor,
sensor_data_t data 
)
inlinestatic

Get sensor light level data.

Parameters
sensorThe address of an initialized sensor descriptor.
dataSpecifies an address where sensor data is stored.
Returns
bool true if the call succeeds, else false is returned.

References sensor_read(), and SENSOR_READ_LIGHT.

static bool sensor_get_pressure ( sensor_t sensor,
sensor_data_t data 
)
inlinestatic

Get pressure sensor data.

Parameters
sensorThe address of an initialized sensor descriptor.
dataSpecifies an address where sensor data is stored.
Returns
bool true if the call succeeds, else false is returned.

References sensor_read(), and SENSOR_READ_PRESSURE.

static bool sensor_get_proximity ( sensor_t sensor,
sensor_data_t data 
)
inlinestatic

Get sensor proximity data.

Parameters
sensorThe address of an initialized sensor descriptor.
dataSpecifies an address where sensor data is stored.
Returns
bool true if the call succeeds, else false is returned.

References sensor_read(), and SENSOR_READ_PROXIMITY.

static bool sensor_get_range ( sensor_t sensor,
int16_t *  range 
)
inlinestatic

Get the sensor operational range.

Parameters
sensorThe address of an initialized sensor descriptor.
rangeThe current sensor operational range.
Returns
bool true if the call succeeds, else false is returned.

References SENSOR_GET_RANGE, and sensor_ioctl().

static bool sensor_get_rotation ( sensor_t sensor,
sensor_data_t data 
)
inlinestatic

Get rotation sensor data.

Parameters
sensorThe address of an initialized sensor descriptor.
dataSpecifies an address where sensor data is stored.
Returns
bool true if the call succeeds, else false is returned.

References sensor_read(), and SENSOR_READ_ROTATION.

static bool sensor_get_sample_interval ( sensor_t sensor,
int16_t *  interval_ms 
)
inlinestatic

Get the sensor operational sample interval.

Parameters
sensorThe address of an initialized sensor descriptor.
interval_msAddress where sample interval to be returned.
Returns
bool true if the call succeeds, else false is returned.

References SENSOR_GET_SAMPLE_RATE, sensor_ioctl(), and status.

static bool sensor_get_sample_rate ( sensor_t sensor,
int16_t *  sample_Hz 
)
inlinestatic

Get the sensor operational sample rate.

Parameters
sensorThe address of an initialized sensor descriptor.
sample_HzThe current sensor sample rate in Hertz.
Returns
bool true if the call succeeds, else false is returned.

References SENSOR_GET_SAMPLE_RATE, and sensor_ioctl().

bool sensor_get_state ( sensor_t sensor,
sensor_state_t mode 
)

Get a sensor mode.

This routine gets the current sensor execution state which may be one of the following values:

 - SENSOR_STATE_NORMAL
 - SENSOR_STATE_SLEEP
 - SENSOR_STATE_SUSPEND
 - SENSOR_STATE_LOWEST_POWER
 - SENSOR_STATE_LOW_POWER
 - SENSOR_STATE_HIGH_POWER
 - SENSOR_STATE_HIGHEST_POWER
 - SENSOR_STATE_RESET

These execution states are not supported in all devices. The function return value will indicate whether or not the request could be processed. The result of the request, when supported, is device dependent.

Parameters
sensorThe address of an initialized sensor descriptor.
modeThe current sensor mode is returned to this location.
Returns
bool true if the call succeeds, else false is returned.

This routine gets the current sensor execution state which may be one of the following values:

  • SENSOR_STATE_NORMAL
  • SENSOR_STATE_SLEEP
  • SENSOR_STATE_SUSPEND
  • SENSOR_STATE_LOWEST_POWER
  • SENSOR_STATE_LOW_POWER
  • SENSOR_STATE_HIGH_POWER
  • SENSOR_STATE_HIGHEST_POWER
  • SENSOR_STATE_RESET

These execution states are not supported in all devices. The function return value will indicate whether or not the request could be processed. The result of the request, when supported, is device dependent.

Parameters
sensorThe address of an initialized sensor descriptor.
modeThe current sensor mode is returned to this location.
Returns
bool true if the call succeeds, else false is returned.

References sensor_desc::mod.

static bool sensor_get_temperature ( sensor_t sensor,
sensor_data_t data 
)
inlinestatic

Get temperature sensor data.

Parameters
sensorThe address of an initialized sensor descriptor.
dataSpecifies an address where sensor data is stored.
Returns
bool true if the call succeeds, else false is returned.

References sensor_read(), and SENSOR_READ_TEMPERATURE.

bool sensor_get_threshold ( sensor_t sensor,
sensor_threshold_t  type,
int16_t *  value 
)

Get a sensor operational threshold.

Parameters
sensorThe address of an initialized sensor descriptor.
thresholdA specified sensor operational threshold.
valueAddress of location to return threshold value
Returns
bool true if the call succeeds, else false is returned.
Parameters
sensorThe address of an initialized sensor descriptor.
typeA specified sensor operational threshold type.
valueAddress of location to return threshold value
Returns
bool true if the call succeeds, else false is returned.

References SENSOR_DRV_CALL, SENSOR_GET_THRESHOLD, status, sensor_threshold_desc_t::type, and sensor_threshold_desc_t::value.

static bool sensor_get_vector ( sensor_t sensor,
vector3_t vector 
)
inlinestatic

Get vector sensor data.

This routine reads a specified sensor and returns the data stored in in a vector3_t data format for use with API routines that operate on that format.

In the event of a false return from this routine, the contents stored at the location specified by "data" are undefined.

Parameters
sensorThe address of an initialized sensor descriptor.
vectorSpecifies an address where sensor data is stored.
Returns
bool true if the call succeeds, else false is returned.

References sensor_ioctl(), and SENSOR_READ_VECTOR.

bool sensor_ioctl ( sensor_t sensor,
sensor_command_t  cmd,
void *  arg 
)

Execute a sensor device control function.

Parameters
sensorThe address of an initialized sensor descriptor.
cmdSpecifies the IOCTL command.
argSpecifies command parameters (varies by command).
Returns
bool true if the call succeeds, else false is returned.
Parameters
sensorThe address of an initialized sensor descriptor.
cmdSpecifies the IOCTL command.
argSpecifies command parameters (varies by command).
Returns
bool true if the call succeeds, else false is returned.

References sensor_hal::bandwidth, sensor_device_t::caps, sensor_desc::drv, sensor_desc::err, sensor_desc::hal, index, sensor_hal::range, sensor_hal::sample_rate, sensor_band_index(), SENSOR_DRV_CALL, SENSOR_ERR_FUNCTION, SENSOR_ERR_PARAMS, SENSOR_GET_BANDWIDTH, SENSOR_GET_RANGE, SENSOR_GET_SAMPLE_RATE, sensor_range_index(), SENSOR_SET_BANDWIDTH, SENSOR_SET_RANGE, and SENSOR_SET_SAMPLE_RATE.

Referenced by sensor_disable_event(), sensor_enable_event(), sensor_get_bandwidth(), sensor_get_range(), sensor_get_sample_interval(), sensor_get_sample_rate(), sensor_get_vector(), sensor_set_bandwidth(), sensor_set_current(), sensor_set_range(), sensor_set_sample_interval(), and sensor_set_sample_rate().

bool sensor_irq_connect ( uint32_t  intr_pin,
void(*)(volatile void *)  handler,
void *  arg 
)

Install a sensor device interrupt handler.

This routine will enable interrupts on the pin specified by the intr_pin parameter and call a user-defined callback handler when an interrupt is detected. The arg parameter is used to pass the address of user-defined input and output storage for the callback handler. Calling the routine with the handler parameter set to 0 (the NULL pointer) will cause interrupts to be disabled for the specified GPIO pin.

Parameters
intr_pinBoard-specific interrupt / GPIO pin interface to the MCU.
handlerThe address of a user-defined interrupt handler.
argAn optional address passed to the interrupt handler.
Returns
bool true if the call succeeds, else false.

References sensor_board_irq_connect(), and status.

Referenced by bma150_init(), bma220_init(), bma222_init(), bma250_init(), itg3200_init(), kxtf9_init(), and sfh7770_init().

sensor_hal_t* sensor_list ( size_t *  dev_count)

Fetch the sensor hardware descriptor list.

This routine returns the system address of a table of sensor hardware descriptors along with the number of descriptors in the dev_count parameter. This utility is currently used to abstract the details of the device list implementation from the rest of the API. However, it will not be retained in future versions of the API. As a result applications and library code should not use this routine. If list iteration is required in API clients, use the sensor_device_enum() function.

Parameters
dev_countThe list descriptor count is returned here.
Returns
The address of the sensor hardware descriptor list.

Sensor Device List

When a new driver is added to the API a HAL descriptor indicating the sensor type, xxx_init() function prefix, bus address (where applicable), and I/O Pin assignment (where applicable) should be conditionally allocated in this table.

References ARRAYSIZE, SENSOR_HAL_DESC, SENSOR_TYPE_ACCELEROMETER, SENSOR_TYPE_BAROMETER, SENSOR_TYPE_COMPASS, SENSOR_TYPE_GYROSCOPE, SENSOR_TYPE_LIGHT, and SENSOR_TYPE_PROXIMITY.

Referenced by sensor_device_enum(), and sensor_find().

bool sensor_platform_init ( void  )

Initialize the Sensor Platform Hardware.

This function initializes the Atmel Xplained platform hardware and must be called once from the client application before any of the Sensors Xplained API routines can be used.

After the platform board initialization (i.e. board_init()) configures GPIO pins, interrupts, etc., this routine initializes the microcontroller hardware abstraction layer (HAL) for the Xplained Sensor API.

Note
Sensor device availability varies by development board. Even in cases where the underlying platform has a supported sensor device, the required support code for the sensor service may not have been implemented. Consult the development board documentation to determine whether the sensor API is supported.
See Also
Sensors Xplained Extension Board Configuration
Returns
bool true if the call succeeds, else false is returned.

This function initializes the Atmel Xplained platform hardware and must be called once from the client application before any of the Sensors Xplained API routines can be used.

After the platform board initialization (i.e. board_init()) configures GPIO pins, interrupts, etc., this routine initializes the AVR and AVR32 hardware abstraction layer (HAL) for the Xplained Sensor API.

Returns
bool true if the call succeeds, else false is returned.

References usart_options_t::baudrate, board_init(), BUS_TYPE_UNKNOWN, BUSIO_IF, BUSIO_SPEED, BUSIO_TYPE, CONFIG_USART_BAUDRATE, CONFIG_USART_CHAR_LENGTH, CONFIG_USART_IF, CONFIG_USART_PARITY, CONFIG_USART_STOP_BIT, delay_ms, sensor_bus_init, SENSOR_START_DELAY_MSEC, stdio_serial_init(), stdio_usb_init(), and sysclk_init().

bool sensor_read ( sensor_t sensor,
sensor_read_t  type,
sensor_data_t data 
)

Read sensor data.

This is a generic routine that will call a specified sensor function
returning \c vector sensor data.  It is used primarily by API routines
but may be called by special-case application or library code where
needed to extend the API semantics.

As an example, consider a multiple-axis gyroscope driver implementing
the sensor_funcs_t.get_rotation() interface.  An application will usually
call the sensor_get_rotation() routine in this case, but the angular
rate might be obtained from the device as follows:
sensor_t gyroscope;
...
sensor_read(&gyroscope, SENSOR_READ_ROTATION, &omega);
...

In the event of a false return from this routine, the contents stored at the location specified by "data" are undefined.

Parameters
sensorThe address of an initialized sensor descriptor.
typeType of read operation to perform.
dataSpecifies an address where sensor data is stored.
Returns
bool true if the call succeeds, else false is returned.

This is a generic routine that will call a specified sensor function returning sensor data. It is used primarily by API routines but may be called by special-case application or library code where needed to extend the API semantics.

As an example, consider a multiple-axis gyroscope driver implementing the sensor_funcs_t.get_rotation() interface. An application will usually call the sensor_get_rotation() routine in this case, but the angular rate might be obtained from the device as follows:

*
* sensor_t gyroscope;
* sensor_data_t omega;
* ...
*
* sensor_read (&gyroscope, SENSOR_READ_ROTATION, &omega);
* ...
*
*

In the event of a false return from this routine, the contents stored at the location specified by "data" are undefined.

Parameters
sensorThe address of an initialized sensor descriptor.
typeType of sample to read from sensor
dataSpecifies an address where sensor data is stored.
Returns
bool true if the call succeeds, else false is returned.

References read(), SENSOR_DRV_CALL, sensor_timestamp(), and sensor_data_t::timestamp.

Referenced by sensor_device_id(), sensor_get_acceleration(), sensor_get_angle(), sensor_get_field(), sensor_get_heading(), sensor_get_intensity(), sensor_get_light(), sensor_get_pressure(), sensor_get_proximity(), sensor_get_rotation(), and sensor_get_temperature().

bool sensor_reset ( sensor_t sensor,
int  arg 
)

Initiate a sensor device software reset.

Parameters
sensorThe address of an initialized sensor descriptor.
argDevice-specific argument options.
Returns
bool true if the call succeeds, else false is returned.
Parameters
sensorThe address of an initialized sensor descriptor.
Returns
bool true if the call succeeds, else false is returned.

References sensor_set_state(), and SENSOR_STATE_RESET.

bool sensor_selftest ( sensor_t sensor,
int *  test_code,
void *  arg 
)

Activate a sensor self-test function.

Parameters
sensorAddress of an initialized sensor device descriptor.
test_codeAddress of a device-specific numeric test code.
argDevice-specific self-test argument options.
Returns
bool true if the test succeeds, else false is returned.
Parameters
sensorAddress of an initialized sensor device descriptor.
test_codeAddress of a device-specific numeric test code.
argDevice-specific self-test argument options.
Returns
bool true if the test succeeds, else false is returned.

References sensor_desc::err, SENSOR_DRV_CALL, SENSOR_ERR_FUNCTION, and SENSOR_ERR_SELFTEST.

static bool sensor_set_bandwidth ( sensor_t sensor,
int16_t  bandwidth_Hz 
)
inlinestatic

Set the sensor operational bandwidth.

Parameters
sensorThe address of an initialized sensor descriptor.
bandwidth_HzThe new sensor operational bandwidth in Hertz.
Returns
bool true if the call succeeds, else false is returned.

References sensor_ioctl(), and SENSOR_SET_BANDWIDTH.

static bool sensor_set_channel ( sensor_t sensor,
int16_t  channel 
)
inlinestatic

Set sensor channel.

This routine selects the individual channel within a multi-channel sensor device. This selection is then used is subsequent function calls that control the sensor.

Specifying a value of -1 (SENSOR_CHANNEL_ALL) for the sensor channel indicates that all channels are to be affected by the subsequent function calls.

Parameters
sensorThe address of an initialized sensor descriptor.
channelThe number of the channel to be selected, or -1 for all.
Returns
bool true if the call succeeds, else false is returned.

References sensor_desc::channel.

static bool sensor_set_current ( sensor_t sensor,
int16_t  current_mA 
)
inlinestatic

Set the sensor operational current.

Parameters
sensorThe address of an initialized sensor descriptor.
current_mAThe new sensor operational current in mA
Returns
bool true if the call succeeds, else false is returned.

References sensor_ioctl(), and SENSOR_SET_CURRENT.

static bool sensor_set_range ( sensor_t sensor,
int16_t  range 
)
inlinestatic

Set the sensor operational range.

Parameters
sensorThe address of an initialized sensor descriptor.
rangeThe new sensor operational range.
Returns
bool true if the call succeeds, else false is returned.

References sensor_ioctl(), and SENSOR_SET_RANGE.

static bool sensor_set_sample_interval ( sensor_t sensor,
int16_t  interval_ms 
)
inlinestatic

Set the sensor operational sample interval.

Parameters
sensorThe address of an initialized sensor descriptor.
interval_msThe new sensor sample interval in milliseconds.
Returns
bool true if the call succeeds, else false is returned.

References sensor_ioctl(), and SENSOR_SET_SAMPLE_RATE.

static bool sensor_set_sample_rate ( sensor_t sensor,
int16_t  sample_Hz 
)
inlinestatic

Set the sensor operational sample rate.

Parameters
sensorThe address of an initialized sensor descriptor.
sample_HzThe new sensor operational sample rate in Hertz.
Returns
bool true if the call succeeds, else false is returned.

References sensor_ioctl(), and SENSOR_SET_SAMPLE_RATE.

bool sensor_set_state ( sensor_t sensor,
sensor_state_t  mode 
)

Set a sensor mode.

This routine sets a specified sensor execution state to one of the following values:

 - SENSOR_STATE_NORMAL
 - SENSOR_STATE_SLEEP
 - SENSOR_STATE_SUSPEND
 - SENSOR_STATE_LOWEST_POWER
 - SENSOR_STATE_LOW_POWER
 - SENSOR_STATE_HIGH_POWER
 - SENSOR_STATE_HIGHEST_POWER
 - SENSOR_STATE_RESET

These execution states are not supported in all devices. The function return value will indicate whether or not the request could be processed. The result of the request, when supported, is device dependent.

Parameters
sensorThe address of an initialized sensor descriptor.
modeA specified sensor operational mode.
Returns
bool true if the call succeeds, else false is returned.

This routine sets a specified sensor execution state to one of the following values:

  • SENSOR_STATE_NORMAL
  • SENSOR_STATE_SLEEP
  • SENSOR_STATE_SUSPEND
  • SENSOR_STATE_LOWEST_POWER
  • SENSOR_STATE_LOW_POWER
  • SENSOR_STATE_HIGH_POWER
  • SENSOR_STATE_HIGHEST_POWER
  • SENSOR_STATE_RESET

These execution states are not supported in all devices. The function return value will indicate whether or not the request could be processed. The result of the request, when supported, is device dependent.

Parameters
sensorThe address of an initialized sensor descriptor.
modeA specified sensor operational mode.
Returns
bool true if the call succeeds, else false is returned.

References sensor_desc::mod, SENSOR_DRV_CALL, SENSOR_SET_STATE, SENSOR_STATE_NORMAL, and SENSOR_STATE_RESET.

Referenced by sensor_reset(), and sensor_sleep().

bool sensor_set_tap ( sensor_t sensor,
sensor_tap_params_t params 
)

Set tap event parameters.

Parameters
sensorAddress of an initialized sensor device descriptor.
paramsAddress of a tap parameter structure.
Returns
bool true if the call succeeds, else false is returned.
Parameters
sensorAddress of an initialized sensor device descriptor.
paramsAddress of a tap parameter structure.
Returns
bool true if the call succeeds, else false is returned.

References SENSOR_DRV_CALL, and SENSOR_SET_TAP.

bool sensor_set_threshold ( sensor_t sensor,
sensor_threshold_t  type,
int16_t  value 
)

Set a sensor operational threshold.

Parameters
sensorThe address of an initialized sensor descriptor.
thresholdA specified sensor operational threshold.
valueThe value of the specified threshold.
Returns
bool true if the call succeeds, else false is returned.
Parameters
sensorThe address of an initialized sensor descriptor.
typeA specified sensor operational threshold type.
valueThe value of the specified threshold.
Returns
bool true if the call succeeds, else false is returned.

References SENSOR_DRV_CALL, SENSOR_SET_THRESHOLD, sensor_threshold_desc_t::type, and sensor_threshold_desc_t::value.

bool sensor_sleep ( sensor_t sensor,
int  arg 
)

Set a sensor device to low-power or standby mode.

Parameters
sensorThe address of an initialized sensor descriptor.
argDevice-specific argument options.
Returns
bool true if the call succeeds, else false is returned.
Parameters
sensorThe address of an initialized sensor descriptor.
Returns
bool true if the call succeeds, else false is returned.

References sensor_set_state(), and SENSOR_STATE_SLEEP.

uint32_t sensor_timestamp ( void  )

This function returns the current timestamp counter value.

The timestamp facility is implemented in terms of the XMEGA or UC3 timer and clock function APIs.

Returns
The current counter value (microseconds).

References cpu_cy_2_us(), Get_system_register, and sysclk_get_cpu_hz().

Referenced by bma150_isr(), bma220_isr(), bma222_isr(), bma250_isr(), imu3000_isr(), itg3200_isr(), kxtf9_isr(), sensor_read(), and sfh7770_isr().