BAS Client Functions

General Description

API unique to BAS designs configured as a GATT Client role.

A letter 'c' is appended to the API name: Cy_BLE_BASC_

Functions
cy_en_ble_api_result_t	Cy_BLE_BASC_GetCharacteristicValue (cy_stc_ble_conn_handle_t connHandle, uint8_t serviceIndex, cy_en_ble_bas_char_index_t charIndex)
	This function is used to read the characteristic value from the server identified by charIndex. More...
cy_en_ble_api_result_t	Cy_BLE_BASC_SetCharacteristicDescriptor (cy_stc_ble_conn_handle_t connHandle, uint8_t serviceIndex, cy_en_ble_bas_char_index_t charIndex, cy_en_ble_bas_descr_index_t descrIndex, uint8_t attrSize, uint8_t *attrValue)
	Sends a request to set a characteristic descriptor of the specified Battery service characteristic on the server device. More...
cy_en_ble_api_result_t	Cy_BLE_BASC_GetCharacteristicDescriptor (cy_stc_ble_conn_handle_t connHandle, uint8_t serviceIndex, cy_en_ble_bas_char_index_t charIndex, cy_en_ble_bas_descr_index_t descrIndex)
	Sends a request to get a characteristic descriptor of the specified Battery service characteristic from the server device. More...

Function Documentation

Cy_BLE_BASC_GetCharacteristicValue()

cy_en_ble_api_result_t Cy_BLE_BASC_GetCharacteristicValue	(	cy_stc_ble_conn_handle_t	connHandle,
		uint8_t	serviceIndex,
		cy_en_ble_bas_char_index_t	charIndex
	)

This function is used to read the characteristic value from the server identified by charIndex.

This function call can result in generation of the following events based on a response from the server device:

• CY_BLE_EVT_BASC_READ_CHAR_RESPONSE
• CY_BLE_EVT_GATTC_ERROR_RSP

Parameters

connHandle	The BLE peer device connection handle.
serviceIndex	The index of the service instance; e.g. if two Battery services are supported in your design, then the first service will be identified by serviceIndex of 0 and the second service by serviceIndex of 1.
charIndex	The index of a service characteristic of type cy_en_ble_bas_char_index_t.

Returns

A return value of type cy_en_ble_api_result_t.

Error Codes	Description
CY_BLE_SUCCESS	The Read Request was sent successfully.
CY_BLE_ERROR_INVALID_PARAMETER	Validation of the input parameter failed.
CY_BLE_ERROR_INVALID_OPERATION	Operation is invalid for this characteristic.
CY_BLE_ERROR_INVALID_STATE	Connection with the server is not established.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	Memory allocation failed.
CY_BLE_ERROR_GATT_DB_INVALID_ATTR_HANDLE	The peer device doesn't have the particular characteristic.

Events

If execution is successful (return value = CY_BLE_SUCCESS), these events can appear:
If the BAS service-specific callback is registered (with Cy_BLE_BAS_RegisterAttrCallback):

• CY_BLE_EVT_BASC_READ_CHAR_RESPONSE - If the requested attribute is successfully read on the peer device, the details (charIndex, value, etc.) are provided with an event parameter structure of type cy_stc_ble_bas_char_value_t.

Otherwise (if a BAS service-specific callback is not registered):

• CY_BLE_EVT_GATTC_READ_RSP - If the requested attribute is successfully read on the peer device, the details (handle, value, etc.) are provided with the event parameters structure cy_stc_ble_gattc_read_rsp_param_t.
• CY_BLE_EVT_GATTC_ERROR_RSP - If an error occurred with the requested attribute on the peer device, the details are provided with the event parameters structure cy_stc_ble_gatt_err_param_t.

Cy_BLE_BASC_SetCharacteristicDescriptor()

cy_en_ble_api_result_t Cy_BLE_BASC_SetCharacteristicDescriptor	(	cy_stc_ble_conn_handle_t	connHandle,
		uint8_t	serviceIndex,
		cy_en_ble_bas_char_index_t	charIndex,
		cy_en_ble_bas_descr_index_t	descrIndex,
		uint8_t	attrSize,
		uint8_t *	attrValue
	)

Sends a request to set a characteristic descriptor of the specified Battery service characteristic on the server device.

Internally, a Write Request is sent to the GATT Server and on successful execution of the request on the server side, the following events can be generated:

• CY_BLE_EVT_BASS_NOTIFICATION_ENABLED
• CY_BLE_EVT_BASS_NOTIFICATION_DISABLED

Parameters

connHandle	The BLE peer device connection handle.
serviceIndex	The index of the service instance; e.g. if two Battery services are supported in your design, then the first service will be identified by serviceIndex of 0 and the second service by serviceIndex of 1.
charIndex	The index of a service characteristic of type cy_en_ble_bas_char_index_t.
descrIndex	The index of a service characteristic descriptor of type cy_en_ble_bas_descr_index_t.
attrSize	The size of the characteristic descriptor attribute.
attrValue	The pointer to the characteristic descriptor value data that should be sent to the server device.

Returns

A return value of type cy_en_ble_api_result_t.

Error Codes	Description
CY_BLE_SUCCESS	The request was sent successfully.
CY_BLE_ERROR_INVALID_PARAMETER	Validation of the input parameter failed.
CY_BLE_ERROR_INVALID_OPERATION	Operation is invalid for this characteristic.
CY_BLE_ERROR_GATT_DB_INVALID_ATTR_HANDLE	The peer device doesn't have the particular characteristic.
CY_BLE_ERROR_INVALID_STATE	Connection with the server is not established.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	Memory allocation failed.

Events

If execution is successful (return value = CY_BLE_SUCCESS), these events can appear:
If a BAS service-specific callback is registered with Cy_BLE_BAS_RegisterAttrCallback():

• CY_BLE_EVT_BASC_WRITE_DESCR_RESPONSE - If the requested attribute is successfully written on the peer device, the details (charIndex, descrIndex, etc.) are provided with an event parameter structure of type cy_stc_ble_bas_descr_value_t.

Otherwise (if a BAS service-specific callback is not registered):

• CY_BLE_EVT_GATTC_WRITE_RSP - If the requested attribute is successfully written on the peer device.
• CY_BLE_EVT_GATTC_ERROR_RSP - If an error occurred with the requested attribute on the peer device, the details are provided with an event parameter structure cy_stc_ble_gatt_err_param_t.

Cy_BLE_BASC_GetCharacteristicDescriptor()

cy_en_ble_api_result_t Cy_BLE_BASC_GetCharacteristicDescriptor	(	cy_stc_ble_conn_handle_t	connHandle,
		uint8_t	serviceIndex,
		cy_en_ble_bas_char_index_t	charIndex,
		cy_en_ble_bas_descr_index_t	descrIndex
	)

Sends a request to get a characteristic descriptor of the specified Battery service characteristic from the server device.

This function call can result in generation of the following events based on a response from the server device:

• CY_BLE_EVT_BASC_READ_DESCR_RESPONSE
• CY_BLE_EVT_GATTC_ERROR_RSP

Parameters

connHandle	The BLE peer device connection handle.
serviceIndex	The index of the service instance; e.g. if two Battery services are supported in your design, then the first service will be identified by serviceIndex of 0 and the second service by serviceIndex of 1.
charIndex	The index of a service characteristic of type cy_en_ble_bas_char_index_t.
descrIndex	The index of a service characteristic descriptor of type cy_en_ble_bas_descr_index_t.

Returns

A return value of type cy_en_ble_api_result_t.

Error Codes	Description
CY_BLE_SUCCESS	The request was sent successfully.
CY_BLE_ERROR_INVALID_PARAMETER	Validation of the input parameter failed.
CY_BLE_ERROR_INVALID_OPERATION	Operation is invalid for this characteristic.
CY_BLE_ERROR_INVALID_STATE	Connection with the server is not established.
CY_BLE_ERROR_MEMORY_ALLOCATION_FAILED	Memory allocation failed.

Events

If execution is successful (return value = CY_BLE_SUCCESS), these events can appear:
If a BAS service-specific callback is registered (with Cy_BLE_BAS_RegisterAttrCallback):

• CY_BLE_EVT_BASC_READ_DESCR_RESPONSE - If the requested attribute is successfully read on the peer device, the details (charIndex, descrIndex, value, etc.) are provided with an event parameter structure of type cy_stc_ble_bas_descr_value_t.

Otherwise (if a BAS service-specific callback is not registered):

• CY_BLE_EVT_GATTC_READ_RSP - If the requested attribute is successfully read on the peer device, the details (handle, value, etc.) are provided with the event parameters structure cy_stc_ble_gattc_read_rsp_param_t.
• CY_BLE_EVT_GATTC_ERROR_RSP - If an error occurred with the requested attribute on the peer device, the details are provided with the event parameters structure cy_stc_ble_gatt_err_param_t.