1 /* 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 struct sensing_sensor_version { 40 union { 41 uint32_t value; /**< The version represented as a 32-bit value. */ 42 struct { 43 uint8_t major; /**< The major version number. */ 44 uint8_t minor; /**< The minor version number. */ 45 uint8_t hotfix; /**< The hotfix version number. */ 46 uint8_t build; /**< The build version number. */ 47 }; 48 }; 49 }; 50 51 /** 52 * @brief Macro to create a sensor version value. 53 * 54 */ 55 #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 #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 #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 #define SENSING_SENSITIVITY_INDEX_ALL -1 84 85 /** 86 * @brief Sensing subsystem sensor state. 87 * 88 */ 89 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 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 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 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 struct sensing_sensor_info { 133 /** Name of the sensor instance */ 134 const char *name; 135 136 /** Friendly name of the sensor instance */ 137 const char *friendly_name; 138 139 /** Vendor name of the sensor instance */ 140 const char *vendor; 141 142 /** Model name of the sensor instance */ 143 const char *model; 144 145 /** Sensor type */ 146 const int32_t type; 147 148 /** Minimal report interval in micro seconds */ 149 const uint32_t minimal_interval; 150 }; 151 152 /** 153 * @struct sensing_callback_list 154 * @brief Sensing subsystem event callback list 155 * 156 */ 157 struct sensing_callback_list { 158 sensing_data_event_t on_data_event; /**< Callback function for a sensor data event. */ 159 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 struct sensing_sensor_config { 168 enum sensing_sensor_attribute attri; /**< Attribute of the sensor configuration. */ 169 170 /** \ref SENSING_SENSITIVITY_INDEX_ALL */ 171 int8_t data_field; /**< Data field of the sensor configuration. */ 172 173 union { 174 /** Interval between two sensor samples in microseconds (us). */ 175 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 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 uint64_t latency; 190 }; 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 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 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 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 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 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 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 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_*/ 294
