Merge pull request #1 from pan-/PHY_API

Phy api

Author: pan-

features/FEATURE_BLE/ble/BLETypes.h

@@ -572,6 +572,110 @@ struct peer_address_type_t :SafeEnum<peer_address_type_t, uint8_t> {
         SafeEnum<peer_address_type_t, uint8_t>(PUBLIC) { }
 };
 
+/**
+ * Type that describes a bluetooth PHY(sical) transport.
+ */
+struct phy_t : SafeEnum<phy_t, uint8_t> {
+    /** struct scoped enum wrapped by the class */
+    enum type {
+        /**
+         * 1Mbit/s LE.
+         *
+         * @note This physical transport was available since Bluetooth 4.0
+         */
+        LE_1M = 1,
+
+        /**
+         * 2Mbit/s LE.
+         *
+         * Modulation is similar to LE_1M but differs in rate. Therefore range
+         * performances are in the same ballpark as LE_1M while the increased rate
+         * minimize time spent to transfer or receive a packet which leads to a
+         * better power consumption and/or faster transfer.
+         *
+         * @note This transport has been introduced with the Bluetooth 5.
+         * @note When operating at 2Mbit/s range is not exactly identical to the
+         * range at 1Mbit/s due to a loss in sensitivity.
+         */
+        LE_2M = 2,
+
+        /**
+         * LE Coded PHY.
+         *
+         * This transport reuse the 1Mbit/s channel with different coding schemes.
+         * Either two (S=2) or eight (S=8) symbols can be used to represent a
+         * bit while the 1Mbit/s transport use 1 symbol to code 1 bit of data.
+         *
+         * Here is the data rate of the two coding schemes:
+         *   - S=2: 500kbit/s
+         *   - S=8: 125kbit/s
+         *
+         * The goal of the coded PHY is to increase the range of BLE devices.
+         * Of course given it takes more time to transfer data, transmission
+         * and reception last longer which leads to an increase in power
+         * consumption.
+         *
+         * @note This transport has been introduced with the Bluetooth 5.
+         */
+        LE_CODED
+    };
+
+    /**
+     * Construct a new instance of phy_t.
+     */
+    phy_t(type value) :
+        SafeEnum<phy_t, uint8_t>(value) { }
+};
+
+/**
+ * Type that describe a set of PHY(sical) transports.
+ */
+struct phys_t {
+    /**
+     * If equal to 1 then the set includes phy_t::LE_1M.
+     */
+    uint8_t le_1m:1;
+
+    /**
+     * If equal to 1 then the set includes phy_t::LE_2M.
+     */
+    uint8_t le_2m:1;
+
+    /**
+     * If equal to 1 then the set includes phy_t::LE_CODED.
+     */
+    uint8_t le_coded:1;
+};
+
+/**
+ * Type describing the number of symbols per bit in le coded PHY.
+ */
+struct coded_symbol_per_bit_t :SafeEnum<coded_symbol_per_bit_t, uint8_t> {
+    /** struct scoped enum wrapped by the class */
+    enum type {
+        /**
+         * The Number of symbol used to code a bit is undefined.
+         */
+        UNDEFINED,
+
+        /**
+         * Two symbols to code a bit.
+         */
+        S2,
+
+        /**
+         * Eight symbols to code a bit.
+         */
+        S8
+    };
+
+    /**
+     * Construct a new instance of coded_symbol_per_bit_t.
+     */
+    coded_symbol_per_bit_t(type value) :
+        SafeEnum<coded_symbol_per_bit_t, uint8_t>(value) { }
+};
+
 } // namespace ble
 
 /**

features/FEATURE_BLE/ble/Gap.h

@@ -533,6 +533,21 @@ class Gap {
      */
     typedef ble::peer_address_type_t PeerAddressType_t;
 
+    /**
+     * Enumeration of BLE PHY
+     */
+    typedef ble::phy_t Phy_t;
+
+    /**
+     * Set of BLE PHYs
+     */
+    typedef ble::phys_t Phys_t;
+
+    /**
+     * Enumeration of type of symbols that can be used with LE coded PHY.
+     */
+    typedef ble::coded_symbol_per_bit_t CodedSymbolPerBit_t;
+
     /**
      * Parameters of a BLE connection.
      */
@@ -1071,6 +1086,68 @@ class Gap {
     typedef CallChainOfFunctionPointersWithContext<const Gap *>
         GapShutdownCallbackChain_t;
 
+
+    /**
+     * Definition of the general handler of Gap related events.
+     */
+    struct EventHandler {
+        /**
+         * Function invoked when the current transmitter and receiver PHY have
+         * been read for a given connection.
+         *
+         * @param status Status of the operation: BLE_ERROR_NONE in case of
+         * success or an appropriate error code.
+         *
+         * @param connectionHandle: The handle of the connection for which the
+         * PHYs have been read.
+         *
+         * @param txPhy PHY used by the transmitter.
+         *
+         * @param rxPhy PHY used by the receiver.
+         */
+        virtual void onPhyRead(
+            ble_error_t status,
+            Handle_t connectionHandle,
+            ble::phy_t txPhy,
+            ble::phy_t rxPhy
+        ) = 0;
+
+        /**
+         * Function invoked when the update process of the PHY has been completed.
+         *
+         * The process can be initiated by a call to the function setPhy, the
+         * local bluetooth subsystem or the peer.
+         *
+         * @param status Status of the operation: BLE_ERROR_NONE in case of
+         * success or an appropriate error code.
+         *
+         * @param connectionHandle: The handle of the connection on which the
+         * operation was made.
+         *
+         * @param txPhy PHY used by the transmitter.
+         *
+         * @param rxPhy PHY used by the receiver.
+         *
+         * @note Success doesn't mean the PHY has been updated it means both
+         * ends have negociated the best phy according to their configuration and
+         * capabilities. The PHY currently used are present in the txPhy and
+         * rxPhy parameters.
+         */
+        virtual void onPhyUpdateComplete(
+            ble_error_t status,
+            Handle_t connectionHandle,
+            ble::phy_t txPhy,
+            ble::phy_t rxPhy
+        ) = 0;
+
+    protected:
+        /**
+         * Prevent polymorphic deletion and avoid uncessery virtual destructor
+         * as the Gap class will never delete the instance it contains.
+         */
+        ~EventHandler() { }
+    };
+
     /*
      * The following functions are meant to be overridden in the platform-specific subclass.
      */
@@ -1331,6 +1408,72 @@ class Gap {
         const GapScanningParams *scanParams
     );
 
+    /**
+     * Read the PHY used by the transmitter and the receiver on a connection.
+     *
+     * Once the PHY has been read, it is reported back via the function onPhyRead
+     * of the event handler registered by the application.
+     *
+     * @param connection Handle of the connection for which the PHY being used is
+     * queried.
+     *
+     * @return BLE_ERROR_NONE if the read PHY procedure has been started or an
+     * appropriate error code.
+     */
+    virtual ble_error_t readPhy(Handle_t connection) {
+        return BLE_ERROR_NOT_IMPLEMENTED;
+    }
+
+    /**
+     * Set the prefered PHYs to use in a connection.
+     *
+     * @param txPhy: Set of PHYs prefered for tx operations. If NULL then no
+     * prefered PHYs are set and the default value of the subsytem is used.
+     *
+     * @param rxPhy: Set of PHYs prefered for rx operations. If NULL then no
+     * prefered PHYs are set and the default value of the subsytem is used.
+     *
+     * @return BLE_ERROR_NONE if the preferences have been set or an appropriate
+     * error code.
+     */
+    virtual ble_error_t setPreferedPhys(
+        const Phys_t* txPhys,
+        const Phys_t* rxPhys
+    ) {
+        return BLE_ERROR_NOT_IMPLEMENTED;
+    }
+
+    /**
+     * Update the PHY used by a connection.
+     *
+     * Once the update process has been completed, it is reported back to the
+     * application via the function onPhyUpdateComplete of the event handler
+     * registered by the application.
+     *
+     * @param connection Handle of the connection to update.
+     *
+     * @param txPhys Set of PHYs prefered for tx operations. If NULL then the
+     * choice is up to the Bluetooth subsystem.
+     *
+     * @param rxPhys Set of PHYs prefered for rx operations. If NULL then the
+     * choice is up to the Bluetooth subsystem.
+     *
+     * @param codedSymbol Number of symbols used to code a bit when le coded is
+     * used. If the value is UNDEFINED then the choice is up to the Bluetooth
+     * subsystem.
+     *
+     * @return BLE_ERROR_NONE if the update PHY procedure has been successfully
+     * started or an error code.
+     */
+    virtual ble_error_t setPhy(
+        Handle_t connection,
+        const Phys_t* txPhys,
+        const Phys_t* rxPhys,
+        CodedSymbolPerBit_t codedSymbol
+    ) {
+        return BLE_ERROR_NONE;
+    }
+
     /**
      * Initiate a disconnection procedure.
      *
@@ -2446,6 +2589,17 @@ class Gap {
 
     /* Event handlers. */
 public:
+
+    /**
+     * Assign the event handler implementation that will be used by the gap
+     * module to signal events back to the application.
+     *
+     * @param handler Application implementation of an Eventhandler.
+     */
+    void setEventHandler(EventHandler* handler) {
+        _eventHandler = handler;
+    }
+
     /**
      * Register a callback handling timeout events.
      *
@@ -2674,6 +2828,7 @@ class Gap {
         disconnectionCallChain.clear();
         radioNotificationCallback = NULL;
         onAdvertisementReport     = NULL;
+        _eventHandler = NULL;
 
         return BLE_ERROR_NONE;
     }
@@ -2694,7 +2849,8 @@ class Gap {
         radioNotificationCallback(),
         onAdvertisementReport(),
         connectionCallChain(),
-        disconnectionCallChain() {
+        disconnectionCallChain(),
+        _eventHandler(NULL) {
         _advPayload.clear();
         _scanResponse.clear();
     }
@@ -2938,6 +3094,11 @@ class Gap {
      */
     DisconnectionEventCallbackChain_t disconnectionCallChain;
 
+    /**
+     * Event handler provided by the application.
+     */
+    EventHandler* _eventHandler;
+
 private:
     /**
      * Callchain containing all registered callback handlers for shutdown