1 /** 2 * @file hi_tsensor.h 3 * 4 * Copyright (c) 2020 HiSilicon (Shanghai) Technologies CO., LIMITED. 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 /** 19 * @defgroup iot_tsensor Tsensor 20 * @ingroup drivers 21 */ 22 23 #ifndef __HI_TSENSOR_H__ 24 #define __HI_TSENSOR_H__ 25 #include <hi_types_base.h> 26 27 #ifdef __cplusplus 28 extern "C" { 29 #endif 30 31 /** 32 * @ingroup iot_tsensor 33 * @brief Callback function of Tsensor interruption. CNcomment:Tsensor中断回调函数。CNend 34 * 35 * @par 描述: 36 * Callback function of Tsensor interruption. CNcomment:Tsensor回调函数。CNend 37 * 38 * @attention None 39 * @param data [IN] type #hi_s16，Parameter transfer of the callback function, indicating the temperature when the 40 * interrupt is reported.CNcomment:回调函数参数传递，表示中断上报时的温度值。CNend 41 * 42 * @retval None 43 * @par 依赖: 44 * @li hi_tsensor.h：Tsensor APIs.CNcomment:文件用于描述获取tsensor相关接口。CNend 45 * @see None 46 */ 47 typedef hi_void (*hi_tsensor_callback_func)(hi_s16); 48 49 /** 50 * @ingroup iot_tsensor 51 * 52 * Tsensor report mode.CNcomment:Tsensor上报模式。CNend 53 */ 54 typedef enum { 55 HI_TSENSOR_MODE_16_POINTS_SINGLE = 0, /**< Mode: 16 points single.CNcomment:模式：16点平均单次上报 CNend */ 56 HI_TSENSOR_MODE_16_POINTS_LOOP = 1, /**< Mode: 16 points loop.CNcomment:模式：16点平均循环上报 CNend */ 57 HI_TSENSOR_MODE_1_POINT_LOOP = 2, /**< Mode: 1 point loop.CNcomment:模式：单点循环上报 CNend */ 58 HI_TSENSOR_MODE_MAX, /**< Invalid input parameter, which cannot be used. 59 CNcomment:错误入参，不可使用 CNend */ 60 }hi_tsensor_mode; 61 62 #define HI_TSENSOR_INVALID_CODE 0xFFFF /* Tsensor 无效温度码，有效温度码为(0-255) */ 63 #define HI_TSENSOR_INVALID_TEMP (-1000) /* Tsensor 无效温度, 有效温度码为(-40-140) */ 64 65 /** 66 * @ingroup iot_tsensor 67 * @brief tsensor module start.CNcomment:tsensor模块启动。CNend 68 * 69 * @par 描述: 70 * tsensor module start.CNcomment:tsensor启动温度采集。CNend 71 * 72 * @attention Period is valid when mode = #HI_TSENSOR_MODE_16_POINTS_LOOP or HI_TSENSOR_MODE_1_POINT_LOOP. 73 * By default, the tsensor HI_TSENSOR_MODE_16_POINTS_SINGLE temperature collection mode is enabled for the 74 * Wi-Fi module. If this function is repeatedly called, the default mode used by the Wi-Fi module will be 75 * overwritten. If you want to use the tsensor module for other services, you can register the 76 * corresponding interrupt callback function in the service. 77 CNcomment:period仅当mode为HI_TSENSOR_MODE_16_POINTS_SINGLE有效, period范围: period * 31.25us > 16 * 192us; 78 WiFi模块默认启用tsensor HI_TSENSOR_MODE_16_POINTS_SINGLE温度采集模式，重复调用此函数会覆盖WiFi模块使 79 用的默认模式， 如要将tsensor模块用于其他业务，可直接在该业务内注册对应的中断回调函数。CNend 80 * 81 * @param mode [IN] type #hi_tsensor_mode，Mode of Tsensor temperature acquisition. 82 CNcomment:Tsensor温度采集模式。CNend 83 * @param period [IN] type #hi_u16，Acquisition period, it is the multiple of 2 ms. 84 CNcomment:温度自动检测周期，为32K时钟数。CNend 85 * 86 * @retval #0 Success. 87 * @retval #Other Failure. For details, see hi_errno.h. 88 * @par 依赖: 89 * @li hi_tsensor.h：for Tsensor APIs.CNcomment:文件用于描述tsensor相关接口。CNend 90 * @see None 91 */ 92 hi_u32 hi_tsensor_start(hi_tsensor_mode mode, hi_u16 period); 93 94 /** 95 * @ingroup iot_tsensor 96 * @brief Read temperature data.CNcomment:读取温度值。CNend 97 * 98 * @par 描述: 99 * Read temperature data.CNcomment:在启动tsensor温度采集后，读取温度值。CNend 100 * 101 * @attention None 102 * @param temperature [IN] type #hi_s16*，address wait to be writed the temperature value. 103 CNcomment:待写入温度值的地址。CNend 104 * 105 * @retval #0 Success. 106 * @retval #Other Failure. For details, see hi_errno.h. 107 * @par 依赖: 108 * @li hi_tsensor.h：for Tsensor APIs.CNcomment:文件用于描述tsensor相关接口。CNend 109 * @see None 110 */ 111 hi_u32 hi_tsensor_read_temperature(hi_s16* temperature); 112 113 /** 114 * @ingroup iot_tsensor 115 * @brief Tsensor module stop.CNcomment:停止tsensor温度采集。CNend 116 * 117 * @par 描述: 118 * Tsensor module stop.CNcomment:停止tsensor温度采集。CNend 119 * 120 * @attention By default, the tsensor function is enabled for the Wi-Fi module. If this function is invoked, the 121 * temperature threshold protection function of the Wi-Fi module registration will be affected. 122 CNcomment:WiFi模块默认启用tsensor，调用此函数将会影响WiFi本身注册的温度阈值保护等功能。CNend 123 * @param None 124 * 125 * @retval None 126 * @par 依赖: 127 * @li hi_tsensor.h：for Tsensor APIs.CNcomment:文件用于描述tsensor相关接口。CNend 128 * @see None 129 */ 130 hi_void hi_tsensor_stop(hi_void); 131 132 /** 133 * @ingroup iot_tsensor 134 * @brief Destroy Tsensor module.CNcomment:销毁tsensor模块。CNend 135 * 136 * @par 描述: 137 * On the basis of hi_tsensor_stop, this interface disables the reporting of tsensor interrupts and clears 138 * the callback functions registered by users.CNcomment:在hi_tsensor_stop的基础上，此接口同时禁用了 139 tsensor的中断上报，并清空用户注册的回调函数。CNend 140 * 141 * @attention After this API is called, if the interrupt callback function is used, you need to invoke the corresponding 142 * interface to set the interrupt function before starting the interrupt, and enable the interrupt reporting 143 * function.By default, the tsensor function is enabled for the Wi-Fi module. If this function is invoked, 144 * the temperature threshold protection function of the Wi-Fi module registration will be affected. 145 CNcomment:调用此接口后，对于使用中断回调的场景，在start之前，需再次调用相应接口设置中断函数，开启中断上报； 146 WiFi模块默认启用tsensor，调用此函数将会影响WiFi本身注册的温度阈值保护等功能。CNend 147 * 148 * @param None 149 * 150 * @retval None 151 * @par 依赖: 152 * @li hi_tsensor.h：for Tsensor APIs.CNcomment:文件用于描述tsensor相关接口。CNend 153 * @see None 154 */ 155 hi_void hi_tsensor_destroy(hi_void); 156 157 /** 158 * @ingroup iot_tsensor 159 * @brief Sets the temperature calibration.CNcomment:温度校准设置。CNend 160 * 161 * @par 描述: 162 * Sets the temperature calibration.CNcomment:温度校准设置。CNend 163 * 164 * @attention None 165 * @param trim_code [IN] type #hi_u8，Low 4bit valid. The corresponding temperature calibration values are 166 * as follows:CNcomment:低4bit有效，对应的温度校准值如下所示:CNend 167 * 0000 ―― 0.000 ℃ 168 * 0001 ―― 1.410 ℃ 169 * 0010 ―― 2.820 ℃ 170 * 0011 ―― 4.230 ℃ 171 * 0100 ―― 5.640 ℃ 172 * 0101 ―― 7.050 ℃ 173 * 0110 ―― 8.460 ℃ 174 * 0111 ―― 9.870 ℃ 175 * 1000 ―― 0.000℃ 176 * 1001 ―― -1.410 ℃ 177 * 1010 ―― -2.820 ℃ 178 * 1011 ―― -4.230 ℃ 179 * 1100 ―― -5.640 ℃ 180 * 1101 ―― -7.050 ℃ 181 * 1110 ―― -8.460 ℃ 182 * 1111 ―― -9.870 ℃ 183 * @param trim_sel [IN] type #hi_bool，0：The temp_trim of the Tsensor IP is directly loaded by the efuse. 184 CNcomment:选择Tsensor IP的temp_trim由efuse直接加载，CNend 185 * 1：The temp_trim of the Tsensor IP is configured by the register. 186 CNcomment:选择Tsensor IP的temp_trim由寄存器配置。CNend 187 * 188 * @retval None 189 * @par 依赖: 190 * @li hi_tsensor.h：for Tsensor APIs.CNcomment:文件用于描述tsensor相关接口。CNend 191 * @see None 192 */ 193 hi_void hi_tsensor_set_temp_trim(hi_u8 trim_code, hi_bool trim_sel); 194 195 /** 196 * @ingroup iot_tsensor 197 * @brief Converts the temperature code into a temperature value.CNcomment:温度码转换成温度值。CNend 198 * 199 * @par 描述: 200 * Converts the temperature code into a temperature value.CNcomment:将温度码转换成温度值。CNend 201 * 202 * @attention None 203 * @param code [IN] type #hi_u8，temperature value.CNcomment:温度码。CNend 204 * 205 * @retval #hi_s16 Valid temperature value or invalid data (HI_TSENSOR_INVALID_TEMP). 206 CNcomment:有效的温度值或无效数据(HI_TSENSOR_INVALID_TEMP)。CNend 207 * 208 * @par 依赖: 209 * @li hi_tsensor.h：for Tsensor APIs.CNcomment:文件用于描述tsensor相关接口。CNend 210 * @see None 211 */ 212 hi_s16 hi_tsensor_code_to_temperature(hi_u8 code); 213 214 /** 215 * @ingroup iot_tsensor 216 * @brief Converts the temperature into a temperature code.CNcomment:温度值转换成温度码。CNend 217 * 218 * @par 描述: 219 * Converts the temperature into a temperature code.CNcomment:将温度值转换成温度码。CNend 220 * 221 * @attention None 222 * @param temp [IN] type #hi_float，temperature code.CNcomment:温度值。CNend 223 * 224 * @retval #hi_u16 Valid temperature value or invalid data (HI_TSENSOR_INVALID_TEMP). 225 CNcomment:有效的温度值或无效数据(HI_TSENSOR_INVALID_TEMP)。CNend 226 * @par 依赖: 227 * @li hi_tsensor.h：for Tsensor APIs.CNcomment:文件用于描述tsensor相关接口。CNend 228 * @see None 229 */ 230 hi_u16 hi_tsensor_temperature_to_code(hi_s16 temp); 231 232 /** 233 * @ingroup iot_tsensor 234 * @brief Sets the temperature threshold.CNcomment:设置温度阈值门限。CNend 235 * 236 * @par 描述: 237 * Sets the temperature threshold.CNcomment:设置温度阈值门限。CNend 238 * 239 * @attention This function is invoked before tsensor temperature collection is started. This function is invoked to 240 * enable the function of reporting the temperature threshold interrupt. A maximum of three temperature 241 * threshold interrupt callback functions can be registered at the same time. When the Wi-Fi service is 242 * started, this interface is invoked to set the default high and low temperature thresholds. Before other 243 * services use this interface, check whether the default high and low temperature thresholds need to be 244 * changed. CNcomment:在启动tsensor温度采集之前调用，调用此函数将使能温度阈值门限中断上报, 最多可同时注册 245 3个温度阈值门限中断回调函数;WiFi业务启动时会调用此接口设置默认的高低温门限，此后其他业务使用此接口前， 246 请确认是否要修改默认的高低温门限值。CNend 247 * 248 * @param low_temp [IN] type #hi_s16，Low Temperature Threshold.CNcomment:低温门限。CNend 249 * @param high_temp [IN] type #hi_s16，High Temperature Threshold.CNcomment:高温门限。CNend 250 * @param callback_func [IN] type #hi_tsensor_callback_func，Indicates the callback function when the temperature 251 * exceeds the threshold.CNcomment:温度超阈值中断回调函数。CNend 252 * 253 * @retval #0 Success. 254 * @retval #Other Failure. For details, see hi_errno.h. 255 * @par 依赖: 256 * @li hi_tsensor.h：for Tsensor APIs.CNcomment:文件用于描述tsensor相关接口。CNend 257 * @see None 258 */ 259 hi_u32 hi_tsensor_set_outtemp_threshold(hi_s16 low_temp, hi_s16 high_temp, 260 hi_tsensor_callback_func callback_func); 261 262 /** 263 * @ingroup iot_tsensor 264 * @brief To set the threshold for the over-high temperature threshold.CNcomment:设置超高温阈值门限。CNend 265 * 266 * @par 描述: 267 * To set the threshold for the over-high temperature threshold.CNcomment:设置超高温阈值门限。CNend 268 * 269 * @attention This function is invoked before tsensor temperature collection is started. This function is invoked to 270 * enable the function of reporting the temperature threshold interrupt. A maximum of three temperature 271 * threshold interrupt callback functions can be registered at the same time. When the Wi-Fi service is 272 * started, this interface is invoked to set the default high and low temperature thresholds. Before other 273 * services use this interface, check whether the default high and low temperature thresholds need to be 274 * changed. CNcomment:在启动tsensor温度采集之前调用，调用此函数将使能温度阈值门限中断上报, 最多可同时注册 275 3个温度阈值门限中断回调函数;WiFi业务启动时会调用此接口设置默认的高低温门限，此后其他业务使用此接口前， 276 请确认是否要修改默认的高低温门限值。CNend 277 * 278 * @param over_temp [IN] type #hi_s16，Ultra-high temperature threshold.CNcomment:超高温门限。CNend 279 * @param callback_func [IN] type #hi_tsensor_callback_func，Interrupt callback function when the temperature 280 * exceeds the upper temperature threshold. CNcomment:温度超过超高温门限中断回调函数。CNend 281 * 282 * @retval #0 Success. 283 * @retval #Other Failure. For details, see hi_errno.h. 284 * @par 依赖: 285 * @li hi_tsensor.h：for Tsensor APIs.CNcomment:文件用于描述tsensor相关接口。CNend 286 * @see None 287 */ 288 hi_u32 hi_tsensor_set_overtemp_threshold(hi_s16 over_temp, hi_tsensor_callback_func callback_func); 289 290 /** 291 * @ingroup iot_tsensor 292 * @brief Sets the overtemperature power-off threshold.CNcomment:设置过温掉电阈值门限。CNend 293 * 294 * @par 描述: 295 * Sets the overtemperature power-off threshold.CNcomment:设置过温掉电阈值门限。CNend 296 * 297 * @attention This function is invoked before tsensor temperature collection is started. This function is invoked to 298 * enable the function of reporting the temperature threshold interrupt. A maximum of three temperature 299 * threshold interrupt callback functions can be registered at the same time. When the Wi-Fi service is 300 * started, this interface is invoked to set the default high and low temperature thresholds. Before other 301 * services use this interface, check whether the default high and low temperature thresholds need to be 302 * changed. CNcomment:在启动tsensor温度采集之前调用，调用此函数将使能温度阈值门限中断上报, 最多可同时注册 303 3个温度阈值门限中断回调函数;WiFi业务启动时会调用此接口设置默认的高低温门限，此后其他业务使用此接口前， 304 请确认是否要修改默认的高低温门限值。CNend 305 * 306 * @param pd_temp [IN] type #hi_s16，Indicates the threshold of the overtemperature power-off threshold. 307 CNcomment:过温掉电阈值门限。CNend 308 * 309 * @retval #0 Success. 310 * @retval #Other Failure. For details, see hi_errno.h. 311 * @par 依赖: 312 * @li hi_tsensor.h：for Tsensor APIs.CNcomment:文件用于描述tsensor相关接口。CNend 313 * @see None 314 */ 315 hi_u32 hi_tsensor_set_pdtemp_threshold(hi_s16 pd_temp); 316 317 /** 318 * @ingroup iot_tsensor 319 * @brief Registers the callback function for the temperature collection completion interrupt. 320 CNcomment:注册温度采集完成中断回调函数。CNend 321 * 322 * @par 描述: 323 * Registers the callback function for the temperature collection completion interrupt. 324 CNcomment:注册温度采集完成中断回调函数。CNend 325 * 326 * @attention This function is invoked before tsensor temperature collection is started. This function is invoked to 327 * enable the function of reporting the temperature threshold interrupt. A maximum of three temperature 328 * threshold interrupt callback functions can be registered at the same time. The tsensor temperature 329 * collection period is short. In HI_TSENSOR_MODE_16_POINTS_LOOP and HI_TSENSOR_MODE_1_POINT_LOOP modes, 330 * the collection completion interrupt is frequently triggered, occupying a large number of CPU resources. 331 * As a result, other services may fail to be scheduled. In HI_TSENSOR_MODE_16_POINTS_SINGLE mode, a large 332 * period can be set to avoid this problem, however, if the value of period is too large, the temperature 333 * monitoring density decreases. Therefore, it is recommended that you do not read the temperature by 334 * collecting data. CNcomment:在启动tsensor温度采集之前调用，调用此函数将使能温度采集完成中断上报, 335 最多可同时注册3个温度采集完成中断回调函数;tsensor温度采集周期很短，HI_TSENSOR_MODE_16_POINTS_LOOP和 336 HI_TSENSOR_MODE_1_POINT_LOOP模式下采集完成中断会频繁触发，占用大量cpu资源，可能会导致其他业务得不到调度， 337 HI_TSENSOR_MODE_16_POINTS_SINGLE模式虽然可以通过设置较大的period来避免这个问题，但过大的period值将会导致温度监控密度 338 的下降，因此建议尽量不要通过采集完成中断的方式读取温度。CNend 339 * 340 * @param callback_func [IN] type #hi_tsensor_callback_func，Temperature collection completion interrupt callback 341 * function.CNcomment:温度采集完成中断回调函数。CNend 342 * 343 * @retval #0 Success. 344 * @retval #Other Failure. For details, see hi_errno.h. 345 * @par 依赖: 346 * @li hi_tsensor.h：for Tsensor APIs.CNcomment:文件用于描述tsensor相关接口。CNend 347 * @see None 348 */ 349 hi_u32 hi_tsensor_register_temp_collect_finish_int_callback(hi_tsensor_callback_func callback_func); 350 351 /** 352 * @ingroup iot_tsensor 353 * @brief Save register-related values before going to deep sleep.CNcomment:深睡前保存相关寄存器内容。CNend 354 * 355 * @par 描述: 356 * Regs-related values are saved before entering deep sleep to facilitate sleep recovery. 357 CNcomment:深睡前保存相关寄存器内容，以便于睡醒恢复Tsensor。CNend 358 * 359 * @attention Called before deep sleep. It must be used in pairs with hi_tsensor_lp_restore. 360 CNcomment:在深睡前调用，必须与hi_tsensor_lp_restore接口成对使用。CNend 361 * @param None 362 * 363 * @retval None 364 * @par 依赖: 365 * @li hi_tsensor.h：for Tsensor APIs.CNcomment:文件用于描述tsensor相关接口。CNend 366 * @see hi_tsensor_lp_restore。 367 */ 368 hi_void hi_tsensor_lp_save(hi_void); 369 370 /** 371 * @ingroup iot_tsensor 372 * @brief Restore register related values after deep sleep wake up.CNcomment:深睡唤醒后恢复寄存器内容。CNend 373 * 374 * @par 描述: 375 * Restore register related values after deep sleep wake up.CNcomment:深睡唤醒后恢复寄存器内容。CNend 376 * 377 * @attention Called after deep sleep wake up. It must be used in pairs with hi_tsensor_lp_save. 378 CNcomment:深睡唤醒后调用，必须与hi_tsensor_lp_save接口成对使用。CNend 379 * @param None 380 * 381 * @retval None 382 * @par 依赖: 383 * @li hi_tsensor.h：for Tsensor APIs.CNcomment:文件用于描述tsensor相关接口。CNend 384 * @see hi_tsensor_lp_save。 385 */ 386 hi_void hi_tsensor_lp_restore(hi_void); 387 388 #ifdef __cplusplus 389 } 390 #endif 391 392 #endif 393