| BlueNRG-1 Master/Central Library

- Main Page
- Classes
- Files

- File List
- File Members

Classes | Macros | Typedefs
master_basic_profile.h File Reference

Header file for BlueNRG-1 master/central library APIs. More...

`#include "sm.h"`

Go to the source code of this file.

## Classes

struct | initDevS
| Master initialization parameters. More...
struct | securitySetS
| Master security parameter settings. More...
struct | devDiscoveryS
| Device discovery parameters. More...
struct | connDevS
| Connection Device parameters. More...
struct | connUpdateParamS
| Connection Parameters received from peer peripheral device during an l2cap connection parameter update request. More...
struct | dataReceivedS
| Data received from the peer peripheral device during notification, indication and write request. More...
struct | dataPermitExchangeS
| Data received from the peer peripheral device when a write or a read request is received and the application has set the permit request event in the characteristic. More...

## Macros

#define | LIMITED_DISCOVERY_PROCEDURE 0x01
| Limited discovery procedure used during device discovery. Define used in Master_DeviceDiscovery() More...
#define | GENERAL_DISCOVERY_PROCEDURE 0x02
| General discovery procedure used during device discovery. Define used in Master_DeviceDiscovery() More...
#define | DEVICE_DISCOVERED 0x01
| Device found during the device discovery procedure Define used in Master_DeviceDiscovery_CB() More...
#define | DEVICE_DISCOVERY_PROCEDURE_ENDED 0x02
| Device discovery procedure ended from the application with function call Mater_TerminateDiscovery(). Define used in Master_DeviceDiscovery_CB(). More...
#define | DEVICE_DISCOVERY_PROCEDURE_TIMEOUT 0x03
| Device discovery procedure timeout. Define used in Master_DeviceDiscovery_CB() More...
#define | DIRECT_CONNECTION_PROCEDURE 0x03
| Direct connection establishment procedure used during device connection. procedure. Define used in Master_DeviceConnection() More...
#define | AUTO_CONNECTION_PROCEDURE 0x04
| Auto connection establishment procedure used during the device connection. Define used in Master_DeviceConnection() More...
#define | CONNECTION_ESTABLISHED_EVT 0x01
| Connection established event raised to signal the application that the connection procedure is ended with success. Define used in Master_Connection_CB() More...
#define | CONNECTION_FAILED_EVT 0x02
| Connection failed event raised to signal the application that the connection procedure is failed. Define used in Master_Connection_CB() More...
#define | DISCONNECTION_EVT 0x03
| Disconnection event. Define used in Master_Connection_CB() More...
#define | STOP_CONNECTION_PROCEDURE_EVT 0x04
| Stop connection procedure event is raised when there is an error during the switch between fast scan connection procedure and redeuce power connection procedure. Define used in Master_Connection_CB() More...
#define | CONNECTION_UPDATE_PARAMETER_REQUEST_EVT 0x05
| Connection update parameters event raised when the master basic profile receives the l2cap connection parameter request from the peer device. Define used in Master_Connection_CB() More...
#define | PRIMARY_SERVICE_DISCOVERY 0x01
| Primary Service Discovery procedure ended event. Define used in Master_ServiceCharacPeerDiscovery_CB() More...
#define | GET_CHARACTERISTICS_OF_A_SERVICE 0x02
| Get Characteristics of a Service procdure ended event. Define used in Master_ServiceCharacPeerDiscovery_CB() More...
#define | FIND_INCLUDED_SERVICES 0x03
| Find all included services procedure ended event. Define used in Master_ServiceCharacPeerDiscovery_CB() More...
#define | FIND_CHARAC_DESCRIPTORS 0x04
| Find all descriptors for a given characteristic procedure ended event. Define used in Master_ServiceCharacPeerDiscovery_CB() More...
#define | NOTIFICATION_INDICATION_CHANGE_STATUS 0x05
| This event signals the status of the Notification and Indication change characteristic configuration descriptor procedure executed from the application. Define used in Master_PeerDataExchange_CB() More...
#define | READ_VALUE_STATUS 0x06
| This event signals the status of the Read Characteristic value procedure executed from the application. Define used in Master_PeerDataExchange_CB() More...
#define | WRITE_VALUE_STATUS 0x07
| This event signals the status of the Write Characteristic value procedure executed from the application. Define used in Master_PeerDataExchange_CB() More...
#define | READ_LONG_VALUE_STATUS 0x08
| This event signals the status of Read Long Characteristic value procedure executed from the application. Define used in Master_PeerDataExchange_CB() More...
#define | NOTIFICATION_DATA_RECEIVED 0x09
| This event signals the Notification data received form the peer device. Define used in Master_PeerDataExchange_CB() More...
#define | INDICATION_DATA_RECEIVED 0x0A
| This event signals the Indication data received from the peer device. Define used in Master_PeerDataExchange_CB() More...
#define | ATTRIBUTE_MODIFICATION_RECEIVED 0x0B
| This event signals the Attribute modification from the peer device. Define used in Master_PeerDataExchange_CB() More...
#define | WRITE_PERMIT_REQUEST 0x0C
| This event is given to the application when a write request, write command or signed write command is received by the server from the client. This event will be given to the application only if the event bit for this event generation is set when the characteristic was added. When this event is received, the application has to check whether the value being requested for write is allowed to be written and respond with the command Master_WriteResponse(). Define used in Master_PeerDataPermitExchange_CB() More...
#define | READ_PERMIT_REQUEST 0x0D
| This event is given to the application when a read request or read blob request is received by the server from the client. This event will be given to the application only if the event bit for this event generation is set when the characteristic was added. On receiving this event, the application can update the value of the handle if it desires and when done it has to use the Master_AllowRead() command to indicate to the stack that it can send the response to the client. Define used in Master_PeerDataPermitExchange_CB() More...
#define | ERROR_INSUFFICIENT_AUTHENTICATION 0x05
| The insufficient authentication error code is received when the master wants read/write a peer device characteristic with authentication security enabled, and the pairing/bonding procedure is still not started. Define used in Master_Pairing_CB() More...
#define | ERROR_INSUFFICIENT_AUTHORIZATION 0x08
| The insufficient authorization error code is received when the master wants read/write a characteristic with authorization security enabled, and the pairing/bonding procedure is still not started Define used in Master_Pairing_CB() More...
#define | ERROR_INSUFFICIENT_ENCRYPTION 0x0F
| The insufficient encryption error code is received when the master wnats read/write a characteristic with encryption security enabled, and the pairing/bonding procedure is still not started. Define used in Master_Pairing_CB() More...
#define | PASS_KEY_REQUEST 0x10
| Pass key request event code is received when the pairing/bonding proceudre is started with the MITM option enabled. Define used in Master_Pairing_CB() More...

## Typedefs

typedef struct initDevS | initDevType
| Master initialization parameters. More...
typedef struct securitySetS | securitySetType
| Master security parameter settings. More...
typedef struct devDiscoveryS | devDiscoveryType
| Device discovery parameters. More...
typedef struct connDevS | connDevType
| Connection Device parameters. More...
typedef struct connUpdateParamS | connUpdateParamType
| Connection Parameters received from peer peripheral device during an l2cap connection parameter update request. More...
typedef struct dataReceivedS | dataReceivedType
| Data received from the peer peripheral device during notification, indication and write request. More...
typedef struct dataPermitExchangeS | dataPermitExchangeType
| Data received from the peer peripheral device when a write or a read request is received and the application has set the permit request event in the characteristic. More...

## Functions

Master Configuration Functions
uint8_t | Master_Init (initDevType *param)
| Initializes the Device in Master mode, sets the public address and the TX otuput power. More...
Master Device Discovery Functions
uint8_t | Master_DeviceDiscovery (devDiscoveryType *param)
| Starts the device discovery procedure. The procedure is terminated when either the upper layers issue a command to terminate the procedure (see Master_TerminateDiscovery() function call) or a timeout happens (timeout value is 10.24 sec). More...
uint8_t | Master_TerminateDiscovery (void)
| Forces the end of the GAP device discovery procedure. More...
void | Master_DeviceDiscovery_CB (uint8_t *status, uint8_t *addr_type, uint8_t *addr, uint8_t *data_length, uint8_t *data, uint8_t *RSSI)
| This callback returns the remote device's information discovered during the scan. More...
Master Device Connection Functions
uint8_t | Master_DeviceConnection (connDevType *param)
| Starts the connection procedure. More...
void | Master_Connection_CB (uint8_t *connection_evt, uint8_t *status, uint16_t *connection_handle, connUpdateParamType *param)
| This callback returns the connection procedure status. More...
uint8_t | Master_TerminateGAPConnectionProcedure (void)
| Terminates the GAP connection procedure ongoing. More...
uint8_t | Master_CloseConnection (uint16_t handle)
| Close the connection with the peer device connected. More...
uint8_t | Master_ConnectionUpdateParamResponse (uint16_t conn_handle, uint8_t accepted, connUpdateParamType *param)
| This function shall be called by the master when it receives a connection parameter update request from the peer device. If the master rejects these parameters can send the response with the accepted parameter set to FALSE or ignore the request. This function shall be managed only if the master has already discovered all the services and characteristics. If theese discovery procedure are ongoing, the master basic profile sends automatically the connection parameter response with status rejected. More...
Master Discovery Services & Characteristics Functions
uint8_t | Master_GetPrimaryServices (uint16_t conn_handle, uint8_t *numPrimaryService, uint8_t *primaryService, uint16_t size)
| Gets all primary service from the peer device. The primary service allocated on the connected peer device are availables when the Master_ServiceCharacPeerDiscovery_CB() is raised with the procedure value euqal to PRIMARY_SERVICE_DISCOVERY. More...
uint8_t | Master_GetCharacOfService (uint16_t conn_handle, uint16_t start_service_handle, uint16_t end_service_handle, uint8_t *numCharac, uint8_t *charac, uint16_t size)
| Gets all characteristics of a service from the peer device. The characteristics of a service allocated on the connected peer device are available when the Master_ServiceCharacPeerDiscovery_CB() is raised with the procedure value euqal to GET_CHARACTERISTICS_OF_A_SERVICE. More...
uint8_t | Master_GetIncludeServices (uint16_t conn_handle, uint16_t start_service_handle, uint16_t end_service_handle, uint8_t *numIncludedServices, uint8_t *includedServices, uint16_t size)
| Starts the procedure to find all the included sevices from the peer device. The included services are available when the Master_ServiceCharacPeerDiscovery_CB() is raised with the procedure value euqal to FIND_INCLUDED_SERVICES. More...
uint8_t | Master_GetCharacDescriptors (uint16_t conn_handle, uint16_t start_value_charac_handle, uint16_t end_charac_handle, uint8_t *numCharacDesc, uint8_t *characDesc, uint16_t size)
| Starts the procedure to find all the characteristic descirptors from the peer device. The characteristic descriptors are available when the Master_ServiceCharacPeerDiscovery_CB() is raised with the procedure value euqal to FIND_CHARAC_DESCRIPTORS. More...
void | Master_ServiceCharacPeerDiscovery_CB (uint8_t *procedure, uint8_t *status, uint16_t *connection_handle)
| This callback will be called at the end of the following procedure: More...
Master Data Exchange Functions
uint8_t | Master_NotifIndic_Status (uint16_t conn_handle, uint16_t config_desc_handle, uint8_t notification_enable, uint8_t indication_enable)
| This function sets the notification and indication status on the peer BLE device. More...
uint8_t | Master_Read_Value (uint16_t conn_handle, uint16_t attr_value_handle, uint16_t *data_length, uint8_t *data, uint16_t size)
| This function starts a read procedure on the peer BLE device. More...
uint8_t | Master_Read_Long_Value (uint16_t conn_handle, uint16_t attr_value_handle, uint16_t *data_length, uint8_t *data, uint8_t offset, uint16_t size)
| This function starts a read long procedure on the peer BLE device. More...
uint8_t | Master_Write_Value (uint16_t conn_handle, uint16_t attr_value_handle, uint8_t value_len, uint8_t *attr_value)
| This function starts a write procedure on the peer BLE device. More...
uint8_t | Master_WriteWithoutResponse_Value (uint16_t conn_handle, uint16_t attr_value_handle, uint8_t value_len, uint8_t *attr_value)
| This function executes a write without response on the peer BLE device. More...
uint8_t | Master_WriteResponse (uint16_t conn_handle, uint16_t attr_value_handle, uint8_t write_status, uint8_t err_code, uint8_t attr_value_len, uint8_t *attr_value)
| This function allows or rejects a write reqeust from the peer device. More...
uint8_t | Master_AllowRead (uint16_t conn_handle)
| This function allows the master to send a response to a read reqeust from the peer device. More...
void | Master_PeerDataExchange_CB (uint8_t *procedure, uint8_t *status, uint16_t *connection_handle, dataReceivedType *data)
| This callback will be called at the end of the following procedure: More...
void | Master_PeerDataPermitExchange_CB (uint8_t *procedure, uint16_t *connection_handle, dataPermitExchangeType *data)
| This callback will be called when a read or write operation procedure is required from the peer device and the application has set the permit request event in the characteristic. More...
Master Security Functions
uint8_t | Master_SecuritySet (securitySetType *param)
| Sets the security parameter on the master device. More...
uint8_t | Master_Start_Pairing_Procedure (uint16_t conn_handle, uint8_t force_rebond)
| This function starts the pairing and bonding procedure with the peer BLE device. More...
uint8_t | Master_Passkey_Response (uint16_t conn_handle, uint32_t key)
| This command should be sent by the Host in response to PASS_KEY_REQUEST received from the Master_Pairing_CB(). The command parameter contains the pass key which will be used during the pairing process. More...
uint8_t | Master_ClearSecurityDatabase (void)
| Clear the security database. More...
void | Master_Pairing_CB (uint16_t *conn_handle, uint8_t *status)
| This callback returns the pairing procedure status. More...
Master Common Services Functions
uint32_t | Master_Process (void)
| This function needs to be called inside a main loop to run the Master state machines. More...
uint8_t | Master_SetTxPower (uint8_t level)
| Sets the TX output power level used during the communication Default value is -2.1 dBm. More...
uint8_t | Master_HostExitTimeoutPowerSave (void)
| This function signals at the master that the host micro exits from a power save with timeout as advised from the master basic profile. More...

## Detailed Description

Header file for BlueNRG-1 master/central library APIs.

Author
  AMG - RF Application team

Version
  V1.1.0

Date
  04-November-2016

Attention

THE PRESENT FIRMWARE WHICH IS FOR GUIDANCE ONLY AIMS AT PROVIDING CUSTOMERS WITH CODING INFORMATION REGARDING THEIR PRODUCTS IN ORDER FOR THEM TO SAVE TIME. AS A RESULT, STMICROELECTRONICS SHALL NOT BE HELD LIABLE FOR ANY DIRECT, INDIRECT OR CONSEQUENTIAL DAMAGES WITH RESPECT TO ANY CLAIMS ARISING FROM THE CONTENT OF SUCH FIRMWARE AND/OR THE USE MADE BY CUSTOMERS OF THE CODING INFORMATION CONTAINED HEREIN IN CONNECTION WITH THEIR PRODUCTS.

##
© COPYRIGHT 2016 STMicroelectronics

Definition in file master_basic_profile.h.

## Macro Definition Documentation

#define ATTRIBUTE_MODIFICATION_RECEIVED 0x0B

This event signals the Attribute modification from the peer device. Define used in Master_PeerDataExchange_CB()

Definition at line 197 of file master_basic_profile.h.

#define AUTO_CONNECTION_PROCEDURE 0x04

Auto connection establishment procedure used during the device connection. Define used in Master_DeviceConnection()

Definition at line 76 of file master_basic_profile.h.

#define CONNECTION_ESTABLISHED_EVT 0x01

Connection established event raised to signal the application that the connection procedure is ended with success. Define used in Master_Connection_CB()

Definition at line 84 of file master_basic_profile.h.

#define CONNECTION_FAILED_EVT 0x02

Connection failed event raised to signal the application that the connection procedure is failed. Define used in Master_Connection_CB()

Definition at line 92 of file master_basic_profile.h.

#define CONNECTION_UPDATE_PARAMETER_REQUEST_EVT 0x05

Connection update parameters event raised when the master basic profile receives the l2cap connection parameter request from the peer device. Define used in Master_Connection_CB()

Definition at line 114 of file master_basic_profile.h.

#define DEVICE_DISCOVERED 0x01

Device found during the device discovery procedure Define used in Master_DeviceDiscovery_CB()

Definition at line 48 of file master_basic_profile.h.

#define DEVICE_DISCOVERY_PROCEDURE_ENDED 0x02

Device discovery procedure ended from the application with function call Mater_TerminateDiscovery(). Define used in Master_DeviceDiscovery_CB().

Definition at line 55 of file master_basic_profile.h.

#define DEVICE_DISCOVERY_PROCEDURE_TIMEOUT 0x03

Device discovery procedure timeout. Define used in Master_DeviceDiscovery_CB()

Definition at line 61 of file master_basic_profile.h.

#define DIRECT_CONNECTION_PROCEDURE 0x03

Direct connection establishment procedure used during device connection. procedure. Define used in Master_DeviceConnection()

Definition at line 69 of file master_basic_profile.h.

#define DISCONNECTION_EVT 0x03

Disconnection event. Define used in Master_Connection_CB()

Definition at line 98 of file master_basic_profile.h.

#define ERROR_INSUFFICIENT_AUTHENTICATION 0x05

The insufficient authentication error code is received when the master wants read/write a peer device characteristic with authentication security enabled, and the pairing/bonding procedure is still not started. Define used in Master_Pairing_CB()

Definition at line 228 of file master_basic_profile.h.

#define ERROR_INSUFFICIENT_AUTHORIZATION 0x08

The insufficient authorization error code is received when the master wants read/write a characteristic with authorization security enabled, and the pairing/bonding procedure is still not started Define used in Master_Pairing_CB()

Definition at line 237 of file master_basic_profile.h.

#define ERROR_INSUFFICIENT_ENCRYPTION 0x0F

The insufficient encryption error code is received when the master wnats read/write a characteristic with encryption security enabled, and the pairing/bonding procedure is still not started. Define used in Master_Pairing_CB()

Definition at line 246 of file master_basic_profile.h.

#define FIND_CHARAC_DESCRIPTORS 0x04

Find all descriptors for a given characteristic procedure ended event. Define used in Master_ServiceCharacPeerDiscovery_CB()

Definition at line 142 of file master_basic_profile.h.

#define FIND_INCLUDED_SERVICES 0x03

Find all included services procedure ended event. Define used in Master_ServiceCharacPeerDiscovery_CB()

Definition at line 135 of file master_basic_profile.h.

#define GENERAL_DISCOVERY_PROCEDURE 0x02

General discovery procedure used during device discovery. Define used in Master_DeviceDiscovery()

Definition at line 42 of file master_basic_profile.h.

#define GET_CHARACTERISTICS_OF_A_SERVICE 0x02

Get Characteristics of a Service procdure ended event. Define used in Master_ServiceCharacPeerDiscovery_CB()

Definition at line 129 of file master_basic_profile.h.

#define INDICATION_DATA_RECEIVED 0x0A

This event signals the Indication data received from the peer device. Define used in Master_PeerDataExchange_CB()

Definition at line 190 of file master_basic_profile.h.

#define LIMITED_DISCOVERY_PROCEDURE 0x01

Limited discovery procedure used during device discovery. Define used in Master_DeviceDiscovery()

Definition at line 36 of file master_basic_profile.h.

#define NOTIFICATION_DATA_RECEIVED 0x09

This event signals the Notification data received form the peer device. Define used in Master_PeerDataExchange_CB()

Definition at line 183 of file master_basic_profile.h.

#define NOTIFICATION_INDICATION_CHANGE_STATUS 0x05

This event signals the status of the Notification and Indication change characteristic configuration descriptor procedure executed from the application. Define used in Master_PeerDataExchange_CB()

Definition at line 152 of file master_basic_profile.h.

#define PASS_KEY_REQUEST 0x10

Pass key request event code is received when the pairing/bonding proceudre is started with the MITM option enabled. Define used in Master_Pairing_CB()

Definition at line 256 of file master_basic_profile.h.

#define PRIMARY_SERVICE_DISCOVERY 0x01

Primary Service Discovery procedure ended event. Define used in Master_ServiceCharacPeerDiscovery_CB()

Definition at line 122 of file master_basic_profile.h.

#define READ_LONG_VALUE_STATUS 0x08

This event signals the status of Read Long Characteristic value procedure executed from the application. Define used in Master_PeerDataExchange_CB()

Definition at line 176 of file master_basic_profile.h.

#define READ_PERMIT_REQUEST 0x0D

This event is given to the application when a read request or read blob request is received by the server from the client. This event will be given to the application only if the event bit for this event generation is set when the characteristic was added. On receiving this event, the application can update the value of the handle if it desires and when done it has to use the Master_AllowRead() command to indicate to the stack that it can send the response to the client. Define used in Master_PeerDataPermitExchange_CB()

Definition at line 217 of file master_basic_profile.h.

#define READ_VALUE_STATUS 0x06

This event signals the status of the Read Characteristic value procedure executed from the application. Define used in Master_PeerDataExchange_CB()

Definition at line 160 of file master_basic_profile.h.

#define STOP_CONNECTION_PROCEDURE_EVT 0x04

Stop connection procedure event is raised when there is an error during the switch between fast scan connection procedure and redeuce power connection procedure. Define used in Master_Connection_CB()

Definition at line 106 of file master_basic_profile.h.

#define WRITE_PERMIT_REQUEST 0x0C

This event is given to the application when a write request, write command or signed write command is received by the server from the client. This event will be given to the application only if the event bit for this event generation is set when the characteristic was added. When this event is received, the application has to check whether the value being requested for write is allowed to be written and respond with the command Master_WriteResponse(). Define used in Master_PeerDataPermitExchange_CB()

Definition at line 207 of file master_basic_profile.h.

#define WRITE_VALUE_STATUS 0x07

This event signals the status of the Write Characteristic value procedure executed from the application. Define used in Master_PeerDataExchange_CB()

Definition at line 168 of file master_basic_profile.h.

## Typedef Documentation

typedef struct connDevS connDevType

Connection Device parameters.

typedef struct connUpdateParamS connUpdateParamType

Connection Parameters received from peer peripheral device during an l2cap connection parameter update request.

typedef struct dataPermitExchangeS dataPermitExchangeType

Data received from the peer peripheral device when a write or a read request is received and the application has set the permit request event in the characteristic.

typedef struct dataReceivedS dataReceivedType

Data received from the peer peripheral device during notification, indication and write request.

typedef struct devDiscoveryS devDiscoveryType

Device discovery parameters.

typedef struct initDevS initDevType

Master initialization parameters.

typedef struct securitySetS securitySetType

Master security parameter settings.

## Function Documentation

uint8_t Master_AllowRead | ( | uint16_t | conn_handle | ) |

This function allows the master to send a response to a read reqeust from the peer device.

Parameters

  conn_handle | Conenction handle

Return values

  Status | of call

Note
  This function must be called inside the Master_PeerDataPermitExchange_CB() callback

uint8_t Master_ClearSecurityDatabase | ( | void |  | ) |

Clear the security database.

Note
  All the devices in the security database will be removed.

Return values

  Status | of call

uint8_t Master_CloseConnection | ( | uint16_t | handle | ) |

Close the connection with the peer device connected.

Parameters

  handle | Connection handle to close

Return values

  Status | of the call

void Master_Connection_CB | ( | uint8_t * | connection_evt,
|  | uint8_t * | status,
|  | uint16_t * | connection_handle,
|  | connUpdateParamType * | param
| ) |  |

This callback returns the connection procedure status.

Parameters

  connection_evt | Connection event. Possible values are:
  - CONNECTION_ESTABLISHED_EVT
  - CONNECTION_FAILED_EVT
  - DISCONNECTION_EVT
  - STOP_CONNECTION_PROCEDURE_EVT
  - CONNECTION_UPDATE_PARAMETER_REQUEST_EVT
  status | Connection status.
  connection_handle | Connection handle
  param | Connection parameters suggested from the slave, used ONLY when the CONNECTION_UPDATE_PARAMETER_REQUEST_EVT is raised.

Return values

  None |

uint8_t Master_ConnectionUpdateParamResponse | ( | uint16_t | conn_handle,
|  | uint8_t | accepted,
|  | connUpdateParamType * | param
| ) |  |

This function shall be called by the master when it receives a connection parameter update request from the peer device. If the master rejects these parameters can send the response with the accepted parameter set to FALSE or ignore the request. This function shall be managed only if the master has already discovered all the services and characteristics. If theese discovery procedure are ongoing, the master basic profile sends automatically the connection parameter response with status rejected.

Parameters

  conn_handle | Connection handle
  accepted | TRUE if the peripheral peer request is accepted, FALSE otherwise.
  param | Connection parameter to update

Return values

  Status | of the call.

uint8_t Master_DeviceConnection | ( | connDevType * | param | ) |

Starts the connection procedure.

Parameters

  param | Connection Device parameters (see connDevType structure)

Return values

  Status | of the call.

uint8_t Master_DeviceDiscovery | ( | devDiscoveryType * | param | ) |

Starts the device discovery procedure. The procedure is terminated when either the upper layers issue a command to terminate the procedure (see Master_TerminateDiscovery() function call) or a timeout happens (timeout value is 10.24 sec).

Parameters

  param | Device discovery parameters (see devDiscoveryType structure)

Return values

  Status | of the call.

void Master_DeviceDiscovery_CB | ( | uint8_t * | status,
|  | uint8_t * | addr_type,
|  | uint8_t * | addr,
|  | uint8_t * | data_length,
|  | uint8_t * | data,
|  | uint8_t * | RSSI
| ) |  |

This callback returns the remote device's information discovered during the scan.

Parameters

  status | of the device discovery callback. Valid values are:
  - DEVICE_DISCOVERED
  - DEVICE_DISCOVERY_PROCEDURE_ENDED
  - DEVICE_DISCOVERY_PROCEDURE_TIMEOUT
  addr_type | Address Type, possible values are:
  - 0 = Public Device Address
  - 1 = Random Device Address
  addr | Remote device address
  data_length | Lenght of advertising or scan response data.
  data | Advertising or scan response data
  RSSI | RSSI (signed integer).

Return values

  None |

uint8_t Master_GetCharacDescriptors | ( | uint16_t | conn_handle,
|  | uint16_t | start_value_charac_handle,
|  | uint16_t | end_charac_handle,
|  | uint8_t * | numCharacDesc,
|  | uint8_t * | characDesc,
|  | uint16_t | size
| ) |  |

Starts the procedure to find all the characteristic descirptors from the peer device. The characteristic descriptors are available when the Master_ServiceCharacPeerDiscovery_CB() is raised with the procedure value euqal to FIND_CHARAC_DESCRIPTORS.

Parameters

  conn_handle | Connection handle
  start_value_charac_handle | Value Handle of a given characteristic
  end_charac_handle | End Handle of a given characteristic
  numCharacDesc | Number of descriptors found in a given characterisric When the Master_ServiceCharacPeerDiscovery_CB() will be received, the content of this parameter will be available.
  characDesc | Array with the descriptors associated to a given characteritstic. The array will be a sequence of elements with the following format:
  - 1 byte Format handle data (1 = lists with 16 bit UUID, 2 = lists with 128 bit UUID)
  - 2 bytes Characteristic descriptor Handle
  - n bytes (2 or 16) UUID according the format field When the Master_ServiceCharacPeerDiscovery_CB() will be received, the content of this parameter will be available.
  size | Max size of the charac descriptor array. If the information read from the peer device exceeds this size a BLE_STATUS_INSUFFICIENT_RESOURCES error is returned

Return values

  Status | of call

uint8_t Master_GetCharacOfService | ( | uint16_t | conn_handle,
|  | uint16_t | start_service_handle,
|  | uint16_t | end_service_handle,
|  | uint8_t * | numCharac,
|  | uint8_t * | charac,
|  | uint16_t | size
| ) |  |

Gets all characteristics of a service from the peer device. The characteristics of a service allocated on the connected peer device are available when the Master_ServiceCharacPeerDiscovery_CB() is raised with the procedure value euqal to GET_CHARACTERISTICS_OF_A_SERVICE.

Parameters

  conn_handle | Connection handle
  start_service_handle | Start Handle of a given service
  end_service_handle | End Handle of a given service
  numCharac | Number of characteristics allocated for a given service When the Master_ServiceCharacPeerDiscovery_CB() will be received, the content of this parameter will be available.
  charac | Array with the characterisitcs information. The array will be a sequence of elements with the following format:
  - 1 byte UUID Type (1 = 16 bit, 2 = 128 bit)
  - 2 bytes Characteristic Handle
  - 1 bytes Characteristic Properties
  - 2 bytes Characteristic Value Handle
  - n bytes (2 or 16) Characteristics UUID When the Master_ServiceCharacPeerDiscovery_CB() will be received, the content of this parameter will be available.
  size | Max size of the charac array. If the information read from the peer device exceeds this size a BLE_STATUS_INSUFFICIENT_RESOURCES error is returned

Return values

  Status | of call

uint8_t Master_GetIncludeServices | ( | uint16_t | conn_handle,
|  | uint16_t | start_service_handle,
|  | uint16_t | end_service_handle,
|  | uint8_t * | numIncludedServices,
|  | uint8_t * | includedServices,
|  | uint16_t | size
| ) |  |

Starts the procedure to find all the included sevices from the peer device. The included services are available when the Master_ServiceCharacPeerDiscovery_CB() is raised with the procedure value euqal to FIND_INCLUDED_SERVICES.

Parameters

  conn_handle | Connection handle
  start_service_handle | Start Handle of a given service
  end_service_handle | End Handle of a given service
  numIncludedServices | Number of included services found in a given service When the Master_ServiceCharacPeerDiscovery_CB() will be received, the content of this parameter will be available.
  includedServices | Array with the included services information. The array will be a sequence of elements with the following format:
  - 1 byte size of the information (6 or 8)
  - 2 bytes Characteristic Handle
  - 2 bytes Start Included Handle
  - 2 bytes End Included Handle
  - 2 bytes UUID only if it is a 16-bit Bluetooth UUID When the Master_ServiceCharacPeerDiscovery_CB() will be received, the content of this parameter will be available.
  size | Max size of the included services array. If the information read from the peer device exceeds this size a BLE_STATUS_INSUFFICIENT_RESOURCES error is returned

Return values

  Status | of call

uint8_t Master_GetPrimaryServices | ( | uint16_t | conn_handle,
|  | uint8_t * | numPrimaryService,
|  | uint8_t * | primaryService,
|  | uint16_t | size
| ) |  |

Gets all primary service from the peer device. The primary service allocated on the connected peer device are availables when the Master_ServiceCharacPeerDiscovery_CB() is raised with the procedure value euqal to PRIMARY_SERVICE_DISCOVERY.

Parameters

  conn_handle | Connection handle
  numPrimaryService | Number of services allocated on the connected peer device. When the Master_ServiceCharacPeerDiscovery_CB() will be received, the content of this parameter will be available.
  primaryService | Array with the primary service information. The array will be a sequence of elements with the following format:
  - 1 byte UUID Type (1 = 16 bit, 2 = 128 bit)
  - 2 bytes Service Start Handle
  - 2 bytes Service End Handle
  - n bytes (2 or 16) Service UUID When the Master_ServiceCharacPeerDiscovery_CB() will be received, the content of this parameter will be available.
  size | Max size of the primaryService array. If the information read from the peer device exceeds this size a BLE_STATUS_INSUFFICIENT_RESOURCES error is returned.

Return values

  Status | of call

uint8_t Master_HostExitTimeoutPowerSave | ( | void |  | ) |

This function signals at the master that the host micro exits from a power save with timeout as advised from the master basic profile.

Return values

  Status | of the call

uint8_t Master_Init | ( | initDevType * | param | ) |

Initializes the Device in Master mode, sets the public address and the TX otuput power.

Parameters

  param | Master initialization parameters (see initDevType structure)

Return values

  Status | of the call.

uint8_t Master_NotifIndic_Status | ( | uint16_t | conn_handle,
|  | uint16_t | config_desc_handle,
|  | uint8_t | notification_enable,
|  | uint8_t | indication_enable
| ) |  |

This function sets the notification and indication status on the peer BLE device.

Parameters

  conn_handle | Connction handle
  config_desc_handle | Configuration descriptor handle
  notification_enable | TRUE if the client enables the server notification. FALSE otherwise
  indication_enable | TRUE if the client enables the server indication. FALSE otherwise

Note
  The Master_PeerDataExchange_CB() function is called with the status of the Master_NotifIndic_Status() commands. The procedure parameter in the Master_PeerDataExchange_CB() will be set to NOTIFICATION_INDICATION_CHANGE_STATUS

Return values

  Status | of call

void Master_Pairing_CB | ( | uint16_t * | conn_handle,
|  | uint8_t * | status
| ) |  |

This callback returns the pairing procedure status.

Parameters

  conn_handle | Connection handle
  status | Status of the pairing request. Possible values are:
  - ERROR_INSUFFICIENT_AUTHENTICATION
  - ERROR_INSUFFICIENT_AUTHORIZATION
  - ERROR_INSUFFICIENT_ENCRYPTION
  - BLE_STATUS_SUCCESS
  - PASS_KEY_REQUEST

Return values

  None |

Note
  When this callback returns an ERROR value, means that the master is not paired and bonded to the peer device and the application tries to executes an operation that requires pairing and bonding. When a procedure raises an ERROR status, the application needs to start the pairing procedure and at the end needs to repeat the procedure that has generated the error. In case of PASS_KEY_REQUEST status you need to call inside the Master_Pairing_CB() the function Master_PassKey_Response()

uint8_t Master_Passkey_Response | ( | uint16_t | conn_handle,
|  | uint32_t | key
| ) |  |

This command should be sent by the Host in response to PASS_KEY_REQUEST received from the Master_Pairing_CB(). The command parameter contains the pass key which will be used during the pairing process.

Parameters

  conn_handle | Connection handle
  key | Pass key, value range: 0 – 999999 (decimal)

Return values

  Status | of call

void Master_PeerDataExchange_CB | ( | uint8_t * | procedure,
|  | uint8_t * | status,
|  | uint16_t * | connection_handle,
|  | dataReceivedType * | data
| ) |  |

This callback will be called at the end of the following procedure:

- NOTIFICATION_INDICATION_CHANGE_STATUS
- READ_VALUE_STATUS
- READ_LONG_VALUE_STATUS
- WRITE_VALUE_STATUS
- NOTIFICATION_DATA_RECEIVED
- INDICATION_DATA_RECEIVED
- ATTRIBUTE_MODIFICATION_RECEIVED
  Parameters

    procedure | Master procedure ended.
    status | Status of the procedure
    connection_handle | Connection handle
    data | Data received type. This param is used ONLY when the master receives notifications, indications and attribute modifications.

  Note
    For the READ_VALUE_STATUS and READ_LONG_VALUE_STATUS procedures, the characteristic value will be returned on the variables used during the procedure call.

void Master_PeerDataPermitExchange_CB | ( | uint8_t * | procedure,
|  | uint16_t * | connection_handle,
|  | dataPermitExchangeType * | data
| ) |  |

This callback will be called when a read or write operation procedure is required from the peer device and the application has set the permit request event in the characteristic.

Parameters

  procedure | Master procedure to serve:
  - READ_PERMIT_REQUEST
  - WRITE_PERMIT_REQUEST
  connection_handle | Connection handle
  data | Characteristic information to allow the read or write operation. (see dataPermitExchangeType) and attribute modifications.

uint32_t Master_Process | ( | void |  | ) |

This function needs to be called inside a main loop to run the Master state machines.

Return values

  The | return value is a bitmask to signal the application if the Host micro can enter in power save or not. The bitmask format is:
  - 1 bit flag to signal if the micro can enter in power save or not. This is the LSB.
  - 1 bit flag to signal if the micro needs to enable the power save with a timeout.
  - 30 bits power save timeout, the latest MSB. These 30 bits are valid if the second bit is set. At the end of the timeout, the application shall call the function Master_HostExitTimeoutPowerSave() to signal the master basic profile that the host micro has applied the power save with timeout as suggested from the basic profile.

uint8_t Master_Read_Long_Value | ( | uint16_t | conn_handle,
|  | uint16_t | attr_value_handle,
|  | uint16_t * | data_length,
|  | uint8_t * | data,
|  | uint8_t | offset,
|  | uint16_t | size
| ) |  |

This function starts a read long procedure on the peer BLE device.

Parameters

  conn_handle | Connction handle
  attr_value_handle | Attribute value handle of the characteristic to read
  data_length | Length of data received When the Master_PeerDataExchange_CB() will be received, the content of this parameter will be available.
  data | Data read from the peer device When the Master_PeerDataExchange_CB() will be received, the content of this parameter will be available.
  offset | Offset from which the value needs to be read
  size | Max size of the data array. If the information read from the peer device exceeds this size a BLE_STATUS_INSUFFICIENT_RESOURCES error is returned

Note
  The Master_PeerDataExchange_CB() function is called with the status of the read commands. The procedure parameter in the Master_PeerDataExchange_CB() will be set to READ_LONG_VALUE_STATUS

Return values

  Status | of call

uint8_t Master_Read_Value | ( | uint16_t | conn_handle,
|  | uint16_t | attr_value_handle,
|  | uint16_t * | data_length,
|  | uint8_t * | data,
|  | uint16_t | size
| ) |  |

This function starts a read procedure on the peer BLE device.

Parameters

  conn_handle | Connction handle
  attr_value_handle | Attribute value handle of the characteristic to read
  data_length | Length of data received When the Master_PeerDataExchange_CB() will be received, the content of this parameter will be available.
  data | Data read from the peer device When the Master_PeerDataExchange_CB() will be received, the content of this parameter will be available.
  size | Max size of the data array. If the information read from the peer device exceeds this size a BLE_STATUS_INSUFFICIENT_RESOURCES error is returned

Note
  The Master_PeerDataExchange_CB() function is called with the status of the read commands. The procedure parameter in the Master_PeerDataExchange_CB() will be set to READ_VALUE_STATUS

Return values

  Status | of call

uint8_t Master_SecuritySet | ( | securitySetType * | param | ) |

Sets the security parameter on the master device.

Parameters

  param | Master security settings (see securitySetType strucure)

Return values

  Status | of call.

void Master_ServiceCharacPeerDiscovery_CB | ( | uint8_t * | procedure,
|  | uint8_t * | status,
|  | uint16_t * | connection_handle
| ) |  |

This callback will be called at the end of the following procedure:

- PRIMARY_SERVICE_DISCOVERY
- GET_CHARACTERISTICS_OF_A_SERVICE
- FIND_INCLUDED_SERVICES
- FIND_CHARAC_DESCRIPTORS
  Parameters

    procedure | Master procedure ended
    status | Status of the procedure
    connection_handle | Connection handle

  Note
    All the information about the primary service, characteristics, included services.... will be returned on the variables used to start the procedure.

uint8_t Master_SetTxPower | ( | uint8_t | level | ) |

Sets the TX output power level used during the communication Default value is -2.1 dBm.

Parameters

  level | Power Level, valid range is [0 - 7]. The following table determines the output power level (dBm):
  - 0 = -15
  - 1 = -11.7
  - 2 = -8.4
  - 3 = -5.1
  - 4 = -2.1
  - 5 = 1.4
  - 6 = 4.7
  - 7 = 8.0

Return values

  Status | of the call

uint8_t Master_Start_Pairing_Procedure | ( | uint16_t | conn_handle,
|  | uint8_t | force_rebond
| ) |  |

This function starts the pairing and bonding procedure with the peer BLE device.

Parameters

  conn_handle | Connction handle
  force_rebond | TRUE if the master device wants force the rebond.

Note
  The Master_Pairing_CB() function is called with the status of the pairing procedure.

Return values

  Status | of call

uint8_t Master_TerminateDiscovery | ( | void |  | ) |

Forces the end of the GAP device discovery procedure.

Return values

  Status | of the call.

uint8_t Master_TerminateGAPConnectionProcedure | ( | void |  | ) |

Terminates the GAP connection procedure ongoing.

Return values

  Status | of the call

Note
  This function call ends only the GAP connection procedure ongoing, at this step the central is not still connected. If the central is connected, to close the connection call Master_CloseConnection()

uint8_t Master_Write_Value | ( | uint16_t | conn_handle,
|  | uint16_t | attr_value_handle,
|  | uint8_t | value_len,
|  | uint8_t * | attr_value
| ) |  |

This function starts a write procedure on the peer BLE device.

Parameters

  conn_handle | Connction handle
  attr_value_handle | Attribute handle of the characteristic value to write
  value_len | Length of the data to write
  attr_value | Data to write

Note
  The Master_PeerDataExchange_CB() function is called with the status of the write procedure. The procedure parameter in the Master_PeerDataExchange_CB() will be set to WRITE_VALUE_STATUS

Return values

  Status | of call

uint8_t Master_WriteResponse | ( | uint16_t | conn_handle,
|  | uint16_t | attr_value_handle,
|  | uint8_t | write_status,
|  | uint8_t | err_code,
|  | uint8_t | attr_value_len,
|  | uint8_t * | attr_value
| ) |  |

This function allows or rejects a write reqeust from the peer device.

Parameters

  conn_handle | Conenction handle
  attr_value_handle | Handle of the attribute to write
  write_status | 0x00: The value can be written to the attribute specified by attr_handle 0x01: The value cannot be written to the attribute specified by the attr_handle.
  err_code | The error code that has to be passed to the peer device in case the write has to be rejected.
  attr_value_len | Length of the value to be written
  attr_value | Value to be written

Return values

  Status | of call

Note
  This function must be called inside the Master_PeerDataPermitExchange_CB() callback

uint8_t Master_WriteWithoutResponse_Value | ( | uint16_t | conn_handle,
|  | uint16_t | attr_value_handle,
|  | uint8_t | value_len,
|  | uint8_t * | attr_value
| ) |  |

This function executes a write without response on the peer BLE device.

Parameters

  conn_handle | Connction handle
  attr_value_handle | Attribute handle of the characteristic value to write
  value_len | Length of the data to write
  attr_value | Data to write

Note
  This function doesn't have a response from the peer device, so the Master_PeerDataExchange_CB() function is not called

Return values

  Status | of call