Generic Attribute Profile Server (gatt_server)
These commands and events are used by the local GATT server to manage the local GATT database.gatt_server commands
gatt_server_disable_capabilities
Disable the given capabilities in the local GATT database. See gatt_server_set_capabilities for more formation.
C API
/* Function */
struct gecko_msg_gatt_server_disable_capabilities_rsp_t *gecko_cmd_gatt_server_disable_capabilities(uint32 caps);
/* Response id */
gecko_rsp_gatt_server_disable_capabilities_id
/* Response structure */
struct gecko_msg_gatt_server_disable_capabilities_rsp_t
{
uint16 result;
}
Command Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint32 | caps | Capabilities to disable |
Response Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint16 | result |
Result code
|
gatt_server_enable_capabilities
Enable additional capabilities in the local GATT database. Already enabled capabilities keep unchanged after this command. See gatt_server_set_capabilities for more formation.
C API
/* Function */
struct gecko_msg_gatt_server_enable_capabilities_rsp_t *gecko_cmd_gatt_server_enable_capabilities(uint32 caps);
/* Response id */
gecko_rsp_gatt_server_enable_capabilities_id
/* Response structure */
struct gecko_msg_gatt_server_enable_capabilities_rsp_t
{
uint16 result;
}
Command Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint32 | caps | Capabilities to enable |
Response Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint16 | result |
Result code
|
gatt_server_find_attribute
Find attributes of a certain type from a local GATT database. The type is usually given as a 16-bit or 128-bit UUID in little endian format.
C API
/* Function */
struct gecko_msg_gatt_server_find_attribute_rsp_t *gecko_cmd_gatt_server_find_attribute(uint16 start, uint8 type_len, const uint8 *type_data);
/* Response id */
gecko_rsp_gatt_server_find_attribute_id
/* Response structure */
struct gecko_msg_gatt_server_find_attribute_rsp_t
{
uint16 result;
uint16 attribute;
}
Command Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint16 | start | Search start handle |
| uint8 | type_len | Array length. |
| uint8array | type_data | Variable length byte array. The first byte defines the length of data that follows, 0 - 255 bytes. |
Response Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint16 | result |
Result code
|
| uint16 | attribute | Attribute handle |
gatt_server_get_enabled_capabilities
Get capabilities currently enabled in the local GATT database.
C API
/* Function */
struct gecko_msg_gatt_server_get_enabled_capabilities_rsp_t *gecko_cmd_gatt_server_get_enabled_capabilities();
/* Response id */
gecko_rsp_gatt_server_get_enabled_capabilities_id
/* Response structure */
struct gecko_msg_gatt_server_get_enabled_capabilities_rsp_t
{
uint16 result;
uint32 caps;
}
Command does not have parameters (for BGAPI headers refer to link)
Response Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint16 | result |
Result code
|
| uint32 | caps | Enabled capabilities |
gatt_server_get_mtu
Get the size of ATT Message Transfer Units (MTU) for a connection.
C API
/* Function */
struct gecko_msg_gatt_server_get_mtu_rsp_t *gecko_cmd_gatt_server_get_mtu(uint8 connection);
/* Response id */
gecko_rsp_gatt_server_get_mtu_id
/* Response structure */
struct gecko_msg_gatt_server_get_mtu_rsp_t
{
uint16 result;
uint16 mtu;
}
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
|
| uint16 | mtu | The maximum ATT_MTU used by the connection |
gatt_server_read_attribute_type
Read the type of an attribute from a local GATT database. The type is a UUID, usually 16 or 128 bits long in little endian format.
C API
/* Function */
struct gecko_msg_gatt_server_read_attribute_type_rsp_t *gecko_cmd_gatt_server_read_attribute_type(uint16 attribute);
/* Response id */
gecko_rsp_gatt_server_read_attribute_type_id
/* Response structure */
struct gecko_msg_gatt_server_read_attribute_type_rsp_t
{
uint16 result;
uint8array type;
}
Command Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint16 | attribute | Attribute handle |
Response Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint16 | result |
Result code
|
| uint8array | type | Variable length byte array. The first byte defines the length of data that follows, 0 - 255 bytes. |
gatt_server_read_attribute_value
Read the value of an attribute from a local GATT database. Only (maximum BGAPI payload size - 3) amount of data can be read at once. The application can continue reading with increased offset value if it receives (maximum BGAPI payload size - 3) amount of data.
C API
/* Function */
struct gecko_msg_gatt_server_read_attribute_value_rsp_t *gecko_cmd_gatt_server_read_attribute_value(uint16 attribute, uint16 offset);
/* Response id */
gecko_rsp_gatt_server_read_attribute_value_id
/* Response structure */
struct gecko_msg_gatt_server_read_attribute_value_rsp_t
{
uint16 result;
uint8array value;
}
Command Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint16 | attribute | Attribute handle |
| uint16 | offset | Value offset |
Response Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint16 | result |
Result code
|
| uint8array | value | Variable length byte array. The first byte defines the length of data that follows, 0 - 255 bytes. |
gatt_server_send_characteristic_notification
Send notifications or indications to one or more remote GATT clients. At most ATT_MTU - 3 amount of data can be sent one time.
A notification or indication is sent only if the client has enabled it by setting the corresponding flag to the Client Characteristic Configuration descriptor. If the Client Characteristic Configuration descriptor supports both notifications and indications, the stack will always send a notification even when the client has enabled both.
A new indication to a GATT client can't be sent until an outstanding indication procedure with the same client has completed. The procedure is completed when a confirmation from the client is received. The confirmation is indicated by gatt_server_characteristic_status event.
Error bg_err_wrong_state is returned if the characteristic does not have the notification property, or if the client has not enabled the notification. The same applies to the indication property, and in addition, bg_err_wrong_state is returned if an indication procedure with the same client is outstanding. Always check the response for this command for errors before trying to send more data.
C API
/* Function */
struct gecko_msg_gatt_server_send_characteristic_notification_rsp_t *gecko_cmd_gatt_server_send_characteristic_notification(uint8 connection, uint16 characteristic, uint8 value_len, const uint8 *value_data);
/* Response id */
gecko_rsp_gatt_server_send_characteristic_notification_id
/* Response structure */
struct gecko_msg_gatt_server_send_characteristic_notification_rsp_t
{
uint16 result;
uint16 sent_len;
}
Command Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint8 | connection |
A handle of the connection over which the notification or indication is sent. Values:
|
| uint16 | characteristic | Characteristic handle |
| uint8 | value_len | Array length. |
| uint8array | value_data | Value to be notified or indicated |
Response Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint16 | result |
Result code
|
| uint16 | sent_len | The length of data sent if only one connected device is the receiver; otherwise an unused value. |
gatt_server_send_user_read_response
Send a response to a user_read_request event. The response needs to be sent within 30 seconds, otherwise no more GATT transactions are allowed by the remote side. If attr_errorcode is set to 0, the characteristic value is sent to the remote GATT client in the standard way. Other attr_errorcode values will cause the local GATT server to send an attribute protocol error response instead of the actual data. At most ATT_MTU - 1 amount of data can be sent at one time. The client will continue reading by sending new read request with an increased offset value if it receives ATT_MTU - 1 amount of data.
C API
/* Function */
struct gecko_msg_gatt_server_send_user_read_response_rsp_t *gecko_cmd_gatt_server_send_user_read_response(uint8 connection, uint16 characteristic, uint8 att_errorcode, uint8 value_len, const uint8 *value_data);
/* Response id */
gecko_rsp_gatt_server_send_user_read_response_id
/* Response structure */
struct gecko_msg_gatt_server_send_user_read_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 | att_errorcode | Attribute protocol error code
|
| uint8 | value_len | Array length. |
| uint8array | value_data | Characteristic value to send to the GATT client. Ignored if att_errorcode is not 0. |
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 client |
gatt_server_send_user_write_response
Send a response to a gatt_server_user_write_request event when parameter att_opcode in the event is Write Request (see att_opcode). The response needs to be sent within 30 seconds, otherwise no more GATT transactions are allowed by the remote side. If attr_errorcode is set to 0, the ATT protocol's write response is sent to indicate to the remote GATT client that the write operation was processed successfully. Other values will cause the local GATT server to send an ATT protocol error response.
C API
/* Function */
struct gecko_msg_gatt_server_send_user_write_response_rsp_t *gecko_cmd_gatt_server_send_user_write_response(uint8 connection, uint16 characteristic, uint8 att_errorcode);
/* Response id */
gecko_rsp_gatt_server_send_user_write_response_id
/* Response structure */
struct gecko_msg_gatt_server_send_user_write_response_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 | att_errorcode | Attribute protocol error code
|
Response Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint16 | result |
Result code
|
gatt_server_set_capabilities
Reset capabilities that should be enabled by the GATT database. A service is visible to remote GATT clients if at least one of its capabilities is enabled. The same applies to a characteristic and its attributes. Capability identifiers and their corresponding bit flag values can be found in the auto-generated database header file. See UG118: Blue Gecko Bluetooth Profile Toolkit Developer's Guide for how to declare capabilities in the GATT database.
Changing the capabilities of a database effectively causes a database change (attributes being added or removed) from a remote GATT client point of view. If the database has a Generic Attribute service and Service Changed characteristic, the stack will monitor the local database change status and manage service changed indications for a GATT client that has enabled the indication configuration of the Service Changed characteristic.
C API
/* Function */
struct gecko_msg_gatt_server_set_capabilities_rsp_t *gecko_cmd_gatt_server_set_capabilities(uint32 caps, uint32 reserved);
/* Response id */
gecko_rsp_gatt_server_set_capabilities_id
/* Response structure */
struct gecko_msg_gatt_server_set_capabilities_rsp_t
{
uint16 result;
}
Command Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint32 | caps | Bit flags of capabilities to reset. Value 0 sets the default database capabilities. |
| uint32 | reserved | Use the value 0 on this reserved field. Do not use none-zero values because they are reserved for future use. |
Response Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint16 | result |
Result code
|
gatt_server_set_max_mtu
Set the maximum size of ATT Message Transfer Units (MTU). The functionality is the same as gatt_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 was established.
C API
/* Function */
struct gecko_msg_gatt_server_set_max_mtu_rsp_t *gecko_cmd_gatt_server_set_max_mtu(uint16 max_mtu);
/* Response id */
gecko_rsp_gatt_server_set_max_mtu_id
/* Response structure */
struct gecko_msg_gatt_server_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 succeeded |
gatt_server_write_attribute_value
Write the value of an attribute in the local GATT database. Writing the value of a characteristic of the local GATT database will not trigger notifications or indications to the remote GATT client if the characteristic has a property to indicate or notify and the client has enabled notification or indication. Notifications and indications are sent to the remote GATT client using gatt_server_send_characteristic_notification command.
C API
/* Function */
struct gecko_msg_gatt_server_write_attribute_value_rsp_t *gecko_cmd_gatt_server_write_attribute_value(uint16 attribute, uint16 offset, uint8 value_len, const uint8 *value_data);
/* Response id */
gecko_rsp_gatt_server_write_attribute_value_id
/* Response structure */
struct gecko_msg_gatt_server_write_attribute_value_rsp_t
{
uint16 result;
}
Command Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint16 | attribute | Attribute handle |
| uint16 | offset | Value offset |
| uint8 | value_len | Array length. |
| uint8array | value_data | Value |
Response Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint16 | result |
Result code
|
gatt_server events
gatt_server_attribute_value
Indicates that the value of an attribute in the local GATT database was changed by a remote GATT client. The parameter att_opcode describes which GATT procedure was used to change the value.
C API
/* event id*/
gecko_evt_gatt_server_attribute_value_id
/* event structure*/
struct gecko_msg_gatt_server_attribute_value_evt_t
{
uint8 connection;
uint16 attribute;
uint8 att_opcode;
uint16 offset;
uint8array value;
}
Event Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint8 | connection | Connection handle |
| uint16 | attribute | Attribute Handle |
| uint8 | att_opcode | Attribute opcode that informs the procedure from which the value was received. |
| uint16 | offset | Value offset |
| uint8array | value | Value |
gatt_server_user_read_request
Indicates that a remote GATT client is attempting to read a value of an attribute from the local GATT database, where the attribute was defined in the GATT database XML file to have the type="user". The parameter att_opcode informs which GATT procedure was used to read the value. The application needs to respond to this request by using the gatt_server_send_user_read_response command within 30 seconds, otherwise further GATT transactions are not allowed by the remote side.
C API
/* event id*/
gecko_evt_gatt_server_user_read_request_id
/* event structure*/
struct gecko_msg_gatt_server_user_read_request_evt_t
{
uint8 connection;
uint16 characteristic;
uint8 att_opcode;
uint16 offset;
}
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 that informs the procedure from which the value was received. |
| uint16 | offset | Value offset |
gatt_server_user_write_request
Indicates that a remote GATT client is attempting to write a value of an attribute into the local GATT database, where the attribute was defined in the GATT database XML file to have the type="user". The parameter att_opcode informs which attribute procedure was used to write the value. If the att_opcode is Write Request (see att_opcode), the application needs to respond to this request by using the gatt_server_send_user_write_response command within 30 seconds, otherwise further GATT transactions are not allowed by the remote side. If the value of att_opcode is Execute Write Request, it indicates that this is a queued prepare write request received earlier and now the GATT server is processing the execute write. The event gatt_server_execute_write_completed will be emitted after all queued requests have been processed.
C API
/* event id*/
gecko_evt_gatt_server_user_write_request_id
/* event structure*/
struct gecko_msg_gatt_server_user_write_request_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 that informs the procedure from which the value was received. |
| uint16 | offset | Value offset |
| uint8array | value | Value |
gatt_server_characteristic_status
Indicates either that a local Client Characteristic Configuration descriptor was changed by the remote GATT client, or that a confirmation from the remote GATT client was received upon a successful reception of the indication. Confirmation by the remote GATT client should be received within 30 seconds after an indication was sent with the gatt_server_send_characteristic_notification command, otherwise further GATT transactions over this connection are not allowed by the stack.
C API
/* event id*/
gecko_evt_gatt_server_characteristic_status_id
/* event structure*/
struct gecko_msg_gatt_server_characteristic_status_evt_t
{
uint8 connection;
uint16 characteristic;
uint8 status_flags;
uint16 client_config_flags;
}
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 | status_flags | Describes whether Client Characteristic Configuration was changed or if a confirmation was received. |
| uint16 | client_config_flags | This field carries the new value of the Client Characteristic Configuration. If the status_flags is 0x2 (confirmation received), the value of this field can be ignored. |
gatt_server_execute_write_completed
Execute write completed event indicates that the execute write command from a remote GATT client has completed with the given result.
C API
/* event id*/
gecko_evt_gatt_server_execute_write_completed_id
/* event structure*/
struct gecko_msg_gatt_server_execute_write_completed_evt_t
{
uint8 connection;
uint16 result;
}
Event Parameters (for BGAPI headers refer to link)
| Type | Name | Description |
|---|---|---|
| uint8 | connection | Connection handle |
| uint16 | result | Execute write result |
gatt_server enumerations
gatt_server_characteristic_status_flag
These values describe whether the characteristic client configuration was changed or whether a characteristic confirmation was received.
Enumerations
| Value | Name | Description |
|---|---|---|
| 1 | gatt_server_client_config | Characteristic client configuration has been changed. |
| 2 | gatt_server_confirmation | Characteristic confirmation has been received. |