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 Ncp { 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 /** 102 * This class is an interface which provides a set of async APIs to control the 103 * Thread network. 104 * 105 * The APIs are unified for both NCP and RCP cases. 106 */ 107 class ThreadHost : virtual public NetworkProperties 108 { 109 public: 110 using AsyncResultReceiver = std::function<void(otError, const std::string &)>; 111 using ChannelMasksReceiver = 112 std::function<void(uint32_t /*aSupportedChannelMask*/, uint32_t /*aPreferredChannelMask*/)>; 113 using DeviceRoleHandler = std::function<void(otError, otDeviceRole)>; 114 using ThreadStateChangedCallback = std::function<void(otChangedFlags aFlags)>; 115 116 struct ChannelMaxPower 117 { 118 uint16_t mChannel; 119 int16_t mMaxPower; // INT16_MAX indicates that the corresponding channel is disabled. 120 }; 121 122 /** 123 * Create a Thread Controller Instance. 124 * 125 * This is a factory method that will decide which implementation class will be created. 126 * 127 * @param[in] aInterfaceName A string of the Thread interface name. 128 * @param[in] aRadioUrls The radio URLs (can be IEEE802.15.4 or TREL radio). 129 * @param[in] aBackboneInterfaceName The Backbone network interface name. 130 * @param[in] aDryRun TRUE to indicate dry-run mode. FALSE otherwise. 131 * @param[in] aEnableAutoAttach Whether or not to automatically attach to the saved network. 132 * 133 * @returns Non-null OpenThread Controller instance. 134 */ 135 static std::unique_ptr<ThreadHost> Create(const char *aInterfaceName, 136 const std::vector<const char *> &aRadioUrls, 137 const char *aBackboneInterfaceName, 138 bool aDryRun, 139 bool aEnableAutoAttach); 140 141 /** 142 * This method joins this device to the network specified by @p aActiveOpDatasetTlvs. 143 * 144 * If there is an ongoing 'Join' operation, no action will be taken and @p aReceiver will be 145 * called after the request is completed. The previous @p aReceiver will also be called. 146 * 147 * @param[in] aActiveOpDatasetTlvs A reference to the active operational dataset of the Thread network. 148 * @param[in] aReceiver A receiver to get the async result of this operation. 149 */ 150 virtual void Join(const otOperationalDatasetTlvs &aActiveOpDatasetTlvs, const AsyncResultReceiver &aRecevier) = 0; 151 152 /** 153 * This method instructs the device to leave the current network gracefully. 154 * 155 * 1. If there is already an ongoing 'Leave' operation, no action will be taken and @p aReceiver 156 * will be called after the previous request is completed. The previous @p aReceiver will also 157 * be called. 158 * 2. If this device is not in disabled state, OTBR sends Address Release Notification (i.e. ADDR_REL.ntf) 159 * to gracefully detach from the current network and it takes 1 second to finish. 160 * 3. Then Operational Dataset will be removed from persistent storage. 161 * 4. If everything goes fine, @p aReceiver will be invoked with OT_ERROR_NONE. Otherwise, other errors 162 * will be passed to @p aReceiver when the error happens. 163 * 164 * @param[in] aReceiver A receiver to get the async result of this operation. 165 */ 166 virtual void Leave(const AsyncResultReceiver &aRecevier) = 0; 167 168 /** 169 * This method migrates this device to the new network specified by @p aPendingOpDatasetTlvs. 170 * 171 * @param[in] aPendingOpDatasetTlvs A reference to the pending operational dataset of the Thread network. 172 * @param[in] aReceiver A receiver to get the async result of this operation. 173 */ 174 virtual void ScheduleMigration(const otOperationalDatasetTlvs &aPendingOpDatasetTlvs, 175 const AsyncResultReceiver aReceiver) = 0; 176 177 /** 178 * This method enables/disables the Thread network. 179 * 180 * 1. If there is an ongoing 'SetThreadEnabled' operation, no action will be taken and @p aReceiver 181 * will be invoked with error OT_ERROR_BUSY. 182 * 2. If the host hasn't been initialized, @p aReceiver will be invoked with error OT_ERROR_INVALID_STATE. 183 * 3. When @p aEnabled is false, this method will first trigger a graceful detach and then disable Thread 184 * network interface and the stack. 185 * 186 * @param[in] aEnabled true to enable and false to disable. 187 * @param[in] aReceiver A receiver to get the async result of this operation. 188 */ 189 virtual void SetThreadEnabled(bool aEnabled, const AsyncResultReceiver aReceiver) = 0; 190 191 /** 192 * This method sets the country code. 193 * 194 * The country code refers to the 2-alpha code defined in ISO-3166. 195 * 196 * 1. If @p aCountryCode isn't valid, @p aReceiver will be invoked with error OT_ERROR_INVALID_ARGS. 197 * 2. If the host hasn't been initialized, @p aReceiver will be invoked with error OT_ERROR_INVALID_STATE. 198 * 199 * @param[in] aCountryCode The country code. 200 */ 201 virtual void SetCountryCode(const std::string &aCountryCode, const AsyncResultReceiver &aReceiver) = 0; 202 203 /** 204 * Gets the supported and preferred channel masks. 205 * 206 * If the operation succeeded, @p aReceiver will be invoked with the supported and preferred channel masks. 207 * Otherwise, @p aErrReceiver will be invoked with the error and @p aReceiver won't be invoked in this case. 208 * 209 * @param aReceiver A receiver to get the channel masks. 210 * @param aErrReceiver A receiver to get the error if the operation fails. 211 */ 212 virtual void GetChannelMasks(const ChannelMasksReceiver &aReceiver, const AsyncResultReceiver &aErrReceiver) = 0; 213 214 /** 215 * Sets the max power of each channel. 216 * 217 * 1. If the host hasn't been initialized, @p aReceiver will be invoked with error OT_ERROR_INVALID_STATE. 218 * 2. If any value in @p aChannelMaxPowers is invalid, @p aReceiver will be invoked with error 219 * OT_ERROR_INVALID_ARGS. 220 * 221 * @param[in] aChannelMaxPowers A vector of ChannelMaxPower. 222 * @param[in] aReceiver A receiver to get the async result of this operation. 223 */ 224 virtual void SetChannelMaxPowers(const std::vector<ChannelMaxPower> &aChannelMaxPowers, 225 const AsyncResultReceiver &aReceiver) = 0; 226 227 /** 228 * This method adds a event listener for Thread state changes. 229 * 230 * @param[in] aCallback The callback to receive Thread state changed events. 231 */ 232 virtual void AddThreadStateChangedCallback(ThreadStateChangedCallback aCallback) = 0; 233 234 /** 235 * Returns the co-processor type. 236 */ 237 virtual CoprocessorType GetCoprocessorType(void) = 0; 238 239 /** 240 * Returns the co-processor version string. 241 */ 242 virtual const char *GetCoprocessorVersion(void) = 0; 243 244 /** 245 * This method returns the Thread network interface name. 246 * 247 * @returns A pointer to the Thread network interface name string. 248 */ 249 virtual const char *GetInterfaceName(void) const = 0; 250 251 /** 252 * Initializes the Thread controller. 253 */ 254 virtual void Init(void) = 0; 255 256 /** 257 * Deinitializes the Thread controller. 258 */ 259 virtual void Deinit(void) = 0; 260 261 /** 262 * The destructor. 263 */ 264 virtual ~ThreadHost(void) = default; 265 }; 266 267 } // namespace Ncp 268 } // namespace otbr 269 270 #endif // OTBR_AGENT_THREAD_HOST_HPP_ 271