GATT Client#

GATT Client.

Detailed Description#

GATT Client.

The commands and events in this class are used to browse and manage attributes in a remote GATT server.

Enumeration Type Documentation#

sl_bt_gatt_att_opcode_t#

enum sl_bt_gatt_att_opcode_t

Attribute Protocol Opcode.

sl_bt_gatt_client_config_flag_t#

enum sl_bt_gatt_client_config_flag_t

Characteristic Client Configuration Flag.

sl_bt_gatt_execute_write_flag_t#

enum sl_bt_gatt_execute_write_flag_t

Execute Write Flag.

Function Documentation#

sl_bt_gatt_set_max_mtu()#

Set the maximum size of ATT Message Transfer Units (MTU). Functionality is the same as sl_bt_gatt_server_set_max_mtu and this setting applies to both GATT client and server. If the given value is too large according to the maximum BGAPI payload size, the system will select the maximum possible value as the maximum ATT_MTU. If the maximum ATT_MTU is larger than 23, the GATT client in the stack will automatically send an MTU exchange request after a Bluetooth connection has been established.

Parameters

Default: 247 | | [out] | max_mtu_out | The maximum ATT_MTU selected by the system if this command succeeds |

Returns

SL_STATUS_OK if successful. Error code otherwise.

sl_bt_gatt_discover_primary_services()#

sl_status_t sl_bt_gatt_discover_primary_services ( uint8_t connection )

Discover all primary services of a remote GATT database. This command generates a unique gatt_service event for every discovered primary service. Received sl_bt_evt_gatt_procedure_completed event indicates that this GATT procedure has successfully completed or failed with an error.

Parameters

Returns

SL_STATUS_OK if successful. Error code otherwise.

Events

• sl_bt_evt_gatt_service - Discovered service from remote GATT database

• sl_bt_evt_gatt_procedure_completed - Procedure was successfully completed or failed with an error.

sl_bt_gatt_discover_primary_services_by_uuid()#

Discover primary services with the specified UUID in a remote GATT database. This command generates unique gatt_service event for every discovered primary service. Received sl_bt_evt_gatt_procedure_completed event indicates that this GATT procedure was successfully completed or failed with an error.

Parameters

Returns

SL_STATUS_OK if successful. Error code otherwise.

Events

• sl_bt_evt_gatt_service - Discovered service from remote GATT database.

• sl_bt_evt_gatt_procedure_completed - Procedure was successfully completed or failed with an error.

sl_bt_gatt_find_included_services()#

Find the services that are included by a service in a remote GATT database. This command generates a unique gatt_service event for each included service. The received sl_bt_evt_gatt_procedure_completed event indicates that this GATT procedure was successfully completed or failed with an error.

Parameters

Returns

SL_STATUS_OK if successful. Error code otherwise.

Events

• sl_bt_evt_gatt_service - Discovered service from remote GATT database.

• sl_bt_evt_gatt_procedure_completed - Procedure was successfully completed or failed with an error.

sl_bt_gatt_discover_characteristics()#

Discover all characteristics of a GATT service from a remote GATT database. This command generates a unique gatt_characteristic event for every discovered characteristic. Received sl_bt_evt_gatt_procedure_completed event indicates that this GATT procedure was successfully completed or failed with an error.

Parameters

Returns

SL_STATUS_OK if successful. Error code otherwise.

Events

• sl_bt_evt_gatt_characteristic - Discovered characteristic from remote GATT database.

• sl_bt_evt_gatt_procedure_completed - Procedure was successfully completed or failed with an error.

sl_bt_gatt_discover_characteristics_by_uuid()#

Discover all characteristics of a GATT service in a remote GATT database having the specified UUID. This command generates a unique gatt_characteristic event for every discovered characteristic having the specified UUID. Received sl_bt_evt_gatt_procedure_completed event indicates that this GATT procedure was successfully completed or failed with an error.

Parameters

Returns

SL_STATUS_OK if successful. Error code otherwise.

Events

• sl_bt_evt_gatt_characteristic - Discovered characteristic from remote GATT database.

• sl_bt_evt_gatt_procedure_completed - Procedure was successfully completed or failed with an error.

sl_bt_gatt_discover_descriptors()#

Discover all descriptors of a GATT characteristic in a remote GATT database. It generates a unique gatt_descriptor event for every discovered descriptor. Received sl_bt_evt_gatt_procedure_completed event indicates that this GATT procedure has successfully completed or failed with an error.

Parameters

Returns

SL_STATUS_OK if successful. Error code otherwise.

Events

• sl_bt_evt_gatt_descriptor - Discovered descriptor from remote GATT database.

• sl_bt_evt_gatt_procedure_completed - Procedure was successfully completed or failed with an error.

sl_bt_gatt_set_characteristic_notification()#

Enable or disable the notifications and indications sent from a remote GATT server. This procedure discovers a characteristic client configuration descriptor and writes the related configuration flags to a remote GATT database. A received sl_bt_evt_gatt_procedure_completed event indicates that this GATT procedure was successfully completed or that it failed with an error.

Parameters

• sl_bt_gatt_notification (0x1): Notification

• sl_bt_gatt_indication (0x2): Indication |

Returns

SL_STATUS_OK if successful. Error code otherwise.

Events

• sl_bt_evt_gatt_procedure_completed - Procedure was successfully completed or failed with an error.

• sl_bt_evt_gatt_characteristic_value - If an indication or notification has been enabled for a characteristic, this event is triggered whenever an indication or notification is sent by the remote GATT server. The triggering conditions of the GATT server are defined by an upper level, for example by a profile. As a result, it is possible that no values are ever received, or that it may take time, depending on how the server is configured.

sl_bt_gatt_send_characteristic_confirmation()#

Send a confirmation to a remote GATT server after receiving a characteristic indication. The sl_bt_evt_gatt_characteristic_value event carries the att_opcode containing sl_bt_gatt_handle_value_indication (0x1d), which reveals that an indication has been received and must be confirmed with this command. The confirmation needs to be sent within 30 seconds, otherwise further GATT transactions are not allowed by the remote side.

Parameters

Returns

SL_STATUS_OK if successful. Error code otherwise.

sl_bt_gatt_read_characteristic_value()#

Read the value of a characteristic from a remote GATT database. A single sl_bt_evt_gatt_characteristic_value is generated if the characteristic value fits in one ATT PDU. Otherwise, more than one sl_bt_evt_gatt_characteristic_value event is generated because the firmware will automatically use the Read Long Characteristic Values procedure. A received sl_bt_evt_gatt_procedure_completed event indicates that all data was read successfully or that an error response was received.

Note that the GATT client does not verify if the requested attribute is a characteristic value. Therefore, before calling this command, ensure that the attribute handle is for a characteristic value, for example, by performing characteristic discovery.

Parameters

Returns

SL_STATUS_OK if successful. Error code otherwise.

Events

• sl_bt_evt_gatt_characteristic_value - Contains the data of a characteristic sent by the GATT Server.

• sl_bt_evt_gatt_procedure_completed - Procedure was successfully completed or failed with an error.

sl_bt_gatt_read_characteristic_value_from_offset()#

Read a partial characteristic value with a specified offset and maximum length from a remote GATT database. It is equivalent to sl_bt_gatt_read_characteristic_value if both the offset and maximum length parameters are 0. A single sl_bt_evt_gatt_characteristic_value event is generated if the value to read fits in one ATT PDU. Otherwise, more than one sl_bt_evt_gatt_characteristic_value events are generated because the firmware will automatically use the Read Long Characteristic Values procedure. A received sl_bt_evt_gatt_procedure_completed event indicates that all data was read successfully or that an error response was received.

Parameters

Returns

SL_STATUS_OK if successful. Error code otherwise.

Events

• sl_bt_evt_gatt_characteristic_value - Contains data of a characteristic sent by the GATT Server.

• sl_bt_evt_gatt_procedure_completed - Procedure was successfully completed or failed with an error.

sl_bt_gatt_read_multiple_characteristic_values()#

Read values of multiple characteristics from a remote GATT database at once. The GATT server returns values in one ATT PDU as the response. If the total set of values is greater than (ATT_MTU - 1) bytes in length, only the first (ATT_MTU - 1) bytes are included. A single sl_bt_evt_gatt_characteristic_value event is generated, in which the characteristic is set to 0 and data in the value parameter is a concatenation of characteristic values in the order they were requested. The received sl_bt_evt_gatt_procedure_completed event indicates either that this GATT procedure was successfully completed or failed with an error.

Use this command only for characteristics values that have a known fixed size, except the last one that could have variable length.

When the remote GATT server is from Silicon Labs Bluetooth stack, the server returns ATT Invalid PDU (0x04) if this command only reads one characteristic value. The server returns ATT Application Error 0x80 if this command reads the value of a user-type characteristic.

Parameters

Returns

SL_STATUS_OK if successful. Error code otherwise.

Events

• sl_bt_evt_gatt_characteristic_value - A concatenation of characteristic values in the order they were requested

• sl_bt_evt_gatt_procedure_completed - Procedure was either successfully completed or failed with an error.

sl_bt_gatt_read_characteristic_value_by_uuid()#

Read characteristic values of a service from a remote GATT database by giving the UUID of the characteristic and the handle of the service containing this characteristic. If multiple characteristic values are received in one ATT PDU, one sl_bt_evt_gatt_characteristic_value event is generated for each value. If the first characteristic value does not fit in one ATT PDU, the firmware automatically uses the Read Long Characteristic Values procedure and generate more sl_bt_evt_gatt_characteristic_value events until the value has been completely read. A received sl_bt_evt_gatt_procedure_completed event indicates that all data was read successfully or that an error response was received.

Parameters

Returns

SL_STATUS_OK if successful. Error code otherwise.

Events

• sl_bt_evt_gatt_characteristic_value - Contains the data of a characteristic sent by the GATT Server.

• sl_bt_evt_gatt_procedure_completed - Procedure was successfully completed or failed with an error.

sl_bt_gatt_write_characteristic_value()#

Write the value of a characteristic in a remote GATT database. If the given value does not fit in one ATT PDU, "write long" GATT procedure is used automatically. Received sl_bt_evt_gatt_procedure_completed event indicates that all data was written successfully or that an error response was received.

Parameters

Returns

SL_STATUS_OK if successful. Error code otherwise.

Events

• sl_bt_evt_gatt_procedure_completed - Procedure was successfully completed or failed with an error.

sl_bt_gatt_write_characteristic_value_without_response()#

Write the value of a characteristic in a remote GATT server. It does not generate an event. All failures on the server are ignored silently. For example, if an error is generated in the remote GATT server and the given value is not written into the database, no error message will be reported to the local GATT client. Note that this command can't be used to write long values. At most ATT_MTU - 3 amount of data can be sent once.

Parameters

Returns

SL_STATUS_OK if successful. Error code otherwise.

sl_bt_gatt_prepare_characteristic_value_write()#

Add a characteristic value to the write queue of a remote GATT server. It can be used when long attributes need to be written or a set of values needs to be written atomically. At most ATT_MTU - 5 amount of data can be sent at one time. Writes are executed or canceled with the sl_bt_gatt_execute_characteristic_value_write command. Whether the writes succeed or not is indicated in the response of the sl_bt_gatt_execute_characteristic_value_write command.

In all use cases where the amount of data to transfer fits into the BGAPI payload, use the command sl_bt_gatt_write_characteristic_value to write long values because it transparently performs the prepare_write and execute_write commands.

Parameters

Returns

SL_STATUS_OK if successful. Error code otherwise.

Events

• sl_bt_evt_gatt_procedure_completed - Procedure was successfully completed or failed with an error.

sl_bt_gatt_prepare_characteristic_value_reliable_write()#

Add a characteristic value to the write queue of a remote GATT server and verifies whether the value was correctly received by the server. Received sl_bt_evt_gatt_procedure_completed event indicates that this GATT procedure was successfully completed or failed with an error. Specifically, error code 0x0194 (data_corrupted) will be returned if the value received from the GATT server's response fails to pass the reliable write verification. At most, ATT_MTU - 5 amount of data can be sent at one time. Writes are executed or canceled with the sl_bt_gatt_execute_characteristic_value_write command. Whether the writes succeed or not is indicated in the response of the sl_bt_gatt_execute_characteristic_value_write command.

Parameters

Returns

SL_STATUS_OK if successful. Error code otherwise.

Events

• sl_bt_evt_gatt_procedure_completed - Procedure was successfully completed or failed with an error.

sl_bt_gatt_execute_characteristic_value_write()#

Commit or cancel previously queued writes to a long characteristic of a remote GATT server. Writes are sent to the queue with sl_bt_gatt_prepare_characteristic_value_write command. Content, offset, and length of queued values are validated by this procedure. A received sl_bt_evt_gatt_procedure_completed event indicates that all data was written successfully or that an error response was received.

Parameters

• sl_bt_gatt_commit (0x1): Commit all queued writes |

Returns

SL_STATUS_OK if successful. Error code otherwise.

Events

• sl_bt_evt_gatt_procedure_completed - Procedure was successfully completed or failed with an error.

sl_bt_gatt_read_descriptor_value()#

Read the descriptor value of a characteristic in a remote GATT database. A single sl_bt_evt_gatt_descriptor_value event is generated if the descriptor value fits in one ATT PDU. Otherwise, more than one sl_bt_evt_gatt_descriptor_value events are generated because the firmware automatically uses the Read Long Characteristic Values procedure. A received sl_bt_evt_gatt_procedure_completed event indicates that all data was read successfully or that an error response was received.

Parameters

Returns

SL_STATUS_OK if successful. Error code otherwise.

Events

• sl_bt_evt_gatt_descriptor_value - Descriptor value received from the remote GATT server.

• sl_bt_evt_gatt_procedure_completed - Procedure was successfully completed or failed with an error.

sl_bt_gatt_write_descriptor_value()#

Write the value of a characteristic descriptor in a remote GATT database. If the given value does not fit in one ATT PDU, "write long" GATT procedure is used automatically. Received sl_bt_evt_gatt_procedure_completed event indicates either that all data was written successfully or that an error response was received.

Parameters

Returns

SL_STATUS_OK if successful. Error code otherwise.

Events

• sl_bt_evt_gatt_procedure_completed - Procedure was successfully completed or failed with an error.