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