1 /* 2 * Copyright (c) 2017, 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 for NCP service. 32 */ 33 34 #ifndef OTBR_AGENT_NCP_OPENTHREAD_HPP_ 35 #define OTBR_AGENT_NCP_OPENTHREAD_HPP_ 36 37 #include "openthread-br/config.h" 38 39 #include <chrono> 40 #include <memory> 41 42 #include <assert.h> 43 44 #include <openthread/backbone_router_ftd.h> 45 #include <openthread/cli.h> 46 #include <openthread/instance.h> 47 #include <openthread/openthread-system.h> 48 49 #include "common/mainloop.hpp" 50 #include "common/task_runner.hpp" 51 #include "common/types.hpp" 52 #include "utils/thread_helper.hpp" 53 54 namespace otbr { 55 #if OTBR_ENABLE_FEATURE_FLAGS 56 // Forward declaration of FeatureFlagList proto. 57 class FeatureFlagList; 58 #endif 59 60 namespace Ncp { 61 62 /** 63 * This interface defines NCP Controller functionality. 64 * 65 */ 66 class ControllerOpenThread : public MainloopProcessor 67 { 68 public: 69 using ThreadStateChangedCallback = std::function<void(otChangedFlags aFlags)>; 70 71 /** 72 * This constructor initializes this object. 73 * 74 * @param[in] aInterfaceName A string of the NCP interface name. 75 * @param[in] aRadioUrls The radio URLs (can be IEEE802.15.4 or TREL radio). 76 * @param[in] aBackboneInterfaceName The Backbone network interface name. 77 * @param[in] aDryRun TRUE to indicate dry-run mode. FALSE otherwise. 78 * @param[in] aEnableAutoAttach Whether or not to automatically attach to the saved network. 79 * 80 */ 81 ControllerOpenThread(const char *aInterfaceName, 82 const std::vector<const char *> &aRadioUrls, 83 const char *aBackboneInterfaceName, 84 bool aDryRun, 85 bool aEnableAutoAttach); 86 87 /** 88 * This method initialize the NCP controller. 89 * 90 */ 91 void Init(void); 92 93 /** 94 * This method deinitialize the NCP controller. 95 * 96 */ 97 void Deinit(void); 98 99 /** 100 * Returns an OpenThread instance. 101 * 102 * @retval Non-null OpenThread instance if `ControllerOpenThread::Init()` has been called. 103 * Otherwise, it's guaranteed to be `null` 104 */ GetInstance(void)105 otInstance *GetInstance(void) { return mInstance; } 106 107 /** 108 * This method gets the thread functionality helper. 109 * 110 * @retval The pointer to the helper object. 111 * 112 */ GetThreadHelper(void)113 otbr::agent::ThreadHelper *GetThreadHelper(void) 114 { 115 assert(mThreadHelper != nullptr); 116 return mThreadHelper.get(); 117 } 118 119 void Update(MainloopContext &aMainloop) override; 120 void Process(const MainloopContext &aMainloop) override; 121 122 /** 123 * This method posts a task to the timer 124 * 125 * @param[in] aDelay The delay in milliseconds before executing the task. 126 * @param[in] aTask The task function. 127 * 128 */ 129 void PostTimerTask(Milliseconds aDelay, TaskRunner::Task<void> aTask); 130 131 /** 132 * This method registers a reset handler. 133 * 134 * @param[in] aHandler The handler function. 135 * 136 */ 137 void RegisterResetHandler(std::function<void(void)> aHandler); 138 139 /** 140 * This method adds a event listener for Thread state changes. 141 * 142 * @param[in] aCallback The callback to receive Thread state changed events. 143 * 144 */ 145 void AddThreadStateChangedCallback(ThreadStateChangedCallback aCallback); 146 147 /** 148 * This method resets the OpenThread instance. 149 * 150 */ 151 void Reset(void); 152 153 /** 154 * This method returns the Thread protocol version as a string. 155 * 156 * @returns A pointer to the Thread version string. 157 * 158 */ 159 static const char *GetThreadVersion(void); 160 161 /** 162 * This method returns the Thread network interface name. 163 * 164 * @returns A pointer to the Thread network interface name string. 165 * 166 */ GetInterfaceName(void) const167 const char *GetInterfaceName(void) const { return mConfig.mInterfaceName; } 168 169 static otbrLogLevel ConvertToOtbrLogLevel(otLogLevel aLogLevel); 170 171 #if OTBR_ENABLE_FEATURE_FLAGS 172 /** 173 * Apply the feature flag values to OpenThread through OpenThread APIs. 174 * 175 * @param[in] aFeatureFlagList The feature flag list to be applied to OpenThread. 176 * 177 * @returns The error value of underlying OpenThread API calls. 178 * 179 */ 180 otError ApplyFeatureFlagList(const FeatureFlagList &aFeatureFlagList); 181 182 /** 183 * This method returns the applied FeatureFlagList in ApplyFeatureFlagList call. 184 * 185 * @returns the applied FeatureFlagList's serialized bytes. 186 * 187 */ GetAppliedFeatureFlagListBytes(void)188 const std::string &GetAppliedFeatureFlagListBytes(void) 189 { 190 return mAppliedFeatureFlagListBytes; 191 } 192 #endif 193 194 ~ControllerOpenThread(void) override; 195 196 private: HandleStateChanged(otChangedFlags aFlags,void * aContext)197 static void HandleStateChanged(otChangedFlags aFlags, void *aContext) 198 { 199 static_cast<ControllerOpenThread *>(aContext)->HandleStateChanged(aFlags); 200 } 201 void HandleStateChanged(otChangedFlags aFlags); 202 203 static void HandleBackboneRouterDomainPrefixEvent(void *aContext, 204 otBackboneRouterDomainPrefixEvent aEvent, 205 const otIp6Prefix *aDomainPrefix); 206 void HandleBackboneRouterDomainPrefixEvent(otBackboneRouterDomainPrefixEvent aEvent, 207 const otIp6Prefix *aDomainPrefix); 208 209 #if OTBR_ENABLE_DUA_ROUTING 210 static void HandleBackboneRouterNdProxyEvent(void *aContext, 211 otBackboneRouterNdProxyEvent aEvent, 212 const otIp6Address *aAddress); 213 void HandleBackboneRouterNdProxyEvent(otBackboneRouterNdProxyEvent aEvent, const otIp6Address *aAddress); 214 #endif 215 216 bool IsAutoAttachEnabled(void); 217 void DisableAutoAttach(void); 218 219 static otLogLevel ConvertToOtLogLevel(otbrLogLevel aLevel); 220 221 otError SetOtbrAndOtLogLevel(otbrLogLevel aLevel); 222 223 otInstance *mInstance; 224 225 otPlatformConfig mConfig; 226 std::unique_ptr<otbr::agent::ThreadHelper> mThreadHelper; 227 std::vector<std::function<void(void)>> mResetHandlers; 228 TaskRunner mTaskRunner; 229 std::vector<ThreadStateChangedCallback> mThreadStateChangedCallbacks; 230 bool mEnableAutoAttach = false; 231 #if OTBR_ENABLE_FEATURE_FLAGS 232 // The applied FeatureFlagList in ApplyFeatureFlagList call, used for debugging purpose. 233 std::string mAppliedFeatureFlagListBytes; 234 #endif 235 }; 236 237 } // namespace Ncp 238 } // namespace otbr 239 240 #endif // OTBR_AGENT_NCP_OPENTHREAD_HPP_ 241