Microchip® Advanced Software Framework

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
GATT Client APIs

This group includes all GATT Client APIs; Discover, Read, Write, ...

Functions

at_ble_status_t at_ble_characteristic_discover_all (at_ble_handle_t conn_handle, at_ble_handle_t start_handle, at_ble_handle_t end_handle)
 Discover all Characteristics declared in a connected device. More...
 
at_ble_status_t at_ble_characteristic_discover_by_uuid (at_ble_handle_t conn_handle, at_ble_handle_t start_handle, at_ble_handle_t end_handle, at_ble_uuid_t *uuid)
 Discover all Characteristics of a given UUID declared in a connected device. More...
 
at_ble_status_t at_ble_characteristic_read (at_ble_handle_t conn_handle, at_ble_handle_t char_handle, uint16_t offset, uint16_t length)
 Read a characteristic given its handle. More...
 
at_ble_status_t at_ble_characteristic_read_by_uuid (at_ble_handle_t conn_handle, at_ble_handle_t start_handle, at_ble_handle_t end_handle, at_ble_uuid_t *uuid)
 Read a characteristic given its UUID. More...
 
at_ble_status_t at_ble_characteristic_read_long (at_ble_handle_t conn_handle, at_ble_handle_t char_handle, uint16_t offset, uint16_t length)
 Long read a characteristic given its handle. More...
 
at_ble_status_t at_ble_characteristic_read_multiple (at_ble_handle_t conn_handle, at_ble_char_list *char_handle_list, uint8_t char_handle_count)
 Read a list of characteristics given their handles. More...
 
at_ble_status_t at_ble_characteristic_reliable_write_cancel (at_ble_handle_t conn_handle)
 Cancels a pending prepared reliable write operation. More...
 
at_ble_status_t at_ble_characteristic_reliable_write_execute (at_ble_handle_t conn_handle)
 Executes a pending prepared write operation. More...
 
at_ble_status_t at_ble_characteristic_reliable_write_prepare (at_ble_handle_t conn_handle, at_ble_handle_t char_handle, uint16_t offset, uint16_t length, uint8_t *data)
 add a new prepared write request More...
 
at_ble_status_t at_ble_characteristic_write (at_ble_handle_t conn_handle, at_ble_handle_t char_handle, uint16_t offset, uint16_t length, uint8_t *data, bool signed_write, bool with_response)
 Write a characteristic value in peer device and write completion will be reported via AT_BLE_CHARACTERISTIC_WRITE_CMD_CMP event after firmware handling. More...
 
at_ble_status_t at_ble_descriptor_discover_all (at_ble_handle_t conn_handle, at_ble_handle_t start_handle, at_ble_handle_t end_handle)
 Discover all Descriptors declared in a connected device. More...
 
at_ble_status_t at_ble_exchange_mtu (at_ble_handle_t conn_handle)
 send the MTU exchange command to peer device More...
 
at_ble_status_t at_ble_included_service_discover_all (at_ble_handle_t conn_handle, at_ble_handle_t start_handle, at_ble_handle_t end_handle)
 Discover all included services declared in a connected device. More...
 
at_ble_status_t at_ble_primary_service_discover_all (at_ble_handle_t conn_handle, at_ble_handle_t start_handle, at_ble_handle_t end_handle)
 Discover all Primary services in a peer device. More...
 
at_ble_status_t at_ble_primary_service_discover_by_uuid (at_ble_handle_t conn_handle, at_ble_handle_t start_handle, at_ble_handle_t end_handle, at_ble_uuid_t *uuid)
 Discover Primary service of a given UUID declared and located in a peer device. More...
 

at_ble_status_t at_ble_characteristic_discover_all ( at_ble_handle_t  conn_handle,
at_ble_handle_t  start_handle,
at_ble_handle_t  end_handle 
)

Discover all Characteristics declared in a connected device.

Search will go from start_handle to end_handle, whenever a characteristic is found AT_BLE_CHARACTERISTIC_FOUND event is sent and AT_BLE_DISCOVERY_COMPLETE is sent at end of discover operation.

Parameters
[in]conn_handlehandle of the connection
[in]start_handlestart of the searched range
[in]end_handleend of the searched range
Returns
Upon successful completion the function shall return AT_BLE_ATT_ATTRIBUTE_NOT_FOUND, Otherwise the function shall return at_ble_status_t

Search will go from start_handle to end_handle, whenever a characteristic is found AT_BLE_CHARACTERISTIC_FOUND event is sent and AT_BLE_DISCOVERY_COMPLETE is sent at end of discover operation.

Parameters
[in]conn_handleHandle of the connection
[in]start_handleStart of the searched range
[in]end_handleEnd of the searched range
Returns
AT_BLE_SUCCESS Operation completed successfully
AT_BLE_INVALID_PARAM Invalid arguments
AT_BLE_FAILURE Generic error

References AT_BLE_INVALID_PARAM, GATTC_DISC_ALL_CHAR, gattc_disc_cmd_handler(), and NULL.

at_ble_status_t at_ble_characteristic_discover_by_uuid ( at_ble_handle_t  conn_handle,
at_ble_handle_t  start_handle,
at_ble_handle_t  end_handle,
at_ble_uuid_t uuid 
)

Discover all Characteristics of a given UUID declared in a connected device.

search will go from start_handle to end_handle, whenever a characteristic of matching UUID is found AT_BLE_CHARACTERISTIC_FOUND event is sent and AT_BLE_DISCOVERY_COMPLETE is sent at end of discover operation.

Parameters
[in]conn_handlehandle of the connection
[in]start_handlestart of the searched range
[in]end_handleend of the searched range
[in]uuidUUID of the characteristic to be found, with LSB byte First in UUID value member
Returns
Upon successful completion the function shall return AT_BLE_ATT_ATTRIBUTE_NOT_FOUND, Otherwise the function shall return at_ble_status_t

Search will go from start_handle to end_handle, whenever a characteristic of matching UUID is found AT_BLE_CHARACTERISTIC_FOUND event is sent and AT_BLE_DISCOVERY_COMPLETE is sent at end of discover operation.

Parameters
[in]conn_handleHandle of the connection
[in]start_handleStart of the searched range
[in]end_handleEnd of the searched range
[in]uuidUUID of the characteristic to be found, with LSB byte First in UUID value member
Returns
AT_BLE_SUCCESS Operation completed successfully
AT_BLE_INVALID_PARAM Invalid arguments
AT_BLE_FAILURE Generic error

References AT_BLE_INVALID_PARAM, at_ble_uuid_type2len(), GATTC_DISC_BY_UUID_CHAR, gattc_disc_cmd_handler(), at_ble_uuid_t::type, and at_ble_uuid_t::uuid.

at_ble_status_t at_ble_characteristic_read ( at_ble_handle_t  conn_handle,
at_ble_handle_t  char_handle,
uint16_t  offset,
uint16_t  length 
)

Read a characteristic given its handle.

Read value will be reported via AT_BLE_CHARACTERISTIC_READ_RESPONSE event

Parameters
[in]conn_handlehandle of the connection
[in]char_handlehandle of the characteristic
[in]offsetoffset at where to start reading
[in]length= 0 then the response will retrieve the full length of the characteristic (read all) > 0 && < full length then the passed length will be red by == full length || > full length full length will be retrieved
Returns
Upon successful completion the function shall return AT_BLE_SUCCESS, Otherwise the function shall return at_ble_status_t

Read value will be reported via AT_BLE_CHARACTERISTIC_READ_RESPONSE event.

Parameters
[in]conn_handleHandle of the connection
[in]char_handleHandle of the characteristic
[in]offsetOffset at where to start reading
[in]lengthMaximum length of data to read
Returns
AT_BLE_SUCCESS Operation completed successfully
AT_BLE_INVALID_PARAM Invalid arguments
AT_BLE_FAILURE Generic error

References gattc_read_cmd_handler_simple_read().

at_ble_status_t at_ble_characteristic_read_by_uuid ( at_ble_handle_t  conn_handle,
at_ble_handle_t  start_handle,
at_ble_handle_t  end_handle,
at_ble_uuid_t uuid 
)

Read a characteristic given its UUID.

search will go from start_handle to end_handle, whenever a descriptor with given UUID is found its value will be read and reported via AT_BLE_CHARACTERISTIC_READ_BY_UUID_RESPONSE event

Parameters
[in]conn_handlehandle of the connection
[in]start_handlestart of the searched range
[in]end_handleend of the searched range
[in]uuidUUID of the read characteristic, with LSB byte First in UUID value member
Returns
Upon successful completion the function shall return AT_BLE_ATT_ATTRIBUTE_NOT_FOUND, Otherwise the function shall return at_ble_status_t

Search will go from start_handle to end_handle, whenever a descriptor with given UUID is found its value will be read and reported via AT_BLE_CHARACTERISTIC_READ_RESPONSE event.

Parameters
[in]conn_handleHandle of the connection
[in]start_handleStart of the searched range
[in]end_handleEnd of the searched range
[in]uuidUUID of the read characteristic, with LSB byte First in UUID value member
Returns
AT_BLE_SUCCESS Operation completed successfully
AT_BLE_FAILURE Generic error

References AT_BLE_INVALID_PARAM, at_ble_uuid_type2len(), gattc_read_cmd_handler_by_uuid(), at_ble_uuid_t::type, and at_ble_uuid_t::uuid.

at_ble_status_t at_ble_characteristic_read_long ( at_ble_handle_t  conn_handle,
at_ble_handle_t  char_handle,
uint16_t  offset,
uint16_t  length 
)

Long read a characteristic given its handle.

read value will be reported via AT_BLE_CHARACTERISTIC_READ_RESPONSE event

Parameters
[in]conn_handlehandle of the connection
[in]char_handlehandle of the characteristic
[in]offsetoffset at where to start reading
[in]length*
[in]length= 0 then the response will retrieve the full length of the characteristic (read all) > 0 && < full length then the passed length will be red by == full length || > full length full length will be retrieved (read all)
Returns
Upon successful completion the function shall return AT_BLE_SUCCESS, Otherwise the function shall return at_ble_status_t
at_ble_status_t at_ble_characteristic_read_multiple ( at_ble_handle_t  conn_handle,
at_ble_char_list char_handle_list,
uint8_t  char_handle_count 
)

Read a list of characteristics given their handles.

read values will be reported via AT_BLE_CHARACTERISTIC_READ_RESPONSE event after delivering all requested value the the user will receive AT_BLE_CHARACTERISTIC_READ_MULTIBLE_RESPONSE to indicate end of procedure

Parameters
[in]conn_handlehandle of the connection
[in]char_handle_listlist of structures of characteristic handles and their lengths
[in]char_handle_countnumber of characteristic handles fro more info, refer to at_ble_char_list
Returns
Upon successful completion the function shall return AT_BLE_SUCCESS, Otherwise the function shall return at_ble_status_t
at_ble_status_t at_ble_characteristic_reliable_write_cancel ( at_ble_handle_t  conn_handle)

Cancels a pending prepared reliable write operation.

Cancels a pending prepared reliable write operation

Parameters
[in]conn_handlehandle of the connection
Returns
Upon successful completion the function shall return AT_BLE_SUCCESS, Otherwise the function shall return at_ble_status_t

Cancels a pending prepared reliable write operation.

Cancels a pending prepared write operation.

Parameters
[in]conn_handleHandle of the connection
Returns
AT_BLE_SUCCESS Operation completed successfully
AT_BLE_FAILURE Generic error

References gattc_execute_write_cmd_handler().

at_ble_status_t at_ble_characteristic_reliable_write_execute ( at_ble_handle_t  conn_handle)

Executes a pending prepared write operation.

send write Execute to peer device to Execute pending prepared write operation, write completion will be reported via AT_BLE_CHARACTERISTIC_WRITE_CMD_CMP event.

Parameters
[in]conn_handlehandle of the connection
Returns
Upon successful completion the function shall return AT_BLE_SUCCESS, Otherwise the function shall return at_ble_status_t

Executes a pending prepared write operation. Write completion will be reported via AT_BLE_CHARACTERISTIC_WRITE_RESPONSE event.

Parameters
[in]conn_handleHandle of the connection
Returns
AT_BLE_SUCCESS Operation completed successfully
AT_BLE_FAILURE Generic error

References gattc_execute_write_cmd_handler().

at_ble_status_t at_ble_characteristic_reliable_write_prepare ( at_ble_handle_t  conn_handle,
at_ble_handle_t  char_handle,
uint16_t  offset,
uint16_t  length,
uint8_t *  data 
)

add a new prepared write request

Adds a new request to a pending prepared write operation, or starts a new prepared write operation if none was started before

Parameters
[in]conn_handlehandle of the connection
[in]char_handlehandle of the characteristic
[in]offsetoffset at where to start write
[in]lengthlength of data to write
[in]dataa buffer where write data is stored
Returns
Upon successful completion the function shall return AT_BLE_SUCCESS, Otherwise the function shall return at_ble_status_t

add a new prepared write request

Adds a new request to a pending prepared write operation, or starts a new prepared write operation if none was started before.

Parameters
[in]conn_handleHandle of the connection
[in]char_handleHandle of the characteristic
[in]offsetOffset at where to start write
[in]lengthLength of data to write
[in]dataA buffer where write data is stored
Returns
AT_BLE_SUCCESS Operation completed successfully
AT_BLE_FAILURE Generic error

References GATTC_WRITE, and gattc_write_cmd_handler().

at_ble_status_t at_ble_characteristic_write ( at_ble_handle_t  conn_handle,
at_ble_handle_t  char_handle,
uint16_t  offset,
uint16_t  length,
uint8_t *  data,
bool  signed_write,
bool  with_response 
)

Write a characteristic value in peer device and write completion will be reported via AT_BLE_CHARACTERISTIC_WRITE_CMD_CMP event after firmware handling.

In case of signed write and write without response AT_BLE_CHARACTERISTIC_WRITE_CMD_CMP is triggered as soon as packet has been sent over the air. In case of write with response AT_BLE_CHARACTERISTIC_WRITE_CMD_CMP is triggered if error happened or when response is received from peer device.

Parameters
[in]conn_handlehandle of the connection
[in]char_handlehandle of the characteristic
[in]offsetoffset at where to start write
[in]lengthlength of data to write
[in]dataa buffer where write data is stored
[in]signed_writeif true, perform a signed write
[in]with_responseif true, perform a write with response procedure, otherwise perform write with no response procedure
Note
  • If data length > MTU-3 then the write operation will be converted to long write instead of normal write operation, this scenario will be taken over by BLE stack firmware.
Returns
Upon successful completion the function shall return AT_BLE_SUCCESS, Otherwise the function shall return at_ble_status_t

Write a characteristic value in peer device and write completion will be reported via AT_BLE_CHARACTERISTIC_WRITE_CMD_CMP event after firmware handling.

If with_response is True, write completion will be reported via AT_BLE_CHARACTERISTIC_WRITE_RESPONSE event.

Parameters
[in]conn_handleHandle of the connection
[in]char_handleHandle of the characteristic
[in]offsetOffset at where to start write
[in]lengthLength of data to write
[in]dataA buffer where write data is stored
[in]signed_writeIf true, perform a signed write
[in]with_responseIf true, perform a write with response procedure, otherwise perform write with no response procedure
Returns
AT_BLE_SUCCESS Operation completed successfully
AT_BLE_FAILURE Generic error

References GATTC_WRITE, gattc_write_cmd_handler(), GATTC_WRITE_NO_RESPONSE, and GATTC_WRITE_SIGNED.

at_ble_status_t at_ble_descriptor_discover_all ( at_ble_handle_t  conn_handle,
at_ble_handle_t  start_handle,
at_ble_handle_t  end_handle 
)

Discover all Descriptors declared in a connected device.

Search will go from start_handle to end_handle, whenever a descriptor is found AT_BLE_DESCRIPTOR_FOUND event is sent and AT_BLE_DISCOVERY_COMPLETE is sent at end of discover operation.

Parameters
[in]conn_handlehandle of the connection
[in]start_handlestart of the searched range
[in]end_handleend of the searched range
Returns
Upon successful completion the function shall return AT_BLE_ATT_ATTRIBUTE_NOT_FOUND, Otherwise the function shall return at_ble_status_t

Search will go from start_handle to end_handle, whenever a descriptor is found AT_BLE_DESCRIPTOR_FOUND event is sent and AT_BLE_DISCOVERY_COMPLETE is sent at end of discover operation.

Parameters
[in]conn_handleHandle of the connection
[in]start_handleStart of the searched range
[in]end_handleEnd of the searched range
Returns
AT_BLE_SUCCESS Operation completed successfully
AT_BLE_INVALID_PARAM Invalid arguments
AT_BLE_FAILURE Generic error

References AT_BLE_INVALID_PARAM, gattc_disc_cmd_handler(), GATTC_DISC_DESC_CHAR, and NULL.

at_ble_status_t at_ble_exchange_mtu ( at_ble_handle_t  conn_handle)

send the MTU exchange command to peer device

Sends the MTU Exchange command to peer device to start exchanging the MTu maximum allowed length (Octet). if the peer device changes his MTU value according to the sender's MTU. the sender will receive the indication AT_BLE_MTU_CHANGED_INDICATION with the exchanged MTU value then receive AT_BLE_MTU_CHANGED_CMD_COMPLETE . if the peer device didn't accept the MTU value AT_BLE_MTU_CHANGED_CMD_COMPLETE will be sent.

Parameters
[in]conn_handlehandle of the connection
Returns
Upon successful completion the function shall return AT_BLE_SUCCESS, Otherwise the function shall return at_ble_status_t

send the MTU exchange command to peer device

Parameters
[in]conn_handleHandle of the connection
Returns
AT_BLE_SUCCESS Operation completed successfully
AT_BLE_FAILURE Generic error

References gattc_mtu_cmd_handler().

at_ble_status_t at_ble_included_service_discover_all ( at_ble_handle_t  conn_handle,
at_ble_handle_t  start_handle,
at_ble_handle_t  end_handle 
)

Discover all included services declared in a connected device.

Search will go from start_handle to end_handle, whenever a service is found AT_BLE_INCLUDED_SERVICE_FOUND event is sent and AT_BLE_DISCOVERY_COMPLETE is sent at end of discover operation.

Parameters
[in]conn_handlehandle of the connection
[in]start_handlestart of the searched range
[in]end_handleend of the searched range
Returns
Upon successful completion the function shall return AT_BLE_ATT_ATTRIBUTE_NOT_FOUND, Otherwise the function shall return at_ble_status_t

Search will go from start_handle to end_handle, whenever a service is found AT_BLE_INCLUDED_SERVICE_FOUND event is sent and AT_BLE_DISCOVERY_COMPLETE is sent at end of discover operation.

Parameters
[in]conn_handleHandle of the connection
[in]start_handleStart of the searched range
[in]end_handleEnd of the searched range
Returns
AT_BLE_SUCCESS Operation completed successfully
AT_BLE_INVALID_PARAM Invalid arguments
AT_BLE_FAILURE Generic error

References AT_BLE_INVALID_PARAM, gattc_disc_cmd_handler(), GATTC_DISC_INCLUDED_SVC, and NULL.

at_ble_status_t at_ble_primary_service_discover_all ( at_ble_handle_t  conn_handle,
at_ble_handle_t  start_handle,
at_ble_handle_t  end_handle 
)

Discover all Primary services in a peer device.

Discover all Primary services in a peer device from a specified start_handle to a specified end_handle, whenever a service is found AT_BLE_PRIMARY_SERVICE_FOUND event is sent and AT_BLE_DISCOVERY_COMPLETE is sent at the end of discover operation.

Parameters
[in]conn_handlehandle of the connected peer
[in]start_handlestart of the searched range
[in]end_handleend of the searched range
Returns
Upon successful completion the function shall return AT_BLE_SUCCESS, Otherwise the function shall return at_ble_status_t

Discover all Primary services in a peer device.

Search will go from start_handle to end_handle, whenever a service is found AT_BLE_PRIMARY_SERVICE_FOUND event is sent and AT_BLE_DISCOVERY_COMPLETE is sent at end of discover operation.

Parameters
[in]conn_handleHandle of the connection
[in]start_handleStart of the searched range
[in]end_handleEnd of the searched range
Returns
AT_BLE_SUCCESS Operation completed successfully
AT_BLE_INVALID_PARAM Invalid arguments
AT_BLE_FAILURE Generic error

References AT_BLE_INVALID_PARAM, GATTC_DISC_ALL_SVC, gattc_disc_cmd_handler(), and NULL.

at_ble_status_t at_ble_primary_service_discover_by_uuid ( at_ble_handle_t  conn_handle,
at_ble_handle_t  start_handle,
at_ble_handle_t  end_handle,
at_ble_uuid_t uuid 
)

Discover Primary service of a given UUID declared and located in a peer device.

Search will go from start_handle to end_handle, whenever a service of matching UUID is found AT_BLE_PRIMARY_SERVICE_FOUND event is sent and AT_BLE_DISCOVERY_COMPLETE is sent at end of discover operation.

Parameters
[in]conn_handlehandle of the connected peer
[in]start_handlestart of the searched range
[in]end_handleend of the searched range
[in]uuidUUID of the service to be found, with LSB byte First in UUID value member
Returns
Upon successful completion the function shall return AT_BLE_SUCCESS, Otherwise the function shall return at_ble_status_t

Discover Primary service of a given UUID declared and located in a peer device.

Search will go from start_handle to end_handle, whenever a service of matching UUID is found AT_BLE_PRIMARY_SERVICE_FOUND event is sent and AT_BLE_DISCOVERY_COMPLETE is sent at end of discover operation.

Parameters
[in]conn_handleHandle of the connection
[in]start_handleStart of the searched range
[in]end_handleEnd of the searched range
[in]uuidUUID of the service to be found, with LSB byte First in UUID value member
Returns
AT_BLE_SUCCESS Operation completed successfully
AT_BLE_INVALID_PARAM Invalid arguments
AT_BLE_FAILURE Generic error

References AT_BLE_INVALID_PARAM, at_ble_uuid_type2len(), GATTC_DISC_BY_UUID_SVC, gattc_disc_cmd_handler(), at_ble_uuid_t::type, and at_ble_uuid_t::uuid.