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 the struct 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 the sensor_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
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
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 returned

  • arg: The argument provided to sensor_read() function.

  • data: A single sensor reading for that sensor listener

  • type: 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 sensor

  • data: Ptr to sensor data

  • type: 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 sensor

  • low_thresh: The sensor low threshold

  • high_thresh: The sensor high threshold

  • arg: 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 event

  • arg: The opaque argument provided during registration

  • event: 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 from

  • type: 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 sensor

  • type: The type of sensor value to get configuration for

  • cfg: 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 stucture

  • arg: 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 sensor

  • type: type of sensor

  • stt: 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 sensor

  • type: 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

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

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 initialize

  • dev: 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 from

  • type: The type of sensor data to read from the sensor

  • data_func: The callback to call for data returned from that sensor

  • arg: 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 for

  • type: The types of sensor data available for this sensor

  • driver: 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 for

  • mask: 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 object

  • type: 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 for

  • s_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 for

  • type: The type of sensor configuration to read

  • cfg: 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_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.

struct sensor_read_ctx
#include <sensor.h>

Read context for calling user function with argument.