Generic Attribute Profile (gatt)
The commands and events in this class are used to browse and manage attributes in a remote GATT server.gatt commands
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 gatt_procedure_completed event indicates that this GATT procedure was successfully completed or failed with an error.
C API
/* Function */
struct gecko_msg_gatt_discover_characteristics_rsp_t *gecko_cmd_gatt_discover_characteristics(uint8 connection, uint32 service);
/* Response id */
gecko_rsp_gatt_discover_characteristics_id
/* Response structure */
struct gecko_msg_gatt_discover_characteristics_rsp_t
{
uint16 result;
}
Command Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint8 | connection | Connection handle |
| uint32 | service | GATT service handle This value is normally received from the gatt_service event. |
Response Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint16 | result |
Result code
|
Events generated
| Event | Description |
|---|---|
| gatt_characteristic | Discovered characteristic from remote GATT database. |
| gatt_procedure_completed | Procedure was successfully completed or failed with an error. |
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 gatt_procedure_completed event indicates that this GATT procedure was successfully completed or failed with an error.
C API
/* Function */
struct gecko_msg_gatt_discover_characteristics_by_uuid_rsp_t *gecko_cmd_gatt_discover_characteristics_by_uuid(uint8 connection, uint32 service, uint8 uuid_len, const uint8 *uuid_data);
/* Response id */
gecko_rsp_gatt_discover_characteristics_by_uuid_id
/* Response structure */
struct gecko_msg_gatt_discover_characteristics_by_uuid_rsp_t
{
uint16 result;
}
Command Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint8 | connection | Connection handle |
| uint32 | service | GATT service handle This value is normally received from the gatt_service event. |
| uint8 | uuid_len | Array length. |
| uint8array | uuid_data | Characteristic UUID in little endian format |
Response Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint16 | result |
Result code
|
Events generated
| Event | Description |
|---|---|
| gatt_characteristic | Discovered characteristic from remote GATT database. |
| gatt_procedure_completed | Procedure was successfully completed or failed with an error. |
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 gatt_procedure_completed event indicates that this GATT procedure has successfully completed or failed with an error.
C API
/* Function */
struct gecko_msg_gatt_discover_descriptors_rsp_t *gecko_cmd_gatt_discover_descriptors(uint8 connection, uint16 characteristic);
/* Response id */
gecko_rsp_gatt_discover_descriptors_id
/* Response structure */
struct gecko_msg_gatt_discover_descriptors_rsp_t
{
uint16 result;
}
Command Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint8 | connection | Connection handle |
| uint16 | characteristic | GATT characteristic handle This value is normally received from the gatt_characteristic event. |
Response Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint16 | result |
Result code
|
Events generated
| Event | Description |
|---|---|
| gatt_descriptor | Discovered descriptor from remote GATT database. |
| gatt_procedure_completed | Procedure was successfully completed or failed with an error. |
gatt_discover_primary_services
Discover all primary services of a remote GATT database. This command generates a unique gatt_service event for every discovered primary service. Received gatt_procedure_completed event indicates that this GATT procedure has successfully completed or failed with an error.
C API
/* Function */
struct gecko_msg_gatt_discover_primary_services_rsp_t *gecko_cmd_gatt_discover_primary_services(uint8 connection);
/* Response id */
gecko_rsp_gatt_discover_primary_services_id
/* Response structure */
struct gecko_msg_gatt_discover_primary_services_rsp_t
{
uint16 result;
}
Command Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint8 | connection | Connection handle |
Response Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint16 | result |
Result code
|
Events generated
| Event | Description |
|---|---|
| gatt_service | Discovered service from remote GATT database |
| gatt_procedure_completed | Procedure was successfully completed or failed with an error. |
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 gatt_procedure_completed event indicates that this GATT procedure was successfully completed or failed with an error.
C API
/* Function */
struct gecko_msg_gatt_discover_primary_services_by_uuid_rsp_t *gecko_cmd_gatt_discover_primary_services_by_uuid(uint8 connection, uint8 uuid_len, const uint8 *uuid_data);
/* Response id */
gecko_rsp_gatt_discover_primary_services_by_uuid_id
/* Response structure */
struct gecko_msg_gatt_discover_primary_services_by_uuid_rsp_t
{
uint16 result;
}
Command Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint8 | connection | Connection handle |
| uint8 | uuid_len | Array length. |
| uint8array | uuid_data | Service UUID in little endian format |
Response Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint16 | result |
Result code
|
Events generated
| Event | Description |
|---|---|
| gatt_service | Discovered service from remote GATT database. |
| gatt_procedure_completed | Procedure was successfully completed or failed with an error. |
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 prepare_characteristic_value_write command. Content, offset, and length of queued values are validated by this procedure. A received gatt_procedure_completed event indicates that all data was written successfully or that an error response was received.
C API
/* Function */
struct gecko_msg_gatt_execute_characteristic_value_write_rsp_t *gecko_cmd_gatt_execute_characteristic_value_write(uint8 connection, uint8 flags);
/* Response id */
gecko_rsp_gatt_execute_characteristic_value_write_id
/* Response structure */
struct gecko_msg_gatt_execute_characteristic_value_write_rsp_t
{
uint16 result;
}
Command Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint8 | connection | Connection handle |
| uint8 | flags |
gatt_execute_write_flag
|
Response Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint16 | result |
Result code
|
Events generated
| Event | Description |
|---|---|
| gatt_procedure_completed | Procedure was successfully completed or failed with an error. |
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 gatt_procedure_completed event indicates that this GATT procedure was successfully completed or failed with an error.
C API
/* Function */
struct gecko_msg_gatt_find_included_services_rsp_t *gecko_cmd_gatt_find_included_services(uint8 connection, uint32 service);
/* Response id */
gecko_rsp_gatt_find_included_services_id
/* Response structure */
struct gecko_msg_gatt_find_included_services_rsp_t
{
uint16 result;
}
Command Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint8 | connection | Connection handle |
| uint32 | service | GATT service handle This value is normally received from the gatt_service event. |
Response Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint16 | result |
Result code
|
Events generated
| Event | Description |
|---|---|
| gatt_service | Discovered service from remote GATT database. |
| gatt_procedure_completed | Procedure was successfully completed or failed with an error. |
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 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 execute_characteristic_value_write command. Whether the writes succeed or not is indicated in the response of the execute_characteristic_value_write command.
C API
/* Function */
struct gecko_msg_gatt_prepare_characteristic_value_reliable_write_rsp_t *gecko_cmd_gatt_prepare_characteristic_value_reliable_write(uint8 connection, uint16 characteristic, uint16 offset, uint8 value_len, const uint8 *value_data);
/* Response id */
gecko_rsp_gatt_prepare_characteristic_value_reliable_write_id
/* Response structure */
struct gecko_msg_gatt_prepare_characteristic_value_reliable_write_rsp_t
{
uint16 result;
uint16 sent_len;
}
Command Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint8 | connection | Connection handle |
| uint16 | characteristic | GATT characteristic handle This value is normally received from the gatt_characteristic event. |
| uint16 | offset | Offset of the characteristic value |
| uint8 | value_len | Array length. |
| uint8array | value_data | Value to write into the specified characteristic of the remote GATT database |
Response Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint16 | result |
Result code
|
| uint16 | sent_len | The length of data sent to the remote GATT server |
Events generated
| Event | Description |
|---|---|
| gatt_procedure_completed | Procedure was successfully completed or failed with an error. |
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 execute_characteristic_value_write command. Whether the writes succeed or not is indicated in the response of the execute_characteristic_value_write command.
In all use cases where the amount of data to transfer fits into the BGAPI payload, use the command gatt_write_characteristic_value to write long values because it transparently performs the prepare_write and execute_write commands.
C API
/* Function */
struct gecko_msg_gatt_prepare_characteristic_value_write_rsp_t *gecko_cmd_gatt_prepare_characteristic_value_write(uint8 connection, uint16 characteristic, uint16 offset, uint8 value_len, const uint8 *value_data);
/* Response id */
gecko_rsp_gatt_prepare_characteristic_value_write_id
/* Response structure */
struct gecko_msg_gatt_prepare_characteristic_value_write_rsp_t
{
uint16 result;
uint16 sent_len;
}
Command Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint8 | connection | Connection handle |
| uint16 | characteristic | GATT characteristic handle This value is normally received from the gatt_characteristic event. |
| uint16 | offset | Offset of the characteristic value |
| uint8 | value_len | Array length. |
| uint8array | value_data | Value to write into the specified characteristic of the remote GATT database |
Response Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint16 | result |
Result code
|
| uint16 | sent_len | The length of data sent to the remote GATT server |
Events generated
| Event | Description |
|---|---|
| gatt_procedure_completed | Procedure was successfully completed or failed with an error. |
gatt_read_characteristic_value
Read the value of a characteristic from a remote GATT database. A single gatt_characteristic_value event is generated if the characteristic value fits in one ATT PDU. Otherwise, more than one gatt_characteristic_value event is generated because the firmware will automatically use the Read Long Characteristic Values procedure. A received 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.
C API
/* Function */
struct gecko_msg_gatt_read_characteristic_value_rsp_t *gecko_cmd_gatt_read_characteristic_value(uint8 connection, uint16 characteristic);
/* Response id */
gecko_rsp_gatt_read_characteristic_value_id
/* Response structure */
struct gecko_msg_gatt_read_characteristic_value_rsp_t
{
uint16 result;
}
Command Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint8 | connection | Connection handle |
| uint16 | characteristic | GATT characteristic handle This value is normally received from the gatt_characteristic event. |
Response Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint16 | result |
Result code
|
Events generated
| Event | Description |
|---|---|
| gatt_characteristic_value | Contains the data of a characteristic sent by the GATT Server. |
| gatt_procedure_completed | Procedure was successfully completed or failed with an error. |
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, then one 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 gatt_characteristic_value events until the value has been completely read. A received gatt_procedure_completed event indicates that all data was read successfully or that an error response was received.
C API
/* Function */
struct gecko_msg_gatt_read_characteristic_value_by_uuid_rsp_t *gecko_cmd_gatt_read_characteristic_value_by_uuid(uint8 connection, uint32 service, uint8 uuid_len, const uint8 *uuid_data);
/* Response id */
gecko_rsp_gatt_read_characteristic_value_by_uuid_id
/* Response structure */
struct gecko_msg_gatt_read_characteristic_value_by_uuid_rsp_t
{
uint16 result;
}
Command Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint8 | connection | Connection handle |
| uint32 | service | GATT service handle This value is normally received from the gatt_service event. |
| uint8 | uuid_len | Array length. |
| uint8array | uuid_data | Characteristic UUID in little endian format |
Response Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint16 | result |
Result code
|
Events generated
| Event | Description |
|---|---|
| gatt_characteristic_value | Contains the data of a characteristic sent by the GATT Server. |
| gatt_procedure_completed | Procedure was successfully completed or failed with an error. |
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 gatt_read_characteristic_value if both the offset and maximum length parameters are 0. A single gatt_characteristic_value event is generated if the value to read fits in one ATT PDU. Otherwise, more than one gatt_characteristic_value events are generated because the firmware will automatically use the Read Long Characteristic Values procedure. A received gatt_procedure_completed event indicates that all data was read successfully or that an error response was received.
C API
/* Function */
struct gecko_msg_gatt_read_characteristic_value_from_offset_rsp_t *gecko_cmd_gatt_read_characteristic_value_from_offset(uint8 connection, uint16 characteristic, uint16 offset, uint16 maxlen);
/* Response id */
gecko_rsp_gatt_read_characteristic_value_from_offset_id
/* Response structure */
struct gecko_msg_gatt_read_characteristic_value_from_offset_rsp_t
{
uint16 result;
}
Command Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint8 | connection | Connection handle |
| uint16 | characteristic | GATT characteristic handle This value is normally received from the gatt_characteristic event. |
| uint16 | offset | Offset of the characteristic value |
| uint16 | maxlen | Maximum bytes to read. If this parameter is 0, all characteristic values starting at a given offset will be read. |
Response Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint16 | result |
Result code
|
Events generated
| Event | Description |
|---|---|
| gatt_characteristic_value | Contains the data of a characteristic sent by the GATT Server. |
| gatt_procedure_completed | Procedure was successfully completed or failed with an error. |
gatt_read_descriptor_value
Read the descriptor value of a characteristic in a remote GATT database. A single gatt_descriptor_value event is generated if the descriptor value fits in one ATT PDU. Otherwise, more than one gatt_descriptor_value events are generated because the firmware automatically uses the Read Long Characteristic Values procedure. A received gatt_procedure_completed event indicates that all data was read successfully or that an error response was received.
C API
/* Function */
struct gecko_msg_gatt_read_descriptor_value_rsp_t *gecko_cmd_gatt_read_descriptor_value(uint8 connection, uint16 descriptor);
/* Response id */
gecko_rsp_gatt_read_descriptor_value_id
/* Response structure */
struct gecko_msg_gatt_read_descriptor_value_rsp_t
{
uint16 result;
}
Command Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint8 | connection | Connection handle |
| uint16 | descriptor | GATT characteristic descriptor handle |
Response Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint16 | result |
Result code
|
Events generated
| Event | Description |
|---|---|
| gatt_descriptor_value | Descriptor value received from the remote GATT server. |
| gatt_procedure_completed | Procedure was successfully completed or failed with an error. |
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 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 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.
C API
/* Function */
struct gecko_msg_gatt_read_multiple_characteristic_values_rsp_t *gecko_cmd_gatt_read_multiple_characteristic_values(uint8 connection, uint8 characteristic_list_len, const uint8 *characteristic_list_data);
/* Response id */
gecko_rsp_gatt_read_multiple_characteristic_values_id
/* Response structure */
struct gecko_msg_gatt_read_multiple_characteristic_values_rsp_t
{
uint16 result;
}
Command Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint8 | connection | Connection handle |
| uint8 | characteristic_list_len | Array length. |
| uint8array | characteristic_list_data | List of uint16 characteristic handles each in little endian format. |
Response Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint16 | result |
Result code
|
Events generated
| Event | Description |
|---|---|
| gatt_characteristic_value | A concatenation of characteristic values in the order they were requested |
| gatt_procedure_completed | Procedure was either successfully completed or failed with an error. |
gatt_send_characteristic_confirmation
Send a confirmation to a remote GATT server after receiving a characteristic indication. The gatt_characteristic_value event carries the att_opcode containing 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.
C API
/* Function */
struct gecko_msg_gatt_send_characteristic_confirmation_rsp_t *gecko_cmd_gatt_send_characteristic_confirmation(uint8 connection);
/* Response id */
gecko_rsp_gatt_send_characteristic_confirmation_id
/* Response structure */
struct gecko_msg_gatt_send_characteristic_confirmation_rsp_t
{
uint16 result;
}
Command Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint8 | connection | Connection handle |
Response Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint16 | result |
Result code
|
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 gatt_procedure_completed event indicates that this GATT procedure was successfully completed or that it failed with an error.
C API
/* Function */
struct gecko_msg_gatt_set_characteristic_notification_rsp_t *gecko_cmd_gatt_set_characteristic_notification(uint8 connection, uint16 characteristic, uint8 flags);
/* Response id */
gecko_rsp_gatt_set_characteristic_notification_id
/* Response structure */
struct gecko_msg_gatt_set_characteristic_notification_rsp_t
{
uint16 result;
}
Command Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint8 | connection | Connection handle |
| uint16 | characteristic | GATT characteristic handle This value is normally received from the gatt_characteristic event. |
| uint8 | flags | Characteristic client configuration flags |
Response Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint16 | result |
Result code
|
Events generated
| Event | Description |
|---|---|
| gatt_procedure_completed | Procedure was successfully completed or failed with an error. |
| 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. |
gatt_set_max_mtu
Set the maximum size of ATT Message Transfer Units (MTU). Functionality is the same as 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 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.
C API
/* Function */
struct gecko_msg_gatt_set_max_mtu_rsp_t *gecko_cmd_gatt_set_max_mtu(uint16 max_mtu);
/* Response id */
gecko_rsp_gatt_set_max_mtu_id
/* Response structure */
struct gecko_msg_gatt_set_max_mtu_rsp_t
{
uint16 result;
uint16 max_mtu;
}
Command Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint16 | max_mtu | Maximum size of Message Transfer Units (MTU) allowed
|
Response Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint16 | result |
Result code
|
| uint16 | max_mtu | The maximum ATT_MTU selected by the system if this command succeeds |
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 gatt_procedure_completed event indicates that all data was written successfully or that an error response was received.
C API
/* Function */
struct gecko_msg_gatt_write_characteristic_value_rsp_t *gecko_cmd_gatt_write_characteristic_value(uint8 connection, uint16 characteristic, uint8 value_len, const uint8 *value_data);
/* Response id */
gecko_rsp_gatt_write_characteristic_value_id
/* Response structure */
struct gecko_msg_gatt_write_characteristic_value_rsp_t
{
uint16 result;
}
Command Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint8 | connection | Connection handle |
| uint16 | characteristic | GATT characteristic handle This value is normally received from the gatt_characteristic event. |
| uint8 | value_len | Array length. |
| uint8array | value_data | Characteristic value |
Response Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint16 | result |
Result code
|
Events generated
| Event | Description |
|---|---|
| gatt_procedure_completed | Procedure was successfully completed or failed with an error. |
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.
C API
/* Function */
struct gecko_msg_gatt_write_characteristic_value_without_response_rsp_t *gecko_cmd_gatt_write_characteristic_value_without_response(uint8 connection, uint16 characteristic, uint8 value_len, const uint8 *value_data);
/* Response id */
gecko_rsp_gatt_write_characteristic_value_without_response_id
/* Response structure */
struct gecko_msg_gatt_write_characteristic_value_without_response_rsp_t
{
uint16 result;
uint16 sent_len;
}
Command Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint8 | connection | Connection handle |
| uint16 | characteristic | GATT characteristic handle This value is normally received from the gatt_characteristic event. |
| uint8 | value_len | Array length. |
| uint8array | value_data | Characteristic value |
Response Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint16 | result |
Result code
|
| uint16 | sent_len | The length of data sent to the remote GATT server |
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 gatt_procedure_completed event indicates either that all data was written successfully or that an error response was received.
C API
/* Function */
struct gecko_msg_gatt_write_descriptor_value_rsp_t *gecko_cmd_gatt_write_descriptor_value(uint8 connection, uint16 descriptor, uint8 value_len, const uint8 *value_data);
/* Response id */
gecko_rsp_gatt_write_descriptor_value_id
/* Response structure */
struct gecko_msg_gatt_write_descriptor_value_rsp_t
{
uint16 result;
}
Command Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint8 | connection | Connection handle |
| uint16 | descriptor | GATT characteristic descriptor handle |
| uint8 | value_len | Array length. |
| uint8array | value_data | Descriptor value |
Response Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint16 | result |
Result code
|
Events generated
| Event | Description |
|---|---|
| gatt_procedure_completed | Procedure was successfully completed or failed with an error. |
gatt events
gatt_mtu_exchanged
Indicates that an ATT_MTU exchange procedure is completed. The mtu parameter describes new MTU size. MTU size 23 is used before this event is received.
C API
/* event id*/
gecko_evt_gatt_mtu_exchanged_id
/* event structure*/
struct gecko_msg_gatt_mtu_exchanged_evt_t
{
uint8 connection;
uint16 mtu;
}
Event Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint8 | connection | Connection handle |
| uint16 | mtu | Exchanged ATT_MTU |
gatt_service
Indicate that a GATT service in the remote GATT database was discovered. This event is generated after issuing either the gatt_discover_primary_services or gatt_discover_primary_services_by_uuid command.
C API
/* event id*/
gecko_evt_gatt_service_id
/* event structure*/
struct gecko_msg_gatt_service_evt_t
{
uint8 connection;
uint32 service;
uint8array uuid;
}
Event Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint8 | connection | Connection handle |
| uint32 | service | GATT service handle |
| uint8array | uuid | Service UUID in little endian format |
gatt_characteristic
Indicates that a GATT characteristic in the remote GATT database was discovered. This event is generated after issuing either the gatt_discover_characteristics or gatt_discover_characteristics_by_uuid command.
C API
/* event id*/
gecko_evt_gatt_characteristic_id
/* event structure*/
struct gecko_msg_gatt_characteristic_evt_t
{
uint8 connection;
uint16 characteristic;
uint8 properties;
uint8array uuid;
}
Event Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint8 | connection | Connection handle |
| uint16 | characteristic | GATT characteristic handle |
| uint8 | properties | Characteristic properties |
| uint8array | uuid | Characteristic UUID in little endian format |
gatt_descriptor
Indicates that a GATT characteristic descriptor in the remote GATT database was discovered. It is generated after issuing the gatt_discover_descriptors command.
C API
/* event id*/
gecko_evt_gatt_descriptor_id
/* event structure*/
struct gecko_msg_gatt_descriptor_evt_t
{
uint8 connection;
uint16 descriptor;
uint8array uuid;
}
Event Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint8 | connection | Connection handle |
| uint16 | descriptor | GATT characteristic descriptor handle |
| uint8array | uuid | Descriptor UUID in little endian format |
gatt_characteristic_value
Indicates that the value of one or several characteristics in the remote GATT server was received. It is triggered by several commands: gatt_read_characteristic_value, gatt_read_characteristic_value_from_offset, gatt_read_characteristic_value_by_uuid, gatt_read_multiple_characteristic_values; and when the remote GATT server sends indications or notifications after enabling notifications with gatt_set_characteristic_notification. The parameter att_opcode indicates which type of GATT transaction triggered this event. In particular, if the att_opcode type is handle_value_indication (0x1d), the application needs to confirm the indication with gatt_send_characteristic_confirmation.
C API
/* event id*/
gecko_evt_gatt_characteristic_value_id
/* event structure*/
struct gecko_msg_gatt_characteristic_value_evt_t
{
uint8 connection;
uint16 characteristic;
uint8 att_opcode;
uint16 offset;
uint8array value;
}
Event Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint8 | connection | Connection handle |
| uint16 | characteristic | GATT characteristic handle This value is normally received from the gatt_characteristic event. |
| uint8 | att_opcode | Attribute opcode, which indicates the GATT transaction used |
| uint16 | offset | Value offset |
| uint8array | value | Characteristic value |
gatt_descriptor_value
Indicates that the value of a descriptor in the remote GATT server was received. This event is generated by the gatt_read_descriptor_value command.
C API
/* event id*/
gecko_evt_gatt_descriptor_value_id
/* event structure*/
struct gecko_msg_gatt_descriptor_value_evt_t
{
uint8 connection;
uint16 descriptor;
uint16 offset;
uint8array value;
}
Event Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint8 | connection | Connection handle |
| uint16 | descriptor | GATT characteristic descriptor handle |
| uint16 | offset | Value offset |
| uint8array | value | Descriptor value |
gatt_procedure_completed
Indicates that the current GATT procedure was completed successfully or that it failed with an error. All GATT commands excluding gatt_write_characteristic_value_without_response and gatt_send_characteristic_confirmation will trigger this event. As a result, the application must wait for this event before issuing another GATT command (excluding the two aforementioned exceptions).
C API
/* event id*/
gecko_evt_gatt_procedure_completed_id
/* event structure*/
struct gecko_msg_gatt_procedure_completed_evt_t
{
uint8 connection;
uint16 result;
}
Event Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint8 | connection | Connection handle |
| uint16 | result |
Result code
|
gatt enumerations
gatt_att_opcode
These values indicate which attribute request or response has caused the event.
Enumerations
| Value | Name | Description |
|---|---|---|
| 8 | gatt_read_by_type_request | Read by type request |
| 9 | gatt_read_by_type_response | Read by type response |
| 10 | gatt_read_request | Read request |
| 11 | gatt_read_response | Read response |
| 12 | gatt_read_blob_request | Read blob request |
| 13 | gatt_read_blob_response | Read blob response |
| 14 | gatt_read_multiple_request | Read multiple request |
| 15 | gatt_read_multiple_response | Read multiple response |
| 18 | gatt_write_request | Write request |
| 19 | gatt_write_response | Write response |
| 82 | gatt_write_command | Write command |
| 22 | gatt_prepare_write_request | Prepare write request |
| 23 | gatt_prepare_write_response | Prepare write response |
| 24 | gatt_execute_write_request | Execute write request |
| 25 | gatt_execute_write_response | Execute write response |
| 27 | gatt_handle_value_notification | Notification |
| 29 | gatt_handle_value_indication | Indication |
gatt_client_config_flag
These values define whether the client is to receive notifications or indications from a remote GATT server.
Enumerations
| Value | Name | Description |
|---|---|---|
| 0 | gatt_disable | Disable notifications and indications |
| 1 | gatt_notification | Notification |
| 2 | gatt_indication | Indication |
gatt_execute_write_flag
These values define whether the GATT server is to cancel all queued writes or commit all queued writes to a remote database.
Enumerations
| Value | Name | Description |
|---|---|---|
| 0 | gatt_cancel | Cancel all queued writes |
| 1 | gatt_commit | Commit all queued writes |