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 otError Set(const char *aDomain); 57 58 /** 59 * Overloads operator `==` to evaluate whether or not two `Domain` instances are equal. 60 * 61 * @param[in] aOther The other `Domain` instance to compare with. 62 * 63 * @retval TRUE If the two `Domain` instances are equal. 64 * @retval FALSE If the two `Domain` instances not equal. 65 */ operator ==(const Domain & aOther) const66 bool operator==(const Domain &aOther) const { return strcmp(m8, aOther.m8) == 0; } 67 68 /** 69 * Overloads operator `!=` to evaluate whether or not the `Domain` is unequal to a given C string. 70 * 71 * @param[in] aCString A C string to compare with. Can be `nullptr` which then returns 'TRUE'. 72 * 73 * @retval TRUE If the two regulatory domains are not equal. 74 * @retval FALSE If the two regulatory domains are equal. 75 */ operator !=(const char * aCString) const76 bool operator!=(const char *aCString) const { return (aCString == nullptr) ? true : strcmp(m8, aCString) != 0; } 77 78 /** 79 * Gets the regulatory domain as a null terminated C string. 80 * 81 * @returns The regulatory domain as a null terminated C string array. 82 */ AsCString(void) const83 const char *AsCString(void) const { return m8; } 84 85 private: 86 static constexpr uint8_t kDomainSize = 8; 87 char m8[kDomainSize + 1]; 88 }; 89 90 class TargetPower 91 { 92 public: 93 static constexpr uint16_t kInfoStringSize = 12; ///< Recommended buffer size to use with `ToString()`. 94 typedef String<kInfoStringSize> InfoString; 95 96 /** 97 * Parses an target power string. 98 * 99 * The string MUST follow the format: "<channel_start>,<channel_end>,<target_power>". 100 * For example, "11,26,2000" 101 * 102 * @param[in] aString A pointer to the null-terminated string. 103 * 104 * @retval OT_ERROR_NONE Successfully parsed the target power string. 105 * @retval OT_ERROR_PARSE Failed to parse the target power string. 106 */ 107 otError FromString(char *aString); 108 109 /** 110 * Returns the start channel. 111 * 112 * @returns The channel. 113 */ GetChannelStart(void) const114 uint8_t GetChannelStart(void) const { return mChannelStart; } 115 116 /** 117 * Returns the end channel. 118 * 119 * @returns The channel. 120 */ GetChannelEnd(void) const121 uint8_t GetChannelEnd(void) const { return mChannelEnd; } 122 123 /** 124 * Returns the target power. 125 * 126 * @returns The target power, in 0.01 dBm. 127 */ GetTargetPower(void) const128 int16_t GetTargetPower(void) const { return mTargetPower; } 129 130 /** 131 * Converts the target power into a human-readable string. 132 * 133 * @returns An `InfoString` object representing the target power. 134 */ 135 InfoString ToString(void) const; 136 137 private: 138 uint8_t mChannelStart; 139 uint8_t mChannelEnd; 140 int16_t mTargetPower; 141 }; 142 143 class RawPowerSetting 144 { 145 public: 146 // Recommended buffer size to use with `ToString()`. 147 static constexpr uint16_t kInfoStringSize = OPENTHREAD_CONFIG_POWER_CALIBRATION_RAW_POWER_SETTING_SIZE * 2 + 1; 148 typedef String<kInfoStringSize> InfoString; 149 150 /** 151 * Sets the raw power setting from a given null terminated hex C string. 152 * 153 * @param[in] aRawPowerSetting A raw power setting hex C string. 154 * 155 * @retval OT_ERROR_NONE Successfully set the raw power setting. 156 * @retval OT_ERROR_INVALID_ARGS The given raw power setting is too long. 157 */ 158 otError Set(const char *aRawPowerSetting); 159 160 /** 161 * Converts the raw power setting into a human-readable string. 162 * 163 * @returns An `InfoString` object representing the calibrated power. 164 */ 165 InfoString ToString(void) const; 166 GetData(void) const167 const uint8_t *GetData(void) const { return mData; } GetLength(void) const168 uint16_t GetLength(void) const { return mLength; } 169 170 private: 171 static constexpr uint16_t kMaxRawPowerSettingSize = OPENTHREAD_CONFIG_POWER_CALIBRATION_RAW_POWER_SETTING_SIZE; 172 173 uint8_t mData[kMaxRawPowerSettingSize]; 174 uint16_t mLength; 175 }; 176 177 class CalibratedPower 178 { 179 public: 180 // Recommended buffer size to use with `ToString()`. 181 static constexpr uint16_t kInfoStringSize = 20 + RawPowerSetting::kInfoStringSize; 182 typedef String<kInfoStringSize> InfoString; 183 184 /** 185 * Parses an calibrated power string. 186 * 187 * The string MUST follow the format: "<channel_start>,<channel_end>,<actual_power>,<raw_power_setting>". 188 * For example, "11,26,2000,1122aabb" 189 * 190 * @param[in] aString A pointer to the null-terminated string. 191 * 192 * @retval OT_ERROR_NONE Successfully parsed the calibrated power string. 193 * @retval OT_ERROR_PARSE Failed to parse the calibrated power string. 194 */ 195 otError FromString(char *aString); 196 197 /** 198 * Returns the start channel. 199 * 200 * @returns The channel. 201 */ GetChannelStart(void) const202 uint8_t GetChannelStart(void) const { return mChannelStart; } 203 204 /** 205 * Sets the start channel. 206 * 207 * @param[in] aChannelStart The start channel. 208 */ SetChannelStart(uint8_t aChannelStart)209 void SetChannelStart(uint8_t aChannelStart) { mChannelStart = aChannelStart; } 210 211 /** 212 * Returns the end channel. 213 * 214 * @returns The channel. 215 */ GetChannelEnd(void) const216 uint8_t GetChannelEnd(void) const { return mChannelEnd; } 217 218 /** 219 * Sets the end channel. 220 * 221 * @param[in] aChannelEnd The end channel. 222 */ SetChannelEnd(uint8_t aChannelEnd)223 void SetChannelEnd(uint8_t aChannelEnd) { mChannelEnd = aChannelEnd; } 224 225 /** 226 * Returns the actual power. 227 * 228 * @returns The actual measured power, in 0.01 dBm. 229 */ GetActualPower(void) const230 int16_t GetActualPower(void) const { return mActualPower; } 231 232 /** 233 * Sets the actual channel. 234 * 235 * @param[in] aActualPower The actual power in 0.01 dBm. 236 */ SetActualPower(int16_t aActualPower)237 void SetActualPower(int16_t aActualPower) { mActualPower = aActualPower; } 238 239 /** 240 * Returns the raw power setting. 241 * 242 * @returns A reference to the raw power setting. 243 */ GetRawPowerSetting(void) const244 const RawPowerSetting &GetRawPowerSetting(void) const { return mRawPowerSetting; } 245 246 /** 247 * Sets the raw power setting. 248 * 249 * @param[in] aRawPowerSetting The raw power setting. 250 */ SetRawPowerSetting(const RawPowerSetting & aRawPowerSetting)251 void SetRawPowerSetting(const RawPowerSetting &aRawPowerSetting) { mRawPowerSetting = aRawPowerSetting; } 252 253 /** 254 * Converts the calibrated power into a human-readable string. 255 * 256 * @returns An `InfoString` object representing the calibrated power. 257 */ 258 InfoString ToString(void) const; 259 260 private: 261 uint8_t mChannelStart; 262 uint8_t mChannelEnd; 263 int16_t mActualPower; 264 RawPowerSetting mRawPowerSetting; 265 }; 266 } // namespace Power 267 } // namespace ot 268 #endif // OT_POSIX_PLATFORM_POWER_HPP_ 269