1 /*!
2  * \file      LoRaMacAdr.h
3  *
4  * \brief     LoRa MAC ADR implementation
5  *
6  * \copyright Revised BSD License, see section \ref LICENSE.
7  *
8  * \code
9  *                ______                              _
10  *               / _____)             _              | |
11  *              ( (____  _____ ____ _| |_ _____  ____| |__
12  *               \____ \| ___ |    (_   _) ___ |/ ___)  _ \
13  *               _____) ) ____| | | || |_| ____( (___| | | |
14  *              (______/|_____)_|_|_| \__)_____)\____)_| |_|
15  *              (C)2013-2017 Semtech
16  *
17  *               ___ _____ _   ___ _  _____ ___  ___  ___ ___
18  *              / __|_   _/_\ / __| |/ / __/ _ \| _ \/ __| __|
19  *              \__ \ | |/ _ \ (__| ' <| _| (_) |   / (__| _|
20  *              |___/ |_/_/ \_\___|_|\_\_| \___/|_|_\\___|___|
21  *              embedded.connectivity.solutions===============
22  *
23  * \endcode
24  *
25  * \author    Miguel Luis ( Semtech )
26  *
27  * \author    Gregory Cristian ( Semtech )
28  *
29  * \author    Daniel Jaeckle ( STACKFORCE )
30  *
31  * \author    Johannes Bruder ( STACKFORCE )
32  *
33  * \defgroup  LORAMACADR LoRa MAC ADR implementation
34  *            Implementation of the ADR algorithm for LoRa.
35  * \{
36  */
37 #ifndef __LORAMACADR_H__
38 #define __LORAMACADR_H__
39 
40 #ifdef __cplusplus
41 extern "C"
42 {
43 #endif
44 
45 /*! \} defgroup LORAMACADR */
46 
47 /*
48  * Parameter structure for the function CalcNextAdr.
49  */
50 typedef struct sCalcNextAdrParams
51 {
52     /*!
53      * Set to true, if the function should update the channels mask.
54      */
55     bool UpdateChanMask;
56     /*!
57      * Set to true, if ADR is enabled.
58      */
59     bool AdrEnabled;
60     /*!
61      * ADR ack counter.
62      */
63     uint32_t AdrAckCounter;
64     /*!
65      * ADR Ack limit
66      */
67     uint16_t AdrAckLimit;
68     /*!
69      * ADR Ack delay
70      */
71     uint16_t AdrAckDelay;
72     /*!
73      * Datarate used currently.
74      */
75     int8_t Datarate;
76     /*!
77      * TX power used currently.
78      */
79     int8_t TxPower;
80     /*!
81      * NbTrans counter used currently.
82      */
83     uint8_t NbTrans;
84     /*!
85      * UplinkDwellTime
86      */
87     uint8_t UplinkDwellTime;
88     /*!
89      * Region
90      */
91     LoRaMacRegion_t Region;
92 }CalcNextAdrParams_t;
93 
94 /*!
95  * \brief Calculates the next datarate to set, when ADR is on or off.
96  *
97  * \details Here is a summary of the actions:
98  *
99  * | ADR_ACK_CNT | Action                                                    |
100  * | ----------- | --------------------------------------------------------- |
101  * | 0... 63     | Do nothing                                                |
102  * | 64...95     | Set ADR ack bit                                           |
103  * | 96...127    | Set TX power to default (if already default, do nothing)  |
104  * | 128...159   | Set data rate to default (if already default, do nothing) |
105  * | >=160       | Set NbTrans to 1, re-enable default channels              |
106  *
107  * \param [IN] adrNext Pointer to the function parameters.
108  *
109  * \param [OUT] drOut The calculated datarate for the next TX.
110  *
111  * \param [OUT] txPowOut The TX power for the next TX.
112  *
113  * \param [OUT] nbTransOut The NbTrans counter.
114  *
115  * \param [OUT] adrAckCounter The calculated ADR acknowledgement counter.
116  *
117  * \retval Returns true, if an ADR request should be performed.
118  */
119 bool LoRaMacAdrCalcNext( CalcNextAdrParams_t* adrNext, int8_t* drOut, int8_t* txPowOut,
120                          uint8_t* nbTransOut, uint32_t* adrAckCounter );
121 
122 #ifdef __cplusplus
123 }
124 #endif
125 
126 #endif // __LORAMACADR_H__
127