1 /* 2 * Copyright (c) 2024, 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 includes definitions of Thead Controller Interface. 32 */ 33 34 #ifndef OTBR_AGENT_THREAD_HOST_HPP_ 35 #define OTBR_AGENT_THREAD_HOST_HPP_ 36 37 #include <functional> 38 #include <memory> 39 40 #include <openthread/dataset.h> 41 #include <openthread/error.h> 42 #include <openthread/thread.h> 43 44 #include "lib/spinel/coprocessor_type.h" 45 46 #include "common/logging.hpp" 47 48 namespace otbr { 49 namespace Host { 50 51 /** 52 * This interface provides access to some Thread network properties in a sync way. 53 * 54 * The APIs are unified for both NCP and RCP cases. 55 */ 56 class NetworkProperties 57 { 58 public: 59 /** 60 * Returns the device role. 61 * 62 * @returns the device role. 63 */ 64 virtual otDeviceRole GetDeviceRole(void) const = 0; 65 66 /** 67 * Returns whether or not the IPv6 interface is up. 68 * 69 * @retval TRUE The IPv6 interface is enabled. 70 * @retval FALSE The IPv6 interface is disabled. 71 */ 72 virtual bool Ip6IsEnabled(void) const = 0; 73 74 /** 75 * Returns the Partition ID. 76 * 77 * @returns The Partition ID. 78 */ 79 virtual uint32_t GetPartitionId(void) const = 0; 80 81 /** 82 * Returns the active operational dataset tlvs. 83 * 84 * @param[out] aDatasetTlvs A reference to where the Active Operational Dataset will be placed. 85 */ 86 virtual void GetDatasetActiveTlvs(otOperationalDatasetTlvs &aDatasetTlvs) const = 0; 87 88 /** 89 * Returns the pending operational dataset tlvs. 90 * 91 * @param[out] aDatasetTlvs A reference to where the Pending Operational Dataset will be placed. 92 */ 93 virtual void GetDatasetPendingTlvs(otOperationalDatasetTlvs &aDatasetTlvs) const = 0; 94 95 /** 96 * The destructor. 97 */ 98 virtual ~NetworkProperties(void) = default; 99 }; 100 101 enum ThreadEnabledState 102 { 103 kStateDisabled = 0, 104 kStateEnabled = 1, 105 kStateDisabling = 2, 106 kStateInvalid = 255, 107 }; 108 109 /** 110 * This class is an interface which provides a set of async APIs to control the 111 * Thread network. 112 * 113 * The APIs are unified for both NCP and RCP cases. 114 */ 115 class ThreadHost : virtual public NetworkProperties 116 { 117 public: 118 using AsyncResultReceiver = std::function<void(otError, const std::string &)>; 119 using ChannelMasksReceiver = 120 std::function<void(uint32_t /*aSupportedChannelMask*/, uint32_t /*aPreferredChannelMask*/)>; 121 using DeviceRoleHandler = std::function<void(otError, otDeviceRole)>; 122 using ThreadStateChangedCallback = std::function<void(otChangedFlags aFlags)>; 123 using ThreadEnabledStateCallback = std::function<void(ThreadEnabledState aState)>; 124 125 struct ChannelMaxPower 126 { 127 uint16_t mChannel; 128 int16_t mMaxPower; // INT16_MAX indicates that the corresponding channel is disabled. 129 }; 130 131 /** 132 * Create a Thread Controller Instance. 133 * 134 * This is a factory method that will decide which implementation class will be created. 135 * 136 * @param[in] aInterfaceName A string of the Thread interface name. 137 * @param[in] aRadioUrls The radio URLs (can be IEEE802.15.4 or TREL radio). 138 * @param[in] aBackboneInterfaceName The Backbone network interface name. 139 * @param[in] aDryRun TRUE to indicate dry-run mode. FALSE otherwise. 140 * @param[in] aEnableAutoAttach Whether or not to automatically attach to the saved network. 141 * 142 * @returns Non-null OpenThread Controller instance. 143 */ 144 static std::unique_ptr<ThreadHost> Create(const char *aInterfaceName, 145 const std::vector<const char *> &aRadioUrls, 146 const char *aBackboneInterfaceName, 147 bool aDryRun, 148 bool aEnableAutoAttach); 149 150 /** 151 * This method joins this device to the network specified by @p aActiveOpDatasetTlvs. 152 * 153 * If there is an ongoing 'Join' operation, no action will be taken and @p aReceiver will be 154 * called after the request is completed. The previous @p aReceiver will also be called. 155 * 156 * @param[in] aActiveOpDatasetTlvs A reference to the active operational dataset of the Thread network. 157 * @param[in] aReceiver A receiver to get the async result of this operation. 158 */ 159 virtual void Join(const otOperationalDatasetTlvs &aActiveOpDatasetTlvs, const AsyncResultReceiver &aRecevier) = 0; 160 161 /** 162 * This method instructs the device to leave the current network gracefully. 163 * 164 * 1. If there is already an ongoing 'Leave' operation, no action will be taken and @p aReceiver 165 * will be called after the previous request is completed. The previous @p aReceiver will also 166 * be called. 167 * 2. If this device is not in disabled state, OTBR sends Address Release Notification (i.e. ADDR_REL.ntf) 168 * to gracefully detach from the current network and it takes 1 second to finish. 169 * 3. Then Operational Dataset will be removed from persistent storage if @p aEraseDataset is true. 170 * 4. If everything goes fine, @p aReceiver will be invoked with OT_ERROR_NONE. Otherwise, other errors 171 * will be passed to @p aReceiver when the error happens. 172 * 173 * @param[in] aReceiver A receiver to get the async result of this operation. 174 */ 175 virtual void Leave(bool aEraseDataset, const AsyncResultReceiver &aRecevier) = 0; 176 177 /** 178 * This method migrates this device to the new network specified by @p aPendingOpDatasetTlvs. 179 * 180 * @param[in] aPendingOpDatasetTlvs A reference to the pending operational dataset of the Thread network. 181 * @param[in] aReceiver A receiver to get the async result of this operation. 182 */ 183 virtual void ScheduleMigration(const otOperationalDatasetTlvs &aPendingOpDatasetTlvs, 184 const AsyncResultReceiver aReceiver) = 0; 185 186 /** 187 * This method enables/disables the Thread network. 188 * 189 * 1. If there is an ongoing 'SetThreadEnabled' operation, no action will be taken and @p aReceiver 190 * will be invoked with error OT_ERROR_BUSY. 191 * 2. If the host hasn't been initialized, @p aReceiver will be invoked with error OT_ERROR_INVALID_STATE. 192 * 3. When @p aEnabled is false, this method will first trigger a graceful detach and then disable Thread 193 * network interface and the stack. 194 * 195 * @param[in] aEnabled true to enable and false to disable. 196 * @param[in] aReceiver A receiver to get the async result of this operation. 197 */ 198 virtual void SetThreadEnabled(bool aEnabled, const AsyncResultReceiver aReceiver) = 0; 199 200 /** 201 * This method sets the country code. 202 * 203 * The country code refers to the 2-alpha code defined in ISO-3166. 204 * 205 * 1. If @p aCountryCode isn't valid, @p aReceiver will be invoked with error OT_ERROR_INVALID_ARGS. 206 * 2. If the host hasn't been initialized, @p aReceiver will be invoked with error OT_ERROR_INVALID_STATE. 207 * 208 * @param[in] aCountryCode The country code. 209 */ 210 virtual void SetCountryCode(const std::string &aCountryCode, const AsyncResultReceiver &aReceiver) = 0; 211 212 /** 213 * Gets the supported and preferred channel masks. 214 * 215 * If the operation succeeded, @p aReceiver will be invoked with the supported and preferred channel masks. 216 * Otherwise, @p aErrReceiver will be invoked with the error and @p aReceiver won't be invoked in this case. 217 * 218 * @param aReceiver A receiver to get the channel masks. 219 * @param aErrReceiver A receiver to get the error if the operation fails. 220 */ 221 virtual void GetChannelMasks(const ChannelMasksReceiver &aReceiver, const AsyncResultReceiver &aErrReceiver) = 0; 222 223 #if OTBR_ENABLE_POWER_CALIBRATION 224 /** 225 * Sets the max power of each channel. 226 * 227 * 1. If the host hasn't been initialized, @p aReceiver will be invoked with error OT_ERROR_INVALID_STATE. 228 * 2. If any value in @p aChannelMaxPowers is invalid, @p aReceiver will be invoked with error 229 * OT_ERROR_INVALID_ARGS. 230 * 231 * @param[in] aChannelMaxPowers A vector of ChannelMaxPower. 232 * @param[in] aReceiver A receiver to get the async result of this operation. 233 */ 234 virtual void SetChannelMaxPowers(const std::vector<ChannelMaxPower> &aChannelMaxPowers, 235 const AsyncResultReceiver &aReceiver) = 0; 236 #endif 237 238 /** 239 * This method adds a event listener for Thread state changes. 240 * 241 * @param[in] aCallback The callback to receive Thread state changed events. 242 */ 243 virtual void AddThreadStateChangedCallback(ThreadStateChangedCallback aCallback) = 0; 244 245 /** 246 * This method adds a event listener for Thread Enabled state changes. 247 * 248 * @param[in] aCallback The callback to receive Thread Enabled state changed events. 249 */ 250 virtual void AddThreadEnabledStateChangedCallback(ThreadEnabledStateCallback aCallback) = 0; 251 252 /** 253 * Returns the co-processor type. 254 */ 255 virtual CoprocessorType GetCoprocessorType(void) = 0; 256 257 /** 258 * Returns the co-processor version string. 259 */ 260 virtual const char *GetCoprocessorVersion(void) = 0; 261 262 /** 263 * This method returns the Thread network interface name. 264 * 265 * @returns A pointer to the Thread network interface name string. 266 */ 267 virtual const char *GetInterfaceName(void) const = 0; 268 269 /** 270 * Initializes the Thread controller. 271 */ 272 virtual void Init(void) = 0; 273 274 /** 275 * Deinitializes the Thread controller. 276 */ 277 virtual void Deinit(void) = 0; 278 279 /** 280 * The destructor. 281 */ 282 virtual ~ThreadHost(void) = default; 283 }; 284 285 } // namespace Host 286 } // namespace otbr 287 288 #endif // OTBR_AGENT_THREAD_HOST_HPP_ 289