Sensor API¶
The sensor API implements the sensor abstraction and the functions:
For a sensor device driver package to initialize a sensor object with the device specific information.
For an application to read sensor data from a sensor and to configure a sensor for polling.
A sensor is represented by the struct sensor
object.
Sensor API Functions Used by a Sensor Device Driver Package¶
A sensor device driver package must use the sensor API to initialize device specific information for a sensor object and to change sensor configuration types.
Initializing a Sensor Object¶
When the BSP or the sensor creator package creates an OS device for a
sensor named SENSORNAME
, it specifies the <sensorname>_init()
callback function, that the device driver exports, for the
os_dev_create()
function to call to initialize the device. The
<sensorname>_init()
function must use the following sensor API
functions to set the driver and interface information in the sensor
object:
The
sensor_init()
function to initialize thestruct sensor
object for the device.The
sensor_set_driver()
function to set the types that the sensor device supports and the sensor driver functions to read the sensor data from the device and to retrieve the value type for a given sensor type.The
sensor_set_interface()
function to set the interface to use to communicate with the sensor device.
Notes:
See the Sensor Device Driver page for the functions and data structures that a sensor driver package exports.
The
<sensorname>_init()
function must also call thesensor_mgr_register()
function to register the sensor with the sensor manager. See the Sensor Manager API for details.
Setting the Configured Sensor Types¶
The BSP, or the sensor creator package, also calls the
<sensorname>_config()
function to configure the sensor device with
default values. The <sensorname>_config()
function is exported by
the sensor device driver and must call the sensor API
sensor_set_type_mask()
function to set the configured sensor types
in the sensor object. The configured sensor types are a subset of the
sensor types that the device supports. The sensor framework must know
the sensor types that a sensor device is configured for because it only
reads sensor data for the configured sensor types.
Note: An application may also call the <sensorname>_config()
function to configure the sensor device.
Sensor API Functions Used By an Application¶
The sensor API provides the functions for an application to read sensor data from a sensor and to configure a sensor for polling.
Reading Sensor Data¶
An application calls the sensor_read()
function to read sensor data
from a sensor device. You specify a bit mask of the configured sensor
types to read from a sensor device and a callback function to call when
the sensor data is read. The callback is called for each specified
configured type and the data read for that sensor type is passed to the
callback.
Setting a Poll Rate for A Sensor¶
The sensor manager implements a poller that reads sensor data from a
sensor at specified poll intervals. An application must call the
sensor_set_poll_rate_ms()
function to set the poll rate for a sensor
in order for poller to poll the sensor.
Note: An application needs to register a sensor listener to receive the sensor data that the sensor manager poller reads from a sensor.
Data Structures¶
We list the main data structures that the sensor API uses and mention things to note. For more details, see the sensor.h include file.
Sensor Object¶
The struct sensor
data structure represents the sensor device. The
sensor API, the sensor manager
API, and the sensor
listener API
all operate on the sensor
object abstraction. A sensor is maintained
in the sensor manager global sensors list.
struct sensor {
/* The OS device this sensor inherits from, this is typically a sensor
* specific driver.
*/
struct os_dev *s_dev;
/* The lock for this sensor object */
struct os_mutex s_lock;
/* A bit mask describing the types of sensor objects available from this
* sensor. If the bit corresponding to the sensor_type_t is set, then this
* sensor supports that variable.
*/
sensor_type_t s_types;
/* Sensor mask of the configured sensor type s*/
sensor_type_t s_mask;
/**
* Poll rate in MS for this sensor.
*/
uint32_t s_poll_rate;
/* The next time at which we want to poll data from this sensor */
os_time_t s_next_run;
/* Sensor driver specific functions, created by the device registering the
* sensor.
*/
struct sensor_driver *s_funcs;
/* Sensor last reading timestamp */
struct sensor_timestamp s_sts;
/* Sensor interface structure */
struct sensor_itf s_itf;
/* A list of listeners that are registered to receive data off of this
* sensor
*/
SLIST_HEAD(, sensor_listener) s_listener_list;
/* The next sensor in the global sensor list. */
SLIST_ENTRY(sensor) s_next;
};
Note: There are two fields, s_types
and s_mask
, of type
sensor_type_t
. The s_types
field is a bit mask that specifies
the sensor types that the sensor device supports. The s_mask
field
is a bit mask that specifies the sensor types that the sensor device is
configured for. Only sensor data for a configured sensor type can be
read.
Sensor Types¶
The sensor_type_t
type is an enumeration of a bit mask of sensor
types, with each bit representing one sensor type. Here is an excerpt of
the enumeration values. See the
sensor.h
for details:
typedef enum {
/* No sensor type, used for queries */
SENSOR_TYPE_NONE = 0,
/* Accelerometer functionality supported */
SENSOR_TYPE_ACCELEROMETER = (1 << 0),
/* Magnetic field supported */
SENSOR_TYPE_MAGNETIC_FIELD = (1 << 1),
/* Gyroscope supported */
SENSOR_TYPE_GYROSCOPE = (1 << 2),
/* Light supported */
SENSOR_TYPE_LIGHT = (1 << 3),
/* Temperature supported */
SENSOR_TYPE_TEMPERATURE = (1 << 4),
....
SENSOR_TYPE_USER_DEFINED_6 = (1 << 31),
/* A selector, describes all sensors */
SENSOR_TYPE_ALL = 0xFFFFFFFF
} sensor_type_t;
Sensor Interface¶
The struct sensor_itf
data structure represents the interface the
sensor device driver uses to communicate with the sensor device.
struct sensor_itf {
/* Sensor interface type */
uint8_t si_type;
/* Sensor interface number */
uint8_t si_num;
/* Sensor CS pin */
uint8_t si_cs_pin;
/* Sensor address */
uint16_t si_addr;
};
The si_cs_pin
specifies the chip select pin and is optional. The
si_type
field must be of the following types:
#define SENSOR_ITF_SPI (0)
#define SENSOR_ITF_I2C (1)
#define SENSOR_ITF_UART (2)
Sensor Value Type¶
The struct sensor_cfg
data structure represents the configuration
sensor type:
/**
* Configuration structure, describing a specific sensor type off of
* an existing sensor.
*/
struct sensor_cfg {
/* The value type for this sensor (e.g. SENSOR_VALUE_TYPE_INT32).
* Used to describe the result format for the value corresponding
* to a specific sensor type.
*/
uint8_t sc_valtype;
/* Reserved for future usage */
uint8_t _reserved[3];
};
Only the sc_valtype
field is currently used and specifies the data
value type of the sensor data. The valid value types are:
/**
* Opaque 32-bit value, must understand underlying sensor type
* format in order to interpret.
*/
#define SENSOR_VALUE_TYPE_OPAQUE (0)
/**
* 32-bit signed integer
*/
#define SENSOR_VALUE_TYPE_INT32 (1)
/**
* 32-bit floating point
*/
#define SENSOR_VALUE_TYPE_FLOAT (2)
/**
* 32-bit integer triplet.
*/
#define SENSOR_VALUE_TYPE_INT32_TRIPLET (3)
/**
* 32-bit floating point number triplet.
*/
#define SENSOR_VALUE_TYPE_FLOAT_TRIPLET (4)
Sensor Driver Functions¶
The struct sensor_device
data structure represents the device driver
functions. The sensor device driver must implement the functions and set
up the function pointers.
struct sensor_driver {
sensor_read_func_t sd_read;
sensor_get_config_func_t sd_get_config;
};
API¶
-
enum
sensor_type_t
¶ Values:
-
enumerator
SENSOR_TYPE_NONE
¶
-
enumerator
SENSOR_TYPE_ACCELEROMETER
¶
-
enumerator
SENSOR_TYPE_MAGNETIC_FIELD
¶
-
enumerator
SENSOR_TYPE_GYROSCOPE
¶
-
enumerator
SENSOR_TYPE_LIGHT
¶
-
enumerator
SENSOR_TYPE_TEMPERATURE
¶
-
enumerator
SENSOR_TYPE_AMBIENT_TEMPERATURE
¶
-
enumerator
SENSOR_TYPE_PRESSURE
¶
-
enumerator
SENSOR_TYPE_PROXIMITY
¶
-
enumerator
SENSOR_TYPE_RELATIVE_HUMIDITY
¶
-
enumerator
SENSOR_TYPE_ROTATION_VECTOR
¶
-
enumerator
SENSOR_TYPE_ALTITUDE
¶
-
enumerator
SENSOR_TYPE_WEIGHT
¶
-
enumerator
SENSOR_TYPE_LINEAR_ACCEL
¶
-
enumerator
SENSOR_TYPE_GRAVITY
¶
-
enumerator
SENSOR_TYPE_EULER
¶
-
enumerator
SENSOR_TYPE_COLOR
¶
-
enumerator
SENSOR_TYPE_USER_DEFINED_1
¶
-
enumerator
SENSOR_TYPE_USER_DEFINED_2
¶
-
enumerator
SENSOR_TYPE_USER_DEFINED_3
¶
-
enumerator
SENSOR_TYPE_USER_DEFINED_4
¶
-
enumerator
SENSOR_TYPE_USER_DEFINED_5
¶
-
enumerator
SENSOR_TYPE_USER_DEFINED_6
¶
-
enumerator
SENSOR_TYPE_ALL
¶
-
enumerator
-
enum
sensor_event_type_t
¶ Values:
-
enumerator
SENSOR_EVENT_TYPE_DOUBLE_TAP
¶
-
enumerator
SENSOR_EVENT_TYPE_SINGLE_TAP
¶
-
enumerator
SENSOR_EVENT_TYPE_FREE_FALL
¶
-
enumerator
SENSOR_EVENT_TYPE_SLEEP_CHANGE
¶
-
enumerator
SENSOR_EVENT_TYPE_WAKEUP
¶
-
enumerator
SENSOR_EVENT_TYPE_SLEEP
¶
-
enumerator
SENSOR_EVENT_TYPE_ORIENT_CHANGE
¶
-
enumerator
SENSOR_EVENT_TYPE_ORIENT_X_CHANGE
¶
-
enumerator
SENSOR_EVENT_TYPE_ORIENT_Y_CHANGE
¶
-
enumerator
SENSOR_EVENT_TYPE_ORIENT_Z_CHANGE
¶
-
enumerator
SENSOR_EVENT_TYPE_ORIENT_X_L_CHANGE
¶
-
enumerator
SENSOR_EVENT_TYPE_ORIENT_Y_L_CHANGE
¶
-
enumerator
SENSOR_EVENT_TYPE_ORIENT_Z_L_CHANGE
¶
-
enumerator
SENSOR_EVENT_TYPE_ORIENT_X_H_CHANGE
¶
-
enumerator
SENSOR_EVENT_TYPE_ORIENT_Y_H_CHANGE
¶
-
enumerator
SENSOR_EVENT_TYPE_ORIENT_Z_H_CHANGE
¶
-
enumerator
-
typedef int (*
sensor_data_func_t
)(struct sensor*, void*, void*, sensor_type_t)¶ Callback for handling sensor data, specified in a sensor listener.
- Return
0 on success, non-zero error code on failure.
- Parameters
sensor
: The sensor for which data is being returnedarg
: The argument provided to sensor_read() function.data
: A single sensor reading for that sensor listenertype
: The sensor type for the data function
-
typedef int (*
sensor_trigger_notify_func_t
)(struct sensor*, void*, sensor_type_t)¶ Callback for sending trigger notification.
- Parameters
sensor
: Ptr to the sensordata
: Ptr to sensor datatype
: The sensor type
-
typedef int (*
sensor_trigger_cmp_func_t
)(sensor_type_t, sensor_data_t*, sensor_data_t*, void*)¶ Callback for trigger compare functions.
- Parameters
type
: Type of sensorlow_thresh
: The sensor low thresholdhigh_thresh
: The sensor high thresholdarg
: Ptr to data
-
typedef int (*
sensor_notifier_func_t
)(struct sensor*, void*, sensor_event_type_t)¶ Callback for event notifications.
- Parameters
sensor
: The sensor that observed the eventarg
: The opaque argument provided during registrationevent
: The sensor event type that was observed
-
typedef void (*
sensor_error_func_t
)(struct sensor *sensor, void *arg, int status)¶ Callback for reporting a sensor read error.
- Parameters
sensor
: The sensor for which a read failed.arg
: The optional argument registered with the callback.status
: Indicates the cause of the read failure. Determined by the underlying sensor driver.
-
typedef int (*
sensor_read_func_t
)(struct sensor*, sensor_type_t, sensor_data_func_t, void*, uint32_t)¶ Read a single value from a sensor, given a specific sensor type (e.g.
SENSOR_TYPE_PROXIMITY).
- Return
0 on success, non-zero error code on failure.
- Parameters
sensor
: The sensor to read fromtype
: The type(s) of sensor values to read. Mask containing that type, provide all, to get all values.data_func
: The function to call with each value read. If NULL, it calls all sensor listeners associated with this function.arg
: The argument to pass to the read callback.timeout
: Timeout. If block until result, specify OS_TIMEOUT_NEVER, 0 returns immediately (no wait.)
-
typedef int (*
sensor_get_config_func_t
)(struct sensor*, sensor_type_t, struct sensor_cfg*)¶ Get the configuration of the sensor for the sensor type.
This includes the value type of the sensor.
- Return
0 on success, non-zero error code on failure.
- Parameters
sensor
: Ptr to the sensortype
: The type of sensor value to get configuration forcfg
: A pointer to the sensor value to place the returned result into.
-
typedef int (*
sensor_set_config_func_t
)(struct sensor*, void*)¶ Send a new configuration register set to the sensor.
- Return
0 on success, non-zero error code on failure.
- Parameters
sensor
: Ptr to the sensor-specific stucturearg
: Ptr to the sensor-specific configuration structure
-
typedef int (*
sensor_set_trigger_thresh_t
)(struct sensor*, sensor_type_t, struct sensor_type_traits *stt)¶ Set the trigger and threshold values for a specific sensor for the sensor type.
- Return
0 on success, non-zero error code on failure.
- Parameters
sensor
: Ptr to the sensortype
: type of sensorstt
: Ptr to teh sensor traits
-
typedef int (*
sensor_clear_trigger_thresh_t
)(struct sensor *sensor, sensor_type_t type)¶ Clear the high/low threshold values for a specific sensor for the sensor type.
- Return
0 on success, non-zero error code on failure.
- Parameters
sensor
: Ptr to the sensortype
: Type of sensor
-
typedef int (*
sensor_set_notification_t
)(struct sensor*, sensor_event_type_t)¶ Set the notification expectation for a targeted set of events for the specific sensor.
After this function returns successfully, the implementer shall post corresponding event notifications to the sensor manager.
- Return
0 on success, non-zero error code on failure.
- Parameters
sensor
: The sensor to expect notifications from.event
: The mask of event types to expect notifications from.
-
typedef int (*
sensor_unset_notification_t
)(struct sensor*, sensor_event_type_t)¶ Unset the notification expectation for a targeted set of events for the specific sensor.
- Return
0 on success, non-zero error code on failure.
- Parameters
sensor
: The sensor.event
: The mask of event types.
-
typedef int (*
sensor_handle_interrupt_t
)(struct sensor *sensor)¶ Let driver handle interrupt in the sensor context.
- Return
0 on success, non-zero error code on failure.
- Parameters
sensor
: Ptr to the sensor
-
typedef int (*
sensor_reset_t
)(struct sensor*)¶ Reset Sensor function Ptr.
- Return
0 on success, non-zero on failure
- Parameters
Ptr
: to the sensor
-
void
sensor_pkg_init
(void)¶ Package init function.
Remove when we have post-kernel init stages.
-
int
sensor_itf_lock
(struct sensor_itf *si, os_time_t timeout)¶ Lock access to the sensor_itf specified by si.
Blocks until lock acquired.
- Return
0 on success, non-zero on failure.
- Parameters
si
: The sensor_itf to locktimeout
: The timeout
-
void
sensor_itf_unlock
(struct sensor_itf *si)¶ Unlock access to the sensor_itf specified by si.
- Return
0 on success, non-zero on failure.
- Parameters
si
: The sensor_itf to unlock access to
-
int
sensor_init
(struct sensor *sensor, struct os_dev *dev)¶ Initialize a sensor.
- Return
0 on success, non-zero error code on failure.
- Parameters
sensor
: The sensor to initializedev
: The device to associate with this sensor.
-
int
sensor_lock
(struct sensor *sensor)¶ Lock access to the sensor specified by sensor.
Blocks until lock acquired.
- Return
0 on success, non-zero on failure.
- Parameters
sensor
: The sensor to lock
-
void
sensor_unlock
(struct sensor *sensor)¶ Unlock access to the sensor specified by sensor.
- Parameters
sensor
: The sensor to unlock access to.
-
int
sensor_read
(struct sensor *sensor, sensor_type_t type, sensor_data_func_t data_func, void *arg, uint32_t timeout)¶ Read the data for sensor type “type,” from the given sensor and return the result into the “value” parameter.
- Return
0 on success, non-zero on failure.
- Parameters
sensor
: The sensor to read data fromtype
: The type of sensor data to read from the sensordata_func
: The callback to call for data returned from that sensorarg
: The argument to pass to this callback.timeout
: Timeout before aborting sensor read
-
static inline int
sensor_set_driver
(struct sensor *sensor, sensor_type_t type, struct sensor_driver *driver)¶ Set the driver functions for this sensor, along with the type of sensor data available for the given sensor.
- Return
0 on success, non-zero error code on failure
- Parameters
sensor
: The sensor to set the driver information fortype
: The types of sensor data available for this sensordriver
: The driver functions for this sensor
-
static inline int
sensor_set_type_mask
(struct sensor *sensor, sensor_type_t mask)¶ Set the sensor driver mask so that the developer who configures the sensor tells the sensor framework which sensor data to send back to the user.
- Parameters
sensor
: The sensor to set the mask formask
: The mask
-
static inline sensor_type_t
sensor_check_type
(struct sensor *sensor, sensor_type_t type)¶ Check if sensor type is supported by the sensor device.
- Return
type bitfield, if supported, 0 if not supported
- Parameters
sensor
: The sensor objecttype
: Type to be checked
-
static inline int
sensor_set_interface
(struct sensor *sensor, struct sensor_itf *s_itf)¶ Set interface type and number.
- Parameters
sensor
: The sensor to set the interface fors_itf
: The interface type to set
-
static inline int
sensor_get_config
(struct sensor *sensor, sensor_type_t type, struct sensor_cfg *cfg)¶ Read the configuration for the sensor type “type,” and return the configuration into “cfg.”.
- Return
0 on success, non-zero error code on failure.
- Parameters
sensor
: The sensor to read configuration fortype
: The type of sensor configuration to readcfg
: The configuration structure to point to.
-
SENSOR_VALUE_TYPE_OPAQUE
¶ Opaque 32-bit value, must understand underlying sensor type format in order to interpret.
-
SENSOR_VALUE_TYPE_INT32
¶ 32-bit signed integer
-
SENSOR_VALUE_TYPE_FLOAT
¶ 32-bit floating point
-
SENSOR_VALUE_TYPE_INT32_TRIPLET
¶ 32-bit integer triplet.
-
SENSOR_VALUE_TYPE_FLOAT_TRIPLET
¶ 32-bit floating point number triplet.
-
SENSOR_ITF_SPI
¶ Sensor interfaces.
-
SENSOR_ITF_I2C
¶
-
SENSOR_ITF_UART
¶
-
SENSOR_THRESH_ALGO_WINDOW
¶ Sensor threshold constants.
-
SENSOR_THRESH_ALGO_WATERMARK
¶
-
SENSOR_THRESH_ALGO_USERDEF
¶
-
SENSOR_IGN_LISTENER
¶ Sensor listener constants.
-
STANDARD_ACCEL_GRAVITY
¶ Useful constants.
-
SENSOR_GET_DEVICE
(__s)¶
-
SENSOR_GET_ITF
(__s)¶
-
SENSOR_DATA_CMP_GT
(__d, __t, __f)¶
-
SENSOR_DATA_CMP_LT
(__d, __t, __f)¶
-
struct
sensor_cfg
¶ - #include <sensor.h>
Configuration structure, describing a specific sensor type off of an existing sensor.
-
union
sensor_data_t
¶ - #include <sensor.h>
Public Members
-
struct sensor_mag_data *
smd
¶
-
struct sensor_accel_data *
sad
¶
-
struct sensor_euler_data *
sed
¶
-
struct sensor_quat_data *
sqd
¶
-
struct sensor_accel_data *
slad
¶
-
struct sensor_accel_data *
sgrd
¶
-
struct sensor_gyro_data *
sgd
¶
-
struct sensor_temp_data *
std
¶
-
struct sensor_temp_data *
satd
¶
-
struct sensor_light_data *
sld
¶
-
struct sensor_color_data *
scd
¶
-
struct sensor_press_data *
spd
¶
-
struct sensor_humid_data *
srhd
¶
-
struct sensor_mag_data *
-
struct
sensor_listener
¶ - #include <sensor.h>
-
struct
sensor_notifier
¶ - #include <sensor.h>
Registration for sensor event notifications.
-
struct
sensor_read_ev_ctx
¶ - #include <sensor.h>
Context for sensor read events.
-
struct
sensor_type_traits
¶ - #include <sensor.h>
Sensor type traits list.
-
struct
sensor_notify_ev_ctx
¶ - #include <sensor.h>
-
struct
sensor_notify_os_ev
¶ - #include <sensor.h>
-
struct
sensor_driver
¶ - #include <sensor.h>
-
struct
sensor_timestamp
¶ - #include <sensor.h>
-
struct
sensor_int
¶ - #include <sensor.h>
-
struct
sensor_itf
¶ - #include <sensor.h>
-
struct
sensor
¶ - #include <sensor.h>
Public Members
-
uint32_t
s_poll_rate
¶ Poll rate in MS for this sensor.
-
uint32_t
-
struct
sensor_read_ctx
¶ - #include <sensor.h>
Read context for calling user function with argument.