ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #1 from pan-/PHY_API 

Phy api
pull/7899/head
Vincent Coubard 2018-07-16 11:54:33 +01:00
parent 7d871bfff5
commit 4deb64aed1
2 changed files with 266 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

104
features/FEATURE_BLE/ble/BLETypes.h
View File

@ -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
/**

163
features/FEATURE_BLE/ble/Gap.h
View File

@ -533,6 +533,21 @@ public:
*/
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 @@ public:
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 @@ public:
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 @@ public:
/* 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 @@ public:
disconnectionCallChain.clear();
radioNotificationCallback = NULL;
onAdvertisementReport = NULL;
_eventHandler = NULL;
return BLE_ERROR_NONE;
}
@ -2694,7 +2849,8 @@ protected:
radioNotificationCallback(),
onAdvertisementReport(),
connectionCallChain(),
disconnectionCallChain() {
disconnectionCallChain(),
_eventHandler(NULL) {
_advPayload.clear();
_scanResponse.clear();
}
@ -2938,6 +3094,11 @@ protected:
*/
DisconnectionEventCallbackChain_t disconnectionCallChain;
/**
* Event handler provided by the application.
*/
EventHandler* _eventHandler;
private:
/**
* Callchain containing all registered callback handlers for shutdown