XDK API  3.6.0
Documentation
Files | Typedefs | Enumerations | Functions

This module provides a convenient abstraction to use a device as BLE Peripheral. More...

+ Collaboration diagram for BLE Peripheral:

Files

file  BCDS_BlePeripheral.h
 

Typedefs

typedef enum Ble_PeripheralEvent_E BlePeripheral_Event_T
 Typedef to represent the Bluetooth peripheral event. More...
 
typedef void(* BlePeripheral_EventCallback )(BlePeripheral_Event_T event, void *data)
 Callback function signature to be called when the BLE stack changes its state. More...
 
typedef Retcode_T(* BlePeripheral_ServiceRegistryCallback )(void)
 Callback function definition to be called in order to register the BLE services the application wants to use. More...
 

Enumerations

enum  Ble_PeripheralEvent_E
 Enumeration to represent the Bluetooth peripheral events. More...
 

Functions

Retcode_T BlePeripheral_Deinitialize (void)
 De-initializes the BLE stack, corresponding resources and modules. More...
 
uint32_t BlePeripheral_GetBleTaskStackHighwaterMark (void)
 Gets the BLE peripheral task stack high water mark. More...
 
uint16_t BlePeripheral_GetConnectionHandle (void)
 Gets the Connection handle. More...
 
Retcode_T BlePeripheral_Initialize (BlePeripheral_EventCallback callBackOnEvent, BlePeripheral_ServiceRegistryCallback serviceRegistryCallback)
 Initializes the BLE Peripheral module. More...
 
Retcode_T BlePeripheral_SetDeviceName (uint8_t *name)
 Sets the device name which will be visible to scanning devices. More...
 
Retcode_T BlePeripheral_SetMacAddress (uint64_t macAddress)
 Sets the MAC address of the device. More...
 
Retcode_T BlePeripheral_Sleep (void)
 Sets the BLE peripheral into SLEEP mode. More...
 
Retcode_T BlePeripheral_Start (void)
 Starts the BLE module as a peripheral. More...
 
Retcode_T BlePeripheral_Wakeup (void)
 Wakes up the BLE peripheral and makes it discoverable. More...
 

Detailed Description

A BLE Peripheral is a device that can be discovered and connected by a central device, e.g. a smartphone. There are several applications for Andoid and iOS available in the respective stores that allow to search for nearby BLE peripherals, connect to them and use their services.

This implementation integrates and uses the Alpwise BLE stack. Related documentation is available in the respective library path. It provides several standard Bluetooth Profile and Service implementations, such as Heart Rate Monitor etc.

The supported radio chip is the EM9301.

A typical application flow of an application based on this module is summarized below:

  1. Initialization with event and service registration callbacks
  2. Set the necessary peripheral properties such as name and MAC address
  3. Start (the device will be in sleep mode initially in order to save power)
  4. Wakeup
  5. Use the services API of the registered services to Send & Receive data if connected
  6. Sleep in order to save power
  7. repeat steps 4.-6.
  8. Deinitialize

Example:

#include "BCDS_Basics.h"
#include "BCDS_Retcode.h"
void BluetoothPeripheral_BasicExample()
{
uint8_t deviceName[] = "MyPeripheral";
uint64_t macAdress = UINT64_C(0x12345678);
uint8_t dataToSend[] = "BCDS";
uint8_t dataToSendLen = UINT8_C(4);
BlePeripheral_Initialize(EventCallBack, ServiceRegistrationCallBack);
// In the ServiceRegistrationCallBack initialize and
// register all services that should be available to the application.
// Currently this package supports two services :
// - BCDS Bidirectional Service
// Additionally the service implementations of Alpwise can be used as well as custom services (see e.g. the BCDS Bidirectional Service as example).
// Wait until BLE_PERIPHERAL_STARTED event is received in the EventCallBack.
// The device is now in sleep mode.
// In the background the ServiceRegistrationCallBack will be called and on success triggers
// the BLE_PERIPHERAL_SERVICES_REGISTERED event to be received in the EventCallBack.
// In this example, both "data send complete" and "data receive" callback will be
// registered at the time of service initialization.
// See after the BluetoothPeripheral_BasicExample function for
// reference implementation for ServiceRegistrationCallBack.
// Wait until the BLE_PERIPHERAL_WAKEUP_SUCCEEDED event is received in EventCallBack.
// The device has entered advertising state now and can be discovered and connected by a central device, e.g. a Smartphone with BLE support.
// Once the central device connects, the BLE_PERIPHERAL_CONNECTED event will be received with #Ble_RemoteDeviceAddress_T
// parameter in EventCallBack. Now you are ready to communicate with the connected remote device.
BlePeripheralService_SendData(dataToSend, dataToSendLen)
// Wait for RETCODE_OK as parameter in callback registered at the
// time of service initialization to confirm successful data
// send operation.
// If the BLE_PERIPHERAL_DISCONNECTED event is received in EventCallBack,
// further communications will not be supported until a new
// connection is available. The device will stay in advertising mode
// until BlePeripheral_Sleep is triggered.
// Wait for the BLE_PERIPHERAL_SLEEP_SUCCEEDED event in EventCallBack.
// The device now has entered deep sleep mode.
// In case this is called during an active connection, then
// BLE_PERIPHERAL_DISCONNECTED event with Ble_RemoteDeviceAddress_T
// parameter will be received before BLE_PERIPHERAL_SLEEP_SUCCEEDED in the EventCallBack.
}
Retcode_T ServiceRegistrationCallBack()
{
#if BIDIRECTIONAL_SERVICE
BidirectionalService_Init(readCallback, sendCallBack);
// readCallback will be triggered upon reception of input packets.
// sendCallBack will be triggered upon every single.
// BidirectionalService_SendData trigger to notify the status.
// This will Register the Bi-directional Service.
// Use BidirectionalService_SendData further to send data.
#endif // BIDIRECTIONAL_SERVICE
#if CUSTOM_SERVICE
CustomServices_Init(readCallback, sendCallBack);
// readCallback will be triggered upon reception of input packets.
// sendCallBack will be triggered upon every single
// CustomServices_SendData trigger to notify the status.
CustomServices_Register();
// This will Register the Interface user's Service.
// Use CustomServices_SendData further to send data.
#endif // CUSTOM_SERVICE
return RETCODE_OK;
}
#if CUSTOM_SERVICE
// Implement CustomServices_Init, CustomServices_Register and
// CustomServices_SendData as per application need.
#endif // CUSTOM_SERVICE
Note
  1. Minimum initial connection interval time is defined as 30mSec.(BleGap.h)
  2. The Latency for mode transition INITIALIZATION -> START is ~ 16mSec, for SLEEP -> WAKEUP ~ 2.7mSec.
  3. BlePeripheral_Start must be called only once after initialization. The calling thread must have lesser priority than the BLE peripheral thread. The priority of BLE peripheral thread is defined using the macro BLE_TASK_PRIORITY in package configuration header file (BCDS_BluetoothConfig.h).
  4. If de-initialized, then after initialization BLE start shall be called once again.
  5. After BlePeripheral_Start, the Alpwise stack will be initialized and the radio will be in sleep mode. The BLE_PERIPHERAL_STARTED event will be provided upon successful initialization through BlePeripheral_EventCallback.
  6. After successful BlePeripheral_Start, only BlePeripheral_Wakeup and BlePeripheral_Sleep may be called.
  7. After BlePeripheral_Wakeup, it takes ~50mSec for device to be discoverable.
  8. BLE device is no longer discoverable after entering to SLEEP and vice-versa for WAKEUP.
  9. Upon SLEEP trigger, if the BLE device was previously connected, it would disconnect (providing event) and then enter the SLEEP mode.
  10. Upon SLEEP and WAKEUP trigger we must wait atleast 1 ms before triggering the next power control successfully. It is expected to be synchronized with the corresponding events.
  11. All the SLEEP and WAKEUP trigger operation status will be updated through BLE_PERIPHERAL_SLEEP_SUCCEEDED and BLE_PERIPHERAL_WAKEUP_SUCCEEDED event notification via BLE event callback that would have been registered at the time of initialization.
  12. For all the SLEEP and WAKEUP triggers, application must wait / sync with the events before triggering further operations.

Typedef Documentation

typedef void(* BlePeripheral_EventCallback)(BlePeripheral_Event_T event, void *data)

Callback function signature to be called when the BLE stack changes its state.

Parameters
[in]eventThe event that has occurred.
[in]datavoid pointer pointing to a data type with further information based on the event.
event data type
BLE_PERIPHERAL_STARTED Retcode_T
BLE_PERIPHERAL_SERVICES_REGISTERED unused
BLE_PERIPHERAL_SLEEP_SUCCEEDED Retcode_T
BLE_PERIPHERAL_WAKEUP_SUCCEEDED Retcode_T
BLE_PERIPHERAL_CONNECTED Ble_RemoteDeviceAddress_T
BLE_PERIPHERAL_DISCONNECTED Ble_RemoteDeviceAddress_T
BLE_PERIPHERAL_ERROR Retcode_T
typedef Retcode_T(* BlePeripheral_ServiceRegistryCallback)(void)

Callback function definition to be called in order to register the BLE services the application wants to use. This function will be called after the application has called BlePeripheral_Start. It has to be implemented by the application implementer. Within this function, all services that the application requires have to be registered with the Alpwise stack using the attserver.h interface.

Returns
RETCODE_OK on success, or an error code otherwise. Refer Retcode_General_E and Ble_Retcode_E for other values.

Enumeration Type Documentation

Enumeration to represent the Bluetooth peripheral events. They will be provided through BlePeripheral_EventCallback

Enumerator
BLE_PERIPHERAL_STARTED 

Event indicating that the peripheral has been started and entered sleep mode

BLE_PERIPHERAL_SERVICES_REGISTERED 

This event indicates that the required services have been registered successfully

BLE_PERIPHERAL_SLEEP_SUCCEEDED 

Event indicating that the peripheral has entered sleep mode

BLE_PERIPHERAL_WAKEUP_SUCCEEDED 

Event indicating that the peripheral has entered woken up from sleep and is ready for user interaction

BLE_PERIPHERAL_CONNECTED 

Event indicating that a connection to an external device has been established

BLE_PERIPHERAL_DISCONNECTED 

Event indicating that a connection to an external device has been terminated

BLE_PERIPHERAL_ERROR 

Event indicating that an error has occured

BLE_PERIPHERAL_EVENT_MAX 

Defines boundary of BLE events

Function Documentation

Retcode_T BlePeripheral_Deinitialize ( void  )

De-initializes the BLE stack, corresponding resources and modules.

Returns
RETCODE_OK on success, or an error code otherwise. Refer Retcode_General_E and Ble_Retcode_E for other values.
Warning
The implementation is pending. Do not expect the module to re-initialize again (calling BlePeripheral_Initialize after calling Ble_Deinitialize). Do not make use of this API.
uint32_t BlePeripheral_GetBleTaskStackHighwaterMark ( void  )

Gets the BLE peripheral task stack high water mark

Returns
The BLE task stack high water mark value.
See also
uxTaskGetStackHighWaterMark from FreeRTOS
uint16_t BlePeripheral_GetConnectionHandle ( void  )

Gets the Connection handle for the current connection or 0 if the device is currently not connected.

Returns
The Connection Handle value. 0 if the device is not connected.

+ Here is the caller graph for this function:

Retcode_T BlePeripheral_Initialize ( BlePeripheral_EventCallback  callBackOnEvent,
BlePeripheral_ServiceRegistryCallback  serviceRegistryCallback 
)

Initializes the BLE Peripheral module, i.e. required resources (task, semaphores, queues, etc.) will be created and initialized.

Note
  1. This API shall be called only once.
  2. It will return failure when called the second time.
Parameters
[in]callBackOnEventRegistration of callback function for notification of BLE events.
[in]serviceRegistryCallbackRegistration of callback function used to register the services the application wants to use.
Returns
RETCODE_OK on success, or an error code otherwise. Refer Retcode_General_E and Ble_Retcode_E for other values.
Retcode_T BlePeripheral_SetDeviceName ( uint8_t *  name)

Sets the device name which will be visible to scanning devices.

Parameters
[in]namePointer to the variable containing the device name. The value must be null terminated and should not exceed 21 bytes.
Returns
RETCODE_OK on success, or an error code otherwise. Refer Retcode_General_E and Ble_Retcode_E for other values.
Note
This function must be called before BlePeripheral_Start in order to be effective.
Retcode_T BlePeripheral_SetMacAddress ( uint64_t  macAddress)

Sets the MAC address of the device.

Parameters
[in]macAddressthe MAC address that should be used for this device.
Returns
RETCODE_OK on success, or an error code otherwise. Refer Retcode_General_E and Ble_Retcode_E for other values.
Note
This function must be called before BlePeripheral_Start in order to be effective and macAddress parameters are purpose to BOSCH OUI ID of FC-D6-BD , So that macAddress should starts with "FC-D6-BD" OUI if not, macAddress will be Randomly Generated for ex: XX-XX-XX-XX-XX-XX.
Retcode_T BlePeripheral_Sleep ( void  )

Sets the BLE peripheral into SLEEP mode

Returns
RETCODE_OK on success, or an error code otherwise. Refer Retcode_General_E and Ble_Retcode_E for other values.
Note
BLE_PERIPHERAL_SLEEP_SUCCEEDED will be received in the BlePeripheral_EventCallback. Until it is received, neither BlePeripheral_Sleep nor BlePeripheral_Wakeup shall be triggered.
Retcode_T BlePeripheral_Start ( void  )

Starts the BLE module as a peripheral.

Returns
RETCODE_OK on success, or an error code otherwise. Refer Retcode_General_E and Ble_Retcode_E for other values.
Note
This function initializes the underlying layers and the radio chip to a working state and then switches the radio to sleep mode. Wait and sync for BLE_PERIPHERAL_STARTED event callBack (BlePeripheral_EventCallback) registered at the time of BlePeripheral_Initialize API trigger. The device is in the same state as in BLE_PERIPHERAL_SLEEP_SUCCEEDED event upon receiving BLE_PERIPHERAL_STARTED event.
Retcode_T BlePeripheral_Wakeup ( void  )

Wakes up the BLE peripheral and makes it discoverable.

Returns
RETCODE_OK on success, or an error code otherwise. Refer Retcode_General_E and Ble_Retcode_E for other values.
Note
BLE_PERIPHERAL_WAKEUP_SUCCEEDED will be received in the BlePeripheral_EventCallback. Until it is received, neither BlePeripheral_Sleep nor BlePeripheral_Wakeup shall be triggered. Once the BLE_PERIPHERAL_WAKEUP_SUCCEEDED event is received, the BLE peripheral will advertise.

All rights reserved. The use is subject to the XDK SDK EULA by Bosch Connected Devices and Solutions GmbH.
This documentation file has been automatically generated on Thu Mar 14 2019 19:12:51 by doxygen 1.8.8