Home

BlueNRG, BlueNRG-MS stacks programming guidelines

1. Procedure Description Notes Role Limited It is used for discovery Device filtering is applied discoverable peripheral devices in limited based on Flags AD type Central procedure discovery mode information General i p bae id qiscovery Device filtering is applied peripheral devices in discoverable m based on Flags AD type Central general ad limited discovery procedure information mode It is the procedure for Name discovery retrieving the Bluetooth Central procedure Device Name from connectable devices Table 26 GAP connection procedures Procedure Description Notes Role Allows the connection with Auto connection one or more devices in the establishment directed connectable mode It uses white lists Central procedure or the undirected connectable mode Allows a connection with a lt SUPP oris private Addresses General by using the direct connection set of known peer devices in connection establishment procedure when the directed connectable Central establishment it detects a device with a mode or the undirected procedure private address during the connectable mode passive scan Establish a connection with Selective the Host selected MES connection It uses white lists and it scans connection configuration f Sz Central establishment by this white list r ced r parameters with a set of P devices in the White List Establish a con
2. Data packet header Table 5 Data packet header content Link layer Next sequence Sequence More data Reserved identifier number number 2 bits 1 bit 1 bit 1 bit 3 bits The next sequence number NESN bit is used for performing packet acknowledgments It informs the receiver device of the next sequence number that the transmitting device is expecting it to send Packet is retransmitted until the NESN is different from the sequence number SN value in the sent packet More data bit is used to signal to a device that the transmitting device has more data ready to be sent during the current connection event For a detailed description of advertising and data header contents amp types refer to the Bluetooth specification v4 0 Vol 2 on Section 5 References e Length number of bytes on data field Table 6 Packet length field and valid values Advertising packet Length field bits 6 bits with valid values from 0 to 37 bytes Data packet 5 bits with valid values from 0 to 31 bytes e Data or payload itis the actual transmitted data advertising data scan response data connection establishment data or application data sent during the connection e CRC 24 bits it is used to protect data against bit errors It is calculated over the header length and data fields d DoclD027104 Rev 3 PM0237 Bluetooth low energy technology 1 3 2 d Advertisi
3. PM0237 Design an application using BlueNRG BlueNRG MS ACI APIs d const uint8 t charUuid 2 16 0x66 0x9a 0x0c 0x20 0x00 0x08 0x96 0x9e 0xe2 0x11 0x9e 0xb1 0xe2 0xf2 0x7 3 0xd9 Add the service with service uuid 128bits UUID to the GATT server database The service handle ServHandle is returned 2y ret aci gatt add serv UUID TYPE 128 service uuid PRIMARY SERVICE 7 amp ServHandle if ret BLE STATUS SUCCESS PRINTF Failure n Add the characteristic with charUuid_1 128bits UUID to the service ServHandle This characteristic has 20 as Maximum length of the characteristic value Notify properties CHAR PROP NOTIFY no security permissions ATTR PERMISSION NONE no GATT event mask 0 16 as key encryption size and variable length characteristic 1 The characteristic handle CharHandle 1 is returned ret aci gatt add char ServHandle UUID TYPE 128 charUuid 1 20 CHAR PROP NOTIFY ATTR PERMISSION NONE 0 16 1 amp CharHandle 1 if ret BLE STATUS SUCCESS PRINTF Failure n Add the characteristic with charUuid_2 128bits UUID to the service ServHandle This characteristic has 20 as Maximum length of the characteristic value Read Write and write without response properties no security permissions ATTR PERMISSION NONE notify application when attribute is written GATT_NOTIFY_ATTRIBUTE WRITE as GATT event mask 16 as key encryption size and variable
4. Define Description GAP CENTRAL GAP central role GAP PERIPHERAL GAP peripheral role GATT CLIENT GATT client role GATT SERVER DoclD027104 Rev 3 GATT server role 41 97 Design an application using BlueNRG BlueNRG MS ACI APIs PM0237 3 1 42 97 Initialization phase and main application loop The following main steps are required for properly configure the selected external microcontroller and the SPI communication with a BlueNRG or BlueNRG MS device 1 Initialize the STM32L device clock configuration GPIOs 2 Configure selected BlueNRG platform 3 Initialize the serial communication channel used for I O communication debug and utility information Initialize list heads of ready and free hci data packet queues Init SPI interface for allowing external microcontroller to get access to the BlueNRG features properly Reset the BlueNRG BlueNRG MS network coprocessor Configure BlueNRG BlueNRG MS public address if public address is used Init BLE NRG GATT layer Init BLE NRG GAP layer depending on the selected device role 0 Set the proper security I O capability and authentication requirement if BLE NRG security is used 11 Define the required Services amp Characteristics if the device is a GATT server 12 Add a while 1 loop calling the HCl Process API and a specific user application function where user actions events are processed advertising connections servi
5. Find included services Read by type response event Discovery all characteristics of a service Read by type response Discovery characteristics by UUID Read by type response Discovery all characteristics descriptors Find information response Table 17 Client initiated procedures and related response events Procedure Read characteristic value Response events Read response event Read characteristic value by UUID Read response event Read long characteristic value Read blob response events Read multiple characteristic values Read response event Write characteristic value without response Signed write without response No event is generated No event is generated Write characteristic value Write response event DoclD027 104 Rev 3 25 97 Bluetooth low energy technology PM0237 1 9 26 97 Table 17 Client initiated procedures and related response events continued Procedure Write long characteristic value Response events Prepare write response Execute write response Reliable write Prepare write response Execute write response Table 18 Server initiated procedures and related response events Procedure Response events Notifications No event is generated Indications Confirmation event For a detailed description about the GATT procedures and related responses events r
6. MAC address needs to be stored somewhere in the non volatile memory associated to the product during product manufacturing A user can write its application assuming that the MAC address is placed at a known Flash location of the microcontroller During manufacturing the microcontroller can be programmed with the customer Flash image via JTAG A second step could involve generating the unique MAC address i e reading it from a database and storing of the MAC address in the known location in a free 48 bits area of the Flash When the microcontroller s application needs to access the MAC address simply refers to the known Flash memory location DoclD027104 Rev 3 47 97 Design an application using BlueNRG BlueNRG MS ACI APIs PM0237 48 97 Figure 9 MAC address storage uC memory map This value change for each device MAC address Application code The application code is the same for all devices Alternatively the MAC address can be stored in a free area of the BlueNRG and BlueNRG MS devices Information register IFR region but this does not offer any advantage since e Programming of the MAC in the IFR requires several SPI transaction as follows Make the device entering Updater mode 1 SPI transaction Program the device IFR with MAC address 1 SPI transaction Make the device leaving Updater mode 1 SPI transaction e Access to the MAC address during device initialization at each
7. The Read by group type response is sent in reply to a received Read by group type request and contains the handles and values of the attributes that have been read EVT VENDOR GATT client EVT BLUE ATT READ BY TYPE RESP The Read by type response is sent in reply to a received Read By Type Request and contains the handles and values of the attributes that have been read EVT VENDOR GATT client EVT BLUE GAP DEVICE FOUND only for BlueNRG device Event given by the GAP layer to the upper layers when a device is discovered during scanning as a consequence of one of the GAP procedures started by the upper layers EVT VENDOR GAP central EVT BLUE GATT PROCEDURE COMPLETE A GATT procedure has been completed EVT VENDOR GATT client BlueNRG MS device EVT LE ADVERTISING REPORT only for Event given by the GAP layer to the upper layers when a device is discovered during scanning as a consequence of one of the GAP procedures started by the upper layers EVT LE META EVENT GAP central For a detailed description about the BLE events and related formats refer to the user manual UM1755 and on Table 38 ACI GAP modes APIs in the current document The following pseudocode provides an example of HCT Event CB callback handling some of the described device events EVT DISCONN COMPLETE EVT LE CONN COMPLETE EVT BLUE GATT ATTRIBUTE MODIFIED EVT BLUE GATT NOTIFICA
8. The following pseudocode example illustrates only the specific steps to be followed for providing the pass key for example a random pin to be used for the pairing process when the EVT BLUE GAP PASS KEY REQUEST event is generated on Device 1 Display Only capability tBleStatus ret Generate a random pin with an user specific function pin generate random pin ret aci gap slave security request conn handle BONDING MITM PROTECTION REQUIRED if ret BLE STATUS SUCCESS PRINTF Failure n Since the Device 1 VO capability is set as Display Only it should display the generated pin in the device display Since Device 2 VO capability is set as Keyboard Only the user can provide the pin displayed on Device 1 to the Device 2 though the same aci gap pass key response API by a keyboard DoclD027104 Rev 3 67 97 Design an application using BlueNRG BlueNRG MS ACI APIs PM0237 68 97 Alternatively if the user wants to set the authentication requirements with a fixed pin 0x123456 no pass key event is required the following pseudocode can be used tBleStatus ret ret aci gap set auth requirement MITM PROTECTION REQUIRED OOB AUTH DATA ABSENT NULL 7 16 USE FIXED PIN FOR PAIRING 0x123456 Fixed pin BONDING if ret BLE STATUS SUCCESS PRINTF Failure n NOTEs 1 When the pairing procedure is started by calling the described APIs aci gap slave
9. wa PM0237 y iid d Programming manual BlueNRG BlueNRG MS stacks programming guidelines Introduction The main purpose of this document is to provide a developer with some reference programming guidelines about how to develop a Bluetooth low energy BLE host applications using BlueNRG BlueNRG MS stacks APIs The document describes the BlueNRG BlueNRG MS stacks architecture APIs interface and callbacks allowing to get access to the Bluetooth low energy functions provided by the BlueNRG BlueNRG MS network coprocessors This programming manual also provides some fundamental concepts about the Bluetooth low energy BLE technology in order to associate the BlueNRG BlueNRG MS APIs parameters and related events with the BLE protocol stack features It is assumed that the user already has a basic knowledge about the BLE technology and its main features For more information related to the full set related to the BlueNRG BlueNRG MS devices and the Bluetooth specification v4 0 and v4 1 refer to Section 5 References at the end of this document The BlueNRG is a very low power Bluetooth low energy BLE single mode network processor compliant with Bluetooth specification v4 0 and supporting master or slave role The BlueNRG MS is a very low power Bluetooth low energy BLE single mode network processor compliant with Bluetooth specification v4 1 and supporting both master and slave roles The manual is structured as follows
10. Attribute Attribute type Attribute value m permissions Characteristic value properties read broadcast write write without response notify indicate Determine how characteristic value can be used or how Read only characteristic descriptor can be accessed No authentication No authorization 0x2803 UUID for characteristic attribute type Characteristic value attribute handle Characteristic value UUID 16 or 128 bits DoclD027104 Rev 3 23 97 Bluetooth low energy technology PM0237 1 8 2 1 8 3 24 97 A characteristic declaration contains the value of the characteristic This value is the first attribute after the characteristic declaration Table 13 Characteristic value Attribute handle Attribute type Attribute value Attribute permissions Oxuuuu 16 bits or 128 OxNNNN bits for characteristic Characteristic value UUID Higher layer profile or implementation specific Characteristic descriptors type Characteristic descriptors are used to describe the characteristic value for adding a specific meaning to the characteristic and making it understandable by the user The following characteristic descriptors are available 1 Characteristic extended properties it allows to add extended properties to the characteristic 2 Characteristic user description it enables the device to associate a text string to the characteristic 3 Client characteristi
11. Slot 1 offset 0 ms CE len min 10 ms Slot 1 len 20 ms CE_len_max 20 ms Slot 1 latency 1 gt gt Anchor Period B Second connection ConnIntMin 250 ms Anchor Period 200 ms Connection Interval 400 ms ConnIntMax 500 ms Slot 2 offset 21 5 ms CE len min 10 ms Slot 2 len 50 ms CE_len_max 50 ms Slot 2 latency 2 S E 2 E Anchor Period C Third connection ConnIntMin 50 ms Anchor Period 100 ms Connection Interval 100 ms ConnintMax 150 ms Slot 3 offset 73 ms CE len min 10 ms Slot 3 len 225 5 ms CE len max 100 ms Slot 1 latency 2 Slot 2 latency 4 Slot 3 latency 1 s S s S s 5 S 2 3 3 3 3 2 3 Anchor Period 4 2 3 Timing for Advertising Events The periodicity of the advertising events controlled by advinterval is computed based on the following parameters specified by the Slave through the Host in the HCI LE Set Advertising parameters command e Advertising Interval Min Advertising Interval Max e Advertising Type if Advertising Type is set to High Duty Cycle Directed Advertising then Advertising Interval is set to 3 75ms regardless of the values of Advertising Interval Min and Advertising Interval Max in this case a Timeout is also set to 1 28 s that is the maximum duration of the Advertising event for this case In all other cases the Advertising Interval is chosen equal to the mean value between Advertising Interval Min 5 ms
12. Write Parameters 4 The GAP_Init role parameter values are as follows Table 36 GAP_Init role parameter values Device Role parameter values Note BlueNRG 0x01 Peripheral Broadcaster Observer are not 0x03 Central supported on BlueNRG device 0x01 Peripheral The role parameter can be a 0x02 Broadcaster bitwise OR of any of the BlueNRG MS 0x04 Central supported values multiple roles 0x08 Observer simultaneously support Further on BlueNRG MS stack two new parameters are available on GAP_Init API enable Privacy 0x00 for disabling privacy 0x01 for enabling privacy device name char len it allows to indicate the length of the device name characteristic For a complete description of this API and related parameters refer to the UM1755 and UM1865 User Manuals on the Section 5 References d 46 97 DoclD027104 Rev 3 PM0237 Design an application using BlueNRG BlueNRG MS ACI APIs 3 1 1 3 BLE addresses The following device addresses are supported from BlueNRG and BlueNRG MS devices e Public address e Random address e Private address Public MAC addresses 6 bytes 48 bits address uniquely identifies a BLE device and they are defined by Institute of Electrical and Electronics Engineers IEEE The first 3 bytes of the public address identify the company that issued the identifier and are known as the Organizationally Unique Identifier OUI A
13. and Advertising Interval Max 5ms The Advertising hasn t a maximum duration as in the previous case but it s stopped only if a Connection is established or upon explicit request by Host The length of each advertising event is set by default by the SW to be equal to 14 6ms i e the maximum allowed advertising event length and it cannot be reduced Advertising slots are allocated within the same time base of the master slots i e scanning and connection slots For this reason the Advertising Enable command to be accepted by the SW when at least one master slot is active the Advertising Interval has to be an integer multiple of the actual Anchor Period 90 97 DoclD027104 Rev 3 Ly PM0237 BlueNRG multiple connections timing strategy 4 2 4 4 2 5 4 3 d Timing for scanning Scanning timing is requested by the Master through the following parameters specified by the Host in the HCI LE Set Scan parameters command LE Scan Interval used to compute the periodicity of the scan slots LE Scan Window used to compute the length of the scan slots to be allocated into the master time base Scanning slots are allocated within the same time base of the other active master slots i e connection slots and of the advertising slot if there is one active In order the Scanning Enable command to be accepted by the SW the LE Scan Interval has to be an integer multiple of the actual anchor period Every time t
14. and set them during the initialization phase of the BlueNRG BlueNRG MS device Following is a simple pseudo code showing how to set the read randomly generated security root keys on BlueNRG BlueNRG MS devices uint8 t DIV 2 uint8 t ER 16 uint8 t IR 16 Reset BlueNRG BlueNRG MS device BlueNRG RST Microcontroller specific implementation 1 MCU has to randomly generate DIV ER and IR and store them in a non volatile memory 2 When MCU starts it has to read DIV ER and IR values from the non volatile memory Configure read root key DIV on BlueNRG BlueNRG MS device ret aci hal write config data CONFIG DATA DIV OFFSET CONFIG DATA DIV LEN uint8 t DIV Configure read root key ER on BlueNRG BlueNRG MS device ret aci hal write config data CONFIG DATA ER OFFSET CONFIG DATA ER LEN uint8 t ER Configure read root key IR on BlueNRG BlueNRG MS device DoclD027104 Rev 3 65 97 Design an application using BlueNRG BlueNRG MS ACI APIs PM0237 66 97 ret aci hal write config data CONFIG DATA IR OFFSET CONFIG DATA IR LEN uint8 t IR To successfully pair with a device IO capabilities have to be correctly configured depending on the IO capabilily available on the selected device aci gap set io capability io capability should be used with one of the following io capability value 0x00 Display Only 0x01 Display yes no 0x02 Keyboard Only 0x03 No Input no ou
15. bond information so it has to start the pairing procedure again As a consequence the slave device receives the EVT BLUE GAP BOND LOST event to inform the host application that it is not bonded anymore with the master it was previously bonded Then the slave application can decide to allow the security manager to complete the pairing procedure and re bond with the master by calling the command aci gap allow rebond or just close the connection and inform the user about the security issue 4 Alternatively the out of band method can be selected by using the aci gap set auth requirement with OOB Enable field enabled and the OOB data DoclD027104 Rev 3 Ly PM0237 Design an application using BlueNRG BlueNRG MS ACI APIs specified in OOB_Data This implies that both devices are using this method and they are setting the same OOB data defined through an out of band communication example NF C 3 6 Service and characteristic discovery This section describes the main functions allowing a BlueNRG BlueNRG MS GAP central device to discover the GAP peripheral services amp characteristics once the two devices are connected The sensor profile demo services amp characteristics with related handles are used as reference services and characteristics on the following pseudocode examples Further it is assumed that a GAP central device is connected to a GAP peripheral device running the Sensor Demo profile appl
16. 0x65 0x73 0x74 ret aci gap set discoverable Advertising Type 0x00 Advertising Interval Min 0x20 Advertising Interval Max 0x100 Local Name Length z0x05 Local Name 0x08 0x74 0x65 0x73 0x74 Slave Conn Interval Min 0x0006 DoclD027104 Rev 3 Ly PM0237 Design an application using BlueNRG BlueNRG MS ACI APIs Note d Slave Conn Interval Max 0x0008 Since Master amp Slave device is also acting as a Central device it receives the EVT BLUE GATT NOTIFICATION event related to the characteristics values notified from respectively Slave A and Slave B devices 9 Once Master amp Slave device enters in discovery mode it also waits for connection request coming from the other BlueNRG MS device called Master configured as GAP Central Master device starts discovery procedure for discovering the Master amp Slave device ret aci gap start gen disc proc LE Scan Interval 0x10 LE Scan Window 0x10 Master amp Slave device is discovered thorugh the EVT LE ADVERTISING REPORT event 10 Once the Master amp Slave device is discovered Master device starts a connection procedure for connecting to it Master device connects to Master amp Slave device Master amp Slave addreess type and address have been found during the discovery procedure within the EVT LE ADVERTISING REPORT event ret aci gap create connection LE Scan Interval 0x0010 LE Scan Window 0x0010 Peer Address Type Master amp Slave
17. 37 Table 38 Table 39 Table 40 Table 41 Table 42 Table 43 Table 44 Table 45 Table 46 Table 47 Table 48 Ly BLE RF channel types and frequencies Ee SE ES ee ee eee 10 Advertising data header file content EE EE EE eee 12 Advertising packet typeS EE EE EG EE Re ee ee ee ee ee ee ee ee ee ee 13 Advertising event type and allowable responses EE EE EE EE Ee ee ee 14 Data packet header content EE EE EE SE EE ete ee 14 Packet length field and valid values ie EE EE ee n 14 Connection request timings intervals llle 17 Attribute example ii EE EE EE EE EE EE Ee ee EE ee Ge ee ee rs 19 Attributes protocol messages EE EE EE EE ee ee Re ee ee ee See ee eae 19 Combination of Input Output capabilities on a BLE device SS SS SS SS cee 20 Methods used for calculating the Temporary Key TE EE ee eee ee eae 21 Characteristic declaration anaa aaaea EE EE EE ee ee ee es 23 Characteristic value eenaa n euda aaa a Ee ee ee ee ee ee ee ee a ee se ee ee 24 Service declaration EE cece tees 24 Include declaration EE EE EE EG ee ete 25 Discovery procedures and related response events EE EE se eee eee 25 Client initiated procedures and related response events EE EE EE ee 25 Server initiated procedures and related response events EE EE ee ee 26 GAP roles sies Ds re o s o EE ea a HR TRU ed Se PE ee 26 GAP broadcaster mod
18. BlueNRG MS events and events Callback Whenever there is an ACI event to be processed the ACI framework notifies this event to the user application through the Hc1 Event CB callback The Hc1 Event CB callback is called within the HCI Process on file hci c As a consequence user application is requested to 1 Define the void HCI Event CB void pckt function within his main application pckt is a pointer to the received ACI packet 2 Based on its own application scenario the user has to identify the required device events to be detected and handled and the application specific actions to be done as consequence of such events When implementing a BLE application the most common and widely used device events are the ones related to the discovery connection terminate procedures services and characteristics discovery procedures attribute modified events on a GATT server and attribute notification indication events on a GATT client Table 37 ACI main events sub events or the pairing has failed Event sub event Description Main event Where GAP EVT DISCONN COMPLETE A connection is terminated NA central peripheral Indicates to both of the Hosts GAP EVT LE META EVT LE CONN COMPLETE forming the connection that a new central A EVENT connection has been established peripheral Generated by the GATT server when a client modifies any GATT EVT BLUE GATT
19. address type Peer Address Master amp Slave address Conn Interval Min 0x6c Conn Interval Max 0x6c Conn Latency 0x00 Supervision Timeout 0xc80 Minimum CE Length 0x000c Maximum CE Length 0x000c 11 Once connected Master device enables the characteristic notification on Master amp Slave device using the aci gatt write charac descriptor API 12 Atthis stage Master amp Slave device receives the characteristics notifications from both Slave A Slave B devices since it is a GAP Central and as GAP Peripheral it is also able to notify these characteristics values to the Master device A set of test scripts allowing to exercise the described BlueNRG MS simultaneously Master Slave scenario are provided within the BlueNRG DK SW package see Reference Section These scripts can be run using the BlueNRG GUI and they can be taken as reference for implementing a firmware application using the BlueNRG MS simultaneously master and slave feature DoclD027104 Rev 3 85 97 BlueNRG multiple connections timing strategy PM0237 4 4 1 86 97 BlueNRG multiple connections timing strategy This section provides an overview of the connection timing management strategy of BlueNRG when multiple Master and Slave connections are active Basic concepts about Bluetooth Low Energy timing This section describes the basic concepts related to the Bluetooth Low Energy timing management related to the advertising scanning and
20. all the characteristics of a given service This API starts the GATT the procedure to aci gatt discovery characteristic by uuid discover all the characteristics specified by a UUID This API starts the procedure to discover all characteristic descriptors on the GATT server aci gatt disc all charac descriptors In the context of the BlueNRG sensor profile demo follow a simple pseudocode illustrating how a GAP Central application can discover all the characteristics of the Acceleration service refer to Section Table 49 Second evt att read by group resp event data uintl16 t service handle uintl16 t end group handle ifdef BLUENRG MS service handle 0x000C end group handle 0x0012 else service handle value 0x0010 charac handle value 0x0016 endif BlueNRG GAP Central starts a discovery all the characteristics of a service procedure conn handle is the connection handle returned on HCI Event CB event callback EVT LE CONN COMPLETE event if aci gatt disc all charac of serv conn handle Service handle Service handle end group handle End group handle BLE STATUS SUCCESS if ret BLE STATUS SUCCESS PRINTF Failure n The responses of the procedure are given through the EVT BLUE ATT READ BY TYPE RESP event raised on HCI Event CB callback EVT_VENDOR as main event The end of the procedure is indicated by EvT BLUE GATT PROCEDURE
21. and the authentication requirements e There are three input capabilities a no input b the ability to select yes no c the ability to input a number by using the keyboard e There are two output capabilities No output Numeric output ability to display a six digit number Table 10 Combination of Input Output capabilities on a BLE device No output Display No input No Input No output Display Only Yes No No Input No output Display Yes No Keyboard Keyboard only Keyboard Display The information exchanged in Phase 1 is used to select which STK generation method is used in Phase 2 Phase 2 short term key STK generation e The pairing devices first define a Temporary Key TK by using one of the following methods a The out of band OOB method which uses out of band communication example NFC for the TK agreement it is selected if the out of band bit is set b Passkey Entry method user passes six numeric digits as the TK between the devices c Just Works this method is not authenticated and it does not provide any protection against man in the middle MITM attacks 3 DoclD027104 Rev 3 PM0237 d The selection between PassKey and Just Works method is done based on the following table Table 11 Methods used for calculating the Temporary Key TK Display Keyboard No Input No Keyboard Display only Yes No only Output display p Just Works Just Works Pas
22. at the same time imposes some constraints to the actual connection parameters that the controller can accept An example of the time base parameters and connection slots allocation is shown in Figure 12 Figure 12 Example of allocation of three connection slots Slot 1 has offset 0 with respect to the anchor period Slot 2 has slot latency 2 all slots are spaced by 1 25 ms guard time Setting the timing for the first Master connection The time base mechanism above described is actually started when the first Master connection is created The parameters of such first connection determine the initial value for the anchor period and influence the timing settings that can be accepted for any further Master connection simultaneous with the first one In particular e Theinitial anchor period is chosen equal to the mean value between the maximum and minimum connection period requested by the Host e The first connection slot is placed at the beginning of the anchor period e The duration of the first connection slot is set equal to the maximum of the requested connection length Clearly the relative duration of such first connection slot compared to the anchor period limits the possibility to allocate further connection slots for further Master connections d DoclD027104 Rev 3 PM0237 BlueNRG multiple connections timing strategy 4 2 2 d Setting the timing for further Master connections Once th
23. bluenrg aci h bluenrg updat Header file with updater commands for u It is included by er aci h BlueNRG FW stack bluenrg aci h ACI Interface resources In order to communicate with BlueNRG or BlueNRG MS network processor through the ACI interface framework the external microcontroller requires only the following main resources 1 SPI interface 2 Platform dependent code to write read to from SPI 3 A timer to handle SPI timeouts The BlueNRG BlueNRG MS SPI interface is handled through the functions defined on files SDK EVAL SPI Driver ch and hal ch These APIs allows the external microcontroller to get access to BlueNRG or BlueNRG MS device The BlueNRG BlueNRG MS devices use the SPI IRQ pin to notify the external microcontroller SPI master when it has data to be read this is handled through the HCI Isr placed within the SPI IRQ IROHandler handler on file stm32l1xx it c Standard library framework and within the HAL GPIO EXTI Callback on file bluenrg interface c Cube library framework The SPI IRQ handler is associated to the proper EXTI irq handler based on the selected platform GPIO line for the BlueNRG BlueNRG MS SPI interrupt line The BlueNRG BlueNRG MS kits platforms are targeting the STM32L1xx microcontroller and the related libraries are used in order to get access to the device peripheral Two frameworks are available 1 STM32L1xx standard libraries which are provided within the platform STM32L1 XX Librari
24. can interpreted as follows refer to Bluetooth specification version 4 0 Vol 3 and 4 1 Vol 2 Table 44 Scan response data Scan response data 0x12 data length 0x11 length of service UUID advertising data 0x06 128 bits service UUID type 0x66 0x9A 0x0C 0x20 0x00 0x08 0xA7 0xBA 0xE3 0x11 0x06 0x85 0xC0 0xF7 0x97 0x8A 128 bits service UUID d DoclD027104 Rev 3 PM0237 Design an application using BlueNRG BlueNRG MS ACI APIs 3 5 d Security pairing and bonding This section describes the main functions to be used in order to establish a pairing between two devices authenticate the devices identity encrypt the link and distribute the keys to be used on coming next reconnections When using the security features some low level parameters root keys must be set before raising any other ACI commands e DIV root key used to derive CSRK e Encryption root ER key used to derive LTK and CSRK e identity root IR key used to derive IRK and CSRK The external microcontroller MCU has the responsibilities to provide these parameters as follows 1 It has to randomly generate the three root key values if not already generated and store them in a non volatile memory The three root keys have to be generated only one time in order to univocally establish the specific BlueNRG BlueNRG MS device security settings 2 Each time the MCU starts it has to read the root keys from the non volatile memory
25. connections procedures as Central for connecting respectively to Slave A and Slave B devices Connect to Slave A Slave A addreess type and address have been found during the discovery procedure within the EVT LE ADVERTISING REPORT event 7 ret aci gap create connection LE Scan Interval 0x0010 LE Scan Window 0x0010 Peer Address Type Slave A address type Peer Address Slave A address Conn Interval Min 0x6c Conn Interval Max 0x6c Conn Latency 0x00 Supervision Timeout 0xc80 Minimum CE Length 0x000c Maximum CE Length 0x000c Connect to Slave B Slave B addreess type and address have been found during the discovery procedure within the EVT LE ADVERTISING REPORT event ud ret aci gap create connection LE Scan Interval 0x0010 LE Scan Window 0x0010 Peer Address Type Slave B address type Peer Address Slave B address Conn Interval Min 0x6c Conn Interval Max 0x6c Conn Latency 0x00 Supervision Timeout 0xc80 Minimum CE Length 0x000c Maximum CE Length 0x000c 7T Once connected Master amp Slave device enables the characteristics notification on both of them using the aci gatt write charac descriptor API Slave A and Slave B devices start the characterisitic notification by using the aci gatt upd char val API 8 Atthis stage Master amp Slave device enters in discovery mode acting as Peripheral Put Master amp Slave device in Discoverable Mode with Name Test 0x08 0x74
26. connections operations Advertising timing The timing of the advertising state is characterized by 3 timing parameters linked by this formula T advEvent advinterval advDelay where T_advEvent time between the start of two consecutive advertising events if the advertising event type is either a scannable undirected event type or a non connectable undirected type the advInterval shall not be less than 100 ms if the advertising event type is a connectable undirected event type or connectable directed event type used in a low duty cycle mode the advlnterval can be 20 ms or greater e advDelay pseudo random value with a range of 0 ms to 10 ms generated by the Link Layer for each advertising event Figure 11 Advertising timings Advertising Advertising Advertising Event Event Event T advEvent T advEvent T advlnterval advlnterval i z Advertising State entered d DoclD027104 Rev 3 PM0237 BlueNRG multiple connections timing strategy 4 1 2 4 2 d Scanning timing The timing of the scanning state is characterized by 2 timing parameters e scanlnterval defined as the interval between the start of two consecutive scan windows e scanWindow time during which Link Layer listens on an advertising channel index The scanWindow and scanlnterval parameters shall be less than or equal to 10 24 s The scanWindow shall be less than or equal to the scanlnterval Connection Timing T
27. data length 0x0D length of the event data pr handle value pair length 0x06 length of each discovered service data service handle end group handle service uuid DoclD027104 Rev 3 Ly PM0237 Design an application using BlueNRG BlueNRG MS ACI APIs d pr attribute data list 0x0C bytes as follows Table 48 First evt att read by group resp event data Service Handle End Group Handle Service UUID Note Attribute profile service GATT_Init adds it 0x0001 0x0004 0x1801 Standard 16 bits service UUID GAP profile service 0x0005 0x000F BlueNRG 0x1800 GAP Init adds it 0x000B BlueNRG MS Standard 16 bits service UUID Second evt att read by group resp event data pr conn handle 0x0801 connection handle pr event data length 0x15 length of the event data pr attribute data length 0x14 length of each discovered service data service handle end group handle pr attribute data list content service uuid 0x14 bytes as follows Table 49 Second evt att read by group resp event data Service Handle End Group Service UUID Note Handle 0x0010 0x0016 Acceleration BlueNRG BlueNRG 0x02366E80CF3A11E19AB40002A5D5 service 0x000C 0x0012 C51B 128 bits service BlueNRG MS BlueNRG MS proprietary UUID Third evt att read by group resp event data pr conn handle 0x0801 connection handle pr event dat
28. hal write config data CONFIG DATA PUBADDR OFFSET CONFIG DATA PUBADDR LEN bdaddr if ret BLE STATUS SUCCESS PRINTF Failure n sy void GAP Peripheral Make Discoverable void d DoclD027104 Rev 3 PM0237 Design an application using BlueNRG BlueNRG MS ACI APIs d tBleStatus ret const char local name AD TYPE COMPLETE LOCAL NAME B l u e N R G As scan response data a proprietary 128bits Service UUID is used This 128bits data cannot be inserted within the advertising packet ADV IND due its length constraints 31 bytes s AD Type description 0x11 length 0x06 128 bits Service UUID type 0x8a 0x97 0xf7 0xc0 0x85 0x06 0x11 0xe3 0xba 0xa7 0x08 0x00 0x20 0x0c 0x9a 0x66 128 bits Service UUID uint8 t ServiceUUID Scan 18 0x11 0x06 0x8a 0x97 0xf7 0xc0 0x85 0x06 0x11 0xe3 0xba 0xa7 0x08 0x00 0x2 0 0x0c 0x9a 0x66 Enable scan response to be sent when GAP peripheral receives Scan requests from GAP Central performing general discovery procedure active scan hci le set scan resp data 18 ServiceUUID Scan Put the GAP peripheral in general discoverable mode Advertising Event Type ADV IND undirected scannable and connectable Adv Interval Min 0 Adv Interval Max 0 Address Type PUBLIC ADDR public address 0x00 Adv Filter Policy NO WHITE LIST USE no whit list is used Local Name Length 8 Local Name BlueNRG S
29. length 0x15 length of each discovered characteristic data characteristic handle properties characteristic value handle characteristic UUID pr handle value pair 0x15 bytes as follows Table 53 Second evt att read by type resp event data Characteristic handle 0x0014 BlueNRG 0x0010 BlueNRG MS Characteristic properties 0x12 notify and read Characteristic value handle 0x0015 BlueNRG 0x0011 BlueNRG MS Characteristic UUID 0x340A1B80CF4B11E1AC360002A5D 5C51B Note Acceleration characteristic 128bits characteristic proprietary UUID In the context of the Sensor Profile Demo when the discovery all characteristics of a service procedure completes the EVT BLUE GATT PROCEDURE COMPLETE is generated on GAP Central application with following evt gatt procedure complete data pr datall pr conn handle pr data length 0x00 0x0801 0x01 connection handle length of the event data event data Similar steps can be followed in order to discover all the characteristics of the environment service refer to Table 45 BlueNRG sensor profile demo services amp characteristics handles and Table 46 BlueNRG MS sensor profile demo services amp characteristics handles 3 7 Characteristic notification indications write read This section describes the main functions for getting access to BLE device charac
30. resolve an authorization error d 18 97 DoclD027104 Rev 3 PM0237 Bluetooth low energy technology Attribute example Table 8 Attribute example Attribute handle Attribute type Attribute value Attribute permissions Read Only No 0x0008 Temperature UUID Temperature Value authorization No authentication e Temperature UUID is defined by Temperature characteristic specification and it is a signed 16 bit integer A collection of attributes is called a database that is always contained in an attribute server Attribute protocol defines a set of methods protocol for discovering reading and writing attributes on a peer device It implements the peer to peer Client Server protocol between an attribute server and an attribute client as follows e Server role A Contains all attributes attribute database Receives requests executes responds commands Canindicate notify an attribute value when data change e Client role Talk with server Sends requests wait for response it can access read update write the data Can confirm indications Attributes exposed by a Server can be discovered read and written by the Client and they can be indicated and notified by the Server as described in Table 9 Table 9 Attributes protocol messages Protocol Data Unit PDU message Sent by Description Request Client Client requests something
31. security request or aci gap send pairing request and the value ret BLE STATUS SUCCESS is returned on termination of the procedure a EVT BLUE GAP PAIRING CMPLT event is returned on the HCI Event CB event callback to indicate the pairing status e 0x00 Pairing success 0x01 Pairing Timeout e 0x02 Pairing Failed The pairing status is given from the status field of the evt gap pairing cmplt data associated to the EVT BLUE GAP PAIRING CMPLT event 2 When 2 devices get paired the link is automatically encrypted during the first connection If bonding is also enabled keys are stored for a future time when the 2 devices get connected again the link can be simply encrypted without no need to perform again the pairing procedure Host applications can simply use the same APIs which will not perform the paring process but will just encrypt the link e aci gap slave security request on the GAP Peripheral slave device or e aci gap send pairing request on the GAP Central master device 3 Ifa slave has already bonded with a master it can send a slave security request to the master to encrypt the link When receiving the slave security request the master may encrypt the link initiate the pairing procedure or reject the request Typically the master only encrypts the link without performing the pairing procedure Instead if the master starts the pairing procedure it means that for some reasons the master lost its
32. the following steps at initialization time on main function 1 Init SPI interface by calling the following API SdkEvalSpilnit SPI MODE EXTI 2 Reset the BlueNRG module by calling the following API BlueNRG RST The user is also requested to place HCI Isr within the SPI IRQ IRQHandler handler on file stm32l1xx it c on Standard library framework and within the HAL GPIO EXTI Callback on file bluenrg interface c on Cube library framework This allows BlueNRG BlueNRG MS device to use the SPI IRQ pin to notify the external microcontroller SPI master when it has data to be read d DoclD027104 Rev 3 37 97 BlueNRG BlueNRG MS stacks architecture and ACI PM0237 2 3 Other platforms resources files The SW framework provides other files handling some platform dependent resources as O communication channel USB or UART buttons LEDs EEPROM Table 30 SW framework platforms drivers File SDK_EVAL_lo ch SDK_EVAL_Buttons ch SDK EVAL Leds ch SDK EVAL Eeprom ch Description Main APIs handling VO communicatio n USB virtual COM or UART APIs handling platform buttons APIs handling platform LEDs APIs handling EEPROM Location platform STM32L1XX Libraries SDK_Eval_STM 32L on STM32L1 standard library framework Drivers BSP STM32L1xx_STEVAL_IDBOOxV1 on STM32L1 Cube library framework These APIs are platform STM32L1XxX Libraries SDK_Eval_STM 32L on STM32
33. vendor event data evt blue aci blue evt void event pckt data switch blue evt ecode case EVT BLUE ATT READ BY GROUP RESP evt att read by group resp pr void blue evt data evt att read by group resp parameters pr conn handle connection handle pr event data length total length of the event data pr attribute data length length of each specific data within the attribute data list pr attribute data list l event data i i Add user code for decoding the pr attribute data list and getting the services handle end group handle and service uuid EVT BLUE ATT READ BY GROUP RESP break case EVT BLUE GATT PROCEDURE COMPLETE evt gatt procedure complete pr void blue evt data evt gatt procedure complete parameters pr conn handle connection handle pr attribute data length length of the event data pr data l event data If needed add user code for using the event data EVT BLUE GATT PROCEDURE COMPLETE break switch blue evt ecode EVT VENDOR break switch evt gt subevent end HCI Event CB In the context of the Sensor Profile Demo the GAP Central application should get three EVT BLUE ATT READ BY GROUP RESP events with following evt att read by group resp data First evt att read by group resp event data pr conn handle 0x0801 connection handle pr event
34. 010 charac handle value 0x0011 endif GAP peripheral notifies free fall characteristic to GAP central ret aci gatt update char value service handle value acceleration service handle charac handle value free fall characteristic handle 0 characteristic value offset 0x01 characteristic value length amp val characteristic value ret accServHandle freeFallCharHandle 0 1 amp val if ret BLE STATUS SUCCESS PRINTF Failure n tBleStatus ret 80 97 DoclD027104 Rev 3 d PM0237 Design an application using BlueNRG BlueNRG MS ACI APIs d uint8 t buff 6 ifdef BLUENRG MS charac handle value 0x0010 else charac handle value 0x0014 endif Set the mems acceleration values on three axis x y z on buff array GAP peripheral notifies acceleration characteristic to GAP central ret aci gatt update char value service handle value acceleration service handle charac handle value acceleration characteristic handle 0 characteristic value offset 0x06 characteristic value length buff characteristic value i ret accServHandle freeFallCharHandle 0 1 amp val if ret BLE STATUS SUCCESS PRINTF Failure n On GAP Central HCI_Event_cB callback EvT VENDOR as main event the EVT BLUE GATT NOTIFICATION is raised on reception of the characteristic notification accelerat
35. 5 Figure 6 Figure 7 Figure 8 Figure 9 Figure 10 Figure 11 Figure 12 Figure 13 4 97 Bluetooth low energy technology enabled coin cell battery devices 7 Bluetooth low energy stack architecture lille 9 Link Layer state machine EE EE Ee n 11 Ppacketstrieture ss o eid pese Re HARE e ERA n RE EDU SL RR Ee ee Pd 12 Advertising packet with AD type flags EE EE EE EG GE SE GE EE m 15 Example of characteristic definition EE EE EE EE EE Ee ee eee 23 Client and server profiles EE EE EE EE EE EE EE Ee es 32 BlueNRG BlueNRG MS stacks architecture and interface to the external host 34 MAC address storage iii EE ER eet hs 48 BlueNRG MS simultaneous Master amp Slave scenario EE EE Ee Ee eee 83 Advertising timings ssc EE EE EE ade mmm 86 Example of allocation of three connection slots EE 000 ccc eee SS SS SS se ee 88 Example of timing allocation for three successive connections 90 d DoclD027 104 Rev 3 PM0237 List of tables List of tables Table 1 Table 2 Table 3 Table 4 Table 5 Table 6 Table 7 Table 8 Table 9 Table 10 Table 11 Table 12 Table 13 Table 14 Table 15 Table 16 Table 17 Table 18 Table 19 Table 20 Table 21 Table 24 Table 22 Table 23 Table 26 Table 25 Table 27 Table 28 Table 29 Table 30 Table 31 Table 32 Table 33 Table 34 Table 35 Table 36 Table
36. ATTRIBUTE MODIFIED EVT VENDOR attribute on the server if event is server enabled Generated by the GATT client GATT EVT BLUE GATT NOTIFICATION when a server notifies any EVT VENDOR x E E client attribute on the client Generated by the GATT client GATT EVT BLUE GATT INDICATION when a server indicates any EVT VENDOR client attribute on the client Generated by the Security manager to the application when a passkey is required for pairing GAP EVT BLUE GAP PASS KEY REQUEST When this event is received the EVT VENDOR central application has to respond with peripheral the aci gap pass key response API Generated when the pairing process has completed GAP EVT BLUE GAP PAIRING CMPLT successfully or a pairing EVT VENDOR central procedure timeout has occurred peripheral 50 97 DoclD027104 Rev 3 d PM0237 Design an application using BlueNRG BlueNRG MS ACI APIs Table 37 ACI main events sub events continued Event sub event EVT BLUE GAP BOND LOST Description Event generated when a pairing request is issued in response to a slave security request from a master which has previously bonded with the slave When this event is received the upper layer has to issue the command aci gap allow rebond to allow the slave to continue the pairing process with the master Main event EVT VENDOR Where GAP peripheral EVT BLUE ATT READ BY GROUP RESP
37. COMPLETE event on the HCI Event CB callback EVT_VENDOR as main event void HCI Event CB void pckt DoclD027104 Rev 3 75 97 Design an application using BlueNRG BlueNRG MS ACI APIs PM0237 hci uart pckt hci pckt pckt hci event pckt event pckt hci event pckt hci pckt data if hci pckt type HCI EVENT PKT return switch event_pckt gt evt case EVT_VENDOR Get the vendor event data evt blue aci blue evt void event pckt data switch blue_evt gt ecode case EVT BLUE ATT READ BY TYPE RESP evt att read by type resp pr void blue evt data evt att read by type resp parameters pr conn handle connection handle pr event data length total length of the event data pr gt handle value pair length length of each specific data within the handle value pair pr gt handle value pair l event data Add user code for decoding the pr gt handle value pair and get the characteristic handle properties characteristic value handle characteristic UUID EVT BLUE ATT READ BY TYPE RESP break case EVT BLUE GATT PROCEDURE COMPLETE evt gatt procedure complete pr void blue evt data evt gatt procedure complete parameters pr conn handle connection handle pr data length length of the event data d 76 97 DoclD027104 Rev 3 PM0237 Design an application using BlueNRG BlueNRG MS ACI APIs pr gt data
38. E Ee RE A Rcx e UE Res te dx 64 Scan response data EE EE EE EE EE EE ee ee llle 64 BlueNRG sensor profile demo services amp characteristics handles 69 BlueNRG MS sensor profile demo services amp characteristics handles 69 ACI service discovery procedures APIS 0 0000 lees 71 First evt att read by group resp event data EE ee eese 73 DoclD027104 Rev 3 5 97 List of tables PM0237 Table 49 Table 50 Table 51 Table 52 Table 53 Table 54 Table 55 Table 56 Table 57 Table 58 6 97 Second evt att read by group resp event data 0000 00 ee ee 73 Third evt att read by group resp eventdata ii Ee EE ee eee 74 BlueNRG ACI characteristics discovery procedures APIS is leise 75 First evt att read by type resp event data is EE ee eee 77 Second evt att read by type resp event data SE EE Ee ee ee 78 Characteristics update read write APIS SS EE EE SS SS SS SS SS ee ee 78 Timings parameters of the slotting algorithm EE EE EE EE ee 87 References lo MO OO e hh hn 93 LISTOFACKONYMS PP 94 Document revision history lssseee eee 96 d DoclD027 104 Rev 3 PM0237 Bluetooth low energy technology d Bluetooth low energy technology Bluetooth low energy BLE wireless technology has been developed by the Bluetooth Special Interest Group SIG in order to achieve a very low power s
39. File Description Location Notes Middlewares S HCI library functions prototypes and TS TM Plu To be included on the een error code definition eNRGASImple user main application i BlueNRG_HCI PP includes It contains constants and functions for hci_const h HCI layer See Bluetooth Core v 4 0 Vol 2 Part E bluenrg_gatt_s Header file for GATT server definition E Joibe included En me erver h user main application smi Header file for BlueNRG security n To be included on the i manager user main application bluenrg_gap h Header file for BlueNRG GAP layer o Tone ineluged id the user main application TEE Header file that contains commands and To be included on the g_aci events for BlueNRG FW stack user main application bluenrg aci c Header file with ACI definitions for T It is included by onst h BlueNRG FW stack bluenrg aci h bluenrg hal a Header file with HCI commands for T It is included by ci h BlueNRG FW stack bluenrg aci h DoclD027 104 Rev 3 35 97 BlueNRG BlueNRG MS stacks architecture and ACI PM0237 2 2 36 97 Table 28 ACI Interface continued File Description Location Notes bluenrg_I2cap Header file with L2CAP commands for w It is included by aci h BlueNRG FW stack bluenrg aci h bluenrg gatt a Header file with GATT commands for It is included by ci h BlueNRG FW stack bluenrg aci h bluenrg gap a Header file with GAP commands for It is included by ci h BlueNRG FW stack
40. HCI Event CB void pckt hci uart pckt hci pckt pckt hci event pckt event pckt hci event pckt hci pckt data if hci_pckt gt type HCI EVENT PKT return switch event_pckt gt evt case EVT_VENDOR Get the vendor event data evt blue aci blue evt void event pckt data switch blue_evt gt ecode case EVT BLUE GAP DEVICE FOUND evt gap device found pr void blue evt data evt gap device found parameters pr evt type event type advertising packets types pr bdaddr type type of the peer address PUBLIC ADDR RANDOM ADDR pr gt bdaddr address of the peer device found during scanning pr length length of advertising or scan response data pr data RSSI length advertising or scan response data RSSI RSSI is last octect signed integer x Add user code for decoding the evt gap device found event data based on the specific pr evt type ADV IND SCAN RSP EVT BLUE GAP DEVICE FOUND break case EVT BLUE GAP PROCEDURE COMPLETE When the general discovery procedure is terminated d 62 97 DoclD027104 Rev 3 PM0237 Design an application using BlueNRG BlueNRG MS ACI APIs d EVT BLUE GAP PROCEDURE COMPLETE event is returned with the procedure code set to GAP GENERAL DISCOVERY PROC 0x02 evt gap procedure complete pr void blue evt data evt gap procedure complete parameters pr procedure code te
41. L1 standard library framework Drivers BSP STM32L1xx_STEVAL_IDBOOxV1 on STM32L1 Cube library framework These APIs are platform STM32L1XxX Libraries SDK_Eval_STM 32L on STM32L1 standard library framework Drivers BSP STM32L1xx_STEVAL_IDBOOxV1 on STM32L1 Cube library framework On BlueNRG platform STM32L1XxX Libraries SDK_Eval_STM 32L on STM32L1 standard library framework Drivers BSP STM32L1xx_STEVAL_IDBOOxV1 on STM32L1 Cube library framework Notes These APIs are mapped to the specific microcontroller drivers handling USB virtual COM or UART mapped to the specific microcontroller drivers handling GPIOs mapped to the specific microcontroller drivers handling GPIOs BlueNRG MS kits an external EEPROM is provided for storing platform manufacturing tests results These files should be ported adapted to address another external microcontroller 2 3 1 Platforms configuration In order to easily support the BlueNRG BlueNRG MS kits platforms the BlueNRG SW framework is designed for recognizing such platforms at runtime User is only requested to call the SdkEvalldentification API at initialization time on main function BlueNRG BlueNRG MS kits platforms can be also supported at compile time by adding respectively only one of the following define on EWARM workspace preprocessor options USER DEFINED PLATFORM STEVAL IDBOO2V1 itis valid for both BlueNRG BlueNRG MS development platf
42. Peripheral in discoverable mode void GAP Central Make Connection void tBleStatus ret tBDAddr GAP Peripheral address 0xaa 0x00 0x00 OxE1 0x80 0x02 Start the direct connection establishment procedure to the GAP peripheral device in general discoverable mode using the following connection parameters Scan Interval 0x4000 Scan Window 0x4000 Peer Address Type PUBLIC ADDR GAP peripheral address type public address Peer Address 0xaa 0x00 0x00 OxE1 0x80 0x02 Own Address Type PUBLIC ADDR device address type Conn Interval Min 40 Minimum value for the connection event interval Conn Interval Max 40 Maximum value for the connection event interval DoclD027104 Rev 3 59 97 Design an application using BlueNRG BlueNRG MS ACI APIs PM0237 Note 3 4 2 Note 60 97 Conn Latency 0 Slave latency for the connection in a number of connection events Supervision Timeout 60 Supervision timeout for the LE Link Conn Len Min 2000 Minimum length of connection needed for the LE connection Conn Len Max 2000 Maximum length of connection needed for the LE connection ret aci gap create connection 0x4000 0x4000 PUBLIC ADDR GAP Peripheral address PUBLIC ADDR 40 40 0 60 2000 2000 if ret BLE STATUS SUCCESS PRINTF Failure n end GAP Peripheral Make Discoverable 1 If ret BLE STATUS SUCCESS is returned on termination of
43. Puts the device into undirected connectable mode Table 39 ACI discovery procedures APIs ACI API aci_gap_start_limited_discovery_proc aci_gap_start_general_discovery_proc Description Starts the limited discovery procedure The controller is commanded to start active scanning When this procedure is started only the devices in limited discoverable mode are returned to the upper layers Starts the general discovery procedure The controller is commanded to start active scanning Table 40 ACI connection procedures APIs ACI API aci_gap_start_auto_conn_establishment aci_gap_create_connection aci_gap_start_general_conn_establishment Description Starts the auto connection establishment procedure The devices specified are added to the white list of the controller and a LE Create Connection call is made to the controller by GAP with the initiator filter policy set to use whitelist to determine which advertiser to connect to Starts the direct connection establishment procedure A LE_Create_Connection call will be made to the controller by GAP with the initiator filter policy set to ignore whitelist and process connectable advertising packets only for the specified device Starts a general connection establishment procedure The host enables scanning in the controller with the scanner filter policy set to accept all advertising packets and fr
44. TION void HCI Event CB void pckt hci uart pckt hci pckt pckt hci event pckt event pckt hci event pckt hci pckt data if hci_pckt gt type HCI EVENT PKT return d DoclD027 104 Rev 3 51 97 Design an application using BlueNRG BlueNRG MS ACI APIs PM0237 switch event _pckt gt evt case EVT DISCONN COMPLETE BlueNRG disconnection event Add user code for handling BLE disconnect event based on application scenarios sy break case EVT LE META EVENT Get the meta event data evt le meta event evt void event pckt data Analyze the specific sub event switch evt gt subevent case EVT LE CONN COMPLETE BlueNRG connection event connection complete event get the related data evt le connection complete cc void evt data Connection parameters cc gt status connection status 0x00 Connection successfully completed cc handle connection handle to be used for the communication during the connection cc role BLE device role 0x01 master 0x02 slave cc gt peer bdaddr type connected device address type 0x00 public 0x01 random cc gt peer bdaddr connected device address CC interval connection interval cc latency connection latency cc supervision timeout connection supervision timeout cc master clock accuracy master clock accuracy Add user code for handling connection event based on applicati
45. _gap_set_non discover 0x03 non connectable able API undirected advertising 0x00 connectable ee undirected advertising Sets the device in limited default discoverable mode The device I is discoverable for a maximum 0x02 scannable undirected period of TGAP advertising lim adv timeout 180 seconds The advertising can be disabled at any time by calling aci gap set non discover able API aci gap set limited discoverable 0x03 non connectable undirected advertising Sets the device in non discoverable mode This aci gap set non discoverable NA command disables the LL advertising and sets the device in standby state Sets the device in direct connectable mode The device is directed connectable mode only for 1 28 seconds If no aci gap set direct connectable NA connection is established within this duration the device enters non discoverable mode and advertising has to be enabled again explicitly d DoclD027104 Rev 3 PM0237 Design an application using BlueNRG BlueNRG MS ACI APIs d Table 38 ACI GAP modes APIs continued API advertising aci_gap_set_non_connectable Supported advertising event types 0x02 scannable undirected Description Puts the device into non 0x03 non connectable undirected advertising connectable mode aci_gap_set_undirect_connectable NA
46. a length 0x15 length of the event data pr gt attribute data length 0x14 length of each discovered service data service pr attribute data list handle end group handle 0x14 bytes as follows DoclD027104 Rev 3 service uuid 73 97 Design an application using BlueNRG BlueNRG MS ACI APIs PM0237 Table 50 Third evt att read by group resp event data Service handle End group Service UUID Note handle 0x0017 0x001A Environmental BlueNRG BlueNRG 0x42821A40E47711E282D00002A5D5 service 0x0013 0x0016 C51B 128bits service BlueNRG MS BlueNRG MS proprietary UUID In the context of the Sensor Profile Demo when the discovery all primary service procedure completes the EVT BLUE GATT PROCEDURE COMPLETE is generated on GAP Central application with following evt gatt procedure complete data pr conn handle 0x0801 connection handle pr data length 0x01 length of the event data pr gt data 0x00 event data d 74 97 DoclD027 104 Rev 3 PM0237 Design an application using BlueNRG BlueNRG MS ACI APIs 3 6 2 d Characteristics discovery procedures and related GATT events Following is a list of the characteristic discovery APIs with associated description Table 51 BlueNRG ACI characteristics discovery procedures APIs Discovery service API Description This API starts the GATT procedure to discover aci_gatt_disc_all_charac_of_serv
47. allows to include the file USER Platform Configuration auto h which contains the BlueNRG BlueNRG MS kits platforms define values used during the runtime auto configuration procedure performed from SdkEvalldentification function This header file must not be modified by user Similar approach can be followed on STM32L1xx Cube context by referring as example to the files USER Platform Configuration bluenrg h on Drivers BSP STM32L 1xx_BlueNRG folder and USER Platform Configuration h on DriverslBSPISTMA32L1xx Nucleo folder these files are used for addressing the STM32L NUCLEO L152RE X NUCLEO IDB04A1 BlueNRG platform DoclD027104 Rev 3 39 97 BlueNRG BlueNRG MS stacks architecture and ACI PM0237 2 4 Note 40 97 How to port the ACI SPI interface framework to a selected microcontroller BlueNRG BlueNRG MS devices are network coprocessors providing the Bluetooth low energy features In order to get access to its functionality an external microcontroller can be used by implementing the ACI SPI interface framework previously described BlueNRG BlueNRG MS development kits software package provides a reference framework targeting this ACI SPI interface This framework can be ported to another external microcontroller by following these steps 1 Define a specific USER Platform Configuration h with specific user platform SPI configuration refer to Section 2 3 1 Platforms configuration 2 On the selected user application prep
48. amp Slave is configured as Central amp Peripheral by setting role as GAP PERIPHERAL ROLE GAP CENTRAL ROLE on GAP Init API Further it is configured with stack mode 3 for being able to connect to more than one Peripheral device Let s also assume that this device define a service with a characteristic 2 Two BlueNRG MS devices called Slave A Slave B are configured as Peripheral by setting role as GAP PERIPHERAL ROLE on GAP Init API Both Slave A and Slave B define the same service and characteristic as Master amp Slave device 3 One BlueNRG MS device called Master is configured as Central by setting role as GAP CENTRAL ROLE on GAP Init API 4 Both Slave A and Slave B devices enter in discovery mode as follows ret aci gap set discoverable Advertising Type 0x00 Advertising Interval Min 0x20 Advertising Interval Max 0x100 Local Name Length 0x05 Local Name 0x08 0x74 0x65 0x73 0x74 Slave Conn Interval Min 0x0006 Slave Conn Interval Max 0x0008 5 Master amp Slave device performs a discovery procedure in order to discover the peripheral devices Slave A and Slave B ret aci gap start gen disc proc LE Scan Interval 0x10 LE Scan Window 0x10 DoclD027104 Rev 3 83 97 Design an application using BlueNRG BlueNRG MS ACI APIs PM0237 84 97 The two devices are discovered thorugh the EVT LE ADVERTISING REPORT events 6 Once the two devices are discovered Master amp Slave device starts two
49. application A characteristic can be added to this service using this command aci gatt add char ServHandle Char UUID Type Char UUID 16 Char Value Length Char Properties Security Permissions GATT Evt Mask Enc Key Size Is Variable amp CharHandle This command returns the pointer to the Characteristic Handle Char Handle which is used to identify the characteristic within the user application For a detailed description of the aci gatt add serv and aci gatt add char functions parameters refer to the user manuals UM1755 and UM1865 The following pseudocode example illustrates the steps to be followed for adding a service and two associated characteristic on a proprietary non standard profile tBleStatus Add Server Services Characteristics void tBleStatus ret The following 128bits UUIDs have been generated from the random UUID generator D973F2E0 B19E 11E2 9E96 0800200C9A66 Service 128bits UUID D973F2E1 B19E 11E2 9E96 0800200C9A66 Characteristic 1 128bits UUID D973F2E2 B19E 11E2 9E96 0800200C9A66 Characteristic 2 128bits UUID Service 128bits UUID const uint8 t service uuid 16 0x66 0x9a 0x0c 0x20 0x00 0x08 0x96 0x9e 0xe2 0x11 0x9e 0xb1 0xe0 0xf2 0x7 3 0xd9 Characteristic 1 128bits UUID const uint8 t charUuid 1 16 0x66 0x9a 0x0c 0x20 0x00 0x08 0x96 0x9e 0xe2 0x11 0x9e 0xb1 0xe1 0xf2 0x7 3 0xd9 Characteristic 2 128bits UUID DoclD027104 Rev 3 Ly
50. at the time base has been configured and started as described above then the slot allocation algorithm will try within certain limits to dynamically reconfigure the time base to allocate further host requests In particular the following three cases are considered 1 The current anchor period falls within the Conn Interval Min and Conn Interval Max range specified for the new connection In this case no change is applied to the time base and the connection interval for the new connection is set equal to the current anchor period 2 The current anchor period in smaller than the Conn Interval Min required for the new connection In this case the algorithm searches for an integer number m such that Conn Interval Min lt Anchor Period ms Conn Interval Max If such value is found then the current anchor period is maintained and the connection interval for the new connection is set equal to Anchor Period e m with slot latency equal to m 3 The current anchor period in larger than the Conn nterval Max required for the new connection In this case the algorithm searches for an integer number amp such that Anchor Period k Conn Interval Min lt lt Conn Interval Max If such value is found then the current anchor period is reduced to Anchor Period k The connection interval for the new connection is set equal to Anchor Period k and the slot latency for the existing connections is multiplied by a factor k Note that in t
51. ation using BlueNRG BlueNRG MS ACI APIs 3 Note d Design an application using BlueNRG BlueNRG MS ACI APIs This section provides information and code examples about how to design and implement a Bluetooth low energy application on the selected microcontroller User implementing a BLE host application on the selected MCU has to go through some basic and common steps 1 Initialization phase and main application Loop BlueNRG BlueNRG MS events and events Callback setup Services and characteristic configuration on GATT server Create a connection discoverable connectable modes amp procedures Security pairing amp bonding Service and characteristic discovery Characteristic notification indications write read Basic typical error conditions description o 40900 2 WN The STM32L1xx microcontroller is the reference external microcontroller used for the programming guidelines described on the following sections since the available BlueNRG BlueNRG MS kits platforms are based on such microcontroller On the following sections some user application Defines are used to simply identify the devices Bluetooth low energy role central peripheral client and server Further on each provided pseudo codes any reference to BlueNRG device is also valid for the BlueNRG MS device Any specific difference is highlighted whenever it is needed by using ifdef BLUENRG MS Table 31 User application defines for BLE devices role
52. ave role and it defines timings of transmissions e Advertiser device is in Slave Role it communicates with a single device in Master Role DoclD027104 Rev 3 11 97 Bluetooth low energy technology PM0237 1 3 1 12 97 BLE packets A packet is a labeled data that is transmitted by one device and received by one or more other devices The BLE data packet structure is described below Figure 4 Packet structure Bits Access Address v 3 3 S o GAMSEC201411251133 e Preamble RF synchronization sequence e Access address 32 bits advertising or data access addresses it is used to identify the communication packets on physical layer channel e Header its content depends on the packet type advertising or data packet a Advertiser packet header Table 2 Advertising data header file content Advertising packet type Reserved Tx address type Rx address type d DoclD027104 Rev 3 PM0237 Bluetooth low energy technology d b Advertising packet type Table 3 Advertising packet types Packet type Description Connectable undirected ADNVCTND advertising Connectable directed ADV DIRECT IND a EE advertising Non connectable undirected ADV_NONCONN_IND Ln advertising Notes Used by an advertiser when it wants another device to connect to it Device can be scanned by a scanning device or go into a connection as a slave device on connection request rece
53. bed based on the most common BLE functionalities User developer can adapt modify replace them 3 When performing the GATT_Init amp GAP Init APIs BlueNRG and BlueNRG MS stacks always add two standard services Attribute Profile Service 0x1801 with Service Changed Characteristic and GAP Service 0x1800 with Device Name and Appearance characteristics 4 The last attribute handle reserved for the standard GAP service is OxOOOF on BlueNRG stack and 0x000B on BlueNRG MS stack Table 32 BlueNRG GATT GAP default services Default services Start handle End handle Service UUID Attribute profile service 0x0001 0x0004 0x1801 Generic access profile GAP 0x0005 Ox000F 0x1800 Service Table 33 BlueNRG GATT GAP default characteristics Default Attribute Char Char Char value length Services Characteristic handle Char property value UUID bytes handle Attribute profile service Ee 0x0002 Indicate 0x0003 Ox2A05 4 changed Generic access profile GAP service Read Write without response Write Device name 0x0006 Authenticated Signed 0x0007 0x2A00 7 Writes Read Write without Response Write Appearance 0x0008 Authenticated Signed 0x0009 0x2A01 2 Writes 44 97 d DoclD027104 Rev 3 PM0237 Design an application using BlueNRG BlueNRG MS ACI APIs Table 33 BlueNRG GATT GAP default characteristics continued Default Characteristic Attribute Char propert id Char Char value length Se
54. c configuration it is mandatory if the characteristic can be notified or indicated Client application must write this characteristic descriptor for enabling characteristic notification or indication provided that the characteristic property allows notification or indication 4 Server characteristic configuration optional descriptor 5 Characteristic presentation format it allows to define the characteristic value presentation format through some fields as format exponent unit namespace description in order to correctly display the related value example temperature measurement value in 9C format 6 Characteristic aggregation format It allows to aggregate several characteristic presentation formats For a detailed description of the characteristic descriptors refer to the Bluetooth specification v4 0 Service attribute type A service is a collection of characteristics which operate together to provide a global service to an applicative profile For example the Health Thermometer service includes characteristics for a temperature measurement value and a time interval between measurements A service or primary service can refer other services that are called secondary services A service is defined as follows Table 14 Service declaration Attribute handle Attribute type Attribute value Attribute permissions 0x2800 UUID for Read only Primary Service or Oxuuuu 16 bits or 128 OR ES 0x2801 UUID for bits for Se
55. ce and it wants to find a specific service without the need to get any other services aci gatt disc all prim services aci gatt disc prim services by service uuid This API starts the procedure to find all included services It is used when a GATT client wants to discover secondary services once the primary services have been discovered aci gatt find included services The following pseudocode example illustrates the aci gatt disc all prim services API GAP Central starts a discovery all services procedure conn_handle is the connection handle returned on HCI Event CB event callback EVT LE CONN COMPLETE event if aci gatt disc all prim services conn handle BLE STATUS SUCCESS if ret BLE STATUS SUCCESS PRINTF Failure n The responses of the procedure are given through the EVT BLUE ATT READ BY GROUP RESP event raised on HCI Event CB callback EVT VENDOR as main event The end of the procedure is indicated by EVT BLUE GATT PROCEDURE COMPLETE event on the HCI Event CB callback EVT VENDOR as main event void HCI Event CB void pckt hei uart pckt hci pckt pckt hci event pckt event pckt hci event pckt hci pckt data if hci pckt type HCI EVENT PKT return switch event pckt evt case EVT VENDOR d DoclD027104 Rev 3 71 97 Design an application using BlueNRG BlueNRG MS ACI APIs PM0237 72 97 Get the
56. ces and characteristics discovery notification and related events oum 3 OOND The following pseudocode example illustrates the required initialization steps int main void int ret Device Initialization Init Device Identify BlueNRG BlueNRG MS platform SdkEvalldentification Configure I O communication channel It requires the void IO Receive Data uint8 t rx data uinti16 t data size function where user received data should be processed SdkEval IO Config processInputData Initialize list heads of ready and free hci data packet queues HCI Init Init SPI interface SdkEvalSpilnit SPI MODE EXTI Reset the BlueNRG network coprocessor BlueNRG RST Configure BlueNRG address as public its public address is used uint8 t bdaddr l0xaa 0x00 0x00 OxE1 0x80 0x02 ret aci hal write config data CONFIG DATA PUBADDR OFFSET CONFIG DATA PUBADDR LEN bdaddr if ret PRINTF Setting BD ADDR failed Wn d DoclD027104 Rev 3 PM0237 Design an application using BlueNRG BlueNRG MS ACI APIs Init BlueNRG GATT layer ret aci gatt init if ret PRINTF GATT Init failed Nn Init BlueNRG GAP layer as peripheral or central uintl16 t service handle dev name char handle appearance char handle if GAP PERIPHERAL uint8 t role GAP PERIPHERAL ROLE else uint8 t role GAP CENTRAL ROLE endif if BLUENRG MS ret aci gap init ro
57. connection bonding procedures Different types of discoverable and connectable modes can be uses at the same time The following GAP modes are defined Table 20 GAP broadcaster mode Mode Description Notes GAP role Device only broadcasts data using the link layer Broadcasts data can be Broadcast mode advertising channels and detected by a device using Broadcaster packets it does not set any the observation procedure bit on Flags AD type Table 21 GAP discoverable modes Mode Description Notes GAP role f It cannot set the limited and lt cannot us discoveted by a Non discoverable f device performing a general general discoverable bits on dnm Peripheral mode or limited discovery Flags AD type procedure It is allowed for about 30 sec T it sets the limited It is used by devices with Limited which user has recently i discoverable bit on Flags AD Peripheral discoverable mode ipe interacted For example ypa when a user presses a button on the device It is used when a device It sets the general General wants to be discoverable discoverable bit on Flags AD ER Peripheral discoverable mode There is no limit on the type TE a discoverability time DoclD027 104 Rev 3 27 197 Bluetooth low energy technology PM0237 28 97 Table 22 GAP connectable modes Mode Description Notes GAP role Ingen anl
58. cy Channel type 37 2402 MHz Advertising channel 0 2404 MHz Data channel 1 2406 MHz Data channel Data channel 10 2424 MHz Data channel 38 2426 MHz Advertising channel 11 2428 MHz Data channel 12 2430 MHz Data channel Data channel 36 2478 MHz Data channel 39 2480 MHz Advertising channel BLE is an Adaptive Frequency Hopping AFH technology that can use only a subset of all the available frequencies in order to avoid the frequencies used by other no adaptive technologies This allows to move from a bad channel to a known good channel by using a specific frequency hopping algorithm which determines the next good channel to be used d 10 97 DoclD027104 Rev 3 PM0237 Bluetooth low energy technology 1 3 d Link Layer LL The link layer LL defines how two devices can use a radio for transmitting information between each other The link layer defines a state machine with five states Figure 3 Link Layer state machine Advertising GAMSEC201411251131 e Standby the device does not transmit or receive packets e Advertising the device broadcasts advertisements in advertising channels it is called an advertiser device e Scanning device looks for advertisers devices it is called a scanner device e Initiating the device initiates connection to advertiser device Connection the initiator device is in Master Role it communicates with the device in the Sl
59. dress e Advertising channel map which of the three advertising channels should be used e Advertising filter policy Process scan connection requests from devices in the white list Process all scan connection requests default advertiser filter policy Process connection requests from all devices but only scan requests in the white list Process scan requests from all devices but only connection requests in the white list DoclD027104 Rev 3 15 97 Bluetooth low energy technology PM0237 1 3 3 16 97 A white list is a list of stored device addresses used by the device controller for filtering devices The white list content cannot be modified while it is being used If the device is in advertising state and is using a white list to filter the devices scan requests or connection requests it has to disable advertising mode for changing its white list Scanning state There are two types of scanning e Passive scanning it allows to receive advertisement data from an advertiser device e Active scanning when an advertisement packet is received device can send back a Scan Request packet in order to get a Scan Response from the advertiser This allows the scanner device to get additional information from the advertiser device The following scan parameters can be set e Scanning type passive or active e Scaninterval how often the controller should scan e Scan window for each scanning interval it defines how
60. dures ss EE EE EE EE eee 25 1 9 Generic access profile GAP EE RR RE ER Re ee ee ek 26 1 10 BLE profiles and applications EE EE Ee ees 31 1 10 1 Proximity profile example EE EE EE EE EE EE ee ee ee eee 32 2 BlueNRG BlueNRG MS stacks architecture and ACI 34 2 1 ACI Interface iu sss ok EE xe RC X GRACE A em X RR aed KCN CR aye LR 35 2 2 ACI Interface resources EE EE EE EE EE EE eee 36 2 3 Other platforms resources files SS SS EE SS eee 38 2 3 1 Platforms configuration ie EE Re tee 38 2 4 How to port the ACI SPI interface framework to a selected microcontroller 40 3 Design an application using BlueNRG BlueNRG MS ACI APIs 41 3 1 Initialization phase and main application loop 42 3 1 1 BLEaddresses iis Eg GN rroan pel ERR RE ERR 47 3 1 2 Set tx power level 0 EE EE EE EE EE teens 49 2 97 DoclD027104 Rev 3 Ly PM0237 Contents 3 2 BlueNRG BlueNRG MS events and events Callback 50 3 3 Services and characteristic configuration lille 54 3 4 Create a connection discoverable and connectable APIs 56 3 4 1 Set discoverable mode amp use direct connection establishment procedure 58 3 4 2 Set discoverable mode amp use general discovery procedure active scan 60 3 5 Security pairing and bonding EE EE EE Ee ee 65 3 6 Service and characteristic discovery 0 cece eee ee
61. e EE EE EE ee elle 27 GAP discoverable modes EE EE EE cece eee eee teens 27 GAP observer procedure 00 EE cee cette eee 28 GAP connectable modes 00 cee eet ee ee ee ee ee ee 28 GAP bondable modes 0 EE EE EE SE Ge teens 28 GAP connection procedures EE se ee GE GE eee 29 GAP discovery procedures EE Se Ee rr 29 GAP bonding procedures ie rerai radir ene a 30 AGI Interface o cr soap ED ere atus RE RE ee Ege Male ore dag le ite rd 35 ACI Interface resources files EE EE EE ES ee ess 37 SW framework platforms drivers Ee se 000 ee ee ES ee ee eee 38 User application defines for BLE devices role 0 000 SS SS SS ees 41 BlueNRG GATT GAP default services SS ES SE SS SE eee 44 BlueNRG GATT GAP default characteristics 0 0 00 ee 44 BlueNRG MS GATT GAP default services llle 45 BlueNRG MS GATT GAP default characteristics 2c cee eee eee 45 GAP Init role parameter values 2 0 nananana aaa 46 ACI main events sub event SS SEE SS ee nee eee ene 50 ACI GAP modes APIS gauna a aa sea i a e eee ete eee eee 56 ACI discovery procedures APIS l l nn 57 ACI connection procedures APIS EE GE ee eee EE ee ee ee ee ess 57 ADV IND event ios me Raad Gaede ede aee pee ala ER br Ra eg Rg eap ES 64 ADV IND advertising data ii EE EE Ee EE EG ee Ee n 64 SCAN RSP event cece tbe o eee m IRR E
62. e Accelerati MEN 0x0010 0x0011 0x0012 NA characteristic EE NA 0x0013 NA NA NA service Tempe kie 0x0014 0xx0015 NA 0x0016 Characteristic Note The different attribute value handles are due to the last attribute handle reserved for the standard GAP service 0x000F on BlueNRG stack and 0x000B on BlueNRG MS stack For detailed information about the sensor profile demo refer to the user manual UM1686 and the sensor demo source code available within the development kit software package see References On the following example the BlueNRG GAP peripheral sensor profile demo environmental service is defining only the temperature characteristic no expansion board with pressure and humidity sensors is used 70 97 DoclD027 104 Rev 3 3 PM0237 Design an application using BlueNRG BlueNRG MS ACI APIs 3 6 1 Service discovery procedures and related GATT events Following is a list of the service discovery APIs with related description Table 47 ACI service discovery procedures APIs Discovery Service API Description This API starts the GATT client procedure to discover all primary services on the GATT server It is used when a GATT client connects to a device and it wants to find all the primary services provided on the device to determine what it can do This API starts the GATT client procedure to discover a primary service on the GATT server by using its UUID It is used when a GATT client connects to a devi
63. e connection interval again later When a connection is established a master has to transmit a packet to the slave on every connection event for allowing slave to send packets to the master Optionally a slave device can skip a given number of connection events slave latency DoclD027104 Rev 3 17 97 Bluetooth low energy technology PM0237 A connection event is the time between the start of the last connection event and the beginning of the next connection event ABLE slave device can only be connected to one BLE master device but a BLE master device can be connected to several BLE slave devices On the Bluetooth SIG there is no limit on the number of slaves a master can connect to this is limited by the specific used BLE technology or stack 1 4 Host controller interface HCI The Host Controller Interface HCI layer provides a mean of communication between the host and controller either through software API or by a hardware interface such as SPI UART or USB It comes from standard Bluetooth specification with new additional commands for low energy specific functions 1 5 Logical link control and adaptation layer protocol L2CAP The Logical Link Control and Adaptation Layer Protocol L2CAP supports higher level protocol multiplexing packet segmentation and reassembly operation and the conveying of quality of service information 1 6 Attribute Protocol ATT The Attribute Protocol ATT allows a device to expose c
64. e 69 3 6 1 Service discovery procedures and related GATT events 71 3 6 2 Characteristics discovery procedures and related GATT events 75 3 7 Characteristic notification indications write read 78 3 8 Basic typical error conditions description EE EE EE EE Es ske 82 3 9 BlueNRG MS simultaneously Master Slave scenario 82 4 BlueNRG multiple connections timing strategy 86 4 1 Basic concepts about Bluetooth Low Energy timing 86 4 1 1 Advertising timing 0 0 n 86 4 1 2 Scanning timing esi reran yraa a A es 87 4 1 3 Connection Timing llle Rh 87 4 2 BlueNRG timing and slot allocation concepts lssss 87 4 2 1 Setting the timing for the first Master connection 88 4 2 2 Setting the timing for further Master connections 89 4 2 3 Timing for Advertising Events ei essen 90 4 2 4 Timing forscanning ssseeelse eh 91 4 2 5 Slave timing 2 2 ssec emm eee ace che eae a T d 91 4 3 BlueNRG multiple Master amp Slave connections guidelines 91 5 References cce e ds unu RARR Re RE a A RN Ra BERE ED RED SS 93 Appendix A List of acronyms and abbreviations 94 6 Revision history ass ass ES ERERE E RERIEEWRATRERSEEREREEERREES 96 d DoclD027104 Rev 3 3 97 List of figures PM0237 List of figures Figure 1 Figure 2 Figure 3 Figure 4 Figure
65. e Fundamentals of Bluetooth low energy BLE technology e BlueNRG BlueNRG MS stacks architecture and application command interface ACI overview e How to design an application using the BlueNRG BlueNRG MS stacks ACI APIs Note The document content is valid for both BlueNRG and BlueNRG MS devices Any specific difference is highlighted whenever it is needed September 2015 DoclD027104 Rev 3 1 97 www st com Contents PM0237 Contents 1 Bluetooth low energy technology 000 EE RR RR RR eee eee 7 1 1 BLE stack architecture 20 00 0200 8 1 2 Physical layer ARE ELE EER RE R REK RRR EY Eg Ra Reed Re dc ee Ree EE 9 1 3 Eink Layer EL iu vex vu dire aao PA wan et n aO AE teste 11 1 3 1 BLE packets ocs neraed i mnai ee EE Ge Ge ee ee ses 12 1 3 2 Advertising state ia ER EE RE EE ER ES ree 15 1 3 3 Scanning state EE EE EE tee 16 1 3 4 Connection state EE EE EE EE EE tee 17 1 4 Host controller interface HCl EE Ee ee 18 1 5 Logical link control and adaptation layer protocol L2CAP 18 1 6 Attribute Protocol ATT sse LER RE RE Rx RE SR Pee eek EER REK 18 1 7 Security Manager SM ske orb uror mech RR ab hh Rem Re oe 20 1 8 Generic attribute profile GATT llle 22 1 8 1 Characteristic attribute type EE EE Ee ee ek ed ee 22 1 8 2 Characteristic descriptors type EE SE EE Ee ee ee ee 24 1 8 3 Service attribute type nananana EE EE EE ee 24 1 8 4 GATT proce
66. e mode with scan response enabled DoclD027104 Rev 3 63 97 Design an application using BlueNRG BlueNRG MS ACI APIs PM0237 64 97 1 EVT BLUE GAP DEVICE FOUND BlueNRG EVT LE ADVERTISING REPORT BlueNRG MS with advertising packet type evt type ADV IND 2 EVT BLUE GAP DEVICE FOUND BlueNRG device EVT LE ADVERTISING REPORT BlueNRG MS with scan response packet type evt type SCAN RSP Table 41 ADV IND event Eventtype Address type Address Advertising data RSSI 0x02 0x01 0x06 0x08 0x08 0x42 0x6 C 0x75 0x65 0x4 E 0x52 0x47 0x02 0x 0A 0x08 0x00 0x00 public 0x0280E1003 ADV IND address 412 The advertising data can be interpreted as follows refer to Bluetooth specification version 4 0 Vol 3 and 4 1 Vol 2 on Section 5 References Table 42 ADV IND advertising data Flags AD type field Local name field Tx power level 0x02 length of the field 0x08 length of the field 0x01 AD type Flags 0x08 Shortened local name 0x02 Length of the field 0x06 0x110 Bit 2 BR EDR type Ox0A Tx Power type Not Supported Bit 1 general 0x42 0x6C 0x75 0x65 0x4E0x 0x08 power value discoverable mode 52 0x47 BlueNRG Table 43 SCAN RSP event Eventtype Addresstype Address Scan response data RSSI 0x04 0x12 0x66 0x9A 0x0C 0x20 0x00 0x0 SCAN_RS pcd poc dd 8 0xA7 0xBA 0xE3 0x11 0x06 0x85 0 OxDA P xC0 0xF7 0x97 0x8A 0x06 0x11 The scan response data
67. ed BlueNRG multiple Master amp Slave connections guidelines The following guidelines should be followed for properly handling multiple master and slave connections using BlueNRG amp BlueNRG MS devices 1 Avoid over allocating connection event length choose Minimum CE Length and Maximum CE Length as small as possible to strictly satisfy the application needs Doing so will help the allocation algorithm to allocate several connections within the DoclD027104 Rev 3 91 97 BlueNRG multiple connections timing strategy PM0237 92 97 anchor period and to reduce the anchor period if needed to allocate connections with a small connection interval For the first Master connection a If possible create the connection with the shortest connection interval as the first one Doing so will help allocating further connections with connection interval multiple of the initial anchor period b If possible choose Conn_Interval_Min Conn Interval Max as multiple of 10 ms Doing so will help allocating further connections with connection interval submultiple by a factor 2 4 and 8 or more of the initial anchor period being still a multiple of 1 25 ms For additional Master connections a Choose Scanlnterval equal to the connection interval of one of the existing Master connections b Choose ScanWin such that the sum of the allocated master slots including Advertising if active is lower than the shortest allocated connection inte
68. efer to the Bluetooth specification v4 0 on Section 5 References Generic access profile GAP The Bluetooth system defines a base profile implemented by all Bluetooth devices called Generic Access Profile GAP This generic profile defines the basic requirements of a Bluetooth device The four GAP profiles roles are described in the table below Table 19 GAP roles Role Description Transmitter Receiver Typical example Broadcaster Sends advertising events M O Temperature sensor which sends temperature values Temperature display which Observer Receives advertising events O M just receives and display temperature values Always a slave It is on connectable Peripheral advertising mode M M Watch Supports all LL control procedures Encryption is optional Always a master It never advertises Central It supports active or passive M M Mobile phone scan It supports all LL control procedures Encryption is optional 1 M Mandatory O Optional DoclD027104 Rev 3 d PM0237 Bluetooth low energy technology d On GAP context two fundamental concepts are defined e GAP modes it configures a device to act in a specific way for a long time There are four GAP modes types broadcast discoverable connectable and bendable type e GAP procedures it configures a device to perform a single action for a specific limited time There are four GAP procedures types observer discovery
69. ertain pieces of data known as attributes to another device The device exposing attributes is referred to as the Server and the peer device using them is called the Client An attribute is a data with the following components e Attribute handle it is a 16 bits value which identifies an attribute on a Server allowing the Client to reference the attribute in read or write requests e Attribute type it is defined by a Universally Unique Identifier UUID which determines what the value means Standard 16 bits attribute UUIDs are defined by Bluetooth SIG e Attribute value a 0 512 octets in length e Attribute permissions they are defined by each higher layer that uses the attribute They specify the security level required for read and or write access as well as notification and or indication The permissions are not discoverable using the attribute protocol There are different permissions types Access permissions they determine which types of requests can be performed on an attribute readable writable readable and writable Authentication permissions they determine if attributes require authentication or not If an authentication error is raised client can try to authenticate it by using the Security Manager and send back the request Authorization permissions no authorization authorization this is a property of a server which can authorize a client to access or not to a set of attributes client cannot
70. ervice Uuid Length 0 no service to be advertised Service Uuid List NULL Slave Conn Interval Min 0 Slave connection internal minimum value Slave Conn Interval Max 0 Slave connection internal maximum value 7 u J ret aci gap set discoverable ADV IND 0 0 PUBLIC ADDR NO WHITE LIST USE sizeof local name local name 0 NULL 0 0 if ret BLE STATUS SUCCESS PRINTF Failure n end GAP Peripheral Make Discoverable GAP Central start general discovery procedure to discover the GAP peripheral device in discoverable mode void GAP Central General Discovery Procedure void tBleStatus ret DoclD027104 Rev 3 61 97 Design an application using BlueNRG BlueNRG MS ACI APIs PM0237 Start the general discovery procedure active scan using the following parameters Scan Interval 0x4000 Scan Window 0x4000 Own address type 0x00 public device address filterDuplicates 0x00 duplicate filtering disabled ret aci gap start general discovery proc 0x4000 0x4000 0x00 0x00 if ret BLE STATUS SUCCESS PRINTF Failure n The responses of the procedure are given through the EVT BLUE GAP DEVICE FOUND BlueNRG and EVT LE ADVERTISING REPORT BlueNRG MS events raised on HCI Event CB callback evr VENDOR as main event The end of the procedure is indicated by EVT BLUE GAP PROCEDURE COMPLETE event on the HCl Event CB callback EVT VENDOR as main event void
71. es S TM32L1xx_StdPeriph_Driver folder 2 STM32L1xx Cube libraries which are provided within the Drivers STM32L1xx HAL Driver folder 3 DoclD027104 Rev 3 PM0237 BlueNRG BlueNRG MS stacks architecture and ACI Table 29 ACI Interface resources files File Description Location Notes Main APIs These APIs are handling SPI Platform STM32L 1Xx Libraries SDK_Eval_STM mapped to the SDK_EVAL_SPI_Driver ch hal ch clock ch communicatio n with BlueNRG BlueNRG MS device Other APIs handling communicatio n with BlueNRG BlueNRG MS device SPI timer APIs 32L src on STM32L1 standard library framework Drivers BSP STM32L1xx_BlueNRG on STM32L1 Cube library framework platform STM32L1XX only on STM32L 1 standard library framework platform STM32L1XX on STM32L1 standard library framework It is defined within the specific user application folder on STM32L1 Cube library framework specific microcontroller low level drivers handling the SPI peripheral It provides the low level APIs handling the SPI timeouts stm32l1xx it c Standard library stm32xx it c Cube Library Main Interrupt Service Routines It is defined within the specific user application folder When using another external microcontroller these files should be ported adapted for addressing the ACI SPI communication In order to proper setup the ACI SPI interface user is only requested to perform
72. event data vy If needed add user code for using the event data EVT BLUE GATT PROCEDURE COMPLETE break switch blue evt ecode EVT VENDOR break switch evt gt subevent end HCI Event CB In the context of the BlueNRG Senor Profile Demo the GAP Central application should get two EVT BLUE ATT READ BY TYPE RESP events with following evt att read by type resp data First evt att read by type resp event data 0x0801 pr conn handle connection handle pr event data length 0x16 length of the event data pr gt handle value pair length 0x15 length of each discovered characteristic data characteristic handle properties characteristic value handle characteristic UUID pr gt handle value pair 0x15 bytes as follows Table 52 First evt att read by type resp event data Characteristic Characteristic Characteristic Characteristic UUID Note handle properties value handle Free Fall 0x0011 0x0012 characteristic BlueNRG 0x10 notify BlueNRG OxE23E78AO0CFA4A11E18FFCO0002A5D5 128 bits 0x000D y OXOOOE C51B characteristic BlueNRG MS BlueNRG MS proprietary UUID Second evt att read by type resp event data pr conn handle 0x0801 connection handle pr event data length 0x16 length of the event data Ky DocIDO27104 Rev 3 77 97 Design an application using BlueNRG BlueNRG MS ACI APIs PM0237 pr handle value pair
73. first data packet e Transmit window offset offset of transmit window start e Connection interval time between two connection events e Slavelatency number of times slave can ignore connection events before it is forced to listen e Supervision timeout max time between two correctly received packets before link is considered lost e Channel map 37 bits 12 good 0 bad e Frequency hop value random number between 5 and 16 e Sleep clock accuracy range used to determine the uncertainty window of the slave device at connection event For a detailed description of the connection request packet refer to Bluetooth Specification V4 0 Vol 6 Section 2 3 3 The allowed timing ranges are summarized in Table 7 Table 7 Connection request timings intervals Parameter Min Max Note Transmit window size 1 25 milliseconds 10 milliseconds Transmit window Offset 0 Connection interval Multiples ol 123 milliseconds Connection interval 7 5 milliseconds 4 seconds Multiples 0f1 25 milliseconds Supervision Timeout 100 milliseconds 32 seconds Muupies 2n milliseconds The transmit window starts after the end of the connection request packet plus the transmit window offset plus a mandatory delay of 1 25 ms When the transmit window starts the slave device enters in receiver mode and wait for a packet from the master device If no packet is received within this time the slave leaves receiver mode and it tries on
74. from server it always causes a response Server sends response to a request from a Response Server 3 client Command Client Client commands something to server no response Notification Samar Server notifies client of new value no confirmation AR Server indicates to client new value it always Indication Server causes a confirmation Confirmation Client Confirmation to an indication Ly DoclD027104 Rev 3 19 97 Bluetooth low energy technology PM0237 1 7 20 97 Security Manager SM The Bluetooth low energy link layer supports encryption and authentication by using the Cipher Block Chaining Message Authentication Code CCM algorithm and a 128 bit AES block cipher When encryption and authentication are used in a connection a 4 byte Message Integrity Check MIC is appended to the payload of the data channel PDU Encryption is applied to both the PDU payload and MIC fields When two devices want to encrypt the communication during the connection the Security Manager uses the pairing procedure This procedure allows to authenticate two devices and creates a common link key that can be used as a basis for a trusted relationship or a single secure connection Pairing procedure is a three phase process Phase 1 pairing feature exchange e The two connected devices communicates their input output capabilities by using the Pairing request message This message also contains a bit stating if out of band data is available
75. he LE Scan Interval is greater than the actual anchor period the SW automatically tries to subsample the LE Scan Interval and to reduce the allocated scan slot length up to of the LE Scan Window in order to keep the same duty cycle required by the Host given that Scanning parameters are just recommendations as stated by BT official specifications v 4 1 Vol 2 Part E 87 8 10 Slave timing The Slave timing is defined by the Master when the connection is created so the connection slots for Slave links are managed asynchronously with respect to the time base mechanism described above The Slave assumes that the Master may use a connection event length as long as the connection interval The scheduling algorithm adopts a round robin arbitration strategy any time a collision condition is predicted between a Slave and a Master slot In addition to this the scheduler may also impose a dynamic limit to the Slave connection slot duration to preserve both Master and Slave connections In particular e Ifthe end of a Master connection slot overlaps the beginning of a Slave connection slot then Master and Slave connections are alternatively preserved canceled e Ifthe end of a Slave connection slot overlaps the beginning of a Master connection slot then the Slave Connection slot length is hard limited to avoid such overlap If the resulting time interval is too small to allow for at least a two packets exchange then round robin arbitration is us
76. he timing of connection events is determined by 2 parameters e connection event interval conninterval time interval between the start of two consecutive connection events which shall never overlap the point in time where a connection event starts is named an anchor point At the anchor point a master shall start to transmit a Data Channel PDU to the slave which in turn listens to the packet sent by its master at the anchor point The master shall ensure that a connection event closes atleast T_IFS 150 us Inter Frame Spacing time i e time interval between consecutive packets on same channel index before the anchor point of next connection event The conninterval shall be a multiple of 1 25 ms in the range of 7 5 ms to 4 0 s e Slave latency connSlaveLatency allows a slave to use a reduced number of connection events This parameter defines the number of consecutive connection events that the slave device is not required to listen for the master When the Host wants to create a connection it provides the Controller with the maximum and minimum values of the connection interval Conn Interval Min Conn Interval Max and connection length Minimum CE Length Maximum CE Length thus giving the Controller some flexibility in choosing the actual parameters in order to fulfill additional timing constraints e g in the case of multiple connections BlueNRG timing and slot allocation concepts The BlueNRG adopts a time slotting mechanis
77. his case the following conditions must also be satisfied e Anchor Period k must be a multiple of 1 25 ms e Anchor Period k must be large enough to contain all the connection slots already allocated to the previous connections Once that a suitable anchor period has been found according to the criteria listed above then a time interval for the actual connection slot is allocated therein In general if enough space can be found in the anchor period the algorithm will allocate the maximum requested connection event length otherwise will reduce it to the actual free space When several successive connections are created the relative connection slots are normally placed in sequence with a small guard interval between 1 5 ms when a connection is closed this generally results in an unused gap between two connection slots If a new connection is created afterwards then the algorithm will first try to fit the new connection slot inside one of the existing gaps if no gap is wide enough then the connection slot will just be placed after the last one Figure 13 shows an example of how the time base parameters are managed when successive connections are created DoclD027104 Rev 3 89 97 BlueNRG multiple connections timing strategy PM0237 Figure 13 Example of timing allocation for three successive connections A First connection ConnIntMin 100 ms Anchor Period 200 ms Connection Interval 1 200 ms ConnIntMax 300 ms gt
78. ication The GAP central device use the service and discovery procedures to find the GAP Peripheral sensor profile demo service and characteristics Table 45 BlueNRG sensor profile demo services amp characteristics handles Characteristic eae Service characteristic Characteristic client Characteristic Service Characteristic descriptor handle value handle f format handle configuration handle Acceleration NA 0x0010 NA NA service Free Fall 0x0011 0x0012 0x0013 NA characteristic sere 0x0014 0x0015 0x0016 NA characteristic Enyironmental NA 0x0017 NA NA service Temperatur 0x0018 0x0019 NA 0x001A characteristic Table 46 BlueNRG MS sensor profile demo services amp characteristics handles Service Characteristic Service characteristic Characteristic value handle Characteristic client descriptor Characteristic format handle handle configuration handle Acceleration NA 0x000C NA NA NA service F Fall hu a 0x000D OXOOOE OXOOOF NA characteristic 3 DoclD027104 Rev 3 69 97 Design an application using BlueNRG BlueNRG MS ACI APIs PM0237 Table 46 BlueNRG MS sensor profile demo services amp characteristics handles continued Service Characteristic Service characteristic Characteristic value handle Characteristic client descriptor Characteristic format handle handle configuration handl
79. ies It uses a spread spectrum frequency hopping full duplex signal Key features of Bluetooth low energy technology are e robustness performance e reliability e interoperability e low data rate e low power In particular Bluetooth low energy technology has been created for the purpose of transmitting very small packets of data at a time while consuming significantly less power than Basic Rate Enhanced Data Rate High Speed BR EDR HS devices The Bluetooth low energy technology is designed for addressing two alternative implementations e Smart device e Smart Ready device Smart devices support only support the BLE standard It is used for applications in which low power consumption and coin cell battery is the key point as sensors Smart Ready devices support both BR EDR HS and BLE standards typically a mobile or a laptop device The Bluetooth low energy stack consists of two components e Controller e Host The Controller includes the Physical Layer and the Link Layer The Host includes the Logical Link Control and Adaptation Protocol L2CAP the Security Manager SM the Attribute protocol ATT Generic Attribute Profile GATT and the Generic Access Profile GAP The interface between the two components is called Host Controller Interface HCI d DoclD027104 Rev 3 PM0237 Bluetooth low energy technology 1 2 q In addition Bluetooth specification v4 1 have been released with new sup
80. ification tBleStatus ret uintl16 t handle value ifdef BLUENRG MS handle value OXOOOF else handle value 0x0013 endif Enable the free fall characteristic client descriptor configuration for ret aci gatt write charac descriptor conn handle handle value handle for free fall client descriptor configuration 0x02 attribute value length 0x0001 attribute value 1 for notification if ret BLE STATUS SUCCESS PRINTF Failure n ifdef BLUENRG MS handle value 0x0012 else handle value 0x0016 d DoclD027104 Rev 3 79 97 Design an application using BlueNRG BlueNRG MS ACI APIs PM0237 endif Enable the acceleration characteristic client descriptor configuration for notification ret aci gatt write charac descriptor conn handle handle value handle for acceleration client descriptor configuration 0x02 attribute value length 0x0001 attribute value 1 for notification if ret BLE STATUS SUCCESS PRINTF Failure n Once the characteristics notification have been enabled from the GAP Central the GAP peripheral can notify a new value for the free fall and acceleration characteristics as follows tBleStatus ret uint8 t val 0x01 uint16_t service handle value uintl16 t charac handle value ifdef BLUENRG MS service handle value 0x000C charac handle value 0x000D else service handle value 0x0
81. ion or free fall from the GAP Peripheral device Follow a pseudo code of the HCI Event CB callback void HCI Event CB void pckt hei uart pckt hci pckt pckt hci event pckt event pckt hci event pckt hci pckt data if hci pckt type HCI EVENT PKT return switch event pckt evt case EVT VENDOR Get the vendor event data evt blue aci blue evt void event pckt data switch blue evt secode case EVT BLUE GATT NOTIFICATION DoclDO27104 Rev 3 81 97 Design an application using BlueNRG BlueNRG MS ACI APIs PM0237 3 8 3 9 82 97 evt gatt attr notification evt evt gatt attr notification blue evt gt data evt gatt attr notification data evt conn handle connection handle evt event data length length of attribute value handle 2 bytes evt attr handle handle of the notified characteristic evt attr value characteristic value Add user code for handling the received notification based on the application scenario break switch blue evt ecode switch evt gt subevent end HCI Event CB Basic typical error conditions description On BlueNRG BlueNRG MS ACI framework the tBleStatus type is defined in order to return the BlueNRG BlueNRG MS stack error conditions The status and error codes are defined within the header file ble status h When a stack API is called it is recommended to get the API return status and to mon
82. itor it in order to track potential error conditions BLE STATUS SUCCESS 0x00 is returned when the API is successfully executed For a detailed list of error conditions associated to each ACI API refer to the UM1755 and UM1865 user manuals on Section 5 References BlueNRG MS simultaneously Master Slave scenario BlueNRG MS device stack supports multiple roles simultaneously This allows the same device to act as Master on one or more connections up to eight connections are supported on Stack Mode 3 and to act as a Slave on another connection The following pseudo code describes how a BlueNRG MS device can be initialized for supporting Central and Peripheral roles simultaneously uint8 t role GAP PERIPHERAL ROLE GAP CENTRAL ROLE ret aci gap init role 0 0x07 amp service handle amp dev name char handle amp appearance char handle A simultaneous Master and Slave test scenario can be easily targeted as follows d DoclD027104 Rev 3 PM0237 Design an application using BlueNRG BlueNRG MS ACI APIs d Figure 10 BlueNRG MS simultaneous Master amp Slave scenario Master amp Slave is a GAP peripheral r Master amp Slave 2 5 7 b N Slave A 9 Slave B 1 BlueNRG MS GAP central 2 BlueNRG MS GAP central mode 3 amp peripheral 3 BlueNRG MS GAP peripheral Master amp Slave is a GAP central Master amp Slave is a GAP central 1 One BlueNRG MS device called Master
83. le 0 0x07 amp service handle amp dev name char handle amp appearance char handle else ret aci_gap_init role amp service_handle amp dev_name_char_handle amp appearance char handle endif if ret PRINTF GAP Init failed n If security is used set the I O capability and authentication requirement refer to Section Hif GATT SERVER User application function where service and characteristics are defined refer to Section Services amp Characteristics Configuration Section ret Add Server Services Characteristics if ret BLE STATUS SUCCESS PRINTF Services amp Characteristics added successfully Nn else PRINTF Error while adding Services amp Characteristics NMn endif Main Application Loop while 1 Process any pending HCI events read HCI Process User specific application function where user actions and events are processed advertising connections services and characteristics discovery notification xy User Process d DoclD027104 Rev 3 43 97 Design an application using BlueNRG BlueNRG MS ACI APIs PM0237 end main Note 1 Init_Device initializes the STM32L1xx microcontroller according to the selected framework Standard or Cube library 2 User_Process is just an application dependent function On the following sections some reference specific actions events are descri
84. length characteristic 1 The characteristic handle CharHandle 2 is returned ret aci_gatt_add_char ServHandle UUID_TYPE 128 charUuid_2 20 CHAR PROP WRITE CHAR PROP WRITE WITHOUT RESP ATTR PERMISSION NONE GATT NOTIFY ATTRIBUTE WRITE 16 1 amp CharHandle 2 if ret BLE STATUS SUCCESS PRINTF Failure n return ret end Add_Server Services Characteristics DoclD027104 Rev 3 55 97 Design an application using BlueNRG BlueNRG MS ACI APIs PM0237 3 4 56 97 Create a connection discoverable and connectable APIs In order to establish a connection between a BlueNRG GAP central master device and a BlueNRG GAP peripheral slave device the GAP discoverable connectable modes and procedures can be used as described in Table 38 ACI GAP modes APIs Table 39 ACI discovery procedures APIs Table 40 ACI connection procedures APIs and by following the related ACI APIs described in the user manuals UM1755 and UM1865 Section 5 References GAP peripheral discoverable and connectable modes APIs Different types of discoverable and connectable modes can be used as described by the following APIs Table 38 ACI GAP modes APIs Supported advertising API event types Description 0x00 connectable undirected advertising Sets the device in general default discoverable mode aci gap set discoverable 0x02 scannable undirected di device iS discoverable Unt advertising the host issues the aci
85. long the device scans e Scan filter policy it can accept all the advertising packets default policy or only the ones on the white list Once the scan parameters are set it is possible to enable the device scanning The controller of the scanner devices sends to upper layers any received advertising packets within an Advertising Report event This event includes the advertiser address advertiser data and the received signal strength indication RSSI of this advertising packet The RSSI can be used with the transmit power level information included within the advertising packets to determine the path loss of the signal and identify how far the device is Path loss Tx power RSSI 3 DoclD027 104 Rev 3 PM0237 Bluetooth low energy technology 1 3 4 3 Connection state When data to be transmitted are more complex than the ones allowed by advertising data or a bidirectional reliable communication between two devices is needed the connection is established When an initiator device receives an advertising packet from an advertising device to which it wants to connect it can send a connect request packet to the advertiser device This packet includes all the required information needed for establishing and handling the connection between the two devices e Access address used in the connection in order to identify communications on a physical link e CRC initialization value e Transmit window size timing window for
86. lows uint8 t bdaddr 0x12 0x34 0x00 OxE1 0x80 0x02 ret aci hal write config data CONFIG DATA PUBADDR OFFSET CONFIG DATA PUBAD DR LEN bdaddr if ret BLE STATUS SUCCESS PRINTF Failure n void GAP Peripheral Make Discoverable void tBleStatus ret const char local namell AD TYPE COMPLETE LOCAL NAME B l u e N R G FP E tat tet t disable scan response passive scan hci le set scan resp data 0 NULL Put the GAP peripheral in general discoverable mode Advertising Event Type ADV IND undirected scannable and connectable Adv Interval Min 0 Adv Interval Max 0 Address Type PUBLIC ADDR public address 0x00 d DoclD027104 Rev 3 PM0237 Design an application using BlueNRG BlueNRG MS ACI APIs d Adv Filter Policy NO WHITE LIST USE no whit list is used Local Name Length 13 Local Name BlueNRG Test Service Uuid Length 0 no service to be advertised Service Uuid List NULL Slave Conn Interval Min 0 Slave connection internal minimum value Slave Conn Interval Max 0 Slave connection internal maximum value T ret aci gap set discoverable ADV IND 0 0 PUBLIC ADDR NO WHITE LIST USE sizeof local name local name 0 NULL 0 0 if ret BLE STATUS SUCCESS PRINTF Failure n end GAP Peripheral Make Discoverable GAP Central direct connection establishment procedure to connect to the GAP
87. m in order to be able to allocate simultaneous Master and Slave connections The basic parameters controlling the slotting mechanism are Table 55 Timings parameters of the slotting algorithm Parameter Description Recurring time interval inside which up to 8 connection slots can be allocated Anchor Period Among these 8 slots only 1 at a time may be a scanning or advertising slot they are mutually exclusive Time interval inside which a full event i e Advertising or Scanning and Slot Duration Connection takes place the slot duration is the time duration assigned to the connection slot and is linked to the maximum duration of a connection event DoclD027104 Rev 3 87 97 BlueNRG multiple connections timing strategy PM0237 4 2 1 88 97 Table 55 Timings parameters of the slotting algorithm Parameter Description Time value corresponding to the delay between the beginning of an anchor period a and the beginning of the Connection Slot Number representing the actual utilization rate of a certain connection slot in successive anchor periods Slot Latency For instance a slot latency equal to 1 means that a certain connection slot is actually used in each anchor period a slot latency equal to n means that a certain connection slot is actually used only once every n anchor periods Such timing allocation concept allows for a clean time handling of multiple connections but
88. mands utilize and extend the standard HCI data format defined within the Bluetooth specification v4 0 and v4 1 The ACI interface supports the following commands e Standard HCI commands for controller as defined by Bluetooth specification v4 0 and v4 1 e Vendor Specific VS HCI commands for controller e Vendor Specific VS ACI commands for host L2CAP ATT SM GATT GAP The reference ACI interface framework is provided within the BlueNRG BlueNRG MS kits software package targeting the BlueNRG BlueNRG MS kits based on STM32L1 external microcontroller refer to Section 5 References The ACI interface framework contains the code that is used to send ACI commands to the BlueNRG and BlueNRG MS network processors It also provides definitions of device events This framework allows to format each ACI command in the proper way and send the command incline with the defined ACI SPI communication protocol The ACI SPI communication protocol is described on the user manuals UM1755 BlueNRG Bluetooth LE stack application command interface ACI and UM1865 BlueNRG MS Bluetooth LE stack application command interface ACI available on ST BlueNRG web pages These user manuals also provide a complete description of all related devices ACI command formats name parameters return values and generated events The ACI framework interface is defined by the following header files Table 28 ACI Interface
89. ment MITM PROTECTION REQUIRED OOB AUTH DATA ABSENT no OOB data is present NULL no OOB data 7 Min encryption key size 16 Max encryption key size DONOT USE FIXED PIN FOR PAIRING no fixed pin 0 fixed pin not used DoclD027104 Rev 3 Ly PM0237 Design an application using BlueNRG BlueNRG MS ACI APIs d BONDING bonding is enabled if ret BLE STATUS SUCCESS PRINTF Failure n Once the security IO capability and authentication requirements are defined an application can initiate a pairing procedure as follow 1 byusingaci gap slave security request on a GAP Peripheral slave device it sends a slave security request to the master tBleStatus ret ret aci gap slave security request conn handle BONDING MITM PROTECTION REQUIRED Me if ret BLE STATUS SUCCESS PRINTF Failure n or 2 byusing the aci gap send pairing request ona GAP Central master device Since the DONOT USE FIXED PIN FOR PAIRING no fixed pin has been set once the paring procedure is initiated by one of the 2 devices BlueNRG BlueNRG MS will generate the EVT BLUE GAP PASS KEY REQUEST event with related connection handle for asking to the host application to provide the password to be used for establishing the encryption key BlueNRG BlueNRG MS application has to provide the correct password by using the aci gap pass key response conn handle passkey API
90. n Organizationally Unique Identifier OUI is a 24 bit number that is purchased from the IEEE This identifier uniquely identifies a company and it allows to reserve a block of possible public addresses up to 2 24 coming from the remaining 3 bytes of the public address for the exclusive use of a company with a specific OUI An organization company can request a new set of 6 bytes addresses when at least the 95 of previously allocated block of addresses have been used up to 2 24 possible addresses are available with a specific OUI BlueNRG and BlueNRG MS devices don t have a valid preassigned MAC address since the MAC address is specific to manufacturers The public address must be set by the external processor The ACI command to set the MAC address is ACT HAL WRITE CONFIG DATA opcode OxFCOC with command parameters as follow e Offset 0x00 0x00 identify the BTLE public address i e MAC address e Length 0x06 Length of the MAC address e Value Oxaabbccddeeff 48 bit array for MAC address The command ACI HAL WRITE CONFIG DATA should be sent to BlueNRG and BlueNRG MS devices by the uC before starting BLE operations after each power up or reset of BlueNRG The following pseudocode example illustrates how to set a public address uint8 t bdaddr 0x12 0x34 0x00 OxE1 0x80 0x02 ret aci hal write config data CONFIG DATA PUBADDR OFFSET CONFIG DATA PUBAD DR LEN bdaddr if ret PRINTF Setting address failed n
91. nection with Direct connection e a specific device using a General and selective establishment ERA Central set of connection interval procedures uses it procedure parameters Connection Updates the connection parameter update parameters used during the Central procedure connection Terminate Terminates a GAP Central procedure procedure DoclD027 104 Rev 3 29 97 Bluetooth low energy technology PM0237 30 97 Table 27 GAP bonding procedures Procedure Bonding procedure Description Starts the pairing process with the bonding bit set on the pairing request Notes Role Central For a detailed description of the GAP procedures refer to the Bluetooth specification v4 0 DoclD027 104 Rev 3 3 PM0237 Bluetooth low energy technology 1 10 d BLE profiles and applications A service collects a set of characteristics and exposes the behavior of these characteristics what the device does but not how a device uses them A service does not define characteristic use cases Use cases determine which services are required how to use Services on a device This is done through a profile which defines which services are required for a specific use case e Profile clients implement use cases e Profile servers implement services A profile may implement single or multiple services available and specified at http developer bluetooth org Standard profiles or proprie
92. ng connections 3 DoclD027104 Rev 3 PM0237 References 5 References Table 56 References table Name Title AN4494 Bringing up the BlueNRG application note BlueNRG datasheet Bluetooth low energy wireless network processor BlueNRG MS datasheet Bluetooth low energy wireless network processor BlueNRG DK SW package BlueNRG SW package for BlueNRG and BlueNRG MS kits Bluetooth specification V4 0 Specification of the Bluetooth system v4 0 Bluetooth specification V4 1 Specification of the Bluetooth system v4 1 UM1755 BlueNRG Bluetooth LE stack application command interface ACI user manual UM1865 BlueNRG MS Bluetooth LE stack application command interface ACI user manual UM1686 BlueNRG development kits user manual UM1870 BlueNRG MS development kits user manual d DoclD027 104 Rev 3 93 97 List of acronyms and abbreviations PM0237 Appendix A List of acronyms and abbreviations This appendix lists the standard acronyms and abbreviations used throughout the document Table 57 List of acronyms Term Meaning ACI Application command interface ATT Attribute protocol BLE Bluetooth low energy BR Basic rate CRC Cyclic redundancy check CSRK Connection signature resolving Key EDR Enhanced data rate EXTI External interrupt GAP Generic access profile GATT Generic attribute profile GFSK Gaussian fre
93. ng state Advertising states allow Link Layer to transmit advertising packets and also to respond with scan responses to scan requests coming from devices which are actively scanning An advertiser device can be moved to a standby state by stopping the advertising Each time a device advertises it sends the same packet on each of the three advertising channels This three packets sequence is called an advertising event The time between two advertising events is referred to as the advertising interval which can go from 20 milliseconds to every 10 28 seconds Following is an example of advertising packet that lists the Service UUID that the device implements General Discoverable flag tx power 4dbm Service data temperature service and 16 bits service UUIDs Figure 5 Advertising packet with AD type flags GAMSEC201411251139 The Flags AD type byte contains the following flag bits e Limited Discoverable Mode bit 0 e General Discoverable Mode bit 1 BR EDR Not Supported bit 2 It is 1 on BLE e Simultaneous LE and BR EDR to Same Device Capable Controller bit 3 e Simultaneous LE and BR EDR to Same Device Capable Host bit 4 The Flags AD type shall be included in the advertising data if any of the bits are non zero it is not included in scan response The following advertising parameters can be set before enabling advertising e Advertising interval e Advertising address type e Advertising device ad
94. om the scanning results all the devices are sent to the upper layer using the event EVT BLUE GAP DEVICE FOUND on BlueNRG device and EVT LE ADVERTISING REPORT on BlueNRG MS device DoclD027104 Rev 3 57 97 Design an application using BlueNRG BlueNRG MS ACI APIs PM0237 3 4 1 Note 58 97 Table 40 ACI connection procedures APIs continued ACI API Description It starts a selective connection establishment procedure The GAP adds the specified device addresses into white list and enables scanning in the controller with the scanner filter policy set to accept packets only from devices in aci_gap_start_selective_conn_establishment whitelist All the devices found are sent to the upper layer by the event EVT_BLUE_GAP_DEVICE_FOUND on BlueNRG device and EVT LE ADVERTISING REPORT on BlueNRG MS device aci gap terminate gap procedure Terminate the specified GAP procedure Set discoverable mode amp use direct connection establishment procedure The following pseudocode example illustrates only the specific steps to be followed for putting a GAP Peripheral device in general discoverable mode and for a GAP central device to direct connect to it through a direct connection establishment procedure GAP Peripheral general discoverable mode and no scan response is sent Note It is assumed that the device public address has been set during the initialization phase as fol
95. on Scenarios conn handle cc handle EVT LE CONN COMPLETE break switch evt subevent EVT LE META EVENT break case EVT VENDOR Get the vendor event data evt blue aci blue evt void event pckt data d 52 97 DoclD027104 Rev 3 PM0237 Design an application using BlueNRG BlueNRG MS ACI APIs d switch blue_evt gt ecode Hif GATT SERVER case EVT BLUE GATT ATTRIBUTE MODIFIED Get attribute modification event data evt gatt attr modified evt evt gatt attr modified blue evt gt data evt gt conn_handle the connection handle which modified the attribute evt gt attr_handle handle of the attribute that was modified evt gt data_length the length of the data evt gt att_data pointer to the new value length is data length Add user code for handling attribute modification event based on application scenarios EVT BLUE GATT ATTRIBUTE MODIFIED break endif GATT SERVER dif GATT CLIENT case EVT BLUE GATT NOTIFICATION Get attribute notification event data evt gatt attr notification evt evt gatt attr notification blue evt data evt conn handle the connection handle which notified the attribute evt event data length length of attribute value handle 2 bytes evt attr handle attribute handle evt attr value pointer to attribute value length is event data length 2 Add user code for handling at
96. orms USER DEFINED PLATFORM STEVAL IDBO003V1 itis valid for both BlueNRG BlueNRG MS USB dongles 38 97 DoclD027104 Rev 3 Ly PM0237 BlueNRG BlueNRG MS stacks architecture and ACI Note d The following define values allow to select at compile time the specific platforms header files provided within the platform STM32L1XX Libraries SDK_Eval_STM32L inc folder STM32L1xx standard library case dif USER DEFINED PLATFORM STEVAL IDB002V1 include USER Platform Configuration STEVAL IDB002V1 h elif USER DEFINED PLATFORM STEVAL IDBOO3V1 include USER Platform Configuration STEVAL IDBO003V1 h endif A user platform can be simply supported at compile time by following these steps 1 Create a file USER Platform Configuration h with specific user platform configuration USER Platform Configuration STEVAL IDBO02V1 h Or USER Platform Configuration STEVAL IDB003V1 h can be used as reference on STM32L1xx standard library case to be extended based on available user platform resources 2 Place the USER Platform Configuration h on the STM32L platform STM32L1XxX Libraries SDK_Eval_STM32L inc folder STM32L1xx standard library case 3 On the selected EWARM workspace preprocessor options add this define USER DEFINED PLATFORM USER EVAL PLATFORM If no user platform is defined at compile time through the related preprocessor option USER DEFINED PLATFORM is automatically set to STEVAL IDBOOxV1 This
97. ported features e Multiple roles simultaneously support e Support simultaneous advertising and scanning e Support being Slave of up to two Masters simultaneously e Privacy V1 1 e Low Duty Cycle Directed Advertising e Connection parameters request procedure e LEPing e 32 bits UUIDs e L2CAP Connection Oriented Channels For more information about these new features refer to the related specification document Figure 2 Bluetooth low energy stack architecture Host Controller Interface Link layer PHY layer GAMSEC201411251124 Physical layer The physical layer is a 1 Mbps adaptive frequency hopping Gaussian Frequency Shift Keying GFSK radio It operates in the license free 2 4 GHz ISM band at 2400 2483 5 MHz Many other standards use this band IEEE 802 11 IEEE 802 15 The BLE system uses 40 RF channels 0 39 with 2 MHz spacing These RF channels have frequencies centered at DoclD027104 Rev 3 9 97 Bluetooth low energy technology PM0237 2402 k 2 MHz where k 0 39 There are two channels types 1 Advertising channels that use three fixed RF channels 37 38 and 39 for a Advertising channel packets b Packets used for discoverability connectability c Used for broadcasting scanning 2 Data physical channel uses the other 37 RF channels for bidirectional communication between connected devices Table 1 BLE RF channel types and frequencies Channel index RF center frequen
98. power up or reset requires several SPI transaction as follows Make the device entering Updater mode 1 SPI transaction Read MAC address from the device IFR 1 SPI transaction Make the device leaving Updater mode 1 SPI transaction BLE standard can also use random addresses which are defined by users and they do not follow the public addresses rules The random addresses are handled autonomously by the device are set at each reset but they can also be overwritten by the external processor using the hci le set random address APIl Private addresses are used when privacy is enabled and according to the Bluetooth low energy specification For more information about private addresses refer to Section 1 7 Security Manager SM DoclD027104 Rev 3 Ly PM0237 Design an application using BlueNRG BlueNRG MS ACI APIs 3 1 2 3 Set tx power level During the initialization phase user can also select the transmitting power level using the following API aci_hal_set_tx_power_level high or standard power level Follow a pseudocode example for setting the radio transmit power in high power and 2 dBm output power ret aci hal set tx power level 1 4 For a complete description of this API and related parameters refer to the UM1755 and UM1865 user manuals on the Section 5 References DoclD027 104 Rev 3 49 97 Design an application using BlueNRG BlueNRG MS ACI APIs PM0237 3 2 BlueNRG
99. ption Used by an advertiser when it wants a particular device to connect to it The ADV_DIRECT_IND packet contains only advertiser s address and initiator address Used by an advertiser when it wants to provide some information to all the devices but it does not want other devices to ask it for more information or to connect to it Device simply sends advertising packets on related channels but it does not want to be connectable or scannable by any other device Scannable undirected ADV_SCAN_IND gn ET x advertising Used by an advertiser which wants to allow a scanner to require more information from it The device cannot connect but itis discoverable for advertising data and scan response data SCAN REQ Scan request SCAN RSP Scan response Used by a device in scanning state to request addition information to the advertiser Used by an advertiser device to provide additional information to a scan device CONNECT REQ Connection request DoclD027104 Rev 3 Sent by an initiating device to a device in connectable discoverable mode 13 97 Bluetooth low energy technology PM0237 14 97 The advertising event type determines the allowable responses Table 4 Advertising event type and allowable responses Allowable response Advertising event type SCAN REQ CONNECT REQ ADV IND YES YES ADV DIRECT IND NO YES ADV NONCONN IND NO NO ADV SCAN IND YES NO
100. quency Shift keying HCI Host controller interface IFR Information register IRK Identity resolving key ISM Industrial scientific and medical LE Low energy L2CAP Logical link control adaptation layer protocol LTK Long term key MCU Microcontroller unit MITM Man in the middle NA Not applicable NESN Next sequence number OOB Out of band PDU Protocol data unit RF Radio frequency RSSI Received signal strength indicator SIG Special interest group SM Security manager SN Sequence number USB Universal serial bus 94 97 DoclD027 104 Rev 3 Ky PM0237 List of acronyms and abbreviations d Table 57 List of acronyms continued UUID Term Universally unique identifier Meaning WPAN Wireless personal area networks DoclD027 104 Rev 3 95 97 Revision history PM0237 6 96 97 Revision history Table 58 Document revision history Date Revision Changes 23 Jan 2015 1 Initial release The document has been adapted to refer to both BlueNRG and ud cu BlueNRG MS devices Added reference to STM32L Cube library framework on 02 Sep 2015 3 Chapter 2 BlueNRG BlueNRG MS stacks architecture and ACI Added Chapter 4 BlueNRG multiple connections timing strategy DoclD027 104 Rev 3 d PM0237 IMPORTANT NOTICE PLEASE READ CAREFULLY STMicroelectronics NV and its subsidiaries ST reserve the right to make changes corrections enhancements modification
101. re able to recognize it It is also possible to transmit authenticated data over an unencrypted Link Layer connection by using the CSRK key a 12 byte signature is placed after the data payload at the ATT layer The signature algorithm also uses a counter which allows to provide protection against replay attacks an external device which can simply capture some packets and send them later as they are without any understanding of packet content the receiver device simply checks the packet counter and discards it since its frame counter is less than the latest received good packet DoclD027104 Rev 3 21 97 Bluetooth low energy technology PM0237 1 8 1 8 1 22 97 Generic attribute profile GATT The Generic Attribute Profile GATT defines a framework for using the ATT protocol and it is used for services characteristics descriptors discovery characteristics reading writing indication and notification On GATT context when two devices are connected there are two devices roles e GATT client it is the device which accesses data on the remote GATT server via read write notify or indicate operations e GATT server it is the device which stores data locally and provides data access methods to a remote GATT client It is possible for a device to be a GATT server and a GATT client at the same time The GATT role of a device is logically separated from the master slave role The master slave roles define how
102. rminated procedure code pr status BLE STATUS SUCCESS BLE STATUS FAILED or ERR AUTH FAILURE pr gt data VARIABLE SIZE procedure specific data if applicable xf If needed add user code for handling the event data EVT BLUE GAP PROCEDURE COMPLETE break switch blue evt ecode EVT VENDOR break case EVT LE META EVENT evt le meta event evt void event pckt data switch evt subevent case EVT LE ADVERTISING REPORT BlueNRG MS stack le advertising info pr void evt gt data 1 evt data 0 is number of reports On BlueNRG MS is always 1 le advertising info parameters pr evt type event type advertising packets types pr bdaddr type type of the peer address PUBLIC ADDR RANDOM ADDR pr gt bdaddr address of the peer device found during scanning pr length length of advertising or scan response data pr data RSSI length advertising or scan response data RSSI RSSI is last octect signed integer Add user code for decoding the le advertising info event data based on the specific pr evt type ADV IND SCAN RSP EVT LE ADVERTISING REPORT break end switch EVT LE META EVENT break V switch event_pckt gt evt V end HCI Event CB In particular in this specific context the following events are raised on the GAP Central HCI Event CB as a consequence of the GAP peripheral device in discoverabl
103. rocessor options add this define USER DEFINED PLATFORM USER EVAL PLATFORM 3 Replace the STM32L1xx libraries on folder platform STM32L1 XX Libraries STM32L1xx_StdPeriph_Driver folder with the specific microcontroller low level drivers STM32L1xx standard library case 4 Replace the CMSIS Cortex M3 files and the startup file file startup stm32l1xx md s accordingly to the selected microcontroller 5 Readapt port accordingly to the selected microcontroller the file system stm32l1xx c handling the system clock configuration for STM32L 1xx 6 Adapt port the files described in the section in order to refer to the selected external microcontroller low level drivers Readapt port accordingly to the selected microcontroller the stm3211xx it c STD library stm32xx it c Cube Library files make sure that HCI Isr is called within the SPI irq API handling the external IRQ interrupt on the IRQ line Once the ACI SPI interface framework has been ported to the selected microcontroller user can verify that SPI access from external microcontroller is working by performing the basic test described in the section SPI Interface of the application note AN4494 Bringing up the BlueNRG BlueNRG MS available on ST BlueNRG and BlueNRG MS web pages Similar approach can be followed on STM32L1xx Cube context by referring to the specific files on Drivers folder CMSIS and STM32L1xx HAL Driver d DoclD027 104 Rev 3 PM0237 Design an applic
104. rval c Choose Conn Interval Min and Conn Interval Max such that the interval contains either a multiple of the shortest allocated connection interval asubmultiple of the shortest allocated connection interval being also a multiple of 1 25 ms d Choose Maximum CE Length Minimum CE Length such that the sum of the allocated master slots including Advertising if active plus Minimum CE Length is lower than the shortest allocated connection interval Every time you start Advertising a If Direct Advertising choose Advertising Interval Min Advertising Interval Max integer multiple of the shortest allocated connection interval b If not Direct Advertising choose Advertising Interval Min Advertising Interval Max such that Advertising Interval Min 5ms is an integer multiple of the shortest allocated connection interval Every time you start Scanning a Choose Scanlnterval equal to the connection interval of one of the existing Master connections b Choose ScanWin such that the sum of the allocated master slots including Advertising if active is lower than the shortest allocated connection interval Keep in mind that the process of creating multiple connections then closing some of them and creating new ones again over time tends to decrease the overall efficiency of the slot allocation algorithm In case of difficulties in allocating new connections the time base can be reset to the original state closing all existi
105. rvice UUID Ao AU ENGANAN No authorization Secondary Service DocID027104 Rev 3 Ly PM0237 Bluetooth low energy technology 1 8 4 d A service shall contain a service declaration and may contain definitions and characteristic definitions A service includes declaration follows the service declaration and any other attributes of the server Table 15 Include declaration Attribute handle Attribute permissions Attribute type Attribute value 0x2802 UUID Include service End grou Service Read only OxNNNN for include attribute group No authentication handle UUID ap attribute type handle No authorization Include service attribute handle is the attribute handle of the included secondary service and end group handle is the handle of the last attribute within the included secondary service GATT procedures The Generic Attribute Profile GATT defines a standard set of procedures allowing to discover services characteristics related descriptors and how to use them The following procedures are available e Discovery procedures Table 16 e Client initiated procedures Table 17 e Serverinitiated procedures Table 18 Table 16 Discovery procedures and related response events Procedure Discovery all primary services Response events Read by group response Discovery primary service by service UUID Find by type value response
106. rvices handle property UUID bytes handle Peripheral Preferred 0x000A Read Write without Ox000B Ox2A04 8 Connection Response Write Parameters Reconnection Read Write without Address 0X00 Response Write EL d Peripheral Preterred 0x000E Read Write 0x000F 0x2A04 8 Connection Parameters Table 34 BlueNRG MS GATT GAP default services Default services Start handle End handle Service UUID Atribute prone 0x0001 0x0004 0x1801 service Generic access profile 0x0005 0x000B 0x1800 GAP service Table 35 BlueNRG MS GATT GAP default characteristics Char Default Characteristic Attribute TE value Char Char value length Services handle property UUID bytes handle Attribute Profile Service POM 0x0002 Indicate 0x0003 Ox2A05 4 Changed Generic Access Profile GAP Service Read Write without Response Write Device Name 0x0006 Authenticated Signed 0x0007 Ox2A00 7 Writes Ky DoclD027104 Rev 3 45 97 Design an application using BlueNRG BlueNRG MS ACI APIs PM0237 Table 35 BlueNRG MS GATT GAP default characteristics Default Characteristic Attribute Char bropert bil Char Char value length Services handle property UUID bytes handle Read Write without Response Write Appearance 0x0008 Authenticated Signed 0x0009 0x2A01 2 Writes Peripheral Preferred 0x000A Read Write without 0x000B 0x2A04 8 Connection Response
107. s and improvements to ST products and or to this document at any time without notice Purchasers should obtain the latest relevant information on ST products before placing orders ST products are sold pursuant to ST s terms and conditions of sale in place at the time of order acknowledgement Purchasers are solely responsible for the choice selection and use of ST products and ST assumes no liability for application assistance or the design of Purchasers products No license express or implied to any intellectual property right is granted by ST herein Resale of ST products with provisions different from the information set forth herein shall void any warranty granted by ST for such product ST and the ST logo are trademarks of ST All other product or service names are the property of their respective owners Information in this document supersedes and replaces information previously supplied in any prior versions of this document 2015 STMicroelectronics All rights reserved d DoclD027104 Rev 3 97 97
108. skey Entry Just Works Passkey Entry Display Just Works Just Works Passkey Entry Just Works Passkey Entry Yes No Keyboard Only Passkey Entry Passkey Entry Passkey Entry Just Works Passkey Entry No Input No Just Works Just Works Just Works Just Works Just Works Output Keyboard Display Passkey Entry Passkey Entry Passkey Entry Just Works Passkey Entry Phase 3 transport specific key distribution e Once the Phase 2 is completed up to three 128 bit keys can be distributed by messages encrypted with the STK key a Long term key LTK it is used to generate the 128 bit key used for Link Layer encryption and authentication b Connection signature resolving key CSRK it is used for the data signing performed at the ATT layer Bluetooth low energy technology c Identity resolving key IRK itis used to generate a private address on the basis of a device public address When the established encryption keys are stored in order to be used for future authentication the devices are bonded Another security mechanism supported from BLE is the use of private addresses A private address is generated by encrypting the public address of the device This private address can be resolved by a trusted device that has been provided with the corresponding encryption key This allows the device to use a private address for a more secure communication and to change it frequently only devices with the related IRK a
109. tandard operating with a coin cell battery for several years Classic Bluetooth technology was developed as a wireless standard allowing to replace cables connecting portable and or fixed electronic devices but it cannot achieve an extreme level of battery life because of its fast hopping connection oriented behavior and relatively complex connection procedures Bluetooth low energy devices consume only a fraction of the power of standard Bluetooth products and enable devices with coin cell batteries to be wirelessly connected to standard Bluetooth enabled devices Figure 1 Bluetooth low energy technology enabled coin cell battery devices GAMSEC201411251047 Bluetooth low energy technology is used on a broad range of sensor applications transmitting small amounts of data e Automotive e Sport and fitness e Healthcare e Entertainment e Home automation e Security and proximity DoclD027104 Rev 3 7 97 Bluetooth low energy technology PM0237 1 1 8 97 BLE stack architecture Bluetooth low energy technology has been formally adopted by the Bluetooth Core Specification version 4 0 on Section 5 References This version of the Bluetooth standard supports two systems of wireless technology e Basic rate e Bluetooth low energy Bluetooth low energy technology operates in the unlicensed industrial scientific and medical ISM band at 2 4 to 2 485 GHz which is available and unlicensed in most countr
110. tary profiles can be used When using a non standard profile a 128 bit UUID is required and must be generated randomly Currently any standard Bluetooth SIG profile services and characteristics uses 16 bit UUIDs Services amp characteristics specification amp UUID assignation can be downloaded from the following SIG web pages e _https developer bluetooth org gatt services Pages ServicesHome aspx e https developer bluetooth org gatt characteristics Pages CharacteristicsHome aspx DoclD027 104 Rev 3 31 97 Bluetooth low energy technology PM0237 Figure 7 Client and server profiles Server ServiceA i Service B Use case 1 uses Service A and B Use case 2 uses Service B GAMSEC201411251354 1 10 1 Proximity profile example This section simply describes the Proximity Profile in terms its target how it works and required services Target e When is a device close very far far away cause an alert d 32 97 DoclD027104 Rev 3 PM0237 Bluetooth low energy technology d How it works e if a device disconnects e cause an alert e alerton link loss Link Loss service ifadevice is too far away cause an alert on path loss Immediate Alert amp Tx Power service e Link Loss service Alert Level characteristic Behavior on link loss cause alert as enumerated e Immediate Alert service Alert Level characteristic Beha
111. teristics Table 54 Characteristics update read write APIs Discovery service API Description Where If notifications or indications are enabled aci_gatt_update_char_value on the characteristic this API sends a GATT server notification or indication to the client aci_gatt_read_charac_val Pi the procedure to read the attribute GATT dlient It starts the procedure to write the attribute 3 value when the procedure is completed a aci gatt write charac value EVT BLUE GATT PROCEDURE COMP GATT client LETE event is generated It starts the procedure to write a aci gatt write without response characteristic value without waiting for any GATT client response from the server 78 97 DoclD027104 Rev 3 ky PM0237 Design an application using BlueNRG BlueNRG MS ACI APIs Table 54 Characteristics update read write APIs Discovery service API Description Where It start the procedure to write a characteristic descriptor SATI client aci_gatt_write_charac_descriptor It confirms an indication This command has to be sent when the application aci gatt confirm indication receives the event GATT client EVT BLUE GATT INDICATION on the reception of a characteristic indication In the context of the sensor profile demo follow a simple pseudo code the GAP Central application should use in order to configure the free fall and the acceleration characteristics client descriptors configuration for not
112. the BLE radio connection is managed and the GATT client server roles are determined by the data storage and flow of data As consequence it is not required that a slave peripheral device has to be the GATT server and that a master central device has to be the GATT client Attributes as transported by the ATT are encapsulated within the following fundamental types 1 Characteristics with related descriptors 2 Services primary secondary and include Characteristic attribute type A characteristic is an attribute type which contains a single value and any number of descriptors describing the characteristic value that may make it understandable by the user A characteristic exposes the type of data that the value represents if the value can be read or written how to configure the value to be indicated or notified and it says what a value means A characteristic has the following components 1 Characteristic declaration 2 Characteristic value 3 Characteristic descriptor s d DoclD027104 Rev 3 PM0237 Bluetooth low energy technology 3 Figure 6 Example of characteristic definition Characteristic Definition Characteristic Declaration Characteristic Value Declaration Descriptor Declaration Descriptor Declaration GAMSEC201411251245 A characteristic declaration is an attribute defined as follows Table 12 Characteristic declaration Attribute handle OxNNNN
113. the GAP procedure a EVT LE CONN COMPLETE event is returned on the HCI Event CB event callback to indicate that a connection has been established with the Gap Peripheral address same event is returned on the GAP peripheral device 2 The connection procedure can be explicitly terminated by issuing the command aci gap terminate gap procedure 3 The last two parameters Conn Len Min and Conn Len Max of the aci gap create connection are the length of the connection event needed for the BLE connection These parameters allows user to specify the amount of time the master has to allocate for a single slave so they must be wisely choosen In particular when a master connects to more slaves the connection interval for each slave must be equal or a multiple of the other connection intervals and user must not overdo the connection event length for each slave Set discoverable mode amp use general discovery procedure active scan The following pseudocode example illustrates only the specific steps to be followed for putting a GAP Peripheral device in general discoverable mode and for a GAP central device to start a general discovery procedure in order to discover devices within its radio range GAP Peripheral general discoverable mode scan responses are sent It is assumed that the device public address has been set during the initialization phase as follows uint8 t bdaddr 0x12 0x34 0x00 OxE1 0x80 0x02 ret aci
114. tput 0x04 Keyboard display PassKey Entry example with 2 BlueNRG devices Device_1 Device_2 The following pseudocode example illustrates only the specific steps to be followed for pairing two devices by using the PassKey entry method As described in Section Table 11 Methods used for calculating the Temporary Key TK Device 1 Device 2 have to set the IO capability in order to select PassKey entry as a security method On this particular example Display Only on Device 1 and KeyBoard Only on Device 2 are selected as follows Device 1 tBleStatus ret ret aci gap set io capability IO CAP DISPLAY ONLY if ret BLE STATUS SUCCESS PRINTF Failure n Device 2 tBleStatus ret ret aci gap set io capability IO CAP KEYBOARD ONLY if ret BLE STATUS SUCCESS PRINTF Failure n Once the IO capability are defined the aci gap set auth requirement should be used for setting all the security authentication requirements the device needs MITM mode authenticated link or not OOB data present or not use fixed pin or not enabling bonding or not The following pseudocode example illustrates only the specific steps to be followed for setting the authentication requirements for a device with MITM protection No OOB data don t use fixed pin this configuration is used to authenticate the link and to use a not fixed pin during the pairing process with PassKey Method ret aci gap set auth require
115. tribute notification event based on application scenarios EVT BLUE GATT NOTIFICATION break break endif GATT CLIENT switch blue evt ecode EVT VENDOR break switch evt gt subevent end HCI Event CB DoclD027104 Rev 3 53 97 Design an application using BlueNRG BlueNRG MS ACI APIs PM0237 3 3 54 97 Services and characteristic configuration In order to add a service and related characteristics a user application has to define the specific profile to be addressed 1 Standard profile defined by Bluetooth SIG organization The user must follow the profile specification and services characteristic specification documents in order to implement them by using the related defined Profile Services amp Characteristics 16 bits UUID refer to Bluetooth SIG web page https www bluetooth org en us specification adopted specifications 2 Proprietary non standard profile The user must define its own services and characteristics In this case 128 bits UIDS are required and must be generated by profile implementers refer to UUID generator web page http Awww famkruithof net uuid uuidgen A service can be added using the following command aci gatt add serv Service UUID Type Service UUID 16 Service Type Max Attributes Records amp ServHandle This command returns the pointer to the Service Handle ServHandle which is used to identify the service within the user
116. vior when written cause alert as enumerated e Tx Power service Tx Power characteristic Behavior when read reports current Tx Power for connection DoclD027 104 Rev 3 33 97 BlueNRG BlueNRG MS stacks architecture and ACI PM0237 2 34 97 BlueNRG BlueNRG MS stacks architecture and ACI The BlueNRG BlueNRG MS devices are network coprocessors which provide high level interface to control its Bluetooth low energy functionalities This interface is called ACI application command interface Figure 8 BlueNRG BlueNRG MS stacks architecture and interface to the external host EXTERNAL MCU nare ad Application Command Interface ACI Power Memo Management ry BLE Controller Standard or proprietary GAMSEC201411261359 BlueNRG and BlueNRG MS devices embed respectively the Bluetooth Smart protocol stack v4 0 and v4 1 and as a consequence no BLE library is required on the external microcontroller except for profiles and all the functions needed to communicate with the BlueNRG or BlueNRG MS device SPI interface The SPI interface communication protocol allows the external microcontroller to send ACI commands to control the BlueNRG or BlueNRG MS device and to receive the ACI events generate from the BlueNRG or BlueNRG MS device network coprocessor DoclD027104 Rev 3 Ly PM0237 BlueNRG BlueNRG MS stacks architecture and ACI 2 1 d ACI interface The ACI com
117. y use It cannot use a connectable Nonseconneetapis SDN INONCONN IND or advertising packet when it Peripheral mode ADV SCAN IND Sng p P n advertise advertising packets It is used from a Peripheral device that wants to connect Direct connectable It uses ADV DIRECT quickly ioa Central devise It i ah can be used only for 1 28 Peripheral mode advertising packet seconds and it requires both peripheral and central devices addresses It is used from a device that wants to be connectable Since ADV IND advertising packet can include the Flags AD type a device can be in discoverable and undirected pda d ias the ed iu connectable mode at the Peripheral connectable mode advertising packet safe time Connectable mode is terminated when the device moves to connection mode or when it moves to non connectable mode Table 23 GAP bondable modes Mode Description Notes GAP role Non bondable does not allow bondig No keys are stored from the be created with a peer Peripheral mode device device Device accepts bonding Bondable mode request from a Central Peripheral device The following GAP procedures are defined in Table 24 Table 24 GAP observer procedure Procedure Description Notes Role Observation It allows a device to look for Observer procedure broadcaster devices data DoclD027104 Rev 3 d PM0237 Bluetooth low energy technology d Table 25 GAP discovery procedures

BlueNRG, BlueNRG-MS stacks programming guidelines

Contents

Download Pdf Manuals

Related Search

Related Contents