Sensing

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_info *	sensing_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.

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))

Build a packed sensing_sensor_version value.

Parameters

_major	Major version.
_minor	Minor version.
_hotfix	Hotfix version.
_build	Build 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

handle	Sensor instance handle passed to sensing_open_sensor.
buf	Pointer to a sensor-type-specific sample buffer; see Data Types and Sensor Types (Sensing).
context	User 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

enum 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

enum 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

handle

The 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

handle	The sensor instance handle.
configs	The configs to be get according to config attribute.
count	count 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

handle

The 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_sensors	Get number of sensor instances.
info	For 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

info	The sensor info got from sensing_get_sensors
cb_list	callback list to be registered to sensing, must have a static lifetime.
handle	The 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

dev	pointer device get from device tree.
cb_list	callback list to be registered to sensing, must have a static lifetime.
handle	The 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

handle	The sensor instance handle.
configs	The configs to be set according to config attribute.
count	count of configs.

Returns

0 on success or negative error value on failure, not support etc.