Line data Source code
1 0 : /*
2 : * Copyright (c) 2022-2023 Intel Corporation.
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : #ifndef ZEPHYR_INCLUDE_SENSING_H_
8 : #define ZEPHYR_INCLUDE_SENSING_H_
9 :
10 : /**
11 : * @defgroup sensing_api Sensing
12 : * @brief High-level sensor framework.
13 : * @ingroup os_services
14 : *
15 : * The Sensing subsystem provides a high-level API for applications to discover sensors, open sensor
16 : * instances, configure reporting behavior, and receive sampled data via callbacks.
17 : * For low-level sensor access, see @ref sensor_interface.
18 : *
19 : * @{
20 : */
21 :
22 : #include <zephyr/sensing/sensing_datatypes.h>
23 : #include <zephyr/sensing/sensing_sensor_types.h>
24 : #include <zephyr/device.h>
25 :
26 : #ifdef __cplusplus
27 : extern "C" {
28 : #endif
29 :
30 : /**
31 : * @brief Sensor Version
32 : */
33 1 : struct sensing_sensor_version {
34 : union {
35 1 : uint32_t value; /**< The version represented as a 32-bit value. */
36 : struct {
37 1 : uint8_t major; /**< The major version number. */
38 1 : uint8_t minor; /**< The minor version number. */
39 1 : uint8_t hotfix; /**< The hotfix version number. */
40 1 : uint8_t build; /**< The build version number. */
41 : };
42 0 : };
43 : };
44 :
45 : /**
46 : * @brief Build a packed @ref sensing_sensor_version value.
47 : *
48 : * @param _major Major version.
49 : * @param _minor Minor version.
50 : * @param _hotfix Hotfix version.
51 : * @param _build Build number.
52 : * @return 32-bit packed version value
53 : */
54 1 : #define SENSING_SENSOR_VERSION(_major, _minor, _hotfix, _build) \
55 : (FIELD_PREP(GENMASK(31, 24), _major) | \
56 : FIELD_PREP(GENMASK(23, 16), _minor) | \
57 : FIELD_PREP(GENMASK(15, 8), _hotfix) | \
58 : FIELD_PREP(GENMASK(7, 0), _build))
59 :
60 : /**
61 : * @name Sensor reporting flags
62 : * @{
63 : */
64 :
65 : /**
66 : * @brief Sensor flag indicating if this sensor is reporting data on event.
67 : *
68 : * Reporting sensor data when the sensor event occurs, such as a motion detect sensor reporting
69 : * a motion or motionless detected event.
70 : *
71 : * @note Mutually exclusive with \ref SENSING_SENSOR_FLAG_REPORT_ON_CHANGE
72 : */
73 1 : #define SENSING_SENSOR_FLAG_REPORT_ON_EVENT BIT(0)
74 :
75 : /**
76 : * @brief Sensor flag indicating if this sensor is reporting data on change.
77 : *
78 : * Reporting sensor data when the sensor data changes.
79 : *
80 : * @note Mutually exclusive with \ref SENSING_SENSOR_FLAG_REPORT_ON_EVENT
81 : */
82 1 : #define SENSING_SENSOR_FLAG_REPORT_ON_CHANGE BIT(1)
83 :
84 : /** @} */
85 :
86 : /**
87 : * @brief Sentinel index meaning "apply to all data fields".
88 : *
89 : * Used with sensitivity configuration where a sensor provides multiple fields in a single sample.
90 : */
91 1 : #define SENSING_SENSITIVITY_INDEX_ALL -1
92 :
93 : /**
94 : * @brief Sensor state.
95 : *
96 : * This enumeration defines the possible states of a sensor.
97 : */
98 1 : enum sensing_sensor_state {
99 : SENSING_SENSOR_STATE_READY = 0, /**< The sensor is ready. */
100 : SENSING_SENSOR_STATE_OFFLINE = 1, /**< The sensor is offline. */
101 : };
102 :
103 : /**
104 : * @brief Sensor configuration attribute.
105 : *
106 : * This enumeration defines the possible attributes of a sensor configuration.
107 : */
108 1 : enum sensing_sensor_attribute {
109 : /**
110 : * Reporting interval between samples, in microseconds (us).
111 : *
112 : * See @ref sensing_sensor_config::interval.
113 : */
114 : SENSING_SENSOR_ATTRIBUTE_INTERVAL = 0,
115 :
116 : /**
117 : * Per-field sensitivity threshold.
118 : *
119 : * See @ref sensing_sensor_config::sensitivity.
120 : */
121 : SENSING_SENSOR_ATTRIBUTE_SENSITIVITY = 1,
122 :
123 : /**
124 : * Maximum batching latency, in microseconds (us).
125 : *
126 : * See @ref sensing_sensor_config::latency.
127 : */
128 : SENSING_SENSOR_ATTRIBUTE_LATENCY = 2,
129 :
130 : /** Number of supported attributes. */
131 : SENSING_SENSOR_ATTRIBUTE_MAX,
132 : };
133 :
134 : /**
135 : * @brief Opaque handle to an opened sensor instance.
136 : *
137 : * A valid handle is obtained from @ref sensing_open_sensor or @ref sensing_open_sensor_by_dt and
138 : * must be closed with @ref sensing_close_sensor when no longer needed.
139 : */
140 1 : typedef void *sensing_sensor_handle_t;
141 :
142 : /**
143 : * @brief Data event callback signature.
144 : *
145 : * The Sensing subsystem invokes this callback to deliver buffered samples for the opened sensor.
146 : *
147 : * @param handle Sensor instance handle passed to @ref sensing_open_sensor.
148 : * @param buf Pointer to a sensor-type-specific sample buffer; see @ref sensing_datatypes and
149 : * @ref sensing_sensor_types.
150 : * @param context User context pointer as provided in @ref sensing_callback_list::context.
151 : */
152 1 : typedef void (*sensing_data_event_t)(
153 : sensing_sensor_handle_t handle,
154 : const void *buf,
155 : void *context);
156 :
157 : /**
158 : * @brief Read-only description of a sensor instance.
159 : */
160 1 : struct sensing_sensor_info {
161 : /** Name of the sensor instance */
162 1 : const char *name;
163 :
164 : /** Friendly name of the sensor instance */
165 1 : const char *friendly_name;
166 :
167 : /** Vendor name of the sensor instance */
168 1 : const char *vendor;
169 :
170 : /** Model name of the sensor instance */
171 1 : const char *model;
172 :
173 : /** Sensor type */
174 1 : const int32_t type;
175 :
176 : /** Minimal report interval in micro seconds */
177 1 : const uint32_t minimal_interval;
178 : };
179 :
180 : /**
181 : * @struct sensing_callback_list
182 : * @brief Sensing subsystem event callback list
183 : *
184 : */
185 :
186 : /**
187 : * @brief Callback registration for a sensor instance.
188 : */
189 1 : struct sensing_callback_list {
190 1 : sensing_data_event_t on_data_event; /**< Callback function for a sensor data event. */
191 1 : void *context; /**< Context that will be passed to the callback. */
192 : };
193 :
194 : /**
195 : * @struct sensing_sensor_config
196 : * @brief Sensing subsystem sensor configure, including interval, sensitivity, latency
197 : *
198 : */
199 1 : struct sensing_sensor_config {
200 1 : enum sensing_sensor_attribute attri; /**< Attribute of the sensor configuration. */
201 :
202 : /** \ref SENSING_SENSITIVITY_INDEX_ALL */
203 1 : int8_t data_field; /**< Data field of the sensor configuration. */
204 :
205 : union {
206 : /** Interval between two sensor samples in microseconds (us). */
207 1 : uint32_t interval;
208 :
209 : /**
210 : * Sensitivity threshold for reporting new data. A new sensor sample is reported
211 : * only if the difference between it and the previous sample exceeds this
212 : * sensitivity value.
213 : */
214 1 : uint32_t sensitivity;
215 :
216 : /**
217 : * Maximum duration for batching sensor samples before reporting in
218 : * microseconds (us). This defines how long sensor samples can be
219 : * accumulated before they must be reported.
220 : */
221 1 : uint64_t latency;
222 0 : };
223 : };
224 :
225 : /**
226 : * @brief Get all supported sensor instances' information.
227 : *
228 : * This API just returns read only information of sensor instances, pointer info will
229 : * directly point to internal buffer, no need for caller to allocate buffer,
230 : * no side effect to sensor instances.
231 : *
232 : * @param num_sensors Get number of sensor instances.
233 : * @param info For receiving sensor instances' information array pointer.
234 : * @return 0 on success or negative error value on failure.
235 : */
236 1 : int sensing_get_sensors(int *num_sensors, const struct sensing_sensor_info **info);
237 :
238 : /**
239 : * @brief Open sensor instance by sensing sensor info
240 : *
241 : * Application clients use it to open a sensor instance and get its handle.
242 : * Support multiple Application clients for open same sensor instance,
243 : * in this case, the returned handle will different for different clients.
244 : * meanwhile, also register sensing callback list
245 : *
246 : * @param info The sensor info got from \ref sensing_get_sensors
247 : * @param cb_list callback list to be registered to sensing, must have a static
248 : * lifetime.
249 : * @param handle The opened instance handle, if failed will be set to NULL.
250 : * @return 0 on success or negative error value on failure.
251 : */
252 1 : int sensing_open_sensor(
253 : const struct sensing_sensor_info *info,
254 : struct sensing_callback_list *cb_list,
255 : sensing_sensor_handle_t *handle);
256 :
257 : /**
258 : * @brief Open sensor instance by device.
259 : *
260 : * Application clients use it to open a sensor instance and get its handle.
261 : * Support multiple Application clients for open same sensor instance,
262 : * in this case, the returned handle will different for different clients.
263 : * meanwhile, also register sensing callback list.
264 : *
265 : * @param dev pointer device get from device tree.
266 : * @param cb_list callback list to be registered to sensing, must have a static
267 : * lifetime.
268 : * @param handle The opened instance handle, if failed will be set to NULL.
269 : * @return 0 on success or negative error value on failure.
270 : */
271 1 : int sensing_open_sensor_by_dt(
272 : const struct device *dev, struct sensing_callback_list *cb_list,
273 : sensing_sensor_handle_t *handle);
274 :
275 : /**
276 : * @brief Close sensor instance.
277 : *
278 : * @param handle The sensor instance handle need to close.
279 : * @return 0 on success or negative error value on failure.
280 : */
281 1 : int sensing_close_sensor(
282 : sensing_sensor_handle_t *handle);
283 :
284 : /**
285 : * @brief Set current config items to Sensing subsystem.
286 : *
287 : * @param handle The sensor instance handle.
288 : * @param configs The configs to be set according to config attribute.
289 : * @param count count of configs.
290 : * @return 0 on success or negative error value on failure, not support etc.
291 : */
292 1 : int sensing_set_config(
293 : sensing_sensor_handle_t handle,
294 : struct sensing_sensor_config *configs, int count);
295 :
296 : /**
297 : * @brief Get current config items from Sensing subsystem.
298 : *
299 : * @param handle The sensor instance handle.
300 : * @param configs The configs to be get according to config attribute.
301 : * @param count count of configs.
302 : * @return 0 on success or negative error value on failure, not support etc.
303 : */
304 1 : int sensing_get_config(
305 : sensing_sensor_handle_t handle,
306 : struct sensing_sensor_config *configs, int count);
307 :
308 : /**
309 : * @brief Get sensor information from sensor instance handle.
310 : *
311 : * @param handle The sensor instance handle.
312 : * @return a const pointer to \ref sensing_sensor_info on success or NULL on failure.
313 : */
314 1 : const struct sensing_sensor_info *sensing_get_sensor_info(
315 : sensing_sensor_handle_t handle);
316 :
317 : #ifdef __cplusplus
318 : }
319 : #endif
320 :
321 : /**
322 : * @}
323 : */
324 :
325 : #endif /*ZEPHYR_INCLUDE_SENSING_H_*/
|
