1 /*
2  *  Copyright (c) 2022, 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 strain 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 #ifndef OT_POSIX_PLATFORM_POWER_HPP_
30 #define OT_POSIX_PLATFORM_POWER_HPP_
31 
32 #include <assert.h>
33 #include <stdio.h>
34 #include <string.h>
35 
36 #include <openthread/error.h>
37 #include <openthread/platform/radio.h>
38 #include "common/string.hpp"
39 
40 namespace ot {
41 namespace Power {
42 
43 class Domain
44 {
45 public:
Domain(void)46     Domain(void) { m8[0] = '\0'; }
47 
48     /**
49      * Sets the regulatory domain from a given null terminated C string.
50      *
51      * @param[in] aDomain   A regulatory domain name C string.
52      *
53      * @retval OT_ERROR_NONE           Successfully set the regulatory domain.
54      * @retval OT_ERROR_INVALID_ARGS   Given regulatory domain is too long.
55      *
56      */
57     otError Set(const char *aDomain);
58 
59     /**
60      * Overloads operator `==` to evaluate whether or not two `Domain` instances are equal.
61      *
62      * @param[in]  aOther  The other `Domain` instance to compare with.
63      *
64      * @retval TRUE   If the two `Domain` instances are equal.
65      * @retval FALSE  If the two `Domain` instances not equal.
66      *
67      */
operator ==(const Domain & aOther) const68     bool operator==(const Domain &aOther) const { return strcmp(m8, aOther.m8) == 0; }
69 
70     /**
71      * Overloads operator `!=` to evaluate whether or not the `Domain` is unequal to a given C string.
72      *
73      * @param[in]  aCString  A C string to compare with. Can be `nullptr` which then returns 'TRUE'.
74      *
75      * @retval TRUE   If the two regulatory domains are not equal.
76      * @retval FALSE  If the two regulatory domains are equal.
77      *
78      */
operator !=(const char * aCString) const79     bool operator!=(const char *aCString) const { return (aCString == nullptr) ? true : strcmp(m8, aCString) != 0; }
80 
81     /**
82      * Gets the regulatory domain as a null terminated C string.
83      *
84      * @returns The regulatory domain as a null terminated C string array.
85      *
86      */
AsCString(void) const87     const char *AsCString(void) const { return m8; }
88 
89 private:
90     static constexpr uint8_t kDomainSize = 8;
91     char                     m8[kDomainSize + 1];
92 };
93 
94 class TargetPower
95 {
96 public:
97     static constexpr uint16_t       kInfoStringSize = 12; ///< Recommended buffer size to use with `ToString()`.
98     typedef String<kInfoStringSize> InfoString;
99 
100     /**
101      * Parses an target power string.
102      *
103      * The string MUST follow the format: "<channel_start>,<channel_end>,<target_power>".
104      * For example, "11,26,2000"
105      *
106      * @param[in]  aString   A pointer to the null-terminated string.
107      *
108      * @retval OT_ERROR_NONE   Successfully parsed the target power string.
109      * @retval OT_ERROR_PARSE  Failed to parse the target power string.
110      *
111      */
112     otError FromString(char *aString);
113 
114     /**
115      * Returns the start channel.
116      *
117      * @returns The channel.
118      *
119      */
GetChannelStart(void) const120     uint8_t GetChannelStart(void) const { return mChannelStart; }
121 
122     /**
123      * Returns the end channel.
124      *
125      * @returns The channel.
126      *
127      */
GetChannelEnd(void) const128     uint8_t GetChannelEnd(void) const { return mChannelEnd; }
129 
130     /**
131      * Returns the target power.
132      *
133      * @returns The target power, in 0.01 dBm.
134      *
135      */
GetTargetPower(void) const136     int16_t GetTargetPower(void) const { return mTargetPower; }
137 
138     /**
139      * Converts the target power into a human-readable string.
140      *
141      * @returns  An `InfoString` object representing the target power.
142      *
143      */
144     InfoString ToString(void) const;
145 
146 private:
147     uint8_t mChannelStart;
148     uint8_t mChannelEnd;
149     int16_t mTargetPower;
150 };
151 
152 class RawPowerSetting
153 {
154 public:
155     // Recommended buffer size to use with `ToString()`.
156     static constexpr uint16_t kInfoStringSize = OPENTHREAD_CONFIG_POWER_CALIBRATION_RAW_POWER_SETTING_SIZE * 2 + 1;
157     typedef String<kInfoStringSize> InfoString;
158 
159     /**
160      * Sets the raw power setting from a given null terminated hex C string.
161      *
162      * @param[in] aRawPowerSetting  A raw power setting hex C string.
163      *
164      * @retval OT_ERROR_NONE           Successfully set the raw power setting.
165      * @retval OT_ERROR_INVALID_ARGS   The given raw power setting is too long.
166      *
167      */
168     otError Set(const char *aRawPowerSetting);
169 
170     /**
171      * Converts the raw power setting into a human-readable string.
172      *
173      * @returns  An `InfoString` object representing the calibrated power.
174      *
175      */
176     InfoString ToString(void) const;
177 
GetData(void) const178     const uint8_t *GetData(void) const { return mData; }
GetLength(void) const179     uint16_t       GetLength(void) const { return mLength; }
180 
181 private:
182     static constexpr uint16_t kMaxRawPowerSettingSize = OPENTHREAD_CONFIG_POWER_CALIBRATION_RAW_POWER_SETTING_SIZE;
183 
184     uint8_t  mData[kMaxRawPowerSettingSize];
185     uint16_t mLength;
186 };
187 
188 class CalibratedPower
189 {
190 public:
191     // Recommended buffer size to use with `ToString()`.
192     static constexpr uint16_t       kInfoStringSize = 20 + RawPowerSetting::kInfoStringSize;
193     typedef String<kInfoStringSize> InfoString;
194 
195     /**
196      * Parses an calibrated power string.
197      *
198      * The string MUST follow the format: "<channel_start>,<channel_end>,<actual_power>,<raw_power_setting>".
199      * For example, "11,26,2000,1122aabb"
200      *
201      * @param[in]  aString   A pointer to the null-terminated string.
202      *
203      * @retval OT_ERROR_NONE   Successfully parsed the calibrated power string.
204      * @retval OT_ERROR_PARSE  Failed to parse the calibrated power string.
205      *
206      */
207     otError FromString(char *aString);
208 
209     /**
210      * Returns the start channel.
211      *
212      * @returns The channel.
213      *
214      */
GetChannelStart(void) const215     uint8_t GetChannelStart(void) const { return mChannelStart; }
216 
217     /**
218      * Sets the start channel.
219      *
220      * @param[in]  aChannelStart  The start channel.
221      *
222      */
SetChannelStart(uint8_t aChannelStart)223     void SetChannelStart(uint8_t aChannelStart) { mChannelStart = aChannelStart; }
224 
225     /**
226      * Returns the end channel.
227      *
228      * @returns The channel.
229      *
230      */
GetChannelEnd(void) const231     uint8_t GetChannelEnd(void) const { return mChannelEnd; }
232 
233     /**
234      * Sets the end channel.
235      *
236      * @param[in]  aChannelEnd  The end channel.
237      *
238      */
SetChannelEnd(uint8_t aChannelEnd)239     void SetChannelEnd(uint8_t aChannelEnd) { mChannelEnd = aChannelEnd; }
240 
241     /**
242      * Returns the actual power.
243      *
244      * @returns The actual measured power, in 0.01 dBm.
245      *
246      */
GetActualPower(void) const247     int16_t GetActualPower(void) const { return mActualPower; }
248 
249     /**
250      * Sets the actual channel.
251      *
252      * @param[in]  aActualPower  The actual power in 0.01 dBm.
253      *
254      */
SetActualPower(int16_t aActualPower)255     void SetActualPower(int16_t aActualPower) { mActualPower = aActualPower; }
256 
257     /**
258      * Returns the raw power setting.
259      *
260      * @returns A reference to the raw power setting.
261      *
262      */
GetRawPowerSetting(void) const263     const RawPowerSetting &GetRawPowerSetting(void) const { return mRawPowerSetting; }
264 
265     /**
266      * Sets the raw power setting.
267      *
268      * @param[in]  aRawPowerSetting  The raw power setting.
269      *
270      */
SetRawPowerSetting(const RawPowerSetting & aRawPowerSetting)271     void SetRawPowerSetting(const RawPowerSetting &aRawPowerSetting) { mRawPowerSetting = aRawPowerSetting; }
272 
273     /**
274      * Converts the calibrated power into a human-readable string.
275      *
276      * @returns  An `InfoString` object representing the calibrated power.
277      *
278      */
279     InfoString ToString(void) const;
280 
281 private:
282     uint8_t         mChannelStart;
283     uint8_t         mChannelEnd;
284     int16_t         mActualPower;
285     RawPowerSetting mRawPowerSetting;
286 };
287 } // namespace Power
288 } // namespace ot
289 #endif // OT_POSIX_PLATFORM_POWER_HPP_
290