ATSAMB11 Custom Service Implementation

Transcription

1 Custom Service Implementation Introduction This document demonstrates how to use the Bluetooth Low Energy SoC by building a custom specific profile using the Microchip BluSDK Smart Software Development Kit. This document covers: Technical overview of the board from hardware architecture to software design Description of the required process for developing the Bluetooth Low Energy peripheral application with the Handling of Bluetooth Low Energy custom services and characteristics Figure 1. Bluetooth Low Energy System Solution with 2018 Microchip Technology Inc. Application Note DS A-page 1

2 Table of Contents Introduction Getting Started Software Prerequisites Embedded Firmware Software API Hardware Prerequisites Hardware Setup Creating and Initializing the Project Creating Project from ASF Compiling and Testing the Project Establishing Connection with Central Device Configuring and Starting the Advertisement Process Managing GAP events Setup/Handling of Pre-Defined Service from ASF Adding Device Info Service Component from ASF Wizard to Project Configuring and Loading Device Information Service Setting up and Handling Custom Service Configuring and Loading the Custom Environment Service Updating the Temperature Characteristic Appendix A: Pre-defined Service Software Solution Appendix B: Custom Service Software Solution Document Revision History The Microchip Web Site Customer Change Notification Service...57 Customer Support Microchip Devices Code Protection Feature Legal Notice...58 Trademarks Quality Management System Certified by DNV...59 Worldwide Sales and Service Microchip Technology Inc. Application Note DS A-page 2

3 Getting Started 1. Getting Started This chapter describes the setup and basic software and hardware requirements. 1.1 Software Prerequisites Installation Steps of Atmel Studio 7 1. Download and install the Atmel Studio software. 2. Install the Advanced Software Framework (ASF) package. Note: The software for ZR module is supported with ASF and above. If DFP version is not or above, update the DFP version to For more details on installing the Device Pack, see Installing Device Pack using Device Pack Manager. Note: For more information on the previous releases, refer to the Atmel Studio Release Notes (42685J) available on the Microchip web page Installing Microchip Bluetooth Data Application on a Mobile Device 1. Open the App Store (iphone /ios) or Google Play Store (Android) on the mobile device. 2. Search for Microchip Bluetooth Data. 3. Click Install to install the application on the device. The following figure shows the dashboard of the Microchip Bluetooth Data app. Figure 1-1. Microchip Bluetooth Data Dashboard 2018 Microchip Technology Inc. Application Note DS A-page 3

4 Getting Started Installing Device Pack using Device Pack Manager 1. Open Atmel Studio. 2. Choose Tools > Device Pack Manager. Figure 1-2. Start Page AtmelStudio Window 3. Click Check for Updates to check new pack of the, and then click Install selected packs. Figure 1-3. Device Pack Manager Window 4. Click Install. By clicking install, the user agrees to the license terms mentioned Microchip Technology Inc. Application Note DS A-page 4

5 Getting Started Figure 1-4. End User License Agreement 5. After a successful update, Close the Pack Manager and restart Atmel Studio. Figure 1-5. Device Pack Manager Dialog Box 1.2 Embedded Firmware The Bluetooth Low Energy communication is based on the network stack stored in the Read Only Memory (ROM). This stack requires Generic Access Profile (GAP) parameters and attributes to be functional, which are pushed from the application into the internal SRAM, using internal messages. The ROM coded firmware embeds the layers of the Bluetooth Low Energy stack that runs on top of the peripheral drivers and RTOS scheduler. Generic Access Profile (GAP) 2018 Microchip Technology Inc. Application Note DS A-page 5

6 Getting Started GAP controls the Bluetooth Low Energy connection, advertising, makes the device visible to the outside world, and determines how two devices interact with each other. GAP defines two main roles for the Bluetooth Low Energy device: Central and Peripheral. Generic Attribute Profile (GATT) and Attribute Protocol (ATT) GATT defines how the Bluetooth Low Energy device transfers the data. The GATT process is based on services and characteristics stored in Attribute Protocol (ATT). ATT is a simple look up table stored in the SRAM. Security Manager (SM) The SM defines the procedure for pairing, authentication, and encryption between Bluetooth Low Energy devices. This layer is mainly used if security is requested on that particular connection. Logical Link Control and Adaptation Protocol (L2CAP) L2CAP supports high level protocol multiplexing, packet segmentation/reassembly, and conveying the quality of service information. L2CAP permits applications to transmit and receive the data packets with channel flow control and retransmission. Direct Test Mode (DTM) DTM allows testing of the radio's Physical Layer (PHY) by transmitting and receiving the test packet sequences. This is often used in compliance and production line testing, without the need to go through the complete Bluetooth Low Energy Protocol Stack. 1.3 Software API The is provided with a dedicated host software API layer. This API layer provides an easy and reliable solution to add Bluetooth Low Energy capabilities to any user application. The API provides a set of high level Bluetooth functions with abstraction of the transport protocol used between the user application and the. Figure 1-6. Software API The API operation relies on a request-response mechanism. The specific requests are sent to the through a corresponding API function call. The event messages are then returned by the on request processing or on specific Bluetooth Low Energy events. These event messages are to be handled by the application, according to the user application requirements. The following figure illustrates a typical Bluetooth Low Energy peripheral application flow Microchip Technology Inc. Application Note DS A-page 6

7 Getting Started Figure 1-7. Bluetooth Low Energy Peripheral Application Flow CAUTION The user application must be non-blocking to ensure that the Bluetooth Low Energy events are handled in time. The following figure describes the BluSDK Smart file architecture Microchip Technology Inc. Application Note DS A-page 7

8 Getting Started Figure 1-8. BluSDK Smart File Architecture 1.4 Hardware Prerequisites This Custom Service Implementation application note details the code implementation procedures which use the ZR-XPRO kit. The SAMB11-ZR Xplained Pro evaluation kit is a hardware platform used to evaluate the -ZR210CA module SAMB11-ZR Xplained Pro Board The SAMB11-ZR Xplained Pro evaluation kit is a hardware platform used to evaluate the - ZR210CA module. Supported by the Atmel Studio integrated development platform, the kit provides easy access to the features of the ZR and explains how to integrate the device in a custom design. The Xplained Pro MCU series evaluation kits include an on-board embedded debugger, and no external tools are necessary to program or debug the ZR. The Xplained Pro extension kits offer additional peripherals to extend the features of the board and ease the development of custom designs Microchip Technology Inc. Application Note DS A-page 8

9 Getting Started Figure 1-9. SAMB11-ZR Xplained Pro Board The SAMB11-ZR Xplained Pro board contains: -ZR210CA Module Bluetooth Low Energy module with 2.4 GHz, Bluetooth Low Energy Digital Temperature Sensor Integrated temperature sensor with nonvolatile registers and serial EEPROM. Compatible with two-wire (I 2 C) and SMBus serial interfaces Current Measurement Header Embedded current measurement circuitry with support for data visualization 1.5 Hardware Setup Connect the board to PC using the Debug USB Connector Microchip Technology Inc. Application Note DS A-page 9

10 Getting Started Figure SAMB11 XPRO Connection to PC The hardware is ready for development Microchip Technology Inc. Application Note DS A-page 10

11 Creating and Initializing the Project 2. Creating and Initializing the Project This chapter details the process of creating an application startup project using Atmel Studio. Prior to creating a project, the user must know hardware architecture and software requirements to configure drivers. 2.1 Creating Project from ASF Advanced Software Framework has a pre-configured startup template project that includes Bluetooth Low Energy software API for the and their peripheral driver dependencies. This is used as a starting project for any Bluetooth Low Energy project development. To create the project, follow the steps below: 1. Navigate to File > New > Example Project... in Atmel Studio. 2. From Device Family drop-down list, choose SAMB Select BLE-Startup Template - SAMB11 ZR Xplained Board. Note: The related projects are prefixed with BLE, making it easier to filter the project in the dialog box. Figure 2-1. Advanced Software Framework - New Example Project 4. Click OK and accept the license agreement by checking I accept the license agreement check box. 5. Click Finish. The BLE startup project is now created and loaded in Atmel Studio Microchip Technology Inc. Application Note DS A-page 11

12 Creating and Initializing the Project Figure 2-2. Startup_Template Project Note: The main project routine of startup template project already includes the SAMB11 CortexM0 MCU low level initialization, Bluetooth Low Energy initialization. The added ASF components in project can be viewed from ASF>ASF Wizard. Select the created project from the "Project" drop down box Microchip Technology Inc. Application Note DS A-page 12

13 Creating and Initializing the Project Figure 2-3. ASF Wizard Window 6. The main routine contains the low level initialization and BLE initialization. The following figure illustrates the flow of the main routine. Figure 2-4. Main Routine Flow 2018 Microchip Technology Inc. Application Note DS A-page 13

14 Creating and Initializing the Project 2.2 Compiling and Testing the Project 1. Click or press F7 button to compile the project. 2. Verify that no build error appears in Atmel Studio output window. Figure 2-5. Atmel Studio Output Window 3. To access the project properties, go to Project > STARTUP_TEMPLATE_SAMB11ZR_XPLAINED_PRO1 Properties. Figure 2-6. Compiling the Project 4. In project properties, click the Tool tab, and select the EDBG of SAMB11ZR Xplained Pro board as debugger/programmer Microchip Technology Inc. Application Note DS A-page 14

15 Creating and Initializing the Project Figure 2-7. Selection of Debugger/Programmer 5. Open any Terminal application (for example, TeraTerm). Click Serial radio button and click OK. 6. In TeraTerm, choose Setup > Serial port... and set the following parameters: Set Baudrate as Set Parity as none Set Stop bit as 1 Also, check if EDBG associated COM Port is listed in Windows Device Manager. 7. Click or press F7 to save the project. 8. Click or press Ctrl+Alt+F5 to program the project binary on the SAMB11-ZR Xplained Pro. 9. The initialization of the ZR module must return the Bluetooth Device Address and Address type as shown in the following figure Microchip Technology Inc. Application Note DS A-page 15

16 Creating and Initializing the Project Figure 2-8. Console Log Window Note: 1. The initialization of ZR takes few seconds, due to application code and patch code bootloading from internal SPI Flash to RAM Microchip Technology Inc. Application Note DS A-page 16

17 Establishing Connection with Central Device 3. Establishing Connection with Central Device The Bluetooth Low Energy connectivity is added to the application that is used to connect with the Bluetooth Low Energy central. The first step is about the management of the Bluetooth connection with a central device. When using the device, this process is managed by the corresponding API function calls associated with events handling. The interaction between the internal stack, application layer and Bluetooth Low Energy central during connection establishment is as follows: Figure 3-1. Establishing Connection with Central Device On the application layer side, the management of the Bluetooth connection is performed through three main steps: 1. GAP callback registration 2. Advertisement configuration 3. event handling In the existing project main routine, the integration of these steps is highlighted in red in the following flowchart Microchip Technology Inc. Application Note DS A-page 17

18 Establishing Connection with Central Device Figure 3-2. Main Routine Flow Chart 3.1 Configuring and Starting the Advertisement Process The Bluetooth Low Energy devices transmit advertisement packets to show their presence to nearby devices. The advertisement packet is sent periodically at a time interval defined by variable advinterval defined in the Bluetooth SIG specification. To avoid any collision with other wireless networks such as Wi-Fi, a channel change is performed for each advertisement packet sent (data frequency hopping), as illustrated in the following figure. Figure 3-3. Advertisement Process During advertisement, the payload structure to be sent differs from application to application and is set by using encapsulated packet data unit type information (PDU_TYPE) Microchip Technology Inc. Application Note DS A-page 18

19 Establishing Connection with Central Device Figure 3-4. PDU Advertising Preamble b Access Address 0x8E89BED6 Packet Data Unit (PDU) Advertising / Data CRC 1 Byte 4 Bytes Advertising Channel PDU 3 Bytes Header Payload 2 Bytes 6-37 Bytes PDU Type RFU TxAdd RxAdd Length RFU 4 Bits 2 Bits 1 Bit 1 Bit 6 Bits 2 Bits The following table lists the different PDU types used according to device role. Table 3-1. Device Roles for Advertising Event Types Advertising Event Types (PDU_TYPE) Broadcaster Observer Peripheral Central Connectible undirected event (ADV_IND) Excluded Excluded Mandatory Excluded Connectible directed event (ADV_DIRECT_IND) Non-connectible undirected event (ADV_NONCONN_IND) Excluded Excluded Optional Excluded Mandatory Excluded Optional Excluded Scannable undirected event (ADV_SCAN_IND) Optional Excluded Optional Excluded As the device acts as a Bluetooth Low Energy peripheral, the "connectable undirected event (ADV_IND)" advertising type is used. See the following description about the ADV_IND advertisement packet Microchip Technology Inc. Application Note DS A-page 19

20 Establishing Connection with Central Device Figure 3-5. ADV_IND Advertisement Packet The ADV_IND payload contains different Advertisement Data types (AD 0 - AD n), which provide specific information to the central device such as "device short name", "Tx power level" and "list of available services UUIDs". The number of advertisement data types that can be added to the advertisement payload are limited by the advertisement payload size of 31 octets. Following is a list of advertisement data types that are commonly found in ADV_IND payload Flags (AD Type 0x00) The flags describe the basic device capability, such as BLE support, BLE discoverable mode, BR/EDR support and simultaneous BR/ED Available Service UUID (AD Types 0x02 to 0x07) The Bluetooth Low Energy advertisement payloads are limited to 31 bytes. Therefore, only two 128-bit UUID values can be added to the payload. For this purpose, the specific AD types describe the length of the advertised UUID and provide information as to whether the payload contains a incomplete/complete list of UUID supported by the GATT server. 0x02 incomplete list of 16-bit UUIDs (adopted GATT services) 0x03 complete list of 16-bit UUIDs (adopted GATT services) 0x06 incomplete list of 128-bit UUIDs (custom GATT services) 0x07 complete list of 128-bit UUIDs (custom GATT services) Note: When a 16-bit UUID is transmitted, only the unique 2-byte value is sent. The client knows that; it is required to be injected into the base UUID. For example, the Health Thermometer Service is assigned as 0x1809, so its equivalent UUID is: F9B34FB Device Name (AD Types 0x08 to 0x09) This AD type field is used to advertise the local name of the device in the network. The local name data type value indicates if the name is complete or shortened. If the name is shortened, the complete name can be read after the connection is established. 0x08 shortened local name 0x09 complete local name Note: 1. A shortened name contains only continuous characters from the beginning of the full name. For example, if the device name is "BT_Device_Name", then the shortened name can be "BT_Device" or "BT_Dev" Microchip Technology Inc. Application Note DS A-page 20

21 Establishing Connection with Central Device 2. Complete GAP data type list is available at: For management of the advertisement process and covering the different configurations specified by Bluetooth SIG, the interface driver provides the two functions (at_ble_adv_data_set and at_ble_adv_start) elaborated in the following sections. In the application, use these two functions to set up the following ADV_IN type payload. Figure 3-6. ADV_IN Type Payload Process Setting the Advertisement Payload (at_ble_adv_data_set) Prototype at_ble_status_t at_ble_adv_data_set (uint8_t const *const adv_data, uint8_t adv_data_len, uint8_t const *const scan_resp_data, uint8_t scan_response_data_len); Description set, clear, or update the advertisement and scan response data. Parameters adv_data raw data to be placed in advertisement packet adv_data_len data length for adv_data. Max size: 28 bytes (3 bytes are reserved to set advertising AD type flags based on the selected Advertising mode and the user is not required to configure AD type flags in the advertisement payload) scan_resp_data raw data to be placed in the scan response packet. If NULL, no changes are made to the current scan response packet data scan_response_data_len data length for scan_resp_data. Max size: 31 bytes Return Execution Status This function requires a parameter raw adv_data to be passed. Following is an example of adv_data definition: static uint8_t adv_data[] = 0x08,// AD2 Length = 8 (AD_TYPE + AD) 0x09,// AD2 Type = Complete local Name 'M','y','_','S','E','N','S' // AD2 = My_SENS ; Starting the Advertisement Process (at_ble_adv_start) Prototype at_ble_status_t at_ble_adv_start (at_ble_adv_type_t type at_ble_adv_mode_t mode, 2018 Microchip Technology Inc. Application Note DS A-page 21

22 Establishing Connection with Central Device at_ble_addr_t *peer_addr, at_ble_filter_type_t filtered, uint16_t interval, uint16_t timeout, bool disable_randomness); Description start advertisement process. Parameters type advertising type to be used, can be: AT_BLE_ADV_TYPE_UNDIRECTED AT_BLE_ADV_TYPE_DIRECTED AT_BLE_ADV_TYPE_SCANNABLE_UNDIRECTED AT_BLE_ADV_TYPE_NONCONN_UNDIRECTED AT_BLE_ADV_TYPE_DIRECTED_LDC AT_BLE_ADV_TYPE_SCAN_RESPONSE mode Advertising mode to be used, can be: AT_BLE_ADV_NON_DISCOVERABLE AT_BLE_ADV_GEN_DISCOVERABLE AT_BLE_ADV_LIM_DISCOVERABLE AT_BLE_ADV_BROADCASTER_MODE peer_addr specify peer address, when advertising type is AT_BLE_ADV_TYPE_DIRECTED. filtered AT_BLE_ADV_FP_ANY allow scan and connection requests from anyone. AT_BLE_ADV_FP_FILTER_SCANREQ allow scan request from White List devices only. AT_BLE_ADV_FP_FILTER_CONNREQ allow connection request from White List devices only. AT_BLE_ADV_FP_FILTER_BOTH allow scan and connection requests from White List devices only. interval advertisement interval (in ms units). timeout advertising timeout between 0x0001 and 0x028F in scale of seconds. This parameter must be set to '0', if type equals AT_BLE_ADV_TYPE_DIRECTED disable_randomness when disabled, advertisements are performed at the exact interval without adding random 10 ms tempo. Return execution status Advertisement Process In this assignment, the advertisement process includes the following configuration: Undirected (Type : AT_BLE_ADV_TYPE_UNDIRECTED) Discoverable (Mode : AT_BLE_ADV_GEN_DISCOVERABLE) No peer address (peer_addr = NULL) No filtering (filtered = AT_BLE_ADV_FP_ANY) Advertisement interval 1s (interval = 1600) Maximum timeout 655 seconds (timeout : 655) Randomness enabled (disable_randomness = FALSE) 2018 Microchip Technology Inc. Application Note DS A-page 22

23 Establishing Connection with Central Device Starting the Advertisement Process 1. Open startup_template_app.c file. 2. Declare the following ble_status global variable in startup_template_app.c as volatile. #include <asf.h> #include "platform.h" #include "at_ble_api.h" #include "console_serial.h" #include "timer_hw.h" #include "ble_manager.h" #include "ble_utils.h" #include "button.h" #include "startup_template_app.h" volatile at_ble_status_t ble_status; 3. Declare the following adv_data global variable in startup_template_app.c as static. static uint8_t adv_data[] = 0x08,// AD2 Length = 8 (AD_TYPE + AD) 0x09,// AD2 Type = Complete local Name 'M','y','_','S','E','N','S' // AD2 = My_SENS ; Note: 1. The name of the device is to be changed (AD2 field). 2. According to the new name, AD2 length must be adapted to new AD2 content. 4. Add the following start_advertisement function in startup_template_app.c and define the function prototype void start_advertisement (void); to avoid warnings. void start_advertisement (void) printf("\r\n*** Assignment 2.1: Start Advertisement"); /*Set advertisement data*/ ble_status = at_ble_adv_data_set(adv_data,sizeof(adv_data),null,0); /*Start Advertisement*/ ble_status = at_ble_adv_start(at_ble_adv_type_undirected,\ AT_BLE_ADV_GEN_DISCOVERABLE,NULL,AT_BLE_ADV_FP_ANY,1600,655,0); if(ble_status!= AT_BLE_SUCCESS) printf("\r\n*** Failed to start advertisement"); 5. Start the advertisement process by adding the following highlighted code to the application main routine. int main(void) platform_driver_init(); acquire_sleep_lock(); /* Initialize serial console */ serial_console_init(); /* Hardware timer */ hw_timer_init(); /* button initialization */ gpio_init(); button_init(); button_register_callback(button_cb); hw_timer_register_callback(timer_callback_fn); DBG_LOG("Initializing BLE Application"); /* initialize the BLE chip and Set the Device Address */ ble_device_init(null); /* Start Advertising process */ start_advertisement(); register_resume_callback(platform_resume_cb); /* Set ULP mode */ 2018 Microchip Technology Inc. Application Note DS A-page 23

24 Establishing Connection with Central Device ble_set_ulp_mode(ble_ulp_mode_set); while(true) /* BLE Event task */ ble_event_task(ble_event_timeout); /* Write application task */ 6. Click or press Ctrl+S to save the project. 7. Click or press F7 button to compile the project. 8. Verify that no build error appears in Atmel Studio output window. Figure 3-7. Atmel Studio Output Window 9. Click or press Ctrl+Alt+F5 to program the project binary on the SAMB11-ZR Xplained Pro. 10. Open the Microchip Bluetooth Data Application on Android or ios mobile device. Press the Bluetooth Smart button. Press the START SCAN button. Note: The device must appear in the Microchip Bluetooth Data Application Microchip Technology Inc. Application Note DS A-page 24

25 Establishing Connection with Central Device Figure 3-8. Microchip Bluetooth Data Application 11. The terminal must display the following log output. Figure 3-9. Log Output Window 3.2 Managing GAP events The management of the Bluetooth connection at the application level is done through reception and handling of events reported by the internal stack. These events are generated by GAP, GATT, and L2CAP layers to notify the host about the ongoing Bluetooth interaction with other devices in its vicinity Microchip Technology Inc. Application Note DS A-page 25

26 Establishing Connection with Central Device To manage events coming from the module, the host driver must provide a ble_mgr_events_callback_handler function that allows registration of application callback function to be executed on each event reported by the module. Prototype bool ble_mgr_events_callback_handler (ble_mgr_event_cb_t event_cb_type, ble_mgr_event_t event_type, const void *ble_event_handler); Description used by Profile/Service/Application to register the Bluetooth Low Energy events callbacks. Parameters event_cb_type types of actions to perform on callbacks, can be either: REGISTER_CALL_BACK or UNREGISTER_CALL_BACK event_type any one of the event types can be used: BLE_GAP_EVENT_TYPE, BLE_GATT_CLIENT_EVENT_TYPE, BLE_GATT_SERVER_EVENT_TYPE, BLE_L2CAP_EVENT_TYPE, BLE_GATT_HTPT_EVENT_TYPE, BLE_DTM_EVENT_TYPE, BLE_CUSTOM_EVENT_TYPE ble_event_handler pointer to handler list Structure ble_gap_event_cb_t defines the GAP callbacks. Similarly, structures ble_gatt_client_event_cb_t and ble_gatt_server_event_cb_t define the callbacks of GATT events. typedef struct ble_gap_event_cb /// BLE Undefined events received from SAMB11, which is not handled in Library ble_event_callback_t undefined; /// BLE scan information contains the peer device scan information Refer \ref at_ble_scan_info_t ble_event_callback_t scan_info; /// Once the BLE scan timeout or scan stop will trigger the scan report event Refer \ref at_ble_scan_report_t ble_event_callback_t scan_report; /// Advertisement complete event Refer \ref at_ble_adv_cmp_evt_t ble_event_callback_t advt_cmp; /// Advertisement report in case of advertisement stopped due to advertisement timeout Refer \ref at_ble_adv_report_t ble_event_callback_t adv_report; /// BLE device own random address changed event Refer \ref at_ble_rand_addr_changed_t ble_event_callback_t rand_addr_changed; /// BLE connected event, device connected to peer device Refer \ref at_ble_connected_t ble_event_callback_t connected; /// BLE disconnected event, device disconnected from peer device Refer \ref at_ble_disconnected_t ble_event_callback_t disconnected; /// Connection parameter update done on peer device and own device Refer \ref at_ble_conn_param_update_done_t ble_event_callback_t conn_parameter_update_done; /// Connection parameter update request from peer device Refer \ref at_ble_conn_param_update_request_t ble_event_callback_t conn_param_update_request; /// Pair complete event as part of end of pairing process Refer \ref at_ble_pair_done_t 2018 Microchip Technology Inc. Application Note DS A-page 26

27 Establishing Connection with Central Device ble_event_callback_t pair_done; /// Pair request event from Central device Refer \ref at_ble_pair_request_t ble_event_callback_t pair_request; /// Slave security request received from peer Peripheral device Refer \ref at_ble_slave_sec_request_t ble_event_callback_t slave_sec_request; /// Pair Key request event from Peer central device Refer \ref at_ble_pair_key_request_t ble_event_callback_t pair_key_request; /// encryption request comes from the peer device. Needs to supply the bonding information which is stored earlier \ref at_ble_encryption_request_t ble_event_callback_t encryption_request; /// encryption status changed event received from SMP once the encryption is started \ref at_ble_encryption_status_changed_t ble_event_callback_t encryption_status_changed; /// Event triggered once the Resolve random address is resolved using supplied IRK's. \ref at_ble_resolv_rand_addr_status_t ble_event_callback_t resolv_rand_addr_status; /// Event is triggered once the connection signature information indication received. \ref at_ble_sign_counter_t ble_event_callback_t sign_counters_ind; /// Peer attribute information indication received Event. \ref at_ble_peer_att_info_ind_t ble_event_callback_t peer_att_info_ind; /// Peer device channel map received indication. \ref at_ble_channel_map_t ble_event_callback_t con_channel_map_ind; ble_gap_event_cb_t; Note: Callback definition is application-specific. If the application layer requires a specific event callback, then the specific member of the structure is to be assigned with the address of the callback function. In this assignment, two callback functions on "Connected" and "Disconnected" GAP events are used. This allows the application to restart the advertising process on "Disconnect", manage connection information, and start/stop sensor data update Handling of Connected and Disconnected GAP Events 1. Open the startup_template_app.c file. 2. Define the following software flags as global variables in startup_template_app.c file for Connect callback function. volatile bool timer_flag = false; volatile bool connected_flag = false; 3. Declare and implement the following ble_connected_cb function in the startup_template_app.c file. /* Callback registered for AT_BLE_CONNECTED event*/ static at_ble_status_t ble_connected_cb (void *param) printf("\r\n*** Assignment 2.2: Application connected "); connected_flag = true; ALL_UNUSED(param); return AT_BLE_SUCCESS; 4. Declare and implement the following ble_disconnected_cb function in startup_template_app.c file for Disconnect callback function. /* Callback registered for AT_BLE_DISCONNECTED event */ static at_ble_status_t ble_disconnected_cb (void *param) printf("\r\n*** Assignment 2.2: Application disconnected "); connected_flag = false; start_advertisement(); ALL_UNUSED(param);return AT_BLE_SUCCESS; 5. Declare the following static GAP callback structure in startup_template_app.c file. static const ble_gap_event_cb_t app_gap_handle =.connected = ble_connected_cb, // AT_BLE_CONNECTED 2018 Microchip Technology Inc. Application Note DS A-page 27

28 Establishing Connection with Central Device.disconnected = ble_disconnected_cb, // AT_BLE_DISCONNECTED ; 6. Add the following register_samb11_callbacks function in startup_template_app.c. void register_samb11_callbacks(void) /* Register GAP Callbacks */ printf("\r\n*** Assignment 2.2: Register SAMB11 callbacks"); ble_status = ble_mgr_events_callback_handler(register_call_back,\ BLE_GAP_EVENT_TYPE,&app_gap_handle); if (ble_status!= true) printf("\r\n##error when Registering SAMB11 callbacks"); 7. Add the register_samb11_callbacks function call prior to start advertisement in the application main routine. int main(void) platform_driver_init(); acquire_sleep_lock(); /* Initialize serial console */ serial_console_init(); /* Hardware timer */ hw_timer_init(); /* button initialization */ gpio_init(); button_init(); button_register_callback(button_cb); hw_timer_register_callback(timer_callback_fn); DBG_LOG("Initializing BLE Application"); /* initialize the BLE chip and Set the Device Address */ ble_device_init(null); /* Register SAMB11 Gap Callbacks */ register_samb11_callbacks () ; /* Start Advertising process */ start_advertisement(); register_resume_callback(platform_resume_cb); /* Set ULP mode */ ble_set_ulp_mode(ble_ulp_mode_set); while(true) /* BLE Event task */ ble_event_task(ble_event_timeout); /* Write application task */ 8. Press or the F7 button to compile the project and verify that no build errors appear in the Atmel Studio output window. Figure Atmel Studio Output Window 2018 Microchip Technology Inc. Application Note DS A-page 28

29 Establishing Connection with Central Device 9. Click or press Ctrl+S to save the project. 10. Click or press Ctrl + Alt + F5 to program the project binary on the SAMB11-ZR Xplained Pro and check correct initialization of the. 11. Open the Microchip Bluetooth Data application on Android or ios device. 12. Press Bluetooth Smart. 13. Press the <Start Scan> button and pair peripherals by selecting them in the device list (pass key: ) (See the following figure). Note: 1. Pairing event handling is carried out by ble_manager.c. Refer to ble_pair_key_request_handler() for code implementation. The default pass key of is also fixed inside this function. The pass key can be changed. Figure Console Log Window Note: After peripheral pairing, no services information is displayed in the "Microchip Bluetooth Data" application, as no service is currently defined and started on peripheral side Microchip Technology Inc. Application Note DS A-page 29

30 Setup/Handling of Pre-Defined Service from Setup/Handling of Pre-Defined Service from ASF The management of services is done in the GATT layer of the ROM coded Bluetooth Low Energy stack. The GATT transactions are based on high level nested objects called "Profiles", "Services" and "Characteristics" stored in SRAM memory of the device. This assignment adds the predefined service of information service from ASF library. Figure 4-1. GATT Layers Profiles: Profiles are not available in the Bluetooth Low Energy peripheral; these profiles are simply a predefined collection of services that have been compiled by either the Bluetooth SIG (adopted GATT based profile) or by the application developer (custom profiles). For example, the Heart Rate Profile combines the Heart Rate Service and the Device Information Service. Note: The complete list of officially adopted GATT-based profiles is available on the Bluetooth Developer Portal. Services: A service is a collection of data and associated behaviors, which accomplish a particular function or feature of a device, or portions of a device. A service may reference other primary or secondary services and/or a set of characteristics that make up the service. Each service distinguishes itself from other services by means of a unique numeric ID called as UUID, which can be either 16-bit (for officially adopted Bluetooth Low Energy Services) or 128-bit (for custom services). Note: A full list of officially adopted services and their UUIDs is available on the Bluetooth Developer Portal. Characteristics: A characteristic is the lowest level concept in GATT transactions. It contains a single data point with different attributes such as notify, read, or write capabilities. Similar to Services, each characteristic can be distinguished by a SIG-defined adopted UUID (16-bit) or custom (128-bit) UUID. This UUID ensures interoperability across Bluetooth Low Energy devices. The characteristics are important to interact with in a Bluetooth Low Energy network. In addition to standard UUID, the custom UUID is used in case of specific application. When characteristics with custom UUID are used in a device, then it will be interoperable only with those devices that support these characteristics with custom UUID Microchip Technology Inc. Application Note DS A-page 30

31 Setup/Handling of Pre-Defined Service from... In this assignment, the following steps are added to the application to set up and handle a device information service within the module. The following steps are added to the startup project: Adding device info service component from ASF (refer the following figure) Configuring and loading the service Figure 4-2. Device Information Service 4.1 Adding Device Info Service Component from ASF Wizard to Project To use the officially adopted GATT-based profiles from SIG, ASF provides Bluetooth Low Energy service components such as init functions that pre-define services. Note: Before starting this assignment, be sure to follow the steps mentioned in Creating the Project and Initializing and Establishing Connection with Central Device. 1. Click ASF > ASF Wizard. 2. Search for BLE-Device Information Services(component) in the Available Modules (refer following figure) and click Add>> Microchip Technology Inc. Application Note DS A-page 31

32 Setup/Handling of Pre-Defined Service from... Figure 4-3. Available Modules Now, BLE-Device Information Services (component) appears in Selected Modules area as shown in the following figure. Figure 4-4. Selected Modules 3. Click Apply to add the component to the project. 4. Click OK to confirm the addition of BLE-Device Information Services (component) to the project in the Atmel Software Framework pop-up window Microchip Technology Inc. Application Note DS A-page 32

33 Setup/Handling of Pre-Defined Service from... Figure 4-5. Atmel Software Framework 5. The Device Information Service component is added to the project and is confirmed by device_information folder added in Solution Explorer. Figure 4-6. Device Information Service Added to Project 4.2 Configuring and Loading Device Information Service The interface driver provides a set of GATT functions that allows storing and updating the services in the memories. Prototype at_ble_status_t at_ble_primary_service_define( at_ble_uuid_t *uuid, at_ble_handle_t *service_handle, at_ble_included_service_t *included_service_list, uint16_t included_service_count, at_ble_characteristic_t *charactristic_list, uint16_t charactristic_count); Description defines a new primary service along with its included services and characteristics in. Parameters Uuid [In] primary service UUID Microchip Technology Inc. Application Note DS A-page 33

34 Setup/Handling of Pre-Defined Service from... service_handle [Out] service handle is returned here. included_service_list [In] an array of included service references. included_service_count [In] number of elements in included_service_list. charactristic_list [In/Out] an array of characteristics included in the service, this array is updated with respective characteristics handles. charactristic_count[in] number of elements in charactristic_list. Return execution status This function requires an argument as GATT description structure of the service, that is implemented. The previously added device info service component provides Bluetooth Low Energy service middleware including the init functions that predefine the services. See below dis_init_service from device info BLE service (device_info.h/.c). Prototype void dis_init_service(dis_gatt_service_handler_t *device_info_serv) Description initialize the device information service handler in the application. Parameters device_info_serv [In/out] pointer to device info, GATT description handler to be updated. Return none the following is the sample code of GATT device info service descriptor definition in the application: device_info_serv->serv_handle = 0; device_info_serv->serv_uuid.type = AT_BLE_UUID_16; device_info_serv->serv_uuid.uuid[0] = (uint8_t) DIS_SERVICE_UUID; device_info_serv->serv_uuid.uuid[1] = (uint8_t) (DIS_SERVICE_UUID >> 8); //Characteristic Info for Manufacturer Name String device_info_serv->serv_chars[0].char_val_handle = 0; /* handle stored here */ device_info_serv->serv_chars[0].uuid.type = AT_BLE_UUID_16; device_info_serv->serv_chars[0].uuid.uuid[0] = (uint8_t) IS_CHAR_MANUFACTURER_NAME_UUID; /* UUID : Manufacturer Name String */ device_info_serv->serv_chars[0].uuid.uuid[1] = (uint8_t) (DIS_CHAR_MANUFACTURER_NAME_UUID >> 8); /* UUID : Manufacturer Name String */ device_info_serv->serv_chars[0].properties = AT_BLE_CHAR_READ; /* Properties */ memcpy(char_value.manufacturer_name,default_manufacturer_name,dis_char_manufacturer_name_init_ LEN); device_info_serv->serv_chars[0].init_value = char_value.manufacturer_name; device_info_serv->serv_chars[0].value_init_len = DIS_CHAR_MANUFACTURER_NAME_INIT_LEN; device_info_serv->serv_chars[0].value_max_len = DIS_CHAR_MANUFACTURER_NAME_MAX_LEN; #if BLE_PAIR_ENABLE device_info_serv->serv_chars[0].value_permissions = AT_BLE_ATTR_READABLE_REQ_AUTHN_NO_AUTHR; /* permissions */ #else device_info_serv->serv_chars[0].value_permissions = AT_BLE_ATTR_READABLE_NO_AUTHN_NO_AUTHR; /* permissions */ #endif device_info_serv->serv_chars[0].user_desc = NULL; /* user defined name */ device_info_serv->serv_chars[0].user_desc_len = 0; device_info_serv->serv_chars[0].user_desc_max_len = 0; device_info_serv->serv_chars[0].user_desc_permissions = AT_BLE_ATTR_NO_PERMISSIONS; /*user description permissions*/ device_info_serv->serv_chars[0].client_config_permissions = AT_BLE_ATTR_NO_PERMISSIONS; / *client config permissions*/ device_info_serm hdsv->serv_chars[0].server_config_permissions = AT_BLE_ATTR_NO_PERMISSIONS; / *server config permissions*/ device_info_serv->serv_chars[0].user_desc_handle = 0; /*user desc handles*/ device_info_serv->serv_chars[0].client_config_handle = 0; /*client config handles*/ device_info_serv->serv_chars[0].server_config_handle = 0; /*server config handles*/ device_info_serv->serv_chars[0].presentation_format = NULL; /* presentation format */ 2018 Microchip Technology Inc. Application Note DS A-page 34

35 Setup/Handling of Pre-Defined Service from... Note: In case of custom service, the above definition initialization must be taken care of by the developer Procedure to Configure and Load Device Info Service 1. Include device info service header file (device_info.h) at the beginning of startup_template_app.c file. #include <asf.h> #include "platform.h" #include "at_ble_api.h" #include "console_serial.h" #include "timer_hw.h" #include "ble_manager.h" #include "ble_utils.h" #include "button.h" #include "startup_template_app.h" #include "device_info.h" 2. Define a device info service handler as global in startup_template_app.c file. /* Services handlers */ dis_gatt_service_handler_t dis_service_handler; 3. Add dis_init_service and at_ble_primary_service_define functions, above the advertisement start in main routine. /* Initialize Device Info service in GATT */ printf("\r\n*** Assignment 3.2: Start Device Info Service"); dis_init_service (&dis_service_handler) ; /* Define the primary service in the GATT server database */ if ((dis_primary_service_define (&dis_service_handler))!= AT_BLE_SUCCESS) printf("\r\n Device Information Service definition failed"); 4. Click or press Ctrl + S to save the project and compile the project by pressing or F7 button. 5. Verify that no build error appears in Atmel Studio output window. Figure 4-7. Atmel Studio Output Window 6. Click or press Ctrl+Alt+F5 to program the project binary on the SAMB11-ZR Xplained Pro. 7. Open Microchip Bluetooth Data application on Android or ios device and press Bluetooth Smart option. 8. Press Start Scan button and connect to peripheral. Note: The device name is a characteristic and contains the name of the device. This device name can be read by the central device to know the name of the device in order to differentiate the devices. This is being set using at_ble_device_name_set()api. The device name is set by default, when ble_device_init is called and the value is pre-defined using BLE_DEVICE_NAME. The device name can also be sent as part of advertisement payload to be same as the one configured in at_ble_adv_data_set() API. It is the responsibility of users to keep the device name set in advertisement payload the same as that configured in at_ble_device_name_set() Microchip Technology Inc. Application Note DS A-page 35

36 Setup/Handling of Pre-Defined Service from Now the device info service must be visible after pairing with peripheral under Microchip Bluetooth Data application. Figure 4-8. Service List in Microchip Bluetooth Data Application Note: The device must be removed using the "Forget Device" option from mobile settings in case of unsuccessful pairing between the and the app. This happens due to previously stored paring information in mobile. However, the cannot store pairing due to RESET option, as it was stored in temporary storage (RAM). 10. The serial terminal must display the following log output window Microchip Technology Inc. Application Note DS A-page 36

37 Setup/Handling of Pre-Defined Service from... Figure 4-9. Console Log Window 2018 Microchip Technology Inc. Application Note DS A-page 37

38 Setting up and Handling Custom Service 5. Setting up and Handling Custom Service The previous assignment describes the handling of Bluetooth Low Energy SIG-defined device info service, which is the predefined service available in ASF component. This assignment describes the custom service, wherein the service initialization needs to be implemented by the user. In the context of customized environment service, the following service description is pushed in the memory. Figure 5-1. Custom Service Custom Environment Service Description: UUID type Custom UUID (128-bit) UUID 1bc5d5a a687-e c1ba5af0 Characteristic 0 (Temperature) User description temperature UUID type custom UUID (128-bit) UUID 1bc5d5a a687-e d8ba5af0 Properties read notify Value permission no authorization required Client config permission no permission Server config permission no permission Note: In this definition, UUIDs are generated randomly. Custom services/characteristics are free to use any 128-bit UUID less than the base UUID. There is no reserved space for vendors to use 16-bit or 32-bit UUIDs. With this definition, any temperature change is notified to the central through notification mechanism. When "notify" property of the Client Characteristic Configuration Descriptor is enabled by the central and the device writes the new value, then this updated value is automatically sent to the central through a notification. The central is not required to send read characteristic commands explicitly to the peripheral (GATT server). To set up and handle the custom environment service in the module, the following steps are added to the application: Configure and load the custom service Update temperature characteristic and notify to the central device Receive and handle notification in the application 2018 Microchip Technology Inc. Application Note DS A-page 38

39 Setting up and Handling Custom Service Figure 5-2. Custom Service Flowchart 5.1 Configuring and Loading the Custom Environment Service The interface driver provides the following set of GATT functions that allow it to push and update the service descriptions in the SRAM memory. Note: Before starting this assignment, be sure to follow the steps mentioned in Creating the Project and Initializing and Establishing Connection with Central Device. Prototype at_ble_status_t at_ble_primary_service_define( at_ble_uuid_t *uuid, at_ble_handle_t *service_handle, at_ble_included_service_t *included_service_list, uint16_t included_service_count, at_ble_characteristic_t *charactristic_list, uint16_t charactristic_count); Description defines a new primary service along with its included services and characteristics in the. Parameters Uuid [In] primary service UUID service_handle [Out] service handle is returned here included_service_list [In] array of included service references included_service_count [In] number of elements in included_service_list charactristic_list [In/Out] an array of characteristics included in the service, updated with respective characteristics handles charactristic_count[in] number of elements in charactristic_list Return execution status Characteristics 2018 Microchip Technology Inc. Application Note DS A-page 39

40 Setting up and Handling Custom Service Characteristics definition is done through specific array of following at_ble_characteristic_t structure instances: typedef struct at_ble_handle_t char_val_handle; /**< Here the stack will store the char. value handle for future use */ at_ble_uuid_t uuid; /**< Characteristic UUID */ at_ble_char_properties_t properties; /**< Characteristic properties, values for Client Characteristic Configuration Descriptor and Server Characteristic Configuration Descriptor will be decided from this value*/ uint8_t *init_value; /**< initial value of this characteristic */ uint16_t value_init_len; /**< initial value length */ uint16_t value_max_len; /**< maximum possible length of the char. value */ at_ble_attr_permissions_t value_permissions; /**< Value permissions */ //TODO: can this value be deduced from properties field? uint8_t *user_desc; /**< a user friendly description, this value will be stored in the relevant descriptor, if no user description is desired set to NULL */ uint16_t user_desc_len; /**< the user friendly description length, this value will be stored in the relevant descriptor, if no user description is desired set to 0*/ uint16_t user_desc_max_len; /**< Maximum possible length for the user friendly description, this value will be stored in the relevant descriptor, if no user description is desired set to 0 */ at_ble_char_presentation_t *presentation_format; /**< Characteristic presentation format, this value will be stored in the relevant descriptor, if no presentation format is necessary set to NULL */ at_ble_attr_permissions_t user_desc_permissions; at_ble_attr_permissions_t client_config_permissions; at_ble_attr_permissions_t server_config_permissions; at_ble_handle_t user_desc_handle; at_ble_handle_t client_config_handle; at_ble_handle_t server_config_handle; at_ble_characteristic_t; Procedure to Configure and Load Custom Environment Service 1. Define the following service UUID and characteristic UUID in startup_template_app.c file. #define ENVIRONMENT_SERVICE_UUID 0x1b,0xc5,0xd5,0xa5,0x02,0x00,0xa6,0x87,\ 0xe5,0x11,0x36,0x39,0xc0,0xba,0x5a,0xf0 #define TEMPERATURE_CHAR_UUID 0x1b,0xc5,0xd5,0xa5,0x02,0x00,0xa6,0x87,\ 0xe5,0x11,0x36,0x39,0xd8,0xba,0x5a,0xf0 2. Define the following environment service handler and characteristics variable as global in startup_template_app.c file. /* Services handlers */ at_ble_handle_t environment_service_handler; at_ble_characteristic_t environment_service_characs[1]; 3. Add the following service initialization function custom_environment_service_init in startup_template_app.c. void custom_environment_service_init(void) at_ble_uuid_t environment_service_uuid; uint8_t serv_uuid[] = ENVIRONMENT_SERVICE_UUID; uint8_t charac0_uuid[] = TEMPERATURE_CHAR_UUID; /* Set service UUID */ environment_service_uuid.type = AT_BLE_UUID_128; memcpy(environment_service_uuid.uuid,serv_uuid,16); /* Define temperature characteristic */ environment_service_characs[0].user_desc = (uint8_t *)"Temperature"; environment_service_characs[0].user_desc_len = 10; environment_service_characs[0].user_desc_max_len = 10; environment_service_characs[0].uuid.type = AT_BLE_UUID_128; memcpy(environment_service_characs[0].uuid.uuid,charac0_uuid,16); 2018 Microchip Technology Inc. Application Note DS A-page 40

41 Setting up and Handling Custom Service environment_service_characs[0].properties = AT_BLE_CHAR_READ \ AT_BLE_CHAR_NOTIFY; environment_service_characs[0].value_max_len = sizeof(uint8_t); // length of temperature value environment_service_characs[0].value_permissions =\ (AT_BLE_ATTR_READABLE_NO_AUTHN_NO_AUTHR); /* Push service configuration in SAMB11 */ if(at_ble_primary_service_define(&environment_service_uuid,\ &environment_service_handler,null,0,\ environment_service_characs,1)!=at_ble_success) printf("\r\n*** Assignment 4.1: Failed to Initialize custom environment service"); else printf("\r\n*** Assignment 4.1: Initialize custom environment service"); 4. Declare and implement the following GATT event callback function custom_char_changed_app_event in startup_template_app.c file. If a client (central) enables notifications for a server, the server (peripheral) receives an AT_BLE_CHARACTERISTIC_CHANGED event and this event callback is called. /* Callback registered for char changed event*/ static at_ble_status_t custom_char_changed_app_event (void *param) at_ble_characteristic_changed_t *char_changed_param_handle = (at_ble_characteristic_changed_t *)param; if((environment_service_characs[0].client_config_handle == char_changed_param_handle ->char_handle) && (char_changed_param_handle->char_new_value[0])) printf("\r\n*** Assignment 4.1:Characteristic changed event"); return AT_BLE_SUCCESS; 5. Declare and implement the following custom_notification_confirmation_handler function in startup_template_app.c file. /* Callback registered for notification confirmed event*/ static at_ble_status_t custom_notification_confirmation_handler (void *param) at_ble_cmd_complete_event_t *event_param = (at_ble_cmd_complete_event_t *)param; if (event_param->status == AT_BLE_SUCCESS) printf("\r\n*** Assignment 4.1:Notification Successfully sent over the air"); else printf("\r\n*** Assignment 4.1:Sending Notification over the air failed"); return AT_BLE_SUCCESS; 6. Declare the following GATT server callback structure in startup_template_app.c file. This assignment uses two GATT callbacks. static const ble_gatt_server_event_cb_t app_gatt_server_handle =.notification_confirmed= custom_notification_confirmation_handler,.characteristic_changed = custom_char_changed_app_event, ; 7. Add the following register_gatt_server_callbacks function in startup_template_app.c to register GATT server callback for notification confirmation event. /* Register GATT callbacks at BLE manager level*/ void register_gatt_server_callbacks(void) /* Register GAP Callbacks */ printf("\r\n*** Assignment 4.1: Register GATT Server callbacks"); ble_status = ble_mgr_events_callback_handler(register_call_back,\ BLE_GATT_SERVER_EVENT_TYPE,&app_gatt_server_handle); if (ble_status!= true) printf("\r\n##error when Registering SAMB11 callbacks"); 2018 Microchip Technology Inc. Application Note DS A-page 41

42 Setting up and Handling Custom Service 8. Add custom_environment_service_init and register_gatt_server_callbacks function calls prior to start advertisement in the application main routine to initialize custom service and to register the GATT server callbacks. int main(void) platform_driver_init(); acquire_sleep_lock(); /* Initialize serial console */ serial_console_init(); /* Hardware timer */ hw_timer_init(); /* button initialization */ gpio_init(); button_init(); button_register_callback(button_cb); hw_timer_register_callback(timer_callback_fn); DBG_LOG("Initializing BLE Application"); /* initialize the BLE chip and Set the Device Address */ ble_device_init(null); /* Register SAMB11 Gap Callbacks */ register_samb11_callbacks () ; /* Custom service init */ custom_environment_service_init ( ) ; /* Register Gatt server callbacks */ register_gatt_server_callbacks ( ) ; /* Start Advertising process */ start_advertisement(); register_resume_callback(platform_resume_cb); /* Set ULP mode */ ble_set_ulp_mode(ble_ulp_mode_set); while(true) /* BLE Event task */ ble_event_task(ble_event_timeout); /* Write application task */ 9. Click or press Ctrl+S to save the project. 10. Compile the project by pressing or F7 button. 11. Verify that no build error appears in the Atmel Studio output window. Figure 5-3. Atmel Studio Output Window 12. Click or press Ctrl+Alt+F5 to program the project binary on the SAMB11-ZR Xplained Pro Microchip Technology Inc. Application Note DS A-page 42

43 Setting up and Handling Custom Service 13. Open the Microchip Bluetooth Data application and press Bluetooth Smart on Android or ios device. 14. Connect and pair to the peripheral (pass key: ). 15. Custom service must now be visible after pairing with peripheral under "Microchip Bluetooth Data" application. Figure 5-4. Service List in Microchip Bluetooth Data Application Note: If the pairing of with Microchip Bluetooth Data is not successful, then remove the pairing information from mobile by selecting Forget Device from the mobile settings. The reason for this is that the mobile app stores the previous pairing information, but the device lost the previous pairing information due to RESET since it was stored on temporary storage (RAM). Custom service is displayed as unknown service as shown in the preceding figure, as this service is not a SIG-defined service Microchip Technology Inc. Application Note DS A-page 43

44 Setting up and Handling Custom Service Figure 5-5. Generic Information 16. Serial terminal client must display the following log output. Figure 5-6. Log Output Window 5.2 Updating the Temperature Characteristic In the previous assignment, the custom Temperature characteristic is defined with a notify attribute. This attributes notify the central when a new characteristic value is available. The update of any notify characteristic value is based on following interaction between the application layer and the internal stack Microchip Technology Inc. Application Note DS A-page 44

45 Setting up and Handling Custom Service Figure 5-7. Characteristic Notification Setting a Characteristic Value ( at_ble_characteristic_value_set) Prototype at_ble_status_t at_ble_characteristic_value_set at_ble_handle_t handle, uint8_t *value, uint16_t len) Description sets a characteristic value in the memory Parameters handle [in/out] pointer to characteristic handle to be changed value [in] new value len [in] value length, in bytes Return execution status Sending a Notification (at_ble_notification_send) Prototype at_ble_status_t at_ble_notification_send( at_ble_handle_t conn_handle, at_ble_handle_t attr_handle); Description Sends a Notification Parameters conn_handle[in] handle of the connection to be notified attr_handle [in] handle of the attribute originating the notification Return Execution Status 2018 Microchip Technology Inc. Application Note DS A-page 45

46 Setting up and Handling Custom Service Sending Temperature Information Once in Every 10 Seconds to Central 1. Modify the following timer_callback_fn callback function from the startup_template_app.c file. static void timer_callback_fn(void) timer_flag = true; send_plf_int_msg_ind(ram_isr_table_timer0_index, TIMER_EXPIRED_CALLBACK_TYPE_DETECT, NULL, 0); hw_timer_init() in main routine of startup_template_app.c initializes the hardware dual timer. send_plf_int_msg_ind(ram_isr_table_timer0_index, TIMER_EXPIRED_CALLBACK_TYPE_DETECT, NULL, 0); function posts the platform event. The driver offers simple APIs to manage interrupts generated by the set of available GPIOs and peripherals on the. For these interrupts, the developer is allowed to register an interrupt callback that is to be executed upon triggering the configured interrupt source. Callbacks are executed from ISR context and then this interrupt event is messaged to the application task. Note: Callbacks are executed from ISR context, therefore it is important not to execute long routines, add delays, or print trace messages inside the interrupt callback functions as it impacts the timing of firmware task. Instead, post a platform event to the main event handling loop and add any routines inside the platform event handler. These interrupts are sent as a platform event to the application task to handle it in task context. For more details on interrupt handling in, see BluSDK SMART Interrupts and ULP - Architecture and Usage User's Guide. 2. The platform event is posted on dual timer expiry in the above step. It is required to register the platform event with the platform event callback. This callback gets called by BLE stack when the platform event is posted in Steps 2, 3, and 4 does this operation. Declare the following platform event callback structure in startup_template_app.c file. /* Platform event callback handlers */ static const ble_custom_event_cb_t app_platform_event_handle =.platform_event_ready = platform_interrupt_app_event /* This event not handled in BLE Manager */ ; 3. Add the following register_platform_event_callbacks() function in startup_template_app.c to register the platform event callback for user-defined events. /* Register platform event callback for user defined events*/ void register_platform_event_callbacks(void) /* Register callbacks for user defined custom events */ printf("\r\n*** Assignment 4.2: Register Platform callback"); ble_status = ble_mgr_events_callback_handler(register_call_back, BLE_CUSTOM_EVENT_TYPE,&app_platform_event_handle); if (ble_status!= true) printf("\r\n##error when Registering SAMB11 callbacks"); 4. Add register_platform_event_callbacks() function call prior to start advertisement in the application main routine to register the platform callbacks. As this exercise uses dual timer for sending notification and dual timer is not active in the ULP mode, stop entering to the ULP mode. This is done by changing ble_set_ulp_mode(ble_ulp_mode_set); to ble_set_ulp_mode(ble_ulp_mode_clear); as highlighted below. For more details on interrupt handling in, see BluSDK SMART Interrupts and ULP - Architecture and Usage User's Guide. int main(void) 2018 Microchip Technology Inc. Application Note DS A-page 46

47 Setting up and Handling Custom Service platform_driver_init(); acquire_sleep_lock(); /* Initialize serial console */ serial_console_init(); /* Hardware timer */ hw_timer_init(); /* button initialization */ gpio_init(); button_init(); button_register_callback(button_cb); hw_timer_register_callback(timer_callback_fn); DBG_LOG("Initializing BLE Application"); /* initialize the BLE chip and Set the Device Address */ ble_device_init(null); /* Register SAMB11 Gap Callbacks */ register_samb11_callbacks () ; /* Custom service init */ custom_environment_service_init ( ) ; /* Register Gatt server callbacks */ register_gatt_server_callbacks ( ) ; /* Register SAMB11 Platform Callbacks */ register_platform_event_callbacks(); /* Start Advertising process */ start_advertisement(); register_resume_callback(platform_resume_cb); /* Clear ULP mode */ ble_set_ulp_mode(ble_ulp_mode_clear); while(true) /* BLE Event task */ ble_event_task(ble_event_timeout); /* Write application task */ 5. If a client (central) enables the notifications for a server, the server (peripheral) receives an AT_BLE_CHARACTERISTIC_CHANGED event callback, then start the periodic 10 second timer for sending the notification. Add the following code in previously defined custom_char_changed_app_event function. /* Callback registered for char changed event*/ static at_ble_status_t custom_char_changed_app_event (void *param) at_ble_characteristic_changed_t *char_changed_param_handle = (at_ble_characteristic_changed_t *)param; if((environment_service_characs[0].client_config_handle == char_changed_param_handle ->char_handle) && (char_changed_param_handle->char_new_value[0])) timer_flag = false; hw_timer_start(10); printf("\n*** Assignment 4.1:Characteristic changed event"); return AT_BLE_SUCCESS; 2018 Microchip Technology Inc. Application Note DS A-page 47

48 Setting up and Handling Custom Service 6. Declare the following Temperature_value global variable as static in startup_template_app.c. static uint8_t Temperature_value = 25; 7. Add the following send_temperature_notification function in startup_template_app.c to send temperature every 10 seconds. /* Register GATT callbacks at BLE manager level*/ void send_temperature_notification(void) /* Register GAP Callbacks */ printf("\n*** Assignment 4.2: Send temperature update notification"); /* Dummy temperature value */ Temperature_value++; if(temperature_value > 75) Temperature_value = 25; /* Update attribute data base */ ble_status = at_ble_characteristic_value_set(\ environment_service_characs[0].char_val_handle,\ (uint8_t *)&Temperature_value,\ sizeof(temperature_value)); ble_status = at_ble_notification_send(0,\ environment_service_characs[0].char_val_handle); if(ble_status!= AT_BLE_SUCCESS) printf("\r\nfail to send temperature update notification "); 8. The platform event registered in steps 2, 3, and 4 passes a callback which will be called when the specific platform event is posted in step 1. Add the following code to add AT_PLATFORM_EVENT callback function. When this callback is called, it initiates sending of temperature notification. /* Callback registered for AT_PLATFORM_EVENT event from stack */ static at_ble_status_t platform_interrupt_app_event(void *param) at_ble_status_t status = AT_BLE_SUCCESS; platform_isr_event_t *plf_isr_event = (platform_isr_event_t *)param; /* Flag to start temperature notification */ if ((plf_isr_event->event_type == ((TIMER_EXPIRED_CALLBACK_TYPE_DETECT << 8) RAM_ISR_TABLE_TIMER0_INDEX))) if(connected_flag == true && timer_flag == true) send_temperature_notification(); timer_flag = false; return status; 9. Click to save the project <Ctrl+S>. 10. Compile the project by pressing the button <F7>. 11. Verify that no build error appears in Atmel Studio output window. Figure 5-8. Atmel Studio Output Window 12. Click to program the project binary on the SAMB11-ZR Xplained Pro. 13. Open the Microchip Bluetooth Data Application on Android or ios device Microchip Technology Inc. Application Note DS A-page 48

49 Setting up and Handling Custom Service 14. Connect and pair to the peripheral (pass key: ). 15. Click NOTIFY to start the notification. 16. Temperature information in HEX values must be displayed in the "Microchip Bluetooth Data" application. Figure 5-9. Notification Window 17. Serial terminal must display the following log output: Figure Log Output Window 2018 Microchip Technology Inc. Application Note DS A-page 49