Line data    Source code

       1             : /*
       2             :  *
       3             :  *    Copyright (c) 2020 Project CHIP Authors
       4             :  *    All rights reserved.
       5             :  *
       6             :  *    Licensed under the Apache License, Version 2.0 (the "License");
       7             :  *    you may not use this file except in compliance with the License.
       8             :  *    You may obtain a copy of the License at
       9             :  *
      10             :  *        http://www.apache.org/licenses/LICENSE-2.0
      11             :  *
      12             :  *    Unless required by applicable law or agreed to in writing, software
      13             :  *    distributed under the License is distributed on an "AS IS" BASIS,
      14             :  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      15             :  *    See the License for the specific language governing permissions and
      16             :  *    limitations under the License.
      17             :  */
      18             : 
      19             : /**
      20             :  *    @file
      21             :  *      This file defines the CHIP Connection object that maintains a BLE connection.
      22             :  *
      23             :  */
      24             : 
      25             : #pragma once
      26             : 
      27             : #include <ble/BleConfig.h>
      28             : 
      29             : #include <utility>
      30             : 
      31             : #include <ble/BleError.h>
      32             : #include <ble/BleLayer.h>
      33             : #include <lib/core/CHIPCore.h>
      34             : #include <lib/support/DLLUtil.h>
      35             : #include <system/SystemPacketBuffer.h>
      36             : #include <transport/raw/Base.h>
      37             : 
      38             : namespace chip {
      39             : namespace Transport {
      40             : 
      41             : /** Defines listening parameters for setting up a BLE transport */
      42             : class BleListenParameters
      43             : {
      44             : public:
      45           1 :     explicit BleListenParameters(Ble::BleLayer * layer) : mLayer(layer) {}
      46             :     BleListenParameters(const BleListenParameters &) = default;
      47             :     BleListenParameters(BleListenParameters &&)      = default;
      48             : 
      49           1 :     Ble::BleLayer * GetBleLayer() const { return mLayer; }
      50             : 
      51             :     /**
      52             :      * PreserveExistingBleLayerTransport controls whether the BleBase transport
      53             :      * initialized with these parameters should update the global BleLayer transport
      54             :      * if it is already set.
      55             :      *
      56             :      * This is relevant when there is more than one TransportMgr,
      57             :      * for example, when a device is both a commissioner (has a CHIPDeviceController)
      58             :      * and a commissionee (has a Server) since each TransportMgr will have a BleBase
      59             :      * which can override the global BleLayer transport to point to itself.
      60             :      *
      61             :      * The default value is true - don't override the global BleLayer transport if it is
      62             :      * already set. In other words, the first BleBase to initialize (eg. Server) will be
      63             :      * the active BleBase transport, and the second BleBase to initialize (eg. CHIPDeviceController)
      64             :      * will need to call BleBase.SetBleLayerTransportToSelf if it needs to commission using BLE.
      65             :      *
      66             :      * Call SetPreserveExistingBleLayerTransport(false) to set the global
      67             :      * BleLayer transport to the BleBase created with these parameters, even if it is already
      68             :      * set to another BleBase.
      69             :      *
      70             :      * Use the BleBase.IsBleLayerTransportSetToSelf() and BleBase.SetBleLayerTransportToSelf
      71             :      * methods to toggle between BleBase transports when there is more than one.
      72             :      */
      73           0 :     bool PreserveExistingBleLayerTransport() const { return mPreserveExistingBleLayerTransport; }
      74             :     BleListenParameters & SetPreserveExistingBleLayerTransport(bool preserveExistingBleLayerTransport)
      75             :     {
      76             :         mPreserveExistingBleLayerTransport = preserveExistingBleLayerTransport;
      77             : 
      78             :         return *this;
      79             :     }
      80             : 
      81             : private:
      82             :     Ble::BleLayer * mLayer;
      83             :     bool mPreserveExistingBleLayerTransport = true;
      84             : };
      85             : 
      86             : /** Implements a transport using BLE.
      87             :  *
      88             :  *  TODO: BLE transport currently only allow one BLE connection, neet to clearify if we should support multiple BLE connections.
      89             :  */
      90             : class DLL_EXPORT BLEBase : public Base, public Ble::BleLayerDelegate
      91             : {
      92             :     /**
      93             :      *  The State of the BLE connection
      94             :      *
      95             :      */
      96             :     enum class State
      97             :     {
      98             :         kNotReady    = 0, /**< State before initialization. */
      99             :         kInitialized = 1, /**< State after class is connected and ready. */
     100             :         kConnected   = 2, /**< Endpoint connected. */
     101             :     };
     102             : 
     103             : public:
     104           1 :     BLEBase(System::PacketBufferHandle * packetBuffers, size_t packetBuffersSize) :
     105           1 :         mPendingPackets(packetBuffers), mPendingPacketsSize(packetBuffersSize)
     106           1 :     {}
     107             :     ~BLEBase() override;
     108             : 
     109             :     /**
     110             :      * Initialize a BLE transport to a given peripheral or a given device name.
     111             :      *
     112             :      * @param param        BLE configuration parameters for this transport
     113             :      */
     114             :     CHIP_ERROR Init(const BleListenParameters & param);
     115             : 
     116             :     CHIP_ERROR SendMessage(const Transport::PeerAddress & address, System::PacketBufferHandle && msgBuf) override;
     117             : 
     118           0 :     bool CanSendToPeer(const Transport::PeerAddress & address) override
     119             :     {
     120           0 :         return (mState != State::kNotReady) && (address.GetTransportType() == Type::kBle);
     121             :     }
     122             : 
     123             :     CHIP_ERROR SetEndPoint(Ble::BLEEndPoint * endPoint) override;
     124             : 
     125             :     /**
     126             :      * Change BLE transport to this
     127             :      *
     128             :      * This is relevant when there is more than one TransportMgr,
     129             :      * for example, when a device is both a commissioner (has a CHIPDeviceController)
     130             :      * and a commissionee (has a Server) since each TransportMgr will set
     131             :      * the global BleLayer transport to point to itself.
     132             :      *
     133             :      * In this scenario, the device will need the ability to toggle between a
     134             :      * BleLayer transport for commissioner functionality and one for commissionee functionality.
     135             :      */
     136             :     void SetBleLayerTransportToSelf() { mBleLayer->mBleTransport = this; }
     137             :     bool IsBleLayerTransportSetToSelf() { return mBleLayer->mBleTransport == this; }
     138             : 
     139             : private:
     140             :     void ClearState();
     141             : 
     142             :     /**
     143             :      * Sends the specified message once a connection has been established.
     144             :      *
     145             :      * @param msg - what buffer to send once a connection has been established.
     146             :      *
     147             :      * Ownership of msg is taken over and will be freed at some unspecified time
     148             :      * in the future (once connection succeeds/fails).
     149             :      */
     150             :     CHIP_ERROR SendAfterConnect(System::PacketBufferHandle && msg);
     151             : 
     152             :     // Those functions are BLEConnectionDelegate callbacks used when the connection
     153             :     // parameters used a name instead of a BLE_CONNECTION_OBJECT.
     154             :     void OnBleConnectionComplete(Ble::BLEEndPoint * endPoint) override;
     155             :     void OnBleConnectionError(CHIP_ERROR err) override;
     156             : 
     157             :     void ClearPendingPackets();
     158             : 
     159             :     // Those functions are BLEEndPoint callbacks
     160             :     void OnEndPointMessageReceived(Ble::BLEEndPoint * endPoint, System::PacketBufferHandle && buffer) override;
     161             :     void OnEndPointConnectComplete(Ble::BLEEndPoint * endPoint, CHIP_ERROR err) override;
     162             :     void OnEndPointConnectionClosed(Ble::BLEEndPoint * endPoint, CHIP_ERROR err) override;
     163             : 
     164             :     Ble::BleLayer * mBleLayer       = nullptr;          ///< Associated ble layer
     165             :     State mState                    = State::kNotReady; ///< State of the BLE transport
     166             :     Ble::BLEEndPoint * mBleEndPoint = nullptr;          ///< BLE endpoint used by transport
     167             : 
     168             :     // Data to be sent when connections succeed
     169             :     System::PacketBufferHandle * mPendingPackets;
     170             :     const size_t mPendingPacketsSize;
     171             : };
     172             : 
     173             : template <size_t kPendingPacketSize>
     174             : class BLE : public BLEBase
     175             : {
     176             : public:
     177           2 :     BLE() : BLEBase(mPendingPackets, kPendingPacketSize) {}
     178             : 
     179             : private:
     180             :     System::PacketBufferHandle mPendingPackets[kPendingPacketSize];
     181             : };
     182             : 
     183             : } // namespace Transport
     184             : } // namespace chip