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