Fork for the GitHub

Embed: (wiki syntax)

« Back to documentation index

Bluetooth OOB library

Bluetooth OOB library

This module is used to manage a Bluetooth Out-Of-Band NDEF message, to start a communication based on Bluetooth. More...

Data Structures

struct  Ndef_Bluetooth_OOB_t
 Bluetooth Out-Of-Band data structure. More...
struct  NDEF_EIR_t
 Extended Inquiry Response format. More...

Enumerations

enum  Ndef_Bluetooth_Eir_Types_t {
  BLUETOOTH_EIR_FLAGS = 0x01, BLUETOOTH_EIR_SERVICE_CLASS_UUID_PARTIAL_16 = 0x02, BLUETOOTH_EIR_SERVICE_CLASS_UUID_COMPLETE_16 = 0x03, BLUETOOTH_EIR_SERVICE_CLASS_UUID_PARTIAL_32 = 0x04,
  BLUETOOTH_EIR_SERVICE_CLASS_UUID_COMPLETE_32 = 0x05, BLUETOOTH_EIR_SERVICE_CLASS_UUID_PARTIAL_128 = 0x06, BLUETOOTH_EIR_SERVICE_CLASS_UUID_COMPLETE_128 = 0x07, BLUETOOTH_EIR_SHORT_LOCAL_NAME = 0x08,
  BLUETOOTH_EIR_COMPLETE_LOCAL_NAME = 0x09, BLUETOOTH_EIR_TX_POWER_LEVEL = 0x0A, BLUETOOTH_EIR_DEVICE_CLASS = 0x0D, BLUETOOTH_EIR_SIMPLE_PAIRING_HASH = 0x0E,
  BLUETOOTH_EIR_SIMPLE_PAIRING_RANDOMIZER = 0x0F, BLUETOOTH_EIR_SECURITY_MANAGER_TK_VALUE = 0x10, BLUETOOTH_EIR_SECURITY_MANAGER_FLAGS = 0x11, BLUETOOTH_EIR_SLAVE_CONNECTION_INTERVAL_RANGE = 0x12,
  BLUETOOTH_EIR_SERVICE_SOLICITATION_16 = 0x14, BLUETOOTH_EIR_SERVICE_SOLICITATION_128 = 0x15, BLUETOOTH_EIR_SERVICE_DATA = 0x16, BLUETOOTH_EIR_APPEARANCE = 0x19,
  BLUETOOTH_EIR_BLE_DEVICE_ADDRESS = 0x1B, BLUETOOTH_EIR_BLE_ROLE = 0x1C, BLUETOOTH_EIR_MANUFACTURER_DATA = 0xFF
}
 

Enumerates the Extended Inquiry Responses, as defined in the Bluetooth v4.0 core specification.

More...
enum  Ndef_BLE_Address_Type_t { NDEF_BLE_PUBLIC_ADDRESS_TYPE = 0x0, NDEF_BLE_RANDOM_ADDRESS_TYPE = 0x1, NDEF_BLE_UNDEF_ADDRESS_TYPE = 0xff }
 

Enumerates the Bluetooth LE address types.

More...
enum  Ndef_BLE_Role_t {
  NDEF_BLE_ROLE_PERIPH_ONLY = 0x0, NDEF_BLE_ROLE_CENTRAL_ONLY = 0x1, NDEF_BLE_ROLE_PERIPH_PREFERRED = 0x2, NDEF_BLE_ROLE_CENTRAL_PREFERRED = 0x3,
  NDEF_BLE_ROLE_UNDEF = 0xff
}
 

Enumerates Bluetooth LE Roles.

More...
enum  Ndef_Bluetooth_type_t { NDEF_BLUETOOTH_BREDR, NDEF_BLUETOOTH_BLE }
 

Enumerates Bluetooth protocols.

More...

Functions

uint8_t * NDEF_BluetoothCopy (uint8_t *dst, uint8_t *src, uint32_t length)
 This function copies an array, changing its endianness, usefull to convert data to BLE endianess.
uint16_t NDEF_ReadBluetoothOOB (sRecordInfo_t *pRecord, Ndef_Bluetooth_OOB_t *pBluetooth)
 This function reads a NDEF record and retrieves Bluetooth (BR/EDR or BLE) OOB information if present.
uint16_t NDEF_AppendBluetoothOOB (Ndef_Bluetooth_OOB_t *pBluetooth, char *RecordID, I2C *mi2cChannel)
 This function appends a Bluetooth OOB record to the NDEF message, using the OOB data given in the input structure.
uint32_t NDEF_GetBluetoothOOBLength (Ndef_Bluetooth_OOB_t *pBluetooth)
 This function computeS the payload size for the OOB, using the data given in the input `Ndef_Bluetooth_OOB_t` structure.

Detailed Description

This module is used to manage a Bluetooth Out-Of-Band NDEF message, to start a communication based on Bluetooth.

The Bluetooth OOB format is described by the Bluetooth v4.0 core specification. It consists in a list of Extended Inquiry Responses formated as length-type-value. This module allows to build, write & read such data embedded in a NDEF message.

Bluetooth NDEF Library usage

How to write a Bluetooth Br/Edr OOB

1. Instanciate & initialize a `Ndef_Bluetooth_OOB_t` structure, specifying:

  • the `NDEF_BLUETOOTH_BREDR` type.
  • the mandatory Device Address field.
  • any other optional EIRs.

Ndef_Bluetooth_OOB_t w_bredr_oob = { .Type = NDEF_BLUETOOTH_BREDR, .DeviceAddress = {0x01, 0x02, 0x03, 0x04, 0x05, 0x06}, .OptionalMask = NDEF_BLUETOOTH_OPTION(BLUETOOTH_EIR_COMPLETE_LOCAL_NAME) | NDEF_BLUETOOTH_OPTION(BLUETOOTH_EIR_DEVICE_CLASS) | NDEF_BLUETOOTH_OPTION(BLUETOOTH_EIR_SERVICE_CLASS_UUID_COMPLETE_16), .LocalName = "MyDevice", .nbUUID16 = 2, .ClassUUID16 = {0x111E,0x110B}, .DeviceClass = {0x04,0x04,0x20} }; 2. Clear the NDEF message and call the `NDEF_AppendBluetoothOOB` function to write the OOB:

NDEF_ClearNDEF(); NDEF_AppendBluetoothOOB ( &w_bredr_oob, NULL );

Note:
Second parameter of `NDEF_AppendBluetoothOOB` can be used to specify an ID for the OOB record (useful for the NDEF Handover message, where specifying an ID is mandatory)

How to write a Bluetooth LE OOB

1. Instanciate & initialize a `Ndef_Bluetooth_OOB_t` structure, specifying:

  • the `NDEF_BLUETOOTH_BLE` type.
  • the mandatory Device Address & LE Role fields.
  • any other optional EIRs.

Ndef_Bluetooth_OOB_t w_ble_oob = { .Type = NDEF_BLUETOOTH_BLE, .DeviceAddress = {0x01, 0x02, 0x03, 0x04, 0x05, 0x06}, .DeviceAddressType = NDEF_BLE_PUBLIC_ADDRESS_TYPE, .Role = NDEF_BLE_ROLE_PERIPH_ONLY, .OptionalMask = NDEF_BLUETOOTH_OPTION(BLUETOOTH_EIR_COMPLETE_LOCAL_NAME), .LocalName = "MyDeviceName", };

2. Clear the NDEF message and call the `NDEF_AppendBluetoothOOB` function to write the OOB:

NDEF_ClearNDEF(); NDEF_AppendBluetoothOOB ( &w_ble_oob, NULL );

Note:
Second parameter of `NDEF_AppendBluetoothOOB` can be used to specify an ID for the OOB record (useful for the NDEF Handover message, where specifying an ID is mandatory)

How to read a Bluetooth OOB

1. Read the 1st record of the NDEF message:

sRecordInfo_t record; NDEF_ReadNDEF(NDEF_Buffer); NDEF_IdentifyBuffer(record,NDEF_Buffer); 2. Decode the Bluetooth OOB:

Ndef_Bluetooth_OOB_t bluetooth_oob; NDEF_ReadBluetoothOOB(&record,&bluetooth_oob); 3. Use the data from the `Ndef_Bluetooth_OOB_t` structure to start a Bluetooth connexion.


Enumeration Type Documentation

Enumerates the Bluetooth LE address types.

Enumerator:
NDEF_BLE_PUBLIC_ADDRESS_TYPE 

Public Device Address.

NDEF_BLE_RANDOM_ADDRESS_TYPE 

Random Device Address.

NDEF_BLE_UNDEF_ADDRESS_TYPE 

Device Address is undefined.

Definition at line 97 of file lib_NDEF_Bluetooth.h.

Enumerates Bluetooth LE Roles.

Enumerator:
NDEF_BLE_ROLE_PERIPH_ONLY 

Only Peripheral Role supported.

NDEF_BLE_ROLE_CENTRAL_ONLY 

Only Central Role supported.

NDEF_BLE_ROLE_PERIPH_PREFERRED 

Peripheral and Central Role supported, Peripheral Role preferred for connection establishment.

NDEF_BLE_ROLE_CENTRAL_PREFERRED 

Peripheral and Central Role supported, Central Role preferred for connection establishment.

NDEF_BLE_ROLE_UNDEF 

LE Role is undefined.

Definition at line 104 of file lib_NDEF_Bluetooth.h.

Enumerates the Extended Inquiry Responses, as defined in the Bluetooth v4.0 core specification.

Enumerator:
BLUETOOTH_EIR_FLAGS 

Bluetooth flags:
b0: LE limited Discoverable Mode,
b1: LE general Discoverable Mode,
b2: BR/EDR not supported,
b3: Simultaneous LE & BR/EDR Conroller,
b4: Simultaneous LE & BR/EDR Host.

BLUETOOTH_EIR_SERVICE_CLASS_UUID_PARTIAL_16 

Bluetooth service UUID on 16-bits (partial list)

BLUETOOTH_EIR_SERVICE_CLASS_UUID_COMPLETE_16 

Bluetooth service UUID on 16-bits (complete list)

BLUETOOTH_EIR_SERVICE_CLASS_UUID_PARTIAL_32 

Bluetooth service UUID on 32-bits (partial list)

BLUETOOTH_EIR_SERVICE_CLASS_UUID_COMPLETE_32 

Bluetooth service UUID on 32-bits (complete list)

BLUETOOTH_EIR_SERVICE_CLASS_UUID_PARTIAL_128 

Bluetooth service UUID on 128-bits (partial list)

BLUETOOTH_EIR_SERVICE_CLASS_UUID_COMPLETE_128 

Bluetooth service UUID on 128-bits (complete list)

BLUETOOTH_EIR_SHORT_LOCAL_NAME 

Shortened local name.

BLUETOOTH_EIR_COMPLETE_LOCAL_NAME 

Complete local name.

BLUETOOTH_EIR_TX_POWER_LEVEL 

TX Power Level (1 byte): 0xXX:-127 to +127dBm.

BLUETOOTH_EIR_DEVICE_CLASS 

Class of device, Format defined in Assigned Numbers.

BLUETOOTH_EIR_SIMPLE_PAIRING_HASH 

Simple Pairing Hash C (16 octets), Format defined in [Vol.

2], Part H Section 7.2.2

BLUETOOTH_EIR_SIMPLE_PAIRING_RANDOMIZER 

Simple Pairing Randomizer R (16 octets), Format defined in[Vol.

2], Part H Section 7.2.2

BLUETOOTH_EIR_SECURITY_MANAGER_TK_VALUE 

TK Value: Value as used in pairing over LE Physical channel.

Format defined in [Vol. 3], Part H Section 2.3

BLUETOOTH_EIR_SECURITY_MANAGER_FLAGS 

Flags (1 octet):
b0: OOB Flags Field (0 = OOB data not present, 1 = OOB data present),
b1: LE supported (Host) (i.e.

bit 65 of LMP Extended Feature bits Page 1),
b2: Simultaneous LE and BR/EDR to Same Device Capable (Host) (i.e. bit 66 of LMP Extended Feature bits Page 1)
b3: Address type (0 = Public Address, 1 = Random Address)

BLUETOOTH_EIR_SLAVE_CONNECTION_INTERVAL_RANGE 

Slave Connection Interval Range: The first 2 octets defines the minimum value for the connection interval, The second 2 octets defines the maximum value for the connection interval.

BLUETOOTH_EIR_SERVICE_SOLICITATION_16 

Service UUIDs: List of 16 bit Service UUIDs.

BLUETOOTH_EIR_SERVICE_SOLICITATION_128 

Service UUIDs: List of 128 bit Service UUID.

BLUETOOTH_EIR_SERVICE_DATA 

Service Data (2 or more octets): The first 2 octets contain the 16 bit Service UUID followed by additional service data.

BLUETOOTH_EIR_APPEARANCE 

UUID for `Appearance`: The Appearance characteristic value shall be the enumerated value as defined by Bluetooth Assigned Numbers document.

BLUETOOTH_EIR_BLE_DEVICE_ADDRESS 

6 LSB bytes: Device address, 7th byte: Address type (Public/Random)

BLUETOOTH_EIR_BLE_ROLE 

Device Role: Periph only, Central only, Periph prefered, Central prefered.

BLUETOOTH_EIR_MANUFACTURER_DATA 

Manufacturer Specific Data (2 or more octets): The first 2 octets contain the Company Identifier Code followed by additional manufacturer specific data.

Definition at line 49 of file lib_NDEF_Bluetooth.h.

Enumerates Bluetooth protocols.

Enumerator:
NDEF_BLUETOOTH_BREDR 

Standard bluetooth.

NDEF_BLUETOOTH_BLE 

Bluetooth Low Energy.

Definition at line 113 of file lib_NDEF_Bluetooth.h.


Function Documentation

uint16_t NDEF_AppendBluetoothOOB ( Ndef_Bluetooth_OOB_t pBluetooth,
char *  RecordID,
I2C *  mi2cChannel 
)

This function appends a Bluetooth OOB record to the NDEF message, using the OOB data given in the input structure.

Parameters:
pBluetoothPointer on a `Ndef_Bluetooth_OOB_t` structure containing the OOB information.
RecordIDID to be used for this record (required for Handover case, can be set to NULL in other cases).
Return values:
NDEF_OKThe Bluetooth OOB record has been appended.
NDEF_ERROR_MEMORY_INTERNALThe Bluetooth OOB record cannot be appended due to memory size limitation.
NDEF_ERRORThe Bluetooth OOB record cannot be appended.

Definition at line 284 of file lib_NDEF_Bluetooth.cpp.

uint8_t* NDEF_BluetoothCopy ( uint8_t *  dst,
uint8_t *  src,
uint32_t  length 
)

This function copies an array, changing its endianness, usefull to convert data to BLE endianess.

Parameters:
dstPointer on 1st element of the destination array.
srcpointer on 1st element of the source array .
lengthNumber of element to copy.
Returns:
Pointer to the destination array.

Definition at line 109 of file lib_NDEF_Bluetooth.cpp.

uint32_t NDEF_GetBluetoothOOBLength ( Ndef_Bluetooth_OOB_t pBluetooth )

This function computeS the payload size for the OOB, using the data given in the input `Ndef_Bluetooth_OOB_t` structure.

Parameters:
pBluetoothPointer on a `Ndef_Bluetooth_OOB_t` structure containing the OOB information.
Returns:
Computed length in bytes.

Definition at line 526 of file lib_NDEF_Bluetooth.cpp.

uint16_t NDEF_ReadBluetoothOOB ( sRecordInfo_t *  pRecord,
Ndef_Bluetooth_OOB_t pBluetooth 
)

This function reads a NDEF record and retrieves Bluetooth (BR/EDR or BLE) OOB information if present.

Parameters:
pRecordPointer on the record structure.
pBluetoothPointer on the structure to fill .
Return values:
NDEF_OKOOB information has been retrieved from the NDEF record.
NDEF_ERROROOB information cannot be retrieved.

Definition at line 126 of file lib_NDEF_Bluetooth.cpp.