Zephyr API Documentation 4.2.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches

High-level sensor framework. More...

Topics

 Data Types
 Sensor data structures used by the sensing subsystem.
 Sensor Types (Sensing)
 Sensor type identifiers used by the sensing subsystem.
 Sensors (Sensing)
 Interfaces to manipulate sensors in the sensing subsystem.

Data Structures

struct  sensing_sensor_version
 Sensor Version. More...
struct  sensing_sensor_info
 Read-only description of a sensor instance. More...
struct  sensing_callback_list
 Callback registration for a sensor instance. More...
struct  sensing_sensor_config
 Sensing subsystem sensor configure, including interval, sensitivity, latency. More...

Macros

#define SENSING_SENSOR_VERSION(_major, _minor, _hotfix, _build)
 Build a packed sensing_sensor_version value.
#define SENSING_SENSITIVITY_INDEX_ALL   -1
 Sentinel index meaning "apply to all data fields".

Typedefs

typedef void * sensing_sensor_handle_t
 Opaque handle to an opened sensor instance.
typedef void(* sensing_data_event_t) (sensing_sensor_handle_t handle, const void *buf, void *context)
 Data event callback signature.

Enumerations

enum  sensing_sensor_state { SENSING_SENSOR_STATE_READY = 0 , SENSING_SENSOR_STATE_OFFLINE = 1 }
 Sensor state. More...
enum  sensing_sensor_attribute { SENSING_SENSOR_ATTRIBUTE_INTERVAL = 0 , SENSING_SENSOR_ATTRIBUTE_SENSITIVITY = 1 , SENSING_SENSOR_ATTRIBUTE_LATENCY = 2 , SENSING_SENSOR_ATTRIBUTE_MAX }
 Sensor configuration attribute. More...

Functions

int sensing_get_sensors (int *num_sensors, const struct sensing_sensor_info **info)
 Get all supported sensor instances' information.
int sensing_open_sensor (const struct sensing_sensor_info *info, struct sensing_callback_list *cb_list, sensing_sensor_handle_t *handle)
 Open sensor instance by sensing sensor info.
int sensing_open_sensor_by_dt (const struct device *dev, struct sensing_callback_list *cb_list, sensing_sensor_handle_t *handle)
 Open sensor instance by device.
int sensing_close_sensor (sensing_sensor_handle_t *handle)
 Close sensor instance.
int sensing_set_config (sensing_sensor_handle_t handle, struct sensing_sensor_config *configs, int count)
 Set current config items to Sensing subsystem.
int sensing_get_config (sensing_sensor_handle_t handle, struct sensing_sensor_config *configs, int count)
 Get current config items from Sensing subsystem.
const struct sensing_sensor_infosensing_get_sensor_info (sensing_sensor_handle_t handle)
 Get sensor information from sensor instance handle.

Sensor reporting flags

#define SENSING_SENSOR_FLAG_REPORT_ON_EVENT   BIT(0)
 Sensor flag indicating if this sensor is reporting data on event.
#define SENSING_SENSOR_FLAG_REPORT_ON_CHANGE   BIT(1)
 Sensor flag indicating if this sensor is reporting data on change.

Detailed Description

High-level sensor framework.

The Sensing subsystem provides a high-level API for applications to discover sensors, open sensor instances, configure reporting behavior, and receive sampled data via callbacks. For low-level sensor access, see Sensor Interface.

Macro Definition Documentation

◆ SENSING_SENSITIVITY_INDEX_ALL

#define SENSING_SENSITIVITY_INDEX_ALL   -1

#include <zephyr/sensing/sensing.h>

Sentinel index meaning "apply to all data fields".

Used with sensitivity configuration where a sensor provides multiple fields in a single sample.

◆ SENSING_SENSOR_FLAG_REPORT_ON_CHANGE

#define SENSING_SENSOR_FLAG_REPORT_ON_CHANGE   BIT(1)

#include <zephyr/sensing/sensing.h>

Sensor flag indicating if this sensor is reporting data on change.

Reporting sensor data when the sensor data changes.

Note
Mutually exclusive with SENSING_SENSOR_FLAG_REPORT_ON_EVENT

◆ SENSING_SENSOR_FLAG_REPORT_ON_EVENT

#define SENSING_SENSOR_FLAG_REPORT_ON_EVENT   BIT(0)

#include <zephyr/sensing/sensing.h>

Sensor flag indicating if this sensor is reporting data on event.

Reporting sensor data when the sensor event occurs, such as a motion detect sensor reporting a motion or motionless detected event.

Note
Mutually exclusive with SENSING_SENSOR_FLAG_REPORT_ON_CHANGE

◆ SENSING_SENSOR_VERSION

#define SENSING_SENSOR_VERSION ( _major,
_minor,
_hotfix,
_build )

#include <zephyr/sensing/sensing.h>

Value:
(FIELD_PREP(GENMASK(31, 24), _major) | \
FIELD_PREP(GENMASK(23, 16), _minor) | \
FIELD_PREP(GENMASK(15, 8), _hotfix) | \
FIELD_PREP(GENMASK(7, 0), _build))
#define GENMASK(h, l)
Create a contiguous bitmask starting at bit position l and ending at position h.
Definition util.h:80
#define FIELD_PREP(mask, value)
Definition silabs-pinctrl-siwx91x.h:15

Build a packed sensing_sensor_version value.

Parameters
_majorMajor version.
_minorMinor version.
_hotfixHotfix version.
_buildBuild number.
Returns
32-bit packed version value

Typedef Documentation

◆ sensing_data_event_t

typedef void(* sensing_data_event_t) (sensing_sensor_handle_t handle, const void *buf, void *context)

#include <zephyr/sensing/sensing.h>

Data event callback signature.

The Sensing subsystem invokes this callback to deliver buffered samples for the opened sensor.

Parameters
handleSensor instance handle passed to sensing_open_sensor.
bufPointer to a sensor-type-specific sample buffer; see Data Types and Sensor Types (Sensing).
contextUser context pointer as provided in sensing_callback_list::context.

◆ sensing_sensor_handle_t

typedef void* sensing_sensor_handle_t

#include <zephyr/sensing/sensing.h>

Opaque handle to an opened sensor instance.

A valid handle is obtained from sensing_open_sensor or sensing_open_sensor_by_dt and must be closed with sensing_close_sensor when no longer needed.

Enumeration Type Documentation

◆ sensing_sensor_attribute

#include <zephyr/sensing/sensing.h>

Sensor configuration attribute.

This enumeration defines the possible attributes of a sensor configuration.

Enumerator
SENSING_SENSOR_ATTRIBUTE_INTERVAL 

Reporting interval between samples, in microseconds (us).

See sensing_sensor_config::interval.

SENSING_SENSOR_ATTRIBUTE_SENSITIVITY 

Per-field sensitivity threshold.

See sensing_sensor_config::sensitivity.

SENSING_SENSOR_ATTRIBUTE_LATENCY 

Maximum batching latency, in microseconds (us).

See sensing_sensor_config::latency.

SENSING_SENSOR_ATTRIBUTE_MAX 

Number of supported attributes.

◆ sensing_sensor_state

#include <zephyr/sensing/sensing.h>

Sensor state.

This enumeration defines the possible states of a sensor.

Enumerator
SENSING_SENSOR_STATE_READY 

The sensor is ready.

SENSING_SENSOR_STATE_OFFLINE 

The sensor is offline.

Function Documentation

◆ sensing_close_sensor()

int sensing_close_sensor ( sensing_sensor_handle_t * handle)

#include <zephyr/sensing/sensing.h>

Close sensor instance.

Parameters
handleThe sensor instance handle need to close.
Returns
0 on success or negative error value on failure.

◆ sensing_get_config()

int sensing_get_config ( sensing_sensor_handle_t handle,
struct sensing_sensor_config * configs,
int count )

#include <zephyr/sensing/sensing.h>

Get current config items from Sensing subsystem.

Parameters
handleThe sensor instance handle.
configsThe configs to be get according to config attribute.
countcount of configs.
Returns
0 on success or negative error value on failure, not support etc.

◆ sensing_get_sensor_info()

const struct sensing_sensor_info * sensing_get_sensor_info ( sensing_sensor_handle_t handle)

#include <zephyr/sensing/sensing.h>

Get sensor information from sensor instance handle.

Parameters
handleThe sensor instance handle.
Returns
a const pointer to sensing_sensor_info on success or NULL on failure.

◆ sensing_get_sensors()

int sensing_get_sensors ( int * num_sensors,
const struct sensing_sensor_info ** info )

#include <zephyr/sensing/sensing.h>

Get all supported sensor instances' information.

This API just returns read only information of sensor instances, pointer info will directly point to internal buffer, no need for caller to allocate buffer, no side effect to sensor instances.

Parameters
num_sensorsGet number of sensor instances.
infoFor receiving sensor instances' information array pointer.
Returns
0 on success or negative error value on failure.

◆ sensing_open_sensor()

int sensing_open_sensor ( const struct sensing_sensor_info * info,
struct sensing_callback_list * cb_list,
sensing_sensor_handle_t * handle )

#include <zephyr/sensing/sensing.h>

Open sensor instance by sensing sensor info.

Application clients use it to open a sensor instance and get its handle. Support multiple Application clients for open same sensor instance, in this case, the returned handle will different for different clients. meanwhile, also register sensing callback list

Parameters
infoThe sensor info got from sensing_get_sensors
cb_listcallback list to be registered to sensing, must have a static lifetime.
handleThe opened instance handle, if failed will be set to NULL.
Returns
0 on success or negative error value on failure.

◆ sensing_open_sensor_by_dt()

int sensing_open_sensor_by_dt ( const struct device * dev,
struct sensing_callback_list * cb_list,
sensing_sensor_handle_t * handle )

#include <zephyr/sensing/sensing.h>

Open sensor instance by device.

Application clients use it to open a sensor instance and get its handle. Support multiple Application clients for open same sensor instance, in this case, the returned handle will different for different clients. meanwhile, also register sensing callback list.

Parameters
devpointer device get from device tree.
cb_listcallback list to be registered to sensing, must have a static lifetime.
handleThe opened instance handle, if failed will be set to NULL.
Returns
0 on success or negative error value on failure.

◆ sensing_set_config()

int sensing_set_config ( sensing_sensor_handle_t handle,
struct sensing_sensor_config * configs,
int count )

#include <zephyr/sensing/sensing.h>

Set current config items to Sensing subsystem.

Parameters
handleThe sensor instance handle.
configsThe configs to be set according to config attribute.
countcount of configs.
Returns
0 on success or negative error value on failure, not support etc.