GenericGap.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2017-2017 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef MBED_BLE_GENERIC_GAP
00018 #define MBED_BLE_GENERIC_GAP
00019 
00020 #include <algorithm>
00021 
00022 #include "ble/BLE.h"
00023 #include "ble/BLEProtocol.h"
00024 #include "ble/Gap.h"
00025 #include "ble/pal/PalGap.h"
00026 #include "ble/pal/PalSecurityManager.h"
00027 #include "ble/pal/GapEvents.h"
00028 #include "ble/pal/GapTypes.h"
00029 #include "ble/BLETypes.h"
00030 #include "ble/pal/GenericAccessService.h"
00031 #include "ble/pal/EventQueue.h"
00032 #include "ble/pal/ConnectionEventMonitor.h"
00033 
00034 #include "drivers/Timeout.h"
00035 
00036 namespace ble {
00037 namespace generic {
00038 /**
00039  * Generic implementation of the Gap class.
00040  * It requires a pal::Gap and a pal::GenericAccessService injected at
00041  * construction site.
00042  *
00043  * @attention: Not part of the public interface of BLE API.
00044  */
00045 class GenericGap : public ::Gap,
00046                    public pal::ConnectionEventMonitor,
00047                    public pal::Gap::EventHandler {
00048 
00049 public:
00050     /**
00051      * Construct a GenericGap instance for a given BLE instance ID.
00052      *
00053      * @param ble_instance_id Id of the BLE instance using this instance.
00054      *
00055      * @param pal_gap GAP Platform abstraction instance containing the base GAP
00056      * primitives.
00057      *
00058      * @param generic_access_service Platform abstraction instance managing
00059      * the GATT generic access service.
00060      * 
00061      * @param pal_sm Security Manager Platform abstraction instance containing the base
00062      * Security Manager primitives.
00063      */
00064     GenericGap(
00065         pal::EventQueue &event_queue,
00066         pal::Gap &pal_gap,
00067         pal::GenericAccessService &generic_access_service,
00068         pal::SecurityManager &pal_sm
00069     );
00070 
00071     /**
00072      * @see Gap::~Gap
00073      */
00074     virtual ~GenericGap ();
00075 
00076     /**
00077      * @see Gap::setAddress
00078      */
00079     virtual ble_error_t setAddress (
00080         BLEProtocol::AddressType_t type,
00081         const BLEProtocol::AddressBytes_t address
00082     );
00083 
00084     /**
00085      * @see Gap::getAddress
00086      */
00087     virtual ble_error_t getAddress (
00088         BLEProtocol::AddressType_t *type,
00089         BLEProtocol::AddressBytes_t address
00090     );
00091 
00092     /**
00093      * @see Gap::getMinAdvertisingInterval
00094      */
00095     virtual uint16_t getMinAdvertisingInterval () const;
00096 
00097     /**
00098      * @see Gap::getMinNonConnectableAdvertisingInterval
00099      */
00100     virtual uint16_t getMinNonConnectableAdvertisingInterval () const;
00101 
00102     /**
00103      * @see Gap::getMaxAdvertisingInterval
00104      */
00105     virtual uint16_t getMaxAdvertisingInterval () const;
00106 
00107     /**
00108      * @see Gap::stopAdvertising
00109      */
00110     virtual ble_error_t stopAdvertising ();
00111 
00112     /**
00113      * @see Gap::stopScan
00114      */
00115     virtual ble_error_t stopScan ();
00116 
00117     /**
00118      * @see Gap::connect
00119      */
00120     virtual ble_error_t connect (
00121         const BLEProtocol::AddressBytes_t peerAddr,
00122         PeerAddressType_t peerAddrType,
00123         const ConnectionParams_t *connectionParams,
00124         const GapScanningParams *scanParams
00125     );
00126 
00127     /**
00128      * @see Gap::connect
00129      */
00130     virtual ble_error_t connect (
00131         const BLEProtocol::AddressBytes_t peerAddr,
00132         BLEProtocol::AddressType_t peerAddrType,
00133         const ConnectionParams_t *connectionParams,
00134         const GapScanningParams *scanParams
00135     );
00136 
00137     /**
00138      * @see Gap::readPhy
00139      */
00140     virtual ble_error_t readPhy (Handle_t connection);
00141 
00142     /**
00143     * @see Gap::setPreferredPhys
00144     */
00145     virtual ble_error_t setPreferredPhys (
00146        const phy_set_t* txPhys,
00147        const phy_set_t* rxPhys
00148     );
00149 
00150     /**
00151     * @see Gap::setPhy
00152     */
00153     virtual ble_error_t setPhy (
00154        Handle_t connection,
00155        const phy_set_t* txPhys,
00156        const phy_set_t* rxPhys,
00157        CodedSymbolPerBit_t codedSymbol
00158     );
00159 
00160     /**
00161      * @see Gap::disconnect
00162      */
00163     virtual ble_error_t disconnect (
00164         Handle_t connectionHandle,
00165         DisconnectionReason_t reason
00166     );
00167 
00168     /**
00169      * @see Gap::updateConnectionParams
00170      */
00171     virtual ble_error_t updateConnectionParams (
00172         Handle_t handle,
00173         const ConnectionParams_t *params
00174     );
00175 
00176     /**
00177      * @see Gap::getPreferredConnectionParams
00178      */
00179     virtual ble_error_t getPreferredConnectionParams (
00180         ConnectionParams_t *params
00181     );
00182 
00183     /**
00184      * @see Gap::setPreferredConnectionParams
00185      */
00186     virtual ble_error_t setPreferredConnectionParams (
00187         const ConnectionParams_t *params
00188     );
00189 
00190     /**
00191      * @see Gap::setDeviceName
00192      */
00193     virtual ble_error_t setDeviceName (const uint8_t *deviceName);
00194 
00195     /**
00196      * @see Gap::getDeviceName
00197      */
00198     virtual ble_error_t getDeviceName (uint8_t *deviceName, unsigned *lengthP);
00199 
00200     /**
00201      * @see Gap::setAppearance
00202      */
00203     virtual ble_error_t setAppearance (GapAdvertisingData::Appearance appearance);
00204 
00205     /**
00206      * @see Gap::getAppearance
00207      */
00208     virtual ble_error_t getAppearance (GapAdvertisingData::Appearance *appearanceP);
00209 
00210     /**
00211      * @see Gap::setTxPower
00212      */
00213     virtual ble_error_t setTxPower (int8_t txPower);
00214 
00215     /**
00216      * @see Gap::getPermittedTxPowerValues
00217      */
00218     virtual void getPermittedTxPowerValues (const int8_t **valueArrayPP, size_t *countP);
00219 
00220     /**
00221      * @see Gap::getMaxWhitelistSize
00222      */
00223     virtual uint8_t getMaxWhitelistSize (void) const;
00224 
00225     /**
00226      * @see Gap::getWhitelist
00227      */
00228     virtual ble_error_t getWhitelist (Whitelist_t &whitelist) const;
00229 
00230     /**
00231      * @see Gap::setWhitelist
00232      */
00233     virtual ble_error_t setWhitelist (const Whitelist_t &whitelist);
00234 
00235     /**
00236      * @see Gap::setAdvertisingPolicyMode
00237      */
00238     virtual ble_error_t setAdvertisingPolicyMode (AdvertisingPolicyMode_t mode);
00239 
00240     /**
00241      * @see Gap::setScanningPolicyMode
00242      */
00243     virtual ble_error_t setScanningPolicyMode (ScanningPolicyMode_t mode);
00244 
00245     /**
00246      * @see Gap::setInitiatorPolicyMode
00247      */
00248     virtual ble_error_t setInitiatorPolicyMode (InitiatorPolicyMode_t mode);
00249 
00250     /**
00251      * @see Gap::getAdvertisingPolicyMode
00252      */
00253     virtual AdvertisingPolicyMode_t getAdvertisingPolicyMode (void) const;
00254 
00255     /**
00256      * @see Gap::getScanningPolicyMode
00257      */
00258     virtual ScanningPolicyMode_t getScanningPolicyMode (void) const;
00259 
00260     /**
00261      * @see Gap::getInitiatorPolicyMode
00262      */
00263     virtual InitiatorPolicyMode_t getInitiatorPolicyMode (void) const;
00264 
00265     /**
00266      * @see Gap::startRadioScan
00267      */
00268     virtual ble_error_t startRadioScan (const GapScanningParams &scanningParams);
00269 
00270     /**
00271      * @see Gap::initRadioNotification
00272      */
00273     virtual ble_error_t initRadioNotification (void);
00274 
00275     /**
00276      * @see Gap::enablePrivacy
00277      */
00278     virtual ble_error_t enablePrivacy (bool enable);
00279 
00280     /**
00281      * @see Gap::setPeripheralPrivacyConfiguration
00282      */
00283     virtual ble_error_t setPeripheralPrivacyConfiguration (
00284         const PeripheralPrivacyConfiguration_t *configuration
00285     );
00286 
00287     /**
00288      * @see Gap::getPeripheralPrivacyConfiguration
00289      */
00290     virtual ble_error_t getPeripheralPrivacyConfiguration (
00291         PeripheralPrivacyConfiguration_t *configuration
00292     );
00293 
00294     /**
00295      * @see Gap::setCentralPrivacyConfiguration
00296      */
00297     virtual ble_error_t setCentralPrivacyConfiguration (
00298         const CentralPrivacyConfiguration_t *configuration
00299     );
00300 
00301     /**
00302      * @see Gap::getCentralPrivacyConfiguration
00303      */
00304     virtual ble_error_t getCentralPrivacyConfiguration (
00305         CentralPrivacyConfiguration_t *configuration
00306     );
00307 
00308     /**
00309      * @see Gap::setAdvertisingData
00310      */
00311     virtual ble_error_t setAdvertisingData (
00312         const GapAdvertisingData &advData,
00313         const GapAdvertisingData &scanResponse
00314     );
00315 
00316     /**
00317      * @see Gap::startAdvertising
00318      */
00319     virtual ble_error_t startAdvertising(const GapAdvertisingParams &params);
00320 
00321     /**
00322      * @see Gap::reset
00323      */
00324     virtual ble_error_t reset (void);
00325 
00326     /**
00327      * @copydoc ::Gap::processConnectionEvent
00328      */
00329     void processConnectionEvent (
00330         Handle_t handle,
00331         Role_t role,
00332         peer_address_type_t peerAddrType,
00333         const BLEProtocol::AddressBytes_t peerAddr,
00334         BLEProtocol::AddressType_t ownAddrType,
00335         const BLEProtocol::AddressBytes_t ownAddr,
00336         const ConnectionParams_t *connectionParams,
00337         const uint8_t *peerResolvableAddr,
00338         const uint8_t *localResolvableAddr
00339     );
00340 
00341     /**
00342      * @copydoc ::Gap::processDisconnectionEvent
00343      */
00344     void processDisconnectionEvent (
00345         Handle_t handle,
00346         DisconnectionReason_t reason
00347     );
00348 
00349 private:
00350     /** @note Implements ConnectionEventMonitor.
00351      *  @copydoc ConnectionEventMonitor::set_connection_event_handler
00352      */
00353     void set_connection_event_handler(pal::ConnectionEventMonitor::EventHandler *_connection_event_handler);
00354 
00355     void on_scan_timeout();
00356 
00357     void process_scan_timeout();
00358 
00359     void on_advertising_timeout();
00360 
00361     void process_advertising_timeout();
00362 
00363     void on_gap_event_received(const pal::GapEvent &e);
00364 
00365     void on_advertising_report(const pal::GapAdvertisingReportEvent &e);
00366 
00367     void on_connection_complete(const pal::GapConnectionCompleteEvent &e);
00368 
00369     void on_disconnection_complete(const pal::GapDisconnectionCompleteEvent &e);
00370 
00371     void on_connection_parameter_request(
00372         const pal::GapRemoteConnectionParameterRequestEvent &e
00373     );
00374 
00375     void on_connection_update(const pal::GapConnectionUpdateEvent &e);
00376 
00377     void on_unexpected_error(const pal::GapUnexpectedErrorEvent &e);
00378 
00379     enum AddressUseType_t {
00380         CENTRAL_CONNECTION,
00381         CENTRAL_SCAN,
00382         PERIPHERAL_CONNECTABLE,
00383         PERIPHERAL_NON_CONNECTABLE
00384     };
00385 
00386     pal::own_address_type_t get_own_address_type(AddressUseType_t address_use_type);
00387 
00388     bool initialize_whitelist() const;
00389 
00390     ble_error_t update_address_resolution_setting();
00391 
00392     void set_random_address_rotation(bool enable);
00393 
00394     void update_random_address();
00395 
00396     void on_address_rotation_timeout();
00397 
00398     /* implements pal::Gap::EventHandler */
00399 private:
00400     virtual void on_read_phy(
00401         pal::hci_error_code_t hci_status,
00402         Handle_t connection_handle,
00403         ble::phy_t tx_phy,
00404         ble::phy_t rx_phy
00405     );
00406 
00407     virtual void on_phy_update_complete(
00408         pal::hci_error_code_t hci_status,
00409         Handle_t connection_handle,
00410         ble::phy_t tx_phy,
00411         ble::phy_t rx_phy
00412     );
00413 
00414 private:
00415     pal::EventQueue& _event_queue;
00416     pal::Gap &_pal_gap;
00417     pal::GenericAccessService &_gap_service;
00418     pal::SecurityManager &_pal_sm;
00419     BLEProtocol::AddressType_t _address_type;
00420     ble::address_t _address;
00421     pal::initiator_policy_t _initiator_policy_mode;
00422     pal::scanning_filter_policy_t _scanning_filter_policy;
00423     pal::advertising_filter_policy_t _advertising_filter_policy;
00424     mutable Whitelist_t _whitelist;
00425     
00426     bool _privacy_enabled;
00427     PeripheralPrivacyConfiguration_t _peripheral_privacy_configuration;
00428     CentralPrivacyConfiguration_t _central_privacy_configuration;
00429     ble::address_t _random_static_identity_address;
00430     bool _random_address_rotating;
00431     
00432     mbed::Timeout _advertising_timeout;
00433     mbed::Timeout _scan_timeout;
00434     mbed::Ticker _address_rotation_ticker;
00435     pal::ConnectionEventMonitor::EventHandler *_connection_event_handler;
00436 };
00437 
00438 }
00439 }
00440 
00441 #endif /* MBED_BLE_GENERIC_GAP */