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
28extern "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*/
47typedef hi_void (*hi_tsensor_callback_func)(hi_s16);
48
49/**
50 * @ingroup iot_tsensor
51 *
52 * Tsensor report mode.CNcomment:Tsensor上报模式。CNend
53 */
54typedef 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.
77CNcomment:period仅当mode为HI_TSENSOR_MODE_16_POINTS_SINGLE有效, period范围: period * 31.25us > 16 * 192us;
78WiFi模块默认启用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.
82CNcomment:Tsensor温度采集模式。CNend
83* @param  period           [IN] type #hi_u16，Acquisition period, it is the multiple of 2 ms.
84CNcomment:温度自动检测周期，为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*/
92hi_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.
103CNcomment:待写入温度值的地址。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*/
111hi_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.
122CNcomment: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*/
130hi_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的基础上，此接口同时禁用了
139tsensor的中断上报，并清空用户注册的回调函数。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.
145CNcomment:调用此接口后，对于使用中断回调的场景，在start之前，需再次调用相应接口设置中断函数，开启中断上报；
146WiFi模块默认启用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*/
155hi_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.
184CNcomment:选择Tsensor IP的temp_trim由efuse直接加载，CNend
185*                                                1：The temp_trim of the Tsensor IP is configured by the register.
186CNcomment:选择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*/
193hi_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).
206CNcomment:有效的温度值或无效数据(HI_TSENSOR_INVALID_TEMP)。CNend
207*
208* @par 依赖:
209*            @li hi_tsensor.h：for Tsensor APIs.CNcomment:文件用于描述tsensor相关接口。CNend
210* @see None
211*/
212hi_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).
225CNcomment:有效的温度值或无效数据(HI_TSENSOR_INVALID_TEMP)。CNend
226* @par 依赖:
227*            @li hi_tsensor.h：for Tsensor APIs.CNcomment:文件用于描述tsensor相关接口。CNend
228* @see None
229*/
230hi_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温度采集之前调用，调用此函数将使能温度阈值门限中断上报, 最多可同时注册
2453个温度阈值门限中断回调函数;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*/
259hi_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温度采集之前调用，调用此函数将使能温度阈值门限中断上报, 最多可同时注册
2753个温度阈值门限中断回调函数;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*/
288hi_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温度采集之前调用，调用此函数将使能温度阈值门限中断上报, 最多可同时注册
3033个温度阈值门限中断回调函数;WiFi业务启动时会调用此接口设置默认的高低温门限，此后其他业务使用此接口前，
304请确认是否要修改默认的高低温门限值。CNend
305*
306* @param  pd_temp            [IN] type #hi_s16，Indicates the threshold of the overtemperature power-off threshold.
307CNcomment:过温掉电阈值门限。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*/
315hi_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.
320CNcomment:注册温度采集完成中断回调函数。CNend
321*
322* @par 描述:
323*          Registers the callback function for the temperature collection completion interrupt.
324CNcomment:注册温度采集完成中断回调函数。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和
336HI_TSENSOR_MODE_1_POINT_LOOP模式下采集完成中断会频繁触发，占用大量cpu资源，可能会导致其他业务得不到调度，
337HI_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*/
349hi_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.
357CNcomment:深睡前保存相关寄存器内容，以便于睡醒恢复Tsensor。CNend
358*
359* @attention Called before deep sleep. It must be used in pairs with hi_tsensor_lp_restore.
360CNcomment:在深睡前调用，必须与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*/
368hi_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.
378CNcomment:深睡唤醒后调用，必须与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*/
386hi_void hi_tsensor_lp_restore(hi_void);
387
388#ifdef __cplusplus
389}
390#endif
391
392#endif
393