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_VOLTAGE¶

enumerator SENSOR_TYPE_CURRENT¶

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¶

enumerator SENSOR_EVENT_TYPE_TILT_CHANGE¶

enumerator SENSOR_EVENT_TYPE_TILT_POS¶

enumerator SENSOR_EVENT_TYPE_TILT_NEG¶

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

si: The sensor_itf to lock
timeout: 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 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.

An OS to build, deploy and securely manage billions of devices

Latest News:

Sensor API¶

Sensor API Functions Used by a Sensor Device Driver Package¶

Initializing a Sensor Object¶

Setting the Configured Sensor Types¶

Sensor API Functions Used By an Application¶

Reading Sensor Data¶

Setting a Poll Rate for A Sensor¶

Data Structures¶

Sensor Object¶

Sensor Types¶

Sensor Interface¶

Sensor Value Type¶

Sensor Driver Functions¶

API¶