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