1 /*
2  * Copyright (c) 2018, Nordic Semiconductor ASA
3  * All rights reserved.
4  *
5  * SPDX-License-Identifier: BSD-3-Clause
6  *
7  * Redistribution and use in source and binary forms, with or without
8  * modification, are permitted provided that the following conditions are met:
9  *
10  * 1. Redistributions of source code must retain the above copyright notice, this
11  *    list of conditions and the following disclaimer.
12  *
13  * 2. Redistributions in binary form must reproduce the above copyright
14  *    notice, this list of conditions and the following disclaimer in the
15  *    documentation and/or other materials provided with the distribution.
16  *
17  * 3. Neither the name of Nordic Semiconductor ASA nor the names of its
18  *    contributors may be used to endorse or promote products derived from this
19  *    software without specific prior written permission.
20  *
21  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
22  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23  * IMPLIED WARRANTIES OF MERCHANTABILITY, AND FITNESS FOR A PARTICULAR PURPOSE
24  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
25  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
26  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
27  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
28  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
29  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
30  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
31  * POSSIBILITY OF SUCH DAMAGE.
32  *
33  */
34 
35 #ifndef NRF_802154_RSSI_H__
36 #define NRF_802154_RSSI_H__
37 
38 #include <stdint.h>
39 
40 /**
41  * @defgroup nrf_802154_rssi RSSI measurement function
42  * @{
43  * @ingroup nrf_802154
44  * @brief RSSI calculations used internally in the 802.15.4 driver.
45  */
46 
47 /**
48  * @brief Gets the RSSISAMPLE temperature correction value.
49  *
50  * The correction value is based on the last temperature value reported by the platform.
51  *
52  * @param[in]  rssi_sample  Value read from the RSSISAMPLE register.
53  *
54  * @returns RSSISAMPLE temperature correction value.
55  */
56 int8_t nrf_802154_rssi_sample_temp_corr_value_get(uint8_t rssi_sample);
57 
58 /**
59  * @brief Adjusts the given RSSISAMPLE value by a temperature correction factor.
60  *
61  * @param[in]  rssi_sample  Value read from the RSSISAMPLE register.
62  *
63  * @returns RSSISAMPLE corrected by a temperature factor.
64  */
65 uint8_t nrf_802154_rssi_sample_corrected_get(uint8_t rssi_sample);
66 
67 /**
68  * @brief Adjusts the reported LQI value using a temperature correction factor.
69  *
70  * @param[in]  lqi   Value read from the LQI byte.
71  *
72  * @returns LQI byte value corrected by a temperature factor.
73  */
74 uint8_t nrf_802154_rssi_lqi_corrected_get(uint8_t lqi);
75 
76 /**
77  * @brief Adjusts the EDSAMPLE value using a temperature correction factor.
78  *
79  * @param[in]  ed    Value read from the EDSAMPLE register.
80  *
81  * @returns EDSAMPLE value corrected by a temperature factor.
82  */
83 int16_t nrf_802154_rssi_ed_corrected_get(int16_t ed);
84 
85 /**
86  * @brief Adjusts the CCA ED threshold value using a temperature correction factor.
87  *
88  * @param[in]  cca_ed  Value representing the CCA ED threshold to be corrected.
89  *
90  * @returns CCA ED threshold value corrected by a temperature factor.
91  */
92 uint8_t nrf_802154_rssi_cca_ed_threshold_corrected_get(uint8_t cca_ed);
93 
94 /**
95  * @brief Convert the hardware reported energy detection value to a value compliant with the 802.15.4 specification.
96  *
97  * @param[in]  ed_sample  The hardware reported value
98  *
99  * @returns 802.15.4 compliant energy detection value.
100  */
101 uint8_t nrf_802154_rssi_ed_sample_convert(uint8_t ed_sample);
102 
103 /**
104  * @brief  Converts the energy level received during the energy detection procedure to a dBm value.
105  *
106  * @param[in]  energy_level  Energy level passed by @ref nrf_802154_energy_detected.
107  *
108  * @return  Result of the energy detection procedure in dBm.
109  */
110 int8_t nrf_802154_rssi_dbm_from_energy_level_calculate(uint8_t energy_level);
111 
112 /**
113  * @brief  Converts the EDSAMPLE value to a dBm value.
114  *
115  * @note Performs temperature correction internally.
116  *
117  * @param[in]  ed_sample  The hardware reported value.
118  *
119  * @return  Result of the energy detection procedure in dBm.
120  */
121 int8_t nrf_802154_rssi_ed_sample_to_dbm_convert(uint8_t ed_sample);
122 
123 /**
124  *@}
125  **/
126 
127 #endif // NRF_802154_RSSI_H__
128