Cross-Domain Development Kit XDK110 Platform for Application Development

Transcription

1 BLE Guide Cross-Domain Development Kit Platform for Application Development Bosch Connected Devices and Solutions : BLE Guide Document revision 2.0 Document release date Document number Workbench Version Technical reference code(s) Notes --GUIDE-BLE Data in this document is subject to change without notice. Product photos and pictures are for illustration purposes only and may differ from the real product s appearance. Subject to change without notice

2 BLE Guide Page 2 XDK BLE Guide PLATFORM FOR APPLICATION DEVELOPMENT The XDK provides several BLE APIs to manage the BLE functionality on the device. The interfaces can be used by applications in order to communicate via the ALPWISE BLE stack with surrounding BLE devices. A wide range of BLE functionalities can be achieved using the XDK, from configuration of the BLE controller according to the requirements of the designed XDK application, up to active BLE connections, including data exchange in both ways between the XDK and other BLE devices. Table of Contents 1. XDK BLE OVERVIEW UNDERSTANDING THE BLE PROTOCOLS LEARNING ABOUT BLE COMMUNICATION ROLES UNDERSTANDING BLE DATA PROFILES & SERVICES BLE DATA HIERARCHY XDK SERVICES API OVERVIEW API USAGE PREPARATION SET UP THE SERVICE HANDLING BLE EVENTS INITIALIZE AND STARTUP BLE SENDING DATA TO REMOTE CLIENT DOCUMENT HISTORY AND MODIFICATION This guide assumes a basic understanding of the XDK and the Workspace. For new users, we recommend going through the following guides at xdk.io/guides first: - Workbench Installation - Workbench First Steps - XDK Guide FreeRTOS

3 BLE Guide Page 3 1. XDK BLE Overview 1.1 Understanding the BLE Protocols BLE is built up of several protocols that are being used on different layers to transfer information between physical parts of the chip and the application level. The protocols supported by the ALPWISE BLE stack are depicted in picture 1 and explained below. Picture 1. Description of the ALPWISE protocol stack profiles ALPWISE protocol stack GATT / GAP L2CAP HCI GAP (General Access Profile) initializing and configuring the internal BLE module in regards to BLE role and parameters advertising data visible to other BLE devices with the goal of a connection establishment discovering other devices that are in an advertising state connecting to and disconnecting from devices GATT (Generic Attribute Profile) configuring the data to be provided to other BLE devices querying available data and how the data can be read and/or written providing data exchange services between two BLE devices which interact as server and client (e.g. reading and writing data) L2CAP (Logical Link Control and Adaptation Protocol) multiplexing data between higher layer protocols and lower physical layer protocols segmenting and reassembling incoming and outgoing packets HCI (Host Controller Interface) provides a command interface between a BLE application on a host controller (e.g. XDK application, laptop debugging console) and the BLE controller inside of the XDK enables direct interaction possibilities for the host, like device configuration, discovery, connection, sending / receiving data, etc.

4 BLE Guide Page Learning about BLE Communication Roles The BLE controller (EM9301) supports Bluetooth version 4.0 and can be run as a master or slave device. Depending on state and configuration, the BLE controller can act in the communication roles as seen in picture 2. Picture 2. Overview of BLE communication roles and transition possibilities Connection Master Initiating Central Peripheral/ Broadcaster Slave Observer Advertising Standby Scanning One of the most important differences between a peripheral and central device is that: BLE peripheral mode will support advertising data and accepting incoming connection requests BLE central mode will take over the role of discovering other devices and initiating connections Once the connection is established the BLE devices exchange data in a client-servercommunication consisting of two roles: a server hosting the BLE data services, typically a data sensor offering values like heart rate or accelerometer a client requesting information from the server, typically a data collector computing information (e.g. displaying it to a user) The BLE stack from ALPWISE provides all roles defined in the BLE specification but in most use cases, the XDK is usually employed as a peripheral device to advertise data for interested central devices. After accepting the connection initiation, the XDK communicates as a slave device with the master device by providing data as a server to the client. So the usual setup of BLE use cases with the XDK looks like displayed in picture 3. Picture 3. Data exchange setup between client and server Client Wants data Has data Server XDK

5 BLE Guide Page Understanding BLE Data Profiles & Services BLE Data Hierarchy BLE data is organised in hierarchical elements which makes it easy to understand what the BLE device is offering as a data provider on different detail levels. It also provides the possibility to reuse single components of the structure in other use-cases. Typical data structure is shown in an example profile in picture 4. Picture 4. Data structure including profile, services and characteristics Service Characteristic Value Profile Service Characteristic Value Characteristic Value Characteristic Value In BLE services that fit together for a specific use case (e.g. Battery Service and Heart Rate Service into Heart Rate Profile) are combined into profiles. Services consist of at least one or more characteristics. Characteristics can be seen as data containers with a value and descriptors describing the access rules and allowed data operations. The following operations to move data between the client and the server are supported in BLE: read requests can be executed by the client and the server responds with the requested data write commands are issued by the client to write values to the characteristics of the server notify needs to be actively enabled by the client at the server so the server sends notifications including the values periodically or whenever an update of data is available indicate works the same way notify does but it also requests acknowledgement by the client whenever the values have been received which makes the notify faster but less reliable XDK Services By using the highest level API, two major services can be initialized on the XDK. The first one is a bidirectional communication service. That means that the service consists of two parts, which are reading and writing. The XDK can send data to the remote client, which is a reading operation from the remote client s point of view. Additionally, the remote client can send data to the XDK, which is a write operation from the remote clients point of view.

6 BLE Guide Page 6 The second service consists of the sensors. The remote client can address different sensors via this service. The XDK will know which of the sensors has been addressed and respond respectively. 1.4 API Overview The BLE library consists of three parts, which are the general API for BLE initialization and handling, one for the bidirectional communication service and one for the sensor services. While it is recommended to use the highest level API, deeper levels can be accessed via the Alpwise BLE stack library Picture 5. Communication between the XDK application and ALPWISE protocol stack via BLE API XDK application XDK BLE API ALPWISE BLE stack library The header-files for the high level API are listed in Table 1. Table 1. XDK BLE API Interface _BlePeripheral.h _BidirectionalService.h _SensorServices.h Description BLE initialization, service registration, connection handling API BLE bidirectional service API BLE sensor services API In this guide, the Bidirectional Service will be presented and implemented. To use the API, the necessary header files have to be included, as seen in Code 1. Additionally, semphr.h will be included, as they are necessary to ensure that BLE will function correctly. For more information on semaphores, please refer to the FreeRTOS guide. Code 1. Including header files #include "_BlePeripheral.h" #include "_BidirectionalService.h" #include "semphr.h"

7 BLE Guide Page 7 2. API Usage 2.1 Preparation This guide will use semaphores, and these have to be globally accessible. Additionally, functions that access semaphores usually have a timeout. For this, constant defines will be used. The following code can be placed near the top of the implementation file, below the includes. Code 2. Constant defines and global variables #define BLE_START_SYNC_TIMEOUT #define BLE_WAKEUP_SYNC_TIMEOUT #define BLE_SEND_TIMEOUT UINT32_C(5000) UINT32_C(5000) UINT32_C(1000) static SemaphoreHandle_t BleStartSyncSemphr = NULL; static SemaphoreHandle_t BleWakeUpSyncSemphr = NULL; static SemaphoreHandle_t SendCompleteSyncSemphr = NULL; 2.2 Set up the Service Before BLE can be initialized, some functions have to be defined to set up the service. A service is set up by defining two callbacks. The first will handle incoming data and read requests. The second one will monitor the sending process of every message sent to the remote client. These functions are defined in Code 3 and will be used in another function, that will set up the service. Code 3. Send and Receive Callbacks static void datareceived(uint8_t *rxbuffer, uint8_t rxdatalength) { uint8_t receivebuffer[uint8_c(24)]; memset(receivebuffer, 0, sizeof(receivebuffer)); memcpy(receivebuffer, rxbuffer, rxdatalength < UINT8_C(24)? rxdatalength : UINT8_C(23)); printf("received data: %s \n\r", receivebuffer); static void datasent(retcode_t sendstatus) { _UNUSED(sendStatus); xsemaphoregive(sendcompletesyncsemphr); The function datareceived() will copy the data that the XDK received via BLE into a buffer. If the message is too long, it will be cut off. Finally, the received data will be printed as a string. The function datasent() only releases a semaphore that handles synchronizing multiple sending processes. The function datasent() is called everytime a message is done being sent (either successfully or unsuccessfully). The signatures should stay the same as they are presented here. Otherwise the functions will not work. These two functions are going to be used in a third function that handles initialising and registering the service. Code 4 shows how to implement the function.

8 BLE Guide Page 8 Code 4. Initialize and register the Service static Retcode_T initializeandregisterservice(void) { BidirectionalService_Init(dataReceived, datasent); BidirectionalService_Register(); return RETCODE_OK; Again, the function s signature should not be changed, otherwise it might lead to unexpected behaviour later on. The function initializeandregisterservice() will be used during initialization of the BLE peripherial, later on in this guide. 2.3 Handling BLE Events The BLE library will eventually throw peripheral events, for example when a device connects, or disconnects, but also others, that are needed during initialization and startup. For this, a callback function will be defined. This function is presented in Code 5. It has two inputs, the event itself, and data that belongs to the event. The events and the corresponding data types are listed in the header file _BlePeripheral.h. Code 5. BLE Event Callback static void handleevent(bleperipheral_event_t event, void *data) { switch(event) { case BLE_PERIPHERAL_STARTED: xsemaphoregive( BleStartSyncSemphr ); break; case BLE_PERIPHERAL_WAKEUP_SUCCEEDED: xsemaphoregive( BleWakeUpSyncSemphr ); break; case BLE_PERIPHERAL_CONNECTED: { Ble_RemoteDeviceAddress_T *remoteaddress; remoteaddress = (Ble_RemoteDeviceAddress_T*) data; printf("device connected: %02x:%02x:%02x:%02x:%02x:%02x\n\r", remoteaddress->addr[0], remoteaddress->addr[1], remoteaddress->addr[2], remoteaddress->addr[3], remoteaddress->addr[4], remoteaddress->addr[5]); break; case BLE_PERIPHERAL_DISCONNECTED: printf("device Disconnected\n\r"); break; default: break; The first two events occur during the starting up process. In these cases the semaphores, that were previously taken, will be given back. In the case of connection events, the remote client s address will be printed. In disconnection events, a simple message will be printed.

9 BLE Guide Page Initialize and Startup BLE Now, everything is prepared and it is possible to initialize and startup the BLE peripheral. Code 6 shows which functions have to be called to get the BLE peripheral up and running, using all the functions that have been previously defined in one sequence. This code can be used in any function, for example appinitsystem(). Code 6. Initializing and starting up the BLE peripheral BleStartSyncSemphr = xsemaphorecreatebinary(); BleWakeUpSyncSemphr = xsemaphorecreatebinary(); SendCompleteSyncSemphr = xsemaphorecreatebinary(); BlePeripheral_Initialize(handleEvent, initializeandregisterservice); BlePeripheral_SetDeviceName((uint8_t *) "XDK BLE Guide"); if(retcode_ok == BlePeripheral_Start()) { xsemaphoretake(blestartsyncsemphr, BLE_START_SYNC_TIMEOUT); if(retcode_ok == BlePeripheral_Wakeup()) { xsemaphoretake(blewakeupsyncsemphr, BLE_WAKEUP_SYNC_TIMEOUT); 2.5 Sending Data to Remote Client Now that the BLE peripheral is set up, and clients can connect, the XDK is able to send messages. For this, a function can be defined, that can be called from anywhere. The function is defined in Code 7. It will send a message, and take the corresponding semaphore to synchronize with other messages. Code 7. Sending BLE Messages void transmitdata(void) { Retcode_T sendingreturnvalue = BidirectionalService_SendData( (uint8_t *) "Hello Client", (uint8_t) sizeof("hello Client")); if (sendingreturnvalue == RETCODE_OK) { xsemaphoretake(sendcompletesyncsemphr, BLE_SEND_TIMEOUT); A message can even be sent inside the receivedata() function, as an immediate reaction to incoming messages.

10 BLE Guide Page Document History and Modification Rev. No. Chapter Description of modification/changes Editor Date 2.0 Version 2.0 initial release AFS