1 /*
2 * Copyright (c) 2016, The OpenThread Authors.
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions are met:
7 * 1. Redistributions of source code must retain the above copyright
8 * notice, this list of conditions and the following disclaimer.
9 * 2. Redistributions in binary form must reproduce the above copyright
10 * notice, this list of conditions and the following disclaimer in the
11 * documentation and/or other materials provided with the distribution.
12 * 3. Neither the name of the copyright holder nor the
13 * names of its contributors may be used to endorse or promote products
14 * derived from this software without specific prior written permission.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26 * POSSIBILITY OF SUCH DAMAGE.
27 */
28
29 /**
30 * @file
31 * This file implements link quality information processing and storage.
32 */
33
34 #include "link_quality.hpp"
35
36 #include "instance/instance.hpp"
37
38 namespace ot {
39
40 // This array gives the decimal point digits representing 0/8, 1/8, ..., 7/8 (does not include the '.').
41 static const char *const kDigitsString[8] = {
42 // 0/8, 1/8, 2/8, 3/8, 4/8, 5/8, 6/8, 7/8
43 "0", "125", "25", "375", "5", "625", "75", "875"};
44
AddSample(bool aSuccess,uint16_t aWeight)45 void SuccessRateTracker::AddSample(bool aSuccess, uint16_t aWeight)
46 {
47 uint32_t oldAverage = mFailureRate;
48 uint32_t newValue = (aSuccess) ? 0 : kMaxRateValue;
49 uint32_t n = aWeight;
50
51 // `n/2` is added to the sum to ensure rounding the value to the nearest integer when dividing by `n`
52 // (e.g., 1.2 -> 1, 3.5 -> 4).
53
54 mFailureRate = static_cast<uint16_t>(((oldAverage * (n - 1)) + newValue + (n / 2)) / n);
55 }
56
Add(int8_t aRss)57 Error RssAverager::Add(int8_t aRss)
58 {
59 Error error = kErrorNone;
60 uint16_t newValue;
61
62 VerifyOrExit(aRss != Radio::kInvalidRssi, error = kErrorInvalidArgs);
63
64 // Restrict the RSS value to the closed range [-128, 0]
65 // so the RSS times precision multiple can fit in 11 bits.
66 aRss = Min<int8_t>(aRss, 0);
67
68 // Multiply the RSS value by a precision multiple (currently -8).
69
70 newValue = static_cast<uint16_t>(-aRss);
71 newValue <<= kPrecisionBitShift;
72
73 mCount += (mCount < (1 << kCoeffBitShift));
74 // Maintain arithmetic mean.
75 // newAverage = newValue * (1/mCount) + oldAverage * ((mCount -1)/mCount)
76 mAverage = static_cast<uint16_t>(((mAverage * (mCount - 1)) + newValue) / mCount);
77
78 exit:
79 return error;
80 }
81
GetAverage(void) const82 int8_t RssAverager::GetAverage(void) const
83 {
84 int8_t average;
85
86 VerifyOrExit(mCount != 0, average = Radio::kInvalidRssi);
87
88 average = -static_cast<int8_t>(mAverage >> kPrecisionBitShift);
89
90 // Check for possible round up (e.g., average of -71.5 --> -72)
91
92 if ((mAverage & kPrecisionBitMask) >= (kPrecision >> 1))
93 {
94 average--;
95 }
96
97 exit:
98 return average;
99 }
100
ToString(void) const101 RssAverager::InfoString RssAverager::ToString(void) const
102 {
103 InfoString string;
104
105 VerifyOrExit(mCount != 0);
106 string.Append("%d.%s", -(mAverage >> kPrecisionBitShift), kDigitsString[mAverage & kPrecisionBitMask]);
107
108 exit:
109 return string;
110 }
111
Add(uint8_t aLqi)112 void LqiAverager::Add(uint8_t aLqi)
113 {
114 uint8_t count;
115 uint16_t newAverage;
116
117 if (mCount < NumericLimits<uint8_t>::kMax)
118 {
119 mCount++;
120 }
121
122 count = Min(static_cast<uint8_t>(1 << kCoeffBitShift), mCount);
123
124 newAverage = mAverage;
125 newAverage = (newAverage * (count - 1) + aLqi) / count;
126
127 mAverage = static_cast<uint8_t>(newAverage);
128 }
129
Clear(void)130 void LinkQualityInfo::Clear(void)
131 {
132 mRssAverager.Clear();
133 SetLinkQualityIn(kLinkQuality0);
134 SetLinkQualityOut(kLinkQuality0);
135 mLastRss = Radio::kInvalidRssi;
136
137 mFrameErrorRate.Clear();
138 mMessageErrorRate.Clear();
139 }
140
AddRss(int8_t aRss)141 void LinkQualityInfo::AddRss(int8_t aRss)
142 {
143 uint8_t oldLinkQuality = kNoLinkQuality;
144
145 VerifyOrExit(aRss != Radio::kInvalidRssi);
146
147 mLastRss = aRss;
148
149 if (mRssAverager.HasAverage())
150 {
151 oldLinkQuality = GetLinkQualityIn();
152 }
153
154 SuccessOrExit(mRssAverager.Add(aRss));
155
156 SetLinkQualityIn(CalculateLinkQuality(GetLinkMargin(), oldLinkQuality));
157
158 exit:
159 return;
160 }
161
GetLinkMargin(void) const162 uint8_t LinkQualityInfo::GetLinkMargin(void) const
163 {
164 return ComputeLinkMargin(Get<Mac::SubMac>().GetNoiseFloor(), GetAverageRss());
165 }
166
ToInfoString(void) const167 LinkQualityInfo::InfoString LinkQualityInfo::ToInfoString(void) const
168 {
169 InfoString string;
170
171 string.Append("aveRss:%s, lastRss:%d, linkQuality:%d", mRssAverager.ToString().AsCString(), GetLastRss(),
172 GetLinkQualityIn());
173
174 return string;
175 }
176
ComputeLinkMargin(int8_t aNoiseFloor,int8_t aRss)177 uint8_t ComputeLinkMargin(int8_t aNoiseFloor, int8_t aRss)
178 {
179 int8_t linkMargin = aRss - aNoiseFloor;
180
181 if (linkMargin < 0 || aRss == Radio::kInvalidRssi)
182 {
183 linkMargin = 0;
184 }
185
186 return static_cast<uint8_t>(linkMargin);
187 }
188
LinkQualityForLinkMargin(uint8_t aLinkMargin)189 LinkQuality LinkQualityForLinkMargin(uint8_t aLinkMargin)
190 {
191 return LinkQualityInfo::CalculateLinkQuality(aLinkMargin, LinkQualityInfo::kNoLinkQuality);
192 }
193
GetTypicalRssForLinkQuality(int8_t aNoiseFloor,LinkQuality aLinkQuality)194 int8_t GetTypicalRssForLinkQuality(int8_t aNoiseFloor, LinkQuality aLinkQuality)
195 {
196 int8_t linkMargin = 0;
197
198 switch (aLinkQuality)
199 {
200 case kLinkQuality3:
201 linkMargin = LinkQualityInfo::kLinkQuality3LinkMargin;
202 break;
203
204 case kLinkQuality2:
205 linkMargin = LinkQualityInfo::kLinkQuality2LinkMargin;
206 break;
207
208 case kLinkQuality1:
209 linkMargin = LinkQualityInfo::kLinkQuality1LinkMargin;
210 break;
211
212 default:
213 linkMargin = LinkQualityInfo::kLinkQuality0LinkMargin;
214 break;
215 }
216
217 return linkMargin + aNoiseFloor;
218 }
219
CostForLinkQuality(LinkQuality aLinkQuality)220 uint8_t CostForLinkQuality(LinkQuality aLinkQuality)
221 {
222 static const uint8_t kCostsForLinkQuality[] = {
223 kCostForLinkQuality0, // Link cost for `kLinkQuality0` (0).
224 kCostForLinkQuality1, // Link cost for `kLinkQuality1` (1).
225 kCostForLinkQuality2, // Link cost for `kLinkQuality2` (2).
226 kCostForLinkQuality3, // Link cost for `kLinkQuality3` (3).
227 };
228
229 struct EnumCheck
230 {
231 InitEnumValidatorCounter();
232 ValidateNextEnum(kLinkQuality0);
233 ValidateNextEnum(kLinkQuality1);
234 ValidateNextEnum(kLinkQuality2);
235 ValidateNextEnum(kLinkQuality3);
236 };
237
238 uint8_t cost = Mle::kMaxRouteCost;
239
240 VerifyOrExit(aLinkQuality <= kLinkQuality3);
241 cost = kCostsForLinkQuality[aLinkQuality];
242
243 exit:
244 return cost;
245 }
246
CalculateLinkQuality(uint8_t aLinkMargin,uint8_t aLastLinkQuality)247 LinkQuality LinkQualityInfo::CalculateLinkQuality(uint8_t aLinkMargin, uint8_t aLastLinkQuality)
248 {
249 // Static private method to calculate the link quality from a given
250 // link margin while taking into account the last link quality
251 // value and adding the hysteresis value to the thresholds. If
252 // there is no previous value for link quality, the constant
253 // kNoLinkQuality should be passed as the second argument.
254
255 uint8_t threshold1, threshold2, threshold3;
256 LinkQuality linkQuality = kLinkQuality0;
257
258 threshold1 = kThreshold1;
259 threshold2 = kThreshold2;
260 threshold3 = kThreshold3;
261
262 // Apply the hysteresis threshold based on the last link quality value.
263
264 switch (aLastLinkQuality)
265 {
266 case 0:
267 threshold1 += kHysteresisThreshold;
268
269 OT_FALL_THROUGH;
270
271 case 1:
272 threshold2 += kHysteresisThreshold;
273
274 OT_FALL_THROUGH;
275
276 case 2:
277 threshold3 += kHysteresisThreshold;
278
279 OT_FALL_THROUGH;
280
281 default:
282 break;
283 }
284
285 if (aLinkMargin > threshold3)
286 {
287 linkQuality = kLinkQuality3;
288 }
289 else if (aLinkMargin > threshold2)
290 {
291 linkQuality = kLinkQuality2;
292 }
293 else if (aLinkMargin > threshold1)
294 {
295 linkQuality = kLinkQuality1;
296 }
297
298 return linkQuality;
299 }
300
301 } // namespace ot
302