third_party/ot-br-posix/repo/src/agent/thread_helper.hpp

   1 /*
   2  *    Copyright (c) 2020, 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 Thread helper.
  32  */
  33
  34 #ifndef OTBR_THREAD_HELPER_HPP_
  35 #define OTBR_THREAD_HELPER_HPP_
  36
  37 #include <chrono>
  38 #include <functional>
  39 #include <map>
  40 #include <random>
  41 #include <string>
  42 #include <vector>
  43
  44 #include <openthread/instance.h>
  45 #include <openthread/ip6.h>
  46 #include <openthread/jam_detection.h>
  47 #include <openthread/joiner.h>
  48 #include <openthread/netdata.h>
  49 #include <openthread/thread.h>
  50
  51 #include "common/logging.hpp"
  52
  53 namespace otbr {
  54 namespace Ncp {
  55 class ControllerOpenThread;
  56 }
  57 } // namespace otbr
  58
  59 namespace otbr {
  60 namespace agent {
  61
  62 /**
  63  * This class implements Thread helper.
  64  */
  65 class ThreadHelper
  66 {
  67 public:
  68     using DeviceRoleHandler = std::function<void(otDeviceRole)>;
  69     using ScanHandler       = std::function<void(otError, const std::vector<otActiveScanResult> &)>;
  70     using ResultHandler     = std::function<void(otError)>;
  71
  72     /**
  73      * The constructor of a Thread helper.
  74      *
  75      * @param[in]   aInstance  The Thread instance.
  76      * @param[in]   aNcp       The ncp controller.
  77      *
  78      */
  79     ThreadHelper(otInstance *aInstance, otbr::Ncp::ControllerOpenThread *aNcp);
  80
  81     /**
  82      * This method adds a callback for device role change.
  83      *
  84      * @param[in]   aHandler  The device role handler.
  85      *
  86      */
  87     void AddDeviceRoleHandler(DeviceRoleHandler aHandler);
  88
  89     /**
  90      * This method permits unsecure join on port.
  91      *
  92      * @param[in]   aPort     The port number.
  93      * @param[in]   aSeconds  The timeout to close the port, 0 for never close.
  94      *
  95      * @returns The error value of underlying OpenThread api calls.
  96      *
  97      */
  98     otError PermitUnsecureJoin(uint16_t aPort, uint32_t aSeconds);
  99
 100     /**
 101      * This method performs a Thread network scan.
 102      *
 103      * @param[in]   aHandler  The scan result handler.
 104      *
 105      */
 106     void Scan(ScanHandler aHandler);
 107
 108     /**
 109      * This method attaches the device to the Thread network.
 110      *
 111      * @note The joiner start and the attach proccesses are exclusive
 112      *
 113      * @param[in]   aNetworkName    The network name.
 114      * @param[in]   aPanId          The pan id, UINT16_MAX for random.
 115      * @param[in]   aExtPanId       The extended pan id, UINT64_MAX for random.
 116      * @param[in]   aMasterKey      The master key, empty for random.
 117      * @param[in]   aPSKc           The pre-shared commissioner key, empty for random.
 118      * @param[in]   aChannelMask    A bitmask for valid channels, will random select one.
 119      * @param[in]   aHandler        The attach result handler.
 120      *
 121      */
 122     void Attach(const std::string &         aNetworkName,
 123                 uint16_t                    aPanId,
 124                 uint64_t                    aExtPanId,
 125                 const std::vector<uint8_t> &aMasterKey,
 126                 const std::vector<uint8_t> &aPSKc,
 127                 uint32_t                    aChannelMask,
 128                 ResultHandler               aHandler);
 129
 130     /**
 131      * This method attaches the device to the Thread network.
 132      *
 133      * @note The joiner start and the attach proccesses are exclusive, and the
 134      *       network parameter will be set through the active dataset.
 135      *
 136      * @param[in]   aHandler        The attach result handler.
 137      *
 138      */
 139     void Attach(ResultHandler aHandler);
 140
 141     /**
 142      * This method resets the OpenThread stack.
 143      *
 144      * @returns The error value of underlying OpenThread api calls.
 145      *
 146      */
 147     otError Reset(void);
 148
 149     /**
 150      * This method triggers a thread join process.
 151      *
 152      * @note The joiner start and the attach proccesses are exclusive
 153      *
 154      * @param[in]   aPskd             The pre-shared key for device.
 155      * @param[in]   aProvisioningUrl  The provision url.
 156      * @param[in]   aVendorName       The vendor name.
 157      * @param[in]   aVendorModel      The vendor model.
 158      * @param[in]   aVendorSwVersion  The vendor software version.
 159      * @param[in]   aVendorData       The vendor custom data.
 160      * @param[in]   aHandler          The join result handler.
 161      *
 162      */
 163     void JoinerStart(const std::string &aPskd,
 164                      const std::string &aProvisioningUrl,
 165                      const std::string &aVendorName,
 166                      const std::string &aVendorModel,
 167                      const std::string &aVendorSwVersion,
 168                      const std::string &aVendorData,
 169                      ResultHandler      aHandler);
 170
 171     /**
 172      * This method tries to restore the network after reboot
 173      *
 174      * @returns The error value of underlying OpenThread api calls.
 175      *
 176      */
 177     otError TryResumeNetwork(void);
 178
 179     /**
 180      * This method returns the underlying OpenThread instance.
 181      *
 182      * @returns The underlying instance.
 183      *
 184      */
 185     otInstance *GetInstance(void) { return mInstance; }
 186
 187     /**
 188      * This method handles OpenThread state changed notification.
 189      *
 190      * @param[in]  aFlags    A bit-field indicating specific state that has changed.  See `OT_CHANGED_*` definitions.
 191      *
 192      */
 193     void StateChangedCallback(otChangedFlags aFlags);
 194
 195     /**
 196      * This method logs OpenThread action result.
 197      *
 198      * @param[in] aAction   The action OpenThread performs.
 199      * @param[in] aError    The action result.
 200      *
 201      */
 202     static void LogOpenThreadResult(const char *aAction, otError aError)
 203     {
 204         otbrLog((aError == OT_ERROR_NONE ? OTBR_LOG_INFO : OTBR_LOG_WARNING), "%s: %s", aAction,
 205                 otThreadErrorToString(aError));
 206     }
 207
 208 private:
 209     static void sActiveScanHandler(otActiveScanResult *aResult, void *aThreadHelper);
 210     void        ActiveScanHandler(otActiveScanResult *aResult);
 211
 212     static void sJoinerCallback(otError aError, void *aThreadHelper);
 213     void        JoinerCallback(otError aResult);
 214
 215     void    RandomFill(void *aBuf, size_t size);
 216     uint8_t RandomChannelFromChannelMask(uint32_t aChannelMask);
 217
 218     otInstance *mInstance;
 219
 220     otbr::Ncp::ControllerOpenThread *mNcp;
 221
 222     ScanHandler                     mScanHandler;
 223     std::vector<otActiveScanResult> mScanResults;
 224
 225     std::vector<DeviceRoleHandler> mDeviceRoleHandlers;
 226
 227     std::map<uint16_t, std::chrono::steady_clock::time_point> mUnsecurePortCloseTime;
 228
 229     ResultHandler mAttachHandler;
 230     ResultHandler mJoinerHandler;
 231
 232     std::random_device mRandomDevice;
 233 };
 234
 235 } // namespace agent
 236 } // namespace otbr
 237
 238 #endif // OTBR_THREAD_HELPER_HPP_